@jam-mcp/server 1.4.6 → 1.5.0

package/README.md

@@ -74,10 +74,10 @@ auth login   Store Jira credentials in this user's OS secret store
 runtime      Show or change which JAM build this machine runs
 ```
 
-Written out, that is `npx --yes @jam-mcp/launcher@1.4.6 doctor`, or just `jam
+Written out, that is `npx --yes @jam-mcp/launcher@1.5.0 doctor`, or just `jam
 doctor` if you took the launcher's optional global install. Starting from
 nothing — no install, no runtime chosen yet — use
-`npx --yes @jam-mcp/bootstrap@1.4.6 init` instead.
+`npx --yes @jam-mcp/bootstrap@1.5.0 init` instead.
 
 Credentials come from the process environment or this user's OS secret store —
 never from a repository file — and never appear in logs, telemetry, or tool

package/dist/bootstrap/host-mcp.d.ts

@@ -54,6 +54,7 @@ export declare const defaultHostRunner: HostRunner;
 export declare const persistentHostRunner: HostRunner;
 export declare function hostRegistration(id: HostId, options?: {
     bare?: boolean;
+    version?: string;
 }): HostCommand | undefined;
 /** The removal that has to precede re-registering an entry this host already has. */
 export declare function hostUnregistration(id: HostId): HostCommand | undefined;

package/dist/bootstrap/host-mcp.js

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
-import { JAM_MCP_ENTRY } from "./mcp-config-merger.js";
+import { LAUNCHER_PACKAGE } from "@jam-mcp/launcher";
+import { JAM_MCP_ENTRY, LAUNCHER_PACKAGE_SPEC } from "./mcp-config-merger.js";
 import { shellInvocation, stripPackageRunnerPath } from "./shell-command.js";
 /**
  * These boot a whole Node CLI, and Claude Code health-checks every configured
@@ -75,8 +76,18 @@ export function hostRegistration(id, options = {}) {
     const adapter = ADAPTERS.find((a) => a.id === id);
     if (!adapter)
         return undefined;
-    if (!options.bare)
-        return adapter.register;
+    if (!options.bare) {
+        // `jam update` registers a version this build is not - that is the whole
+        // point of an update. Only the pin moves; the rest of the argv is the same
+        // line setup writes, so the two cannot drift into different registrations.
+        if (!options.version)
+            return adapter.register;
+        const pinned = `${LAUNCHER_PACKAGE}@${options.version}`;
+        return {
+            command: adapter.register.command,
+            args: adapter.register.args.map((arg) => (arg === LAUNCHER_PACKAGE_SPEC ? pinned : arg)),
+        };
+    }
     const at = adapter.register.args.indexOf("--");
     return { command: adapter.register.command, args: [...adapter.register.args.slice(0, at), ...LAUNCH_BARE] };
 }

package/dist/bootstrap/mcp-config-merger.d.ts

@@ -13,7 +13,7 @@ import { LAUNCHER_PACKAGE_SPEC } from "@jam-mcp/launcher";
 export { LAUNCHER_PACKAGE_SPEC };
 export declare const JAM_MCP_ENTRY: {
     readonly command: "npx";
-    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.4.6", "serve"];
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.5.0", "serve"];
 };
 /**
  * Recognise wiring from before the launcher existed: a hard-coded `node` path

package/dist/cli/update.d.ts

@@ -0,0 +1,74 @@
+import { type HostId, type HostRunner } from "../bootstrap/host-mcp.js";
+/**
+ * `jam update` - move this machine to the published release without redoing setup.
+ *
+ * What actually goes stale here is not a directory. JAM is launched by the
+ * host from a registration line, and that line carries an exact pin:
+ *
+ *   jam: npx --yes @jam-mcp/launcher@1.4.5 serve
+ *
+ * A newer JAM on the registry changes nothing until that line moves. Right
+ * after 1.4.6 was published, this machine measured
+ * `registration: HOST_REGISTRATION_STALE (registered 1.4.5)` - the agent was
+ * still talking to the previous server. The command that fixed it was
+ * `jam setup --agent`, which also binds the project, re-detects credentials
+ * and re-plans everything else. Re-running setup is not what "update" means,
+ * so this path never calls it.
+ *
+ * The order is the same one ASC uses, and for the same reason: the new build
+ * is proven to answer *before* the registration is pointed at it. Nothing is
+ * removed first - a failed update leaves the machine running what it was
+ * running.
+ */
+export type UpdateStep = "install" | "verify-install" | "switch-registration" | "verify-health";
+export declare const UPDATE_ORDER: readonly UpdateStep[];
+export type UpdateState = 
+/** Every registration this machine has runs the published release. */
+"CURRENT" | "UPDATE_AVAILABLE"
+/** A registration exists whose version cannot be read - it may run anything. */
+ | "BROKEN"
+/** The registry could not be asked. Nothing is claimed about being up to date. */
+ | "UNKNOWN";
+export type HostPlan = {
+    id: HostId;
+    from?: string;
+    /** A bare `jam serve` entry: the version lives in the global install, not the line. */
+    bare: boolean;
+    action: "repin" | "none" | "unreadable";
+};
+export type JamUpdatePlan = {
+    state: UpdateState;
+    latest?: string;
+    running: string;
+    hosts: HostPlan[];
+    steps: readonly UpdateStep[];
+    detail?: string;
+};
+export type HostFacts = {
+    id: HostId;
+    cliAvailable: boolean;
+    hasJamEntry: boolean;
+    entryVersion?: string;
+    entryBare?: boolean;
+};
+/**
+ * Decide, from what was measured. Pure - it runs nothing and writes nothing.
+ *
+ * A host with no `jam` entry is left alone. Registering JAM somewhere it was
+ * never registered is adoption, not an update, and `jam setup` is where the
+ * person says they want that.
+ */
+export declare function planJamUpdate(input: {
+    latest?: string;
+    hosts: HostFacts[];
+}): JamUpdatePlan;
+export declare function updateLine(plan: JamUpdatePlan): string;
+export type UpdateOptions = {
+    json?: boolean;
+    /** Injected by tests. Nothing here may reach a real host CLI or npm unasked. */
+    run?: HostRunner;
+    /** Injected by tests so a plan never depends on the registry. */
+    latest?: () => string | undefined;
+    hosts?: () => HostFacts[];
+};
+export declare function jamUpdateCommand(command: string | undefined, options?: UpdateOptions): Promise<number>;

package/dist/cli/update.js

@@ -0,0 +1,233 @@
+import { LAUNCHER_PACKAGE, SERVER_VERSION } from "@jam-mcp/launcher";
+import { spawnSync } from "node:child_process";
+import { detectHosts, hostRegistration, hostUnregistration, } from "../bootstrap/host-mcp.js";
+export const UPDATE_ORDER = [
+    "install",
+    "verify-install",
+    "switch-registration",
+    "verify-health",
+];
+/**
+ * Decide, from what was measured. Pure - it runs nothing and writes nothing.
+ *
+ * A host with no `jam` entry is left alone. Registering JAM somewhere it was
+ * never registered is adoption, not an update, and `jam setup` is where the
+ * person says they want that.
+ */
+export function planJamUpdate(input) {
+    const running = SERVER_VERSION;
+    const registered = input.hosts.filter((host) => host.cliAvailable && host.hasJamEntry);
+    if (!input.latest) {
+        return {
+            state: "UNKNOWN",
+            running,
+            hosts: [],
+            steps: [],
+            detail: "the registry could not be asked - nothing is claimed about being up to date",
+        };
+    }
+    const hosts = registered.map((host) => ({
+        id: host.id,
+        ...(host.entryVersion ? { from: host.entryVersion } : {}),
+        bare: host.entryBare === true,
+        action: host.entryVersion === undefined
+            ? "unreadable"
+            : host.entryVersion === input.latest
+                ? "none"
+                : "repin",
+    }));
+    // An entry whose version cannot be read is not "current" - it is a line
+    // running something nobody measured. Say that instead of moving it silently.
+    if (hosts.some((host) => host.action === "unreadable")) {
+        return {
+            state: "BROKEN",
+            latest: input.latest,
+            running,
+            hosts,
+            steps: [...UPDATE_ORDER],
+            detail: "a registration exists whose version could not be read",
+        };
+    }
+    if (hosts.every((host) => host.action === "none")) {
+        return { state: "CURRENT", latest: input.latest, running, hosts, steps: [] };
+    }
+    return { state: "UPDATE_AVAILABLE", latest: input.latest, running, hosts, steps: [...UPDATE_ORDER] };
+}
+export function updateLine(plan) {
+    switch (plan.state) {
+        case "CURRENT":
+            return `Up to date - JAM ${plan.latest} is registered.`;
+        case "UPDATE_AVAILABLE": {
+            const moving = plan.hosts.filter((host) => host.action === "repin");
+            return `Update available - ${plan.latest}: ${moving
+                .map((host) => `${host.id} runs ${host.from}`)
+                .join(", ")}`;
+        }
+        case "BROKEN":
+        case "UNKNOWN":
+            return `${plan.state}: ${plan.detail ?? "(no detail)"}`;
+    }
+}
+/** A process runner with room for an install. The host runner's 20s is not enough for npm. */
+const defaultRunner = ({ command, args }) => {
+    const result = spawnSync(command, args, {
+        encoding: "utf8",
+        timeout: 180_000,
+        shell: process.platform === "win32",
+    });
+    if (result.error)
+        return { status: null, failed: true, stdout: "" };
+    return { status: result.status, failed: false, stdout: result.stdout ?? "" };
+};
+export async function jamUpdateCommand(command, options = {}) {
+    if (command !== undefined && command !== "check" && command !== "plan") {
+        process.stderr.write(`Unknown update command: ${command}\nUsage: jam update [check|plan] [--json]\n`);
+        return 1;
+    }
+    const run = options.run ?? defaultRunner;
+    const latest = (options.latest ?? (() => registryLatest(run)))();
+    const facts = (options.hosts ?? (() => detectHosts(run)))();
+    const plan = planJamUpdate({ ...(latest ? { latest } : {}), hosts: facts });
+    if (command === "check" || command === "plan") {
+        emit(plan, options);
+        return 0;
+    }
+    if (plan.steps.length === 0) {
+        emit(plan, options);
+        return plan.state === "CURRENT" ? 0 : 1;
+    }
+    return apply(plan, run, options);
+}
+function emit(plan, options) {
+    if (options.json)
+        process.stdout.write(`${JSON.stringify({ package: LAUNCHER_PACKAGE, ...plan }, null, 2)}\n`);
+    else
+        process.stdout.write(`${updateLine(plan)}\n`);
+}
+/** What the registry has. undefined when it could not be asked - never a guess. */
+function registryLatest(run) {
+    const result = run({ command: "npm", args: ["view", LAUNCHER_PACKAGE, "version"] });
+    if (result.failed || result.status !== 0)
+        return undefined;
+    const version = result.stdout.trim();
+    return /^\d+\.\d+\.\d+/.test(version) ? version : undefined;
+}
+/**
+ * Does that version actually answer?
+ *
+ * `runtime status --json` is the cheapest honest question: it resolves the
+ * runtime the registered entry would resolve, and needs no bound project. A
+ * pin that cannot answer here is one the host would fail to start - which is
+ * exactly what must not be registered.
+ */
+function launcherAnswers(run, version, bare) {
+    const result = bare
+        ? run({ command: "jam", args: ["runtime", "status", "--json"] })
+        : run({ command: "npx", args: ["--yes", `${LAUNCHER_PACKAGE}@${version}`, "runtime", "status", "--json"] });
+    if (result.failed || result.status !== 0)
+        return undefined;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        return typeof parsed.version === "string" ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function apply(plan, run, options) {
+    const target = plan.latest;
+    process.stdout.write(`${updateLine(plan)}\n`);
+    const moving = plan.hosts.filter((host) => host.action !== "none");
+    // A bare entry runs the global executable, so that is what has to move.
+    // An npx pin is fetched at launch; verifying it is what "install" means there.
+    if (moving.some((host) => host.bare)) {
+        const installed = run({ command: "npm", args: ["install", "-g", `${LAUNCHER_PACKAGE}@${target}`] });
+        if (installed.failed || installed.status !== 0) {
+            process.stderr.write(`install failed: npm install -g ${LAUNCHER_PACKAGE}@${target}\n`);
+            // Nothing was re-registered. The machine still runs what it ran.
+            return 1;
+        }
+    }
+    for (const host of moving) {
+        const answered = launcherAnswers(run, target, host.bare);
+        if (answered !== target) {
+            process.stderr.write(`verify failed: ${target} did not answer as ${target}${answered ? ` (got ${answered})` : ""} - registration left as it is\n`);
+            return 1;
+        }
+    }
+    process.stdout.write(`verified: ${LAUNCHER_PACKAGE}@${target} answers\n`);
+    for (const host of moving) {
+        // `mcp add` over an existing entry changes nothing on Claude Code - it
+        // answers "already exists". The removal is what makes the re-pin land.
+        if (!host.bare) {
+            const remove = hostUnregistration(host.id);
+            if (remove)
+                run(remove);
+        }
+        const register = hostRegistration(host.id, { ...(host.bare ? { bare: true } : { version: target }) });
+        if (!register)
+            continue;
+        const result = run(register);
+        if (result.failed || result.status !== 0) {
+            process.stderr.write(`switch failed on ${host.id}\n`);
+            return rollback(plan, host, run);
+        }
+        process.stdout.write(`registered: ${host.id} -> ${target}\n`);
+    }
+    // Read it back. A registration JAM could not verify is never reported as done.
+    const after = (options.hosts ?? (() => detectHosts(run)))();
+    const stale = after.filter((host) => moving.some((m) => m.id === host.id) && host.entryVersion !== target);
+    if (stale.length > 0) {
+        process.stderr.write(`health: ${stale.map((host) => `${host.id} still runs ${host.entryVersion ?? "?"}`).join(", ")}\n`);
+        return 1;
+    }
+    // A registration that points at a build which cannot read Jira is not a
+    // finished update. `doctor` is the existing health axis - config, credentials
+    // and one live read - so it is asked here rather than reimplemented.
+    const health = doctorVerdict(run, target, moving.some((host) => host.bare));
+    if (health !== "ready") {
+        process.stderr.write(`doctor: ${health} - rolling back\n`);
+        const first = moving[0];
+        return first ? rollback(plan, first, run) : 1;
+    }
+    process.stdout.write(`JAM ${target} is registered, doctor ready.\n`);
+    return 0;
+}
+/**
+ * What `jam doctor --json` says about the build now registered.
+ *
+ * Run through the same entry the host would run, so this measures the thing
+ * that was just registered rather than the process doing the registering.
+ */
+function doctorVerdict(run, version, bare) {
+    const result = bare
+        ? run({ command: "jam", args: ["doctor", "--json"] })
+        : run({ command: "npx", args: ["--yes", `${LAUNCHER_PACKAGE}@${version}`, "doctor", "--json"] });
+    if (result.failed)
+        return "could not be run";
+    try {
+        const parsed = JSON.parse(result.stdout);
+        return typeof parsed.status === "string" ? parsed.status : "unreadable";
+    }
+    catch {
+        return result.status === 0 ? "ready" : "unreadable";
+    }
+}
+/** Put back the pin that was there. Only possible when it was readable. */
+function rollback(plan, host, run) {
+    if (!host.from || host.bare) {
+        process.stderr.write(`Nothing to roll back to on ${host.id} - re-register with \`jam setup --agent\`.\n`);
+        return 1;
+    }
+    const remove = hostUnregistration(host.id);
+    if (remove)
+        run(remove);
+    const back = hostRegistration(host.id, { version: host.from });
+    const result = back ? run(back) : undefined;
+    if (result && !result.failed && result.status === 0) {
+        process.stderr.write(`rolled back - ${host.id} runs ${host.from} again.\n`);
+        return 1;
+    }
+    process.stderr.write(`rollback failed on ${host.id} - re-register with \`jam setup --agent\`.\n`);
+    return 1;
+}

package/dist/cli-entry.d.ts

@@ -3,5 +3,5 @@
  * points (notably @jam-mcp/bootstrap) can forward to exactly these commands
  * instead of reimplementing them.
  */
-export declare const USAGE = "jam - Jira Agent MCP\n\nUsage:\n  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)\n  jam doctor              Diagnose config, credentials and Jira connectivity\n  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]\n                          Wire up this project and run doctor. Binds it to you\n                          alone, writing nothing to the repository; --shared\n                          adopts JAM for the team (project.yaml, .mcp.json)\n  jam runtime             Show which JAM build this machine runs\n  jam runtime use package | development <path>\n                          Change it (writes ~/.jam/config.yaml only, never a project)\n  jam auth login          Store Jira credentials in this user's OS secret store\n  jam auth logout         Remove them again\n\nFor coding agents and scripts (stdout is JSON only, never prompts):\n  jam setup --agent       One shot: detect, plan, apply what is safe, verify\n  jam setup plan --json   Report what setup would change, changing nothing\n  jam setup apply --non-interactive --json\n                          Execute the plan\n  jam doctor --json       Health check as structured output\n  jam auth status --json  Whether Jira credentials are configured (never their value)\n  jam jira search <jql> [--scope preview|complete]\n  jam jira context <KEY> [KEY...]\n  jam jira full <KEY> [KEY...]\n                          Read Jira from the shell - the same reads the MCP\n                          tools do, for a session that cannot see them yet\n\nEnvironment:\n  JIRA_BASE_URL     https://your-site.atlassian.net\n  JIRA_EMAIL        Atlassian account email\n  JIRA_API_TOKEN    Atlassian API token\n  JAM_PROJECT_KEY   Jira project key, used by `jam setup`/`jam serve` when no\n                     .jira-agent/project.yaml exists yet\n\nCredentials and JAM_PROJECT_KEY are read from the current shell's environment\nfirst, then (on Windows) from the User environment - so a value set with\n`setx` works without opening a new terminal.\n";
+export declare const USAGE = "jam - Jira Agent MCP\n\nUsage:\n  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)\n  jam doctor              Diagnose config, credentials and Jira connectivity\n  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]\n                          Wire up this project and run doctor. Binds it to you\n                          alone, writing nothing to the repository; --shared\n                          adopts JAM for the team (project.yaml, .mcp.json)\n  jam update              Move this machine's registration to the published release\n  jam update check        What is registered, what is published (changes nothing)\n  jam runtime             Show which JAM build this machine runs\n  jam runtime use package | development <path>\n                          Change it (writes ~/.jam/config.yaml only, never a project)\n  jam auth login          Store Jira credentials in this user's OS secret store\n  jam auth logout         Remove them again\n\nFor coding agents and scripts (stdout is JSON only, never prompts):\n  jam setup --agent       One shot: detect, plan, apply what is safe, verify\n  jam setup plan --json   Report what setup would change, changing nothing\n  jam setup apply --non-interactive --json\n                          Execute the plan\n  jam doctor --json       Health check as structured output\n  jam auth status --json  Whether Jira credentials are configured (never their value)\n  jam jira search <jql> [--scope preview|complete]\n  jam jira context <KEY> [KEY...]\n  jam jira full <KEY> [KEY...]\n                          Read Jira from the shell - the same reads the MCP\n                          tools do, for a session that cannot see them yet\n\nEnvironment:\n  JIRA_BASE_URL     https://your-site.atlassian.net\n  JIRA_EMAIL        Atlassian account email\n  JIRA_API_TOKEN    Atlassian API token\n  JAM_PROJECT_KEY   Jira project key, used by `jam setup`/`jam serve` when no\n                     .jira-agent/project.yaml exists yet\n\nCredentials and JAM_PROJECT_KEY are read from the current shell's environment\nfirst, then (on Windows) from the User environment - so a value set with\n`setx` works without opening a new terminal.\n";
 export declare function runJamCommand(argv: string[]): Promise<number>;

package/dist/cli-entry.js

@@ -3,6 +3,7 @@ import { doctor } from "./cli/doctor.js";
 import { showRuntime, useRuntime } from "./cli/runtime.js";
 import { serve } from "./cli/serve.js";
 import { setup } from "./cli/setup.js";
+import { jamUpdateCommand } from "./cli/update.js";
 import { runSetupWizard } from "./cli/setup-wizard.js";
 import { reportPromptError, Ui } from "./cli/ui.js";
 import { authStatusCommand, doctorJsonCommand, setupAgentCommand, setupApplyCommand, setupPlanCommand, } from "./cli/agent-api.js";
@@ -21,6 +22,8 @@ Usage:
                           Wire up this project and run doctor. Binds it to you
                           alone, writing nothing to the repository; --shared
                           adopts JAM for the team (project.yaml, .mcp.json)
+  jam update              Move this machine's registration to the published release
+  jam update check        What is registered, what is published (changes nothing)
   jam runtime             Show which JAM build this machine runs
   jam runtime use package | development <path>
                           Change it (writes ~/.jam/config.yaml only, never a project)
@@ -99,6 +102,12 @@ export async function runJamCommand(argv) {
             // The wizard can ask; the plain path never does.
             return rest.includes("--non-interactive") ? setup(common) : runSetupWizard(common);
         }
+        case "update":
+            // Not `setup` again: setup re-plans the project binding, credentials and
+            // everything else. An update moves the registration pin and nothing more.
+            return jamUpdateCommand(rest[0] === "--json" ? undefined : rest[0], {
+                json: rest.includes("--json"),
+            });
         case "runtime": {
             const json = rest.includes("--json");
             if (rest[0] === "use")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jam-mcp/server",
-  "version": "1.4.6",
+  "version": "1.5.0",
   "description": "JAM (Jira Agent MCP) - agent-facing Jira access layer: MCP server, setup core, and CLI",
   "keywords": [
     "jira",
@@ -41,7 +41,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jam-mcp/launcher": "1.4.6",
+    "@jam-mcp/launcher": "1.5.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"