@kedge/cli 0.0.0-stage → 0.10.0

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);
+}

package/src/target.ts

@@ -0,0 +1,81 @@
+// Which store a URL is (docs/proposals/p0.10-agent-path.md §4, §6.2). The CLI
+// sends a session, a saved key or a run's record only to a target it can name
+// by identity: production or a preview this store's `<store>-ops` records, or
+// `kedge dev` on this machine. Anything else gets nothing, so an unknown
+// endpoint never receives a token. A store is its account, Worker and
+// database, not its URL: the account's owner can change the workers.dev
+// subdomain, so the URL is computed from the current one on every run.
+import type { Cloudflare } from "./cf";
+import { openOps } from "./deploy";
+import { storeNames } from "./store";
+
+export interface StoreTarget {
+  kind: "production" | "preview" | "local";
+  /** The origin requests go to. */
+  url: string;
+  /** What records bind to: never the URL. A local target's account is `local`. */
+  identity: { account: string; worker: string; database: string };
+  /** Where a CLI session's row is written: that target's own database, and no other. */
+  database: { name: string; id: string | null };
+}
+
+/**
+ * `kedge dev`'s port: the config's `dev.port`, else Wrangler's default 8787
+ * (`DEFAULT_LOCAL_PORT`, wrangler-dist/cli.js:212493, 4.152.0). When 8787 is
+ * taken Wrangler picks another (`memoizeGetPort`, :213241), which then isn't a
+ * target: the command asks for `--key` or `--session` instead.
+ */
+export function devPort(cwd: string): number {
+  const dev = storeNames(cwd).config.dev as { port?: unknown } | undefined;
+  return typeof dev?.port === "number" ? dev.port : 8787;
+}
+
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+/** The target `url` names, or null when it's none this checkout knows. */
+export async function resolveTarget(
+  url: string,
+  cwd: string,
+  cloudflare: () => Promise<Cloudflare>,
+): Promise<StoreTarget | null> {
+  const u = new URL(url);
+  const { names } = storeNames(cwd);
+  if (LOCAL_HOSTS.has(u.hostname)) {
+    if (u.protocol !== "http:" || Number(u.port || 80) !== devPort(cwd)) return null;
+    return {
+      kind: "local",
+      url: u.origin,
+      identity: { account: "local", worker: names.worker, database: "local" },
+      database: { name: names.database, id: null },
+    };
+  }
+  if (u.protocol !== "https:") return null;
+  const cf = await cloudflare();
+  // A lookup, never a create: a store never deployed has no target here.
+  if (!(await cf.findD1(names.ops))) return null;
+  const { ops } = await openOps(cf, names);
+  const host = (worker: string, subdomain: string) => `https://${worker}.${subdomain}.workers.dev`;
+  const subdomain = await cf.workersSubdomain();
+  if (u.origin === host(names.worker, subdomain)) {
+    const db = await ops.resource("d1", names.database);
+    if (!db?.id) return null;
+    return {
+      kind: "production",
+      url: u.origin,
+      identity: { account: cf.account, worker: names.worker, database: db.id },
+      database: { name: names.database, id: db.id },
+    };
+  }
+  // The whole origin, as a preview's is made: a host that only begins with a preview's name isn't it.
+  const rows = await ops.query(
+    "SELECT worker, database_name, database_id FROM preview WHERE state = 'bootstrapped' AND database_id IS NOT NULL",
+  );
+  const p = rows.find((r) => u.origin === host(String(r.worker), subdomain));
+  if (!p) return null;
+  return {
+    kind: "preview",
+    url: u.origin,
+    identity: { account: cf.account, worker: String(p.worker), database: String(p.database_id) },
+    database: { name: String(p.database_name), id: String(p.database_id) },
+  };
+}

package/src/tz.ts

@@ -0,0 +1,79 @@
+// Pinning the store's timezone rules (p0.4-dated-capacity.md §4): `kedge
+// generate` compiles the configured zone from the generating Node's IANA
+// data once, writes the table the Worker passes to createKedge, and composes
+// a migration loading the same rows into tz_transition and pinning
+// store_time. Generating again never changes a pinned version (until P2.3).
+import { compileZone, intlOffsetSeconds, markedMigrationSql, type TzTable } from "@kedge/core";
+
+/** Rows per INSERT: well under D1's statement size limit. */
+const ROWS_PER_INSERT = 500;
+
+/** The zone's transitions from 1970 to 9999 under this toolchain's IANA data. */
+export function compileStoreZone(zone: string): TzTable {
+  const version = process.versions.tz;
+  if (!version) throw new Error("This Node has no IANA tz data version (process.versions.tz)");
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: zone });
+  } catch {
+    throw new Error(`kedge.config.ts: "${zone}" isn't an IANA zone this toolchain knows`);
+  }
+  return compileZone(zone, version, intlOffsetSeconds(zone), {
+    from: 0,
+    to: Date.UTC(9999, 11, 31, 23, 59, 59),
+    // Historical rules can change twice within a week; future ones are seasonal.
+    denseUntil: Date.UTC(2050, 0, 1),
+  });
+}
+
+const sqlText = (s: string) => `'${s.replaceAll("'", "''")}'`;
+
+/**
+ * The migration that pins the zone: refused once any dated row recorded the
+ * previous rules (a booking's labels would change under it), then the rows,
+ * then store_time.
+ */
+export function tzMigrationSql(tz: TzTable): string {
+  const v = sqlText(tz.version);
+  const rows: [number, number][] = [
+    [0, tz.initialOffset],
+    ...tz.at.map((t, i) => [t, tz.offsets[i] as number] as [number, number]),
+  ];
+  const inserts: string[] = [];
+  for (let i = 0; i < rows.length; i += ROWS_PER_INSERT) {
+    const chunk = rows.slice(i, i + ROWS_PER_INSERT).map(([at, off]) => `(${v}, ${at}, ${off})`);
+    inserts.push(`INSERT INTO tz_transition (version, at_utc, offset_seconds) VALUES ${chunk.join(", ")};`);
+  }
+  return [
+    `-- ${tz.zone} at IANA ${tz.version}, pinned by kedge generate (p0.4 §4). A store's zone and
+-- rules are fixed once any dated row exists: the guard refuses this migration then.
+CREATE TABLE _kedge_tz_guard (dated integer NOT NULL CONSTRAINT kedge_tz_pinned CHECK (dated = 0));`,
+    `INSERT INTO _kedge_tz_guard (dated)
+  SELECT (SELECT count(*) FROM (SELECT 1 FROM capacity_pool LIMIT 1))
+       + (SELECT count(*) FROM (SELECT 1 FROM capacity_adjustment LIMIT 1))
+       + (SELECT count(*) FROM (SELECT 1 FROM order_line_period_provenance WHERE source = 'wall_time' LIMIT 1));`,
+    "DROP TABLE _kedge_tz_guard;",
+    // tz_transition and store_time are fenced core tables (p0.5 §7.1).
+    markedMigrationSql("migration:tz", [
+      ...inserts,
+      `UPDATE store_time SET zone = ${sqlText(tz.zone)}, tz_rules_version = ${v} WHERE id = 1;`,
+    ]),
+  ].join("\n--> statement-breakpoint\n");
+}
+
+/** src/kedge.tz.ts: the same table, for createKedge(config, { tz }). */
+export function tzModule(tz: TzTable): string {
+  const what =
+    tz.version === "utc" ? "UTC, the store's default until a zone is configured" : `${tz.zone} at IANA ${tz.version}`;
+  return `// Generated by kedge generate: ${what}, pinned (p0.4 §4).
+// Never edit: the database holds the same rows, and the checkout claim compares versions.
+import type { TzTable } from "@kedge/runtime-cf";
+
+export const tz: TzTable = {
+  zone: ${JSON.stringify(tz.zone)},
+  version: ${JSON.stringify(tz.version)},
+  initialOffset: ${tz.initialOffset},
+  at: [${tz.at.join(",")}],
+  offsets: [${tz.offsets.join(",")}],
+};
+`;
+}

package/src/units.ts

@@ -0,0 +1,185 @@
+// `kedge eject` and doctor's `unit-drift` (docs/proposals/p0.8-cli-agent-kit.md §7):
+// one unit of core copied into the store with the upstream's hash recorded,
+// and, when an upgrade changes that upstream, a failing check that prints the
+// diff. Merging is by hand, then `kedge eject --rebase`: overwriting a
+// customised copy is how upstream changes get lost (research/14 §1).
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { KedgeConfig } from "@kedge/core";
+import type { CheckResult } from "./doctor";
+import { installedPackages, type Manifest } from "./manifest";
+import { sha256 } from "./store";
+
+export interface EjectHeader {
+  unit: string;
+  version: string;
+  upstreamSha256: string;
+}
+
+const HEADER = /^\/\/ kedge-eject: (\{.*\})$/m;
+const overridesDir = (cwd: string) => join(cwd, "src", "overrides");
+const origFile = (cwd: string, unit: string) => join(cwd, ".kedge", "eject", `${unit}.orig.ts`);
+
+/** The installed upstream source of a unit, by the manifest's package and path. */
+export function upstreamSource(cwd: string, manifest: Manifest, unit: string): string {
+  const u = manifest.units[unit];
+  if (!u)
+    throw new Error(
+      `"${unit}" isn't an ejectable unit of Kedge ${manifest.version}: ${Object.keys(manifest.units).join(", ") || "none"}`,
+    );
+  const dir = installedPackages(cwd).get(u.package);
+  if (!dir) throw new Error(`${u.package} isn't installed`);
+  return readFileSync(join(dir, u.path), "utf8");
+}
+
+export function header(text: string): EjectHeader | null {
+  const m = HEADER.exec(text);
+  if (!m) return null;
+  try {
+    return JSON.parse(m[1] as string) as EjectHeader;
+  } catch {
+    return null;
+  }
+}
+
+const identifier = (unit: string) => unit.replace(/[.-](\w)/g, (_, c: string) => c.toUpperCase());
+
+export function eject(cwd: string, manifest: Manifest, unit: string, reason: string): { file: string; wiring: string } {
+  if (!reason.trim())
+    throw new Error('kedge eject needs --reason "<why>": a higher rung couldn\'t do this, and the header says why');
+  const source = upstreamSource(cwd, manifest, unit);
+  const file = join(overridesDir(cwd), `${unit}.ts`);
+  if (existsSync(file))
+    throw new Error(`${unit} is already ejected; after merging an upstream change, kedge eject --rebase ${unit}`);
+  const h: EjectHeader = { unit, version: manifest.version, upstreamSha256: sha256(source) };
+  mkdirSync(overridesDir(cwd), { recursive: true });
+  writeFileSync(file, `// kedge-eject: ${JSON.stringify(h)}\n// Why: ${reason.replace(/\n/g, " ")}\n${source}`);
+  mkdirSync(join(cwd, ".kedge", "eject"), { recursive: true });
+  writeFileSync(origFile(cwd, unit), source);
+  const id = identifier(unit);
+  return {
+    file,
+    wiring: `import ${id} from "./src/overrides/${unit}";\n// in defineConfig({ … }):\n  overrides: { "${unit}": ${id} },`,
+  };
+}
+
+/** After a hand merge: the recorded upstream becomes the installed one. */
+export function rebase(cwd: string, manifest: Manifest, unit: string): void {
+  const file = join(overridesDir(cwd), `${unit}.ts`);
+  if (!existsSync(file)) throw new Error(`${unit} isn't ejected`);
+  const text = readFileSync(file, "utf8");
+  const h = header(text);
+  if (!h) throw new Error(`${file} has no kedge-eject header`);
+  const source = upstreamSource(cwd, manifest, unit);
+  const next: EjectHeader = { unit, version: manifest.version, upstreamSha256: sha256(source) };
+  writeFileSync(file, text.replace(HEADER, `// kedge-eject: ${JSON.stringify(next)}`));
+  writeFileSync(origFile(cwd, unit), source);
+}
+
+/** A unified diff of two texts, by longest common subsequence of lines. */
+export function unifiedDiff(a: string, b: string, aName: string, bName: string, context = 3): string {
+  const x = a.split("\n");
+  const y = b.split("\n");
+  const n = x.length;
+  const m = y.length;
+  const lcs: number[][] = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0));
+  for (let i = n - 1; i >= 0; i--)
+    for (let j = m - 1; j >= 0; j--)
+      (lcs[i] as number[])[j] =
+        x[i] === y[j]
+          ? ((lcs[i + 1] as number[])[j + 1] as number) + 1
+          : Math.max((lcs[i + 1] as number[])[j] as number, (lcs[i] as number[])[j + 1] as number);
+  const ops: { t: " " | "-" | "+"; s: string; ai: number; bi: number }[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < n || j < m) {
+    if (i < n && j < m && x[i] === y[j]) ops.push({ t: " ", s: x[i++] as string, ai: i, bi: ++j });
+    // A deletion before an addition, as diff -u prints them.
+    else if (i < n && (j >= m || ((lcs[i + 1] as number[])[j] as number) >= ((lcs[i] as number[])[j + 1] as number)))
+      ops.push({ t: "-", s: x[i++] as string, ai: i, bi: j });
+    else ops.push({ t: "+", s: y[j++] as string, ai: i, bi: j });
+  }
+  const out = [`--- ${aName}`, `+++ ${bName}`];
+  let k = 0;
+  while (k < ops.length) {
+    if ((ops[k] as { t: string }).t === " ") {
+      k++;
+      continue;
+    }
+    const start = Math.max(0, k - context);
+    let end = k;
+    while (end < ops.length) {
+      let next = end;
+      while (next < ops.length && (ops[next] as { t: string }).t === " ") next++;
+      if (next >= ops.length || next - end > context * 2) break;
+      end = next + 1;
+    }
+    end = Math.min(ops.length, end + context);
+    const hunk = ops.slice(start, end);
+    out.push(`@@ -${hunk[0]?.ai ?? 1} +${hunk[0]?.bi ?? 1} @@`);
+    for (const o of hunk) out.push(`${o.t}${o.s}`);
+    k = end;
+  }
+  return out.join("\n");
+}
+
+/** The upgrade notes' entries that name a unit, from the installed @kedge/docs. */
+function notesFor(cwd: string, unit: string): string[] {
+  const docs = installedPackages(cwd).get("@kedge/docs");
+  if (!docs || !existsSync(join(docs, "upgrading"))) return [];
+  const out: string[] = [];
+  for (const f of readdirSync(join(docs, "upgrading")).filter((f) => f.endsWith(".md"))) {
+    const text = readFileSync(join(docs, "upgrading", f), "utf8");
+    if (text.includes(`unit:${unit}`)) out.push(`upgrading/${f} names ${unit}`);
+  }
+  return out;
+}
+
+/** Doctor's `unit-drift` (§7.3). */
+export function unitDrift(
+  cwd: string,
+  manifest: Manifest | null,
+  config: KedgeConfig | null,
+  o: { ignoreWiring?: boolean } = {},
+): CheckResult {
+  const dir = overridesDir(cwd);
+  const files = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith(".ts")) : [];
+  const wired = Object.keys(config?.overrides ?? {});
+  if (files.length === 0 && wired.length === 0) return { name: "unit-drift", status: "pass" };
+  if (!manifest) return { name: "unit-drift", status: "skip", message: "no release manifest (a workspace install)" };
+  const problems: string[] = [];
+  const seen = new Set<string>();
+  for (const f of files) {
+    const unit = f.slice(0, -3);
+    seen.add(unit);
+    const h = header(readFileSync(join(dir, f), "utf8"));
+    if (!h || h.unit !== unit) {
+      problems.push(
+        `src/overrides/${f} has no kedge-eject header naming ${unit}: eject with kedge eject, never by hand`,
+      );
+      continue;
+    }
+    const u = manifest.units[unit];
+    if (!u) {
+      problems.push(`${unit} isn't an ejectable unit of Kedge ${manifest.version}`);
+      continue;
+    }
+    if (!o.ignoreWiring && !wired.includes(unit))
+      problems.push(`${unit} is ejected but not wired: add it to overrides in kedge.config.ts`);
+    if (u.sha256 !== h.upstreamSha256) {
+      const orig = existsSync(origFile(cwd, unit)) ? readFileSync(origFile(cwd, unit), "utf8") : "";
+      const now = upstreamSource(cwd, manifest, unit);
+      problems.push(
+        `${unit} was ejected from ${h.version}, and Kedge ${manifest.version} changed it upstream: merge the change below by hand, then kedge eject --rebase ${unit}`,
+        ...notesFor(cwd, unit),
+        ...unifiedDiff(orig, now, `${unit} (${h.version})`, `${unit} (${manifest.version})`).split("\n"),
+      );
+    }
+  }
+  if (!o.ignoreWiring)
+    for (const w of wired)
+      if (!seen.has(w)) problems.push(`overrides wires ${w}, but src/overrides/${w}.ts doesn't exist`);
+  return problems.length
+    ? { name: "unit-drift", status: "fail", message: "an ejected unit drifted from its upstream", details: problems }
+    : { name: "unit-drift", status: "pass", message: `${files.length} ejected unit${files.length === 1 ? "" : "s"}` };
+}