pi-forge 0.0.0 → 1.1.4

package/dist/server/config.js

@@ -0,0 +1,326 @@
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+function readEnv(key) {
+    const v = process.env[key];
+    return v === undefined || v === "" ? undefined : v;
+}
+function readInt(key, fallback) {
+    const v = readEnv(key);
+    if (v === undefined)
+        return fallback;
+    const n = Number.parseInt(v, 10);
+    if (!Number.isFinite(n) || n < 0) {
+        throw new Error(`config: ${key} must be a non-negative integer (got ${v})`);
+    }
+    return n;
+}
+function readStringList(key) {
+    const v = readEnv(key);
+    if (v === undefined)
+        return [];
+    // Comma- or whitespace-separated; either is natural in shell, k8s
+    // env, and docker-compose `environment:` lists. Drop empties so
+    // trailing commas don't produce ghost entries.
+    return v
+        .split(/[,\s]+/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+function readBool(key, fallback) {
+    const v = readEnv(key)?.toLowerCase();
+    if (v === undefined)
+        return fallback;
+    if (["1", "true", "yes", "on"].includes(v))
+        return true;
+    if (["0", "false", "no", "off"].includes(v))
+        return false;
+    throw new Error(`config: ${key} must be a boolean-ish value (got ${v})`);
+}
+/**
+ * Forge-owned root. `~/.pi-forge` is the single dotdir we own.
+ * By default it holds both the project registry and the workspace where
+ * user code lives:
+ *
+ *   ~/.pi-forge/
+ *     ├── projects.json   ← FORGE_DATA_DIR by default
+ *     └── workspace/      ← WORKSPACE_PATH by default
+ *
+ * Either path can be relocated independently via its env var (e.g. point
+ * `WORKSPACE_PATH` at an existing `~/Code` dir to use code you already
+ * have on disk). Docker compose sets both explicitly so the container
+ * layout is unchanged.
+ */
+const HOME = homedir();
+if (HOME === "/" || HOME === "") {
+    throw new Error(`config: os.homedir() returned ${JSON.stringify(HOME)}. ` +
+        "This usually means HOME / USERPROFILE is unset. " +
+        "Set WORKSPACE_PATH, PI_CONFIG_DIR, and FORGE_DATA_DIR explicitly, " +
+        "or run the server with a real user account.");
+}
+const FORGE_HOME = join(HOME, ".pi-forge");
+const WORKSPACE_PATH = resolve(readEnv("WORKSPACE_PATH") ?? join(FORGE_HOME, "workspace"));
+// Default to the current user's home so local dev on macOS/Linux just works.
+// In the documented Docker setup this still resolves to `/root/.pi/agent`
+// (root's homedir IS `/root` inside the container), so the production target
+// is unchanged. Override explicitly via PI_CONFIG_DIR if needed.
+const PI_CONFIG_DIR = resolve(readEnv("PI_CONFIG_DIR") ?? join(HOME, ".pi", "agent"));
+const SESSION_DIR = resolve(readEnv("SESSION_DIR") ?? `${WORKSPACE_PATH}/.pi/sessions`);
+/**
+ * Forge-owned data dir. Holds `projects.json` (the project registry
+ * pi-forge layers on top of pi) and any other state that's ours, not
+ * pi's. Defaults to `FORGE_HOME` (~/.pi-forge) so projects.json
+ * sits next to the workspace folder. Kept SEPARATE from `PI_CONFIG_DIR`
+ * (~/.pi/agent), which is owned by the pi SDK — auth.json, models.json,
+ * settings.json. Dropping our state into the SDK's dir was the original
+ * design and got refactored out.
+ */
+const FORGE_DATA_DIR = resolve(readEnv("FORGE_DATA_DIR") ?? FORGE_HOME);
+/**
+ * Path to the built client (Vite output). In production we serve this via
+ * `@fastify/static`. The default resolves relative to the compiled server
+ * file (`packages/server/dist/config.js` → `../../client/dist`), which
+ * works for both the local `npm run build && node dist/index.js` flow and
+ * the Docker image (which mirrors the same `packages/server/dist` +
+ * `packages/client/dist` layout). Override with `CLIENT_DIST_PATH` if you
+ * relocate the built assets.
+ */
+const CLIENT_DIST_PATH = resolve(readEnv("CLIENT_DIST_PATH") ??
+    join(dirname(fileURLToPath(import.meta.url)), "..", "..", "client", "dist"));
+const UI_PASSWORD = readEnv("UI_PASSWORD");
+const API_KEY = readEnv("API_KEY");
+const CORS_ORIGIN = readEnv("CORS_ORIGIN");
+/**
+ * Load a JWT signing key from `${FORGE_DATA_DIR}/jwt-secret`, or
+ * generate-and-persist one on first boot. Treated like an SSH host key:
+ * created once, persisted to the data dir (which is the PVC / bind-mount
+ * in K8s and Docker), reused across restarts so issued tokens stay
+ * valid. Setting `JWT_SECRET` env explicitly skips this entirely.
+ *
+ * Only invoked when `UI_PASSWORD` is set — if browser auth isn't on,
+ * we don't need a secret at all.
+ */
+function loadOrGenerateJwtSecret(dataDir) {
+    const path = join(dataDir, "jwt-secret");
+    if (existsSync(path)) {
+        const v = readFileSync(path, "utf8").trim();
+        // 32 bytes = 256 bits ≈ 43 base64url chars. Anything shorter is
+        // either truncated or hand-edited; regenerate rather than trust it.
+        if (v.length >= 32)
+            return v;
+    }
+    mkdirSync(dataDir, { recursive: true });
+    const secret = randomBytes(48).toString("base64url");
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, `${secret}\n`, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+    console.log(`[config] auto-generated JWT secret persisted at ${path}. ` +
+        "Delete this file to rotate (logs out all browser sessions).");
+    return secret;
+}
+const JWT_SECRET = readEnv("JWT_SECRET") ??
+    (UI_PASSWORD !== undefined ? loadOrGenerateJwtSecret(FORGE_DATA_DIR) : undefined);
+export const config = Object.freeze({
+    port: readInt("PORT", 3000),
+    // HOST default depends on NODE_ENV. Production binds 0.0.0.0 (Docker
+    // image's normal mode); dev binds 127.0.0.1 so a `npm run dev` on a
+    // laptop doesn't silently expose the agent's shell + filesystem to
+    // anyone on the same WiFi/VLAN. Operators who want LAN access in dev
+    // can set HOST=0.0.0.0 explicitly.
+    host: readEnv("HOST") ?? (process.env.NODE_ENV === "production" ? "0.0.0.0" : "127.0.0.1"),
+    logLevel: readEnv("LOG_LEVEL") ?? "info",
+    isTest: (readEnv("NODE_ENV") ?? "") === "test",
+    trustProxy: readBool("TRUST_PROXY", false),
+    workspacePath: WORKSPACE_PATH,
+    piConfigDir: PI_CONFIG_DIR,
+    forgeDataDir: FORGE_DATA_DIR,
+    sessionDir: SESSION_DIR,
+    clientDistPath: CLIENT_DIST_PATH,
+    serveClient: readBool("SERVE_CLIENT", true),
+    /**
+     * Frontend "minimal" mode. When true, the client UI hides the
+     * terminal, git pane, last-turn pane, and the providers/agent
+     * settings sections, and replaces the project folder picker with
+     * a name-only form that creates `<workspacePath>/<name>`. Server
+     * routes are unchanged — this is purely a frontend gate exposed
+     * via `GET /api/v1/ui-config`. Use case: locked-down deployments
+     * where provider config is managed at the deploy level.
+     */
+    minimalUi: readBool("MINIMAL_UI", false),
+    /**
+     * When true, `GET /config/providers` filters out provider entries
+     * whose name does NOT appear as a key in `models.json`. Built-in
+     * providers (anthropic, openai, etc. that the SDK ships with) are
+     * hidden from the Settings → Providers list, leaving only the
+     * custom providers the operator added via `models.json`. Useful
+     * for deployments that route every model through a single internal
+     * gateway (vLLM, LiteLLM, internal proxy) and don't want users
+     * picking the public providers from the UI.
+     *
+     * Intentionally not exposed in docker-compose / .env.example —
+     * advanced env knob, document if/when it's needed widely.
+     */
+    hideBuiltinProviders: readBool("HIDE_BUILTIN_PROVIDERS", false),
+    /**
+     * Path to the forge-owned MCP server registry. Lives in the
+     * data dir (not pi's config dir) because pi has no native MCP
+     * support — `mcp.json` is purely a forge file, surfaced to
+     * the agent via `customTools` on createAgentSession.
+     */
+    mcpConfigFile: join(FORGE_DATA_DIR, "mcp.json"),
+    /**
+     * Path to the forge-private per-project skill overrides file.
+     * Lives in the data dir (NOT in PI_CONFIG_DIR — pi's settings.skills
+     * is global, and not in `<project>/.pi/` — the user picked
+     * forge-private over team-shared so each install has its own
+     * preferences without bleeding into the project tree).
+     */
+    skillOverridesFile: join(FORGE_DATA_DIR, "skills-overrides.json"),
+    /**
+     * Path to the forge-private per-tool override file. Captures
+     * "user has explicitly disabled this builtin tool" and "user has
+     * explicitly disabled this MCP tool" — both as flat allow-by-default
+     * sets. Lives in the data dir (forge-owned; pi's SDK has no
+     * native concept of per-tool toggles, this is purely a forge
+     * filter applied to the `tools` allowlist passed to
+     * createAgentSession).
+     */
+    toolOverridesFile: join(FORGE_DATA_DIR, "tool-overrides.json"),
+    /**
+     * Whether `/api/docs` (Swagger UI + OpenAPI JSON spec) is reachable.
+     * Defaults to true so Docker / production deploys keep working without
+     * extra config (the README quickstart documents `/api/docs`). When
+     * auth is enabled, the existing token check still gates the docs;
+     * when auth is disabled, the docs are an info-leak surface (route
+     * catalogue, body schemas), so security-conscious operators in
+     * unauthenticated public-internet deployments should set
+     * `EXPOSE_DOCS=false` — though that combo is itself discouraged
+     * (see SECURITY.md: never network-expose without auth + TLS).
+     */
+    exposeDocs: readBool("EXPOSE_DOCS", true),
+    auth: Object.freeze({
+        uiPassword: UI_PASSWORD,
+        jwtSecret: JWT_SECRET,
+        apiKey: API_KEY,
+        jwtExpiresInSeconds: readInt("JWT_EXPIRES_IN_SECONDS", 60 * 60 * 24 * 7),
+        loginRateLimitMax: readInt("RATE_LIMIT_LOGIN_MAX", 10),
+        loginRateLimitWindowMs: readInt("RATE_LIMIT_LOGIN_WINDOW_MS", 60_000),
+        /**
+         * When true and the only credential is the env-provided UI_PASSWORD
+         * (no on-disk hash yet), the login response carries
+         * `mustChangePassword: true` and the issued JWT is restricted —
+         * the user can only call `POST /auth/change-password` until they
+         * pick a new password. After the user changes it, the new password
+         * is hashed and persisted to `${FORGE_DATA_DIR}/password-hash`,
+         * and subsequent logins ignore the env value.
+         *
+         * Defaults to true so deployments that bake an initial password
+         * into env (helm secret, docker-compose .env) don't accidentally
+         * leave that credential as the long-lived one.
+         */
+        requirePasswordChange: readBool("REQUIRE_PASSWORD_CHANGE", true),
+        /** Where the persisted scrypt hash lives — see auth.ts. */
+        passwordHashFile: join(FORGE_DATA_DIR, "password-hash"),
+    }),
+    /**
+     * Per-route rate limits applied to the cost-heavy / disk-heavy / CPU-heavy
+     * routes. Defaults are conservative — enough headroom for an interactive
+     * user, low enough that a leaked-token spam loop hits the cap fast.
+     * Operators with higher legitimate volume can raise via env.
+     */
+    rateLimits: Object.freeze({
+        // /sessions/:id/{prompt,steer,compact,navigate} — per-user prompt
+        // floor. 60 / minute = 1 / second sustained, far above interactive
+        // typing speed; a runaway script gets capped in roughly 1 minute.
+        promptMax: readInt("RATE_LIMIT_PROMPT_MAX", 60),
+        promptWindowMs: readInt("RATE_LIMIT_PROMPT_WINDOW_MS", 60_000),
+        // /files/upload — disk fill. 30 / minute keeps an attentive user
+        // unblocked while capping a fill-the-disk loop.
+        uploadMax: readInt("RATE_LIMIT_UPLOAD_MAX", 30),
+        uploadWindowMs: readInt("RATE_LIMIT_UPLOAD_WINDOW_MS", 60_000),
+        // /files/search — CPU. ripgrep walks the workspace; each search is
+        // bounded by ripgrep but a tight loop still spins a CPU core.
+        searchMax: readInt("RATE_LIMIT_SEARCH_MAX", 60),
+        searchWindowMs: readInt("RATE_LIMIT_SEARCH_WINDOW_MS", 60_000),
+        // /git/push — network amplification + rate-limited by the git remote.
+        // Conservative — pushing 10x in a minute is almost always a mistake.
+        pushMax: readInt("RATE_LIMIT_PUSH_MAX", 10),
+        pushWindowMs: readInt("RATE_LIMIT_PUSH_WINDOW_MS", 60_000),
+    }),
+    corsOrigin: CORS_ORIGIN,
+    /**
+     * Extra env-var names the operator wants the integrated terminal
+     * (and the `!` exec route) to inherit from the pi-forge process.
+     *
+     * The terminal env starts from a small allowlist of harmless system
+     * vars (PATH, HOME, USER, SHELL, TERM, locales — see
+     * `pty-manager.ts#TERMINAL_ENV_ALLOWLIST`). Everything else is
+     * dropped — including provider API keys (`OPENAI_API_KEY`,
+     * `AWS_ACCESS_KEY_ID`, etc.) the operator may have in their host
+     * shell that would otherwise be inherited by every spawn. This
+     * defaults to fail-safe: any new sensitive var the operator sets
+     * is hidden from the shell unless they explicitly pass it through.
+     *
+     * Add specific vars here when the shell genuinely needs them
+     * (e.g. `KUBECONFIG`, `EDITOR`, `OPENAI_BASE_URL` for an internal
+     * proxy). Format: comma- or whitespace-separated.
+     *
+     * Example: `TERMINAL_PASSTHROUGH_ENV=KUBECONFIG,EDITOR,NODE_ENV`
+     */
+    terminalPassthroughEnv: Object.freeze(readStringList("TERMINAL_PASSTHROUGH_ENV")),
+    /**
+     * Opt-in: append a pi-forge-defined "secret hygiene" rule to the
+     * agent's system prompt. The rule asks the model to treat env-var
+     * values as credentials by default and not echo them into responses
+     * or tool outputs unless explicitly asked. See
+     * `agent-resource-loader.ts#FORGE_SECRET_HYGIENE_RULE` for the
+     * exact wording and `SECURITY.md` for the threat-model framing
+     * (behavioral nudge, not a security control).
+     *
+     * Default OFF. Operators who want it explicitly opt in by setting
+     * `AGENT_SECRET_HYGIENE_RULE=true`. Kept opt-in (rather than
+     * default-on) so the pi-forge doesn't ship invisible behavioral
+     * rules that constrain the agent in ways the user never asked for.
+     * Deliberately not surfaced in `docker-compose.yml` or
+     * `.env.example` — this is an advanced knob, intentionally
+     * discoverable only via SECURITY.md so operators meet the rule
+     * the same time they meet its caveats.
+     */
+    agentSecretHygieneRule: readBool("AGENT_SECRET_HYGIENE_RULE", false),
+    /**
+     * How long a detached PTY (its WebSocket closed but no replacement
+     * attached yet) is held alive before being reaped. The 10-minute
+     * default protects the common reattach use case: page refresh,
+     * transient network blip, laptop sleep — none of those should kill
+     * the user's shell.
+     *
+     * Operators in resource-constrained envs (kiosks, low-RAM
+     * containers) can shrink this. The integration test pins it to
+     * ~200 ms so the reap-on-close assertion completes within a normal
+     * test budget instead of waiting 10 minutes.
+     *
+     * Read by `pty-manager.ts#IDLE_REAP_MS` at module load. Setting
+     * this to 0 effectively disables reattach-after-WS-drop (every WS
+     * close becomes a hard kill); use that deliberately or not at all.
+     */
+    terminalIdleReapMs: readInt("PTY_IDLE_REAP_MS", 10 * 60 * 1000),
+});
+export function authEnabled() {
+    return (config.auth.uiPassword !== undefined ||
+        config.auth.apiKey !== undefined ||
+        existsSync(config.auth.passwordHashFile));
+}
+/**
+ * True iff this deployment supports the browser password-change flow:
+ * either an env-supplied UI_PASSWORD is in use OR a hash has already
+ * been persisted from a prior change. API-key-only deployments don't
+ * have a password to change, so the Settings → General password
+ * section hides on them. Read by /ui-config.
+ */
+export function passwordAuthEnabled() {
+    return config.auth.uiPassword !== undefined || existsSync(config.auth.passwordHashFile);
+}
+//# sourceMappingURL=config.js.map

package/dist/server/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/server/conversion-worker.mjs

@@ -0,0 +1,90 @@
+// Worker entry for PDF / DOCX / XLSX text extraction.
+//
+// Lives off the main thread because pdfjs-dist (used by pdf-parse) and
+// ExcelJS do heavy synchronous JavaScript work — a 2 MB PDF can block
+// the event loop for several seconds. While blocked, the SSE bridge's
+// heartbeat can't fire and the underlying TCP socket can stall enough
+// for Node's HTTP layer (or any proxy in front) to drop the
+// connection. Browsers see the SSE close and the chat shows
+// "Reconnecting…" right after the user submits a prompt with an
+// attachment.
+//
+// Pure ESM JS (.mjs) so it runs unmodified under both `tsx` (dev) and
+// compiled-prod node — the build script copies it next to the
+// compiled .js dispatcher.
+import { Buffer } from "node:buffer";
+import { parentPort } from "node:worker_threads";
+import ExcelJS from "exceljs";
+import mammoth from "mammoth";
+import { PDFParse } from "pdf-parse";
+
+if (parentPort === null) {
+  throw new Error("conversion-worker.mjs must be loaded as a worker_threads worker");
+}
+
+async function convertPdf(buf) {
+  let parser;
+  try {
+    parser = new PDFParse({ data: new Uint8Array(buf) });
+    const result = await parser.getText();
+    if (result.pages.length === 0) {
+      return "[PDF contained no extractable text — possibly a scanned/image-only document]";
+    }
+    return result.pages.map((p) => `--- Page ${p.num} ---\n${p.text.trimEnd()}`).join("\n\n");
+  } finally {
+    if (parser !== undefined) {
+      await parser.destroy().catch(() => undefined);
+    }
+  }
+}
+
+async function convertDocx(buf) {
+  const result = await mammoth.extractRawText({ buffer: buf });
+  return result.value;
+}
+
+async function convertXlsx(buf) {
+  const wb = new ExcelJS.Workbook();
+  await wb.xlsx.load(buf);
+  const sheets = [];
+  wb.eachSheet((ws) => {
+    const rows = [];
+    ws.eachRow({ includeEmpty: false }, (row) => {
+      const cells = [];
+      row.eachCell({ includeEmpty: true }, (cell) => {
+        cells.push(csvEscape(cell.text ?? ""));
+      });
+      rows.push(cells.join(","));
+    });
+    sheets.push(`--- Sheet: ${ws.name} ---\n${rows.join("\n")}`);
+  });
+  if (sheets.length === 0) return "[Workbook contained no readable sheets]";
+  return sheets.join("\n\n");
+}
+
+function csvEscape(s) {
+  if (s.length === 0) return s;
+  if (/[",\r\n]/.test(s)) return `"${s.replace(/"/g, '""')}"`;
+  return s;
+}
+
+parentPort.on("message", async (msg) => {
+  // msg = { id, format, buf } — buf arrives as ArrayBuffer because
+  // that transfers cheaply between threads.
+  const { id, format, buf } = msg;
+  const buffer = Buffer.from(buf);
+  try {
+    let text;
+    if (format === "pdf") text = await convertPdf(buffer);
+    else if (format === "docx") text = await convertDocx(buffer);
+    else if (format === "xlsx") text = await convertXlsx(buffer);
+    else throw new Error(`unknown format: ${format}`);
+    parentPort.postMessage({ id, ok: true, text });
+  } catch (err) {
+    parentPort.postMessage({
+      id,
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+});

package/dist/server/diagnostics.js

@@ -0,0 +1,137 @@
+/**
+ * Operator-visible error diagnostics. The pi SDK swallows provider
+ * errors into terse messages ("Connection Error", "fetch failed",
+ * "Provider returned an error stop reason") that omit the actual
+ * cause — most commonly a TLS handshake failure, DNS error, or
+ * connection refused. Without the cause chain, an operator gets a
+ * useless one-liner and has to attach a debugger.
+ *
+ * This module:
+ *  1. Installs `unhandledRejection` + `uncaughtException` handlers
+ *     that print the full `cause` chain to stderr.
+ *  2. Exports `formatErrorChain()` for any code path that has caught
+ *     an Error and wants to log the full underlying detail.
+ *  3. When `DEBUG_FETCH=1`, wraps `globalThis.fetch` to log any
+ *     rejection with the full cause chain. This is the surface where
+ *     TLS / DNS / connection errors actually originate; the SDK's
+ *     stringification loses them, so we capture before the SDK does.
+ *
+ * All output goes to `process.stderr` as JSON lines so
+ * `docker logs <container> | jq` works.
+ */
+function asErrorLike(v) {
+    if (v === null || v === undefined)
+        return undefined;
+    if (typeof v !== "object")
+        return undefined;
+    return v;
+}
+export function formatErrorChain(input) {
+    const chain = [];
+    let stack;
+    const seen = new Set();
+    const visit = (v, depth) => {
+        if (depth > 10)
+            return;
+        const e = asErrorLike(v);
+        if (!e || seen.has(v))
+            return;
+        seen.add(v);
+        const entry = {};
+        if (e.name !== undefined)
+            entry.name = e.name;
+        if (e.code !== undefined)
+            entry.code = e.code;
+        if (e.message !== undefined)
+            entry.message = e.message;
+        chain.push(entry);
+        if (stack === undefined && typeof e.stack === "string")
+            stack = e.stack;
+        if (e.cause !== undefined)
+            visit(e.cause, depth + 1);
+        if (Array.isArray(e.errors)) {
+            for (const inner of e.errors)
+                visit(inner, depth + 1);
+        }
+    };
+    visit(input, 0);
+    if (chain.length === 0) {
+        return { message: typeof input === "string" ? input : JSON.stringify(input), chain: [] };
+    }
+    const message = chain
+        .map((c) => [c.name, c.code, c.message].filter(Boolean).join(": "))
+        .filter(Boolean)
+        .join(" → ");
+    const result = { message, chain };
+    if (stack !== undefined)
+        result.stack = stack;
+    return result;
+}
+function writeJson(level, payload) {
+    process.stderr.write(`${JSON.stringify({ level, time: new Date().toISOString(), ...payload })}\n`);
+}
+/**
+ * Install once at server startup. Idempotent — guards against double
+ * registration (e.g. tests that spin up the server multiple times in
+ * one process).
+ */
+let installed = false;
+export function installDiagnostics() {
+    if (installed)
+        return;
+    installed = true;
+    process.on("unhandledRejection", (reason) => {
+        const f = formatErrorChain(reason);
+        writeJson("error", {
+            msg: "unhandledRejection",
+            error: f.message,
+            chain: f.chain,
+            stack: f.stack,
+        });
+    });
+    process.on("uncaughtException", (err) => {
+        const f = formatErrorChain(err);
+        writeJson("error", {
+            msg: "uncaughtException",
+            error: f.message,
+            chain: f.chain,
+            stack: f.stack,
+        });
+    });
+    if (process.env.DEBUG_FETCH === "1") {
+        const orig = globalThis.fetch;
+        globalThis.fetch = async (input, init) => {
+            const url = typeof input === "string"
+                ? input
+                : input instanceof URL
+                    ? input.href
+                    : input.url;
+            try {
+                const res = await orig(input, init);
+                if (!res.ok) {
+                    writeJson("warn", {
+                        msg: "fetch non-2xx",
+                        url,
+                        method: init?.method ?? "GET",
+                        status: res.status,
+                        statusText: res.statusText,
+                    });
+                }
+                return res;
+            }
+            catch (err) {
+                const f = formatErrorChain(err);
+                writeJson("error", {
+                    msg: "fetch threw",
+                    url,
+                    method: init?.method ?? "GET",
+                    error: f.message,
+                    chain: f.chain,
+                });
+                throw err;
+            }
+        };
+        writeJson("info", { msg: "DEBUG_FETCH enabled — wrapping globalThis.fetch" });
+    }
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/server/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"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"}