@llman-sdd/cli 0.3.1 → 0.5.1

package/src/commands/project.ts

@@ -0,0 +1,54 @@
+import { buildReqRegistry, migrateNoteFor, migrateOverviewFor, planDedupe } from '@llman-sdd/core';
+import type { Command } from 'commander';
+
+import { CliError, loadCliConfig, loadSpecEntries, newIo } from '../cli-shared.ts';
+
+export function registerProject(program: Command): void {
+  const project = program.command('project').description('Project management commands');
+
+  project
+    .command('dedupe-req-ids')
+    .description('Remap globally duplicated req ids (report with --dry-run)')
+    .option('--dry-run', 'report the remap plan without writing')
+    .action((options: { dryRun?: boolean }) => {
+      // dedupe registry covers requirement handles (`@req` on 规则: headers) only;
+      // duplicates follow the occurrence model (同文件内共用或跨文件均算)
+      const entries = loadSpecEntries();
+      const { duplicates } = buildReqRegistry(entries);
+      if (duplicates.length === 0) {
+        console.log('No colliding req_id values in llmanspec/specs.');
+        return;
+      }
+      const io = newIo();
+      // r43: --dry-run is zero-side-effect — plan only, never write.
+      const plan = planDedupe(entries, io, 'llmanspec/specs', duplicates, {
+        apply: !options.dryRun,
+      });
+      // predecessor output: `{cap}: {from} → {to}` per remap (prefix in dry-run) + count line.
+      for (const item of plan) {
+        const cap = item.remapFile.replace(/^.*specs\//u, '').replace(/\.feature$/u, '');
+        const prefix = options.dryRun ? '[dry-run] ' : '';
+        console.log(`${prefix}${cap}: ${item.reqId} → ${item.newReqId}`);
+      }
+      console.log(`${plan.length} remapping(s)${options.dryRun ? ' (dry-run)' : ''}`);
+    });
+
+  project
+    .command('migrate')
+    .description('Legacy migration collaboration notes (prints guidance; performs no migration)')
+    .option('--kind <kind>', 'collaboration notes: toon2features | specs-flatten')
+    .action((options: { kind?: string }) => {
+      const locale = loadCliConfig()?.locale ?? 'en';
+      if (options.kind === undefined) {
+        console.log(migrateOverviewFor(locale));
+        return;
+      }
+      const note = migrateNoteFor(options.kind, locale);
+      if (note === null) {
+        throw new CliError(
+          `unknown migration kind: ${options.kind} (expected: toon2features | specs-flatten)`,
+        );
+      }
+      console.log(note);
+    });
+}

package/src/commands/review.ts

@@ -0,0 +1,83 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  buildReview,
+  collectChanges,
+  renderMachine,
+  renderReviewHtml,
+  specIdOf,
+  TEMPLATES_ROOT,
+} from '@llman-sdd/core';
+import type { Command } from 'commander';
+
+import {
+  addReportOutputOptions,
+  CliError,
+  cliMaxScanDepth,
+  exitWith,
+  loadSpecEntries,
+  newIo,
+  resolveOutMode,
+  templateIo,
+} from '../cli-shared.ts';
+import { makeCliGit } from '../io.ts';
+
+export function registerReview(program: Command): void {
+  const review = program
+    .command('review')
+    .description('Aggregate review: pending/unbound/stale signals plus a validate sweep');
+
+  review.option('--capability <capability>', 'restrict the sweep to one capability/spec id');
+  addReportOutputOptions(review);
+  review
+    .option('--export-html <path>', 'write a self-contained HTML report')
+    .action(
+      (options: {
+        capability?: string;
+        json?: boolean;
+        compactJson?: boolean;
+        output?: string;
+        exportHtml?: string;
+      }) => {
+        const io = newIo();
+        const entries = loadSpecEntries();
+        if (options.capability !== undefined) {
+          const known = new Set(entries.map((e) => specIdOf(e)));
+          if (!known.has(options.capability)) {
+            throw new CliError(`capability \`${options.capability}\` not found`);
+          }
+        }
+        const activeChanges = collectChanges(io, process.cwd(), new Date(), {
+          maxScanDepth: cliMaxScanDepth(program),
+        });
+        // B17: 墙钟与 base-ref env 由 CLI 注入,core 不直读 process.*/new Date()
+        const now = new Date();
+        const result = buildReview(
+          {
+            entries,
+            boundChangeCount: activeChanges.filter((c) => c.hasBinding).length,
+            activeChanges,
+            capability: options.capability,
+            git: makeCliGit(process.cwd()),
+            root: process.cwd(),
+            specsDir: 'llmanspec/specs',
+            baseRefEnv: process.env.LLMANSPEC_BASE_REF,
+          },
+          io,
+        );
+        if (options.exportHtml !== undefined) {
+          const template = templateIo.readText(join(TEMPLATES_ROOT, 'shared', 'review.html'));
+          writeFileSync(options.exportHtml, renderReviewHtml(template, result, now));
+          console.log(`wrote ${options.exportHtml}`);
+        }
+        const outMode = resolveOutMode(options.output, options.json, options.compactJson);
+        if (outMode !== 'human') {
+          console.log(renderMachine({ signals: result.signals, summary: result.summary }, outMode));
+        } else {
+          console.log(result.lines.join('\n'));
+        }
+        if (result.exitCode !== 0) exitWith(result.exitCode);
+      },
+    );
+}

package/src/commands/show.ts

@@ -0,0 +1,268 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  collectChanges,
+  collectSpecs,
+  morphologyOf,
+  renderMachine,
+  showChangeJson,
+  specIdOf,
+} from '@llman-sdd/core';
+import type { Command } from 'commander';
+
+import {
+  addReportOutputOptions,
+  CliError,
+  cliMaxScanDepth,
+  loadSpecEntries,
+  newIo,
+  resolveChangeIdOrExit,
+} from '../cli-shared.ts';
+import { makeCliGit } from '../io.ts';
+
+function hasSection(proposal: string, heading: string): boolean {
+  return (
+    new RegExp(`^## ${heading.replace(/[/\\]/u, '')}\\s*$`, 'mu').test(proposal) ||
+    proposal.includes(`## ${heading}`)
+  );
+}
+
+function renderSpecJson(
+  entries: ReturnType<typeof loadSpecEntries>,
+  item: string,
+  opts: { metaOnly: boolean; noScenarios: boolean },
+): Record<string, unknown> {
+  const entry = entries.find((e) => specIdOf(e) === item);
+  const doc = entry?.doc as
+    | {
+        header: { capability: string | null; purpose: string | null };
+        rules: {
+          reqId: string;
+          title: string;
+          description: string;
+          scenarios: {
+            name: string;
+            steps: { kind: string; text: string }[];
+          }[];
+        }[];
+        orphans: { name: string; steps: { kind: string; text: string }[] }[];
+      }
+    | undefined;
+  const cap = entry ? (doc?.header.capability ?? item) : item;
+  const purpose = doc?.header.purpose ?? '';
+  const rules = doc?.rules ?? [];
+  const morphology = morphologyOf(entry?.doc as never);
+  if (opts.metaOnly) {
+    return {
+      id: item,
+      featureId: cap,
+      title: cap,
+      purpose,
+      overview: purpose,
+      requirementCount: rules.length,
+      morphology,
+    };
+  }
+  const requirements = rules.map((rule) => ({
+    reqId: rule.reqId,
+    title: rule.title,
+    text: rule.description,
+    scenarios: opts.noScenarios
+      ? []
+      : rule.scenarios.map((a) => ({
+          id: a.name,
+          rawText: `GIVEN: ${a.steps
+            .filter((s) => s.kind === 'given')
+            .map((s) => s.text)
+            .join('\n')}\nWHEN: ${a.steps
+            .filter((s) => s.kind === 'when')
+            .map((s) => s.text)
+            .join('\n')}\nTHEN: ${a.steps
+            .filter((s) => s.kind === 'then')
+            .map((s) => s.text)
+            .join('\n')}`,
+          source: 'acceptance',
+          reqIds: [rule.reqId],
+        })),
+  }));
+  return {
+    id: item,
+    title: cap,
+    purpose,
+    overview: purpose,
+    requirementCount: rules.length,
+    requirements,
+    morphology,
+  };
+}
+
+export function registerShow(program: Command): void {
+  const show = program
+    .command('show')
+    .description('Show a change or spec')
+    .argument('<item>')
+    .option('--type <type>', 'force disambiguation: change | spec')
+    .option('-r, --requirement <n>', 'spec only: show a specific requirement by 1-based index');
+  addReportOutputOptions(show, {
+    outputHint: 'json | compact-json | toon | human | {json,meta-only|no-scenarios|reqs-only}',
+  });
+  show.action(
+    (
+      item: string,
+      options: {
+        output?: string;
+        type?: string;
+        requirement?: string;
+        json?: boolean;
+        compactJson?: boolean;
+      },
+    ) => {
+      // D4 shared surface: the registered --json/--compact-json aliases feed
+      // the same token set as --output so show honors them uniformly.
+      const outTokens = new Set(
+        [
+          ...(options.output ?? '').split(','),
+          ...(options.json === true ? ['json'] : []),
+          ...(options.compactJson === true ? ['compact-json'] : []),
+        ]
+          .map((t) => t.trim())
+          .filter((t) => t !== ''),
+      );
+      const VALID_TOKENS = new Set([
+        'json',
+        'toon',
+        'human',
+        'compact-json',
+        'compact',
+        'meta-only',
+        'no-scenarios',
+        'reqs-only',
+      ]);
+      for (const token of outTokens) {
+        if (!VALID_TOKENS.has(token)) {
+          throw new CliError(
+            `invalid --output token: ${token} (json | toon | human | compact-json | compact | meta-only | no-scenarios | reqs-only)`,
+            2,
+          );
+        }
+      }
+      // B10/Q1: `compact-json` is a real machine mode (single-line JSON), not a
+      // text fallback; legacy `compact` token aliases it.
+      const asCompact = outTokens.has('compact') || outTokens.has('compact-json');
+      const metaOnly = outTokens.has('meta-only');
+      const noScenarios = outTokens.has('no-scenarios');
+      const reqsOnly = outTokens.has('reqs-only');
+      // toon-default-output: no --output → toon; machine modes share the json
+      // gates (Why/What validation) and suppress the prefix hint; `human` is the
+      // sole predecessor text form. Legacy modifiers (meta-only/no-scenarios/reqs-only/
+      // -r) belong to the text face — they route to human (predecessor no-op render
+      // semantics preserved). The predecessor delta modifier was removed: unknown
+      // tokens are rejected like other report commands.
+      const wantsMachine = outTokens.has('json') || outTokens.has('toon') || asCompact;
+      // no --output at all → toon; explicit legacy-only modifiers → human text
+      const isHuman = options.output !== undefined && (outTokens.has('human') || !wantsMachine);
+      const asJson = !isHuman;
+      const showMode: 'json' | 'compact-json' | 'toon' = asCompact
+        ? 'compact-json'
+        : outTokens.has('json')
+          ? 'json'
+          : 'toon';
+      // predecessor: unknown output tokens are rejected by clap; script consumers rely on
+      // the deprecation being a no-op render rather than an error.
+      // Spec 判定与 collectSpecs/discoverSpecs 同口径:扁平文件与目录式
+      // `specs/<cap>/<cap>.feature` 均按 entry 精确 id(specIdOf:capability ?? 去
+      // `.feature` 后缀的 fileName)命中;r25 spec id 精确匹配优先于 change 前缀,
+      // 不做模糊解析。
+      // Discover once per run — the spec lookup, summary and JSON render below
+      // all share these entries.
+      const entries = loadSpecEntries();
+      const specEntry = entries.find((e) => specIdOf(e) === item);
+      const isSpec =
+        options.type === 'spec' ||
+        existsSync(join('llmanspec', 'specs', `${item}.feature`)) ||
+        specEntry !== undefined;
+
+      if (isSpec) {
+        const flatSpecPath = join('llmanspec', 'specs', `${item}.feature`);
+        // discoverSpecs 的 fileName 已是含 specs 目录前缀的相对路径
+        // (如 `llmanspec/specs/<cap>/<cap>.feature`),直接使用。
+        const specPath =
+          specEntry !== undefined && !existsSync(flatSpecPath) ? specEntry.fileName : flatSpecPath;
+        if (!existsSync(specPath)) {
+          throw new CliError(`spec not found: ${item}`);
+        }
+        if (asJson) {
+          console.log(
+            renderMachine(
+              renderSpecJson(entries, item, {
+                metaOnly,
+                noScenarios: noScenarios || reqsOnly,
+              }),
+              showMode,
+            ),
+          );
+          return;
+        }
+        // text mode: predecessor ignores all output modifiers (meta-only/no-scenarios/-r)
+        // and renders the full source + morphology.
+        const raw = readFileSync(specPath, 'utf8').trimEnd();
+        const summary = collectSpecs(entries).find((x) => x.id === item);
+        const morphology = summary
+          ? `\n\n## Morphology\nruleCount=${summary.morphology.ruleCount} enforced=${summary.morphology.ruleEnforcedCount} pending=${summary.morphology.rulePendingCount} acceptanceCount=${summary.morphology.acceptanceCount}`
+          : '';
+        console.log(`## Spec\n${raw}${morphology}`);
+        return;
+      }
+
+      // ---- change ----
+      // r61: predecessor r112 prefix chain — exact > unique prefix > multiple > not found.
+      const resolved = resolveChangeIdOrExit(program, item, { suppressHint: asJson });
+      const changeId = resolved.id;
+      const viaPrefix = resolved.viaPrefix;
+      const proposal = readFileSync(join('llmanspec', 'changes', changeId, 'proposal.md'), 'utf8');
+      if (asJson) {
+        // predecessor parse_change gates: Why first, then What Changes (json only).
+        if (!hasSection(proposal, 'Why')) {
+          throw new CliError('Change must have a Why section');
+        }
+        if (!hasSection(proposal, 'What Changes')) {
+          throw new CliError('Change must have a What Changes section');
+        }
+        const result = showChangeJson(
+          {
+            io: newIo(),
+            git: makeCliGit(process.cwd()),
+            root: process.cwd(),
+            specsDir: 'llmanspec/specs',
+          },
+          changeId,
+          { matchedViaPrefix: viaPrefix },
+        );
+        console.log(renderMachine(result, showMode));
+        return;
+      }
+      // text: Stage / path / content / Gates trailer (no section gates).
+      const changes = collectChanges(newIo(), process.cwd(), new Date(), {
+        maxScanDepth: cliMaxScanDepth(program),
+      });
+      const change = changes.find((c) => c.name === changeId);
+      console.log(`Stage: ${change?.stage ?? 'draft'}`);
+      console.log(`path: ${changeId}`);
+      process.stdout.write(proposal);
+      if (!proposal.endsWith('\n')) console.log();
+      const gates = showChangeJson(
+        {
+          io: newIo(),
+          git: makeCliGit(process.cwd()),
+          root: process.cwd(),
+          specsDir: 'llmanspec/specs',
+        },
+        changeId,
+      ).gateChecks as { name: string; pass: boolean; hint: string }[];
+      const passCount = gates.filter((g) => g.pass).length;
+      console.log(`Gates: ${passCount}/${gates.length} pass`);
+      for (const g of gates.filter((g) => !g.pass)) console.log(`✗ ${g.name}: ${g.hint}`);
+    },
+  );
+}

package/src/commands/spec.ts

@@ -0,0 +1,181 @@
+import { existsSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+
+import {
+  addReq,
+  addScenario,
+  hasNativeRules,
+  migrateNativeSource,
+  nextReqId,
+  resolveReq,
+  scaffoldSpec,
+} from '@llman-sdd/core';
+import type { Command } from 'commander';
+
+import { CliError, loadCliConfig, loadSpecEntries, newIo } from '../cli-shared.ts';
+
+/** Walk paths collecting .feature files (directories recurse). */
+function collectFeatureFiles(paths: string[]): string[] {
+  const files: string[] = [];
+  const walk = (dir: string): void => {
+    for (const name of readdirSync(dir).toSorted()) {
+      const full = join(dir, name);
+      if (statSync(full).isDirectory()) walk(full);
+      else if (name.endsWith('.feature')) files.push(full);
+    }
+  };
+  for (const p of paths) {
+    if (!existsSync(p)) throw new CliError(`path not found: ${p}`);
+    if (statSync(p).isDirectory()) walk(p);
+    else files.push(p);
+  }
+  return files;
+}
+
+function confirmInteractive(question: string): Promise<boolean> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}
+
+export function registerSpec(program: Command): void {
+  const spec = program.command('spec').description('Spec authoring helpers');
+
+  spec
+    .command('skeleton')
+    .description('Generate a single-track spec skeleton for a capability')
+    .argument('<capability>')
+    .option('--force', 'overwrite an existing spec file')
+    .action((capability: string, options: { force?: boolean }) => {
+      const locale = loadCliConfig()?.locale ?? 'en';
+      const path = join('llmanspec', 'specs', `${capability}.feature`);
+      if (!options.force && existsSync(path)) {
+        throw new CliError(`spec already exists: ${path} (use --force to overwrite)`);
+      }
+      const written = scaffoldSpec(newIo(), 'llmanspec/specs', capability, locale, {
+        force: options.force,
+      });
+      console.log(`wrote ${written}`);
+    });
+
+  spec
+    .command('next-req-id')
+    .description('Allocate the next free global req id (rN)')
+    .option('--json', 'emit {reqId}')
+    .action((options: { json?: boolean }) => {
+      const reqId = nextReqId(newIo(), 'llmanspec/specs');
+      if (options.json) console.log(JSON.stringify({ reqId }, null, 2));
+      else console.log(reqId);
+    });
+
+  spec
+    .command('add-req')
+    .alias('add-requirement')
+    .description('Append a 规则: block (with @req handle) to a capability spec')
+    .argument('<capability>')
+    .argument('<req_id>')
+    .requiredOption('--title <title>', 'rule title')
+    .requiredOption('--statement <statement>', 'rule statement (free text; multiple lines via \\n)')
+    .action((capability: string, reqId: string, options: { title: string; statement: string }) => {
+      const io = newIo();
+      const path = addReq(io, 'llmanspec/specs', loadSpecEntries(), {
+        capability,
+        reqId,
+        title: options.title,
+        statement: options.statement,
+      });
+      console.log(path);
+    });
+
+  spec
+    .command('add-scenario')
+    .description('Insert a nested 场景: under the named rule in a spec')
+    .argument('<capability>')
+    .argument('<req_id>')
+    .argument('<scenario_id>')
+    .option('--given <given>', 'Given step (optional)')
+    .requiredOption('--when <when>', 'When step')
+    .requiredOption('--then <then>', 'Then step')
+    .action(
+      (
+        capability: string,
+        reqId: string,
+        scenarioId: string,
+        options: { given?: string; when: string; then: string },
+      ) => {
+        const io = newIo();
+        const path = addScenario(io, 'llmanspec/specs', loadSpecEntries(), {
+          capability,
+          reqId,
+          scenarioId,
+          given: options.given,
+          when: options.when,
+          thenText: options.then,
+        });
+        console.log(path);
+      },
+    );
+
+  spec
+    .command('migrate-native')
+    .description('Migrate legacy tag-based .feature files to the native 规则:/场景: layout')
+    .argument('[paths...]', 'feature files or directories (default: llmanspec/specs)')
+    .option('--dry-run', 'print the migration plan without writing')
+    .option('-y, --yes', 'proceed without per-file confirmation')
+    .action(async (paths: string[], options: { dryRun?: boolean; yes?: boolean }) => {
+      const targets = collectFeatureFiles(paths.length > 0 ? paths : ['llmanspec/specs']);
+      const io = newIo();
+      let migrated = 0;
+      let skipped = 0;
+      for (const file of targets) {
+        const source = io.readText(file);
+        // already native? layout detection via the official parser
+        if (hasNativeRules(source)) {
+          skipped++;
+          if (options.dryRun) console.log(`[skip] ${file} (already native)`);
+          continue;
+        }
+        const result = migrateNativeSource(source);
+        if (!result.ok) {
+          console.error(`[error] ${file}: ${result.message}`);
+          continue;
+        }
+        const line = `[migrate] ${file}: ${result.rules} rule(s), ${result.scenarios} scenario(s)`;
+        if (options.dryRun) {
+          console.log(`${line} (dry-run)`);
+          migrated++;
+          continue;
+        }
+        if (options.yes || (await confirmInteractive(`${line}. Write? (y/N) `))) {
+          writeFileSync(file, result.content, 'utf8');
+          console.log(line);
+          migrated++;
+        } else {
+          console.log(`[skip] ${file} (declined)`);
+        }
+      }
+      console.log(`migrate-native: ${migrated} file(s) migrated, ${skipped} already native`);
+    });
+
+  spec
+    .command('resolve-req')
+    .description('Resolve an rN to its capability and statement')
+    .argument('<req_id>')
+    .action((reqId: string) => {
+      const resolved = resolveReq(loadSpecEntries(), reqId);
+      if (resolved === null) {
+        throw new CliError(`req id not found: ${reqId}`);
+      }
+      console.log(`reqId: ${resolved.reqId}`);
+      console.log(`capability: ${resolved.capability}`);
+      console.log(`title: ${resolved.title}`);
+      console.log(`statement: ${resolved.statement.replaceAll('\n', ' ')}`);
+      console.log('harness:');
+      for (const h of resolved.harness) console.log(`  - ${h}`);
+    });
+}