@cardstack/boxel-cli 0.0.1 → 0.1.1

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@cardstack/boxel-cli",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "license": "MIT",
   "description": "CLI tools for Boxel workspace management",
   "main": "./dist/index.js",
   "bin": {
-    "boxel": "./dist/index.js"
+    "boxel": "./bin/boxel.js"
   },
   "files": [
     "dist/**/*",
@@ -28,36 +28,37 @@
   },
   "author": "Cardstack",
   "dependencies": {
-    "@aws-crypto/sha256-js": "^5.2.0",
+    "@aws-crypto/sha256-js": "catalog:",
     "commander": "^13.1.0",
     "dotenv": "^16.4.7",
-    "ignore": "^5.2.0",
+    "ignore": "catalog:",
+    "jsonwebtoken": "catalog:",
     "p-limit": "^7.3.0"
   },
   "devDependencies": {
-    "@types/node": "^24.3.0",
-    "@typescript-eslint/eslint-plugin": "^7.18.0",
-    "@typescript-eslint/parser": "^7.18.0",
-    "concurrently": "^8.2.2",
+    "@cardstack/local-types": "workspace:*",
+    "@cardstack/postgres": "workspace:*",
+    "@cardstack/runtime-common": "workspace:*",
+    "content-tag": "catalog:",
+    "@types/jsonwebtoken": "catalog:",
+    "@types/node": "catalog:",
+    "@typescript-eslint/eslint-plugin": "catalog:",
+    "@typescript-eslint/parser": "catalog:",
+    "concurrently": "catalog:",
     "esbuild": "^0.19.0",
-    "eslint": "^8.57.1",
-    "eslint-plugin-n": "^17.17.0",
-    "eslint-plugin-prettier": "^5.5.4",
-    "prettier": "^3.6.2",
+    "eslint": "catalog:",
+    "eslint-plugin-n": "catalog:",
+    "eslint-plugin-prettier": "catalog:",
+    "prettier": "catalog:",
     "ts-node": "^10.9.1",
-    "tsx": "^4.0.0",
-    "typescript": "~5.9.3",
-    "vite": "^6.3.2",
-    "vitest": "^2.1.9",
-    "@cardstack/local-types": "0.0.0",
-    "@cardstack/runtime-common": "1.0.0",
-    "@cardstack/postgres": "0.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vitest": "catalog:"
   },
   "scripts": {
-    "build": "pnpm clean && tsx scripts/build.ts",
+    "build": "pnpm clean && NODE_NO_WARNINGS=1 ts-node --transpileOnly scripts/build.ts",
+    "build:plugin": "NODE_NO_WARNINGS=1 ts-node --transpileOnly scripts/build-plugin.ts",
+    "build:skills": "NODE_NO_WARNINGS=1 ts-node --transpileOnly scripts/build-skills.ts",
     "clean": "rm -rf dist/*",
     "start": "NODE_NO_WARNINGS=1 ts-node --transpileOnly src/index.ts",
     "lint": "concurrently \"pnpm:lint:*(!fix)\" --names \"lint:\"",
@@ -67,12 +68,20 @@
     "lint:types": "tsc --noEmit",
     "test": "vitest run",
     "test:unit": "vitest run --exclude 'tests/integration/**'",
+    "test:unit-exclude-smoke": "vitest run --exclude 'tests/integration/**' --exclude 'tests/smoke.test.ts'",
     "test:integration": "./tests/scripts/run-integration-with-test-pg.sh",
     "test:watch": "vitest",
     "version:patch": "npm version patch",
     "version:minor": "npm version minor",
     "version:major": "npm version major",
-    "publish:npm": "npm publish",
-    "publish:dry": "npm publish --dry-run"
+    "publish:npm": "pnpm publish --no-git-checks",
+    "publish:dry": "pnpm publish --dry-run --no-git-checks"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "bin": {
+      "boxel": "./dist/index.js"
+    }
   }
-}
+}

package/src/build-program.ts

@@ -0,0 +1,91 @@
+import { Command } from 'commander';
+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';
+
+/**
+ * Construct the boxel CLI program with every command registered. Pure builder
+ * — does not call `program.parse()` and has no side effects on argv. Both the
+ * runtime entry point (`src/index.ts`) and the plugin generator
+ * (`scripts/build-plugin.ts`) call this so the Commander tree is one source of
+ * truth.
+ */
+export function buildBoxelProgram(version: string): Command {
+  const program = new Command();
+
+  program
+    .name('boxel')
+    .description('CLI tools for Boxel workspace management')
+    .version(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.',
+    )
+    .hook('preAction', (thisCommand) => {
+      let opts = thisCommand.optsWithGlobals?.() ?? thisCommand.opts();
+      if (opts.quiet) {
+        setQuiet(true);
+      }
+    });
+
+  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)')
+    .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;
+          matrixUrl?: string;
+          realmServerUrl?: 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);
+      },
+    );
+
+  registerFileCommand(program);
+  registerRealmCommand(program);
+  registerRunCommand(program);
+  registerSearchCommand(program);
+  registerReadTranspiledCommand(program);
+
+  return program;
+}

package/src/commands/file/delete.ts

@@ -0,0 +1,110 @@
+import type { Command } from 'commander';
+import {
+  getProfileManager,
+  NO_ACTIVE_PROFILE_ERROR,
+  type ProfileManager,
+} from '../../lib/profile-manager';
+import { isProtectedFile } from '../../lib/realm-sync-base';
+import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
+import { SupportedMimeType } from '@cardstack/runtime-common/supported-mime-type';
+import { FG_RED, DIM, RESET } from '../../lib/colors';
+import { cliLog } from '../../lib/cli-log';
+
+export interface DeleteResult {
+  ok: boolean;
+  error?: string;
+}
+
+export interface DeleteCommandOptions {
+  profileManager?: ProfileManager;
+}
+
+interface DeleteCliOptions {
+  realm: string;
+  json?: boolean;
+}
+
+/**
+ * Delete a file from a realm.
+ *
+ * Sends an HTTP DELETE request for the given path within the realm.
+ * Uses the per-realm JWT via `ProfileManager.authedRealmFetch`.
+ */
+export async function deleteFile(
+  realmUrl: string,
+  path: string,
+  options?: DeleteCommandOptions,
+): Promise<DeleteResult> {
+  let pm = options?.profileManager ?? getProfileManager();
+  let active = pm.getActiveProfile();
+  if (!active) {
+    return {
+      ok: false,
+      error: NO_ACTIVE_PROFILE_ERROR,
+    };
+  }
+
+  if (isProtectedFile(path)) {
+    return {
+      ok: false,
+      error: `Cannot delete protected file: ${path}`,
+    };
+  }
+
+  let url = new URL(path, ensureTrailingSlash(realmUrl)).href;
+
+  let response: Response;
+  try {
+    response = await pm.authedRealmFetch(url, {
+      method: 'DELETE',
+      headers: { Accept: SupportedMimeType.CardSource },
+    });
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+
+  if (!response.ok) {
+    let body = await response.text().catch(() => '(no body)');
+    return {
+      ok: false,
+      error: `HTTP ${response.status}: ${body.slice(0, 300)}`,
+    };
+  }
+
+  return { ok: true };
+}
+
+export function registerDeleteCommand(parent: Command): void {
+  parent
+    .command('delete')
+    .description('Delete a file from a realm')
+    .argument('<path>', 'Realm-relative file path to delete')
+    .requiredOption('--realm <realm-url>', 'The realm URL to delete from')
+    .option('--json', 'Output raw JSON response')
+    .action(async (filePath: string, opts: DeleteCliOptions) => {
+      let result: DeleteResult;
+      try {
+        result = await deleteFile(opts.realm, filePath);
+      } catch (err) {
+        console.error(
+          `${FG_RED}Error:${RESET} ${err instanceof Error ? err.message : String(err)}`,
+        );
+        process.exit(1);
+      }
+
+      if (opts.json) {
+        cliLog.output(JSON.stringify(result, null, 2));
+      } else if (result.ok) {
+        console.log(`${DIM}Deleted:${RESET} ${filePath}`);
+      } else {
+        console.error(`${FG_RED}Error:${RESET} ${result.error}`);
+      }
+
+      if (!result.ok) {
+        process.exit(1);
+      }
+    });
+}

package/src/commands/file/index.ts

@@ -0,0 +1,20 @@
+import type { Command } from 'commander';
+import { registerDeleteCommand } from './delete';
+import { registerListCommand } from './list';
+import { registerLintCommand } from './lint';
+import { registerReadCommand } from './read';
+import { registerTouchCommand } from './touch';
+import { registerWriteCommand } from './write';
+
+export function registerFileCommand(program: Command): void {
+  let file = program
+    .command('file')
+    .description('Read, write, search, and manage files in a realm');
+
+  registerDeleteCommand(file);
+  registerListCommand(file);
+  registerLintCommand(file);
+  registerReadCommand(file);
+  registerTouchCommand(file);
+  registerWriteCommand(file);
+}

package/src/commands/file/lint.ts

@@ -0,0 +1,235 @@
+import type { Command } from 'commander';
+import { readFileSync, writeFileSync } from 'fs';
+import {
+  getProfileManager,
+  NO_ACTIVE_PROFILE_ERROR,
+  type ProfileManager,
+} from '../../lib/profile-manager';
+import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
+import { SupportedMimeType } from '@cardstack/runtime-common/supported-mime-type';
+import { FG_GREEN, FG_RED, FG_YELLOW, DIM, RESET } from '../../lib/colors';
+import { cliLog } from '../../lib/cli-log';
+import { write } from './write';
+
+export interface LintMessage {
+  ruleId: string | null;
+  severity: 1 | 2;
+  message: string;
+  line: number;
+  column: number;
+  endLine?: number;
+  endColumn?: number;
+}
+
+export interface LintResult {
+  ok: boolean;
+  error?: string;
+  fixed?: boolean;
+  output?: string;
+  messages?: LintMessage[];
+}
+
+export interface LintCommandOptions {
+  profileManager?: ProfileManager;
+}
+
+/**
+ * Lint a single file's source code via the realm's `_lint` endpoint.
+ *
+ * Sends the source to `POST <realmUrl>/_lint` with `X-Filename` and
+ * `X-HTTP-Method-Override: QUERY` headers. Returns the lint result
+ * containing messages and optionally auto-fixed output.
+ *
+ * Uses the per-realm JWT via `ProfileManager.authedRealmFetch`.
+ */
+export async function lint(
+  realmUrl: string,
+  source: string,
+  filename: string,
+  options?: LintCommandOptions,
+): Promise<LintResult> {
+  let pm = options?.profileManager ?? getProfileManager();
+  let active = pm.getActiveProfile();
+  if (!active) {
+    return {
+      ok: false,
+      error: NO_ACTIVE_PROFILE_ERROR,
+    };
+  }
+
+  let lintUrl = `${ensureTrailingSlash(realmUrl)}_lint`;
+
+  try {
+    let response = await pm.authedRealmFetch(lintUrl, {
+      method: 'POST',
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': SupportedMimeType.CardSource,
+        'X-Filename': filename,
+        'X-HTTP-Method-Override': 'QUERY',
+      },
+      body: source,
+    });
+
+    if (!response.ok) {
+      let body = await response.text().catch(() => '(no body)');
+      return {
+        ok: false,
+        error: `HTTP ${response.status}: ${body.slice(0, 300)}`,
+      };
+    }
+
+    let json = (await response.json()) as {
+      fixed: boolean;
+      output: string;
+      messages: LintMessage[];
+    };
+
+    return {
+      ok: true,
+      fixed: json.fixed,
+      output: json.output,
+      messages: json.messages,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+interface LintCliOptions {
+  realm: string;
+  file?: string;
+  json?: boolean;
+  fix?: boolean;
+}
+
+export function registerLintCommand(parent: Command): void {
+  parent
+    .command('lint')
+    .description('Lint a file in a realm using the realm lint endpoint')
+    .argument('<path>', 'Realm-relative file path to lint (e.g., my-card.gts)')
+    .requiredOption('--realm <realm-url>', 'The realm URL to lint against')
+    .option(
+      '--file <local-filepath>',
+      'Read source from a local file instead of fetching from the realm',
+    )
+    .option('--json', 'Output raw JSON response')
+    .option('--fix', 'Write auto-fixed output back to the source')
+    .action(async (filePath: string, opts: LintCliOptions) => {
+      let pm = getProfileManager();
+      let active = pm.getActiveProfile();
+      if (!active) {
+        console.error(`${FG_RED}Error:${RESET} ${NO_ACTIVE_PROFILE_ERROR}`);
+        process.exit(1);
+      }
+
+      let source: string;
+
+      if (opts.file) {
+        try {
+          source = readFileSync(opts.file, 'utf-8');
+        } catch (err) {
+          console.error(
+            `${FG_RED}Error:${RESET} Could not read local file: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          process.exit(1);
+        }
+      } else {
+        let readUrl = new URL(filePath, ensureTrailingSlash(opts.realm)).href;
+        try {
+          let response = await pm.authedRealmFetch(readUrl, {
+            method: 'GET',
+            headers: { Accept: SupportedMimeType.CardSource },
+          });
+          if (!response.ok) {
+            let body = await response.text().catch(() => '(no body)');
+            console.error(
+              `${FG_RED}Error:${RESET} Could not read file from realm: HTTP ${response.status}: ${body.slice(0, 300)}`,
+            );
+            process.exit(1);
+          }
+          source = await response.text();
+        } catch (err) {
+          console.error(
+            `${FG_RED}Error:${RESET} ${err instanceof Error ? err.message : String(err)}`,
+          );
+          process.exit(1);
+        }
+      }
+
+      let result: LintResult;
+      try {
+        result = await lint(opts.realm, source, filePath, {
+          profileManager: pm,
+        });
+      } catch (err) {
+        console.error(
+          `${FG_RED}Error:${RESET} ${err instanceof Error ? err.message : String(err)}`,
+        );
+        process.exit(1);
+      }
+
+      if (opts.json) {
+        cliLog.output(JSON.stringify(result, null, 2));
+        if (!result.ok) {
+          process.exit(1);
+        }
+        return;
+      }
+
+      if (!result.ok) {
+        console.error(`${FG_RED}Error:${RESET} ${result.error}`);
+        process.exit(1);
+      }
+
+      // Handle --fix: write fixed output back to the source
+      if (opts.fix && result.fixed && result.output) {
+        if (opts.file) {
+          writeFileSync(opts.file, result.output, 'utf-8');
+          console.log(`${FG_GREEN}Fixed:${RESET} ${opts.file}`);
+        } else {
+          let writeResult = await write(opts.realm, filePath, result.output, {
+            profileManager: pm,
+          });
+          if (!writeResult.ok) {
+            console.error(
+              `${FG_RED}Error:${RESET} Could not write fixed file: ${writeResult.error}`,
+            );
+            process.exit(1);
+          }
+          console.log(
+            `${FG_GREEN}Fixed:${RESET} ${filePath} ${DIM}→${RESET} ${opts.realm}`,
+          );
+        }
+      }
+
+      let messages = result.messages ?? [];
+      let errors = messages.filter((m) => m.severity === 2);
+      let warnings = messages.filter((m) => m.severity === 1);
+
+      if (messages.length === 0) {
+        console.log(`${DIM}No lint issues found.${RESET}`);
+        return;
+      }
+
+      for (let msg of messages) {
+        let color = msg.severity === 2 ? FG_RED : FG_YELLOW;
+        let level = msg.severity === 2 ? 'error' : 'warning';
+        let rule = msg.ruleId ? ` (${msg.ruleId})` : '';
+        console.log(
+          `${color}${level}${RESET} ${msg.line}:${msg.column} ${msg.message}${DIM}${rule}${RESET}`,
+        );
+      }
+
+      console.log(
+        `\n${DIM}${errors.length} error(s), ${warnings.length} warning(s)${RESET}`,
+      );
+
+      if (errors.length > 0) {
+        process.exit(1);
+      }
+    });
+}

package/src/commands/file/list.ts

@@ -0,0 +1,121 @@
+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 { SupportedMimeType } from '@cardstack/runtime-common/supported-mime-type';
+import { FG_RED, DIM, RESET } from '../../lib/colors';
+import { cliLog } from '../../lib/cli-log';
+
+export interface ListFilesResult {
+  filenames: string[];
+  error?: string;
+}
+
+export interface ListFilesCommandOptions {
+  profileManager?: ProfileManager;
+}
+
+interface ListFilesCliOptions {
+  realm: string;
+  json?: boolean;
+}
+
+/**
+ * List all file paths in a realm via the `_mtimes` endpoint.
+ * Returns relative paths (e.g., `hello.gts`, `Cards/my-card.json`).
+ */
+export async function listFiles(
+  realmUrl: string,
+  options?: ListFilesCommandOptions,
+): Promise<ListFilesResult> {
+  let pm = options?.profileManager ?? getProfileManager();
+  let active = pm.getActiveProfile();
+  if (!active) {
+    return {
+      filenames: [],
+      error: NO_ACTIVE_PROFILE_ERROR,
+    };
+  }
+
+  let normalizedRealmUrl = ensureTrailingSlash(realmUrl);
+  let mtimesUrl = `${normalizedRealmUrl}_mtimes`;
+
+  try {
+    let response = await pm.authedRealmFetch(mtimesUrl, {
+      method: 'GET',
+      headers: { Accept: SupportedMimeType.Mtimes },
+    });
+
+    if (!response.ok) {
+      let body = await response.text().catch(() => '(no body)');
+      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),
+    };
+  }
+}
+
+export function registerListCommand(file: Command): void {
+  file
+    .command('list')
+    .alias('ls')
+    .description('List all files in a realm')
+    .requiredOption('--realm <realm-url>', 'The realm URL to list files from')
+    .option('--json', 'Output raw JSON response')
+    .action(async (opts: ListFilesCliOptions) => {
+      let result: ListFilesResult;
+      try {
+        result = await listFiles(opts.realm);
+      } catch (err) {
+        console.error(
+          `${FG_RED}Error:${RESET} ${err instanceof Error ? err.message : String(err)}`,
+        );
+        process.exit(1);
+      }
+
+      if (opts.json) {
+        cliLog.output(JSON.stringify(result, null, 2));
+        if (result.error) {
+          process.exit(1);
+        }
+      } else if (result.error) {
+        console.error(`${FG_RED}Error:${RESET} ${result.error}`);
+        process.exit(1);
+      } else {
+        for (let filename of result.filenames) {
+          console.log(`${DIM}${filename}${RESET}`);
+        }
+        console.log(`\n${DIM}${result.filenames.length} file(s)${RESET}`);
+      }
+    });
+}