npm - @davesheffer/hunch - Versions diffs - 1.20.3 → 1.21.1 - Mend

@davesheffer/hunch 1.20.3 → 1.21.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md +3 -3
package/dist/cli/dna.js +116 -0
package/dist/cli/index.js +112 -1
package/dist/cli/invocation.js +16 -3
package/dist/core/projectDna.js +478 -0
package/dist/core/projectDnaDelivery.js +54 -0
package/dist/core/projectDnaDelta.js +159 -0
package/dist/integrations/scaffold.js +18 -7
package/dist/mcp/server.js +161 -8
package/dist/projectDna.js +10 -0
package/package.json +9 -1
package/server.json +2 -2

package/README.md CHANGED Viewed

@@ -174,7 +174,7 @@ repository, separate from the code repository. Hunch does not host it. Create a
 that every teammate can access, install Hunch on team machines and CI, then have one maintainer run:
 ```bash
-npm i -g @davesheffer/hunch@1.20.3
+npm i -g @davesheffer/hunch@1.21.1
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -189,7 +189,7 @@ printed by Hunch. Omit `--migrate` for a new setup.
 After the pointer commit lands, teammates need Hunch installed and Git access to the memory repo:
 ```bash
-npm i -g @davesheffer/hunch@1.20.3
+npm i -g @davesheffer/hunch@1.21.1
 git pull
 hunch init
 hunch doctor
@@ -237,7 +237,7 @@ but stops automatic memory commits and pushes. As a team-coordinated rollback, r
 commit to stop discovery after teammates pull the revert. Existing machines retain their ignored
 local overlay until they are deliberately disconnected; do not delete the memory repo as part of a
 rollback. For this rollout, reinstall the previous published package with
-`npm i -g @davesheffer/hunch@1.20.2`; the release receipt resolves and records the verified rollback
+`npm i -g @davesheffer/hunch@1.20.3`; the release receipt resolves and records the verified rollback
 target from the npm registry instead of trusting Git tags. Pause enforcement first as shown above,
 and keep every team client on the same release before resuming Matrix policy workflows.

package/dist/cli/dna.js ADDED Viewed

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { Command } from "commander";
+import { discoverProjectDna, evaluateProjectDnaMatch } from "../core/projectDna.js";
+import { diffProjectDna } from "../core/projectDnaDelta.js";
+import { projectDnaDeliverySupplement } from "../core/projectDnaDelivery.js";
+function gitRoot() {
+    try {
+        return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 5_000,
+        }).trim();
+    }
+    catch {
+        throw new Error("Project DNA must run inside a Git repository");
+    }
+}
+function printProfile(root, revision, json) {
+    const profile = discoverProjectDna(root, revision);
+    if (json) {
+        process.stdout.write(`${JSON.stringify(profile, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`Project DNA ${profile.profile_id}\n`);
+    process.stdout.write(`revision: ${profile.repository_revision}\n`);
+    process.stdout.write(`history sample: ${profile.history_sample_count}\n`);
+    process.stdout.write(`committed convention files: ${profile.source_files.length ? profile.source_files.join(", ") : "none"}\n`);
+    if (!profile.traits.length) {
+        process.stdout.write("traits: none yet (insufficient evidence)\n");
+        return;
+    }
+    for (const trait of profile.traits) {
+        process.stdout.write(`- [${trait.category}] ${trait.claim} (${trait.confidence.toFixed(2)}; ${trait.id})\n`);
+    }
+}
+const program = new Command();
+program
+    .name("hunch-dna")
+    .description("Derive and inspect Hunch Project DNA from exact committed repository evidence.")
+    .option("--revision <ref>", "Git revision to inspect", "HEAD")
+    .option("--json", "emit the sealed machine-readable profile")
+    .action((options) => {
+    printProfile(gitRoot(), options.revision, !!options.json);
+});
+program
+    .command("match")
+    .description("Score a commit/PR/issue/message against deterministic applicable DNA traits.")
+    .requiredOption("--kind <kind>", "commit | pull_request | issue | message")
+    .requiredOption("--title <title>", "artifact title/subject")
+    .option("--body <body>", "artifact body")
+    .option("--revision <ref>", "Git revision whose DNA applies", "HEAD")
+    .option("--json", "emit the sealed match contract")
+    .action((options) => {
+    if (!(new Set(["commit", "pull_request", "issue", "message"])).has(options.kind)) {
+        throw new Error("--kind must be commit, pull_request, issue, or message");
+    }
+    const artifact = {
+        kind: options.kind,
+        title: options.title,
+        ...(options.body !== undefined ? { body: options.body } : {}),
+    };
+    const globals = program.opts();
+    const revision = options.revision ?? globals.revision ?? "HEAD";
+    const json = options.json ?? globals.json ?? false;
+    const profile = discoverProjectDna(gitRoot(), revision);
+    const match = evaluateProjectDnaMatch(profile, artifact);
+    if (json)
+        process.stdout.write(`${JSON.stringify(match, null, 2)}\n`);
+    else {
+        process.stdout.write(`Project DNA match: ${match.score === null ? "n/a" : `${match.score}%`} (${match.applicable_checks} applicable checks)\n`);
+        for (const check of match.checks.filter((item) => item.applicable)) {
+            process.stdout.write(`- ${check.passed ? "PASS" : "FAIL"} ${check.key}: ${check.detail}\n`);
+        }
+    }
+});
+program
+    .command("context")
+    .description("Render the bounded advisory DNA supplement intended for Hunch delivery/context assembly.")
+    .option("--revision <ref>", "Git revision to inspect", "HEAD")
+    .option("--traits <count>", "maximum DNA traits in the orientation slice", "8")
+    .option("--json", "emit supplement JSON")
+    .action((options) => {
+    const globals = program.opts();
+    const revision = options.revision ?? globals.revision ?? "HEAD";
+    const json = options.json ?? globals.json ?? false;
+    const cap = Number(options.traits);
+    const supplement = projectDnaDeliverySupplement(discoverProjectDna(gitRoot(), revision), cap);
+    if (json)
+        process.stdout.write(`${JSON.stringify(supplement, null, 2)}\n`);
+    else
+        process.stdout.write(`${supplement?.text ?? "No evidence-backed Project DNA traits yet."}\n`);
+});
+program
+    .command("diff")
+    .description("Compare DNA at two exact revisions; reports observation drift without inferring causality.")
+    .argument("<from>", "older Git revision")
+    .argument("<to>", "newer Git revision")
+    .option("--json", "emit the sealed delta contract")
+    .action((from, to, options) => {
+    const root = gitRoot();
+    const delta = diffProjectDna(discoverProjectDna(root, from), discoverProjectDna(root, to));
+    const json = options.json ?? program.opts().json ?? false;
+    if (json)
+        process.stdout.write(`${JSON.stringify(delta, null, 2)}\n`);
+    else {
+        process.stdout.write(`Project DNA drift ${delta.delta_id}: ${delta.changed ? `${delta.changes.length} change(s)` : "no observed change"}\n`);
+        for (const change of delta.changes)
+            process.stdout.write(`- ${change.kind}: ${change.key}\n`);
+    }
+});
+program.parseAsync().catch((error) => {
+    process.stderr.write(`hunch-dna: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=dna.js.map

package/dist/cli/index.js CHANGED Viewed

@@ -57,6 +57,9 @@ import { compileVerifiedEvidenceMap, formatVerifiedEvidenceMap } from "../core/e
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
 import { buildDeliveryEnvelope, DELIVERY_PROFILES } from "../core/delivery.js";
 import { deriveChangeIdentity } from "../core/changeIdentity.js";
+import { discoverProjectDna, evaluateProjectDnaMatch } from "../core/projectDna.js";
+import { diffProjectDna } from "../core/projectDnaDelta.js";
+import { projectDnaDeliverySupplement } from "../core/projectDnaDelivery.js";
 import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
 import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpolicy.js";
 import { isHumanConfirmed } from "../core/strictgate.js";
@@ -306,7 +309,7 @@ program
     // Claude's native hooks run alongside provider-specific hooks below. Every
     // adapter reads firmness at run time, so changing it needs no config rewrite.
     if (opts.agentHooks !== false) {
-        const a = installClaudeHooks(root, `${inv.shell} hook`);
+        const a = installClaudeHooks(root, `${inv.agentHookShell} hook`);
         console.log(`  ✓ Claude Code agent hooks ${a.action} (firmness: ${firmness} — change with \`hunch firmness <level>\`)`);
     }
     // Multi-assistant compatibility: MCP + grounding + lifecycle adapters share
@@ -2903,6 +2906,114 @@ landscapeCmd
     console.log(`  hunch landscape adopt --ref ${discovery.sourceRevision} --expected ${discovery.discoveryHash} --all --reviewed-by <you>${discovery.issues.length ? " --acknowledge-issues" : ""}`);
     console.log("Or pass --candidate <hash...> to adopt an explicit subset; relationships require both endpoint resources.");
 });
+// ---- dna (read-only, exact-revision repository convention profile) -------
+const dnaCmd = program
+    .command("dna")
+    .description("Inspect evidence-backed Project DNA and evaluate repository-native artifacts without writing graph authority.");
+dnaCmd
+    .command("inspect")
+    .description("Derive a deterministic Project DNA profile from one exact Git revision. This command never writes memory.")
+    .option("--ref <ref>", "Git commit/ref to inspect", "HEAD")
+    .option("--json", "emit the complete machine-readable profile")
+    .action((opts) => {
+    try {
+        const profile = discoverProjectDna(findRoot(), opts.ref);
+        if (opts.json) {
+            console.log(JSON.stringify(profile, null, 2));
+            return;
+        }
+        console.log(`Project DNA at ${profile.repository_revision}`);
+        console.log(`Profile: ${profile.profile_id} (${profile.content_hash})`);
+        console.log(`Evidence: ${profile.history_sample_count} commit subject(s), ${profile.source_files.length} convention file(s)`);
+        if (profile.source_files.length)
+            console.log(`Sources: ${profile.source_files.join(", ")}`);
+        console.log(`\nTRAITS (${profile.traits.length})`);
+        for (const trait of profile.traits) {
+            console.log(`  ${trait.id}  [${trait.category}/${trait.confidence.toFixed(3)}] ${trait.claim}`);
+            console.log(`    ${trait.evidence.map((evidence) => `${evidence.ref} @ ${evidence.revision.slice(0, 12)} (${evidence.content_hash})`).join("; ")}`);
+        }
+        console.log("\nAdvisory observation only; no trait was adopted into graph authority.");
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+});
+dnaCmd
+    .command("match")
+    .description("Explainably score a commit, PR, issue, or message against deterministic checks in an exact-revision DNA profile.")
+    .requiredOption("--kind <kind>", "artifact kind: commit, pull_request, issue, or message")
+    .requiredOption("--title <title>", "artifact title or commit subject")
+    .option("--body <body>", "artifact body (for example a PR description)")
+    .option("--ref <ref>", "Git commit/ref whose DNA should be used", "HEAD")
+    .option("--json", "emit the complete machine-readable match envelope")
+    .action((opts) => {
+    try {
+        if (!["commit", "pull_request", "issue", "message"].includes(opts.kind)) {
+            return fail("--kind must be commit, pull_request, issue, or message");
+        }
+        const profile = discoverProjectDna(findRoot(), opts.ref);
+        const match = evaluateProjectDnaMatch(profile, {
+            kind: opts.kind,
+            title: opts.title,
+            body: opts.body,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(match, null, 2));
+            return;
+        }
+        console.log(`Project Match: ${match.score === null ? "not enough deterministic checks" : `${match.score.toFixed(1)}/100`}`);
+        console.log(`Profile: ${match.profile_id} @ ${match.repository_revision}`);
+        for (const check of match.checks.filter((candidate) => candidate.applicable)) {
+            console.log(`  ${check.passed ? "PASS" : "FAIL"}  ${check.key} — ${check.detail}`);
+        }
+        console.log("Advisory only; the score does not grant or change enforcement authority.");
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+});
+dnaCmd
+    .command("context")
+    .description("Render the bounded advisory Project DNA supplement used by normal Hunch context delivery.")
+    .option("--ref <ref>", "Git commit/ref to inspect", "HEAD")
+    .option("--traits <count>", "maximum traits in the orientation slice", "8")
+    .option("--json", "emit the complete machine-readable supplement")
+    .action((opts) => {
+    try {
+        const traitCap = Number(opts.traits);
+        const supplement = projectDnaDeliverySupplement(discoverProjectDna(findRoot(), opts.ref), traitCap);
+        if (opts.json)
+            console.log(JSON.stringify(supplement, null, 2));
+        else
+            console.log(supplement?.text ?? "No evidence-backed Project DNA traits yet.");
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+});
+dnaCmd
+    .command("diff")
+    .description("Compare two exact-revision DNA profiles without rewriting either snapshot.")
+    .argument("<from>", "older Git revision")
+    .argument("<to>", "newer Git revision")
+    .option("--json", "emit the complete sealed delta")
+    .action((from, to, opts) => {
+    try {
+        const root = findRoot();
+        const delta = diffProjectDna(discoverProjectDna(root, from), discoverProjectDna(root, to));
+        if (opts.json) {
+            console.log(JSON.stringify(delta, null, 2));
+            return;
+        }
+        console.log(`Project DNA drift ${delta.delta_id}: ${delta.changed ? `${delta.changes.length} change(s)` : "no observed change"}`);
+        for (const change of delta.changes)
+            console.log(`  ${change.kind}  ${change.key}`);
+        console.log("Observation only; no Project DNA profile or graph authority was rewritten.");
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+});
 landscapeCmd
     .command("adopt")
     .description("Human-confirm a reviewed candidate set and write only those exact records through Hunch's normal graph boundary.")

package/dist/cli/invocation.js CHANGED Viewed

@@ -16,6 +16,13 @@ export function dim(s) {
 export function publishedMcpInvocation() {
     return { command: "npx", args: ["-y", `--package=${HUNCH_NPX_PACKAGE_SPEC}`, "hunch"] };
 }
+/** Render a structured invocation for the host shell. Safe tokens stay bare so
+ *  PowerShell can execute the first token; paths and other unsafe tokens use
+ *  JSON string quoting, which is accepted by PowerShell, cmd, and POSIX sh. */
+export function shellInvocation(inv) {
+    const token = (part) => /^[A-Za-z0-9_@:=+.,/-]+$/.test(part) ? part : JSON.stringify(part);
+    return [inv.command, ...inv.args].map(token).join(" ");
+}
 /** The doctor command's synthesis-status line(s) for a resolved provider.
  *  Exported for testing — the previous version (a bare provider-name switch,
  *  before the resolveSynthesisProvider preference system existed) had zero
@@ -77,23 +84,29 @@ export function resolveInvocation() {
     // absolute-node invocation below.
     const installed = !isDev && entry.replace(/\\/g, "/").includes("/node_modules/");
     if (installed) {
+        const mcp = publishedMcpInvocation();
         return {
             shell: `${q(process.execPath)} ${q(entry)}`,
-            mcp: publishedMcpInvocation(),
+            agentHookShell: shellInvocation(mcp),
+            mcp,
         };
     }
     if (isDev) {
+        const mcp = { command: "npx", args: ["tsx", entry] };
         return {
             shell: `npx tsx ${q(entry)}`,
-            mcp: { command: "npx", args: ["tsx", entry] },
+            agentHookShell: shellInvocation(mcp),
+            mcp,
         };
     }
     // Source-checkout dist run (e.g. `node dist/cli/index.js`, npm link): inherently
     // per-machine. Use the absolute node binary (process.execPath) rather than a bare
     // `node`, so the hook works even when nvm's `node` isn't on the hook's PATH.
+    const mcp = { command: process.execPath, args: [entry] };
     return {
         shell: `${q(process.execPath)} ${q(entry)}`,
-        mcp: { command: process.execPath, args: [entry] },
+        agentHookShell: shellInvocation(mcp),
+        mcp,
     };
 }
 //# sourceMappingURL=invocation.js.map