@cardstack/boxel-cli 0.0.1 → 0.1.1

package/src/commands/realm/push.ts

@@ -8,10 +8,10 @@ import {
   CheckpointManager,
   type CheckpointChange,
 } from '../../lib/checkpoint-manager';
-import {
-  getProfileManager,
-  type ProfileManager,
-} from '../../lib/profile-manager';
+import type { ProfileManager } from '../../lib/profile-manager';
+import type { RealmAuthenticator } from '../../lib/realm-authenticator';
+import { resolveRealmAuthenticator } from '../../lib/auth-resolver';
+import { resolveRealmSecretSeed } from '../../lib/prompt';
 import {
   type SyncManifest,
   computeFileHash,
@@ -25,14 +25,19 @@ interface PushOptions extends SyncOptions {
   force?: boolean;
 }
 
+// Fresh realms always include these server-managed cards even when the local
+// workspace has never pulled them. Treat them as realm artifacts, not user
+// drift, so `push --delete` only removes genuine remote-only user files.
+const REMOTE_DELETE_EXCLUSIONS = new Set(['index.json', 'realm.json']);
+
 class RealmPusher extends RealmSyncBase {
   hasError = false;
 
   constructor(
     private pushOptions: PushOptions,
-    profileManager: ProfileManager,
+    authenticator: RealmAuthenticator,
   ) {
-    super(pushOptions, profileManager);
+    super(pushOptions, authenticator);
   }
 
   async sync(): Promise<void> {
@@ -225,10 +230,16 @@ class RealmPusher extends RealmSyncBase {
 
     if (this.pushOptions.deleteRemote) {
       const filesToDelete = new Set(initialRemoteFiles.keys());
+      const skippedDeleteArtifacts: string[] = [];
 
       for (const relativePath of filesToDelete) {
         if (isProtectedFile(relativePath)) {
           filesToDelete.delete(relativePath);
+          continue;
+        }
+        if (REMOTE_DELETE_EXCLUSIONS.has(relativePath)) {
+          filesToDelete.delete(relativePath);
+          skippedDeleteArtifacts.push(relativePath);
         }
       }
 
@@ -236,21 +247,26 @@ class RealmPusher extends RealmSyncBase {
         filesToDelete.delete(relativePath);
       }
 
-      if (filesToDelete.size > 0) {
+      if (skippedDeleteArtifacts.length > 0) {
         console.log(
-          `Deleting ${filesToDelete.size} remote files that don't exist locally`,
+          `Skipping ${skippedDeleteArtifacts.length} realm-managed remote artifact(s): ${skippedDeleteArtifacts.join(', ')}`,
         );
+      }
 
-        await Promise.all(
-          Array.from(filesToDelete).map(async (relativePath) => {
-            try {
-              await this.deleteFile(relativePath);
-            } catch (error) {
-              this.hasError = true;
-              console.error(`Error deleting ${relativePath}:`, error);
-            }
-          }),
+      if (filesToDelete.size > 0) {
+        const deletePlan = Array.from(filesToDelete).sort();
+        console.log(
+          `Deleting ${deletePlan.length} remote files that don't exist locally: ${deletePlan.join(', ')}`,
         );
+
+        for (const relativePath of deletePlan) {
+          try {
+            await this.deleteFile(relativePath);
+          } catch (error) {
+            this.hasError = true;
+            console.error(`Error deleting ${relativePath}:`, error);
+          }
+        }
       }
     }
 
@@ -308,6 +324,18 @@ export interface PushCommandOptions {
   dryRun?: boolean;
   force?: boolean;
   profileManager?: ProfileManager;
+  /**
+   * Pre-resolved realm secret seed for administrative access. When set, the
+   * CLI mints a JWT locally and skips Matrix login + /_server-session +
+   * /_realm-auth. The `--realm-secret-seed` CLI flag is resolved via
+   * `resolveRealmSecretSeed` (env var or interactive prompt) before being
+   * passed here.
+   */
+  realmSecretSeed?: string;
+  /**
+   * @internal Test hook: supply an already-constructed authenticator.
+   */
+  authenticator?: RealmAuthenticator;
 }
 
 export function registerPushCommand(realm: Command): void {
@@ -322,13 +350,30 @@ export function registerPushCommand(realm: Command): void {
     .option('--delete', 'Delete remote files that do not exist locally')
     .option('--dry-run', 'Show what would be done without making changes')
     .option('--force', 'Upload all files, even if unchanged')
+    .option(
+      '--realm-secret-seed',
+      'Administrative auth: prompt for a realm secret seed and mint a JWT locally instead of using a Matrix profile (env: BOXEL_REALM_SECRET_SEED)',
+    )
     .action(
       async (
         localDir: string,
         realmUrl: string,
-        options: { delete?: boolean; dryRun?: boolean; force?: boolean },
+        options: {
+          delete?: boolean;
+          dryRun?: boolean;
+          force?: boolean;
+          realmSecretSeed?: boolean;
+        },
       ) => {
-        await pushCommand(localDir, realmUrl, options);
+        const realmSecretSeed = await resolveRealmSecretSeed(
+          options.realmSecretSeed === true,
+        );
+        await pushCommand(localDir, realmUrl, {
+          delete: options.delete,
+          dryRun: options.dryRun,
+          force: options.force,
+          realmSecretSeed,
+        });
       },
     );
 }
@@ -338,13 +383,20 @@ export async function pushCommand(
   realmUrl: string,
   options: PushCommandOptions,
 ): Promise<void> {
-  let pm = options.profileManager ?? getProfileManager();
-  let active = pm.getActiveProfile();
-  if (!active) {
-    console.error(
-      'Error: no active profile. Run `boxel profile add` to create one.',
-    );
-    process.exit(1);
+  let authenticator: RealmAuthenticator;
+  if (options.authenticator) {
+    authenticator = options.authenticator;
+  } else {
+    const resolution = resolveRealmAuthenticator({
+      realmUrl,
+      realmSecretSeed: options.realmSecretSeed,
+      profileManager: options.profileManager,
+    });
+    if (!resolution.ok) {
+      console.error(`Error: ${resolution.error}`);
+      process.exit(1);
+    }
+    authenticator = resolution.authenticator;
   }
 
   if (!(await pathExists(localDir))) {
@@ -361,7 +413,7 @@ export async function pushCommand(
         dryRun: options.dryRun,
         force: options.force,
       },
-      pm,
+      authenticator,
     );
 
     await pusher.sync();

package/src/commands/realm/remove.ts

@@ -0,0 +1,281 @@
+import type { Command } from 'commander';
+import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
+import {
+  getProfileManager,
+  NO_ACTIVE_PROFILE_ERROR,
+  type ProfileManager,
+} from '../../lib/profile-manager';
+import { prompt } from '../../lib/prompt';
+import { DIM, FG_CYAN, FG_GREEN, FG_RED, RESET } from '../../lib/colors';
+
+export interface RemoveRealmOptions {
+  realmUrl: string;
+  dryRun?: boolean;
+  profileManager?: ProfileManager;
+}
+
+export interface RemoveRealmResult {
+  /** Normalized URL the operation targeted (always trailing-slashed). */
+  realmUrl: string;
+  /** True only when both server delete and Matrix unlink completed. */
+  removed: boolean;
+  /** True when DELETE /_delete-realm returned 204. */
+  serverDeleted: boolean;
+  /** True when Matrix `app.boxel.realms` was rewritten without the URL. */
+  unlinked: boolean;
+  /** Number of entries before the change. */
+  previousCount: number;
+  /** Number of entries the next list would contain (computed even on dry-run). */
+  nextCount: number;
+  /**
+   * True when the URL was not present in `app.boxel.realms`. Mutually
+   * exclusive with a successful real removal.
+   */
+  notInList?: boolean;
+  error?: string;
+}
+
+/**
+ * Remove a realm: delete server-side files / index / registry via
+ * `DELETE /_delete-realm`, then unlink the URL from the active profile's
+ * `app.boxel.realms` Matrix account_data list. Mirrors the host UI's
+ * workspace delete flow and inverts `boxel realm create`.
+ *
+ * Programmatic API. Returns a result object on every code path; never
+ * prompts and never calls `process.exit`. The CLI wraps this with a TTY
+ * confirmation step (see `registerRemoveCommand`).
+ */
+export async function removeRealm(
+  options: RemoveRealmOptions,
+): Promise<RemoveRealmResult> {
+  let realmUrl = ensureTrailingSlash(options.realmUrl.trim());
+  let pm = options.profileManager ?? getProfileManager();
+  let active = pm.getActiveProfile();
+  if (!active) {
+    return {
+      realmUrl,
+      removed: false,
+      serverDeleted: false,
+      unlinked: false,
+      previousCount: 0,
+      nextCount: 0,
+      error: NO_ACTIVE_PROFILE_ERROR,
+    };
+  }
+
+  let existing: string[];
+  try {
+    existing = await pm.getUserRealms();
+  } catch (err) {
+    return {
+      realmUrl,
+      removed: false,
+      serverDeleted: false,
+      unlinked: false,
+      previousCount: 0,
+      nextCount: 0,
+      error: `Failed to load realm list: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    };
+  }
+  let normalized = existing.map(ensureTrailingSlash);
+  let previousCount = normalized.length;
+  let matchCount = normalized.filter((u) => u === realmUrl).length;
+
+  if (matchCount === 0) {
+    return {
+      realmUrl,
+      removed: false,
+      serverDeleted: false,
+      unlinked: false,
+      previousCount,
+      nextCount: previousCount,
+      notInList: true,
+      error: 'Realm is not in app.boxel.realms. Nothing to remove.',
+    };
+  }
+
+  let nextCount = previousCount - matchCount;
+
+  if (options.dryRun) {
+    return {
+      realmUrl,
+      removed: false,
+      serverDeleted: false,
+      unlinked: false,
+      previousCount,
+      nextCount,
+    };
+  }
+
+  let realmServerUrl = active.profile.realmServerUrl.replace(/\/$/, '');
+  let response: Response;
+  try {
+    response = await pm.authedRealmServerFetch(
+      `${realmServerUrl}/_delete-realm`,
+      {
+        method: 'DELETE',
+        headers: { 'Content-Type': 'application/vnd.api+json' },
+        body: JSON.stringify({
+          data: { type: 'realm', id: realmUrl },
+        }),
+      },
+    );
+  } catch (err) {
+    return {
+      realmUrl,
+      removed: false,
+      serverDeleted: false,
+      unlinked: false,
+      previousCount,
+      nextCount: previousCount,
+      error: `Failed to reach realm server: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    };
+  }
+
+  if (!response.ok) {
+    let body = await safeReadResponseText(response);
+    let error =
+      response.status === 403
+        ? `You do not own this realm and cannot delete it on the server. Server returned 403: ${body}`
+        : `Realm server returned ${response.status}: ${body}`;
+    return {
+      realmUrl,
+      removed: false,
+      serverDeleted: false,
+      unlinked: false,
+      previousCount,
+      nextCount: previousCount,
+      error,
+    };
+  }
+
+  let unlinked: boolean;
+  try {
+    unlinked = await pm.removeFromUserRealms(realmUrl);
+  } catch (err) {
+    return {
+      realmUrl,
+      removed: false,
+      serverDeleted: true,
+      unlinked: false,
+      previousCount,
+      nextCount: previousCount,
+      error: `Server delete succeeded, but Matrix unlink failed: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    };
+  }
+
+  if (!unlinked) {
+    return {
+      realmUrl,
+      removed: false,
+      serverDeleted: true,
+      unlinked: false,
+      previousCount,
+      nextCount: previousCount,
+      error:
+        'Server delete succeeded, but Matrix account_data did not contain the URL by the time we PUT (concurrent edit?). Server-side files are gone; please refresh and check your realm list.',
+    };
+  }
+
+  return {
+    realmUrl,
+    removed: true,
+    serverDeleted: true,
+    unlinked,
+    previousCount,
+    nextCount,
+  };
+}
+
+async function safeReadResponseText(response: Response): Promise<string> {
+  try {
+    return await response.text();
+  } catch {
+    return '<no response body>';
+  }
+}
+
+interface RemoveCliOptions {
+  yes?: boolean;
+  dryRun?: boolean;
+}
+
+export function registerRemoveCommand(realm: Command): void {
+  realm
+    .command('remove')
+    .description(
+      'Remove a realm — deletes server-side files and unlinks it from your realm list',
+    )
+    .argument('<realm-url>', 'realm URL to remove')
+    .option('-y, --yes', 'Skip the interactive confirmation prompt')
+    .option('--dry-run', 'Preview the change without writing to Matrix')
+    .action(async (realmUrlInput: string, opts: RemoveCliOptions) => {
+      let normalized = ensureTrailingSlash(realmUrlInput.trim());
+
+      let preview = await removeRealm({
+        realmUrl: normalized,
+        dryRun: true,
+      });
+
+      if (preview.error && !preview.notInList) {
+        console.error(`${FG_RED}Error:${RESET} ${preview.error}`);
+        process.exit(1);
+      }
+
+      if (preview.notInList) {
+        console.error(`${FG_RED}Error:${RESET} ${preview.error}`);
+        process.exit(1);
+      }
+
+      console.log(`Remove target: ${FG_CYAN}${preview.realmUrl}${RESET}`);
+      console.log(
+        `${DIM}app.boxel.realms: ${preview.previousCount} -> ${preview.nextCount}${RESET}`,
+      );
+
+      if (opts.dryRun) {
+        console.log(
+          `${DIM}[DRY RUN] No server delete or Matrix changes sent.${RESET}`,
+        );
+        return;
+      }
+
+      if (!opts.yes) {
+        if (!process.stdin.isTTY) {
+          console.error(
+            `${FG_RED}Error:${RESET} stdin is not a TTY. Pass --yes to confirm in non-interactive mode.`,
+          );
+          process.exit(1);
+        }
+        let answer = await prompt(
+          'This will permanently delete the realm files, indexer state, and registry entry on the server. Proceed? (y/N) ',
+        );
+        if (!/^y/i.test(answer)) {
+          console.log(`${DIM}Cancelled.${RESET}`);
+          return;
+        }
+      }
+
+      let result = await removeRealm({ realmUrl: normalized });
+      if (result.error || !result.removed) {
+        console.error(
+          `${FG_RED}Error:${RESET} ${result.error ?? 'Removal did not complete.'}`,
+        );
+        if (result.serverDeleted && !result.unlinked) {
+          console.error(
+            `${DIM}The realm is gone, but your account_data still references ${result.realmUrl}.${RESET}`,
+          );
+        }
+        process.exit(1);
+      }
+
+      console.log(
+        `${FG_GREEN}Removed:${RESET} ${FG_CYAN}${result.realmUrl}${RESET}`,
+      );
+    });
+}