@jam-mcp/server 1.0.0

package/dist/cli/auth.js

@@ -0,0 +1,201 @@
+import { CompositeCredentialProvider } from "../adapters/credentials/composite.js";
+import { SecretStoreUnavailableError, resolveSecretStore, secretStoreDisabled, } from "../adapters/credentials/secret-store.js";
+import { ProjectConfigSchema } from "../config/schema.js";
+import { toJamError } from "../domain/errors.js";
+import { Ui } from "./ui.js";
+const TOKEN_URL = "https://id.atlassian.com/manage-profile/security/api-tokens";
+// A sentence, not a command: JAM does not know whether this shell wants
+// `export`, `set` or `$env:`, and printing one of them as if it were runnable
+// is worse than describing what has to end up in the environment. Matches the
+// wording the secret store already uses for the same situation.
+const ENV_HINT = "Set JIRA_BASE_URL, JIRA_EMAIL and JIRA_API_TOKEN instead.";
+/**
+ * Bounded rather than open: a run whose input has stopped producing usable
+ * answers has to end, and a login that spins forever on a script or a pipe is
+ * worse than one that gives up and says why.
+ */
+const MAX_PROMPT_ATTEMPTS = 3;
+/**
+ * Re-ask one step until its answer parses.
+ *
+ * Losing an entire login to one mistyped URL is not a safety property, it is
+ * just the step forgetting what it was asking for. The retry stays inside the
+ * step so callers still see a single exit code.
+ */
+async function askUntilValid(ask, parse, onInvalid) {
+    for (let attempt = 1; attempt <= MAX_PROMPT_ATTEMPTS; attempt++) {
+        const parsed = parse(await ask());
+        if (parsed !== undefined)
+            return parsed;
+        onInvalid();
+    }
+    return undefined;
+}
+function giveUp(ui, what) {
+    ui.line();
+    ui.failure(`No usable ${what} after ${MAX_PROMPT_ATTEMPTS} attempts`);
+    ui.next(ENV_HINT);
+    return 1;
+}
+/**
+ * A provider caches its answer for its own lifetime, so the effective source
+ * after a write can only be observed through a new one.
+ */
+function freshPort() {
+    return new CompositeCredentialProvider();
+}
+export async function authLoginCommand(options = {}) {
+    const ui = options.ui ?? new Ui();
+    const store = "store" in options ? options.store : resolveSecretStore();
+    const readBack = options.readBack ?? freshPort;
+    ui.section("Authentication");
+    if (!store) {
+        // Disabled and absent are different problems with different fixes, and
+        // saying "no store" when one was switched off sends the user hunting.
+        if (secretStoreDisabled()) {
+            ui.failure("Secret store disabled by JAM_DISABLE_SECRET_STORE");
+            ui.line("  That variable is for isolated test sandboxes. Unset it and run this again.");
+            ui.next(ENV_HINT);
+            return 1;
+        }
+        ui.failure("No usable secret store was found on this system");
+        ui.line("  JAM stores credentials where the operating system holds them for you,");
+        ui.line("  so an editor launched from a Dock or Start menu can still read them.");
+        ui.next(ENV_HINT);
+        return 1;
+    }
+    const existing = readBack().describe();
+    // Any page from their Jira site, pasted whole. Nobody should have to know
+    // what an origin is, or strip a path by hand, to log in.
+    const baseUrl = await askUntilValid(() => ui.prompt("Paste your Jira URL", ENV_HINT, existing.baseUrl ?? undefined), toJiraOrigin, () => {
+        ui.failure("That does not look like a Jira URL");
+        ui.line("  Paste any page URL from your Jira site.");
+    });
+    if (!baseUrl)
+        return giveUp(ui, "Jira URL");
+    // Checked at its own step: an empty email used to surface only after the
+    // token had been typed, which asks for a secret in order to reject the line
+    // before it.
+    const email = await askUntilValid(() => ui.prompt("Atlassian account email", ENV_HINT, existing.email ?? undefined), (raw) => raw.trim() || undefined, () => ui.failure("An Atlassian account email is required"));
+    if (!email)
+        return giveUp(ui, "Atlassian account email");
+    ui.line(`  Create a token at ${TOKEN_URL}`);
+    const apiToken = await ui.secret("Atlassian API token", ENV_HINT);
+    if (!apiToken) {
+        ui.failure("An API token is required");
+        ui.next(ENV_HINT);
+        return 1;
+    }
+    const values = { baseUrl, email, apiToken };
+    // Verified before it is stored. A rejected token written to the keychain is
+    // the worst outcome available here: every later command fails, and the thing
+    // that is wrong looks like the thing that was just fixed.
+    const verify = options.verify ?? ((v) => verifyAgainstJira(ui, v));
+    const failure = await verify(values);
+    if (failure) {
+        ui.line();
+        ui.failure("Jira rejected these credentials");
+        ui.line(`  ${failure}`);
+        ui.line("  Nothing was stored.");
+        return 1;
+    }
+    try {
+        store.write(values);
+    }
+    catch (err) {
+        ui.failure("Could not store the credentials");
+        ui.line(`  ${err instanceof Error ? err.message : String(err)}`);
+        if (err instanceof SecretStoreUnavailableError)
+            ui.next(err.remedy);
+        return 1;
+    }
+    ui.success("Authentication stored", `${email} · ${baseUrl} (${store.label})`);
+    reportOverride(ui, readBack());
+    return 0;
+}
+export function authLogoutCommand(options = {}) {
+    const ui = options.ui ?? new Ui();
+    const store = "store" in options ? options.store : resolveSecretStore();
+    const readBack = options.readBack ?? freshPort;
+    ui.section("Authentication");
+    if (!store) {
+        ui.warn("No secret store on this system, so there is nothing stored to remove");
+        reportRemaining(ui, readBack());
+        return 0;
+    }
+    store.clear();
+    ui.success("Removed the stored credentials");
+    reportRemaining(ui, readBack());
+    return 0;
+}
+/**
+ * Warn when an exported variable shadows what was just stored.
+ *
+ * The chain merges per field, so this is not "are all three exported" - one
+ * stale `export` in a shell profile is enough to make part of the stored
+ * credential unreachable, and the resulting split shows up as "mixed".
+ */
+function reportOverride(ui, port) {
+    const source = port.describe().source;
+    if (source === "secret-store")
+        return;
+    if (source === "mixed") {
+        ui.warn("Current JIRA_* environment variables override part of the stored credentials");
+    }
+    else {
+        ui.warn("Current JIRA_* environment variables override the stored credentials");
+    }
+    ui.line(`  Effective source: ${source}`);
+    ui.line("  Unset them to use what was just stored.");
+}
+/** After a logout, say plainly whether anything still authenticates JAM. */
+function reportRemaining(ui, port) {
+    const described = port.describe();
+    const stillResolves = Boolean(described.baseUrl && described.email && described.hasToken);
+    if (!stillResolves && described.source === "none") {
+        ui.line("  JAM is no longer authenticated.");
+        return;
+    }
+    ui.warn(stillResolves
+        ? "Jira credentials still resolve from outside the secret store"
+        : "Part of a Jira credential still resolves from outside the secret store");
+    ui.line(`  Effective source: ${described.source}`);
+    ui.line("  Unset JIRA_BASE_URL, JIRA_EMAIL and JIRA_API_TOKEN to finish logging out.");
+}
+/** undefined when Jira accepted the credentials; otherwise the reason. */
+async function verifyAgainstJira(ui, values) {
+    const port = {
+        load: () => values,
+        describe: () => ({ baseUrl: values.baseUrl, email: values.email, hasToken: true, source: "process" }),
+    };
+    try {
+        const { JiraCloudReadAdapter } = await import("../adapters/jira-cloud/jira-read.adapter.js");
+        const jira = new JiraCloudReadAdapter(port, ProjectConfigSchema.parse({}));
+        const me = await ui.spin("Checking Jira access...", () => jira.getCurrentUser());
+        ui.success("Jira accepted the credentials", me.displayName ?? me.emailAddress ?? me.accountId);
+        return undefined;
+    }
+    catch (err) {
+        const jamError = toJamError(err);
+        return `${jamError.code}: ${jamError.message}`;
+    }
+}
+/**
+ * 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 function toJiraOrigin(input) {
+    let url;
+    try {
+        url = new URL(input.trim());
+    }
+    catch {
+        return undefined;
+    }
+    return url.protocol === "http:" || url.protocol === "https:" ? url.origin : undefined;
+}

package/dist/cli/doctor.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `jam doctor` exists to answer one question fast: is this a Jira problem, a
+ * credential problem, or a local setup problem? It is read-only - it never
+ * bootstraps a missing project.yaml (that is `jam setup`'s job) - and runs the
+ * "full" health gate, including live Jira connectivity.
+ */
+export declare function doctor(cwd?: string): Promise<number>;

package/dist/cli/doctor.js

@@ -0,0 +1,31 @@
+import { buildDeps } from "../deps.js";
+import { toJamError } from "../domain/errors.js";
+import { runHealthGate } from "../bootstrap/boot-health-gate.js";
+/**
+ * `jam doctor` exists to answer one question fast: is this a Jira problem, a
+ * credential problem, or a local setup problem? It is read-only - it never
+ * bootstraps a missing project.yaml (that is `jam setup`'s job) - and runs the
+ * "full" health gate, including live Jira connectivity.
+ */
+export async function doctor(cwd) {
+    let deps;
+    try {
+        // Optional fallback: doctor reports what `jam serve` would run with -
+        // including a key that comes from this user's binding rather than from a
+        // file in the repository - and never refuses to load.
+        deps = await buildDeps({ cwd, keyFallback: "optional" });
+    }
+    catch (err) {
+        process.stdout.write(`[FAIL] Project config - ${toJamError(err).message}\n`);
+        return 1;
+    }
+    const gate = await runHealthGate(deps, "full");
+    for (const check of gate.checks) {
+        process.stdout.write(`${check.ok ? "[OK]  " : "[FAIL]"} ${check.name}${check.detail ? ` - ${check.detail}` : ""}\n`);
+    }
+    const failed = gate.checks.filter((c) => !c.ok);
+    process.stdout.write(failed.length === 0
+        ? `\nAll ${gate.checks.length} checks passed.\n`
+        : `\n${failed.length} of ${gate.checks.length} checks failed: ${failed.map((f) => f.name).join(", ")}\n`);
+    return gate.passed ? 0 : 1;
+}

package/dist/cli/runtime.d.ts

@@ -0,0 +1,16 @@
+export type RuntimeCommandOptions = {
+    /** Injected by tests; defaults to the real user home. */
+    home?: string;
+    json?: boolean;
+};
+/**
+ * `jam runtime` - inspect or change which JAM build this machine runs.
+ *
+ * The config module is imported from the launcher rather than reimplemented
+ * here: the launcher reads this file on every MCP start, so a second writer
+ * with its own idea of the format is how the two drift apart.
+ *
+ * This command touches ~/.jam/config.yaml only. It never writes to a project.
+ */
+export declare function showRuntime(options?: RuntimeCommandOptions): number;
+export declare function useRuntime(mode: string | undefined, source: string | undefined, options?: RuntimeCommandOptions): number;

package/dist/cli/runtime.js

@@ -0,0 +1,97 @@
+import { readRuntimeConfig, resolveRuntime, runtimeConfigPath, writeRuntimeConfig, LauncherError, } from "@jam-mcp/launcher";
+/**
+ * `jam runtime` - inspect or change which JAM build this machine runs.
+ *
+ * The config module is imported from the launcher rather than reimplemented
+ * here: the launcher reads this file on every MCP start, so a second writer
+ * with its own idea of the format is how the two drift apart.
+ *
+ * This command touches ~/.jam/config.yaml only. It never writes to a project.
+ */
+export function showRuntime(options = {}) {
+    const config = readRuntimeConfig(options.home);
+    if (!config) {
+        if (options.json) {
+            writeJson({ status: "not_configured", code: "JAM_RUNTIME_CONFIG_MISSING" });
+            return 1;
+        }
+        process.stdout.write("No JAM runtime is configured for this user.\n");
+        process.stdout.write("\nRun:\n  jam runtime use package\n");
+        return 1;
+    }
+    let resolved;
+    let error;
+    try {
+        resolved = resolveRuntime(config);
+    }
+    catch (err) {
+        error = err instanceof Error ? err.message : String(err);
+    }
+    if (options.json) {
+        writeJson({
+            status: resolved ? "configured" : "invalid",
+            mode: config.runtime.mode,
+            ...(config.runtime.mode === "development" ? { source: config.runtime.source } : {}),
+            ...(resolved ? { version: resolved.version } : {}),
+            ...(error ? { error } : {}),
+            configPath: runtimeConfigPath(options.home),
+        });
+        return resolved ? 0 : 1;
+    }
+    process.stdout.write(`Runtime: ${config.runtime.mode}\n`);
+    if (config.runtime.mode === "development") {
+        process.stdout.write(`Source:  ${config.runtime.source}\n`);
+    }
+    if (resolved) {
+        process.stdout.write(`Version: ${resolved.version}\n`);
+    }
+    else {
+        process.stdout.write(`\n[FAIL] ${error}\n`);
+    }
+    process.stdout.write(`Config:  ${runtimeConfigPath(options.home)}\n`);
+    return resolved ? 0 : 1;
+}
+export function useRuntime(mode, source, options = {}) {
+    if (mode === "package") {
+        const path = writeRuntimeConfig({ version: 1, runtime: { mode: "package" } }, options.home);
+        report({ mode: "package", path }, options);
+        return 0;
+    }
+    if (mode === "development") {
+        if (!source) {
+            process.stderr.write("Usage: jam runtime use development <path-to-jam-checkout>\n");
+            return 1;
+        }
+        // Validate before persisting, so a bad path fails here rather than on the
+        // next MCP start where the error surfaces without context.
+        try {
+            resolveRuntime({ version: 1, runtime: { mode: "development", source } });
+        }
+        catch (err) {
+            if (err instanceof LauncherError) {
+                process.stderr.write(`[jam] ${err.code}: ${err.message}\n`);
+                if (err.nextCommand)
+                    process.stderr.write(`\nRun:\n  ${err.nextCommand}\n`);
+            }
+            else {
+                process.stderr.write(`[jam] ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+            return 1;
+        }
+        const path = writeRuntimeConfig({ version: 1, runtime: { mode: "development", source } }, options.home);
+        report({ mode: "development", source, path }, options);
+        return 0;
+    }
+    process.stderr.write("Usage: jam runtime use package | jam runtime use development <path>\n");
+    return 1;
+}
+function report(result, options) {
+    if (options.json) {
+        writeJson({ status: "configured", ...result, configPath: result.path });
+        return;
+    }
+    process.stdout.write(`Runtime set to ${result.mode}${result.source ? ` (${result.source})` : ""}.\n`);
+}
+function writeJson(payload) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}

package/dist/cli/serve.d.ts

@@ -0,0 +1,7 @@
+import { type BootstrapForServeOptions } from "../bootstrap/bootstrap-orchestrator.js";
+/**
+ * stdout is reserved for the MCP protocol - every diagnostic here goes to
+ * stderr. A failed boot gate means the server never calls `connect()`: a
+ * half-started MCP is worse than a clear failure message and a non-zero exit.
+ */
+export declare function serve(options?: BootstrapForServeOptions): Promise<number>;

package/dist/cli/serve.js

@@ -0,0 +1,23 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { bootstrapForServe } from "../bootstrap/bootstrap-orchestrator.js";
+import { createServer } from "../mcp/create-server.js";
+/**
+ * stdout is reserved for the MCP protocol - every diagnostic here goes to
+ * stderr. A failed boot gate means the server never calls `connect()`: a
+ * half-started MCP is worse than a clear failure message and a non-zero exit.
+ */
+export async function serve(options = {}) {
+    const { deps, gate } = await bootstrapForServe(options);
+    if (!gate.passed) {
+        process.stderr.write("[jam] boot check failed - MCP server not started:\n");
+        for (const check of gate.checks.filter((c) => c.fatal && !c.ok)) {
+            process.stderr.write(`  [FAIL] ${check.name}${check.detail ? ` - ${check.detail}` : ""}\n`);
+        }
+        process.stderr.write("Run `jam setup` to fix configuration, or `jam doctor` for the full diagnosis.\n");
+        return 1;
+    }
+    const server = createServer(deps);
+    await server.connect(new StdioServerTransport());
+    process.stderr.write(`[jam] serving on stdio (project=${deps.config.project.key || "unset"}, config=${deps.configPath ?? `none (key from ${deps.keySource ?? "defaults"})`})\n`);
+    return -1; // stays alive on the stdio transport
+}

package/dist/cli/setup-wizard.d.ts

@@ -0,0 +1,37 @@
+import { type SetupPlan } from "../bootstrap/setup-plan.js";
+import type { CredentialPort } from "../ports/credentials.port.js";
+import type { JiraReadPort } from "../ports/jira-read.port.js";
+import type { AuthOptions } from "./auth.js";
+import type { HostRunner } from "../bootstrap/host-mcp.js";
+import { Ui } from "./ui.js";
+export type WizardOptions = {
+    cwd?: string;
+    home?: string;
+    explicitKey?: string;
+    /** `--shared`: adopt JAM for the team by writing into the repository. */
+    shared?: boolean;
+    /** Injected by tests so no test ever registers JAM with a real host. */
+    runHost?: HostRunner;
+    migrate?: boolean;
+    ui?: Ui;
+    /**
+     * Injected by tests. Without these the wizard reads the machine it runs on -
+     * the real keychain through `detectSetupState`, the real Jira through
+     * `listVisibleProjects` and the health gate, and the real `JAM_PROJECT_KEY`
+     * through the plan. Production passes none of them and behaves as before.
+     */
+    credentials?: CredentialPort;
+    jira?: JiraReadPort;
+    env?: NodeJS.ProcessEnv;
+    auth?: AuthOptions;
+};
+/**
+ * `jam setup`, the human path.
+ *
+ * Runs the same detect -> plan -> apply -> verify core the agent API uses; the
+ * only difference is presentation and the ability to ask. Anything that can be
+ * determined is determined - the wizard never asks a question it already knows
+ * the answer to, and never re-walks steps that are already done.
+ */
+export declare function runSetupWizard(options?: WizardOptions): Promise<number>;
+export type { SetupPlan };