@txco/web-abi 0.0.0-stage → 0.2.0

package/src/envelope.ts

@@ -0,0 +1,49 @@
+// The chassis's side of the contract: the request envelope a runner hands
+// the bridge, and the delta the bridge answers with.
+
+/** The parts of the chassis's request envelope the bridge reads. */
+export interface TxcEnvelope {
+  _txc?: {
+    client?: { ip?: string };
+    web?: {
+      req?: {
+        method?: string;
+        host?: string;
+        url?: { full?: string; path?: string; query?: { raw?: string } };
+        /** Header name → values, one per line. */
+        headers?: Record<string, string[] | string>;
+        /** The body, base64; absent when empty. */
+        body?: string;
+      };
+    };
+  };
+  [k: string]: unknown;
+}
+
+/** The response half: what an op writes to answer an HTTP request. */
+export interface TxcWebRes {
+  status: number;
+  /** Lower-case header name → values. */
+  headers: Record<string, string[]>;
+  /** The body, base64; absent for HEAD, 204 and 304. */
+  body?: string;
+}
+
+/**
+ * The bridge's answer: a delta the chassis merges into the run, never the
+ * envelope echoed back (op answers merge by appending arrays, so an echo
+ * would duplicate every header).
+ */
+export interface TxcDelta {
+  _txc: { web: { res: TxcWebRes }; halt: true };
+}
+
+/** What a server entry gets beside the Request. Deliberately minimal. */
+export interface TxcContext {
+  readonly client: { readonly ip: string };
+}
+
+/** The server/ entry's default export. */
+export interface FetchHandler {
+  fetch(request: Request, ctx: TxcContext): Response | Promise<Response>;
+}

package/src/harness.ts

@@ -0,0 +1,149 @@
+// The harness: load a build's server/ entry and check it honours the
+// contract, before any runner exists; and serve a build locally behind the
+// same bridge a runner will use.
+
+import { createServer, type IncomingMessage, type Server } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import { extname, join, normalize, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { dispatch } from "./bridge.js";
+import type { FetchHandler, TxcEnvelope } from "./envelope.js";
+import { readManifest } from "./manifest.js";
+
+/** Imports a build's server entry and checks its default export. */
+export async function loadServer(abiDir: string): Promise<FetchHandler> {
+  const m = await readManifest(abiDir);
+  if (!m.server) throw new Error("the manifest names no server.entry: this is a static build");
+  const mod = await import(pathToFileURL(join(abiDir, m.server.entry)).href);
+  const h = mod.default as FetchHandler | undefined;
+  if (!h || typeof h.fetch !== "function") {
+    throw new Error(`${m.server.entry}: the default export must be { fetch(request, ctx) }`);
+  }
+  return h;
+}
+
+/** Builds an envelope the way the chassis's web head does, for a request. */
+export function envelopeFor(method: string, path: string, init: { headers?: Record<string, string[]>; body?: Uint8Array; host?: string; ip?: string } = {}): TxcEnvelope {
+  const host = init.host ?? "localhost";
+  const q = path.indexOf("?");
+  return {
+    _txc: {
+      client: { ip: init.ip ?? "127.0.0.1" },
+      web: {
+        req: {
+          method,
+          host,
+          url: { full: `http://${host}${path}`, path: q < 0 ? path : path.slice(0, q), query: { raw: q < 0 ? "" : path.slice(q + 1) } },
+          headers: init.headers ?? {},
+          body: init.body && init.body.byteLength > 0 ? Buffer.from(init.body).toString("base64") : undefined,
+        },
+      },
+    },
+  };
+}
+
+export interface CheckResult {
+  name: string;
+  ok: boolean;
+  detail?: string;
+}
+
+/**
+ * Drives a server entry with the requests every handler must answer, through
+ * the bridge, and checks each answer is a valid delta: a status in
+ * 100–599, headers as arrays, no echo of the request envelope, a body only
+ * where one is allowed.
+ */
+export async function checkServer(abiDir: string): Promise<CheckResult[]> {
+  const results: CheckResult[] = [];
+  let handler: FetchHandler;
+  try {
+    handler = await loadServer(abiDir);
+    results.push({ name: "load", ok: true });
+  } catch (e) {
+    return [{ name: "load", ok: false, detail: (e as Error).message }];
+  }
+  const probes: Array<[string, TxcEnvelope, string]> = [
+    ["GET /", envelopeFor("GET", "/", { headers: { accept: ["text/html"] } }), "GET"],
+    ["GET unknown page", envelopeFor("GET", "/txco-web-abi-check-unknown", { headers: { accept: ["text/html"] } }), "GET"],
+    ["POST unknown", envelopeFor("POST", "/txco-web-abi-check-unknown", { headers: { "content-type": ["application/json"] }, body: new TextEncoder().encode("{}") }), "POST"],
+    ["HEAD /", envelopeFor("HEAD", "/"), "HEAD"],
+  ];
+  for (const [name, env, method] of probes) {
+    const delta = await dispatch(handler, env);
+    const res = delta?._txc?.web?.res;
+    const problems: string[] = [];
+    if (!res || !Number.isInteger(res.status) || res.status < 100 || res.status > 599) problems.push("no valid status");
+    if (res && Object.values(res.headers).some((v) => !Array.isArray(v))) problems.push("headers must be arrays");
+    if ((delta as unknown as { _txc: { web: { req?: unknown } } })._txc.web.req !== undefined) problems.push("the answer echoes the request");
+    if (method === "HEAD" && res?.body) problems.push("a HEAD answer carries a body");
+    if (res?.status === 500 && (method === "HEAD" || (res.body && Buffer.from(res.body, "base64").toString() === "internal error\n"))) {
+      problems.push("the handler threw or returned no Response (a 500 from the bridge)");
+    }
+    try {
+      JSON.stringify(delta);
+    } catch {
+      problems.push("the delta isn't serialisable");
+    }
+    results.push({ name, ok: problems.length === 0, detail: problems.join("; ") || `→ ${res?.status}` });
+  }
+  return results;
+}
+
+const TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8", ".css": "text/css", ".js": "text/javascript", ".mjs": "text/javascript",
+  ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png", ".jpg": "image/jpeg",
+  ".webp": "image/webp", ".ico": "image/x-icon", ".txt": "text/plain; charset=utf-8", ".woff2": "font/woff2",
+};
+
+async function readBody(req: IncomingMessage): Promise<Uint8Array> {
+  const chunks: Buffer[] = [];
+  for await (const c of req) chunks.push(c as Buffer);
+  return Buffer.concat(chunks);
+}
+
+/**
+ * Serves a build locally: public/ files first (as the chassis's static
+ * serving answers first), everything else through the bridge to server/.
+ * For local development; not a chassis.
+ */
+export async function serve(abiDir: string, opts: { port?: number; host?: string } = {}): Promise<Server> {
+  const handler = await loadServer(abiDir);
+  const pub = join(abiDir, "public");
+  const server = createServer(async (req, res) => {
+    const method = (req.method ?? "GET").toUpperCase();
+    const path = new URL(req.url ?? "/", "http://localhost").pathname;
+    if (method === "GET" || method === "HEAD") {
+      const segs = path.split("/").filter(Boolean);
+      if (!segs.some((s) => s.startsWith("."))) {
+        const file = normalize(join(pub, ...segs, path.endsWith("/") ? "index.html" : ""));
+        if (file.startsWith(pub + sep) || file === pub) {
+          try {
+            if ((await stat(file)).isFile()) {
+              const bytes = await readFile(file);
+              res.writeHead(200, { "content-type": TYPES[extname(file)] ?? "application/octet-stream" });
+              res.end(method === "HEAD" ? undefined : bytes);
+              return;
+            }
+          } catch {
+            // not a file: the server answers
+          }
+        }
+      }
+    }
+    const headers: Record<string, string[]> = {};
+    for (let i = 0; i < req.rawHeaders.length; i += 2) {
+      (headers[req.rawHeaders[i].toLowerCase()] ??= []).push(req.rawHeaders[i + 1]);
+    }
+    const delta = await dispatch(handler, envelopeFor(method, req.url ?? "/", {
+      headers, body: await readBody(req), host: req.headers.host, ip: req.socket.remoteAddress ?? "",
+    }));
+    const out = delta._txc.web.res;
+    for (const [name, values] of Object.entries(out.headers)) res.setHeader(name, values);
+    res.writeHead(out.status);
+    res.end(out.body ? Buffer.from(out.body, "base64") : undefined);
+  });
+  await new Promise<void>((resolve) => server.listen(opts.port ?? 0, opts.host ?? "127.0.0.1", resolve));
+  return server;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./manifest.js";
+export * from "./envelope.js";
+export * from "./bridge.js";
+export * from "./harness.js";

package/src/manifest.ts

@@ -0,0 +1,127 @@
+// 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;
+
+export interface Manifest {
+  abi: 1;
+  server?: { entry: string };
+  immutable?: string[];
+  [extension: `x-${string}`]: unknown;
+}
+
+export interface Problem {
+  /** A JSON pointer into the manifest ("" is the root). */
+  pointer: string;
+  message: string;
+}
+
+export type ValidationResult = { ok: true; manifest: Manifest } | { ok: false; errors: Problem[] };
+
+const ENTRY_RE = /^server\/[^/\\][^\\]*\.m?js$/;
+const PREFIX_RE = /^[^/\\][^\\]*\/$/;
+
+function cleanPath(p: string): boolean {
+  if (p === "" || p.startsWith("/") || p.endsWith("/")) return false;
+  return p.split("/").every((seg) => seg !== "" && !seg.startsWith("."));
+}
+
+/** Validates a parsed manifest. */
+export function validateManifest(doc: unknown): ValidationResult {
+  const errors: Problem[] = [];
+  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 as Record<string, unknown>;
+  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 as Record<string, unknown>;
+      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 as unknown as Manifest };
+}
+
+/** Reads and validates <dir>/txco-web.json. Throws on an unreadable or invalid manifest. */
+export async function readManifest(dir: string): Promise<Manifest> {
+  const raw = await readFile(join(dir, MANIFEST_NAME), "utf8");
+  let doc: unknown;
+  try {
+    doc = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`${MANIFEST_NAME}: not valid JSON: ${(e as Error).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: string): string {
+  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/src/producer.ts

@@ -0,0 +1,269 @@
+// 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: number): number => 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";
+
+/** 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 function renderOps(o: RenderOptions): Record<string, string> {
+  const scope = o.scope ?? PRODUCER_SCOPE;
+  const notes = (o.notes ?? []).map((l) => (l ? `# ${l}` : "#")).join("\n");
+  const extra = notes ? `${notes}\n` : "";
+  const out: Record<string, string> = {};
+  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: number, html: string): string {
+  // 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: ReadonlySet<string> = new Set([MANIFEST_NAME, "public", "server", "ops", ".gitignore", ".DS_Store"]);
+
+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[];
+}
+
+const within = (child: string, parent: string) => {
+  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: OutDirCheck): string[] {
+  const dir = resolve(c.dir);
+  const problems: string[] = [];
+  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: string, ops: Record<string, string>): Promise<void> {
+  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: string, manifest: Record<string, unknown>): Promise<void> {
+  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: string): Promise<string[]> {
+  const out: string[] = [];
+  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 as { parentPath?: string; path?: string }).parentPath ?? (e as { path?: string }).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: string): boolean {
+  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: string): { prefix: string; external: boolean } {
+  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: string): boolean {
+  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: string, out: string, prefix = ""): Promise<{ skipped: string[] }> {
+  const skipped: string[] = [];
+  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/txco-web.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://thanks.computer/schemas/txco-web-1.json",
+  "title": "TxCo Web ABI manifest (txco-web.json)",
+  "description": "Describes a Web ABI directory: public/ (files), an optional server/ Fetch entry, and ops/ (.txcl). It describes the artifact, never its routing: web behaviour is ops.",
+  "type": "object",
+  "required": ["abi"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "abi": {
+      "description": "The ABI version.",
+      "const": 1
+    },
+    "server": {
+      "description": "The application server, a Fetch handler module: export default { fetch(request, ctx) }. Absent for a static build.",
+      "type": "object",
+      "required": ["entry"],
+      "additionalProperties": false,
+      "properties": {
+        "entry": {
+          "description": "The ES module, relative to the ABI directory and under server/.",
+          "type": "string",
+          "maxLength": 512,
+          "pattern": "^server/[^/\\\\][^\\\\]*\\.m?js$"
+        }
+      }
+    },
+    "immutable": {
+      "description": "public/ prefixes whose files carry a content hash in their name, served with a year-long immutable cache. Each ends in '/'.",
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 2,
+        "maxLength": 512,
+        "pattern": "^[^/\\\\][^\\\\]*/$"
+      }
+    }
+  },
+  "patternProperties": {
+    "^x-": true
+  },
+  "additionalProperties": false
+}