@jam-mcp/server 1.0.0

package/dist/bootstrap/project-config-bootstrapper.js

@@ -0,0 +1,69 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+export const DEFAULT_PRESETS_PATH = join(homedir(), ".jira-agent", "presets.yaml");
+/**
+ * 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 function decideProjectKey(root, options = {}) {
+    const explicit = options.explicitKey?.trim();
+    if (explicit)
+        return { key: explicit, source: "explicit" };
+    const envKey = (options.env ?? process.env).JAM_PROJECT_KEY?.trim();
+    if (envKey)
+        return { key: envKey, source: "env" };
+    const bindingKey = options.bindingKey?.trim();
+    if (bindingKey)
+        return { key: bindingKey, source: "binding" };
+    const preset = findPresetKey(root, options.presetsPath ?? DEFAULT_PRESETS_PATH);
+    if (preset)
+        return { key: preset, source: "preset" };
+    return undefined;
+}
+function findPresetKey(root, presetsPath) {
+    if (!existsSync(presetsPath))
+        return undefined;
+    let parsed;
+    try {
+        parsed = (parseYaml(readFileSync(presetsPath, "utf8")) ?? {});
+    }
+    catch {
+        // A broken preset file should not crash bootstrap - just skip it.
+        return undefined;
+    }
+    const target = normalizePath(root);
+    for (const entry of parsed.projects ?? []) {
+        if (!entry.match || !entry.key)
+            continue;
+        if (normalizePath(entry.match) === target)
+            return entry.key;
+    }
+    return undefined;
+}
+/** Windows paths are case-insensitive; every other platform is compared as-is. */
+export function normalizePath(p) {
+    const resolved = resolve(p);
+    return platform() === "win32" ? resolved.toLowerCase() : resolved;
+}
+const GENERATED_HEADER = "# Generated by JAM. Safe to commit.\n";
+/**
+ * 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 function writeBootstrapConfig(root, key) {
+    const dir = join(root, ".jira-agent");
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, "project.yaml");
+    writeFileSync(path, `${GENERATED_HEADER}version: 1\n\nproject:\n  key: ${key}\n`, "utf8");
+    return path;
+}

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

@@ -0,0 +1,53 @@
+import { type ProjectConfig } from "../config/schema.js";
+import { type BootstrapSource } from "./project-config-bootstrapper.js";
+import { type GitRemoteFn } from "./workspace-identity.js";
+export type ResolvedProjectConfig = {
+    config: ProjectConfig;
+    configPath?: string;
+    root: string;
+    /**
+     * Where the key came from when no config file supplied it. Undefined when
+     * `configPath` is set - "from the file" is what `configPath` already says.
+     */
+    keySource?: BootstrapSource;
+};
+export type ResolveConfigOptions = {
+    cwd?: string;
+    /**
+     * What to do when the project has no config file.
+     *
+     * - `"required"` - fall back to an explicit key (flag, env, personal
+     *   binding, preset) and throw JAM_SETUP_REQUIRED when none applies.
+     *   `jam serve` cannot start without one.
+     * - `"optional"` - resolve the same way, but fall back to schema defaults
+     *   instead of throwing. `jam doctor` reports the state of the machine;
+     *   refusing to load would leave it with nothing to report.
+     * - absent - no fallback at all.
+     *
+     * Resolution either way. Nothing here is ever written.
+     */
+    keyFallback?: "required" | "optional";
+    /** `--project` override, only consulted when `keyFallback` is set. */
+    explicitKey?: string;
+    /** Injected by tests so a decision never depends on the machine's JAM_PROJECT_KEY. */
+    env?: NodeJS.ProcessEnv;
+    /** Injected by tests so a decision never reads the developer's own presets. */
+    presetsPath?: string;
+    /** Injected by tests to isolate `~/.jam`. */
+    home?: string;
+    /** Injected by tests so identity never depends on the checkout under test. */
+    git?: GitRemoteFn;
+};
+/**
+ * Find this project's JAM config, or decide its key in memory.
+ *
+ * Reads and decides; it never writes. Persisting a decision is `jam setup`'s
+ * job alone (`setup-apply.ts`), because creating a file in someone's
+ * repository is a change they asked for, not a side effect of starting a
+ * server.
+ *
+ * Throws JAM_SETUP_REQUIRED when a key is allowed to come from a fallback but
+ * no explicit source can supply one - JAM never guesses a Jira project from a
+ * repo or folder name.
+ */
+export declare function resolveProjectConfig(options?: ResolveConfigOptions): ResolvedProjectConfig;

package/dist/bootstrap/project-config-resolver.js

@@ -0,0 +1,59 @@
+import { resolve } from "node:path";
+import { loadConfig } from "../config/load-config.js";
+import { ProjectConfigSchema } from "../config/schema.js";
+import { JamError } from "../domain/errors.js";
+import { findProjectBinding } from "./project-bindings.js";
+import { decideProjectKey } from "./project-config-bootstrapper.js";
+import { resolveProjectRoot } from "./project-root-resolver.js";
+import { workspaceIdentity } from "./workspace-identity.js";
+/**
+ * Find this project's JAM config, or decide its key in memory.
+ *
+ * Reads and decides; it never writes. Persisting a decision is `jam setup`'s
+ * job alone (`setup-apply.ts`), because creating a file in someone's
+ * repository is a change they asked for, not a side effect of starting a
+ * server.
+ *
+ * Throws JAM_SETUP_REQUIRED when a key is allowed to come from a fallback but
+ * no explicit source can supply one - JAM never guesses a Jira project from a
+ * repo or folder name.
+ */
+export function resolveProjectConfig(options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const { root, hasConfig, gitRoot } = resolveProjectRoot(cwd);
+    if (hasConfig) {
+        const loaded = loadConfig(root);
+        return { config: loaded.config, configPath: loaded.path, root };
+    }
+    if (!options.keyFallback) {
+        const loaded = loadConfig(cwd);
+        return { config: loaded.config, configPath: loaded.path, root };
+    }
+    // Read only: a personal binding is consulted here and written nowhere, so
+    // starting a server leaves the user's own files alone as well as the repo's.
+    const bindingKey = findProjectBinding(workspaceIdentity(root, {
+        ...(gitRoot ? { gitRoot } : {}),
+        ...(options.git ? { git: options.git } : {}),
+    }), options.home)?.key;
+    const decision = decideProjectKey(root, {
+        ...(options.explicitKey ? { explicitKey: options.explicitKey } : {}),
+        ...(options.env ? { env: options.env } : {}),
+        ...(bindingKey ? { bindingKey } : {}),
+        ...(options.presetsPath ? { presetsPath: options.presetsPath } : {}),
+    });
+    if (!decision) {
+        if (options.keyFallback === "optional") {
+            const loaded = loadConfig(cwd);
+            return { config: loaded.config, configPath: loaded.path, root };
+        }
+        throw new JamError("JAM_SETUP_REQUIRED", `No .jira-agent/project.yaml found under ${root}, and no project key could be determined safely (no --project, no JAM_PROJECT_KEY, no matching preset). Run \`jam setup --project <KEY>\`.`, { root });
+    }
+    // The file this used to write held nothing but the key: every other field
+    // came back from schema defaults on the next read. Parsing the key directly
+    // produces the same config without touching the repository.
+    return {
+        config: ProjectConfigSchema.parse({ project: { key: decision.key } }),
+        root,
+        keySource: decision.source,
+    };
+}

package/dist/bootstrap/project-root-resolver.d.ts

@@ -0,0 +1,22 @@
+export type ProjectRoot = {
+    root: string;
+    /** True when an existing `.jira-agent/project.yaml` was found at `root`. */
+    hasConfig: boolean;
+    /**
+     * The nearest enclosing repository, when there is one. Already found on the
+     * way up; reported so workspace identity does not have to walk again.
+     */
+    gitRoot?: string;
+};
+/**
+ * Nearest-ancestor search from `startDir`:
+ *   1. the nearest `.jira-agent/project.yaml` - that directory is the root
+ *   2. else the nearest `.git` - a FILE in a worktree/submodule counts just as
+ *      much as a directory, since `existsSync` doesn't care which
+ *   3. else `startDir` itself, so JAM still boots outside any repo
+ *
+ * This is deliberately the nearest ancestor, not the outermost repo root - a
+ * project nested inside a monorepo should not have JAM walk past its own
+ * `.git` into the monorepo's.
+ */
+export declare function resolveProjectRoot(startDir?: string): ProjectRoot;

package/dist/bootstrap/project-root-resolver.js

@@ -0,0 +1,43 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { CONFIG_RELATIVE_PATH } from "../config/load-config.js";
+/**
+ * Nearest-ancestor search from `startDir`:
+ *   1. the nearest `.jira-agent/project.yaml` - that directory is the root
+ *   2. else the nearest `.git` - a FILE in a worktree/submodule counts just as
+ *      much as a directory, since `existsSync` doesn't care which
+ *   3. else `startDir` itself, so JAM still boots outside any repo
+ *
+ * This is deliberately the nearest ancestor, not the outermost repo root - a
+ * project nested inside a monorepo should not have JAM walk past its own
+ * `.git` into the monorepo's.
+ */
+export function resolveProjectRoot(startDir = process.cwd()) {
+    let dir = resolve(startDir);
+    let gitRoot;
+    let configRoot;
+    for (;;) {
+        if (configRoot === undefined && existsSync(join(dir, CONFIG_RELATIVE_PATH))) {
+            configRoot = dir;
+            // Keep walking only far enough to learn which repository this is in;
+            // the config still decides the root.
+            if (gitRoot !== undefined)
+                break;
+        }
+        if (gitRoot === undefined && existsSync(join(dir, ".git"))) {
+            gitRoot = dir;
+            if (configRoot !== undefined)
+                break;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    const root = configRoot ?? gitRoot ?? resolve(startDir);
+    return {
+        root,
+        hasConfig: configRoot !== undefined,
+        ...(gitRoot ? { gitRoot } : {}),
+    };
+}

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

@@ -0,0 +1,31 @@
+import { type HostRunner } from "./host-mcp.js";
+import type { SetupChange, SetupPlan } from "./setup-plan.js";
+export type AppliedChange = SetupChange & {
+    applied: true;
+};
+export type ApplyResult = {
+    applied: AppliedChange[];
+    /** Mirrors plan.changes.length > 0 - useful for agents deciding what to report. */
+    changesApplied: boolean;
+};
+export type ApplyOptions = {
+    /** Project root; defaults to the root recorded in the plan. */
+    root?: string;
+    /** The jam entry to write. Defaults to the canonical form. */
+    mcpEntry?: unknown;
+    /** Injected by tests to isolate ~/.jam. */
+    home?: string;
+    /** Injected by tests so no test ever registers JAM with a real host. */
+    runHost?: HostRunner;
+};
+/**
+ * Execute exactly the changes a plan listed - nothing more.
+ *
+ * Apply deliberately re-decides nothing. If a change is not in the plan it
+ * does not happen, which is what makes `plan` a trustworthy preview and keeps
+ * human and agent paths honest about what they are about to do.
+ *
+ * Idempotent in practice: re-detecting after an apply produces a plan with no
+ * changes, so running setup twice is a no-op rather than a rewrite.
+ */
+export declare function applySetupPlan(plan: SetupPlan, options?: ApplyOptions): ApplyResult;

package/dist/bootstrap/setup-apply.js

@@ -0,0 +1,61 @@
+import { defaultHostRunner } from "./host-mcp.js";
+import { JAM_MCP_ENTRY, writeJamMcpEntry } from "./mcp-config-merger.js";
+import { writeProjectBinding } from "./project-bindings.js";
+import { writeBootstrapConfig } from "./project-config-bootstrapper.js";
+/**
+ * Execute exactly the changes a plan listed - nothing more.
+ *
+ * Apply deliberately re-decides nothing. If a change is not in the plan it
+ * does not happen, which is what makes `plan` a trustworthy preview and keeps
+ * human and agent paths honest about what they are about to do.
+ *
+ * Idempotent in practice: re-detecting after an apply produces a plan with no
+ * changes, so running setup twice is a no-op rather than a rewrite.
+ */
+export function applySetupPlan(plan, options = {}) {
+    const root = options.root ?? plan.project?.root;
+    const applied = [];
+    for (const change of plan.changes) {
+        switch (change.target) {
+            case "project-config": {
+                if (!root)
+                    throw new Error("Cannot apply a project-config change without a project root.");
+                writeBootstrapConfig(root, change.key);
+                applied.push({ ...change, applied: true });
+                break;
+            }
+            case "mcp-config": {
+                if (!root)
+                    throw new Error("Cannot apply an mcp-config change without a project root.");
+                writeJamMcpEntry(root, options.mcpEntry ?? JAM_MCP_ENTRY);
+                applied.push({ ...change, applied: true });
+                break;
+            }
+            case "host-mcp": {
+                // The argv came from the plan, so this runs what was previewed and
+                // 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;
+                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(" ")}`);
+                }
+                applied.push({ ...change, applied: true });
+                break;
+            }
+            case "personal-binding": {
+                // Everything needed is in the change. The workspace was identified and
+                // the key decided at plan time, so applying cannot reach a different
+                // answer than the one previewed.
+                writeProjectBinding({
+                    workspace: change.workspaceId,
+                    key: change.key,
+                    ...(root ? { path: root } : {}),
+                }, options.home);
+                applied.push({ ...change, applied: true });
+                break;
+            }
+        }
+    }
+    return { applied, changesApplied: applied.length > 0 };
+}

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

@@ -0,0 +1,102 @@
+import { type HostId } from "./host-mcp.js";
+import type { MigrationTarget } from "./migration-target.js";
+import { type BootstrapSource } from "./project-config-bootstrapper.js";
+import type { SetupState } from "./setup-state.js";
+export type SetupStatus = "already_configured" | "ready_to_apply" | "user_action_required";
+export type SetupCode = "JAM_PROJECT_SELECTION_REQUIRED" | "JAM_BINDINGS_UNREADABLE" | "JAM_AUTH_REQUIRED" | "JAM_RUNTIME_CONFIG_MISSING" | "JAM_PROJECT_CONFIG_INVALID" | "JAM_MCP_CONFIG_UNREADABLE" | "JAM_MIGRATION_TARGET_UNAVAILABLE";
+export type SetupChange = {
+    type: "create";
+    target: "project-config";
+    path: string;
+    key: string;
+    keySource: BootstrapSource;
+} | {
+    type: "create";
+    target: "mcp-config";
+    path: string;
+} | {
+    type: "merge";
+    target: "mcp-config";
+    path: string;
+    preserveExisting: string[];
+} | {
+    type: "replace";
+    target: "mcp-config";
+    path: string;
+    reason: "migrate";
+} | {
+    type: "create" | "replace";
+    target: "personal-binding";
+    path: string;
+    workspaceId: string;
+    key: string;
+    keySource: BootstrapSource;
+    /** Present on a rebind, so the preview shows what is being replaced. */
+    previousKey?: string;
+} | {
+    type: "create";
+    target: "host-mcp";
+    host: HostId;
+    /**
+     * The exact argv apply will run, decided here and never recomputed -
+     * so `plan --json` shows what is about to happen, and running a host's
+     * CLI stays on the apply side of the line.
+     */
+    command: string;
+    args: string[];
+};
+export type SetupPlan = {
+    status: SetupStatus;
+    code?: SetupCode;
+    changes: SetupChange[];
+    requiresUserAction: boolean;
+    /** Populated by the caller when status is JAM_PROJECT_SELECTION_REQUIRED. */
+    projects?: {
+        key: string;
+        name: string;
+    }[];
+    /** Why a requested migration was refused, when status is JAM_MIGRATION_TARGET_UNAVAILABLE. */
+    migrationTarget?: MigrationTarget;
+    nextAction?: {
+        type: "authenticate" | "select_project" | "configure_runtime";
+        command?: string;
+    };
+    project?: {
+        root: string;
+        key?: string;
+    };
+};
+export type PlanOptions = {
+    /**
+     * `--shared`: adopt JAM for the team, writing `.jira-agent/project.yaml` and
+     * `.mcp.json` into the repository. Without it setup is personal and the
+     * repository is left alone - discovery is allowed, adoption is asked for.
+     */
+    shared?: boolean;
+    /** `--project KEY`. */
+    explicitKey?: string;
+    /** `--migrate`: rewrite a legacy jam entry instead of leaving it alone. */
+    migrate?: boolean;
+    env?: NodeJS.ProcessEnv;
+    presetsPath?: string;
+    /** True when the existing jam entry does not match the current canonical form. */
+    jamEntryIsLegacy?: boolean;
+    /**
+     * Whether the package a `--migrate` rewrite would point at can be resolved.
+     * Observed by the caller, like `jamEntryIsLegacy` - the planner never probes.
+     * Absent means not verified, and an unverified target refuses the rewrite.
+     */
+    migrationTarget?: MigrationTarget;
+};
+/**
+ * Decide what setup would do, changing nothing.
+ *
+ * Pure by construction: every input arrives through `state` and `options`, and
+ * the result is a list of changes for apply to execute verbatim. Keeping the
+ * decision separate from the mutation is what lets a human preview it, an
+ * agent reason about it, and both go through identical logic.
+ *
+ * Safe Bootstrap is preserved here: a project key comes from an explicit
+ * source or not at all. JAM never infers one from a repo or directory name.
+ */
+export declare function computeSetupPlan(state: SetupState, options?: PlanOptions): SetupPlan;

package/dist/bootstrap/setup-plan.js

@@ -0,0 +1,224 @@
+import { join } from "node:path";
+import { CONFIG_RELATIVE_PATH } from "../config/load-config.js";
+import { hostRegistration } from "./host-mcp.js";
+import { projectBindingsPath } from "./project-bindings.js";
+import { decideProjectKey } from "./project-config-bootstrapper.js";
+/**
+ * Decide what setup would do, changing nothing.
+ *
+ * Pure by construction: every input arrives through `state` and `options`, and
+ * the result is a list of changes for apply to execute verbatim. Keeping the
+ * decision separate from the mutation is what lets a human preview it, an
+ * agent reason about it, and both go through identical logic.
+ *
+ * Safe Bootstrap is preserved here: a project key comes from an explicit
+ * source or not at all. JAM never infers one from a repo or directory name.
+ */
+export function computeSetupPlan(state, options = {}) {
+    const changes = [];
+    const shared = options.shared ?? false;
+    // A config file that exists but cannot be parsed is a stop, not something to
+    // overwrite - the user's settings are in there. It is read in both scopes,
+    // so a broken one blocks either.
+    if (state.project.error) {
+        return {
+            status: "user_action_required",
+            code: "JAM_PROJECT_CONFIG_INVALID",
+            changes: [],
+            requiresUserAction: true,
+            project: { root: state.project.root },
+        };
+    }
+    // Personal setup never opens .mcp.json, so a broken one there is not its
+    // problem to report.
+    if (shared && state.mcp.unreadable) {
+        return {
+            status: "user_action_required",
+            code: "JAM_MCP_CONFIG_UNREADABLE",
+            changes: [],
+            requiresUserAction: true,
+            project: { root: state.project.root },
+        };
+    }
+    const key = resolveKey(state, options);
+    if (!key) {
+        return {
+            status: "user_action_required",
+            code: "JAM_PROJECT_SELECTION_REQUIRED",
+            changes: [],
+            requiresUserAction: true,
+            nextAction: { type: "select_project", command: "jam setup --project <KEY>" },
+            project: { root: state.project.root },
+        };
+    }
+    const project = { root: state.project.root, key: key.key };
+    if (!shared) {
+        // Personal scope: the record of "this workspace is that Jira project"
+        // lives with the user, and nothing in the repository is touched.
+        const bindingChange = planBindingChange(state, key);
+        if (bindingChange && state.bindingsUnreadable) {
+            return {
+                status: "user_action_required",
+                code: "JAM_BINDINGS_UNREADABLE",
+                changes: [],
+                requiresUserAction: true,
+                project,
+            };
+        }
+        if (bindingChange)
+            changes.push(bindingChange);
+        changes.push(...planHostChanges(state));
+        return finish(changes, state, project);
+    }
+    if (!state.project.hasConfig) {
+        changes.push({
+            type: "create",
+            target: "project-config",
+            path: joinConfigPath(state.project.root),
+            key: key.key,
+            keySource: key.source,
+        });
+    }
+    const mcpChange = planMcpChange(state, options);
+    // A migration replaces wiring the user already has working. Refuse to plan
+    // that against a destination nobody has confirmed is reachable - and answer
+    // the flag they typed before reporting anything else. The rest of the plan
+    // survives: declining the rewrite is no reason to leave the project unwired.
+    if (mcpChange?.type === "replace" && options.migrationTarget?.available !== true) {
+        return {
+            status: "user_action_required",
+            code: "JAM_MIGRATION_TARGET_UNAVAILABLE",
+            changes,
+            requiresUserAction: true,
+            ...(options.migrationTarget ? { migrationTarget: options.migrationTarget } : {}),
+            project,
+        };
+    }
+    if (mcpChange)
+        changes.push(mcpChange);
+    return finish(changes, state, project);
+}
+/**
+ * The stops that apply to either scope, and the verdict.
+ *
+ * Credentials and runtime are human boundaries: JAM can wire things up
+ * regardless, but it cannot authenticate on the user's behalf. Both stops
+ * therefore still carry their changes - apply them, then stop for the person.
+ */
+function finish(changes, state, project) {
+    if (!state.credentials.present) {
+        return {
+            status: "user_action_required",
+            code: "JAM_AUTH_REQUIRED",
+            changes,
+            requiresUserAction: true,
+            nextAction: { type: "authenticate" },
+            project,
+        };
+    }
+    if (!state.runtime.configured) {
+        return {
+            status: "user_action_required",
+            code: "JAM_RUNTIME_CONFIG_MISSING",
+            changes,
+            requiresUserAction: true,
+            nextAction: { type: "configure_runtime", command: "jam runtime use package" },
+            project,
+        };
+    }
+    return {
+        status: changes.length === 0 ? "already_configured" : "ready_to_apply",
+        changes,
+        requiresUserAction: false,
+        project,
+    };
+}
+/**
+ * Register JAM with each coding agent that can be reached and does not have
+ * it yet.
+ *
+ * A host whose CLI is missing gets no change at all: JAM will not guess at
+ * another program's config file, and a half-wired host reported as done is
+ * worse than one the user is told about. The caller prints the command for
+ * those.
+ */
+function planHostChanges(state) {
+    const changes = [];
+    for (const host of state.hosts) {
+        if (!host.cliAvailable || host.hasJamEntry)
+            continue;
+        const registration = hostRegistration(host.id);
+        if (!registration)
+            continue;
+        changes.push({
+            type: "create",
+            target: "host-mcp",
+            host: host.id,
+            command: registration.command,
+            args: registration.args,
+        });
+    }
+    return changes;
+}
+/**
+ * What the binding file should say, or nothing when it already says it.
+ *
+ * A repository that declares its own key needs no personal note: the team's
+ * file is already the answer, and recording a second copy would only create
+ * something to disagree with later.
+ */
+function planBindingChange(state, key) {
+    if (state.project.key)
+        return undefined;
+    const existing = state.project.binding;
+    if (existing?.key === key.key)
+        return undefined;
+    return {
+        type: existing ? "replace" : "create",
+        target: "personal-binding",
+        path: projectBindingsPath(),
+        workspaceId: state.workspaceId,
+        key: key.key,
+        keySource: key.source,
+        ...(existing ? { previousKey: existing.key } : {}),
+    };
+}
+function resolveKey(state, options) {
+    // An existing project.yaml wins: setup must never silently repoint a project,
+    // and a personal note must never override what the team committed.
+    if (state.project.key)
+        return { key: state.project.key, source: "explicit" };
+    const decideOptions = {};
+    if (options.explicitKey)
+        decideOptions.explicitKey = options.explicitKey;
+    if (options.env)
+        decideOptions.env = options.env;
+    if (state.project.binding)
+        decideOptions.bindingKey = state.project.binding.key;
+    if (options.presetsPath)
+        decideOptions.presetsPath = options.presetsPath;
+    return decideProjectKey(state.project.root, decideOptions);
+}
+function planMcpChange(state, options) {
+    if (!state.mcp.exists) {
+        return { type: "create", target: "mcp-config", path: state.mcp.path };
+    }
+    if (!state.mcp.hasJamEntry) {
+        return {
+            type: "merge",
+            target: "mcp-config",
+            path: state.mcp.path,
+            preserveExisting: state.mcp.otherServers,
+        };
+    }
+    // An existing jam entry is left alone unless migration was asked for
+    // explicitly - overwriting someone's customised wiring is not setup's call.
+    const legacy = options.jamEntryIsLegacy ?? state.mcp.jamEntryIsLegacy;
+    if (options.migrate && legacy) {
+        return { type: "replace", target: "mcp-config", path: state.mcp.path, reason: "migrate" };
+    }
+    return undefined;
+}
+function joinConfigPath(root) {
+    return join(root, CONFIG_RELATIVE_PATH);
+}