@txco/web-abi 0.0.0-stage → 0.2.0

package/dist/manifest.js

@@ -0,0 +1,116 @@
+// The Web ABI manifest (txco-web.json): what a build is, never its routing.
+// This validator mirrors txco-web.schema.json plus the rules a schema can't
+// express, and is held to the same fixture corpus as the Go validator
+// (chassis/webabi), so the two agree.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+/** The manifest's file name at the root of an ABI directory. */
+export const MANIFEST_NAME = "txco-web.json";
+/** The manifest's abi value this kit reads. */
+export const ABI_VERSION = 1;
+/** Producers' ops live in the band starting here, after every author op. */
+export const PRODUCER_SCOPE = 900000;
+const ENTRY_RE = /^server\/[^/\\][^\\]*\.m?js$/;
+const PREFIX_RE = /^[^/\\][^\\]*\/$/;
+function cleanPath(p) {
+    if (p === "" || p.startsWith("/") || p.endsWith("/"))
+        return false;
+    return p.split("/").every((seg) => seg !== "" && !seg.startsWith("."));
+}
+/** Validates a parsed manifest. */
+export function validateManifest(doc) {
+    const errors = [];
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
+        return { ok: false, errors: [{ pointer: "", message: "the manifest must be a JSON object" }] };
+    }
+    const m = doc;
+    for (const key of Object.keys(m)) {
+        if (!["$schema", "abi", "server", "immutable"].includes(key) && !key.startsWith("x-")) {
+            errors.push({ pointer: "", message: `unknown property "${key}" (a manifest describes the build, never its routing; extensions start with x-)` });
+        }
+    }
+    if (!("abi" in m)) {
+        errors.push({ pointer: "", message: 'missing required property "abi"' });
+    }
+    else if (m.abi !== ABI_VERSION) {
+        errors.push({ pointer: "/abi", message: `abi must be ${ABI_VERSION}` });
+    }
+    if ("$schema" in m && typeof m.$schema !== "string") {
+        errors.push({ pointer: "/$schema", message: "must be a string" });
+    }
+    if ("server" in m) {
+        const s = m.server;
+        if (typeof s !== "object" || s === null || Array.isArray(s)) {
+            errors.push({ pointer: "/server", message: "must be an object" });
+        }
+        else {
+            const so = s;
+            for (const key of Object.keys(so)) {
+                if (key !== "entry")
+                    errors.push({ pointer: "/server", message: `unknown property "${key}"` });
+            }
+            if (typeof so.entry !== "string") {
+                errors.push({ pointer: "/server", message: 'missing required property "entry"' });
+            }
+            else if (!ENTRY_RE.test(so.entry) || so.entry.length > 512) {
+                errors.push({ pointer: "/server/entry", message: "must be a .js or .mjs module under server/" });
+            }
+            else if (!cleanPath(so.entry)) {
+                errors.push({ pointer: "/server/entry", message: "the entry must be a clean path under server/" });
+            }
+        }
+    }
+    if ("immutable" in m) {
+        const im = m.immutable;
+        if (!Array.isArray(im)) {
+            errors.push({ pointer: "/immutable", message: "must be an array of prefixes" });
+        }
+        else {
+            if (new Set(im).size !== im.length) {
+                errors.push({ pointer: "/immutable", message: "items must be unique" });
+            }
+            im.forEach((p, i) => {
+                const ptr = `/immutable/${i}`;
+                if (typeof p !== "string" || p.length < 2 || p.length > 512 || !PREFIX_RE.test(p)) {
+                    errors.push({ pointer: ptr, message: "a prefix is a relative path ending in '/'" });
+                }
+                else if (!cleanPath(p.replace(/\/$/, ""))) {
+                    errors.push({ pointer: ptr, message: "a prefix must be a clean path, with no '.' or '..' segment" });
+                }
+                else if (p.split("/")[0] === "_txco") {
+                    errors.push({ pointer: ptr, message: "_txco/ is reserved for the installer" });
+                }
+            });
+        }
+    }
+    return errors.length > 0 ? { ok: false, errors } : { ok: true, manifest: m };
+}
+/** Reads and validates <dir>/txco-web.json. Throws on an unreadable or invalid manifest. */
+export async function readManifest(dir) {
+    const raw = await readFile(join(dir, MANIFEST_NAME), "utf8");
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`${MANIFEST_NAME}: not valid JSON: ${e.message}`);
+    }
+    const r = validateManifest(doc);
+    if (!r.ok) {
+        throw new Error(`${MANIFEST_NAME}: ` + r.errors.map((p) => `${p.pointer || "/"}: ${p.message}`).join("; "));
+    }
+    return r.manifest;
+}
+/**
+ * The private root of a public/ path: cut at the end of its first "_"
+ * segment ("" when it has none). The installer writes one public marker per
+ * root, so `_app/x.js` → `_app`, `assets/_Dk3.js` → itself.
+ */
+export function publicRoot(rel) {
+    const segs = rel.split("/");
+    for (let i = 0; i < segs.length; i++) {
+        if (segs[i].startsWith("_"))
+            return segs.slice(0, i + 1).join("/");
+    }
+    return "";
+}

package/dist/producer.d.ts

@@ -0,0 +1,100 @@
+/** Where the catch-all sits: after the navigation op, since ops in one scope run concurrently. */
+export declare const catchAllScope: (scope: number) => number;
+/**
+ * A navigation: an HTTP GET or HEAD of a path whose last segment has no
+ * extension. Everything else (an asset miss, a POST) is the catch-all's.
+ */
+export declare const NAV_GUARD: string;
+/** The page a 404 op serves when the build has no 404.html. */
+export declare const BUILTIN_404: string;
+/** An HTML page from public/, embedded in an op. */
+export interface Page {
+    /** Its file name in public/, for the comments. */
+    name: string;
+    html: string;
+}
+/**
+ * How a page navigation nothing else answered is handled:
+ *
+ *  - "spa": the app routes in the browser: 200, with the app shell;
+ *  - "routes": the same, but only for a path the framework's route table
+ *    knows (`routes`); any other navigation gets the shell with 404;
+ *  - "404": every page is a file in public/, so a path that reached the ops
+ *    has no page: 404, with the 404 page;
+ *  - "none": no navigation op, only the catch-all.
+ */
+export type NavMode = "spa" | "routes" | "404" | "none";
+export interface RenderOptions {
+    mode: NavMode;
+    /** The navigation op's scope; the catch-all goes 900 above it. Default 900000. */
+    scope?: number;
+    /** The generated-file header's producer name. */
+    producer: string;
+    /**
+     * The shell ("spa" and "routes": required), the 404 page ("404": null
+     * writes a built-in one), or null ("none").
+     */
+    page: Page | null;
+    /**
+     * For "routes": an RE2 regex source, anchored, matching exactly the app's
+     * page paths, with "/" escaped for txcl's /…/ literal.
+     */
+    routes?: string;
+    /** The producer's own comment lines, added to the navigation op's header. */
+    notes?: readonly string[];
+}
+/**
+ * Renders the build's ops, as path (relative to ops/) → file text: one
+ * navigation op for the mode, and the catch-all, a plain 404 for every other
+ * HTTP request, so every request reaching the end of the stack is answered.
+ */
+export declare function renderOps(o: RenderOptions): Record<string, string>;
+/** The EMIT tail for a page answer: the page as a readable b64"…" literal, and halt. */
+export declare function emitPage(status: number, html: string): string;
+/** What may already be in an output dir: a previous build, and nothing else. */
+export declare const ABI_ENTRIES: ReadonlySet<string>;
+export interface OutDirCheck {
+    /** The output dir the build is about to wipe and rewrite. */
+    dir: string;
+    /** Paths the wipe must not reach: the project root, the sources, another build's output. */
+    protect?: readonly string[];
+    /** Paths the output dir must not sit inside (a bundler's own outDir, which it empties). */
+    notInside?: readonly string[];
+    /** The dir's current entries, or null when it doesn't exist. */
+    entries: readonly string[] | null;
+    /** Entries a producer's own previous build leaves, besides ABI_ENTRIES. */
+    allow?: readonly string[];
+}
+/** Every reason a build mustn't wipe and rewrite the output dir. Empty when it may. */
+export declare function checkOutDir(c: OutDirCheck): string[];
+/** Replaces <out>/ops/ with the given ops (path relative to ops/ → text). */
+export declare function writeOps(out: string, ops: Record<string, string>): Promise<void>;
+/** Validates the manifest, then writes <out>/txco-web.json. Throws on an invalid one. */
+export declare function writeManifest(out: string, manifest: Record<string, unknown>): Promise<void>;
+/** Every file under root, as "/"-separated paths relative to it, sorted. */
+export declare function listFiles(root: string): Promise<string[]>;
+/**
+ * Whether a file name carries a content hash: Vite's `main-BxYz12Ab.js`,
+ * Nuxt's `entry.CdEf34Gh.css`. A heuristic, for warnings only.
+ */
+export declare function looksHashed(name: string): boolean;
+/**
+ * Where a build lands under public/, from its base path: "/app/" serves the
+ * site under /app/, so its files go under public/app/. A relative or root
+ * base serves it at the root. A full URL (a CDN) loads the assets from
+ * elsewhere: the files still go to the root, and the producer should warn.
+ */
+export declare function publicPrefix(base: string): {
+    prefix: string;
+    external: boolean;
+};
+/** Whether a "/"-separated relative path is one a Web ABI build never deploys: a dot segment. */
+export declare function isDotPath(rel: string): boolean;
+/**
+ * Copies a framework's static output dir into <out>/public/<prefix>,
+ * leaving out every dot path (they never deploy). Returns the ones it left
+ * out, other than .vite/ (build metadata), for the producer to warn about.
+ */
+export declare function copyPublic(from: string, out: string, prefix?: string): Promise<{
+    skipped: string[];
+}>;

package/dist/producer.js

@@ -0,0 +1,204 @@
+// What every Web ABI producer writes beside public/: the ops that answer a
+// request no file did, the manifest, and the guard that runs before a build
+// overwrites its output dir. The producers (a framework adapter, a Nitro
+// preset, a Vite plugin) share it, so their ops stay the same rules
+// (chassis/webabi checks that they agree).
+import { cp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { MANIFEST_NAME, PRODUCER_SCOPE, validateManifest } from "./manifest.js";
+/** Where the catch-all sits: after the navigation op, since ops in one scope run concurrently. */
+export const catchAllScope = (scope) => scope + 900;
+/**
+ * A navigation: an HTTP GET or HEAD of a path whose last segment has no
+ * extension. Everything else (an asset miss, a POST) is the catch-all's.
+ */
+export const NAV_GUARD = '@src == "http" && (@web.req.method == "GET" || @web.req.method == "HEAD")\n' +
+    "     && @web.req.url.path !~ /(?i)\\.[a-z0-9]+$/";
+/** The page a 404 op serves when the build has no 404.html. */
+export const BUILTIN_404 = '<!doctype html>\n<html lang="en"><head><meta charset="utf-8"><title>404 Not Found</title></head>' +
+    "<body><h1>404 Not Found</h1></body></html>\n";
+/**
+ * Renders the build's ops, as path (relative to ops/) → file text: one
+ * navigation op for the mode, and the catch-all, a plain 404 for every other
+ * HTTP request, so every request reaching the end of the stack is answered.
+ */
+export function renderOps(o) {
+    const scope = o.scope ?? PRODUCER_SCOPE;
+    const notes = (o.notes ?? []).map((l) => (l ? `# ${l}` : "#")).join("\n");
+    const extra = notes ? `${notes}\n` : "";
+    const out = {};
+    if (o.mode === "routes") {
+        if (o.page === null)
+            throw new Error("renderOps: a routes build needs its shell");
+        if (!o.routes)
+            throw new Error("renderOps: a routes build needs its route matcher");
+        out[`${scope}/spa-fallback.txcl`] = `# ${o.producer} — SPA fallback: known routes (generated; do not edit by hand).
+#
+# Serves the app shell (${o.page.name}) with 200 for a navigation to a known
+# page route that no file or earlier op answered. Paired with spa-404.txcl.
+${extra}# Regenerated on every build — the shell embeds content-hashed asset URLs.
+WHEN ${NAV_GUARD}
+     && @web.req.url.path =~ /${o.routes}/
+${emitPage(200, o.page.html)}`;
+        out[`${scope}/spa-404.txcl`] = `# ${o.producer} — SPA 404 (generated; do not edit by hand).
+#
+# A navigation matching no known page route is a real miss: 404, with the
+# shell as the body so the client renders its error page.
+WHEN ${NAV_GUARD}
+     && @web.req.url.path !~ /${o.routes}/
+${emitPage(404, o.page.html)}`;
+    }
+    else if (o.mode === "spa") {
+        if (o.page === null)
+            throw new Error("renderOps: an spa build needs its shell");
+        out[`${scope}/spa-fallback.txcl`] = `# ${o.producer} — SPA fallback (generated; do not edit by hand).
+#
+# Serves the app shell (${o.page.name}) with 200 for any page navigation
+# nothing else answered: the app routes in the browser, so unknown pages get
+# 200 too and the client renders its not-found view.
+${extra}# Regenerated on every build — the shell embeds content-hashed asset URLs.
+WHEN ${NAV_GUARD}
+${emitPage(200, o.page.html)}`;
+    }
+    else if (o.mode === "404") {
+        const what = o.page
+            ? `Serves ${o.page.name} with 404`
+            : "Serves a plain 404 page (the build has no 404.html)";
+        out[`${scope}/page-404.txcl`] = `# ${o.producer} — 404 page (generated; do not edit by hand).
+#
+# ${what} for any page navigation nothing else answered:
+# no file in public/ and no op of the stack had a page for it.
+${extra}# Regenerated on every build — the page embeds content-hashed asset URLs.
+WHEN ${NAV_GUARD}
+${emitPage(404, o.page ? o.page.html : BUILTIN_404)}`;
+    }
+    out[`${catchAllScope(scope)}/not-found.txcl`] = `# ${o.producer} — not found (generated; do not edit by hand).
+#
+# Every other HTTP request that reached the end of the stack: an asset that
+# doesn't exist, a method nothing handles. Without it the request would get
+# the envelope back as JSON. It sits after the navigation ops on purpose: ops
+# in one scope run concurrently.
+WHEN @src == "http"
+  EMIT @web.res.status = 404,
+       @web.res.headers.content-type.0 = "text/plain; charset=utf-8",
+       @web.res.body = b64"404 not found\\n",
+       @halt = true
+`;
+    return out;
+}
+/** The EMIT tail for a page answer: the page as a readable b64"…" literal, and halt. */
+export function emitPage(status, html) {
+    // The lexer base64-encodes a b64"…" literal at parse time, so the file stays
+    // readable HTML. Only backslash and double-quote need escaping.
+    const escaped = html.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    return `  EMIT @web.res.status = ${status},
+       @web.res.headers.content-type.0 = "text/html; charset=utf-8",
+       @web.res.headers.cache-control.0 = "no-cache",
+       @web.res.body = b64"${escaped}",
+       @halt = true
+`;
+}
+/** What may already be in an output dir: a previous build, and nothing else. */
+export const ABI_ENTRIES = new Set([MANIFEST_NAME, "public", "server", "ops", ".gitignore", ".DS_Store"]);
+const within = (child, parent) => {
+    const rel = relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+};
+/** Every reason a build mustn't wipe and rewrite the output dir. Empty when it may. */
+export function checkOutDir(c) {
+    const dir = resolve(c.dir);
+    const problems = [];
+    if (dir.split(sep).includes("OPS")) {
+        problems.push(`the output dir ${dir} is inside OPS/. A Web ABI build lives outside the stack tree; txco.yaml binds it to a stack (stacks: <name>: abi: <dir>).`);
+    }
+    for (const p of c.protect ?? []) {
+        if (p && within(resolve(p), dir)) {
+            problems.push(`the output dir ${dir} holds ${resolve(p)}, and the build wipes the output dir. Point it at a directory of its own.`);
+        }
+    }
+    for (const p of c.notInside ?? []) {
+        if (p && within(dir, resolve(p))) {
+            problems.push(`the output dir ${dir} is inside ${resolve(p)}, another build's output. Point it at a directory of its own.`);
+        }
+    }
+    const allowed = new Set([...ABI_ENTRIES, ...(c.allow ?? [])]);
+    const foreign = (c.entries ?? []).filter((e) => !allowed.has(e));
+    if (foreign.length > 0) {
+        problems.push(`the output dir ${dir} holds ${foreign.map((e) => `"${e}"`).join(", ")}, which isn't part of a Web ABI build, and the build wipes it. Point the output somewhere else, or empty it.`);
+    }
+    return problems;
+}
+/** Replaces <out>/ops/ with the given ops (path relative to ops/ → text). */
+export async function writeOps(out, ops) {
+    await rm(join(out, "ops"), { recursive: true, force: true });
+    for (const [rel, text] of Object.entries(ops)) {
+        const file = join(out, "ops", rel);
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, text);
+    }
+}
+/** Validates the manifest, then writes <out>/txco-web.json. Throws on an invalid one. */
+export async function writeManifest(out, manifest) {
+    const r = validateManifest(manifest);
+    if (!r.ok) {
+        throw new Error(`${MANIFEST_NAME}: ` + r.errors.map((p) => `${p.pointer || "/"}: ${p.message}`).join("; "));
+    }
+    await mkdir(out, { recursive: true });
+    await writeFile(join(out, MANIFEST_NAME), JSON.stringify(manifest, null, 2) + "\n");
+}
+/** Every file under root, as "/"-separated paths relative to it, sorted. */
+export async function listFiles(root) {
+    const out = [];
+    for (const e of await readdir(root, { recursive: true, withFileTypes: true })) {
+        // parentPath is Node ≥ 20.12; earlier 20.x calls it path.
+        const parent = e.parentPath ?? e.path ?? root;
+        if (e.isFile())
+            out.push(relative(root, join(parent, e.name)).split(sep).join("/"));
+    }
+    return out.sort();
+}
+/**
+ * Whether a file name carries a content hash: Vite's `main-BxYz12Ab.js`,
+ * Nuxt's `entry.CdEf34Gh.css`. A heuristic, for warnings only.
+ */
+export function looksHashed(name) {
+    const stem = name.replace(/\.[^.]+$/, "");
+    const run = stem.match(/[A-Za-z0-9_-]{8,}/);
+    return run !== null && /[0-9A-Z]/.test(run[0]);
+}
+/**
+ * Where a build lands under public/, from its base path: "/app/" serves the
+ * site under /app/, so its files go under public/app/. A relative or root
+ * base serves it at the root. A full URL (a CDN) loads the assets from
+ * elsewhere: the files still go to the root, and the producer should warn.
+ */
+export function publicPrefix(base) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(base) || base.startsWith("//"))
+        return { prefix: "", external: true };
+    const path = base.replace(/^\.?\/+|\/+$/g, "");
+    return { prefix: path && path !== "." ? `${path}/` : "", external: false };
+}
+/** Whether a "/"-separated relative path is one a Web ABI build never deploys: a dot segment. */
+export function isDotPath(rel) {
+    return rel.split("/").some((s) => s.startsWith("."));
+}
+/**
+ * Copies a framework's static output dir into <out>/public/<prefix>,
+ * leaving out every dot path (they never deploy). Returns the ones it left
+ * out, other than .vite/ (build metadata), for the producer to warn about.
+ */
+export async function copyPublic(from, out, prefix = "") {
+    const skipped = [];
+    await cp(from, join(out, "public", prefix), {
+        recursive: true,
+        filter: (src) => {
+            const rel = relative(from, src).split(sep).join("/");
+            if (rel === "" || !isDotPath(rel))
+                return true;
+            if (rel !== ".vite" && !rel.startsWith(".vite/"))
+                skipped.push(rel);
+            return false;
+        },
+    });
+    return { skipped };
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@txco/web-abi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "The TxCo Web ABI kit: the txco-web.json schema and validator, the envelope ↔ Fetch bridge every runner uses, a harness that checks a build's server/ Fetch handler, and the ops and manifest writer producers share.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "keywords": ["txco", "thanks-computer", "web-abi", "fetch", "conformance"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LoremLabs/thanks-computer.git",
+    "directory": "sdk/web-abi"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": ["dist", "src", "txco-web.schema.json", "README.md"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./bridge": {
+      "types": "./dist/bridge.d.ts",
+      "default": "./dist/bridge.js"
+    },
+    "./harness": {
+      "types": "./dist/harness.d.ts",
+      "default": "./dist/harness.js"
+    },
+    "./producer": {
+      "types": "./dist/producer.d.ts",
+      "default": "./dist/producer.js"
+    },
+    "./schema.json": "./txco-web.schema.json"
+  },
+  "bin": {
+    "txco-web-abi": "./dist/cli.js"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/bridge.ts

@@ -0,0 +1,115 @@
+// The envelope ↔ Fetch bridge. A runner hands it the chassis's request
+// envelope; it builds a Fetch Request, calls the server entry, and turns the
+// Response into the delta the chassis merges. Every runner uses this one
+// mapping, so a handler sees the same Request wherever it runs.
+
+import type { FetchHandler, TxcContext, TxcDelta, TxcEnvelope } from "./envelope.js";
+
+/** An op answer is capped at 4 MiB (--op-payload-max); the body is base64 inside it. */
+export const DEFAULT_MAX_ANSWER_BYTES = 3 * 1024 * 1024;
+
+// Hop-by-hop headers (RFC 9110 §7.6.1) and those the Request computes.
+const DROPPED_HEADERS = new Set([
+  "connection", "keep-alive", "proxy-connection", "transfer-encoding", "te", "trailer",
+  "upgrade", "content-length", "host",
+]);
+
+export interface RequestOptions {
+  /** Refuse a request body larger than this (bytes). Default: no limit. */
+  maxBodyBytes?: number;
+}
+
+/** Builds the Fetch Request an envelope describes. */
+export function envelopeToRequest(env: TxcEnvelope, opts: RequestOptions = {}): Request {
+  const req = env._txc?.web?.req ?? {};
+  const method = (req.method ?? "GET").toUpperCase();
+  let url = req.url?.full;
+  if (!url) {
+    const host = req.host ?? "localhost";
+    const raw = req.url?.query?.raw;
+    url = `http://${host}${req.url?.path ?? "/"}${raw ? "?" + raw : ""}`;
+  }
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(req.headers ?? {})) {
+    if (DROPPED_HEADERS.has(name.toLowerCase())) continue;
+    for (const v of Array.isArray(value) ? value : [value]) headers.append(name, v);
+  }
+  let body: ArrayBuffer | undefined;
+  if (req.body && method !== "GET" && method !== "HEAD") {
+    const bytes = Buffer.from(req.body, "base64");
+    if (opts.maxBodyBytes !== undefined && bytes.byteLength > opts.maxBodyBytes) {
+      throw new Error(`request body is ${bytes.byteLength} bytes, over ${opts.maxBodyBytes}`);
+    }
+    body = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(body).set(bytes);
+  }
+  return new Request(url, { method, headers, body });
+}
+
+/** The handler's context: only what the contract defines. */
+export function contextFrom(env: TxcEnvelope): TxcContext {
+  return Object.freeze({ client: Object.freeze({ ip: env._txc?.client?.ip ?? "" }) });
+}
+
+export interface DeltaOptions {
+  /** The request's method: a HEAD answer carries no body. */
+  method?: string;
+  /** Refuse a body larger than this (bytes). */
+  maxAnswerBytes?: number;
+}
+
+/** Turns a Response into the chassis delta. */
+export async function responseToDelta(res: Response, opts: DeltaOptions = {}): Promise<TxcDelta> {
+  const headers: Record<string, string[]> = {};
+  res.headers.forEach((value, name) => {
+    if (name === "set-cookie") return; // each cookie on its own line, below
+    (headers[name] ??= []).push(value);
+  });
+  const cookies = res.headers.getSetCookie();
+  if (cookies.length > 0) headers["set-cookie"] = cookies;
+
+  const delta: TxcDelta = { _txc: { web: { res: { status: res.status, headers } }, halt: true } };
+  const noBody = (opts.method ?? "GET").toUpperCase() === "HEAD" || res.status === 204 || res.status === 304;
+  if (!noBody) {
+    const bytes = Buffer.from(await res.arrayBuffer());
+    const max = opts.maxAnswerBytes ?? DEFAULT_MAX_ANSWER_BYTES;
+    if (bytes.byteLength > max) {
+      throw new Error(`response body is ${bytes.byteLength} bytes, over the ${max}-byte answer limit`);
+    }
+    if (bytes.byteLength > 0) delta._txc.web.res.body = bytes.toString("base64");
+  }
+  return delta;
+}
+
+function errorDelta(status: number, message: string, method: string): TxcDelta {
+  const res: TxcDelta["_txc"]["web"]["res"] = { status, headers: { "content-type": ["text/plain; charset=utf-8"] } };
+  if (method.toUpperCase() !== "HEAD") res.body = Buffer.from(message + "\n").toString("base64");
+  return { _txc: { web: { res }, halt: true } };
+}
+
+/**
+ * Runs one request through a handler, end to end. A handler that throws, or
+ * returns something other than a Response, answers 500; the error is never
+ * shown to the client.
+ */
+export async function dispatch(handler: FetchHandler, env: TxcEnvelope, opts: RequestOptions & DeltaOptions = {}): Promise<TxcDelta> {
+  const method = env._txc?.web?.req?.method ?? "GET";
+  let request: Request;
+  try {
+    request = envelopeToRequest(env, opts);
+  } catch {
+    return errorDelta(413, "request body too large", method);
+  }
+  let res: unknown;
+  try {
+    res = await handler.fetch(request, contextFrom(env));
+  } catch {
+    return errorDelta(500, "internal error", method);
+  }
+  if (!(res instanceof Response)) return errorDelta(500, "internal error", method);
+  try {
+    return await responseToDelta(res, { ...opts, method: request.method });
+  } catch {
+    return errorDelta(502, "response too large", method);
+  }
+}

package/src/cli.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// txco-web-abi: validate a manifest, check a build's server/, or serve a
+// build locally.
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { checkServer, serve } from "./harness.js";
+import { MANIFEST_NAME, validateManifest } from "./manifest.js";
+
+const USAGE = `Usage: txco-web-abi <command> <abi-dir>
+
+Commands:
+  validate <abi-dir>                 check txco-web.json against the Web ABI schema
+  check-server <abi-dir> [--json]    drive the build's server/ entry through the bridge
+  serve <abi-dir> [--port N]         serve public/ and server/ locally
+`;
+
+async function main(argv: string[]): Promise<number> {
+  const [cmd, dir, ...rest] = argv;
+  if (!cmd || !dir) {
+    process.stderr.write(USAGE);
+    return 2;
+  }
+  switch (cmd) {
+    case "validate": {
+      let doc: unknown;
+      try {
+        doc = JSON.parse(await readFile(join(dir, MANIFEST_NAME), "utf8"));
+      } catch (e) {
+        process.stderr.write(`${MANIFEST_NAME}: ${(e as Error).message}\n`);
+        return 1;
+      }
+      const r = validateManifest(doc);
+      if (r.ok) {
+        process.stdout.write(`${MANIFEST_NAME}: ok\n`);
+        return 0;
+      }
+      for (const p of r.errors) process.stdout.write(`${p.pointer || "/"}: ${p.message}\n`);
+      return 1;
+    }
+    case "check-server": {
+      const results = await checkServer(dir);
+      if (rest.includes("--json")) {
+        process.stdout.write(JSON.stringify({ ok: results.every((r) => r.ok), results }, null, 2) + "\n");
+      } else {
+        for (const r of results) process.stdout.write(`${r.ok ? "✓" : "✗"} ${r.name}${r.detail ? "  " + r.detail : ""}\n`);
+      }
+      return results.every((r) => r.ok) ? 0 : 1;
+    }
+    case "serve": {
+      const i = rest.indexOf("--port");
+      const port = i >= 0 ? Number(rest[i + 1]) : 8787;
+      const server = await serve(dir, { port });
+      const addr = server.address();
+      process.stdout.write(`serving ${dir} on http://127.0.0.1:${typeof addr === "object" && addr ? addr.port : port}\n`);
+      return await new Promise<number>(() => {}); // until interrupted
+    }
+    default:
+      process.stderr.write(USAGE);
+      return 2;
+  }
+}
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (e) => {
+    process.stderr.write(`txco-web-abi: ${(e as Error).message}\n`);
+    process.exit(1);
+  },
+);