@kedge/cli 0.0.0-stage → 0.9.0

package/src/schema.ts

@@ -0,0 +1,72 @@
+// The store's composed schema, built the way D1 applies it: each migration
+// file in one transaction, in lock order, into an in-memory SQLite. Doctor and
+// generate read objects from it rather than from SQL text, so a name inside a
+// comment or a string can't count as an object (docs/proposals/p0.8-cli-agent-kit.md §4.2).
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { BREAK, statementTexts } from "@kedge/core";
+import { byCodePoint } from "./order";
+
+export interface SchemaObject {
+  type: "table" | "index" | "trigger" | "view" | "constraint";
+  name: string;
+  table: string;
+  sql: string;
+}
+
+export interface Schema {
+  db: DatabaseSync;
+  objects: SchemaObject[];
+}
+
+/** Applies each file as one transaction, as D1 does, so a deferred obligation is checked at its commit. */
+export function applyMigrations(db: DatabaseSync, texts: readonly string[]): void {
+  for (const text of texts) {
+    db.exec("BEGIN");
+    try {
+      for (const part of text.split(BREAK)) for (const s of statementTexts(part)) db.exec(`${s};`);
+      db.exec("COMMIT");
+    } catch (e) {
+      db.exec("ROLLBACK");
+      throw e;
+    }
+  }
+}
+
+/** Named constraints in a table's CREATE statement (`CONSTRAINT <name>`), quoted or not. */
+export function namedConstraints(createSql: string): string[] {
+  return [...createSql.matchAll(/\bCONSTRAINT\s+["`[]?([A-Za-z0-9_]+)/gi)].map((m) => m[1] as string);
+}
+
+/** RAISE codes in an object's SQL: the text before the first `:` or space, which the error map keys on. */
+export function raiseCodes(sql: string): string[] {
+  return [
+    ...new Set(
+      [...sql.matchAll(/\bRAISE\s*\(\s*(?:ABORT|FAIL|ROLLBACK)\s*,\s*'([^']*)'/gi)].map(
+        (m) => (m[1] as string).split(/[: ]/)[0] as string,
+      ),
+    ),
+  ];
+}
+
+export function schemaOf(texts: readonly string[]): Schema {
+  const db = new DatabaseSync(":memory:");
+  applyMigrations(db, texts);
+  const rows = db
+    .prepare("SELECT type, name, tbl_name AS tbl, sql FROM sqlite_master WHERE name NOT LIKE 'sqlite_%'")
+    .all() as { type: SchemaObject["type"]; name: string; tbl: string; sql: string | null }[];
+  const objects: SchemaObject[] = [];
+  for (const r of rows) {
+    objects.push({ type: r.type, name: r.name, table: r.tbl, sql: r.sql ?? "" });
+    if (r.type === "table")
+      for (const c of namedConstraints(r.sql ?? ""))
+        objects.push({ type: "constraint", name: c, table: r.name, sql: r.sql ?? "" });
+  }
+  return { db, objects: objects.sort((a, b) => byCodePoint(a.name, b.name)) };
+}
+
+/** The store's composed migrations, in lock order. */
+export function composedTexts(cwd: string, lock: { entries: readonly { file: string }[] }): string[] {
+  return lock.entries.map((e) => readFileSync(join(cwd, "migrations", e.file), "utf8"));
+}

package/src/sqlite-verify.ts

@@ -0,0 +1,333 @@
+// Verifies plugin SQL against the real schema with SQLite's own authorizer.
+// The token rules (plugin-sql-rules.ts) guess which tables a statement
+// touches; SQLite knows. Five codex rounds found syntax the guesses missed
+// (quoted names, schema qualifiers, parenthesised tables, CTEs, renames), so
+// at build time `kedge generate` compiles every statement a plugin will run
+// against core's and the plugins' migrations in an in-memory database, and
+// checks each table SQLite reports reading or writing, through views and
+// triggers included. Nothing is executed except migrations. The token rules
+// still run at runtime, where Workers has no SQLite authorizer.
+import { DatabaseSync } from "node:sqlite";
+import {
+  acquireSql,
+  BREAK,
+  createEntitySql,
+  entityTriggersSql,
+  type FactTable,
+  factGuardSql,
+  factTables,
+  type LintIssue,
+  PERMANENT_IDENTITIES,
+  type PluginDefinition,
+  splitStatements,
+  statementTexts,
+  type Token,
+  tokenize,
+} from "@kedge/core";
+
+// SQLite authorizer action codes (sqlite.org/c3ref/c_alter_table.html).
+const A = {
+  CREATE_INDEX: 1,
+  CREATE_TABLE: 2,
+  CREATE_TRIGGER: 7,
+  CREATE_VIEW: 8,
+  DELETE: 9,
+  DROP_INDEX: 10,
+  DROP_TABLE: 11,
+  DROP_TRIGGER: 16,
+  DROP_VIEW: 17,
+  INSERT: 18,
+  PRAGMA: 19,
+  READ: 20,
+  SELECT: 21,
+  UPDATE: 23,
+  ALTER_TABLE: 26,
+  REINDEX: 27,
+  ANALYZE: 28,
+  FUNCTION: 31,
+  RECURSIVE: 33,
+} as const;
+
+type Access = [action: number, a: string | null, b: string | null, db: string | null, source: string | null];
+
+const SYSTEM = /^sqlite_(master|schema|sequence|temp_master|temp_schema|stat\d)$/;
+
+/**
+ * Judges one statement's accesses. `own` is the owner's namespace. A source
+ * (the view or trigger an access happens inside) that isn't a `plg_` object
+ * is core's: a read view, a core trigger, or a guard core generated, fired by
+ * the plugin's write. Plugin triggers and views must be `plg_<name>_…`, so a
+ * plugin can't pass its own SQL off as core's.
+ */
+function judge(
+  accesses: readonly Access[],
+  own: (name: string) => boolean,
+  ddl: boolean,
+  add: (rule: string, message: string) => void,
+): void {
+  for (const [action, a, b, , source] of accesses) {
+    const coreSource = source !== null && !source.startsWith("plg_");
+    switch (action) {
+      case A.SELECT:
+      case A.FUNCTION:
+      case A.RECURSIVE:
+        break;
+      case A.PRAGMA:
+        // SQLite runs these itself to validate an ALTER TABLE ADD COLUMN; a plugin can't write a PRAGMA (token rules).
+        if (
+          ddl &&
+          ["quick_check", "integrity_check", "table_info", "table_xinfo", "foreign_key_list"].includes(a ?? "")
+        )
+          break;
+        add("forbidden-statement", `PRAGMA ${a} isn't allowed in plugin SQL`);
+        break;
+      case A.READ:
+        if (ddl && (a ?? "").startsWith("pragma_")) break; // the same internal validation
+        // Permanent identities are read by the foreign keys a plugin row may hold to them.
+        if (!a || own(a) || coreSource || /^kedge_v\d+_/.test(a) || SYSTEM.test(a) || PERMANENT_IDENTITIES.has(a))
+          break;
+        add("core-table", `reads "${a}"${source ? ` (in ${source})` : ""}; read core only through kedge_vN_ views`);
+        break;
+      case A.INSERT:
+      case A.UPDATE:
+      case A.DELETE:
+        if (!a || own(a) || coreSource || (ddl && SYSTEM.test(a)) || a === "sqlite_sequence") break;
+        add("foreign-write", `writes "${a}"${source ? ` (in ${source})` : ""}; plugin SQL writes only its own tables`);
+        break;
+      case A.CREATE_TABLE:
+      case A.CREATE_VIEW:
+      case A.DROP_TABLE:
+      case A.DROP_VIEW:
+      case A.ALTER_TABLE:
+        if (!ddl) add("ddl-outside-migration", "DDL belongs in a migration");
+        // ALTER reports (db, table); the others (name, null).
+        if (!own((action === A.ALTER_TABLE ? b : a) ?? ""))
+          add("prefix", `"${action === A.ALTER_TABLE ? b : a}" isn't the owner's`);
+        break;
+      case A.CREATE_INDEX:
+      case A.CREATE_TRIGGER:
+      case A.DROP_INDEX:
+      case A.DROP_TRIGGER:
+        if (!ddl) add("ddl-outside-migration", "DDL belongs in a migration");
+        // (name, table): both the owner's. SQLite names a UNIQUE's own index sqlite_autoindex_<table>_n.
+        if (!(own(a ?? "") || (a ?? "").startsWith(`sqlite_autoindex_${b}_`)) || !own(b ?? ""))
+          add("core-ddl", `"${a}" on "${b}" isn't the owner's object on the owner's table`);
+        break;
+      case A.REINDEX:
+      case A.ANALYZE:
+        if (!ddl) add("ddl-outside-migration", "DDL belongs in a migration");
+        break;
+      default:
+        add("forbidden-statement", `SQLite action ${action} isn't allowed in plugin SQL`);
+    }
+  }
+}
+
+/** A trigger body's statements, made compilable on their own: NEW./OLD. columns and RAISE(...) become NULL. */
+function triggerBodies(sql: string): string[] {
+  const out: string[] = [];
+  for (const st of splitStatements(tokenize(sql))) {
+    const words = st.filter((t) => t.kind === "word").map((t) => (t as { upper: string }).upper);
+    if (words[0] !== "CREATE" || !words.slice(0, 4).includes("TRIGGER")) continue;
+    const begin = st.findIndex((t) => t.kind === "word" && (t as { upper: string }).upper === "BEGIN");
+    const body = st.slice(begin + 1, -1); // up to the final END
+    out.push(...bodyStatements(sql, body));
+  }
+  return out;
+}
+
+/**
+ * Rebuilds a trigger body's statements from the source text, keeping what
+ * sits between tokens (so `!=` stays one operator), with NEW./OLD. columns
+ * and RAISE(...) replaced by NULL so each compiles on its own.
+ */
+function bodyStatements(sql: string, body: readonly Token[]): string[] {
+  const stmts: string[] = [];
+  let cur = "";
+  let last = body[0]?.start ?? 0;
+  const emit = (text: string, start: number, end: number) => {
+    cur += sql.slice(last, start) + text;
+    last = end;
+  };
+  for (let i = 0; i < body.length; i++) {
+    const t = body[i] as Token;
+    const up = t.kind === "word" ? (t as { upper: string }).upper : "";
+    if ((up === "NEW" || up === "OLD") && body[i + 1]?.text === "." && body[i + 2]) {
+      emit("NULL", t.start, (body[i + 2] as Token).end);
+      i += 2;
+      continue;
+    }
+    if (up === "RAISE" && body[i + 1]?.text === "(") {
+      let depth = 0;
+      let j = i + 1;
+      for (; j < body.length; j++) {
+        if (body[j]?.text === "(") depth++;
+        if (body[j]?.text === ")" && --depth === 0) break;
+      }
+      emit("NULL", t.start, (body[Math.min(j, body.length - 1)] as Token).end);
+      i = j;
+      continue;
+    }
+    if (t.text === ";") {
+      cur += sql.slice(last, t.start);
+      if (cur.trim()) stmts.push(cur.trim());
+      cur = "";
+      last = t.end;
+      continue;
+    }
+    emit(sql.slice(t.start, t.end), t.start, t.end);
+  }
+  if (cur.trim()) stmts.push(cur.trim());
+  return stmts;
+}
+
+export interface VerifyInput {
+  /** Core's migration files, in order. */
+  coreSql: readonly string[];
+  plugins: readonly {
+    // biome-ignore lint/suspicious/noExplicitAny: each plugin brings its own options type
+    definition: PluginDefinition<any>;
+    /** The SQL the plugin builds at runtime, from the linter's sample inputs. */
+    runtime: readonly { where: string; sql: string; context?: string }[];
+    historicalFacts?: readonly FactTable[];
+  }[];
+}
+
+/** Compiles every plugin statement against the real schema and judges what SQLite says it touches. */
+export function verifyWithSqlite(input: VerifyInput): (LintIssue & { plugin: string })[] {
+  const db = new DatabaseSync(":memory:");
+  const issues: (LintIssue & { plugin: string })[] = [];
+  // One transaction per migration, as D1 applies one: a migration's marker
+  // (p0.5 §7.1) is a deferred obligation checked at its commit, not per statement.
+  const run = (text: string) => {
+    db.exec("BEGIN");
+    for (const part of text.split(BREAK)) for (const s of statementTexts(part)) db.exec(`${s};`);
+    db.exec("COMMIT");
+  };
+  for (const text of input.coreSql) run(text);
+  // Generated entity tables are core's SQL, installed as is, so plugin SQL
+  // that reads one compiles (codex code r2). Fields are never removed (§4.3),
+  // so the current declaration's table has every column history gave it.
+  // Their triggers too, so SQLite compiles every generated one (codex code r7).
+  for (const p of input.plugins)
+    for (const [entity, def] of Object.entries(p.definition.entities ?? {}))
+      run(
+        [
+          ...createEntitySql(p.definition.name, entity, def),
+          ...entityTriggersSql(p.definition.name, entity, def, ""),
+        ].join(BREAK),
+      );
+
+  let accesses: Access[] = [];
+  const reportedKeys = new Set<string>();
+  const record = (action: number, a: string | null, b: string | null, dbName: string | null, source: string | null) => {
+    accesses.push([action, a ?? null, b ?? null, dbName ?? null, source ?? null]);
+    return 0;
+  };
+  db.setAuthorizer(record);
+  const names = () =>
+    new Set(
+      (db.prepare("SELECT name, tbl_name FROM sqlite_master").all() as { name: string; tbl_name: string }[]).map(
+        (r) => `${r.name}\u0000${r.tbl_name}`,
+      ),
+    );
+  let facts = new Set<string>();
+  const check = (plugin: string, where: string, text: string, ddl: boolean, execute: boolean) => {
+    const own = (name: string) => name.startsWith(`plg_${plugin}_`);
+    accesses = [];
+    try {
+      if (execute) {
+        // The authorizer doesn't report where a rename lands, so compare the
+        // schema: every object a migration statement leaves behind is the owner's.
+        db.setAuthorizer(null);
+        const before = names();
+        db.setAuthorizer(record);
+        db.exec(`${text};`);
+        db.setAuthorizer(null);
+        for (const n of names()) {
+          if (before.has(n)) continue;
+          const [name = "", table = ""] = n.split("\u0000");
+          if (!(own(name) || name.startsWith(`sqlite_autoindex_${table}_`)) || !own(table))
+            issues.push({
+              plugin,
+              rule: "prefix",
+              message: `leaves "${name}" on "${table}" outside ${`plg_${plugin}_`}…`,
+              at: where,
+            });
+        }
+        // Every foreign key from the owner's tables to core, however it was
+        // declared (CREATE TABLE or ADD COLUMN), is NO ACTION: core rebuilds its
+        // tables, and SQLite fires CASCADE and SET NULL on that drop.
+        const tables = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all() as { name: string }[];
+        for (const { name } of tables.filter((t) => own(t.name))) {
+          const fks = db.prepare(`SELECT "table", on_update, on_delete FROM pragma_foreign_key_list(?)`).all(name) as {
+            table: string;
+            on_update: string;
+            on_delete: string;
+          }[];
+          for (const fk of fks) {
+            if (own(fk.table)) continue;
+            const key = `${plugin}:${name}:${fk.table}`;
+            if ((fk.on_update !== "NO ACTION" || fk.on_delete !== "NO ACTION") && !reportedKeys.has(key)) {
+              reportedKeys.add(key);
+              issues.push({
+                plugin,
+                rule: "core-fk-action",
+                message: `${name} → ${fk.table} must be NO ACTION`,
+                at: where,
+              });
+            }
+          }
+        }
+        db.setAuthorizer(record);
+      } else db.prepare(text);
+    } catch (e) {
+      issues.push({
+        plugin,
+        rule: "invalid-sql",
+        message: `doesn't compile against the schema: ${(e as Error).message}`,
+        at: where,
+      });
+      return;
+    }
+    judge(accesses, own, ddl, (rule, message) =>
+      issues.push({ plugin, rule, message, at: `${where}: ${text.slice(0, 60)}` }),
+    );
+    // A fact table, current or once declared, holds facts that back money and
+    // pending releases. SQLite runs no DELETE trigger on DROP TABLE, so a
+    // rebuild that drops or renames one could lose them unseen; until core has
+    // a controlled way to move facts, it is refused.
+    for (const [action, a, b] of accesses) {
+      // ALTER TABLE is one action for ADD COLUMN and RENAME alike; only a rename moves the table.
+      const renames = /^\s*ALTER\s+TABLE\b[\s\S]*\bRENAME\b/i.test(text);
+      const table = action === A.DROP_TABLE ? a : action === A.ALTER_TABLE && renames ? b : null;
+      if (table && facts.has(table))
+        issues.push({
+          plugin,
+          rule: "fact-table-change",
+          message: `"${table}" holds plugin facts; it can't be dropped or renamed`,
+          at: where,
+        });
+    }
+  };
+
+  for (const p of input.plugins) {
+    const def = p.definition;
+    facts = new Set(factTables(def, p.historicalFacts ?? []).map((f) => f.table));
+    for (const m of def.migrations ?? []) {
+      for (const s of statementTexts(m.sql)) check(def.name, m.id, s, true, true);
+      for (const s of triggerBodies(m.sql)) check(def.name, `${m.id} trigger body`, s, false, false);
+    }
+    // Core-owned SQL is installed as is, then the plugin's runtime SQL is compiled against all of it.
+    db.setAuthorizer(null);
+    run([...factGuardSql(def, p.historicalFacts ?? []), ...acquireSql(def)].join(BREAK));
+    db.setAuthorizer(record);
+    for (const [key, body] of Object.entries(def.acquire ?? {})) {
+      for (const s of bodyStatements(body as string, tokenize(body as string)))
+        check(def.name, `acquire ${key}`, s, false, false);
+    }
+    // Acquire bodies were checked above, with NEW. columns made compilable.
+    for (const r of p.runtime) if (r.context !== "acquire") check(def.name, r.where, r.sql, false, false);
+  }
+  return issues;
+}

package/src/store.ts

@@ -0,0 +1,132 @@
+// What a deploy knows about the store before it touches Cloudflare: its names,
+// from wrangler.jsonc (create-kedge gave them a random suffix, so nothing else
+// in the account chooses them, p0.8 §6.1), its Git state, and the effective
+// config a plan freezes.
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { readWrangler } from "./doctor";
+import { installedPackages } from "./manifest";
+import { byCodePoint } from "./order";
+
+/** The starter's id until a first deploy writes the real one (§6.1). */
+export const PLACEHOLDER_ID = "00000000-0000-0000-0000-000000000000";
+
+export interface StoreNames {
+  worker: string;
+  database: string;
+  databaseId: string;
+  queue: string;
+  ops: string;
+}
+
+export type WranglerJson = Record<string, unknown> & {
+  name?: string;
+  main?: string;
+  d1_databases?: { binding?: string; database_name?: string; database_id?: string; migrations_dir?: string }[];
+  queues?: { producers?: { binding?: string; queue?: string }[]; consumers?: { queue?: string }[] };
+  migrations?: Record<string, unknown>[];
+  triggers?: { crons?: string[] };
+  vars?: Record<string, string>;
+  routes?: unknown;
+  route?: unknown;
+  /** The admin's static assets (p0.9 §2.1). */
+  assets?: { directory?: string; binding?: string; not_found_handling?: string; run_worker_first?: unknown };
+};
+
+export function storeNames(cwd: string): { names: StoreNames; config: WranglerJson; file: string } {
+  const w = readWrangler(cwd);
+  if (!w) throw new Error("no wrangler.jsonc in this directory");
+  const config = w.config as WranglerJson;
+  const db = config.d1_databases?.find((d) => d.binding === "DB");
+  const queue = config.queues?.producers?.find((q) => q.binding === "EVENTS")?.queue;
+  if (!config.name || !db?.database_name || !queue)
+    throw new Error("wrangler.jsonc needs a name, a DB database and an EVENTS queue");
+  return {
+    names: {
+      worker: config.name,
+      database: db.database_name,
+      databaseId: db.database_id ?? PLACEHOLDER_ID,
+      queue,
+      ops: `${config.name}-ops`,
+    },
+    config,
+    file: w.file,
+  };
+}
+
+export const sha256 = (b: Buffer | string) => createHash("sha256").update(b).digest("hex");
+
+export interface Git {
+  head(): string;
+  /** Paths with uncommitted changes. */
+  dirty(): string[];
+  /** HEAD's version of a file, or null. */
+  show(path: string): string | null;
+  isAncestor(older: string, newer: string): boolean;
+}
+
+export function git(cwd: string): Git {
+  const run = (args: string[]) => spawnSync("git", args, { cwd, encoding: "utf8" });
+  return {
+    head() {
+      const r = run(["rev-parse", "HEAD"]);
+      if (r.status !== 0) throw new Error("kedge deploy needs a Git repository with a commit");
+      return r.stdout.trim();
+    },
+    dirty() {
+      return run(["status", "--porcelain"])
+        .stdout.split("\n")
+        .filter(Boolean)
+        .map((l) => l.slice(3));
+    },
+    show(path) {
+      const r = run(["show", `HEAD:${path}`]);
+      return r.status === 0 ? r.stdout : null;
+    },
+    isAncestor(older, newer) {
+      return run(["merge-base", "--is-ancestor", older, newer]).status === 0;
+    },
+  };
+}
+
+/**
+ * A dirty worktree refuses a deploy, so the plan is the commit's alone, with
+ * one exception: wrangler.jsonc whose only change is the first deploy writing
+ * the database id over the placeholder (§6.1).
+ */
+export function dirtyBeyondId(cwd: string, g: Git, databaseId: string | null): string[] {
+  return g.dirty().filter((p) => {
+    if (p !== "wrangler.jsonc" || !databaseId) return true;
+    const head = g.show("wrangler.jsonc");
+    return head === null || head.replace(PLACEHOLDER_ID, databaseId) !== readFileSync(join(cwd, p), "utf8");
+  });
+}
+
+/** Every file under a directory with its sha256, by path inside it. */
+export function hashTree(dir: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  const walk = (d: string) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.isFile()) out[relative(dir, p)] = sha256(readFileSync(p));
+    }
+  };
+  if (existsSync(dir)) walk(dir);
+  return Object.fromEntries(Object.entries(out).sort(([a], [b]) => byCodePoint(a, b)));
+}
+
+/** The store's installed Kedge, by package and version. */
+export function packageVersions(cwd: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [name, dir] of installedPackages(cwd))
+    out[name] = (JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as { version: string }).version;
+  return Object.fromEntries(Object.entries(out).sort(([a], [b]) => byCodePoint(a, b)));
+}
+
+/** The DO classes a migrations list leaves declared, as a stable key for "did the lifecycle change". */
+export function classesKey(migrations: WranglerJson["migrations"] = []): string {
+  return JSON.stringify(migrations);
+}

package/src/tar.ts

@@ -0,0 +1,125 @@
+// A tar stream, read as data (docs/proposals/p0.8-cli-agent-kit.md §5.3). A
+// preview's plan may come from somewhere untrusted, so `preview apply` never
+// opens its directory: a path check on a directory can't be made safe
+// (`modules/leak -> /proc/self` makes `modules/leak/environ` look like a
+// regular file, and a source can be swapped between check and read). In a
+// stream a symlink is only an entry, which this refuses.
+
+export interface TarEntry {
+  path: string;
+  data: Buffer;
+}
+
+export class TarRefused extends Error {
+  constructor(message: string) {
+    super(`the plan's tar stream is refused: ${message}`);
+    this.name = "TarRefused";
+  }
+}
+
+const field = (b: Buffer, at: number, len: number) =>
+  b
+    .subarray(at, at + len)
+    .toString("utf8")
+    .replace(/\0.*$/s, "");
+/** An octal field: digits 0–7 only, so no sign and no base-256 form; anything else is NaN and refuses. */
+const octal = (b: Buffer, at: number, len: number) => {
+  const s = field(b, at, len).trim();
+  if (s === "") return 0;
+  return /^[0-7]+$/.test(s) ? Number.parseInt(s, 8) : Number.NaN;
+};
+
+/** Pax records (`<len> key=value\n`): only `path` matters here. */
+function paxPath(data: Buffer): string | null {
+  let rest = data.toString("utf8");
+  while (rest.length) {
+    const sp = rest.indexOf(" ");
+    const len = Number.parseInt(rest.slice(0, sp), 10);
+    if (!Number.isFinite(len) || len <= 0) break;
+    const rec = rest.slice(sp + 1, len - 1);
+    const eq = rec.indexOf("=");
+    if (rec.slice(0, eq) === "path") return rec.slice(eq + 1);
+    rest = rest.slice(len);
+  }
+  return null;
+}
+
+/** Regular files only, with limits enforced while reading. Directories are skipped; anything else refuses. */
+export function readTar(stream: Buffer, limits: { files: number; fileBytes: number; totalBytes: number }): TarEntry[] {
+  const out: TarEntry[] = [];
+  let total = 0;
+  let entries = 0;
+  let at = 0;
+  let nextPath: string | null = null;
+  while (at + 512 <= stream.length) {
+    const h = stream.subarray(at, at + 512);
+    if (h.every((x) => x === 0)) break;
+    let sum = 0;
+    for (let i = 0; i < 512; i++) sum += i >= 148 && i < 156 ? 32 : (h[i] as number);
+    if (sum !== octal(h, 148, 8)) throw new TarRefused("a header's checksum is wrong");
+    const size = octal(h, 124, 12);
+    // A negative or unparsable size would hold the cursor still and loop the trusted process (codex code r2).
+    if (!Number.isSafeInteger(size) || size < 0)
+      throw new TarRefused("an entry's size isn't a plain non-negative number");
+    // Every entry counts against the limits, metadata included, so none can be repeated without end.
+    if (++entries > limits.files * 4) throw new TarRefused(`more than ${limits.files * 4} entries`);
+    total += size;
+    if (total > limits.totalBytes) throw new TarRefused(`the plan is over ${limits.totalBytes} bytes`);
+    const type = String.fromCharCode(h[156] as number);
+    const prefix = field(h, 345, 155);
+    const name = prefix ? `${prefix}/${field(h, 0, 100)}` : field(h, 0, 100);
+    const start = at + 512;
+    const end = start + size;
+    if (end > stream.length) throw new TarRefused("an entry runs past the stream's end");
+    const data = stream.subarray(start, end);
+    at = start + Math.ceil(size / 512) * 512;
+    if (type === "x") {
+      nextPath = paxPath(data);
+      continue;
+    }
+    if (type === "g") continue;
+    if (type === "L") {
+      nextPath = data.toString("utf8").replace(/\0.*$/s, "");
+      continue;
+    }
+    const path = (nextPath ?? name).replace(/^\.\//, "");
+    nextPath = null;
+    if (type === "5") continue;
+    if (type !== "0" && type !== "\0")
+      throw new TarRefused(
+        `${path} isn't a regular file (type ${JSON.stringify(type)}): links and devices aren't taken`,
+      );
+    if (path === "" || path.startsWith("/") || path.split("/").includes("..") || path.includes("\\"))
+      throw new TarRefused(`${path} is absolute or climbs out`);
+    if (size > limits.fileBytes) throw new TarRefused(`${path} is over ${limits.fileBytes} bytes`);
+    if (out.length >= limits.files) throw new TarRefused(`more than ${limits.files} files`);
+    if (out.some((e) => e.path === path)) throw new TarRefused(`${path} appears twice`);
+    out.push({ path, data: Buffer.from(data) });
+  }
+  return out;
+}
+
+/** A plain ustar stream of regular files, for the plan `preview build` hands `apply`. */
+export function writeTar(entries: readonly TarEntry[]): Buffer {
+  const chunks: Buffer[] = [];
+  for (const e of entries) {
+    if (Buffer.byteLength(e.path) > 100) throw new Error(`${e.path} is too long for a plan`);
+    const h = Buffer.alloc(512);
+    h.write(e.path, 0, "utf8");
+    h.write("0000644\0", 100);
+    h.write("0000000\0", 108);
+    h.write("0000000\0", 116);
+    h.write(`${e.data.length.toString(8).padStart(11, "0")}\0`, 124);
+    h.write("00000000000\0", 136);
+    h.write("        ", 148);
+    h.write("0", 156);
+    h.write("ustar\0", 257);
+    h.write("00", 263);
+    let sum = 0;
+    for (const x of h) sum += x;
+    h.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148);
+    chunks.push(h, e.data, Buffer.alloc((512 - (e.data.length % 512)) % 512));
+  }
+  chunks.push(Buffer.alloc(1024));
+  return Buffer.concat(chunks);
+}