@kedge/cli 0.0.0-stage → 0.9.0

package/src/commands.ts

@@ -0,0 +1,757 @@
+// P0.8's commands that touch Cloudflare or a running store
+// (docs/proposals/p0.8-cli-agent-kit.md §3): deploy, migrate, restore --list,
+// secret, seed, keys create --url, dev. Each command's target is fixed by what
+// it is: deploy and preview only ever act on Cloudflare; migrate acts locally
+// unless given --remote; nothing decides from the environment that it's
+// acting on production.
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { KedgeConfig } from "@kedge/core";
+import { type Cloudflare, restCloudflare, wranglerBin } from "./cf";
+import { ComposeError, compose, type Lock } from "./compose";
+import {
+  adminBuildIn,
+  appliedNames,
+  Deployer,
+  DeployRefused,
+  openOps,
+  SCOPE,
+  supersededLock,
+  uncertainMigrations,
+} from "./deploy";
+import { readWrangler } from "./doctor";
+import { installedPackages, ownManifest } from "./manifest";
+import { OperationHeld } from "./ops";
+import { git, storeNames } from "./store";
+import { compileStoreZone } from "./tz";
+
+export interface CommandDeps {
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  coreDir: string;
+  cf?: Cloudflare;
+  fetch?: typeof fetch;
+  checkFast?: () => Promise<number>;
+  log?: (s: string) => void;
+  error?: (s: string) => void;
+  /** Asks the person at the terminal; `hidden` doesn't echo (a password). Tests answer it. */
+  ask?: (question: string, hidden: boolean) => Promise<string>;
+}
+
+/**
+ * The terminal's answers, one reader for every question of a command: a second
+ * readline would lose what the first had buffered, so piped answers (an agent
+ * writing the password and code to stdin) would reach only the first question.
+ * A hidden answer isn't echoed, so a password stays off the screen.
+ */
+export async function terminalAsker(): Promise<{ ask: NonNullable<CommandDeps["ask"]>; close: () => void }> {
+  const { createInterface } = await import("node:readline");
+  const tty = Boolean(process.stdin.isTTY);
+  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: tty });
+  const out = rl as unknown as { _writeToOutput: (s: string) => void; output: NodeJS.WriteStream };
+  let muted = false;
+  const write = out._writeToOutput.bind(rl);
+  out._writeToOutput = (s: string) => {
+    if (!muted) write(s);
+  };
+  const lines = rl[Symbol.asyncIterator]();
+  return {
+    async ask(question, hidden) {
+      process.stdout.write(question);
+      muted = hidden && tty;
+      try {
+        const next = await lines.next();
+        if (next.done) throw new DeployRefused("no answer on stdin");
+        return next.value;
+      } finally {
+        if (muted) process.stdout.write("\n");
+        muted = false;
+      }
+    },
+    close: () => rl.close(),
+  };
+}
+
+export function flag(args: readonly string[], name: string): string | undefined {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+export function flagsOf(args: readonly string[], name: string): string[] {
+  return args.flatMap((a, i) => (a === name && args[i + 1] ? [args[i + 1] as string] : []));
+}
+export function varsOf(args: readonly string[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const v of flagsOf(args, "--var")) {
+    const i = v.indexOf("=");
+    if (i < 1) throw new DeployRefused(`--var takes KEY=VALUE, not "${v}"`);
+    out[v.slice(0, i)] = v.slice(i + 1);
+  }
+  return out;
+}
+/** `<from>/<to>`, each an ISO instant. */
+export function windowOf(arg: string | undefined): { from: number; to: number } | undefined {
+  if (!arg) return undefined;
+  const [a, b] = arg.split("/");
+  const from = Date.parse(a ?? "");
+  const to = Date.parse(b ?? "");
+  if (!Number.isFinite(from) || !Number.isFinite(to) || to <= from)
+    throw new DeployRefused("--maintenance-window takes <from>/<to>, two ISO instants, from before to");
+  return { from, to };
+}
+
+const loadConfig = async (cwd: string) =>
+  ((await import(pathToFileURL(join(cwd, "kedge.config.ts")).href)) as { default: KedgeConfig }).default;
+const lockOf = (cwd: string) => JSON.parse(readFileSync(join(cwd, "kedge.lock.json"), "utf8")) as Lock;
+
+/** `wrangler deploy --dry-run --outdir`: bundles the store's code on this (trusted) machine. */
+export function bundleWithWrangler(cwd: string) {
+  return (config: string, outdir: string) => {
+    const r = spawnSync(process.execPath, [wranglerBin(), "deploy", "--dry-run", "--outdir", outdir, "-c", config], {
+      cwd,
+      encoding: "utf8",
+      env: { ...process.env, WRANGLER_SEND_METRICS: "false" },
+    });
+    if (r.status !== 0)
+      throw new DeployRefused(
+        `bundling failed:\n${`${r.stdout}\n${r.stderr}`.trim().split("\n").slice(-15).join("\n")}`,
+      );
+    // Only what uploads stays: Wrangler's README.md and source maps name paths relative to the output
+    // directory, so a resume's rebuild elsewhere never reproduced the plan (research/26), and
+    // `versions upload --no-bundle` sends neither.
+    for (const f of readdirSync(outdir)) if (f === "README.md" || f.endsWith(".map")) rmSync(join(outdir, f));
+  };
+}
+
+async function deployer(d: CommandDeps): Promise<Deployer> {
+  const config = await loadConfig(d.cwd);
+  return new Deployer({
+    cf: d.cf ?? restCloudflare(d.env, d.fetch),
+    cwd: d.cwd,
+    manifest: ownManifest(),
+    lock: lockOf(d.cwd),
+    git: git(d.cwd),
+    bundle: bundleWithWrangler(d.cwd),
+    checkFast: d.checkFast ?? (async () => 0),
+    plugins: config.plugins ?? [],
+    env: d.env,
+    ...(d.log ? { log: d.log } : {}),
+  });
+}
+
+/** Turns a refusal into its message and exit code; anything else is a bug and propagates. */
+async function refusals(d: CommandDeps, work: () => Promise<void>): Promise<number> {
+  try {
+    await work();
+    return 0;
+  } catch (e) {
+    if (e instanceof DeployRefused || e instanceof OperationHeld || e instanceof ComposeError) {
+      (d.error ?? console.error)(e.message);
+      return 1;
+    }
+    throw e;
+  }
+}
+
+export async function deployCommand(args: readonly string[], d: CommandDeps): Promise<number> {
+  return refusals(d, async () => {
+    const dep = await deployer(d);
+    (d.log ?? console.log)(
+      `deploying ${dep.names.worker} on account ${(d.cf ?? restCloudflare(d.env, d.fetch)).account}`,
+    );
+    const resolve = flag(args, "--resolve-intent");
+    if (resolve) return dep.resolveIntent(resolve, args.includes("--not-executed"));
+    if (args.includes("--record-active")) return dep.recordActive(flag(args, "--reason") ?? "");
+    if (args.includes("--abort-cutover")) return dep.abortCutover();
+    const supersede = flag(args, "--supersede");
+    if (supersede) return dep.supersede(supersede);
+    if (args.includes("--adopt-existing")) {
+      const release = flag(args, "--from-release");
+      if (!release)
+        throw new DeployRefused(
+          "--adopt-existing needs --from-release <version>: the release serving now, by your word",
+        );
+      return dep.adoptExisting(release, (f) => readFileSync(join(d.cwd, "migrations", f), "utf8"));
+    }
+    const window = windowOf(flag(args, "--maintenance-window"));
+    const takeOver = flag(args, "--take-over");
+    await dep.deploy({
+      vars: varsOf(args),
+      adopt: flagsOf(args, "--adopt"),
+      allowOlder: args.includes("--allow-older"),
+      resume: args.includes("--resume"),
+      confirmStopped: args.includes("--confirm-stopped"),
+      ...(window ? { window } : {}),
+      ...(takeOver ? { takeOver } : {}),
+    });
+  });
+}
+
+export async function migrateCommand(args: readonly string[], d: CommandDeps): Promise<number> {
+  if (!args.includes("--remote")) {
+    // Local: the dev database, through Wrangler's own bookkeeping.
+    const r = spawnSync(process.execPath, [wranglerBin(), "d1", "migrations", "apply", "DB", "--local"], {
+      cwd: d.cwd,
+      stdio: "inherit",
+    });
+    return r.status ?? 1;
+  }
+  return refusals(d, async () => (await deployer(d)).migrateRemote());
+}
+
+/**
+ * `kedge generate --supersede <op-id>` (§6.2): holding the stopped operation,
+ * the applied prefix kept byte for byte and the proven-unapplied suffix
+ * recomposed from the corrected sources.
+ */
+export async function generateSupersede(opId: string, d: CommandDeps): Promise<number> {
+  return refusals(d, async () => {
+    const cf = d.cf ?? restCloudflare(d.env, d.fetch);
+    const names = storeNames(d.cwd).names;
+    const { ops } = await openOps(cf, names);
+    const held = await ops.current(SCOPE);
+    if (!held || held.op_id !== opId) throw new DeployRefused(`no operation ${opId} holds this store`);
+    await ops.resume(SCOPE, opId);
+    try {
+      const db = await ops.resource("d1", names.database);
+      if (!db?.id) throw new DeployRefused("no database is recorded for this store");
+      const applied = await appliedNames(cf, db.id);
+      const { lock, removed } = supersededLock(lockOf(d.cwd), applied);
+      // Before anything is deleted: a submitted file that could still land can't be recomposed (codex code r21).
+      const uncertain = (await uncertainMigrations(ops, opId)).flatMap((i) =>
+        (JSON.parse(i.detail) as { files: string[] }).files.filter((f) => removed.includes(f)),
+      );
+      if (uncertain.length)
+        throw new DeployRefused(
+          `${uncertain.join(", ")} ${uncertain.length === 1 ? "was" : "were"} submitted and could still land, so ${uncertain.length === 1 ? "it stays" : "they stay"} as ${uncertain.length === 1 ? "it is" : "they are"}: fix forward with a new migration, or a person who knows it never ran says so with kedge deploy --resolve-intent <id> --not-executed`,
+        );
+      const config = await loadConfig(d.cwd);
+      for (const f of removed) if (existsSync(join(d.cwd, "migrations", f))) unlinkSync(join(d.cwd, "migrations", f));
+      writeFileSync(join(d.cwd, "kedge.lock.json"), `${JSON.stringify(lock, null, 2)}\n`);
+      const result = compose({
+        coreDir: d.coreDir,
+        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(d.cwd, "local"),
+        outDir: join(d.cwd, "migrations"),
+        lockPath: join(d.cwd, "kedge.lock.json"),
+        now: Date.now(),
+        ...(config.timezone ? { timezone: config.timezone } : {}),
+        compileZone: compileStoreZone,
+        tzPath: join(d.cwd, "src", "kedge.tz.ts"),
+      });
+      (d.log ?? console.log)(
+        `kept ${applied.length} applied; recomposed ${result.written.filter((f) => f.endsWith(".sql")).join(", ") || "nothing"}. Commit, then kedge deploy --supersede ${opId}`,
+      );
+    } finally {
+      await ops.stop(SCOPE, opId);
+    }
+  });
+}
+
+/** `kedge restore --list` (§6.5): restore points. Restoring waits for P1.18's barrier. */
+export async function restoreCommand(args: readonly string[], d: CommandDeps): Promise<number> {
+  if (!args.includes("--list")) {
+    (d.error ?? console.error)(
+      "kedge restore restores nothing yet: rewinding D1 under a live store needs P1.18's recovery barrier and reconciliation (docs/10). `kedge restore --list` prints the restore points; `wrangler d1 time-travel restore` exists for an emergency, outside Kedge's guarantees.",
+    );
+    return 1;
+  }
+  return refusals(d, async () => {
+    const cf = d.cf ?? restCloudflare(d.env, d.fetch);
+    const { ops } = await openOps(cf, storeNames(d.cwd).names);
+    const log = d.log ?? console.log;
+    for (const r of await ops.deployments()) {
+      const before = JSON.parse(r.before_half) as {
+        bookmark?: string;
+        versionId?: string | null;
+        release?: string | null;
+      };
+      const after = r.after_half ? (JSON.parse(r.after_half) as { versionId?: string; release?: string }) : null;
+      log(
+        `${new Date(r.created_at).toISOString()}  ${r.mode.padEnd(8)}  before ${before.bookmark ?? "(none)"} (${before.release ?? "nothing"}, ${before.versionId ?? "no Worker"}) → ${after ? `${after.release} ${after.versionId}` : "unfinished"}`,
+      );
+    }
+    log(
+      "These are D1 Time Travel bookmarks taken before each deploy's migrations. Restoring through Kedge arrives with P1.18.",
+    );
+  });
+}
+
+export async function secretCommand(args: readonly string[], d: CommandDeps): Promise<number> {
+  const [sub, name] = args;
+  if ((sub !== "put" && sub !== "delete") || !name) {
+    (d.error ?? console.error)("usage: kedge secret put <NAME> (value on stdin) | kedge secret delete <NAME>");
+    return 2;
+  }
+  return refusals(d, async () => {
+    const value = sub === "put" ? readFileSync(0, "utf8").replace(/\r?\n$/, "") : null;
+    if (value !== null && value.length < 32) throw new DeployRefused("a Kedge secret is at least 32 bytes");
+    await (await deployer(d)).secret(name, value);
+  });
+}
+
+// ---- against a running store's HTTP API -------------------------------------------------------------------
+
+const SAMPLE_APPAREL = [
+  {
+    title: "Linen shirt",
+    handle: "linen-shirt",
+    variants: [
+      ["S", 4900],
+      ["M", 4900],
+      ["L", 5200],
+    ],
+  },
+  { title: "Canvas tote", handle: "canvas-tote", variants: [["One size", 1800]] },
+  {
+    title: "Wool beanie",
+    handle: "wool-beanie",
+    variants: [
+      ["Grey", 2400],
+      ["Navy", 2400],
+    ],
+  },
+  {
+    title: "Selvedge jeans",
+    handle: "selvedge-jeans",
+    variants: [
+      ["30", 12000],
+      ["32", 12000],
+      ["34", 12000],
+    ],
+  },
+] as const;
+
+/** Local, or a preview this store's ops knows; anything else only with --live (§3). */
+async function seedTarget(url: string, args: readonly string[], d: CommandDeps): Promise<string | null> {
+  const host = new URL(url).hostname;
+  if (host === "localhost" || host === "127.0.0.1" || host === "[::1]") return null;
+  if (args.includes("--live")) return null;
+  try {
+    const cf = d.cf ?? restCloudflare(d.env, d.fetch);
+    const { ops } = await openOps(cf, storeNames(d.cwd).names);
+    // The whole origin, as a preview's is made: a host that only begins with a preview's name isn't it (codex code r17).
+    const origin = new URL(url).origin;
+    const subdomain = await cf.workersSubdomain();
+    const rows = await ops.query("SELECT worker FROM preview WHERE state = 'bootstrapped'");
+    if (rows.some((r) => origin === `https://${String(r.worker)}.${subdomain}.workers.dev`)) return null;
+  } catch {
+    // no ops database reachable: not a known preview
+  }
+  return `${url} isn't local or a preview this store knows: seeding a live store needs --live, someone's choice`;
+}
+
+export async function seed(
+  base: string,
+  auth: Record<string, string>,
+  fetchImpl: typeof fetch = fetch,
+  log: (s: string) => void = console.log,
+): Promise<string[]> {
+  const variants: string[] = [];
+  for (const p of SAMPLE_APPAREL) {
+    const res = await fetchImpl(new URL("/admin/products", base), {
+      method: "POST",
+      headers: { ...auth, "content-type": "application/json", "idempotency-key": `kedge-seed-${p.handle}` },
+      body: JSON.stringify({
+        title: p.title,
+        handle: p.handle,
+        variants: p.variants.map(([title, price]) => ({
+          sku: `${p.handle}-${title}`.toUpperCase().replace(/[^A-Z0-9]+/g, "-"),
+          title,
+          prices: { USD: price },
+          stock: { loc_default: 50 },
+        })),
+      }),
+    });
+    const body = (await res.json()) as { variantIds?: string[]; error?: { code?: string } };
+    if (res.status === 409 && body.error?.code === "CONFLICT") continue; // already seeded: the handle exists
+    if (!res.ok) throw new DeployRefused(`seeding ${p.handle} failed: ${res.status} ${body.error?.code ?? ""}`);
+    variants.push(...(body.variantIds ?? []));
+    log(`seeded ${p.title}`);
+  }
+  return variants;
+}
+
+function authOf(args: readonly string[]): Record<string, string> {
+  const token = flag(args, "--key") ?? flag(args, "--session");
+  if (!token) throw new DeployRefused("give --key <sk_…> or --session <token>");
+  return { authorization: `Bearer ${token}` };
+}
+
+/** Ends a session the CLI made; a failure leaves it to expire, as it would anyway. */
+async function signOutBearer(url: string, token: string, d: CommandDeps): Promise<void> {
+  await (d.fetch ?? fetch)(new URL("/auth/admin/sign-out", url), {
+    method: "POST",
+    headers: { authorization: `Bearer ${token}` },
+  }).catch(() => undefined);
+}
+
+/**
+ * `--sign-in <email>` (p0.9 §7.3): P0.5's bearer ceremonies run by the CLI, a
+ * password then a TOTP code, because an admin user's own session is an HttpOnly
+ * cookie they can't hand to `--session`. It sends the store's own origin, which
+ * the Worker counts as an admin origin (§4.1). The session serves one command.
+ */
+async function signInBearer(url: string, email: string, d: CommandDeps): Promise<string> {
+  const f = d.fetch ?? fetch;
+  const terminal = d.ask ? null : await terminalAsker();
+  try {
+    return await ceremonies(url, email, d, f, d.ask ?? (terminal as NonNullable<typeof terminal>).ask);
+  } finally {
+    terminal?.close();
+  }
+}
+
+async function ceremonies(
+  url: string,
+  email: string,
+  d: CommandDeps,
+  f: typeof fetch,
+  ask: NonNullable<CommandDeps["ask"]>,
+): Promise<string> {
+  const headers = {
+    origin: new URL(url).origin,
+    "x-kedge-csrf": "1",
+    "x-kedge-session-mode": "bearer",
+    "content-type": "application/json",
+  };
+  const post = async (path: string, body: unknown) => {
+    const r = await f(new URL(path, url), { method: "POST", headers, body: JSON.stringify(body) });
+    const j = (await r.json().catch(() => ({}))) as Record<string, unknown>;
+    if (!r.ok)
+      throw new DeployRefused(
+        `${path} answered ${r.status} ${String((j.error as { code?: string } | undefined)?.code ?? "")}`,
+      );
+    return j;
+  };
+  const first = await post("/auth/admin/sign-in", { email, password: await ask(`password for ${email}: `, true) });
+  const challenge = (first.challenge as { token?: string } | undefined)?.token;
+  // Every staff account has a second factor once its invite completes, so a
+  // weak session here is one that couldn't create keys anyway; it's ended, not left behind.
+  if (!challenge) {
+    if (typeof first.session_token === "string") await signOutBearer(url, first.session_token, d);
+    throw new DeployRefused(`${email} has no second factor yet: finish its invite in the admin first`);
+  }
+  // A mistyped code is a 401 that keeps the challenge (p0.9 §11), so it asks
+  // again; each wrong code counts toward P0.5's lockout, so not forever.
+  for (let attempt = 1; ; attempt++) {
+    const code = (await ask("authenticator code: ", false)).trim();
+    try {
+      const strong = await post("/auth/admin/totp/challenge", { challenge_token: challenge, code });
+      if (typeof strong.session_token !== "string") throw new DeployRefused("the TOTP challenge answered no session");
+      return strong.session_token;
+    } catch (e) {
+      if (attempt >= 3 || !(e instanceof DeployRefused) || !/ 401 UNAUTHORIZED$/.test(e.message)) throw e;
+      (d.error ?? console.error)("that code wasn't accepted; try the next one");
+    }
+  }
+}
+
+export async function seedCommand(args: readonly string[], d: CommandDeps): Promise<number> {
+  return refusals(d, async () => {
+    if (flag(args, "--sample") !== "apparel")
+      throw new DeployRefused("kedge seed --sample apparel --url <url> --key <sk_…>");
+    const url = flag(args, "--url");
+    if (!url) throw new DeployRefused("kedge seed needs --url");
+    const refused = await seedTarget(url, args, d);
+    if (refused) throw new DeployRefused(refused);
+    await seed(url, authOf(args), d.fetch ?? fetch, d.log ?? console.log);
+  });
+}
+
+/** `keys create --url`: through the Worker, so the pepper never leaves it (§6.1). */
+export async function keysOverHttp(args: readonly string[], d: CommandDeps): Promise<number> {
+  return refusals(d, async () => {
+    const url = flag(args, "--url") as string;
+    const email = flag(args, "--sign-in");
+    if (email) {
+      const token = await signInBearer(url, email, d);
+      try {
+        return await createKeys(url, args, { authorization: `Bearer ${token}` }, d);
+      } finally {
+        // The session was made for this one command: ending it keeps a bearer
+        // token that could create keys from outliving the terminal it was typed in.
+        await signOutBearer(url, token, d);
+      }
+    }
+    return createKeys(url, args, authOf(args), d);
+  });
+}
+
+/** The keys themselves, under whichever credential the caller has (P0.8 §6.1). */
+async function createKeys(url: string, args: readonly string[], auth: Record<string, string>, d: CommandDeps) {
+  const f = d.fetch ?? fetch;
+  const post = async (path: string, body: unknown) => {
+    const r = await f(new URL(path, url), {
+      method: "POST",
+      headers: {
+        ...auth,
+        "content-type": "application/json",
+        "idempotency-key": `kedge-keys-${crypto.randomUUID()}`,
+      },
+      body: JSON.stringify(body),
+    });
+    const j = (await r.json()) as Record<string, unknown>;
+    if (!r.ok)
+      throw new DeployRefused(
+        `${path} answered ${r.status} ${String((j.error as { code?: string } | undefined)?.code ?? "")}`,
+      );
+    return j;
+  };
+  const name = flag(args, "--name") ?? "Storefront";
+  const log = d.log ?? console.log;
+  if (args.includes("--secret")) {
+    const grants = flagsOf(args, "--grant").map((permission) => ({ permission, row_scope: "all" }));
+    if (!grants.length) throw new DeployRefused("a secret key needs at least one --grant <permission>");
+    const k = await post("/admin/api-keys", { name, grants });
+    log(`secret key ${String(k.id)} (shown once):\n${String(k.key)}`);
+    return;
+  }
+  const sf = await post("/admin/storefronts", { name, allowed_origins: flagsOf(args, "--origin") });
+  const k = await post(`/admin/storefronts/${String(sf.id)}/keys`, { name });
+  log(`storefront ${String(sf.id)}, key ${String(k.id)}`);
+  log(`publishable key (send as x-kedge-key; shown once):\n${String(k.key)}`);
+}
+
+/**
+ * The environment with the preview key `kedge dev` wrote to .dev.vars when the environment holds none
+ * (codex code r16): that one key, never the rest of the local secrets.
+ */
+export function withPreviewKey(d: Pick<CommandDeps, "cwd" | "env">): NodeJS.ProcessEnv {
+  if (d.env.KEDGE_PREVIEW_KEY) return d.env;
+  const vars = join(d.cwd, ".dev.vars");
+  const key = existsSync(vars) ? /^KEDGE_PREVIEW_KEY=(.+)$/m.exec(readFileSync(vars, "utf8"))?.[1]?.trim() : undefined;
+  return key ? { ...d.env, KEDGE_PREVIEW_KEY: key } : d.env;
+}
+
+/** `kedge dev`: fresh local secrets once, local migrations, then wrangler dev (§3). */
+/**
+ * What `kedge dev` adds to `wrangler dev` (p0.9 §3.5): the admin's build defined
+ * into the Worker's code, as deploy and preview define it. It refuses a config
+ * whose `routes` or `dev` host would make Wrangler rewrite the request's origin
+ * (`--local-upstream` "defaults to dev.host or route", `wrangler dev --help`,
+ * 4.152.0): sign-in relies on the request's URL being the browser's own origin.
+ */
+export function devArgs(cwd: string): string[] {
+  const w = readWrangler(cwd);
+  const c = (w?.config ?? {}) as Record<string, unknown> & { dev?: Record<string, unknown> };
+  const rewrites = [
+    ...(c.routes !== undefined ? ["routes"] : []),
+    ...(c.route !== undefined ? ["route"] : []),
+    ...(c.dev?.host !== undefined ? ["dev.host"] : []),
+    ...(c.dev?.local_upstream !== undefined ? ["dev.local_upstream"] : []),
+  ];
+  if (rewrites.length)
+    throw new DeployRefused(
+      `wrangler.jsonc sets ${rewrites.join(", ")}, which makes wrangler dev give the Worker another origin than the browser's, and the admin's sign-in would be refused: remove ${rewrites.length === 1 ? "it" : "them"} (kedge deploy refuses routes too)`,
+    );
+  const dir = (c.assets as { directory?: string } | undefined)?.directory;
+  const id = dir ? adminBuildIn(resolve(cwd, dir)) : null;
+  return id ? ["--define", `KEDGE_ADMIN_BUILD:${JSON.stringify(id)}`] : [];
+}
+
+export function devCommand(d: CommandDeps): number {
+  const vars = join(d.cwd, ".dev.vars");
+  if (!existsSync(vars)) {
+    const lines = [
+      "CART_TOKEN_SECRET",
+      "ORDER_TOKEN_SECRET",
+      "KEDGE_AUTH_SECRET_V1",
+      "KEDGE_KEY_PEPPER_V1",
+      "KEDGE_TOTP_KEY_V1",
+      "KEDGE_PREVIEW_KEY",
+    ].map((n) => `${n}=${Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString("base64url")}`);
+    writeFileSync(vars, `# Local secrets for kedge dev, made once; never commit this file.\n${lines.join("\n")}\n`, {
+      mode: 0o600,
+    });
+    (d.log ?? console.log)("wrote .dev.vars with fresh local secrets");
+  }
+  const migrated = spawnSync(process.execPath, [wranglerBin(), "d1", "migrations", "apply", "DB", "--local"], {
+    cwd: d.cwd,
+    stdio: "inherit",
+  });
+  if (migrated.status !== 0) return migrated.status ?? 1;
+  let extra: string[];
+  try {
+    extra = devArgs(d.cwd);
+  } catch (e) {
+    (d.log ?? console.log)((e as Error).message);
+    return 1;
+  }
+  return spawnSync(process.execPath, [wranglerBin(), "dev", ...extra], { cwd: d.cwd, stdio: "inherit" }).status ?? 0;
+}
+
+export const removeIfExists = (p: string) => rmSync(p, { recursive: true, force: true });
+
+// ---- kedge preview (§5) ------------------------------------------------------------------------------------
+
+function branchName(cwd: string): string {
+  const r = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd, encoding: "utf8" });
+  const b = r.stdout.trim();
+  if (r.status !== 0 || !b || b === "HEAD") throw new DeployRefused("give --name: this checkout has no branch");
+  return b;
+}
+
+export async function previewCommand(args: readonly string[], d: CommandDeps): Promise<number> {
+  const { applyPlan, buildPlan, cacheCredentials, destroyPreview, hasScenarios, runScenarios, sweepPreviews, tarPlan } =
+    await import("./preview");
+  const { signInOwner } = await import("@kedge/testing/http");
+  const sub = args[0] === "build" || args[0] === "apply" || args[0] === "destroy" ? args[0] : null;
+  const log = d.log ?? console.log;
+  return refusals(d, async () => {
+    const store = (): string => String(storeNames(d.cwd).config.name);
+    // A sweep names no preview, so it needs no branch (a detached CI checkout has none).
+    const sweep = sub === "destroy" && args.includes("--sweep");
+    const name = flag(args, "--name") ?? (sub === "apply" || sweep ? undefined : branchName(d.cwd));
+    if (sub === "destroy") {
+      const cf = d.cf ?? restCloudflare(d.env, d.fetch);
+      if (args.includes("--sweep")) {
+        await sweepPreviews({ cf, store: store(), log });
+        return;
+      }
+      await destroyPreview({
+        cf,
+        store: store(),
+        name: name as string,
+        log,
+        ...(flag(args, "--take-over") ? { takeOver: flag(args, "--take-over") as string } : {}),
+        confirmStopped: args.includes("--confirm-stopped"),
+      });
+      return;
+    }
+    const build = async () => {
+      if (d.checkFast && (await d.checkFast()) !== 0) throw new DeployRefused("kedge check --fast failed");
+      const config = await loadConfig(d.cwd);
+      return buildPlan({
+        cwd: d.cwd,
+        name: name as string,
+        lock: lockOf(d.cwd),
+        vars: varsOf(args),
+        secrets: config.preview?.secrets ?? [],
+        bundle: bundleWithWrangler(d.cwd),
+      });
+    };
+    if (sub === "build") {
+      const { dir } = await build();
+      log(`plan written to ${dir}`);
+      return;
+    }
+    const cf = d.cf ?? restCloudflare(d.env, d.fetch);
+    const takeOver = flag(args, "--take-over");
+    const common = {
+      cf,
+      env: withPreviewKey(d),
+      secretEnv: flagsOf(args, "--secret-env"),
+      fresh: args.includes("--fresh"),
+      confirmStopped: args.includes("--confirm-stopped"),
+      log,
+      ...(takeOver ? { takeOver } : {}),
+      ...(d.fetch ? { fetch: d.fetch } : {}),
+    };
+    if (sub === "apply") {
+      const source = args[1];
+      if (!source) throw new DeployRefused("kedge preview apply <plan.tar | -> [--store <name>] [--name <name>]");
+      const stream = source === "-" ? readFileSync(0) : readFileSync(source);
+      const store = flag(args, "--store");
+      const a = await applyPlan({ ...common, stream, ...(store ? { store } : {}), ...(name ? { name } : {}) });
+      await a.release("applied");
+      log(`preview ${a.worker} serves ${a.url}`);
+      return;
+    }
+    // Both halves, then the store's scenarios, under the preview's operation to the last result (§5.3).
+    const { dir, plan } = await build();
+    const a = await applyPlan({ ...common, stream: tarPlan(dir) });
+    const identity = `${plan.store}/${plan.name}`;
+    // One Owner sign-in for every scenario file, before the cache, which then keeps its step: files signing
+    // in at once would send one step's code, and all but one be refused (codex code r29).
+    // Whatever fails after the deploy still ends the operation: left held, the next preview or destroy
+    // would need --take-over --confirm-stopped for a run that merely threw (codex code r30).
+    let code: number;
+    try {
+      const owner = a.credentials.owner;
+      const ownerSession =
+        owner && hasScenarios(d.cwd)
+          ? await signInOwner(a.url, owner, a.credentials.adminOrigin ?? "https://kedge-preview.invalid")
+          : undefined;
+      const cached = cacheCredentials(d.cwd, identity, a.credentials);
+      log(`preview ${a.worker} serves ${a.url} (credentials in ${cached})`);
+      // The admin, when the store serves it (p0.9 §3.4): the preview's own origin signs in, with no ADMIN_ORIGINS.
+      if (plan.assets) log(`admin: ${a.url}/app/`);
+      code = runScenarios(d.cwd, { ...a.credentials, ...(ownerSession ? { ownerSession } : {}) }, d.env);
+    } catch (e) {
+      await a.release(`scenarios didn't run: ${(e as Error).message}`);
+      throw e;
+    }
+    await a.release(code === 0 ? "scenarios passed" : "scenarios failed");
+    if (code !== 0) throw new DeployRefused("the store's scenarios failed against the preview");
+  });
+}
+
+// ---- kedge eject, kedge upgrade (§7, §8) -------------------------------------------------------------------
+
+export async function ejectCommand(args: readonly string[], d: CommandDeps): Promise<number> {
+  const { eject, rebase } = await import("./units");
+  const manifest = ownManifest();
+  const log = d.log ?? console.log;
+  const fail = (m: string) => {
+    (d.error ?? console.error)(m);
+    return 1;
+  };
+  if (!manifest) return fail("kedge eject needs an installed release (a workspace install has no manifest)");
+  try {
+    const r = flag(args, "--rebase");
+    if (r) {
+      rebase(d.cwd, manifest, r);
+      log(`${r} now records Kedge ${manifest.version}'s upstream`);
+      return 0;
+    }
+    const unit = args[0];
+    if (!unit || unit.startsWith("--"))
+      return fail(`usage: kedge eject <unit> --reason "<why>"; units: ${Object.keys(manifest.units).join(", ")}`);
+    const out = eject(d.cwd, manifest, unit, flag(args, "--reason") ?? "");
+    log(`wrote ${out.file}. Wire it in kedge.config.ts:\n${out.wiring}`);
+    return 0;
+  } catch (e) {
+    return fail((e as Error).message);
+  }
+}
+
+export async function upgradeCommand(
+  args: readonly string[],
+  d: CommandDeps & { kedge: (argv: string[]) => Promise<number> },
+): Promise<number> {
+  const { upgrade, UpgradeRefused } = await import("./upgrade");
+  const to = flag(args, "--to");
+  if (!to) {
+    (d.error ?? console.error)("usage: kedge upgrade --to <version> [--from-packs <dir>]");
+    return 2;
+  }
+  try {
+    const fromPacks = flag(args, "--from-packs");
+    await upgrade({
+      cwd: d.cwd,
+      to,
+      ...(fromPacks ? { fromPacks } : {}),
+      git: git(d.cwd),
+      manifest: () => {
+        // The CLI just installed is the target's: read its manifest from the store, not this process.
+        const dir = installedPackages(d.cwd).get("@kedge/cli");
+        return dir && existsSync(join(dir, "kedge-manifest.json"))
+          ? JSON.parse(readFileSync(join(dir, "kedge-manifest.json"), "utf8"))
+          : null;
+      },
+      kedge: d.kedge,
+      ...(d.log ? { log: d.log } : {}),
+    });
+    return 0;
+  } catch (e) {
+    if (e instanceof UpgradeRefused) {
+      (d.error ?? console.error)(e.message);
+      return 1;
+    }
+    throw e;
+  }
+}