patchwork-os 0.2.0-beta.0 → 0.2.0-beta.10

package/dist/fsWatchWithFallback.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Watch a directory for any change, falling back to mtime polling when
+ * `fs.watch` is unavailable or fails.
+ *
+ * Motivation: `fs.watch` is unreliable on several real-world filesystems —
+ * Windows network drives (SMB/CIFS), WSL bind mounts, and macOS volumes
+ * mounted from a Linux host all either throw at watch time or stop firing
+ * events silently mid-session. The bridge's plugin hot-reload and kill-
+ * switch flag watcher silently went dead on those mounts.
+ *
+ * Behaviour:
+ *   - First try `fs.watch(dir, { recursive: false })`. If it succeeds, also
+ *     listen for the watcher's `error` event so a mid-session breakdown
+ *     swaps to polling without losing change notifications.
+ *   - If `fs.watch` throws (e.g. ENOENT — the directory doesn't exist yet,
+ *     or EPERM — the filesystem doesn't support watching), start polling
+ *     immediately.
+ *   - Polling: stat the directory every `pollIntervalMs` (default 2000ms)
+ *     and stat each non-dot file in it. Fire `onChange` if any file's
+ *     mtime advanced, a file appeared, or a file disappeared. If the
+ *     directory itself is missing, keep polling — it may appear later.
+ *
+ * Caller filters changes by re-reading the file(s) of interest. The helper
+ * deliberately does NOT expose the changed filename: polling can't reliably
+ * provide that, and fs.watch filenames are already null on some platforms
+ * (Windows rename events, atomic saves). One source of truth keeps callers
+ * platform-agnostic.
+ *
+ * Returns a `stop()` function that releases both the watcher and the timer.
+ */
+export declare function watchDirectoryWithFallback(dir: string, onChange: () => void, opts?: {
+    pollIntervalMs?: number;
+    logger?: {
+        warn: (msg: string) => void;
+    } | undefined;
+}): () => void;

package/dist/fsWatchWithFallback.js

@@ -0,0 +1,128 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Watch a directory for any change, falling back to mtime polling when
+ * `fs.watch` is unavailable or fails.
+ *
+ * Motivation: `fs.watch` is unreliable on several real-world filesystems —
+ * Windows network drives (SMB/CIFS), WSL bind mounts, and macOS volumes
+ * mounted from a Linux host all either throw at watch time or stop firing
+ * events silently mid-session. The bridge's plugin hot-reload and kill-
+ * switch flag watcher silently went dead on those mounts.
+ *
+ * Behaviour:
+ *   - First try `fs.watch(dir, { recursive: false })`. If it succeeds, also
+ *     listen for the watcher's `error` event so a mid-session breakdown
+ *     swaps to polling without losing change notifications.
+ *   - If `fs.watch` throws (e.g. ENOENT — the directory doesn't exist yet,
+ *     or EPERM — the filesystem doesn't support watching), start polling
+ *     immediately.
+ *   - Polling: stat the directory every `pollIntervalMs` (default 2000ms)
+ *     and stat each non-dot file in it. Fire `onChange` if any file's
+ *     mtime advanced, a file appeared, or a file disappeared. If the
+ *     directory itself is missing, keep polling — it may appear later.
+ *
+ * Caller filters changes by re-reading the file(s) of interest. The helper
+ * deliberately does NOT expose the changed filename: polling can't reliably
+ * provide that, and fs.watch filenames are already null on some platforms
+ * (Windows rename events, atomic saves). One source of truth keeps callers
+ * platform-agnostic.
+ *
+ * Returns a `stop()` function that releases both the watcher and the timer.
+ */
+export function watchDirectoryWithFallback(dir, onChange, opts = {}) {
+    const pollIntervalMs = opts.pollIntervalMs ?? 2000;
+    const logger = opts.logger;
+    let watcher = null;
+    let pollTimer = null;
+    let stopped = false;
+    // Snapshot: filename → mtimeMs. Empty Map when directory doesn't exist.
+    let snapshot = new Map();
+    const snapshotDir = () => {
+        const out = new Map();
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const ent of entries) {
+                if (!ent.isFile())
+                    continue;
+                if (ent.name.startsWith("."))
+                    continue;
+                try {
+                    const st = fs.statSync(path.join(dir, ent.name));
+                    out.set(ent.name, st.mtimeMs);
+                }
+                catch {
+                    /* file disappeared between readdir and stat — ignore */
+                }
+            }
+        }
+        catch {
+            /* dir missing — empty snapshot */
+        }
+        return out;
+    };
+    const startPolling = (reason) => {
+        if (pollTimer || stopped)
+            return;
+        if (logger)
+            logger.warn(`[fs-watch] falling back to polling: ${reason}`);
+        snapshot = snapshotDir();
+        pollTimer = setInterval(() => {
+            if (stopped)
+                return;
+            const next = snapshotDir();
+            let changed = next.size !== snapshot.size;
+            if (!changed) {
+                for (const [name, mtime] of next) {
+                    const prev = snapshot.get(name);
+                    if (prev === undefined || prev !== mtime) {
+                        changed = true;
+                        break;
+                    }
+                }
+            }
+            snapshot = next;
+            if (changed)
+                onChange();
+        }, pollIntervalMs);
+        // Don't keep the event loop alive solely for polling.
+        pollTimer.unref?.();
+    };
+    try {
+        watcher = fs.watch(dir, { recursive: false }, () => {
+            if (!stopped)
+                onChange();
+        });
+        watcher.on("error", (err) => {
+            // Watcher broke mid-session. Tear it down, start polling.
+            try {
+                watcher?.close();
+            }
+            catch {
+                /* ignore */
+            }
+            watcher = null;
+            startPolling(`watcher error: ${err.message}`);
+        });
+    }
+    catch (err) {
+        startPolling(`fs.watch threw: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return () => {
+        stopped = true;
+        if (watcher) {
+            try {
+                watcher.close();
+            }
+            catch {
+                /* ignore */
+            }
+            watcher = null;
+        }
+        if (pollTimer) {
+            clearInterval(pollTimer);
+            pollTimer = null;
+        }
+    };
+}
+//# sourceMappingURL=fsWatchWithFallback.js.map

package/dist/fsWatchWithFallback.js.map

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

package/dist/haltPushDispatch.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Bridge → push relay dispatch for recipe halt events.
+ *
+ * Sibling of `dispatchPushNotification` in [src/approvalHttp.ts](./approvalHttp.ts).
+ * The bridge POSTs a halt payload to `${pushServiceUrl}/halt`; the relay
+ * (a hosted push service or the dashboard's `/api/relay/halt` route)
+ * fans it out to every subscribed browser via Web Push.
+ *
+ * SSRF guard mirrors the approval dispatcher: HTTPS-only, hostname
+ * blocklist (localhost / loopback / private IPs after DNS resolve),
+ * 5s abort timeout, fire-and-forget so the recipe runner is never
+ * blocked on a push relay outage.
+ *
+ * Wired via `wireHaltPushDispatch` (subscribes to ActivityLog) — keeps
+ * the runner itself ignorant of push transport.
+ */
+export interface HaltPushPayload {
+    recipeName: string;
+    runSeq: number;
+    /** Always "error" or "halted" — the runner emits "error" today; the
+     *  shape leaves room for the dashboard's halted/error distinction. */
+    status: "error" | "halted";
+    haltReason?: string;
+    haltCategory?: string;
+    stepId?: string;
+    errorMessage?: string;
+    occurredAt?: number;
+}
+/**
+ * Fire-and-forget dispatch. Never throws — caller cannot recover from a
+ * push relay outage. Logged via console.warn for ops visibility.
+ */
+export declare function dispatchHaltPushNotification(pushServiceUrl: string, pushServiceToken: string, payload: HaltPushPayload): Promise<void>;

package/dist/haltPushDispatch.js

@@ -0,0 +1,103 @@
+/**
+ * Bridge → push relay dispatch for recipe halt events.
+ *
+ * Sibling of `dispatchPushNotification` in [src/approvalHttp.ts](./approvalHttp.ts).
+ * The bridge POSTs a halt payload to `${pushServiceUrl}/halt`; the relay
+ * (a hosted push service or the dashboard's `/api/relay/halt` route)
+ * fans it out to every subscribed browser via Web Push.
+ *
+ * SSRF guard mirrors the approval dispatcher: HTTPS-only, hostname
+ * blocklist (localhost / loopback / private IPs after DNS resolve),
+ * 5s abort timeout, fire-and-forget so the recipe runner is never
+ * blocked on a push relay outage.
+ *
+ * Wired via `wireHaltPushDispatch` (subscribes to ActivityLog) — keeps
+ * the runner itself ignorant of push transport.
+ */
+import dns from "node:dns/promises";
+/**
+ * Same SSRF blocklist as `dispatchPushNotification` in approvalHttp.ts.
+ * Duplicated inline to keep this dispatcher self-contained (the
+ * approvalHttp version is module-private and the file is already
+ * dense). If a third dispatcher ever lands, extract to a shared
+ * `src/sanitizeIp.ts`.
+ */
+function isBlockedIp(ip) {
+    if (ip === "::1" || ip === "0:0:0:0:0:0:0:1")
+        return true;
+    const parts = ip.split(".").map(Number);
+    if (parts.length !== 4)
+        return false;
+    const [a, b] = parts;
+    if (a === 127)
+        return true;
+    if (a === 10)
+        return true;
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    if (a === 192 && b === 168)
+        return true;
+    if (a === 169 && b === 254)
+        return true;
+    return false;
+}
+/**
+ * Fire-and-forget dispatch. Never throws — caller cannot recover from a
+ * push relay outage. Logged via console.warn for ops visibility.
+ */
+export async function dispatchHaltPushNotification(pushServiceUrl, pushServiceToken, payload) {
+    if (!pushServiceUrl.startsWith("https://")) {
+        console.warn(`[halt-push] Rejected non-HTTPS push service URL`);
+        return;
+    }
+    let hostname;
+    try {
+        hostname = new URL(pushServiceUrl).hostname;
+    }
+    catch {
+        console.warn(`[halt-push] Malformed push service URL — skipping`);
+        return;
+    }
+    if (hostname === "localhost") {
+        console.warn(`[halt-push] Blocked loopback push service hostname`);
+        return;
+    }
+    try {
+        const resolved = await dns.lookup(hostname);
+        if (isBlockedIp(resolved.address)) {
+            console.warn(`[halt-push] Blocked private/loopback IP for push service: ${resolved.address}`);
+            return;
+        }
+    }
+    catch (err) {
+        console.warn(`[halt-push] DNS resolution failed for ${hostname}: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5_000);
+    try {
+        const res = await fetch(`${pushServiceUrl}/halt`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${pushServiceToken}`,
+            },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            // 404 is informational ("no subscribers yet") — same relay
+            // contract as the approval path. Anything else is worth a warn.
+            if (res.status !== 404) {
+                console.warn(`[halt-push] Non-2xx from push relay: ${res.status} ${res.statusText}`);
+            }
+        }
+    }
+    catch (err) {
+        console.warn(`[halt-push] Dispatch failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=haltPushDispatch.js.map

package/dist/haltPushDispatch.js.map

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

package/dist/httpBodyValidation.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Strict allow-list validation for HTTP request body keys.
+ *
+ * `readJsonBody<T>()` is type-erased at runtime — the generic only documents
+ * the EXPECTED shape; unknown top-level keys are silently kept on the parsed
+ * object and dropped by the handler's destructure. Misspelled fields
+ * (`enabledZ`, `targerName`, `vasr`) succeed as a no-op + 200, which masks
+ * client bugs and complicates dashboard debugging.
+ *
+ * This helper closes the silent-failure gap for the highest-value
+ * configuration endpoints (settings, telemetry, kill-switch, recipe run /
+ * promote / trust). Callers extract the body, run this check, and on
+ * failure return a 400 enumerating the unknown keys.
+ *
+ * Sister module to `httpErrorResponse.ts`; same one-function-one-file style.
+ */
+import type { ServerResponse } from "node:http";
+export type AllowedKeysResult = {
+    ok: true;
+} | {
+    ok: false;
+    unknownKeys: string[];
+};
+/**
+ * Returns `{ok: true}` when every own enumerable key on `body` is in
+ * `allowed`. Otherwise lists the offending keys.
+ *
+ * Uses `Object.hasOwn` to avoid prototype walk surface (see project memory
+ * `feedback_record_string_prototype_walk.md` — 5 prod sites burned by
+ * `key in obj` / bare bracket access on attacker-controlled objects).
+ *
+ * Non-object / null / array bodies short-circuit `{ok: true}` — the
+ * handler's own shape-check will reject them with its existing 400.
+ */
+export declare function validateAllowedBodyKeys(body: unknown, allowed: readonly string[]): AllowedKeysResult;
+/**
+ * Convenience: writes the canonical 400 response and returns true when the
+ * body fails the allow-list check. Returns false on success so callers can
+ * `if (respondIfUnknownBodyKeys(...)) return;` and keep flowing.
+ */
+export declare function respondIfUnknownBodyKeys(res: ServerResponse, body: unknown, allowed: readonly string[]): boolean;

package/dist/httpBodyValidation.js

@@ -0,0 +1,45 @@
+/**
+ * Returns `{ok: true}` when every own enumerable key on `body` is in
+ * `allowed`. Otherwise lists the offending keys.
+ *
+ * Uses `Object.hasOwn` to avoid prototype walk surface (see project memory
+ * `feedback_record_string_prototype_walk.md` — 5 prod sites burned by
+ * `key in obj` / bare bracket access on attacker-controlled objects).
+ *
+ * Non-object / null / array bodies short-circuit `{ok: true}` — the
+ * handler's own shape-check will reject them with its existing 400.
+ */
+export function validateAllowedBodyKeys(body, allowed) {
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        return { ok: true };
+    }
+    const allowSet = new Set(allowed);
+    const unknownKeys = [];
+    for (const key of Object.keys(body)) {
+        if (!Object.hasOwn(body, key))
+            continue;
+        if (!allowSet.has(key))
+            unknownKeys.push(key);
+    }
+    if (unknownKeys.length > 0) {
+        return { ok: false, unknownKeys };
+    }
+    return { ok: true };
+}
+/**
+ * Convenience: writes the canonical 400 response and returns true when the
+ * body fails the allow-list check. Returns false on success so callers can
+ * `if (respondIfUnknownBodyKeys(...)) return;` and keep flowing.
+ */
+export function respondIfUnknownBodyKeys(res, body, allowed) {
+    const result = validateAllowedBodyKeys(body, allowed);
+    if (result.ok)
+        return false;
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({
+        error: "Unknown body fields",
+        unknownKeys: result.unknownKeys,
+    }));
+    return true;
+}
+//# sourceMappingURL=httpBodyValidation.js.map

package/dist/httpBodyValidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpBodyValidation.js","sourceRoot":"","sources":["../src/httpBodyValidation.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAa,EACb,OAA0B;IAE1B,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAA+B,CAAC,EAAE,CAAC;QAC/D,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAc,EAAE,GAAG,CAAC;YAAE,SAAS;QAClD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IACpC,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,GAAmB,EACnB,IAAa,EACb,OAA0B;IAE1B,MAAM,MAAM,GAAG,uBAAuB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACtD,IAAI,MAAM,CAAC,EAAE;QAAE,OAAO,KAAK,CAAC;IAC5B,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAC3D,GAAG,CAAC,GAAG,CACL,IAAI,CAAC,SAAS,CAAC;QACb,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EAAE,MAAM,CAAC,WAAW;KAChC,CAAC,CACH,CAAC;IACF,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/httpErrorResponse.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Centralized HTTP error responder for the bridge's plain-`http` route
+ * handlers.
+ *
+ * Replaces the ~96 inline `res.end(JSON.stringify({error: err.message}))`
+ * blocks scattered across `server.ts`, `connectorRoutes.ts`,
+ * `recipeRoutes.ts`, `inboxRoutes.ts`, and `oauthRoutes.ts` — every one of
+ * which leaked the underlying error message (and sometimes a stack frame
+ * via `Error.toString`) to the network. CodeQL flagged each as
+ * `js/stack-trace-exposure` (89 open alerts at the time of writing).
+ *
+ * Contract:
+ *   - Always returns a generic `{error: "Internal server error"}` body, never
+ *     the underlying error.message — even for non-Error throws.
+ *   - Logs the full detail (stack preferred, message fallback, String(err)
+ *     last) to stderr with an optional context label so post-incident
+ *     debugging is unaffected.
+ *   - Idempotent on `headersSent` / `writableEnded` so callers nested inside
+ *     other try/catch blocks can safely call this without re-throwing.
+ *
+ * Note: the dashboard's Next.js route handlers (`dashboard/src/app/api/**`)
+ * are a separate runtime — they use `NextResponse.json(...)` and have their
+ * own (smaller) leak surface; this helper is bridge-side only.
+ */
+import type { ServerResponse } from "node:http";
+/**
+ * Write a generic 500 response and log the underlying error detail
+ * server-side.
+ *
+ * @param res     The Node http response to write to.
+ * @param err     The thrown value caught by the route handler.
+ * @param context Optional short tag identifying the route ("recipes/lint",
+ *                "connectors/jira/connect", etc.). Surfaces in the server
+ *                log only — never sent to the client.
+ */
+export declare function respond500(res: ServerResponse, err: unknown, context?: string): void;

package/dist/httpErrorResponse.js

@@ -0,0 +1,46 @@
+/**
+ * Centralized HTTP error responder for the bridge's plain-`http` route
+ * handlers.
+ *
+ * Replaces the ~96 inline `res.end(JSON.stringify({error: err.message}))`
+ * blocks scattered across `server.ts`, `connectorRoutes.ts`,
+ * `recipeRoutes.ts`, `inboxRoutes.ts`, and `oauthRoutes.ts` — every one of
+ * which leaked the underlying error message (and sometimes a stack frame
+ * via `Error.toString`) to the network. CodeQL flagged each as
+ * `js/stack-trace-exposure` (89 open alerts at the time of writing).
+ *
+ * Contract:
+ *   - Always returns a generic `{error: "Internal server error"}` body, never
+ *     the underlying error.message — even for non-Error throws.
+ *   - Logs the full detail (stack preferred, message fallback, String(err)
+ *     last) to stderr with an optional context label so post-incident
+ *     debugging is unaffected.
+ *   - Idempotent on `headersSent` / `writableEnded` so callers nested inside
+ *     other try/catch blocks can safely call this without re-throwing.
+ *
+ * Note: the dashboard's Next.js route handlers (`dashboard/src/app/api/**`)
+ * are a separate runtime — they use `NextResponse.json(...)` and have their
+ * own (smaller) leak surface; this helper is bridge-side only.
+ */
+const GENERIC_BODY = JSON.stringify({ error: "Internal server error" });
+/**
+ * Write a generic 500 response and log the underlying error detail
+ * server-side.
+ *
+ * @param res     The Node http response to write to.
+ * @param err     The thrown value caught by the route handler.
+ * @param context Optional short tag identifying the route ("recipes/lint",
+ *                "connectors/jira/connect", etc.). Surfaces in the server
+ *                log only — never sent to the client.
+ */
+export function respond500(res, err, context) {
+    const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+    console.error(`[http-500]${context ? ` ${context}` : ""}: ${detail}`);
+    if (!res.headersSent) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+    }
+    if (!res.writableEnded) {
+        res.end(GENERIC_BODY);
+    }
+}
+//# sourceMappingURL=httpErrorResponse.js.map

package/dist/httpErrorResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpErrorResponse.js","sourceRoot":"","sources":["../src/httpErrorResponse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC,CAAC;AAExE;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACxB,GAAmB,EACnB,GAAY,EACZ,OAAgB;IAEhB,MAAM,MAAM,GACV,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAClE,OAAO,CAAC,KAAK,CAAC,aAAa,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC,CAAC;IACtE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;QACrB,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;QACvB,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACxB,CAAC;AACH,CAAC"}

package/dist/inboxRoutes.d.ts

@@ -14,6 +14,28 @@
  * preserved verbatim from the original.
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * Phase 0β provenance shape. Optional + additive — files without
+ * frontmatter return `provenance: undefined`.
+ */
+export interface InboxProvenance {
+    recipe?: string;
+    runSeq?: number;
+    trigger?: string;
+    deliveredAt?: string;
+}
+/**
+ * Split a markdown file into its YAML-frontmatter block (parsed as a flat
+ * `key: value` map) and the remaining body. Frontmatter is recognised
+ * only when the file begins with `---\n` and a closing `---` line is
+ * found within the first 30 lines (cap to bound the scan). Returns
+ * `{ provenance: undefined, body: content }` for files without
+ * frontmatter so callers degrade gracefully on legacy inbox items.
+ */
+export declare function parseInboxFile(content: string): {
+    provenance: InboxProvenance | undefined;
+    body: string;
+};
 /**
  * Try to handle an `/inbox` or `/inbox/<filename>.md` route. Returns true
  * if the route was dispatched (caller should `return` from the request