@kedge/cli 0.9.0 → 0.10.1

package/src/d1-batch.ts

@@ -0,0 +1,68 @@
+// The CLI's own audited batches against a store's D1 (p0.5 §3.4, D-054):
+// `staff`, direct `keys create`, and a CLI session's row (p0.10 §6.2), each
+// one file through `wrangler d1 execute`, locally or on Cloudflare.
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CliBatch } from "@kedge/db";
+import { wranglerBin } from "./cf";
+import { childFailed, childStdio } from "./output";
+
+/** Runs one CLI batch against the store's D1; tests replace it. */
+export type Executor = (
+  b: CliBatch,
+  opts: { database: string; remote: boolean; cwd: string; config?: string; env?: Record<string, string> },
+) => number;
+
+/** The bootstrap Wrangler's whole environment: PATH, an empty HOME, and what Kedge resolved. */
+export function bootstrapEnv(
+  env: NodeJS.ProcessEnv,
+  home: string,
+  resolved: Record<string, string> = {},
+): Record<string, string> {
+  return { PATH: env.PATH ?? "", HOME: home, WRANGLER_SEND_METRICS: "false", CI: "1", ...resolved };
+}
+
+export const wranglerExecute: Executor = (b, opts) => {
+  const dir = mkdtempSync(join(tmpdir(), "kedge-"));
+  const file = join(dir, "batch.sql");
+  // An empty dotenv file of our own: Wrangler then loads none of the store's, whose stale
+  // CLOUDFLARE_* values could redirect the resolved credentials (codex code r4).
+  const envFile = join(dir, "empty.env");
+  try {
+    writeFileSync(file, b.sql, { mode: 0o600 });
+    writeFileSync(envFile, "");
+    // The CLI's own Wrangler with only what Kedge resolved: an inherited environment could carry a
+    // global API key, which Wrangler prefers to a token and would send instead (codex code r5),
+    // and an empty HOME holds no one's login. The store directory stays the working one, for its
+    // config and its local state.
+    const r = spawnSync(
+      process.execPath,
+      [
+        wranglerBin(),
+        "d1",
+        "execute",
+        opts.database,
+        "--file",
+        file,
+        opts.remote ? "--remote" : "--local",
+        "--yes",
+        "--env-file",
+        envFile,
+        ...(opts.config ? ["-c", opts.config] : []),
+      ],
+      {
+        cwd: opts.cwd,
+        stdio: childStdio(),
+        env: bootstrapEnv(process.env, dir, opts.env),
+        maxBuffer: 1 << 26,
+      },
+    );
+    childFailed(r);
+    return r.status ?? 1;
+  } finally {
+    // The file holds no secret (only digests), but it needn't outlive the run.
+    rmSync(dir, { recursive: true, force: true });
+  }
+};

package/src/deploy.ts

@@ -11,7 +11,14 @@ import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFi
 import { join, resolve } from "node:path";
 import { maintenanceModule } from "@kedge/runtime-cf/maintenance";
 import { DO_STATE_FORMAT } from "@kedge/runtime-cf/release";
-import { type Cloudflare, UnknownOutcome, type WorkerSettings } from "./cf";
+import {
+  CHOOSE_JURISDICTION,
+  type Cloudflare,
+  type JurisdictionChoice,
+  NeedsPerson,
+  UnknownOutcome,
+  type WorkerSettings,
+} from "./cf";
 import type { Lock, LockEntry } from "./compose";
 import { declaredClasses } from "./doctor";
 import type { Manifest } from "./manifest";
@@ -143,6 +150,8 @@ export interface DeployDeps {
 }
 
 export interface DeployOptions {
+  /** The person's choice of where a new store's data lives (p0.10 §7); read from the record after. */
+  jurisdiction?: JurisdictionChoice;
   vars?: Record<string, string>;
   window?: { from: number; to: number };
   adopt?: string[];
@@ -161,16 +170,29 @@ export class DeployRefused extends Error {
 
 const lockSha = (lock: Lock) => sha256(JSON.stringify(lock.entries.map((e) => [e.file, e.sha256])));
 
-/** The ops database: found or created by exact name, and refused unless it's this store's (§6.1). */
+/**
+ * The ops database: found or created by exact name, and refused unless it's
+ * this store's (§6.1). Creating it fixes the store's jurisdiction (p0.10 §7),
+ * so only a caller given the person's choice may create it: `ask` (a first
+ * deploy or preview without one) hands off for it, and a caller passing
+ * nothing never creates, refusing a store that was never deployed. Cloudflare's record is the authority: a database
+ * found, made by a run that stopped or by another asking for something else,
+ * is read back and refused unless it matches the choice, and the record is
+ * written from its own value.
+ */
 export async function openOps(
   cf: Cloudflare,
   names: StoreNames,
   now = Date.now,
-): Promise<{ ops: OpsStore; id: string }> {
+  want?: JurisdictionChoice | "ask",
+): Promise<{ ops: OpsStore; id: string; jurisdiction: JurisdictionChoice }> {
   let id = await cf.findD1(names.ops);
   if (!id) {
+    if (want === "ask") throw new NeedsPerson(CHOOSE_JURISDICTION);
+    if (want === undefined)
+      throw new DeployRefused(`no ${names.ops}: this store hasn't been deployed; run kedge deploy first`);
     try {
-      id = await cf.createD1(names.ops);
+      id = await cf.createD1(names.ops, want === "none" ? null : want);
     } catch (e) {
       // Two first deploys contending here both end at the same database (§6.1). Whatever the
       // error said, the name is what decides: found, it's the other deploy's; the meta check
@@ -185,9 +207,17 @@ export async function openOps(
   ).map((r) => String(r.name));
   if (tables.length && !tables.includes("kedge_ops_meta"))
     throw new DeployRefused(`${names.ops} exists and isn't a Kedge operations database: it holds ${tables.join(", ")}`);
+  const actual = await cf.d1Jurisdiction(dbId);
+  if (want !== undefined && want !== "ask" && want !== actual)
+    throw new DeployRefused(
+      `${names.ops} exists in jurisdiction ${actual}, not ${want}: a store's jurisdiction is fixed when its first database is made`,
+    );
   const ops = new OpsStore((sql, params) => cf.queryD1(dbId, sql, params), now);
   await ops.init(names.worker);
-  return { ops, id: dbId };
+  const recorded = await ops.settle("jurisdiction", actual);
+  if (recorded !== actual)
+    throw new DeployRefused(`${names.ops} records jurisdiction ${recorded}, but Cloudflare says ${actual}`);
+  return { ops, id: dbId, jurisdiction: actual };
 }
 
 /**
@@ -259,6 +289,8 @@ export class Deployer {
   readonly names: StoreNames;
   readonly wrangler: WranglerJson;
   private ops!: OpsStore;
+  /** The store's jurisdiction, as `<store>-ops` records it (p0.10 §7). */
+  private jurisdiction: JurisdictionChoice = "none";
   private opId!: string;
   private plan!: Plan;
   private progress: Progress = {};
@@ -317,6 +349,13 @@ export class Deployer {
         "wrangler.jsonc declares routes: kedge deploy manages cron and settings in P0.8, not routes or custom domains; attach a domain in the dashboard until P0.10",
       );
     const vars = { ...(this.wrangler.vars ?? {}), ...(o.vars ?? {}) };
+    // Every Durable Object ID is minted in the store's jurisdiction from this (p0.10 §7): another value
+    // would reach empty objects under the same names, so it's the record's, never the config's.
+    if (vars.KEDGE_JURISDICTION !== undefined && vars.KEDGE_JURISDICTION !== this.jurisdiction)
+      throw new DeployRefused(
+        `KEDGE_JURISDICTION is ${vars.KEDGE_JURISDICTION} in the config or --var, but this store's jurisdiction is ${this.jurisdiction}`,
+      );
+    vars.KEDGE_JURISDICTION = this.jurisdiction;
     const config: WranglerJson = { ...this.wrangler, vars };
     delete config.build;
     const dbs = (config.d1_databases ?? []).map((d) =>
@@ -398,9 +437,13 @@ export class Deployer {
     create: () => Promise<string>,
   ): Promise<string> {
     const rec = await this.ops.resource(kind, name);
+    // A recorded database is checked like a found one: the record is ours, the jurisdiction Cloudflare's (codex code r12).
+    if (rec?.id && kind === "d1") await this.sameJurisdiction(name, rec.id);
     if (rec?.id) return rec.id;
     const found = await find();
     if (found) {
+      // A database found is accepted only in the store's jurisdiction: Cloudflare can't change it after (p0.10 §7).
+      if (kind === "d1") await this.sameJurisdiction(name, found);
       if (rec?.state === "creating" || this.plan.adopt.includes(name)) {
         await this.ops.recordResource(kind, name, found, "ours");
         return found;
@@ -424,6 +467,12 @@ export class Deployer {
     return id;
   }
 
+  private async sameJurisdiction(name: string, id: string): Promise<void> {
+    const j = await this.d.cf.d1Jurisdiction(id);
+    if (j !== this.jurisdiction)
+      throw new DeployRefused(`${name} is in jurisdiction ${j}, and this store's is ${this.jurisdiction}`);
+  }
+
   private async ownWorker(): Promise<boolean> {
     const rec = await this.ops.resource("worker", this.names.worker);
     const exists = await this.d.cf.findWorker(this.names.worker);
@@ -487,7 +536,8 @@ export class Deployer {
       const v = this.d.env?.[s];
       if (v !== undefined && v.length < 32) throw new DeployRefused(`${s} in the environment is under 32 bytes`);
     }
-    const { ops } = await openOps(this.d.cf, this.names, this.now);
+    const { ops, jurisdiction } = await openOps(this.d.cf, this.names, this.now, o.jurisdiction ?? "ask");
+    this.jurisdiction = jurisdiction;
     this.ops = ops;
     const held = await ops.current(SCOPE);
     if (o.resume || o.takeOver) {
@@ -552,8 +602,9 @@ export class Deployer {
    * a resume, with its unanswered calls unknown.
    */
   private async end(e: unknown): Promise<void> {
-    const clean =
-      e instanceof DeployRefused && !this.progress.deploymentId && (await this.ops.unresolved(SCOPE)).length === 0;
+    // A handoff is a refusal too: nothing ran that a resume would need (p0.10 §5).
+    const refused = e instanceof DeployRefused || e instanceof NeedsPerson;
+    const clean = refused && !this.progress.deploymentId && (await this.ops.unresolved(SCOPE)).length === 0;
     if (clean) await this.ops.finish(SCOPE, this.opId, "refused", [this.plan]).catch(() => {});
     else await this.ops.stop(SCOPE, this.opId).catch(() => {});
   }
@@ -717,7 +768,7 @@ export class Deployer {
       "d1",
       this.names.database,
       () => cf.findD1(this.names.database),
-      () => cf.createD1(this.names.database),
+      () => cf.createD1(this.names.database, this.jurisdiction === "none" ? null : this.jurisdiction),
     );
     p.queueId = await this.own(
       "queue",
@@ -781,9 +832,10 @@ export class Deployer {
     if (!p.deploymentId) this.compatible(servingRow);
     if (p.mode === "cutover" && !p.first && !p.deploymentId) {
       const w = this.plan.window;
+      // Downtime on a store that has served customers is the merchant's to schedule (p0.10 §5).
       if (!w || this.now() < w.from || this.now() > w.to)
-        await this.refuse(
-          "a pending core migration is a cutover: on a store that has served traffic it needs --maintenance-window <from>/<to>, with now inside it (§6.3)",
+        throw new NeedsPerson(
+          "this release changes the database in a way the running store can't serve through, so the store shows a maintenance page for a few minutes while it applies: choose when, then run kedge deploy --maintenance-window <from>/<to> during that window",
         );
     }
     await this.step("classified");
@@ -1100,7 +1152,8 @@ export class Deployer {
    */
   async supersede(opId: string): Promise<void> {
     if ((await this.d.checkFast()) !== 0) throw new DeployRefused("kedge check --fast failed");
-    const { ops } = await openOps(this.d.cf, this.names, this.now);
+    const { ops, jurisdiction } = await openOps(this.d.cf, this.names, this.now);
+    this.jurisdiction = jurisdiction;
     this.ops = ops;
     const held = await ops.current(SCOPE);
     if (!held || held.op_id !== opId) throw new DeployRefused(`no operation ${opId} holds this store`);
@@ -1189,7 +1242,8 @@ export class Deployer {
       throw new DeployRefused(
         "--resolve-intent needs --not-executed: it's a statement that the call never took effect",
       );
-    const { ops } = await openOps(this.d.cf, this.names, this.now);
+    const { ops, jurisdiction } = await openOps(this.d.cf, this.names, this.now);
+    this.jurisdiction = jurisdiction;
     const i = await ops.intent(id);
     // Also a migration reconcile closed for its absence: absence permits a retry, only a person can say it never ran.
     const restatable = i?.kind === "migrate" && i.state === "not_executed" && !i.resolved_by?.startsWith("stated by");
@@ -1205,7 +1259,8 @@ export class Deployer {
 
   async recordActive(reason: string): Promise<void> {
     if (!reason) throw new DeployRefused("--record-active needs --reason");
-    const { ops } = await openOps(this.d.cf, this.names, this.now);
+    const { ops, jurisdiction } = await openOps(this.d.cf, this.names, this.now);
+    this.jurisdiction = jurisdiction;
     this.ops = ops;
     // The operation first, then the reads it records (codex code r12).
     this.opId = await ops.start(SCOPE, "record-active", { reason }, "record");
@@ -1250,7 +1305,8 @@ export class Deployer {
   }
 
   async abortCutover(): Promise<void> {
-    const { ops } = await openOps(this.d.cf, this.names, this.now);
+    const { ops, jurisdiction } = await openOps(this.d.cf, this.names, this.now);
+    this.jurisdiction = jurisdiction;
     this.ops = ops;
     const held = await ops.current(SCOPE);
     if (!held) throw new DeployRefused("no operation to abort");
@@ -1303,7 +1359,8 @@ export class Deployer {
   async secret(name: string, value: string | null): Promise<void> {
     if (!/^[A-Z][A-Z0-9_]*$/.test(name))
       throw new DeployRefused("a secret's name is upper-case letters, digits and underscores");
-    const { ops } = await openOps(this.d.cf, this.names, this.now);
+    const { ops, jurisdiction } = await openOps(this.d.cf, this.names, this.now);
+    this.jurisdiction = jurisdiction;
     this.ops = ops;
     const rows = await ops.deployments();
     this.plan = { commit: "secret", adopt: [], vars: {} } as unknown as Plan;
@@ -1410,7 +1467,11 @@ export class Deployer {
   /** A fresh run, or (from `kedge deploy --resume`) the held one, which this checkout's lock must match. */
   async migrateRemote(held?: OperationRow): Promise<void> {
     // A resumed run keeps the executor that claimed it.
-    if (!held) this.ops = (await openOps(this.d.cf, this.names, this.now)).ops;
+    if (!held) {
+      const opened = await openOps(this.d.cf, this.names, this.now);
+      this.ops = opened.ops;
+      this.jurisdiction = opened.jurisdiction;
+    }
     const ops = this.ops;
     const db = await ops.resource("d1", this.names.database);
     if (!db?.id) throw new DeployRefused("no database is recorded for this store: kedge deploy makes it");
@@ -1481,8 +1542,19 @@ export class Deployer {
   }
 
   // ---- §6.1: a store deployed before P0.8 ---------------------------------------------------------------
-  async adoptExisting(release: string, texts: (file: string) => string): Promise<void> {
-    const { ops } = await openOps(this.d.cf, this.names, this.now);
+  async adoptExisting(release: string, texts: (file: string) => string, choice?: JurisdictionChoice): Promise<void> {
+    // A store deployed before P0.10 minted its Durable Objects with no jurisdiction, so its jurisdiction is
+    // none whatever anyone would choose now: another would address new, empty objects under the same
+    // names. Its database says so too, read before anything is made (codex code r12).
+    const live = await this.d.cf.findD1(this.names.database);
+    if (!live) throw new DeployRefused(`no database named ${this.names.database}`);
+    const actual = await this.d.cf.d1Jurisdiction(live);
+    if (actual !== "none" || (choice !== undefined && choice !== "none"))
+      throw new DeployRefused(
+        `a store deployed before P0.10 keeps jurisdiction none (its Durable Objects were made without one); ${this.names.database} is ${actual}${choice ? ` and --jurisdiction says ${choice}` : ""}`,
+      );
+    const { ops, jurisdiction } = await openOps(this.d.cf, this.names, this.now, "none");
+    this.jurisdiction = jurisdiction;
     this.ops = ops;
     // The operation first, then every read it decides on: read before, a deploy finishing in between
     // would be recorded over with what it replaced (codex code r12).

package/src/doctor.ts

@@ -26,6 +26,8 @@ export interface CheckResult {
   message?: string;
   /** Lines under the message: each problem, or each stated exception. */
   details?: string[];
+  /** A failure only a person can fix (p0.10 §5): doctor then exits 3 with this as its `for you:` line. */
+  handoff?: string;
 }
 
 export interface DoctorInput {
@@ -447,6 +449,52 @@ const FAMILY_SECRET: Record<string, string> = {
   totp: "KEDGE_TOTP_KEY_V",
 };
 
+/**
+ * Whether the resolved credentials reach the store's account, claiming only
+ * what a read can show (p0.10 §4). A list succeeding proves the token answers
+ * for this account; it doesn't prove a write (Cloudflare's D1 list takes `D1
+ * Read` or `D1 Write`, creating a database only the latter:
+ * https://developers.cloudflare.com/api/resources/d1/subresources/database/methods/list/),
+ * so the writes are named as unverified, never passed. The token itself is never shown.
+ */
+export async function credentialsChecks(input: {
+  cf: import("./cf").Cloudflare;
+  source: string;
+  base: string;
+}): Promise<CheckResult[]> {
+  const { NeedsPerson } = await import("./cf");
+  const where = `from ${input.source}, sent to ${input.base}, account ${input.cf.account}`;
+  const read = await input.cf.readable();
+  const refused = Object.entries(read).filter(([, status]) => status !== null);
+  const out: CheckResult[] = [];
+  if (refused.length === Object.keys(read).length && refused.every(([, s]) => s === 401 || s === 403))
+    out.push(fail("credentials", `the token doesn't answer for this account (${where})`));
+  else if (refused.length)
+    out.push(
+      fail(
+        "credentials",
+        `the token can't list everything a store uses (${where})`,
+        refused.map(([kind, s]) => (s ? `${kind}: Cloudflare answered ${s}` : `${kind}: no answer`)),
+      ),
+    );
+  else
+    out.push(
+      pass(
+        "credentials",
+        `${where}; lists Workers, D1 and Queues. Writes are unverified until the first deploy: Workers Scripts Edit, D1 Edit, Queues Edit`,
+      ),
+    );
+  try {
+    out.push(pass("workers.dev", `${await input.cf.workersSubdomain()}.workers.dev`));
+  } catch (e) {
+    // Any answer is a report: a token that can't read the subdomain fails this check, never the run (codex code r7).
+    // An account without one is the owner's to choose: a handoff, not a technical failure (codex code r9).
+    if (e instanceof NeedsPerson) out.push({ ...fail("workers.dev", e.handoff), handoff: e.handoff });
+    else out.push(fail("workers.dev", (e as Error).message));
+  }
+  return out;
+}
+
 export interface RemoteDoctorInput {
   cwd: string;
   cf: import("./cf").Cloudflare;
@@ -465,9 +513,19 @@ export async function doctorRemote(input: RemoteDoctorInput): Promise<CheckResul
   const names = storeNames(input.cwd).names;
   const opsId = await input.cf.findD1(names.ops);
   if (!opsId) return [skip("remote", `no ${names.ops}: this store hasn't been deployed with kedge deploy`)];
-  const { ops } = await openOps(input.cf, names);
+  const { ops, jurisdiction } = await openOps(input.cf, names);
   const db = await ops.resource("d1", names.database);
 
+  // jurisdiction: the store's database is where <store>-ops records the store's data lives (p0.10 §7).
+  if (db?.id) {
+    const actual = await input.cf.d1Jurisdiction(db.id);
+    out.push(
+      actual === jurisdiction
+        ? pass("jurisdiction", jurisdiction)
+        : fail("jurisdiction", `${names.database} is in ${actual}, but the store's jurisdiction is ${jurisdiction}`),
+    );
+  }
+
   // applied: D1's record is a prefix of the lock, and what ops recorded of each file's bytes still holds.
   if (db?.id) {
     const problems = appliedProblems(input.lock, await appliedNames(input.cf, db.id), await ops.appliedHashes());
@@ -559,7 +617,7 @@ export async function doctorRemote(input: RemoteDoctorInput): Promise<CheckResul
 
   // previews: old ones, and lost creates whose names are re-checked for 7 days (§3.1).
   const previews = await ops.query(
-    "SELECT identity, worker, database_name, queue_name, state, lost_create, updated_at FROM preview",
+    "SELECT identity, worker, database_name, database_id, queue_name, state, lost_create, updated_at FROM preview",
   );
   const old = previews.filter((p) => p.state !== "destroyed" && now - Number(p.updated_at) > 14 * 86_400_000);
   const orphans: string[] = [];
@@ -578,7 +636,14 @@ export async function doctorRemote(input: RemoteDoctorInput): Promise<CheckResul
     if (await input.cf.findD1(String(p.database_name))) orphans.push(`database ${String(p.database_name)}`);
     if (await input.cf.findQueue(String(p.queue_name))) orphans.push(`queue ${String(p.queue_name)}`);
   }
-  if (orphans.length)
+  // A live preview's database where its store's data lives (p0.10 §7, codex code r13).
+  const misplaced: string[] = [];
+  for (const p of previews.filter((p) => p.state === "bootstrapped" && p.database_id))
+    if ((await input.cf.d1Jurisdiction(String(p.database_id))) !== jurisdiction)
+      misplaced.push(`database ${String(p.database_name)}`);
+  if (misplaced.length)
+    out.push(fail("previews", `a preview's database isn't in the store's jurisdiction, ${jurisdiction}`, misplaced));
+  else if (orphans.length)
     out.push(
       fail("previews", "a destroyed preview's late create left resources: kedge preview destroy --sweep", orphans),
     );