@kedge/cli 0.0.0-stage → 0.9.0

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"}` };
+}

package/src/upgrade.ts

@@ -0,0 +1,235 @@
+// `kedge upgrade --to <version>` (docs/proposals/p0.8-cli-agent-kit.md §8.2).
+// Medusa's rule: cover every release in between and stop on the first failure
+// rather than pile on speculative fixes (research/14 §1). Hydrogen's: write what
+// a codemod can't do to a file. And Kedge's own: a deploy refuses a release not
+// proven against the one serving, and composed migrations can't be un-composed,
+// so a target more than one supported step away refuses before anything changes.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { isMap, parse, parseDocument } from "yaml";
+import { installedPackages, type Manifest } from "./manifest";
+import { byCodePoint } from "./order";
+import type { Git } from "./store";
+import { unitDrift } from "./units";
+
+export interface NoteEntry {
+  id: string;
+  affects?: string[];
+  detect?: string;
+  codemod?: string | null;
+  manual?: string;
+  verify?: string;
+}
+
+export interface UpgradeNote {
+  version: string;
+  upgradesFrom: string | null;
+  /** Packages this release adds to a store, written in before the install (p0.9 §3.2). */
+  adds?: string[];
+  entries: NoteEntry[];
+}
+
+export class UpgradeRefused extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UpgradeRefused";
+  }
+}
+
+export function readNotes(dir: string): Map<string, UpgradeNote> {
+  const out = new Map<string, UpgradeNote>();
+  if (!existsSync(dir)) return out;
+  for (const f of readdirSync(dir).filter((f) => f.endsWith(".md"))) {
+    const m = /^---\n([\s\S]*?)\n---\n/.exec(readFileSync(join(dir, f), "utf8"));
+    if (!m) continue;
+    const fm = parse(m[1] as string) as Partial<UpgradeNote>;
+    if (typeof fm.version === "string")
+      out.set(fm.version, {
+        version: fm.version,
+        upgradesFrom: fm.upgradesFrom ?? null,
+        ...(Array.isArray(fm.adds)
+          ? { adds: fm.adds.filter((a) => typeof a === "string" && a.startsWith("@kedge/")) }
+          : {}),
+        entries: fm.entries ?? [],
+      });
+  }
+  return out;
+}
+
+/** The releases from `current` to `target`, each proven against the one before; null when there's no such chain. */
+export function chain(notes: ReadonlyMap<string, UpgradeNote>, current: string, target: string): string[] | null {
+  const stages: string[] = [];
+  let at: string | null = target;
+  while (at && at !== current) {
+    stages.unshift(at);
+    if (stages.length > 50) return null;
+    at = notes.get(at)?.upgradesFrom ?? null;
+  }
+  return at === current ? stages : null;
+}
+
+export interface UpgradeInput {
+  cwd: string;
+  to: string;
+  fromPacks?: string;
+  git: Git;
+  manifest: (cwd: string) => Manifest | null;
+  /** Runs a command in the store; tests replace it. */
+  run?: (cmd: string, args: string[], cwd: string) => number;
+  /** `kedge generate` then `kedge check`, by the CLI the upgrade just installed, never this process's older one. */
+  kedge: (argv: string[]) => Promise<number>;
+  log?: (s: string) => void;
+}
+
+/** The target's @kedge/docs, fetched before anything is installed, so its notes decide. */
+function fetchDocs(to: string, fromPacks: string | undefined): { dir: string; cleanup: () => void } {
+  const tmp = mkdtempSync(join(tmpdir(), "kedge-upgrade-"));
+  let tgz: string;
+  if (fromPacks) tgz = join(fromPacks, `kedge-docs-${to}.tgz`);
+  else {
+    const r = spawnSync("npm", ["pack", `@kedge/docs@${to}`, "--pack-destination", tmp], { encoding: "utf8" });
+    if (r.status !== 0)
+      throw new UpgradeRefused(`can't fetch @kedge/docs@${to}: ${r.stderr.trim().split("\n").at(-1)}`);
+    tgz = join(tmp, r.stdout.trim().split("\n").at(-1) as string);
+  }
+  if (!existsSync(tgz)) throw new UpgradeRefused(`no @kedge/docs ${to} at ${tgz}`);
+  const x = spawnSync("tar", ["-xzf", tgz, "-C", tmp]);
+  if (x.status !== 0) throw new UpgradeRefused(`can't unpack ${tgz}`);
+  return { dir: join(tmp, "package"), cleanup: () => rmSync(tmp, { recursive: true, force: true }) };
+}
+
+/**
+ * The workspace's Kedge overrides, made to name the requested source: each package's tarball in
+ * `fromPacks`, or none, for the registry. An override left from the last source wins at install, and
+ * the old release would stay installed under the new one's version (codex code r30). Other overrides stay.
+ */
+export function reconcileOverrides(text: string, to: string, fromPacks?: string): string {
+  const doc = parseDocument(text);
+  const found = doc.get("overrides");
+  const overrides = isMap(found) ? found : doc.createNode({});
+  for (const item of [...overrides.items]) {
+    const key = String((item.key as { value?: unknown })?.value ?? item.key);
+    if (key.startsWith("@kedge/")) overrides.delete(key);
+  }
+  if (fromPacks) {
+    const tgz = new RegExp(`^kedge-(.+)-${to.replace(/\./g, "\\.")}\\.tgz$`);
+    const packs = readdirSync(fromPacks)
+      .map((f) => [f, tgz.exec(f)?.[1]] as const)
+      .filter((x): x is readonly [string, string] => Boolean(x[1]))
+      .sort(([, a], [, b]) => byCodePoint(a, b));
+    if (!packs.length) throw new UpgradeRefused(`no Kedge ${to} packs in ${fromPacks}`);
+    for (const [file, name] of packs) overrides.set(`@kedge/${name}`, `file:${join(fromPacks, file)}`);
+  }
+  if (overrides.items.length) doc.set("overrides", overrides);
+  else doc.delete("overrides");
+  return doc.toString();
+}
+
+/** Installed Kedge packages that aren't the target's version, which no codemod may run against. */
+export function notAt(cwd: string, to: string): string[] {
+  return [...installedPackages(cwd)]
+    .map(([name, dir]) => [
+      name,
+      (JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as { version: string }).version,
+    ])
+    .filter(([, v]) => v !== to)
+    .map(([name, v]) => `${name} ${v}`);
+}
+
+export async function upgrade(input: UpgradeInput): Promise<void> {
+  const log = input.log ?? console.log;
+  const run = input.run ?? ((cmd, args, cwd) => spawnSync(cmd, args, { cwd, stdio: "inherit" }).status ?? 1);
+  if (input.git.dirty().length)
+    throw new UpgradeRefused("commit first: an upgrade's diff should be the upgrade's alone");
+  const cliDir = installedPackages(input.cwd).get("@kedge/cli");
+  if (!cliDir) throw new UpgradeRefused("@kedge/cli isn't installed here");
+  const current = (JSON.parse(readFileSync(join(cliDir, "package.json"), "utf8")) as { version: string }).version;
+  if (current === input.to) throw new UpgradeRefused(`already on ${current}`);
+  const docs = fetchDocs(input.to, input.fromPacks);
+  let notes: Map<string, UpgradeNote>;
+  try {
+    notes = readNotes(join(docs.dir, "upgrading"));
+  } finally {
+    docs.cleanup();
+  }
+  const stages = chain(notes, current, input.to);
+  if (!stages) throw new UpgradeRefused(`Kedge ${input.to}'s upgrade notes don't reach ${current}: no supported path`);
+  if (stages.length > 1)
+    throw new UpgradeRefused(
+      `${input.to} is ${stages.length} supported steps from ${current}; deploy each in turn:\n${stages.map((v) => `  kedge upgrade --to ${v}${input.fromPacks ? " --from-packs <dir>" : ""}, then kedge deploy`).join("\n")}`,
+    );
+
+  // Every @kedge package to the target, together.
+  const pkgFile = join(input.cwd, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgFile, "utf8")) as Record<string, Record<string, string>>;
+  for (const field of ["dependencies", "devDependencies"])
+    for (const dep of Object.keys(pkg[field] ?? {}))
+      if (dep.startsWith("@kedge/")) (pkg[field] as Record<string, string>)[dep] = input.to;
+  // A package the release adds, before the one install, so the codemod that uses it finds it (p0.9 §3.2).
+  for (const added of notes.get(input.to)?.adds ?? [])
+    if (!pkg.dependencies?.[added] && !pkg.devDependencies?.[added]) {
+      pkg.dependencies = { ...(pkg.dependencies ?? {}), [added]: input.to };
+      log(`added ${added} ${input.to}, which this release brings`);
+    }
+  writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+  const ws = join(input.cwd, "pnpm-workspace.yaml");
+  if (existsSync(ws) || input.fromPacks)
+    writeFileSync(ws, reconcileOverrides(existsSync(ws) ? readFileSync(ws, "utf8") : "", input.to, input.fromPacks));
+  // An upgrade changes the lockfile by definition; CI would otherwise freeze it.
+  if (run("pnpm", ["install", "--no-frozen-lockfile"], input.cwd) !== 0)
+    throw new UpgradeRefused("pnpm install failed; nothing else ran");
+  const stale = notAt(input.cwd, input.to);
+  if (stale.length) throw new UpgradeRefused(`the install left ${stale.join(", ")}, not ${input.to}; no codemod ran`);
+
+  // Each entry's codemod, from the newly installed @kedge/docs; what's left goes to UPGRADE-TODO.md.
+  const installedDocs = installedPackages(input.cwd).get("@kedge/docs");
+  const note = notes.get(input.to) as UpgradeNote;
+  const todo: string[] = [
+    `# Upgrading to Kedge ${input.to}`,
+    "",
+    `From ${current}. Written by kedge upgrade; work through it, then delete it.`,
+    "",
+  ];
+  for (const e of note.entries) {
+    const left: string[] = [];
+    if (e.codemod) {
+      const file = installedDocs ? join(installedDocs, "upgrading", "codemods", `${e.codemod}.mjs`) : "";
+      if (!file || !existsSync(file)) left.push(`the codemod ${e.codemod} is missing from @kedge/docs`);
+      else {
+        const mod = (await import(pathToFileURL(file).href)) as {
+          default: (
+            dir: string,
+          ) => { changed: string[]; todo: string[] } | Promise<{ changed: string[]; todo: string[] }>;
+        };
+        const r = await mod.default(input.cwd);
+        for (const c of r.changed) log(`codemod ${e.codemod}: changed ${c}`);
+        left.push(...r.todo);
+      }
+    }
+    // Manual steps stand beside a codemod, not instead of one: what it can't do is why they're there (codex code r10).
+    if (e.manual) left.push(e.manual);
+    if (left.length)
+      todo.push(
+        `## ${e.id}`,
+        "",
+        ...(e.affects?.length ? [`Affects: ${e.affects.join(", ")}`, ""] : []),
+        ...left.map((l) => `- ${l}`),
+        ...(e.verify ? ["", `Verify: \`${e.verify}\``] : []),
+        "",
+      );
+  }
+  const drift = unitDrift(input.cwd, input.manifest(input.cwd), null, { ignoreWiring: true });
+  if (drift.status === "fail") todo.push("## Ejected units", "", "```diff", ...(drift.details ?? []), "```", "");
+  writeFileSync(join(input.cwd, "UPGRADE-TODO.md"), `${todo.join("\n").trimEnd()}\n`);
+  log("wrote UPGRADE-TODO.md");
+
+  // Then generate and check, stopping at the first failure with its output.
+  if ((await input.kedge(["generate"])) !== 0)
+    throw new UpgradeRefused("kedge generate failed after the upgrade; UPGRADE-TODO.md says what's left");
+  if ((await input.kedge(["check"])) !== 0)
+    throw new UpgradeRefused("kedge check failed after the upgrade; UPGRADE-TODO.md says what's left");
+  log(`upgraded to Kedge ${input.to}; nothing is committed`);
+}

package/src/worker-config.ts

@@ -0,0 +1,81 @@
+// The store's Worker config (docs/proposals/p0.6b-webhooks-calendar-preview.md
+// §2.8): every Worker that sends webhooks needs `global_fetch_strictly_public`,
+// or a `fetch` to a host in its own zone goes straight to that zone's origin,
+// around Cloudflare's security settings for it
+// (https://developers.cloudflare.com/workers/configuration/compatibility-flags/#global-fetch-strictly-public).
+//
+// `kedge generate` reads the config as wrangler does, to a value, and checks
+// that value; it never edits the file. Editing JSONC text without a full
+// parser failed three codex rounds (a trailing comma, a commented-out list,
+// a string holding a bracket), so the merchant adds the flag, told exactly
+// where. An `env.<name>` that sets its own list overrides the top-level one
+// ("Inheritable keys … can be inherited (or overridden) by
+// environment-specific configuration",
+// https://developers.cloudflare.com/workers/wrangler/configuration/#inheritable-keys),
+// so each such list needs the flag too.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const STRICTLY_PUBLIC = "global_fetch_strictly_public";
+const FILES = ["wrangler.jsonc", "wrangler.json"];
+
+/**
+ * JSONC as JSON: comments and trailing commas dropped, every string kept
+ * byte for byte. One pass that knows when it is inside a string, so nothing
+ * a string holds is read as a comment, a comma or structure.
+ */
+export function jsoncToJson(text: string): string {
+  let out = "";
+  let i = 0;
+  const skip = (from: number): number => {
+    let j = from;
+    for (;;) {
+      if (/\s/.test(text[j] ?? "")) j++;
+      else if (text.startsWith("//", j)) j = text.includes("\n", j) ? text.indexOf("\n", j) + 1 : text.length;
+      else if (text.startsWith("/*", j)) j = text.includes("*/", j + 2) ? text.indexOf("*/", j + 2) + 2 : text.length;
+      else return j;
+    }
+  };
+  while (i < text.length) {
+    const ch = text[i] as string;
+    if (ch === '"') {
+      let j = i + 1;
+      while (j < text.length && text[j] !== '"') j += text[j] === "\\" ? 2 : 1;
+      out += text.slice(i, j + 1);
+      i = j + 1;
+    } else if (text.startsWith("//", i) || text.startsWith("/*", i)) {
+      i = skip(i);
+      out += " ";
+    } else if (ch === ",") {
+      const next = skip(i + 1);
+      if (text[next] !== "]" && text[next] !== "}") out += ",";
+      i++;
+    } else {
+      out += ch;
+      i++;
+    }
+  }
+  return out;
+}
+
+type Flags = unknown;
+const hasFlag = (flags: Flags) => Array.isArray(flags) && flags.includes(STRICTLY_PUBLIC);
+
+/** The Worker config's refusal, or null when every list it deploys with holds the flag. */
+export function strictlyPublic(cwd: string): { file: string | null; problem: string | null } {
+  const file = FILES.map((f) => join(cwd, f)).find((f) => existsSync(f));
+  if (!file) return { file: null, problem: null };
+  let config: { compatibility_flags?: Flags; env?: Record<string, { compatibility_flags?: Flags }> };
+  try {
+    config = JSON.parse(jsoncToJson(readFileSync(file, "utf8")));
+  } catch (e) {
+    return { file, problem: `${file} doesn't parse as JSONC: ${(e as Error).message}` };
+  }
+  const add = `add "${STRICTLY_PUBLIC}" to`;
+  if (!hasFlag(config.compatibility_flags))
+    return { file, problem: `${file}: ${add} the top-level "compatibility_flags" (webhooks need it, p0.6b §2.8)` };
+  for (const [name, env] of Object.entries(config.env ?? {}))
+    if (env && typeof env === "object" && "compatibility_flags" in env && !hasFlag(env.compatibility_flags))
+      return { file, problem: `${file}: env.${name} sets its own "compatibility_flags"; ${add} it (p0.6b §2.8)` };
+  return { file, problem: null };
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.