@basein/runner 0.2.8 → 0.2.11

package/dist/bin/setup.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `bir setup` — from an installed package to a recording, replaying project,
+ * in one command and with nothing left open.
+ *
+ * It is the sequence the guides used to ask a person to type, done in order and
+ * checked at each step:
+ *
+ *   1. the service address, verified to be the API and not a website, then
+ *      stored in ~/.baseinstrunner/config.json so no terminal needs BIR_AUTH_URL;
+ *   2. the sign-in — a setup token from the console, a cached session, or the
+ *      browser flow — stored the way `bir login` stores it;
+ *   3. the project: MCP servers wrapped, hooks wired, the scenario server added
+ *      and pre-approved (`bir install --global --replay`);
+ *   4. the recorder, started in the background and from now on started by the
+ *      SessionStart hook whenever it is missing;
+ *   5. a summary that names the account, the servers, the recorder's log, and
+ *      the one thing left to do: start Claude Code.
+ *
+ * Idempotent, so it is also the upgrade path and the "is it still right?" path.
+ * It never prompts: under `curl | sh` stdin is the script itself, and a script
+ * that stops to ask is a script that hangs. Everything it needs is an argument
+ * or an environment variable, and everything it decides is printed.
+ *
+ * THE WRONG FOLDER. A terminal opened from the Start menu begins in the home
+ * directory, and that is where a first paste often lands. Refusing would throw
+ * away the two things that already went right — the install and the sign-in —
+ * so instead the sign-in is kept, and the summary names the two commands left:
+ * `cd <project>` and `bir setup`. The second needs no token; the session is
+ * cached.
+ */
+export interface SetupArgs {
+    /** `--auth-url`; else BIR_AUTH_URL; else the stored address. */
+    authUrl?: string;
+    /** `--token`; else the BIR_SETUP_TOKEN environment variable. Never echoed. */
+    token?: string;
+    /** `--project`: the directory to record. Default: the current one. */
+    project?: string;
+    /** `--no-browser` → false. Undefined lets `deviceLogin` decide. */
+    browser?: boolean;
+    /** `--no-replay` → false: wrap and record, but add no scenario server. */
+    replay: boolean;
+    /** `--no-daemon` → false: wire everything, start nothing. */
+    daemon: boolean;
+    /** `--allow-servers a,b`: the servers replay may call unattended, stored for this project. */
+    allowServers?: string;
+}
+export interface SetupDeps {
+    out: (line?: string) => void;
+    err: (line: string) => void;
+    /**
+     * Wrap the current directory: `bir install --replay` (or without), with the
+     * invocation the caller decided. Returns its exit code.
+     */
+    install: (opts: {
+        replay: boolean;
+    }) => Promise<number>;
+    /** Absolute path of `dist/bin/bir-hooks.js`, for the daemon. */
+    hooksScript: string;
+    env?: NodeJS.ProcessEnv;
+    /** Injected by tests; defaults to `process.chdir`. */
+    chdir?: (dir: string) => void;
+}
+/** True when `claude` (Claude Code) is on PATH or in its native install location. */
+export declare function claudeOnPath(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The console for an API address, when the deployment follows the
+ * `api.<domain>` convention this project uses. Undefined otherwise — a guessed
+ * link is worse than none.
+ */
+export declare function consoleUrlFor(apiUrl: string): string | undefined;
+export declare function runSetup(args: SetupArgs, deps: SetupDeps): Promise<number>;
+//# sourceMappingURL=setup.d.ts.map

package/dist/bin/setup.js

@@ -0,0 +1,286 @@
+/**
+ * `bir setup` — from an installed package to a recording, replaying project,
+ * in one command and with nothing left open.
+ *
+ * It is the sequence the guides used to ask a person to type, done in order and
+ * checked at each step:
+ *
+ *   1. the service address, verified to be the API and not a website, then
+ *      stored in ~/.baseinstrunner/config.json so no terminal needs BIR_AUTH_URL;
+ *   2. the sign-in — a setup token from the console, a cached session, or the
+ *      browser flow — stored the way `bir login` stores it;
+ *   3. the project: MCP servers wrapped, hooks wired, the scenario server added
+ *      and pre-approved (`bir install --global --replay`);
+ *   4. the recorder, started in the background and from now on started by the
+ *      SessionStart hook whenever it is missing;
+ *   5. a summary that names the account, the servers, the recorder's log, and
+ *      the one thing left to do: start Claude Code.
+ *
+ * Idempotent, so it is also the upgrade path and the "is it still right?" path.
+ * It never prompts: under `curl | sh` stdin is the script itself, and a script
+ * that stops to ask is a script that hangs. Everything it needs is an argument
+ * or an environment variable, and everything it decides is printed.
+ *
+ * THE WRONG FOLDER. A terminal opened from the Start menu begins in the home
+ * directory, and that is where a first paste often lands. Refusing would throw
+ * away the two things that already went right — the install and the sign-in —
+ * so instead the sign-in is kept, and the summary names the two commands left:
+ * `cd <project>` and `bir setup`. The second needs no token; the session is
+ * cached.
+ */
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join, parse as parsePath, resolve as resolvePath } from "node:path";
+import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, describeAuthService, deviceLogin, loadStoredConfig, normalizeAuthUrl, rememberAuthUrl, tokenLogin, } from "../auth/client.js";
+import { activeSessions, ensureDaemon, SETUP_TOKEN_ENV, stopDaemon, } from "../control/daemon.js";
+import { normalizePath } from "../control/paths.js";
+import { isWrapped, projectRecord, readSidecar, SCENARIO_SERVER_KEY, setProjectRecord, writeSidecar, allocateFreeProjectPort, } from "../config/generate.js";
+import { resolveServers } from "../config/resolve.js";
+import { errText } from "../util/log.js";
+import { packageVersion } from "../util/version.js";
+/** True when `claude` (Claude Code) is on PATH or in its native install location. */
+export function claudeOnPath(env = process.env) {
+    const names = process.platform === "win32" ? ["claude.exe", "claude.cmd", "claude"] : ["claude"];
+    const dirs = (env.PATH ?? env.Path ?? "").split(delimiter).filter(Boolean);
+    dirs.push(join(homedir(), ".local", "bin"));
+    return dirs.some((dir) => names.some((name) => existsSync(join(dir, name))));
+}
+/** A directory nobody means to record from: the home folder or a drive root. */
+function looksLikeNotAProject(dir) {
+    const norm = normalizePath(dir);
+    if (norm === normalizePath(homedir()))
+        return "your home folder";
+    if (normalizePath(parsePath(dir).root) === norm)
+        return "the root of a drive";
+    return undefined;
+}
+/**
+ * The console for an API address, when the deployment follows the
+ * `api.<domain>` convention this project uses. Undefined otherwise — a guessed
+ * link is worse than none.
+ */
+export function consoleUrlFor(apiUrl) {
+    try {
+        const u = new URL(apiUrl);
+        if (!u.hostname.startsWith("api."))
+            return undefined;
+        return `${u.protocol}//${u.hostname.slice("api.".length)}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function runSetup(args, deps) {
+    const { out, err } = deps;
+    const env = deps.env ?? process.env;
+    const chdir = deps.chdir ?? ((dir) => process.chdir(dir));
+    // The token is read once and then removed from this process's environment,
+    // so nothing started from here — the recorder above all — inherits it.
+    const token = args.token ?? env[SETUP_TOKEN_ENV];
+    delete env[SETUP_TOKEN_ENV];
+    if (env === process.env)
+        delete process.env[SETUP_TOKEN_ENV];
+    // ── 1. the service ───────────────────────────────────────────────────────
+    // `||`, not `??`: an environment that *sets* BIR_AUTH_URL to nothing (a
+    // wrapper script, a CI job) means "not set", not "the empty address".
+    const configured = (args.authUrl || env.BIR_AUTH_URL || loadStoredConfig().authUrl || "").trim();
+    if (!configured) {
+        err("No service address. Pass --auth-url https://api.your-service, or set BIR_AUTH_URL.");
+        err(AUTH_URL_HINT);
+        return 1;
+    }
+    const baseUrl = await normalizeAuthUrl(configured);
+    const problem = await describeAuthService(baseUrl);
+    if (problem) {
+        err(`${baseUrl} is not a BaseIn service: ${problem}.`);
+        err(AUTH_URL_HINT);
+        return 1;
+    }
+    const envUrl = (env.BIR_AUTH_URL ?? "").replace(/\/+$/, "");
+    const storedUrl = (loadStoredConfig().authUrl ?? "").replace(/\/+$/, "");
+    if (envUrl && ((args.authUrl && envUrl !== baseUrl) || (!args.authUrl && storedUrl && envUrl !== storedUrl))) {
+        // Every process reads BIR_AUTH_URL before the stored address, so a stale
+        // value in a profile file (the pre-0.2.9 installers wrote one) would send
+        // tomorrow's recordings elsewhere — or, now that sessions are bound to
+        // their service, nowhere. Said whether the address came from --auth-url or
+        // from the store; a bare `bir setup` in a second project is the usual case.
+        err(`BIR_AUTH_URL in this environment is ${envUrl}, but ${args.authUrl ? "this sets up" : "the stored address is"} ${args.authUrl ? baseUrl : storedUrl}.`);
+        err("Remove that variable (check your shell profile), or the recorder will not record.");
+    }
+    const project = resolvePath(args.project ?? process.cwd());
+    if (!existsSync(project) || !statSync(project).isDirectory()) {
+        err(`Project directory not found: ${project}`);
+        return 1;
+    }
+    out(`==> Setting up the runner (${packageVersion()})`);
+    out(`    service   ${baseUrl}`);
+    // ── 2. the sign-in ───────────────────────────────────────────────────────
+    let session;
+    try {
+        if (token !== undefined) {
+            if (!token.trim()) {
+                err("--token needs the token itself: bir setup --token <token>");
+                return 1;
+            }
+            try {
+                session = await tokenLogin(baseUrl, token);
+            }
+            catch (e) {
+                // The same line, pasted twice: a setup token is single-use, and the
+                // second paste — after a failure past the sign-in, or as the upgrade
+                // path — carries a token the first paste already redeemed. The sign-in
+                // that first paste made is still on disk; that is the one to keep.
+                const cached = e instanceof DeviceFlowAborted && e.reason === "expired_token"
+                    ? await authenticate({ authUrl: baseUrl })
+                    : undefined;
+                if (!cached)
+                    throw e;
+                session = cached;
+                out(`    the setup token was already used; keeping the sign-in from before (${cached.user.email})`);
+            }
+        }
+        else {
+            // A cached session is bound to the service that issued it (auth/client.ts);
+            // `authenticate` answers nothing for another one, and the browser flow runs.
+            session = await authenticate({ authUrl: baseUrl });
+            if (!session) {
+                out("    signing in through the browser (a setup token from the console skips this)");
+                // The install scripts run this with stderr on a pipe, and `deviceLogin`
+                // would read that as "nobody is watching" and open nothing. Somebody is:
+                // they just pasted the line. Only SSH, where the browser would open on
+                // the wrong machine, still keeps the link on paper.
+                const overSsh = Boolean(env.SSH_CONNECTION || env.SSH_TTY);
+                session = await deviceLogin(baseUrl, { openBrowser: args.browser ?? !overSsh });
+            }
+        }
+    }
+    catch (e) {
+        if (e instanceof DeviceFlowAborted) {
+            err(e.message);
+            return 1;
+        }
+        if (e instanceof DeviceFlowUnsupported) {
+            err("this service does not offer browser sign-in or setup tokens; run `bir login --password`.");
+            return 1;
+        }
+        err(`sign-in failed: ${errText(e)}`);
+        return 1;
+    }
+    if (!session) {
+        err("not signed in — run `bir setup` again (or `bir login`).");
+        return 1;
+    }
+    rememberAuthUrl(baseUrl);
+    out(`    account   ${session.user.email}`);
+    // ── 3. the wrong folder ──────────────────────────────────────────────────
+    const notAProject = looksLikeNotAProject(project);
+    if (notAProject) {
+        out();
+        out(`Signed in as ${session.user.email}. This is ${notAProject}, so nothing was wired here.`);
+        out("Two commands left. Open a terminal in the project you start Claude Code in, and run:");
+        out(`    cd ${process.platform === "win32" ? "C:\\path\\to\\your\\project" : "~/path/to/your/project"}`);
+        out("    bir setup");
+        out("No token is needed the second time; the sign-in is kept on this computer.");
+        return 0;
+    }
+    // ── 4. the project ───────────────────────────────────────────────────────
+    chdir(project);
+    if (args.allowServers !== undefined) {
+        // Stored before install so the recorder started below reads it at start.
+        const sidecar = readSidecar();
+        const port = projectRecord(sidecar, project)?.port ?? (await allocateFreeProjectPort(sidecar, project));
+        const list = args.allowServers.split(",").map((s) => s.trim()).filter(Boolean);
+        setProjectRecord(sidecar, project, { port, replay: { ...(projectRecord(sidecar, project)?.replay ?? {}), allowServers: list.length ? list : undefined } });
+        writeSidecar(sidecar);
+    }
+    out("==> Wiring the project");
+    const code = await deps.install({ replay: args.replay });
+    if (code !== 0)
+        return code;
+    // ── 5. the recorder ──────────────────────────────────────────────────────
+    let ensured;
+    if (args.daemon) {
+        out("==> Starting the recorder in the background");
+        try {
+            ensured = await ensureDaemon(project, {
+                hooksScript: deps.hooksScript,
+                env,
+                restartOnSkew: true,
+            });
+            if (!ensured.started &&
+                ensured.status.health.recording === false &&
+                activeSessions(ensured.status.health) === 0) {
+                // A recorder that came up before there was a sign-in (a `bir up` on a
+                // fresh machine, a session that expired) has nowhere to send steps.
+                // There is one now, and nothing is mid-run: replace it rather than
+                // tell the person to.
+                out("    the running recorder has no sign-in; replacing it");
+                await stopDaemon(project);
+                ensured = await ensureDaemon(project, { hooksScript: deps.hooksScript, env });
+                ensured = { ...ensured, restarted: true };
+            }
+        }
+        catch (e) {
+            err(`the recorder did not start: ${errText(e)}`);
+            err("Everything else is in place. Fix that, then run `bir up` here.");
+            return 1;
+        }
+    }
+    // ── 6. the summary ───────────────────────────────────────────────────────
+    const wrapped = resolveServers(project)
+        .filter((s) => s.name !== SCENARIO_SERVER_KEY && isWrapped(s.config))
+        .map((s) => s.name);
+    const health = ensured?.status.health;
+    const replay = health?.replay;
+    const recording = health ? health.recording !== false : undefined;
+    const policy = projectRecord(readSidecar(), project)?.replay;
+    const allow = replay?.allowServers ?? policy?.allowServers ?? null;
+    out();
+    out(`Done. Recording${args.replay ? " and replay are" : " is"} on for ${project}`);
+    out(`  account    ${session.user.email}  (${baseUrl})`);
+    out(`  wrapped    ${wrapped.length ? wrapped.join(", ") : "(no MCP servers here)"}`);
+    if (!args.replay) {
+        out("  replay     not installed (--no-replay)");
+    }
+    else if (wrapped.length === 0) {
+        out("  replay     steer mode only — no MCP servers wrapped here; add a .mcp.json and run `bir setup` again for direct replay");
+    }
+    else {
+        const on = replay ? replay.enabled !== false : policy?.enabled !== false;
+        out(`  replay     ${on ? "on" : "off"} — direct execution allowed for: ${allow?.length ? allow.join(", ") : `all wrapped (narrow it with \`bir replay allow ${wrapped[0]}\`)`}`);
+    }
+    if (ensured) {
+        const { info, health: h } = ensured.status;
+        const theirs = String(h.hooksVersion ?? info.version ?? "");
+        out(`  recorder   ${ensured.started ? (ensured.restarted ? "restarted" : "started") : "already running"} in the background (pid ${info.pid})` +
+            " — it starts itself with every Claude Code session");
+        if (theirs && theirs !== packageVersion()) {
+            out(`             recorder ${theirs} is still serving an open Claude Code session; it restarts to ${packageVersion()} with the next session`);
+        }
+        if (info.logFile)
+            out(`  log        ${info.logFile}`);
+        if (recording === false) {
+            out("  !! the recorder has no session to record with — run `bir login`, then `bir up --restart`");
+        }
+    }
+    else {
+        out("  recorder   not started (--no-daemon); the SessionStart hook starts it, or run `bir up`");
+    }
+    out();
+    const console_ = consoleUrlFor(baseUrl);
+    if (claudeOnPath(env)) {
+        out("Now:  claude");
+    }
+    else {
+        out("Now:  install Claude Code, then start it here:  claude");
+        out(process.platform === "win32"
+            ? "        irm https://claude.ai/install.ps1 | iex"
+            : "        curl -fsSL https://claude.ai/install.sh | bash");
+    }
+    out('  first time in this folder: say Yes to "trust this folder"');
+    out("  just installed Claude Code? it asks you to sign in to Claude (it needs a Claude subscription)");
+    out(`  give it a task that takes 4+ tool calls — it appears ${console_ ? `at ${console_}/recordings` : "in the console's Recordings"} within a minute of finishing`);
+    out("Any time:  bir doctor     bir investigate     bir down (stop)     bir uninstall (undo)");
+    return recording === false ? 1 : 0;
+}
+//# sourceMappingURL=setup.js.map

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

@@ -19,10 +19,50 @@ export interface ClaudeCodePaths {
     claudeJson: string;
     /** `<cwd>/.mcp.json` (project scope). */
     mcpJson: string;
-    /** `<cwd>/.claude/settings.json` (hooks). */
+    /**
+     * `<cwd>/.claude/settings.json` — the file a team commits. Hooks used to go
+     * here; they are only ever *removed* from it now (see {@link ClaudeCodePaths.settingsLocal}).
+     */
     settings: string;
+    /**
+     * `<cwd>/.claude/settings.local.json` — "you, in this project", the file
+     * Claude Code itself keeps out of git. Where the hooks go: they carry a
+     * bearer token and an absolute path to this machine's node, neither of which
+     * belongs in a teammate's clone.
+     */
+    settingsLocal: string;
 }
 export declare function claudeCodePaths(cwd: string, claudeJsonOverride?: string): ClaudeCodePaths;
+/** The line `bir` adds to a repository's exclude file. */
+export declare const LOCAL_SETTINGS_EXCLUDE = ".claude/settings.local.json";
+/**
+ * Keep `.claude/settings.local.json` out of version control, the way Claude
+ * Code does when *it* creates the file — it only does so for files it wrote.
+ *
+ * `.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
+ * 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;
+/** Undo {@link ensureGitExclude}: drop the line, leave everything else. */
+export declare function removeGitExclude(dir: string, line?: string): string | undefined;
+/**
+ * Pre-approve project-scoped MCP servers by name (`enabledMcpjsonServers`).
+ *
+ * Claude Code asks before it uses a server from `.mcp.json`, and a "No" there
+ * silently leaves a direct replay with nowhere to deliver its results. The
+ * runner's own scenario server is approved here, in the person's local
+ * settings, so the question is never asked. Returns the file's new text.
+ */
+export declare function enableMcpjsonServers(settingsPath: string, names: string[]): string;
+/** Undo {@link enableMcpjsonServers} for `names`; drops the key when empty. */
+export declare function disableMcpjsonServers(settingsPath: string, names: string[]): string | undefined;
+/** True when `settingsPath` holds any hook of ours. */
+export declare function hasBirHooks(settingsPath: string): boolean;
 /** Which file holds a given scope's `mcpServers` for this cwd. */
 export declare function fileForScope(scope: Scope, paths: ClaudeCodePaths): string;
 export declare function sha256(text: string): string;
@@ -52,19 +92,65 @@ export declare const HOOK_ROUTES: Array<{
     timeout: number;
     async?: boolean;
 }>;
-export interface HookEntry {
+export interface HttpHookEntry {
     type: "http";
     url: string;
     timeout: number;
     headers?: Record<string, string>;
     async?: boolean;
 }
+/**
+ * A command hook in Claude Code's **exec form**: 'command' is spawned directly
+ * with 'args' as its argument vector and no shell in between. That is the only
+ * form that survives every host: a path with a space in it needs no quoting,
+ * and it runs the same under Git Bash, PowerShell and cmd.exe.
+ */
+export interface CommandHookEntry {
+    type: "command";
+    command: string;
+    args: string[];
+    timeout: number;
+}
+export type HookEntry = HttpHookEntry | CommandHookEntry;
 export type HooksBlock = Record<string, Array<{
     matcher?: string;
     hooks: HookEntry[];
 }>>;
-/** Build the `hooks` block pointing at a control server. */
-export declare function buildHooksBlock(controlUrl: string, token: string): HooksBlock;
+/**
+ * The argument that makes a 'bir-hooks' invocation the SessionStart hook.
+ * 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;
+export interface HooksBlockOptions {
+    /**
+     * Make SessionStart start the recorder itself when none is running.
+     *
+     * 'node' is the interpreter and 'hooksScript' the absolute path of
+     * dist/bin/bir-hooks.js. The hook then reads the SessionStart payload, starts
+     * 'bir-hooks' in the background if this directory has no live control
+     * server, and relays the payload to it — so the HTTP SessionStart hook is
+     * **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.
+     */
+    ensure?: {
+        node: string;
+        hooksScript: string;
+        nodeFlags?: 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.
+ */
+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