@pome-sh/cli 0.1.0

package/node_modules/@pome-sh/sdk/dist/recorder.js

@@ -0,0 +1,373 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Twin-core recorder (F-681 / F-720). Home: `packages/sdk/src/recorder.ts`
+// (`@pome-sh/sdk`). There is no separate `packages/twin-core` package — the
+// SDK *is* twin-core for recorder ownership. All first-party twins and the
+// CLI harness consume this module.
+//
+// In-memory recorder + `handle()` helper. `handle({mutation}, fn)` wraps a
+// Hono handler so every wrapped route emits a `RecorderEvent` matching
+// `recording-spec.md` v1.0:
+//   - `latency_ms` boundary: start = Date.now() before request body parse,
+//     end = Date.now() immediately before c.json() writes the response.
+//   - `state_mutation` = the `mutation` flag passed in. For tool-derived
+//     routes the SDK plumbs the tool's declared mutation flag, so the
+//     recording-spec invariant ("must equal the tool's declared mutation
+//     flag") holds by construction.
+//   - `error` = response_body.message when status >= 400, null otherwise.
+//   - Memory: bounded by session timeout × max-rps; events live for the
+//     pod's lifetime and are read once via GET /_pome/events at end-of-run.
+//
+// ── Write-through contract (F-720) ──────────────────────────────────────────
+//
+// Acceptance: an event is *accepted* once `RecorderStore.record()` returns.
+// For the in-memory store that means the row is in the heap tape. For a
+// durable/file-backed store it means the row has been queued for append to
+// the NDJSON file (and is visible via `events()`); durability to disk is
+// completed by `flush()` / `close()` (see below). Callers must not treat
+// `record()` alone as a crash-safe fsync.
+//
+// Redaction: `createRecorderHandle` redacts *before* every `store.record()`
+// call — including custom stores and direct `recorder.record()` — so no
+// store ever sees unredacted secrets. Stores must not re-emit raw bodies.
+//
+// Persisted row shape (F-698): durable stores write one redacted
+// `TwinHttpEvent` NDJSON line per accepted event (shared-types
+// `twinHttpEventSchema`) so on-disk `events.jsonl` matches the uploaded
+// raw-trace byte shape. The in-memory mirror / `GET /_pome/events` still
+// exposes legacy `RecorderEvent` rows.
+//
+// `flush()`: optional. When present, resolves after every accepted event is
+// durable on the store's backing medium (fsync for file-backed). In-memory
+// stores may omit it (no-op if called via a handle that forwards). Callers
+// that need crash-bounded loss (≤ in-flight event) must await `flush()`
+// before relying on the on-disk tape, or use a store that fsyncs on each
+// `record()` (F-698 production default).
+//
+// `close()`: optional. When present, flushes pending writes, releases the
+// backing resource, and is idempotent. After `close()`, further `record()`
+// calls are undefined (stores should throw or no-op). Callers must await
+// `close()` (or at least `flush()`) before upload/finalize so every accepted
+// write has either landed on disk or surfaced as a flush/close error.
+//
+// Bounded stores (`maxEvents`): the cap applies only to the in-memory mirror
+// used by `events()` / `GET /_pome/events` (memory pressure). The durable
+// NDJSON tape is append-only and retains every accepted write — including
+// rows later dropped from the heap mirror — so crash-safe upload reads the
+// tape, not `events()`.
+//
+// Default runtime behavior: `createRecorderStore()` remains heap-only.
+// Set `POME_RECORDER_EVENTS_PATH` (or pass `createFileBackedRecorderStore`)
+// for durable write-through; twin boot resolves via `resolveRecorderStore()`.
+import { randomUUID } from "node:crypto";
+import { closeSync, createWriteStream, fsync, mkdirSync, openSync, } from "node:fs";
+import { dirname } from "node:path";
+import { envelopeFor } from "./errors.js";
+import { redactEvent } from "./redaction.js";
+export function createRecorderStore(options = {}) {
+    const items = [];
+    const cap = options.maxEvents !== undefined ? Math.max(1, options.maxEvents) : undefined;
+    let droppedCount = 0;
+    return {
+        record(event) {
+            items.push(event);
+            if (cap !== undefined) {
+                while (items.length > cap) {
+                    items.shift();
+                    droppedCount += 1;
+                }
+            }
+        },
+        events() {
+            return [...items];
+        },
+        count() {
+            return items.length;
+        },
+        dropped() {
+            return droppedCount;
+        },
+        async flush() {
+            // Heap-only: accepted === durable for this store.
+        },
+        async close() {
+            // No backing resource.
+        },
+    };
+}
+/**
+ * Env key for the durable recorder tape. When set, twin boot paths and the
+ * self-host harness use `createFileBackedRecorderStore` instead of heap-only.
+ * Architecture (F-698 / §9 Q3): recorder *transport* lives in twin-core
+ * (`packages/sdk`); twins inherit durability by reading this env.
+ */
+export const POME_RECORDER_EVENTS_PATH = "POME_RECORDER_EVENTS_PATH";
+/**
+ * Wrap a legacy `RecorderEvent` into the unified `TwinHttpEvent` NDJSON row
+ * shape used by uploaded `events.jsonl` (FDRS-398). Pass-through only when
+ * `kind` is already `"TwinHttpEvent"`; any other kind is re-wrapped so the
+ * durable tape never persists a mismatched discriminator. Disk rows from the
+ * durable store use this shape so finalize/upload does not need a second wrap
+ * for crash-streamed events.
+ */
+export function toTwinHttpEventRow(event) {
+    const maybeKind = event.kind;
+    if (maybeKind === "TwinHttpEvent") {
+        const existing = event;
+        return {
+            ...existing,
+            event_id: typeof existing.event_id === "string" ? existing.event_id : event.request_id,
+            parent_id: null,
+        };
+    }
+    return {
+        ...event,
+        kind: "TwinHttpEvent",
+        event_id: event.request_id,
+        parent_id: null,
+    };
+}
+/**
+ * Durable recorder store (F-720 contract / F-698 implementation).
+ *
+ * Keeps an in-memory mirror of legacy `RecorderEvent` rows for `events()` /
+ * `GET /_pome/events` (unchanged API), and appends each accepted event as a
+ * `TwinHttpEvent` NDJSON line so on-disk `events.jsonl` matches the uploaded
+ * raw-trace byte shape. `flush()` drains pending writes and rethrows the
+ * first append/fsync failure; `fsync` (default true) bounds crash loss to
+ * the in-flight event. `maxEvents` caps only the heap mirror — the NDJSON
+ * tape stays append-only.
+ */
+export function createFileBackedRecorderStore(options) {
+    const items = [];
+    const cap = options.maxEvents !== undefined ? Math.max(1, options.maxEvents) : undefined;
+    let droppedCount = 0;
+    let closed = false;
+    const doFsync = options.fsync !== false;
+    mkdirSync(dirname(options.path), { recursive: true });
+    // Open the fd synchronously so fsync never races createWriteStream's
+    // async open (which can leave `writer.fd` undefined and silently skip
+    // durability on the first write).
+    const fd = openSync(options.path, "a");
+    const writer = createWriteStream(options.path, { fd, autoClose: false });
+    const pending = new Set();
+    // First append/fsync failure is retained so a later flush()/close() still
+    // reports it even after the rejected promise leaves `pending`.
+    let writeFailure = null;
+    function enqueueWrite(line) {
+        const write = new Promise((resolve, reject) => {
+            writer.write(line, (err) => {
+                if (err) {
+                    reject(err);
+                    return;
+                }
+                if (!doFsync) {
+                    resolve();
+                    return;
+                }
+                fsync(fd, (fsyncErr) => (fsyncErr ? reject(fsyncErr) : resolve()));
+            });
+        });
+        pending.add(write);
+        // Handle rejection here so a failed write before flush() is not an
+        // unhandled rejection, and so flush() can still surface the error after
+        // the promise has left `pending`.
+        void write.then(() => {
+            pending.delete(write);
+        }, (err) => {
+            pending.delete(write);
+            if (!writeFailure) {
+                writeFailure = err instanceof Error ? err : new Error(String(err));
+            }
+        });
+    }
+    async function flush() {
+        while (pending.size > 0) {
+            // allSettled: individual failures are already captured in writeFailure;
+            // awaiting a rejected member of `pending` must not short-circuit drain.
+            await Promise.allSettled([...pending]);
+        }
+        if (writeFailure) {
+            const err = writeFailure;
+            writeFailure = null;
+            throw err;
+        }
+    }
+    return {
+        record(event) {
+            if (closed) {
+                throw new Error("RecorderStore.record() after close()");
+            }
+            items.push(event);
+            if (cap !== undefined) {
+                while (items.length > cap) {
+                    items.shift();
+                    droppedCount += 1;
+                }
+            }
+            enqueueWrite(`${JSON.stringify(toTwinHttpEventRow(event))}\n`);
+        },
+        events() {
+            return [...items];
+        },
+        count() {
+            return items.length;
+        },
+        dropped() {
+            return droppedCount;
+        },
+        flush,
+        async close() {
+            if (closed) {
+                await flush();
+                return;
+            }
+            closed = true;
+            await flush();
+            await new Promise((resolve, reject) => {
+                writer.end((err) => {
+                    try {
+                        closeSync(fd);
+                    }
+                    catch (closeErr) {
+                        reject(err ?? closeErr);
+                        return;
+                    }
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            });
+        },
+    };
+}
+/**
+ * Resolve the recorder store for a twin boot: durable file-backed when
+ * `POME_RECORDER_EVENTS_PATH` is set, otherwise the in-memory default.
+ */
+export function resolveRecorderStore(options = {}) {
+    const path = process.env[POME_RECORDER_EVENTS_PATH]?.trim();
+    if (path) {
+        return createFileBackedRecorderStore({ ...options, path });
+    }
+    return createRecorderStore(options);
+}
+export function createRecorderHandle(options) {
+    const store = options.store ?? createRecorderStore();
+    const errorEnvelope = options.errorEnvelope ?? envelopeFor;
+    function emit(c, started, requestBody, result, mutation, fidelity, error) {
+        const requestId = `req_${randomUUID()}`;
+        // FDRS-402 / FDRS-653 stamping (F-683: engine parity with the per-twin
+        // recorders it replaces): correlation_id persists the adapter's
+        // x-pome-correlation-id (falling back to the request id), and the task
+        // author's x-pome-scenario-step-id lands as the canonical task_step_id
+        // plus the legacy scenario_step_id key (frozen v1 trace format —
+        // preserve semantics, tolerant readers accept either).
+        const stepId = c.req.header("x-pome-scenario-step-id") ?? null;
+        const correlationHeader = c.req.header("x-pome-correlation-id") ?? null;
+        // Redaction is unconditional at the engine layer (F-681 / F-720): every
+        // event that reaches any store — including custom stores — is already
+        // scrubbed.
+        store.record(redactEvent({
+            ts: new Date().toISOString(),
+            run_id: options.runId,
+            twin: options.twin,
+            request_id: requestId,
+            correlation_id: correlationHeader ?? requestId,
+            task_step_id: stepId,
+            scenario_step_id: stepId,
+            step_id: null,
+            // FDRS-402 adapter-rich path: only twins that pin `stampToolCallId`
+            // persist the header here (github); the default tape stamps null.
+            tool_call_id: options.stampToolCallId ? correlationHeader : null,
+            method: c.req.method,
+            path: new URL(c.req.url).pathname,
+            request_body: requestBody,
+            status: result.status,
+            response_body: result.body,
+            latency_ms: Date.now() - started,
+            fidelity,
+            state_mutation: mutation,
+            state_delta: result.delta ?? null,
+            error,
+        }));
+    }
+    return {
+        record(event) {
+            store.record(redactEvent(event));
+        },
+        events() {
+            return store.events();
+        },
+        count() {
+            return store.count?.() ?? store.events().length;
+        },
+        dropped() {
+            return store.dropped?.() ?? 0;
+        },
+        async flush() {
+            await store.flush?.();
+        },
+        async close() {
+            await store.close?.();
+        },
+        handle({ mutation, fidelity = "semantic", errorEnvelope: perCallEnvelope }, fn) {
+            const projectError = perCallEnvelope ?? errorEnvelope;
+            return async (c) => {
+                const started = Date.now();
+                let requestBody = null;
+                try {
+                    requestBody =
+                        c.req.method === "GET" || c.req.method === "HEAD"
+                            ? null
+                            : await readRequestJson(c);
+                    const result = await fn(c);
+                    const effectiveMutation = result.mutation ?? mutation;
+                    const errorMsg = result.status >= 400 ? extractMessage(result.body) ?? "request failed" : null;
+                    emit(c, started, requestBody, result, effectiveMutation, fidelity, errorMsg);
+                    return respondWith(c, result.status, result.body);
+                }
+                catch (caught) {
+                    const envelope = projectError(caught);
+                    // Failed routes never mutated state — record as state_mutation=false
+                    // regardless of the declared flag. Per recording-spec § state_mutation,
+                    // the field reflects whether the request *did* mutate state.
+                    const errMsg = extractMessage(envelope.body) ??
+                        (caught instanceof Error ? caught.message : "request failed");
+                    emit(c, started, requestBody, { status: envelope.status, body: envelope.body }, false, fidelity, errMsg);
+                    return respondWith(c, envelope.status, envelope.body);
+                }
+            };
+        },
+    };
+}
+// The Response constructor forbids a body on null-body statuses (204/205/
+// 304) — `c.json(null, 204)` throws and surfaces as a 500. github's frozen
+// surface answers deletes and the collaborator-membership check with a bare
+// 204 (F-682), so those statuses return an empty body.
+function respondWith(c, status, body) {
+    if (status === 204 || status === 205 || status === 304) {
+        return c.body(null, status);
+    }
+    return c.json(body, status);
+}
+// `clone()` throws synchronously once the body stream is disturbed — e.g.
+// after the form token resolver's parseBody() read a form-encoded POST
+// (F-683). A consumed or non-JSON body records as null, never a 500.
+async function readRequestJson(c) {
+    try {
+        return await c.req.raw.clone().json();
+    }
+    catch {
+        return null;
+    }
+}
+function extractMessage(body) {
+    if (body && typeof body === "object" && "message" in body) {
+        const message = body.message;
+        return typeof message === "string" ? message : undefined;
+    }
+    return undefined;
+}
+//# sourceMappingURL=recorder.js.map

package/node_modules/@pome-sh/sdk/dist/recorder.js.map

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

package/node_modules/@pome-sh/sdk/dist/redaction.d.ts

@@ -0,0 +1 @@
+export { redactEvent, redactSecrets } from "@pome-sh/shared-types/redaction";

package/node_modules/@pome-sh/sdk/dist/redaction.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: Apache-2.0
+export { redactEvent, redactSecrets } from "@pome-sh/shared-types/redaction";
+//# sourceMappingURL=redaction.js.map

package/node_modules/@pome-sh/sdk/dist/redaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC"}

package/node_modules/@pome-sh/sdk/dist/server-helpers.d.ts

@@ -0,0 +1,39 @@
+import { type ToolSpec, type TwinDefinition } from "./index.js";
+export declare class TwinBootError extends Error {
+    constructor(message: string);
+}
+/** Engine-owned `/_pome/*` route names a twin's `pomeRoutes` may not shadow. */
+export declare const POME_CORE_ROUTE_NAMES: Set<string>;
+export declare function makeDeltaSink(): {
+    report(d: import("@pome-sh/shared-types").RecorderEvent["state_delta"]): void;
+    value(): {
+        before: Record<string, unknown> | null;
+        after: Record<string, unknown> | null;
+    } | null;
+};
+/** Hostnames the boot guard treats as loopback binds. */
+export declare function isLoopbackHost(value: string): boolean;
+export declare function shadowedPrefix(routePath: string): string | null;
+export declare function assertUniqueToolNames<TDomain>(tools: ReadonlyArray<ToolSpec<TDomain>>, twinId: string): void;
+export declare function findTool<TDb, TSeed, TDomain>(definition: TwinDefinition<TDb, TSeed, TDomain>, name: string): ToolSpec<TDomain>;
+export declare function readJson(req: Request): Promise<unknown>;
+/**
+ * Convenience helper for `recorder.handle` inner functions. Returns a
+ * 200 response with the supplied `mutation` flag (default: false). Mirrors
+ * `packages/twin-github/src/app.ts:ok`.
+ */
+export declare function ok(body: unknown, mutation?: boolean): {
+    status: 200;
+    body: unknown;
+    mutation: boolean;
+};
+/**
+ * Convenience helper for `recorder.handle` inner functions. Returns a
+ * 201 response with `mutation: true`. Mirrors
+ * `packages/twin-github/src/app.ts:created`.
+ */
+export declare function created(body: unknown): {
+    status: 201;
+    body: unknown;
+    mutation: true;
+};

package/node_modules/@pome-sh/sdk/dist/server-helpers.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Internal helpers for `@pome-sh/sdk/server` (`createApp`/`serve`). Split
+// out of server.ts (F-685) purely for module-size hygiene; everything a twin
+// may import (TwinBootError, isLoopbackHost) is re-exported from server.ts,
+// which stays the only public entry.
+import { RESERVED_SESSION_PREFIXES } from "./index.js";
+import { UnknownToolError } from "./errors.js";
+export class TwinBootError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TwinBootError";
+    }
+}
+/** Engine-owned `/_pome/*` route names a twin's `pomeRoutes` may not shadow. */
+export const POME_CORE_ROUTE_NAMES = new Set(["health", "state", "events"]);
+export function makeDeltaSink() {
+    let delta = null;
+    return {
+        report(d) {
+            delta = d;
+        },
+        value() {
+            return delta;
+        },
+    };
+}
+/** Hostnames the boot guard treats as loopback binds. */
+export function isLoopbackHost(value) {
+    return value === "127.0.0.1" || value === "::1" || value === "localhost";
+}
+export function shadowedPrefix(routePath) {
+    for (const prefix of RESERVED_SESSION_PREFIXES) {
+        if (routePath === prefix || routePath.startsWith(`${prefix}/`))
+            return prefix;
+    }
+    return null;
+}
+export function assertUniqueToolNames(tools, twinId) {
+    const seen = new Set();
+    for (const tool of tools) {
+        if (seen.has(tool.name)) {
+            throw new TwinBootError(`Twin "${twinId}" has duplicate tool name: ${tool.name}`);
+        }
+        seen.add(tool.name);
+    }
+}
+export function findTool(definition, name) {
+    const tool = definition.tools.find((t) => t.name === name);
+    if (!tool) {
+        throw new UnknownToolError(name);
+    }
+    return tool;
+}
+export async function readJson(req) {
+    try {
+        const cloned = req.clone();
+        const text = await cloned.text();
+        if (!text)
+            return null;
+        return JSON.parse(text);
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            throw err;
+        return null;
+    }
+}
+/**
+ * Convenience helper for `recorder.handle` inner functions. Returns a
+ * 200 response with the supplied `mutation` flag (default: false). Mirrors
+ * `packages/twin-github/src/app.ts:ok`.
+ */
+export function ok(body, mutation = false) {
+    return { status: 200, body, mutation };
+}
+/**
+ * Convenience helper for `recorder.handle` inner functions. Returns a
+ * 201 response with `mutation: true`. Mirrors
+ * `packages/twin-github/src/app.ts:created`.
+ */
+export function created(body) {
+    return { status: 201, body, mutation: true };
+}
+//# sourceMappingURL=server-helpers.js.map

package/node_modules/@pome-sh/sdk/dist/server-helpers.js.map

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

package/node_modules/@pome-sh/sdk/dist/server.d.ts

@@ -0,0 +1,46 @@
+import { Hono } from "hono";
+import { type TwinDefinition } from "./index.js";
+import { type RecorderStore } from "./recorder.js";
+export { TwinBootError, isLoopbackHost, created, ok } from "./server-helpers.js";
+export { createRecorderHandle, createRecorderStore, createFileBackedRecorderStore, resolveRecorderStore, toTwinHttpEventRow, POME_RECORDER_EVENTS_PATH, } from "./recorder.js";
+export type { RecorderStore, RecorderStoreOptions, FileBackedRecorderStoreOptions, ErrorEnvelopeFn, } from "./recorder.js";
+export { bearerAuth, requireAdminAuth, resolveAuthSecret } from "./auth.js";
+export { createAdminGate, setClientIp } from "./admin-gate.js";
+export type { AdminGateOptions } from "./admin-gate.js";
+export { TwinError, UnknownToolError } from "./errors.js";
+export { redactEvent, redactSecrets } from "./redaction.js";
+export { FAILURE_INJECTION_OVERRIDE_KEY, createFailureInjectionStore, failureInjectionMiddleware, failureInjectionRuleSchema, } from "./failure-injection.js";
+export type { FailureInjectionMiddlewareOptions, FailureInjectionMode, FailureInjectionOverride, FailureInjectionRule, FailureInjectionStore, } from "./failure-injection.js";
+export { PROVIDER_SHAPED_TEAM_ID, formTokenResolver, mintProviderToken, queryTokenResolver, verifyProviderToken, } from "./auth.js";
+export type { AuthEnvelope, BearerAuthOptions, MintProviderTokenOptions, ProviderTokenSpec, SessionClaims, SessionValue, TokenResolver, UnauthorizedKind, } from "./auth.js";
+export { twinBuildInfo } from "./build-info.js";
+export type { TwinBuildInfo } from "./build-info.js";
+export interface ServeOptions<TDb = unknown, TSeed = unknown> {
+    /** Optional. When set, `serve()` binds a Node HTTP server. */
+    port?: number;
+    /** Bind hostname. Defaults to "127.0.0.1". */
+    hostname?: string;
+    /** Opaque database handle forwarded to `definition.domain({ db })`. */
+    db?: TDb;
+    /** Initial seed forwarded to `definition.domain({ seed })`. Validated against `definition.seed` if provided. */
+    seed?: TSeed;
+    /** Custom recorder store. Defaults to `resolveRecorderStore()` (durable when `POME_RECORDER_EVENTS_PATH` is set). */
+    recorder?: RecorderStore;
+    /** Run identifier embedded in every recorder event. Defaults to "local". */
+    runId?: string;
+}
+export declare function createApp<TDb, TSeed, TDomain>(definition: TwinDefinition<TDb, TSeed, TDomain>, options?: ServeOptions<TDb, TSeed>): Hono;
+export interface ServeResult {
+    app: Hono;
+    /**
+     * Stop the bound HTTP server (if any), then flush+close the recorder store
+     * so durable tapes drain before process exit (F-698).
+     */
+    close(): Promise<void>;
+}
+/**
+ * Build the app and bind a Node HTTP server. If `port` is omitted, no
+ * server is bound — `close()` still flushes the recorder store.
+ */
+export declare function serve<TDb, TSeed, TDomain>(definition: TwinDefinition<TDb, TSeed, TDomain>, options?: ServeOptions<TDb, TSeed>): Promise<ServeResult>;
+/** Engine-owned `/_pome/*` route names a twin's `pomeRoutes` may not shadow. */