@dzhechkov/harness-core 0.3.123 → 0.3.125

package/src/feature-adr-setup.ts

@@ -32,6 +32,11 @@ export interface SetupSpec {
   /** scaffold a starter `architecture/degradations.md` — the accepted-degradations registry the R6
    *  challenge panel (C1) reads so it does not re-flag debt you already own. Create-if-absent. */
   readonly degradations?: boolean;
+  /** P3 (fa-improvements): scaffold DETERMINISTIC guard tests into the project — a declarative
+   *  `guards.config.json` + a zero-dependency Node runner `check.mjs` (LOC cap, secret scan, frozen-file
+   *  sha256 pins, each with an explicit waiver mechanism). `true` for defaults, or `{ locCap }` to tune.
+   *  Moves rules a reviewer "might notice" down to layer 1 of the cost-of-detection ladder. Create-if-absent. */
+  readonly guards?: boolean | { readonly locCap?: number };
 }
 
 export interface SetupScan {
@@ -57,7 +62,7 @@ export interface ScaffoldResult { readonly files: readonly ScaffoldFile[] }
 /** One existing on-disk file: `exists` distinguishes ABSENT from EXISTS-BUT-UNREADABLE (never clobber either). */
 export interface ExistingFile { readonly exists: boolean; readonly content?: string }
 /** The existing files the scaffold compares against. */
-export interface ExistingScaffoldFiles { readonly vision: ExistingFile; readonly manifest: ExistingFile; readonly projectSkills: ExistingFile; readonly testing: ExistingFile; readonly degradations?: ExistingFile }
+export interface ExistingScaffoldFiles { readonly vision: ExistingFile; readonly manifest: ExistingFile; readonly projectSkills: ExistingFile; readonly testing: ExistingFile; readonly degradations?: ExistingFile; readonly guardsConfig?: ExistingFile; readonly guardsRunner?: ExistingFile }
 
 // Canonical committed paths (ADR: everything under architecture/).
 export const P_VISION = 'architecture/vision.md';
@@ -66,6 +71,8 @@ export const P_MANIFEST = 'architecture/subsystems.manifest.json';
 export const P_PROJECT_SKILLS = 'architecture/project-skills.json';
 export const P_CRITIC = 'architecture/project-critic/SKILL.md';
 export const P_DEGRADATIONS = 'architecture/degradations.md';
+export const P_GUARDS_CONFIG = 'architecture/guards/guards.config.json';
+export const P_GUARDS_RUNNER = 'architecture/guards/check.mjs';
 
 const byStr = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
 const uniqSorted = (xs: readonly string[]): string[] => [...new Set(xs)].sort(byStr);
@@ -235,6 +242,122 @@ function structuredFile(path: string, existing: ExistingFile, render: () => stri
  * are append-only merged (existing content, order, and unknown keys preserved). A file only gets `create`
  * when it is genuinely ABSENT. Malformed existing content never crashes and never clobbers.
  */
+/** Default LOC (lines of code) cap for the scaffolded guard — the classic god-object threshold. */
+export const DEFAULT_GUARD_LOC_CAP = 700;
+
+/** Render the declarative guard config. Data, not behavior — the owner edits caps/waivers here. */
+export function renderGuardsConfig(opts: { locCap?: number } = {}): string {
+  const cap = typeof opts.locCap === 'number' && Number.isFinite(opts.locCap) && opts.locCap > 0 ? Math.floor(opts.locCap) : DEFAULT_GUARD_LOC_CAP;
+  return JSON.stringify({
+    $doc: 'Deterministic project guards (fa-improvements P3). Enforced by architecture/guards/check.mjs — wire `node architecture/guards/check.mjs` into your test/CI command. Every waiver REQUIRES a reason: a conscious exception is recorded, not silently allowed. The project-critic role must NOT re-flag rules enforced here — only waivers without a reason.',
+    locCap: {
+      limit: cap,
+      include: ['src/**', 'lib/**', 'app/**', 'test/**', 'tests/**'],
+      extensions: ['.ts', '.tsx', '.js', '.mjs', '.cjs', '.py', '.go', '.rs', '.java'],
+      waivers: [{ path: 'example/generated-file.ts', reason: 'generated code — delete this sample waiver' }],
+    },
+    secretScan: {
+      include: ['src/**', 'lib/**', 'app/**', 'test/**', 'tests/**', 'docs/**'],
+      waivers: [],
+    },
+    frozenFiles: [] as { path: string; sha256: string; reason: string }[],
+  }, null, 2) + '\n';
+}
+
+/**
+ * Render the ZERO-DEPENDENCY guard runner (plain Node ≥18, no framework, no install): LOC cap + high-signal
+ * secret scan + frozen-file sha256 pins, waivers with required reasons, `--json`, exit 1 on violation.
+ * Deliberately a portable .mjs, not a vitest/pytest file — it runs in ANY stack's CI with just Node.
+ */
+export function renderGuardsRunner(): string {
+  return [
+    '#!/usr/bin/env node',
+    "// architecture/guards/check.mjs — deterministic project guards (generated by dz feature-adr-setup --guards).",
+    '// Zero dependencies: plain Node >=18. Wire into CI/test: `node architecture/guards/check.mjs` (exit 1 = violation).',
+    '// Rules and waivers live in guards.config.json — a waiver without a reason is itself a violation.',
+    "import { readFileSync, readdirSync, statSync } from 'node:fs';",
+    "import { join, extname, sep } from 'node:path';",
+    "import { createHash } from 'node:crypto';",
+    '',
+    "const ROOT = process.cwd();",
+    "const CFG = JSON.parse(readFileSync(join(ROOT, 'architecture/guards/guards.config.json'), 'utf8'));",
+    "const JSON_MODE = process.argv.includes('--json');",
+    'const violations = [];',
+    '',
+    "const SECRETS = [",
+    "  { name: 'private-key-pem', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP |ENCRYPTED )?PRIVATE KEY-----/ },",
+    "  { name: 'openai-key', re: /\\bsk-[A-Za-z0-9_-]{20,}\\b/ },",
+    "  { name: 'stripe-key', re: /\\bsk_(?:live|test)_[A-Za-z0-9]{16,}\\b/ },",
+    "  { name: 'github-token', re: /\\bgh[pousr]_[A-Za-z0-9]{36,}\\b/ },",
+    "  { name: 'aws-access-key', re: /\\bAKIA[0-9A-Z]{16}\\b/ },",
+    "  { name: 'slack-token', re: /\\bxox[baprs]-[A-Za-z0-9-]{10,}\\b/ },",
+    "  { name: 'google-api-key', re: /\\bAIza[0-9A-Za-z_-]{35}\\b/ },",
+    '];',
+    "const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'target', 'coverage', '.next', 'vendor', '__pycache__']);",
+    '',
+    '// include patterns are simple dir prefixes (the part before /**). Deterministic, no glob dependency.',
+    "const prefixes = (pats) => (pats || []).map((p) => String(p).split('/**')[0]).filter(Boolean);",
+    'function walk(dir, out) {',
+    '  let entries = [];',
+    '  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }',
+    '  for (const e of entries) {',
+    '    if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) walk(join(dir, e.name), out); }',
+    '    else if (e.isFile()) out.push(join(dir, e.name));',
+    '  }',
+    '  return out;',
+    '}',
+    "const rel = (p) => p.slice(ROOT.length + 1).split(sep).join('/');",
+    'function filesUnder(pats) {',
+    '  const out = [];',
+    '  for (const pre of prefixes(pats)) walk(join(ROOT, pre), out);',
+    '  return out;',
+    '}',
+    'function waiverFor(list, relPath) {',
+    "  for (const w of list || []) { if (w && w.path === relPath) return w; }",
+    '  return null;',
+    '}',
+    'function applyWaiver(rule, relPath, list, detail) {',
+    '  const w = waiverFor(list, relPath);',
+    "  if (!w) { violations.push({ rule, path: relPath, detail }); return; }",
+    "  if (!w.reason || !String(w.reason).trim()) violations.push({ rule: rule + '-waiver', path: relPath, detail: 'waived WITHOUT a reason — a silent exception is a violation' });",
+    '}',
+    '',
+    '// 1) LOC cap (the god-object guard: deterministic wc -l, not reviewer judgment)',
+    'if (CFG.locCap && CFG.locCap.limit > 0) {',
+    '  const exts = new Set(CFG.locCap.extensions || []);',
+    '  for (const f of filesUnder(CFG.locCap.include)) {',
+    '    if (exts.size && !exts.has(extname(f))) continue;',
+    "    let n = 0; try { n = readFileSync(f, 'utf8').split('\\n').length; } catch { continue; }",
+    '    if (n > CFG.locCap.limit) applyWaiver(\'loc-cap\', rel(f), CFG.locCap.waivers, n + \' lines > cap \' + CFG.locCap.limit);',
+    '  }',
+    '}',
+    '',
+    '// 2) secret scan (high-signal shapes only — ordinary prose and hashes do not trip it)',
+    'if (CFG.secretScan) {',
+    '  for (const f of filesUnder(CFG.secretScan.include)) {',
+    "    let text = ''; try { text = readFileSync(f, 'utf8'); } catch { continue; }",
+    '    for (const s of SECRETS) { if (s.re.test(text)) applyWaiver(\'secret-scan\', rel(f), CFG.secretScan.waivers, \'looks like a \' + s.name); }',
+    '  }',
+    '}',
+    '',
+    '// 3) frozen-file sha256 pins (tamper/drift evidence for files that must not change silently)',
+    'for (const fz of CFG.frozenFiles || []) {',
+    '  if (!fz || !fz.path || !fz.sha256) continue;',
+    '  let actual = null;',
+    "  try { actual = createHash('sha256').update(readFileSync(join(ROOT, fz.path))).digest('hex'); } catch { /* missing counts as changed */ }",
+    "  if (actual !== fz.sha256) violations.push({ rule: 'frozen-file', path: fz.path, detail: actual ? 'sha256 changed (pinned ' + fz.sha256.slice(0, 12) + '…, actual ' + actual.slice(0, 12) + '…)' : 'file missing/unreadable' });",
+    '}',
+    '',
+    'if (JSON_MODE) { console.log(JSON.stringify({ ok: violations.length === 0, violations })); }',
+    'else {',
+    "  if (violations.length === 0) console.log('guards: ✓ all deterministic guards pass');",
+    "  else { console.log('guards: ✗ ' + violations.length + ' violation(s)'); for (const v of violations) console.log('  [' + v.rule + '] ' + v.path + ' — ' + v.detail); }",
+    '}',
+    'process.exit(violations.length === 0 ? 0 : 1);',
+    '',
+  ].join('\n');
+}
+
 export function scaffoldFromSpec(spec: SetupSpec, existing: ExistingScaffoldFiles): ScaffoldResult {
   const files: ScaffoldFile[] = [];
   if (spec.vision) files.push(proseFile(P_VISION, existing.vision, () => renderVisionDoc(spec.vision!)));
@@ -246,6 +369,13 @@ export function scaffoldFromSpec(spec: SetupSpec, existing: ExistingScaffoldFile
   const nextPS = buildProjectSkillsFromSpec(spec);
   files.push(structuredFile(P_PROJECT_SKILLS, existing.projectSkills, () => JSON.stringify(nextPS, null, 2) + '\n', (parsed) => mergeProjectSkills(parsed, (nextPS.roles ?? {}) as Record<string, string>, nextPS.extra ?? [])));
   if (spec.degradations) files.push(proseFile(P_DEGRADATIONS, existing.degradations ?? { exists: false }, renderDegradationsDoc));
+  if (spec.guards) {
+    const gOpts = typeof spec.guards === 'object' ? spec.guards : {};
+    // Both create-if-absent: the config is the owner's to edit after scaffolding; the runner is regenerable
+    // but never clobbered (a project may have patched it — treat like any owned file).
+    files.push(proseFile(P_GUARDS_CONFIG, existing.guardsConfig ?? { exists: false }, () => renderGuardsConfig(gOpts)));
+    files.push(proseFile(P_GUARDS_RUNNER, existing.guardsRunner ?? { exists: false }, renderGuardsRunner));
+  }
   return { files: [...files].sort((a, b) => byStr(a.path, b.path)) };
 }
 
@@ -292,5 +422,7 @@ export function readExistingForScaffold(repoRoot: string): ExistingScaffoldFiles
     projectSkills: readExistingFile(join(repoRoot, P_PROJECT_SKILLS)),
     testing: readExistingFile(join(repoRoot, P_TESTING)),
     degradations: readExistingFile(join(repoRoot, P_DEGRADATIONS)),
+    guardsConfig: readExistingFile(join(repoRoot, P_GUARDS_CONFIG)),
+    guardsRunner: readExistingFile(join(repoRoot, P_GUARDS_RUNNER)),
   };
 }

package/src/sign.ts

@@ -118,10 +118,18 @@ export function listPackFiles(root: string): string[] {
   const out: string[] = [];
   const walk = (dir: string, rel: string): void => {
     for (const e of readdirSync(dir, { withFileTypes: true })) {
+      // node_modules/.git are unsigned territory BY DESIGN (installed deps / VCS metadata — not pack
+      // content; npm tarballs ship neither). The SIGN and VERIFY walks MUST share these exclusions:
+      // an asymmetry here false-TAMPERs every pnpm workspace pack whose node_modules holds symlinks
+      // (found live arming task #36 — 10 of 23 skill packs flagged right after signing).
+      if (e.name === 'node_modules' || e.name === '.git') continue;
       if (e.name === MANIFEST_NAME || e.name === SBOM_NAME) continue;
       const abs = join(dir, e.name);
       const r = rel ? rel + '/' + e.name : e.name;
       if (e.isDirectory()) walk(abs, r);
+      // NOT else-isFile: a symlink (or other non-file) OUTSIDE the excluded dirs must stay VISIBLE to the
+      // verify sweep — it fails as "present but not signed" / "is a symlink" (R3-4: a smuggled symlink is a
+      // finding, not something to silently ignore). Only node_modules/.git are exempt territory.
       else out.push(r);
     }
   };
@@ -129,6 +137,27 @@ export function listPackFiles(root: string): string[] {
   return out.sort();
 }
 
+/**
+ * The SIGN-side file list: same exclusions as {@link listPackFiles}, but REGULAR FILES ONLY — `dz sign`
+ * never signs a symlink (hashing one would follow it outside the pack). The verify sweep intentionally
+ * sees MORE than this (symlinks/specials outside node_modules), so a smuggled entry fails verification.
+ */
+export function listSignablePackFiles(root: string): string[] {
+  const out: string[] = [];
+  const walk = (dir: string, rel: string): void => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.name === 'node_modules' || e.name === '.git') continue;
+      if (e.name === MANIFEST_NAME || e.name === SBOM_NAME) continue;
+      const abs = join(dir, e.name);
+      const r = rel ? rel + '/' + e.name : e.name;
+      if (e.isDirectory()) walk(abs, r);
+      else if (e.isFile()) out.push(r);
+    }
+  };
+  walk(root, '');
+  return out.sort();
+}
+
 /**
  * The bytes that get signed (FR-7). Sorted by path, LF endings, no trailing whitespace, and no
  * dependence on JSON key order — a signature must not depend on how a serialiser felt that day.