@kage-core/kage-graph-mcp 1.1.15 → 1.1.17

package/README.md

@@ -9,15 +9,29 @@ This package exposes two surfaces:
 
 ## Latest Release
 
-`1.1.15` hardens the npm release path and memory-only review flow:
-
-- `npm run release:npm:dry-run` runs the guarded release checks without
-  publishing.
-- `npm run release:npm` builds the release helper, requires a clean worktree,
-  fetches the remote branch, verifies local `HEAD` contains `origin/<branch>`,
-  runs tests and `npm pack --dry-run`, pushes the branch before publishing,
-  publishes with `--access public`, verifies npm registry metadata, and performs
-  a smoke install.
+`1.1.17` publishes content-based graph freshness:
+
+- `kage pr check` now uses graph input hashes, so push-only operations and
+  empty/same-tree commits do not force another refresh while real source,
+  approved-memory, or code-index changes still stale generated graph artifacts.
+
+`1.1.16` fixes the guarded release helper's npm verification step:
+
+- exact-version `npm view` checks now retry with backoff after publish so npm
+  registry propagation does not make a successful publish look failed.
+- the release helper is maintainer-only repo tooling: public package metadata no
+  longer exposes npm release scripts, and `dist/release.js` is excluded from the
+  published tarball.
+
+`1.1.15` hardened the npm release path and memory-only review flow:
+
+- the source-repo maintainer helper can run the guarded release checks without
+  publishing, or push/publish/smoke-test when explicitly invoked from a built
+  checkout.
+- it requires a clean worktree, fetches the remote branch, verifies local `HEAD`
+  contains `origin/<branch>`, runs tests and `npm pack --dry-run`, pushes the
+  branch before publishing, publishes with `--access public`, verifies npm
+  registry metadata, and performs a smoke install.
 - all git steps run with `GIT_EDITOR=true` so agent sessions cannot get stuck in
   an interactive commit or rebase editor.
 - `kage propose --from-diff` now includes repo memory packet-only changes from
@@ -54,20 +68,27 @@ This package exposes two surfaces:
 ```bash
 npm install
 npm run build
-npm run release:npm:dry-run
 ```
 
-Publishing from the repo should use the guarded release script after the release
-commit is ready:
+Publishing from the source repo should use the guarded maintainer helper after
+the release commit is ready. It is intentionally not exposed as a public npm
+script or included in the published tarball:
 
 ```bash
-npm run release:npm
+npm run build --prefix mcp
+cd mcp
+node dist/release.js --dry-run
+node dist/release.js --publish --push --smoke
 ```
 
 The script fetches the current branch and blocks if the remote branch is not an
 ancestor of local `HEAD`, which prevents publishing an npm version from a branch
 that cannot be pushed cleanly.
 
+Do not refresh again just because the branch was pushed. Graph freshness is
+based on source, approved memory, and code-index inputs; empty/same-tree commits
+are accepted by `kage pr check`.
+
 ## CLI
 
 ```bash
@@ -221,9 +242,10 @@ hashes, git state, audit trust, inbox counts, and metrics readiness. CI, PR, and
 sync workflows build it after refresh.
 
 Use `kage refresh --project <repo>` or the `kage_refresh` MCP tool after
-meaningful file changes. Refresh rebuilds indexes, code graph, memory graph,
-metrics, and stale-memory metadata. Memory is marked stale when status or
-feedback says it is stale, its TTL expires, or grounded paths disappear.
+meaningful file/content changes. Refresh rebuilds indexes, code graph, memory
+graph, metrics, and stale-memory metadata. Memory is marked stale when status or
+feedback says it is stale, its TTL expires, or grounded paths disappear. Pushes
+and empty/same-tree commits do not need another refresh.
 
 Use `kage gc --project <repo> --dry-run` to preview stale packet cleanup.
 `kage gc --project <repo>` marks stale repo packets deprecated, rebuilds
@@ -396,7 +418,7 @@ Minimum policy:
 Before code changes or repo-specific answers:
 1. Call `kage_context` with `project_dir` and the user task as `query`.
 2. Capture reusable learnings with `kage_learn` or `kage_capture`.
-3. After meaningful file changes, call `kage_refresh`.
+3. After meaningful file/content changes, call `kage_refresh`; skip it for push-only or same-tree commits.
 4. Before finishing changed-file tasks, call `kage_propose_from_diff` or `kage_pr_summarize`.
 5. Before merge, call `kage_pr_check`.
 6. Never publish or promote org/global memory automatically.

package/dist/index.js

@@ -217,7 +217,7 @@ function listTools() {
         },
         {
             name: "kage_refresh",
-            description: "Rebuild repo indexes, code graph, memory graph, metrics, and stale-memory metadata. Agents should run this after meaningful file changes and before PR checks.",
+            description: "Rebuild repo indexes, code graph, memory graph, metrics, and stale-memory metadata. Agents should run this after meaningful file/content changes before PR checks; push-only or same-tree commits do not need another refresh.",
             inputSchema: {
                 type: "object",
                 properties: {

package/dist/kernel.js

@@ -193,8 +193,10 @@ decisions, debugging, explanation, or action. Do not store raw transcripts.
 
 ## End-Of-Task Proposal
 
-After meaningful file changes, call \`kage_refresh\` so indexes, code graph,
-memory graph, metrics, and stale-memory checks are current.
+After meaningful file/content changes, call \`kage_refresh\` so indexes, code
+graph, memory graph, metrics, and stale-memory checks are current. Do not
+refresh solely because a branch was pushed, an empty commit was created, or the
+git commit changed without graph inputs changing.
 
 Before finishing a task that changed files, call \`kage_pr_summarize\` or
 \`kage_propose_from_diff\`, then call \`kage_pr_check\`.
@@ -232,7 +234,7 @@ For normal coding tasks:
 1. \`kage_context\` — validate + recall + code graph + knowledge graph in one call
 2. Work on the task
 3. \`kage_learn\` for concrete learnings
-4. \`kage_refresh\` after meaningful file changes
+4. \`kage_refresh\` after meaningful file/content changes, not after push-only or same-tree commits
 5. \`kage_propose_from_diff\` before the final response to create repo-local change memory
 
 For quick factual questions, \`kage_context\` alone is enough. For status or demo requests, call \`kage_metrics\`.
@@ -882,6 +884,9 @@ function gitBranch(projectDir) {
 function gitHead(projectDir) {
     return readGit(projectDir, ["rev-parse", "HEAD"]);
 }
+function gitTree(projectDir) {
+    return readGit(projectDir, ["rev-parse", "HEAD^{tree}"]);
+}
 function gitMergeBase(projectDir) {
     return readGit(projectDir, ["merge-base", "HEAD", "origin/main"])
         || readGit(projectDir, ["merge-base", "HEAD", "origin/master"]);
@@ -1863,6 +1868,49 @@ function externalIndexFiles(projectDir) {
         { path: (0, node_path_1.join)(projectDir, "dump.lsif"), parser: "lsif", format: "lsif" },
     ];
 }
+function sha256Hex(content) {
+    return (0, node_crypto_1.createHash)("sha256").update(content).digest("hex");
+}
+function projectRelative(projectDir, path) {
+    return (0, node_path_1.relative)(projectDir, path).replace(/\\/g, "/");
+}
+function graphInputHash(entries) {
+    const hash = (0, node_crypto_1.createHash)("sha256");
+    const sorted = entries.slice().sort((a, b) => a.kind.localeCompare(b.kind) || a.path.localeCompare(b.path));
+    for (const entry of sorted) {
+        hash.update(entry.kind);
+        hash.update("\0");
+        hash.update(entry.path);
+        hash.update("\0");
+        hash.update(entry.sha256);
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+function fileInputEntries(projectDir, paths, kind) {
+    return paths
+        .filter((path) => (0, node_fs_1.existsSync)(path))
+        .map((path) => ({
+        kind,
+        path: projectRelative(projectDir, path),
+        sha256: sha256Hex((0, node_fs_1.readFileSync)(path)),
+    }));
+}
+function codeGraphInputHash(projectDir) {
+    return graphInputHash([
+        ...fileInputEntries(projectDir, listCodeFiles(projectDir), "code_file"),
+        ...fileInputEntries(projectDir, externalIndexFiles(projectDir).map((index) => index.path), "external_code_index"),
+    ]);
+}
+function knowledgeGraphInputHash(projectDir, codeInputHash = codeGraphInputHash(projectDir)) {
+    const packetEntries = loadPacketEntriesFromDir(packetsDir(projectDir))
+        .filter((entry) => entry.packet.status === "approved")
+        .map((entry) => entry.path);
+    return graphInputHash([
+        { kind: "code_graph_input", path: ".agent_memory/code_graph/input", sha256: codeInputHash },
+        ...fileInputEntries(projectDir, packetEntries, "approved_packet"),
+    ]);
+}
 function normalizeExternalKind(value) {
     const kind = String(value ?? "").toLowerCase();
     if (["function", "method", "class", "constant", "route", "test"].includes(kind))
@@ -2103,7 +2151,9 @@ function buildCodeGraph(projectDir) {
     ensureMemoryDirs(projectDir);
     const branch = gitBranch(projectDir);
     const head = gitHead(projectDir);
+    const tree = gitTree(projectDir);
     const mergeBase = gitMergeBase(projectDir);
+    const inputHash = codeGraphInputHash(projectDir);
     const absoluteFiles = listCodeFiles(projectDir);
     const knownFiles = new Set(absoluteFiles.map((path) => (0, node_path_1.relative)(projectDir, path).replace(/\\/g, "/")));
     const files = [];
@@ -2188,7 +2238,7 @@ function buildCodeGraph(projectDir) {
         project_dir: projectDir,
         repo_key: repoKey(projectDir),
         generated_at: nowIso(),
-        repo_state: { branch, head, merge_base: mergeBase },
+        repo_state: { branch, head, merge_base: mergeBase, tree, input_hash: inputHash },
         files: files.sort((a, b) => a.path.localeCompare(b.path)),
         symbols: symbols.sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line || a.name.localeCompare(b.name)),
         imports: imports.sort((a, b) => a.from_path.localeCompare(b.from_path) || a.line - b.line || a.specifier.localeCompare(b.specifier)),
@@ -2212,6 +2262,7 @@ function buildKnowledgeGraph(projectDir) {
     const packets = loadApprovedPackets(projectDir).sort((a, b) => a.id.localeCompare(b.id));
     const branch = gitBranch(projectDir);
     const head = gitHead(projectDir);
+    const tree = gitTree(projectDir);
     const mergeBase = gitMergeBase(projectDir);
     const entities = new Map();
     const edges = new Map();
@@ -2219,6 +2270,7 @@ function buildKnowledgeGraph(projectDir) {
     const repoEntityId = graphEntityId("repo", repoKey(projectDir));
     const generatedFrom = packets.map((packet) => packet.updated_at).sort().at(-1) ?? null;
     const codeGraph = buildCodeGraph(projectDir);
+    const inputHash = knowledgeGraphInputHash(projectDir, codeGraph.repo_state.input_hash ?? codeGraphInputHash(projectDir));
     addEntity(entities, {
         id: repoEntityId,
         type: "repo",
@@ -2540,7 +2592,7 @@ function buildKnowledgeGraph(projectDir) {
         project_dir: projectDir,
         repo_key: repoKey(projectDir),
         generated_from_updated_at: generatedFrom,
-        repo_state: { branch, head, merge_base: mergeBase },
+        repo_state: { branch, head, merge_base: mergeBase, tree, input_hash: inputHash },
         episodes: episodes.sort((a, b) => a.id.localeCompare(b.id)),
         entities: [...entities.values()].sort((a, b) => a.id.localeCompare(b.id)),
         edges: [...edges.values()].sort((a, b) => a.id.localeCompare(b.id)),
@@ -4239,7 +4291,7 @@ Before making code changes or answering implementation questions:
 1. Call kage_context with project_dir and the user task as query.
 2. Use returned memory only when it is relevant, source-backed, and not stale.
 When you learn something reusable: kage_learn.
-After meaningful file changes: kage_refresh.
+After meaningful file/content changes: kage_refresh. Push-only or same-tree commits do not need another refresh.
 Before finishing a task that changed files: kage_pr_summarize or kage_propose_from_diff, then kage_pr_check.
 If recalled memory helped: kage_feedback helpful. If wrong or stale: kage_feedback wrong or stale."
 fi
@@ -4963,15 +5015,22 @@ function createReviewArtifact(projectDir) {
     (0, node_fs_1.writeFileSync)(path, `${lines.join("\n").trim()}\n`, "utf8");
     return { path, pending: pending.length };
 }
-function graphIsCurrent(projectDir, relativePath, head) {
+function graphIsCurrent(projectDir, relativePath, expected) {
     const path = (0, node_path_1.join)(projectDir, relativePath);
     if (!(0, node_fs_1.existsSync)(path))
         return false;
-    if (!head)
-        return true;
     try {
         const graph = readJson(path);
-        return graph.repo_state?.head === head;
+        const repoState = graph.repo_state;
+        if (!repoState)
+            return false;
+        if (expected.inputHash && repoState.input_hash)
+            return repoState.input_hash === expected.inputHash;
+        if (expected.tree && repoState.tree)
+            return repoState.tree === expected.tree;
+        if (!expected.head)
+            return true;
+        return repoState.head === expected.head;
     }
     catch {
         return false;
@@ -5005,6 +5064,9 @@ function prCheck(projectDir) {
     const overlay = buildBranchOverlay(projectDir);
     const rawStatus = readGit(projectDir, ["status", "--porcelain", "-uall"]) ?? "";
     const validation = validateProject(projectDir);
+    const tree = gitTree(projectDir);
+    const codeInputHash = codeGraphInputHash(projectDir);
+    const memoryInputHash = knowledgeGraphInputHash(projectDir, codeInputHash);
     const stalePackets = loadPacketsFromDir(packetsDir(projectDir))
         .map((packet) => ({ packet, reasons: staleMemoryReasons(projectDir, packet) }))
         .filter((entry) => entry.reasons.length)
@@ -5014,8 +5076,8 @@ function prCheck(projectDir) {
         .map(parsePorcelainPath)
         .map((path) => path.replace(/^.* -> /, ""))
         .filter((path) => path.startsWith(".agent_memory/packets/") && path.endsWith(".json"))).sort();
-    const codeGraphCurrent = graphIsCurrent(projectDir, ".agent_memory/code_graph/graph.json", overlay.head);
-    const memoryGraphCurrent = graphIsCurrent(projectDir, ".agent_memory/graph/graph.json", overlay.head);
+    const codeGraphCurrent = graphIsCurrent(projectDir, ".agent_memory/code_graph/graph.json", { head: overlay.head, tree, inputHash: codeInputHash });
+    const memoryGraphCurrent = graphIsCurrent(projectDir, ".agent_memory/graph/graph.json", { head: overlay.head, tree, inputHash: memoryInputHash });
     const errors = [...validation.errors];
     const warnings = [...validation.warnings];
     const requiredActions = [];
@@ -5024,7 +5086,7 @@ function prCheck(projectDir) {
         requiredActions.push("Run kage refresh, then update or supersede stale packets.");
     }
     if (!codeGraphCurrent || !memoryGraphCurrent) {
-        errors.push("Generated graph artifacts are missing or not current for this branch head.");
+        errors.push("Generated graph artifacts are missing or not current for this working tree content.");
         requiredActions.push("Run kage refresh --project <dir> before merge.");
     }
     if (!memoryPacketChanges.length && overlay.changed_files.some((path) => !path.startsWith(".agent_memory/"))) {

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "1.1.15",
+  "version": "1.1.17",
   "description": "Local-first repo memory, code graph, and recall MCP server for coding agents",
   "main": "dist/index.js",
   "files": [
     "dist/**/*.js",
     "!dist/**/*.test.js",
+    "!dist/release.js",
     "viewer/**/*",
     "!viewer/graphs/*.json",
     "README.md"
@@ -21,9 +22,7 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "ts-node index.ts",
-    "test": "npm run build && node --test dist/**/*.test.js",
-    "release:npm:dry-run": "npm run build && node dist/release.js --dry-run",
-    "release:npm": "npm run build && node dist/release.js --publish --push --smoke"
+    "test": "npm run build && node --test dist/**/*.test.js"
   },
   "keywords": [
     "mcp",

package/dist/release.js

@@ -1,121 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseReleaseArgs = parseReleaseArgs;
-exports.buildNpmReleasePlan = buildNpmReleasePlan;
-exports.runNpmRelease = runNpmRelease;
-const node_child_process_1 = require("node:child_process");
-const node_fs_1 = require("node:fs");
-const node_os_1 = require("node:os");
-const node_path_1 = require("node:path");
-const DEFAULT_CACHE = "/private/tmp/kage-npm-cache";
-function parseReleaseArgs(argv) {
-    const options = {
-        publish: false,
-        push: false,
-        smoke: false,
-        cache: DEFAULT_CACHE,
-    };
-    for (let index = 0; index < argv.length; index += 1) {
-        const arg = argv[index];
-        if (arg === "--publish")
-            options.publish = true;
-        else if (arg === "--dry-run")
-            options.publish = false;
-        else if (arg === "--push")
-            options.push = true;
-        else if (arg === "--smoke")
-            options.smoke = true;
-        else if (arg === "--cache") {
-            const value = argv[index + 1];
-            if (!value)
-                throw new Error("--cache requires a path");
-            options.cache = value;
-            index += 1;
-        }
-        else {
-            throw new Error(`Unknown release option: ${arg}`);
-        }
-    }
-    return options;
-}
-function buildNpmReleasePlan(context) {
-    const gitEnv = { GIT_EDITOR: "true" };
-    const steps = [
-        { name: "ensure clean worktree", command: "git", args: ["status", "--porcelain", "-uall"], env: gitEnv, expectEmptyStdout: true },
-        { name: "fetch remote branch", command: "git", args: ["fetch", "origin", context.branch], env: gitEnv },
-        { name: "ensure branch contains remote", command: "git", args: ["merge-base", "--is-ancestor", `origin/${context.branch}`, "HEAD"], env: gitEnv },
-        { name: "run package tests", command: "npm", args: ["test"] },
-        { name: "pack dry run", command: "npm", args: ["--cache", context.cache, "pack", "--dry-run"] },
-    ];
-    if (context.push) {
-        steps.push({ name: "push branch", command: "git", args: ["push", "origin", context.branch], env: gitEnv });
-    }
-    if (context.publish) {
-        steps.push({ name: "publish package", command: "npm", args: ["--cache", context.cache, "publish", "--access", "public"] }, { name: "verify npm version", command: "npm", args: ["view", `${context.packageName}@${context.version}`, "version"] });
-        if (context.smoke) {
-            steps.push({
-                name: "smoke install published package",
-                command: "npm",
-                args: ["--cache", context.cache, "install", "--prefix", smokeInstallDir(context.version), `${context.packageName}@${context.version}`],
-            });
-        }
-    }
-    return steps;
-}
-function smokeInstallDir(version) {
-    return (0, node_path_1.join)((0, node_os_1.tmpdir)(), `kage-npm-smoke-${version}`);
-}
-function stdout(command, args, cwd) {
-    return (0, node_child_process_1.execFileSync)(command, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
-}
-function packageMetadata(packageDir) {
-    const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(packageDir, "package.json"), "utf8"));
-    if (typeof pkg.name !== "string" || typeof pkg.version !== "string") {
-        throw new Error("package.json must contain string name and version");
-    }
-    return { name: pkg.name, version: pkg.version };
-}
-function runStep(step, cwd) {
-    console.log(`release:npm: ${step.name}`);
-    if (step.expectEmptyStdout) {
-        const output = (0, node_child_process_1.execFileSync)(step.command, step.args, {
-            cwd,
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "inherit"],
-            env: { ...process.env, ...step.env },
-        }).trim();
-        if (output)
-            throw new Error(`release:npm: ${step.name} failed because output was not empty:\n${output}`);
-        return;
-    }
-    (0, node_child_process_1.execFileSync)(step.command, step.args, {
-        cwd,
-        stdio: "inherit",
-        env: { ...process.env, ...step.env },
-    });
-}
-function runNpmRelease(argv = process.argv.slice(2), packageDir = process.cwd()) {
-    const options = parseReleaseArgs(argv);
-    const repoRoot = stdout("git", ["rev-parse", "--show-toplevel"], packageDir);
-    const branch = stdout("git", ["branch", "--show-current"], repoRoot);
-    if (!branch)
-        throw new Error("npm release requires a named git branch");
-    (0, node_fs_1.mkdirSync)(options.cache, { recursive: true });
-    if (options.smoke)
-        (0, node_fs_1.mkdirSync)(smokeInstallDir(packageMetadata(packageDir).version), { recursive: true });
-    const metadata = packageMetadata(packageDir);
-    const plan = buildNpmReleasePlan({ ...options, branch, packageName: metadata.name, version: metadata.version });
-    console.log(`release:npm: package ${metadata.name}@${metadata.version}`);
-    console.log(`release:npm: mode ${options.publish ? "publish" : "dry-run"}`);
-    for (const step of plan)
-        runStep(step, repoRoot === (0, node_path_1.resolve)(packageDir, "..") ? packageDir : repoRoot);
-}
-if (process.argv[1] && process.argv[1].endsWith("release.js")) {
-    try {
-        runNpmRelease();
-    }
-    catch (error) {
-        console.error(error instanceof Error ? error.message : String(error));
-        process.exit(2);
-    }
-}