@jam-mcp/server 1.0.0

package/dist/cli/ui.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The whole of JAM's terminal presentation.
+ *
+ * Deliberately hand-rolled rather than pulled from a TUI library: JAM needs a
+ * status line, a section heading and a single-choice list, and a dependency
+ * that renders full-screen frames would be a lot of surface for that. It also
+ * keeps the non-TTY path honest - everything here degrades to plain lines.
+ */
+export type UiOptions = {
+    stream?: NodeJS.WriteStream;
+    input?: NodeJS.ReadStream;
+    /** Force interactivity on or off; defaults to detection. */
+    interactive?: boolean;
+    color?: boolean;
+};
+export declare const SYMBOLS: {
+    readonly section: "◆";
+    readonly success: "✓";
+    readonly warning: "!";
+    readonly failure: "×";
+    readonly selected: "❯";
+    readonly pending: "○";
+    readonly next: "›";
+};
+/**
+ * Colour is suppressed for NO_COLOR, for CI, and for anything that is not a
+ * TTY - a log file full of escape codes helps nobody. Meaning is never carried
+ * by colour alone; every state also has a distinct symbol.
+ */
+export declare function colorEnabled(stream: NodeJS.WriteStream, env?: NodeJS.ProcessEnv): boolean;
+export declare function interactiveEnabled(stream: NodeJS.WriteStream, input: NodeJS.ReadStream, env?: NodeJS.ProcessEnv): boolean;
+export declare class CancelledError extends Error {
+    constructor();
+}
+/**
+ * Raised when a question is unavoidable but there is no terminal to ask it in.
+ * Distinct from any JAM/Jira error: nothing is wrong with the setup, there is
+ * just no one to answer, and the fix is a flag rather than a diagnosis.
+ */
+export declare class NonInteractiveError extends Error {
+    /** A whole instruction, printed as given - not a bare flag or command. */
+    readonly flagHint: string;
+    constructor(question: string, flagHint: string);
+}
+/**
+ * The one mapping of a prompt that could not run to an exit code.
+ *
+ * Returns undefined for anything else, which the caller must rethrow: a
+ * cancelled prompt is not a failure, and a missing terminal is guidance rather
+ * than a diagnosis, but a real fault must still surface as one.
+ */
+export declare function reportPromptError(err: unknown, ui: Ui): number | undefined;
+export type Choice<T> = {
+    value: T;
+    label: string;
+    /** Shown dimmed under the label. */
+    hint?: string;
+};
+export declare class Ui {
+    readonly interactive: boolean;
+    private readonly stream;
+    private readonly input;
+    private readonly useColor;
+    constructor(options?: UiOptions);
+    private paint;
+    write(text: string): void;
+    line(text?: string): void;
+    /**
+     * A stage heading. Sections replace a rigid "[2/5]" counter, which lies
+     * whenever a step turns out to be already done and gets skipped.
+     */
+    section(title: string, subtitle?: string): void;
+    success(text: string, detail?: string): void;
+    warn(text: string, detail?: string): void;
+    failure(text: string, detail?: string): void;
+    pending(text: string, detail?: string): void;
+    next(text: string): void;
+    private status;
+    /**
+     * Spinner for genuine waiting only - a network round trip, a package
+     * download. Spinning while reading a local file is theatre that makes fast
+     * operations look slow.
+     */
+    spin<T>(label: string, work: () => Promise<T>): Promise<T>;
+    /**
+     * Free-text answer, echoed as it is typed.
+     *
+     * The line editor is Node's readline, not JAM's: IME composition, CJK width,
+     * grapheme deletion, cursor movement and paste are the terminal's job, and a
+     * hand-rolled reader gets every one of them wrong. Cancelling is Ctrl-C,
+     * Ctrl-D or a closed stdin - readline swallows a lone Escape, so unlike
+     * `secret()` and `select()` this prompt cannot be cancelled with it.
+     */
+    prompt(question: string, flagHint: string, fallback?: string): Promise<string>;
+    /**
+     * Secret answer - nothing typed is ever echoed, to this stream or any other.
+     *
+     * No dots, no length hint, no redraw: an API token pasted into a terminal
+     * should leave no trace on screen for someone glancing over, in a screen
+     * share, or in scrollback.
+     */
+    secret(question: string, flagHint: string): Promise<string>;
+    /**
+     * The only place raw mode and a hand-managed buffer still live.
+     *
+     * A token needs four things - no echo, paste, delete, Enter - and a line
+     * editor that echoes nothing is not something readline offers. Everything
+     * `prompt` needs and this does not - cursor movement, IME, character width -
+     * stays out.
+     */
+    private readSecret;
+    /**
+     * Single-choice list. Throws in non-interactive mode rather than silently
+     * picking a default - an unattended run that quietly chose for you is worse
+     * than one that tells you which flag to pass.
+     */
+    select<T>(question: string, choices: Choice<T>[], flagHint: string): Promise<T>;
+}

package/dist/cli/ui.js

@@ -0,0 +1,338 @@
+import { createInterface, emitKeypressEvents } from "node:readline";
+export const SYMBOLS = {
+    section: "◆",
+    success: "✓",
+    warning: "!",
+    failure: "×",
+    selected: "❯",
+    pending: "○",
+    next: "›",
+};
+// Escape sequences are spelled out rather than typed literally: a raw 0x1b in
+// source is invisible in most editors and does not survive careless tooling.
+const CSI = "[";
+const ANSI = {
+    reset: `${CSI}0m`,
+    dim: `${CSI}2m`,
+    cyan: `${CSI}36m`,
+    green: `${CSI}32m`,
+    yellow: `${CSI}33m`,
+    red: `${CSI}31m`,
+    hideCursor: `${CSI}?25l`,
+    showCursor: `${CSI}?25h`,
+};
+const cursorUp = (rows) => `${CSI}${rows}A`;
+/**
+ * Colour is suppressed for NO_COLOR, for CI, and for anything that is not a
+ * TTY - a log file full of escape codes helps nobody. Meaning is never carried
+ * by colour alone; every state also has a distinct symbol.
+ */
+export function colorEnabled(stream, env = process.env) {
+    if (env["NO_COLOR"] !== undefined)
+        return false;
+    if (env["CI"])
+        return false;
+    return Boolean(stream.isTTY);
+}
+export function interactiveEnabled(stream, input, env = process.env) {
+    if (env["CI"])
+        return false;
+    return Boolean(stream.isTTY && input.isTTY);
+}
+export class CancelledError extends Error {
+    constructor() {
+        super("Cancelled.");
+        this.name = "CancelledError";
+    }
+}
+/**
+ * Raised when a question is unavoidable but there is no terminal to ask it in.
+ * Distinct from any JAM/Jira error: nothing is wrong with the setup, there is
+ * just no one to answer, and the fix is a flag rather than a diagnosis.
+ */
+export class NonInteractiveError extends Error {
+    /** A whole instruction, printed as given - not a bare flag or command. */
+    flagHint;
+    constructor(question, flagHint) {
+        super(`${question} cannot be asked without a terminal.`);
+        this.name = "NonInteractiveError";
+        this.flagHint = flagHint;
+    }
+}
+/**
+ * The one mapping of a prompt that could not run to an exit code.
+ *
+ * Returns undefined for anything else, which the caller must rethrow: a
+ * cancelled prompt is not a failure, and a missing terminal is guidance rather
+ * than a diagnosis, but a real fault must still surface as one.
+ */
+export function reportPromptError(err, ui) {
+    if (err instanceof CancelledError) {
+        ui.line();
+        ui.warn("Cancelled. Nothing was changed.");
+        return 130;
+    }
+    if (err instanceof NonInteractiveError) {
+        ui.line();
+        ui.failure(err.message);
+        // Printed verbatim. A hint that is a sentence must not be dressed up as a
+        // command the user could paste, and JAM cannot know their shell anyway.
+        ui.next(err.flagHint);
+        return 1;
+    }
+    return undefined;
+}
+export class Ui {
+    interactive;
+    stream;
+    input;
+    useColor;
+    constructor(options = {}) {
+        this.stream = options.stream ?? process.stdout;
+        this.input = options.input ?? process.stdin;
+        this.useColor = options.color ?? colorEnabled(this.stream);
+        this.interactive = options.interactive ?? interactiveEnabled(this.stream, this.input);
+    }
+    paint(text, code) {
+        return this.useColor ? `${ANSI[code]}${text}${ANSI.reset}` : text;
+    }
+    write(text) {
+        this.stream.write(text);
+    }
+    line(text = "") {
+        this.write(`${text}\n`);
+    }
+    /**
+     * A stage heading. Sections replace a rigid "[2/5]" counter, which lies
+     * whenever a step turns out to be already done and gets skipped.
+     */
+    section(title, subtitle) {
+        this.line();
+        this.line(`${this.paint(SYMBOLS.section, "cyan")} ${title}`);
+        if (subtitle)
+            this.line(`  ${this.paint(subtitle, "dim")}`);
+    }
+    success(text, detail) {
+        this.status(this.paint(SYMBOLS.success, "green"), text, detail);
+    }
+    warn(text, detail) {
+        this.status(this.paint(SYMBOLS.warning, "yellow"), text, detail);
+    }
+    failure(text, detail) {
+        this.status(this.paint(SYMBOLS.failure, "red"), text, detail);
+    }
+    pending(text, detail) {
+        this.status(this.paint(SYMBOLS.pending, "dim"), text, detail);
+    }
+    next(text) {
+        this.line();
+        this.line(`${this.paint(SYMBOLS.next, "cyan")} ${text}`);
+    }
+    status(symbol, text, detail) {
+        const padded = detail ? text.padEnd(22) : text;
+        this.line(`${symbol} ${padded}${detail ? ` ${this.paint(detail, "dim")}` : ""}`);
+    }
+    /**
+     * Spinner for genuine waiting only - a network round trip, a package
+     * download. Spinning while reading a local file is theatre that makes fast
+     * operations look slow.
+     */
+    async spin(label, work) {
+        if (!this.interactive) {
+            this.pending(label);
+            return work();
+        }
+        const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+        let i = 0;
+        this.write(ANSI.hideCursor);
+        const timer = setInterval(() => {
+            this.write(`\r${this.paint(frames[i % frames.length], "cyan")} ${label}`);
+            i++;
+        }, 80);
+        try {
+            return await work();
+        }
+        finally {
+            clearInterval(timer);
+            this.write(`\r${" ".repeat(label.length + 4)}\r`);
+            this.write(ANSI.showCursor);
+        }
+    }
+    /**
+     * Free-text answer, echoed as it is typed.
+     *
+     * The line editor is Node's readline, not JAM's: IME composition, CJK width,
+     * grapheme deletion, cursor movement and paste are the terminal's job, and a
+     * hand-rolled reader gets every one of them wrong. Cancelling is Ctrl-C,
+     * Ctrl-D or a closed stdin - readline swallows a lone Escape, so unlike
+     * `secret()` and `select()` this prompt cannot be cancelled with it.
+     */
+    async prompt(question, flagHint, fallback) {
+        if (!this.interactive)
+            throw new NonInteractiveError(question, flagHint);
+        const suffix = fallback ? ` ${this.paint(`[${fallback}]`, "dim")}` : "";
+        // One interface per question, closed in finally. A long-lived one on
+        // process.stdin would swallow the MCP stdio transport in `jam serve`.
+        // historySize 0: a Jira URL and an email are the user's, not JAM's to keep.
+        const rl = createInterface({
+            input: this.input,
+            output: this.stream,
+            terminal: true,
+            historySize: 0,
+        });
+        try {
+            const answer = await new Promise((resolve, reject) => {
+                // Ctrl-C, Ctrl-D and a stdin that ends all arrive as `close`. Without
+                // this the question would hang on a stream nobody is answering.
+                rl.once("close", () => reject(new CancelledError()));
+                rl.question(`${question}${suffix} `, resolve);
+            });
+            return answer || (fallback ?? "");
+        }
+        finally {
+            rl.close();
+        }
+    }
+    /**
+     * Secret answer - nothing typed is ever echoed, to this stream or any other.
+     *
+     * No dots, no length hint, no redraw: an API token pasted into a terminal
+     * should leave no trace on screen for someone glancing over, in a screen
+     * share, or in scrollback.
+     */
+    async secret(question, flagHint) {
+        if (!this.interactive)
+            throw new NonInteractiveError(question, flagHint);
+        return this.readSecret(question);
+    }
+    /**
+     * The only place raw mode and a hand-managed buffer still live.
+     *
+     * A token needs four things - no echo, paste, delete, Enter - and a line
+     * editor that echoes nothing is not something readline offers. Everything
+     * `prompt` needs and this does not - cursor movement, IME, character width -
+     * stays out.
+     */
+    async readSecret(question) {
+        this.write(`${question} `);
+        emitKeypressEvents(this.input);
+        const wasRaw = this.input.isRaw ?? false;
+        this.input.setRawMode?.(true);
+        this.input.resume();
+        let buffer = "";
+        let removeListener = () => { };
+        try {
+            return await new Promise((resolve, reject) => {
+                const onKey = (str, key) => {
+                    if (key.name === "return" || key.name === "enter") {
+                        this.line();
+                        resolve(buffer);
+                        return;
+                    }
+                    if (key.name === "escape" || (key.ctrl && key.name === "c")) {
+                        this.line();
+                        reject(new CancelledError());
+                        return;
+                    }
+                    // Every shape a delete arrives in. Terminals disagree: Backspace may
+                    // send DEL (0x7f) or BS (0x08), and a Delete key can arrive as an
+                    // escape sequence that readline names "delete". Matching only
+                    // key.name === "backspace" leaves the rest to fall through to the
+                    // printable branch, where they are stripped to "" and silently do
+                    // nothing - which reads as "backspace is broken".
+                    if (key.name === "backspace" ||
+                        key.name === "delete" ||
+                        str === "\u007f" ||
+                        str === "\b") {
+                        // Drops one UTF-16 unit, not one grapheme. An API token is ASCII,
+                        // and no Unicode editor is coming here - that is what `prompt` and
+                        // readline are for.
+                        if (buffer.length === 0)
+                            return;
+                        buffer = buffer.slice(0, -1);
+                        return;
+                    }
+                    // Ignore control keys; take printable characters, including whole
+                    // runs of them, which is how a paste arrives.
+                    if (key.ctrl || str === undefined || str === "")
+                        return;
+                    const printable = str.replace(/[\u0000-\u001f\u007f]/g, "");
+                    if (!printable)
+                        return;
+                    buffer += printable;
+                };
+                removeListener = () => this.input.off("keypress", onKey);
+                this.input.on("keypress", onKey);
+            });
+        }
+        finally {
+            // Teardown lives here and nowhere else: a listener stranded by a throw
+            // would let the next prompt receive the tail of a token. No cursor
+            // restore - this never hides it, and a no-op write would only suggest
+            // otherwise.
+            removeListener();
+            this.input.setRawMode?.(wasRaw);
+            this.input.pause();
+        }
+    }
+    /**
+     * Single-choice list. Throws in non-interactive mode rather than silently
+     * picking a default - an unattended run that quietly chose for you is worse
+     * than one that tells you which flag to pass.
+     */
+    async select(question, choices, flagHint) {
+        if (choices.length === 0)
+            throw new Error("select() needs at least one choice");
+        if (!this.interactive)
+            throw new NonInteractiveError(question, flagHint);
+        let index = 0;
+        const rows = choices.length * 2 + 1;
+        const render = (first) => {
+            if (!first)
+                this.write(cursorUp(rows));
+            this.line(question);
+            choices.forEach((choice, i) => {
+                const active = i === index;
+                const marker = active ? this.paint(SYMBOLS.selected, "cyan") : " ";
+                const label = active ? this.paint(choice.label, "cyan") : choice.label;
+                this.line(`${marker} ${label}`);
+                this.line(`  ${this.paint(choice.hint ?? "", "dim")}`);
+            });
+        };
+        render(true);
+        this.write(ANSI.hideCursor);
+        emitKeypressEvents(this.input);
+        const wasRaw = this.input.isRaw ?? false;
+        this.input.setRawMode?.(true);
+        this.input.resume();
+        let removeListener = () => { };
+        try {
+            return await new Promise((resolve, reject) => {
+                const onKey = (_str, key) => {
+                    if (key.name === "up") {
+                        index = (index - 1 + choices.length) % choices.length;
+                        render(false);
+                    }
+                    else if (key.name === "down") {
+                        index = (index + 1) % choices.length;
+                        render(false);
+                    }
+                    else if (key.name === "return") {
+                        resolve(choices[index].value);
+                    }
+                    else if (key.name === "escape" || (key.ctrl && key.name === "c")) {
+                        reject(new CancelledError());
+                    }
+                };
+                removeListener = () => this.input.off("keypress", onKey);
+                this.input.on("keypress", onKey);
+            });
+        }
+        finally {
+            removeListener();
+            this.input.setRawMode?.(wasRaw);
+            this.input.pause();
+            this.write(ANSI.showCursor);
+        }
+    }
+}

package/dist/cli-entry.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Command dispatch for the JAM CLI, separated from the bin so other entry
+ * points (notably @jam-mcp/bootstrap) can forward to exactly these commands
+ * instead of reimplementing them.
+ */
+export declare const USAGE = "jam - Jira Agent MCP\n\nUsage:\n  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)\n  jam doctor              Diagnose config, credentials and Jira connectivity\n  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]\n                          Wire up this project and run doctor. Binds it to you\n                          alone, writing nothing to the repository; --shared\n                          adopts JAM for the team (project.yaml, .mcp.json)\n  jam runtime             Show which JAM build this machine runs\n  jam runtime use package | development <path>\n                          Change it (writes ~/.jam/config.yaml only, never a project)\n  jam auth login          Store Jira credentials in this user's OS secret store\n  jam auth logout         Remove them again\n\nFor coding agents and scripts (stdout is JSON only, never prompts):\n  jam setup --agent       One shot: detect, plan, apply what is safe, verify\n  jam setup plan --json   Report what setup would change, changing nothing\n  jam setup apply --non-interactive --json\n                          Execute the plan\n  jam doctor --json       Health check as structured output\n  jam auth status --json  Whether Jira credentials are configured (never their value)\n\nEnvironment:\n  JIRA_BASE_URL     https://your-site.atlassian.net\n  JIRA_EMAIL        Atlassian account email\n  JIRA_API_TOKEN    Atlassian API token\n  JAM_PROJECT_KEY   Jira project key, used by `jam setup`/`jam serve` when no\n                     .jira-agent/project.yaml exists yet\n\nCredentials and JAM_PROJECT_KEY are read from the current shell's environment\nfirst, then (on Windows) from the User environment - so a value set with\n`setx` works without opening a new terminal.\n";
+export declare function runJamCommand(argv: string[]): Promise<number>;

package/dist/cli-entry.js

@@ -0,0 +1,124 @@
+import { authLoginCommand, authLogoutCommand } from "./cli/auth.js";
+import { doctor } from "./cli/doctor.js";
+import { showRuntime, useRuntime } from "./cli/runtime.js";
+import { serve } from "./cli/serve.js";
+import { setup } from "./cli/setup.js";
+import { runSetupWizard } from "./cli/setup-wizard.js";
+import { reportPromptError, Ui } from "./cli/ui.js";
+import { authStatusCommand, doctorJsonCommand, setupAgentCommand, setupApplyCommand, setupPlanCommand, } from "./cli/agent-api.js";
+/**
+ * Command dispatch for the JAM CLI, separated from the bin so other entry
+ * points (notably @jam-mcp/bootstrap) can forward to exactly these commands
+ * instead of reimplementing them.
+ */
+export const USAGE = `jam - Jira Agent MCP
+
+Usage:
+  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)
+  jam doctor              Diagnose config, credentials and Jira connectivity
+  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]
+                          Wire up this project and run doctor. Binds it to you
+                          alone, writing nothing to the repository; --shared
+                          adopts JAM for the team (project.yaml, .mcp.json)
+  jam runtime             Show which JAM build this machine runs
+  jam runtime use package | development <path>
+                          Change it (writes ~/.jam/config.yaml only, never a project)
+  jam auth login          Store Jira credentials in this user's OS secret store
+  jam auth logout         Remove them again
+
+For coding agents and scripts (stdout is JSON only, never prompts):
+  jam setup --agent       One shot: detect, plan, apply what is safe, verify
+  jam setup plan --json   Report what setup would change, changing nothing
+  jam setup apply --non-interactive --json
+                          Execute the plan
+  jam doctor --json       Health check as structured output
+  jam auth status --json  Whether Jira credentials are configured (never their value)
+
+Environment:
+  JIRA_BASE_URL     https://your-site.atlassian.net
+  JIRA_EMAIL        Atlassian account email
+  JIRA_API_TOKEN    Atlassian API token
+  JAM_PROJECT_KEY   Jira project key, used by \`jam setup\`/\`jam serve\` when no
+                     .jira-agent/project.yaml exists yet
+
+Credentials and JAM_PROJECT_KEY are read from the current shell's environment
+first, then (on Windows) from the User environment - so a value set with
+\`setx\` works without opening a new terminal.
+`;
+function findFlagValue(argv, flag) {
+    const index = argv.indexOf(flag);
+    return index >= 0 ? argv[index + 1] : undefined;
+}
+/**
+ * Commands that may ask a question share the wizard's mapping: a cancelled
+ * prompt is not a failure, and a missing terminal is guidance rather than a
+ * diagnosis.
+ */
+async function withPrompts(run) {
+    const ui = new Ui();
+    try {
+        return await run();
+    }
+    catch (err) {
+        const code = reportPromptError(err, ui);
+        if (code === undefined)
+            throw err;
+        return code;
+    }
+}
+export async function runJamCommand(argv) {
+    const [command, ...rest] = argv;
+    switch (command ?? "serve") {
+        case "serve":
+            return serve();
+        case "doctor":
+            return rest.includes("--json") ? doctorJsonCommand() : doctor();
+        case "setup": {
+            const explicitKey = findFlagValue(rest, "--project");
+            const common = {
+                ...(explicitKey ? { explicitKey } : {}),
+                ...(rest.includes("--migrate") ? { migrate: true } : {}),
+                // Personal by default: JAM is configured for this user, and the
+                // repository is only written to when someone asks for the team.
+                ...(rest.includes("--shared") ? { shared: true } : {}),
+            };
+            // Agent entry points first: each is non-interactive by construction, so
+            // no question can ever block an automated caller.
+            if (rest.includes("--agent"))
+                return setupAgentCommand(common);
+            if (rest[0] === "plan")
+                return setupPlanCommand(common);
+            if (rest[0] === "apply")
+                return setupApplyCommand(common);
+            // The wizard can ask; the plain path never does.
+            return rest.includes("--non-interactive") ? setup(common) : runSetupWizard(common);
+        }
+        case "runtime": {
+            const json = rest.includes("--json");
+            if (rest[0] === "use")
+                return useRuntime(rest[1], rest[2], { json });
+            return showRuntime({ json });
+        }
+        case "auth": {
+            if (rest[0] === "status")
+                return authStatusCommand();
+            // login/logout are human-only by design: an agent must stop at
+            // JAM_AUTH_REQUIRED and hand the person this command, never run it with a
+            // token it was given.
+            if (rest[0] === "login")
+                return withPrompts(() => authLoginCommand());
+            if (rest[0] === "logout")
+                return withPrompts(async () => authLogoutCommand());
+            process.stderr.write("Usage: jam auth login | status [--json] | logout\n");
+            return 1;
+        }
+        case "help":
+        case "--help":
+        case "-h":
+            process.stdout.write(USAGE);
+            return 0;
+        default:
+            process.stderr.write(`Unknown command: ${command}\n\n${USAGE}`);
+            return 1;
+    }
+}

package/dist/config/load-config.d.ts

@@ -0,0 +1,18 @@
+import { type ProjectConfig } from "./schema.js";
+export declare const CONFIG_RELATIVE_PATH: string;
+/**
+ * Walk up from `startDir` looking for `.jira-agent/project.yaml`.
+ * Returns undefined when the project has no JAM config at all.
+ */
+export declare function findConfigPath(startDir?: string): string | undefined;
+export type LoadedConfig = {
+    config: ProjectConfig;
+    /** Undefined when defaults were used because no file was found. */
+    path?: string;
+};
+/**
+ * A missing config file is not fatal - JAM falls back to schema defaults so a
+ * bare `jam serve` still works. A malformed one IS fatal: silently running
+ * with the wrong field policy is worse than refusing to start.
+ */
+export declare function loadConfig(startDir?: string): LoadedConfig;

package/dist/config/load-config.js

@@ -0,0 +1,48 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { JamError } from "../domain/errors.js";
+import { ProjectConfigSchema } from "./schema.js";
+export const CONFIG_RELATIVE_PATH = join(".jira-agent", "project.yaml");
+/**
+ * Walk up from `startDir` looking for `.jira-agent/project.yaml`.
+ * Returns undefined when the project has no JAM config at all.
+ */
+export function findConfigPath(startDir = process.cwd()) {
+    let dir = resolve(startDir);
+    for (;;) {
+        const candidate = join(dir, CONFIG_RELATIVE_PATH);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * A missing config file is not fatal - JAM falls back to schema defaults so a
+ * bare `jam serve` still works. A malformed one IS fatal: silently running
+ * with the wrong field policy is worse than refusing to start.
+ */
+export function loadConfig(startDir = process.cwd()) {
+    const path = findConfigPath(startDir);
+    if (!path) {
+        return { config: ProjectConfigSchema.parse({}) };
+    }
+    let raw;
+    try {
+        raw = parseYaml(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        throw new JamError("CONFIG_INVALID", `Could not parse ${path}: ${err instanceof Error ? err.message : String(err)}`, { path });
+    }
+    const parsed = ProjectConfigSchema.safeParse(raw ?? {});
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+            .join("; ");
+        throw new JamError("CONFIG_INVALID", `Invalid ${path} - ${issues}`, { path });
+    }
+    return { config: parsed.data, path };
+}