@jam-mcp/server 1.0.0

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

@@ -0,0 +1,73 @@
+import { type RuntimeMode } from "@jam-mcp/launcher";
+import type { CredentialPort, CredentialSource } from "../ports/credentials.port.js";
+import { type HostRunner, type HostState } from "./host-mcp.js";
+import { type McpInspection } from "./mcp-config-merger.js";
+import { type ProjectBinding } from "./project-bindings.js";
+import { type GitRemoteFn } from "./workspace-identity.js";
+export type RuntimeState = {
+    configured: boolean;
+    mode?: RuntimeMode;
+    source?: string;
+    version?: string;
+    /** Set when a runtime is configured but cannot currently be resolved. */
+    error?: string;
+};
+export type CredentialState = {
+    present: boolean;
+    source: CredentialSource;
+    baseUrl?: string;
+    email?: string;
+};
+export type ProjectState = {
+    root: string;
+    hasConfig: boolean;
+    configPath?: string;
+    key?: string;
+    /** Set when a config file exists but could not be parsed. */
+    error?: string;
+    /** What this user has bound this workspace to, if anything. */
+    binding?: ProjectBinding;
+};
+export type SetupState = {
+    cwd: string;
+    /** Stable id for this workspace - what a personal binding is recorded against. */
+    workspaceId: string;
+    /**
+     * True when `~/.jam/projects.yaml` exists but could not be read. Recorded
+     * rather than thrown so planning can refuse to rewrite it, instead of
+     * discovering the problem halfway through applying.
+     */
+    bindingsUnreadable: boolean;
+    runtime: RuntimeState;
+    credentials: CredentialState;
+    project: ProjectState;
+    mcp: McpInspection & {
+        jamEntryIsLegacy: boolean;
+    };
+    /**
+     * The coding agents on this machine and whether each already knows about
+     * jam. Empty unless probing was asked for: it costs a process launch per
+     * host, which `jam doctor` has no reason to pay.
+     */
+    hosts: HostState[];
+};
+export type DetectOptions = {
+    cwd?: string;
+    /** Injected by tests to isolate ~/.jam. */
+    home?: string;
+    credentials?: CredentialPort;
+    /** Injected by tests so identity never depends on the checkout under test. */
+    git?: GitRemoteFn;
+    /** Probe the host CLIs. Only the setup paths need this. */
+    probeHosts?: boolean;
+    /** Injected by tests so no test ever reaches a real host CLI. */
+    runHost?: HostRunner;
+};
+/**
+ * Snapshot everything setup needs to decide, without changing any of it.
+ *
+ * Strictly read-only: no file is created, and no config is bootstrapped. That
+ * separation is what makes `setup plan` safe to run speculatively, and what
+ * lets an agent inspect a machine before proposing anything.
+ */
+export declare function detectSetupState(options?: DetectOptions): SetupState;

package/dist/bootstrap/setup-state.js

@@ -0,0 +1,89 @@
+import { readRuntimeConfig, resolveRuntime, } from "@jam-mcp/launcher";
+import { CompositeCredentialProvider } from "../adapters/credentials/composite.js";
+import { loadConfig } from "../config/load-config.js";
+import { detectHosts } from "./host-mcp.js";
+import { inspectMcpConfig, isLegacyJamEntry } from "./mcp-config-merger.js";
+import { inspectProjectBindings } from "./project-bindings.js";
+import { resolveProjectRoot } from "./project-root-resolver.js";
+import { workspaceIdentity } from "./workspace-identity.js";
+/**
+ * Snapshot everything setup needs to decide, without changing any of it.
+ *
+ * Strictly read-only: no file is created, and no config is bootstrapped. That
+ * separation is what makes `setup plan` safe to run speculatively, and what
+ * lets an agent inspect a machine before proposing anything.
+ */
+export function detectSetupState(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const located = resolveProjectRoot(cwd);
+    const workspaceId = workspaceIdentity(located.root, {
+        ...(located.gitRoot ? { gitRoot: located.gitRoot } : {}),
+        ...(options.git ? { git: options.git } : {}),
+    });
+    const bindings = inspectProjectBindings(options.home);
+    const binding = bindings.bindings.find((b) => b.workspace === workspaceId);
+    return {
+        cwd,
+        workspaceId,
+        bindingsUnreadable: bindings.status === "unreadable",
+        runtime: detectRuntime(options.home),
+        credentials: detectCredentials(options.credentials ?? new CompositeCredentialProvider()),
+        project: { ...detectProject(located), ...(binding ? { binding } : {}) },
+        mcp: detectMcp(located.root),
+        hosts: options.probeHosts ? detectHosts(options.runHost) : [],
+    };
+}
+function detectRuntime(home) {
+    const config = readRuntimeConfig(home);
+    if (!config)
+        return { configured: false };
+    const state = { configured: true, mode: config.runtime.mode };
+    if (config.runtime.mode === "development")
+        state.source = config.runtime.source;
+    try {
+        state.version = resolveRuntime(config).version;
+    }
+    catch (err) {
+        state.error = err instanceof Error ? err.message : String(err);
+    }
+    return state;
+}
+function detectCredentials(credentials) {
+    const described = credentials.describe();
+    const state = {
+        present: Boolean(described.baseUrl && described.email && described.hasToken),
+        source: described.source,
+    };
+    // Presence and origin only - the token value never enters this snapshot.
+    if (described.baseUrl)
+        state.baseUrl = described.baseUrl;
+    if (described.email)
+        state.email = described.email;
+    return state;
+}
+function detectProject(located) {
+    const { root, hasConfig } = located;
+    if (!hasConfig)
+        return { root, hasConfig: false };
+    try {
+        const loaded = loadConfig(root);
+        const state = { root, hasConfig: true };
+        if (loaded.path)
+            state.configPath = loaded.path;
+        if (loaded.config.project.key)
+            state.key = loaded.config.project.key;
+        return state;
+    }
+    catch (err) {
+        return {
+            root,
+            hasConfig: true,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/** Inspection plus whether the existing jam entry predates launcher-based wiring. */
+function detectMcp(root) {
+    const inspection = inspectMcpConfig(root);
+    return { ...inspection, jamEntryIsLegacy: isLegacyJamEntry(inspection.jamEntry) };
+}

package/dist/bootstrap/workspace-identity.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Reads a repository's `origin` remote. Injected by tests so no test depends
+ * on the checkout it happens to run in.
+ */
+export type GitRemoteFn = (root: string) => string | undefined;
+/**
+ * Ask git for `origin`, and treat every failure as "no remote".
+ *
+ * git missing, not a repository, no `origin`, a stalled filesystem - all of
+ * them mean the same thing to a caller, and none of them is worth an error or
+ * a log line. `shell: false` unlike the npm probe in `migration-target.ts`:
+ * git is a real executable, so routing it through a shell would only add
+ * quoting hazards around the user's path.
+ */
+export declare const readGitRemote: GitRemoteFn;
+/**
+ * One repository, one identity, whichever URL form was cloned.
+ *
+ * `git@host:org/repo.git` and `https://host/org/repo` are the same repository
+ * and must produce the same string, or a binding made from one clone would be
+ * invisible from another.
+ *
+ * Two rules are load-bearing rather than cosmetic:
+ *
+ * - **Any userinfo is dropped.** A remote can carry `user:token@`, and a token
+ *   must never reach `~/.jam/projects.yaml`, a log line or telemetry.
+ * - **An explicit non-default port is kept.** `git.example.com:8443/org/repo`
+ *   and `git.example.com/org/repo` may be different services - self-hosted
+ *   GitLab makes that ordinary - so only a port that is the scheme's own
+ *   default is dropped.
+ */
+export declare function canonicalRemote(url: string): string | undefined;
+export type WorkspaceIdentityOptions = {
+    /** The repository root, when `root` is inside one. */
+    gitRoot?: string;
+    /** Injected by tests. */
+    git?: GitRemoteFn;
+};
+/**
+ * A stable id for "this workspace", used to bind it to a Jira project.
+ *
+ * Prefers the canonical remote plus the project's offset inside the
+ * repository, so two clones of one repo share a binding and two packages in a
+ * monorepo do not. Falls back to the normalised absolute path when there is no
+ * remote to ask about - which is honest about its ceiling: a folder that moves
+ * loses its binding.
+ *
+ * No realpath: the preset matcher already compares non-realpathed absolute
+ * paths, and resolving symlinks only here would create a case where a preset
+ * matches and a binding does not.
+ */
+export declare function workspaceIdentity(root: string, options?: WorkspaceIdentityOptions): string;

package/dist/bootstrap/workspace-identity.js

@@ -0,0 +1,114 @@
+import { spawnSync } from "node:child_process";
+import { platform } from "node:os";
+import { relative } from "node:path";
+import { normalizePath } from "./project-config-bootstrapper.js";
+/** Local file read, not a network call - a second is already generous. */
+const GIT_TIMEOUT_MS = 2_000;
+/**
+ * Ask git for `origin`, and treat every failure as "no remote".
+ *
+ * git missing, not a repository, no `origin`, a stalled filesystem - all of
+ * them mean the same thing to a caller, and none of them is worth an error or
+ * a log line. `shell: false` unlike the npm probe in `migration-target.ts`:
+ * git is a real executable, so routing it through a shell would only add
+ * quoting hazards around the user's path.
+ */
+export const readGitRemote = (root) => {
+    const result = spawnSync("git", ["config", "--get", "remote.origin.url"], {
+        cwd: root,
+        encoding: "utf8",
+        timeout: GIT_TIMEOUT_MS,
+        shell: false,
+    });
+    if (result.error || result.status !== 0)
+        return undefined;
+    const url = result.stdout?.trim();
+    return url ? url : undefined;
+};
+const DEFAULT_PORTS = {
+    http: "80",
+    https: "443",
+    ssh: "22",
+    git: "9418",
+};
+/**
+ * One repository, one identity, whichever URL form was cloned.
+ *
+ * `git@host:org/repo.git` and `https://host/org/repo` are the same repository
+ * and must produce the same string, or a binding made from one clone would be
+ * invisible from another.
+ *
+ * Two rules are load-bearing rather than cosmetic:
+ *
+ * - **Any userinfo is dropped.** A remote can carry `user:token@`, and a token
+ *   must never reach `~/.jam/projects.yaml`, a log line or telemetry.
+ * - **An explicit non-default port is kept.** `git.example.com:8443/org/repo`
+ *   and `git.example.com/org/repo` may be different services - self-hosted
+ *   GitLab makes that ordinary - so only a port that is the scheme's own
+ *   default is dropped.
+ */
+export function canonicalRemote(url) {
+    const trimmed = url.trim();
+    if (!trimmed)
+        return undefined;
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(trimmed)) {
+        let parsed;
+        try {
+            parsed = new URL(trimmed);
+        }
+        catch {
+            return undefined;
+        }
+        const host = parsed.hostname.toLowerCase();
+        if (!host)
+            return undefined;
+        const scheme = parsed.protocol.replace(":", "").toLowerCase();
+        // WHATWG already drops http/https default ports; this covers ssh and git.
+        const port = parsed.port && parsed.port !== DEFAULT_PORTS[scheme] ? `:${parsed.port}` : "";
+        const path = cleanPath(parsed.pathname);
+        return path ? `${host}${port}/${path}` : undefined;
+    }
+    // scp-like: [user@]host:path. The text after the colon is a path, never a
+    // port - reading it as one would turn org/repo into a port number.
+    const scp = /^(?:[^@/]+@)?([^:/]+):(.+)$/.exec(trimmed);
+    if (scp) {
+        const host = scp[1].toLowerCase();
+        const path = cleanPath(scp[2]);
+        return path ? `${host}/${path}` : undefined;
+    }
+    return undefined;
+}
+function cleanPath(raw) {
+    return raw
+        .replace(/^\/+/, "")
+        .replace(/\/+$/, "")
+        .replace(/\.git$/i, "")
+        .toLowerCase();
+}
+/**
+ * A stable id for "this workspace", used to bind it to a Jira project.
+ *
+ * Prefers the canonical remote plus the project's offset inside the
+ * repository, so two clones of one repo share a binding and two packages in a
+ * monorepo do not. Falls back to the normalised absolute path when there is no
+ * remote to ask about - which is honest about its ceiling: a folder that moves
+ * loses its binding.
+ *
+ * No realpath: the preset matcher already compares non-realpathed absolute
+ * paths, and resolving symlinks only here would create a case where a preset
+ * matches and a binding does not.
+ */
+export function workspaceIdentity(root, options = {}) {
+    const git = options.git ?? readGitRemote;
+    const gitRoot = options.gitRoot;
+    const remote = gitRoot ? canonicalRemote(git(gitRoot) ?? "") : undefined;
+    if (remote) {
+        const offset = toPosix(relative(gitRoot, root));
+        return offset ? `git:${remote}#${offset}` : `git:${remote}`;
+    }
+    return `path:${toPosix(normalizePath(root))}`;
+}
+function toPosix(p) {
+    const forward = p.split("\\").join("/");
+    return platform() === "win32" ? forward.toLowerCase() : forward;
+}

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

@@ -0,0 +1,63 @@
+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 { GitRemoteFn } from "../bootstrap/workspace-identity.js";
+/**
+ * The machine-readable half of setup.
+ *
+ * Everything here shares the detect/plan/apply core with the human wizard -
+ * only the interface differs. An agent gets structured status codes instead of
+ * prose so it never has to infer intent from an error message, and never has
+ * to assemble JAM's config files itself.
+ *
+ * Contract, enforced by tests:
+ *   stdout - valid JSON and nothing else, no ANSI, no prompts
+ *   stderr - diagnostics only
+ */
+export type AgentOptions = {
+    cwd?: string;
+    home?: string;
+    explicitKey?: string;
+    /** `--shared`: adopt JAM for the team, writing into the repository. */
+    shared?: boolean;
+    migrate?: boolean;
+    /** Injected by tests so a plan never depends on the machine's JIRA_* env. */
+    credentials?: CredentialPort;
+    /** Injected by tests so a plan never depends on the machine's JAM_PROJECT_KEY. */
+    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 identity never depends on the checkout under test. */
+    git?: GitRemoteFn;
+    /** Injected by tests so no test ever registers JAM with a real host. */
+    runHost?: HostRunner;
+};
+export declare function emitJson(payload: unknown): void;
+/**
+ * `jam setup plan --json` - what setup would do, having done nothing.
+ */
+export declare function setupPlanCommand(options?: AgentOptions): Promise<number>;
+/**
+ * `jam setup apply --non-interactive --json` - execute a freshly computed plan.
+ *
+ * Applies whatever the plan safely can even when a human step remains, and
+ * says so via `changesApplied`. A missing credential should not leave a
+ * project half-wired.
+ */
+export declare function setupApplyCommand(options?: AgentOptions): Promise<number>;
+/**
+ * `jam setup --agent` - one shot: detect, plan, apply what is safe, verify.
+ *
+ * Stops only where a person is genuinely required (choosing a Jira project,
+ * authenticating), and reports exactly how far it got.
+ */
+export declare function setupAgentCommand(options?: AgentOptions): Promise<number>;
+/** `jam doctor --json`. */
+export declare function doctorJsonCommand(options?: AgentOptions): Promise<number>;
+/**
+ * `jam auth status --json` - presence and origin only.
+ *
+ * Never returns the credential itself. An agent needs to know whether
+ * authentication is configured, not what it is.
+ */
+export declare function authStatusCommand(options?: AgentOptions): number;

package/dist/cli/agent-api.js

@@ -0,0 +1,149 @@
+import { runHealthGate } from "../bootstrap/boot-health-gate.js";
+import { listVisibleProjects } from "../bootstrap/jira-projects.js";
+import { computeSetupPlanWithPreflight, } from "../bootstrap/migration-target.js";
+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";
+export function emitJson(payload) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+function detect(options) {
+    return detectSetupState({
+        ...(options.cwd ? { cwd: options.cwd } : {}),
+        ...(options.home ? { home: options.home } : {}),
+        ...(options.credentials ? { credentials: options.credentials } : {}),
+        ...(options.git ? { git: options.git } : {}),
+        probeHosts: !options.shared,
+        ...(options.runHost ? { runHost: options.runHost } : {}),
+    });
+}
+function planFrom(state, options) {
+    return computeSetupPlanWithPreflight(state, {
+        ...(options.shared ? { shared: options.shared } : {}),
+        ...(options.explicitKey ? { explicitKey: options.explicitKey } : {}),
+        ...(options.migrate ? { migrate: options.migrate } : {}),
+        ...(options.env ? { env: options.env } : {}),
+        ...(options.migrationTarget ? { migrationTarget: options.migrationTarget } : {}),
+    });
+}
+/** Enrich a selection-required plan with the projects the account can see. */
+async function withProjects(plan, options) {
+    if (plan.code !== "JAM_PROJECT_SELECTION_REQUIRED")
+        return plan;
+    const { projects } = await listVisibleProjects(options.credentials);
+    return projects.length > 0 ? { ...plan, projects } : plan;
+}
+/**
+ * `jam setup plan --json` - what setup would do, having done nothing.
+ */
+export async function setupPlanCommand(options = {}) {
+    const plan = await withProjects(planFrom(detect(options), options), options);
+    emitJson({ ...plan, changesApplied: false });
+    return plan.requiresUserAction ? 1 : 0;
+}
+/**
+ * `jam setup apply --non-interactive --json` - execute a freshly computed plan.
+ *
+ * Applies whatever the plan safely can even when a human step remains, and
+ * says so via `changesApplied`. A missing credential should not leave a
+ * project half-wired.
+ */
+export async function setupApplyCommand(options = {}) {
+    const state = detect(options);
+    const plan = planFrom(state, options);
+    if (plan.code === "JAM_PROJECT_SELECTION_REQUIRED") {
+        emitJson({ ...(await withProjects(plan, options)), changesApplied: false });
+        return 1;
+    }
+    if (plan.code === "JAM_PROJECT_CONFIG_INVALID" ||
+        plan.code === "JAM_MCP_CONFIG_UNREADABLE" ||
+        plan.code === "JAM_BINDINGS_UNREADABLE") {
+        emitJson({ ...plan, changesApplied: false });
+        return 1;
+    }
+    const result = applySetupPlan(plan, {
+        ...(options.home ? { home: options.home } : {}),
+        ...(options.runHost ? { runHost: options.runHost } : {}),
+    });
+    emitJson({ ...plan, status: applyStatus(plan), changesApplied: result.changesApplied });
+    return plan.requiresUserAction ? 1 : 0;
+}
+function applyStatus(plan) {
+    return plan.requiresUserAction ? "user_action_required" : "already_configured";
+}
+/**
+ * `jam setup --agent` - one shot: detect, plan, apply what is safe, verify.
+ *
+ * Stops only where a person is genuinely required (choosing a Jira project,
+ * authenticating), and reports exactly how far it got.
+ */
+export async function setupAgentCommand(options = {}) {
+    const state = detect(options);
+    const plan = planFrom(state, options);
+    if (plan.code === "JAM_PROJECT_SELECTION_REQUIRED") {
+        emitJson({ ...(await withProjects(plan, options)), changesApplied: false });
+        return 1;
+    }
+    if (plan.code === "JAM_PROJECT_CONFIG_INVALID" ||
+        plan.code === "JAM_MCP_CONFIG_UNREADABLE" ||
+        plan.code === "JAM_BINDINGS_UNREADABLE") {
+        emitJson({ ...plan, changesApplied: false });
+        return 1;
+    }
+    const { changesApplied } = applySetupPlan(plan, {
+        ...(options.home ? { home: options.home } : {}),
+        ...(options.runHost ? { runHost: options.runHost } : {}),
+    });
+    if (plan.requiresUserAction) {
+        emitJson({ ...plan, changesApplied });
+        return 1;
+    }
+    const health = await gateResult(state.project.root);
+    emitJson({
+        status: health.passed ? "ready" : "verification_failed",
+        changesApplied,
+        project: plan.project,
+        checks: health.checks,
+    });
+    return health.passed ? 0 : 1;
+}
+/** `jam doctor --json`. */
+export async function doctorJsonCommand(options = {}) {
+    const state = detect(options);
+    const health = await gateResult(state.project.root);
+    emitJson({
+        status: health.passed ? "ready" : "failed",
+        ...(health.error ? { error: health.error } : {}),
+        project: { root: state.project.root, ...(state.project.key ? { key: state.project.key } : {}) },
+        checks: health.checks,
+    });
+    return health.passed ? 0 : 1;
+}
+/**
+ * `jam auth status --json` - presence and origin only.
+ *
+ * Never returns the credential itself. An agent needs to know whether
+ * authentication is configured, not what it is.
+ */
+export function authStatusCommand(options = {}) {
+    const { credentials } = detect(options);
+    emitJson({
+        status: credentials.present ? "configured" : "not_configured",
+        ...(credentials.present ? {} : { code: "JAM_AUTH_REQUIRED" }),
+        source: credentials.source,
+        ...(credentials.email ? { email: credentials.email } : {}),
+        ...(credentials.baseUrl ? { baseUrl: credentials.baseUrl } : {}),
+    });
+    return credentials.present ? 0 : 1;
+}
+async function gateResult(root) {
+    try {
+        const deps = await buildDeps({ cwd: root, keyFallback: "optional" });
+        const gate = await runHealthGate(deps, "full");
+        return { passed: gate.passed, checks: gate.checks };
+    }
+    catch (err) {
+        return { passed: false, checks: [], error: toJamError(err).message };
+    }
+}

package/dist/cli/auth.d.ts

@@ -0,0 +1,39 @@
+import { type SecretStore, type StoredCredentials } from "../adapters/credentials/secret-store.js";
+import type { CredentialPort } from "../ports/credentials.port.js";
+import { Ui } from "./ui.js";
+/**
+ * `jam auth login` / `jam auth logout`.
+ *
+ * Human-facing on purpose: these are the one step of setup an agent must not
+ * perform. An agent that asks a person for a token, or stores one, has done
+ * something wrong regardless of intent - so this path prompts, and the agent
+ * path stops at JAM_AUTH_REQUIRED and hands the user this command.
+ *
+ * `jam auth status` stays in the agent API: it is presence and origin only,
+ * and its JSON shape is a contract.
+ */
+export type AuthOptions = {
+    ui?: Ui;
+    /** Injected by tests so the suite never touches a real keychain. */
+    store?: SecretStore | undefined;
+    /** Reads back what is now in effect. A fresh port each call - see below. */
+    readBack?: () => CredentialPort;
+    /**
+     * Injected by tests. Real verification talks to Jira, which no unit test may
+     * do - and the guarantee under test (nothing is stored unless Jira accepted
+     * it) is about the ordering, not about the network.
+     */
+    verify?: (values: StoredCredentials) => Promise<string | undefined>;
+};
+export declare function authLoginCommand(options?: AuthOptions): Promise<number>;
+export declare function authLogoutCommand(options?: AuthOptions): number;
+/**
+ * The origin of any URL from the user's Jira site, or undefined.
+ *
+ * Parsed rather than trimmed, because a pathname is the failure that actually
+ * happens: someone copies the project page URL, and JiraClient resolves each
+ * REST path *relative* to the base, so `/jira/software/c/projects/KEY/summary`
+ * gets the API path appended to it. Atlassian answers that with its HTML shell
+ * at 200, and the only symptom is "Jira returned a non-JSON response".
+ */
+export declare function toJiraOrigin(input: string): string | undefined;