balladeer 1.0.7 → 1.0.11

package/dist/user-scope.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Install Balladeer once per laptop.
+ *
+ * Setup used to write two files into one repository checkout, uncommitted: an
+ * `.mcp.json` entry and a hook in `.claude/settings.json`. A coding host lists
+ * a project server only when that exact folder is open, so every other clone,
+ * every worktree and every teammate saw nothing, and `/mcp` on two laptops
+ * showed only the legacy server. This registers the same server and the same
+ * hook at the host's user scope instead: one entry that runs in every session,
+ * and decides at run time, from the folder's git remote, which connection it
+ * is for. Nothing to commit and nothing per folder.
+ *
+ * Every write here is an additive merge that refuses to touch an entry it does
+ * not own, exactly as the project writers do. What it owns is recognised by
+ * shape, never by trust in the name.
+ */
+export declare const USER_SCOPE_OWNER = "Balladeer current guidance (user scope, loader 1)";
+export type UserScopeHost = "claude" | "codex";
+export type UserScopeWrite = Readonly<{
+    host: UserScopeHost;
+    path: string;
+    status: "current" | "written" | "refused";
+    reason?: string;
+}>;
+/**
+ * The command a host runs to reach Balladeer, with no repository named: the
+ * directory decides.
+ *
+ * With a durable command installed, the entries name it by absolute path:
+ * no npx, so a session start costs node's startup and nothing else, and no
+ * PATH, so a host launched from the dock finds it. A laptop where the durable
+ * install was refused gets the `npx` form on the current major, which works
+ * everywhere and costs a registry lookup per session. The checkout form
+ * exists so this repository's own tests can point a host at source.
+ */
+export declare function userScopeCommand(published: boolean, installed?: string): {
+    command: string;
+    args: string[];
+};
+/** `~/.claude.json` carries the user-scope MCP list under `mcpServers`. */
+export declare function mergeClaudeUserMcp(home: string, published: boolean, installed?: string): UserScopeWrite;
+/** Ours when it runs `npx` on our published specifier, or `node` on this
+ * checkout's entry file, with `mcp` as the subcommand and no repository named:
+ * a repository argument at user scope would pin every folder to one connection. */
+export declare function isOurUserEntry(entry: unknown): boolean;
+/**
+ * Where `ensureInstalled` puts the durable command: Volta's shim directory, an
+ * npm global prefix's `bin` with the package beside it under `lib/node_modules`,
+ * or this product's own fallback prefix under the person's home.
+ */
+export declare function isInstalledCommandPath(command: string): boolean;
+/** `~/.claude/settings.json` carries user-scope hooks. */
+export declare function mergeClaudeUserHooks(home: string, published: boolean, installed?: string): UserScopeWrite;
+/** `~/.codex/config.toml` carries both the server and the hooks for Codex, in
+ * one fenced block this command owns end to end. */
+export declare function mergeCodexUserConfig(home: string, published: boolean, installed?: string): UserScopeWrite;
+/** A copy of this command running out of a source checkout registers the
+ * checkout; any installed or npx copy registers the published package. */
+export declare function runningFromCheckout(entry?: string): boolean;
+/** The home whose host files get the entries. `BALLADEER_USER_HOME` exists for
+ * this repository's own tests, which cannot move HOME under a Volta-managed
+ * Node without losing Node. */
+export declare function userHome(environment?: NodeJS.ProcessEnv): string;
+/** Register both hosts. Codex is skipped, not refused, on a laptop without it. */
+export declare function installUserScope(options: {
+    environment: NodeJS.ProcessEnv;
+    published: boolean;
+    home?: string;
+    /** The durable command's absolute path, when one is installed. */
+    installed?: string;
+}): UserScopeWrite[];

package/dist/user-scope.js

@@ -0,0 +1,267 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { parse } from "@iarna/toml";
+import { HOOK_SPECIFIER, checkoutEntryPath } from "./release.js";
+import { writeJsonAtomically } from "./mcp-config.js";
+/**
+ * Install Balladeer once per laptop.
+ *
+ * Setup used to write two files into one repository checkout, uncommitted: an
+ * `.mcp.json` entry and a hook in `.claude/settings.json`. A coding host lists
+ * a project server only when that exact folder is open, so every other clone,
+ * every worktree and every teammate saw nothing, and `/mcp` on two laptops
+ * showed only the legacy server. This registers the same server and the same
+ * hook at the host's user scope instead: one entry that runs in every session,
+ * and decides at run time, from the folder's git remote, which connection it
+ * is for. Nothing to commit and nothing per folder.
+ *
+ * Every write here is an additive merge that refuses to touch an entry it does
+ * not own, exactly as the project writers do. What it owns is recognised by
+ * shape, never by trust in the name.
+ */
+export const USER_SCOPE_OWNER = "Balladeer current guidance (user scope, loader 1)";
+const CLAUDE_EVENTS = ["SessionStart", "UserPromptSubmit", "SubagentStart"];
+/**
+ * The command a host runs to reach Balladeer, with no repository named: the
+ * directory decides.
+ *
+ * With a durable command installed, the entries name it by absolute path:
+ * no npx, so a session start costs node's startup and nothing else, and no
+ * PATH, so a host launched from the dock finds it. A laptop where the durable
+ * install was refused gets the `npx` form on the current major, which works
+ * everywhere and costs a registry lookup per session. The checkout form
+ * exists so this repository's own tests can point a host at source.
+ */
+export function userScopeCommand(published, installed) {
+    if (installed !== undefined)
+        return { command: installed, args: [] };
+    return published
+        ? { command: "npx", args: ["-y", HOOK_SPECIFIER] }
+        : { command: "node", args: [checkoutEntryPath()] };
+}
+function ordinaryFile(path) {
+    return !existsSync(path) || (lstatSync(path).isFile() && !lstatSync(path).isSymbolicLink());
+}
+/** `~/.claude.json` carries the user-scope MCP list under `mcpServers`. */
+export function mergeClaudeUserMcp(home, published, installed) {
+    const path = join(home, ".claude.json");
+    const host = "claude";
+    if (!ordinaryFile(path))
+        return { host, path, status: "refused", reason: "not an ordinary file" };
+    let root = {};
+    if (existsSync(path)) {
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                throw new Error();
+            root = parsed;
+        }
+        catch {
+            return { host, path, status: "refused", reason: "could not read valid JSON" };
+        }
+    }
+    const servers = root.mcpServers && typeof root.mcpServers === "object" && !Array.isArray(root.mcpServers)
+        ? root.mcpServers
+        : {};
+    const { command, args } = userScopeCommand(published, installed);
+    const expected = { type: "stdio", command, args: [...args, "mcp"] };
+    const current = servers.balladeer;
+    if (current !== undefined && !isOurUserEntry(current)) {
+        return {
+            host,
+            path,
+            status: "refused",
+            reason: "an entry named balladeer that is not Balladeer's is already there",
+        };
+    }
+    if (current !== undefined && JSON.stringify(current) === JSON.stringify(expected))
+        return { host, path, status: "current" };
+    root.mcpServers = { ...servers, balladeer: expected };
+    writeJsonAtomically(path, JSON.stringify(root, null, 2) + "\n");
+    return { host, path, status: "written" };
+}
+/** Ours when it runs `npx` on our published specifier, or `node` on this
+ * checkout's entry file, with `mcp` as the subcommand and no repository named:
+ * a repository argument at user scope would pin every folder to one connection. */
+export function isOurUserEntry(entry) {
+    if (!entry || typeof entry !== "object")
+        return false;
+    const record = entry;
+    if (!Array.isArray(record.args) || record.args.some((a) => typeof a !== "string"))
+        return false;
+    const args = record.args;
+    if (record.command === "npx")
+        return (args.length === 3 &&
+            args[0] === "-y" &&
+            /^balladeer@(?:latest|1|\d+\.\d+\.\d+)$/.test(args[1]) &&
+            args[2] === "mcp");
+    if (record.command === "node" || String(record.command).endsWith("/node"))
+        return args.length === 2 && args[0] === checkoutEntryPath() && args[1] === "mcp";
+    // The durable command by absolute path: ours when it sits where this
+    // product's installer puts it and is asked for `mcp` alone. The July client
+    // also registered an absolute `balladeer mcp`, from its own home, so the
+    // name is not enough; the place is what says whose it is.
+    if (typeof record.command === "string" && isAbsolute(record.command))
+        return isInstalledCommandPath(record.command) && args.length === 1 && args[0] === "mcp";
+    return false;
+}
+/**
+ * Where `ensureInstalled` puts the durable command: Volta's shim directory, an
+ * npm global prefix's `bin` with the package beside it under `lib/node_modules`,
+ * or this product's own fallback prefix under the person's home.
+ */
+export function isInstalledCommandPath(command) {
+    if (basename(command) !== "balladeer")
+        return false;
+    const normalized = command.replaceAll("\\", "/");
+    if (/\/\.volta\/bin\/balladeer$/.test(normalized))
+        return true;
+    if (/\/\.local\/share\/balladeer\/npm\/bin\/balladeer$/.test(normalized))
+        return true;
+    const bin = dirname(command);
+    return (basename(bin) === "bin" &&
+        existsSync(join(dirname(bin), "lib", "node_modules", "balladeer", "package.json")));
+}
+/** `~/.claude/settings.json` carries user-scope hooks. */
+export function mergeClaudeUserHooks(home, published, installed) {
+    const path = join(home, ".claude", "settings.json");
+    const host = "claude";
+    if (!ordinaryFile(path))
+        return { host, path, status: "refused", reason: "not an ordinary file" };
+    let root = {};
+    if (existsSync(path)) {
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                throw new Error();
+            root = parsed;
+        }
+        catch {
+            return { host, path, status: "refused", reason: "could not read valid JSON" };
+        }
+    }
+    const hooks = root.hooks && typeof root.hooks === "object" && !Array.isArray(root.hooks)
+        ? { ...root.hooks }
+        : {};
+    const { command, args } = userScopeCommand(published, installed);
+    const line = [command, ...args, "guidance", "--hook", "claude"].join(" ");
+    let changed = false;
+    for (const event of CLAUDE_EVENTS) {
+        const rows = hooks[event] === undefined ? [] : hooks[event];
+        if (!Array.isArray(rows))
+            return { host, path, status: "refused", reason: `hooks.${event} is not a list` };
+        const own = rows.filter((row) => row?.hooks?.some((h) => h.statusMessage === USER_SCOPE_OWNER));
+        const expected = {
+            hooks: [
+                {
+                    type: "command",
+                    command: `${line} --event ${event}`,
+                    // npx resolves from its cache in well under this; the first run on
+                    // a laptop that has never fetched the package needs the network.
+                    timeout: 10,
+                    statusMessage: USER_SCOPE_OWNER,
+                },
+            ],
+        };
+        if (own.length > 1)
+            return { host, path, status: "refused", reason: `two Balladeer hooks under ${event}` };
+        if (own.length === 1 && JSON.stringify(own[0]) === JSON.stringify(expected))
+            continue;
+        hooks[event] = [...rows.filter((row) => !own.includes(row)), expected];
+        changed = true;
+    }
+    if (!changed)
+        return { host, path, status: "current" };
+    root.hooks = hooks;
+    mkdirSync(dirname(path), { recursive: true });
+    writeJsonAtomically(path, JSON.stringify(root, null, 2) + "\n");
+    return { host, path, status: "written" };
+}
+const CODEX_START = "# balladeer:user:start";
+const CODEX_END = "# balladeer:user:end";
+/** `~/.codex/config.toml` carries both the server and the hooks for Codex, in
+ * one fenced block this command owns end to end. */
+export function mergeCodexUserConfig(home, published, installed) {
+    const path = join(home, ".codex", "config.toml");
+    const host = "codex";
+    if (!ordinaryFile(path))
+        return { host, path, status: "refused", reason: "not an ordinary file" };
+    let previous = "";
+    try {
+        if (existsSync(path))
+            previous = readFileSync(path, "utf8");
+        parse(previous);
+    }
+    catch {
+        return { host, path, status: "refused", reason: "could not read valid TOML" };
+    }
+    const { command, args } = userScopeCommand(published, installed);
+    const line = [command, ...args, "guidance", "--hook", "codex"].join(" ");
+    const block = [
+        CODEX_START,
+        "[mcp_servers.balladeer]",
+        `command = ${JSON.stringify(command)}`,
+        `args = ${JSON.stringify([...args, "mcp"])}`,
+        ...CLAUDE_EVENTS.flatMap((event) => [
+            `[[hooks.${event}]]`,
+            `[[hooks.${event}.hooks]]`,
+            'type = "command"',
+            `command = ${JSON.stringify(`${line} --event ${event}`)}`,
+            "timeout = 10",
+            "additionalContextLimit = 0",
+        ]),
+        CODEX_END,
+    ].join("\n");
+    const starts = [...previous.matchAll(/^# balladeer:user:start\r?$/gm)];
+    const ends = [...previous.matchAll(/^# balladeer:user:end\r?$/gm)];
+    if (starts.length !== ends.length || starts.length > 1)
+        return { host, path, status: "refused", reason: "the Balladeer block is malformed" };
+    if (starts[0] && ends[0]) {
+        if (starts[0].index >= ends[0].index)
+            return { host, path, status: "refused", reason: "the Balladeer block is malformed" };
+        const old = previous.slice(starts[0].index, ends[0].index + CODEX_END.length);
+        if (old === block)
+            return { host, path, status: "current" };
+        const after = previous.slice(0, starts[0].index) + block + previous.slice(ends[0].index + CODEX_END.length);
+        parse(after);
+        mkdirSync(dirname(path), { recursive: true });
+        writeJsonAtomically(path, after);
+        return { host, path, status: "written" };
+    }
+    if (/^\[mcp_servers\.balladeer\]/m.test(previous))
+        return {
+            host,
+            path,
+            status: "refused",
+            reason: "an mcp_servers.balladeer table that is not Balladeer's is already there",
+        };
+    const after = previous + (previous.endsWith("\n") || previous === "" ? "" : "\n") + block + "\n";
+    parse(after);
+    mkdirSync(dirname(path), { recursive: true });
+    writeJsonAtomically(path, after);
+    return { host, path, status: "written" };
+}
+/** A copy of this command running out of a source checkout registers the
+ * checkout; any installed or npx copy registers the published package. */
+export function runningFromCheckout(entry = process.argv[1] ?? "") {
+    const normalized = entry.replaceAll("\\", "/");
+    return normalized.includes("/packages/cli/dist/") && !normalized.includes("/node_modules/");
+}
+/** The home whose host files get the entries. `BALLADEER_USER_HOME` exists for
+ * this repository's own tests, which cannot move HOME under a Volta-managed
+ * Node without losing Node. */
+export function userHome(environment = process.env) {
+    return resolve(environment.BALLADEER_USER_HOME?.trim() || environment.HOME?.trim() || homedir());
+}
+/** Register both hosts. Codex is skipped, not refused, on a laptop without it. */
+export function installUserScope(options) {
+    const home = options.home ?? userHome(options.environment);
+    const writes = [
+        mergeClaudeUserMcp(home, options.published, options.installed),
+        mergeClaudeUserHooks(home, options.published, options.installed),
+    ];
+    if (existsSync(join(home, ".codex")))
+        writes.push(mergeCodexUserConfig(home, options.published, options.installed));
+    return writes;
+}

package/dist/wire.d.ts

@@ -5,10 +5,10 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export declare const CLI_VERSION = "1.0.7";
+export declare const CLI_VERSION = "1.0.11";
 export declare const CLI_INVOCATION = "npx -y balladeer@latest";
 export declare const CLIENT_HEADER = "x-balladeer-client";
-export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.7";
+export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.11";
 export declare const DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
 export type DelegatedScope = "repository:enroll" | "agent:issue" | "ci:connect" | "workspace:invite" | "candidate:propose";
 export declare const DELEGATED_SCOPES: readonly DelegatedScope[];
@@ -222,6 +222,19 @@ export type ClaudeDesktopStep = Readonly<{
     reason?: string;
 }>;
 export type JsonStep = Readonly<{
+    /** The earlier Balladeer found on this machine and what setup did about it. */
+    step: "earlier";
+    removed: readonly {
+        path: string;
+        found: string;
+        backup?: string;
+    }[];
+    failed: readonly {
+        path: string;
+        found: string;
+        reason: string;
+    }[];
+}> | Readonly<{
     step: "guidance_loader";
     status: "installed_needs_host_trust" | "installed_trust_unverified" | "unavailable" | "not_applicable";
     changed: boolean;

package/dist/wire.js

@@ -5,7 +5,7 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export const CLI_VERSION = "1.0.7";
+export const CLI_VERSION = "1.0.11";
 export const CLI_INVOCATION = "npx -y balladeer@latest";
 export const CLIENT_HEADER = "x-balladeer-client";
 export const CLIENT_HEADER_VALUE = `balladeer/${CLI_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "balladeer",
-  "version": "1.0.7",
+  "version": "1.0.11",
   "description": "Set up Balladeer from your terminal, or from a coding agent's.",
   "license": "Apache-2.0",
   "private": false,
@@ -22,7 +22,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && node build-guidance.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "pnpm --dir ../.. compat:release"
   },
   "devDependencies": {
     "typescript": "5.9.3",