@llman-sdd/cli 0.7.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llman-sdd/cli",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "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.7.0",
+    "@llman-sdd/core": "0.7.1",
     "commander": "^15.0.0"
   },
   "engines": {

package/src/commands/archive.ts

@@ -14,6 +14,7 @@ import type { Command } from 'commander';
 
 import { CliError } from '../cli-shared.ts';
 import { makeCliGit, makeIo } from '../io.ts';
+import { progressNote } from '../progress.ts';
 
 /**
  * r24: warn (never block) when freeze/thaw runs outside the main checkout —
@@ -69,6 +70,8 @@ export function registerArchive(program: Command): void {
             for (const line of await runList(io, sz, root)) console.log(line);
             return;
           }
+          // 7z 压缩可能耗时 — 进度提示防止看上去卡住(B1);dry-run/list 不走压缩
+          if (!options.dryRun) progressNote('freeze.pack', root);
           const result = await runFreeze(io, sz, root, {
             before: options.before,
             keepRecent: Number(options.keepRecent),
@@ -105,6 +108,8 @@ export function registerArchive(program: Command): void {
       const sz = await makeEmbeddedSevenZip();
       const io = makeIo(root);
       try {
+        // 7z 解包可能耗时 — 进度提示防止看上去卡住(B1)
+        progressNote('thaw.unpack', root);
         const result = await runThaw(io, sz, root, options.change, { dest: options.dest });
         for (const line of result.lines) console.log(line);
       } catch (error) {

package/src/commands/change.ts

@@ -1,5 +1,5 @@
 import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { basename, resolve } from 'node:path';
 
 import {
   CLOSE_OUT_TASK_HINT,
@@ -291,9 +291,9 @@ export function registerChange(program: Command): void {
           skipCleanTree: true,
           today: new Date().toISOString().slice(0, 10),
         });
-        const archiveName = (result.archiveDir ?? '').slice(
-          (result.archiveDir ?? '').lastIndexOf('/') + 1,
-        );
+        // node:path.basename — platform-aware (win32 backslashes would defeat
+        // a hand-rolled lastIndexOf('/')).
+        const archiveName = basename(result.archiveDir ?? '');
         console.log(`Change '${id}' archived as '${archiveName}'.`);
         if (result.executedIn !== null) {
           console.log(`executed in target worktree ${result.executedIn}`);

package/src/commands/context.ts

@@ -9,6 +9,7 @@ import {
 import type { Command } from 'commander';
 
 import { CliError, loadSpecEntries, newIo, resolveBackend } from '../cli-shared.ts';
+import { progressNote } from '../progress.ts';
 
 // (err path below converted to CliError; resolveBackend may also throw CliError)
 
@@ -45,6 +46,8 @@ export function registerContext(program: Command): void {
         console.log(JSON.stringify(unavailableResult(), null, 2));
         return;
       }
+      // LLM 链路可能是秒级 — 进度提示防止看上去卡住(B1)
+      progressNote('context.retrieve', process.cwd());
       const result = await runContextRetrieval({
         config,
         task: options.task ?? '',

package/src/commands/init.ts

@@ -6,6 +6,7 @@ import type { Command } from 'commander';
 
 import { CliError, templateIo, version } from '../cli-shared.ts';
 import { makeCliGit, makeIo } from '../io.ts';
+import { progressNote } from '../progress.ts';
 
 /**
  * r93: the repo-root instance (git toplevel, or outside any repo) carries the
@@ -43,6 +44,8 @@ export function registerInit(program: Command): void {
           mkdirSync(root, { recursive: true });
         }
         const repoRootInstance = isRepoRootInstance(root);
+        // 模板生成/子根扫块可能耗时 — 进度提示防止看上去卡住(B1)
+        progressNote('init.generate', root);
         const result = runInit(makeIo(root), templateIo, {
           update: options.update ?? false,
           locale: options.locale ?? options.lang,

package/src/commands/validate.ts

@@ -319,24 +319,28 @@ function warnDirtySpecsOnDefaultBranch(): void {
 let harnessBannerShown = false;
 
 /**
- * r13/r48 trigger state: the nested guard env and the check flags are read
+ * r13/r48 trigger state: the nested guard env and the check flag are read
  * here (CLI boundary) and injected into core as parameters — core harness
- * logic never touches process.env. Commander tri-state (both flags declared):
- * --check → check=true, --no-check → check=false, absent → undefined.
+ * logic never touches process.env. Commander binary state:
+ * --check → check=true, absent → undefined.
  */
 function makeHarnessGate(options: { check?: boolean }): HarnessGate {
   const runCommand = loadCliConfig()?.specs?.check_command ?? null;
   const configured = runCommand !== null && runCommand !== '';
   return {
     nested: process.env.LLMAN_SDD_HARNESS_ACTIVE === '1',
-    check: options.check === false ? 'off' : options.check === true ? 'on' : 'default',
+    // Opt-in harness (2026-10 decision): absent → 'off' — structure/state gate
+    // only; --check → 'on' (explicit full harness). The CLI never sends
+    // 'default'; core still treats a received 'default' as
+    // run-if-configured (its own contract).
+    check: options.check === true ? 'on' : 'off',
     runner: configured ? makeCliHarnessRunner() : undefined,
     runCommand,
     cwd: process.cwd(),
     onBeforeFirstRun: (expanded: string): void => {
       if (harnessBannerShown) return;
       harnessBannerShown = true;
-      console.error(`running spec check: ${expanded} (use --no-check to skip)`);
+      console.error(`running spec check: ${expanded} (explicit --check harness run)`);
     },
   };
 }
@@ -361,8 +365,7 @@ export function registerValidate(program: Command): void {
       'aggregate: validate every discovered llmanspec root (specs scope, any root red → non-zero exit)',
     )
     .option('--include-info', 'keep INFO-level issues (default: WARNING and above)')
-    .option('--no-check', 'skip the spec check')
-    .option('--check', 'run the spec check (default when specs.check_command is configured)');
+    .option('--check', 'run the spec check (full harness) explicitly — opt-in, default skips');
   addReportOutputOptions(validate);
   validate.action(
     (

package/src/io.ts

@@ -14,10 +14,20 @@ import {
   statSync,
   writeFileSync,
 } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 
 import { makeSpawnGit, type GitLike } from '@llman-sdd/core';
 
+/**
+ * Platform-aware parent directory (node:path.dirname, never hand-rolled
+ * '/' slicing): on win32, join() yields backslashes and a lastIndexOf('/')
+ * fallback would resolve to '.', so mkdir of a nested new dir would fail with
+ * ENOENT. Exported for unit-test guards (A2 platform compat).
+ */
+export function parentOf(p: string): string {
+  return dirname(p);
+}
+
 export interface CliIo {
   exists(path: string): boolean;
   readText(path: string): string;
@@ -37,7 +47,6 @@ export interface CliIo {
 
 export function makeIo(root: string): CliIo {
   const full = (p: string): string => (isAbsolute(p) ? p : join(root, p));
-  const parentOf = (p: string): string => p.slice(0, p.lastIndexOf('/')) || '.';
   return {
     exists: (p) => existsSync(full(p)),
     readText: (p) => readFileSync(full(p), 'utf8'),

package/src/progress.ts

@@ -0,0 +1,59 @@
+/**
+ * Localized stage-progress notes (B1): genuinely long-running operations print
+ * a short one-line stderr note in the project locale (zh → zh-Hans text,
+ * everything else English) so neither humans nor agents mistake progress for a
+ * hang. Progress ALWAYS goes to stderr (capture contract: results on stdout,
+ * progress on stderr); each key fires at most once per process; notes are only
+ * emitted before the long op itself, never ahead of domain errors.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+type Locale = 'zh' | 'en';
+
+const NOTES: Record<string, Record<Locale, string>> = {
+  'context.retrieve': {
+    zh: '正在检索 specs 上下文(LLM)...',
+    en: 'Retrieving spec context (LLM)...',
+  },
+  'init.generate': {
+    zh: '正在初始化 llmanspec/ 与 skills...',
+    en: 'Initializing llmanspec/ and skills...',
+  },
+  'freeze.pack': {
+    zh: '正在压缩冻结归档(7z)...',
+    en: 'Packing freeze archive (7z)...',
+  },
+  'thaw.unpack': {
+    zh: '正在解包冻结归档(7z)...',
+    en: 'Unpacking freeze archive (7z)...',
+  },
+};
+
+/** Resolve the note text for a locale (pure; exported for unit tests). */
+export function resolveNote(key: string, locale: Locale): string | undefined {
+  return NOTES[key]?.[locale];
+}
+
+/** Detect the project locale from llmanspec/config.yaml (zh-* → zh, else en). */
+export function detectLocale(cwd: string): Locale {
+  try {
+    const cfg = readFileSync(join(cwd, 'llmanspec', 'config.yaml'), 'utf8');
+    const m = cfg.match(/^locale:\s*([A-Za-z-]+)/mu);
+    if (m?.[1]?.startsWith('zh') ?? false) return 'zh';
+  } catch {
+    // No config at cwd — English fallback.
+  }
+  return 'en';
+}
+
+const shown = new Set<string>();
+
+/** Print a localized progress note to stderr once per key per process. */
+export function progressNote(key: string, cwd: string = process.cwd()): void {
+  if (shown.has(key)) return;
+  const text = resolveNote(key, detectLocale(cwd));
+  if (text === undefined) return;
+  shown.add(key);
+  process.stderr.write(`${text}\n`);
+}