@bridge_gpt/mcp-server 0.1.16 → 0.2.0

package/build/credential-store.js

@@ -0,0 +1,232 @@
+/**
+ * Resolver for Tier-1 bridge-api credentials.
+ *
+ * Resolution order is env-first, then a user-scoped credentials file:
+ *   1. `BAPI_API_KEY` in the process environment (overrides everything).
+ *   2. `$XDG_CONFIG_HOME/bridge/credentials.json` (or `~/.config/bridge/credentials.json`).
+ *   3. `~/.bridge/credentials.json` (only when the primary path is absent).
+ *
+ * The file is keyed by a logical target `bapi:<repoName>`. This module NEVER
+ * creates or initializes credential files, and NEVER places secret values in
+ * thrown errors, returned error strings, or stderr warnings.
+ */
+import path from "path";
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+/** Primary store path: honors a non-empty `XDG_CONFIG_HOME`, else `~/.config`. */
+export function getPrimaryCredentialStorePath(deps) {
+    const xdg = deps.env.XDG_CONFIG_HOME;
+    if (xdg && xdg.trim().length > 0) {
+        return path.join(xdg, "bridge", "credentials.json");
+    }
+    return path.join(deps.homedir(), ".config", "bridge", "credentials.json");
+}
+/** Fallback store path: `~/.bridge/credentials.json`. */
+export function getFallbackCredentialStorePath(deps) {
+    return path.join(deps.homedir(), ".bridge", "credentials.json");
+}
+/**
+ * Choose which store path to read. The primary path is preferred and used
+ * whenever it exists. The fallback is only consulted when the primary is
+ * *absent* (`ENOENT`); a primary that exists but is unreadable does NOT fall
+ * back — the caller surfaces the read error instead.
+ */
+export async function resolveCredentialStorePath(deps) {
+    const primaryPath = getPrimaryCredentialStorePath(deps);
+    const fallbackPath = getFallbackCredentialStorePath(deps);
+    try {
+        await deps.stat(primaryPath);
+        return { found: true, path: primaryPath, isPrimary: true };
+    }
+    catch (err) {
+        const code = err && typeof err === "object" ? err.code : undefined;
+        if (code !== "ENOENT") {
+            // The primary exists but is not statable cleanly — do NOT fall back; let
+            // the subsequent read surface the real error against the primary path.
+            return { found: true, path: primaryPath, isPrimary: true };
+        }
+    }
+    try {
+        await deps.stat(fallbackPath);
+        return { found: true, path: fallbackPath, isPrimary: false };
+    }
+    catch {
+        return { found: false, primaryPath, fallbackPath };
+    }
+}
+// ---------------------------------------------------------------------------
+// Permission warning
+// ---------------------------------------------------------------------------
+/**
+ * On POSIX platforms, warn (but continue) when the credentials file is
+ * group/world accessible. Skipped entirely on Windows. The warning mentions
+ * `0600` but never any secret value.
+ */
+export function warnIfInsecureCredentialFileMode(statResult, platform, filePath, stderr) {
+    if (platform === "win32")
+        return;
+    if ((statResult.mode & 0o077) !== 0) {
+        const write = stderr ?? ((m) => process.stderr.write(`${m}\n`));
+        write(`Warning: credentials file ${filePath} is group/world-accessible; ` +
+            `it should be mode 0600 (run: chmod 600 ${filePath}).`);
+    }
+}
+// ---------------------------------------------------------------------------
+// JSON parsing / validation
+// ---------------------------------------------------------------------------
+/**
+ * Parse and structurally validate the credentials JSON. The root must be an
+ * object whose values are objects of secret-name -> string. Secret *values* are
+ * never echoed into error messages (only logical keys and secret names appear).
+ */
+export function parseCredentialStoreJson(text) {
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, error: "credentials file is not valid JSON" };
+    }
+    if (data === null || typeof data !== "object" || Array.isArray(data)) {
+        return { ok: false, error: "credentials file must be a JSON object" };
+    }
+    for (const [key, value] of Object.entries(data)) {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            return {
+                ok: false,
+                error: `credentials entry "${key}" must be an object of secret names to strings`,
+            };
+        }
+        for (const [secretName, secretValue] of Object.entries(value)) {
+            if (typeof secretValue !== "string") {
+                return {
+                    ok: false,
+                    error: `credentials entry "${key}" has a non-string value for "${secretName}"`,
+                };
+            }
+        }
+    }
+    return { ok: true, value: data };
+}
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+/** Collect trimmed, non-empty env values for the requested keys. */
+function collectEnvValues(env, requiredKeys) {
+    const values = {};
+    const missing = [];
+    for (const key of requiredKeys) {
+        const raw = (env[key] ?? "").trim();
+        if (raw.length > 0) {
+            values[key] = raw;
+        }
+        else {
+            missing.push(key);
+        }
+    }
+    return { values, missing };
+}
+/**
+ * Resolve a logical credential bundle env-first, then from the user-scoped
+ * credentials file. `bundleKey` is the logical store key (e.g. `bapi:<repo>` or
+ * `sfcc:<sandbox-id>`); `requiredKeys` is the exact set of secret names that
+ * must all resolve.
+ *
+ * Behavior:
+ *   - Environment is consulted first. If EVERY required key is present in the
+ *     environment (trimmed, non-empty), the store is NEVER read and `source` is
+ *     `"env"`.
+ *   - Only when one or more keys are missing from the environment is the store
+ *     read (exactly once). Env values override store values key-by-key.
+ *   - The result fails unless every required key resolves.
+ *
+ * Error messages reference only the logical bundle key, the missing secret
+ * names, and the expected store path — never a secret value. Never creates
+ * files.
+ */
+export async function resolveCredentialBundle(bundleKey, requiredKeys, deps) {
+    const primaryPath = getPrimaryCredentialStorePath(deps);
+    const fromEnv = collectEnvValues(deps.env, requiredKeys);
+    if (fromEnv.missing.length === 0) {
+        return { ok: true, values: fromEnv.values, source: "env" };
+    }
+    const resolution = await resolveCredentialStorePath(deps);
+    if (!resolution.found) {
+        return {
+            ok: false,
+            kind: "not-found",
+            error: `No credentials found for "${bundleKey}". Set ${fromEnv.missing.join(", ")} in the ` +
+                `environment, or add them under "${bundleKey}" in ${primaryPath}.`,
+        };
+    }
+    // Permission warning is best-effort and must not block resolution.
+    try {
+        const statResult = await deps.stat(resolution.path);
+        warnIfInsecureCredentialFileMode(statResult, deps.platform, resolution.path, deps.stderr);
+    }
+    catch {
+        /* stat failure here is non-fatal; the read below surfaces real errors */
+    }
+    let raw;
+    try {
+        raw = await deps.readFile(resolution.path);
+    }
+    catch {
+        return {
+            ok: false,
+            kind: "read-error",
+            error: `Unable to read credentials file at ${resolution.path}.`,
+        };
+    }
+    const parsed = parseCredentialStoreJson(raw);
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            kind: "parse-error",
+            error: `Invalid credentials file at ${resolution.path}: ${parsed.error}.`,
+        };
+    }
+    const entry = parsed.value[bundleKey] ?? {};
+    const values = { ...fromEnv.values };
+    const stillMissing = [];
+    for (const key of fromEnv.missing) {
+        // Trim store values exactly like the env path (collectEnvValues), so a
+        // credential pasted into credentials.json with a trailing newline/space is
+        // never sent verbatim in an auth header. Assign the TRIMMED value.
+        const storeValue = typeof entry[key] === "string" ? entry[key].trim() : "";
+        if (storeValue.length > 0) {
+            values[key] = storeValue;
+        }
+        else {
+            stillMissing.push(key);
+        }
+    }
+    if (stillMissing.length > 0) {
+        return {
+            ok: false,
+            kind: "missing-key",
+            error: `No usable value(s) for ${stillMissing.join(", ")} in "${bundleKey}". Add them under ` +
+                `"${bundleKey}" in ${primaryPath}, or set them in the environment.`,
+        };
+    }
+    return { ok: true, values, source: "file" };
+}
+/**
+ * Resolve the `BAPI_API_KEY` for `bapi:<repoName>`. Delegates to the generic
+ * {@link resolveCredentialBundle} with bundle key `bapi:${repoName}` and the
+ * single required key `BAPI_API_KEY`, preserving the historical public return
+ * shape (`{ apiKey, source }`) relied on by `mcp-invoke` and `index.ts`. Env
+ * wins (trimmed, non-empty); otherwise the credentials file is read. Never
+ * leaks secret values; never creates files.
+ */
+export async function resolveBapiCredentials(repoName, deps) {
+    const result = await resolveCredentialBundle(`bapi:${repoName}`, ["BAPI_API_KEY"], deps);
+    if (!result.ok) {
+        return { ok: false, kind: result.kind, error: result.error };
+    }
+    return {
+        ok: true,
+        credentials: { apiKey: result.values.BAPI_API_KEY, source: result.source },
+    };
+}

package/build/decision-page-schema.js

@@ -19,8 +19,8 @@ export const ActionableItemSchema = z
     question: z.string().min(1),
     original_question: z
         .string()
-        .min(1)
-        .describe("The clarifying question or critique point as originally raised; soft cap ~30 words."),
+        .optional()
+        .describe("Optional display-only field: the clarifying question or critique point as originally raised; soft cap ~30 words. Omit it (or pass an empty string) for non-review callers — the renderer omits the section when it is absent or blank."),
     why_it_matters: z
         .string()
         .min(1)
@@ -31,12 +31,12 @@ export const ActionableItemSchema = z
         .describe("Why the recommended branch is the best choice; soft cap ~60 words."),
     codebase_evidence: z
         .string()
-        .min(1)
-        .describe("Combined Assessment paragraph and Codebase Evidence bullet list. Rendered as escaped plain text inside a closed-by-default <details> block."),
+        .optional()
+        .describe("Optional display-only field: combined Assessment paragraph and Codebase Evidence bullet list. Rendered as escaped plain text inside a closed-by-default <details> block, which is omitted when this field is absent or blank."),
     source: z
         .string()
-        .min(1)
-        .describe("Source reference from the combined review-and-resolution doc, e.g. 'Clarifying Q3 (prior round, weak concurrence)'"),
+        .optional()
+        .describe("Optional source reference from the combined review-and-resolution doc, e.g. 'Clarifying Q3 (prior round, weak concurrence)'. When absent the rendered card emits data-source=\"\"."),
     recommendation_index: z
         .number()
         .int()
@@ -69,12 +69,45 @@ export const ActionableItemSchema = z
         });
     }
 });
+// Optional presentation labels that override the page's review-flavored copy.
+// Every field is optional and may be an explicitly empty string (no .min(1)) so
+// a caller can intentionally render an empty heading/title segment. The renderer
+// merges these with raw default constants using nullish coalescing, so an
+// explicit "" is preserved rather than falling back to a default.
+export const DecisionPageLabelsSchema = z.object({
+    title: z
+        .string()
+        .optional()
+        .describe('Overrides the page <title>/<h1> lead text (default "Review Decisions").'),
+    intro: z
+        .string()
+        .optional()
+        .describe("Overrides the actionable-page intro copy shown when there are decisions."),
+    section_heading: z
+        .string()
+        .optional()
+        .describe('Overrides the decision cards <h2> (default "Review Decisions").'),
+    improvements_heading: z
+        .string()
+        .optional()
+        .describe('Overrides the confirmed-improvements <h2> (default "Confirmed Improvements").'),
+});
 // Raw input shape for the `generate_decision_page` tool registration.
 // MCP's registerTool expects a shape object (which the SDK wraps in z.object),
 // not a pre-built z.object. Exporting the shape lets index.ts and the schema
 // share a single source of truth for the input contract.
 export const DecisionPageInputShape = {
     ticket_key: z.string().describe("Jira ticket key, e.g. BAPI-123"),
+    output_subdir: z
+        .string()
+        .optional()
+        .default("review")
+        .describe('Optional docs-relative subdirectory to write the page under (default "review"). Validated strictly: no absolute paths, backslashes, ".." segments, null bytes, or encoded path tokens.'),
+    output_filename: z
+        .string()
+        .optional()
+        .describe('Optional output filename (default "${ticket_key}-decisions.html"). Must end with .html and contain no path separators; the .html suffix is required and never auto-appended.'),
+    labels: DecisionPageLabelsSchema.optional().describe("Optional presentation-label overrides (title, intro, section_heading, improvements_heading). Presentation-only; does not change data-testid hooks or the submitted JSON shape."),
     actionable_items: z
         .array(ActionableItemSchema)
         .optional()

package/build/decision-page-template.js

@@ -31,6 +31,30 @@ const COPY_SUCCESS_LABEL = "Copied!";
 const COPY_FALLBACK_PROMPT_LABEL = "Auto-copy unavailable. Press Ctrl+C / Cmd+C to copy.";
 const PAGE_INTRO_ASK_COPY = "Have a question about an item? Choose 'Ask about this' for that card; we'll discuss before the changes are made.";
 const PAGE_INTRO_NO_DECISIONS = "All suggestions were confirmed as improvements. No decisions are needed from you.";
+// Raw (unescaped) default label constants. They reproduce the legacy review copy
+// exactly so omitting `labels` yields byte-identical output. Escaping happens at
+// each render site, so these must stay raw to avoid double-escaping.
+const DEFAULT_LABEL_TITLE = "Review Decisions";
+const DEFAULT_LABEL_INTRO = PAGE_INTRO_ASK_COPY;
+const DEFAULT_LABEL_SECTION_HEADING = "Review Decisions";
+const DEFAULT_LABEL_IMPROVEMENTS_HEADING = "Confirmed Improvements";
+/**
+ * Merge caller-supplied labels with the raw default constants using nullish
+ * coalescing (`??`), NOT logical OR — an explicit empty-string label is an
+ * intentional override and must be preserved rather than replaced by a default.
+ */
+function resolveDecisionPageLabels(labels) {
+    return {
+        title: labels?.title ?? DEFAULT_LABEL_TITLE,
+        intro: labels?.intro ?? DEFAULT_LABEL_INTRO,
+        section_heading: labels?.section_heading ?? DEFAULT_LABEL_SECTION_HEADING,
+        improvements_heading: labels?.improvements_heading ?? DEFAULT_LABEL_IMPROVEMENTS_HEADING,
+    };
+}
+/** True only when a string is present and not whitespace-only. */
+function hasDisplayText(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
 // ---------------------------------------------------------------------------
 // Template
 // ---------------------------------------------------------------------------
@@ -38,17 +62,21 @@ const DEFAULT_ASSETS = { faviconBase64: "", logoBase64: "", fontsRelPath: "" };
 export function generateDecisionPageHtml(data, assets = DEFAULT_ASSETS) {
     const { ticket_key, actionable_items, clear_improvements } = data;
     const hasDecisions = actionable_items.length > 0;
+    const effectiveLabels = resolveDecisionPageLabels(data.labels);
     const faviconLink = assets.faviconBase64
         ? `<link rel="icon" type="image/png" sizes="32x32" href="data:image/png;base64,${assets.faviconBase64}">`
         : "";
     const fontFaces = assets.fontsRelPath ? renderFontFaces(assets.fontsRelPath) : "";
-    const pageIntro = hasDecisions ? PAGE_INTRO_ASK_COPY : PAGE_INTRO_NO_DECISIONS;
+    // The has-decisions intro is an overridable label; the no-decisions copy is a
+    // fixed constant because the MCP handler returns before rendering in that path
+    // (this branch is only reachable from direct renderer callers/tests).
+    const pageIntro = hasDecisions ? effectiveLabels.intro : PAGE_INTRO_NO_DECISIONS;
     return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Review Decisions: ${escapeHtml(ticket_key)}</title>
+  <title>${escapeHtml(effectiveLabels.title)}: ${escapeHtml(ticket_key)}</title>
   ${faviconLink}
   <style>
 ${fontFaces}
@@ -407,12 +435,12 @@ ${fontFaces}
 ${renderHeader(assets)}
   <main class="main-content">
     <div class="container">
-      <h1>Review Decisions: ${escapeHtml(ticket_key)}</h1>
+      <h1>${escapeHtml(effectiveLabels.title)}: ${escapeHtml(ticket_key)}</h1>
       <p class="page-intro">${escapeHtml(pageIntro)}</p>
 
-${hasDecisions ? renderForm(data) : renderNoDecisions()}
+${hasDecisions ? renderForm(data, effectiveLabels) : renderNoDecisions()}
 
-${renderImprovements(clear_improvements)}
+${renderImprovements(clear_improvements, effectiveLabels)}
 
     </div>
   </main>
@@ -466,13 +494,13 @@ function renderNoDecisions() {
         <p>No decisions needed. All suggestions were confirmed as improvements.</p>
       </div>`;
 }
-function renderForm(data) {
+function renderForm(data, labels) {
     const { actionable_items } = data;
     let html = `      <div id="form-container">
         <form id="decision-form">`;
     if (actionable_items.length > 0) {
         html += `
-          <h2>Review Decisions</h2>`;
+          <h2>${escapeHtml(labels.section_heading)}</h2>`;
         for (const item of actionable_items) {
             html += renderDecisionItem(item);
         }
@@ -547,13 +575,25 @@ function renderDecisionItem(item) {
               </div>`;
     // Encode option labels for client-side JS to resolve chosen_label
     const labelsJson = escapeHtml(JSON.stringify(item.options));
-    return `
-          <section class="card" data-item-id="${id}" data-item-type="decision" data-source="${escapeHtml(item.source)}" data-labels="${labelsJson}" data-testid="decision-card" aria-labelledby="${titleId}">
-            <h3 class="card-title" id="${titleId}" data-testid="decision-card-title">${escapeHtml(item.question)}</h3>
+    // Optional review-flavored display sections: omit entirely when the field is
+    // missing, empty, or whitespace-only so non-review callers can skip them.
+    const originalQuestionSection = hasDisplayText(item.original_question)
+        ? `
             <section class="card-section" data-testid="original-question-section" aria-labelledby="${originalQuestionLabelId}">
               <div class="card-section-label" id="${originalQuestionLabelId}">Original question</div>
               <div class="card-section-body" data-testid="original-question-body">${escapeHtml(item.original_question)}</div>
-            </section>
+            </section>`
+        : "";
+    const codebaseEvidenceSection = hasDisplayText(item.codebase_evidence)
+        ? `
+            <details class="codebase-evidence" data-testid="codebase-evidence">
+              <summary>Codebase evidence</summary>
+              <div class="codebase-evidence-body" data-testid="codebase-evidence-body">${escapeHtml(item.codebase_evidence)}</div>
+            </details>`
+        : "";
+    return `
+          <section class="card" data-item-id="${id}" data-item-type="decision" data-source="${escapeHtml(item.source ?? "")}" data-labels="${labelsJson}" data-testid="decision-card" aria-labelledby="${titleId}">
+            <h3 class="card-title" id="${titleId}" data-testid="decision-card-title">${escapeHtml(item.question)}</h3>${originalQuestionSection}
             <section class="card-section" data-testid="why-it-matters-section" aria-labelledby="${whyItMattersLabelId}">
               <div class="card-section-label" id="${whyItMattersLabelId}">Why it matters</div>
               <div class="card-section-body" data-testid="why-it-matters-body">${escapeHtml(item.why_it_matters)}</div>
@@ -568,14 +608,10 @@ function renderDecisionItem(item) {
             <div class="comment-area">
               <label for="${textareaId}">Comment</label>
               <textarea id="${textareaId}" name="${textareaId}" placeholder="Required for None of these selections..." data-testid="decision-comment"></textarea>
-            </div>
-            <details class="codebase-evidence" data-testid="codebase-evidence">
-              <summary>Codebase evidence</summary>
-              <div class="codebase-evidence-body" data-testid="codebase-evidence-body">${escapeHtml(item.codebase_evidence)}</div>
-            </details>
+            </div>${codebaseEvidenceSection}
           </section>`;
 }
-function renderImprovements(improvements) {
+function renderImprovements(improvements, labels) {
     if (improvements.length === 0)
         return "";
     let items = "";
@@ -593,7 +629,7 @@ function renderImprovements(improvements) {
           </li>`;
     }
     return `      <section data-testid="confirmed-improvements">
-      <h2>Confirmed Improvements</h2>
+      <h2>${escapeHtml(labels.improvements_heading)}</h2>
       <p>These improvements have been confirmed and will be applied. No action needed from you.</p>
       <ul class="improvements-list">${items}
       </ul>

package/build/doctor.js

@@ -14,6 +14,8 @@
  * spawning, no MCP server startup. It only ever runs read-only PATH probes
  * (`which`/`where`, `bash --version`, `git rev-parse`) through the injected deps.
  */
+import { readFile, stat } from "fs/promises";
+import os from "os";
 import { createDefaultStartTicketsDeps } from "./start-tickets.js";
 import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
 import { getDoctorPrereqDescriptors, probePrerequisite, } from "./start-tickets-prereqs.js";
@@ -32,7 +34,8 @@ export function getDoctorUsage() {
         "  -h, --help                    Show this help",
         "",
         "Checks (for the current OS): the start-tickets preflight prerequisites plus",
-        "uv plus the selected agent's command.",
+        "uv, the selected agent's command, Bridge API credential resolution, and",
+        "worktree MCP registration reachability.",
         "",
         "Exit code: 0 when all required prerequisites are present, non-zero otherwise.",
     ].join("\n");
@@ -100,9 +103,22 @@ export async function collectDoctorResults(deps, agentName) {
     if (!descriptorsResult.ok) {
         return { ok: false, unsupported: true, error: descriptorsResult.error };
     }
+    // Augment with read-only filesystem deps so the doctor-only credential and
+    // worktree-MCP-registration probes can run. These are intentionally NOT part
+    // of StartTicketsDeps (live preflight never reads files); doctor injects them
+    // here, and they remain strictly read-only (readFile/stat/homedir only). If a
+    // caller (e.g. a unit test) already supplied them on `deps`, honor those so
+    // the probes are deterministic.
+    const injected = deps;
+    const probeDeps = {
+        ...deps,
+        readFile: injected.readFile ?? ((p) => readFile(p, "utf-8")),
+        stat: injected.stat ?? ((p) => stat(p)),
+        homedir: injected.homedir ?? os.homedir,
+    };
     const results = [];
     for (const descriptor of descriptorsResult.descriptors) {
-        results.push(await probePrerequisite(deps, descriptor));
+        results.push(await probePrerequisite(probeDeps, descriptor));
     }
     return { ok: true, results };
 }

package/build/fetch-stub.js

@@ -0,0 +1,139 @@
+/**
+ * Hand-rolled global ``fetch`` stub for the pipeline-orchestrator tests.
+ *
+ * Replaces the undici MockAgent/setGlobalDispatcher mocking that broke when
+ * Dependabot bumped undici past Node's bundled copy. Instead of intercepting
+ * Node's internal dispatcher, we swap ``globalThis.fetch`` itself: the stub
+ * matches registered routes by method + path (string-exact or RegExp) +
+ * optional query subset, records every call for assertions, and throws loudly
+ * on any unmatched request so nothing escapes to the real network (the
+ * ``agent.disableNetConnect()`` equivalent). It depends only on Node's global
+ * ``Response``/``Headers``/``URL`` — no package required, and no coupling to
+ * Node's bundled undici version.
+ *
+ * Two registration styles mirror undici's ``.intercept().reply(...)``:
+ *  - ``replyOnce(spec, status, body, responseOptions?)`` — a one-shot route
+ *    consumed FIFO; matches a single request, like an undici interceptor. Used
+ *    by the persistence and execution tests (including tests that register two
+ *    responses for the same method+path to be returned in order).
+ *  - ``route(spec, handler)`` — a persistent route whose handler runs on every
+ *    matching request. The handler receives the captured call and returns
+ *    ``{ statusCode, data, responseOptions }`` — the same shape undici's
+ *    ``reply((opts) => ...)`` callback returned — so stateful fakes port over
+ *    almost verbatim.
+ */
+export class FetchStub {
+    original;
+    routes = [];
+    /** Every request seen since the last ``reset()``, in order. */
+    calls = [];
+    /** Replace ``globalThis.fetch`` with the stub. */
+    install() {
+        this.original = globalThis.fetch;
+        globalThis.fetch = ((input, init) => this.handle(input, init));
+    }
+    /** Restore the original ``globalThis.fetch``. */
+    restore() {
+        if (this.original)
+            globalThis.fetch = this.original;
+        this.original = undefined;
+    }
+    /** Clear all registered routes and recorded calls (per-test reset). */
+    reset() {
+        this.routes = [];
+        this.calls = [];
+    }
+    /** Register a persistent route that matches every qualifying request. */
+    route(spec, handler) {
+        this.routes.push({ spec, handler, once: false, consumed: false });
+        return this;
+    }
+    /**
+     * Register a one-shot route consumed FIFO — mirrors a single undici
+     * ``.intercept(spec).reply(status, body, responseOptions)``. Object bodies
+     * are JSON-serialized (and default to ``content-type: application/json``
+     * unless the caller set one); string bodies pass through untouched.
+     */
+    replyOnce(spec, status, body, responseOptions) {
+        const isObjectBody = body !== undefined && body !== null && typeof body === "object";
+        const data = body === undefined || body === null
+            ? ""
+            : typeof body === "string"
+                ? body
+                : JSON.stringify(body);
+        const headers = { ...(responseOptions?.headers ?? {}) };
+        if (isObjectBody &&
+            !Object.keys(headers).some((k) => k.toLowerCase() === "content-type")) {
+            headers["content-type"] = "application/json";
+        }
+        this.routes.push({
+            spec,
+            handler: () => ({ statusCode: status, data, responseOptions: { headers } }),
+            once: true,
+            consumed: false,
+        });
+        return this;
+    }
+    handle(input, init) {
+        const opts = (init ?? {});
+        const rawUrl = typeof input === "string"
+            ? input
+            : input instanceof URL
+                ? input.toString()
+                : String(input?.url ?? input);
+        const url = new URL(rawUrl);
+        const method = (opts.method ?? "GET").toUpperCase();
+        const headers = new Headers(opts.headers ?? {});
+        const body = opts.body === undefined || opts.body === null
+            ? undefined
+            : String(opts.body);
+        const call = {
+            url,
+            path: url.pathname + url.search,
+            method,
+            headers,
+            body,
+            json: () => JSON.parse(body ?? ""),
+        };
+        this.calls.push(call);
+        for (const r of this.routes) {
+            if (r.once && r.consumed)
+                continue;
+            if (!FetchStub.matches(r.spec, call))
+                continue;
+            if (r.once)
+                r.consumed = true;
+            const result = r.handler(call);
+            return Promise.resolve(new Response(result.data ?? "", {
+                status: result.statusCode,
+                headers: result.responseOptions?.headers ?? {},
+            }));
+        }
+        // No match: emulate disableNetConnect() — fail loudly, never hit the net.
+        const registered = this.routes
+            .map((r) => `${(r.spec.method ?? "GET").toUpperCase()} ${String(r.spec.path ?? "*")}`)
+            .join(", ");
+        throw new Error(`FetchStub: no route matched ${method} ${call.path} ` +
+            `(net connect is disabled). Registered routes: [${registered}]`);
+    }
+    static matches(spec, call) {
+        if ((spec.method ?? "GET").toUpperCase() !== call.method)
+            return false;
+        if (spec.path !== undefined) {
+            if (typeof spec.path === "string") {
+                if (spec.path !== call.url.pathname)
+                    return false;
+            }
+            else if (!spec.path.test(call.url.pathname)) {
+                return false;
+            }
+        }
+        if (spec.query) {
+            for (const [k, v] of Object.entries(spec.query)) {
+                if (call.url.searchParams.get(k) !== v)
+                    return false;
+            }
+        }
+        return true;
+    }
+}