@jam-mcp/server 1.3.2 → 1.4.1

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.3.2 doctor`, or just `jam
+Written out, that is `npx --yes @jam-mcp/launcher@1.4.1 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.3.2 init` instead.
+`npx --yes @jam-mcp/bootstrap@1.4.1 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/adapters/credentials/secret-store.d.ts

@@ -22,8 +22,13 @@ export type RunResult = {
     stderr: string;
     error?: NodeJS.ErrnoException;
 };
-/** Injected by tests so the suite never touches a real keychain. */
-export type RunFn = (command: string, args: string[], input?: string) => RunResult;
+/**
+ * Injected by tests so the suite never touches a real keychain.
+ *
+ * `env` is merged over the inherited environment, and carries only values that
+ * are not secret - a file path, say. Secrets travel on stdin.
+ */
+export type RunFn = (command: string, args: string[], input?: string, env?: Record<string, string>) => RunResult;
 export interface SecretStore {
     /** Shown by `jam auth login`. Names the mechanism, never a value. */
     readonly label: string;

package/dist/adapters/credentials/secret-store.js

@@ -30,10 +30,11 @@ export function secretStoreDisabled(env = process.env) {
 function account() {
     return userInfo().username;
 }
-function defaultRun(command, args, input) {
+function defaultRun(command, args, input, env) {
     const result = spawnSync(command, args, {
         encoding: "utf8",
         ...(input === undefined ? {} : { input }),
+        ...(env === undefined ? {} : { env: { ...process.env, ...env } }),
         // No shell: arguments are passed as an array, so nothing is re-parsed.
         windowsHide: true,
     });
@@ -138,43 +139,94 @@ function linuxStore(run) {
  * Kept separate from ~/.jam/config.yaml, which declares itself hand-editable
  * and free of credentials.
  */
+/**
+ * Both scripts need DPAPI, and both must survive a host that rewrote where
+ * PowerShell looks for modules.
+ *
+ * A CI runner does exactly that - it prepends its own paths, including ones
+ * belonging to a different PowerShell edition, and then Windows PowerShell 5.1
+ * either cannot resolve `ConvertTo-SecureString` at all or trips over type data
+ * from a module that was never meant for it. Neither failure says anything
+ * about credentials, so both look like a JAM bug to whoever reads them.
+ *
+ * So the child starts from the machine's own module path and asks for the
+ * module by name. This changes nothing outside that one short-lived process.
+ */
+const IMPORT_SECURITY = "$env:PSModulePath=[Environment]::GetEnvironmentVariable('PSModulePath','Machine');" +
+    "Import-Module Microsoft.PowerShell.Security -ErrorAction Stop;";
+/**
+ * What the child writes, we read as UTF-8 - so say so before it writes anything.
+ *
+ * `spawnSync` is told `encoding: "utf8"`, but powershell.exe writes through the
+ * console code page, which on a Korean install is 949. The bytes and the decoder
+ * then disagree and an error message arrives as mojibake: the user is handed a
+ * failure they cannot even read. Setting the output encoding inside the child
+ * changes nothing outside it.
+ */
+const UTF8_OUTPUT = "[Console]::OutputEncoding=[Text.Encoding]::UTF8;" +
+    "$OutputEncoding=[Text.Encoding]::UTF8;";
+/**
+ * Read stdin as UTF-8, by saying so on the stream rather than on the console.
+ *
+ * `[Console]::In` on Windows PowerShell 5.1 is already bound to the console
+ * input code page by the time a `-Command` script could change it, so a value
+ * with non-ASCII in it - a Jira account under a Korean name, say - arrived
+ * mangled and was then encrypted mangled. Opening the standard input stream
+ * with an explicit encoding sidesteps that entirely.
+ */
+const READ_STDIN_UTF8 = "$in=(New-Object IO.StreamReader(" +
+    "[Console]::OpenStandardInput(),[Text.Encoding]::UTF8)).ReadToEnd();";
 function windowsStore(run) {
     const dir = join(homedir(), ".jam");
     const path = join(dir, "credentials.dpapi");
-    // The path reaches PowerShell as an argument, never interpolated into the
-    // script text; the secret reaches it on stdin.
+    /**
+     * The path reaches PowerShell in an environment variable, never in argv and
+     * never interpolated into the script text.
+     *
+     * It used to ride as a trailing argument with `-args`, which does not work:
+     * `powershell.exe -Command` appends what follows to the command text rather
+     * than filling `$args` - that is `-File` semantics - so the script read
+     * `$args[0]` as `$null` and `Set-Content` refused the null path. Reading was
+     * broken the same way and failed quietly, since `Test-Path $null` is false.
+     *
+     * The variable holds a path, not a secret. The secret still reaches the
+     * process on stdin and appears nowhere else.
+     */
+    const PATH_VAR = "JAM_SECRET_FILE";
     const decrypt = [
         "-NoProfile",
         "-NonInteractive",
         "-Command",
-        "$p=$args[0]; if(!(Test-Path $p)){exit 1};" +
+        UTF8_OUTPUT +
+            IMPORT_SECURITY +
+            `$p=$env:${PATH_VAR}; if(!(Test-Path $p)){exit 1};` +
             "$s=Get-Content $p -Raw | ConvertTo-SecureString;" +
             "[Runtime.InteropServices.Marshal]::PtrToStringAuto(" +
             "[Runtime.InteropServices.Marshal]::SecureStringToBSTR($s))",
-        "-args",
     ];
     const encrypt = [
         "-NoProfile",
         "-NonInteractive",
         "-Command",
-        "$in=[Console]::In.ReadToEnd();" +
+        UTF8_OUTPUT +
+            IMPORT_SECURITY +
+            READ_STDIN_UTF8 +
             "$in | ConvertTo-SecureString -AsPlainText -Force |" +
-            " ConvertFrom-SecureString | Set-Content $args[0] -NoNewline",
-        "-args",
+            ` ConvertFrom-SecureString | Set-Content $env:${PATH_VAR} -NoNewline`,
     ];
     return {
         label: "Windows DPAPI (user-encrypted file)",
         read() {
             if (!existsSync(path))
                 return undefined;
-            const res = run("powershell", [...decrypt, path]);
+            const res = run("powershell", decrypt, undefined, { [PATH_VAR]: path });
             if (res.error || res.status !== 0)
                 return undefined;
             return parse(res.stdout.trim());
         },
         write(values) {
             mkdirSync(dir, { recursive: true });
-            const res = run("powershell", [...encrypt, path], JSON.stringify(values));
+            const res = run("powershell", encrypt, JSON.stringify(values), { [PATH_VAR]: path });
             if (res.error?.code === "ENOENT")
                 throw unavailable("powershell");
             if (res.status !== 0)

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

@@ -18,6 +18,18 @@ export type HostState = {
     cliAvailable: boolean;
     /** Whether it already has a `jam` entry registered for this user. */
     hasJamEntry: boolean;
+    /**
+     * The launcher pin that entry actually runs, when the listing shows it.
+     *
+     * An entry existing is not the same as an entry being current: a pin written
+     * by an older release keeps running that release's server, which serves a
+     * different set of tools. Reading only the name made a stale registration
+     * indistinguishable from a good one, and setup then reported
+     * `already_configured` over it.
+     */
+    entryVersion?: string;
+    /** The entry is present but does not run the launcher this release registers. */
+    entryStale?: boolean;
 };
 export type HostRunResult = {
     status: number | null;
@@ -29,6 +41,8 @@ export type HostRunResult = {
 export type HostRunner = (command: HostCommand) => HostRunResult;
 export declare const defaultHostRunner: HostRunner;
 export declare function hostRegistration(id: HostId): HostCommand | undefined;
+/** The removal that has to precede re-registering an entry this host already has. */
+export declare function hostUnregistration(id: HostId): HostCommand | undefined;
 /**
  * Is `jam` in this listing?
  *
@@ -42,6 +56,19 @@ export declare function hostRegistration(id: HostId): HostCommand | undefined;
  * `mcp add` on an existing entry writes the same launcher line back.
  */
 export declare function listsJamEntry(stdout: string): boolean;
+/** The listing line for `jam`, ANSI stripped, or null when there is none. */
+export declare function jamEntryLine(stdout: string): string | null;
+/** The launcher version a listing line runs, when the line names one. */
+export declare function entryLauncherVersion(line: string): string | undefined;
+/**
+ * Does this entry run the launcher this release registers?
+ *
+ * Anything else - an older pin, an unpinned spec, a line whose command JAM
+ * cannot read - counts as stale. That direction is deliberate: `mcp add`
+ * rewrites the same entry, so a needless repair costs one command, while a
+ * missed one leaves the agent talking to a server nobody tested it against.
+ */
+export declare function isEntryStale(line: string): boolean;
 /**
  * Ask each host what it has, and whether it is there at all.
  *

package/dist/bootstrap/host-mcp.js

@@ -30,16 +30,22 @@ const ADAPTERS = [
         // `-s user` is the whole point: registered for this user on this machine,
         // not for whichever project happens to be open.
         register: { command: "claude", args: ["mcp", "add", "jam", "-s", "user", ...LAUNCH] },
+        unregister: { command: "claude", args: ["mcp", "remove", "jam", "-s", "user"] },
     },
     {
         id: "codex",
         probe: { command: "codex", args: ["mcp", "list"] },
         register: { command: "codex", args: ["mcp", "add", "jam", ...LAUNCH] },
+        unregister: { command: "codex", args: ["mcp", "remove", "jam"] },
     },
 ];
 export function hostRegistration(id) {
     return ADAPTERS.find((a) => a.id === id)?.register;
 }
+/** The removal that has to precede re-registering an entry this host already has. */
+export function hostUnregistration(id) {
+    return ADAPTERS.find((a) => a.id === id)?.unregister;
+}
 const ANSI = /\[[0-9;?]*[A-Za-z]/g;
 /**
  * Is `jam` in this listing?
@@ -54,11 +60,32 @@ const ANSI = /\[[0-9;?]*[A-Za-z]/g;
  * `mcp add` on an existing entry writes the same launcher line back.
  */
 export function listsJamEntry(stdout) {
-    return stdout
+    return jamEntryLine(stdout) !== null;
+}
+/** The listing line for `jam`, ANSI stripped, or null when there is none. */
+export function jamEntryLine(stdout) {
+    const line = stdout
         .replace(ANSI, "")
         .split(/\r?\n/)
-        .some((line) => /^\s*jam(?=[\s:])/.test(line));
+        .find((candidate) => /^\s*jam(?=[\s:])/.test(candidate));
+    return line ?? null;
+}
+/** The launcher version a listing line runs, when the line names one. */
+export function entryLauncherVersion(line) {
+    return /@jam-mcp\/launcher@([^\s"']+)/.exec(line)?.[1];
+}
+/**
+ * Does this entry run the launcher this release registers?
+ *
+ * Anything else - an older pin, an unpinned spec, a line whose command JAM
+ * cannot read - counts as stale. That direction is deliberate: `mcp add`
+ * rewrites the same entry, so a needless repair costs one command, while a
+ * missed one leaves the agent talking to a server nobody tested it against.
+ */
+export function isEntryStale(line) {
+    return entryLauncherVersion(line) !== EXPECTED_LAUNCHER_VERSION;
 }
+const EXPECTED_LAUNCHER_VERSION = entryLauncherVersion(JAM_MCP_ENTRY.args.join(" "));
 /**
  * Ask each host what it has, and whether it is there at all.
  *
@@ -85,10 +112,16 @@ function probeHosts(run) {
         if (result.failed || result.status !== 0) {
             return { id: adapter.id, cliAvailable: false, hasJamEntry: false };
         }
+        const line = jamEntryLine(result.stdout);
+        if (!line)
+            return { id: adapter.id, cliAvailable: true, hasJamEntry: false };
+        const version = entryLauncherVersion(line);
         return {
             id: adapter.id,
             cliAvailable: true,
-            hasJamEntry: listsJamEntry(result.stdout),
+            hasJamEntry: true,
+            ...(version ? { entryVersion: version } : {}),
+            entryStale: isEntryStale(line),
         };
     });
 }

package/dist/bootstrap/live-toolset.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What the registered entry actually serves.
+ *
+ * Counting the tools of the process doing the counting proves nothing about
+ * the agent's experience: the agent talks to whatever the host registration
+ * launches, which may be an older release with a different tool set. This asks
+ * that process directly, over the protocol the agent uses.
+ */
+export type LiveToolsetVerdict = "OK" | "LIVE_TOOLSET_MISMATCH" | "UNREACHABLE";
+export type LiveToolsetResult = {
+    verdict: LiveToolsetVerdict;
+    expected: string[];
+    actual?: string[];
+    missing?: string[];
+    detail?: string;
+};
+export type ToolsetProbe = (argv: {
+    command: string;
+    args: string[];
+}) => Promise<string[] | null>;
+export declare const expectedTools: () => string[];
+/**
+ * Speak just enough MCP to ask for the tool list: initialize, initialized,
+ * tools/list. A full client would pull in the SDK's transport machinery for
+ * one question that is three lines of JSON.
+ */
+export declare const defaultToolsetProbe: ToolsetProbe;
+/**
+ * Compare what the registered command serves against what this release
+ * defines. A tool the agent cannot see is a tool it does not have, whatever
+ * the package on disk says.
+ */
+export declare function checkLiveToolset(argv: {
+    command: string;
+    args: string[];
+}, probe?: ToolsetProbe): Promise<LiveToolsetResult>;

package/dist/bootstrap/live-toolset.js

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+import { SERVER_VERSION } from "@jam-mcp/launcher";
+import { TOOL_NAMES } from "../mcp/create-server.js";
+const HANDSHAKE_TIMEOUT_MS = 30_000;
+export const expectedTools = () => [...TOOL_NAMES].sort();
+/**
+ * Speak just enough MCP to ask for the tool list: initialize, initialized,
+ * tools/list. A full client would pull in the SDK's transport machinery for
+ * one question that is three lines of JSON.
+ */
+export const defaultToolsetProbe = ({ command, args }) => new Promise((resolve) => {
+    const child = spawn(command, args, {
+        stdio: ["pipe", "pipe", "ignore"],
+        shell: process.platform === "win32",
+    });
+    let buffer = "";
+    let settled = false;
+    const done = (value) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        child.stdin.end();
+        child.kill();
+        resolve(value);
+    };
+    const timer = setTimeout(() => done(null), HANDSHAKE_TIMEOUT_MS);
+    child.on("error", () => done(null));
+    child.on("exit", () => done(null));
+    child.stdout.on("data", (chunk) => {
+        buffer += chunk.toString("utf8");
+        let newline = buffer.indexOf("\n");
+        while (newline >= 0) {
+            const line = buffer.slice(0, newline).trim();
+            buffer = buffer.slice(newline + 1);
+            newline = buffer.indexOf("\n");
+            if (!line)
+                continue;
+            try {
+                const message = JSON.parse(line);
+                if (message.id === 2) {
+                    done((message.result?.tools ?? []).map((tool) => tool.name).sort());
+                    return;
+                }
+            }
+            catch {
+                // Not our line. The server owns stdout for the protocol; anything
+                // unparseable is noise from a wrapper and is skipped rather than
+                // treated as a failure.
+            }
+        }
+    });
+    const send = (payload) => {
+        child.stdin.write(`${JSON.stringify(payload)}\n`);
+    };
+    send({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+            protocolVersion: "2024-11-05",
+            capabilities: {},
+            clientInfo: { name: "jam-doctor", version: SERVER_VERSION },
+        },
+    });
+    send({ jsonrpc: "2.0", method: "notifications/initialized" });
+    send({ jsonrpc: "2.0", id: 2, method: "tools/list" });
+});
+/**
+ * Compare what the registered command serves against what this release
+ * defines. A tool the agent cannot see is a tool it does not have, whatever
+ * the package on disk says.
+ */
+export async function checkLiveToolset(argv, probe = defaultToolsetProbe) {
+    const expected = expectedTools();
+    const actual = await probe(argv).catch(() => null);
+    if (actual === null) {
+        return { verdict: "UNREACHABLE", expected, detail: "the registered command did not answer tools/list" };
+    }
+    const missing = expected.filter((name) => !actual.includes(name));
+    if (missing.length > 0) {
+        return { verdict: "LIVE_TOOLSET_MISMATCH", expected, actual, missing };
+    }
+    return { verdict: "OK", expected, actual };
+}

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

@@ -13,12 +13,19 @@ 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.3.2", "serve"];
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.4.1", "serve"];
 };
 /**
- * Recognise wiring from before the launcher existed: a hard-coded path to one
- * machine's checkout, or a bare `jam` that depends on a global PATH install.
- * Both work only where they were written, which is why `--migrate` exists.
+ * Recognise wiring from before the launcher existed: a hard-coded `node` path
+ * to one machine's checkout. That works only where it was written, which is
+ * why `--migrate` exists.
+ *
+ * A bare `jam` is deliberately NOT legacy any more. It is what a persistent
+ * install (`npm install -g @jam-mcp/launcher@<exact>`) provides, and on a
+ * machine whose package runner is broken it is the entry that still works —
+ * a real Windows npm was seen failing to start `npx` children at all. Someone
+ * who registered it chose it; `--migrate` must not silently rewrite that
+ * choice back into the very path that fails there.
  */
 export declare function isLegacyJamEntry(entry: unknown): boolean;
 export type McpMergeResult = {

package/dist/bootstrap/mcp-config-merger.js

@@ -18,16 +18,21 @@ export const JAM_MCP_ENTRY = {
     args: ["--yes", LAUNCHER_PACKAGE_SPEC, "serve"],
 };
 /**
- * Recognise wiring from before the launcher existed: a hard-coded path to one
- * machine's checkout, or a bare `jam` that depends on a global PATH install.
- * Both work only where they were written, which is why `--migrate` exists.
+ * Recognise wiring from before the launcher existed: a hard-coded `node` path
+ * to one machine's checkout. That works only where it was written, which is
+ * why `--migrate` exists.
+ *
+ * A bare `jam` is deliberately NOT legacy any more. It is what a persistent
+ * install (`npm install -g @jam-mcp/launcher@<exact>`) provides, and on a
+ * machine whose package runner is broken it is the entry that still works —
+ * a real Windows npm was seen failing to start `npx` children at all. Someone
+ * who registered it chose it; `--migrate` must not silently rewrite that
+ * choice back into the very path that fails there.
  */
 export function isLegacyJamEntry(entry) {
     if (!entry || typeof entry !== "object")
         return false;
     const { command, args } = entry;
-    if (command === "jam")
-        return true;
     if (command === "node")
         return true;
     if (command === "npx" && Array.isArray(args)) {

package/dist/bootstrap/setup-apply.js

@@ -36,6 +36,11 @@ export function applySetupPlan(plan, options = {}) {
                 // decides nothing. A failure is that host's failure, reported with the
                 // command that produced it - never retried against another host.
                 const run = options.runHost ?? defaultHostRunner;
+                // A repair removes the stale entry first. Its failure is not reported on
+                // its own: if the entry is already gone the removal fails harmlessly, and
+                // if it is still there the registration below fails and says so.
+                if (change.precede)
+                    run({ command: change.precede.command, args: change.precede.args });
                 const result = run({ command: change.command, args: change.args });
                 if (result.failed || result.status !== 0) {
                     throw new Error(`Registering JAM with ${change.host} failed: ${change.command} ${change.args.join(" ")}`);

package/dist/bootstrap/setup-plan.d.ts

@@ -34,7 +34,7 @@ export type SetupChange = {
     /** Present on a rebind, so the preview shows what is being replaced. */
     previousKey?: string;
 } | {
-    type: "create";
+    type: "create" | "replace";
     target: "host-mcp";
     host: HostId;
     /**
@@ -44,6 +44,18 @@ export type SetupChange = {
      */
     command: string;
     args: string[];
+    /**
+     * Run before the registration, on a repair. The host CLI refuses to add an
+     * entry that already exists, so the stale one has to go first - and which
+     * command does that is decided here, not worked out during apply.
+     */
+    precede?: {
+        command: string;
+        args: string[];
+    };
+    /** On a repair: the launcher pin the entry runs today, so the preview names it. */
+    previousVersion?: string;
+    reason?: "stale-registration";
 };
 export type SetupPlan = {
     status: SetupStatus;

package/dist/bootstrap/setup-plan.js

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { CONFIG_RELATIVE_PATH } from "../config/load-config.js";
-import { hostRegistration } from "./host-mcp.js";
+import { hostRegistration, hostUnregistration } from "./host-mcp.js";
 import { projectBindingsPath } from "./project-bindings.js";
 import { decideProjectKey } from "./project-config-bootstrapper.js";
 import { portableBootstrapCommand } from "@jam-mcp/launcher";
@@ -155,17 +155,25 @@ function finish(changes, state, project) {
 function planHostChanges(state) {
     const changes = [];
     for (const host of state.hosts) {
-        if (!host.cliAvailable || host.hasJamEntry)
+        if (!host.cliAvailable)
+            continue;
+        // An entry that exists but runs an older launcher is not "already set up":
+        // that pin decides which server, and so which tools, the agent actually gets.
+        if (host.hasJamEntry && host.entryStale !== true)
             continue;
         const registration = hostRegistration(host.id);
         if (!registration)
             continue;
+        const removal = hostUnregistration(host.id);
         changes.push({
-            type: "create",
+            type: host.hasJamEntry ? "replace" : "create",
             target: "host-mcp",
             host: host.id,
             command: registration.command,
             args: registration.args,
+            ...(host.hasJamEntry && removal ? { precede: { command: removal.command, args: removal.args } } : {}),
+            ...(host.entryVersion ? { previousVersion: host.entryVersion } : {}),
+            ...(host.hasJamEntry ? { reason: "stale-registration" } : {}),
         });
     }
     return changes;

package/dist/cli/agent-api.d.ts

@@ -1,6 +1,7 @@
 import { type MigrationTarget } from "../bootstrap/migration-target.js";
 import type { CredentialPort } from "../ports/credentials.port.js";
-import type { HostRunner } from "../bootstrap/host-mcp.js";
+import { type HostRunner } from "../bootstrap/host-mcp.js";
+import { type ToolsetProbe } from "../bootstrap/live-toolset.js";
 import type { GitRemoteFn } from "../bootstrap/workspace-identity.js";
 /**
  * The machine-readable half of setup.
@@ -27,6 +28,8 @@ export type AgentOptions = {
     env?: NodeJS.ProcessEnv;
     /** Injected by tests so a plan never shells out to npm to verify a migration target. */
     migrationTarget?: MigrationTarget;
+    /** Injected by tests so doctor never launches a real MCP server to read its tools. */
+    toolsetProbe?: ToolsetProbe;
     /** Injected by tests so identity never depends on the checkout under test. */
     git?: GitRemoteFn;
     /** Injected by tests so no test ever registers JAM with a real host. */
@@ -52,7 +55,15 @@ export declare function setupApplyCommand(options?: AgentOptions): Promise<numbe
  * authenticating), and reports exactly how far it got.
  */
 export declare function setupAgentCommand(options?: AgentOptions): Promise<number>;
-/** `jam doctor --json`. */
+/**
+ * `jam doctor --json`.
+ *
+ * Three axes, kept apart on purpose. The package on this machine being current
+ * says nothing about what the host registration launches, and neither says what
+ * the agent can actually call - a stale pin serves an older tool set while every
+ * local check passes. Reporting them as one verdict is how a broken setup was
+ * reported as ready.
+ */
 export declare function doctorJsonCommand(options?: AgentOptions): Promise<number>;
 /**
  * `jam auth status --json` - presence and origin only.

package/dist/cli/agent-api.js

@@ -5,6 +5,9 @@ import { applySetupPlan } from "../bootstrap/setup-apply.js";
 import { detectSetupState } from "../bootstrap/setup-state.js";
 import { buildDeps } from "../deps.js";
 import { toJamError } from "../domain/errors.js";
+import { hostRegistration } from "../bootstrap/host-mcp.js";
+import { checkLiveToolset } from "../bootstrap/live-toolset.js";
+import { SERVER_VERSION } from "@jam-mcp/launcher";
 export function emitJson(payload) {
     process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
 }
@@ -108,17 +111,74 @@ export async function setupAgentCommand(options = {}) {
     });
     return health.passed ? 0 : 1;
 }
-/** `jam doctor --json`. */
+/**
+ * `jam doctor --json`.
+ *
+ * Three axes, kept apart on purpose. The package on this machine being current
+ * says nothing about what the host registration launches, and neither says what
+ * the agent can actually call - a stale pin serves an older tool set while every
+ * local check passes. Reporting them as one verdict is how a broken setup was
+ * reported as ready.
+ */
 export async function doctorJsonCommand(options = {}) {
+    // detect() already probes the hosts for every non-shared path; doctor wants that.
     const state = detect(options);
     const health = await gateResult(state.project.root);
+    const axes = await inspectAxes(state, options);
+    // 등록이 아예 없는 것은 결함이 아니다 — 새 머신, 호스트 CLI 없는 CI, 아직 setup 을
+    // 안 한 사용자 모두 정상 상태다. 전체 판정을 무너뜨리는 것은 **거짓말하는 상태**뿐:
+    // 낡은 핀을 실행 중인 등록(STALE)과, 등록은 맞는데 실제 도구가 다른 경우(MISMATCH).
+    const axesOk = axes.registration !== "HOST_REGISTRATION_STALE" && axes.live !== "LIVE_TOOLSET_MISMATCH";
+    const passed = health.passed && axesOk;
     emitJson({
-        status: health.passed ? "ready" : "failed",
+        status: passed ? "ready" : "failed",
         ...(health.error ? { error: health.error } : {}),
         project: { root: state.project.root, ...(state.project.key ? { key: state.project.key } : {}) },
+        axes,
         checks: health.checks,
     });
-    return health.passed ? 0 : 1;
+    return passed ? 0 : 1;
+}
+async function inspectAxes(state, options) {
+    const packageVersion = state.runtime.version;
+    const axes = {
+        package: packageVersion === SERVER_VERSION ? "PACKAGE_READY" : "PACKAGE_NOT_READY",
+        ...(packageVersion ? { packageVersion } : {}),
+        registration: "UNREGISTERED",
+        live: "UNCHECKED",
+    };
+    const hosts = state.hosts.filter((host) => host.cliAvailable);
+    if (state.hosts.length > 0 && hosts.length === 0) {
+        return { ...axes, registration: "HOST_UNREACHABLE", detail: "no host CLI answered" };
+    }
+    const registered = hosts.find((host) => host.hasJamEntry);
+    if (!registered)
+        return axes;
+    axes.registration = registered.entryStale ? "HOST_REGISTRATION_STALE" : "OK";
+    if (registered.entryVersion)
+        axes.registeredVersion = registered.entryVersion;
+    // A stale entry has already answered the question the live check would ask,
+    // and asking it means launching that older release. Repair first.
+    if (registered.entryStale)
+        return axes;
+    const registration = hostRegistration(registered.id);
+    const launch = registration ? launcherArgv(registration.args) : null;
+    if (!launch)
+        return { ...axes, live: "UNCHECKED", detail: "could not read the registered command" };
+    const result = await checkLiveToolset(launch, options.toolsetProbe);
+    axes.live = result.verdict === "OK" ? "OK" : result.verdict;
+    if (result.missing && result.missing.length > 0)
+        axes.missingTools = result.missing;
+    if (result.detail)
+        axes.detail = result.detail;
+    return axes;
+}
+/** The registration argv carries the launch command after `--`. */
+function launcherArgv(args) {
+    const at = args.indexOf("--");
+    if (at < 0 || args.length <= at + 1)
+        return null;
+    return { command: args[at + 1], args: args.slice(at + 2) };
 }
 /**
  * `jam auth status --json` - presence and origin only.

package/dist/cli/setup.js

@@ -108,7 +108,9 @@ function reportApplied(applied, plan) {
             continue;
         }
         if (change.target === "host-mcp") {
-            line(`[OK]   ${change.host} - jam registered for this user`);
+            line(change.type === "replace"
+                ? `[OK]   ${change.host} - jam re-registered, replacing a stale launcher pin${change.previousVersion ? ` (${change.previousVersion})` : ""}`
+                : `[OK]   ${change.host} - jam registered for this user`);
             continue;
         }
         if (change.target === "project-config") {

package/dist/mcp/create-server.d.ts

@@ -2,6 +2,13 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { JamDeps } from "../deps.js";
 export declare const SERVER_NAME = "jam";
 export declare const TOOL_COUNT: number;
+/**
+ * The same contract by name, for the checks that ask a *running* server what it
+ * serves. The registrars above cannot be introspected for their tool names, and
+ * counting is not enough: five tools with one renamed is still five.
+ * `tests/contract/tools.test.ts` holds this list to what the server registers.
+ */
+export declare const TOOL_NAMES: readonly ["jira_search", "jira_context", "jira_full", "jira_write_plan", "jira_write_apply"];
 /**
  * The external contract: three read tools and two write tools.
  *

package/dist/mcp/create-server.js

@@ -21,6 +21,19 @@ const REGISTER_TOOLS = [
     registerJiraWriteApply,
 ];
 export const TOOL_COUNT = REGISTER_TOOLS.length;
+/**
+ * The same contract by name, for the checks that ask a *running* server what it
+ * serves. The registrars above cannot be introspected for their tool names, and
+ * counting is not enough: five tools with one renamed is still five.
+ * `tests/contract/tools.test.ts` holds this list to what the server registers.
+ */
+export const TOOL_NAMES = [
+    "jira_search",
+    "jira_context",
+    "jira_full",
+    "jira_write_plan",
+    "jira_write_apply",
+];
 /**
  * The external contract: three read tools and two write tools.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jam-mcp/server",
-  "version": "1.3.2",
+  "version": "1.4.1",
   "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.3.2",
+    "@jam-mcp/launcher": "1.4.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"

package/dist/adapters/jira-cloud/jira-edit-metadata.adapter.d.ts

@@ -1,25 +0,0 @@
-import type { EditFieldMetadata } from "../../domain/write.js";
-import type { CredentialPort } from "../../ports/credentials.port.js";
-import type { JiraEditMetadataPort } from "../../ports/jira-edit-metadata.port.js";
-/**
- * Jira Cloud REST v3 edit metadata for one issue.
- *
- * `GET /rest/api/3/issue/{key}/editmeta`, `retry: false`. Its answer decides
- * whether a mutation may proceed and what shape it takes, so a
- * retried-and-stale answer is worse than a failure - the same argument that
- * keeps `getTransitions`, the create metadata calls and the assignability
- * check on the non-retrying side.
- *
- * Jira keys the response by field id, and describes each field with a `schema`
- * and a list of `operations`. Both travel, because both are what the decision
- * is made in; the rest of the document does not.
- *
- * Anything JAM cannot read is dropped rather than half-understood. A field
- * that survives here with the wrong shape would be a field JAM claims to
- * understand well enough to write.
- */
-export declare class JiraCloudEditMetadataAdapter implements JiraEditMetadataPort {
-    private readonly client;
-    constructor(credentials: CredentialPort, fetchImpl?: typeof fetch);
-    getEditableFields(issueKey: string): Promise<EditFieldMetadata[]>;
-}

package/dist/adapters/jira-cloud/jira-edit-metadata.adapter.js

@@ -1,84 +0,0 @@
-import { JiraClient } from "./jira-client.js";
-/**
- * Jira Cloud REST v3 edit metadata for one issue.
- *
- * `GET /rest/api/3/issue/{key}/editmeta`, `retry: false`. Its answer decides
- * whether a mutation may proceed and what shape it takes, so a
- * retried-and-stale answer is worse than a failure - the same argument that
- * keeps `getTransitions`, the create metadata calls and the assignability
- * check on the non-retrying side.
- *
- * Jira keys the response by field id, and describes each field with a `schema`
- * and a list of `operations`. Both travel, because both are what the decision
- * is made in; the rest of the document does not.
- *
- * Anything JAM cannot read is dropped rather than half-understood. A field
- * that survives here with the wrong shape would be a field JAM claims to
- * understand well enough to write.
- */
-export class JiraCloudEditMetadataAdapter {
-    client;
-    constructor(credentials, fetchImpl) {
-        this.client = fetchImpl ? new JiraClient(credentials, fetchImpl) : new JiraClient(credentials);
-    }
-    async getEditableFields(issueKey) {
-        const { data } = await this.client.request({
-            path: `rest/api/3/issue/${encodeURIComponent(issueKey)}/editmeta`,
-            retry: false,
-        });
-        const fields = data?.fields;
-        if (!fields || typeof fields !== "object")
-            return [];
-        return Object.entries(fields)
-            .map(([id, raw]) => toEditField(id, raw))
-            .filter((f) => f !== undefined);
-    }
-}
-function toEditField(id, raw) {
-    if (!raw || typeof raw !== "object")
-        return undefined;
-    // A field with no schema type is a field JAM cannot classify, and an
-    // unclassifiable field is one it must not decide it can write.
-    const type = typeof raw.schema?.type === "string" ? raw.schema.type : undefined;
-    if (!type)
-        return undefined;
-    const allowed = toOptions(raw.allowedValues);
-    return {
-        id,
-        name: typeof raw.name === "string" ? raw.name : id,
-        required: raw.required === true,
-        operations: Array.isArray(raw.operations)
-            ? raw.operations.filter((op) => typeof op === "string")
-            : [],
-        schema: {
-            type,
-            ...(typeof raw.schema?.items === "string" ? { items: raw.schema.items } : {}),
-            ...(typeof raw.schema?.custom === "string" ? { custom: raw.schema.custom } : {}),
-            ...(typeof raw.schema?.customId === "number" ? { customId: raw.schema.customId } : {}),
-        },
-        ...(allowed ? { allowedValues: allowed } : {}),
-    };
-}
-/**
- * The options Jira offers, when it constrains the field at all.
- *
- * Absent and empty mean different things and stay apart: absent is "Jira did
- * not constrain this", empty is "Jira constrains it and offers nothing". The
- * first permits a free value, the second permits none.
- *
- * Jira labels an option `value` on a select and `name` on some other pickers.
- * Both are read; an option with neither an id nor a label is dropped, because
- * it can be neither chosen nor recognised afterwards.
- */
-function toOptions(raw) {
-    if (!Array.isArray(raw))
-        return undefined;
-    return raw
-        .map((entry) => {
-        const o = entry;
-        const id = typeof o?.id === "string" ? o.id : typeof o?.id === "number" ? String(o.id) : undefined;
-        const label = typeof o?.value === "string" ? o.value : typeof o?.name === "string" ? o.name : undefined;
-        return id && label ? { id, label } : undefined;
-    })
-        .filter((o) => o !== undefined);
-}

package/dist/policy/custom-field-policy.d.ts

@@ -1,93 +0,0 @@
-import type { ProjectConfig } from "../config/schema.js";
-import type { CustomFieldKind, CustomFieldRequirements, CustomFieldUpdateInput, CustomFieldValueView, EditFieldMetadata, EditFieldOption } from "../domain/write.js";
-/**
- * What JAM will write to a custom field, and everything that has to be true
- * first.
- *
- * Three separate permissions have to line up, and none of them implies
- * another:
- *
- *  1. **The team said so.** The field's exact id is in the project's whitelist
- *     with `writable: true`. Being readable is not being writable - reading a
- *     field and letting an agent change it are different decisions, and a
- *     config written before JAM could write must not start granting writes
- *     because JAM learned how.
- *  2. **Jira allows it here and now.** The field is on this issue's edit
- *     screen for this account, and Jira lists `set` among its operations.
- *     Asked, never modelled: applicability depends on project, issue type,
- *     field contexts, screens and permissions, and JAM does not carry a copy
- *     of any of that.
- *  3. **JAM knows the shape.** The field's type is one of four families whose
- *     wire form JAM can produce from a plain value and compare afterwards.
- *     Anything else is refused rather than posted to find out.
- */
-type WritableField = {
-    id: string;
-    name: string;
-};
-/**
- * Which configured field this selector names.
- *
- * The id is the identity; the name is an alias for people. Resolution is exact
- * on either - no substring, no fuzz - because the alternative is an agent's
- * approximate word choosing which field on somebody's board gets rewritten.
- *
- * Only `writable: true` entries are candidates, including for the refusal
- * message: naming a read-only field as an alternative would suggest it is one
- * selector away from being written.
- */
-export declare function resolveWritableField(config: ProjectConfig, requested: string): WritableField;
-/**
- * The field as Jira currently offers it on this issue, or a refusal.
- *
- * Absent from the edit metadata and present-but-not-settable are different
- * situations with the same answer for the caller, so they share a code and
- * differ in the detail: one means the field is not on this screen, the other
- * that Jira will not let this account set it.
- */
-export declare function assertEditable(issueKey: string, field: WritableField, metadata: EditFieldMetadata[]): EditFieldMetadata;
-/**
- * Which of the four families this field belongs to, if any.
- *
- * Classified from Jira's own `schema`, which is the vocabulary Jira answers
- * in. The implementation key (`schema.custom`) deliberately does not decide
- * it: there are hundreds of them, they are app-specific, and a field's wire
- * shape follows its type rather than its plugin.
- *
- * Anything unclassified is refused. Posting an unknown type to see what
- * happens would use a Jira 400 as schema discovery, and on the occasions it
- * did not 400 it would write something nobody described.
- */
-export declare function classifyKind(field: EditFieldMetadata): CustomFieldKind;
-/**
- * The value, checked against the family and turned into what Jira expects.
- *
- * Types are never coerced. `"5"` is not `5`: a caller that meant a number can
- * say so, and silently converting would make JAM's idea of the value differ
- * from the caller's in exactly the cases where it matters.
- *
- * Nothing here clears a field. Empty strings, empty arrays and null are
- * refused rather than treated as "unset" - removing a value is a different
- * intent from setting one, and it is not in this version.
- */
-export declare function resolveCustomFieldValue(field: EditFieldMetadata, kind: CustomFieldKind, input: CustomFieldUpdateInput): {
-    jiraValue: unknown;
-    view: CustomFieldValueView;
-    resolvedOptions?: EditFieldOption[];
-};
-/**
- * Do this plan's premises still hold?
- *
- * Semantic, like the create schema check and for the same reason: comparing
- * whole metadata documents would invalidate every outstanding plan whenever an
- * unrelated field appeared on the screen. What is compared is what the plan
- * actually rested on - the field is still settable, still the same family,
- * still the same schema, and every option it chose is still offered under the
- * same label.
- *
- * A renamed option is treated as a changed one. The id is the identity, but a
- * label is what the plan showed a human before they agreed to it, and "Backend"
- * becoming "Platform" is a different statement about the issue.
- */
-export declare function assertCustomFieldUnchanged(issueKey: string, requirements: CustomFieldRequirements, metadata: EditFieldMetadata[]): void;
-export {};

package/dist/policy/custom-field-policy.js

@@ -1,230 +0,0 @@
-import { JamError } from "../domain/errors.js";
-/**
- * Which configured field this selector names.
- *
- * The id is the identity; the name is an alias for people. Resolution is exact
- * on either - no substring, no fuzz - because the alternative is an agent's
- * approximate word choosing which field on somebody's board gets rewritten.
- *
- * Only `writable: true` entries are candidates, including for the refusal
- * message: naming a read-only field as an alternative would suggest it is one
- * selector away from being written.
- */
-export function resolveWritableField(config, requested) {
-    const wanted = requested.trim();
-    if (wanted.length === 0) {
-        throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "custom-field.update needs a non-empty `input.field`.", { operation: "custom-field.update" });
-    }
-    const writable = config.customFields.filter((f) => f.writable);
-    const match = writable.find((f) => f.id.toLowerCase() === wanted.toLowerCase()) ??
-        writable.find((f) => f.name.trim().toLowerCase() === wanted.toLowerCase());
-    if (!match) {
-        throw new JamError("JAM_WRITE_FIELD_NOT_ALLOWED", writable.length === 0
-            ? `No custom field in this project is writable. A team opts one in by adding \`writable: true\` to its entry in .jira-agent/project.yaml; being readable does not make a field writable.`
-            : `"${requested}" is not a writable custom field in this project. JAM writes only the exact ids a team has opted in.`, {
-            requested,
-            writableCustomFields: writable.map((f) => ({ id: f.id, name: f.name })),
-        });
-    }
-    return { id: match.id, name: match.name };
-}
-/**
- * The field as Jira currently offers it on this issue, or a refusal.
- *
- * Absent from the edit metadata and present-but-not-settable are different
- * situations with the same answer for the caller, so they share a code and
- * differ in the detail: one means the field is not on this screen, the other
- * that Jira will not let this account set it.
- */
-export function assertEditable(issueKey, field, metadata) {
-    const found = metadata.find((f) => f.id === field.id);
-    if (!found) {
-        throw new JamError("JAM_WRITE_CUSTOM_FIELD_NOT_EDITABLE", `Jira does not offer ${field.name} (${field.id}) on ${issueKey}'s edit screen for this account. The field may not apply to this project or issue type, or this account may not be able to edit it.`, { issueKey, fieldId: field.id, fieldName: field.name, reason: "NOT_ON_EDIT_SCREEN" });
-    }
-    if (!found.operations.includes("set")) {
-        throw new JamError("JAM_WRITE_CUSTOM_FIELD_NOT_EDITABLE", `Jira lists ${field.name} (${field.id}) on ${issueKey} but does not offer "set" for it${found.operations.length > 0 ? ` - only ${found.operations.join(", ")}` : ""}. JAM only sets a value; it does not add to or remove from one.`, {
-            issueKey,
-            fieldId: field.id,
-            fieldName: field.name,
-            operations: found.operations,
-            reason: "SET_NOT_OFFERED",
-        });
-    }
-    return found;
-}
-/**
- * Which of the four families this field belongs to, if any.
- *
- * Classified from Jira's own `schema`, which is the vocabulary Jira answers
- * in. The implementation key (`schema.custom`) deliberately does not decide
- * it: there are hundreds of them, they are app-specific, and a field's wire
- * shape follows its type rather than its plugin.
- *
- * Anything unclassified is refused. Posting an unknown type to see what
- * happens would use a Jira 400 as schema discovery, and on the occasions it
- * did not 400 it would write something nobody described.
- */
-export function classifyKind(field) {
-    const { type, items } = field.schema;
-    if (type === "string" && !items)
-        return "text";
-    if (type === "number" && !items)
-        return "number";
-    if (type === "option" && !items)
-        return "single-option";
-    if (type === "array" && items === "option")
-        return "multi-option";
-    throw new JamError("JAM_WRITE_CUSTOM_FIELD_TYPE_UNSUPPORTED", `${field.name} (${field.id}) is a ${describeType(field)} field, and JAM does not know how to write one safely yet. Supported: single-line text, number, single-select and multi-select.`, {
-        fieldId: field.id,
-        fieldName: field.name,
-        schema: field.schema,
-        supported: ["text", "number", "single-option", "multi-option"],
-    });
-}
-function describeType(field) {
-    const { type, items } = field.schema;
-    return items ? `${type} of ${items}` : type;
-}
-/**
- * The value, checked against the family and turned into what Jira expects.
- *
- * Types are never coerced. `"5"` is not `5`: a caller that meant a number can
- * say so, and silently converting would make JAM's idea of the value differ
- * from the caller's in exactly the cases where it matters.
- *
- * Nothing here clears a field. Empty strings, empty arrays and null are
- * refused rather than treated as "unset" - removing a value is a different
- * intent from setting one, and it is not in this version.
- */
-export function resolveCustomFieldValue(field, kind, input) {
-    const { value } = input;
-    const named = { id: field.id, name: field.name };
-    switch (kind) {
-        case "text": {
-            if (typeof value !== "string")
-                throw wrongType(field, kind, value);
-            const text = value.trim();
-            if (text.length === 0)
-                throw refuseClear(field);
-            return { jiraValue: text, view: { ...named, value: text } };
-        }
-        case "number": {
-            if (typeof value !== "number" || !Number.isFinite(value))
-                throw wrongType(field, kind, value);
-            return { jiraValue: value, view: { ...named, value } };
-        }
-        case "single-option": {
-            if (typeof value !== "string")
-                throw wrongType(field, kind, value);
-            const option = resolveOption(field, value);
-            // Jira takes the option by id. The label is what a person reads, and two
-            // options could carry the same one.
-            return {
-                jiraValue: { id: option.id },
-                view: { ...named, value: option },
-                resolvedOptions: [option],
-            };
-        }
-        case "multi-option": {
-            if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
-                throw wrongType(field, kind, value);
-            }
-            if (value.length === 0)
-                throw refuseClear(field);
-            const seen = new Set();
-            for (const raw of value) {
-                const key = raw.trim().toLowerCase();
-                if (seen.has(key)) {
-                    throw new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", `"${raw}" appears more than once in the value for ${field.name}. JAM does not quietly drop the repeat - say each option once.`, { fieldId: field.id, repeated: raw });
-                }
-                seen.add(key);
-            }
-            // Every option resolves, or none is written. A partly-applied selection
-            // is a selection nobody asked for.
-            const options = value.map((raw) => resolveOption(field, raw));
-            return {
-                jiraValue: options.map((o) => ({ id: o.id })),
-                view: { ...named, value: options },
-                resolvedOptions: options,
-            };
-        }
-    }
-}
-/**
- * Which option Jira offers under this name, if exactly one does.
- *
- * An option id wins outright, then an exact label ignoring case and space.
- * Nothing partial: Jira's option lists are short and a caller can name one
- * exactly, so a near miss is a question rather than a guess.
- */
-function resolveOption(field, requested) {
-    const allowed = field.allowedValues;
-    if (!allowed) {
-        throw new JamError("JAM_WRITE_CUSTOM_FIELD_TYPE_UNSUPPORTED", `${field.name} (${field.id}) is a select field, but Jira did not say which options it offers, so JAM cannot resolve "${requested}" to one.`, { fieldId: field.id, fieldName: field.name, schema: field.schema });
-    }
-    const wanted = requested.trim();
-    const byId = allowed.filter((o) => o.id === wanted);
-    const matches = byId.length > 0
-        ? byId
-        : allowed.filter((o) => o.label.trim().toLowerCase() === wanted.toLowerCase());
-    if (matches.length === 0) {
-        throw new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", allowed.length === 0
-            ? `Jira offers no options for ${field.name} on this issue, so "${requested}" cannot be set.`
-            : `"${requested}" is not an option Jira offers for ${field.name}. Allowed: ${allowed.map((o) => o.label).join(", ")}.`, { fieldId: field.id, requested, allowed });
-    }
-    if (matches.length > 1) {
-        throw new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", `"${requested}" matches ${matches.length} options for ${field.name}. Pass the option id of the one you mean.`, { fieldId: field.id, requested, candidates: matches });
-    }
-    return matches[0];
-}
-/**
- * Do this plan's premises still hold?
- *
- * Semantic, like the create schema check and for the same reason: comparing
- * whole metadata documents would invalidate every outstanding plan whenever an
- * unrelated field appeared on the screen. What is compared is what the plan
- * actually rested on - the field is still settable, still the same family,
- * still the same schema, and every option it chose is still offered under the
- * same label.
- *
- * A renamed option is treated as a changed one. The id is the identity, but a
- * label is what the plan showed a human before they agreed to it, and "Backend"
- * becoming "Platform" is a different statement about the issue.
- */
-export function assertCustomFieldUnchanged(issueKey, requirements, metadata) {
-    const field = metadata.find((f) => f.id === requirements.fieldId);
-    if (!field) {
-        throw schemaChanged(`${requirements.fieldName} (${requirements.fieldId}) is no longer on ${issueKey}'s edit screen for this account.`, { issueKey, fieldId: requirements.fieldId });
-    }
-    if (!field.operations.includes("set")) {
-        throw schemaChanged(`Jira no longer offers "set" for ${requirements.fieldName} on ${issueKey}.`, { issueKey, fieldId: field.id, operations: field.operations });
-    }
-    if (field.schema.type !== requirements.schema.type ||
-        field.schema.items !== requirements.schema.items) {
-        throw schemaChanged(`${requirements.fieldName} is no longer a ${requirements.kind} field.`, { issueKey, fieldId: field.id, planned: requirements.schema, current: field.schema });
-    }
-    for (const planned of requirements.resolvedOptions ?? []) {
-        const current = field.allowedValues?.find((o) => o.id === planned.id);
-        if (!current) {
-            throw schemaChanged(`Option "${planned.label}" is no longer offered for ${requirements.fieldName}.`, { issueKey, fieldId: field.id, option: planned });
-        }
-        if (current.label !== planned.label) {
-            throw schemaChanged(`Option "${planned.label}" has been renamed to "${current.label}", so this plan no longer describes the change it showed.`, { issueKey, fieldId: field.id, planned, current });
-        }
-    }
-}
-function schemaChanged(what, details) {
-    return new JamError("JAM_WRITE_SCHEMA_CHANGED", `${what} This plan was built on the field's configuration as it was, so it no longer describes a change JAM can make. Nothing was written - plan again.`, details);
-}
-function wrongType(field, kind, value) {
-    const wanted = {
-        text: "a string",
-        number: "a number",
-        "single-option": "a string naming one option",
-        "multi-option": "an array of strings naming options",
-    }[kind];
-    return new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", `${field.name} (${field.id}) is a ${kind} field and needs ${wanted}. JAM does not convert between types - "5" and 5 are different values, and guessing which was meant is not JAM's to do.`, { fieldId: field.id, kind, received: typeof value });
-}
-function refuseClear(field) {
-    return new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", `custom-field.update sets a value; it does not clear one. ${field.name} cannot be set to an empty value in this version.`, { fieldId: field.id, reason: "CLEAR_NOT_SUPPORTED" });
-}

package/dist/ports/jira-edit-metadata.port.d.ts

@@ -1,22 +0,0 @@
-import type { EditFieldMetadata } from "../domain/write.js";
-/**
- * What Jira will let this account change on one issue, right now.
- *
- * `GET /rest/api/3/issue/{key}/editmeta` is the authority, and it is asked
- * rather than reconstructed. A custom field's applicability depends on the
- * project, the issue type, the field's contexts, the screen it is on and the
- * permissions of whoever is asking - JAM does not carry a copy of that model,
- * and the field-context APIs that would let it try need administrator rights
- * most tokens do not have. So the question is put to Jira in the form it can
- * answer exactly: on this issue, for this account, what is editable and how.
- *
- * The same shape as the other read-shaped ports, for the same reasons: it
- * mutates nothing, so it does not belong behind the write port's no-retry
- * contract, and it answers a question about a configuration rather than about
- * an issue, so the read port's completeness semantics would mean nothing here.
- *
- * It does not retry. Its answer decides a mutation.
- */
-export interface JiraEditMetadataPort {
-    getEditableFields(issueKey: string): Promise<EditFieldMetadata[]>;
-}

package/dist/ports/jira-edit-metadata.port.js

@@ -1 +0,0 @@
-export {};