@kedge/cli 0.9.0 → 0.10.1

package/src/commands.ts

@@ -6,11 +6,24 @@
 // acting on production.
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
 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 { 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,
@@ -22,9 +35,14 @@ import {
   uncertainMigrations,
 } from "./deploy";
 import { readWrangler } from "./doctor";
+import { badOrigins, ENV, keysSave, type Wanted } from "./keys-save";
 import { installedPackages, ownManifest } from "./manifest";
-import { OperationHeld } from "./ops";
+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 { devPort, resolveTarget, type StoreTarget } from "./target";
 import { compileStoreZone } from "./tz";
 
 export interface CommandDeps {
@@ -38,18 +56,49 @@ export interface CommandDeps {
   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 (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.
+ * 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(): Promise<{ ask: NonNullable<CommandDeps["ask"]>; close: () => void }> {
+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 tty = Boolean(process.stdin.isTTY);
-  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: tty });
+  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);
@@ -57,16 +106,27 @@ export async function terminalAsker(): Promise<{ ask: NonNullable<CommandDeps["a
     if (!muted) write(s);
   };
   const lines = rl[Symbol.asyncIterator]();
+  const waitMs = o.waitMs ?? ANSWER_WAIT_MS;
   return {
     async ask(question, hidden) {
-      process.stdout.write(question);
+      output.write(question);
       muted = hidden && tty;
+      let timer: NodeJS.Timeout | undefined;
       try {
-        const next = await lines.next();
+        // 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 {
-        if (muted) process.stdout.write("\n");
+        clearTimeout(timer);
+        if (muted) output.write("\n");
         muted = false;
       }
     },
@@ -124,10 +184,13 @@ export function bundleWithWrangler(cwd: string) {
   };
 }
 
-async function deployer(d: CommandDeps): Promise<Deployer> {
+/** 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: d.cf ?? restCloudflare(d.env, d.fetch),
+    cf: cf ?? (await cloudflareOf(d)),
     cwd: d.cwd,
     manifest: ownManifest(),
     lock: lockOf(d.cwd),
@@ -140,26 +203,57 @@ async function deployer(d: CommandDeps): Promise<Deployer> {
   });
 }
 
-/** 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> {
+/**
+ * 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 {
-    await work();
+    // 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) {
-    if (e instanceof DeployRefused || e instanceof OperationHeld || e instanceof ComposeError) {
-      (d.error ?? console.error)(e.message);
-      return 1;
-    }
-    throw 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 dep = await deployer(d);
-    (d.log ?? console.log)(
-      `deploying ${dep.names.worker} on account ${(d.cf ?? restCloudflare(d.env, d.fetch)).account}`,
-    );
+    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") ?? "");
@@ -172,11 +266,23 @@ export async function deployCommand(args: readonly string[], d: CommandDeps): Pr
         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"));
+      // 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"),
@@ -185,18 +291,20 @@ export async function deployCommand(args: readonly string[], d: CommandDeps): Pr
       ...(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: "inherit",
-    });
-    return r.status ?? 1;
-  }
+  // Local: the dev database, through Wrangler's own bookkeeping.
+  if (!args.includes("--remote")) return migrateLocal(d);
   return refusals(d, async () => (await deployer(d)).migrateRemote());
 }
 
@@ -207,7 +315,7 @@ export async function migrateCommand(args: readonly string[], d: CommandDeps): P
  */
 export async function generateSupersede(opId: string, d: CommandDeps): Promise<number> {
   return refusals(d, async () => {
-    const cf = d.cf ?? restCloudflare(d.env, d.fetch);
+    const cf = await cloudflareOf(d);
     const names = storeNames(d.cwd).names;
     const { ops } = await openOps(cf, names);
     const held = await ops.current(SCOPE);
@@ -260,8 +368,11 @@ export async function restoreCommand(args: readonly string[], d: CommandDeps): P
     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 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 {
@@ -325,24 +436,16 @@ const SAMPLE_APPAREL = [
   },
 ] 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`;
-}
+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,
@@ -352,7 +455,7 @@ export async function seed(
 ): Promise<string[]> {
   const variants: string[] = [];
   for (const p of SAMPLE_APPAREL) {
-    const res = await fetchImpl(new URL("/admin/products", base), {
+    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({
@@ -366,8 +469,9 @@ export async function seed(
         })),
       }),
     });
-    const body = (await res.json()) as { variantIds?: string[]; error?: { code?: string } };
+    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}`);
@@ -375,10 +479,16 @@ export async function seed(
   return variants;
 }
 
-function authOf(args: readonly string[]): Record<string, string> {
+/** `--key` or `--session`, when given. */
+function givenAuth(args: readonly string[]): Record<string, string> | null {
   const token = flag(args, "--key") ?? flag(args, "--session");
-  if (!token) throw new DeployRefused("give --key <sk_…> or --session <token>");
-  return { authorization: `Bearer ${token}` };
+  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. */
@@ -395,9 +505,9 @@ async function signOutBearer(url: string, token: string, d: CommandDeps): Promis
  * 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> {
+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();
+  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 {
@@ -419,13 +529,12 @@ async function ceremonies(
     "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>;
+    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((j.error as { code?: string } | undefined)?.code ?? "")}`,
+        `${path} answered ${r.status} ${String((r.body.error as { code?: string } | undefined)?.code ?? "")}`,
       );
-    return j;
+    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;
@@ -456,9 +565,46 @@ export async function seedCommand(args: readonly string[], d: CommandDeps): Prom
       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);
+    // 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,
+    });
   });
 }
 
@@ -466,9 +612,10 @@ export async function seedCommand(args: readonly string[], d: CommandDeps): Prom
 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);
+      const token = await signInBearer(url, email, d, args.includes("--answers-stdin"));
       try {
         return await createKeys(url, args, { authorization: `Bearer ${token}` }, d);
       } finally {
@@ -481,11 +628,49 @@ export async function keysOverHttp(args: readonly string[], d: CommandDeps): Pro
   });
 }
 
+/**
+ * `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 f(new URL(path, url), {
+    const r = await storeRequest(f, new URL(path, url), {
       method: "POST",
       headers: {
         ...auth,
@@ -494,12 +679,11 @@ async function createKeys(url: string, args: readonly string[], auth: Record<str
       },
       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 ?? "")}`,
+        `${path} answered ${r.status} ${String((r.body.error as { code?: string } | undefined)?.code ?? "")}`,
       );
-    return j;
+    return r.body;
   };
   const name = flag(args, "--name") ?? "Storefront";
   const log = d.log ?? console.log;
@@ -508,12 +692,13 @@ async function createKeys(url: string, args: readonly string[], auth: Record<str
     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;
+    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 };
 }
 
 /**
@@ -553,7 +738,41 @@ export function devArgs(cwd: string): string[] {
   return id ? ["--define", `KEDGE_ADMIN_BUILD:${JSON.stringify(id)}`] : [];
 }
 
-export function devCommand(d: CommandDeps): number {
+/**
+ * The local database's migrations, through Wrangler's own bookkeeping, in one
+ * line: Wrangler prints its whole status table again after each migration,
+ * thousands of lines for a new store (p0.10.1 §1, 8). Its full output is shown
+ * only when it fails.
+ */
+export function migrateLocal(d: Pick<CommandDeps, "cwd" | "log" | "error">): number {
+  const r = spawnSync(process.execPath, [wranglerBin(), "d1", "migrations", "apply", "DB", "--local"], {
+    cwd: d.cwd,
+    encoding: "utf8",
+    env: { ...process.env, WRANGLER_SEND_METRICS: "false" },
+    maxBuffer: 1 << 26,
+  });
+  const out = `${r.stdout ?? ""}${r.stderr ?? ""}`;
+  if (r.status !== 0) {
+    (d.error ?? console.error)(out.trim().split("\n").slice(-40).join("\n"));
+    return r.status ?? 1;
+  }
+  const n = new Set(out.match(/\b\d{4}_[a-z0-9_]+\.sql\b/g) ?? []).size;
+  (d.log ?? console.log)(
+    n ? `applied ${n} migration${n === 1 ? "" : "s"} to the local database` : "the local database is up to date",
+  );
+  return 0;
+}
+
+/** Whether something already listens on the port: Wrangler would otherwise move to another, silently. */
+function portTaken(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.once("error", () => resolve(true));
+    server.listen(port, "127.0.0.1", () => server.close(() => resolve(false)));
+  });
+}
+
+export async function devCommand(d: CommandDeps): Promise<number> {
   const vars = join(d.cwd, ".dev.vars");
   if (!existsSync(vars)) {
     const lines = [
@@ -569,11 +788,16 @@ export function devCommand(d: CommandDeps): number {
     });
     (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;
+  // One port for dev, its invite link and the CLI's local target (p0.10.1 §3): taken is a refusal, never a move.
+  const port = devPort(d.cwd);
+  if (await portTaken(port)) {
+    (d.error ?? console.error)(
+      `port ${port} is in use: stop what's on it, or set "dev": { "port": <another> } in wrangler.jsonc`,
+    );
+    return 1;
+  }
+  const migrated = migrateLocal(d);
+  if (migrated !== 0) return migrated;
   let extra: string[];
   try {
     extra = devArgs(d.cwd);
@@ -581,7 +805,20 @@ export function devCommand(d: CommandDeps): number {
     (d.log ?? console.log)((e as Error).message);
     return 1;
   }
-  return spawnSync(process.execPath, [wranglerBin(), "dev", ...extra], { cwd: d.cwd, stdio: "inherit" }).status ?? 0;
+  const origin = `http://localhost:${port}`;
+  // Where the store and its admin are, and how a person signs in to a new store's admin (p0.10.1 §1, 5).
+  (d.log ?? console.log)(
+    [
+      `the store: ${origin}   its admin: ${origin}/app/`,
+      "no one can sign in to the admin until there's an Owner: pnpm kedge staff invite-owner <your email>",
+    ].join("\n"),
+  );
+  return (
+    spawnSync(process.execPath, [wranglerBin(), "dev", "--port", String(port), ...extra], {
+      cwd: d.cwd,
+      stdio: "inherit",
+    }).status ?? 0
+  );
 }
 
 export const removeIfExists = (p: string) => rmSync(p, { recursive: true, force: true });
@@ -607,10 +844,10 @@ export async function previewCommand(args: readonly string[], d: CommandDeps): P
     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);
+      const cf = await cloudflareOf(d);
       if (args.includes("--sweep")) {
         await sweepPreviews({ cf, store: store(), log });
-        return;
+        return {};
       }
       await destroyPreview({
         cf,
@@ -620,7 +857,7 @@ export async function previewCommand(args: readonly string[], d: CommandDeps): P
         ...(flag(args, "--take-over") ? { takeOver: flag(args, "--take-over") as string } : {}),
         confirmStopped: args.includes("--confirm-stopped"),
       });
-      return;
+      return { destroyed: name };
     }
     const build = async () => {
       if (d.checkFast && (await d.checkFast()) !== 0) throw new DeployRefused("kedge check --fast failed");
@@ -637,11 +874,15 @@ export async function previewCommand(args: readonly string[], d: CommandDeps): P
     if (sub === "build") {
       const { dir } = await build();
       log(`plan written to ${dir}`);
-      return;
+      return { plan: dir };
     }
-    const cf = d.cf ?? restCloudflare(d.env, d.fetch);
+    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"),
@@ -659,7 +900,7 @@ export async function previewCommand(args: readonly string[], d: CommandDeps): P
       const a = await applyPlan({ ...common, stream, ...(store ? { store } : {}), ...(name ? { name } : {}) });
       await a.release("applied");
       log(`preview ${a.worker} serves ${a.url}`);
-      return;
+      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();
@@ -670,13 +911,14 @@ export async function previewCommand(args: readonly string[], d: CommandDeps): P
     // 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;
-      const cached = cacheCredentials(d.cwd, identity, a.credentials);
+      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/`);
@@ -687,6 +929,13 @@ export async function previewCommand(args: readonly string[], d: CommandDeps): P
     }
     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",
+    };
   });
 }