@jam-mcp/server 1.0.0

package/dist/bootstrap/host-mcp.js

@@ -0,0 +1,98 @@
+import { spawnSync } from "node:child_process";
+import { JAM_MCP_ENTRY } from "./mcp-config-merger.js";
+/**
+ * These boot a whole Node CLI, and Claude Code health-checks every configured
+ * server while listing, which is seconds rather than milliseconds.
+ */
+const HOST_TIMEOUT_MS = 20_000;
+export const defaultHostRunner = ({ command, args }) => {
+    const result = spawnSync(command, args, {
+        encoding: "utf8",
+        timeout: HOST_TIMEOUT_MS,
+        // Both CLIs are npm shims on Windows, and Node refuses to spawn a .cmd
+        // without a shell. Every argument JAM passes is a bare token - no JSON, no
+        // spaces - precisely so this cannot become a quoting hazard.
+        shell: process.platform === "win32",
+    });
+    if (result.error)
+        return { status: null, failed: true, stdout: "" };
+    return { status: result.status, failed: false, stdout: result.stdout ?? "" };
+};
+/**
+ * `add`, not `add-json`: the JSON form would put a quoted blob through a
+ * Windows shell, and every argument here is a bare token instead.
+ */
+const LAUNCH = ["--", JAM_MCP_ENTRY.command, ...JAM_MCP_ENTRY.args];
+const ADAPTERS = [
+    {
+        id: "claude-code",
+        probe: { command: "claude", args: ["mcp", "list"] },
+        // `-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] },
+    },
+    {
+        id: "codex",
+        probe: { command: "codex", args: ["mcp", "list"] },
+        register: { command: "codex", args: ["mcp", "add", "jam", ...LAUNCH] },
+    },
+];
+export function hostRegistration(id) {
+    return ADAPTERS.find((a) => a.id === id)?.register;
+}
+const ANSI = /\[[0-9;?]*[A-Za-z]/g;
+/**
+ * Is `jam` in this listing?
+ *
+ * Both CLIs exit 0 whether or not a server exists, so the exit code says
+ * nothing and the name column is the only signal available. Matched as the
+ * first token of a line so a server called `jam-something`, or the word
+ * appearing in a URL, cannot be mistaken for it.
+ *
+ * ponytail: this reads another program's table. If either changes its listing
+ * format the effect is a redundant registration attempt, not a wrong one -
+ * `mcp add` on an existing entry writes the same launcher line back.
+ */
+export function listsJamEntry(stdout) {
+    return stdout
+        .replace(ANSI, "")
+        .split(/\r?\n/)
+        .some((line) => /^\s*jam(?=[\s:])/.test(line));
+}
+/**
+ * Ask each host what it has, and whether it is there at all.
+ *
+ * Read-only by construction: `mcp list` reports. A host that cannot be reached
+ * is recorded as unavailable rather than assumed empty - so planning has
+ * something to refuse rather than something to guess.
+ */
+export function detectHosts(run = defaultHostRunner) {
+    // The wizard re-detects after each step, and Claude Code health-checks every
+    // configured server while listing - seconds each time. The answer cannot
+    // change inside one command, so it is asked once. Only the real runner is
+    // cached; an injected one is a test, and must always be called.
+    if (run === defaultHostRunner && cachedHosts)
+        return cachedHosts;
+    const probed = probeHosts(run);
+    if (run === defaultHostRunner)
+        cachedHosts = probed;
+    return probed;
+}
+let cachedHosts;
+function probeHosts(run) {
+    return ADAPTERS.map((adapter) => {
+        const result = run(adapter.probe);
+        if (result.failed || result.status !== 0) {
+            return { id: adapter.id, cliAvailable: false, hasJamEntry: false };
+        }
+        return {
+            id: adapter.id,
+            cliAvailable: true,
+            hasJamEntry: listsJamEntry(result.stdout),
+        };
+    });
+}
+/** How a person would do it by hand, for the hosts JAM could not reach. */
+export function describeHostCommand({ command, args }) {
+    return [command, ...args].join(" ");
+}

package/dist/bootstrap/jira-projects.d.ts

@@ -0,0 +1,16 @@
+import type { CredentialPort } from "../ports/credentials.port.js";
+import type { ProjectRef } from "../ports/jira-read.port.js";
+export type VisibleProjects = {
+    projects: ProjectRef[];
+    truncated: boolean;
+    /** Set when the list could not be fetched; the caller still has to ask the user. */
+    error?: string;
+};
+/**
+ * Advisory list of Jira projects this account can see.
+ *
+ * Used only to help a person (or an agent's user) pick a key when none could
+ * be decided safely. It never selects one - Safe Bootstrap holds regardless of
+ * how many projects come back.
+ */
+export declare function listVisibleProjects(credentials?: CredentialPort): Promise<VisibleProjects>;

package/dist/bootstrap/jira-projects.js

@@ -0,0 +1,24 @@
+import { CompositeCredentialProvider } from "../adapters/credentials/composite.js";
+import { ProjectConfigSchema } from "../config/schema.js";
+/**
+ * Advisory list of Jira projects this account can see.
+ *
+ * Used only to help a person (or an agent's user) pick a key when none could
+ * be decided safely. It never selects one - Safe Bootstrap holds regardless of
+ * how many projects come back.
+ */
+export async function listVisibleProjects(credentials = new CompositeCredentialProvider()) {
+    const described = credentials.describe();
+    if (!described.baseUrl || !described.email || !described.hasToken) {
+        return { projects: [], truncated: false, error: "Jira credentials are not configured." };
+    }
+    try {
+        const { JiraCloudReadAdapter } = await import("../adapters/jira-cloud/jira-read.adapter.js");
+        const jira = new JiraCloudReadAdapter(credentials, ProjectConfigSchema.parse({}));
+        return await jira.listProjects();
+    }
+    catch (err) {
+        const { toJamError } = await import("../domain/errors.js");
+        return { projects: [], truncated: false, error: toJamError(err).message };
+    }
+}

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

@@ -0,0 +1,58 @@
+/**
+ * The canonical jam entry for a project's `.mcp.json`.
+ *
+ * Goes through the launcher rather than naming a JAM install directly, so the
+ * file says only "this project uses JAM" - which build actually runs is the
+ * reader's own choice, in their own ~/.jam/config.yaml. That is what makes
+ * this line safe to commit and share across machines.
+ *
+ * Pinned to an exact version. A floating tag would silently change what a
+ * teammate's editor launches.
+ */
+export declare const LAUNCHER_PACKAGE_SPEC = "@jam-mcp/launcher@1.0.0";
+export declare const JAM_MCP_ENTRY: {
+    readonly command: "npx";
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.0.0", "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.
+ */
+export declare function isLegacyJamEntry(entry: unknown): boolean;
+export type McpMergeResult = {
+    path: string;
+    /** "created" | "added" | "unchanged" - what actually happened to the file. */
+    action: "created" | "added" | "unchanged";
+};
+export type McpInspection = {
+    path: string;
+    exists: boolean;
+    /** True when the file exists but is not valid JSON - callers must not overwrite it blindly. */
+    unreadable: boolean;
+    hasJamEntry: boolean;
+    /** Entry names other than "jam", which must survive any mutation. */
+    otherServers: string[];
+    jamEntry?: unknown;
+};
+/**
+ * Read `.mcp.json` without touching it. This is what lets `setup plan` report
+ * what it *would* do: the decision is made here once, and apply only writes.
+ */
+export declare function inspectMcpConfig(root: string): McpInspection;
+/**
+ * Write a jam entry into `.mcp.json`, preserving every other server verbatim.
+ *
+ * Unconditional by design - the caller decides *whether* to write; this only
+ * decides *how*, so that "should I touch this file" lives in exactly one place.
+ */
+export declare function writeJamMcpEntry(root: string, entry?: unknown): string;
+/**
+ * Merge a PATH-based JAM entry into `.mcp.json`, preserving everything else.
+ *
+ * Deliberately does NOT record an absolute path to this JAM checkout - that
+ * would break the moment a teammate clones to a different location. `command:
+ * "jam"` relies on `jam` being on PATH (see `jam setup`'s PATH check), which is
+ * what keeps this file safe to commit and share.
+ */
+export declare function mergeMcpConfig(root: string): McpMergeResult;

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

@@ -0,0 +1,119 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { SERVER_VERSION } from "@jam-mcp/launcher";
+/**
+ * The canonical jam entry for a project's `.mcp.json`.
+ *
+ * Goes through the launcher rather than naming a JAM install directly, so the
+ * file says only "this project uses JAM" - which build actually runs is the
+ * reader's own choice, in their own ~/.jam/config.yaml. That is what makes
+ * this line safe to commit and share across machines.
+ *
+ * Pinned to an exact version. A floating tag would silently change what a
+ * teammate's editor launches.
+ */
+export const LAUNCHER_PACKAGE_SPEC = `@jam-mcp/launcher@${SERVER_VERSION}`;
+export const JAM_MCP_ENTRY = {
+    command: "npx",
+    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.
+ */
+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)) {
+        return !args.some((arg) => typeof arg === "string" && arg.startsWith("@jam-mcp/launcher@"));
+    }
+    return false;
+}
+/**
+ * Read `.mcp.json` without touching it. This is what lets `setup plan` report
+ * what it *would* do: the decision is made here once, and apply only writes.
+ */
+export function inspectMcpConfig(root) {
+    const path = join(root, ".mcp.json");
+    if (!existsSync(path)) {
+        return { path, exists: false, unreadable: false, hasJamEntry: false, otherServers: [] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return { path, exists: true, unreadable: true, hasJamEntry: false, otherServers: [] };
+    }
+    const servers = parsed.mcpServers ?? {};
+    const inspection = {
+        path,
+        exists: true,
+        unreadable: false,
+        hasJamEntry: Boolean(servers["jam"]),
+        otherServers: Object.keys(servers).filter((name) => name !== "jam"),
+    };
+    if (servers["jam"])
+        inspection.jamEntry = servers["jam"];
+    return inspection;
+}
+/**
+ * Write a jam entry into `.mcp.json`, preserving every other server verbatim.
+ *
+ * Unconditional by design - the caller decides *whether* to write; this only
+ * decides *how*, so that "should I touch this file" lives in exactly one place.
+ */
+export function writeJamMcpEntry(root, entry = JAM_MCP_ENTRY) {
+    const path = join(root, ".mcp.json");
+    let parsed = {};
+    if (existsSync(path)) {
+        try {
+            parsed = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch (err) {
+            throw new Error(`Could not parse existing ${path}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const servers = parsed["mcpServers"] ?? {};
+    const merged = { ...parsed, mcpServers: { ...servers, jam: entry } };
+    writeFileSync(path, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+    return path;
+}
+/**
+ * Merge a PATH-based JAM entry into `.mcp.json`, preserving everything else.
+ *
+ * Deliberately does NOT record an absolute path to this JAM checkout - that
+ * would break the moment a teammate clones to a different location. `command:
+ * "jam"` relies on `jam` being on PATH (see `jam setup`'s PATH check), which is
+ * what keeps this file safe to commit and share.
+ */
+export function mergeMcpConfig(root) {
+    const path = join(root, ".mcp.json");
+    if (!existsSync(path)) {
+        writeFileSync(path, `${JSON.stringify({ mcpServers: { jam: JAM_MCP_ENTRY } }, null, 2)}\n`, "utf8");
+        return { path, action: "created" };
+    }
+    const raw = readFileSync(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Could not parse existing ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (parsed.mcpServers?.["jam"]) {
+        return { path, action: "unchanged" };
+    }
+    const merged = {
+        ...parsed,
+        mcpServers: { ...(parsed.mcpServers ?? {}), jam: JAM_MCP_ENTRY },
+    };
+    writeFileSync(path, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+    return { path, action: "added" };
+}

package/dist/bootstrap/migration-target.d.ts

@@ -0,0 +1,60 @@
+import { type PlanOptions, type SetupPlan } from "./setup-plan.js";
+import type { SetupState } from "./setup-state.js";
+/**
+ * Whether the package a migration would point `.mcp.json` at can actually be
+ * resolved right now.
+ *
+ * `--migrate` is the one path that rewrites wiring a teammate already has
+ * working. Rewriting it toward something that cannot be fetched turns a working
+ * configuration into a broken one, and the failure surfaces much later - as a
+ * module-not-found from inside the editor's MCP child process.
+ */
+export type MigrationTarget = {
+    spec: string;
+    available: boolean;
+    /**
+     * `not-found` - the registry answered, and this spec is not there. That may
+     * mean unpublished, or simply absent from the registry this user is
+     * configured against; the check cannot tell those apart and does not claim to.
+     * `unverifiable` - no usable answer at all (offline, proxy, timeout, no npm).
+     */
+    reason?: "not-found" | "unverifiable";
+    detail?: string;
+};
+/** Result shape of a `spawnSync`-style call, narrowed to what the check reads. */
+export type RunResult = {
+    status: number | null;
+    stderr: string;
+    error?: NodeJS.ErrnoException;
+};
+/** Injected by tests so the suite never shells out or reaches a registry. */
+export type RunFn = (command: string, args: string[]) => RunResult;
+/**
+ * Ask npm whether `spec` resolves, using the user's own npm configuration.
+ *
+ * `npm view` rather than a direct registry request on purpose: it honours the
+ * user's `.npmrc`, scoped auth, proxy and custom registry, so a privately
+ * published launcher answers correctly instead of looking missing.
+ *
+ * Fails closed. Everything that cannot be verified - offline, blocked proxy,
+ * npm not on PATH, timeout - would also break `npx --yes <spec> serve` at launch
+ * time, so "cannot verify" and "would not work" are the same population.
+ *
+ * The spec is derived from a release constant, never from user input.
+ */
+export declare function checkMigrationTarget(spec?: string, run?: RunFn): MigrationTarget;
+/**
+ * Plan, probing the migration target only when a destructive replacement is
+ * actually pending.
+ *
+ * The probe is gated on the *plan*, not on the `--migrate` flag. A flag alone
+ * would make setup reach the network in cases that never rewrite anything -
+ * no `.mcp.json`, no jam entry, already canonical wiring, or a stop earlier in
+ * the plan - which would add a network dependency and an offline timeout for
+ * nothing.
+ *
+ * `computeSetupPlan` is pure, so planning twice costs nothing and keeps the
+ * probe out of the planner: the first pass answers "is an unverified
+ * replacement pending", the second decides with the fact in hand.
+ */
+export declare function computeSetupPlanWithPreflight(state: SetupState, options?: PlanOptions, check?: () => MigrationTarget): SetupPlan;

package/dist/bootstrap/migration-target.js

@@ -0,0 +1,80 @@
+import { spawnSync } from "node:child_process";
+import { LAUNCHER_PACKAGE_SPEC } from "./mcp-config-merger.js";
+import { computeSetupPlan } from "./setup-plan.js";
+const PROBE_TIMEOUT_MS = 10_000;
+function runNpm(command, args) {
+    const result = spawnSync(command, args, {
+        encoding: "utf8",
+        timeout: PROBE_TIMEOUT_MS,
+        // npm on Windows is a shell script, not an executable.
+        shell: process.platform === "win32",
+    });
+    return {
+        status: result.status,
+        stderr: result.stderr ?? "",
+        ...(result.error ? { error: result.error } : {}),
+    };
+}
+/**
+ * Ask npm whether `spec` resolves, using the user's own npm configuration.
+ *
+ * `npm view` rather than a direct registry request on purpose: it honours the
+ * user's `.npmrc`, scoped auth, proxy and custom registry, so a privately
+ * published launcher answers correctly instead of looking missing.
+ *
+ * Fails closed. Everything that cannot be verified - offline, blocked proxy,
+ * npm not on PATH, timeout - would also break `npx --yes <spec> serve` at launch
+ * time, so "cannot verify" and "would not work" are the same population.
+ *
+ * The spec is derived from a release constant, never from user input.
+ */
+export function checkMigrationTarget(spec = LAUNCHER_PACKAGE_SPEC, run = runNpm) {
+    const result = run("npm", ["view", spec, "version"]);
+    // Checked first: both a failed spawn and a timeout leave `status` null.
+    if (result.error) {
+        return unverifiable(spec, result.error.code ?? result.error.message);
+    }
+    if (result.status === 0) {
+        return { spec, available: true };
+    }
+    if (/\bE404\b/.test(result.stderr)) {
+        return {
+            spec,
+            available: false,
+            reason: "not-found",
+            detail: `npm could not find ${spec} in the configured registry.`,
+        };
+    }
+    return unverifiable(spec, `npm view exited ${result.status ?? "without a status"}`);
+}
+function unverifiable(spec, detail) {
+    return {
+        spec,
+        available: false,
+        reason: "unverifiable",
+        detail: `Could not verify ${spec}: ${detail}`,
+    };
+}
+/**
+ * Plan, probing the migration target only when a destructive replacement is
+ * actually pending.
+ *
+ * The probe is gated on the *plan*, not on the `--migrate` flag. A flag alone
+ * would make setup reach the network in cases that never rewrite anything -
+ * no `.mcp.json`, no jam entry, already canonical wiring, or a stop earlier in
+ * the plan - which would add a network dependency and an offline timeout for
+ * nothing.
+ *
+ * `computeSetupPlan` is pure, so planning twice costs nothing and keeps the
+ * probe out of the planner: the first pass answers "is an unverified
+ * replacement pending", the second decides with the fact in hand.
+ */
+export function computeSetupPlanWithPreflight(state, options = {}, check = () => checkMigrationTarget()) {
+    // An injected target is authoritative - never probe over the caller's answer.
+    if (options.migrationTarget)
+        return computeSetupPlan(state, options);
+    const planned = computeSetupPlan(state, options);
+    if (planned.code !== "JAM_MIGRATION_TARGET_UNAVAILABLE")
+        return planned;
+    return computeSetupPlan(state, { ...options, migrationTarget: check() });
+}

package/dist/bootstrap/project-bindings.d.ts

@@ -0,0 +1,48 @@
+/**
+ * One workspace bound to one Jira project, for this user only.
+ *
+ * `path` is provenance for the human reading the file - JAM resolves by
+ * `workspace` and never by path, so editing it repoints nothing.
+ */
+export type ProjectBinding = {
+    workspace: string;
+    key: string;
+    path?: string;
+};
+/**
+ * Why reading distinguishes three states rather than returning a list:
+ * discovery can shrug at a broken file, but a write must not. Rewriting the
+ * whole file from an empty list that actually meant "could not parse" destroys
+ * bindings that are still in there.
+ */
+export type BindingsInspection = {
+    path: string;
+    status: "absent" | "parsed" | "unreadable";
+    bindings: ProjectBinding[];
+    /** Set when status is "unreadable". */
+    reason?: string;
+};
+/**
+ * User-local, and deliberately separate from `~/.jam/config.yaml`: that file
+ * answers which JAM build runs, this one answers which Jira project a
+ * workspace belongs to, and neither should move when the other changes.
+ */
+export declare function projectBindingsPath(home?: string): string;
+/** Read-only. Never creates the directory, so `detect` stays free of writes. */
+export declare function inspectProjectBindings(home?: string): BindingsInspection;
+/**
+ * Discovery. A damaged file yields no bindings rather than turning every
+ * command into an error - the same stance the preset file and the runtime
+ * config already take.
+ */
+export declare function readProjectBindings(home?: string): ProjectBinding[];
+export declare function findProjectBinding(workspaceId: string, home?: string): ProjectBinding | undefined;
+/**
+ * Record one binding, preserving every other entry.
+ *
+ * Fail-closed on a file that exists but will not parse: refusing costs the
+ * user one edit, while rewriting would silently drop bindings this build
+ * could not read. Same reasoning as `.mcp.json`, which is never overwritten
+ * when it does not parse.
+ */
+export declare function writeProjectBinding(binding: ProjectBinding, home?: string): string;

package/dist/bootstrap/project-bindings.js

@@ -0,0 +1,112 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { JamError } from "../domain/errors.js";
+const FILE_VERSION = 1;
+const HEADER = "# JAM personal project bindings for this user. Safe to edit by hand.\n" +
+    "# Never put Jira credentials here.\n" +
+    "# `path` is provenance only - JAM matches on `workspace`.\n";
+/**
+ * User-local, and deliberately separate from `~/.jam/config.yaml`: that file
+ * answers which JAM build runs, this one answers which Jira project a
+ * workspace belongs to, and neither should move when the other changes.
+ */
+export function projectBindingsPath(home = homedir()) {
+    return join(home, ".jam", "projects.yaml");
+}
+/** Read-only. Never creates the directory, so `detect` stays free of writes. */
+export function inspectProjectBindings(home) {
+    const path = projectBindingsPath(home);
+    if (!existsSync(path))
+        return { path, status: "absent", bindings: [] };
+    let raw;
+    try {
+        raw = parseYaml(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        return {
+            path,
+            status: "unreadable",
+            bindings: [],
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+    if (!raw || typeof raw !== "object") {
+        return { path, status: "unreadable", bindings: [], reason: "not a mapping" };
+    }
+    const version = raw.version;
+    if (version !== undefined && version !== FILE_VERSION) {
+        // A newer file is not a broken one, but this build cannot promise to
+        // rewrite it without losing whatever it does not understand.
+        return {
+            path,
+            status: "unreadable",
+            bindings: [],
+            reason: `version ${String(version)} is not supported by this build`,
+        };
+    }
+    // `bindings:` with nothing after it parses as null, which is what a person
+    // is left with after deleting the last entry by hand. That is an empty list,
+    // not a damaged file - refusing to write there would be a dead end.
+    const list = raw.bindings ?? [];
+    if (!Array.isArray(list)) {
+        return { path, status: "unreadable", bindings: [], reason: "`bindings` is not a list" };
+    }
+    const bindings = [];
+    for (const entry of (list ?? [])) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const workspace = entry.workspace;
+        const key = entry.key;
+        if (typeof workspace !== "string" || !workspace.trim())
+            continue;
+        if (typeof key !== "string" || !key.trim())
+            continue;
+        const path_ = entry.path;
+        bindings.push({
+            workspace: workspace.trim(),
+            key: key.trim(),
+            ...(typeof path_ === "string" && path_.trim() ? { path: path_.trim() } : {}),
+        });
+    }
+    return { path, status: "parsed", bindings };
+}
+/**
+ * Discovery. A damaged file yields no bindings rather than turning every
+ * command into an error - the same stance the preset file and the runtime
+ * config already take.
+ */
+export function readProjectBindings(home) {
+    return inspectProjectBindings(home).bindings;
+}
+export function findProjectBinding(workspaceId, home) {
+    return readProjectBindings(home).find((b) => b.workspace === workspaceId);
+}
+/**
+ * Record one binding, preserving every other entry.
+ *
+ * Fail-closed on a file that exists but will not parse: refusing costs the
+ * user one edit, while rewriting would silently drop bindings this build
+ * could not read. Same reasoning as `.mcp.json`, which is never overwritten
+ * when it does not parse.
+ */
+export function writeProjectBinding(binding, home) {
+    const inspection = inspectProjectBindings(home);
+    if (inspection.status === "unreadable") {
+        throw new JamError("JAM_BINDINGS_UNREADABLE", `Refusing to rewrite ${inspection.path}: ${inspection.reason ?? "it could not be read"}. Fix or remove that file, then try again.`, { path: inspection.path });
+    }
+    const kept = inspection.bindings.filter((b) => b.workspace !== binding.workspace);
+    const next = [...kept, binding].sort((a, b) => a.workspace.localeCompare(b.workspace));
+    const body = next
+        .map((b) => {
+        const lines = [`  - workspace: ${JSON.stringify(b.workspace)}`, `    key: ${b.key}`];
+        if (b.path)
+            lines.push(`    path: ${JSON.stringify(b.path)}`);
+        return lines.join("\n");
+    })
+        .join("\n");
+    mkdirSync(dirname(inspection.path), { recursive: true });
+    writeFileSync(inspection.path, `${HEADER}version: ${FILE_VERSION}\n\nbindings:\n${body}\n`, "utf8");
+    return inspection.path;
+}

package/dist/bootstrap/project-config-bootstrapper.d.ts

@@ -0,0 +1,37 @@
+export type BootstrapSource = "explicit" | "env" | "binding" | "preset";
+export type KeyDecision = {
+    key: string;
+    source: BootstrapSource;
+};
+export declare const DEFAULT_PRESETS_PATH: string;
+export type DecideProjectKeyOptions = {
+    explicitKey?: string;
+    env?: NodeJS.ProcessEnv;
+    /**
+     * The key this user has bound to this workspace, already looked up. Passed
+     * in rather than read here so this function stays a pure ordering of
+     * explicit sources.
+     */
+    bindingKey?: string;
+    presetsPath?: string;
+};
+/**
+ * Decide a project key from explicit sources only - JAM never guesses a Jira
+ * project from a folder or repo name. Order: `--project` flag, then
+ * `JAM_PROJECT_KEY`, then this user's binding for the workspace, then a
+ * matching entry in the legacy preset file. Returns undefined when none
+ * apply, which the caller must treat as "cannot decide safely".
+ *
+ * Flag over environment over persisted, because what someone typed for this
+ * run should beat what a shell exported, which should beat what was recorded
+ * some time ago.
+ */
+export declare function decideProjectKey(root: string, options?: DecideProjectKeyOptions): KeyDecision | undefined;
+/** Windows paths are case-insensitive; every other platform is compared as-is. */
+export declare function normalizePath(p: string): string;
+/**
+ * Writes the minimal `.jira-agent/project.yaml`. Only the key is set - every
+ * other field is left to the schema's built-in defaults so this file stays
+ * legible and merge-friendly.
+ */
+export declare function writeBootstrapConfig(root: string, key: string): string;