@cardstack/boxel-cli 0.0.1

package/src/commands/profile.ts

@@ -0,0 +1,457 @@
+import * as readline from 'readline';
+import { Writable } from 'stream';
+import type { ProfileManager } from '../lib/profile-manager';
+import {
+  getProfileManager,
+  formatProfileBadge,
+  getEnvironmentFromMatrixId,
+  getEnvironmentLabel,
+  getUsernameFromMatrixId,
+} from '../lib/profile-manager';
+import {
+  FG_GREEN,
+  FG_YELLOW,
+  FG_CYAN,
+  FG_MAGENTA,
+  FG_RED,
+  DIM,
+  BOLD,
+  RESET,
+} from '../lib/colors';
+
+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());
+    });
+  });
+}
+
+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 = (char: Buffer) => {
+      try {
+        const c = char.toString();
+        if (c === '\n' || c === '\r') {
+          cleanup();
+          process.stdout.write('\n');
+          resolve(password);
+        } 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 {
+          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);
+    }
+  });
+}
+
+export interface ProfileCommandOptions {
+  user?: string;
+  password?: string;
+  name?: string;
+}
+
+export async function profileCommand(
+  subcommand?: string,
+  arg?: string,
+  options?: ProfileCommandOptions,
+): Promise<void> {
+  const manager = getProfileManager();
+
+  switch (subcommand) {
+    case 'list':
+      await listProfiles(manager);
+      break;
+
+    case 'add': {
+      const password = options?.password || process.env.BOXEL_PASSWORD;
+      if (options?.user && password) {
+        await addProfileNonInteractive(
+          manager,
+          options.user,
+          password,
+          options.name,
+        );
+      } else {
+        await addProfile(manager);
+      }
+      break;
+    }
+
+    case 'switch':
+      if (!arg) {
+        console.error(
+          `${FG_RED}Error:${RESET} Please specify a profile to switch to.`,
+        );
+        console.log(`Usage: boxel profile switch <profile-id>`);
+        console.log(`\nAvailable profiles:`);
+        await listProfiles(manager);
+        process.exit(1);
+      }
+      await switchProfile(manager, arg);
+      break;
+
+    case 'remove':
+      if (!arg) {
+        console.error(
+          `${FG_RED}Error:${RESET} Please specify a profile to remove.`,
+        );
+        process.exit(1);
+      }
+      await removeProfile(manager, arg);
+      break;
+
+    case 'migrate':
+      await migrateFromEnv(manager);
+      break;
+
+    default:
+      manager.printStatus();
+      console.log(`\n${DIM}Commands:${RESET}`);
+      console.log(
+        `  ${FG_CYAN}boxel profile list${RESET}      List all profiles`,
+      );
+      console.log(
+        `  ${FG_CYAN}boxel profile add${RESET}       Add a new profile`,
+      );
+      console.log(
+        `  ${FG_CYAN}boxel profile switch${RESET}    Switch active profile`,
+      );
+      console.log(
+        `  ${FG_CYAN}boxel profile remove${RESET}    Remove a profile`,
+      );
+      console.log(
+        `  ${FG_CYAN}boxel profile migrate${RESET}   Import from .env file`,
+      );
+  }
+}
+
+async function listProfiles(manager: ProfileManager): Promise<void> {
+  const profiles = manager.listProfiles();
+  const activeId = manager.getActiveProfileId();
+
+  if (profiles.length === 0) {
+    console.log(`\n${FG_YELLOW}No profiles configured.${RESET}`);
+    console.log(`Run ${FG_CYAN}boxel profile add${RESET} to create one.`);
+    return;
+  }
+
+  console.log(`\n${BOLD}Saved Profiles:${RESET}\n`);
+
+  for (const id of profiles) {
+    const profile = manager.getProfile(id)!;
+    const isActive = id === activeId;
+    const env = getEnvironmentFromMatrixId(id);
+
+    const marker = isActive ? `${FG_GREEN}\u2605${RESET} ` : '  ';
+    const envLabel = getEnvironmentLabel(env);
+    const envColor = env === 'production' ? FG_MAGENTA : FG_CYAN;
+
+    console.log(`${marker}${BOLD}${id}${RESET}`);
+    console.log(`    ${DIM}Name:${RESET} ${profile.displayName}`);
+    console.log(
+      `    ${DIM}Environment:${RESET} ${envColor}${envLabel}${RESET}`,
+    );
+    console.log(`    ${DIM}Realm Server:${RESET} ${profile.realmServerUrl}`);
+    console.log('');
+  }
+
+  if (activeId) {
+    console.log(`${DIM}\u2605 = active profile${RESET}`);
+  }
+}
+
+async function addProfile(manager: ProfileManager): Promise<void> {
+  console.log(`\n${BOLD}Add New Profile${RESET}\n`);
+
+  console.log(`Which environment?`);
+  console.log(`  ${FG_CYAN}1${RESET}) Staging (realms-staging.stack.cards)`);
+  console.log(`  ${FG_MAGENTA}2${RESET}) Production (app.boxel.ai)`);
+  console.log(`  ${FG_GREEN}3${RESET}) Local (localhost:4201)`);
+
+  const envChoice = await prompt('\nChoice [1/2/3]: ');
+  const isProduction = envChoice === '2';
+  const isLocal = envChoice === '3';
+
+  let domain: string;
+  let defaultMatrixUrl: string;
+  let defaultRealmUrl: string;
+
+  if (isLocal) {
+    domain = 'localhost';
+    defaultMatrixUrl = 'http://localhost:8008';
+    defaultRealmUrl = 'http://localhost:4201/';
+  } else if (isProduction) {
+    domain = 'boxel.ai';
+    defaultMatrixUrl = 'https://matrix.boxel.ai';
+    defaultRealmUrl = 'https://app.boxel.ai/';
+  } else {
+    domain = 'stack.cards';
+    defaultMatrixUrl = 'https://matrix-staging.stack.cards';
+    defaultRealmUrl = 'https://realms-staging.stack.cards/';
+  }
+
+  console.log(`\nEnter your Boxel username (without @ or domain)`);
+  console.log(`${DIM}Example: ctse, aallen90${RESET}`);
+  const username = await prompt('Username: ');
+
+  if (!username) {
+    console.error(`${FG_RED}Error:${RESET} Username is required.`);
+    process.exit(1);
+  }
+
+  const matrixId = `@${username}:${domain}`;
+
+  if (manager.getProfile(matrixId)) {
+    console.log(`\n${FG_YELLOW}Profile ${matrixId} already exists.${RESET}`);
+    const overwrite = await prompt('Overwrite? [y/N]: ');
+    if (overwrite.toLowerCase() !== 'y') {
+      console.log('Cancelled.');
+      return;
+    }
+  }
+
+  const password = await promptPassword('Password: ');
+
+  if (!password) {
+    console.error(`${FG_RED}Error:${RESET} Password is required.`);
+    process.exit(1);
+  }
+
+  const defaultDisplayName = `${username} \u00b7 ${domain}`;
+  const displayNameInput = await prompt(
+    `Display name [${defaultDisplayName}]: `,
+  );
+  const displayName = displayNameInput || defaultDisplayName;
+
+  await manager.addProfile(
+    matrixId,
+    password,
+    displayName,
+    defaultMatrixUrl,
+    defaultRealmUrl,
+  );
+
+  console.log(
+    `\n${FG_GREEN}\u2713${RESET} Profile created: ${formatProfileBadge(matrixId)}`,
+  );
+
+  if (manager.getActiveProfileId() === matrixId) {
+    console.log(`${DIM}This profile is now active.${RESET}`);
+  } else {
+    const switchNow = await prompt('Switch to this profile now? [Y/n]: ');
+    if (switchNow.toLowerCase() !== 'n') {
+      manager.switchProfile(matrixId);
+      console.log(
+        `${FG_GREEN}\u2713${RESET} Switched to ${formatProfileBadge(matrixId)}`,
+      );
+    }
+  }
+}
+
+async function switchProfile(
+  manager: ProfileManager,
+  profileId: string,
+): Promise<void> {
+  const profiles = manager.listProfiles();
+  let matchedId = profileId;
+
+  if (!profiles.includes(profileId)) {
+    const matches = profiles.filter((id) => {
+      const username = getUsernameFromMatrixId(id);
+      return id.includes(profileId) || username === profileId;
+    });
+
+    if (matches.length === 0) {
+      console.error(`${FG_RED}Error:${RESET} Profile not found: ${profileId}`);
+      console.log(`\nAvailable profiles:`);
+      for (const id of profiles) {
+        console.log(`  ${id}`);
+      }
+      process.exit(1);
+    } else if (matches.length === 1) {
+      matchedId = matches[0];
+    } else {
+      console.error(`${FG_RED}Error:${RESET} Ambiguous profile: ${profileId}`);
+      console.log(`\nMatching profiles:`);
+      for (const id of matches) {
+        console.log(`  ${id}`);
+      }
+      process.exit(1);
+    }
+  }
+
+  if (manager.switchProfile(matchedId)) {
+    console.log(
+      `${FG_GREEN}\u2713${RESET} Switched to ${formatProfileBadge(matchedId)}`,
+    );
+  } else {
+    console.error(`${FG_RED}Error:${RESET} Failed to switch profile.`);
+    process.exit(1);
+  }
+}
+
+async function removeProfile(
+  manager: ProfileManager,
+  profileId: string,
+): Promise<void> {
+  const profile = manager.getProfile(profileId);
+  if (!profile) {
+    console.error(`${FG_RED}Error:${RESET} Profile not found: ${profileId}`);
+    process.exit(1);
+  }
+
+  const confirm = await prompt(`Remove profile ${profileId}? [y/N]: `);
+  if (confirm.toLowerCase() !== 'y') {
+    console.log('Cancelled.');
+    return;
+  }
+
+  if (await manager.removeProfile(profileId)) {
+    console.log(`${FG_GREEN}\u2713${RESET} Profile removed.`);
+
+    const newActive = manager.getActiveProfileId();
+    if (newActive) {
+      console.log(`Active profile is now: ${formatProfileBadge(newActive)}`);
+    }
+  } else {
+    console.error(`${FG_RED}Error:${RESET} Failed to remove profile.`);
+    process.exit(1);
+  }
+}
+
+async function addProfileNonInteractive(
+  manager: ProfileManager,
+  matrixId: string,
+  password: string,
+  displayName?: string,
+): Promise<void> {
+  if (!matrixId.startsWith('@') || !matrixId.includes(':')) {
+    console.error(
+      `${FG_RED}Error:${RESET} Invalid Matrix ID format. Expected @user:domain`,
+    );
+    process.exit(1);
+  }
+
+  if (manager.getProfile(matrixId)) {
+    console.log(
+      `${FG_YELLOW}Profile ${matrixId} already exists. Updating password.${RESET}`,
+    );
+    await manager.updatePassword(matrixId, password);
+    if (displayName) {
+      manager.updateDisplayName(matrixId, displayName);
+    }
+    console.log(
+      `${FG_GREEN}\u2713${RESET} Profile updated: ${formatProfileBadge(matrixId)}`,
+    );
+    return;
+  }
+
+  await manager.addProfile(matrixId, password, displayName);
+  console.log(
+    `${FG_GREEN}\u2713${RESET} Profile created: ${formatProfileBadge(matrixId)}`,
+  );
+
+  const activeId = manager.getActiveProfileId();
+  if (activeId !== matrixId) {
+    console.log(
+      `${DIM}Use 'boxel profile switch ${matrixId}' to switch to this profile.${RESET}`,
+    );
+  }
+}
+
+async function migrateFromEnv(manager: ProfileManager): Promise<void> {
+  console.log(`\n${BOLD}Migrate from .env${RESET}\n`);
+
+  const matrixUrl = process.env.MATRIX_URL;
+  const username = process.env.MATRIX_USERNAME;
+  const password = process.env.MATRIX_PASSWORD;
+  const realmServerUrl = process.env.REALM_SERVER_URL;
+
+  if (!matrixUrl || !username || !password || !realmServerUrl) {
+    console.log(
+      `${FG_YELLOW}No complete credentials found in environment variables.${RESET}`,
+    );
+    console.log(
+      `\nRequired variables: MATRIX_URL, MATRIX_USERNAME, MATRIX_PASSWORD, REALM_SERVER_URL`,
+    );
+    return;
+  }
+
+  const result = await manager.migrateFromEnv();
+  if (result) {
+    if (result.created) {
+      console.log(
+        `${FG_GREEN}\u2713${RESET} Created profile: ${formatProfileBadge(result.profileId)}`,
+      );
+      console.log(
+        `\n${DIM}You can now remove credentials from .env if desired.${RESET}`,
+      );
+    } else {
+      console.log(
+        `${FG_YELLOW}Profile ${formatProfileBadge(result.profileId)} already exists.${RESET} Password has been updated if it changed.`,
+      );
+      console.log(
+        `\n${DIM}Use 'boxel profile add -u ${result.profileId} -p <password>' to update other fields.${RESET}`,
+      );
+    }
+  } else {
+    console.log(`${FG_YELLOW}Migration failed.${RESET}`);
+  }
+}

package/src/commands/realm/create.ts

@@ -0,0 +1,245 @@
+import type { Command } from 'commander';
+import {
+  iconURLFor,
+  getRandomBackgroundURL,
+} from '@cardstack/runtime-common/realm-display-defaults';
+import {
+  getProfileManager,
+  type ProfileManager,
+} from '../../lib/profile-manager';
+import { FG_GREEN, FG_CYAN, RESET } from '../../lib/colors';
+
+const REALM_NAME_PATTERN = /^[a-z0-9-]+$/;
+
+export function registerCreateCommand(realm: Command): void {
+  realm
+    .command('create')
+    .description('Create a new realm on the realm server')
+    .argument('<realm-name>', 'realm name (lowercase, numbers, hyphens only)')
+    .argument('<display-name>', 'display name for the realm')
+    .option('--background <url>', 'background image URL')
+    .option('--icon <url>', 'icon image URL')
+    .action(
+      async (
+        realmName: string,
+        displayName: string,
+        options: CreateCommandOptions,
+      ) => {
+        await executeCreateRealmCommand(realmName, displayName, options);
+      },
+    );
+}
+
+export interface CreateOptions {
+  background?: string;
+  icon?: string;
+  profileManager?: ProfileManager;
+  /** Wait for the realm to pass its readiness check (default: false). */
+  waitForReady?: boolean;
+}
+
+interface CreateCommandOptions {
+  background?: string;
+  icon?: string;
+}
+
+export interface CreateRealmResult {
+  realmUrl: string;
+  created: boolean;
+  realmToken?: string;
+}
+
+/**
+ * Core realm creation logic. Returns result on success, throws on failure.
+ * No console output or process.exit — suitable for programmatic use.
+ *
+ * Handles "already exists" gracefully by returning `created: false`
+ * with an authorization token for the existing realm.
+ */
+export async function createRealm(
+  realmName: string,
+  displayName: string,
+  options: CreateOptions = {},
+): Promise<CreateRealmResult> {
+  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 attributes: Record<string, string | undefined> = {
+    endpoint: realmName,
+    name: displayName,
+    backgroundURL: options.background ?? getRandomBackgroundURL(),
+    iconURL: options.icon ?? iconURLFor(displayName) ?? iconURLFor(realmName),
+  };
+
+  let response = await pm.authedRealmServerFetch(
+    `${realmServerUrl}/_create-realm`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/vnd.api+json' },
+      body: JSON.stringify({
+        data: { type: 'realm', attributes },
+      }),
+    },
+  );
+
+  if (!response.ok) {
+    let errorBody: string;
+    try {
+      errorBody = await response.text();
+    } catch {
+      errorBody = 'server returned a non-serialized object body';
+    }
+    if (errorBody.includes('[object Object]')) {
+      errorBody = 'server returned a non-serialized object body';
+    }
+
+    if (errorBody.includes('already exists')) {
+      let realmUrl = extractRealmUrlFromError(
+        errorBody,
+        realmServerUrl,
+        realmName,
+      );
+      let realmToken = await fetchRealmToken(pm, realmUrl);
+
+      try {
+        await pm.addToUserRealms(realmUrl);
+      } catch {
+        // Non-critical
+      }
+
+      return { realmUrl, created: false, realmToken };
+    }
+
+    throw new Error(`Realm server returned ${response.status}: ${errorBody}`);
+  }
+
+  let result = await response.json();
+  let rawRealmUrl = result?.data?.id;
+  if (typeof rawRealmUrl !== 'string' || rawRealmUrl.trim() === '') {
+    throw new Error(
+      `Realm server response did not include a realm URL (data.id) for "${realmName}".`,
+    );
+  }
+  let realmUrl = ensureTrailingSlash(rawRealmUrl);
+
+  let realmToken = await fetchRealmToken(pm, realmUrl);
+
+  try {
+    await pm.addToUserRealms(realmUrl);
+  } catch {
+    // Non-critical — realm still works without dashboard registration
+  }
+
+  if (options.waitForReady && realmToken) {
+    await waitForRealmReady(realmUrl, realmToken);
+  }
+
+  return {
+    realmUrl,
+    created: true,
+    realmToken,
+  };
+}
+
+async function fetchRealmToken(
+  pm: ProfileManager,
+  realmUrl: string,
+): Promise<string | undefined> {
+  try {
+    let serverToken = await pm.getOrRefreshServerToken();
+    return await pm.fetchAndStoreRealmToken(realmUrl, serverToken);
+  } catch {
+    return undefined;
+  }
+}
+
+async function waitForRealmReady(
+  realmUrl: string,
+  authorization: string,
+): Promise<void> {
+  let readinessUrl = new URL('_readiness-check', realmUrl).href;
+  let timeoutMs = 15_000;
+  let retryDelayMs = 250;
+  let startedAt = Date.now();
+  let lastError: string | undefined;
+
+  while (Date.now() - startedAt < timeoutMs) {
+    try {
+      let response = await fetch(readinessUrl, {
+        headers: {
+          Accept: 'application/vnd.api+json',
+          Authorization: authorization,
+        },
+      });
+
+      if (response.ok) {
+        return;
+      }
+
+      lastError = `HTTP ${response.status}`;
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+  }
+
+  throw new Error(
+    `Timed out waiting for realm ${realmUrl} to become ready${
+      lastError ? `: ${lastError}` : ''
+    }`,
+  );
+}
+
+/**
+ * CLI entry point for `boxel realm create`. Validates input, calls createRealm,
+ * formats output, and exits on error.
+ */
+async function executeCreateRealmCommand(
+  realmName: string,
+  displayName: string,
+  options: CreateCommandOptions,
+): Promise<void> {
+  if (!REALM_NAME_PATTERN.test(realmName)) {
+    console.error(
+      'Error: realm name must contain only lowercase letters, numbers, and hyphens',
+    );
+    process.exit(1);
+  }
+
+  try {
+    let result = await createRealm(realmName, displayName, options);
+    let verb = result.created ? 'created' : 'already exists';
+    console.log(
+      `${FG_GREEN}Realm ${verb}:${RESET} ${FG_CYAN}${result.realmUrl}${RESET}`,
+    );
+  } catch (e: unknown) {
+    console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(1);
+  }
+}
+
+function extractRealmUrlFromError(
+  errorBody: string,
+  realmServerUrl: string,
+  endpoint: string,
+): string {
+  let urlMatch = errorBody.match(/'(https?:\/\/[^']+)'/);
+  if (urlMatch) {
+    return ensureTrailingSlash(urlMatch[1]);
+  }
+  throw new Error(
+    `Could not determine realm URL from server error response for endpoint "${endpoint}" on "${realmServerUrl}". The response did not include an explicit realm URL.`,
+  );
+}
+
+function ensureTrailingSlash(url: string): string {
+  return url.endsWith('/') ? url : `${url}/`;
+}

package/src/commands/realm/index.ts

@@ -0,0 +1,16 @@
+import type { Command } from 'commander';
+import { registerCreateCommand } from './create';
+import { registerPullCommand } from './pull';
+import { registerPushCommand } from './push';
+import { registerSyncCommand } from './sync';
+
+export function registerRealmCommand(program: Command): void {
+  let realm = program
+    .command('realm')
+    .description('Manage realms on the realm server');
+
+  registerCreateCommand(realm);
+  registerPullCommand(realm);
+  registerPushCommand(realm);
+  registerSyncCommand(realm);
+}