@cardstack/boxel-cli 0.0.1 → 0.1.0

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@cardstack/boxel-cli",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "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,35 @@
   },
   "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",
     "clean": "rm -rf dist/*",
     "start": "NODE_NO_WARNINGS=1 ts-node --transpileOnly src/index.ts",
     "lint": "concurrently \"pnpm:lint:*(!fix)\" --names \"lint:\"",
@@ -67,6 +66,7 @@
     "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",
@@ -74,5 +74,12 @@
     "version:major": "npm version major",
     "publish:npm": "npm publish",
     "publish:dry": "npm publish --dry-run"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "bin": {
+      "boxel": "./dist/index.js"
+    }
   }
-}
+}

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}`);
+      }
+    });
+}

package/src/commands/file/read.ts

@@ -0,0 +1,113 @@
+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 ReadResult {
+  ok: boolean;
+  status?: number;
+  /** Raw text content of the file. */
+  content?: string;
+  error?: string;
+}
+
+export interface ReadCommandOptions {
+  profileManager?: ProfileManager;
+}
+
+interface ReadCliOptions {
+  realm: string;
+  json?: boolean;
+}
+
+/**
+ * Read a file from a realm. Always returns the raw text content.
+ * Callers should parse the content themselves if needed (e.g. JSON).
+ *
+ * Uses the per-realm JWT via `ProfileManager.authedRealmFetch`.
+ */
+export async function read(
+  realmUrl: string,
+  path: string,
+  options?: ReadCommandOptions,
+): Promise<ReadResult> {
+  let pm = options?.profileManager ?? getProfileManager();
+  let active = pm.getActiveProfile();
+  if (!active) {
+    return {
+      ok: false,
+      error: NO_ACTIVE_PROFILE_ERROR,
+    };
+  }
+
+  let url = new URL(path, ensureTrailingSlash(realmUrl)).href;
+
+  let response: Response;
+  try {
+    response = await pm.authedRealmFetch(url, {
+      method: 'GET',
+      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,
+      status: response.status,
+      error: `HTTP ${response.status}: ${body.slice(0, 300)}`,
+    };
+  }
+
+  let text = await response.text();
+  return { ok: true, status: response.status, content: text };
+}
+
+export function registerReadCommand(parent: Command): void {
+  parent
+    .command('read')
+    .description('Read a file from a realm')
+    .argument(
+      '<path>',
+      'Realm-relative file path (e.g., hello-world.json, Cards/my-card.gts)',
+    )
+    .requiredOption('--realm <realm-url>', 'The realm URL to read from')
+    .option('--json', 'Output raw JSON response')
+    .action(async (filePath: string, opts: ReadCliOptions) => {
+      let result: ReadResult;
+      try {
+        result = await read(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) {
+        cliLog.output(result.content ?? '');
+      } else {
+        console.error(
+          `${DIM}Status:${RESET} ${result.status ?? '(no status)'}`,
+        );
+        console.error(`${FG_RED}Error:${RESET} ${result.error}`);
+      }
+
+      if (!result.ok) {
+        process.exit(1);
+      }
+    });
+}