felenova-backlog 0.1.0

package/dist/init/auth.js

@@ -0,0 +1,194 @@
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+import { ApiError, get } from '../api.js';
+import { CONFIG_FILENAME } from '../config.js';
+import { explain } from '../errors.js';
+import { readToken, tokenPath } from '../token.js';
+/**
+ * The token and the project. Both are decided before `init` writes anything: a refusal
+ * here must leave the repo exactly as it was, including the token file.
+ *
+ * There is no device flow — the service mints PATs in the web UI and nothing else. So the
+ * only interactive path is a hidden paste.
+ */
+/** A refusal `init` renders as one line. */
+export class InitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InitError';
+    }
+}
+/**
+ * Reads one line with the echo suppressed: the PAT never reaches the terminal, and so
+ * never reaches a scrollback buffer or a screen recording.
+ *
+ * The mute is a discarding output stream rather than an override of readline's internal
+ * `_writeToOutput` — that hook does not catch the per-character echo a terminal-mode
+ * interface writes, and the token would appear one character at a time.
+ */
+export async function promptHidden(prompt, io) {
+    const discard = new Writable({
+        write(_chunk, _encoding, done) {
+            done();
+        },
+    });
+    const rl = createInterface({ input: io.input, output: discard, terminal: true });
+    io.output.write(prompt);
+    try {
+        return await new Promise((resolve) => {
+            rl.question('', (answer) => resolve(answer.trim()));
+        });
+    }
+    finally {
+        rl.close();
+        io.output.write('\n');
+    }
+}
+/** Reads one visible line. */
+export async function promptLine(prompt, io) {
+    const rl = createInterface({ input: io.input, output: io.output, terminal: true });
+    try {
+        return await new Promise((resolve) => {
+            rl.question(prompt, (answer) => resolve(answer.trim()));
+        });
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * `--token` → `$BACKLOG_TOKEN` → `~/.config/backlog/token` → an interactive paste.
+ * Never logged, never echoed, never returned inside a message.
+ */
+export async function resolveInitToken(opts) {
+    const fromFlag = opts.flagToken?.trim();
+    if (fromFlag)
+        return { token: fromFlag, source: 'flag' };
+    const fromEnv = opts.env.BACKLOG_TOKEN?.trim();
+    if (fromEnv)
+        return { token: fromEnv, source: 'env' };
+    const fromFile = readToken(opts.home);
+    if (fromFile)
+        return { token: fromFile, source: 'file' };
+    if (!opts.io.interactive) {
+        throw new InitError(`no PAT available — pass --token, set BACKLOG_TOKEN, or put one in ${tokenPath(opts.home)} (mint it at ${opts.url}/me → "Mint a token")`);
+    }
+    const pasted = await promptHidden(`Paste a PAT (minted at ${opts.url}/me → "Mint a token"): `, opts.io);
+    if (!pasted)
+        throw new InitError('no PAT entered — nothing was written');
+    return { token: pasted, source: 'prompt' };
+}
+function parseProjects(body) {
+    if (!Array.isArray(body)) {
+        throw new InitError('the service returned a malformed project list — run: backlog doctor');
+    }
+    return body.map((raw) => {
+        const row = (raw ?? {});
+        const slug = typeof row.slug === 'string' ? row.slug : '';
+        if (!slug) {
+            throw new InitError('the service returned a project with no slug — run: backlog doctor');
+        }
+        return {
+            slug,
+            name: typeof row.name === 'string' ? row.name : slug,
+            role: typeof row.role === 'string' ? row.role : 'unknown',
+        };
+    });
+}
+/**
+ * `GET /v1/projects` — which is also the token's validation. A 401/403 renders through
+ * `explain()`: one sentence, no status code, no JSON.
+ */
+export async function fetchVisibleProjects(opts) {
+    try {
+        const body = await get({ url: opts.url, fetchImpl: opts.fetchImpl }, opts.token, '/v1/projects');
+        return parseProjects(body);
+    }
+    catch (err) {
+        if (err instanceof ApiError)
+            throw new InitError(explain(err, { url: opts.url }));
+        throw err;
+    }
+}
+function slugList(projects) {
+    return projects.map((p) => p.slug).join(', ');
+}
+/**
+ * Only what `GET /v1/projects` returned is offerable (SVC-008): a slug that is not in the
+ * list is a membership problem, and the CLI says so in the same words `doctor` uses.
+ *
+ * The order is `--project` → the project an existing `backlog.config.json` already names →
+ * the only visible project → a prompt. `configured` is what makes a re-run in a repo that
+ * is already set up non-interactive-safe: the repo has already answered "which project",
+ * and re-asking (or refusing because several are visible) would make `init` unusable in CI
+ * and annoying everywhere else. It is a *default*, not an override: `--project` still wins,
+ * and a configured project the token can no longer see is refused exactly like a typed one
+ * — silently falling back to a different project would point the repo's commands at the
+ * wrong register.
+ */
+export async function chooseProject(opts) {
+    const { projects, requested } = opts;
+    if (projects.length === 0) {
+        throw new InitError(`this token can see no projects — ask the Owner for a role on one (${opts.url}/me shows what it can reach)`);
+    }
+    const refuseUnseen = (slug, source) => {
+        const sentence = explain(new ApiError(404, 'not_found', ''), { project: slug, url: opts.url });
+        throw new InitError(`${sentence}${source}; visible to this token: ${slugList(projects)}`);
+    };
+    if (requested?.trim()) {
+        const slug = requested.trim();
+        const match = projects.find((p) => p.slug === slug);
+        if (match)
+            return match;
+        refuseUnseen(slug, '');
+    }
+    const configured = opts.configured?.trim();
+    if (configured) {
+        const match = projects.find((p) => p.slug === configured);
+        if (match)
+            return match;
+        refuseUnseen(configured, ` (named in ${CONFIG_FILENAME} — pass --project <slug> to point this repo somewhere else)`);
+    }
+    if (projects.length === 1) {
+        const only = projects[0];
+        if (!only)
+            throw new InitError('the service returned an empty project list');
+        return only;
+    }
+    if (!opts.io.interactive) {
+        throw new InitError(`several projects are visible (${slugList(projects)}) — re-run with --project <slug>`);
+    }
+    opts.io.output.write('Projects this token can see:\n');
+    projects.forEach((p, i) => {
+        opts.io.output.write(`  ${i + 1}) ${p.slug} — ${p.name} (${p.role})\n`);
+    });
+    const answer = await promptLine(`Pick one [1-${projects.length}]: `, opts.io);
+    const index = Number.parseInt(answer, 10);
+    const picked = Number.isInteger(index) ? projects[index - 1] : undefined;
+    if (!picked) {
+        throw new InitError(`"${answer}" is not one of 1-${projects.length} — re-run and pick a number, or pass --project <slug>`);
+    }
+    return picked;
+}
+/** Whether to persist the PAT: the flag if given, else an interactive y/N, else no. */
+export async function shouldSaveToken(opts) {
+    if (opts.flag !== undefined)
+        return opts.flag;
+    // It is already there, and `readToken` proved the mode. Nothing to consent to.
+    if (opts.source === 'file')
+        return false;
+    if (opts.yes)
+        return true;
+    // Only the human who just pasted a PAT is asked. A token that arrived by flag or in the
+    // environment is somebody's deliberate, possibly throwaway choice — persisting it needs
+    // `--save-token`, not a question nobody expected.
+    if (opts.source !== 'prompt')
+        return false;
+    if (!opts.io.interactive)
+        return false;
+    const answer = await promptLine(`Save the PAT to ${tokenPath(opts.home)} (mode 600)? [y/N] `, {
+        ...opts.io,
+    });
+    return /^y(es)?$/i.test(answer.trim());
+}
+//# sourceMappingURL=auth.js.map

package/dist/init/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/init/auth.ts"],"names":[],"mappings":"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"}

package/dist/init/claudemd.d.ts

@@ -0,0 +1,16 @@
+import { type ClaudeSectionContext } from './templates.js';
+/**
+ * The section is marker-delimited so a second `init` can update it without a diff, and so
+ * the rest of somebody's `CLAUDE.md` is never in play. An *unmarked* "Backlog → Conductor"
+ * heading is someone's hand-written prose: it is left exactly as it is and reported.
+ */
+export declare const CLAUDE_FILENAME = "CLAUDE.md";
+export type ClaudeOutcome = 'created' | 'appended' | 'updated' | 'unchanged' | 'legacy';
+export interface ClaudeResult {
+    outcome: ClaudeOutcome;
+    line: string;
+}
+export declare function writeClaudeSection(opts: {
+    cwd: string;
+    ctx: ClaudeSectionContext;
+}): ClaudeResult;

package/dist/init/claudemd.js

@@ -0,0 +1,62 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { InitError } from './auth.js';
+import { claudeSection, END_MARKER, LEGACY_HEADING, START_MARKER, } from './templates.js';
+/**
+ * The section is marker-delimited so a second `init` can update it without a diff, and so
+ * the rest of somebody's `CLAUDE.md` is never in play. An *unmarked* "Backlog → Conductor"
+ * heading is someone's hand-written prose: it is left exactly as it is and reported.
+ */
+export const CLAUDE_FILENAME = 'CLAUDE.md';
+export function writeClaudeSection(opts) {
+    const path = join(opts.cwd, CLAUDE_FILENAME);
+    const block = claudeSection(opts.ctx);
+    let text = null;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        text = null;
+    }
+    if (text === null) {
+        writeFileSync(path, block, 'utf8');
+        return {
+            outcome: 'created',
+            line: `${CLAUDE_FILENAME}: created with the Backlog → Conductor section`,
+        };
+    }
+    const start = text.indexOf(START_MARKER);
+    const end = text.indexOf(END_MARKER);
+    if (start !== -1 && end === -1) {
+        throw new InitError(`${path} has ${START_MARKER} but no ${END_MARKER} — close the block by hand; init will not guess where it ends`);
+    }
+    if (start !== -1 && end < start) {
+        throw new InitError(`${path} has ${END_MARKER} before ${START_MARKER} — fix the markers by hand`);
+    }
+    if (start !== -1) {
+        const after = end + END_MARKER.length;
+        const current = text.slice(start, after);
+        const replacement = block.trimEnd();
+        if (current === replacement) {
+            return { outcome: 'unchanged', line: `${CLAUDE_FILENAME}: section already up to date` };
+        }
+        writeFileSync(path, `${text.slice(0, start)}${replacement}${text.slice(after)}`, 'utf8');
+        return {
+            outcome: 'updated',
+            line: `${CLAUDE_FILENAME}: section updated in place (only the text between the markers)`,
+        };
+    }
+    if (text.includes(LEGACY_HEADING)) {
+        return {
+            outcome: 'legacy',
+            line: `${CLAUDE_FILENAME}: an unmarked "Backlog → Conductor" heading is already there — left alone; delete it if you want init to manage the section`,
+        };
+    }
+    const prefix = text === '' || text.endsWith('\n') ? text : `${text}\n`;
+    writeFileSync(path, `${prefix}\n${block}`, 'utf8');
+    return {
+        outcome: 'appended',
+        line: `${CLAUDE_FILENAME}: Backlog → Conductor section appended`,
+    };
+}
+//# sourceMappingURL=claudemd.js.map

package/dist/init/claudemd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claudemd.js","sourceRoot":"","sources":["../../src/init/claudemd.ts"],"names":[],"mappings":"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"}

package/dist/init/index.d.ts

@@ -0,0 +1,47 @@
+export { InitError } from './auth.js';
+/**
+ * `backlog init` — the one command that turns a repo into a client of the register.
+ *
+ * Two invariants shape the order below. First, **nothing is written until the token and
+ * the project are settled**: a refusal (a rejected PAT, a project the token cannot see)
+ * must leave the repo, and `~/.config/backlog/token`, exactly as they were. Second,
+ * **every write is create-if-missing, merge, or refuse** — `init` never overwrites a file
+ * it did not write, and a second run is a byte-for-byte no-op that prints what it left
+ * alone (DECISION-027).
+ *
+ * The doctor runs last and decides only the exit code, after everything is on disk: a
+ * failing check is a diagnosis, not a reason to leave the install half-done.
+ */
+export interface InitFlags {
+    url?: string | undefined;
+    project?: string | undefined;
+    token?: string | undefined;
+    /** `--save-token` / `--no-save-token`; undefined means "ask, or don't". */
+    saveToken?: boolean | undefined;
+    /** `--yes`: never prompt, and consent to storing a pasted PAT. */
+    yes?: boolean | undefined;
+    /** `--force-mcp`: replace a differing register server entry (`MCP_SERVER_KEY`). */
+    forceMcp?: boolean | undefined;
+    /** `--force-plugin`: replace a payload file that exists with different content. */
+    forcePlugin?: boolean | undefined;
+}
+export interface InitOptions {
+    cwd: string;
+    home: string;
+    env: NodeJS.ProcessEnv;
+    flags: InitFlags;
+    fetchImpl?: typeof fetch | undefined;
+    input?: NodeJS.ReadableStream | undefined;
+    output?: NodeJS.WritableStream | undefined;
+    /** Overrides TTY detection; `--yes` forces it off. */
+    interactive?: boolean | undefined;
+}
+export interface InitResult {
+    /** The doctor's verdict — the process exit code comes from this, and only this. */
+    ok: boolean;
+    lines: string[];
+    project: string;
+    url: string;
+    conductorDir: string;
+}
+export declare function runInit(opts: InitOptions): Promise<InitResult>;

package/dist/init/index.js

@@ -0,0 +1,159 @@
+import { join } from 'node:path';
+import { CONFIG_FILENAME, ConfigError, loadConfig, writeConfig } from '../config.js';
+import { runDoctorRemote } from '../doctor.js';
+import { saveToken, tokenPath } from '../token.js';
+import { chooseProject, fetchVisibleProjects, InitError, resolveInitToken, shouldSaveToken, } from './auth.js';
+import { writeClaudeSection } from './claudemd.js';
+import { writeMcpJson } from './mcp.js';
+import { installPlugin } from './plugin.js';
+import { scaffoldConductor, updateGitignore } from './scaffold.js';
+import { DEFAULT_CONDUCTOR_DIR, DEFAULT_URL } from './templates.js';
+export { InitError } from './auth.js';
+function describeTokenSource(source, home) {
+    switch (source) {
+        case 'flag':
+            return 'read from --token';
+        case 'env':
+            return 'read from BACKLOG_TOKEN';
+        case 'file':
+            return `read from ${tokenPath(home)}`;
+        default:
+            return 'read from the prompt';
+    }
+}
+function existingConfig(cwd) {
+    // A config file directly in `cwd` is the one `init` owns. A broken one is reported by
+    // its own message rather than being silently replaced.
+    const path = join(cwd, CONFIG_FILENAME);
+    try {
+        const loaded = loadConfig(cwd);
+        if (!loaded || loaded.path !== path)
+            return null;
+        return { ...loaded.config, path: loaded.path };
+    }
+    catch (err) {
+        if (err instanceof ConfigError) {
+            throw new InitError(`${err.message} — fix or delete ${err.path}, then run init again (init never rewrites a config it cannot read)`);
+        }
+        throw err;
+    }
+}
+export async function runInit(opts) {
+    const lines = [];
+    const output = opts.output ?? process.stdout;
+    const say = (line) => {
+        lines.push(line);
+        output.write(`${line}\n`);
+    };
+    const inTty = Boolean(opts.input?.isTTY && output.isTTY);
+    const io = {
+        input: opts.input ?? process.stdin,
+        output,
+        interactive: opts.flags.yes ? false : (opts.interactive ?? inTty),
+    };
+    const prior = existingConfig(opts.cwd);
+    // 2. the service URL: --url → BACKLOG_URL → an existing config → the shipped default
+    const url = (opts.flags.url?.trim() ||
+        opts.env.BACKLOG_URL?.trim() ||
+        prior?.url ||
+        DEFAULT_URL).replace(/\/+$/, '');
+    // 1. the token, still without writing anything
+    const token = await resolveInitToken({
+        flagToken: opts.flags.token,
+        env: opts.env,
+        home: opts.home,
+        url,
+        io,
+    });
+    say(`token: ${describeTokenSource(token.source, opts.home)}`);
+    say(`url: ${url}`);
+    // 3. only what GET /v1/projects returns is offerable (SVC-008)
+    const projects = await fetchVisibleProjects({
+        url,
+        token: token.token,
+        fetchImpl: opts.fetchImpl,
+    });
+    say(`projects: ${projects.length} visible to this token (${projects.map((p) => p.slug).join(', ')})`);
+    const project = await chooseProject({
+        requested: opts.flags.project,
+        // The repo's existing answer is the default when no flag gives one (Task 6's finding):
+        // a re-run must not have to re-choose, and must not refuse just because the token can
+        // see more than one project.
+        configured: prior?.project,
+        projects,
+        url,
+        io,
+    });
+    // Say where the choice came from when it came from the config, so a re-run that picks a
+    // project without asking is not mistaken for a guess.
+    const fromConfig = !opts.flags.project?.trim() && prior?.project === project.slug;
+    say(`project: ${project.slug} — ${project.name} (${project.role})${fromConfig ? ` — from ${CONFIG_FILENAME}` : ''}`);
+    // the token is proven now, so persisting it is finally safe
+    const save = await shouldSaveToken({
+        flag: opts.flags.saveToken,
+        yes: opts.flags.yes,
+        source: token.source,
+        home: opts.home,
+        io,
+    });
+    if (save) {
+        const path = saveToken(opts.home, token.token);
+        say(`token: saved to ${path} (mode 600)`);
+    }
+    else if (token.source === 'file') {
+        say(`token: already at ${tokenPath(opts.home)}`);
+    }
+    else {
+        say(`token: not saved — to keep it: printf '%s\\n' "$BACKLOG_TOKEN" > ${tokenPath(opts.home)} && chmod 600 ${tokenPath(opts.home)}`);
+    }
+    // 4. backlog.config.json — created, or updated in place with only the three keys
+    const conductorDir = prior?.conductor_dir ?? DEFAULT_CONDUCTOR_DIR;
+    const configPath = join(opts.cwd, CONFIG_FILENAME);
+    const wanted = { url, project: project.slug, conductor_dir: conductorDir };
+    if (!prior) {
+        writeConfig(configPath, wanted);
+        say(`${CONFIG_FILENAME}: created (url, project, conductor_dir)`);
+    }
+    else if (prior.url === wanted.url &&
+        prior.project === wanted.project &&
+        prior.conductor_dir === wanted.conductor_dir) {
+        say(`${CONFIG_FILENAME}: unchanged`);
+    }
+    else {
+        writeConfig(configPath, wanted);
+        say(`${CONFIG_FILENAME}: updated in place (project ${project.slug}, conductor_dir ${conductorDir})`);
+    }
+    // 5. .mcp.json — create, or merge without touching another tool's server
+    say(writeMcpJson({ cwd: opts.cwd, url, force: Boolean(opts.flags.forceMcp) }).line);
+    say(updateGitignore(opts.cwd));
+    // 6. the conductor scaffold — create-if-missing, file by file
+    for (const line of scaffoldConductor({ cwd: opts.cwd, conductorDir }).lines)
+        say(line);
+    // 7. CLAUDE.md — one marked section, updated in place on a second run
+    say(writeClaudeSection({
+        cwd: opts.cwd,
+        ctx: { url, project: project.slug, conductorDir },
+    }).line);
+    // 8. the plugin payload — one line per file, then the summary
+    for (const line of installPlugin({ cwd: opts.cwd, force: Boolean(opts.flags.forcePlugin) })
+        .lines) {
+        say(line);
+    }
+    // 9. the doctor, last: it decides the exit code, never what gets written
+    const report = await runDoctorRemote(opts.env, {
+        cwd: opts.cwd,
+        home: opts.home,
+        url,
+        project: project.slug,
+        ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+    });
+    say('doctor:');
+    for (const check of report.checks) {
+        // Same rendering as the `doctor` command: a hint is advice about a failure, so a
+        // passing check prints its name and nothing else.
+        const hint = check.ok || !check.hint ? '' : ` — ${check.hint}`;
+        say(`  ${check.ok ? 'ok  ' : 'FAIL'} ${check.name}${hint}`);
+    }
+    return { ok: report.ok, lines, project: project.slug, url, conductorDir };
+}
+//# sourceMappingURL=index.js.map

package/dist/init/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/init/index.ts"],"names":[],"mappings":"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"}

package/dist/init/mcp.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `.mcp.json` is a file other tools own too — every other server in it belongs to someone
+ * else. So this is a merge, never a rewrite: add the `backlog` key when it is absent, keep
+ * every other key exactly as it was, and refuse a differing `backlog` entry rather than
+ * silently re-pointing somebody's MCP client.
+ */
+export declare const MCP_FILENAME = ".mcp.json";
+export type McpOutcome = 'created' | 'added' | 'identical' | 'replaced';
+export interface McpResult {
+    outcome: McpOutcome;
+    line: string;
+}
+/** Create or merge. Returns the line `init` prints; throws when it would have to clobber. */
+export declare function writeMcpJson(opts: {
+    cwd: string;
+    url: string;
+    force: boolean;
+}): McpResult;

package/dist/init/mcp.js

@@ -0,0 +1,97 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { InitError } from './auth.js';
+import { MCP_SERVER_KEY, mcpServerEntry } from './templates.js';
+/**
+ * `.mcp.json` is a file other tools own too — every other server in it belongs to someone
+ * else. So this is a merge, never a rewrite: add the `backlog` key when it is absent, keep
+ * every other key exactly as it was, and refuse a differing `backlog` entry rather than
+ * silently re-pointing somebody's MCP client.
+ */
+export const MCP_FILENAME = '.mcp.json';
+function stable(value) {
+    return JSON.stringify(value);
+}
+function describeDifference(existing, wanted) {
+    const lines = [];
+    const row = (existing ?? {});
+    const url = row.url;
+    if (url !== wanted.url) {
+        lines.push(`  url: ${typeof url === 'string' ? url : stable(url)} → ${wanted.url}`);
+    }
+    const type = row.type;
+    if (type !== wanted.type) {
+        lines.push(`  type: ${typeof type === 'string' ? type : stable(type)} → ${wanted.type}`);
+    }
+    const headers = (row.headers ?? {});
+    const auth = headers.Authorization;
+    if (auth !== wanted.headers.Authorization) {
+        // The wanted value is the literal placeholder; an existing one is only ever echoed
+        // when it is *not* a token-shaped string.
+        const shown = typeof auth === 'string' && /bkl_|secret/i.test(auth) ? '<a literal value>' : stable(auth);
+        lines.push(`  headers.Authorization: ${shown} → ${stable(wanted.headers.Authorization)}`);
+    }
+    if (lines.length === 0)
+        lines.push(`  ${stable(existing)} → ${stable(wanted)}`);
+    return lines.join('\n');
+}
+/** Create or merge. Returns the line `init` prints; throws when it would have to clobber. */
+export function writeMcpJson(opts) {
+    const path = join(opts.cwd, MCP_FILENAME);
+    const wanted = mcpServerEntry(opts.url);
+    let text = null;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        text = null;
+    }
+    if (text === null) {
+        const doc = { mcpServers: { [MCP_SERVER_KEY]: wanted } };
+        writeFileSync(path, `${JSON.stringify(doc, null, 2)}\n`, 'utf8');
+        return {
+            outcome: 'created',
+            line: `${MCP_FILENAME}: created with the ${MCP_SERVER_KEY} server entry (${wanted.headers.Authorization})`,
+        };
+    }
+    let doc;
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            throw new Error('not an object');
+        }
+        doc = parsed;
+    }
+    catch {
+        throw new InitError(`${path} is not a JSON object — fix it by hand; init never rewrites an existing ${MCP_FILENAME}`);
+    }
+    const rawServers = doc.mcpServers;
+    if (rawServers !== undefined && (typeof rawServers !== 'object' || rawServers === null)) {
+        throw new InitError(`${path} has an "mcpServers" that is not an object — fix it by hand; init never rewrites an existing ${MCP_FILENAME}`);
+    }
+    const servers = { ...(rawServers ?? {}) };
+    const existing = servers[MCP_SERVER_KEY];
+    if (existing !== undefined) {
+        if (stable(existing) === stable(wanted)) {
+            return {
+                outcome: 'identical',
+                line: `${MCP_FILENAME}: ${MCP_SERVER_KEY} entry already correct — left alone`,
+            };
+        }
+        if (!opts.force) {
+            throw new InitError(`${path} already has a different "${MCP_SERVER_KEY}" server entry:\n${describeDifference(existing, wanted)}\nedit ${MCP_FILENAME} yourself, or re-run with --force-mcp to replace just that entry`);
+        }
+    }
+    servers[MCP_SERVER_KEY] = wanted;
+    writeFileSync(path, `${JSON.stringify({ ...doc, mcpServers: servers }, null, 2)}\n`, 'utf8');
+    return existing === undefined
+        ? {
+            outcome: 'added',
+            line: `${MCP_FILENAME}: added the ${MCP_SERVER_KEY} server entry (${wanted.headers.Authorization}); every other server left as it was`,
+        }
+        : {
+            outcome: 'replaced',
+            line: `${MCP_FILENAME}: replaced the ${MCP_SERVER_KEY} server entry (--force-mcp); every other server left as it was`,
+        };
+}
+//# sourceMappingURL=mcp.js.map

package/dist/init/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../src/init/mcp.ts"],"names":[],"mappings":"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"}