@cardstack/boxel-cli 0.0.1 → 0.1.1

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

package/src/commands/file/touch.ts

@@ -0,0 +1,222 @@
+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 { listFiles } from './list';
+import { read } from './read';
+import { write } from './write';
+import { FG_GREEN, FG_RED, DIM, RESET } from '../../lib/colors';
+
+export interface TouchResult {
+  ok: boolean;
+  touched: string[];
+  skipped: { path: string; reason: string }[];
+  error?: string;
+}
+
+export interface TouchCommandOptions {
+  /** When true, enumerate every `.json` and `.gts` file in the realm. */
+  all?: boolean;
+  /** When true, do not perform any state-changing requests. */
+  dryRun?: boolean;
+  profileManager?: ProfileManager;
+}
+
+interface TouchCliOptions {
+  realm: string;
+  all?: boolean;
+  dryRun?: boolean;
+  json?: boolean;
+}
+
+const TOUCH_COMMENT = '// touched for re-index';
+
+/**
+ * Touch one or more files in a realm to force re-indexing. The touch is a
+ * semantically-neutral mutation: a `_touched` timestamp in JSON `meta`,
+ * or a toggle of `// touched for re-index` for `.gts` files.
+ *
+ * Pass `all: true` (with empty `paths`) to touch every `.json` and `.gts`
+ * file enumerated via the realm's `_mtimes` endpoint.
+ */
+export async function touchFiles(
+  realmUrl: string,
+  paths: string[],
+  options?: TouchCommandOptions,
+): Promise<TouchResult> {
+  let pm = options?.profileManager ?? getProfileManager();
+  let active = pm.getActiveProfile();
+  if (!active) {
+    return {
+      ok: false,
+      touched: [],
+      skipped: [],
+      error: NO_ACTIVE_PROFILE_ERROR,
+    };
+  }
+
+  let targets: string[];
+
+  if (options?.all) {
+    if (paths.length > 0) {
+      return {
+        ok: false,
+        touched: [],
+        skipped: [],
+        error: 'Cannot pass file paths together with --all',
+      };
+    }
+    let listed = await listFiles(realmUrl, { profileManager: pm });
+    if (listed.error) {
+      return {
+        ok: false,
+        touched: [],
+        skipped: [],
+        error: listed.error,
+      };
+    }
+    targets = listed.filenames.filter(
+      (p) => (p.endsWith('.json') || p.endsWith('.gts')) && !isProtectedFile(p),
+    );
+  } else {
+    if (paths.length === 0) {
+      return {
+        ok: false,
+        touched: [],
+        skipped: [],
+        error: 'No file paths provided. Pass paths or use --all.',
+      };
+    }
+    targets = paths;
+  }
+
+  let touched: string[] = [];
+  let skipped: { path: string; reason: string }[] = [];
+
+  for (let path of targets) {
+    if (!path.endsWith('.json') && !path.endsWith('.gts')) {
+      skipped.push({ path, reason: 'unsupported extension' });
+      continue;
+    }
+
+    if (isProtectedFile(path)) {
+      skipped.push({ path, reason: 'protected file' });
+      continue;
+    }
+
+    let readResult = await read(realmUrl, path, { profileManager: pm });
+    if (!readResult.ok || readResult.content == null) {
+      skipped.push({ path, reason: readResult.error ?? 'read failed' });
+      continue;
+    }
+
+    if (options?.dryRun) {
+      touched.push(path);
+      continue;
+    }
+
+    let next = path.endsWith('.json')
+      ? touchJson(readResult.content)
+      : touchGts(readResult.content);
+
+    let writeResult = await write(realmUrl, path, next, {
+      profileManager: pm,
+    });
+    if (!writeResult.ok) {
+      skipped.push({ path, reason: writeResult.error ?? 'write failed' });
+      continue;
+    }
+
+    touched.push(path);
+  }
+
+  return { ok: skipped.length === 0, touched, skipped };
+}
+
+function touchJson(content: string): string {
+  try {
+    let data = JSON.parse(content);
+    if (data?.data) {
+      data.data.meta = { ...(data.data.meta ?? {}), _touched: Date.now() };
+      return JSON.stringify(data, null, 2) + '\n';
+    }
+  } catch {
+    // fall through to whitespace toggle
+  }
+  return toggleTrailingNewline(content);
+}
+
+function toggleTrailingNewline(content: string): string {
+  return content.endsWith('\n\n') ? content.slice(0, -1) : content + '\n';
+}
+
+function touchGts(content: string): string {
+  // Only strip the dedicated trailing marker line we ourselves appended,
+  // so occurrences inside string literals or unrelated comments are left
+  // untouched and the mutation stays semantically neutral.
+  let trailingMarker = `\n${TOUCH_COMMENT}\n`;
+  if (content.endsWith(trailingMarker)) {
+    return content.slice(0, -trailingMarker.length) + '\n';
+  }
+  return content.endsWith('\n')
+    ? content + TOUCH_COMMENT + '\n'
+    : content + '\n' + TOUCH_COMMENT + '\n';
+}
+
+export function registerTouchCommand(parent: Command): void {
+  parent
+    .command('touch')
+    .description(
+      'Force realm re-indexing of one or more files by making a semantically-neutral edit. ' +
+        '--all touches every .json/.gts in the realm without confirmation; use with care.',
+    )
+    .argument(
+      '[paths...]',
+      'Realm-relative file path(s) to touch (omit when using --all)',
+    )
+    .requiredOption('--realm <realm-url>', 'The realm URL to touch files in')
+    .option('--all', 'Touch every .json and .gts file in the realm')
+    .option('--dry-run', 'Print files that would be touched without writing')
+    .option('--json', 'Output raw JSON response')
+    .action(async (paths: string[], opts: TouchCliOptions) => {
+      let result: TouchResult;
+      try {
+        result = await touchFiles(opts.realm, paths, {
+          all: opts.all,
+          dryRun: opts.dryRun,
+        });
+      } 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 if (result.error) {
+        console.error(`${FG_RED}Error:${RESET} ${result.error}`);
+      } else {
+        let prefix = opts.dryRun ? `${DIM}[dry-run]${RESET} ` : '';
+        for (let path of result.touched) {
+          console.log(`${prefix}${FG_GREEN}touched${RESET} ${path}`);
+        }
+        for (let { path, reason } of result.skipped) {
+          console.log(
+            `${FG_RED}skipped${RESET} ${path} ${DIM}(${reason})${RESET}`,
+          );
+        }
+        let verb = opts.dryRun ? 'would touch' : 'touched';
+        console.log(
+          `\n${DIM}${verb} ${result.touched.length} file(s)${result.skipped.length > 0 ? `, skipped ${result.skipped.length}` : ''}${RESET}`,
+        );
+      }
+
+      if (!result.ok) {
+        process.exit(1);
+      }
+    });
+}

package/src/commands/file/write.ts

@@ -0,0 +1,152 @@
+import type { Command } from 'commander';
+import { readFileSync } 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, DIM, RESET } from '../../lib/colors';
+import { cliLog } from '../../lib/cli-log';
+
+export interface WriteResult {
+  ok: boolean;
+  error?: string;
+}
+
+export interface WriteCommandOptions {
+  profileManager?: ProfileManager;
+}
+
+interface WriteCliOptions {
+  realm: string;
+  file?: string;
+  json?: boolean;
+}
+
+/**
+ * Write a file to a realm. Content is sent as-is with card+source MIME type.
+ * Path should include the file extension.
+ *
+ * Uses the per-realm JWT via `ProfileManager.authedRealmFetch`.
+ */
+export async function write(
+  realmUrl: string,
+  path: string,
+  content: string,
+  options?: WriteCommandOptions,
+): Promise<WriteResult> {
+  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;
+
+  try {
+    let response = await pm.authedRealmFetch(url, {
+      method: 'POST',
+      headers: {
+        Accept: SupportedMimeType.CardSource,
+        'Content-Type': SupportedMimeType.CardSource,
+      },
+      body: content,
+    });
+
+    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 };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/** Write to stderr so hints don't pollute stdout (important when piping/--json). */
+function stderr(msg: string): void {
+  process.stderr.write(msg + '\n');
+}
+
+async function readStdin(): Promise<string> {
+  let chunks: Buffer[] = [];
+  for await (let chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
+export function registerWriteCommand(parent: Command): void {
+  parent
+    .command('write')
+    .description('Write a file to a realm (reads content from STDIN or --file)')
+    .argument(
+      '<path>',
+      'Realm-relative file path (e.g., hello.gts, Cards/my-card.json)',
+    )
+    .requiredOption('--realm <realm-url>', 'The realm URL to write to')
+    .option(
+      '--file <filepath>',
+      'Read content from a local file instead of STDIN',
+    )
+    .option('--json', 'Output raw JSON response')
+    .action(async (filePath: string, opts: WriteCliOptions) => {
+      let content: string;
+      if (opts.file) {
+        try {
+          content = readFileSync(opts.file, 'utf-8');
+        } catch (err) {
+          stderr(
+            `${FG_RED}Error:${RESET} Could not read file: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          process.exit(1);
+        }
+      } else {
+        if (process.stdin.isTTY) {
+          stderr(
+            `${DIM}Reading from STDIN. Type or paste content, then press Enter followed by Ctrl+D to finish.${RESET}`,
+          );
+        }
+        content = await readStdin();
+        stderr(
+          `${DIM}Received ${content.length} bytes. Writing to realm...${RESET}`,
+        );
+      }
+
+      let result: WriteResult;
+      try {
+        result = await write(opts.realm, filePath, content);
+      } catch (err) {
+        stderr(
+          `${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(
+          `${FG_GREEN}Written:${RESET} ${filePath} ${DIM}→${RESET} ${opts.realm}`,
+        );
+      } else {
+        stderr(`${FG_RED}Error:${RESET} ${result.error}`);
+      }
+
+      if (!result.ok) {
+        process.exit(1);
+      }
+    });
+}