diffninja 0.2.0 → 0.3.1

package/dist/review/setup.d.ts

@@ -3,13 +3,15 @@
  * agent CLI (Claude Code, Codex, OMP, pi) with one command.
  *
  * The setup installs the package globally first so the registration points
- * at a permanent binary instead of the npx cache. When the global install is
- * unavailable it falls back to an npx-based entry and says so. The server
+ * at a permanent binary instead of the npx cache, and brings a global install
+ * older than itself up to its own version, so running the newest setup is how
+ * a user updates. When the global install is unavailable it falls back to an
+ * npx-based entry pinned to its own version and says so. The server
  * needs no key or environment: reviews are local, and connected reviews reuse
  * the `gh` session.
  */
 import { type Stats } from "node:fs";
-export declare const setupHelp = "diffninja setup. Register the diffninja MCP server on every detected agent CLI.\n\n  npx -y diffninja setup [--cli claude,codex,omp,pi] [--dry-run]\n  diffninja setup --uninstall [--cli codex]\n\nDetects Claude Code, Codex, OMP, and pi from their config files or binaries\nand registers the diffninja MCP server in each user config, pointing at the\nglobally installed package. Installs the package globally first\n(`npm install -g diffninja`) so the registration keeps working; when that\ninstall fails it registers an npx-based entry instead and says so.\n\nOptions:\n  --cli NAMES    Only these CLIs, comma-separated: claude,codex,omp,pi.\n  --uninstall    Remove the diffninja server from every detected CLI.\n  --dry-run      Show what would change, without installing or writing.\n  --no-install   Skip the global install and register npx-based entries.\n  --help         Show this help.\n\nThe server needs no API key: static reviews run locally, and pull request\nreviews reuse your authenticated gh session.\n";
+export declare const setupHelp = "diffninja setup. Register the diffninja MCP server on every detected agent CLI.\n\n  npx -y diffninja@latest setup [--cli claude,codex,omp,pi] [--dry-run]\n  diffninja setup --uninstall [--cli codex]\n\nDetects Claude Code, Codex, OMP, and pi from their config files or binaries\nand registers the diffninja MCP server in each user config, pointing at the\nglobally installed package. Installs the package globally first\n(`npm install -g diffninja@<this version>`) so the registration keeps\nworking, and updates a global install older than this setup, so running\n`npx -y diffninja@latest setup` again is how you update. When that install\nfails it registers an npx-based entry pinned to this version and says so.\n\nOptions:\n  --cli NAMES    Only these CLIs, comma-separated: claude,codex,omp,pi.\n  --uninstall    Remove the diffninja server from every detected CLI.\n  --dry-run      Show what would change, without installing or writing.\n  --no-install   Skip installing or updating the global package; without one,\n                 register npx-based entries.\n  --help         Show this help.\n\nThe server needs no API key: static reviews run locally, and pull request\nreviews reuse your authenticated gh session.\n";
 export declare const CLI_NAMES: readonly ["claude", "codex", "omp", "pi"];
 export type CliName = (typeof CLI_NAMES)[number];
 export interface McpEntry {
@@ -29,7 +31,8 @@ export interface SetupOptions {
 }
 export interface Npm {
     rootG(): Promise<string>;
-    installG(): Promise<boolean>;
+    /** `npm install -g <spec>`, e.g. `diffninja@0.3.1`; true on success. */
+    installG(spec: string): Promise<boolean>;
 }
 export interface CliReport {
     cli: CliName;
@@ -44,9 +47,16 @@ export interface SetupReport {
 }
 export interface SetupDeps {
     npm?: Npm;
+    /** Version this setup installs and pins; defaults to the running package's. */
+    version?: string;
 }
-/** Entry that runs the published package on demand, without an install. */
-export declare function npxEntry(platform?: NodeJS.Platform): McpEntry;
+/**
+ * Entry that runs the published package on demand, without an install. It
+ * names this setup's version: an unversioned package lets npx keep running
+ * whichever copy it cached first, while a pinned one changes with each newer
+ * setup, which rewrites the entry.
+ */
+export declare function npxEntry(platform?: NodeJS.Platform, version?: string): McpEntry;
 /**
  * Entry for a command that Windows ships only as a `.cmd` shim, which a client
  * that spawns without a shell cannot launch. Running npm's JS entry point with
@@ -60,6 +70,14 @@ export declare function windowsCliEntry(name: string, args: readonly string[], c
 /** Entry that runs the globally installed package. `globalRoot` is `npm root -g`. */
 export declare function globalEntry(globalRoot: string): McpEntry;
 export declare function globalEntryExists(globalRoot: string): boolean;
+/** Version of the globally installed package, or undefined when its manifest is missing or unreadable. */
+export declare function globalVersion(globalRoot: string): string | undefined;
+/**
+ * Whether a global install at `installed` should be brought up to `version`.
+ * A manifest that cannot be read or compared counts as older, so a broken
+ * install is repaired; a newer one is never downgraded.
+ */
+export declare function globalIsOlder(installed: string | undefined, version: string): boolean;
 /**
  * npm runner. Shell-free by design: on Windows npm is a `.cmd` shim, so runs
  * go through `npmSpawnSpec`, which resolves npm's JS entry point instead.

package/dist/review/setup.js

@@ -3,37 +3,43 @@
  * agent CLI (Claude Code, Codex, OMP, pi) with one command.
  *
  * The setup installs the package globally first so the registration points
- * at a permanent binary instead of the npx cache. When the global install is
- * unavailable it falls back to an npx-based entry and says so. The server
+ * at a permanent binary instead of the npx cache, and brings a global install
+ * older than itself up to its own version, so running the newest setup is how
+ * a user updates. When the global install is unavailable it falls back to an
+ * npx-based entry pinned to its own version and says so. The server
  * needs no key or environment: reviews are local, and connected reviews reuse
  * the `gh` session.
  */
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { once } from "node:events";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { lstat, mkdir, open, readFile, readlink, realpath, rename, rm, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, delimiter, dirname, join, resolve } from "node:path";
 import { z } from "zod";
 import { npmCliPath, npmSpawnSpec } from "../languages/grammars.js";
 import { removeTomlTable, upsertTomlTable } from "./toml.js";
+import { compareVersions, packageVersion } from "./version.js";
 export const setupHelp = `diffninja setup. Register the diffninja MCP server on every detected agent CLI.
 
-  npx -y diffninja setup [--cli claude,codex,omp,pi] [--dry-run]
+  npx -y diffninja@latest setup [--cli claude,codex,omp,pi] [--dry-run]
   diffninja setup --uninstall [--cli codex]
 
 Detects Claude Code, Codex, OMP, and pi from their config files or binaries
 and registers the diffninja MCP server in each user config, pointing at the
 globally installed package. Installs the package globally first
-(\`npm install -g diffninja\`) so the registration keeps working; when that
-install fails it registers an npx-based entry instead and says so.
+(\`npm install -g diffninja@<this version>\`) so the registration keeps
+working, and updates a global install older than this setup, so running
+\`npx -y diffninja@latest setup\` again is how you update. When that install
+fails it registers an npx-based entry pinned to this version and says so.
 
 Options:
   --cli NAMES    Only these CLIs, comma-separated: claude,codex,omp,pi.
   --uninstall    Remove the diffninja server from every detected CLI.
   --dry-run      Show what would change, without installing or writing.
-  --no-install   Skip the global install and register npx-based entries.
+  --no-install   Skip installing or updating the global package; without one,
+                 register npx-based entries.
   --help         Show this help.
 
 The server needs no API key: static reviews run locally, and pull request
@@ -42,9 +48,14 @@ reviews reuse your authenticated gh session.
 export const CLI_NAMES = ["claude", "codex", "omp", "pi"];
 const jsonValueSchema = z.lazy(() => z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(jsonValueSchema), z.record(z.string(), jsonValueSchema)]));
 const jsonObjectSchema = z.object({}).catchall(jsonValueSchema);
-/** Entry that runs the published package on demand, without an install. */
-export function npxEntry(platform = process.platform) {
-    const args = ["-y", "-p", "diffninja", "diffninja-mcp"];
+/**
+ * Entry that runs the published package on demand, without an install. It
+ * names this setup's version: an unversioned package lets npx keep running
+ * whichever copy it cached first, while a pinned one changes with each newer
+ * setup, which rewrites the entry.
+ */
+export function npxEntry(platform = process.platform, version = packageVersion()) {
+    const args = ["-y", "-p", `diffninja@${version}`, "diffninja-mcp"];
     return platform === "win32" ? windowsCliEntry("npx", args) : { command: "npx", args };
 }
 /**
@@ -70,6 +81,27 @@ export function globalEntry(globalRoot) {
 export function globalEntryExists(globalRoot) {
     return existsSync(join(globalRoot, "diffninja", "dist", "review", "mcp-cli.js"));
 }
+const installedManifestSchema = z.object({ version: z.string() });
+/** Version of the globally installed package, or undefined when its manifest is missing or unreadable. */
+export function globalVersion(globalRoot) {
+    try {
+        const manifest = installedManifestSchema.safeParse(JSON.parse(readFileSync(join(globalRoot, "diffninja", "package.json"), "utf8")));
+        return manifest.success ? manifest.data.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether a global install at `installed` should be brought up to `version`.
+ * A manifest that cannot be read or compared counts as older, so a broken
+ * install is repaired; a newer one is never downgraded.
+ */
+export function globalIsOlder(installed, version) {
+    if (installed === undefined)
+        return true;
+    return (compareVersions(installed, version) ?? -1) < 0;
+}
 /**
  * npm runner. Shell-free by design: on Windows npm is a `.cmd` shim, so runs
  * go through `npmSpawnSpec`, which resolves npm's JS entry point instead.
@@ -90,8 +122,8 @@ export function createNpm(overrides = {}) {
             });
             return (await exitCode(child)) === 0 ? out.trim() : "";
         },
-        async installG() {
-            return (await exitCode(run(["install", "-g", `--allow-scripts=${INSTALL_SCRIPT_PACKAGES.join(",")}`, "diffninja"], true))) === 0;
+        async installG(spec) {
+            return (await exitCode(run(["install", "-g", `--allow-scripts=${INSTALL_SCRIPT_PACKAGES.join(",")}`, spec], true))) === 0;
         },
     };
 }
@@ -123,35 +155,70 @@ async function globalRoot(npm) {
         return undefined;
     }
 }
+/** Run one global install; a throw counts as a failed install. */
+async function installGlobal(npm, spec) {
+    try {
+        return await npm.installG(spec);
+    }
+    catch {
+        return false;
+    }
+}
 /**
- * Resolve the registration entry. `--dry-run` never installs: it reports the
- * install it would have run and the entry that install would have produced.
+ * Resolve the registration entry. A global install older than `version` is
+ * updated to it first; one that cannot be updated keeps its entry, with a
+ * warning naming the command that updates it. `--dry-run` never installs: it
+ * reports the install it would have run and the entry that install would have
+ * produced.
  */
-async function resolveEntry(noInstall, npm, quiet, dryRun) {
+async function resolveEntry(noInstall, npm, quiet, dryRun, version) {
+    const spec = `diffninja@${version}`;
     const root = await globalRoot(npm);
-    if (root !== undefined && globalEntryExists(root))
+    if (root !== undefined && globalEntryExists(root)) {
+        const installed = globalVersion(root);
+        if (!globalIsOlder(installed, version))
+            return { entry: globalEntry(root), viaNpx: false };
+        const from = installed ?? "an unknown version";
+        const update = `npm install -g ${spec}`;
+        if (noInstall) {
+            if (!quiet)
+                console.error(`diffninja: the global install is ${from}, older than this setup (${version}); update it with ${update}.`);
+        }
+        else if (dryRun) {
+            if (!quiet)
+                console.log(`diffninja: dry run: would update the global install from ${from} to ${version} (${update}).`);
+        }
+        else {
+            if (!quiet)
+                console.log(`diffninja: updating the global install from ${from} to ${version} (${update})...`);
+            const updated = await installGlobal(npm, spec);
+            const updatedRoot = updated ? await globalRoot(npm) : undefined;
+            if (updatedRoot !== undefined && globalEntryExists(updatedRoot))
+                return { entry: globalEntry(updatedRoot), viaNpx: false };
+            if (!globalEntryExists(root)) {
+                if (!quiet)
+                    console.error("diffninja: global update failed and left no install; registering npx-based entries instead.");
+                return { entry: npxEntry(process.platform, version), viaNpx: true };
+            }
+            if (!quiet)
+                console.error(`diffninja: update failed; the global install is still ${globalVersion(root) ?? from}. Update it with ${update}.`);
+        }
         return { entry: globalEntry(root), viaNpx: false };
+    }
     if (dryRun) {
         if (!noInstall && root !== undefined) {
             if (!quiet)
-                console.log("diffninja: dry run: would install the package globally (npm install -g diffninja).");
+                console.log(`diffninja: dry run: would install the package globally (npm install -g ${spec}).`);
             return { entry: globalEntry(root), viaNpx: false };
         }
         if (!quiet)
             console.error("diffninja: dry run: global install unavailable; would register npx-based entries instead.");
-        return { entry: npxEntry(), viaNpx: true };
+        return { entry: npxEntry(process.platform, version), viaNpx: true };
     }
     if (!noInstall) {
         if (!quiet)
-            console.log("diffninja: installing the package globally (npm install -g diffninja)...");
-        let installed = false;
-        try {
-            installed = await npm.installG();
-        }
-        catch {
-            installed = false;
-        }
-        if (installed) {
+            console.log(`diffninja: installing the package globally (npm install -g ${spec})...`);
+        if (await installGlobal(npm, spec)) {
             const installedRoot = await globalRoot(npm);
             if (installedRoot !== undefined && globalEntryExists(installedRoot)) {
                 return { entry: globalEntry(installedRoot), viaNpx: false };
@@ -160,7 +227,7 @@ async function resolveEntry(noInstall, npm, quiet, dryRun) {
     }
     if (!quiet)
         console.error("diffninja: global install unavailable; registering npx-based entries instead.");
-    return { entry: npxEntry(), viaNpx: true };
+    return { entry: npxEntry(process.platform, version), viaNpx: true };
 }
 function findOnPath(name, pathDirs) {
     const candidates = process.platform === "win32" ? [name, `${name}.cmd`, `${name}.exe`] : [name];
@@ -486,10 +553,11 @@ export async function runSetup(options = {}, deps = {}) {
     const quiet = options.quiet === true;
     const uninstall = options.uninstall === true;
     const dryRun = options.dryRun === true;
+    const version = deps.version ?? packageVersion();
     let entry;
     let viaNpx = false;
     if (!uninstall) {
-        const resolved = await resolveEntry(options.noInstall === true, deps.npm ?? realNpm, quiet, dryRun);
+        const resolved = await resolveEntry(options.noInstall === true, deps.npm ?? realNpm, quiet, dryRun, version);
         entry = resolved.entry;
         viaNpx = resolved.viaNpx;
     }
@@ -545,5 +613,5 @@ export async function runSetup(options = {}, deps = {}) {
             console.log("note: pi needs the pi-mcp-extension for MCP support (pi install npm:pi-mcp-extension)");
         }
     }
-    return { entry: entry ?? npxEntry(), viaNpx, clis: reports };
+    return { entry: entry ?? npxEntry(process.platform, version), viaNpx, clis: reports };
 }

package/dist/review/types.d.ts

@@ -2,6 +2,7 @@ import type { PullRequestIntent, ReviewEvidence } from "./evidence-types.js";
 import type { ChangeFacts } from "./change-facts.js";
 import type { ReviewQuestion } from "./questions.js";
 import type { HunkHistory, ProjectContext } from "./history.js";
+import type { AgentExplanation, ExplainedFunction } from "./explanation.js";
 export type ReviewStatus = "attention" | "uncertain" | "low" | "passed";
 /**
  * Structural status for a call-flow node. The engine only knows `same`,
@@ -184,6 +185,20 @@ export interface ReviewReport {
      * agent's reading rather than a verified claim.
      */
     agentSummary?: AgentSummary;
+    /**
+     * Every function a reader meets in this report (around the hunks and in the
+     * call flows), each with a stable `<file>#<name>` id, for the reviewing agent
+     * to explain in business terms. Empty for a patch, which resolves none;
+     * absent only on a report assembled by hand, which counts as empty.
+     */
+    functions?: ExplainedFunction[];
+    /**
+     * The reviewing agent's business explanation: a plain purpose for every
+     * listed function, the processes the change touches as steps and decisions,
+     * and the business rules it adds, changes, or removes. Attributed to the
+     * client that wrote it; never generated by diffninja.
+     */
+    agentExplanation?: AgentExplanation;
     /**
      * Local repository context for a git-range review: prior reverts, contributor
      * guidelines, and sibling-file conventions. Absent for a patch.

package/dist/review/version.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The version of the running diffninja package, read from its own
+ * `package.json`. Both layouts put it two levels up: `src/review/` in a
+ * checkout and `dist/review/` in the published package, which always ships
+ * `package.json`.
+ */
+export declare function packageVersion(): string;
+/**
+ * Compare two `major.minor.patch` versions: negative when `left` is older,
+ * zero when equal, positive when newer. A prerelease sorts before its release;
+ * two prereleases of one release compare by their tags as text. Undefined when
+ * either is not a version.
+ */
+export declare function compareVersions(left: string, right: string): number | undefined;

package/dist/review/version.js

@@ -0,0 +1,44 @@
+/**
+ * The version of the running diffninja package, read from its own
+ * `package.json`. Both layouts put it two levels up: `src/review/` in a
+ * checkout and `dist/review/` in the published package, which always ships
+ * `package.json`.
+ */
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+const manifestSchema = z.object({ version: z.string() });
+let cached;
+export function packageVersion() {
+    cached ??= manifestSchema.parse(JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"))).version;
+    return cached;
+}
+/**
+ * Compare two `major.minor.patch` versions: negative when `left` is older,
+ * zero when equal, positive when newer. A prerelease sorts before its release;
+ * two prereleases of one release compare by their tags as text. Undefined when
+ * either is not a version.
+ */
+export function compareVersions(left, right) {
+    const a = parseVersion(left);
+    const b = parseVersion(right);
+    if (a === undefined || b === undefined)
+        return undefined;
+    for (let index = 0; index < 3; index += 1) {
+        const difference = a.core[index] - b.core[index];
+        if (difference !== 0)
+            return difference;
+    }
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (a.prerelease === undefined)
+        return 1;
+    if (b.prerelease === undefined)
+        return -1;
+    return a.prerelease < b.prerelease ? -1 : 1;
+}
+function parseVersion(text) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(text.trim());
+    if (match === null)
+        return undefined;
+    return { core: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease: match[4] };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffninja",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Local, deterministic PR review for coding agents over MCP: call flows, change facts, and a human review workspace",
   "type": "module",
   "exports": {