@dzhechkov/harness-cli 0.3.228 → 0.3.230

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.228",
+  "version": "0.3.230",
   "description": "The dz CLI — install AI skills for Claude Code, Codex, OpenCode, Hermes, OpenClaude, GitHub Copilot. 35 commands, 13 presets, 6 platform targets.",
   "type": "module",
   "license": "MIT",
@@ -55,7 +55,7 @@
     "@dzhechkov/skills-reverse-engineering": "^0.1.0",
     "@dzhechkov/skills-presentation-storyteller": "^0.1.0",
     "@dzhechkov/skills-website-cloner": "^0.1.0",
-    "@dzhechkov/harness-core": "0.3.121"
+    "@dzhechkov/harness-core": "0.3.122"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/src/cli.ts

@@ -102,6 +102,11 @@ import {
   resolveTrustRoot,
   decideVerifyPolicy,
   generateSigningKeypair,
+  evaluateGuard,
+  resolveRules,
+  auditRecord,
+  guardExitCode,
+  DEFAULT_RULES,
   decideProvenance,
   isInsideTree,
   signManifest,
@@ -3384,8 +3389,8 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
   // Reject unknown flags/options so a typo (e.g. `--dry-rum`) can NEVER be
   // silently swallowed and flip the command into live-publish mode.
   const allowedFlags = new Set(['dry-run', 'no-dry-run', 'yes', 'confirm', 'bump-only', 'help', 'require-signing', 'provenance', 'no-provenance']);
-  const allowedOptions = new Set(['filter', 'claim-check']);
-  const allowedHelp = '  allowed: --dry-run (default), --yes/--confirm/--no-dry-run (go live), --bump-only, --filter <substr>, --claim-check <off|warn|error>';
+  const allowedOptions = new Set(['filter', 'claim-check', 'no-guard']);
+  const allowedHelp = '  allowed: --dry-run (default), --yes/--confirm/--no-dry-run (go live), --bump-only, --filter <substr>, --claim-check <off|warn|error>, --no-guard "<reason>" (skip the guard pre-flight; logged)';
   for (const flag of flags) {
     if (!allowedFlags.has(flag)) {
       write(`dz publish: unknown option --${flag}`);
@@ -3402,6 +3407,29 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
     }
   }
 
+  // dz guard pre-flight (ADR-002 option A): publish is the most dangerous, least-reversible self-mutation, so
+  // it ALWAYS runs the declarative guard first. A HARD violation refuses the publish; `--no-guard "<reason>"`
+  // is the logged escape hatch (the override lands in .dz/guard-audit.jsonl — visible, never silent).
+  {
+    let guardRoot = cwd;
+    try { guardRoot = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8' }).trim() || cwd; } catch { /* not git */ }
+    const noGuard = options.get('no-guard');
+    if (noGuard !== undefined && noGuard.trim() === '') {
+      write('dz publish: --no-guard requires a reason (it is logged): --no-guard "hotfix, guard re-run after"');
+      return 1;
+    }
+    const guardResult = runGuardEvaluation(guardRoot, 'publish', undefined, noGuard);
+    if (guardResult.verdict === 'block' && noGuard === undefined) {
+      write('dz publish: ✗ BLOCKED by dz guard (HARD invariant violated):');
+      for (const v of guardResult.violations.filter((x) => x.severity === 'hard')) write(`  [BLOCK] ${v.rule}: ${v.detail}`);
+      write('  → fix the violation(s), or override with --no-guard "<reason>" (logged to .dz/guard-audit.jsonl).');
+      return 1;
+    }
+    if (guardResult.verdict === 'block') write(`dz publish: ⚠ guard BLOCK overridden via --no-guard: ${noGuard} (logged)`);
+    else if (guardResult.verdict === 'warn') for (const v of guardResult.violations) write(`dz publish: ⚠ guard warn — ${v.rule}: ${v.detail}`);
+    else write('dz publish: ✓ guard pre-flight passed');
+  }
+
   // ADR-001 (publish-provenance): decide BEFORE any work — flag validation, then a pre-flight that
   // refuses `--provenance` where no OIDC token can be minted. `off` is an escape hatch that names itself.
   if (flags.has('provenance') && flags.has('no-provenance')) {
@@ -4193,6 +4221,168 @@ function cmdDriftCheck(options: Map<string, string>, flags: Set<string>, cwd: st
   return driftExit || sigFatal;
 }
 
+const DEFAULT_STORE_CAP = 5000;
+
+/** Read the optional `.dz/guard.json` — `{ rules?: [...], storeCap?: number }`. Missing/broken ⇒ defaults. */
+function loadGuardConfig(root: string): { rules?: unknown[]; storeCap?: number } {
+  const p = join(root, '.dz', 'guard.json');
+  if (!existsSync(p)) return {};
+  try {
+    const j = JSON.parse(readFileSync(p, 'utf8'));
+    return j && typeof j === 'object' ? j : {};
+  } catch { return {}; }
+}
+
+/** Extract labelled (a,b) count pairs from the READMEs that must agree (the parity invariant, inline). */
+function gatherReadmeCounts(root: string): { label: string; a: number; b: number }[] {
+  const read = (rel: string): string => { try { return readFileSync(join(root, rel), 'utf8'); } catch { return ''; } };
+  const rootMd = read('README.md');
+  const cliMd = read('packages/@dzhechkov/harness-cli/README.md');
+  const num = (s: string, re: RegExp): number | null => { const m = s.match(re); return m && m[1] ? Number(m[1]) : null; };
+  const pairs: { label: string; a: number; b: number }[] = [];
+  const cjm = num(rootMd, /## User Journey — 6 phases, (\d+) commands/);
+  const cliAll = num(cliMd, /## All Commands \((\d+)\)/);
+  const rootAll = num(rootMd, /## All Commands \((\d+)\)/);
+  if (cjm !== null && cliAll !== null) pairs.push({ label: 'commands (root CJM header vs cli All Commands)', a: cjm, b: cliAll });
+  if (rootAll !== null && cliAll !== null) pairs.push({ label: 'All Commands (root vs cli)', a: rootAll, b: cliAll });
+  return pairs;
+}
+
+/** Gather the facts one op needs. All I/O is best-effort — a missing signal skips its rule, never crashes. */
+function gatherGuardFacts(op: string, root: string, text: string | undefined, storeCap: number): Record<string, unknown> {
+  const facts: Record<string, unknown> = { op };
+  if (op === 'publish') {
+    // Read every workspace manifest ONCE: build a name→version map, then resolve each `workspace:*` dep to the
+    // version pnpm WOULD publish it as. In a pnpm workspace (pnpm-workspace.yaml present) `workspace:*` in source
+    // is correct and gets rewritten at publish — so reporting it raw would be a FALSE gate. We mirror the rewrite:
+    // a resolvable workspace dep becomes its real semver (safe → the rule passes); an UNRESOLVABLE one (points at
+    // no workspace package, or not a pnpm workspace) stays `workspace:*` so the rule catches a dep that WOULD ship
+    // raw. That is the genuinely dangerous case the rule exists for.
+    const manifests: { name?: string; version?: string; private?: boolean; dependencies?: Record<string, string> }[] = [];
+    try {
+      const out = execSync('git ls-files "packages/@dzhechkov/*/package.json"', { cwd: root, encoding: 'utf-8' });
+      for (const rel of out.split('\n').map((s) => s.trim()).filter(Boolean)) {
+        try { manifests.push(JSON.parse(readFileSync(join(root, rel), 'utf8')) as typeof manifests[number]); } catch { /* skip unreadable */ }
+      }
+    } catch { /* not a git repo */ }
+    const versionByName = new Map<string, string>();
+    for (const m of manifests) if (m.name && typeof m.version === 'string') versionByName.set(m.name, m.version);
+    const pnpmWorkspace = existsSync(join(root, 'pnpm-workspace.yaml'));
+    const packages: { name: string; deps: Record<string, string> }[] = [];
+    for (const m of manifests) {
+      if (m.private === true) continue; // unpublished packages are exempt
+      const deps: Record<string, string> = {};
+      for (const [dep, spec] of Object.entries(m.dependencies ?? {})) {
+        deps[dep] = (typeof spec === 'string' && spec.startsWith('workspace:') && pnpmWorkspace && versionByName.has(dep))
+          ? versionByName.get(dep)! // pnpm rewrites this to a real semver at publish → safe
+          : spec; // non-pnpm, or an unresolvable workspace dep → keep raw so the rule catches a would-ship-raw dep
+      }
+      packages.push({ name: m.name ?? '(unnamed)', deps });
+    }
+    facts['packages'] = packages;
+    try { facts['drift'] = sweepSkillDrift(root, { scope: 'packages', allowlist: readDriftAllowlist(root) }).drifted.map((d) => d.name); } catch { /* skip */ }
+    facts['counts'] = gatherReadmeCounts(root);
+  }
+  if (op === 'consolidate') {
+    try { facts['drift'] = sweepSkillDrift(root, { scope: 'packages', allowlist: readDriftAllowlist(root) }).drifted.map((d) => d.name); } catch { /* skip */ }
+  }
+  if (op === 'teach' || op === 'consolidate') {
+    if (op === 'teach' && text) facts['secretTargets'] = [{ label: 'lesson', text }];
+    let count = 0;
+    try { count = loadStorePatternsSync(root).length; } catch { /* skip → cap never trips */ count = 0; }
+    facts['store'] = { count, cap: storeCap };
+  }
+  return facts;
+}
+
+/**
+ * Load config → resolve rules → gather facts → evaluate → append the audit record. The ONE evaluation path,
+ * shared by `dz guard check` and the `dz publish` pre-flight (ADR-002 option A) so they can never disagree.
+ * `overrideReason` (when the caller forces through a block) is logged, never silent.
+ */
+function runGuardEvaluation(root: string, op: string, text: string | undefined, overrideReason: string | undefined): ReturnType<typeof evaluateGuard> {
+  const cfg = loadGuardConfig(root);
+  // Number.isFinite, not just > 0: a config `storeCap: 1e400` parses to Infinity, passes `> 0`, and would
+  // silently DISABLE the cap (count <= Infinity always). Non-finite ⇒ fall back to the default.
+  const storeCap = typeof cfg.storeCap === 'number' && Number.isFinite(cfg.storeCap) && cfg.storeCap > 0 ? cfg.storeCap : DEFAULT_STORE_CAP;
+  const rules = resolveRules(Array.isArray(cfg.rules) ? (cfg.rules as never[]) : undefined);
+  const facts = gatherGuardFacts(op, root, text, storeCap);
+  const result = evaluateGuard(facts as never, rules);
+  // audit (append-only). ts is real time here (a CLI, not the sandboxed workflow).
+  try {
+    const rec = auditRecord(result, new Date().toISOString(), overrideReason !== undefined ? { reason: overrideReason } : undefined);
+    mkdirSync(join(root, '.dz'), { recursive: true });
+    writeFileSync(join(root, '.dz', 'guard-audit.jsonl'), JSON.stringify(rec) + '\n', { flag: 'a' });
+  } catch { /* audit is best-effort, never blocks the verdict */ }
+  return result;
+}
+
+/**
+ * `dz guard` — the declarative constraint layer that refuses a self-mutating op when a HARD invariant is
+ * violated. Simple outside: `dz guard check --op publish` works with zero config (built-in defaults).
+ *   check --op <publish|teach|consolidate|reindex> [--text <s>] [--json] [--force <reason>]
+ *   --init     scaffold an editable .dz/guard.json (only if you want to customise)
+ *   log [--limit N]   tail the append-only .dz/guard-audit.jsonl
+ * Exit 1 on a HARD block (0 with --force <reason>, which is logged); 0 on warn/pass.
+ */
+function cmdGuard(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  let root = cwd;
+  try { root = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8' }).trim() || cwd; } catch { /* not git */ }
+  const sub = options.get('_positional_0') ?? 'check';
+
+  if (flags.has('init') || sub === 'init') {
+    const p = join(root, '.dz', 'guard.json');
+    if (existsSync(p) && !flags.has('force')) { write(`dz guard --init: ${p} already exists (pass --force to overwrite)`); return 1; }
+    const scaffold = {
+      storeCap: DEFAULT_STORE_CAP,
+      rules: DEFAULT_RULES.map((r) => ({ id: r.id, severity: r.severity, enabled: true, description: r.description })),
+    };
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(scaffold, null, 2) + '\n');
+    write(`dz guard --init: wrote ${p} (edit severity/enabled to customise; delete it to return to built-in defaults)`);
+    return 0;
+  }
+
+  if (sub === 'log') {
+    const p = join(root, '.dz', 'guard-audit.jsonl');
+    if (!existsSync(p)) { write('dz guard log: no audit yet (.dz/guard-audit.jsonl)'); return 0; }
+    const limit = Math.max(1, Number(options.get('limit') ?? '20') || 20);
+    // parse-filter BEFORE emitting: a corrupt line must not make the --json output invalid JSON.
+    const rows = readFileSync(p, 'utf8').split('\n').filter(Boolean).slice(-limit)
+      .map((row) => { try { return JSON.parse(row) as { ts: string; op: string; verdict: string; override?: { reason: string } }; } catch { return null; } })
+      .filter((r): r is { ts: string; op: string; verdict: string; override?: { reason: string } } => r !== null);
+    if (flags.has('json')) { write(JSON.stringify(rows)); return 0; }
+    for (const r of rows) {
+      write(`${r.ts}  ${String(r.op).padEnd(11)} ${String(r.verdict).toUpperCase()}${r.override ? `  (forced: ${r.override.reason})` : ''}`);
+    }
+    return 0;
+  }
+
+  if (sub !== 'check') {
+    write(`dz guard: unknown subcommand '${sub}' — use: check --op <op> | --init | log`);
+    return 1;
+  }
+
+  // check
+  const op = options.get('op');
+  if (op === undefined || !['publish', 'teach', 'consolidate', 'reindex'].includes(op)) {
+    write('dz guard check: --op must be one of publish | teach | consolidate | reindex');
+    return 1;
+  }
+  const force = options.get('force');
+  const forced = force !== undefined;
+  const result = runGuardEvaluation(root, op, options.get('text'), force);
+
+  if (flags.has('json')) { write(JSON.stringify({ ...result, forced }, null, 2)); return guardExitCode(result, forced); }
+
+  const glyph = result.verdict === 'block' ? '✗' : result.verdict === 'warn' ? '⚠' : '✓';
+  write(`dz guard (${op}): ${glyph} ${result.verdict.toUpperCase()}  [checked: ${result.checked.join(', ') || 'no rules for this op'}]`);
+  for (const v of result.violations) write(`  [${v.severity === 'hard' ? 'BLOCK' : 'warn'}] ${v.rule}: ${v.detail}`);
+  if (result.verdict === 'block' && forced) write(`  → forced through: ${force} (logged to .dz/guard-audit.jsonl)`);
+  else if (result.verdict === 'block') write('  → blocked. Fix the HARD violation(s), or override with --force "<reason>" (logged).');
+  return guardExitCode(result, forced);
+}
+
 /**
  * `dz sync-canonical <skill>` — the healer. Treats the resolved canonical (`--from` →
  * `skills-meta/<skill>` → `--auto` most-complete copy) as authoritative and overwrites every other
@@ -5169,6 +5359,8 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdSign(options, flags, cwd, write);
       case 'sbom':
         return cmdSbom(options, flags, cwd, write);
+      case 'guard':
+        return cmdGuard(options, flags, cwd, write);
       case 'verify-pack':
         return cmdVerifyPack(options, flags, cwd, write);
       case 'setup':