@jam-mcp/server 1.5.0 → 1.6.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.5.0 doctor`, or just `jam
+Written out, that is `npx --yes @jam-mcp/launcher@1.6.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.5.0 init` instead.
+`npx --yes @jam-mcp/bootstrap@1.6.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/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.5.0", "serve"];
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.6.0", "serve"];
 };
 /**
  * Recognise wiring from before the launcher existed: a hard-coded `node` path

package/dist/cli/lifecycle.d.ts

@@ -0,0 +1,66 @@
+import { type HostId, type HostRunner, type HostState } from "../bootstrap/host-mcp.js";
+export type LifecycleOptions = {
+    json?: boolean;
+    /** Injected by tests. Nothing here may reach a real host CLI or npm unasked. */
+    run?: HostRunner;
+    hosts?: () => HostState[];
+};
+export type RefreshHostPlan = {
+    id: HostId;
+    from?: string;
+    bare: boolean;
+    action: "repin" | "none";
+};
+export type RefreshPlan = {
+    /** The version this build is. `refresh` never moves off it - that is `update`. */
+    version: string;
+    hosts: RefreshHostPlan[];
+    steps: readonly string[];
+};
+/**
+ * What `refresh` would converge. Pure: it runs nothing and writes nothing.
+ *
+ * The scope is deliberately small. A registration that points at a different
+ * launcher than this build is what goes stale here. The project binding, the
+ * credentials, `~/.jam/config.yaml` and every byte of Jira data are outside
+ * it - re-deciding those is `setup`, and calling it "refresh" is how a person
+ * loses a binding they never asked to change.
+ */
+export declare function planRefresh(hosts: readonly HostState[], version?: string): RefreshPlan;
+export declare function refreshLine(plan: RefreshPlan): string;
+/**
+ * `jam refresh` - keep the version, make the registration match it again.
+ *
+ * Nothing is removed before the replacement is known to work, which is the
+ * same order `update` uses and for the same reason: a failed refresh leaves
+ * the machine running what it was running.
+ */
+export declare function jamRefreshCommand(command: string | undefined, options?: LifecycleOptions): Promise<number>;
+export type UninstallPlan = {
+    /** Registrations that would be removed. */
+    hosts: HostId[];
+    /** Whether a global launcher install would be removed with it. */
+    runtime: string | null;
+    preserve: string[];
+};
+/**
+ * `jam uninstall` - remove what JAM installed, keep what is the person's.
+ *
+ * Removed: the MCP registrations JAM wrote, and the global launcher when one
+ * is installed. Kept: `~/.jam` in full - the project bindings, the runtime
+ * choice and the credentials in the OS secret store. There is no purge here
+ * on purpose: nothing yet needs a command that destroys those, and an
+ * irreversible one that nobody asked for is worse than a missing one.
+ */
+export declare function planUninstall(hosts: readonly HostState[], installed: string | null): UninstallPlan;
+export declare function jamUninstallCommand(command: string | undefined, options?: LifecycleOptions): Promise<number>;
+/**
+ * `jam status` - the first place a person asks what is going on.
+ *
+ * This is `doctor`'s user-facing role under the name both products use. The
+ * judgement is not reimplemented: the same health gate and the same per-axis
+ * verdicts answer here, so the two commands can never disagree.
+ */
+export declare function jamStatusCommand(options?: {
+    json?: boolean;
+}): Promise<number>;

package/dist/cli/lifecycle.js

@@ -0,0 +1,233 @@
+import { LAUNCHER_PACKAGE, SERVER_VERSION } from "@jam-mcp/launcher";
+import { spawnSync } from "node:child_process";
+import { doctorJsonCommand } from "./agent-api.js";
+import { doctor } from "./doctor.js";
+import { detectHosts, hostRegistration, hostUnregistration, } from "../bootstrap/host-mcp.js";
+/**
+ * The lifecycle words JAM shares with ASC: `refresh` and `uninstall`.
+ *
+ * The two products answer to the same vocabulary because a person should not
+ * have to remember which one uses which verb:
+ *
+ *   setup      make it usable for the first time
+ *   status     what is configured, what works, what is blocked
+ *   update     move to a newer published release
+ *   refresh    keep the version, re-converge what this build registered
+ *   uninstall  remove the product; the person's state stays
+ *   runtime    which build this machine actually runs
+ *
+ * What is different is ownership, and that stays different. JAM is the Jira
+ * access layer: it has no execution mode, no approval path and no session
+ * model. A Jira write still travels ASC's decision path and lands through
+ * JAM's own write plan/apply - this file does not change that.
+ */
+/** A runner with room for npm. The host runner's 20s is not enough for an install. */
+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 ?? "" };
+};
+/**
+ * What `refresh` would converge. Pure: it runs nothing and writes nothing.
+ *
+ * The scope is deliberately small. A registration that points at a different
+ * launcher than this build is what goes stale here. The project binding, the
+ * credentials, `~/.jam/config.yaml` and every byte of Jira data are outside
+ * it - re-deciding those is `setup`, and calling it "refresh" is how a person
+ * loses a binding they never asked to change.
+ */
+export function planRefresh(hosts, version = SERVER_VERSION) {
+    const registered = hosts.filter((host) => host.cliAvailable && host.hasJamEntry);
+    const plans = registered.map((host) => ({
+        id: host.id,
+        ...(host.entryVersion ? { from: host.entryVersion } : {}),
+        bare: host.entryBare === true,
+        // A bare entry runs the global executable, so its line is already whatever
+        // that executable is. Only a pinned line can point somewhere else.
+        action: host.entryBare === true || host.entryVersion === version ? "none" : "repin",
+    }));
+    const moving = plans.filter((host) => host.action === "repin");
+    return {
+        version,
+        hosts: plans,
+        steps: moving.length === 0 ? [] : ["switch-registration", "verify"],
+    };
+}
+export function refreshLine(plan) {
+    const moving = plan.hosts.filter((host) => host.action === "repin");
+    if (plan.hosts.length === 0)
+        return "No host has a JAM registration - `jam setup` is what adds one.";
+    return moving.length === 0
+        ? `Registration is current - JAM ${plan.version}. Version unchanged.`
+        : `Would re-register: ${moving.map((host) => `${host.id} runs ${host.from ?? "?"}`).join(", ")}`;
+}
+/**
+ * `jam refresh` - keep the version, make the registration match it again.
+ *
+ * Nothing is removed before the replacement is known to work, which is the
+ * same order `update` uses and for the same reason: a failed refresh leaves
+ * the machine running what it was running.
+ */
+export async function jamRefreshCommand(command, options = {}) {
+    if (command !== undefined && command !== "check" && command !== "plan") {
+        process.stderr.write(`Unknown refresh command: ${command}\nUsage: jam refresh [check|plan] [--json]\n`);
+        return 1;
+    }
+    const run = options.run ?? defaultRunner;
+    const hosts = (options.hosts ?? (() => detectHosts(run)))();
+    const plan = planRefresh(hosts);
+    if (command === "check" || command === "plan") {
+        if (options.json)
+            process.stdout.write(`${JSON.stringify({ package: LAUNCHER_PACKAGE, ...plan }, null, 2)}\n`);
+        else
+            process.stdout.write(`${refreshLine(plan)}\n`);
+        return 0;
+    }
+    if (plan.steps.length === 0) {
+        if (options.json)
+            process.stdout.write(`${JSON.stringify({ package: LAUNCHER_PACKAGE, ...plan, changed: [] }, null, 2)}\n`);
+        else
+            process.stdout.write(`${refreshLine(plan)}\n`);
+        return 0;
+    }
+    const changed = [];
+    for (const host of plan.hosts.filter((h) => h.action === "repin")) {
+        // `mcp add` over an existing entry changes nothing on Claude Code - it
+        // answers "already exists". The removal is what makes the re-pin land.
+        const remove = hostUnregistration(host.id);
+        if (remove)
+            run(remove);
+        const register = hostRegistration(host.id, { version: plan.version });
+        if (!register)
+            continue;
+        const result = run(register);
+        if (result.failed || result.status !== 0) {
+            process.stderr.write(`refresh failed on ${host.id} - re-register with \`jam setup --agent\`.\n`);
+            return 1;
+        }
+        changed.push(host.id);
+    }
+    // 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) => changed.includes(host.id) && host.entryBare !== true && host.entryVersion !== plan.version);
+    if (stale.length > 0) {
+        process.stderr.write(`health: ${stale.map((host) => `${host.id} still runs ${host.entryVersion ?? "?"}`).join(", ")}\n`);
+        return 1;
+    }
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify({ package: LAUNCHER_PACKAGE, ...plan, changed }, null, 2)}\n`);
+    }
+    else {
+        for (const id of changed)
+            process.stdout.write(`registered: ${id} -> ${plan.version}\n`);
+        process.stdout.write(`JAM ${plan.version} is registered. Version unchanged.\n`);
+    }
+    return 0;
+}
+/**
+ * `jam uninstall` - remove what JAM installed, keep what is the person's.
+ *
+ * Removed: the MCP registrations JAM wrote, and the global launcher when one
+ * is installed. Kept: `~/.jam` in full - the project bindings, the runtime
+ * choice and the credentials in the OS secret store. There is no purge here
+ * on purpose: nothing yet needs a command that destroys those, and an
+ * irreversible one that nobody asked for is worse than a missing one.
+ */
+export function planUninstall(hosts, installed) {
+    return {
+        hosts: hosts.filter((host) => host.cliAvailable && host.hasJamEntry).map((host) => host.id),
+        runtime: installed,
+        preserve: [
+            "~/.jam/projects.yaml - which project each checkout is bound to",
+            "~/.jam/config.yaml - the runtime this machine chose",
+            "Jira credentials in the OS secret store",
+            "every .jira-agent/project.yaml a repository carries",
+        ],
+    };
+}
+export async function jamUninstallCommand(command, options = {}) {
+    if (command !== undefined && command !== "plan") {
+        process.stderr.write(`Unknown uninstall command: ${command}\nUsage: jam uninstall [plan] [--json]\n`);
+        return 1;
+    }
+    const run = options.run ?? defaultRunner;
+    const hosts = (options.hosts ?? (() => detectHosts(run)))();
+    const installed = globalLauncher(run);
+    const plan = planUninstall(hosts, installed);
+    if (command === "plan") {
+        if (options.json)
+            process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);
+        else {
+            process.stdout.write(plan.hosts.length === 0
+                ? "No host registration to remove.\n"
+                : `Would remove the JAM registration from: ${plan.hosts.join(", ")}\n`);
+            if (plan.runtime)
+                process.stdout.write(`Would remove ${LAUNCHER_PACKAGE}@${plan.runtime}\n`);
+            for (const kept of plan.preserve)
+                process.stdout.write(`Would keep: ${kept}\n`);
+        }
+        return 0;
+    }
+    let worst = 0;
+    for (const id of plan.hosts) {
+        const remove = hostUnregistration(id);
+        if (!remove)
+            continue;
+        const result = run(remove);
+        if (result.failed || result.status !== 0) {
+            process.stderr.write(`could not remove the registration from ${id}\n`);
+            worst = 1;
+            continue;
+        }
+        process.stdout.write(`removed: ${id} registration\n`);
+    }
+    if (plan.runtime) {
+        const removal = run({ command: "npm", args: ["uninstall", "-g", LAUNCHER_PACKAGE] });
+        if (removal.failed || removal.status !== 0) {
+            process.stderr.write(`could not remove ${LAUNCHER_PACKAGE} - run: npm uninstall -g ${LAUNCHER_PACKAGE}\n`);
+            worst = 1;
+        }
+        else {
+            process.stdout.write(`removed: ${LAUNCHER_PACKAGE}@${plan.runtime}\n`);
+        }
+    }
+    process.stdout.write("\nYour state stays:\n");
+    for (const kept of plan.preserve)
+        process.stdout.write(`  ${kept}\n`);
+    return worst;
+}
+/** The globally installed launcher version, or null when there is none. */
+function globalLauncher(run) {
+    const result = run({ command: "npm", args: ["ls", "-g", "--depth=0", "--json", LAUNCHER_PACKAGE] });
+    if (result.failed)
+        return null;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        return parsed.dependencies?.[LAUNCHER_PACKAGE]?.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `jam status` - the first place a person asks what is going on.
+ *
+ * This is `doctor`'s user-facing role under the name both products use. The
+ * judgement is not reimplemented: the same health gate and the same per-axis
+ * verdicts answer here, so the two commands can never disagree.
+ */
+export async function jamStatusCommand(options = {}) {
+    if (options.json)
+        return doctorJsonCommand();
+    process.stdout.write(`jam ${SERVER_VERSION}\n`);
+    const code = await doctor();
+    process.stdout.write(code === 0
+        ? "\nNext: nothing - reading Jira is ready. `jam update` when a newer release is out.\n"
+        : "\nNext: `jam setup` binds this project and stores what is missing. `jam refresh` only re-registers.\n");
+    return code;
+}

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 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 const USAGE = "jam - Jira Agent MCP\n\nLifecycle (the same words ASC uses)\n  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]\n                          Wire up this project and verify it. Binds it to you\n                          alone, writing nothing to the repository; --shared\n                          adopts JAM for the team (project.yaml, .mcp.json)\n  jam status              What is configured, what works, what is blocked\n  jam update              Move this machine's registration to the published release\n  jam refresh             Keep the version; re-register what this build owns\n  jam uninstall           Remove JAM's registrations; your bindings and credentials stay\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\nJira\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\nAuthentication\n  jam auth status [--json]  Whether Jira credentials are configured (never their value)\n  jam auth login            Store them 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 status --json       Health check as structured output\n  jam update check|plan [--json]\n  jam refresh check|plan [--json]\n  jam uninstall plan [--json]\n\nHost runtime\n  jam serve               Run the MCP server over stdio - this is what Claude\n                          Code and Codex launch. Not a command a person types.\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

@@ -4,6 +4,7 @@ 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 { jamRefreshCommand, jamStatusCommand, jamUninstallCommand } from "./cli/lifecycle.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";
@@ -15,34 +16,45 @@ import { runJiraRead } from "./cli/jira-read.js";
  */
 export const USAGE = `jam - Jira Agent MCP
 
-Usage:
-  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)
-  jam doctor              Diagnose config, credentials and Jira connectivity
+Lifecycle (the same words ASC uses)
   jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]
-                          Wire up this project and run doctor. Binds it to you
+                          Wire up this project and verify it. Binds it to you
                           alone, writing nothing to the repository; --shared
                           adopts JAM for the team (project.yaml, .mcp.json)
+  jam status              What is configured, what works, what is blocked
   jam update              Move this machine's registration to the published release
-  jam update check        What is registered, what is published (changes nothing)
+  jam refresh             Keep the version; re-register what this build owns
+  jam uninstall           Remove JAM's registrations; your bindings and credentials stay
   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)
-  jam auth login          Store Jira credentials in this user's OS secret store
-  jam auth logout         Remove them again
 
-For coding agents and scripts (stdout is JSON only, never prompts):
-  jam setup --agent       One shot: detect, plan, apply what is safe, verify
-  jam setup plan --json   Report what setup would change, changing nothing
-  jam setup apply --non-interactive --json
-                          Execute the plan
-  jam doctor --json       Health check as structured output
-  jam auth status --json  Whether Jira credentials are configured (never their value)
+Jira
   jam jira search <jql> [--scope preview|complete]
   jam jira context <KEY> [KEY...]
   jam jira full <KEY> [KEY...]
                           Read Jira from the shell - the same reads the MCP
                           tools do, for a session that cannot see them yet
 
+Authentication
+  jam auth status [--json]  Whether Jira credentials are configured (never their value)
+  jam auth login            Store them in this user's OS secret store
+  jam auth logout           Remove them again
+
+For coding agents and scripts (stdout is JSON only, never prompts):
+  jam setup --agent       One shot: detect, plan, apply what is safe, verify
+  jam setup plan --json   Report what setup would change, changing nothing
+  jam setup apply --non-interactive --json
+                          Execute the plan
+  jam status --json       Health check as structured output
+  jam update check|plan [--json]
+  jam refresh check|plan [--json]
+  jam uninstall plan [--json]
+
+Host runtime
+  jam serve               Run the MCP server over stdio - this is what Claude
+                          Code and Codex launch. Not a command a person types.
+
 Environment:
   JIRA_BASE_URL     https://your-site.atlassian.net
   JIRA_EMAIL        Atlassian account email
@@ -80,7 +92,12 @@ export async function runJamCommand(argv) {
     switch (command ?? "serve") {
         case "serve":
             return serve();
+        case "status":
+            return jamStatusCommand({ json: rest.includes("--json") });
+        // The old name for the same question. It keeps working for two minor
+        // releases; `status` is the word both products answer to.
         case "doctor":
+            process.stderr.write("Deprecated. Use `jam status`.\n");
             return rest.includes("--json") ? doctorJsonCommand() : doctor();
         case "setup": {
             const explicitKey = findFlagValue(rest, "--project");
@@ -108,6 +125,16 @@ export async function runJamCommand(argv) {
             return jamUpdateCommand(rest[0] === "--json" ? undefined : rest[0], {
                 json: rest.includes("--json"),
             });
+        case "refresh":
+            // Not `update`: the version does not move here. Only the registration
+            // this build owns is brought back to it.
+            return jamRefreshCommand(rest[0]?.startsWith("--") ? undefined : rest[0], {
+                json: rest.includes("--json"),
+            });
+        case "uninstall":
+            return jamUninstallCommand(rest[0]?.startsWith("--") ? 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.5.0",
+  "version": "1.6.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.5.0",
+    "@jam-mcp/launcher": "1.6.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"