@dzhechkov/harness-cli 0.3.227 → 0.3.228

package/README.md

@@ -289,6 +289,10 @@ Ed25519 over a file manifest, plus a CycloneDX SBOM. Zero dependencies (`node:cr
 tamper-evidence, never truthfulness.
 
 ```bash
+# One-time: generate the Ed25519 keypair. The PRIVATE key is written OUTSIDE the repo (mode 0600);
+# the PUBLIC key is printed — commit it as keys/dz.pub. dz refuses an --out inside the repo tree.
+dz sign --init --out ~/.dz/keys/dz.key
+
 # Sign a pack. The private key MUST live outside the repo — dz refuses otherwise.
 dz sign --pack packages/@dzhechkov/skills-qe --key ~/.dz/keys/dz.key
 
@@ -296,11 +300,17 @@ dz sign --pack packages/@dzhechkov/skills-qe --key ~/.dz/keys/dz.key
 # whoever replaced the pack would have replaced a key shipped inside it.
 dz verify-pack --pack packages/@dzhechkov/skills-qe          # exit 0 = unmodified
 dz verify-pack --pack ./downloaded-pack --pubkey keys/dz.pub # explicit trust root
+
+# The SBOM on its own (CycloneDX 1.5, a file-level bill of materials for the pack):
+dz sbom --pack packages/@dzhechkov/skills-qe                 # print to stdout
+dz sbom --pack packages/@dzhechkov/skills-qe --out sbom.json # write to a file
 ```
 
 A single flipped byte, a deleted file, or an **added** file all fail verification and the offending
 path is named. Every degenerate input (no manifest, empty file list, empty signature, no public key)
-fails **closed** — absence never reads as success.
+fails **closed** — absence never reads as success. `dz doctor` **and** `dz drift-check` run this check
+over the installed packs: a **tampered** pack is fatal (blocks); an **unsigned** pack or a missing trust
+root is reported, not fatal (transitional — the existing packs are not yet signed).
 
 `dz publish` runs the check before publishing anything. With `keys/dz.pub` committed, an unsigned or
 mismatching pack **blocks the release**. Until then, packs publish unsigned and `dz publish` says so on
@@ -433,7 +443,7 @@ Get the whole set with `dz init --target claude-code --preset meta`, or pick one
 
 > **A skill and its npx toolkit are not duplicates — they're a graduation.** Several skills (e.g. `feature-adr`, `design-thinking`) exist BOTH as a skill inside a `dz` preset AND as a standalone `npx` package. The preset's SKILL.md is **fully functional on its own** (the whole methodology — modules + references — travels with it, and it auto-activates by description), and it's the only way to compile that capability to the **non-Claude platforms** (Codex/OpenCode/Hermes/OpenClaude) via `dz`. The npx package adds **project-level runtime governance** around the same skill: a slash command, governance rules, a context shard, and (for feature-adr) reward-learning + `/harvest`. So: pick the **skill/preset** for a working capability across platforms; pick the **npx toolkit** when you want it as a governed, command-driven fixture of one project.
 
-## All Commands (52)
+## All Commands (53)
 
 ```
 dz setup             --target <name> [--preset <name>] [--select id,id,...] [--skills-dir <dir>] [--memory agentdb] [--no-memory] [--no-hooks] [--install-driver] [--force]
@@ -488,6 +498,8 @@ dz challenge --plan <plan.md> [--json] [--context-only] [--author <model>]   # a
 dz routing [--stage <s>] [--json]   # inspect the learned cost-optimal routing store: what `args.models.<stage>='auto-cost'` believes per (stage, complexity-tier, model) — gated attempts/successes/rate (feeds feature-adr model selection)
 dz bto-optimize --split|--plan|--select|--scope-check|--diff [--json]   # deterministic engine behind /bto-optimize: hold-out split + hard-capped budget + no-regress-on-holdout winner selection (defeats judge-gaming); prose-only, diff-confirmed, never auto-writes
 dz discrimination-check --test <f[,f]> [--base <ref>] [--name <filter>] [--runner <cmd>] [--json]   # §42 test-discrimination gate for feature-adr Step-8: run the ADR's property test in an isolated git worktree at pre-feature base — it MUST go red without the fix; a green is a false green (HIGH finding, advisory, never auto-aborts)
+dz sign --init --out <path>  |  --pack <dir> --key <path>   # --init: generate the Ed25519 keypair (private OUTSIDE the repo, prints the public key for keys/dz.pub); else sign a pack's manifest + CycloneDX SBOM
+dz sbom --pack <dir> [--out <file>]   # emit the CycloneDX 1.5 SBOM for a pack standalone (file-level bill of materials); print to stdout or write to a file
 dz publish           [--filter <name>] [--bump-only] [--claim-check <off|warn|error>]   (dry-run by default; pass --yes/--confirm to go live; claim-check gate defaults to warn — surfaces README claim findings, never blocks)
 dz auto-canonicalize --source <github-url> --pack <skills-pack>
 dz sync-upstream     [--package <dir>] [--list] [--all]

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2OH,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AA+oJD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwI5E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA4OH,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAovJD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA0I5E"}

package/dist/cli.js

@@ -3,13 +3,13 @@
  *
  * @packageDocumentation
  */
-import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
 import { homedir, tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
-import { createSkill, getSkillInfo, getWorkflow, isTargetName, listSkills, runDoctor, runInit, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, WORKFLOW_NAMES, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, decideProvenance, isInsideTree, signManifest, verifyManifest, assertKeyOutsideTree, decidePublishGate, MANIFEST_NAME, SBOM_NAME, buildArchitectureMap, renderMapHuman, findArchitectureDrift, renderDriftReport, scanWorkspacePackages, loadSubsystemManifest, loadProductVision, checkFeatureAgainstArchitecture, renderArchCheck, planProjectSkills, guidanceForStage, renderInjectionReport, analyzeCorpus, renderRakeReport, renderCriticSection, rakeAsLesson, rakeReward, DEFAULT_RAKE_THRESHOLDS, streamSessionEvents, findLatestTranscript, detectProcessRakes, buildRetro, renderRetro, retroLessonText, PROCESS_SIGNATURES, RETRO_DOMAIN, scanForSetup, buildSetupPlan, scaffoldFromSpec, renderScaffoldPreview, readExistingForScaffold, assembleChallengeContext, buildChallengeBrief, planDiscriminationCheck, classifyDiscrimination, pickAdversaryModel, CHALLENGE_QUESTIONS, loadOutcomes, renderOutcomes, statsForKey, selectAutoCost, recordProvisional, finalizeOutcome, COST_LADDER, splitScenarios, budgetPlan, selectWinner, proseScopeOk, renderProseDiff, readScenarioIds, DEFAULT_MAX_JUDGE_RUNS, } from '@dzhechkov/harness-core';
+import { createSkill, getSkillInfo, getWorkflow, isTargetName, listSkills, runDoctor, runInit, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, WORKFLOW_NAMES, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, decideProvenance, isInsideTree, signManifest, verifyManifest, assertKeyOutsideTree, decidePublishGate, MANIFEST_NAME, SBOM_NAME, buildArchitectureMap, renderMapHuman, findArchitectureDrift, renderDriftReport, scanWorkspacePackages, loadSubsystemManifest, loadProductVision, checkFeatureAgainstArchitecture, renderArchCheck, planProjectSkills, guidanceForStage, renderInjectionReport, analyzeCorpus, renderRakeReport, renderCriticSection, rakeAsLesson, rakeReward, DEFAULT_RAKE_THRESHOLDS, streamSessionEvents, findLatestTranscript, detectProcessRakes, buildRetro, renderRetro, retroLessonText, PROCESS_SIGNATURES, RETRO_DOMAIN, scanForSetup, buildSetupPlan, scaffoldFromSpec, renderScaffoldPreview, readExistingForScaffold, assembleChallengeContext, buildChallengeBrief, planDiscriminationCheck, classifyDiscrimination, pickAdversaryModel, CHALLENGE_QUESTIONS, loadOutcomes, renderOutcomes, statsForKey, selectAutoCost, recordProvisional, finalizeOutcome, COST_LADDER, splitScenarios, budgetPlan, selectWinner, proseScopeOk, renderProseDiff, readScenarioIds, DEFAULT_MAX_JUDGE_RUNS, } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
 const USAGE = `dz - DZ cross-platform harness CLI
@@ -2912,10 +2912,86 @@ function reportPackVerification(cwd, explicitPubkey, requireSigning, write) {
     return fatal > 0 ? 1 : 0;
 }
 function cmdSign(options, flags, cwd, write) {
+    // `dz sign --init` — one-time keygen. Writes the PRIVATE key OUTSIDE the repo (default ~/.dz/keys/dz.key,
+    // mode 0600) and prints the PUBLIC key for the operator to commit as keys/dz.pub. The private key never
+    // touches the repo or a tarball (the hard invariant — enforced by assertKeyOutsideTree).
+    if (flags.has('init')) {
+        const outPath = resolve(cwd, options.get('out') ?? join(homedir(), '.dz', 'keys', 'dz.key'));
+        // Resolve symlinks BEFORE the containment check: an --out (or a parent dir) that is a symlink pointing
+        // INTO the repo would otherwise slip the private key inside the tree past a string-only guard — including a
+        // DANGLING symlink whose target does not exist yet (existsSync follows the link and reports false, so the
+        // symlink itself must be resolved via lstat/readlink, not existsSync).
+        const realTarget = (() => {
+            // walk up to the deepest path that exists as ANY entry (file, dir, or even a dangling symlink).
+            let anc = outPath;
+            const tail = [];
+            for (;;) {
+                try {
+                    lstatSync(anc);
+                    break;
+                }
+                catch { /* not present */ }
+                const parent = dirname(anc);
+                if (parent === anc)
+                    return outPath; // reached root without an existing entry
+                tail.unshift(basename(anc));
+                anc = parent;
+            }
+            let base;
+            try {
+                base = realpathSync(anc); // resolves dirs/files and any RESOLVABLE symlink chain
+            }
+            catch {
+                // `anc` exists but realpath threw → a dangling symlink: resolve its immediate target by hand.
+                try {
+                    base = resolve(dirname(anc), readlinkSync(anc));
+                }
+                catch {
+                    return outPath;
+                }
+            }
+            return tail.length ? join(base, ...tail) : base;
+        })();
+        try {
+            assertKeyOutsideTree(realTarget, cwd);
+        }
+        catch (err) {
+            write(`dz sign --init: ${err.message}`);
+            write('  choose an --out path (and parent) OUTSIDE the repository (e.g. ~/.dz/keys/dz.key)');
+            return 1;
+        }
+        if (existsSync(outPath) && !flags.has('force')) {
+            write(`dz sign --init: ${outPath} already exists — refusing to overwrite (pass --force to replace)`);
+            write('  overwriting a signing key orphans every pack signed with the old one.');
+            return 1;
+        }
+        const { privateKey, publicKey } = generateSigningKeypair();
+        try {
+            mkdirSync(dirname(outPath), { recursive: true });
+            // Unlink an existing file first: writeFileSync's `mode` is ignored when the file already exists, so a
+            // pre-existing 0644 key would stay world-readable after --force. Removing it forces a fresh 0600 create.
+            if (existsSync(outPath))
+                rmSync(outPath, { force: true });
+            writeFileSync(outPath, privateKey, { mode: 0o600 });
+            chmodSync(outPath, 0o600); // belt-and-suspenders: guarantee 0600 regardless of umask/prior state
+        }
+        catch (err) {
+            write(`dz sign --init: could not write the private key to ${outPath}: ${err.message}`);
+            return 1;
+        }
+        write(`dz sign --init: Ed25519 keypair generated.`);
+        write(`  private key → ${outPath} (mode 0600, OUTSIDE the repo — never commit it)`);
+        write(`  public key  → commit the block below as ${TRUST_ROOT_REL}:`);
+        write('');
+        write(publicKey.trimEnd());
+        write('');
+        write(`  then: dz sign --pack <dir> --key ${outPath}   (sign a pack)`);
+        return 0;
+    }
     const pack = options.get('pack');
     const key = options.get('key');
     if (!pack || !key) {
-        write('dz sign: --pack <dir> and --key <path> are both required');
+        write('dz sign: --pack <dir> and --key <path> are both required (or: dz sign --init to generate a keypair)');
         write('  the key path MUST be outside the repository working tree (a leaked signing key is not revertible)');
         return 1;
     }
@@ -2984,6 +3060,49 @@ function cmdVerifyPack(options, flags, cwd, write) {
         write(`  ${f.path}: ${f.reason}`);
     return 1;
 }
+/**
+ * `dz sbom` — emit a CycloneDX 1.5 SBOM (Software Bill of Materials) for a pack, standalone (no signing).
+ * The same inventory `dz sign` writes as `sbom.json`, available on its own for audit/procurement. Components
+ * are the pack's shipped files with their SHA-256 — a file-level bill of materials for the pack.
+ *   --pack <dir>   the pack to inventory (required)
+ *   --out <file>   write here (default: print to stdout)
+ *   --json         (implied) SPDX/CycloneDX is already JSON
+ */
+function cmdSbom(options, flags, cwd, write) {
+    const pack = options.get('pack');
+    if (!pack) {
+        write('dz sbom: --pack <dir> is required');
+        return 1;
+    }
+    const packDir = resolve(cwd, pack);
+    if (!existsSync(packDir)) {
+        write(`dz sbom: no such pack: ${packDir}`);
+        return 1;
+    }
+    const files = packFiles(packDir);
+    if (files.length === 0) {
+        write('dz sbom: the pack contains no files');
+        return 1;
+    }
+    const manifest = buildManifest(packDir, basename(packDir), files);
+    const sbom = buildSbom(manifest);
+    const out = JSON.stringify(sbom, null, 2);
+    const outOpt = options.get('out');
+    if (outOpt !== undefined) {
+        const outPath = resolve(cwd, outOpt);
+        try {
+            writeFileSync(outPath, out + '\n');
+        }
+        catch (err) {
+            write(`dz sbom: could not write ${outPath}: ${err.message}`);
+            return 1;
+        }
+        write(`dz sbom: ${sbom.components.length} component(s) → ${outPath} (CycloneDX ${sbom.specVersion})`);
+        return 0;
+    }
+    write(out);
+    return 0;
+}
 function cmdPublish(options, flags, cwd, write) {
     // Reject unknown flags/options so a typo (e.g. `--dry-rum`) can NEVER be
     // silently swallowed and flip the command into live-publish mode.
@@ -3739,29 +3858,37 @@ function cmdDriftCheck(options, flags, cwd, write) {
         write(`allowlisted (accepted drift): ${r.allowlisted.map((d) => d.name).join(', ')}`);
     }
     write(`DRIFTED (unexpected, byte-differences between copies): ${r.drifted.length}`);
+    let driftExit = 0;
     if (r.drifted.length === 0) {
         write('✓ no unexpected intra-monorepo skill drift');
-        return 0;
-    }
-    write('');
-    write('skill'.padEnd(34) + 'copies  drift/total');
-    for (const d of r.drifted) {
-        write(d.name.padEnd(34) +
-            String(d.copies).padStart(4) +
-            '    ' +
-            `${d.driftFiles}/${d.totalFiles}` +
-            (d.missingFiles ? ` (+${d.missingFiles} missing)` : ''));
     }
+    else {
+        write('');
+        write('skill'.padEnd(34) + 'copies  drift/total');
+        for (const d of r.drifted) {
+            write(d.name.padEnd(34) +
+                String(d.copies).padStart(4) +
+                '    ' +
+                `${d.driftFiles}/${d.totalFiles}` +
+                (d.missingFiles ? ` (+${d.missingFiles} missing)` : ''));
+        }
+        write('');
+        write('→ fix each: heal drift, then commit. Remediation per skill:');
+        for (const d of r.drifted) {
+            const hasMeta = existsSync(join(root, 'packages', '@dzhechkov', 'skills-meta', d.name));
+            write(hasMeta
+                ? `    dz sync-canonical ${d.name}`
+                : `    dz sync-canonical ${d.name} --from <a-known-good-copy>   (no skills-meta canonical)`);
+        }
+        write('  (accept a drift intentionally: add its name to .dz/drift-allowlist.json with a reason)');
+        driftExit = 1; // EXIT CODE 1 = the CI gate trips
+    }
+    // Supplementary CI check: installed-pack signatures. A TAMPERED pack trips the gate (fatal); an unsigned
+    // pack or a missing trust root is reported, not fatal — the same warn/block posture as `dz doctor` (the
+    // primary signature gate). drift-check surfaces it so the CI drift view also flags a tampered pack.
     write('');
-    write('→ fix each: heal drift, then commit. Remediation per skill:');
-    for (const d of r.drifted) {
-        const hasMeta = existsSync(join(root, 'packages', '@dzhechkov', 'skills-meta', d.name));
-        write(hasMeta
-            ? `    dz sync-canonical ${d.name}`
-            : `    dz sync-canonical ${d.name} --from <a-known-good-copy>   (no skills-meta canonical)`);
-    }
-    write('  (accept a drift intentionally: add its name to .dz/drift-allowlist.json with a reason)');
-    return 1; // EXIT CODE 1 = the CI gate trips
+    const sigFatal = reportPackVerification(root, options.get('pubkey'), flags.has('require-signing'), write);
+    return driftExit || sigFatal;
 }
 /**
  * `dz sync-canonical <skill>` — the healer. Treats the resolved canonical (`--from` →
@@ -4784,6 +4911,8 @@ export async function runCli(argv, io = {}) {
                 return cmdClaimCheck(options, optionLists, flags, cwd, write);
             case 'sign':
                 return cmdSign(options, flags, cwd, write);
+            case 'sbom':
+                return cmdSbom(options, flags, cwd, write);
             case 'verify-pack':
                 return cmdVerifyPack(options, flags, cwd, write);
             case 'setup':