@basein/runner 0.1.0

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

@@ -0,0 +1,76 @@
+/**
+ * adapters/claude-code — read and rewrite Claude Code's own configuration.
+ *
+ * Two files, three scopes, and one rule that decides everything (Phase 7.3):
+ * **write to the winning scope.** If a local-scope entry shadows the project one,
+ * rewriting `.mcp.json` changes nothing — the install looks successful and never
+ * 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".
+ */
+import { type McpServerConfig, type Scope } from "../resolve.js";
+export interface ClaudeCodePaths {
+    /** `~/.claude.json` (user + local scopes). */
+    claudeJson: string;
+    /** `<cwd>/.mcp.json` (project scope). */
+    mcpJson: string;
+    /** `<cwd>/.claude/settings.json` (hooks). */
+    settings: string;
+}
+export declare function claudeCodePaths(cwd: string, claudeJsonOverride?: string): ClaudeCodePaths;
+/** 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;
+/** Read a file's text, or null when it does not exist. */
+export declare function readTextOrNull(path: string): string | null;
+/**
+ * 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.
+ */
+export declare function setServerEntry(scope: Scope, cwd: string, name: string, entry: McpServerConfig | null, paths: ClaudeCodePaths): {
+    file: string;
+    text: string;
+};
+/**
+ * The hook events `bir-hooks` registers, and the control route each drives.
+ *
+ * `PostToolUseFailure` is registered rather than inferred from a `PostToolUse`
+ * payload's shape: a failing tool fires the *failure* event, and a recorder that
+ * 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.
+ */
+export declare const HOOK_ROUTES: Array<{
+    event: string;
+    route: string;
+    matcher?: string;
+    timeout: number;
+    async?: boolean;
+}>;
+export interface HookEntry {
+    type: "http";
+    url: string;
+    timeout: number;
+    headers?: Record<string, string>;
+    async?: boolean;
+}
+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;
+/**
+ * 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.
+ */
+export declare function installHooks(settingsPath: string, block: HooksBlock): string;
+/** Remove only our hook entries, and drop events left empty. */
+export declare function uninstallHooks(settingsPath: string): string | undefined;
+//# sourceMappingURL=claude-code.d.ts.map

package/dist/config/adapters/claude-code.js

@@ -0,0 +1,181 @@
+/**
+ * adapters/claude-code — read and rewrite Claude Code's own configuration.
+ *
+ * Two files, three scopes, and one rule that decides everything (Phase 7.3):
+ * **write to the winning scope.** If a local-scope entry shadows the project one,
+ * rewriting `.mcp.json` changes nothing — the install looks successful and never
+ * 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".
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { claudeJsonPath, parseJsonFile, projectKeyFor } from "../resolve.js";
+export function claudeCodePaths(cwd, claudeJsonOverride) {
+    return {
+        claudeJson: claudeJsonPath(claudeJsonOverride),
+        mcpJson: join(cwd, ".mcp.json"),
+        settings: join(cwd, ".claude", "settings.json"),
+    };
+}
+/** Which file holds a given scope's `mcpServers` for this cwd. */
+export function fileForScope(scope, paths) {
+    switch (scope) {
+        case "project":
+            return paths.mcpJson;
+        case "local":
+        case "user":
+            return paths.claudeJson;
+        default:
+            throw new Error(`scope ${scope} has no Claude Code file`);
+    }
+}
+export function sha256(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/** Read a file's text, or null when it does not exist. */
+export function readTextOrNull(path) {
+    try {
+        return existsSync(path) ? readFileSync(path, "utf8") : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeJson(path, value) {
+    const text = JSON.stringify(value, null, 2) + "\n";
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text, "utf8");
+    return text;
+}
+/**
+ * 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.
+ */
+export function setServerEntry(scope, cwd, name, entry, paths) {
+    const file = fileForScope(scope, paths);
+    const parsed = parseJsonFile(file) ?? {};
+    if (scope === "local") {
+        const projects = parsed.projects ?? {};
+        const key = projectKeyFor(projects, cwd);
+        const project = projects[key] ?? {};
+        const servers = { ...(project.mcpServers ?? {}) };
+        if (entry === null)
+            delete servers[name];
+        else
+            servers[name] = entry;
+        parsed.projects = { ...projects, [key]: { ...project, mcpServers: servers } };
+    }
+    else {
+        const servers = { ...(parsed.mcpServers ?? {}) };
+        if (entry === null)
+            delete servers[name];
+        else
+            servers[name] = entry;
+        parsed.mcpServers = servers;
+    }
+    return { file, text: writeJson(file, parsed) };
+}
+// ── hooks ──────────────────────────────────────────────────────────────────
+/**
+ * The hook events `bir-hooks` registers, and the control route each drives.
+ *
+ * `PostToolUseFailure` is registered rather than inferred from a `PostToolUse`
+ * payload's shape: a failing tool fires the *failure* event, and a recorder that
+ * 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.
+ */
+export const HOOK_ROUTES = [
+    { event: "SessionStart", route: "/session/start", matcher: "", timeout: 10 },
+    // 15s, not 5s, because this hook now awaits the similar-prompt match before it
+    // can return a steering directive (docs/calculatedReplay.md §10). The wait is
+    // itself bounded by `BIR_MATCH_BUDGET_MS` (2.5s), well inside this; the extra
+    // headroom is for a slow first embed on the service, not for us to spend.
+    //
+    // It must NEVER become `async`. An async hook is fire-and-forget, so it cannot
+    // return `additionalContext` at all — replay would silently never arm.
+    { event: "UserPromptSubmit", route: "/session/prompt", matcher: "", timeout: 15 },
+    // PreToolUse and PostToolUse are likewise NOT async, and that is load-bearing
+    // twice over: correlation needs `updatedInput` back, and a steered replay needs
+    // step N's output threaded into `respParams` *before* step N+1's input is
+    // computed (docs/calculatedReplay.md §7.3).
+    { event: "PreToolUse", route: "/tool/pre", matcher: "*", timeout: 30 },
+    { event: "PostToolUse", route: "/tool/post", matcher: "*", timeout: 30 },
+    { event: "PostToolUseFailure", route: "/tool/post", matcher: "*", timeout: 30 },
+    { event: "SubagentStart", route: "/session/agent", matcher: "", timeout: 5 },
+    { event: "SubagentStop", route: "/session/agent", matcher: "", timeout: 5 },
+    { event: "Stop", route: "/session/stop", matcher: "", timeout: 10 },
+    { event: "StopFailure", route: "/session/stop", matcher: "", timeout: 10 },
+    // NOT async. An async hook is fire-and-forget, and `SessionEnd` fires while the
+    // host is exiting — the exit wins that race and the request is never sent, so
+    // every run was left unfinished on the server. It is cheap to wait for now
+    // (`Stop` has already sealed the run; this only drains the queue), and a run
+    // that is actually finished is worth a few hundred milliseconds at shutdown.
+    { event: "SessionEnd", route: "/session/end", matcher: "", timeout: 30 },
+];
+/** Build the `hooks` block pointing at a control server. */
+export function buildHooksBlock(controlUrl, token) {
+    const base = controlUrl.replace(/\/+$/, "");
+    const block = {};
+    for (const { event, route, matcher, timeout, async } of HOOK_ROUTES) {
+        const hook = {
+            type: "http",
+            url: `${base}${route}`,
+            timeout,
+            headers: { Authorization: `Bearer ${token}` },
+        };
+        if (async)
+            hook.async = true;
+        block[event] = [{ matcher: matcher ?? "", hooks: [hook] }];
+    }
+    return block;
+}
+/** True when a hook entry points at a BaseInstRunner control server. */
+function isBirHook(entry) {
+    const url = entry.url ?? "";
+    return HOOK_ROUTES.some(({ route }) => url.endsWith(route));
+}
+/**
+ * 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.
+ */
+export function installHooks(settingsPath, block) {
+    const parsed = parseJsonFile(settingsPath) ?? {};
+    const hooks = { ...(parsed.hooks ?? {}) };
+    for (const [event, matchers] of Object.entries(block)) {
+        const existing = (hooks[event] ?? []).filter((m) => !(m.hooks ?? []).some((h) => isBirHook(h)));
+        hooks[event] = [...existing, ...matchers];
+    }
+    parsed.hooks = hooks;
+    return writeJson(settingsPath, parsed);
+}
+/** Remove only our hook entries, and drop events left empty. */
+export function uninstallHooks(settingsPath) {
+    const parsed = parseJsonFile(settingsPath);
+    if (!parsed?.hooks)
+        return undefined;
+    const hooks = { ...parsed.hooks };
+    for (const [event, matchers] of Object.entries(hooks)) {
+        const kept = (matchers ?? [])
+            .map((m) => ({ ...m, hooks: (m.hooks ?? []).filter((h) => !isBirHook(h)) }))
+            .filter((m) => m.hooks.length > 0);
+        if (kept.length === 0)
+            delete hooks[event];
+        else
+            hooks[event] = kept;
+    }
+    if (Object.keys(hooks).length === 0)
+        delete parsed.hooks;
+    else
+        parsed.hooks = hooks;
+    return writeJson(settingsPath, parsed);
+}
+//# sourceMappingURL=claude-code.js.map

package/dist/config/adapters/generic.d.ts

@@ -0,0 +1,17 @@
+/**
+ * adapters/generic — the `--config <path>` adapter (Phase 7.6, D8).
+ *
+ * This is what makes "any MCP client" real. Cursor, Codex, an Agent SDK harness
+ * and everything not yet written keep their servers in a file of the shape
+ * `{ "mcpServers": { … } }` — the de-facto standard — but in a location this
+ * project has no business guessing. So the generic path takes the path from the
+ * user and never looks for one.
+ *
+ * There are no scopes here: the file given is the whole configuration, and it is
+ * both the read source and the write target.
+ */
+import { type McpServerConfig } from "../resolve.js";
+export declare function readGenericServers(path: string): Record<string, McpServerConfig>;
+/** Set or delete one entry, preserving every other key in the file. */
+export declare function setGenericServerEntry(path: string, name: string, entry: McpServerConfig | null): string;
+//# sourceMappingURL=generic.d.ts.map

package/dist/config/adapters/generic.js

@@ -0,0 +1,36 @@
+/**
+ * adapters/generic — the `--config <path>` adapter (Phase 7.6, D8).
+ *
+ * This is what makes "any MCP client" real. Cursor, Codex, an Agent SDK harness
+ * and everything not yet written keep their servers in a file of the shape
+ * `{ "mcpServers": { … } }` — the de-facto standard — but in a location this
+ * project has no business guessing. So the generic path takes the path from the
+ * user and never looks for one.
+ *
+ * There are no scopes here: the file given is the whole configuration, and it is
+ * both the read source and the write target.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseJsonFile } from "../resolve.js";
+export function readGenericServers(path) {
+    const parsed = parseJsonFile(path);
+    if (parsed === undefined)
+        throw new Error(`MCP config not readable at ${path}`);
+    return parsed.mcpServers ?? {};
+}
+/** Set or delete one entry, preserving every other key in the file. */
+export function setGenericServerEntry(path, name, entry) {
+    const parsed = parseJsonFile(path) ?? {};
+    const servers = { ...(parsed.mcpServers ?? {}) };
+    if (entry === null)
+        delete servers[name];
+    else
+        servers[name] = entry;
+    parsed.mcpServers = servers;
+    const text = JSON.stringify(parsed, null, 2) + "\n";
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text, "utf8");
+    return text;
+}
+//# sourceMappingURL=generic.js.map

package/dist/config/generate.d.ts

@@ -0,0 +1,127 @@
+/**
+ * config/generate — turn a resolved MCP entry into its proxied twin (Phase 7.2).
+ *
+ * The **key is preserved**, always. The model emits
+ * `mcp__chrome-devtools__navigate_page` and the client routes that name by the
+ * config key; change the key and the name changes with it, which would be a
+ * model-visible edit (a non-goal) as well as a broken scenario corpus.
+ *
+ * Reversibility is not an afterthought (Phase 7.4): the original entry is stashed
+ * verbatim in `~/.baseinstrunner/installed.json` before anything is rewritten, so
+ * `bir uninstall` restores exactly what was there — including fields
+ * BaseInstRunner never understood.
+ */
+import { type McpServerConfig, type Scope } from "./resolve.js";
+/** npm package name, as it appears in a generated `npx -p` invocation. */
+export declare const PACKAGE_NAME = "@basein/runner";
+/**
+ * How the generated entry reaches a `bir` binary.
+ *
+ *   npx     `npx -y -p @basein/runner@<version> bir-proxy` — resolves through the
+ *           registry, so it survives a missing global install. Always pinned:
+ *           an unpinned spec lets two runners provisioned a week apart run
+ *           different proxy versions against the same service, with nothing in
+ *           the recording to say which.
+ *   local   an absolute path into this checkout — developing BaseInstRunner.
+ *   global  an absolute path into the globally installed package. No registry
+ *           round trip, no PATH lookup, works offline. What a fleet wants.
+ *
+ * `local` and `global` produce the same shape; they differ only in where the
+ * caller resolved the path from, and `bir` refuses `--global` when it is not
+ * itself running from an installed package.
+ */
+export type Invocation = "npx" | "local" | "global";
+/**
+ * The `-p` argument for an npx invocation. Unpinned only when no version is
+ * known — every caller inside `bir` knows one.
+ */
+export declare function packageSpec(version?: string): string;
+/**
+ * The config key of the first-party scenario server (docs/calculatedReplay.md §6.3).
+ *
+ * Reserved: `bir install` refuses to wrap a user's own server under this name,
+ * because `mcp__bir__run_scenario` is how a `direct` replay's results reach the
+ * model, and a collision would route that call somewhere else entirely.
+ */
+export declare const SCENARIO_SERVER_KEY = "bir";
+export interface WrapOptions {
+    serverName: string;
+    /** Injected as `BIR_CONTROL_URL` so an SDK session needs no discovery file. */
+    controlUrl?: string;
+    /** Emit `--no-correlation` so this server is never schema-relaxed. */
+    noCorrelation?: boolean;
+    /**
+     * How to invoke the proxy. `"npx"` (default) survives a global install being
+     * absent; `"local"` points at this checkout's built entry point, which is what
+     * you want while developing BaseInstRunner itself.
+     */
+    invocation?: Invocation;
+    /** Absolute path to `dist/bin/bir-proxy.js`, for `local` and `global`. */
+    proxyPath?: string;
+    /** Pins the npx spec. Omitted only by tests that do not care which version. */
+    version?: string;
+}
+/** A wrapped entry is always a stdio entry: the proxy is the process the host spawns. */
+export interface WrappedEntry {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+/** True when this entry already points at `bir-proxy` — makes install idempotent. */
+export declare function isWrapped(config: McpServerConfig): boolean;
+/**
+ * Build the proxied entry for `config`. Everything after `--` is the original
+ * invocation, passed through untouched so the upstream is spawned exactly as the
+ * host would have spawned it.
+ */
+export declare function wrapEntry(config: McpServerConfig, opts: WrapOptions): WrappedEntry;
+/**
+ * The entry for the scenario server itself. Not a proxy: it wraps nothing and
+ * spawns nothing, it just forwards one call to the control server.
+ */
+export declare function scenarioEntry(opts: {
+    invocation?: Invocation;
+    scenarioPath?: string;
+    controlUrl?: string;
+    version?: string;
+}): WrappedEntry;
+/** True when this entry is the scenario server — makes `install --replay` idempotent. */
+export declare function isScenarioServer(config: McpServerConfig): boolean;
+export interface InstalledRecord {
+    /** Original entry, verbatim. `null` means the entry did not exist before. */
+    original: McpServerConfig | null;
+    scope: Scope;
+    /** File the entry was written to, so uninstall edits the same one. */
+    file: string;
+    cwd: string;
+    installedAt: number;
+}
+/**
+ * A file we edited, captured before the first edit.
+ *
+ * `writtenSha` is the hash of what *we* left behind. On uninstall a file that
+ * still hashes to it is restored from `originalText` **byte-for-byte**; a file
+ * edited since is repaired entry-by-entry instead, because clobbering somebody's
+ * later edit is worse than an imperfect restore.
+ */
+export interface FileBackup {
+    originalText: string | null;
+    writtenSha: string;
+}
+export interface InstalledSidecar {
+    version: 1;
+    /** Stable loopback token written into the hook settings at install time. */
+    token?: string;
+    /** Port the hook settings were written with. */
+    controlPort?: number;
+    /** `<cwd>::<serverName>` → record. */
+    servers: Record<string, InstalledRecord>;
+    /** Absolute path → the text that was there before we touched it. */
+    files?: Record<string, FileBackup>;
+    /** Settings files whose `hooks` block we added, for a clean uninstall. */
+    hookFiles?: string[];
+}
+export declare function readSidecar(): InstalledSidecar;
+export declare function writeSidecar(sidecar: InstalledSidecar): void;
+export declare function sidecarKey(cwd: string, serverName: string): string;
+//# sourceMappingURL=generate.d.ts.map

package/dist/config/generate.js

@@ -0,0 +1,114 @@
+/**
+ * config/generate — turn a resolved MCP entry into its proxied twin (Phase 7.2).
+ *
+ * The **key is preserved**, always. The model emits
+ * `mcp__chrome-devtools__navigate_page` and the client routes that name by the
+ * config key; change the key and the name changes with it, which would be a
+ * model-visible edit (a non-goal) as well as a broken scenario corpus.
+ *
+ * Reversibility is not an afterthought (Phase 7.4): the original entry is stashed
+ * verbatim in `~/.baseinstrunner/installed.json` before anything is rewritten, so
+ * `bir uninstall` restores exactly what was there — including fields
+ * BaseInstRunner never understood.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { configDir, ensureDir, installedPath } from "../control/paths.js";
+import { isRemote } from "./resolve.js";
+/** npm package name, as it appears in a generated `npx -p` invocation. */
+export const PACKAGE_NAME = "@basein/runner";
+/**
+ * The `-p` argument for an npx invocation. Unpinned only when no version is
+ * known — every caller inside `bir` knows one.
+ */
+export function packageSpec(version) {
+    return version ? `${PACKAGE_NAME}@${version}` : PACKAGE_NAME;
+}
+/**
+ * The config key of the first-party scenario server (docs/calculatedReplay.md §6.3).
+ *
+ * Reserved: `bir install` refuses to wrap a user's own server under this name,
+ * because `mcp__bir__run_scenario` is how a `direct` replay's results reach the
+ * model, and a collision would route that call somewhere else entirely.
+ */
+export const SCENARIO_SERVER_KEY = "bir";
+/** True when this entry already points at `bir-proxy` — makes install idempotent. */
+export function isWrapped(config) {
+    if (isRemote(config))
+        return false;
+    const argv = [config.command, ...(config.args ?? [])].join(" ");
+    return /\bbir-proxy\b/.test(argv);
+}
+/**
+ * Build the proxied entry for `config`. Everything after `--` is the original
+ * invocation, passed through untouched so the upstream is spawned exactly as the
+ * host would have spawned it.
+ */
+export function wrapEntry(config, opts) {
+    const proxyArgs = ["--server-name", opts.serverName];
+    if (opts.noCorrelation)
+        proxyArgs.push("--no-correlation");
+    if (isRemote(config)) {
+        proxyArgs.push("--url", config.url, "--transport", config.type);
+        for (const [key, value] of Object.entries(config.headers ?? {})) {
+            // §9: the proxy holds the credential for a remote upstream, because the
+            // host's own OAuth now authenticates *us*. It is passed at spawn and never
+            // written to BaseInstRunner's own state.
+            proxyArgs.push("--header", `${key}:${value}`);
+        }
+    }
+    else {
+        proxyArgs.push("--", config.command, ...(config.args ?? []));
+    }
+    const env = {};
+    if (opts.controlUrl)
+        env.BIR_CONTROL_URL = opts.controlUrl;
+    if (!isRemote(config)) {
+        for (const [key, value] of Object.entries(config.env ?? {}))
+            env[key] = value;
+    }
+    const invocation = opts.invocation ?? "npx";
+    const entry = invocation !== "npx" && opts.proxyPath
+        ? { command: process.execPath, args: [opts.proxyPath, ...proxyArgs] }
+        : { command: "npx", args: ["-y", "-p", packageSpec(opts.version), "bir-proxy", ...proxyArgs] };
+    if (Object.keys(env).length > 0)
+        entry.env = env;
+    return entry;
+}
+/**
+ * The entry for the scenario server itself. Not a proxy: it wraps nothing and
+ * spawns nothing, it just forwards one call to the control server.
+ */
+export function scenarioEntry(opts) {
+    const entry = opts.invocation && opts.invocation !== "npx" && opts.scenarioPath
+        ? { command: process.execPath, args: [opts.scenarioPath] }
+        : { command: "npx", args: ["-y", "-p", packageSpec(opts.version), "bir-scenario"] };
+    if (opts.controlUrl)
+        entry.env = { BIR_CONTROL_URL: opts.controlUrl };
+    return entry;
+}
+/** True when this entry is the scenario server — makes `install --replay` idempotent. */
+export function isScenarioServer(config) {
+    if (isRemote(config))
+        return false;
+    return /\bbir-scenario\b/.test([config.command, ...(config.args ?? [])].join(" "));
+}
+export function readSidecar() {
+    const path = installedPath();
+    if (!existsSync(path))
+        return { version: 1, servers: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return { version: 1, servers: parsed.servers ?? {}, ...parsed };
+    }
+    catch {
+        return { version: 1, servers: {} };
+    }
+}
+export function writeSidecar(sidecar) {
+    ensureDir(configDir());
+    writeFileSync(installedPath(), JSON.stringify(sidecar, null, 2), { mode: 0o600 });
+}
+export function sidecarKey(cwd, serverName) {
+    return `${cwd}::${serverName}`;
+}
+//# sourceMappingURL=generate.js.map

package/dist/config/resolve.d.ts

@@ -0,0 +1,68 @@
+/**
+ * config/resolve — which MCP servers a client would actually use for a cwd.
+ *
+ * Ported from RRepeat's `mcp-registry.ts`, and extended to report **which scope
+ * won**, because that is what Phase 7.3 needs: rewriting a file whose entry is
+ * shadowed by a higher-precedence scope changes nothing at all, and the user is
+ * left with an install that never runs.
+ *
+ * Claude Code merges three scopes, highest precedence first. The whole winning
+ * entry is used — fields are never merged across scopes:
+ *   1. **Local**   — `~/.claude.json` → `projects[<cwd>].mcpServers`
+ *   2. **Project** — `<cwd>/.mcp.json` → `mcpServers`
+ *   3. **User**    — `~/.claude.json` → top-level `mcpServers`
+ *
+ * THE WINDOWS PATH TRAP (Phase 7.1). Claude Code stores the local-scope project
+ * key with forward slashes while `process.cwd()` returns backslashes, and it
+ * keeps one entry per spelling it has seen — so the backslash twin routinely
+ * exists carrying `mcpServers: {}` while the forward-slash one holds the real
+ * config. Matching the literal key misses every time; matching a *normalised*
+ * path, and refusing to stop at an empty twin, is what makes local scope work.
+ */
+/** A stdio server entry. `type` is optional in Claude Code's own files. */
+export interface StdioServerConfig {
+    type?: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+/** A remote server entry (streamable HTTP or legacy SSE). */
+export interface RemoteServerConfig {
+    type: "http" | "sse";
+    url: string;
+    headers?: Record<string, string>;
+}
+export type McpServerConfig = StdioServerConfig | RemoteServerConfig;
+export type Scope = "local" | "project" | "user" | "explicit";
+export interface ResolvedServer {
+    name: string;
+    config: McpServerConfig;
+    /** The scope whose entry won. Writing to any lower one is a no-op. */
+    scope: Scope;
+    /** Scopes that also define this name and are shadowed by `scope`. */
+    shadowed: Scope[];
+}
+export interface ResolveOptions {
+    /** Override the `~/.claude.json` location (tests). */
+    claudeJsonPath?: string;
+    /** A single explicit `{ mcpServers }` file — no scope merging (`--config`). */
+    configPath?: string;
+}
+export declare function isRemote(config: McpServerConfig): config is RemoteServerConfig;
+/** Parse a JSON file. `undefined` if absent; throws if present but malformed. */
+export declare function parseJsonFile(path: string): unknown;
+export declare function claudeJsonPath(override?: string): string;
+/**
+ * The local scope's servers for `cwd`. The literal key is tried first, then
+ * every key is compared as a normalised path — and a key resolving to *no*
+ * servers does not end the search, because the empty twin is exactly the shape
+ * the Windows miss takes on disk.
+ */
+export declare function projectScope(projects: Record<string, {
+    mcpServers?: Record<string, McpServerConfig>;
+}> | undefined, cwd: string): Record<string, McpServerConfig>;
+/** The key under which Claude Code stores (or would store) this cwd's local scope. */
+export declare function projectKeyFor(projects: Record<string, unknown> | undefined, cwd: string): string;
+/** Every MCP server that would be live for `cwd`, with the scope that won. */
+export declare function resolveServers(cwd: string, opts?: ResolveOptions): ResolvedServer[];
+//# sourceMappingURL=resolve.d.ts.map