@llman-sdd/cli 0.3.1 → 0.5.1

package/src/commands/change.ts

@@ -0,0 +1,389 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import {
+  CLOSE_OUT_TASK_HINT,
+  closeOutTaskLines,
+  archiveChange,
+  attachChange,
+  changeDiff,
+  changeDiffInfo,
+  deriveChangeId,
+  finalizeChange,
+  harvestAcrossWorktrees,
+  archiveTaskGate,
+  isCleanTree,
+  newChange,
+  nextUniqueNumber,
+  renderChangeIdTemplate,
+  splitVerb,
+  startChange,
+  validateAllSpecs,
+  decideCloseOutHarness,
+  extractFrontmatter,
+  readNeedsSpecsChange,
+} from '@llman-sdd/core';
+import { Option, type Command } from 'commander';
+
+import {
+  CliError,
+  loadCliConfig,
+  loadSpecEntries,
+  newIo,
+  resolveChangeIdOrExit,
+} from '../cli-shared.ts';
+import { makeCliHarnessRunner } from '../harness.ts';
+import { makeCliGit } from '../io.ts';
+
+function runValidateSweep(): boolean {
+  const report = validateAllSpecs(loadSpecEntries(), newIo());
+  return report.verdicts.some((v) => !v.ok);
+}
+
+/** r81: run or refuse the acceptance command before any merge or rename. */
+function enforceCloseOutHarness(id: string, noCheck: boolean): void {
+  const proposalPath = `llmanspec/changes/${id}/proposal.md`;
+  const proposal = existsSync(proposalPath) ? readFileSync(proposalPath, 'utf8') : '';
+  const needsSpecsChange = readNeedsSpecsChange(extractFrontmatter(proposal));
+  const hasExecutable = loadSpecEntries().some(
+    (entry) =>
+      entry.doc.rules.some((r) => r.scenarios.some((s) => s.runnable && s.stepCount > 0)) ||
+      entry.doc.orphans.some((s) => s.runnable && s.stepCount > 0),
+  );
+  const runCommand = loadCliConfig()?.bdd?.run_command ?? null;
+  const decision = decideCloseOutHarness({
+    noCheck,
+    needsSpecsChange,
+    hasExecutable,
+    runCommand,
+    nested: process.env.LLMAN_SDD_HARNESS_ACTIVE === '1',
+  });
+  if (decision.kind === 'abort') {
+    throw new CliError(`close-out aborted: ${decision.message}`);
+  }
+  if (decision.kind === 'skip') {
+    if (decision.announce) console.error('bdd harness skipped: --no-check');
+    return;
+  }
+  const result = makeCliHarnessRunner().run(decision.command, process.cwd());
+  if (result.spawnError !== undefined || result.exitCode !== 0) {
+    const why = result.spawnError ?? `exit ${result.exitCode}`;
+    throw new CliError(`close-out aborted: bdd harness failed (${why})`);
+  }
+}
+
+/** `--method squash|ff` guard shared by `change archive` / `change finalize`. */
+function assertMergeMethod(method: string | undefined): void {
+  if (method !== undefined && method !== 'squash' && method !== 'ff') {
+    throw new CliError(`invalid --method: ${method}`);
+  }
+}
+
+/**
+ * Unified `change new --from` id derivation (r44/r60). With a configured
+ * `change_id.template` the id is rendered through it (Strict: referencing an
+ * unprovided variable throws, surfacing in both dry-run and real paths); the
+ * heuristic slug is otherwise returned unchanged unless an explicit `--verb`
+ * is given, in which case the override is applied as `{verb}-{subject}` (r44).
+ */
+/**
+ * r35: `change next-id` / change-id harvest scan must skip symlinks and dot
+ * directories. `lstat` (never `stat`) reports the link itself, so a symlink —
+ * even one pointing at a directory — is not a directory here and is neither
+ * counted nor recursed into. The next-id harvest is the single consumer that
+ * requires this no-follow semantics cycle-wide.
+ */
+function isDirectoryNoFollow(path: string): boolean {
+  return lstatSync(resolve(path)).isDirectory();
+}
+function deriveNewId(description: string, verb: string | undefined): string {
+  const slug = deriveChangeId(description);
+  const cliConfig = loadCliConfig();
+  const template = cliConfig?.change_id?.template;
+  if (template) {
+    const { verb: v, subject } = splitVerb(slug, verb);
+    return renderChangeIdTemplate(template, {
+      llman_sdd_unique_id: nextUniqueNumber(
+        {
+          listDir: (p) => readdirSync(resolve(p)),
+          isDirectory: isDirectoryNoFollow,
+        },
+        'llmanspec',
+      ),
+      verb: v,
+      subject,
+      date: new Date().toISOString().slice(0, 10),
+    });
+  }
+  if (verb !== undefined) {
+    const { verb: v, subject } = splitVerb(slug, verb);
+    return `${v}-${subject}`;
+  }
+  return slug;
+}
+
+export function registerChange(program: Command): void {
+  const change = program
+    .command('change')
+    .description('Change lifecycle: new / start / attach / next-id / diff / finalize');
+
+  change
+    .command('new')
+    .description('Create a change draft (exactly one of <id> or --from)')
+    .argument('[id]')
+    .option('--from <description>', 'description the id is derived from')
+    .option('--verb <verb>', 'explicit verb for change_id.template rendering')
+    .option('--force', 'overwrite an existing proposal.md')
+    .option('--dry-run', 'print the resulting id without creating anything')
+    .action(
+      (
+        id: string | undefined,
+        options: { from?: string; verb?: string; force?: boolean; dryRun?: boolean },
+      ) => {
+        if ((id === undefined) === (options.from === undefined)) {
+          throw new CliError('<CHANGE> and --from are mutually exclusive; pass one or the other');
+        }
+        if (options.dryRun) {
+          console.log(id ?? deriveNewId(options.from as string, options.verb));
+          return;
+        }
+        if (options.from !== undefined) {
+          const derived = deriveNewId(options.from, options.verb);
+          console.log(`derived change id: ${derived}`);
+          const io = newIo();
+          const result = newChange(io, { id: derived, force: options.force });
+          console.log(`./${result.path}`);
+          return;
+        }
+        const io = newIo();
+        const result = newChange(io, { id, force: options.force });
+        console.log(`./${result.path}`);
+      },
+    );
+
+  change
+    .command('start')
+    .description('Bind the change to a new feature branch (clean tree + default branch gates)')
+    .argument('<id>')
+    .option(
+      '--branch-prefix <prefix>',
+      'feature branch prefix (default: sdd.branch_prefix config, then sdd/)',
+    )
+    .option(
+      '--base <branch>',
+      'explicit fork-source branch to record (must exist and differ from the new branch; exempts the default-branch gate)',
+    )
+    .option(
+      '--worktree',
+      'create the branch in a dedicated worktree (sdd.worktree_root / sdd.worktree_naming config) instead of switching this checkout',
+    )
+    .action((id: string, options: { branchPrefix?: string; base?: string; worktree?: boolean }) => {
+      const resolved = resolveChangeIdOrExit(program, id);
+      const git = makeCliGit(process.cwd());
+      const config = loadCliConfig();
+      const result = startChange(git, newIo(), resolved.id, {
+        branchPrefix: options.branchPrefix ?? config?.sdd?.branch_prefix ?? 'sdd/',
+        base: options.base,
+        worktree: options.worktree,
+        worktreeRoot: config?.sdd?.worktree_root ?? undefined,
+        worktreeNaming: config?.sdd?.worktree_naming ?? undefined,
+      });
+      console.log(
+        `started change \`${resolved.id}\` → branch \`${result.branch}\` base \`${result.baseSha}\` base-branch \`${result.baseBranch}\``,
+      );
+      if (result.worktreePath !== undefined) console.log(`worktree ${result.worktreePath}`);
+    });
+
+  change
+    .command('attach')
+    .description('Bind the change to the current feature branch')
+    .argument('<id>')
+    .option('--force', 'rebind an already attached change to the current branch')
+    .option('--base <branch>', 'explicit fork-point branch to record')
+    .action((id: string, options: { force?: boolean; base?: string }) => {
+      const resolved = resolveChangeIdOrExit(program, id);
+      const result = attachChange(makeCliGit(process.cwd()), newIo(), resolved.id, {
+        force: options.force,
+        base: options.base,
+      });
+      console.log(
+        `attached change \`${resolved.id}\` → branch \`${result.branch}\` base \`${result.baseSha}\` base-branch \`${result.baseBranch}\``,
+      );
+    });
+
+  change
+    .command('next-id')
+    .description('Preview the next free change id number (read-only)')
+    .option('--json', 'emit {maxNumber, nextNumber, warnings}')
+    .action((options: { json?: boolean }) => {
+      // r35: the scan covers this tree plus every linked git worktree's own
+      // llmanspec/ tree (degrades to the current tree when worktree list fails).
+      const harvest = harvestAcrossWorktrees(
+        makeCliGit(process.cwd()),
+        {
+          listDir: (p) => readdirSync(resolve(p)),
+          isDirectory: isDirectoryNoFollow,
+        },
+        'llmanspec',
+      );
+      if (options.json) {
+        console.log(JSON.stringify(harvest, null, 2));
+        return;
+      }
+      if (harvest.maxNumber === null) console.log('no numbered change dirs found in tree');
+      else console.log(`max number in tree: ${harvest.maxNumber}`);
+      console.log(`next free number: ${harvest.nextNumber}`);
+      for (const w of harvest.warnings) console.error(`warning: ${w}`);
+    });
+
+  change
+    .command('archive')
+    .description('Independent seal-off: task gates + merge + archive rename + commit')
+    .argument('<id>')
+    .option('--into <branch>', 'target branch to merge into')
+    .option('--method <method>', 'merge method: squash | ff')
+    .option('--dry-run', 'print the rename plan only')
+    .addOption(new Option('--force', 'skip task and git gates').hideHelp())
+    .action(
+      (
+        id: string,
+        options: { into?: string; method?: string; dryRun?: boolean; force?: boolean },
+      ) => {
+        assertMergeMethod(options.method);
+        const resolved = resolveChangeIdOrExit(program, id);
+        id = resolved.id;
+        const io = newIo();
+        if (options.dryRun) {
+          const date = new Date().toISOString().slice(0, 10);
+          console.log(
+            `Would move llmanspec/changes/${id} -> llmanspec/changes/archive/${date}-${id}`,
+          );
+          return;
+        }
+        // r40 task gate: single core implementation (archiveTaskGate); the
+        // CLI only renders the blocked output + options list, byte-identical.
+        if (!options.force) {
+          const tasksPath = `llmanspec/changes/${id}/tasks.md`;
+          const gate = archiveTaskGate(
+            existsSync(tasksPath) ? readFileSync(tasksPath, 'utf8') : null,
+          );
+          if (gate.blocked) {
+            console.error(`Archive blocked: ${gate.pendingLines.length} unchecked task(s).`);
+            for (const line of gate.pendingLines) {
+              console.error(`  - [ ] ${line.replace(/^-\s+\[ \]\s*/u, '').trim()}`);
+            }
+            // D9: point at a close-out pseudo-task with the single shared hint.
+            const closeOut = closeOutTaskLines(gate.pendingLines);
+            if (closeOut.length > 0) {
+              console.error(
+                `  task "${closeOut[0]?.replace(/^-\s+\[ \]\s*/u, '').trim() ?? ''}" looks like a close-out step; ${CLOSE_OUT_TASK_HINT}`,
+              );
+            }
+            console.error(
+              'Options:\n  1. Complete the remaining tasks\n  2. Use --force to archive anyway (not recommended)',
+            );
+            throw new Error('archive blocked by unchecked tasks');
+          }
+          if (!isCleanTree(makeCliGit(process.cwd()))) {
+            throw new CliError('`change archive` requires a clean working tree');
+          }
+        }
+        enforceCloseOutHarness(id, false);
+        const result = archiveChange(makeCliGit(process.cwd()), io, id, {
+          into: options.into,
+          method: options.method as 'squash' | 'ff' | undefined,
+          force: options.force,
+          skipCleanTree: true,
+          today: new Date().toISOString().slice(0, 10),
+        });
+        const archiveName = (result.archiveDir ?? '').slice(
+          (result.archiveDir ?? '').lastIndexOf('/') + 1,
+        );
+        console.log(`Change '${id}' archived as '${archiveName}'.`);
+        if (result.executedIn !== null) {
+          console.log(`executed in target worktree ${result.executedIn}`);
+        }
+      },
+    );
+
+  change
+    .command('diff')
+    .description('Print the bound branch diff vs base')
+    .argument('<id>')
+    .option('--json', 'emit {change, branch, base, commitCount}')
+    .option('--export-patch <path>', 'write the diff to a file instead of stdout')
+    .action((id: string, options: { json?: boolean; exportPatch?: string }) => {
+      const resolved = resolveChangeIdOrExit(program, id);
+      id = resolved.id;
+      const git = makeCliGit(process.cwd());
+      if (options.json) {
+        const info = changeDiffInfo(git, newIo(), id);
+        console.log(JSON.stringify(info, null, 2));
+        return;
+      }
+      const diff = changeDiff(git, newIo(), id);
+      if (options.exportPatch !== undefined) {
+        // writeText creates parent dirs — exporting into a fresh path like
+        // out/change.patch must not ENOENT.
+        newIo().writeText(options.exportPatch, diff);
+        console.log(`wrote ${options.exportPatch}`);
+        return;
+      }
+      console.log(diff);
+    });
+
+  change
+    .command('finalize')
+    .description('Validate, merge the feature branch, archive docs, close out with one commit')
+    .argument('<id>')
+    .option('--into <branch>', 'merge target override (defaults to base_branch)')
+    .option(
+      '--method <method>',
+      'merge method: squash | ff (default: sdd.merge_method config, then squash)',
+    )
+    .option('--no-check', 'skip the pre-merge validation sweep')
+    .option('--no-commit', 'skip the close-out commit (manual/CI history)')
+    .action(
+      (
+        id: string,
+        options: { into?: string; method?: string; check?: boolean; commit?: boolean },
+      ) => {
+        assertMergeMethod(options.method);
+        if (options.check !== false) {
+          const failed = runValidateSweep();
+          if (failed) {
+            throw new CliError(
+              'finalize aborted: validation sweep failed (use --no-check to skip)',
+            );
+          }
+        }
+        const resolved = resolveChangeIdOrExit(program, id);
+        id = resolved.id;
+        enforceCloseOutHarness(id, options.check === false);
+        const config = loadCliConfig();
+        const method = options.method ?? config?.sdd?.merge_method ?? 'squash';
+        const result = finalizeChange(makeCliGit(process.cwd()), newIo(), id, {
+          into: options.into,
+          method: method as 'squash' | 'ff',
+          today: new Date().toISOString().slice(0, 10),
+          noCommit: options.commit === false,
+        });
+        for (const w of result.warnings) console.error(`[WARNING] ${w}`);
+        if (options.commit === false) {
+          console.log(
+            `finalized \`${id}\` → ${result.archiveDir} on ${result.target} (close-out commit skipped — run: git add -A && git commit -m "archive(sdd): ${id}")`,
+          );
+          if (result.executedIn !== null) {
+            console.log(`executed in target worktree ${result.executedIn}`);
+          }
+          return;
+        }
+        console.log(
+          `finalized \`${id}\` → ${result.archiveDir} (commit "${result.commitSubject}" on ${result.target})`,
+        );
+        if (result.executedIn !== null) {
+          console.log(`executed in target worktree ${result.executedIn}`);
+        }
+      },
+    );
+}

package/src/commands/config.ts

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs';
+
+import { renderConfigOverview, renderMachine, skillsJson } from '@llman-sdd/core';
+import type { Command } from 'commander';
+
+import { addReportOutputOptions, resolveOutMode, skillDesc } from '../cli-shared.ts';
+
+export function registerConfig(program: Command): void {
+  const configCmd = program
+    .command('config')
+    .description('Project configuration commands (view/edit config.yaml)');
+
+  configCmd.description('Print a read-only llmanspec/config.yaml overview').action(() => {
+    const source = readFileSync('llmanspec/config.yaml', 'utf8');
+    console.log(renderConfigOverview(source).join('\n'));
+  });
+
+  const skills = configCmd.command('skills').description('Manage extra_skills (non-interactive)');
+  addReportOutputOptions(skills);
+  skills.action((options: { json?: boolean; output?: string; compactJson?: boolean }) => {
+    const path = 'llmanspec/config.yaml';
+    const info = skillsJson(readFileSync(path, 'utf8'));
+    const mode = resolveOutMode(options.output, options.json, options.compactJson);
+    if (mode !== 'human') {
+      console.log(renderMachine(info, mode));
+      return;
+    }
+    const enabled = info.enabled;
+    const available = info.available;
+    console.log('Enabled optional skills:');
+    if (enabled.length === 0) console.log('  (none)');
+    else for (const s of enabled) console.log(`  [x] ${s}`);
+    console.log();
+    console.log('Available but not enabled:');
+    for (const s of available) {
+      if (!enabled.includes(s)) console.log(`  [ ] ${s} — ${skillDesc(s)}`);
+    }
+  });
+}

package/src/commands/context.ts

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+
+import {
+  loadTreeWithAutoRebuild,
+  resolveChatConfig,
+  runContextRetrieval,
+  unavailableResult,
+} from '@llman-sdd/core';
+import type { Command } from 'commander';
+
+import { CliError, loadSpecEntries, newIo, resolveBackend } from '../cli-shared.ts';
+
+// (err path below converted to CliError; resolveBackend may also throw CliError)
+
+export function registerContext(program: Command): void {
+  program
+    .command('context')
+    .description('Get specs relevant to a task (agent-oriented, pageindex agentic retrieval)')
+    .option('--task <task>', 'natural language task description')
+    .option('--paths <paths>', 'comma-separated file paths')
+    .option('--top <n>', 'max entries per tier', '5')
+    .option('--backend <name>', 'retrieval backend (pageindex only)')
+    .action(async (options: { task?: string; paths?: string; top?: string; backend?: string }) => {
+      resolveBackend(options.backend);
+      if (!options.task && !options.paths) {
+        throw new CliError('at least one of --task or --paths is required');
+      }
+      const config = resolveChatConfig(process.env as Record<string, string | undefined>);
+      // r62: lazy refresh runs BEFORE the chat-model gate (predecessor r97 — the index
+      // self-heals even when retrieval subsequently fails with api_error).
+      const refresh = loadTreeWithAutoRebuild(newIo(), 'llmanspec/specs', loadSpecEntries(), {
+        chatModel: process.env.LLMAN_SDD_INDEX_CHAT_MODEL ?? '',
+      });
+      if (refresh.tree === null || refresh.error !== null) {
+        const failed = unavailableResult();
+        failed.status.errorKind = 'index_rebuild_failed';
+        failed.status.qualityNote =
+          refresh.error ?? 'index rebuild failed — run `llman-sdd index rebuild`';
+        console.log(JSON.stringify(failed, null, 2));
+        return;
+      }
+      const tree = refresh.tree;
+      if (config === null) {
+        // predecessor parity: unavailable/error JSON on stdout, exit 0.
+        console.log(JSON.stringify(unavailableResult(), null, 2));
+        return;
+      }
+      const result = await runContextRetrieval({
+        config,
+        task: options.task ?? '',
+        paths: options.paths,
+        top: Number(options.top),
+        tree,
+        readFile: (p) => readFileSync(p, 'utf8'),
+        root: process.cwd(),
+      });
+      console.log(JSON.stringify(result, null, 2));
+    });
+}

package/src/commands/graph.ts

@@ -0,0 +1,35 @@
+import { graphMermaid } from '@llman-sdd/core';
+import type { Command } from 'commander';
+
+import { cliMaxScanDepth, CliError, newIo } from '../cli-shared.ts';
+
+export function registerGraph(program: Command): void {
+  program
+    .command('graph')
+    .description('Generate a change dependency graph (mermaid)')
+    .argument('[change]', 'seed change id (BFS over depends_on)')
+    .option('--format <format>', 'output format', 'mermaid')
+    .option('--scope <scope>', 'active | archived | all (comma-combined)', 'active')
+    .option(
+      '--depth <n>',
+      'expansion depth: 0 = scope only, 1 = direct deps (default), N = recursive',
+    )
+    .action(
+      (change: string | undefined, options: { format: string; scope?: string; depth?: string }) => {
+        if (options.format !== 'mermaid') {
+          throw new CliError(`unsupported --format: ${options.format} (mermaid only)`, 2);
+        }
+        const depth = options.depth !== undefined ? Number(options.depth) : undefined;
+        if (depth !== undefined && (!Number.isInteger(depth) || depth < 0)) {
+          throw new CliError(`invalid --depth: ${options.depth}`);
+        }
+        const graphOpts = {
+          scope: options.scope,
+          depth: depth ?? 1,
+          seed: change,
+          maxScanDepth: cliMaxScanDepth(program),
+        };
+        console.log(graphMermaid(newIo(), process.cwd(), graphOpts).join('\n'));
+      },
+    );
+}

package/src/commands/index.ts

@@ -0,0 +1,43 @@
+import { checkIndexFreshness, rebuildIndex, renderMachine } from '@llman-sdd/core';
+import type { Command } from 'commander';
+
+import {
+  addReportOutputOptions,
+  exitWith,
+  loadSpecEntries,
+  newIo,
+  resolveBackend,
+  resolveOutMode,
+} from '../cli-shared.ts';
+
+export function registerIndex(program: Command): void {
+  const indexCmd = program
+    .command('index')
+    .description('Index management commands (rebuild, check freshness)');
+
+  indexCmd
+    .command('rebuild')
+    .description('Rebuild the pageindex tree from spec IR (no LLM)')
+    .option('--backend <name>', 'index backend (pageindex only)')
+    .action((options: { backend?: string }) => {
+      resolveBackend(options.backend);
+      const result = rebuildIndex(newIo(), 'llmanspec/specs', loadSpecEntries(), {
+        chatModel: process.env.LLMAN_SDD_INDEX_CHAT_MODEL ?? '',
+      });
+      for (const line of result.lines.slice(0, -1)) console.error(line);
+      if (result.lines.length > 0) console.log(result.lines.at(-1));
+    });
+
+  const check = indexCmd.command('check').description('Check index freshness without rebuilding');
+  addReportOutputOptions(check);
+  check.action((options: { output?: string; json?: boolean; compactJson?: boolean }) => {
+    const result = checkIndexFreshness(newIo(), 'llmanspec/specs');
+    const mode = resolveOutMode(options.output, options.json, options.compactJson);
+    if (mode !== 'human') {
+      console.log(renderMachine({ fresh: result.fresh, notes: result.lines }, mode));
+    } else {
+      for (const line of result.lines) console.log(line);
+    }
+    if (!result.fresh) exitWith(1);
+  });
+}

package/src/commands/init.ts

@@ -0,0 +1,37 @@
+import { mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { runInit } from '@llman-sdd/core';
+import type { Command } from 'commander';
+
+import { CliError, templateIo, version } from '../cli-shared.ts';
+import { makeIo } from '../io.ts';
+
+export function registerInit(program: Command): void {
+  program
+    .command('init')
+    .description('Initialize llmanspec in your project (--update to refresh existing)')
+    .argument('[path]', 'target directory (created when missing; defaults to cwd)')
+    .option('--update', 'refresh an existing installation')
+    .option('--locale <locale>', 'locale for generated templates (defaults to config or en)')
+    .option('--lang <locale>', 'alias of --locale')
+    .action(
+      (path: string | undefined, options: { update?: boolean; locale?: string; lang?: string }) => {
+        if (options.locale !== undefined && options.lang !== undefined) {
+          throw new CliError('--locale and --lang are mutually exclusive (they are aliases)');
+        }
+        let root = process.cwd();
+        if (path !== undefined) {
+          root = resolve(path);
+          mkdirSync(root, { recursive: true });
+        }
+        const result = runInit(makeIo(root), templateIo, {
+          update: options.update ?? false,
+          locale: options.locale ?? options.lang,
+          version,
+        });
+        const removed = result.removed.length > 0 ? `, removed: ${result.removed.join(', ')}` : '';
+        console.log(`initialized llmanspec (${result.skills.length} skills${removed})`);
+      },
+    );
+}

package/src/commands/list.ts

@@ -0,0 +1,69 @@
+import {
+  collectChanges,
+  collectSpecs,
+  renderChangesJson,
+  renderChangesList,
+  renderSpecsJson,
+  renderSpecsList,
+} from '@llman-sdd/core';
+import type { Command } from 'commander';
+
+import {
+  CliError,
+  assertCompactJsonPairing,
+  addReportOutputOptions,
+  cliMaxScanDepth,
+  loadSpecEntries,
+  newIo,
+  resolveOutMode,
+} from '../cli-shared.ts';
+
+export function registerList(program: Command): void {
+  const list = program
+    .command('list')
+    .description('List changes or specs')
+    .option('--specs', 'list specs instead of changes')
+    .option('--sort <order>', 'recent (mtime desc, default) | name');
+  addReportOutputOptions(list);
+  list.action(
+    (options: {
+      specs?: boolean;
+      json?: boolean;
+      compactJson?: boolean;
+      output?: string;
+      sort?: string;
+    }) => {
+      if (!assertCompactJsonPairing(options)) return;
+      if (options.sort !== undefined && options.sort !== 'recent' && options.sort !== 'name') {
+        throw new CliError(`invalid --sort: ${options.sort}`);
+      }
+      const emit = (text: string): void => {
+        console.log(options.compactJson ? text.replaceAll('\n', '') : text);
+      };
+      if (options.specs) {
+        const summaries = collectSpecs(loadSpecEntries());
+        const specsMode = resolveOutMode(options.output, options.json, options.compactJson);
+        emit(
+          specsMode !== 'human'
+            ? renderSpecsJson(summaries, specsMode)
+            : renderSpecsList(summaries).join('\n'),
+        );
+        return;
+      }
+      let changes = collectChanges(newIo(), process.cwd(), new Date(), {
+        maxScanDepth: cliMaxScanDepth(program),
+      });
+      if (options.sort === 'name') {
+        changes = [...changes].toSorted((a, b) => a.name.localeCompare(b.name));
+      }
+      emit(
+        (() => {
+          const changesMode = resolveOutMode(options.output, options.json, options.compactJson);
+          return changesMode !== 'human'
+            ? renderChangesJson(changes, changesMode)
+            : renderChangesList(changes, new Date()).join('\n');
+        })(),
+      );
+    },
+  );
+}