@basein/runner 0.2.11 → 0.3.0

package/dist/config/adapters/claude-code.d.ts

@@ -7,11 +7,18 @@
  * runs. `resolveServers` reports the winner; this module writes there and warns
  * loudly when a lower scope also defines the name.
  *
- * Byte-for-byte reversibility: the *text* of every file touched is stashed before
- * the first edit, together with a hash of what we wrote. On uninstall, a file
- * still matching that hash is restored verbatim; a file edited since is repaired
- * entry-by-entry instead, with a warning. That is the difference between "we put
- * the entries back" and "the file is as you left it".
+ * Byte-for-byte reversibility: the *text* of every project file touched is
+ * stashed before the first edit, together with a hash of what we wrote. On
+ * uninstall, a file still matching that hash — and not changed by anybody else
+ * between two of our writes — is restored verbatim; a file edited since is
+ * repaired entry-by-entry instead, with a warning. `~/.claude.json` is always
+ * repaired entry by entry: it is Claude Code's own, rewritten constantly, and
+ * holds every project's settings.
+ *
+ * Where the wrapped entries go (bir.ts, install): the LOCAL scope, as an
+ * override of the same name — never the team's `.mcp.json`, which gets
+ * committed and would carry this machine's node and runner paths to every
+ * clone, and never the user scope, which applies to every project.
  */
 import { type McpServerConfig, type Scope } from "../resolve.js";
 export interface ClaudeCodePaths {
@@ -42,12 +49,21 @@ export declare const LOCAL_SETTINGS_EXCLUDE = ".claude/settings.local.json";
  * `.git/info/exclude`, never `.gitignore`: the first is the person's own,
  * untracked list; the second is a file the team owns and would see in a diff.
  * Walks up from `dir` to find the repository, follows a worktree's `gitdir:`
- * pointer, and appends the line once. Returns the exclude file's path when the
+ * pointer to the repository's common git directory (the only exclude file git
+ * reads for a linked worktree), and appends the line once. Returns the exclude file's path when the
  * line is there (added or already present), undefined outside a repository or
  * when the file could not be written — an exclude that fails is a note, not a
  * failed install.
  */
 export declare function ensureGitExclude(dir: string, line?: string): string | undefined;
+/**
+ * {@link ensureGitExclude}, also saying whether the line was ADDED now (false:
+ * it was already there — somebody's own, which uninstall must leave alone).
+ */
+export declare function ensureGitExcludeLine(dir: string, line?: string): {
+    path: string;
+    added: boolean;
+} | undefined;
 /** Undo {@link ensureGitExclude}: drop the line, leave everything else. */
 export declare function removeGitExclude(dir: string, line?: string): string | undefined;
 /**
@@ -68,6 +84,28 @@ export declare function fileForScope(scope: Scope, paths: ClaudeCodePaths): stri
 export declare function sha256(text: string): string;
 /** Read a file's text, or null when it does not exist. */
 export declare function readTextOrNull(path: string): string | null;
+/**
+ * Read-modify-write one JSON file, safely:
+ *
+ *   - a file that is not plain JSON (comments, trailing commas, a torn write)
+ *     is REFUSED with an error naming it, never rewritten from a guess;
+ *   - the file is re-read just before the write, and the edit is applied again
+ *     to the fresh text when somebody else changed it in between (Claude Code
+ *     rewrites `~/.claude.json` constantly, and a lost update there loses a
+ *     server the user just added, or ours);
+ *   - the write itself is atomic (util/atomic-write.ts), so Claude Code never
+ *     reads a half-written config, and a symlinked file stays a symlink.
+ *
+ * `mutate` gets a fresh parse each attempt and must not keep state between
+ * calls. Returns the text written, for the sidecar's hash.
+ */
+export declare function editJson(path: string, mutate: (parsed: Record<string, unknown>) => void): string;
+/**
+ * Throw (naming the file) when `path` exists and is not a plain JSON object —
+ * so an install can refuse up front, before it has written anything, instead
+ * of stopping halfway through with some files changed and others not.
+ */
+export declare function assertEditableJson(path: string): void;
 /**
  * Set (or delete, with `entry === null`) one MCP server entry in `scope`.
  * Returns the file's new text so the caller can hash it for the sidecar.
@@ -76,6 +114,17 @@ export declare function setServerEntry(scope: Scope, cwd: string, name: string,
     file: string;
     text: string;
 };
+/**
+ * Set (or delete) one entry of the local scope under each of `keys` in
+ * `~/.claude.json`, in ONE atomic edit. `shouldTouch` sees the entry currently
+ * under a key (or undefined) and may veto that key — so a user's own entry
+ * under another spelling of the project is never overwritten or deleted.
+ * Returns the text written and the keys actually changed (none: no write).
+ */
+export declare function setLocalEntries(claudeJson: string, keys: string[], name: string, entry: McpServerConfig | null, shouldTouch?: (current: McpServerConfig | undefined) => boolean): {
+    text?: string;
+    keys: string[];
+};
 /**
  * The hook events `bir-hooks` registers, and the control route each drives.
  *
@@ -84,6 +133,17 @@ export declare function setServerEntry(scope: Scope, cwd: string, name: string,
  * only listens to the success one records a step that never closes.
  * `SubagentStart` / `SubagentStop` carry `agent_id`, which is what lets a
  * subagent's steps be attributed rather than silently interleaved.
+ *
+ * THE TIMEOUTS ARE THE USER'S WORST CASE. Claude Code waits for a hung hook up
+ * to its `timeout`, so each number here is how long a slow or blackholed
+ * service could make a person wait — at every prompt, every tool call, every
+ * `/exit`. The control server keeps its own per-route deadlines well inside
+ * them (prompt ≤ 7 s, tool/pre ≤ 12 s, tool/post and stop ≤ 2 s, end ≤ 1 s,
+ * start ≤ 2 s) and answers `{}` on overrun, so these are the second line of
+ * defence, not a budget to spend. SessionEnd matters twice: Claude Code's own
+ * default for it is 1.5 s, and whatever is written here RAISES that — the 30 it
+ * used to be turned every `/exit` during a service incident into a 30 s wait.
+ * A re-run of `bir setup` rewrites existing installs with these.
  */
 export declare const HOOK_ROUTES: Array<{
     event: string;
@@ -121,8 +181,12 @@ export type HooksBlock = Record<string, Array<{
  * Exported so the binary and the adapter cannot drift apart on the spelling.
  */
 export declare const ENSURE_ARG = "ensure";
-/** How long SessionStart may wait for a background recorder to come up. */
-export declare const ENSURE_TIMEOUT_S = 30;
+/**
+ * How long SessionStart may wait for a background recorder to come up. The
+ * ensure hook keeps its own budget at 12 s or less and always exits 0; this is
+ * the host's ceiling on top of it.
+ */
+export declare const ENSURE_TIMEOUT_S = 15;
 export interface HooksBlockOptions {
     /**
      * Make SessionStart start the recorder itself when none is running.
@@ -134,27 +198,41 @@ export interface HooksBlockOptions {
      * **replaced**, not added to. Hooks for one event run in parallel, and an
      * HTTP hook racing the daemon it depends on would fail every first session.
      *
-     * Omitted for an npx invocation: resolving a package inside a hook is too
-     * slow to start a recorder from, so those installs keep the HTTP hook and a
-     * recorder someone started.
+     * The `{ command, args }` form is an already-built exec-form invocation —
+     * what an npx install uses (`npx --prefer-offline -y -p <spec> bir-hooks
+     * ensure`, in `cmd /c` on Windows). It pays npx's start-up once per session,
+     * which is affordable there and not per tool call; without it nothing ever
+     * starts the recorder of an npx install, and every hook of every session
+     * fails against a port nobody listens on.
      */
     ensure?: {
         node: string;
         hooksScript: string;
         nodeFlags?: string[];
+    } | {
+        command: string;
+        args: string[];
     };
 }
 /** Build the 'hooks' block pointing at a control server. */
 export declare function buildHooksBlock(controlUrl: string, token: string, opts?: HooksBlockOptions): HooksBlock;
 /**
- * True when a hook entry is one of ours: an HTTP hook aimed at a control-server
- * route, or the exec-form command hook that starts the recorder.
+ * True when a hook entry is one of ours, and only then — install and uninstall
+ * delete what this says is ours, so a false positive deletes somebody's hook.
+ *
+ *   HTTP: a loopback URL (127.0.0.1 / localhost / [::1]) whose path is exactly
+ *         one of our routes, AND either our kind of bearer token or a port in
+ *         the range `bir` allocates (the token-less 0.2.8 shape). A hook to
+ *         `https://hooks.example.com/session/end` is somebody else's.
+ *   exec: our self-starting SessionStart hook — `bir-hooks.js ensure`, or the
+ *         npx form `… -p @basein/runner@<v> bir-hooks ensure`.
  */
 export declare function isBirHook(entry: unknown): boolean;
 /**
  * Merge our hooks into a settings file, leaving every other hook alone. Returns
  * the new text. Our own entries are replaced rather than appended, so repeated
- * installs stay idempotent.
+ * installs stay idempotent — hook by hook: a user's own hook that happens to
+ * share a matcher group with one of ours stays exactly where it is.
  */
 export declare function installHooks(settingsPath: string, block: HooksBlock): string;
 /** Remove only our hook entries, and drop events left empty. */