@cardstack/boxel-cli 0.0.1 → 0.1.0

package/src/commands/search.ts

@@ -0,0 +1,160 @@
+import type { Command } from 'commander';
+import {
+  getProfileManager,
+  NO_ACTIVE_PROFILE_ERROR,
+  type ProfileManager,
+} from '../lib/profile-manager';
+import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
+import { FG_RED, DIM, RESET } from '../lib/colors';
+import { cliLog } from '../lib/cli-log';
+
+export interface SearchResult {
+  ok: boolean;
+  status?: number;
+  data?: Record<string, unknown>[];
+  error?: string;
+}
+
+export interface SearchCommandOptions {
+  profileManager?: ProfileManager;
+}
+
+/**
+ * Federated search across one or more realms via the `_federated-search`
+ * server endpoint.
+ *
+ * Sends a QUERY request with the provided query object and a `realms` array
+ * merged into the request body. Uses the server JWT via
+ * `ProfileManager.authedRealmServerFetch`.
+ */
+export async function search(
+  realmUrls: string | string[],
+  query: Record<string, unknown>,
+  options?: SearchCommandOptions,
+): Promise<SearchResult> {
+  let pm = options?.profileManager ?? getProfileManager();
+  let active = pm.getActiveProfile();
+  if (!active) {
+    return {
+      ok: false,
+      error: NO_ACTIVE_PROFILE_ERROR,
+    };
+  }
+
+  let realmServerUrl = active.profile.realmServerUrl.replace(/\/$/, '');
+  let searchUrl = `${realmServerUrl}/_federated-search`;
+
+  let realms = (Array.isArray(realmUrls) ? realmUrls : [realmUrls]).map(
+    ensureTrailingSlash,
+  );
+
+  try {
+    let response = await pm.authedRealmServerFetch(searchUrl, {
+      method: 'QUERY',
+      headers: {
+        Accept: 'application/vnd.card+json',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ realms, ...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, status: response.status, data: result.data };
+  } catch (err) {
+    return {
+      ok: false,
+      status: 0,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+interface SearchCliOptions {
+  realm: string[];
+  query: string;
+  json?: boolean;
+}
+
+export function registerSearchCommand(program: Command): void {
+  program
+    .command('search')
+    .description('Federated search across realms using a JSON query')
+    .requiredOption(
+      '--realm <realm-url>',
+      'Realm URL to search (repeatable)',
+      (val: string, acc: string[]) => {
+        acc.push(val);
+        return acc;
+      },
+      [] as string[],
+    )
+    .requiredOption('--query <json>', 'JSON query object (as a string)')
+    .option('--json', 'Output raw JSON response')
+    .action(async (opts: SearchCliOptions) => {
+      if (opts.realm.length === 0) {
+        console.error(
+          `${FG_RED}Error:${RESET} At least one --realm is required`,
+        );
+        process.exit(1);
+      }
+
+      let query: Record<string, unknown>;
+      try {
+        let parsed = JSON.parse(opts.query);
+        if (
+          typeof parsed !== 'object' ||
+          parsed === null ||
+          Array.isArray(parsed)
+        ) {
+          console.error(
+            `${FG_RED}Error:${RESET} --query must be a JSON object, got ${Array.isArray(parsed) ? 'array' : typeof parsed}`,
+          );
+          process.exit(1);
+        }
+        query = parsed as Record<string, unknown>;
+      } catch (err) {
+        console.error(
+          `${FG_RED}Error:${RESET} Invalid JSON in --query: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        process.exit(1);
+        return; // unreachable, but helps TS
+      }
+
+      let result: SearchResult;
+      try {
+        result = await search(opts.realm, query);
+      } catch (err) {
+        console.error(
+          `${FG_RED}Error:${RESET} ${err instanceof Error ? err.message : String(err)}`,
+        );
+        process.exit(1);
+        return;
+      }
+
+      if (opts.json) {
+        cliLog.output(JSON.stringify(result, null, 2));
+      } else if (result.ok) {
+        cliLog.output(JSON.stringify(result.data ?? [], null, 2));
+      } else {
+        console.error(
+          `${DIM}Status:${RESET} ${result.status ?? '(no status)'}`,
+        );
+        console.error(`${FG_RED}Error:${RESET} ${result.error}`);
+      }
+
+      if (!result.ok) {
+        process.exit(1);
+      }
+    });
+}

package/src/index.ts

@@ -3,8 +3,12 @@ import { Command } from 'commander';
 import { readFileSync } from 'fs';
 import { resolve } from 'path';
 import { profileCommand } from './commands/profile';
+import { registerReadTranspiledCommand } from './commands/read-transpiled';
 import { registerRealmCommand } from './commands/realm/index';
+import { registerFileCommand } from './commands/file/index';
 import { registerRunCommand } from './commands/run-command';
+import { registerSearchCommand } from './commands/search';
+import { setQuiet } from './lib/cli-log';
 
 const pkg = JSON.parse(
   readFileSync(resolve(__dirname, '../package.json'), 'utf-8'),
@@ -12,10 +16,36 @@ const pkg = JSON.parse(
 
 const program = new Command();
 
+// `--quiet` is implemented by intercepting `console.log/info/debug`.
+// New commands: write decorative output (status, confirmations, colored
+// lines) with `console.log` — it's silenced for free under `--quiet`.
+// For programmatic output (`--json` payloads, raw file bytes), use
+// `cliLog.output(...)`. Full guidance: see `lib/cli-log.ts`.
 program
   .name('boxel')
   .description('CLI tools for Boxel workspace management')
-  .version(pkg.version);
+  .version(pkg.version)
+  .option(
+    '-q, --quiet',
+    'Suppress informational progress logs (info/log/debug). Errors and warnings, plus command result payloads (JSON, file contents), are still emitted. Use this when invoking the CLI from automation (e.g. the software factory test harness) to keep stdout focused on the result.',
+  )
+  // Toggle quiet mode as soon as the global option is parsed, so that any
+  // module-level setup happening inside command actions sees the right
+  // state. Commander invokes this hook before any subcommand action.
+  .hook('preAction', (thisCommand) => {
+    let opts = thisCommand.optsWithGlobals?.() ?? thisCommand.opts();
+    if (opts.quiet) {
+      setQuiet(true);
+    }
+  });
+
+// Belt-and-suspenders: also flip quiet mode based on a raw scan of argv,
+// so any code that runs between Commander's option parsing and the
+// `preAction` hook sees the right state. We scan for the long form only;
+// `-q` could legitimately be the value of another option in the future.
+if (process.argv.includes('--quiet')) {
+  setQuiet(true);
+}
 
 program
   .command('profile')
@@ -25,11 +55,36 @@ program
   .option('-u, --user <matrixId>', 'Matrix user ID (e.g., @user:boxel.ai)')
   .option('-p, --password <password>', 'Password (for add command)')
   .option('-n, --name <displayName>', 'Display name (for add command)')
+  .option(
+    '-m, --matrix-url <url>',
+    'Matrix server URL (for add command with non-standard domains)',
+  )
+  .option(
+    '-r, --realm-server-url <url>',
+    'Realm server URL (for add command with non-standard domains)',
+  )
+  .addHelpText(
+    'after',
+    `
+Environment variables (for 'add'):
+  BOXEL_PASSWORD       Password; preferred over -p to avoid shell history.
+  BOXEL_ENVIRONMENT    An env-mode slug (e.g. a branch name), interpreted
+                       like scripts/env-slug.sh: URLs are derived as
+                       http://matrix.<slug>.localhost and
+                       http://realm-server.<slug>.localhost/. Overridden
+                       by --matrix-url / --realm-server-url if provided.`,
+  )
   .action(
     async (
       subcommand?: string,
       arg?: string,
-      options?: { user?: string; password?: string; name?: string },
+      options?: {
+        user?: string;
+        password?: string;
+        name?: string;
+        matrixUrl?: string;
+        realmServerUrl?: string;
+      },
     ) => {
       if (options?.password) {
         console.warn(
@@ -41,7 +96,10 @@ program
     },
   );
 
+registerFileCommand(program);
 registerRealmCommand(program);
 registerRunCommand(program);
+registerSearchCommand(program);
+registerReadTranspiledCommand(program);
 
 program.parse();

package/src/lib/auth-resolver.ts

@@ -0,0 +1,58 @@
+import {
+  getProfileManager,
+  type ProfileManager,
+  NO_ACTIVE_PROFILE_ERROR,
+} from './profile-manager';
+import type { RealmAuthenticator } from './realm-authenticator';
+import { SeedAuthenticator } from './seed-auth';
+
+export interface AuthResolverOptions {
+  /** Realm URL the command is operating on (used for registering the seed-auth cache). */
+  realmUrl: string;
+  /**
+   * Already-resolved realm secret seed. Callers who want env + prompt
+   * resolution should go through `resolveRealmSecretSeed` in `./prompt` first.
+   */
+  realmSecretSeed?: string;
+  /** Override the ProfileManager (tests). When seed mode is active we won't touch it. */
+  profileManager?: ProfileManager;
+}
+
+export type AuthResolution =
+  | { ok: true; authenticator: RealmAuthenticator; mode: 'seed' | 'profile' }
+  | { ok: false; error: string };
+
+/**
+ * Pick between seed-based auth and profile-based auth.
+ *
+ *  - If `realmSecretSeed` is present, use `SeedAuthenticator`. We do NOT
+ *    require a profile in this mode — operators using the seed typically
+ *    don't have a Matrix account configured.
+ *  - Otherwise, fall back to the profile flow and require an active profile.
+ */
+export function resolveRealmAuthenticator(
+  options: AuthResolverOptions,
+): AuthResolution {
+  if (options.realmSecretSeed) {
+    // registerRealmUrl throws on a malformed realm URL; surface that as a
+    // resolver error so pull/push/sync keep their friendly CLI error path.
+    try {
+      const authenticator = new SeedAuthenticator({
+        seed: options.realmSecretSeed,
+      });
+      authenticator.registerRealmUrl(options.realmUrl);
+      return { ok: true, authenticator, mode: 'seed' };
+    } catch (error) {
+      return {
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  const pm = options.profileManager ?? getProfileManager();
+  if (!pm.getActiveProfile()) {
+    return { ok: false, error: NO_ACTIVE_PROFILE_ERROR };
+  }
+  return { ok: true, authenticator: pm, mode: 'profile' };
+}

package/src/lib/auth.ts

@@ -14,6 +14,7 @@ interface MatrixLoginResponse {
 }
 
 import { APP_BOXEL_REALMS_EVENT_TYPE } from '@cardstack/runtime-common/matrix-constants';
+import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
 
 export async function matrixLogin(
   matrixUrl: string,
@@ -127,31 +128,40 @@ export async function getRealmTokens(
   return (await response.json()) as RealmTokens;
 }
 
-export async function addRealmToMatrixAccountData(
-  matrixAuth: MatrixAuth,
-  realmUrl: string,
-): Promise<void> {
-  let accountDataUrl = new URL(
+function userRealmsAccountDataUrl(matrixAuth: MatrixAuth): string {
+  return new URL(
     `_matrix/client/v3/user/${encodeURIComponent(matrixAuth.userId)}/account_data/${APP_BOXEL_REALMS_EVENT_TYPE}`,
     matrixAuth.matrixUrl,
   ).href;
+}
 
-  let existingRealms: string[] = [];
+export async function getUserRealmsFromMatrixAccountData(
+  matrixAuth: MatrixAuth,
+): Promise<string[]> {
   try {
-    let getResponse = await fetch(accountDataUrl, {
+    let response = await fetch(userRealmsAccountDataUrl(matrixAuth), {
       headers: { Authorization: `Bearer ${matrixAuth.accessToken}` },
     });
-    if (getResponse.ok) {
-      let data = (await getResponse.json()) as { realms?: string[] };
-      existingRealms = Array.isArray(data.realms) ? [...data.realms] : [];
+    if (!response.ok) {
+      return [];
     }
+    let data = (await response.json()) as { realms?: string[] };
+    return Array.isArray(data.realms) ? [...data.realms] : [];
   } catch {
-    // Best-effort — if we can't read existing realms, start fresh
+    // Best-effort — treat unreachable account data as an empty list
+    return [];
   }
+}
+
+export async function addRealmToMatrixAccountData(
+  matrixAuth: MatrixAuth,
+  realmUrl: string,
+): Promise<void> {
+  let existingRealms = await getUserRealmsFromMatrixAccountData(matrixAuth);
 
   if (!existingRealms.includes(realmUrl)) {
     existingRealms.push(realmUrl);
-    let putResponse = await fetch(accountDataUrl, {
+    let putResponse = await fetch(userRealmsAccountDataUrl(matrixAuth), {
       method: 'PUT',
       headers: {
         'Content-Type': 'application/json',
@@ -167,3 +177,37 @@ export async function addRealmToMatrixAccountData(
     }
   }
 }
+
+// Returns true when at least one entry was removed and a write occurred,
+// false when no entry matched the URL (caller decides how to surface that
+// to the user). Comparison is normalized via `ensureTrailingSlash` and every
+// matching entry is dropped, so legacy duplicates like `https://host/realm`
+// + `https://host/realm/` are both cleaned out in a single PUT.
+export async function removeRealmFromMatrixAccountData(
+  matrixAuth: MatrixAuth,
+  realmUrl: string,
+): Promise<boolean> {
+  let target = ensureTrailingSlash(realmUrl);
+  let existingRealms = await getUserRealmsFromMatrixAccountData(matrixAuth);
+  let next = existingRealms.filter(
+    (url) => ensureTrailingSlash(url) !== target,
+  );
+  if (next.length === existingRealms.length) {
+    return false;
+  }
+  let putResponse = await fetch(userRealmsAccountDataUrl(matrixAuth), {
+    method: 'PUT',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${matrixAuth.accessToken}`,
+    },
+    body: JSON.stringify({ realms: next }),
+  });
+  if (!putResponse.ok) {
+    let text = await putResponse.text();
+    throw new Error(
+      `Failed to update Matrix account data: ${putResponse.status} ${text}`,
+    );
+  }
+  return true;
+}