balladeer 1.0.8 → 1.0.11

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,19 +22,29 @@ 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());
 }
 /** `~/.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 (!ordinaryFile(path))
@@ -54,7 +64,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,14 +94,37 @@ 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");
     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) {
+export function mergeClaudeUserHooks(home, published, installed) {
     const path = join(home, ".claude", "settings.json");
     const host = "claude";
     if (!ordinaryFile(path))
@@ -111,7 +144,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 +182,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 +196,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 +258,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.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.8";
+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.8";
+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.8",
+  "version": "1.0.11",
   "description": "Set up Balladeer from your terminal, or from a coding agent's.",
   "license": "Apache-2.0",
   "private": false,