balladeer 1.0.7 → 1.0.11

package/dist/commands/setup.js

@@ -12,10 +12,12 @@ import { MCP_CONFIG_FILE, currentEntry, entryRepositoryId, isOurEntry, mergeMcpC
 import { DESKTOP_CONFIG_FILE, desktopConfigLocation, desktopServerKey, desktopStdioEntry, mergeDesktopConfig, } from "../desktop-config.js";
 import { selectAgent } from "../agent.js";
 import { installGuidanceLoader } from "../guidance-install.js";
-import { findLegacyInstall, legacyMessage } from "../legacy.js";
+import { openInBrowser } from "../open-browser.js";
+import { describeEarlier, describeRemoval, findEarlier, removeEarlier } from "../remove-earlier.js";
+import { userHome } from "../user-scope.js";
 import { formatInstant } from "../local-time.js";
 import { checkoutEntryPath, commandLine, runningFromRegistryInstall } from "../release.js";
-import { hostHint, repositoryHint } from "../repository.js";
+import { hostHint, repositoryHint, repositoryHints } from "../repository.js";
 import { StoreError, assertStoreWritable, credentialsPath, dropPendingPairing, findPendingPairing, findSession, putAgent, putPendingPairing, putSession, readCredentials, writeCredentials, } from "../store.js";
 import { CLI_VERSION, DELEGATED_SCOPES, } from "../wire.js";
 import { explainText } from "./explain.js";
@@ -143,13 +145,15 @@ function pairedLines(session) {
  * scrolled, or an agent whose context was compacted, is told to approve in the
  * browser, and no other command in this release can produce that URL again.
  */
-function pendingLines(pending, repository, host, waiting, approvalUri) {
+function pendingLines(pending, repository, host, waiting, approvalUri, opened) {
     const opening = waiting
         ? ["Step 1 of 5  Waiting for approval", `  Nobody has approved ${pending.userCode} yet.`]
         : ["Step 1 of 5  Sign in and approve this session"];
     return [
         ...opening,
-        `  Open: ${approvalUri}`,
+        opened
+            ? `  Opened in your browser: ${approvalUri}  (if no page appeared, open that link yourself)`
+            : `  Open: ${approvalUri}`,
         `  The page will show this code: ${pending.userCode}`,
         // A person who belongs to two workspaces approves into whichever one their
         // browser is signed into, and twice that was not the one they meant: the
@@ -159,7 +163,9 @@ function pendingLines(pending, repository, host, waiting, approvalUri) {
         `  ${APPROVE_IN_THE_RIGHT_WORKSPACE}`,
         `  Sent to Balladeer so far: a random code, the name "${repository}", and the hostname "${host}". Nothing else.`,
         `  This pairing expires at ${formatInstant(pending.expiresAt)}.`,
-        "  Approve in the browser, then run this command again to finish.",
+        opened
+            ? "  Approve in the browser; this command waits here and finishes on its own."
+            : "  Approve in the browser, then run this command again to finish.",
         "",
         // Printed on the pairing step and nowhere else, because this is the one
         // moment the answer matters: the person is standing in front of a page that
@@ -259,11 +265,29 @@ export async function runSetup(options) {
     // that still carries the July client gets one instruction and this run stops.
     // Refresh is inside the check rather than outside it, because a repair writes
     // the same two files a first setup writes.
-    const legacy = options.force === true
-        ? undefined
-        : findLegacyInstall(options.environment, options.controlPlane);
-    if (legacy !== undefined) {
-        return fail(options, "legacy_balladeer_present", legacyMessage(legacy), 6);
+    // The earlier Balladeer, still on this machine, is taken off first: both
+    // products answer to the name `balladeer`, and while the older entry stands
+    // the host shows its server and refuses ours. Every file changed is copied
+    // beside itself first and the copies are named. `--force` sets up alongside
+    // it instead, for whoever has decided to run both.
+    if (options.force !== true) {
+        const earlier = findEarlier({
+            home: userHome(options.environment),
+            controlPlane: options.controlPlane,
+            environment: options.environment,
+            cwd: options.cwd,
+        });
+        if (earlier.length > 0) {
+            say(options, "An earlier Balladeer is on this machine:");
+            for (const line of describeEarlier(earlier))
+                say(options, line);
+            const report = removeEarlier(earlier);
+            for (const line of describeRemoval(report))
+                say(options, line);
+            emit(options, { step: "earlier", removed: report.removed, failed: report.failed });
+            if (report.failed.length > 0)
+                return fail(options, "earlier_balladeer_remains", `${report.failed.length} of the earlier Balladeer's entries could not be removed; see above. Fix those by hand, or run this command again with --force to set up alongside it.`, 6);
+        }
     }
     if (options.refresh === true)
         return runRefresh(options);
@@ -371,7 +395,8 @@ export async function runSetup(options) {
             return outcome.exitCode;
         // Printed before the wait as well as instead of it: a run that blocks for ten
         // minutes without ever naming the link is the run whose person cannot act.
-        for (const line of pendingLines(pending, repository, host, true, approvalLink(options, pending.verificationUri)))
+        const opened = openForPerson(options, approvalLink(options, pending.verificationUri));
+        for (const line of pendingLines(pending, repository, host, true, approvalLink(options, pending.verificationUri), opened))
             say(options, line);
         emit(options, {
             step: "pair",
@@ -380,7 +405,7 @@ export async function runSetup(options) {
             verificationUri: approvalLink(options, pending.verificationUri),
             expiresAt: pending.expiresAt,
         });
-        if (!options.wait) {
+        if (!options.wait && !opened) {
             pairingOnlyReceipt(options, "Nothing yet: this pairing is still waiting for someone to approve it.");
             return 0;
         }
@@ -422,7 +447,8 @@ export async function runSetup(options) {
             expiresAt: lapsed.expiresAt,
         });
     }
-    for (const line of pendingLines(pending, repository, host, false, approvalLink(options, pending.verificationUri)))
+    const opened = openForPerson(options, approvalLink(options, pending.verificationUri));
+    for (const line of pendingLines(pending, repository, host, false, approvalLink(options, pending.verificationUri), opened))
         say(options, line);
     emit(options, {
         step: "pair",
@@ -431,7 +457,7 @@ export async function runSetup(options) {
         verificationUri: approvalLink(options, pending.verificationUri),
         expiresAt: pending.expiresAt,
     });
-    if (options.wait) {
+    if (options.wait || opened) {
         return waitForApproval(options, credentials, pending, started.pollIntervalSeconds);
     }
     pairingOnlyReceipt(options, "Started a pairing and printed the link. Nobody has approved it yet.");
@@ -564,6 +590,16 @@ function terminalRefusal(pending, code) {
     }
     return undefined;
 }
+/**
+ * The link, opened for a person at the terminal and for nobody else. Whether a
+ * browser appeared is not known here; the line beside the link says what to do
+ * if none did.
+ */
+export function openForPerson(options, url) {
+    if (options.interactive !== true || options.json)
+        return false;
+    return (options.openLink ?? openInBrowser)(url);
+}
 async function waitForApproval(options, credentials, pending, pollIntervalSeconds) {
     const sleep = options.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
     const now = options.now ?? (() => new Date());
@@ -1676,7 +1712,7 @@ async function runRefresh(input) {
     let storedName;
     try {
         const credentials = readCredentials(options.environment);
-        const selection = selectAgent(credentials.agents, options.controlPlane, undefined, repositoryHint(options.cwd));
+        const selection = selectAgent(credentials.agents, options.controlPlane, undefined, repositoryHints(options.cwd));
         if (selection.kind === "agent") {
             stored = selection.agent.repositoryId;
             storedName = selection.agent.repository;

package/dist/commands/status.js

@@ -4,7 +4,7 @@ import { repositoryRoot } from "../git.js";
 import { MARKER_OBSERVATION_LIMITS, observeMissingMarkers, staleMarkerRow, } from "../markers.js";
 import { formatInstant } from "../local-time.js";
 import { commandLine } from "../release.js";
-import { repositoryHint } from "../repository.js";
+import { repositoryHint, repositoryHints } from "../repository.js";
 import { SEALED_PATHS_SHOWN, sealedPromises } from "../seals.js";
 import { StoreError, findSession, readCredentials } from "../store.js";
 import { CLI_INVOCATION } from "../wire.js";
@@ -103,7 +103,7 @@ async function reportBalladeer(options) {
         return fail(error instanceof StoreError ? error.code : "credential_store_unusable", error instanceof StoreError ? error.message : String(error), 4);
     }
     const here = options.repo ?? repositoryHint(options.cwd);
-    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, here);
+    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, options.repo ?? repositoryHints(options.cwd));
     const storedSession = findSession(credentials, options.controlPlane);
     const repositoryScoped = options.repo !== undefined ||
         options.repository !== undefined ||

package/dist/currency.d.ts

@@ -27,5 +27,8 @@ export declare const CLI_ADVICE_HEADER = "x-balladeer-cli-advice";
 export declare function noteServerVersion(headers: Headers): void;
 /** The one line this run prints about itself, or nothing when it is current. */
 export declare function updateNotice(): string | undefined;
+/** The newer version the server named, when it named one; nothing when this
+ * copy is current or no server has answered yet. */
+export declare function newerVersionPublished(): string | undefined;
 /** For tests, and for a process that runs more than one command. */
 export declare function resetUpdateNotice(): void;

package/dist/currency.js

@@ -24,6 +24,7 @@ export const CLI_ADVICE_HEADER = "x-balladeer-cli-advice";
 const ADVICE_LIMIT = 300;
 const VERSION = /^\d{1,4}\.\d{1,4}\.\d{1,4}$/;
 let notice;
+let newestSeen;
 function older(left, right) {
     const [a, b] = [left.split(".").map(Number), right.split(".").map(Number)];
     for (let index = 0; index < 3; index += 1) {
@@ -55,6 +56,7 @@ export function noteServerVersion(headers) {
         return;
     if (!older(CLI_VERSION, newest))
         return;
+    newestSeen = newest;
     const advice = headers.get(CLI_ADVICE_HEADER);
     const line = advice === null ? "" : bounded(advice);
     notice =
@@ -66,7 +68,13 @@ export function noteServerVersion(headers) {
 export function updateNotice() {
     return notice;
 }
+/** The newer version the server named, when it named one; nothing when this
+ * copy is current or no server has answered yet. */
+export function newerVersionPublished() {
+    return newestSeen;
+}
 /** For tests, and for a process that runs more than one command. */
 export function resetUpdateNotice() {
     notice = undefined;
+    newestSeen = undefined;
 }

package/dist/guidance-hook.mjs

@@ -2027,7 +2027,7 @@ var require_toml = __commonJS({
 });
 
 // src/wire.ts
-var CLI_VERSION = "1.0.7";
+var CLI_VERSION = "1.0.11";
 var CLIENT_HEADER = "x-balladeer-client";
 var CLIENT_HEADER_VALUE = `balladeer/${CLI_VERSION}`;
 var DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
@@ -2119,6 +2119,37 @@ function readCredentials(environment = process.env) {
   }
 }
 
+// src/currency.ts
+var CLI_NEWEST_HEADER = "x-balladeer-cli-newest";
+var CLI_ADVICE_HEADER = "x-balladeer-cli-advice";
+var ADVICE_LIMIT = 300;
+var VERSION = /^\d{1,4}\.\d{1,4}\.\d{1,4}$/;
+var notice;
+var newestSeen;
+function older(left, right) {
+  const [a, b] = [left.split(".").map(Number), right.split(".").map(Number)];
+  for (let index = 0; index < 3; index += 1) {
+    const difference = a[index] - b[index];
+    if (difference !== 0) return difference < 0;
+  }
+  return false;
+}
+function bounded(value) {
+  return value.replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, ADVICE_LIMIT);
+}
+function noteServerVersion(headers) {
+  const newest = headers.get(CLI_NEWEST_HEADER)?.trim();
+  if (newest === void 0 || !VERSION.test(newest)) return;
+  if (!older(CLI_VERSION, newest)) return;
+  newestSeen = newest;
+  const advice = headers.get(CLI_ADVICE_HEADER);
+  const line = advice === null ? "" : bounded(advice);
+  notice = line === "" ? `A newer Balladeer is available (${newest}; this is ${CLI_VERSION}). Run npx -y balladeer@latest setup --refresh to update the command and instructions, then restart this session.` : line;
+}
+function newerVersionPublished() {
+  return newestSeen;
+}
+
 // src/guidance.ts
 import { createHash, randomBytes } from "node:crypto";
 import {
@@ -2275,6 +2306,7 @@ async function loadGuidance(input) {
           ...previous ? { "if-none-match": previous.etag } : {}
         }
       });
+      noteServerVersion(response.headers);
       if (response.status === 304) {
         if (!previous || response.headers.get("etag") !== previous.etag || response.headers.get("x-balladeer-guidance-revision") !== previous.document.revision) {
           throw new Error("invalid_guidance_revalidation");
@@ -2411,6 +2443,11 @@ import {
   writeSync as writeSync2
 } from "node:fs";
 import { basename, dirname as dirname2, isAbsolute, join as join3 } from "node:path";
+
+// src/release.ts
+var HOOK_SPECIFIER = "balladeer@1";
+
+// src/mcp-config.ts
 var MCP_CONFIG_FILE = ".mcp.json";
 function sameOrigin(left, right) {
   try {
@@ -2865,6 +2902,145 @@ function validateProjectGuidanceScope(options) {
   }
 }
 
+// src/agent.ts
+var REPOSITORY_NAME = /^[A-Za-z0-9._-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
+function selectAgent(agents, controlPlane, repositoryId, currentRepository) {
+  const here = agents.filter((agent) => agent.controlPlane === controlPlane);
+  if (typeof currentRepository !== "string") {
+    const candidates = currentRepository.filter(
+      (name) => REPOSITORY_NAME.test(name) && name !== "unknown/unknown"
+    );
+    for (const name of candidates) {
+      const found = selectAgent(agents, controlPlane, repositoryId, name);
+      if (found.kind !== "refused") return found;
+    }
+    return selectAgent(agents, controlPlane, repositoryId, candidates[0] ?? "unknown/unknown");
+  }
+  if (repositoryId !== void 0) {
+    const named = here.find(
+      (agent) => agent.repositoryId === repositoryId || agent.repository?.toLowerCase() === repositoryId.toLowerCase()
+    );
+    if (named === void 0) {
+      return {
+        kind: "refused",
+        reason: `No Balladeer connection for repository ${repositoryId} is stored for ${controlPlane}.`,
+        missingFor: repositoryId
+      };
+    }
+    return withSafeEndpoint(named);
+  }
+  if (!REPOSITORY_NAME.test(currentRepository) || currentRepository === "unknown/unknown") {
+    return {
+      kind: "refused",
+      reason: "This directory has no GitHub origin remote I could read, so I cannot tell which repository's Balladeer connection to use. Pass --repository <id>."
+    };
+  }
+  const matches = here.filter(
+    (agent) => agent.repository?.toLowerCase() === currentRepository.toLowerCase()
+  );
+  const chosen = matches[matches.length - 1];
+  if (chosen === void 0) {
+    return {
+      kind: "refused",
+      reason: `No Balladeer connection for ${currentRepository} is stored for ${controlPlane}.`,
+      missingFor: currentRepository
+    };
+  }
+  return withSafeEndpoint(chosen);
+}
+function withSafeEndpoint(agent) {
+  try {
+    if (new URL(agent.mcpUrl).origin !== new URL(agent.controlPlane).origin) {
+      return {
+        kind: "refused",
+        reason: "That connection's MCP endpoint is not on the control plane it belongs to, so I sent its credential nowhere."
+      };
+    }
+  } catch {
+    return {
+      kind: "refused",
+      reason: "That connection's MCP endpoint is not a URL, so I did not use it."
+    };
+  }
+  return { kind: "agent", agent };
+}
+
+// src/repository.ts
+import { execFileSync as execFileSync2 } from "node:child_process";
+var REPOSITORY_HINT_PATTERN = /^[A-Za-z0-9._-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
+function git(cwd, args) {
+  try {
+    return execFileSync2("git", ["-C", cwd, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return void 0;
+  }
+}
+function ownerName(remote) {
+  const match = /github\.com[:/]+([A-Za-z0-9._-]{1,39})\/([A-Za-z0-9._-]{1,100}?)(?:\.git)?$/.exec(
+    remote
+  );
+  if (!match) return void 0;
+  const hint = `${match[1]}/${match[2]}`;
+  return REPOSITORY_HINT_PATTERN.test(hint) ? hint : void 0;
+}
+function repositoryHints(cwd = process.cwd()) {
+  const names = git(cwd, ["remote"])?.split("\n").filter((name) => name.length > 0) ?? [];
+  const ordered = ["origin", ...names.filter((name) => name !== "origin")];
+  const hints = [];
+  for (const name of ordered) {
+    const url = git(cwd, ["remote", "get-url", name]);
+    const hint = url === void 0 ? void 0 : ownerName(url);
+    if (hint !== void 0 && !hints.some((h) => h.toLowerCase() === hint.toLowerCase()))
+      hints.push(hint);
+  }
+  return hints;
+}
+
+// src/self-update.ts
+import { spawn } from "node:child_process";
+import { existsSync as existsSync3, mkdirSync as mkdirSync5, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join6 } from "node:path";
+var STAMP = "self-update.json";
+var DAY_MS = 24 * 60 * 60 * 1e3;
+function stampPath(environment) {
+  return join6(configHome(environment), STAMP);
+}
+function lastStarted(environment) {
+  const path = stampPath(environment);
+  if (!existsSync3(path)) return 0;
+  try {
+    const parsed = JSON.parse(readFileSync6(path, "utf8"));
+    return typeof parsed.startedAt === "number" ? parsed.startedAt : 0;
+  } catch {
+    return 0;
+  }
+}
+function detached(command, args) {
+  const child = spawn(command, [...args], { detached: true, stdio: "ignore" });
+  child.on("error", () => void 0);
+  child.unref();
+}
+function startSelfUpdateIfDue(newer, deps) {
+  if (newer === void 0) return false;
+  const now = deps.now ?? Date.now;
+  if (now() - lastStarted(deps.environment) < DAY_MS) return false;
+  try {
+    mkdirSync5(configHome(deps.environment), { recursive: true, mode: 448 });
+    writeFileSync3(
+      stampPath(deps.environment),
+      JSON.stringify({ startedAt: now(), toward: newer }) + "\n",
+      { mode: 384 }
+    );
+    (deps.run ?? detached)("npx", ["-y", HOOK_SPECIFIER, "install", "--json"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/commands/guidance.ts
 function readInput(stream) {
   return new Promise((resolve2, reject) => {
@@ -2908,7 +3084,8 @@ function identifier(input) {
   return typeof input === "string" && input.length > 0 && input.length <= 256 ? input : void 0;
 }
 async function runGuidance(options) {
-  if (!options.repositoryId || !validateProjectGuidanceScope({
+  const projectScoped = options.repositoryId !== void 0;
+  if (projectScoped && !validateProjectGuidanceScope({
     cwd: options.cwd,
     hook: options.hook,
     repositoryId: options.repositoryId,
@@ -2929,16 +3106,34 @@ async function runGuidance(options) {
       throw new Error("invalid_hook_event");
     event = parsedEvent;
     const record = input;
-    const agents = readCredentials(options.environment).agents.filter(
+    const credentials = readCredentials(options.environment).agents;
+    const agents = projectScoped ? credentials.filter(
       (agent) => agent.controlPlane === options.controlPlane && agent.repositoryId === options.repositoryId
-    );
-    if (agents.length !== 1 || !agents[0]) throw new Error("guidance_connection_unavailable");
+    ) : (() => {
+      const selection = selectAgent(
+        credentials,
+        options.controlPlane,
+        void 0,
+        repositoryHints(options.cwd)
+      );
+      return selection.kind === "refused" ? [] : [selection.agent];
+    })();
+    if (agents.length !== 1 || !agents[0]) {
+      if (projectScoped) throw new Error("guidance_connection_unavailable");
+      return 0;
+    }
     const loaded = await loadGuidance({
       agent: agents[0],
       environment: options.environment,
       timeoutMs: 750,
       ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
     });
+    if (event === "SessionStart")
+      startSelfUpdateIfDue(newerVersionPublished(), {
+        environment: options.environment,
+        ...options.startUpdate ? { run: options.startUpdate } : {},
+        ...options.now ? { now: options.now } : {}
+      });
     const sessionId = identifier(record.session_id);
     const agentId = identifier(record.agent_id);
     recordGuidanceContext(

package/dist/guidance.js

@@ -1,3 +1,4 @@
+import { noteServerVersion } from "./currency.js";
 import { CLIENT_HEADER, CLIENT_HEADER_VALUE } from "./wire.js";
 import { createHash, randomBytes } from "node:crypto";
 import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
@@ -182,6 +183,9 @@ export async function loadGuidance(input) {
                     ...(previous ? { "if-none-match": previous.etag } : {}),
                 },
             });
+            // The server names the newest published release on every answer; the
+            // hook is where a laptop learns it is behind, and never where it waits.
+            noteServerVersion(response.headers);
             if (response.status === 304) {
                 if (!previous ||
                     response.headers.get("etag") !== previous.etag ||

package/dist/install.d.ts

@@ -19,5 +19,9 @@ export declare function runInstall(options: InstallOptions & {
     json: boolean;
     write: (text: string) => void;
     allowPartial?: boolean;
+    /** Carried into the one JSON object this prints, never as a second line. */
+    extra?: Record<string, unknown>;
+    /** Told the durable command's path once it is installed, before the report. */
+    onInstalled?: (result: InstallResult) => Record<string, unknown> | undefined;
 }): number;
 export {};

package/dist/install.js

@@ -333,6 +333,7 @@ export function ensureInstalled(options) {
 export function runInstall(options) {
     try {
         const result = ensureInstalled(options);
+        const more = options.onInstalled?.(result) ?? {};
         const message = result.manualPathRequired
             ? `Balladeer is installed at ${result.command}. Add ${dirname(result.command)} to your shell PATH and reopen the terminal/coding agent. Automatic PATH editing is unavailable for this shell; this setup process can use the command now.`
             : result.restartRequired
@@ -344,6 +345,8 @@ export function runInstall(options) {
                 ...result,
                 status: result.manualPathRequired ? "path_pending" : result.status,
                 message,
+                ...(options.extra ?? {}),
+                ...more,
             }) + "\n"
             : message + "\n");
         return result.manualPathRequired && !options.allowPartial ? 4 : 0;
@@ -353,7 +356,12 @@ export function runInstall(options) {
             ? error.message
             : "Installation could not access a required local file or command. Allow the reported installer operation and retry; no pairing has started.";
         options.write(options.json
-            ? JSON.stringify({ step: "install", status: "blocked", message }) + "\n"
+            ? JSON.stringify({
+                step: "install",
+                status: "blocked",
+                message,
+                ...(options.extra ?? {}),
+            }) + "\n"
             : message + "\n");
         return 4;
     }

package/dist/open-browser.d.ts

@@ -0,0 +1,13 @@
+import { spawn } from "node:child_process";
+/**
+ * Open a page in the person's default browser, and say whether it was asked.
+ *
+ * Setup's one link used to be copied by hand from the terminal into a browser,
+ * which is the step a person at a keyboard does not want and an agent shell
+ * cannot do at all. So this runs only when a person is there (the caller
+ * checks the terminal), hands the URL to the operating system's own opener,
+ * and does not wait for it: a browser that never appears is reported by the
+ * link staying on screen, never by this command hanging. Nothing here reads
+ * the page or learns what happened in it.
+ */
+export declare function openInBrowser(url: string, platform?: NodeJS.Platform, run?: typeof spawn): boolean;

package/dist/open-browser.js

@@ -0,0 +1,30 @@
+import { spawn } from "node:child_process";
+/**
+ * Open a page in the person's default browser, and say whether it was asked.
+ *
+ * Setup's one link used to be copied by hand from the terminal into a browser,
+ * which is the step a person at a keyboard does not want and an agent shell
+ * cannot do at all. So this runs only when a person is there (the caller
+ * checks the terminal), hands the URL to the operating system's own opener,
+ * and does not wait for it: a browser that never appears is reported by the
+ * link staying on screen, never by this command hanging. Nothing here reads
+ * the page or learns what happened in it.
+ */
+export function openInBrowser(url, platform = process.platform, run = spawn) {
+    if (!/^https:\/\//.test(url))
+        return false;
+    const [command, args] = platform === "darwin"
+        ? ["open", [url]]
+        : platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = run(command, args, { detached: true, stdio: "ignore" });
+        child.on("error", () => undefined);
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/quiet.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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

@@ -0,0 +1,73 @@
+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 };
+}