@cardstack/boxel-cli 0.0.1 → 0.1.1

package/src/lib/boxel-cli-client.ts

@@ -1,6 +1,49 @@
+import { deleteFile, type DeleteResult } from '../commands/file/delete';
+import { read as fileRead, type ReadResult } from '../commands/file/read';
+import {
+  lint as coreLint,
+  type LintResult,
+  type LintMessage,
+} from '../commands/file/lint';
+import {
+  listFiles as coreListFiles,
+  type ListFilesResult,
+} from '../commands/file/list';
+import {
+  search as fileSearch,
+  type SearchResult,
+  type SearchCommandOptions,
+} from '../commands/search';
+import {
+  readTranspiledModule,
+  type ReadTranspiledResult,
+} from '../commands/read-transpiled';
+import {
+  touchFiles as coreTouchFiles,
+  type TouchResult,
+  type TouchCommandOptions,
+} from '../commands/file/touch';
+import { write as coreWrite, type WriteResult } from '../commands/file/write';
+import {
+  cancelIndexing as coreCancelIndexing,
+  type CancelIndexingResult,
+} from '../commands/realm/cancel-indexing';
 import { createRealm as coreCreateRealm } from '../commands/realm/create';
 import { pull as realmPull } from '../commands/realm/pull';
+import { sync as realmSync, type SyncResult } from '../commands/realm/sync';
+import { waitForReady as coreWaitForReady } from '../commands/realm/wait-for-ready';
 import { getProfileManager, type ProfileManager } from './profile-manager';
+import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
+
+export type {
+  ReadResult,
+  ListFilesResult,
+  ReadTranspiledResult,
+  SyncResult,
+  SearchResult,
+  SearchCommandOptions,
+  TouchResult,
+};
 
 const MIME = {
   CardSource: 'application/vnd.card+source',
@@ -9,10 +52,6 @@ const MIME = {
   JSONAPI: 'application/vnd.api+json',
 } as const;
 
-function ensureTrailingSlash(url: string): string {
-  return url.endsWith('/') ? url : `${url}/`;
-}
-
 export interface CreateRealmOptions {
   /** URL slug for the realm (lowercase, numbers, hyphens). */
   realmName: string;
@@ -40,37 +79,31 @@ export interface PullResult {
   error?: string;
 }
 
-export interface ReadResult {
-  ok: boolean;
-  status?: number;
-  /** Parsed JSON document (for .json files). */
-  document?: Record<string, unknown>;
-  /** Raw text content (for non-JSON files like .gts). */
-  content?: string;
-  error?: string;
-}
-
-export interface WriteResult {
-  ok: boolean;
-  error?: string;
-}
-
-export interface DeleteResult {
-  ok: boolean;
-  error?: string;
-}
-
-export interface SearchResult {
-  ok: boolean;
-  status?: number;
-  data?: Record<string, unknown>[];
-  error?: string;
+export interface SyncOptions {
+  /** Resolve conflicts by keeping the local version. */
+  preferLocal?: boolean;
+  /** Resolve conflicts by keeping the remote version. */
+  preferRemote?: boolean;
+  /** Resolve conflicts by keeping the newest version. */
+  preferNewest?: boolean;
+  /** Propagate deletions in both directions. */
+  delete?: boolean;
+  /** Preview without making changes. */
+  dryRun?: boolean;
+  /**
+   * Block on the realm-server until uploaded cards have been indexed,
+   * not just durably written. Appends `?waitForIndex=true` to the
+   * `_atomic` POST. Trades upload latency for read-after-write
+   * consistency — useful when the next step queries the realm's index
+   * (search / list) and can't tolerate the indexer lag introduced by
+   * CS-11003 PR 2's deferred `+source` POST. Off by default; flip on
+   * for hand-off boundaries like the factory's post-seed sync.
+   */
+  waitForIndex?: boolean;
 }
 
-export interface ListFilesResult {
-  filenames: string[];
-  error?: string;
-}
+export type { DeleteResult };
+export type { WriteResult };
 
 export interface RunCommandResult {
   status: 'ready' | 'error' | 'unusable';
@@ -79,21 +112,7 @@ export interface RunCommandResult {
   error?: string | null;
 }
 
-export interface LintMessage {
-  ruleId: string | null;
-  severity: 1 | 2;
-  message: string;
-  line: number;
-  column: number;
-  endLine?: number;
-  endColumn?: number;
-}
-
-export interface LintResult {
-  fixed: boolean;
-  output: string;
-  messages: LintMessage[];
-}
+export type { LintMessage, LintResult };
 
 export interface WaitForReadyResult {
   ready: boolean;
@@ -111,10 +130,7 @@ export interface AtomicResult {
   error?: string;
 }
 
-export interface CancelIndexingResult {
-  ok: boolean;
-  error?: string;
-}
+export type { CancelIndexingResult };
 
 export class BoxelCLIClient {
   private pm: ProfileManager;
@@ -155,148 +171,79 @@ export class BoxelCLIClient {
   }
 
   /**
-   * Read a file from a realm. Returns parsed JSON for .json files,
-   * raw text for everything else (.gts, etc.).
+   * Read a file from a realm. Always returns raw text content.
+   * Callers should parse the content themselves if needed (e.g. JSON).
+   *
+   * Delegates to the standalone `read()` in `commands/file/read.ts`
+   * so the CLI and programmatic API share one implementation.
    */
   async read(realmUrl: string, path: string): Promise<ReadResult> {
-    let url = new URL(path, ensureTrailingSlash(realmUrl)).href;
-
-    try {
-      let response = await this.pm.authedRealmFetch(url, {
-        method: 'GET',
-        headers: { Accept: MIME.CardSource },
-      });
-
-      if (!response.ok) {
-        let body = await response.text();
-        return {
-          ok: false,
-          status: response.status,
-          error: `HTTP ${response.status}: ${body.slice(0, 300)}`,
-        };
-      }
+    return fileRead(realmUrl, path, { profileManager: this.pm });
+  }
 
-      let text = await response.text();
-      try {
-        let document = JSON.parse(text) as Record<string, unknown>;
-        return { ok: true, status: response.status, document };
-      } catch {
-        return { ok: true, status: response.status, content: text };
-      }
-    } catch (err) {
-      return {
-        ok: false,
-        error: err instanceof Error ? err.message : String(err),
-      };
-    }
+  /**
+   * Fetch the TRANSPILED JavaScript output for a realm module. Thin
+   * wrapper around the `read-transpiled` CLI command — delegates to
+   * `readTranspiledModule()` in `commands/read-transpiled.ts` so the
+   * CLI and programmatic API share one implementation.
+   */
+  async readTranspiled(
+    realmUrl: string,
+    path: string,
+  ): Promise<ReadTranspiledResult> {
+    return readTranspiledModule(realmUrl, path, { profileManager: this.pm });
   }
 
   /**
    * Write a file to a realm. Content is sent as-is with card+source MIME type.
    * Path should include the file extension.
+   *
+   * Delegates to `write()` in `commands/file/write.ts` so the CLI and
+   * programmatic API share one implementation.
    */
   async write(
     realmUrl: string,
     path: string,
     content: string,
   ): Promise<WriteResult> {
-    let url = new URL(path, ensureTrailingSlash(realmUrl)).href;
-
-    try {
-      let response = await this.pm.authedRealmFetch(url, {
-        method: 'POST',
-        headers: {
-          Accept: MIME.CardSource,
-          'Content-Type': MIME.CardSource,
-        },
-        body: content,
-      });
-
-      if (!response.ok) {
-        let body = await response.text();
-        return {
-          ok: false,
-          error: `HTTP ${response.status}: ${body.slice(0, 300)}`,
-        };
-      }
-
-      return { ok: true };
-    } catch (err) {
-      return {
-        ok: false,
-        error: err instanceof Error ? err.message : String(err),
-      };
-    }
+    return coreWrite(realmUrl, path, content, { profileManager: this.pm });
   }
 
   /**
-   * Delete a file from a realm.
+   * Delete a file from a realm. Delegates to the standalone
+   * `deleteFile()` command in `commands/file/delete.ts` so the CLI
+   * and programmatic API share one implementation.
    */
   async delete(realmUrl: string, path: string): Promise<DeleteResult> {
-    let url = new URL(path, ensureTrailingSlash(realmUrl)).href;
-
-    try {
-      let response = await this.pm.authedRealmFetch(url, {
-        method: 'DELETE',
-        headers: { Accept: MIME.CardSource },
-      });
-
-      if (!response.ok) {
-        let body = await response.text();
-        return {
-          ok: false,
-          error: `HTTP ${response.status}: ${body.slice(0, 300)}`,
-        };
-      }
+    return deleteFile(realmUrl, path, {
+      profileManager: this.pm,
+    });
+  }
 
-      return { ok: true };
-    } catch (err) {
-      return {
-        ok: false,
-        error: err instanceof Error ? err.message : String(err),
-      };
-    }
+  /**
+   * Touch one or more files in a realm to force re-indexing. Delegates to
+   * `touchFiles()` in `commands/file/touch.ts`.
+   */
+  async touch(
+    realmUrl: string,
+    paths: string[],
+    options?: Pick<TouchCommandOptions, 'all' | 'dryRun'>,
+  ): Promise<TouchResult> {
+    return coreTouchFiles(realmUrl, paths, {
+      ...options,
+      profileManager: this.pm,
+    });
   }
 
   /**
-   * Search a realm using the `_search` endpoint.
+   * Federated search across one or more realms via `_federated-search`.
+   * Delegates to the standalone `search()` in `commands/search.ts`.
    */
   async search(
-    realmUrl: string,
+    realmUrls: string | string[],
     query: Record<string, unknown>,
   ): Promise<SearchResult> {
-    let searchUrl = `${ensureTrailingSlash(realmUrl)}_search`;
-
-    try {
-      let response = await this.pm.authedRealmFetch(searchUrl, {
-        method: 'QUERY',
-        headers: {
-          Accept: MIME.CardJson,
-          'Content-Type': MIME.JSON,
-        },
-        body: JSON.stringify(query),
-      });
-
-      if (!response.ok) {
-        let body = await response.text();
-        return {
-          ok: false,
-          status: response.status,
-          error: `HTTP ${response.status}: ${body.slice(0, 300)}`,
-        };
-      }
-
-      let result = (await response.json()) as {
-        data?: Record<string, unknown>[];
-      };
-      return { ok: true, data: result.data };
-    } catch (err) {
-      return {
-        ok: false,
-        status: 0,
-        error: err instanceof Error ? err.message : String(err),
-      };
-    }
+    return fileSearch(realmUrls, query, { profileManager: this.pm });
   }
 
   /**
@@ -304,49 +251,7 @@ export class BoxelCLIClient {
    * Returns relative paths (e.g., `hello.gts`, `Cards/my-card.json`).
    */
   async listFiles(realmUrl: string): Promise<ListFilesResult> {
-    let normalizedRealmUrl = ensureTrailingSlash(realmUrl);
-    let mtimesUrl = `${normalizedRealmUrl}_mtimes`;
-
-    try {
-      let response = await this.pm.authedRealmFetch(mtimesUrl, {
-        method: 'GET',
-        headers: { Accept: MIME.JSONAPI },
-      });
-
-      if (!response.ok) {
-        let body = await response.text();
-        return {
-          filenames: [],
-          error: `_mtimes returned HTTP ${response.status}: ${body.slice(0, 300)}`,
-        };
-      }
-
-      let json = (await response.json()) as {
-        data?: { attributes?: { mtimes?: Record<string, number> } };
-      };
-      let mtimes =
-        json?.data?.attributes?.mtimes ??
-        (json as unknown as Record<string, number>);
-
-      let filenames: string[] = [];
-      for (let fullUrl of Object.keys(mtimes)) {
-        if (!fullUrl.startsWith(normalizedRealmUrl)) {
-          continue;
-        }
-        let relativePath = fullUrl.slice(normalizedRealmUrl.length);
-        if (!relativePath || relativePath.endsWith('/')) {
-          continue;
-        }
-        filenames.push(relativePath);
-      }
-
-      return { filenames: filenames.sort() };
-    } catch (err) {
-      return {
-        filenames: [],
-        error: err instanceof Error ? err.message : String(err),
-      };
-    }
+    return coreListFiles(realmUrl, { profileManager: this.pm });
   }
 
   /**
@@ -414,32 +319,14 @@ export class BoxelCLIClient {
 
   /**
    * Lint a single file's source code via the realm's `_lint` endpoint.
+   * Delegates to the standalone `lint()` in `commands/file/lint.ts`.
    */
   async lint(
     realmUrl: string,
     source: string,
     filename: string,
   ): Promise<LintResult> {
-    let lintUrl = `${ensureTrailingSlash(realmUrl)}_lint`;
-    let response = await this.pm.authedRealmFetch(lintUrl, {
-      method: 'POST',
-      headers: {
-        Accept: MIME.JSON,
-        'Content-Type': MIME.CardSource,
-        'X-Filename': filename,
-        'X-HTTP-Method-Override': 'QUERY',
-      },
-      body: source,
-    });
-
-    if (!response.ok) {
-      let body = await response.text().catch(() => '(no body)');
-      throw new Error(
-        `_lint returned HTTP ${response.status}: ${body.slice(0, 300)}`,
-      );
-    }
-
-    return (await response.json()) as LintResult;
+    return coreLint(realmUrl, source, filename, { profileManager: this.pm });
   }
 
   /**
@@ -449,28 +336,10 @@ export class BoxelCLIClient {
     realmUrl: string,
     timeoutMs = 30_000,
   ): Promise<WaitForReadyResult> {
-    let readinessUrl = `${ensureTrailingSlash(realmUrl)}_readiness-check`;
-    let startedAt = Date.now();
-
-    while (Date.now() - startedAt < timeoutMs) {
-      try {
-        let response = await this.pm.authedRealmFetch(readinessUrl, {
-          method: 'GET',
-          headers: { Accept: MIME.JSON },
-        });
-        if (response.ok) {
-          return { ready: true };
-        }
-      } catch {
-        // retry
-      }
-      await new Promise((r) => setTimeout(r, 1000));
-    }
-
-    return {
-      ready: false,
-      error: `Realm not ready after ${timeoutMs}ms: ${readinessUrl}`,
-    };
+    return coreWaitForReady(realmUrl, {
+      timeoutMs,
+      profileManager: this.pm,
+    });
   }
 
   /**
@@ -540,33 +409,10 @@ export class BoxelCLIClient {
    * Cancel all indexing jobs (running + pending) for a realm.
    */
   async cancelAllIndexingJobs(realmUrl: string): Promise<CancelIndexingResult> {
-    let cancelUrl = `${ensureTrailingSlash(realmUrl)}_cancel-indexing-job`;
-
-    try {
-      let response = await this.pm.authedRealmFetch(cancelUrl, {
-        method: 'POST',
-        headers: {
-          Accept: MIME.JSON,
-          'Content-Type': MIME.JSON,
-        },
-        body: JSON.stringify({ cancelPending: true }),
-      });
-
-      if (!response.ok) {
-        let body = await response.text();
-        return {
-          ok: false,
-          error: `HTTP ${response.status}: ${body.slice(0, 300)}`,
-        };
-      }
-
-      return { ok: true };
-    } catch (err) {
-      return {
-        ok: false,
-        error: err instanceof Error ? err.message : String(err),
-      };
-    }
+    return coreCancelIndexing(realmUrl, {
+      profileManager: this.pm,
+      cancelPending: true,
+    });
   }
 
   /**
@@ -615,6 +461,27 @@ export class BoxelCLIClient {
     });
   }
 
+  /**
+   * Bidirectional sync between a local workspace and a realm. Thin wrapper
+   * around the `realm sync` command's programmatic `sync()` function so the
+   * CLI and programmatic API share one implementation.
+   */
+  async sync(
+    realmUrl: string,
+    localDir: string,
+    options?: SyncOptions,
+  ): Promise<SyncResult> {
+    return realmSync(localDir, realmUrl, {
+      preferLocal: options?.preferLocal,
+      preferRemote: options?.preferRemote,
+      preferNewest: options?.preferNewest,
+      delete: options?.delete,
+      dryRun: options?.dryRun,
+      waitForIndex: options?.waitForIndex,
+      profileManager: this.pm,
+    });
+  }
+
   async createRealm(options: CreateRealmOptions): Promise<CreateRealmResult> {
     let result = await coreCreateRealm(options.realmName, options.displayName, {
       background: options.backgroundURL,

package/src/lib/cli-log.ts

@@ -0,0 +1,132 @@
+/**
+ * Centralized logger for the boxel CLI.
+ *
+ * # Guidance for command authors
+ *
+ * Pick where output goes by asking: **does anything ever parse this
+ * line programmatically (`--json` consumer, shell pipeline, the
+ * software factory tool executor)?**
+ *
+ * - **No → `console.log` / `console.info` / `console.debug`.** This is
+ *   the default for interactive/decorative output: progress messages,
+ *   colored confirmations ("Fixed: foo.gts"), summaries, anything you'd
+ *   write with ANSI escapes from `lib/colors`. Under `--quiet` these are
+ *   intercepted and silenced — a fresh command author doesn't need to
+ *   know quiet mode exists.
+ * - **Yes → `cliLog.output(...)`.** This is for raw payloads a caller
+ *   parses: the `--json` branch (`cliLog.output(JSON.stringify(result, null, 2))`),
+ *   raw file content from `read`/`read-transpiled`, and any other
+ *   stdout-as-contract output. `cliLog.output` writes to stdout
+ *   regardless of `--quiet`.
+ * - **Errors / warnings → `console.error` / `console.warn`.** Never
+ *   silenced; goes to stderr.
+ *
+ * Quick heuristic: if the string you're about to print contains
+ * `FG_GREEN`/`DIM`/`RESET`/etc., it's decorative — use `console.log`.
+ * If it's `JSON.stringify(...)` or raw bytes, use `cliLog.output`.
+ *
+ * # How it works
+ *
+ * `--quiet` is a global flag in `src/index.ts`. When set, `setQuiet(true)`
+ * replaces `console.log`/`info`/`debug` with no-ops; `cliLog.output`
+ * writes directly to `process.stdout` and bypasses the interceptor.
+ * Software factory's tool executor passes `--quiet` by default so chatty
+ * progress lines don't pollute CI logs (see `factory-tool-executor.ts`).
+ */
+
+let quiet = false;
+
+/**
+ * Original references to the console methods we intercept. Captured at
+ * module load so `setQuiet(false)` can put them back if quiet mode is
+ * toggled off (the unit tests rely on this).
+ */
+const originalConsoleLog = console.log.bind(console);
+const originalConsoleInfo = console.info.bind(console);
+const originalConsoleDebug = console.debug.bind(console);
+
+/**
+ * Toggle quiet mode. When true, `console.log` / `console.info` /
+ * `console.debug` are replaced with no-ops for the lifetime of the
+ * process. `console.warn` and `console.error` are untouched.
+ *
+ * Idempotent: calling with the same value is a no-op.
+ */
+export function setQuiet(value: boolean): void {
+  if (value === quiet) return;
+  quiet = value;
+  if (quiet) {
+    const noop = () => {
+      /* intentionally empty: silence info/log/debug under --quiet */
+    };
+    console.log = noop;
+    console.info = noop;
+    console.debug = noop;
+  } else {
+    console.log = originalConsoleLog;
+    console.info = originalConsoleInfo;
+    console.debug = originalConsoleDebug;
+  }
+}
+
+export function isQuiet(): boolean {
+  return quiet;
+}
+
+export const cliLog = {
+  /**
+   * Informational progress message. Silenced under `--quiet`. Goes to
+   * stderr (not stdout) so that it never contaminates stdout-payload
+   * commands even when they're inadvertently mixed in.
+   */
+  info(...args: unknown[]): void {
+    if (quiet) return;
+    process.stderr.write(args.map(stringifyArg).join(' ') + '\n');
+  },
+
+  /**
+   * Warning. Always written (even under quiet) — warnings should reach
+   * the operator. Goes to stderr.
+   */
+  warn(...args: unknown[]): void {
+    process.stderr.write(args.map(stringifyArg).join(' ') + '\n');
+  },
+
+  /**
+   * Error. Always written (even under quiet). Goes to stderr.
+   */
+  error(...args: unknown[]): void {
+    process.stderr.write(args.map(stringifyArg).join(' ') + '\n');
+  },
+
+  /**
+   * Programmatic command output — the "result payload" a caller parses.
+   * Writes to stdout and is **never** silenced by `--quiet`.
+   *
+   * Use this **only** for output where stdout is the contract:
+   *   - `--json` branches: `cliLog.output(JSON.stringify(result, null, 2))`
+   *   - raw file content: `read` / `read-transpiled` print bytes via
+   *     `cliLog.output(result.content ?? '')`
+   *   - any other stdout-as-API output a script or the software factory
+   *     pipes/parses
+   *
+   * Do **not** use this for human-facing decorative lines (colored
+   * confirmations, status, summaries, progress). Those go to
+   * `console.log` so the `--quiet` interceptor can silence them.
+   * If you're tempted to wrap the string in ANSI escapes from
+   * `lib/colors`, you want `console.log`, not `cliLog.output`.
+   */
+  output(...args: unknown[]): void {
+    process.stdout.write(args.map(stringifyArg).join(' ') + '\n');
+  },
+};
+
+function stringifyArg(arg: unknown): string {
+  if (typeof arg === 'string') return arg;
+  if (arg instanceof Error) return arg.stack ?? arg.message;
+  try {
+    return JSON.stringify(arg);
+  } catch {
+    return String(arg);
+  }
+}

package/src/lib/colors.ts

@@ -1,9 +1,14 @@
-// ANSI color codes
-export const FG_GREEN = '\x1b[32m';
-export const FG_YELLOW = '\x1b[33m';
-export const FG_CYAN = '\x1b[36m';
-export const FG_MAGENTA = '\x1b[35m';
-export const FG_RED = '\x1b[31m';
-export const DIM = '\x1b[2m';
-export const BOLD = '\x1b[1m';
-export const RESET = '\x1b[0m';
+// Disable ANSI escapes when stdout isn't a TTY (piped to file/pager) or
+// NO_COLOR is set — see https://no-color.org. Evaluated at module load.
+const COLOR_ENABLED = process.stdout.isTTY === true && !process.env.NO_COLOR;
+
+const c = (code: string): string => (COLOR_ENABLED ? code : '');
+
+export const FG_GREEN = c('\x1b[32m');
+export const FG_YELLOW = c('\x1b[33m');
+export const FG_CYAN = c('\x1b[36m');
+export const FG_MAGENTA = c('\x1b[35m');
+export const FG_RED = c('\x1b[31m');
+export const DIM = c('\x1b[2m');
+export const BOLD = c('\x1b[1m');
+export const RESET = c('\x1b[0m');