@llman-sdd/cli 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llman-sdd/cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Spec-driven development workflow CLI (the `llman-sdd` command)",
   "license": "MIT",
   "repository": {
@@ -27,7 +27,7 @@
     "build": "bun run ./scripts/build-binary.ts"
   },
   "dependencies": {
-    "@llman-sdd/core": "0.2.0",
+    "@llman-sdd/core": "0.5.0",
     "commander": "^15.0.0"
   },
   "engines": {

package/src/cli-shared.ts

@@ -0,0 +1,190 @@
+/**
+ * Leaf module shared by every command group: version/templateIo wiring, config
+ * readers, change-id resolution, output-mode helpers and misc constants.
+ * Command modules depend one-way on this file; it must not import any of them.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+
+import {
+  discoverSpecs,
+  embeddedTemplates,
+  loadConfig,
+  makeEmbeddedTemplateIo,
+  resolveChangeId,
+  type TemplateIo,
+} from '@llman-sdd/core';
+import type { Command } from 'commander';
+
+import pkg from '../package.json' with { type: 'json' };
+import { makeIo } from './io.ts';
+
+// Re-exported so leaf consumers (e.g. regression gates under tests/) can type
+// against the commander surface without resolving 'commander' themselves.
+export type { Command } from 'commander';
+
+// Version SSOT is this package's package.json (inlined at compile time — a
+// single-file binary has no on-disk package.json to read); binary builds
+// additionally override it through the LLMAN_SDD_VERSION define injected by
+// scripts/build-binary.ts (git tag > package version).
+
+// Injected at binary build time by scripts/build-binary.ts; falls back to the
+// package version when running from source.
+export const version = process.env.LLMAN_SDD_VERSION ?? pkg.version;
+
+// Compiled single-file binaries have no on-disk templates and Bun <= 1.4.x has
+// no embedding mechanism, so scripts/build-binary.ts injects the template
+// table through the literal define `process.env.LLMAN_SDD_EMBEDDED_TEMPLATES`
+// (define only rewrites literal member access — the read must stay here, not
+// in core); every non-compiled run keeps reading the real filesystem (npm/
+// source/Node). Both init and `review --export-html` resolve through this one
+// seam.
+const embedded = embeddedTemplates(process.env.LLMAN_SDD_EMBEDDED_TEMPLATES);
+export const templateIo: TemplateIo = embedded
+  ? makeEmbeddedTemplateIo(embedded)
+  : {
+      exists: (p) => existsSync(p),
+      readText: (p) => readFileSync(p, 'utf8'),
+    };
+
+/** CLI io rooted at the launch cwd; call at action time so cwd is read per command. */
+export function newIo(): ReturnType<typeof makeIo> {
+  return makeIo(process.cwd());
+}
+
+/**
+ * D5: unified error export. Domain/usage errors thrown from command actions
+ * surface as a single `Error: <message>` line via main.ts with the carried
+ * exit code — commands must NOT set `process.exitCode` directly.
+ */
+export class CliError extends Error {
+  readonly exitCode: number;
+  constructor(message: string, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+/** Single exit-code write point for non-error result paths (e.g. sweep verdicts). */
+export function exitWith(code: number): void {
+  process.exitCode = code;
+}
+
+/** Parse all capability specs under llmanspec/specs via core discovery. */
+export function loadSpecEntries(): ReturnType<typeof discoverSpecs> {
+  return discoverSpecs('llmanspec/specs', newIo());
+}
+
+export function loadCliConfig(): ReturnType<typeof loadConfig> | null {
+  return existsSync('llmanspec/config.yaml')
+    ? loadConfig(readFileSync('llmanspec/config.yaml', 'utf8'))
+    : null;
+}
+
+export function cliMaxScanDepth(program: Command): number {
+  const raw = program.opts().maxScanDepth as string | undefined;
+  const n = raw !== undefined ? Number(raw) : 8;
+  if (!Number.isInteger(n) || n < 1) {
+    throw new CliError(`--max-scan-depth must be >= 1 (got ${raw})`, 2);
+  }
+  return n;
+}
+
+/**
+ * r61: shared predecessor r112 change id resolution for every change-taking command.
+ * Emits the `(prefix match)` hint on stderr; fails by throwing CliError (the
+ * unified exit renders the single `Error: <message>` line and exit code 1).
+ */
+export function resolveChangeIdOrExit(
+  program: Command,
+  input: string,
+  opts: { suppressHint?: boolean } = {},
+): { id: string; viaPrefix: boolean } {
+  const resolved = resolveChangeId(newIo(), process.cwd(), input, {
+    maxScanDepth: cliMaxScanDepth(program),
+  });
+  if (resolved.viaPrefix && opts.suppressHint !== true) {
+    console.error(`'${input}' -> '${resolved.id}' (prefix match)`);
+  }
+  return resolved;
+}
+
+export type OutMode = 'toon' | 'json' | 'compact-json' | 'human';
+
+/**
+ * D4: shared output-flag surface for every report command. Mounts the unified
+ * `--output <toon|json|compact-json|human>` plus the predecessor-compatibility alias
+ * flags (`--json` / `--compact-json`), so report commands no longer duplicate
+ * `.option('--output', ...)` registrations. `outputHint` lets a command keep a
+ * richer value-domain description (show's legacy JSON modifiers).
+ */
+export function addReportOutputOptions(cmd: Command, opts: { outputHint?: string } = {}): void {
+  cmd
+    .option(
+      '--output <mode>',
+      opts.outputHint ?? 'report format: toon (default) | json | compact-json | human',
+    )
+    .option('--json', 'emit structured JSON (v1 compatibility alias)')
+    .option('--compact-json', 'emit single-line JSON (v1 compatibility alias)');
+}
+
+/**
+ * toon-default-output: explicit `--output` wins, then the predecessor-parity legacy
+ * flags, then the toon default. Legacy `--compact-json` keeps its predecessor guard
+ * (must pair with `--json`) — standalone compact goes through `--output`.
+ * Invalid `--output` values are usage errors (exit 2) and throw CliError.
+ */
+export function resolveOutMode(
+  output: string | undefined,
+  legacyJson: boolean | undefined,
+  legacyCompact: boolean | undefined,
+): OutMode {
+  const modes: readonly string[] = ['toon', 'json', 'compact-json', 'human'];
+  if (output !== undefined) {
+    if (!modes.includes(output)) {
+      throw new CliError(`invalid --output: ${output} (toon | json | compact-json | human)`, 2);
+    }
+    return output as OutMode;
+  }
+  if (legacyCompact) return 'compact-json';
+  if (legacyJson) return 'json';
+  return 'toon';
+}
+
+/**
+ * Legacy `--compact-json` guard (see resolveOutMode): standalone compact is
+ * rejected (usage error, exit 2) unless paired with `--json` or an explicit
+ * `--output`.
+ */
+export function assertCompactJsonPairing(options: {
+  compactJson?: boolean;
+  json?: boolean;
+  output?: string;
+}): boolean {
+  if (options.compactJson === true && options.json !== true && options.output === undefined) {
+    throw new CliError('--compact-json requires --json', 2);
+  }
+  return true;
+}
+
+export const SKILL_DESCRIPTIONS: Record<string, string> = {
+  'llman-sdd-continue': 'Fill in missing change artifacts',
+  'llman-sdd-ff': 'Fast-forward propose: planning shell → Branch binding → Specs landing',
+  'llman-sdd-validate': 'Standalone validation skill',
+  'llman-sdd-arch-review': 'Scan shallow modules for deepening candidates',
+  'llman-sdd-wayfinder': 'Plan large foggy work as a decision map',
+  'llman-sdd-research': 'Delegate external research to a background agent',
+};
+export const skillDesc = (name: string): string => SKILL_DESCRIPTIONS[name] ?? '';
+
+export function resolveBackend(flag: string | undefined): 'pageindex' {
+  const chosen = flag ?? process.env.LLMAN_SDD_INDEX_BACKEND ?? 'pageindex';
+  if (chosen === 'rag') {
+    throw new Error(
+      'Backend `rag` is no longer supported. Use the default pageindex backend instead:\nSet `LLMAN_SDD_INDEX_CHAT_MODEL` to a tool-calling chat model, then\nrun `llman-sdd index rebuild`.',
+    );
+  }
+  if (chosen !== 'pageindex') {
+    throw new Error(`Unsupported backend: ${chosen}`);
+  }
+  return 'pageindex';
+}

package/src/commands/archive.ts

@@ -0,0 +1,114 @@
+import { mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import {
+  nonMainCheckoutWarning,
+  probeMainCheckout,
+  runFreeze,
+  runList,
+  runThaw,
+  makeWasmSevenZip,
+  type SevenZipPort,
+} from '@llman-sdd/core';
+import type { Command } from 'commander';
+
+import { CliError } from '../cli-shared.ts';
+import { makeCliGit, makeIo } from '../io.ts';
+
+/**
+ * r24: warn (never block) when freeze/thaw runs outside the main checkout —
+ * the worktree NOT holding the default branch. Probe failures skip silently.
+ */
+function warnIfNotMainCheckout(root: string): void {
+  const warning = nonMainCheckoutWarning(probeMainCheckout(makeCliGit(root)));
+  if (warning !== null) console.log(warning);
+}
+
+/**
+ * Compiled binaries have no on-disk 7zz.wasm (Emscripten would probe $bunfs
+ * and abort), so scripts/build-binary.ts injects it as base64 through the
+ * literal define `process.env.LLMAN_SDD_EMBEDDED_7ZZ_WASM_B64` (define only
+ * rewrites literal member access — the read must stay here, not in core);
+ * unset in source/npm/Node runs → the 7z-wasm glue loads the .wasm from disk.
+ * Directory creation for extraction is likewise injected (core stays pure).
+ */
+function makeEmbeddedSevenZip(): Promise<SevenZipPort> {
+  return makeWasmSevenZip({
+    wasmB64: process.env.LLMAN_SDD_EMBEDDED_7ZZ_WASM_B64,
+    mkdirp: (dir) => mkdirSync(dir, { recursive: true }),
+  });
+}
+
+export function registerArchive(program: Command): void {
+  const archive = program
+    .command('archive')
+    .description(
+      'Archive workflow commands (cold backup). Prefer `change finalize` to seal a change',
+    );
+
+  archive
+    .command('freeze')
+    .description('Freeze dated archived changes into a single 7z cold backup')
+    .option('--before <date>', 'freeze entries older than this date (YYYY-MM-DD)')
+    .option('--keep-recent <n>', 'keep N most recent candidates unfrozen', '0')
+    .option('--dry-run', 'list candidates without freezing')
+    .option('--list', 'list entries already in the cold-backup archive')
+    .action(
+      async (options: {
+        before?: string;
+        keepRecent: string;
+        dryRun?: boolean;
+        list?: boolean;
+      }) => {
+        try {
+          const root = process.cwd();
+          warnIfNotMainCheckout(root);
+          const sz = await makeEmbeddedSevenZip();
+          const io = makeIo(root);
+          if (options.list) {
+            for (const line of await runList(io, sz, root)) console.log(line);
+            return;
+          }
+          const result = await runFreeze(io, sz, root, {
+            before: options.before,
+            keepRecent: Number(options.keepRecent),
+            dryRun: options.dryRun,
+          });
+          for (const line of result.lines) console.log(line);
+        } catch (error) {
+          // Emscripten aborts (e.g. wasm load failure) throw raw RuntimeErrors —
+          // keep the CLI surface one-line like thaw does.
+          throw new CliError((error as Error).message);
+        }
+      },
+    );
+
+  archive
+    .command('thaw')
+    .description('Restore archived change directories from the cold-backup archive')
+    .requiredOption(
+      '--change <name>',
+      'archived change directory to restore (repeatable)',
+      (v: string, prev: string[]) => {
+        prev.push(v);
+        return prev;
+      },
+      [] as string[],
+    )
+    .option('--dest <path>', 'restore into this directory (created when missing)')
+    .action(async (options: { change: string[]; dest?: string }) => {
+      if (options.dest !== undefined) {
+        mkdirSync(resolve(options.dest), { recursive: true });
+      }
+      const root = process.cwd();
+      warnIfNotMainCheckout(root);
+      const sz = await makeEmbeddedSevenZip();
+      const io = makeIo(root);
+      try {
+        const result = await runThaw(io, sz, root, options.change, { dest: options.dest });
+        for (const line of result.lines) console.log(line);
+      } catch (error) {
+        throw new CliError((error as Error).message);
+      }
+    });
+}