harness-dispatch 0.7.9 → 0.9.0

package/dist/client-register.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Register this server with the MCP clients installed on this machine.
+ *
+ * WHY THIS EXISTS. Setup was a copy-paste job: `configure` printed a JSON
+ * snippet and the user pasted it somewhere. Nobody owned the result, and on
+ * the maintainer's machine that produced, at the same time — a Claude Code
+ * entry launching a directory renamed away months earlier, a session hook
+ * pointing at the same dead path, and a working Cursor entry with no
+ * `--config`, so the two clients disagreed about which routes existed while
+ * both appeared to work.
+ *
+ * WHY IT IS PARANOID. This project has failed at exactly this before. v0.1.0
+ * shipped a setup command that wrote `~/.claude/CLAUDE.md` and a hooks entry;
+ * v0.2.0 removed the command and neither artifact was ever cleaned up. Both
+ * were still on the machine seven minor versions later, the hook failing
+ * silently every session. So:
+ *
+ *  - only the two config shapes actually opened on a real machine are written;
+ *  - every write is backed up, merged, and swapped in atomically;
+ *  - an entry that already exists and differs is REPORTED, never overwritten
+ *    without consent — that Cursor entry was good, and a blind writer would
+ *    have destroyed a working setup in the name of fixing it;
+ *  - removal ships in the same change as writing, so the ENTRY is never left
+ *    orphaned when someone changes their mind. Backups are bounded rather than
+ *    removed with it — see pruneOwnBackups for why undoing a registration is
+ *    the worst moment to delete the record of what it replaced.
+ *
+ * It writes MCP server registration and nothing else — no instructions, no
+ * hooks, no behavioural configuration. That is the part that rotted last time.
+ */
+/** The key this server is registered under, and the only one we ever touch. */
+export declare const ENTRY_KEY = "harness-dispatch";
+export interface ServerEntry {
+    command: string;
+    args: string[];
+}
+/**
+ * What a client's config says about us right now.
+ *
+ * `absent` is the client not being installed — not a fault, and not something
+ * to offer. `unreadable` covers a config that will not parse: that is the
+ * other application's problem, and the one thing we must not do is rewrite a
+ * file we could not understand.
+ */
+/**
+ * `absent`: neither the config file nor the client's command exists — not
+ * installed. `missing-file`: the command is on PATH but the file is not there
+ * yet (Claude Code writes it on first interactive launch) — the file will be
+ * created with just our entry, which the client accepts as a user-scope
+ * registration (checked against Claude Code 2.1.258: `claude mcp list` shows
+ * the server from a file holding only `mcpServers`).
+ */
+export type ClientState = "absent" | "missing-file" | "unreadable" | "missing-entry" | "matches" | "differs";
+export interface ClientPlan {
+    id: string;
+    client: string;
+    file: string;
+    /** Carried from the client table so writers never re-derive it. */
+    serversKey: string;
+    state: ClientState;
+    /** The entry currently registered, when there is one. */
+    current?: unknown;
+    /** What we would write. */
+    desired: ServerEntry;
+}
+/**
+ * The entry to write.
+ *
+ * The `--config` path is absolute on purpose. A relative path — or none, which
+ * is what the machine's Cursor entry had — silently falls back to the shipped
+ * defaults, so the client quietly ignores every edit made to the config file
+ * and disagrees with the client next to it about which routes exist. Both look
+ * like they work, which is what made it survive.
+ */
+export declare function desiredEntry(configPath: string, command: string[]): ServerEntry;
+/**
+ * How to launch us, in the way most likely to still work next month.
+ *
+ * A global install is preferred because it needs no network and starts faster.
+ * `npx -y harness-dispatch` is the fallback, not an absolute path into a
+ * checkout: an absolute path is precisely what broke here, and the failure was
+ * invisible for months.
+ *
+ * This resolves PATH, which the read-only inspector deliberately refuses to do
+ * — but the trade is opposite. There, a wrong guess reports a healthy install
+ * as broken. Here, guessing "harness-dispatch" when nothing by that name is
+ * installed writes an entry that can never spawn, which is the exact silent
+ * breakage this whole feature exists to end.
+ */
+export declare function launchCommand(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Launch the build you are running RIGHT NOW, by absolute path.
+ *
+ * This is the one form the rest of this module argues against, and it exists
+ * because refusing to write it did not stop anyone needing it. On a
+ * development checkout the installed-package form is actively wrong: with
+ * nothing installed globally, `npx -y harness-dispatch` fetches the published
+ * version, so registering it would silently swap a checkout that is commits
+ * ahead for an older release — a downgrade that looks like a successful setup.
+ * That is exactly what `connect` found on the maintainer's machine, where the
+ * hand-written absolute entry was the correct one.
+ *
+ * The trade is real and unchanged: an absolute path stops working the moment
+ * the directory is renamed or deleted, silently, which is the failure that
+ * started all of this. It is opt-in per run, the path is printed before it is
+ * written, and `doctor` fails on a client entry naming a path that has gone —
+ * so the failure mode this reintroduces is the one thing already checked for.
+ */
+export declare function devLaunchCommand(entryPath: string): string[];
+/**
+ * What would change, per client, if we registered right now.
+ *
+ * Reports only. Nothing here writes, so a caller can show this and ask — which
+ * is the whole point, given one of the entries this was written for was
+ * already correct.
+ */
+export declare function planClientWrites(configPath: string, opts?: {
+    home?: string;
+    command?: string[];
+    /** Is any of these commands on PATH? Injectable so tests never depend on what is installed. */
+    installed?: (commands: string[]) => boolean;
+}): ClientPlan[];
+export interface WriteOutcome {
+    id: string;
+    client: string;
+    file: string;
+    action: "written" | "unchanged" | "skipped";
+    backupPath?: string;
+    reason?: string;
+}
+/**
+ * Register (or re-register) this server in one client's config.
+ *
+ * Merges: every other server, and every field of an existing entry we do not
+ * set, is preserved. `env` in particular holds live API keys on real machines
+ * — dropping it while "fixing" an entry would break unrelated servers and leak
+ * nothing but the user's afternoon.
+ */
+export declare function writeClientEntry(plan: ClientPlan, opts: {
+    stamp: string;
+    consented?: boolean;
+}): Promise<WriteOutcome>;
+/**
+ * Take our entry back out.
+ *
+ * Ships with the writer, not later: entries this tool created outliving the
+ * feature that created them is the documented way this project has already
+ * gone wrong once. An entry that no longer looks like ours is reported and
+ * LEFT ALONE — someone edited it deliberately, and deleting a hand-tuned entry
+ * because it no longer matches our template would be its own version of the
+ * same mistake.
+ */
+export declare function removeClientEntry(plan: ClientPlan, opts: {
+    stamp: string;
+    force?: boolean;
+}): Promise<WriteOutcome>;
+//# sourceMappingURL=client-register.d.ts.map

package/dist/client-register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-register.d.ts","sourceRoot":"","sources":["../src/client-register.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AASH,+EAA+E;AAC/E,eAAO,MAAM,SAAS,qBAAqB,CAAC;AAE5C,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;;;;GAOG;AACH;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,cAAc,GACd,YAAY,GACZ,eAAe,GACf,SAAS,GACT,SAAS,CAAC;AAEd,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,WAAW,CAAC;IACnB,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2BAA2B;IAC3B,OAAO,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,WAAW,CAG/E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,EAAE,CAI5E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAE5D;AAoCD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE;IACJ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,+FAA+F;IAC/F,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC;CACxC,GACL,UAAU,EAAE,CAuBd;AAgID,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3C,OAAO,CAAC,YAAY,CAAC,CA6DvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACvC,OAAO,CAAC,YAAY,CAAC,CAqCvB"}

package/dist/client-register.js

@@ -0,0 +1,389 @@
+/**
+ * Register this server with the MCP clients installed on this machine.
+ *
+ * WHY THIS EXISTS. Setup was a copy-paste job: `configure` printed a JSON
+ * snippet and the user pasted it somewhere. Nobody owned the result, and on
+ * the maintainer's machine that produced, at the same time — a Claude Code
+ * entry launching a directory renamed away months earlier, a session hook
+ * pointing at the same dead path, and a working Cursor entry with no
+ * `--config`, so the two clients disagreed about which routes existed while
+ * both appeared to work.
+ *
+ * WHY IT IS PARANOID. This project has failed at exactly this before. v0.1.0
+ * shipped a setup command that wrote `~/.claude/CLAUDE.md` and a hooks entry;
+ * v0.2.0 removed the command and neither artifact was ever cleaned up. Both
+ * were still on the machine seven minor versions later, the hook failing
+ * silently every session. So:
+ *
+ *  - only the two config shapes actually opened on a real machine are written;
+ *  - every write is backed up, merged, and swapped in atomically;
+ *  - an entry that already exists and differs is REPORTED, never overwritten
+ *    without consent — that Cursor entry was good, and a blind writer would
+ *    have destroyed a working setup in the name of fixing it;
+ *  - removal ships in the same change as writing, so the ENTRY is never left
+ *    orphaned when someone changes their mind. Backups are bounded rather than
+ *    removed with it — see pruneOwnBackups for why undoing a registration is
+ *    the worst moment to delete the record of what it replaced.
+ *
+ * It writes MCP server registration and nothing else — no instructions, no
+ * hooks, no behavioural configuration. That is the part that rotted last time.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { copyFile, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { commandAvailable } from "./dispatchers/shared/which-available.js";
+import { clientConfigLocations } from "./mcp-clients.js";
+/** The key this server is registered under, and the only one we ever touch. */
+export const ENTRY_KEY = "harness-dispatch";
+/**
+ * The entry to write.
+ *
+ * The `--config` path is absolute on purpose. A relative path — or none, which
+ * is what the machine's Cursor entry had — silently falls back to the shipped
+ * defaults, so the client quietly ignores every edit made to the config file
+ * and disagrees with the client next to it about which routes exist. Both look
+ * like they work, which is what made it survive.
+ */
+export function desiredEntry(configPath, command) {
+    const [cmd, ...prefix] = command;
+    return { command: cmd ?? "harness-dispatch", args: [...prefix, "--config", path.resolve(configPath)] };
+}
+/**
+ * How to launch us, in the way most likely to still work next month.
+ *
+ * A global install is preferred because it needs no network and starts faster.
+ * `npx -y harness-dispatch` is the fallback, not an absolute path into a
+ * checkout: an absolute path is precisely what broke here, and the failure was
+ * invisible for months.
+ *
+ * This resolves PATH, which the read-only inspector deliberately refuses to do
+ * — but the trade is opposite. There, a wrong guess reports a healthy install
+ * as broken. Here, guessing "harness-dispatch" when nothing by that name is
+ * installed writes an entry that can never spawn, which is the exact silent
+ * breakage this whole feature exists to end.
+ */
+export function launchCommand(env = process.env) {
+    return resolvesOnPath("harness-dispatch", env)
+        ? ["harness-dispatch"]
+        : ["npx", "-y", "harness-dispatch"];
+}
+/**
+ * Launch the build you are running RIGHT NOW, by absolute path.
+ *
+ * This is the one form the rest of this module argues against, and it exists
+ * because refusing to write it did not stop anyone needing it. On a
+ * development checkout the installed-package form is actively wrong: with
+ * nothing installed globally, `npx -y harness-dispatch` fetches the published
+ * version, so registering it would silently swap a checkout that is commits
+ * ahead for an older release — a downgrade that looks like a successful setup.
+ * That is exactly what `connect` found on the maintainer's machine, where the
+ * hand-written absolute entry was the correct one.
+ *
+ * The trade is real and unchanged: an absolute path stops working the moment
+ * the directory is renamed or deleted, silently, which is the failure that
+ * started all of this. It is opt-in per run, the path is printed before it is
+ * written, and `doctor` fails on a client entry naming a path that has gone —
+ * so the failure mode this reintroduces is the one thing already checked for.
+ */
+export function devLaunchCommand(entryPath) {
+    return ["node", path.resolve(entryPath)];
+}
+function resolvesOnPath(cmd, env) {
+    const dirs = (env.PATH ?? env.Path ?? "").split(path.delimiter).filter(Boolean);
+    // On Windows the executable is `harness-dispatch.cmd`/`.exe`, never the bare
+    // name — checking only the bare name would answer "not installed" on every
+    // Windows machine and send everyone to the slower npx form.
+    const exts = process.platform === "win32"
+        ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)
+        : [""];
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            if (existsSync(path.join(dir, cmd + ext.toLowerCase())))
+                return true;
+            if (existsSync(path.join(dir, cmd + ext)))
+                return true;
+        }
+    }
+    return false;
+}
+function sameEntry(a, b) {
+    const e = a;
+    if (!e || typeof e !== "object")
+        return false;
+    if (e.command !== b.command)
+        return false;
+    if (!Array.isArray(e.args) || e.args.length !== b.args.length)
+        return false;
+    return e.args.every((v, i) => v === b.args[i]);
+}
+function readJsonFile(file) {
+    try {
+        return { ok: true, value: JSON.parse(readFileSync(file, "utf8")) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/**
+ * What would change, per client, if we registered right now.
+ *
+ * Reports only. Nothing here writes, so a caller can show this and ask — which
+ * is the whole point, given one of the entries this was written for was
+ * already correct.
+ */
+export function planClientWrites(configPath, opts = {}) {
+    const desired = desiredEntry(configPath, opts.command ?? launchCommand());
+    const installed = opts.installed ?? ((commands) => commands.some((c) => commandAvailable(c)));
+    const locations = clientConfigLocations(opts.home);
+    return locations.map(({ id, client, file, serversKey, commands }) => {
+        const base = { id, client, file, serversKey, desired };
+        if (!existsSync(file)) {
+            return { ...base, state: installed(commands) ? "missing-file" : "absent" };
+        }
+        const parsed = readJsonFile(file);
+        if (!parsed.ok)
+            return { ...base, state: "unreadable" };
+        const servers = parsed.value?.[serversKey];
+        const current = servers && typeof servers === "object"
+            ? servers[ENTRY_KEY]
+            : undefined;
+        if (current === undefined)
+            return { ...base, state: "missing-entry" };
+        return {
+            ...base,
+            state: sameEntry(current, desired) ? "matches" : "differs",
+            current,
+        };
+    });
+}
+/**
+ * Copy the file next to itself before touching it.
+ *
+ * Same directory, so it inherits that directory's permissions rather than
+ * landing somewhere world-readable: `~/.claude.json` holds live API keys on
+ * this machine, and a backup is a copy of those keys.
+ */
+async function backup(file, stamp) {
+    const dest = `${file}.harness-dispatch-backup-${stamp}`;
+    await copyFile(file, dest);
+    await pruneOwnBackups(file);
+    return dest;
+}
+/** How many of our own backups of one file to keep. */
+const KEEP_BACKUPS = 3;
+const NOT_AN_OBJECT = "its config file is not a JSON object, so there is nothing to merge our entry into";
+/**
+ * The parsed file as something safe to spread into, or undefined if it is not.
+ *
+ * "Does it parse" and "is it the shape I am about to merge into" are different
+ * questions, and only the first was being asked. An ARRAY parses fine and then
+ * gets spread into an object: an array-rooted file came back as
+ * `{"0":…,"1":…,"mcpServers":{…}}` and `connect` reported success. A backup is
+ * always taken so it was recoverable — but this module edits OTHER
+ * applications' config files, which is the highest-consequence thing this
+ * product does, and it must not rewrite a shape it does not understand.
+ *
+ * `null`/absent stays mergeable: that is an empty file, which is the ordinary
+ * first-run case.
+ *
+ * Applied at EVERY level this spreads, not just the root. The first version
+ * guarded the root only, so `{"mcpServers": "oops"}` still had its string
+ * rekeyed into `{"0":"o","1":"o",…}` and reported success — the same defect
+ * one level down, found by the very next acceptance pass. Anywhere a spread
+ * happens, this question has to be asked first.
+ */
+function mergeableRoot(value) {
+    if (value === null || value === undefined)
+        return {};
+    if (typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    return value;
+}
+/**
+ * Keep the last few backups of a file, not all of them ever taken.
+ *
+ * Every write AND every removal takes one, so a few rounds of connect/--remove
+ * left a pile of copies of `~/.claude.json` — a file this module's own comment
+ * describes as holding live API keys — with nothing to prune them, no flag to
+ * decline them, and no command to list them. An acceptance pass found one
+ * already sitting on the maintainer's machine, and the module header's claim
+ * that "nothing this creates is left orphaned" was true of the entry and false
+ * of these.
+ *
+ * Bounded rather than removed entirely, and NOT cleared by `--remove`: the
+ * moment someone undoes a registration is the worst possible moment to destroy
+ * the copy of what it looked like before. Only files matching the name this
+ * function itself writes are touched, so a backup anyone else made is not ours
+ * to delete.
+ */
+async function pruneOwnBackups(file) {
+    const dir = path.dirname(file);
+    const prefix = `${path.basename(file)}.harness-dispatch-backup-`;
+    try {
+        const mine = (await readdir(dir))
+            .filter((name) => name.startsWith(prefix))
+            // The stamp is an ISO timestamp with `:` and `.` replaced, so it sorts
+            // lexicographically in chronological order.
+            .sort();
+        for (const name of mine.slice(0, Math.max(0, mine.length - KEEP_BACKUPS))) {
+            await rm(path.join(dir, name), { force: true });
+        }
+    }
+    catch {
+        // Best effort: failing to tidy up must never fail the registration itself.
+    }
+}
+/**
+ * Replace a JSON file without ever leaving it half-written.
+ *
+ * Write a sibling temp file, parse it BACK, and only then rename over the
+ * original — rename within a directory is atomic, so a reader sees the old
+ * file or the new one and never a truncated one. A half-written
+ * `~/.claude.json` costs someone their entire Claude Code configuration, which
+ * is a far worse outcome than failing to register.
+ */
+async function writeJsonAtomic(file, value, opts = {}) {
+    const tmp = `${file}.harness-dispatch-tmp-${process.pid}`;
+    const text = `${JSON.stringify(value, null, 2)}\n`;
+    await mkdir(path.dirname(file), { recursive: true });
+    // Carry the original's permissions onto the replacement.
+    //
+    // `rename` swaps the INODE, so the file that survives has the temp file's
+    // mode — 0644 under a typical umask — not its own. A `~/.claude.json` that
+    // Claude Code created 0600 therefore came back group- and world-readable,
+    // and that file holds live API keys: registering a server would have
+    // silently widened access to somebody's credentials.
+    //
+    // The same module's backup() uses copyFile, which preserves mode, so the two
+    // halves of one write path disagreed about whether the mode mattered. Found
+    // by reading during an acceptance pass; POSIX-only, and unreproducible on
+    // the Windows machine it was found on, which is exactly why it survived.
+    const mode = await stat(file)
+        .then((s) => s.mode & 0o777)
+        .catch(() => opts.createMode);
+    await writeFile(tmp, text, mode === undefined ? "utf8" : { encoding: "utf8", mode });
+    try {
+        JSON.parse(await readFile(tmp, "utf8"));
+    }
+    catch (err) {
+        await rm(tmp, { force: true });
+        throw new Error(`Refusing to write ${file}: the replacement did not parse back as JSON (${String(err)}). ` +
+            "The original file is untouched.");
+    }
+    await rename(tmp, file);
+}
+/**
+ * Register (or re-register) this server in one client's config.
+ *
+ * Merges: every other server, and every field of an existing entry we do not
+ * set, is preserved. `env` in particular holds live API keys on real machines
+ * — dropping it while "fixing" an entry would break unrelated servers and leak
+ * nothing but the user's afternoon.
+ */
+export async function writeClientEntry(plan, opts) {
+    const base = { id: plan.id, client: plan.client, file: plan.file };
+    if (plan.state === "absent") {
+        return { ...base, action: "skipped", reason: "no config file for this client" };
+    }
+    if (plan.state === "unreadable") {
+        return { ...base, action: "skipped", reason: "its config file does not parse as JSON" };
+    }
+    if (plan.state === "matches")
+        return { ...base, action: "unchanged" };
+    if (plan.state === "missing-file") {
+        // Nothing to merge and nothing to back up. 0600 because this file is
+        // where the client will later keep its own credentials.
+        await writeJsonAtomic(plan.file, { [plan.serversKey]: { [ENTRY_KEY]: plan.desired } }, { createMode: 0o600 });
+        return { ...base, action: "written" };
+    }
+    // An entry someone edited by hand is not ours to replace unasked.
+    //
+    // `removeClientEntry` has always refused this and this function did not, so
+    // the protection existed on the half where the cost is lower. An acceptance
+    // pass found OPERATIONS.md promising it for both and measured `connect
+    // --clients claude-code` printing the hand-written entry it was about to
+    // destroy and then destroying it, exit 0.
+    //
+    // `consented` is what the interactive path passes after showing the diff and
+    // getting a yes — that prompt IS the consent, so nothing changes for someone
+    // watching it happen. Naming a client on the command line is not the same
+    // thing: it says which client, not "and overwrite whatever I put there".
+    if (plan.state === "differs" && opts.consented !== true) {
+        return {
+            ...base,
+            action: "skipped",
+            reason: "its entry has been edited by hand — re-run interactively (no --clients, " +
+                "no --yes) to see the difference and confirm, or pass --force to overwrite it",
+        };
+    }
+    const parsed = readJsonFile(plan.file);
+    if (!parsed.ok) {
+        return { ...base, action: "skipped", reason: "its config file does not parse as JSON" };
+    }
+    const root = mergeableRoot(parsed.value);
+    if (root === undefined)
+        return { ...base, action: "skipped", reason: NOT_AN_OBJECT };
+    const serversValue = mergeableRoot(root[plan.serversKey]);
+    if (serversValue === undefined) {
+        return { ...base, action: "skipped", reason: `its \`${plan.serversKey}\` is not a JSON object` };
+    }
+    const servers = { ...serversValue };
+    const existing = mergeableRoot(servers[ENTRY_KEY]);
+    if (existing === undefined) {
+        return { ...base, action: "skipped", reason: `its existing \`${ENTRY_KEY}\` entry is not a JSON object` };
+    }
+    servers[ENTRY_KEY] = { ...existing, ...plan.desired };
+    const backupPath = await backup(plan.file, opts.stamp);
+    await writeJsonAtomic(plan.file, { ...root, [plan.serversKey]: servers });
+    return { ...base, action: "written", backupPath };
+}
+/**
+ * Take our entry back out.
+ *
+ * Ships with the writer, not later: entries this tool created outliving the
+ * feature that created them is the documented way this project has already
+ * gone wrong once. An entry that no longer looks like ours is reported and
+ * LEFT ALONE — someone edited it deliberately, and deleting a hand-tuned entry
+ * because it no longer matches our template would be its own version of the
+ * same mistake.
+ */
+export async function removeClientEntry(plan, opts) {
+    const base = { id: plan.id, client: plan.client, file: plan.file };
+    if (plan.state === "absent" || plan.state === "missing-file" || plan.state === "missing-entry") {
+        return { ...base, action: "unchanged" };
+    }
+    if (plan.state === "unreadable") {
+        return { ...base, action: "skipped", reason: "its config file does not parse as JSON" };
+    }
+    if (plan.state === "differs" && opts.force !== true) {
+        return {
+            ...base,
+            action: "skipped",
+            reason: "its entry has been edited by hand — remove it yourself, or pass --force",
+        };
+    }
+    const parsed = readJsonFile(plan.file);
+    if (!parsed.ok) {
+        return { ...base, action: "skipped", reason: "its config file does not parse as JSON" };
+    }
+    const root = mergeableRoot(parsed.value);
+    // Removal was already safe without this: our entry cannot be present in a
+    // file this shape, so the `ENTRY_KEY in servers` check below returns
+    // "unchanged" before anything is written. Kept anyway so both writers ask
+    // the same question of the same file, rather than one of them being correct
+    // by accident of a later check. A test for it was written and then deleted —
+    // it passed with the guard removed, so it was evidence of nothing.
+    if (root === undefined)
+        return { ...base, action: "unchanged" };
+    const serversValue = mergeableRoot(root[plan.serversKey]);
+    if (serversValue === undefined)
+        return { ...base, action: "unchanged" };
+    const servers = { ...serversValue };
+    if (!(ENTRY_KEY in servers))
+        return { ...base, action: "unchanged" };
+    delete servers[ENTRY_KEY];
+    const backupPath = await backup(plan.file, opts.stamp);
+    await writeJsonAtomic(plan.file, { ...root, [plan.serversKey]: servers });
+    return { ...base, action: "written", backupPath };
+}
+//# sourceMappingURL=client-register.js.map

package/dist/client-register.js.map

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

package/dist/config/validation.d.ts

@@ -67,6 +67,47 @@ export declare const KNOWN_TOP_LEVEL_KEYS: Set<string>;
  */
 export declare const KNOWN_ROUTE_KEYS: Set<string>;
 export declare function warnUnknownRouteKeys(entry: Record<string, unknown>, label: string, warnings: string[]): void;
+/**
+ * A RECOGNISED key carrying the wrong TYPE of value.
+ *
+ * The unknown-key warner above covers a misspelled key. It does not cover a
+ * correctly-spelled one whose value cannot be read: the coercions in
+ * coercions.ts drop on mismatch and the caller supplies a default, silently.
+ * That file's own header names this gap and points at the unknown-key warning
+ * as the mitigation — which does not cover it, because the key is not unknown.
+ *
+ * Found live on the maintainer's machine by an acceptance pass: four routes
+ * carrying `tier: metered`, which is not a number, silently running at the
+ * default tier 3. Nothing had ever said so. `weight: very-high` becomes 1.0 the
+ * same way, and both feed routing decisions.
+ *
+ * Reports rather than rejects, like every other warning here: the config still
+ * loads, and `doctor` exits non-zero so the signal is not merely decorative.
+ *
+ * The one thing it does beyond reporting is DELETE an out-of-range numeric
+ * value from the entry, so the built-in default applies. That is not a second
+ * behaviour bolted on: a non-numeric `tier: metered` already ends up at the
+ * default, because `num()` cannot read it. `tier: -5` is different only in
+ * that the coercion CAN read it, which is exactly why it is dangerous — it
+ * reaches routing and wins. Deleting the key makes the two unusable cases
+ * behave the same way, which is what an operator reading either warning
+ * ("IGNORED, and the built-in default applies instead") is being told.
+ *
+ * Every caller warns before it parses the same object, so the deletion is
+ * visible to the parse that follows.
+ */
+export declare function warnMistypedRouteValues(entry: Record<string, unknown>, label: string, warnings: string[]): void;
+/**
+ * Two route entries sharing one name.
+ *
+ * The later entry wins outright, so everything the earlier one declared is
+ * gone. An acceptance pass measured the consequence: a first entry setting
+ * `safety_profile: read_only` and `workspace_policy: copy` was replaced by a
+ * second with neither, and the surviving route ran `workspace_edit` /
+ * `shared_locked` — silently LESS restrictive than what was written, with no
+ * warning on any surface.
+ */
+export declare function warnDuplicateRouteNames(names: Array<string | undefined>, block: string, warnings: string[]): void;
 export declare function warnUnknownTopLevelKeys(raw: Record<string, unknown>, warnings: string[]): void;
 export declare function warnUnknownSafetyEnums(node: unknown, warnings: string[], where?: string): void;
 //# sourceMappingURL=validation.d.ts.map

package/dist/config/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/config/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAsB7D,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,aAiB/B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gBAAgB,aAU3B,CAAC;AAEH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAAE,GACjB,IAAI,CAQN;AAeD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAgB9F;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,KAAK,SAAK,GAAG,IAAI,CAqC1F"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/config/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAsB7D,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,aAoB/B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gBAAgB,aAU3B,CAAC;AAEH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAAE,GACjB,IAAI,CASN;AAyFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAAE,GACjB,IAAI,CAyDN;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,EAChC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAAE,GACjB,IAAI,CAkBN;AA6BD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAgB9F;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,KAAK,SAAK,GAAG,IAAI,CAqC1F"}