@llman-sdd/cli 0.2.0 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@llman-sdd/cli",
-  "version": "0.2.0",
-  "description": "Spec-driven development workflow CLI (provides both `llman-sdd` and `llmanspec` commands)",
+  "version": "0.3.0",
+  "description": "Spec-driven development workflow CLI (the `llman-sdd` command)",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -9,8 +9,7 @@
     "directory": "apps/cli"
   },
   "bin": {
-    "llman-sdd": "./src/main.ts",
-    "llmanspec": "./src/main.ts"
+    "llman-sdd": "./src/main.ts"
   },
   "files": [
     "src"
@@ -28,7 +27,7 @@
     "build": "bun run ./scripts/build-binary.ts"
   },
   "dependencies": {
-    "@llman-sdd/core": "0.1.4",
+    "@llman-sdd/core": "0.2.0",
     "commander": "^15.0.0"
   },
   "engines": {

package/src/main.ts

@@ -8,16 +8,19 @@ import {
   buildReview,
   collectChanges,
   collectSpecs,
+  currentBranch,
+  defaultBranch,
   discoverSpecs,
   embeddedTemplates,
   graphMermaid,
+  loadTreeWithAutoRebuild,
   makeEmbeddedTemplateIo,
+  morphologyOfScenarios,
   nextReqId,
   changeDiff,
   deriveChangeId,
   finalizeChange,
   loadConfig,
-  loadTree,
   newChange,
   renderChangesJson,
   runContextRetrieval,
@@ -25,6 +28,7 @@ import {
   renderReviewHtml,
   renderSpecsJson,
   renderSpecsList,
+  resolveChangeId,
   runInit,
   scaffoldSpec,
   showChangeJson,
@@ -105,6 +109,42 @@ function cliMaxScanDepth(): number {
   return n;
 }
 
+/**
+ * r61: shared v1-r112 change id resolution for every change-taking command.
+ * Emits the `(prefix match)` hint on stderr and exits with the resolver's
+ * error message when resolution fails; returns null after reporting.
+ */
+function resolveChangeIdOrExit(
+  input: string,
+  opts: { suppressHint?: boolean } = {},
+): { id: string; viaPrefix: boolean } | null {
+  try {
+    const resolved = resolveChangeId(makeIo(process.cwd()), process.cwd(), input, {
+      maxScanDepth: cliMaxScanDepth(),
+    });
+    if (resolved.viaPrefix && opts.suppressHint !== true) {
+      console.error(`'${input}' -> '${resolved.id}' (prefix match)`);
+    }
+    return resolved;
+  } catch (error) {
+    console.error((error as Error).message);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+/** r63: default-branch dirty live specs — workspace-level guard, once per run. */
+function warnDirtySpecsOnDefaultBranch(): void {
+  const git = makeCliGit(process.cwd());
+  const current = currentBranch(git);
+  if (current === null || current !== defaultBranch(git)) return;
+  const out = git.runOpt(['status', '--porcelain', '--', 'llmanspec/specs']) ?? '';
+  if (out.trim() === '') return;
+  console.error(
+    `[WARNING] llmanspec/specs: live specs dirty on default branch \`${current}\`: do not commit unimplemented contracts to the default branch. Switch to the change's bound branch (or \`llman-sdd change start <id>\`) before editing llmanspec/specs/.`,
+  );
+}
+
 function runValidateSweep(): boolean {
   const report = validateAllSpecs(loadSpecEntries(), makeIo(process.cwd()));
   return report.verdicts.some((v) => !v.ok);
@@ -225,6 +265,7 @@ function specV1Items(opts: { strict?: boolean }): VItem[] {
 
 function changeV1Items(names: string[], opts: { stage?: string; strict?: boolean }): VItem[] {
   const io = makeIo(process.cwd());
+  const git = makeCliGit(process.cwd());
   const config = loadCliConfig();
   const items: VItem[] = [];
   for (const name of names) {
@@ -237,7 +278,7 @@ function changeV1Items(names: string[], opts: { stage?: string; strict?: boolean
         min_completion_ratio: config?.archive?.min_completion_ratio ?? null,
         change_id_pattern: config?.change_id?.pattern ?? null,
       },
-      { stage: opts.stage as never, strict: opts.strict === true },
+      { stage: opts.stage as never, strict: opts.strict === true, git },
     );
     items.push({
       id: name,
@@ -351,6 +392,7 @@ program
         process.exitCode = 1;
         return;
       }
+      warnDirtySpecsOnDefaultBranch();
       if (options.type !== undefined && options.type !== 'change' && options.type !== 'spec') {
         console.error(`invalid --type: ${options.type}`);
         process.exitCode = 1;
@@ -401,32 +443,39 @@ program
           process.exitCode = mine.valid ? 0 : 1;
           return;
         }
-        // change single
+        // change single (r61: v1 r112 prefix resolution on the change id)
         const io = makeIo(process.cwd());
         const root = process.cwd();
+        const resolved = resolveChangeIdOrExit(item, { suppressHint: options.json === true });
+        if (resolved === null) return;
+        const changeId = resolved.id;
         const res = validateChange(
           io,
           root,
-          item,
+          changeId,
           {
             strict_defer: loadCliConfig()?.archive?.strict_defer ?? null,
             min_completion_ratio: loadCliConfig()?.archive?.min_completion_ratio ?? null,
             change_id_pattern: loadCliConfig()?.change_id?.pattern ?? null,
           },
-          { stage: options.stage as never, strict: options.strict === true },
+          {
+            stage: options.stage as never,
+            strict: options.strict === true,
+            git: makeCliGit(process.cwd()),
+          },
         );
         const infos = res.issues.filter((i) => i.level === 'INFO');
         if (options.json) {
           renderValidateJson(
             [
               {
-                id: item,
+                id: changeId,
                 type: 'change',
                 valid: res.valid,
                 issues: res.issues,
                 durationMs: 0,
                 staleness: notApplicableStaleness(),
-                matchedViaPrefix: false,
+                matchedViaPrefix: resolved.viaPrefix,
               },
             ],
             options.compactJson === true,
@@ -435,9 +484,9 @@ program
           return;
         }
         if (res.valid) {
-          console.log(`Change '${item}' is valid`);
+          console.log(`Change '${changeId}' is valid`);
         } else {
-          console.error(`Change '${item}' has issues`);
+          console.error(`Change '${changeId}' has issues`);
           for (const issue of res.issues.filter((i) => i.level !== 'INFO'))
             console.error(`  [${issue.level}] ${issue.path}: ${issue.message}`);
           console.error('Next steps:');
@@ -544,13 +593,15 @@ change
     'feature branch prefix (default: sdd.branch_prefix config, then sdd/)',
   )
   .action((id: string, options: { branchPrefix?: string }) => {
+    const resolved = resolveChangeIdOrExit(id);
+    if (resolved === null) return;
     const git = makeCliGit(process.cwd());
     const config = loadCliConfig();
-    const result = startChange(git, makeIo(process.cwd()), id, {
+    const result = startChange(git, makeIo(process.cwd()), resolved.id, {
       branchPrefix: options.branchPrefix ?? config?.sdd?.branch_prefix ?? 'sdd/',
     });
     console.log(
-      `started change \`${id}\` → branch \`${result.branch}\` base \`${result.baseSha}\` base-branch \`${result.baseBranch}\``,
+      `started change \`${resolved.id}\` → branch \`${result.branch}\` base \`${result.baseSha}\` base-branch \`${result.baseBranch}\``,
     );
   });
 
@@ -561,12 +612,14 @@ change
   .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 result = attachChange(makeCliGit(process.cwd()), makeIo(process.cwd()), id, {
+    const resolved = resolveChangeIdOrExit(id);
+    if (resolved === null) return;
+    const result = attachChange(makeCliGit(process.cwd()), makeIo(process.cwd()), resolved.id, {
       force: options.force,
       base: options.base,
     });
     console.log(
-      `attached change \`${id}\` → branch \`${result.branch}\` base \`${result.baseSha}\` base-branch \`${result.baseBranch}\``,
+      `attached change \`${resolved.id}\` → branch \`${result.branch}\` base \`${result.baseSha}\` base-branch \`${result.baseBranch}\``,
     );
   });
 
@@ -607,10 +660,13 @@ change
       options: { into?: string; method?: string; dryRun?: boolean; force?: boolean },
     ) => {
       if (options.method !== undefined && options.method !== 'squash' && options.method !== 'ff') {
-        console.error(`invalid --method \`${options.method}\` (squash | ff)`);
+        console.error(`invalid --method: ${options.method}`);
         process.exitCode = 1;
         return;
       }
+      const resolved = resolveChangeIdOrExit(id);
+      if (resolved === null) return;
+      id = resolved.id;
       const io = makeIo(process.cwd());
       if (options.dryRun) {
         const date = new Date().toISOString().slice(0, 10);
@@ -661,6 +717,9 @@ change
   .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(id);
+    if (resolved === null) return;
+    id = resolved.id;
     const git = makeCliGit(process.cwd());
     if (options.json) {
       const info = changeDiffInfo(git, makeIo(process.cwd()), id);
@@ -705,6 +764,9 @@ change
           return;
         }
       }
+      const resolved = resolveChangeIdOrExit(id);
+      if (resolved === null) return;
+      id = resolved.id;
       const config = loadCliConfig();
       const method = options.method ?? config?.sdd?.merge_method ?? 'squash';
       const result = finalizeChange(makeCliGit(process.cwd()), makeIo(process.cwd()), id, {
@@ -812,20 +874,19 @@ program
       const raw = readFileSync(specPath, 'utf8').trimEnd();
       const summary = collectSpecs(loadSpecEntries()).find((x) => x.id === item);
       const morphology = summary
-        ? `\n\n## Morphology\nruleCount=${summary.morphology.ruleCount} enforced=${summary.morphology.ruleEnforcedCount} manual=${summary.morphology.ruleManualCount} pending=${summary.morphology.rulePendingCount} acceptanceCount=${summary.morphology.acceptanceCount}`
+        ? `\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 ----
-    const proposalPath = join('llmanspec', 'changes', item, 'proposal.md');
-    if (!existsSync(proposalPath)) {
-      console.error(`change not found: ${item}`);
-      process.exitCode = 1;
-      return;
-    }
-    const proposal = readFileSync(proposalPath, 'utf8');
+    // r61: v1 r112 prefix chain — exact > unique prefix > multiple > not found.
+    const resolved = resolveChangeIdOrExit(item, { suppressHint: asJson });
+    if (resolved === null) return;
+    const changeId = resolved.id;
+    const viaPrefix = resolved.viaPrefix;
+    const proposal = readFileSync(join('llmanspec', 'changes', changeId, 'proposal.md'), 'utf8');
     if (asJson) {
       // v1 parse_change gates: Why first, then What Changes (json only).
       if (!hasSection(proposal, 'Why')) {
@@ -843,7 +904,8 @@ program
           root: process.cwd(),
           specsDir: 'llmanspec/specs',
         },
-        item,
+        changeId,
+        { matchedViaPrefix: viaPrefix },
       );
       console.log(JSON.stringify(result, null, asCompact ? 0 : 2));
       return;
@@ -852,9 +914,9 @@ program
     const changes = collectChanges(makeIo(process.cwd()), process.cwd(), new Date(), {
       maxScanDepth: cliMaxScanDepth(),
     });
-    const change = changes.find((c) => c.name === item);
+    const change = changes.find((c) => c.name === changeId);
     console.log(`Stage: ${change?.stage ?? 'draft'}`);
-    console.log(`path: ${item}`);
+    console.log(`path: ${changeId}`);
     process.stdout.write(proposal);
     if (!proposal.endsWith('\n')) console.log();
     const gates = showChangeJson(
@@ -864,7 +926,7 @@ program
         root: process.cwd(),
         specsDir: 'llmanspec/specs',
       },
-      item,
+      changeId,
     ).gateChecks as { name: string; pass: boolean; hint: string }[];
     const passCount = gates.filter((g) => g.pass).length;
     console.log(`Gates: ${passCount}/${gates.length} pass`);
@@ -901,20 +963,7 @@ function renderSpecJson(
   const purpose = doc?.header.purpose ?? '';
   const humans = doc?.scenarios.filter((s) => s.classification === 'human') ?? [];
   const acceptances = doc?.scenarios.filter((s) => s.classification === 'executable') ?? [];
-  const morphology = {
-    ruleCount: humans.length,
-    ruleEnforcedCount: humans.filter((r) =>
-      acceptances.some((a) => a.reqIds.some((rid) => r.reqIds.includes(rid))),
-    ).length,
-    ruleManualCount: humans.filter(
-      (r) => r.reqIds.includes('manual') || r.statement.includes('@manual'),
-    ).length,
-    rulePendingCount: humans.filter(
-      (r) => !acceptances.some((a) => a.reqIds.some((rid) => r.reqIds.includes(rid))),
-    ).length,
-    acceptanceCount: acceptances.length,
-    orphanAcceptanceCount: acceptances.filter((a) => a.reqIds.length === 0).length,
-  };
+  const morphology = morphologyOfScenarios(doc?.scenarios ?? []);
   if (opts.metaOnly) {
     return {
       id: item,
@@ -1140,7 +1189,7 @@ archive
 
 const review = program
   .command('review')
-  .description('Aggregate review: pending/manual/unbound/stale signals plus a validate sweep');
+  .description('Aggregate review: pending/unbound/stale signals plus a validate sweep');
 
 review
   .option('--capability <capability>', 'restrict the sweep to one capability/spec id')
@@ -1346,18 +1395,28 @@ program
       return;
     }
     const config = resolveChatConfig(process.env as Record<string, string | undefined>);
+    // r62: lazy refresh runs BEFORE the chat-model gate (v1 r97 — the index
+    // self-heals even when retrieval subsequently fails with api_error).
+    const refresh = loadTreeWithAutoRebuild(
+      makeIo(process.cwd()),
+      '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) {
       // v1 parity: unavailable/error JSON on stdout, exit 0.
       console.log(JSON.stringify(unavailableResult(), null, 2));
       return;
     }
-    const tree = loadTree(makeIo(process.cwd()));
-    if (tree === null) {
-      const missing = unavailableResult();
-      missing.status.qualityNote = 'index missing — run `llman-sdd index rebuild` first';
-      console.log(JSON.stringify(missing, null, 2));
-      return;
-    }
     const result = await runContextRetrieval({
       config,
       task: options.task ?? '',
@@ -1375,12 +1434,17 @@ function commandChain(argv: string[]): string {
   let chain = '';
   let rest = argv.slice(2);
   while (rest.length > 0) {
-    const child = node.commands.find((c) => c.name() === rest[0]);
+    let child: Command | undefined;
+    for (const cmd of node.commands) {
+      if (cmd.name() === rest[0]) {
+        child = cmd;
+        break;
+      }
+    }
     if (child === undefined) break;
     chain += ` ${child.name()}`;
     node = child;
     rest = rest.slice(1);
-    // eslint-disable-next-line no-loop-func
   }
   return chain;
 }