@kedge/cli 0.0.0-stage → 0.10.0

package/src/main.ts

@@ -0,0 +1,470 @@
+// 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, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { KedgeConfig } from "@kedge/core";
+import { ownerInviteSql, publishableKeySql, recoverSql } from "@kedge/db";
+import {
+  type Cloudflare,
+  cloudflareBase,
+  cloudflareFor,
+  NeedsPerson,
+  resolveCloudflare,
+  restCloudflare,
+  sameAccount,
+  wranglerBin,
+} from "./cf";
+import { check as runCheck } from "./check";
+import {
+  type CommandDeps,
+  deployCommand,
+  devCommand,
+  ejectCommand,
+  failureOf,
+  flag,
+  generateSupersede,
+  keysOverHttp,
+  migrateCommand,
+  previewCommand,
+  restoreCommand,
+  secretCommand,
+  seedCommand,
+  smokeCommand,
+  upgradeCommand,
+} from "./commands";
+import { ComposeError, compose, type Lock } from "./compose";
+import { type Executor, wranglerExecute } from "./d1-batch";
+import { credentialsChecks, doctor, doctorRemote, formatReport } from "./doctor";
+import { invariantsMarkdown, invariantsOf } from "./invariants";
+import { installedPackages } from "./manifest";
+import { emit, withJsonOutput } from "./output";
+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 smoke --url <url> [--run <name>] [--live]
+       kedge keys create (--publishable [--origin <url>]... | --secret --grant <permission>...)
+                         --url <url> (--session <token> | --sign-in <email> [--answers-stdin] | --save) [--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
+  smoke               a test order on one of this store's own URLs: a cart, completion and
+                      placement, resumed by its --run name until it has its number
+  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.
+
+  deploy, preview, seed, staff and keys take --json: one object on stdout when they
+  end ({"ok": true, ...}, or {"ok": false, "error"} / {"ok": false, "handoff"}),
+  everything else on stderr. Exit 3 means a person must act: the last line of stderr
+  starts "for you:". --sign-in asks only a terminal; --answers-stdin reads one line
+  per question from a pipe, waiting 30 seconds for each.`;
+
+/**
+ * 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 ?? (await cloudflareFor(env, cwd))).workersSubdomain()}.workers.dev`;
+  } catch {
+    return null;
+  }
+}
+
+async function bootstrap(
+  command: string,
+  args: string[],
+  cwd: string,
+  execute: Executor,
+  env: NodeJS.ProcessEnv,
+  o: { json: boolean; emit?: (result: Record<string, unknown>) => void; cf?: Cloudflare },
+): Promise<number> {
+  const cf = o.cf;
+  const result = (r: Record<string, unknown>) => {
+    if (o.json) (o.emit ?? emit)(r);
+  };
+  // A usage error is an end too: under --json it's an object, never an empty stdout (codex code r8).
+  const usage = (message: string) => {
+    console.error(message);
+    result({ ok: false, error: message.split("\n")[0] });
+    return 2;
+  };
+  // Wrangler's own words are on stderr already; the object says only that the batch didn't finish.
+  const failed = (status: number) => {
+    result({ ok: false, error: `wrangler d1 execute exited ${status}` });
+    return status;
+  };
+  const config = flag(args, "--config");
+  const remote = args.includes("--remote");
+  // Resolved before any write, as every remote command does (p0.10 §4): no credentials is the
+  // handoff, exit 3, never Wrangler's own failure; and the batch goes where the resolver says,
+  // salve's broker included (codex code r2).
+  const auth = remote ? await resolveCloudflare(env, cwd) : null;
+  // A --config of another file is what Wrangler reads, so its account_id must agree too.
+  if (auth && config) sameAccount(auth.account, resolve(cwd, config));
+  const base = cloudflareBase(env);
+  const opts = {
+    database: flag(args, "--database") ?? "DB",
+    remote,
+    cwd,
+    ...(config ? { config } : {}),
+    ...(auth
+      ? {
+          env: {
+            CLOUDFLARE_API_TOKEN: auth.token(),
+            CLOUDFLARE_ACCOUNT_ID: auth.account,
+            // Always, the default included: Wrangler would otherwise take one from the store's
+            // dotenv files and send this token there (codex code r4).
+            CLOUDFLARE_API_BASE_URL: base,
+          },
+        }
+      : {}),
+  };
+  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 failed(status);
+    const expires = new Date(b.expiresAt).toISOString();
+    console.log(`invite ${b.inviteId} for ${target}, valid until ${expires}`);
+    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).
+    const link = origin ? `${origin}/app/invite#${b.token}` : null;
+    if (link) console.log(`or open the admin's invite page:\n${link}`);
+    result({ ok: true, invite: b.inviteId, email: target, expires_at: expires, token: b.token, link });
+    return 0;
+  }
+  if (command === "keys" && sub === "create" && args.includes("--publishable")) {
+    const name = flag(args, "--name");
+    if (!name) return usage("keys create needs --name");
+    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)
+      return usage("--pepper-version takes a whole number from 1");
+    // The pepper lives in the merchant's own vault, or only in the Worker: theirs to hand over (p0.10 §5).
+    if (!pepper)
+      throw new NeedsPerson(
+        `set KEDGE_KEY_PEPPER_V${pepperVersion} to the Worker's pepper secret, or create the key with --url and --sign-in, which keeps the pepper in the Worker`,
+      );
+    const b = await publishableKeySql({ name, origins, pepperVersion, pepper }, now);
+    const status = execute(b, opts);
+    if (status !== 0) return failed(status);
+    console.log(`storefront ${b.storefrontId}, key ${b.keyId}`);
+    console.log(`publishable key (send as x-kedge-key; shown once):\n${b.key}`);
+    result({ ok: true, storefront: b.storefrontId, key_id: b.keyId, key: b.key });
+    return 0;
+  }
+  return usage(USAGE);
+}
+
+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): into `.claude/skills` for Claude Code, and into
+ * `.agents/skills`, where salve and other agents read them (p0.10 §2, §6.4).
+ */
+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"))) {
+    for (const home of [".claude", ".agents"])
+      cpSync(join(docs, "skills", s), join(cwd, home, "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");
+}
+
+interface RunDeps {
+  execute?: Executor;
+  env?: NodeJS.ProcessEnv;
+  cf?: Cloudflare;
+  /** Where `--json`'s object goes; tests read it. */
+  emit?: (result: Record<string, unknown>) => void;
+}
+
+/** The commands an agent reads the result of (p0.10 §5); doctor has its own `--json`. */
+const JSON_COMMANDS = new Set(["deploy", "preview", "staff", "keys", "seed", "smoke"]);
+
+async function run(argv: string[], cwd: string, deps: RunDeps & { json: boolean }): Promise<number> {
+  const [command, ...flags] = argv;
+  const out = {
+    json: deps.json,
+    ...(deps.emit ? { emit: deps.emit } : {}),
+    ...(deps.execute ? { execute: deps.execute } : {}),
+  };
+  if (command === "keys" && flag(flags, "--url")) {
+    const d0: CommandDeps = { cwd, env: deps.env ?? process.env, coreDir: coreMigrationsDir(), ...out };
+    return keysOverHttp(flags, d0);
+  }
+  if (command === "staff" || command === "keys")
+    return bootstrap(command, flags, cwd, deps.execute ?? wranglerExecute, deps.env ?? process.env, {
+      ...out,
+      ...(deps.cf ? { cf: deps.cf } : {}),
+    });
+  const d: CommandDeps = {
+    cwd,
+    env: deps.env ?? process.env,
+    coreDir: coreMigrationsDir(),
+    checkFast: () => main(["check", "--fast"], cwd),
+    ...out,
+  };
+  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 === "smoke") return smokeCommand(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")) {
+      let auth: Awaited<ReturnType<typeof resolveCloudflare>> | null = null;
+      try {
+        auth = await resolveCloudflare(d.env, cwd);
+      } catch (e) {
+        // No credentials is a check that failed and a handoff, with the offline report still printed (codex code r8).
+        if (!(e instanceof NeedsPerson)) throw e;
+        results.push({ name: "credentials", status: "fail", message: e.handoff, handoff: e.handoff });
+      }
+      if (auth) {
+        const cf = restCloudflare(d.env, fetch, wranglerBin(), auth);
+        const lock = JSON.parse(readFileSync(join(cwd, "kedge.lock.json"), "utf8")) as Lock;
+        const creds = await credentialsChecks({ cf, source: auth.source, base: cloudflareBase(d.env) });
+        results.push(...creds);
+        // Credentials that can't read the account would make every later check throw, not report (codex code r7).
+        if (creds.some((c) => c.status === "fail"))
+          results.push({
+            name: "remote",
+            status: "skip",
+            message: "the store's resources weren't read: fix the credentials first",
+          });
+        else results.push(...(await doctorRemote({ cwd, cf, lock, logpushJobs: () => cf.logpushJobs() })));
+      }
+    }
+    console.log(flags.includes("--json") ? JSON.stringify({ checks: results }, null, 2) : formatReport(results));
+    const handoff = results.find((r) => r.handoff)?.handoff;
+    if (handoff) {
+      console.error(`for you: ${handoff}`);
+      return 3;
+    }
+    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;
+  }
+}
+
+/**
+ * The CLI. A handoff from any command ends it with exit 3 and one sentence for
+ * whoever runs it to pass on (p0.10 §5).
+ */
+export async function main(argv: string[], cwd: string, deps: RunDeps = {}): Promise<number> {
+  const [command, ...flags] = argv;
+  const json = flags.includes("--json") && JSON_COMMANDS.has(command ?? "");
+  return withJsonOutput(json, async () => {
+    try {
+      return await run(argv, cwd, { ...deps, json });
+    } catch (e) {
+      // What escapes a command's own handling (bootstrap, doctor) ends the same way (p0.10 §5).
+      const f = failureOf(e);
+      if (!f) throw e;
+      console.error(f.line);
+      if (json) (deps.emit ?? emit)(f.result);
+      return f.code;
+    }
+  });
+}

package/src/manifest.ts

@@ -0,0 +1,163 @@
+// kedge-manifest.json (docs/proposals/p0.8-cli-agent-kit.md §2): what a release
+// shipped, by package and file, written by scripts/pack-kedge.mjs into
+// @kedge/cli. Doctor compares the store's installed packages, core migrations
+// and ejected units with it. Hashing matches the pack script's, package.json
+// included: its keys are sorted first, because pnpm pack orders the
+// dependencies it rewrites differently from one run to the next.
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface Manifest {
+  version: string;
+  upgradesFrom: string | null;
+  doStateFormat: number;
+  migrations: Record<string, { sha256: string; mode: "n1" | "cutover" }>;
+  units: Record<string, { package: string; path: string; sha256: string }>;
+  packages: Record<string, Record<string, string>>;
+}
+
+const sha256 = (buf: Buffer | string) => createHash("sha256").update(buf).digest("hex");
+const sorted = (v: unknown): unknown =>
+  Array.isArray(v)
+    ? v.map(sorted)
+    : v && typeof v === "object"
+      ? Object.fromEntries(
+          Object.keys(v)
+            .sort()
+            .map((k) => [k, sorted((v as Record<string, unknown>)[k])]),
+        )
+      : v;
+
+export function fileHash(path: string, buf: Buffer): string {
+  return path === "package.json" || path.endsWith("/package.json")
+    ? sha256(JSON.stringify(sorted(JSON.parse(buf.toString("utf8")))))
+    : sha256(buf);
+}
+
+/** This CLI's own manifest, or null where there is none (the monorepo's workspace links). */
+export function ownManifest(): Manifest | null {
+  const file = join(dirname(fileURLToPath(import.meta.url)), "..", "kedge-manifest.json");
+  return existsSync(file) ? (JSON.parse(readFileSync(file, "utf8")) as Manifest) : null;
+}
+
+function filesUnder(dir: string): string[] {
+  const out: string[] = [];
+  const walk = (d: string) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) {
+        if (e.name !== "node_modules") walk(p);
+      } else if (e.isFile()) out.push(relative(dir, p));
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+export interface InstalledDrift {
+  package: string;
+  changed: string[];
+  added: string[];
+  missing: string[];
+}
+
+/** Where Node would find `name` from `fromDir`: each ancestor's node_modules, as the resolution algorithm walks. */
+function locate(fromDir: string, name: string): string | null {
+  let d = fromDir;
+  for (;;) {
+    if (basename(d) !== "node_modules") {
+      const p = join(d, "node_modules", ...name.split("/"));
+      if (existsSync(p)) return realpathSync(p);
+    }
+    const up = dirname(d);
+    if (up === d) return null;
+    d = up;
+  }
+}
+
+/**
+ * Every `@kedge/*` package the store loads, found as Node finds it: the
+ * store's own dependencies, then theirs. pnpm keeps a transitive package out
+ * of the store's node_modules (core, db and server sit beside runtime-cf in
+ * its virtual store), and an edit there would run just the same.
+ */
+export function installedPackages(cwd: string): Map<string, string> {
+  const found = new Map<string, string>();
+  const queue: [string, string][] = [];
+  const pj = join(cwd, "package.json");
+  const own = existsSync(pj) ? (JSON.parse(readFileSync(pj, "utf8")) as Record<string, Record<string, string>>) : {};
+  for (const name of Object.keys({ ...own.dependencies, ...own.devDependencies }))
+    if (name.startsWith("@kedge/")) queue.push([cwd, name]);
+  while (queue.length) {
+    const [from, name] = queue.pop() as [string, string];
+    if (found.has(name)) continue;
+    const dir = locate(from, name);
+    if (!dir) continue;
+    found.set(name, dir);
+    const deps = (
+      JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as { dependencies?: Record<string, string> }
+    ).dependencies;
+    for (const d of Object.keys(deps ?? {})) if (d.startsWith("@kedge/")) queue.push([dir, d]);
+  }
+  return found;
+}
+
+/**
+ * Every installed copy of every `@kedge/*` package the store can load, by directory: two dependents
+ * can resolve the same name to different copies, and checking only the first would leave the one the
+ * runtime loads unchecked (codex code r13).
+ */
+export function installedCopies(cwd: string): { name: string; dir: string }[] {
+  const seen = new Map<string, string>();
+  const queue: [string, string][] = [];
+  const pj = join(cwd, "package.json");
+  const own = existsSync(pj) ? (JSON.parse(readFileSync(pj, "utf8")) as Record<string, Record<string, string>>) : {};
+  for (const name of Object.keys({ ...own.dependencies, ...own.devDependencies }))
+    if (name.startsWith("@kedge/")) queue.push([cwd, name]);
+  while (queue.length) {
+    const [from, name] = queue.pop() as [string, string];
+    const dir = locate(from, name);
+    if (!dir || seen.has(dir)) continue;
+    seen.set(dir, name);
+    const deps = (
+      JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as { dependencies?: Record<string, string> }
+    ).dependencies;
+    for (const d of Object.keys(deps ?? {})) if (d.startsWith("@kedge/")) queue.push([dir, d]);
+  }
+  return [...seen].map(([dir, name]) => ({ name, dir }));
+}
+
+/** Each installed copy of each `@kedge/*` package, its files against what the release shipped. */
+export function installedDrift(cwd: string, manifest: Manifest): InstalledDrift[] {
+  const out: InstalledDrift[] = [];
+  const copies = installedCopies(cwd);
+  const count = (n: string) => copies.filter((c) => c.name === n).length;
+  for (const { name: pkg, dir } of copies) {
+    const name = count(pkg) > 1 ? `${pkg} (${relative(cwd, dir)})` : pkg;
+    const files = manifest.packages[pkg];
+    if (!files) {
+      out.push({
+        package: name,
+        changed: [],
+        added: [`(the whole package: Kedge ${manifest.version} didn't ship it)`],
+        missing: [],
+      });
+      continue;
+    }
+    const have = filesUnder(dir);
+    const d: InstalledDrift = { package: name, changed: [], added: [], missing: [] };
+    for (const f of have) {
+      const want = files[f];
+      if (want === undefined) {
+        // The CLI carries the manifest that lists every other file.
+        if (!(pkg === "@kedge/cli" && f === "kedge-manifest.json")) d.added.push(f);
+      } else if (fileHash(f, readFileSync(join(dir, f))) !== want) d.changed.push(f);
+    }
+    const haveSet = new Set(have);
+    for (const f of Object.keys(files)) if (!haveSet.has(f)) d.missing.push(f);
+    if (d.changed.length || d.added.length || d.missing.length) out.push(d);
+  }
+  return out;
+}