@cyning/harness 1.0.0 → 1.0.2

package/lib/cli.js

@@ -1,6 +1,9 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
 import { readManifest, isNewerVersion } from './manifest.js';
 import {
   resolveHarnessRoot,
+  resolveHarnessRootForTarget,
   resolvePackageVersion,
   resolveTarget,
   wizardScript,
@@ -8,15 +11,21 @@ import {
 import { runBash } from './run.js';
 import { checkTaskFile } from './task.js';
 import { auditTarget } from './audit.js';
+import { mergePackageScripts } from './package-scripts.js';
 
 function usage() {
-  console.log(`@cyning/harness · cyning-harness CLI (v0.3+)
+  console.log(`@cyning/harness · cyning-harness CLI (v1.0.2)
 
 用法:
-  npx @cyning/harness init [--preset NAME] [--ide LIST] [--target PATH] [--yes]
-  npx @cyning/harness upgrade [--target PATH] [--ide LIST] [--yes] [--force] [--gate-check]
+  npx @cyning/harness --version | -V
+  npx @cyning/harness --help | -h
+  npx @cyning/harness init [--preset NAME] [--ide LIST] [--target PATH] [--yes] [--with-scripts] [--pm pnpm|npm|yarn|auto]
+  npx @cyning/harness upgrade [--target PATH] [--ide LIST] [--yes] [--force] [--gate-check] [--with-scripts] [--pm pnpm|npm|yarn|auto]
   npx @cyning/harness check [--target PATH]
   npx @cyning/harness audit [--target PATH] [--task FILE]
+  npx @cyning/harness gate-check [--target PATH] [--task FILE] [--graph] [--json]
+  npx @cyning/harness verify [--target PATH] [--task FILE] [--graph]
+  npx @cyning/harness sync index [--target PATH]
   npx @cyning/harness task check --file PATH [--no-circular] [--registry DIR]...
 
 说明:
@@ -24,6 +33,9 @@ function usage() {
   upgrade     升级已接入仓 · 等价 wizard/upgrade.sh --yes
   check       读 manifest.json · 对比当前包版本是否有可升级版本
   audit       ICVO 机械审计：复用 gate-check · D5 测试声明检查 · S5 git-clean 提醒
+  gate-check  调用 wizard/gate-check.sh（业务仓无需 clone 即可用）
+  verify      30 前聚合：gate-check + audit D5 + S5 warn + 可选 --graph
+  sync index  生成 .cyning-harness/invoke_index.json
   task check  校验 task.harness.v1.json sidecar · --no-circular 检测 depends_on 环
 
 环境:
@@ -51,6 +63,11 @@ export async function runCli(argv) {
     return;
   }
 
+  if (argv.includes('--version') || argv.includes('-V')) {
+    console.log(pkgVersion);
+    return;
+  }
+
   const [cmd, ...rest] = argv;
 
   if (cmd === 'init') {
@@ -69,6 +86,18 @@ export async function runCli(argv) {
     await cmdAudit(rest);
     return;
   }
+  if (cmd === 'gate-check') {
+    await cmdGateCheck(rest);
+    return;
+  }
+  if (cmd === 'verify') {
+    await cmdVerify(rest);
+    return;
+  }
+  if (cmd === 'sync') {
+    await cmdSync(rest);
+    return;
+  }
   if (cmd === 'task') {
     await cmdTask(rest);
     return;
@@ -81,13 +110,16 @@ export async function runCli(argv) {
 
 async function cmdInit(args, harnessRoot, pkgVersion) {
   const yes = args.includes('--yes');
-  let rest = args.filter((a) => a !== '--yes');
+  const withScripts = args.includes('--with-scripts');
+  let rest = args.filter((a) => a !== '--yes' && a !== '--with-scripts');
   const { value: preset, rest: r1 } = takeOption(rest, '--preset');
   rest = r1;
   const { value: ide, rest: r2 } = takeOption(rest, '--ide');
   rest = r2;
   const { value: targetArg, rest: r3 } = takeOption(rest, '--target');
   rest = r3;
+  const { value: pm, rest: r4 } = takeOption(rest, '--pm');
+  rest = r4;
 
   if (rest.length > 0) {
     const err = new Error(`init 未知参数: ${rest.join(' ')}`);
@@ -109,6 +141,18 @@ async function cmdInit(args, harnessRoot, pkgVersion) {
     inherit: true,
   });
 
+  if (withScripts) {
+    const ps = mergePackageScripts(target, pkgVersion, pm || 'auto');
+    if (ps.skipped) {
+      console.log(`warn: ${ps.reason}`);
+    } else if (ps.changed) {
+      console.log(`scripts: ${ps.reason}（pm: ${ps.pm}）`);
+      console.log('提示: 运行 `pnpm install` 或对应 install 使 devDep 生效');
+    } else {
+      console.log(`scripts: ${ps.reason}`);
+    }
+  }
+
   console.log(`manifest: ${target}/.cyning-harness/manifest.json`);
   if (!yes) {
     console.log('init 完成。');
@@ -120,13 +164,23 @@ async function cmdUpgrade(args, harnessRoot, pkgVersion) {
   const force = args.includes('--force');
   const gateCheck = args.includes('--gate-check');
   const yes = args.includes('--yes') || !checkOnly;
+  const withScripts = args.includes('--with-scripts');
   let rest = args.filter(
-    (a) => !['--check', '--force', '--gate-check', '--yes'].includes(a),
+    (a) =>
+      ![
+        '--check',
+        '--force',
+        '--gate-check',
+        '--yes',
+        '--with-scripts',
+      ].includes(a),
   );
   const { value: ide, rest: r1 } = takeOption(rest, '--ide');
   rest = r1;
   const { value: targetArg, rest: r2 } = takeOption(rest, '--target');
   rest = r2;
+  const { value: pm, rest: r3 } = takeOption(rest, '--pm');
+  rest = r3;
 
   if (rest.length > 0) {
     const err = new Error(`upgrade 未知参数: ${rest.join(' ')}`);
@@ -156,6 +210,18 @@ async function cmdUpgrade(args, harnessRoot, pkgVersion) {
     },
     inherit: true,
   });
+
+  if (withScripts) {
+    const ps = mergePackageScripts(target, pkgVersion, pm || 'auto');
+    if (ps.skipped) {
+      console.log(`warn: ${ps.reason}`);
+    } else if (ps.changed) {
+      console.log(`scripts: ${ps.reason}（pm: ${ps.pm}）`);
+      console.log('提示: 运行 `pnpm install` 或对应 install 使 devDep 生效');
+    } else {
+      console.log(`scripts: ${ps.reason}`);
+    }
+  }
 }
 
 async function cmdCheck(args, harnessRoot, pkgVersion) {
@@ -236,6 +302,133 @@ async function cmdAudit(args) {
   }
 }
 
+async function cmdGateCheck(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`用法: npx @cyning/harness gate-check [--target PATH] [--task FILE] [--graph] [--json]`);
+    return;
+  }
+
+  let rest = args;
+  const { value: targetArg, rest: r1 } = takeOption(rest, '--target');
+  rest = r1;
+  const { value: taskFile, rest: r2 } = takeOption(rest, '--task');
+  rest = r2;
+  const graph = rest.includes('--graph');
+  const json = rest.includes('--json');
+  rest = rest.filter((a) => a !== '--graph' && a !== '--json');
+
+  if (rest.length > 0) {
+    const err = new Error(`gate-check 未知参数: ${rest.join(' ')}`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const target = resolveTarget(process.cwd(), targetArg);
+  const harnessRoot = resolveHarnessRootForTarget(target);
+  const script = wizardScript(harnessRoot, 'gate-check.sh');
+  const childArgs = ['--target', target];
+  if (taskFile) childArgs.push('--task', taskFile);
+  if (graph) childArgs.push('--graph');
+  if (json) childArgs.push('--json');
+
+  const result = spawnSync('bash', [script, ...childArgs], {
+    stdio: 'inherit',
+    env: { ...process.env, CYNING_HARNESS: harnessRoot },
+  });
+
+  const exitCode = result.status ?? 1;
+  if (exitCode !== 0) {
+    const err = new Error('');
+    err.exitCode = exitCode;
+    throw err;
+  }
+}
+
+async function cmdVerify(args) {
+  // D3 · implemented in lib/verify.js
+  const { verifyTarget } = await import('./verify.js');
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`用法: npx @cyning/harness verify [--target PATH] [--task FILE] [--graph]
+
+无 --task 时：扫描 docs/tasks/active/task_*.md 并逐项列出闸表（同 gate-check）。
+任一 task 阻塞则 VERIFY: BLOCKED · exit 2；全部可 30 则 VERIFY: PASS。
+`);
+    return;
+  }
+
+  let rest = args;
+  const { value: targetArg, rest: r1 } = takeOption(rest, '--target');
+  rest = r1;
+  const { value: taskFile, rest: r2 } = takeOption(rest, '--task');
+  rest = r2;
+  const graph = rest.includes('--graph');
+  rest = rest.filter((a) => a !== '--graph');
+
+  if (rest.length > 0) {
+    const err = new Error(`verify 未知参数: ${rest.join(' ')}`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const target = resolveTarget(process.cwd(), targetArg);
+  const result = verifyTarget(target, { taskFile, graph });
+
+  // forward gate-check/audit/graph stdout if any
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+
+  const summary = taskFile
+    ? `VERIFY: ${result.ok ? 'PASS' : 'BLOCKED'}${result.reason ? ` · ${result.reason}` : ''} · ${path.basename(taskFile)}`
+    : `VERIFY: ${result.ok ? 'PASS' : 'BLOCKED'}${result.reason ? ` · ${result.reason}` : ''}`;
+  console.log(summary);
+
+  if (!result.ok) {
+    process.exitCode = result.exitCode ?? 2;
+    return;
+  }
+}
+
+async function cmdSync(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`用法: npx @cyning/harness sync index [--target PATH]`);
+    return;
+  }
+
+  const [sub, ...rest] = args;
+  if (sub !== 'index') {
+    const err = new Error(`sync 子命令未知: ${sub ?? '(空)'}\n用法: sync index [--target PATH]`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  let remaining = rest;
+  const { value: targetArg, rest: r1 } = takeOption(remaining, '--target');
+  remaining = r1;
+
+  if (remaining.length > 0) {
+    const err = new Error(`sync index 未知参数: ${remaining.join(' ')}`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const target = resolveTarget(process.cwd(), targetArg);
+  const harnessRoot = resolveHarnessRootForTarget(target);
+  const script = wizardScript(harnessRoot, 'harness-sync.sh');
+
+  const result = spawnSync('bash', [script, '--index', '--target', target], {
+    stdio: 'inherit',
+    env: { ...process.env, CYNING_HARNESS: harnessRoot },
+  });
+
+  const exitCode = result.status ?? 1;
+  if (exitCode !== 0) {
+    const err = new Error('');
+    err.exitCode = exitCode;
+    throw err;
+  }
+}
+
 async function cmdTask(args) {
   const [sub, ...rest] = args;
   if (sub !== 'check') {

package/lib/package-scripts.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DEFAULT_SCRIPTS = {
+  'harness:verify': 'harness verify',
+  'harness:gate': 'harness gate-check',
+  'harness:audit': 'harness audit',
+};
+
+function detectPackageManager(target) {
+  if (fs.existsSync(path.join(target, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(target, 'yarn.lock'))) return 'yarn';
+  if (fs.existsSync(path.join(target, 'package-lock.json'))) return 'npm';
+  return 'npm';
+}
+
+/**
+ * 在 target 仓的 package.json 中 merge devDep + scripts（不覆盖已有 key）。
+ * @returns {{ok: boolean, skipped?: boolean, reason?: string, changed: boolean}}
+ */
+export function mergePackageScripts(target, version, pm = 'auto') {
+  const pkgPath = path.join(target, 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    return {
+      ok: true,
+      skipped: true,
+      reason: '未找到 package.json，跳过 --with-scripts',
+      changed: false,
+    };
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const original = JSON.stringify(pkg);
+
+  if (!pkg.devDependencies) pkg.devDependencies = {};
+  if (pkg.devDependencies['@cyning/harness'] !== version) {
+    pkg.devDependencies['@cyning/harness'] = version;
+  }
+
+  if (!pkg.scripts) pkg.scripts = {};
+  for (const [key, value] of Object.entries(DEFAULT_SCRIPTS)) {
+    if (!Object.prototype.hasOwnProperty.call(pkg.scripts, key)) {
+      pkg.scripts[key] = value;
+    }
+  }
+
+  if (JSON.stringify(pkg) !== original) {
+    fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+    return {
+      ok: true,
+      skipped: false,
+      changed: true,
+      pm: pm === 'auto' ? detectPackageManager(target) : pm,
+      reason: `已写入 @cyning/harness@${version} 与 scripts`,
+    };
+  }
+
+  return {
+    ok: true,
+    skipped: false,
+    changed: false,
+    pm: pm === 'auto' ? detectPackageManager(target) : pm,
+    reason: 'package.json 已包含所需 devDep/scripts',
+  };
+}

package/lib/paths.js

@@ -12,6 +12,33 @@ export function resolveHarnessRoot() {
   return path.resolve(__dirname, '..');
 }
 
+/**
+ * 对指定业务仓 target 解析可用产品包根。
+ * 顺序：env CYNING_HARNESS → target/.cyning-harness/local.json → npm 包根
+ */
+export function resolveHarnessRootForTarget(target) {
+  if (process.env.CYNING_HARNESS) {
+    return path.resolve(process.env.CYNING_HARNESS);
+  }
+
+  const localJson = path.join(target, '.cyning-harness', 'local.json');
+  if (fs.existsSync(localJson)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(localJson, 'utf8'));
+      if (data.cyning_harness_root) {
+        const candidate = path.resolve(target, data.cyning_harness_root);
+        if (fs.existsSync(path.join(candidate, 'wizard', 'gate-check.sh'))) {
+          return candidate;
+        }
+      }
+    } catch {
+      // fall through
+    }
+  }
+
+  return path.resolve(__dirname, '..');
+}
+
 export function resolvePackageVersion(harnessRoot) {
   if (process.env.HARNESS_VERSION) {
     return process.env.HARNESS_VERSION;

package/lib/verify.js

@@ -0,0 +1,152 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveHarnessRootForTarget, wizardScript } from './paths.js';
+import { auditTarget } from './audit.js';
+
+/**
+ * 30 前聚合验证：gate-check + audit D5（仅 --task）+ S5 git-clean warn + 可选 --graph
+ */
+export function verifyTarget(target, options = {}) {
+  const { taskFile, graph } = options;
+  const harnessRoot = resolveHarnessRootForTarget(target);
+
+  // 1. gate-check（含 --graph）
+  const gateResult = runGateCheck(target, taskFile, graph, harnessRoot);
+  if (!gateResult.ok) {
+    return {
+      ok: false,
+      exitCode: 2,
+      reason: gateResult.reason,
+      stdout: gateResult.stdout,
+    };
+  }
+
+  // 2. audit D5（仅当指定 task）
+  if (taskFile) {
+    const audit = auditTarget(target, { taskFile });
+    if (!audit.ok) {
+      return {
+        ok: false,
+        exitCode: 2,
+        reason: audit.test.ok ? 'gate-check 或 audit 未通过' : audit.test.reason,
+        stdout: gateResult.stdout,
+      };
+    }
+  }
+
+  // 3. S5 git-clean：warn 不挡
+  const gitResult = runGitCleanCheck(target);
+  if (gitResult.dirty) {
+    // 把 warn 拼到 stdout 里让 CLI 透传
+    const warn = `WARN: 工作区未 clean（S5）：建议 commit 后再执行 apply\n`;
+    gateResult.stdout += warn;
+  }
+
+  return {
+    ok: true,
+    exitCode: 0,
+    stdout: gateResult.stdout,
+  };
+}
+
+function runGateCheck(target, taskFile, graph, harnessRoot) {
+  const script = wizardScript(harnessRoot, 'gate-check.sh');
+  const args = [script, '--target', target];
+  if (taskFile) args.push('--task', taskFile);
+  if (graph) args.push('--graph');
+
+  const result = spawnSync('bash', args, {
+    encoding: 'utf8',
+    env: { ...process.env, CYNING_HARNESS: harnessRoot },
+  });
+
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      status: result.status,
+      stdout: result.stdout,
+      reason: extractBlockReason(result.stdout, taskFile),
+    };
+  }
+
+  return {
+    ok: true,
+    status: 0,
+    stdout: result.stdout,
+  };
+}
+
+function extractBlockReason(stdout, taskFile) {
+  const taskBasename = taskFile ? path.basename(taskFile) : undefined;
+  const sections = splitGateCheckTaskSections(stdout);
+
+  if (taskBasename) {
+    const section = sections.get(taskBasename) ?? stdout;
+    const arrows = extractArrowBlockLines(section);
+    if (arrows.length > 0) return arrows[0];
+    return 'gate-check blocked';
+  }
+
+  const blocked = [];
+  for (const [name, section] of sections) {
+    const arrows = extractArrowBlockLines(section);
+    if (arrows.length > 0) {
+      blocked.push({ name, reason: arrows[0] });
+    }
+  }
+
+  if (blocked.length === 0) return 'gate-check blocked';
+
+  const total = sections.size;
+  if (blocked.length === 1) {
+    const { name, reason } = blocked[0];
+    return total === 1 ? reason : `${name} · ${reason}`;
+  }
+
+  const names = blocked.map((b) => b.name).join(', ');
+  return `${blocked.length}/${total} tasks blocked · ${names}`;
+}
+
+/** 按 gate-check 输出的 `task: xxx.md` 切段 */
+function splitGateCheckTaskSections(stdout) {
+  const map = new Map();
+  let current = null;
+  const lines = [];
+
+  const flush = () => {
+    if (current) map.set(current, lines.join('\n'));
+  };
+
+  for (const line of stdout.split('\n')) {
+    const match = line.match(/^task: (.+\.md)\s*$/);
+    if (match) {
+      flush();
+      current = match[1];
+      lines.length = 0;
+      lines.push(line);
+    } else if (current) {
+      lines.push(line);
+    }
+  }
+  flush();
+  return map;
+}
+
+/** 只认 gate-check 的 `→ 30 不可开工` 行，避免误匹配表格里的 `❌ 拒 30` */
+function extractArrowBlockLines(section) {
+  return section
+    .split('\n')
+    .filter((line) => line.trimStart().startsWith('→ 30 不可开工'))
+    .map((line) => line.trim().replace(/^→\s*/, ''));
+}
+
+function runGitCleanCheck(target) {
+  const result = spawnSync('git', ['status', '--porcelain'], {
+    encoding: 'utf8',
+    cwd: target,
+  });
+
+  const dirty = result.status === 0 && result.stdout.trim().length > 0;
+  return { dirty };
+}

package/ontology.yaml

@@ -3,7 +3,7 @@
 # 冲突时以 Markdown 为准 · 供未来 harness ontology-check 使用
 
 version: "1.2"
-product_semver: "1.0.0"
+product_semver: "1.0.2"
 license: MIT
 
 classes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyning/harness",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "cyning-harness discipline package · init / upgrade / check CLI",
   "license": "MIT",
   "type": "module",

package/wizard/README.md

@@ -15,6 +15,9 @@ npx @cyning/harness@latest init --preset harness-only --ide cursor,agents
 npx @cyning/harness upgrade
 npx @cyning/harness upgrade --target /path/to/project --yes --force
 
+# 30 前验证
+npx @cyning/harness verify --target /path/to/project
+
 # 仅检查版本
 npx @cyning/harness check
 ```
@@ -22,6 +25,7 @@ npx @cyning/harness check
 - 内部单源：`wizard/install.sh` → `harness-sync.sh apply`（S2 写路径不变）
 - manifest schema：[`schema/manifest.v1.schema.json`](../schema/manifest.v1.schema.json)
 - 本地开发：`node bin/harness.js init --target /path/to/project --preset harness-only --ide cursor,agents --yes`
+- Node 仓可选：`npx @cyning/harness init --with-scripts --pm pnpm`
 
 ---