@cardstack/boxel-cli 0.0.1 → 0.1.1

package/src/lib/find-checkpoint.ts

@@ -0,0 +1,65 @@
+import type { Checkpoint } from './checkpoint-manager';
+
+/**
+ * Length of a checkpoint's `shortHash`. SHA-1's first 7 hex chars, set in
+ * `CheckpointManager.createCheckpoint`. Used to short-circuit the exact
+ * short-hash scan for refs that can't possibly be one.
+ */
+const SHORT_HASH_LENGTH = 7;
+
+export type FindResult =
+  | { kind: 'found'; target: Checkpoint }
+  | { kind: 'none' }
+  | { kind: 'ambiguous'; matches: Checkpoint[] };
+
+/**
+ * Resolve a `--restore` ref against a list of checkpoints. The ref may be a
+ * 1-based index (`'2'`), an exact short hash (`'6701186'`), or a hex prefix
+ * of a full hash (`'abc'`).
+ *
+ * Resolution order:
+ *   1. Exact short-hash match. SHA-1 short hashes are all-digits ~5.9% of
+ *      the time, so digit-only refs that match a short hash exactly must
+ *      win before the index branch.
+ *   2. Digit-only refs → 1-based index. Out-of-range returns `none` rather
+ *      than falling through to hash-prefix matching, since silently matching
+ *      a hash whose prefix happens to be digits would surprise users typing
+ *      what they think is an index.
+ *   3. Hex-prefix match against the full hash.
+ */
+export function findCheckpoint(
+  ref: string,
+  checkpoints: Checkpoint[],
+): FindResult {
+  const trimmed = ref.trim();
+  // Empty refs would `startsWith('')`-match every hash and silently restore
+  // the newest checkpoint — guard explicitly.
+  if (trimmed === '') return { kind: 'none' };
+
+  // Exact short-hash match wins before the digit-only branch.
+  if (trimmed.length === SHORT_HASH_LENGTH) {
+    const exactShort = checkpoints.filter((cp) => cp.shortHash === trimmed);
+    if (exactShort.length === 1) {
+      return { kind: 'found', target: exactShort[0] };
+    }
+    if (exactShort.length > 1) {
+      return { kind: 'ambiguous', matches: exactShort };
+    }
+  }
+
+  // Digit-only input is an index lookup. Falling through to hash-prefix
+  // matching when out of range would silently match short hashes whose prefix
+  // happens to be digits.
+  if (/^\d+$/.test(trimmed)) {
+    const num = parseInt(trimmed, 10);
+    if (num >= 1 && num <= checkpoints.length) {
+      return { kind: 'found', target: checkpoints[num - 1] };
+    }
+    return { kind: 'none' };
+  }
+
+  const matches = checkpoints.filter((cp) => cp.hash.startsWith(trimmed));
+  if (matches.length === 0) return { kind: 'none' };
+  if (matches.length === 1) return { kind: 'found', target: matches[0] };
+  return { kind: 'ambiguous', matches };
+}

package/src/lib/profile-manager.ts

@@ -7,12 +7,18 @@ import {
   getRealmServerToken as fetchRealmServerToken,
   getRealmTokens,
   addRealmToMatrixAccountData,
+  removeRealmFromMatrixAccountData,
+  getUserRealmsFromMatrixAccountData,
   type MatrixAuth,
 } from './auth';
+import type { RealmAuthenticator } from './realm-authenticator';
 
 const DEFAULT_CONFIG_DIR = path.join(os.homedir(), '.boxel-cli');
 const PROFILES_FILENAME = 'profiles.json';
 
+export const NO_ACTIVE_PROFILE_ERROR =
+  'No active profile. Run `boxel profile add` to create one.';
+
 export interface Profile {
   displayName: string;
   matrixUrl: string;
@@ -77,15 +83,15 @@ export function getEnvironmentLabel(env: Environment): string {
 
 /**
  * Format profile for display in command output
- * @example [ctse · staging]
+ * @example [ctse · stack.cards]
  */
 export function formatProfileBadge(matrixId: string): string {
   const username = getUsernameFromMatrixId(matrixId);
-  const env = getEnvironmentLabel(getEnvironmentFromMatrixId(matrixId));
-  return `${DIM}[${RESET}${FG_CYAN}${username}${RESET} ${DIM}\u00b7${RESET} ${FG_MAGENTA}${env}${RESET}${DIM}]${RESET}`;
+  const domain = getDomainFromMatrixId(matrixId);
+  return `${DIM}[${RESET}${FG_CYAN}${username}${RESET} ${DIM}\u00b7${RESET} ${FG_MAGENTA}${domain}${RESET}${DIM}]${RESET}`;
 }
 
-export class ProfileManager {
+export class ProfileManager implements RealmAuthenticator {
   private config: ProfilesConfig;
   private configDir: string;
   private profilesFile: string;
@@ -293,6 +299,35 @@ export class ProfileManager {
     return true;
   }
 
+  // Update one or both server URLs for an existing profile. Cached realm
+  // tokens (and the realm-server token) are tied to the previous servers,
+  // so they're cleared whenever URLs actually change.
+  // Returns true iff at least one URL changed.
+  updateUrls(
+    profileId: string,
+    urls: { matrixUrl?: string; realmServerUrl?: string },
+  ): boolean {
+    const profile = this.config.profiles[profileId];
+    if (!profile) {
+      return false;
+    }
+    let changed = false;
+    if (urls.matrixUrl && urls.matrixUrl !== profile.matrixUrl) {
+      profile.matrixUrl = urls.matrixUrl;
+      changed = true;
+    }
+    if (urls.realmServerUrl && urls.realmServerUrl !== profile.realmServerUrl) {
+      profile.realmServerUrl = urls.realmServerUrl;
+      changed = true;
+    }
+    if (changed) {
+      profile.realmTokens = undefined;
+      profile.realmServerToken = undefined;
+      this.saveConfig();
+    }
+    return changed;
+  }
+
   setRealmToken(realmUrl: string, token: string): void {
     let active = this.getActiveProfile();
     if (!active) {
@@ -490,6 +525,16 @@ export class ProfileManager {
     await addRealmToMatrixAccountData(matrixAuth, realmUrl);
   }
 
+  async removeFromUserRealms(realmUrl: string): Promise<boolean> {
+    let matrixAuth = await this.loginToMatrix();
+    return removeRealmFromMatrixAccountData(matrixAuth, realmUrl);
+  }
+
+  async getUserRealms(): Promise<string[]> {
+    let matrixAuth = await this.loginToMatrix();
+    return getUserRealmsFromMatrixAccountData(matrixAuth);
+  }
+
   async migrateFromEnv(): Promise<{
     profileId: string;
     created: boolean;

package/src/lib/prompt.ts

@@ -0,0 +1,133 @@
+import * as readline from 'readline';
+import { Writable } from 'stream';
+
+export function prompt(question: string): Promise<string> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Read a secret from stdin without echoing it to the TTY. Keystrokes are
+ * masked with `*` and Ctrl+C exits. Intended for seeds, passwords, and other
+ * sensitive CLI input that must not appear in shell history or `ps aux`.
+ */
+export function promptPassword(question: string): Promise<string> {
+  const mutableOutput = new Writable({
+    write: (_chunk, _encoding, callback) => callback(),
+  });
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: mutableOutput,
+    terminal: true,
+  });
+
+  return new Promise((resolve, reject) => {
+    const stdin = process.stdin;
+    const wasFlowing = stdin.readableFlowing;
+
+    if (stdin.isTTY) {
+      stdin.setRawMode(true);
+    }
+
+    const cleanup = () => {
+      stdin.removeListener('data', onData);
+      if (stdin.isTTY) {
+        stdin.setRawMode(false);
+      }
+      rl.close();
+      if (!wasFlowing) {
+        stdin.pause();
+      }
+    };
+
+    const onData = (chunk: Buffer) => {
+      try {
+        // Pastes arrive as a single data event containing many characters.
+        // Strip bracketed-paste markers if the terminal sent them, then walk
+        // the chunk one code point at a time so newlines, backspace, and
+        // Ctrl+C inside a paste still work.
+        const raw = chunk
+          .toString()
+          .split('[200~')
+          .join('')
+          .split('[201~')
+          .join('');
+        for (const c of raw) {
+          if (c === '\n' || c === '\r') {
+            cleanup();
+            process.stdout.write('\n');
+            resolve(password);
+            return;
+          } else if (c === '\u0003') {
+            // Ctrl+C
+            cleanup();
+            process.exit();
+          } else if (c === '\u007F' || c === '\b') {
+            // Backspace
+            if (password.length > 0) {
+              password = password.slice(0, -1);
+              process.stdout.write('\b \b');
+            }
+          } else if (c >= ' ') {
+            // Printable character; suppress other control bytes entirely.
+            password += c;
+            process.stdout.write('*');
+          }
+        }
+      } catch (e) {
+        cleanup();
+        reject(e);
+      }
+    };
+
+    let password = '';
+    try {
+      process.stdout.write(question);
+      stdin.on('data', onData);
+      stdin.resume();
+    } catch (e) {
+      cleanup();
+      reject(e);
+    }
+  });
+}
+
+/**
+ * Resolve a realm secret seed for administrative CLI operations.
+ *
+ * Precedence:
+ *   1. `BOXEL_REALM_SECRET_SEED` env var — used silently if set.
+ *   2. If `flagPresent` is true, prompt the user (no echo).
+ *   3. Otherwise return undefined — caller falls back to profile auth.
+ *
+ * Throws when `--realm-secret-seed` is requested but stdin is not a TTY
+ * (e.g. CI, piped shells) — otherwise `promptPassword` would hang
+ * indefinitely waiting for keypress input it can never receive.
+ */
+export async function resolveRealmSecretSeed(
+  flagPresent: boolean,
+): Promise<string | undefined> {
+  const fromEnv = process.env.BOXEL_REALM_SECRET_SEED;
+  if (fromEnv) {
+    return fromEnv;
+  }
+  if (!flagPresent) {
+    return undefined;
+  }
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      'Cannot prompt for realm secret seed: stdin is not a TTY. ' +
+        'Set BOXEL_REALM_SECRET_SEED in the environment instead.',
+    );
+  }
+  return promptPassword('Realm secret seed: ');
+}

package/src/lib/realm-authenticator.ts

@@ -0,0 +1,12 @@
+/**
+ * Narrow interface over whatever strategy provides authenticated fetch to a
+ * realm. Both `ProfileManager` (Matrix login + per-realm JWT) and
+ * `SeedAuthenticator` (mint a JWT directly from a shared secret seed) satisfy
+ * this interface, so `RealmSyncBase` can accept either.
+ */
+export interface RealmAuthenticator {
+  authedRealmFetch(
+    input: string | URL | Request,
+    init?: RequestInit,
+  ): Promise<Response>;
+}

package/src/lib/realm-sync-base.ts

@@ -1,4 +1,4 @@
-import type { ProfileManager } from './profile-manager';
+import type { RealmAuthenticator } from './realm-authenticator';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import ignoreModule from 'ignore';
@@ -9,6 +9,8 @@ type Ignore = ReturnType<typeof ignoreModule>;
 
 // Files that must never be pushed, deleted, or overwritten on the server via CLI.
 export const PROTECTED_FILES = new Set(['.realm.json']);
+const DELETE_TIMEOUT_MS = 10_000;
+const DELETE_TIMEOUT_PROBE_MS = 3_000;
 
 export function isProtectedFile(relativePath: string): boolean {
   const normalizedPath = relativePath.replace(/\\/g, '/').replace(/^\/+/, '');
@@ -24,6 +26,22 @@ async function pathExists(p: string): Promise<boolean> {
   }
 }
 
+/**
+ * Decode an `atomic:results` `data.id` (or any href the realm echoes
+ * back with URL-encoded path segments). Used so paths that contain
+ * spaces or other characters that get percent-encoded on the wire
+ * round-trip to the same relative path the local listing uses.
+ * Falls back to the raw value on a malformed escape so a single bad
+ * entry can't kill the whole sync.
+ */
+function decodeAtomicResultId(id: string): string {
+  try {
+    return decodeURIComponent(id);
+  } catch {
+    return id;
+  }
+}
+
 export const SupportedMimeType = {
   CardSource: 'application/vnd.card+source',
   DirectoryListing: 'application/vnd.api+json',
@@ -34,6 +52,15 @@ export interface SyncOptions {
   realmUrl: string;
   localDir: string;
   dryRun?: boolean;
+  /**
+   * Append `?waitForIndex=true` to the `_atomic` POST so the realm-server
+   * returns only after the indexer has processed the batch. The
+   * `_atomic` handler hardcoded `waitForIndex: false` after CS-11003
+   * PR 2 (deferred `+source` POST), so callers that read indexed state
+   * (search / list) immediately after a sync race the indexer. Off by
+   * default.
+   */
+  waitForIndex?: boolean;
 }
 
 const REMOTE_CONCURRENCY = 10;
@@ -49,7 +76,7 @@ export abstract class RealmSyncBase {
 
   constructor(
     protected options: SyncOptions,
-    protected profileManager: ProfileManager,
+    protected authenticator: RealmAuthenticator,
   ) {
     this.normalizedRealmUrl = this.normalizeRealmUrl(options.realmUrl);
   }
@@ -98,7 +125,7 @@ export abstract class RealmSyncBase {
     try {
       const url = this.buildDirectoryUrl(dir);
 
-      const response = await this.profileManager.authedRealmFetch(url, {
+      const response = await this.authenticator.authedRealmFetch(url, {
         headers: {
           Accept: 'application/vnd.api+json',
         },
@@ -178,7 +205,7 @@ export abstract class RealmSyncBase {
     try {
       const url = `${this.normalizedRealmUrl}_mtimes`;
 
-      const response = await this.profileManager.authedRealmFetch(url, {
+      const response = await this.authenticator.authedRealmFetch(url, {
         headers: {
           Accept: SupportedMimeType.Mtimes,
         },
@@ -217,7 +244,22 @@ export abstract class RealmSyncBase {
           }
         }
         for (const [fileUrl, mtime] of remoteMtimeEntries) {
-          const relativePath = fileUrl.replace(this.normalizedRealmUrl, '');
+          const rawRelativePath = fileUrl.replace(this.normalizedRealmUrl, '');
+          // Realm `_mtimes` keys are URL-encoded (e.g. spaces → %20).
+          // The local file listing uses decoded paths
+          // (`Knowledge Articles/foo.json`), so leaving the remote
+          // form encoded makes the diff treat the encoded and decoded
+          // variants as two separate files — sync then "downloads"
+          // the remote copy alongside the existing local one and
+          // duplicates the workspace.
+          let relativePath: string;
+          try {
+            relativePath = decodeURIComponent(rawRelativePath);
+          } catch {
+            // Malformed percent escape — fall back to the raw value
+            // so a single bad entry doesn't kill the whole sync.
+            relativePath = rawRelativePath;
+          }
           if (!this.shouldIgnoreRemoteFile(relativePath)) {
             mtimes.set(relativePath, mtime);
           }
@@ -355,7 +397,7 @@ export abstract class RealmSyncBase {
     const content = await fs.readFile(localPath, 'utf8');
     const url = this.buildFileUrl(relativePath);
 
-    const response = await this.profileManager.authedRealmFetch(url, {
+    const response = await this.authenticator.authedRealmFetch(url, {
       method: 'POST',
       headers: {
         'Content-Type': 'text/plain;charset=UTF-8',
@@ -422,8 +464,10 @@ export abstract class RealmSyncBase {
       }),
     );
 
-    const url = `${this.normalizedRealmUrl}_atomic`;
-    const response = await this.profileManager.authedRealmFetch(url, {
+    const url = this.options.waitForIndex
+      ? `${this.normalizedRealmUrl}_atomic?waitForIndex=true`
+      : `${this.normalizedRealmUrl}_atomic`;
+    const response = await this.authenticator.authedRealmFetch(url, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/vnd.api+json',
@@ -439,9 +483,15 @@ export abstract class RealmSyncBase {
       const hrefToRelative = new Map(
         entries.map(([rel]) => [this.buildFileUrl(rel), rel]),
       );
+      // The realm normalizes hrefs: a path with a space goes out as
+      // `Knowledge Articles/...` but comes back URL-encoded as
+      // `Knowledge%20Articles/...`. Decode the response id before the
+      // map lookup so we resolve back to the original relative path
+      // instead of falling through to the raw encoded URL.
       const succeeded = (body['atomic:results'] ?? [])
         .map((r) => r.data?.id)
         .filter((id): id is string => typeof id === 'string')
+        .map((id) => decodeAtomicResultId(id))
         .map((id) => hrefToRelative.get(id) ?? id);
       for (const rel of succeeded) {
         console.log(`  Uploaded: ${rel}`);
@@ -461,7 +511,7 @@ export abstract class RealmSyncBase {
     const perFile = (errorBody.errors ?? []).map((e) => {
       const detail = e.detail ?? '';
       const match = detail.match(/Resource (\S+) /);
-      const href = match ? match[1] : '';
+      const href = match ? decodeAtomicResultId(match[1]) : '';
       const relMap = new Map(
         entries.map(([rel]) => [this.buildFileUrl(rel), rel]),
       );
@@ -495,7 +545,7 @@ export abstract class RealmSyncBase {
 
     const url = this.buildFileUrl(relativePath);
 
-    const response = await this.profileManager.authedRealmFetch(url, {
+    const response = await this.authenticator.authedRealmFetch(url, {
       headers: {
         Accept: SupportedMimeType.CardSource,
       },
@@ -530,13 +580,45 @@ export abstract class RealmSyncBase {
     }
 
     const url = this.buildFileUrl(relativePath);
+    const startedAt = Date.now();
 
-    const response = await this.profileManager.authedRealmFetch(url, {
-      method: 'DELETE',
-      headers: {
-        Accept: SupportedMimeType.CardSource,
-      },
-    });
+    let response: Response;
+    try {
+      response = await this.authenticator.authedRealmFetch(url, {
+        method: 'DELETE',
+        headers: {
+          Accept: SupportedMimeType.CardSource,
+        },
+        signal: AbortSignal.timeout(DELETE_TIMEOUT_MS),
+      });
+    } catch (error) {
+      let elapsedMs = Date.now() - startedAt;
+      console.error(
+        `  Delete request failed after ${elapsedMs}ms: ${relativePath}`,
+      );
+      if (
+        error instanceof Error &&
+        (error.name === 'TimeoutError' || error.name === 'AbortError')
+      ) {
+        let deleteApplied = await this.verifyDeleteApplied(relativePath);
+        if (deleteApplied === true) {
+          console.warn(
+            `  Delete response timed out after ${DELETE_TIMEOUT_MS}ms, but ${relativePath} is already gone on the realm; continuing`,
+          );
+          return;
+        }
+        throw new Error(
+          `Timed out deleting ${relativePath} after ${DELETE_TIMEOUT_MS}ms`,
+          { cause: error },
+        );
+      }
+      throw error;
+    }
+
+    let elapsedMs = Date.now() - startedAt;
+    console.log(
+      `  Delete response for ${relativePath}: ${response.status} ${response.statusText} (${elapsedMs}ms)`,
+    );
 
     if (!response.ok && response.status !== 404) {
       throw new Error(
@@ -547,6 +629,30 @@ export abstract class RealmSyncBase {
     console.log(`  Deleted: ${relativePath}`);
   }
 
+  private async verifyDeleteApplied(
+    relativePath: string,
+  ): Promise<boolean | 'unknown'> {
+    const url = this.buildFileUrl(relativePath);
+    try {
+      const response = await this.authenticator.authedRealmFetch(url, {
+        headers: {
+          Accept: SupportedMimeType.CardSource,
+        },
+        signal: AbortSignal.timeout(DELETE_TIMEOUT_PROBE_MS),
+      });
+      console.warn(
+        `  Delete-timeout probe for ${relativePath}: ${response.status} ${response.statusText}`,
+      );
+      return response.status === 404 ? true : false;
+    } catch (probeError) {
+      console.warn(
+        `  Delete-timeout probe failed for ${relativePath}:`,
+        probeError,
+      );
+      return 'unknown';
+    }
+  }
+
   protected async deleteLocalFile(localPath: string): Promise<void> {
     console.log(`Deleting local: ${localPath}`);