@davesheffer/hunch 1.23.3 → 1.24.0

package/README.md

@@ -49,6 +49,24 @@ assistants without replacing their existing configuration. The next session rece
 story with its sources, not a giant transcript or a generic prompt wall. Lifecycle coverage
 depends on the harness; MCP connectivity alone does not establish automatic grounding or enforcement.
 
+To update Hunch and all configured harness pins for the current repository:
+
+```sh
+hunch update
+```
+
+Agents receive an instruction to run this when you ask **“update Hunch”** in the generated
+Hunch guidance. The command resolves npm's latest release, updates an existing dependency
+to an exact version in its current dependency section, then runs the new version's pin
+repair and integration check. Without a repository dependency it updates the global CLI.
+Use `--global` to also update the global CLI when a local dependency exists, or `--dry-run`
+to preview the commands. Restart active harnesses afterward. This applies to the current
+repository, not every project on your machine. Automatic dependency installation currently
+supports standalone npm projects; other package managers should update their dependency
+explicitly and then use `hunch integrations repair-pins`. Existing hook settings are preserved.
+An installation or check failure stops the command with a nonzero exit; completed npm
+changes are not rolled back. Fix the reported issue and rerun the command.
+
 Check the repository's integrations after upgrading Hunch or switching assistants:
 
 ```sh

package/dist/cli/index.js

@@ -25,6 +25,7 @@ import { writeFileAtomic } from "../core/io.js";
 import { looksLikeCorrection, CORRECTION_NUDGE } from "../core/correction.js";
 import { HUNCH_VERSION } from "../core/version.js";
 import { registerIntegrationCommands } from "./integrations.js";
+import { registerUpdateCommand } from "./update.js";
 import { inspectIntegrations, formatIntegrationHealth, integrationHealthFails, integrationSessionWarning } from "../integrations/health.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { JsonStore } from "../store/jsonStore.js";
@@ -112,6 +113,7 @@ import { resolveInvocation, dim, synthesisStatusLines, maybeWarnOllamaContext }
 const program = new Command();
 program.name("hunch").description("Hunch — engineering memory and a deterministic Change Gate for AI-assisted codebases.").version(HUNCH_VERSION);
 registerIntegrationCommands(program);
+registerUpdateCommand(program);
 let openStore = null;
 function openTeamStore(root, opts = {}) {
     // A committed team.json is an explicit declaration that this checkout belongs

package/dist/cli/update.js

@@ -0,0 +1,72 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { findRoot } from "../core/paths.js";
+const PACKAGE = "@davesheffer/hunch";
+/** Arguments come only from fixed commands and a validated registry version.
+ * Windows needs the shell to resolve npm.cmd; cwd is never interpolated. */
+export function runNpm(root, args, capture = false) {
+    if (args.some(arg => !/^[a-zA-Z0-9@/_.=+:-]+$/.test(arg)))
+        throw new Error("unsafe npm argument");
+    const windows = process.platform === "win32";
+    const result = spawnSync(windows ? `npm ${args.join(" ")}` : "npm", windows ? [] : args, {
+        cwd: root, shell: windows, windowsHide: true,
+        encoding: "utf8", stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0)
+        throw new Error(`npm ${args.join(" ")} failed (${result.status ?? result.signal})${result.stderr ? `: ${result.stderr.trim()}` : ""}`);
+    return result.stdout ?? "";
+}
+/** Fresh child execution is essential: the currently running CLI still has the
+ * old modules loaded after npm replaces its installation. */
+export function updateHunch(root, opts = {}, run = (args, capture) => runNpm(root, args, capture), log = console.log) {
+    const file = join(root, "package.json");
+    const manifest = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
+        throw new Error("package.json must contain an object");
+    if (manifest.name === PACKAGE)
+        throw new Error("Run hunch update in a consumer repository, not Hunch's own source checkout.");
+    const sections = ["dependencies", "devDependencies", "optionalDependencies"];
+    const declared = sections.filter(section => {
+        const deps = manifest[section];
+        if (deps !== undefined && (!deps || typeof deps !== "object" || Array.isArray(deps)))
+            throw new Error(`invalid ${section} in package.json`);
+        return deps && Object.hasOwn(deps, PACKAGE);
+    });
+    if (declared.length > 1)
+        throw new Error("Hunch is declared in multiple dependency sections; resolve the duplicate before updating.");
+    if (declared.length && (manifest.workspaces || (manifest.packageManager && !/^npm@/.test(manifest.packageManager)) || ["pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"].some(name => existsSync(join(root, name))))) {
+        throw new Error("Automatic dependency updates currently support standalone npm projects. Update Hunch to an exact version with your package manager, then run hunch integrations repair-pins.");
+    }
+    const version = JSON.parse(run(["view", `${PACKAGE}@latest`, "version", "--json"], true));
+    if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version))
+        throw new Error("npm returned an invalid Hunch version");
+    const spec = `${PACKAGE}@${version}`;
+    const commands = [];
+    if (declared.length) {
+        const flag = { dependencies: "--save-prod", devDependencies: "--save-dev", optionalDependencies: "--save-optional" }[declared[0]];
+        commands.push(["install", flag, "--save-exact", spec]);
+    }
+    if (!declared.length || opts.global)
+        commands.push(["install", "--global", spec]);
+    // The alias prevents npm exec from substituting a stale local hunch binary.
+    commands.push(["exec", "--yes", `--package=hunch-exact@npm:${spec}`, "--", "hunch", "integrations", "repair-pins"]);
+    log(`${opts.dryRun ? "Preview" : "Updating"}: Hunch ${version} for ${root}`);
+    for (const args of commands) {
+        log(`npm ${args.join(" ")}`);
+        if (!opts.dryRun)
+            run(args);
+    }
+    if (!opts.dryRun)
+        log("Hunch updated; repository integration check passed. Restart or reconnect active harnesses to load the new MCP version.");
+}
+export function registerUpdateCommand(program) {
+    program.command("update")
+        .description("Update Hunch to latest and repair all configured harness pins in this repository")
+        .option("--global", "also update the global CLI when a repository dependency exists")
+        .option("--dry-run", "resolve latest and print commands without changing files")
+        .action((opts) => updateHunch(findRoot(), opts));
+}
+//# sourceMappingURL=update.js.map

package/dist/integrations/claudemd.js

@@ -46,6 +46,7 @@ export function renderHunchSection(store, root) {
     lines.push("**Consult Hunch via the `hunch_*` MCP tools — pick by MOMENT, not from memory:**");
     lines.push("");
     lines.push("**Orient (session/task start):**");
+    lines.push("- When the user asks to **update Hunch**, run `hunch update` from this repository root. It updates to the latest release and repairs all configured harness pins. Use `hunch update --global` to also update a global CLI alongside a repository dependency; reconnect active MCP sessions afterward.");
     lines.push("- `hunch_context(target)` — the minimal relevant slice for what you're about to do; a task phrase falls back to the closest graph matches. **Call FIRST.**");
     lines.push("- `hunch_structure(target?)` — the indexed shape of the repo/dir/file/symbol — orient from the graph, not grep rounds.");
     lines.push("- `hunch_runbook(task)` — the proven steps for a recurring task, before re-deriving them.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.23.3",
+  "version": "1.24.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
@@ -69,7 +69,7 @@
     "node": ">=22.13.0"
   },
   "scripts": {
-    "version": "node tooling/sync-version-pins.mjs && git add plugin/.mcp.json server.json",
+    "version": "node tooling/sync-version-pins.mjs && git add plugin/.mcp.json server.json .windsurf/hooks.json",
     "sync-version-pins": "node tooling/sync-version-pins.mjs",
     "clean": "node --input-type=commonjs -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc -p tsconfig.json",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://www.hunchmemory.com",
-  "version": "1.23.3",
+  "version": "1.24.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.23.3",
+      "version": "1.24.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {