@kedge/cli 0.0.0-stage → 0.10.0

package/src/commands.ts

@@ -0,0 +1,959 @@
+// 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 { isPermission, type KedgeConfig } from "@kedge/core";
+import {
+  type Cloudflare,
+  CloudflareError,
+  cloudflareFor,
+  isJurisdictionChoice,
+  type JurisdictionChoice,
+  NeedsPerson,
+  preflight,
+  UnknownOutcome,
+  wranglerBin,
+} from "./cf";
+import { isCliSession, OLDER_KEDGE, type SessionDeps, withCliSession } from "./cli-session";
+import { ComposeError, compose, type Lock } from "./compose";
+import { type Executor, wranglerExecute } from "./d1-batch";
+import {
+  adminBuildIn,
+  appliedNames,
+  Deployer,
+  DeployRefused,
+  openOps,
+  SCOPE,
+  supersededLock,
+  uncertainMigrations,
+} from "./deploy";
+import { readWrangler } from "./doctor";
+import { badOrigins, ENV, keysSave, type Wanted } from "./keys-save";
+import { installedPackages, ownManifest } from "./manifest";
+import { LostOwnership, OperationHeld } from "./ops";
+import { childStdio, emit } from "./output";
+import { needsLive, smoke } from "./smoke";
+import { git, storeNames } from "./store";
+import { storeRequest } from "./store-api";
+import { resolveTarget, type StoreTarget } from "./target";
+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>;
+  /** Writes a CLI session's row to `kedge dev`'s database; tests replace it. */
+  execute?: Executor;
+  /** The sign-in's stdin; tests give a stream. */
+  stdin?: Stdin;
+  /** `--json`: the command's result as one object on stdout (p0.10 §5). */
+  json?: boolean;
+  /** Where that object goes; tests read it. */
+  emit?: (result: Record<string, unknown>) => void;
+}
+
+/** How long `--answers-stdin` waits for each answer (p0.10 §5). */
+export const ANSWER_WAIT_MS = 30_000;
+
+type Stdin = NodeJS.ReadableStream & { isTTY?: boolean };
+
+/**
+ * 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 would reach
+ * only the first question. A hidden answer isn't echoed, so a password stays
+ * off the screen.
+ *
+ * Only a terminal is asked unless `--answers-stdin` says otherwise, and that's
+ * decided before anything is sent (p0.10 §5): an agent's tool call can hold
+ * stdin open and write nothing, and a read would then wait forever. Piped
+ * answers wait at most `ANSWER_WAIT_MS` each, as `docker login --password-stdin`
+ * is the explicit way in.
+ */
+export async function terminalAsker(o: {
+  answersStdin: boolean;
+  input?: Stdin;
+  output?: NodeJS.WritableStream;
+  waitMs?: number;
+}): Promise<{ ask: NonNullable<CommandDeps["ask"]>; close: () => void }> {
+  const input = o.input ?? process.stdin;
+  // Questions go to stderr, as git's and ssh's do: under --json stdout is the result's alone.
+  const output = o.output ?? process.stderr;
+  const tty = Boolean(input.isTTY);
+  if (!tty && !o.answersStdin)
+    throw new NeedsPerson(
+      "signing in asks for your password and authenticator code: run this command in your own terminal",
+    );
+  const { createInterface } = await import("node:readline");
+  const rl = createInterface({ input, output, 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]();
+  const waitMs = o.waitMs ?? ANSWER_WAIT_MS;
+  return {
+    async ask(question, hidden) {
+      output.write(question);
+      muted = hidden && tty;
+      let timer: NodeJS.Timeout | undefined;
+      try {
+        // A person at a terminal takes the time they need; a pipe that sends nothing is an end.
+        const silence = new Promise<never>((_, reject) => {
+          if (!tty)
+            timer = setTimeout(
+              () => reject(new DeployRefused(`no answer on stdin within ${waitMs / 1000} seconds`)),
+              waitMs,
+            );
+        });
+        const next = await Promise.race([lines.next(), silence]);
+        if (next.done) throw new DeployRefused("no answer on stdin");
+        return next.value;
+      } finally {
+        clearTimeout(timer);
+        if (muted) output.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));
+  };
+}
+
+/** The Cloudflare a command acts on: the given one (tests), else whatever source resolves. */
+const cloudflareOf = async (d: CommandDeps) => d.cf ?? (await cloudflareFor(d.env, d.cwd, d.fetch));
+
+async function deployer(d: CommandDeps, cf?: Cloudflare): Promise<Deployer> {
+  const config = await loadConfig(d.cwd);
+  return new Deployer({
+    cf: cf ?? (await cloudflareOf(d)),
+    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. Under `--json` the outcome is also one object on stdout: what the
+ * command made, its handoff, or its refusal (p0.10 §5).
+ */
+async function refusals(d: CommandDeps, work: () => Promise<unknown>): Promise<number> {
+  const result = (r: Record<string, unknown>) => {
+    if (d.json) (d.emit ?? emit)(r);
+  };
+  try {
+    // What the command made, when it returns it; a void command's object is only `ok`.
+    const made = await work();
+    result({ ok: true, ...(made && typeof made === "object" ? made : {}) });
+    return 0;
+  } catch (e) {
+    const f = failureOf(e);
+    if (!f) throw e;
+    (d.error ?? console.error)(f.line);
+    result(f.result);
+    return f.code;
+  }
+}
+
+/**
+ * How a command that didn't succeed ends, for a person and under `--json`
+ * (p0.10 §5): a handoff (exit 3, the last line `for you:`), or a refusal,
+ * Cloudflare refusing, or Cloudflare not answering (exit 1). An unanswered
+ * call says its outcome is unknown: the operation stays held, for
+ * `deploy --resume` or `doctor --remote` to settle. Null is a bug, which propagates.
+ */
+export function failureOf(e: unknown): { code: 1 | 3; line: string; result: Record<string, unknown> } | null {
+  if (e instanceof NeedsPerson)
+    return { code: 3, line: `for you: ${e.handoff}`, result: { ok: false, handoff: e.handoff } };
+  if (e instanceof UnknownOutcome)
+    return { code: 1, line: e.message, result: { ok: false, error: e.message, outcome: "unknown" } };
+  if (
+    e instanceof DeployRefused ||
+    e instanceof OperationHeld ||
+    e instanceof LostOwnership ||
+    e instanceof ComposeError ||
+    e instanceof CloudflareError
+  )
+    return { code: 1, line: e.message, result: { ok: false, error: e.message } };
+  return null;
+}
+
+export async function deployCommand(args: readonly string[], d: CommandDeps): Promise<number> {
+  return refusals(d, async () => {
+    const cf = await cloudflareOf(d);
+    const dep = await deployer(d, cf);
+    (d.log ?? console.log)(`deploying ${dep.names.worker} on account ${cf.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",
+        );
+      // Adoption takes the store's jurisdiction from what exists, so it asks nothing; a choice is checked against it.
+      const choice = flag(args, "--jurisdiction");
+      await preflight(cf);
+      if (choice !== undefined && !isJurisdictionChoice(choice))
+        throw new DeployRefused(`--jurisdiction takes eu, us, fedramp or none, not "${choice}"`);
+      return dep.adoptExisting(
+        release,
+        (f) => readFileSync(join(d.cwd, "migrations", f), "utf8"),
+        choice as JurisdictionChoice | undefined,
+      );
+    }
+    const window = windowOf(flag(args, "--maintenance-window"));
+    const takeOver = flag(args, "--take-over");
+    const choice = flag(args, "--jurisdiction");
+    await preflight(cf, dep.names.ops, choice);
+    await dep.deploy({
+      ...(choice ? { jurisdiction: choice as JurisdictionChoice } : {}),
+      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 } : {}),
+    });
+    // From the account's subdomain now, never a recorded URL: its owner can change it (p0.10 §4).
+    const url = `https://${dep.names.worker}.${await cf.workersSubdomain()}.workers.dev`;
+    return { worker: dep.names.worker, account: cf.account, url, admin: adminUrl(d.cwd, url) };
+  });
+}
+
+/** The admin's address, when the store serves it (p0.9 §3.3); null when it serves none. */
+function adminUrl(cwd: string, url: string): string | null {
+  return readWrangler(cwd)?.config.assets ? `${url}/app/` : null;
+}
+
+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: childStdio(),
+    });
+    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 = await cloudflareOf(d);
+    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 = await cloudflareOf(d);
+    const names = storeNames(d.cwd).names;
+    // A lookup, never a create: no ops database is no preview, and seeding writes nothing to Cloudflare.
+    if (!(await cf.findD1(names.ops))) throw new DeployRefused("no ops database");
+    const { ops } = await openOps(cf, 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;
+
+const isLocal = (url: string) => ["localhost", "127.0.0.1", "[::1]"].includes(new URL(url).hostname);
+
+/** The store a URL is, for a CLI session or a check: what `resolveTarget` says, credentials resolved as for any remote command. */
+const targetOf = (url: string, d: CommandDeps) => resolveTarget(url, d.cwd, () => cloudflareOf(d));
+
+/** How a CLI session's row is written (p0.10 §6.2). */
+const sessionDeps = (d: CommandDeps): SessionDeps => ({
+  cloudflare: () => cloudflareOf(d),
+  executeLocal: (b) => (d.execute ?? wranglerExecute)(b, { database: "DB", remote: false, cwd: d.cwd }),
+});
+
+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 storeRequest(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 = res.body as { variantIds?: string[]; error?: { code?: string } };
+    if (res.status === 409 && body.error?.code === "CONFLICT") continue; // already seeded: the handle exists
+    if (res.status === 401 && isCliSession(auth)) throw new DeployRefused(OLDER_KEDGE);
+    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;
+}
+
+/** `--key` or `--session`, when given. */
+function givenAuth(args: readonly string[]): Record<string, string> | null {
+  const token = flag(args, "--key") ?? flag(args, "--session");
+  return token ? { authorization: `Bearer ${token}` } : null;
+}
+
+function authOf(args: readonly string[]): Record<string, string> {
+  const auth = givenAuth(args);
+  if (!auth) throw new DeployRefused("give --key <sk_…> or --session <token>");
+  return auth;
+}
+
+/** 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, answersStdin: boolean): Promise<string> {
+  const f = d.fetch ?? fetch;
+  const terminal = d.ask ? null : await terminalAsker({ answersStdin, ...(d.stdin ? { input: d.stdin } : {}) });
+  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 storeRequest(f, new URL(path, url), { method: "POST", headers, body: JSON.stringify(body) });
+    if (!r.ok)
+      throw new DeployRefused(
+        `${path} answered ${r.status} ${String((r.body.error as { code?: string } | undefined)?.code ?? "")}`,
+      );
+    return r.body;
+  };
+  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");
+    // Local, or a preview this store's ops knows by its whole origin (codex code r17); a live store's
+    // customers would see sample products, so it's the owner's call (p0.10 §5).
+    let target: StoreTarget | null = null;
+    if (!isLocal(url) && !args.includes("--live")) {
+      target = await targetOf(url, d);
+      if (target?.kind !== "preview")
+        throw new NeedsPerson(
+          `${url} isn't local or a preview this store knows: sample products on a live store are for its owner to allow; with their yes, run this again with --live`,
+        );
+    }
+    const run = (auth: Record<string, string>) => seed(url, auth, d.fetch ?? fetch, d.log ?? console.log);
+    const given = givenAuth(args);
+    if (given) return { variants: await run(given) };
+    // No key or session given: a CLI session on the store the URL is, and only there (p0.10 §6.2).
+    target ??= await targetOf(url, d);
+    if (!target)
+      throw new DeployRefused(
+        `${url} isn't a store this checkout knows, so it gets no CLI session: give --key <sk_…> or --session <token>`,
+      );
+    return { variants: await withCliSession(target, ["product:write"], sessionDeps(d), run) };
+  });
+}
+
+/** `kedge smoke` (p0.10 §6.3): a named test order, resumed until it has its number. */
+export async function smokeCommand(args: readonly string[], d: CommandDeps): Promise<number> {
+  return refusals(d, async () => {
+    const url = flag(args, "--url");
+    if (!url) throw new DeployRefused("kedge smoke --url <store> [--run <name>] [--live]");
+    const name = flag(args, "--run") ?? "first";
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name))
+      throw new DeployRefused("--run takes a name of letters, digits, - and _, up to 64");
+    const target = await targetOf(url, d);
+    if (!target) throw new DeployRefused(`${url} isn't a store this checkout knows: smoke runs only on its own stores`);
+    needsLive(target, args.includes("--live"));
+    return smoke(target, name, {
+      cwd: d.cwd,
+      fetch: d.fetch ?? fetch,
+      session: sessionDeps(d),
+      log: 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;
+    if (args.includes("--save")) return saveKeys(url, args, d);
+    const email = flag(args, "--sign-in");
+    if (email) {
+      const token = await signInBearer(url, email, d, args.includes("--answers-stdin"));
+      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);
+  });
+}
+
+/**
+ * `keys create --save` (p0.10 §6.2): through a credential reference with a
+ * CLI session, saved to `.env.local`. What it answers names what was saved,
+ * never the key: the key stays in the file, out of the agent's transcript.
+ */
+async function saveKeys(url: string, args: readonly string[], d: CommandDeps) {
+  if (flag(args, "--sign-in") || givenAuth(args))
+    throw new DeployRefused("--save makes its own CLI session: drop --sign-in, --key and --session");
+  const target = await targetOf(url, d);
+  if (!target)
+    throw new DeployRefused(`${url} isn't a store this checkout knows, so it gets no CLI session and no saved key`);
+  const name = flag(args, "--name") ?? "Storefront";
+  const wanted: Wanted = args.includes("--secret")
+    ? { kind: "secret", name, grants: flagsOf(args, "--grant") }
+    : { kind: "publishable", name, origins: flagsOf(args, "--origin") };
+  if (wanted.kind === "secret" && wanted.grants.length === 0)
+    throw new DeployRefused("a secret key needs at least one --grant <permission>");
+  // Origins as the store accepts them, checked before anything is reused or written (codex code r16).
+  const wrong = wanted.kind === "publishable" ? badOrigins(wanted.origins) : [];
+  if (wrong.length)
+    throw new DeployRefused(
+      `not origins: ${wrong.join(", ")} (an origin is a scheme, host and optional port, like https://shop.example)`,
+    );
+  // Checked here, so a typo is one refusal under --json, before any session exists (codex code r15).
+  const bad = wanted.kind === "secret" ? wanted.grants.filter((g) => !isPermission(g)) : [];
+  if (bad.length) throw new DeployRefused(`not permissions: ${bad.join(", ")} (a permission is resource:action)`);
+  // The session that makes it holds the key's grants and api_key:write, and a session holds 16 at most.
+  if (wanted.kind === "secret" && new Set(wanted.grants).size > 15)
+    throw new DeployRefused("--save makes a secret key of at most 15 grants; make a wider one from the admin");
+  const saved = await keysSave(target, wanted, {
+    cwd: d.cwd,
+    fetch: d.fetch ?? fetch,
+    session: sessionDeps(d),
+    log: d.log ?? console.log,
+  });
+  return { saved: Object.keys(saved).sort(), storefront: saved[ENV.storefront] ?? null };
+}
+
+/** 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 storeRequest(f, new URL(path, url), {
+      method: "POST",
+      headers: {
+        ...auth,
+        "content-type": "application/json",
+        "idempotency-key": `kedge-keys-${crypto.randomUUID()}`,
+      },
+      body: JSON.stringify(body),
+    });
+    if (!r.ok)
+      throw new DeployRefused(
+        `${path} answered ${r.status} ${String((r.body.error as { code?: string } | undefined)?.code ?? "")}`,
+      );
+    return r.body;
+  };
+  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 { key_id: k.id, key: k.key };
+  }
+  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)}`);
+  return { storefront: sf.id, key_id: k.id, key: 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 = await cloudflareOf(d);
+      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 { destroyed: name };
+    }
+    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 { plan: dir };
+    }
+    const cf = await cloudflareOf(d);
+    const choice = flag(args, "--jurisdiction");
+    // A full preview builds from this checkout, so it knows its store; a plan applied from elsewhere names its own.
+    await preflight(cf, sub === "apply" ? undefined : `${store()}-ops`, choice);
+    const takeOver = flag(args, "--take-over");
+    const common = {
+      ...(choice ? { jurisdiction: choice as JurisdictionChoice } : {}),
+      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 { worker: a.worker, url: a.url };
+    }
+    // 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;
+    let cached: string;
+    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;
+      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");
+    return {
+      worker: a.worker,
+      url: a.url,
+      admin: plan.assets ? `${a.url}/app/` : null,
+      credentials: cached,
+      scenarios: hasScenarios(d.cwd) ? "passed" : "none",
+    };
+  });
+}
+
+// ---- 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;
+  }
+}