@cardstack/boxel-cli 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardstack/boxel-cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "license": "MIT",
   "description": "CLI tools for Boxel workspace management",
   "main": "./dist/index.js",
@@ -52,8 +52,8 @@
     "vite": "^6.3.2",
     "vitest": "^2.1.9",
     "@cardstack/local-types": "0.0.0",
-    "@cardstack/postgres": "0.0.0",
-    "@cardstack/runtime-common": "1.0.0"
+    "@cardstack/runtime-common": "1.0.0",
+    "@cardstack/postgres": "0.0.0"
   },
   "publishConfig": {
     "access": "public",

package/src/commands/file/index.ts

@@ -9,7 +9,7 @@ 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');
+    .description('Read, write, and manage files in a realm');
 
   registerDeleteCommand(file);
   registerListCommand(file);

package/src/commands/realm/index.ts

@@ -3,6 +3,7 @@ import { registerCancelIndexingCommand } from './cancel-indexing';
 import { registerCreateCommand } from './create';
 import { registerHistoryCommand } from './history';
 import { registerListCommand } from './list';
+import { registerMilestoneCommand } from './milestone';
 import { registerPullCommand } from './pull';
 import { registerPushCommand } from './push';
 import { registerRemoveCommand } from './remove';
@@ -19,6 +20,7 @@ export function registerRealmCommand(program: Command): void {
   registerCreateCommand(realm);
   registerHistoryCommand(realm);
   registerListCommand(realm);
+  registerMilestoneCommand(realm);
   registerPullCommand(realm);
   registerPushCommand(realm);
   registerRemoveCommand(realm);

package/src/commands/realm/milestone.ts

@@ -0,0 +1,375 @@
+import * as fs from 'fs';
+import type { Command } from 'commander';
+import {
+  CheckpointManager,
+  type Checkpoint,
+} from '../../lib/checkpoint-manager';
+import { cliLog } from '../../lib/cli-log';
+import { findCheckpoint } from '../../lib/find-checkpoint';
+import {
+  BOLD,
+  DIM,
+  FG_CYAN,
+  FG_GREEN,
+  FG_MAGENTA,
+  FG_RED,
+  FG_YELLOW,
+  RESET,
+} from '../../lib/colors';
+
+const DEFAULT_LIMIT = 100;
+
+export interface MilestoneOptions {
+  /** A 1-based index, short hash, or full hash to mark as milestone. Requires `name`. */
+  mark?: string;
+  /** Name for the milestone (required when `mark` is given). */
+  name?: string;
+  /** A 1-based index, short hash, or full hash whose milestone tag to remove. */
+  remove?: string;
+  /** Max checkpoints to consider for ref resolution. Defaults to 100. */
+  limit?: number;
+}
+
+export interface MilestoneResult {
+  ok: boolean;
+  /** Populated in list mode. */
+  milestones?: Checkpoint[];
+  /** Populated when a milestone was marked. */
+  marked?: Checkpoint;
+  /** Populated when a milestone was removed. */
+  removed?: boolean;
+  error?: string;
+}
+
+interface MilestoneCliOptions {
+  mark?: string;
+  name?: string;
+  remove?: string;
+  limit?: string;
+  json?: boolean;
+}
+
+type StepResult<T> = ({ ok: true } & T) | { ok: false; error: string };
+
+function errorMessage(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+function formatRelativeDate(date: Date): string {
+  const diffMs = Date.now() - date.getTime();
+  const minutes = Math.floor(diffMs / 60_000);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+  if (days > 7)
+    return `${date.toLocaleDateString()} ${date.toLocaleTimeString()}`;
+  if (days > 0) return `${days} day${days === 1 ? '' : 's'} ago`;
+  if (hours > 0) return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+  if (minutes > 0) return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+  return 'just now';
+}
+
+async function resolveRef(
+  workspaceDir: string,
+  ref: string,
+  limit: number,
+): Promise<StepResult<{ target: Checkpoint }>> {
+  try {
+    const manager = new CheckpointManager(workspaceDir);
+    if (!(await manager.isInitialized())) {
+      return {
+        ok: false,
+        error:
+          'No checkpoint history found for this workspace. ' +
+          'Checkpoints are created automatically during sync operations.',
+      };
+    }
+    const checkpoints = await manager.getCheckpoints(limit);
+    const found = findCheckpoint(ref, checkpoints);
+    if (found.kind === 'none') {
+      return {
+        ok: false,
+        error: `Checkpoint not found: ${ref}. Use a number (1-${checkpoints.length}) or a commit hash.`,
+      };
+    }
+    if (found.kind === 'ambiguous') {
+      const sample = found.matches
+        .slice(0, 5)
+        .map((cp) => cp.shortHash)
+        .join(', ');
+      const more = found.matches.length > 5 ? ', …' : '';
+      return {
+        ok: false,
+        error: `Ambiguous reference: ${ref} matches ${found.matches.length} checkpoints (${sample}${more}). Use a longer prefix or full hash.`,
+      };
+    }
+    return { ok: true, target: found.target };
+  } catch (e) {
+    return {
+      ok: false,
+      error: `Failed to read checkpoints: ${errorMessage(e)}`,
+    };
+  }
+}
+
+async function listMilestonesStep(
+  workspaceDir: string,
+): Promise<StepResult<{ milestones: Checkpoint[] }>> {
+  if (!fs.existsSync(workspaceDir)) {
+    return { ok: false, error: `Directory not found: ${workspaceDir}` };
+  }
+  try {
+    const manager = new CheckpointManager(workspaceDir);
+    if (!(await manager.isInitialized())) {
+      return { ok: true, milestones: [] };
+    }
+    const milestones = await manager.getMilestones();
+    return { ok: true, milestones };
+  } catch (e) {
+    return {
+      ok: false,
+      error: `Failed to read milestones: ${errorMessage(e)}`,
+    };
+  }
+}
+
+async function markMilestoneStep(
+  workspaceDir: string,
+  ref: string,
+  name: string,
+  limit: number,
+): Promise<StepResult<{ marked: Checkpoint }>> {
+  if (!fs.existsSync(workspaceDir)) {
+    return { ok: false, error: `Directory not found: ${workspaceDir}` };
+  }
+  const trimmedName = name.trim();
+  if (!trimmedName) {
+    return { ok: false, error: '--name must not be empty.' };
+  }
+  const resolved = await resolveRef(workspaceDir, ref, limit);
+  if (!resolved.ok) return resolved;
+
+  try {
+    const manager = new CheckpointManager(workspaceDir);
+    const result = await manager.markMilestone(
+      resolved.target.hash,
+      trimmedName,
+    );
+    if (!result) {
+      return {
+        ok: false,
+        error: 'Could not mark milestone. The checkpoint may already have one.',
+      };
+    }
+    const checkpoints = await manager.getCheckpoints(limit);
+    const marked = checkpoints.find((cp) => cp.hash === resolved.target.hash);
+    if (!marked) {
+      return {
+        ok: false,
+        error: 'Milestone created but checkpoint could not be re-read.',
+      };
+    }
+    return { ok: true, marked };
+  } catch (e) {
+    return { ok: false, error: `Failed to mark milestone: ${errorMessage(e)}` };
+  }
+}
+
+async function removeMilestoneStep(
+  workspaceDir: string,
+  ref: string,
+  limit: number,
+): Promise<StepResult<{ removed: boolean }>> {
+  if (!fs.existsSync(workspaceDir)) {
+    return { ok: false, error: `Directory not found: ${workspaceDir}` };
+  }
+  const resolved = await resolveRef(workspaceDir, ref, limit);
+  if (!resolved.ok) return resolved;
+
+  const target = resolved.target;
+  if (!target.isMilestone) {
+    return {
+      ok: false,
+      error: `Checkpoint ${target.shortHash} is not marked as a milestone.`,
+    };
+  }
+
+  try {
+    const manager = new CheckpointManager(workspaceDir);
+    const success = await manager.unmarkMilestone(target.hash);
+    return { ok: true, removed: success };
+  } catch (e) {
+    return {
+      ok: false,
+      error: `Failed to remove milestone: ${errorMessage(e)}`,
+    };
+  }
+}
+
+/**
+ * List, mark, or remove milestones in a workspace's local `.boxel-history/` git repo.
+ * Pure local — does not touch the realm server.
+ */
+export async function realmMilestone(
+  workspaceDir: string,
+  options: MilestoneOptions = {},
+): Promise<MilestoneResult> {
+  if (options.mark !== undefined && options.remove !== undefined) {
+    return {
+      ok: false,
+      error: 'Only one of --mark or --remove may be specified.',
+    };
+  }
+  if (
+    options.limit !== undefined &&
+    (!Number.isInteger(options.limit) || options.limit <= 0)
+  ) {
+    return { ok: false, error: 'limit must be a positive integer.' };
+  }
+  const limit = options.limit ?? DEFAULT_LIMIT;
+
+  if (options.mark !== undefined) {
+    if (options.name === undefined) {
+      return { ok: false, error: '--name is required when using --mark.' };
+    }
+    const r = await markMilestoneStep(
+      workspaceDir,
+      options.mark,
+      options.name,
+      limit,
+    );
+    return r.ok
+      ? { ok: true, marked: r.marked }
+      : { ok: false, error: r.error };
+  }
+
+  if (options.remove !== undefined) {
+    const r = await removeMilestoneStep(workspaceDir, options.remove, limit);
+    return r.ok
+      ? { ok: true, removed: r.removed }
+      : { ok: false, error: r.error };
+  }
+
+  const r = await listMilestonesStep(workspaceDir);
+  return r.ok
+    ? { ok: true, milestones: r.milestones }
+    : { ok: false, error: r.error };
+}
+
+function printMilestones(milestones: Checkpoint[], workspaceDir: string): void {
+  if (milestones.length === 0) {
+    console.log('\nNo milestones marked yet.\n');
+    console.log(
+      `Use ${FG_CYAN}boxel realm milestone <local-dir> --mark <ref> --name <name>${RESET} to mark a checkpoint.`,
+    );
+    console.log(
+      `Use ${FG_CYAN}boxel realm history <local-dir>${RESET} to see available checkpoints.\n`,
+    );
+    return;
+  }
+
+  console.log(`\n${BOLD}Milestones${RESET} ${DIM}(${workspaceDir})${RESET}\n`);
+  for (const cp of milestones) {
+    const sourceIcon =
+      cp.source === 'local' ? '↑' : cp.source === 'remote' ? '↓' : '●';
+    const sourceColor =
+      cp.source === 'local'
+        ? FG_GREEN
+        : cp.source === 'remote'
+          ? FG_CYAN
+          : FG_MAGENTA;
+    console.log(
+      `  ${FG_YELLOW}⭐${RESET} ` +
+        `${FG_YELLOW}${cp.shortHash}${RESET} ` +
+        `${sourceColor}${sourceIcon}${RESET} ` +
+        `${FG_MAGENTA}[${cp.milestoneName}]${RESET} ` +
+        `${cp.message}`,
+    );
+    console.log(`     ${DIM}${formatRelativeDate(cp.date)}${RESET}`);
+  }
+  console.log();
+}
+
+function parseLimit(raw: string | undefined): number | null {
+  if (raw === undefined) return DEFAULT_LIMIT;
+  if (!/^\d+$/.test(raw)) return null;
+  const n = parseInt(raw, 10);
+  return n > 0 ? n : null;
+}
+
+function bailout(msg: string): never {
+  console.error(`${FG_RED}Error:${RESET} ${msg}`);
+  process.exit(1);
+}
+
+export function registerMilestoneCommand(realm: Command): void {
+  realm
+    .command('milestone')
+    .description(
+      'List, mark, or remove milestones in the local .boxel-history/ checkpoint log',
+    )
+    .argument('<local-dir>', 'The local workspace directory')
+    .option(
+      '--mark <ref>',
+      'Mark a checkpoint as a milestone (1-based index, short hash, or full hash)',
+    )
+    .option('--name <name>', 'Name for the milestone (required with --mark)')
+    .option(
+      '--remove <ref>',
+      'Remove the milestone tag from a checkpoint (1-based index, short hash, or full hash)',
+    )
+    .option(
+      '--limit <n>',
+      `Maximum number of checkpoints to consider for ref resolution (default: ${DEFAULT_LIMIT})`,
+    )
+    .option('--json', 'Output result as JSON')
+    .action(async (localDir: string, opts: MilestoneCliOptions) => {
+      if (opts.mark !== undefined && opts.remove !== undefined) {
+        bailout('Only one of --mark or --remove may be specified.');
+      }
+
+      const limit = parseLimit(opts.limit);
+      if (limit === null) {
+        bailout('--limit must be a positive integer.');
+      }
+
+      if (opts.mark !== undefined && opts.name === undefined) {
+        bailout('--name is required when using --mark.');
+      }
+
+      const result = await realmMilestone(localDir, {
+        mark: opts.mark,
+        name: opts.name,
+        remove: opts.remove,
+        limit,
+      });
+
+      if (opts.json) {
+        cliLog.output(JSON.stringify(result, null, 2));
+        if (!result.ok) process.exit(1);
+        return;
+      }
+
+      if (!result.ok) {
+        bailout(result.error!);
+      }
+
+      if (result.marked) {
+        const cp = result.marked;
+        console.log(
+          `\n${FG_GREEN}✓${RESET} ${FG_YELLOW}⭐${RESET} Milestone created: ${FG_MAGENTA}${cp.milestoneName}${RESET}`,
+        );
+        console.log(
+          `  Checkpoint: ${FG_YELLOW}${cp.shortHash}${RESET} ${cp.message}`,
+        );
+        console.log();
+        return;
+      }
+
+      if (result.removed !== undefined) {
+        console.log(`${FG_GREEN}✓${RESET} Milestone removed`);
+        return;
+      }
+
+      printMilestones(result.milestones!, localDir);
+    });
+}

package/src/commands/realm/watch/index.ts

@@ -0,0 +1,12 @@
+import type { Command } from 'commander';
+import { registerStartCommand } from './start';
+import { registerStopCommand } from './stop';
+
+export function registerWatchCommand(realm: Command): void {
+  const watch = realm
+    .command('watch')
+    .description('Watch a Boxel realm; subcommands manage watch processes');
+
+  registerStartCommand(watch);
+  registerStopCommand(watch);
+}

package/src/commands/realm/{watch.ts → watch/start.ts}

@@ -1,27 +1,31 @@
 import { InvalidArgumentError, type Command } from 'commander';
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import { RealmSyncBase, isProtectedFile } from '../../lib/realm-sync-base';
+import { RealmSyncBase, isProtectedFile } from '../../../lib/realm-sync-base';
 import {
   CheckpointManager,
   type Checkpoint,
   type CheckpointChange,
-} from '../../lib/checkpoint-manager';
+} from '../../../lib/checkpoint-manager';
 import {
   type SyncManifest,
   computeFileHash,
   loadManifest,
   saveManifest,
-} from '../../lib/sync-manifest';
-import type { ProfileManager } from '../../lib/profile-manager';
-import type { RealmAuthenticator } from '../../lib/realm-authenticator';
-import { resolveRealmAuthenticator } from '../../lib/auth-resolver';
-import { resolveRealmSecretSeed } from '../../lib/prompt';
+} from '../../../lib/sync-manifest';
+import type { ProfileManager } from '../../../lib/profile-manager';
+import type { RealmAuthenticator } from '../../../lib/realm-authenticator';
+import { resolveRealmAuthenticator } from '../../../lib/auth-resolver';
+import { resolveRealmSecretSeed } from '../../../lib/prompt';
 import {
   acquireWatchLock,
   releaseWatchLock,
   type WatchLockInfo,
-} from '../../lib/watch-lock';
+} from '../../../lib/watch-lock';
+import {
+  registerProcess,
+  unregisterCurrentProcess,
+} from '../../../lib/watch-process-registry';
 import {
   FG_CYAN,
   FG_GREEN,
@@ -29,7 +33,7 @@ import {
   FG_YELLOW,
   DIM,
   RESET,
-} from '../../lib/colors';
+} from '../../../lib/colors';
 
 export interface WatchRealmSpec {
   realmUrl: string;
@@ -472,6 +476,12 @@ export async function watchRealms(
     }, intervalMs);
   };
 
+  try {
+    await registerProcess(specs.map((s) => s.localDir).join(', '));
+  } catch {
+    // Best effort — registry failures must never block the watch.
+  }
+
   await tickAll();
   scheduleNextTick();
 
@@ -496,6 +506,11 @@ export async function watchRealms(
           // Best effort \u2014 a leftover lock will be detected as stale next run.
         }
       }
+      try {
+        await unregisterCurrentProcess();
+      } catch {
+        // Best effort \u2014 leftover entries are pruned on next read.
+      }
       resolve();
     };
 
@@ -572,11 +587,11 @@ function parseNonNegativeSeconds(name: string): (value: string) => number {
   };
 }
 
-export function registerWatchCommand(realm: Command): void {
-  realm
-    .command('watch')
+export function registerStartCommand(watch: Command): void {
+  watch
+    .command('start')
     .description(
-      'Watch a Boxel realm for server-side changes and pull them into a local directory',
+      'Start watching a Boxel realm for server-side changes and pull them into a local directory',
     )
     .argument(
       '<realm-url>',

package/src/commands/realm/watch/stop.ts

@@ -0,0 +1,151 @@
+import { execSync } from 'child_process';
+import type { Command } from 'commander';
+import { listRegisteredProcesses } from '../../../lib/watch-process-registry';
+import { DIM, FG_GREEN, FG_RED, RESET } from '../../../lib/colors';
+
+export interface StoppedProcess {
+  pid: number;
+  workspace: string;
+}
+
+export interface StopResult {
+  stopped: StoppedProcess[];
+  failed: StoppedProcess[];
+}
+
+const SETTLE_MS = 200;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function signalProcess(pid: number): { ok: boolean; alreadyGone: boolean } {
+  try {
+    if (process.platform === 'win32') {
+      try {
+        process.kill(pid);
+      } catch {
+        execSync(`taskkill /PID ${pid} /F`, { stdio: 'ignore' });
+      }
+    } else {
+      process.kill(pid, 'SIGINT');
+    }
+    return { ok: true, alreadyGone: false };
+  } catch (err: any) {
+    if (err?.code === 'ESRCH') {
+      return { ok: true, alreadyGone: true };
+    }
+    return { ok: false, alreadyGone: false };
+  }
+}
+
+interface PsHit {
+  pid: number;
+  workspace: string;
+}
+
+function findViaProcessTable(): PsHit[] {
+  if (process.platform === 'win32') return [];
+  let output: string;
+  try {
+    output = execSync(
+      'ps aux | grep -E "(tsx[[:space:]].*src/index\\.ts[[:space:]]+realm[[:space:]]+watch[[:space:]]+start|[[:space:]]boxel[[:space:]]+realm[[:space:]]+watch[[:space:]]+start|node[[:space:]].*boxel[[:space:]]+realm[[:space:]]+watch[[:space:]]+start)" | grep -v grep | grep -v "[[:space:]]stop"',
+      { encoding: 'utf8' },
+    ).trim();
+  } catch {
+    return [];
+  }
+  if (!output) return [];
+
+  const hits: PsHit[] = [];
+  const seen = new Set<number>();
+  for (const line of output.split('\n')) {
+    if (!line) continue;
+    const parts = line.trim().split(/\s+/);
+    const pid = Number.parseInt(parts[1] ?? '', 10);
+    if (!Number.isFinite(pid) || seen.has(pid)) continue;
+    seen.add(pid);
+
+    let workspace = '.';
+    const match = line.match(/\bstart\s+\S+\s+(\S+)/);
+    if (match && match[1] && !match[1].startsWith('-')) {
+      workspace = match[1];
+    }
+    hits.push({ pid, workspace });
+  }
+  return hits;
+}
+
+export async function stopWatchProcesses(): Promise<StopResult> {
+  const stopped: StoppedProcess[] = [];
+  const failed: StoppedProcess[] = [];
+  const targetedPids = new Set<number>();
+
+  const registered = await listRegisteredProcesses();
+  for (const proc of registered) {
+    if (proc.pid === process.pid) continue;
+    targetedPids.add(proc.pid);
+    const result = signalProcess(proc.pid);
+    const record: StoppedProcess = { pid: proc.pid, workspace: proc.workspace };
+    if (result.ok) {
+      stopped.push(record);
+    } else {
+      failed.push(record);
+    }
+  }
+
+  for (const hit of findViaProcessTable()) {
+    if (hit.pid === process.pid) continue;
+    if (targetedPids.has(hit.pid)) continue;
+    targetedPids.add(hit.pid);
+    const result = signalProcess(hit.pid);
+    const record: StoppedProcess = { pid: hit.pid, workspace: hit.workspace };
+    if (result.ok) {
+      stopped.push(record);
+    } else {
+      failed.push(record);
+    }
+  }
+
+  if (stopped.length > 0) {
+    await sleep(SETTLE_MS);
+    // Trigger another prune so the registry doesn't keep stale entries
+    // for processes that exited cleanly above.
+    await listRegisteredProcesses();
+  }
+
+  return { stopped, failed };
+}
+
+function printResult(result: StopResult): void {
+  if (result.stopped.length === 0 && result.failed.length === 0) {
+    console.log('No running watch processes found.');
+    return;
+  }
+  for (const proc of result.stopped) {
+    console.log(
+      `  ${DIM}⇅${RESET} Stopped: boxel realm watch ${proc.workspace} (PID ${proc.pid})`,
+    );
+  }
+  for (const proc of result.failed) {
+    console.log(
+      `  ${FG_RED}×${RESET} Failed to stop: boxel realm watch ${proc.workspace} (PID ${proc.pid})`,
+    );
+  }
+  if (result.stopped.length > 0) {
+    const plural = result.stopped.length > 1 ? 'es' : '';
+    console.log(
+      `\n${FG_GREEN}✓ Stopped ${result.stopped.length} process${plural}${RESET}`,
+    );
+  }
+}
+
+export function registerStopCommand(watch: Command): void {
+  watch
+    .command('stop')
+    .description('Stop all running boxel realm watch processes')
+    .action(async () => {
+      const result = await stopWatchProcesses();
+      printResult(result);
+    });
+}

package/src/lib/boxel-cli-client.ts

@@ -450,6 +450,18 @@ export class BoxelCLIClient {
     return this.pm.authedRealmServerFetch(input, init);
   }
 
+  /**
+   * Return the realm-server JWT, fetching one via Matrix login if no token
+   * is cached. Use only when you need to hand the bare token to a downstream
+   * client that can't go through `authedServerFetch` (e.g. opencode's
+   * static-Authorization provider config). Prefer `authedServerFetch` for
+   * server endpoints called from JS — it handles per-request 401 retries
+   * that this getter cannot.
+   */
+  async getServerToken(): Promise<string> {
+    return this.pm.getOrRefreshServerToken();
+  }
+
   async pull(
     realmUrl: string,
     localDir: string,