balladeer 1.0.8 → 1.0.12

package/dist/user-scope.js

@@ -1,8 +1,8 @@
 import { existsSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { parse } from "@iarna/toml";
-import { PUBLISHED_SPECIFIER, checkoutEntryPath } from "./release.js";
+import { HOOK_SPECIFIER, checkoutEntryPath } from "./release.js";
 import { writeJsonAtomically } from "./mcp-config.js";
 /**
  * Install Balladeer once per laptop.
@@ -22,21 +22,43 @@ import { writeJsonAtomically } from "./mcp-config.js";
  */
 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. The published form is what a laptop gets; the checkout
- * form exists so this repository's own tests can point a host at source. */
-export function userScopeCommand(published) {
+/**
+ * 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", PUBLISHED_SPECIFIER] }
+        ? { command: "npx", args: ["-y", HOOK_SPECIFIER] }
         : { command: "node", args: [checkoutEntryPath()] };
 }
 function ordinaryFile(path) {
     return !existsSync(path) || (lstatSync(path).isFile() && !lstatSync(path).isSymbolicLink());
 }
+/** The home the entries go under has to exist; a home that does not is a
+ * refusal in a sentence, never a stack trace. */
+function homeExists(home) {
+    try {
+        return lstatSync(home).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 /** `~/.claude.json` carries the user-scope MCP list under `mcpServers`. */
-export function mergeClaudeUserMcp(home, published) {
+export function mergeClaudeUserMcp(home, published, installed) {
     const path = join(home, ".claude.json");
     const host = "claude";
+    if (!homeExists(home))
+        return { host, path, status: "refused", reason: "home directory missing" };
     if (!ordinaryFile(path))
         return { host, path, status: "refused", reason: "not an ordinary file" };
     let root = {};
@@ -54,7 +76,7 @@ export function mergeClaudeUserMcp(home, published) {
     const servers = root.mcpServers && typeof root.mcpServers === "object" && !Array.isArray(root.mcpServers)
         ? root.mcpServers
         : {};
-    const { command, args } = userScopeCommand(published);
+    const { command, args } = userScopeCommand(published, installed);
     const expected = { type: "stdio", command, args: [...args, "mcp"] };
     const current = servers.balladeer;
     if (current !== undefined && !isOurUserEntry(current)) {
@@ -84,16 +106,48 @@ export function isOurUserEntry(entry) {
     if (record.command === "npx")
         return (args.length === 3 &&
             args[0] === "-y" &&
-            /^balladeer@(?:latest|\d+\.\d+\.\d+)$/.test(args[1]) &&
+            /^balladeer@(?:latest|1|\d+\.\d+\.\d+)$/.test(args[1]) &&
             args[2] === "mcp");
+    // A checkout of this repository at any path: the entry setup writes when it
+    // runs from source, on this laptop or another. Ours to replace, never to
+    // refuse; refusing it once left a developer's laptop with no entry at all.
     if (record.command === "node" || String(record.command).endsWith("/node"))
-        return args.length === 2 && args[0] === checkoutEntryPath() && args[1] === "mcp";
+        return (args.length === 2 &&
+            typeof args[0] === "string" &&
+            isAbsolute(args[0]) &&
+            /[\\/]packages[\\/]cli[\\/]dist[\\/]cli\.js$/.test(args[0]) &&
+            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) {
+export function mergeClaudeUserHooks(home, published, installed) {
     const path = join(home, ".claude", "settings.json");
     const host = "claude";
+    if (!homeExists(home))
+        return { host, path, status: "refused", reason: "home directory missing" };
     if (!ordinaryFile(path))
         return { host, path, status: "refused", reason: "not an ordinary file" };
     let root = {};
@@ -111,7 +165,7 @@ export function mergeClaudeUserHooks(home, published) {
     const hooks = root.hooks && typeof root.hooks === "object" && !Array.isArray(root.hooks)
         ? { ...root.hooks }
         : {};
-    const { command, args } = userScopeCommand(published);
+    const { command, args } = userScopeCommand(published, installed);
     const line = [command, ...args, "guidance", "--hook", "claude"].join(" ");
     let changed = false;
     for (const event of CLAUDE_EVENTS) {
@@ -149,7 +203,7 @@ 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) {
+export function mergeCodexUserConfig(home, published, installed) {
     const path = join(home, ".codex", "config.toml");
     const host = "codex";
     if (!ordinaryFile(path))
@@ -163,7 +217,7 @@ export function mergeCodexUserConfig(home, published) {
     catch {
         return { host, path, status: "refused", reason: "could not read valid TOML" };
     }
-    const { command, args } = userScopeCommand(published);
+    const { command, args } = userScopeCommand(published, installed);
     const line = [command, ...args, "guidance", "--hook", "codex"].join(" ");
     const block = [
         CODEX_START,
@@ -225,10 +279,10 @@ export function userHome(environment = process.env) {
 export function installUserScope(options) {
     const home = options.home ?? userHome(options.environment);
     const writes = [
-        mergeClaudeUserMcp(home, options.published),
-        mergeClaudeUserHooks(home, options.published),
+        mergeClaudeUserMcp(home, options.published, options.installed),
+        mergeClaudeUserHooks(home, options.published, options.installed),
     ];
     if (existsSync(join(home, ".codex")))
-        writes.push(mergeCodexUserConfig(home, options.published));
+        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.8";
+export declare const CLI_VERSION = "1.0.12";
 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.8";
+export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.12";
 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;
@@ -332,7 +345,7 @@ export type JsonStep = Readonly<{
     reason?: string;
 }> | Readonly<{
     step: "warning";
-    code: "enforcement_unavailable";
+    code: "enforcement_unavailable" | "not_in_checkout";
     message: string;
 }> | Readonly<{
     step: "promise";

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.8";
+export const CLI_VERSION = "1.0.12";
 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.8",
+  "version": "1.0.12",
   "description": "Set up Balladeer from your terminal, or from a coding agent's.",
   "license": "Apache-2.0",
   "private": false,

package/dist/legacy.d.ts

@@ -1,41 +0,0 @@
-/**
- * The earlier Balladeer, still installed, found before this one writes anything.
- *
- * A team that used the July client has a program on their machine that this one
- * knows nothing about: it updates itself from its own server rather than from
- * npm, it registers an MCP server named `balladeer` for the whole machine, and
- * it installs a session hook and a conventions block of its own. This product
- * registers an MCP server under the same name, per repository. Nothing breaks
- * loudly when both are present, which is the problem: the older session hook
- * keeps firing inside the repository somebody enrolled today, one file ends up
- * carrying two conventions blocks, and the person reads the result as this
- * product misbehaving.
- *
- * The older client can take itself off, reversibly, with `balladeer uninstall`
- * followed by the removal command it prints. So this is a warning that stops
- * rather than a refusal that stands: the sentence names the one thing to do,
- * and `--force` is there for whoever has decided to run both anyway.
- */
-export type LegacyInstall = Readonly<{
-    /** Which file said so, in the form a person can go and open. */
-    where: string;
-    /** What was found there, bounded, so a config file cannot become an essay. */
-    detail: string;
-}>;
-/**
- * The instruction, in the same words `docs/didero-day-one.md` and
- * `docs/didero-mcp-walkthrough.md` print. A person who hits this in the terminal
- * and a person who read the document ahead of time are told to do the same
- * thing, by the same sentence.
- */
-export declare const UNINSTALL_INSTRUCTION = "If you used the earlier Balladeer on this machine: run `balladeer uninstall`, then the removal command it prints, then continue.";
-/**
- * The older install this machine still carries, or nothing.
- *
- * Two places, because those are the two the older client owns that reach into a
- * session in a repository enrolled today: the machine-wide MCP entry under our
- * own name, and the hook that fires at session start.
- */
-export declare function findLegacyInstall(environment: NodeJS.ProcessEnv, controlPlane: string): LegacyInstall | undefined;
-/** What the person reads, whichever of the two files said so. */
-export declare function legacyMessage(found: LegacyInstall): string;

package/dist/legacy.js

@@ -1,143 +0,0 @@
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import { isOurEntry } from "./mcp-config.js";
-/**
- * The instruction, in the same words `docs/didero-day-one.md` and
- * `docs/didero-mcp-walkthrough.md` print. A person who hits this in the terminal
- * and a person who read the document ahead of time are told to do the same
- * thing, by the same sentence.
- */
-export const UNINSTALL_INSTRUCTION = "If you used the earlier Balladeer on this machine: run `balladeer uninstall`, then the removal command it prints, then continue.";
-/** How much of a foreign command line is worth printing back. */
-const DETAIL_LIMIT = 120;
-/**
- * Where the agent host keeps its configuration, read from the environment this
- * command was handed and never from the ambient process.
- *
- * Every command in this package takes its configuration as a parameter, which is
- * what lets a test plant a whole home directory. When the environment names no
- * home there is nothing to read, and a check that cannot read cannot warn: it
- * stays silent rather than guessing at a path.
- */
-function agentHome(environment) {
-    const home = environment.HOME?.trim() || environment.USERPROFILE?.trim() || "";
-    return home.length > 0 ? home : undefined;
-}
-function readJson(path) {
-    try {
-        return JSON.parse(readFileSync(path, "utf8"));
-    }
-    catch {
-        // Absent, unreadable, or somebody's hand-edited file mid-save. None of those
-        // is evidence of an older install, and none of them is this command's to fix.
-        return undefined;
-    }
-}
-function bounded(text) {
-    const flattened = text.replace(/\s+/g, " ").trim();
-    return flattened.length > DETAIL_LIMIT ? `${flattened.slice(0, DETAIL_LIMIT)}...` : flattened;
-}
-/** The command line an MCP entry runs, in the shape a person would recognise. */
-function describeEntry(entry) {
-    const record = entry;
-    if (record !== null && typeof record?.url === "string")
-        return bounded(record.url);
-    const command = typeof record?.command === "string" ? record.command : "";
-    const args = Array.isArray(record?.args)
-        ? record.args.filter((value) => typeof value === "string")
-        : [];
-    const line = [command, ...args].join(" ").trim();
-    return line.length > 0 ? bounded(line) : "a command this copy does not recognise";
-}
-/**
- * Whether a hook's command line is one of ours.
- *
- * This product installs no agent-host hook at all, so in practice every hook
- * naming `balladeer` belongs to the older client. The exception is written down
- * anyway: a team that wired one of our own published or checkout invocations
- * into a hook of their own must not be told their own line is somebody else's
- * program.
- */
-function isOurCommandLine(command) {
-    if (/balladeer@(?:latest|\d+\.\d+\.\d+)\b/.test(command))
-        return true;
-    return /\bnode\b[^\n]*\bpackages[/\\]cli[/\\]dist[/\\]cli\.js\b/.test(command);
-}
-/** Every `command` string anywhere under an agent host's `hooks` setting. */
-function hookCommands(value, found = []) {
-    if (Array.isArray(value)) {
-        for (const item of value)
-            hookCommands(item, found);
-        return found;
-    }
-    if (value === null || typeof value !== "object")
-        return found;
-    for (const [key, child] of Object.entries(value)) {
-        if (key === "command" && typeof child === "string")
-            found.push(child);
-        else
-            hookCommands(child, found);
-    }
-    return found;
-}
-/**
- * The older Balladeer's own MCP entry, if the agent host still carries one.
- *
- * Only the machine-wide block counts. This product writes its entry into the
- * repository's `.mcp.json`, and a host that also records a per-project entry
- * under `projects` records ours there: reading those as foreign would stop
- * setup on the very install it just performed. Under the machine-wide key, an
- * entry named `balladeer` that is not one of our recognised shapes is the older
- * client, because nothing else has reason to claim that name.
- */
-function legacyMcpEntry(home, controlPlane) {
-    const parsed = readJson(join(home, ".claude.json"));
-    const servers = parsed?.mcpServers;
-    if (servers === null || typeof servers !== "object")
-        return undefined;
-    const entry = servers.balladeer;
-    if (entry === undefined || entry === null)
-        return undefined;
-    if (isOurEntry(entry, controlPlane))
-        return undefined;
-    return {
-        where: join(home, ".claude.json"),
-        detail: `an MCP server named balladeer, registered for the whole machine, running ${describeEntry(entry)}`,
-    };
-}
-/** The older Balladeer's session hook, if the agent host still runs one. */
-function legacyHook(home) {
-    const parsed = readJson(join(home, ".claude", "settings.json"));
-    const hooks = parsed?.hooks;
-    if (hooks === undefined)
-        return undefined;
-    const command = hookCommands(hooks).find((line) => /balladeer/i.test(line) && !isOurCommandLine(line));
-    if (command === undefined)
-        return undefined;
-    return {
-        where: join(home, ".claude", "settings.json"),
-        detail: `a hook that runs ${bounded(command)}`,
-    };
-}
-/**
- * The older install this machine still carries, or nothing.
- *
- * Two places, because those are the two the older client owns that reach into a
- * session in a repository enrolled today: the machine-wide MCP entry under our
- * own name, and the hook that fires at session start.
- */
-export function findLegacyInstall(environment, controlPlane) {
-    const home = agentHome(environment);
-    if (home === undefined)
-        return undefined;
-    return legacyMcpEntry(home, controlPlane) ?? legacyHook(home);
-}
-/** What the person reads, whichever of the two files said so. */
-export function legacyMessage(found) {
-    return [
-        `An earlier Balladeer is still installed on this machine: ${found.where} carries ${found.detail}.`,
-        "Both products register an MCP server named balladeer and the earlier one keeps firing its own session hook, so leaving it in place puts two Balladeers in the sessions you open in this repository.",
-        UNINSTALL_INSTRUCTION,
-        "Nothing was changed. Run this command again with --force to set up anyway.",
-    ].join("\n");
-}

package/dist/quiet.d.ts

@@ -1,25 +0,0 @@
-/**
- * Where a person said "not here".
- *
- * With Balladeer registered once per laptop, every session in every folder
- * asks whether this folder is tracked. In one that is not, the hook says so
- * once and names the command that would track it; a person who does not want
- * to hear that again in a scratch clone silences the folder, and one who does
- * not want it for a whole product silences the remote. The default is the
- * folder, because "not here" usually means this checkout and not the repository.
- */
-export type QuietList = Readonly<{
-    schemaVersion: 1;
-    folders: string[];
-    remotes: string[];
-}>;
-export declare function quietPath(environment?: NodeJS.ProcessEnv): string;
-export declare function readQuiet(environment?: NodeJS.ProcessEnv): QuietList;
-/** The folder a session is in, as git names it, so a worktree and a clone are
- * each their own folder while the remote stays one thing. */
-export declare function folderKey(cwd: string): string;
-export declare function isQuiet(cwd: string, environment?: NodeJS.ProcessEnv): boolean;
-export declare function setQuiet(cwd: string, scope: "folder" | "repo", quiet: boolean, environment?: NodeJS.ProcessEnv): {
-    key: string;
-    changed: boolean;
-};

package/dist/quiet.js

@@ -1,73 +0,0 @@
-import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
-import { join } from "node:path";
-import { writeJsonAtomically } from "./mcp-config.js";
-import { repositoryHint } from "./repository.js";
-import { configHome } from "./store.js";
-const EMPTY = { schemaVersion: 1, folders: [], remotes: [] };
-export function quietPath(environment = process.env) {
-    return join(configHome(environment), "quiet.json");
-}
-export function readQuiet(environment = process.env) {
-    const path = quietPath(environment);
-    if (!existsSync(path))
-        return EMPTY;
-    try {
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
-        if (parsed.schemaVersion !== 1)
-            return EMPTY;
-        return {
-            schemaVersion: 1,
-            folders: Array.isArray(parsed.folders) ? parsed.folders.filter(isString) : [],
-            remotes: Array.isArray(parsed.remotes) ? parsed.remotes.filter(isString) : [],
-        };
-    }
-    catch {
-        return EMPTY;
-    }
-}
-const isString = (value) => typeof value === "string";
-function writeQuiet(list, environment) {
-    mkdirSync(configHome(environment), { recursive: true, mode: 0o700 });
-    writeJsonAtomically(quietPath(environment), JSON.stringify(list, null, 2) + "\n");
-}
-/** The folder a session is in, as git names it, so a worktree and a clone are
- * each their own folder while the remote stays one thing. */
-export function folderKey(cwd) {
-    try {
-        return realpathSync(execFileSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-            timeout: 1000,
-        }).trim());
-    }
-    catch {
-        return realpathSync(cwd);
-    }
-}
-export function isQuiet(cwd, environment = process.env) {
-    const list = readQuiet(environment);
-    const folder = folderKey(cwd);
-    const remote = repositoryHint(cwd);
-    return (list.folders.includes(folder) ||
-        (remote !== "unknown/unknown" &&
-            list.remotes.some((r) => r.toLowerCase() === remote.toLowerCase())));
-}
-export function setQuiet(cwd, scope, quiet, environment = process.env) {
-    const list = readQuiet(environment);
-    const key = scope === "folder" ? folderKey(cwd) : repositoryHint(cwd);
-    if (scope === "repo" && key === "unknown/unknown")
-        throw new Error("This folder has no GitHub origin remote, so there is no repository to name.");
-    const field = scope === "folder" ? "folders" : "remotes";
-    const has = list[field].some((x) => x.toLowerCase() === key.toLowerCase());
-    if (has === quiet)
-        return { key, changed: false };
-    const next = {
-        ...list,
-        [field]: quiet
-            ? [...list[field], key]
-            : list[field].filter((x) => x.toLowerCase() !== key.toLowerCase()),
-    };
-    writeQuiet(next, environment);
-    return { key, changed: true };
-}