@cardstack/boxel-cli 0.0.1

package/src/commands/run-command.ts

@@ -0,0 +1,186 @@
+import type { Command } from 'commander';
+import { getProfileManager, type ProfileManager } from '../lib/profile-manager';
+import { FG_GREEN, FG_RED, FG_CYAN, DIM, RESET } from '../lib/colors';
+
+export interface RunCommandResult {
+  status: 'ready' | 'error' | 'unusable';
+  result?: string | null;
+  error?: string | null;
+}
+
+export interface RunCommandOptions {
+  input?: Record<string, unknown>;
+  json?: boolean;
+  profileManager?: ProfileManager;
+}
+
+interface RunCommandCliOptions {
+  realm: string;
+  input?: string;
+  json?: boolean;
+}
+
+export async function runCommand(
+  commandSpecifier: string,
+  realmUrl: string,
+  options?: RunCommandOptions,
+): Promise<RunCommandResult> {
+  let pm = options?.profileManager ?? getProfileManager();
+  let active = pm.getActiveProfile();
+  if (!active) {
+    throw new Error(
+      'No active profile. Run `boxel profile add` to create one.',
+    );
+  }
+
+  let realmServerUrl = active.profile.realmServerUrl.replace(/\/$/, '');
+  let url = `${realmServerUrl}/_run-command`;
+
+  let body = {
+    data: {
+      type: 'run-command',
+      attributes: {
+        realmURL: realmUrl,
+        command: commandSpecifier,
+        commandInput: options?.input ?? null,
+      },
+    },
+  };
+
+  let response: Response;
+  try {
+    response = await pm.authedRealmServerFetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/vnd.api+json',
+        Accept: 'application/vnd.api+json',
+      },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    return {
+      status: 'error',
+      error: `run-command fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  if (!response.ok) {
+    let text = await response.text().catch(() => '(no body)');
+    return {
+      status: 'error',
+      error: `run-command HTTP ${response.status}: ${text}`,
+    };
+  }
+
+  let json: {
+    data?: {
+      attributes?: {
+        status?: string;
+        cardResultString?: string | null;
+        error?: string | null;
+      };
+    };
+  };
+
+  try {
+    json = await response.json();
+  } catch {
+    return {
+      status: 'error',
+      error: `run-command response was not valid JSON (HTTP ${response.status})`,
+    };
+  }
+
+  let attrs = json.data?.attributes;
+  return {
+    status: (attrs?.status as RunCommandResult['status']) ?? 'error',
+    result: attrs?.cardResultString ?? null,
+    error: attrs?.error ?? null,
+  };
+}
+
+export function registerRunCommand(program: Command): void {
+  program
+    .command('run-command')
+    .description(
+      'Execute a host command on the realm server via the prerenderer',
+    )
+    .argument(
+      '<command-specifier>',
+      'Command module path (e.g. @cardstack/boxel-host/commands/get-card-type-schema/default)',
+    )
+    .requiredOption(
+      '--realm <realm-url>',
+      'The realm URL context for the command',
+    )
+    .option('--input <json>', 'JSON string of command input')
+    .option('--json', 'Output raw JSON response')
+    .action(async (commandSpecifier: string, opts: RunCommandCliOptions) => {
+      let input: Record<string, unknown> | undefined;
+      if (opts.input) {
+        try {
+          let parsed = JSON.parse(opts.input);
+          if (
+            typeof parsed !== 'object' ||
+            parsed === null ||
+            Array.isArray(parsed)
+          ) {
+            console.error(
+              `${FG_RED}Error:${RESET} --input must be a JSON object, got ${Array.isArray(parsed) ? 'array' : typeof parsed}`,
+            );
+            process.exit(1);
+          }
+          input = parsed;
+        } catch {
+          console.error(
+            `${FG_RED}Error:${RESET} --input is not valid JSON: ${opts.input}`,
+          );
+          process.exit(1);
+        }
+      }
+
+      let result: RunCommandResult;
+      try {
+        result = await runCommand(commandSpecifier, opts.realm, { input });
+      } catch (err) {
+        console.error(
+          `${FG_RED}Error:${RESET} ${err instanceof Error ? err.message : String(err)}`,
+        );
+        process.exit(1);
+      }
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(
+          `${DIM}Status:${RESET} ${statusColor(result.status)}${result.status}${RESET}`,
+        );
+        if (result.result) {
+          console.log(`${DIM}Result:${RESET}`);
+          try {
+            console.log(JSON.stringify(JSON.parse(result.result), null, 2));
+          } catch {
+            console.log(result.result);
+          }
+        }
+        if (result.error) {
+          console.error(`${FG_RED}Error:${RESET} ${result.error}`);
+        }
+      }
+
+      if (result.status === 'error' || result.status === 'unusable') {
+        process.exit(1);
+      }
+    });
+}
+
+function statusColor(status: string): string {
+  switch (status) {
+    case 'ready':
+      return FG_GREEN;
+    case 'error':
+      return FG_RED;
+    default:
+      return FG_CYAN;
+  }
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+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';
+
+const pkg = JSON.parse(
+  readFileSync(resolve(__dirname, '../package.json'), 'utf-8'),
+);
+
+const program = new Command();
+
+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();

package/src/lib/auth.ts

@@ -0,0 +1,169 @@
+export interface MatrixAuth {
+  accessToken: string;
+  deviceId: string;
+  userId: string;
+  matrixUrl: string;
+}
+
+export type RealmTokens = Record<string, string>;
+
+interface MatrixLoginResponse {
+  access_token: string;
+  device_id: string;
+  user_id: string;
+}
+
+import { APP_BOXEL_REALMS_EVENT_TYPE } from '@cardstack/runtime-common/matrix-constants';
+
+export async function matrixLogin(
+  matrixUrl: string,
+  username: string,
+  password: string,
+): Promise<MatrixAuth> {
+  let response = await fetch(
+    new URL('_matrix/client/v3/login', matrixUrl).href,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        identifier: { type: 'm.id.user', user: username },
+        password,
+        type: 'm.login.password',
+      }),
+    },
+  );
+
+  let json = (await response.json()) as MatrixLoginResponse;
+  if (!response.ok) {
+    throw new Error(
+      `Matrix login failed: ${response.status} ${JSON.stringify(json)}`,
+    );
+  }
+
+  return {
+    accessToken: json.access_token,
+    deviceId: json.device_id,
+    userId: json.user_id,
+    matrixUrl,
+  };
+}
+
+async function getOpenIdToken(
+  matrixAuth: MatrixAuth,
+): Promise<Record<string, unknown>> {
+  let response = await fetch(
+    new URL(
+      `_matrix/client/v3/user/${encodeURIComponent(matrixAuth.userId)}/openid/request_token`,
+      matrixAuth.matrixUrl,
+    ).href,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${matrixAuth.accessToken}`,
+      },
+      body: '{}',
+    },
+  );
+
+  if (!response.ok) {
+    let text = await response.text();
+    throw new Error(`OpenID token request failed: ${response.status} ${text}`);
+  }
+
+  return (await response.json()) as Record<string, unknown>;
+}
+
+export async function getRealmServerToken(
+  matrixAuth: MatrixAuth,
+  realmServerUrl: string,
+): Promise<string> {
+  let openIdToken = await getOpenIdToken(matrixAuth);
+  let url = `${realmServerUrl.replace(/\/$/, '')}/_server-session`;
+
+  let response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(openIdToken),
+  });
+
+  if (!response.ok) {
+    let text = await response.text();
+    throw new Error(`Realm server session failed: ${response.status} ${text}`);
+  }
+
+  let token = response.headers.get('Authorization');
+  if (!token) {
+    throw new Error(
+      'Realm server session response did not include an Authorization header',
+    );
+  }
+  return token;
+}
+
+export async function getRealmTokens(
+  realmServerUrl: string,
+  serverToken: string,
+): Promise<RealmTokens> {
+  let url = `${realmServerUrl.replace(/\/$/, '')}/_realm-auth`;
+
+  let response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      Authorization: serverToken,
+    },
+  });
+
+  if (!response.ok) {
+    let text = await response.text();
+    throw new Error(`Realm auth lookup failed: ${response.status} ${text}`);
+  }
+
+  return (await response.json()) as RealmTokens;
+}
+
+export async function addRealmToMatrixAccountData(
+  matrixAuth: MatrixAuth,
+  realmUrl: string,
+): Promise<void> {
+  let accountDataUrl = new URL(
+    `_matrix/client/v3/user/${encodeURIComponent(matrixAuth.userId)}/account_data/${APP_BOXEL_REALMS_EVENT_TYPE}`,
+    matrixAuth.matrixUrl,
+  ).href;
+
+  let existingRealms: string[] = [];
+  try {
+    let getResponse = await fetch(accountDataUrl, {
+      headers: { Authorization: `Bearer ${matrixAuth.accessToken}` },
+    });
+    if (getResponse.ok) {
+      let data = (await getResponse.json()) as { realms?: string[] };
+      existingRealms = Array.isArray(data.realms) ? [...data.realms] : [];
+    }
+  } catch {
+    // Best-effort — if we can't read existing realms, start fresh
+  }
+
+  if (!existingRealms.includes(realmUrl)) {
+    existingRealms.push(realmUrl);
+    let putResponse = await fetch(accountDataUrl, {
+      method: 'PUT',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${matrixAuth.accessToken}`,
+      },
+      body: JSON.stringify({ realms: existingRealms }),
+    });
+    if (!putResponse.ok) {
+      let text = await putResponse.text();
+      throw new Error(
+        `Failed to update Matrix account data: ${putResponse.status} ${text}`,
+      );
+    }
+  }
+}