@cardstack/boxel-cli 0.0.1 → 0.1.1

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

@@ -1,47 +1,25 @@
 import 'dotenv/config';
-import { Command } from 'commander';
 import { readFileSync } from 'fs';
 import { resolve } from 'path';
-import { profileCommand } from './commands/profile';
-import { registerRealmCommand } from './commands/realm/index';
-import { registerRunCommand } from './commands/run-command';
+import { buildBoxelProgram } from './build-program';
+import { setQuiet } from './lib/cli-log';
 
 const pkg = JSON.parse(
   readFileSync(resolve(__dirname, '../package.json'), 'utf-8'),
 );
 
-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`.
+//
+// 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
-  .name('boxel')
-  .description('CLI tools for Boxel workspace management')
-  .version(pkg.version);
-
-program
-  .command('profile')
-  .description('Manage saved profiles for different users/environments')
-  .argument('[subcommand]', 'list | add | switch | remove | migrate')
-  .argument('[arg]', 'Profile ID (for switch/remove)')
-  .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)')
-  .action(
-    async (
-      subcommand?: string,
-      arg?: string,
-      options?: { user?: string; password?: string; name?: string },
-    ) => {
-      if (options?.password) {
-        console.warn(
-          'Warning: Supplying a password via -p/--password may expose it in shell history and process listings. ' +
-            'For non-interactive usage, prefer the BOXEL_PASSWORD environment variable or use "boxel profile add" interactively.',
-        );
-      }
-      await profileCommand(subcommand, arg, options);
-    },
-  );
-
-registerRealmCommand(program);
-registerRunCommand(program);
-
-program.parse();
+buildBoxelProgram(pkg.version).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;
+}