@kedge/cli 0.0.0-stage → 0.9.0

package/src/fork.ts

@@ -0,0 +1,67 @@
+// `kedge doctor --core-diff` (docs/proposals/p0.8-cli-agent-kit.md §8.3): how far
+// a fork's packages have drifted from a release, per package and file, the
+// way Magento's core:code:changes turns "how far have we drifted" into a number
+// before an upgrade (research/14 §1). It reports; only --strict fails on it.
+// Each package.json is left out: a fork's names its siblings by workspace:*,
+// a release's by version, and that difference isn't drift. Each package's
+// LICENSE is the root one, copied in only while packing, so it's compared
+// with the fork's root LICENSE.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileHash, type Manifest } from "./manifest";
+
+export interface PackageDiff {
+  package: string;
+  changed: string[];
+  added: string[];
+  removed: string[];
+}
+
+export function coreDiff(repo: string, manifest: Manifest): PackageDiff[] {
+  const out: PackageDiff[] = [];
+  for (const [name, files] of Object.entries(manifest.packages)) {
+    const dir = join(repo, "packages", name.replace(/^@kedge\//, ""));
+    const d: PackageDiff = { package: name, changed: [], added: [], removed: [] };
+    const tops = new Set(
+      Object.keys(files)
+        .map((f) => f.split("/")[0] as string)
+        .filter((t) => !t.endsWith(".json")),
+    );
+    for (const [f, want] of Object.entries(files)) {
+      if (f === "package.json") continue;
+      const p = f === "LICENSE" ? join(repo, "LICENSE") : join(dir, f);
+      if (!existsSync(p)) d.removed.push(f);
+      else if (fileHash(f, readFileSync(p)) !== want) d.changed.push(f);
+    }
+    const walk = (d0: string) => {
+      if (!existsSync(d0)) return;
+      for (const e of readdirSync(d0, { withFileTypes: true })) {
+        const p = join(d0, e.name);
+        if (e.isDirectory()) walk(p);
+        else {
+          const rel = relative(dir, p);
+          if (files[rel] === undefined && !(rel.startsWith("migrations/") && !rel.endsWith(".sql"))) d.added.push(rel);
+        }
+      }
+    };
+    for (const t of tops) walk(join(dir, t));
+    if (d.changed.length || d.added.length || d.removed.length) out.push(d);
+  }
+  return out;
+}
+
+export function formatCoreDiff(diffs: readonly PackageDiff[], version: string): string {
+  if (!diffs.length) return `the packages match Kedge ${version}`;
+  const lines = [`drift from Kedge ${version}:`];
+  for (const d of diffs) {
+    lines.push(`  ${d.package}: ${d.changed.length} changed, ${d.added.length} added, ${d.removed.length} removed`);
+    for (const f of d.changed) lines.push(`    ~ ${f}`);
+    for (const f of d.added) lines.push(`    + ${f}`);
+    for (const f of d.removed) lines.push(`    - ${f}`);
+  }
+  const files = diffs.reduce((n, d) => n + d.changed.length + d.added.length + d.removed.length, 0);
+  lines.push(
+    `  ${files} file${files === 1 ? "" : "s"} across ${diffs.length} package${diffs.length === 1 ? "" : "s"}: each is a merge at the next upgrade`,
+  );
+  return lines.join("\n");
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export {
+  CORE_TABLES,
+  errorSources,
+  type LintIssue,
+  lintSql,
+  type Owner,
+  PERMANENT_IDENTITIES,
+  statementTexts,
+  tokenize,
+} from "@kedge/core";
+export { ComposeError, type ComposeInput, type ComposeResult, compose, type Lock, type LockEntry } from "./compose";
+export { lintPlugin } from "./plugin-lint";

package/src/invariants.ts

@@ -0,0 +1,168 @@
+// INVARIANTS.md and invariants.json (docs/proposals/p0.8-cli-agent-kit.md §4.2):
+// core's catalog checked against the composed schema, then each plugin's own
+// constraints and RAISE codes with the codes they map to. `kedge generate`
+// writes both; doctor's `invariants` check reports the catalog's problems.
+import type { ErrorMapEntry } from "@kedge/core";
+import {
+  CATALOG_EXEMPT,
+  type CatalogEntry,
+  CORE_RAISE_CODES,
+  catalogPattern,
+  ENTITY_RAISE_CODES,
+  INVARIANT_CATALOG,
+} from "@kedge/db";
+import { byCodePoint } from "./order";
+import { raiseCodes, type Schema, type SchemaObject } from "./schema";
+
+/** The merchant's own, from `local/`: theirs to name and keep, never core's catalog's (codex code r19). */
+export const isLocal = (o: SchemaObject) => o.name.startsWith("local_") || o.table.startsWith("local_");
+
+/** Objects the catalog speaks for: core's triggers and named constraints. Plugins' are listed per plugin. */
+const claimable = (o: SchemaObject) =>
+  (o.type === "trigger" || o.type === "constraint") && !o.name.startsWith("plg_") && !isLocal(o);
+
+/** Every code core's own SQL raises, and what each becomes. */
+export const CORE_CODES: Readonly<Record<string, string>> = { ...CORE_RAISE_CODES, ...ENTITY_RAISE_CODES };
+
+export interface CatalogProblem {
+  message: string;
+}
+
+export function catalogProblems(
+  schema: Schema,
+  checks: ReadonlySet<string>,
+  catalog: readonly CatalogEntry[] = INVARIANT_CATALOG,
+  exempt: readonly { objects: readonly string[]; reason: string }[] = CATALOG_EXEMPT,
+): CatalogProblem[] {
+  const problems: CatalogProblem[] = [];
+  const objects = schema.objects.filter(claimable);
+  const claimed = new Set<string>();
+  const claim = (where: string, pattern: string) => {
+    const re = catalogPattern(pattern);
+    const hits = objects.filter((o) => re.test(o.name));
+    if (hits.length === 0 && !generated.has(pattern))
+      problems.push({ message: `${where} names "${pattern}", which matches no core trigger or constraint` });
+    for (const h of hits) claimed.add(h.name);
+  };
+  const ids = new Set<string>();
+  const generated = new Set(catalog.filter((e) => e.generated).flatMap((e) => e.objects));
+  for (const e of catalog) {
+    if (ids.has(e.id)) problems.push({ message: `${e.id} is listed twice` });
+    ids.add(e.id);
+    for (const p of e.objects) claim(e.id, p);
+    if (e.check && !checks.has(e.check))
+      problems.push({ message: `${e.id}'s check "${e.check}" isn't in @kedge/testing's INVARIANTS` });
+  }
+  for (const x of exempt) for (const p of x.objects) claim("an exemption", p);
+  const unclaimed = [...new Set(objects.filter((o) => !claimed.has(o.name)).map((o) => o.name))];
+  if (unclaimed.length)
+    problems.push({
+      message: `core objects no catalog entry claims: ${unclaimed.join(", ")} (add them to packages/db/src/invariant-catalog.ts)`,
+    });
+  return problems;
+}
+
+export interface RenderedEntry {
+  id: string;
+  title: string;
+  rule: string;
+  check: string | null;
+  objects: string[];
+  raises: { code: string; error: string }[];
+}
+
+export interface PluginInvariants {
+  plugin: string;
+  constraints: { name: string; table: string; error: string | null }[];
+  raises: { code: string; object: string; error: string | null }[];
+}
+
+export interface Invariants {
+  version: 1;
+  core: RenderedEntry[];
+  plugins: PluginInvariants[];
+}
+
+const coreError = (code: string) => {
+  const e = CORE_CODES[code];
+  return e === undefined ? "UNMAPPED" : e === "defect" ? "INTERNAL (a core defect)" : e;
+};
+
+/**
+ * The plugin a `kedge_<plugin>_*` object belongs to: core generates them around a plugin's own SQL (its
+ * acquire statements, its entities' triggers), so their codes are the plugin's or core's. Longest name
+ * first, so `kedge_gift_card_*` is gift_card's beside a plugin named gift. Doctor and the catalog share
+ * it: a code doctor accepts as mapped is the one INVARIANTS.md shows (codex code r31).
+ */
+export function generatedFor<P extends { name: string }>(name: string, plugins: readonly P[]): P | undefined {
+  return [...plugins].sort((a, b) => b.name.length - a.name.length).find((p) => name.startsWith(`kedge_${p.name}_`));
+}
+
+/** The catalog and every plugin's constraints, as invariants.json holds them. */
+export function invariantsOf(
+  schema: Schema,
+  plugins: readonly { name: string; errors: Readonly<Record<string, ErrorMapEntry>> }[],
+): Invariants {
+  const objects = schema.objects.filter(claimable);
+  const core = INVARIANT_CATALOG.map((e) => {
+    const res = e.objects.map(catalogPattern);
+    const hits = objects.filter((o) => res.some((r) => r.test(o.name)));
+    const raises = new Map<string, { code: string; error: string }>();
+    for (const o of hits) {
+      const owner = generatedFor(o.name, plugins);
+      for (const code of raiseCodes(o.sql)) {
+        const error = owner?.errors[code]?.code ?? coreError(code);
+        raises.set(`${code} ${error}`, { code, error });
+      }
+    }
+    return {
+      id: e.id,
+      title: e.title,
+      rule: e.rule,
+      check: e.check ?? null,
+      objects: [...new Set(hits.map((o) => o.name))],
+      raises: [...raises.values()].sort((a, b) => byCodePoint(a.code, b.code) || byCodePoint(a.error, b.error)),
+    };
+  });
+  const out: PluginInvariants[] = [];
+  for (const p of plugins) {
+    const prefix = `plg_${p.name}_`;
+    const mapped = (key: string) => p.errors[key]?.code ?? null;
+    const constraints = schema.objects
+      .filter((o) => o.type === "constraint" && o.table.startsWith(prefix))
+      .map((o) => ({ name: o.name, table: o.table, error: mapped(o.name) }));
+    const raises = schema.objects
+      .filter((o) => (o.type === "trigger" || o.type === "view") && o.name.startsWith(prefix))
+      .flatMap((o) => raiseCodes(o.sql).map((code) => ({ code, object: o.name, error: mapped(code) })));
+    if (constraints.length || raises.length) out.push({ plugin: p.name, constraints, raises });
+  }
+  return { version: 1, core, plugins: out };
+}
+
+export function invariantsMarkdown(inv: Invariants): string {
+  const lines = [
+    "# Invariants",
+    "",
+    "Generated by `kedge generate` from the composed migrations; never edit it. Each",
+    "rule is enforced by D1 itself, in the batch, so code that breaks it is refused",
+    "with the error shown. Follow the rule and you never meet the error.",
+    "",
+  ];
+  for (const e of inv.core) {
+    lines.push(`## ${e.id}: ${e.title}`, "", e.rule, "");
+    if (e.raises.length) lines.push(`- **Errors:** ${e.raises.map((r) => `\`${r.code}\` → ${r.error}`).join("; ")}`);
+    if (e.check) lines.push(`- **Checked after every test** by \`describeKedgeInvariants\` (\`${e.check}\`)`);
+    lines.push(`- **Enforced by:** ${e.objects.length} objects (\`invariants.json\` lists them)`, "");
+  }
+  if (inv.plugins.length) {
+    lines.push("## Plugins", "");
+    for (const p of inv.plugins) {
+      lines.push(`### ${p.plugin}`, "");
+      for (const c of p.constraints)
+        lines.push(`- constraint \`${c.name}\` on \`${c.table}\` → ${c.error ?? "UNMAPPED"}`);
+      for (const r of p.raises) lines.push(`- \`RAISE '${r.code}'\` in \`${r.object}\` → ${r.error ?? "UNMAPPED"}`);
+      lines.push("");
+    }
+  }
+  return `${lines.join("\n").trimEnd()}\n`;
+}

package/src/main.ts

@@ -0,0 +1,378 @@
+// The `kedge` command. P0.2 ships `generate`, P0.5 the deployment's bootstrap
+// commands (`staff invite-owner`, `staff recover`, `keys create`); doctor,
+// check, preview and deploy arrive with P0.8 (docs/11).
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { KedgeConfig } from "@kedge/core";
+import { type CliBatch, ownerInviteSql, publishableKeySql, recoverSql } from "@kedge/db";
+import { type Cloudflare, restCloudflare } from "./cf";
+import { check as runCheck } from "./check";
+import {
+  type CommandDeps,
+  deployCommand,
+  devCommand,
+  ejectCommand,
+  flag,
+  generateSupersede,
+  keysOverHttp,
+  migrateCommand,
+  previewCommand,
+  restoreCommand,
+  secretCommand,
+  seedCommand,
+  upgradeCommand,
+} from "./commands";
+import { ComposeError, compose, type Lock } from "./compose";
+import { doctor, doctorRemote, formatReport } from "./doctor";
+import { invariantsMarkdown, invariantsOf } from "./invariants";
+import { installedPackages } from "./manifest";
+import { composedTexts, schemaOf } from "./schema";
+import { storeNames } from "./store";
+import { compileStoreZone } from "./tz";
+import { strictlyPublic } from "./worker-config";
+
+const USAGE = `usage: kedge generate [--check] [--supersede <op-id>]
+       kedge check [--fast]
+       kedge doctor [--json]
+       kedge dev
+       kedge migrate [--remote]
+       kedge deploy [--maintenance-window <from>/<to>] [--var K=V]... [--adopt <name>]...
+                    [--resume | --take-over <op-id> --confirm-stopped | --abort-cutover | --supersede <op-id>]
+                    [--resolve-intent <id> --not-executed] [--record-active --reason <what>]
+                    [--adopt-existing --from-release <version>] [--allow-older]
+       kedge preview [--name N] [--var K=V]... [--fresh] [--secret-env NAME]...
+       kedge preview build [--name N] | kedge preview apply <plan.tar|-> [--store S] [--name N]
+       kedge preview destroy [--name N] [--sweep]
+       kedge eject <unit> --reason "<why>" | kedge eject --rebase <unit>
+       kedge upgrade --to <version> [--from-packs <dir>]
+       kedge doctor --core-diff [--upstream <manifest>] [--strict]
+       kedge secret put <NAME> | kedge secret delete <NAME>
+       kedge restore --list
+       kedge seed --sample apparel --url <url> (--key <sk_…> | --session <token>) [--live]
+       kedge keys create (--publishable [--origin <url>]... | --secret --grant <permission>...)
+                         --url <url> (--session <token> | --sign-in <email>) [--name <name>]
+       kedge staff invite-owner <email> [--database DB] [--remote] [--url <url>] [--config wrangler.jsonc]
+       kedge staff recover <email> [--database DB] [--remote] [--config wrangler.jsonc]
+       kedge keys create --publishable --name <name> [--origin <origin>]... [--pepper-version N]
+                         [--database DB] [--remote] [--config wrangler.jsonc]
+
+  generate            compose core, plugin and local migrations into migrations/
+                      and update kedge.lock.json
+  generate --check    fail if generate would write anything (for CI)
+  dev                 fresh local secrets once, local migrations, then wrangler dev
+  migrate             local migrations; --remote applies N−1 files to production, refusing a cutover
+  deploy              migrations before the Worker, under an operation in <store>-ops (§6)
+  preview             a separate Worker with its own D1, queue and Durable Objects, capture
+                      sinks for every effect, seeded, then test/scenarios/*.http.ts against it
+  eject               copy one unit of core into src/overrides, its upstream hash recorded
+  upgrade             every @kedge package to a release one supported step on, its codemods,
+                      UPGRADE-TODO.md, then generate and check; nothing is committed
+  restore --list      the restore points; restoring waits for P1.18
+  check               typecheck, generate --check, doctor, then the store's tests;
+                      --fast stops before the tests (the Stop hook's)
+  doctor              the store's offline checks: lock, installed core, error map,
+                      invariant catalog, code lint, wrangler.jsonc
+  staff invite-owner  the first Owner's one-time invite (only while no active Owner exists)
+  staff recover       reset a sole Owner's factors and print a reenrol invite
+  keys create         a storefront and its first publishable key; reads the pepper from
+                      KEDGE_KEY_PEPPER_V<N> in the environment (N defaults to 1)
+
+  The staff and keys commands run one audited batch through wrangler d1 execute
+  (--local unless --remote) and print the secret once.`;
+
+/** Runs one CLI batch against the store's D1; tests replace it. */
+export type Executor = (
+  b: CliBatch,
+  opts: { database: string; remote: boolean; cwd: string; config?: string },
+) => number;
+
+const wranglerExecute: Executor = (b, opts) => {
+  const dir = mkdtempSync(join(tmpdir(), "kedge-"));
+  const file = join(dir, "batch.sql");
+  try {
+    writeFileSync(file, b.sql, { mode: 0o600 });
+    const r = spawnSync(
+      "npx",
+      [
+        "wrangler",
+        "d1",
+        "execute",
+        opts.database,
+        "--file",
+        file,
+        opts.remote ? "--remote" : "--local",
+        "--yes",
+        ...(opts.config ? ["-c", opts.config] : []),
+      ],
+      { cwd: opts.cwd, stdio: "inherit" },
+    );
+    return r.status ?? 1;
+  } finally {
+    // The file holds no secret (only digests), but it needn't outlive the run.
+    rmSync(dir, { recursive: true, force: true });
+  }
+};
+
+/**
+ * The store's origin for the invite link (p0.9 §3.5): `--url`, or with
+ * `--remote` the Worker's workers.dev URL. Null when neither is known, and then
+ * only the token prints, as before: the link is a convenience.
+ */
+async function inviteOrigin(
+  args: readonly string[],
+  remote: boolean,
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  cf?: Cloudflare,
+): Promise<string | null> {
+  const url = flag(args, "--url");
+  if (url) return new URL(url).origin;
+  if (!remote) return null;
+  try {
+    const worker = storeNames(cwd).names.worker;
+    return `https://${worker}.${await (cf ?? restCloudflare(env)).workersSubdomain()}.workers.dev`;
+  } catch {
+    return null;
+  }
+}
+
+async function bootstrap(
+  command: string,
+  args: string[],
+  cwd: string,
+  execute: Executor,
+  env: NodeJS.ProcessEnv,
+  cf?: Cloudflare,
+): Promise<number> {
+  const config = flag(args, "--config");
+  const opts = {
+    database: flag(args, "--database") ?? "DB",
+    remote: args.includes("--remote"),
+    cwd,
+    ...(config ? { config } : {}),
+  };
+  const now = Date.now();
+  const [sub, target] = args;
+  if (command === "staff" && (sub === "invite-owner" || sub === "recover") && target && !target.startsWith("--")) {
+    const b = sub === "invite-owner" ? await ownerInviteSql(target, now) : await recoverSql(target, now);
+    const status = execute(b, opts);
+    if (status !== 0) return status;
+    console.log(`invite ${b.inviteId} for ${target}, valid until ${new Date(b.expiresAt).toISOString()}`);
+    console.log(`accept with POST /auth/admin/invites/accept and this token (shown once):\n${b.token}`);
+    const origin = await inviteOrigin(args, opts.remote, cwd, env, cf);
+    // The token rides in the fragment, which no server log or Referer carries (p0.9 §3.5).
+    if (origin) console.log(`or open the admin's invite page:\n${origin}/app/invite#${b.token}`);
+    return 0;
+  }
+  if (command === "keys" && sub === "create" && args.includes("--publishable")) {
+    const name = flag(args, "--name");
+    if (!name) {
+      console.error("keys create needs --name");
+      return 2;
+    }
+    const origins = args.flatMap((a, i) => (a === "--origin" && args[i + 1] ? [args[i + 1] as string] : []));
+    const pepperVersion = Number(flag(args, "--pepper-version") ?? "1");
+    const pepper = env[`KEDGE_KEY_PEPPER_V${pepperVersion}`];
+    if (!Number.isSafeInteger(pepperVersion) || pepperVersion < 1 || !pepper) {
+      console.error(`set KEDGE_KEY_PEPPER_V${pepperVersion} to the Worker's pepper secret first`);
+      return 2;
+    }
+    const b = await publishableKeySql({ name, origins, pepperVersion, pepper }, now);
+    const status = execute(b, opts);
+    if (status !== 0) return status;
+    console.log(`storefront ${b.storefrontId}, key ${b.keyId}`);
+    console.log(`publishable key (send as x-kedge-key; shown once):\n${b.key}`);
+    return 0;
+  }
+  console.error(USAGE);
+  return 2;
+}
+
+const INDEX_START = "<!-- kedge:docs-index:start -->";
+const INDEX_END = "<!-- kedge:docs-index:end -->";
+
+/**
+ * AGENTS.md's docs index (§9.3): a compressed list of the installed
+ * @kedge/docs, always in context, between markers so the rest of the file is
+ * the store's. Null when there's no AGENTS.md with the markers or no docs.
+ */
+function agentsIndex(cwd: string): { path: string; text: string } | null {
+  const path = join(cwd, "AGENTS.md");
+  const docs = installedPackages(cwd).get("@kedge/docs");
+  if (!existsSync(path) || !docs) return null;
+  const current = readFileSync(path, "utf8");
+  const a = current.indexOf(INDEX_START);
+  const b = current.indexOf(INDEX_END);
+  if (a < 0 || b < a) return null;
+  const version = (JSON.parse(readFileSync(join(docs, "package.json"), "utf8")) as { version: string }).version;
+  const index = JSON.parse(readFileSync(join(docs, "index.json"), "utf8")) as {
+    entries: { path: string; title: string; summary: string }[];
+  };
+  const lines = [
+    `Kedge ${version}. Read the guide before writing that kind of code; they match what's installed.`,
+    ...index.entries.map((e) => `- [${e.title}](node_modules/@kedge/docs/${e.path}): ${e.summary}`),
+  ];
+  return { path, text: `${current.slice(0, a + INDEX_START.length)}\n${lines.join("\n")}\n${current.slice(b)}` };
+}
+
+/** Skills ship in @kedge/docs and are copied, gitignored, so they always match what's installed (§9.3). */
+function copySkills(cwd: string): string[] {
+  const docs = installedPackages(cwd).get("@kedge/docs");
+  if (!docs || !existsSync(join(docs, "skills")) || !existsSync(join(cwd, ".claude"))) return [];
+  const out: string[] = [];
+  for (const s of readdirSync(join(docs, "skills"))) {
+    cpSync(join(docs, "skills", s), join(cwd, ".claude", "skills", s), { recursive: true });
+    out.push(s);
+  }
+  return out;
+}
+
+/** What generate writes beside the migrations: INVARIANTS.md, invariants.json and AGENTS.md's index. */
+function generatedFiles(cwd: string, lock: Lock, config: KedgeConfig): { path: string; text: string }[] {
+  const schema = schemaOf(composedTexts(cwd, lock));
+  const inv = invariantsOf(
+    schema,
+    (config.plugins ?? []).map((p) => ({ name: p.definition.name, errors: p.definition.errors ?? {} })),
+  );
+  const index = agentsIndex(cwd);
+  return [
+    { path: join(cwd, "INVARIANTS.md"), text: invariantsMarkdown(inv) },
+    { path: join(cwd, "invariants.json"), text: `${JSON.stringify(inv, null, 2)}\n` },
+    ...(index ? [index] : []),
+  ];
+}
+
+/** @kedge/db's migrations, resolved from this package so the CLI and the runtime agree on core's version. */
+function coreMigrationsDir(): string {
+  const entry = fileURLToPath(import.meta.resolve("@kedge/db"));
+  return join(dirname(entry), "..", "migrations");
+}
+
+export async function main(
+  argv: string[],
+  cwd: string,
+  deps: { execute?: Executor; env?: NodeJS.ProcessEnv; cf?: Cloudflare } = {},
+): Promise<number> {
+  const [command, ...flags] = argv;
+  if (command === "keys" && flag(flags, "--url")) {
+    const d0: CommandDeps = { cwd, env: deps.env ?? process.env, coreDir: coreMigrationsDir() };
+    return keysOverHttp(flags, d0);
+  }
+  if (command === "staff" || command === "keys")
+    return bootstrap(command, flags, cwd, deps.execute ?? wranglerExecute, deps.env ?? process.env, deps.cf);
+  const d: CommandDeps = {
+    cwd,
+    env: deps.env ?? process.env,
+    coreDir: coreMigrationsDir(),
+    checkFast: () => main(["check", "--fast"], cwd),
+  };
+  if (command === "deploy") return deployCommand(flags, d);
+  if (command === "migrate") return migrateCommand(flags, d);
+  if (command === "restore") return restoreCommand(flags, d);
+  if (command === "secret") return secretCommand(flags, d);
+  if (command === "seed") return seedCommand(flags, d);
+  if (command === "preview") return previewCommand(flags, d);
+  if (command === "eject") return ejectCommand(flags, d);
+  if (command === "upgrade")
+    return upgradeCommand(flags, {
+      ...d,
+      // The store's own CLI after the install: this process is still the release being replaced.
+      kedge: async (argv) =>
+        spawnSync(join(cwd, "node_modules", ".bin", "kedge"), argv, { cwd, stdio: "inherit" }).status ?? 1,
+    });
+  if (command === "dev") return devCommand(d);
+  if (command === "generate" && flag(flags, "--supersede"))
+    return generateSupersede(flag(flags, "--supersede") as string, d);
+  if (command === "doctor" && flags.includes("--core-diff")) {
+    const { coreDiff, formatCoreDiff } = await import("./fork");
+    const { ownManifest } = await import("./manifest");
+    const upstream = flag(flags, "--upstream");
+    const manifest = upstream ? JSON.parse(readFileSync(upstream, "utf8")) : ownManifest();
+    if (!manifest) {
+      console.error("--core-diff needs a release's manifest: --upstream <dist-packs/<version>/kedge-manifest.json>");
+      return 2;
+    }
+    const diffs = coreDiff(cwd, manifest);
+    console.log(formatCoreDiff(diffs, manifest.version));
+    return flags.includes("--strict") && diffs.length ? 1 : 0;
+  }
+  if (command === "doctor") {
+    const results = await doctor({ cwd, coreDir: coreMigrationsDir() });
+    if (flags.includes("--remote")) {
+      const cf = restCloudflare(d.env);
+      const lock = JSON.parse(readFileSync(join(cwd, "kedge.lock.json"), "utf8")) as Lock;
+      results.push(...(await doctorRemote({ cwd, cf, lock, logpushJobs: () => cf.logpushJobs() })));
+    }
+    console.log(flags.includes("--json") ? JSON.stringify({ checks: results }, null, 2) : formatReport(results));
+    return results.some((r) => r.status === "fail") ? 1 : 0;
+  }
+  if (command === "check")
+    return runCheck({
+      cwd,
+      fast: flags.includes("--fast"),
+      generate: (c: string) => main(["generate", "--check"], c),
+      doctor: (c: string) => main(["doctor"], c),
+    });
+  if (command !== "generate") {
+    console.error(USAGE);
+    return 2;
+  }
+  const check = flags.includes("--check");
+  const configPath = resolve(cwd, "kedge.config.ts");
+  const config = ((await import(pathToFileURL(configPath).href)) as { default: KedgeConfig }).default;
+  try {
+    const result = compose({
+      coreDir: coreMigrationsDir(),
+      plugins: config.plugins ?? [],
+      // A preview's own ports are locked like any other's (p0.8 §5.2).
+      ports: [...(config.ports ?? []), ...(config.preview?.ports ?? [])],
+      localDir: join(cwd, "local"),
+      outDir: join(cwd, "migrations"),
+      lockPath: join(cwd, "kedge.lock.json"),
+      now: Date.now(),
+      dryRun: check,
+      ...(config.timezone ? { timezone: config.timezone } : {}),
+      compileZone: compileStoreZone,
+      tzPath: join(cwd, "src", "kedge.tz.ts"),
+    });
+    for (const n of result.notes) console.log(`note: ${n}`);
+    // P0.6b (§2.8): the Worker's fetch takes the public route, webhooks included.
+    const flag = strictlyPublic(cwd);
+    if (flag.problem) {
+      console.error(flag.problem);
+      return 1;
+    }
+    if (check && (result.written.length > 0 || result.lockChanged)) {
+      const files = [...result.written, ...(result.lockChanged ? ["kedge.lock.json"] : [])];
+      console.error(`kedge generate would write:\n  ${files.join("\n  ")}\nRun kedge generate and commit the result.`);
+      return 1;
+    }
+    for (const f of result.written) console.log(f.endsWith(".ts") ? `wrote ${f}` : `wrote migrations/${f}`);
+    if (result.written.length === 0) console.log("migrations are up to date");
+    if (result.lockChanged && !check) console.log("wrote kedge.lock.json");
+    // The invariant catalog, from what's now composed (§4.2).
+    const generated = generatedFiles(cwd, result.lock, config);
+    const stale = generated.filter((g) => !existsSync(g.path) || readFileSync(g.path, "utf8") !== g.text);
+    if (check && stale.length) {
+      console.error(
+        `kedge generate would write:\n  ${stale.map((g) => relative(cwd, g.path)).join("\n  ")}\nRun kedge generate and commit the result.`,
+      );
+      return 1;
+    }
+    for (const g of stale) {
+      writeFileSync(g.path, g.text);
+      console.log(`wrote ${relative(cwd, g.path)}`);
+    }
+    if (!check) copySkills(cwd);
+    return 0;
+  } catch (e) {
+    if (e instanceof ComposeError) {
+      console.error(e.message);
+      return 1;
+    }
+    throw e;
+  }
+}