@kedge/cli 0.0.0-stage → 0.10.0

package/src/cf.ts

@@ -0,0 +1,729 @@
+// Every command that touches Cloudflare goes through here
+// (docs/proposals/p0.8-cli-agent-kit.md §3): REST calls of one attempt each, so
+// a lost response is an unknown outcome the caller records rather than a
+// retry that might land late; and Wrangler, for what only it does (uploading a
+// bundle, applying migrations with its own bookkeeping), run from a trusted
+// directory with a sanitized environment (§5.3). A failed lookup throws:
+// only a confirmed "not found" counts as absent, the rule every spike's
+// cleanup learned.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseEnv } from "node:util";
+import { jsoncToJson } from "./worker-config";
+
+export type Row = Record<string, unknown>;
+
+export interface Deployment {
+  id: string;
+  versions: { version_id: string; percentage: number }[];
+  message: string | null;
+}
+
+export interface WorkerSettings {
+  logpush: boolean;
+  invocationLogs: boolean | null;
+}
+
+/** A call whose answer never came: the caller records it as an unknown outcome (§3.1). */
+export class UnknownOutcome extends Error {
+  constructor(what: string, from = "Cloudflare") {
+    super(`${what}: no answer from ${from}; its outcome is unknown`);
+    this.name = "UnknownOutcome";
+  }
+}
+
+/**
+ * A Wrangler process that exited non-zero. It may have reached Cloudflare before failing, or
+ * lost the answer, so its outcome is unknown, never "failed": the intent stays for evidence
+ * (an activation's tag in the deployment list, d1_migrations) or a person (codex code r3).
+ */
+export class WranglerFailed extends UnknownOutcome {
+  constructor(
+    what: string,
+    readonly tail: string,
+    readonly outputs: Row[],
+  ) {
+    super(what);
+    this.message = `${what} failed, and may have reached Cloudflare first:\n${tail}`;
+    this.name = "WranglerFailed";
+  }
+}
+
+export class CloudflareError extends Error {
+  constructor(
+    what: string,
+    readonly status: number,
+    readonly codes: number[],
+    /** Cloudflare's own words about its control plane, for the person reading the refusal; never decided on. */
+    readonly detail: string[] = [],
+  ) {
+    super(
+      `${what}: Cloudflare answered ${status}${codes.length ? ` (${codes.join(", ")})` : ""}${detail.length ? `: ${detail.join("; ").slice(0, 300)}` : ""}`,
+    );
+    this.name = "CloudflareError";
+  }
+}
+
+/** What the CLI needs of Cloudflare, by meaning. Tests replace it with a fake that can lose answers. */
+export interface Cloudflare {
+  readonly account: string;
+  findD1(name: string): Promise<string | null>;
+  /** Creates a database in `jurisdiction` (none when null): set only at creation, never after (p0.10 §7). */
+  createD1(name: string, jurisdiction?: Jurisdiction | null): Promise<string>;
+  /** The database's jurisdiction, as Cloudflare records it; `none` when it has none. */
+  d1Jurisdiction(id: string): Promise<JurisdictionChoice>;
+  deleteD1(id: string): Promise<void>;
+  queryD1(id: string, sql: string, params?: readonly unknown[]): Promise<Row[]>;
+  bookmark(id: string): Promise<string>;
+  findQueue(name: string): Promise<string | null>;
+  createQueue(name: string): Promise<string>;
+  deleteQueue(id: string): Promise<void>;
+  consumers(queueId: string): Promise<{ id: string; script: string }[]>;
+  deleteConsumer(queueId: string, consumerId: string): Promise<void>;
+  findWorker(name: string): Promise<boolean>;
+  deleteWorker(name: string): Promise<void>;
+  /** Newest first. */
+  versions(name: string): Promise<{ id: string; created: string; message: string | null }[]>;
+  /** Newest first; the first is what serves. */
+  deployments(name: string): Promise<Deployment[]>;
+  /** One attempt: POST a deployment of one version at 100%, its message the intent's tag. */
+  activate(name: string, versionId: string, message: string): Promise<void>;
+  schedules(name: string): Promise<string[]>;
+  putSchedules(name: string, crons: readonly string[]): Promise<void>;
+  settings(name: string): Promise<WorkerSettings>;
+  patchSettings(name: string, s: WorkerSettings): Promise<void>;
+  secretNames(name: string): Promise<string[]>;
+  /** `wrangler versions upload --no-bundle` of a staged bundle; returns its version id. */
+  uploadVersion(input: UploadInput): Promise<string>;
+  /** `wrangler deploy --no-bundle`: only where Cloudflare requires it, a class change (§3.1). */
+  deployWithClasses(input: UploadInput): Promise<string>;
+  /** `wrangler d1 migrations apply --remote` from a staged directory. */
+  applyMigrations(input: { config: string; database: string }): Promise<void>;
+  /** One SQL file as one transaction (`wrangler d1 execute --file`): the CLI's audited batches (p0.5 §3.4). */
+  executeD1File(input: { database: string; databaseId: string; sql: string }): Promise<void>;
+  /** The account's workers.dev subdomain; none is the person's choice to make (`NeedsPerson`). */
+  workersSubdomain(): Promise<string>;
+  /** One list of each resource type a store uses: null where it answered, else the refusing status (0: no answer). */
+  readable(): Promise<Record<ResourceKind, number | null>>;
+  /** The account's Logpush jobs, or null when the token can't read them. */
+  logpushJobs(): Promise<{ dataset: string; enabled: boolean; fields: string[] | null }[] | null>;
+  /** `wrangler versions secret put|delete`: a new version with one secret changed, not deployed. */
+  versionSecret(worker: string, name: string, value: string | null, message: string): Promise<string>;
+}
+
+export type ResourceKind = "Workers" | "D1" | "Queues";
+
+/**
+ * Where a store's data lives (p0.10 §7): D1 and Durable Object storage
+ * restricted to one jurisdiction, or `none`, which is a choice too. The values
+ * are Cloudflare's for both
+ * (https://developers.cloudflare.com/d1/configuration/data-location/,
+ * https://developers.cloudflare.com/durable-objects/reference/data-location/).
+ */
+export const JURISDICTIONS = ["eu", "us", "fedramp"] as const;
+export type Jurisdiction = (typeof JURISDICTIONS)[number];
+export type JurisdictionChoice = Jurisdiction | "none";
+
+export const isJurisdictionChoice = (v: string): v is JurisdictionChoice =>
+  v === "none" || (JURISDICTIONS as readonly string[]).includes(v);
+
+/** What the person is asked before a store's first resource exists. */
+export const CHOOSE_JURISDICTION =
+  "choose where this store's data lives: eu, us, fedramp or none (it can't change later), then run this again with --jurisdiction <choice>";
+
+export interface UploadInput {
+  /** A generated Wrangler config, every path in it absolute. */
+  config: string;
+  message: string;
+  secretsFile?: string;
+}
+
+const API = "https://api.cloudflare.com/client/v4";
+
+/**
+ * What only a person can do next (p0.10 §5): the command stops with exit 3 and
+ * this one sentence, which an agent passes on as written.
+ */
+export class NeedsPerson extends Error {
+  constructor(readonly handoff: string) {
+    super(handoff);
+  }
+}
+
+/**
+ * Where every Cloudflare call goes: `CLOUDFLARE_API_BASE_URL` when set, as
+ * Wrangler's own calls do, else Cloudflare (p0.10 §4). salve's broker sets it
+ * with a token valid only there, so sending that token to Cloudflare itself
+ * would leak it and fail.
+ */
+export function cloudflareBase(env: NodeJS.ProcessEnv): string {
+  const raw = env.CLOUDFLARE_API_BASE_URL?.trim();
+  if (!raw) return API;
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    throw new Error(`CLOUDFLARE_API_BASE_URL isn't a URL: ${raw}`);
+  }
+  const local = u.hostname === "localhost" || u.hostname === "127.0.0.1";
+  if (u.protocol !== "https:" && !(local && u.protocol === "http:"))
+    throw new Error(`CLOUDFLARE_API_BASE_URL must be https: ${raw}`);
+  return u.href.replace(/\/+$/, "");
+}
+
+/**
+ * An account without a workers.dev subdomain has nowhere to serve a store, and
+ * Kedge never registers one (p0.10 §4): it names every Worker on the account,
+ * so it's the account owner's choice, made where Wrangler sends people to make it
+ * (wrangler-dist/cli.js:165132, 4.152.0).
+ */
+export function noSubdomain(account: string): NeedsPerson {
+  return new NeedsPerson(
+    `this Cloudflare account has no workers.dev subdomain yet: choose one at https://dash.cloudflare.com/${account}/workers/subdomain, then run this again`,
+  );
+}
+
+/**
+ * What every command that can create a store resource checks before its first
+ * Cloudflare write (p0.10 §4), so a missing subdomain stops it with nothing
+ * made rather than after the database and Worker exist. Credentials have
+ * resolved by the time a `Cloudflare` exists. A store with no `<store>-ops`
+ * yet needs its jurisdiction chosen (§7); one that has it must not be given
+ * another. `ops` is that database's name; `preview apply` from a plan names
+ * its store only once the plan is read, and `openOps` checks the same there.
+ */
+export async function preflight(cf: Cloudflare, ops?: string, choice?: string): Promise<void> {
+  if (choice !== undefined && !isJurisdictionChoice(choice))
+    throw new NeedsPerson(
+      `--jurisdiction takes ${JURISDICTIONS.join(", ")} or none, not "${choice}": ${CHOOSE_JURISDICTION}`,
+    );
+  await cf.workersSubdomain();
+  if (ops === undefined) return;
+  const id = await cf.findD1(ops);
+  if (!id && choice === undefined) throw new NeedsPerson(CHOOSE_JURISDICTION);
+  if (id && choice !== undefined) {
+    const actual = await cf.d1Jurisdiction(id);
+    if (actual !== choice)
+      throw new NeedsPerson(
+        `this store's data lives in jurisdiction ${actual}, fixed when it was first deployed: run this again without --jurisdiction, or with --jurisdiction ${actual}`,
+      );
+  }
+}
+
+/** The resolved credentials: where they came from, the account, and a token fresh enough to send. */
+export interface CloudflareAuth {
+  source: "environment" | ".env.local" | "wrangler login";
+  account: string;
+  token: () => string;
+}
+
+/**
+ * The three sources, in order (p0.10 §4): the environment (salve, CI), the
+ * store's `.env.local`, then a `wrangler login` session read through Wrangler's
+ * own `wrangler auth token --json`, never from its files. A login's token is
+ * asked for again before every call: Wrangler refreshes an OAuth token only once
+ * it has expired, and says nothing of how long it has left, so a cached one
+ * could lapse in the middle of a cutover (codex code r1).
+ */
+export async function resolveCloudflare(
+  env: NodeJS.ProcessEnv,
+  cwd: string,
+  fetchImpl: typeof fetch = fetch,
+  wranglerEntry: string = wranglerBin(),
+): Promise<CloudflareAuth> {
+  if (env.CLOUDFLARE_API_TOKEN) {
+    const token = env.CLOUDFLARE_API_TOKEN;
+    if (!env.CLOUDFLARE_ACCOUNT_ID) throw new NeedsPerson("set CLOUDFLARE_ACCOUNT_ID beside CLOUDFLARE_API_TOKEN");
+    sameAccount(env.CLOUDFLARE_ACCOUNT_ID, configIn(cwd));
+    return { source: "environment", account: env.CLOUDFLARE_ACCOUNT_ID, token: () => token };
+  }
+  const file = join(cwd, ".env.local");
+  const local = existsSync(file) ? parseEnv(readFileSync(file, "utf8")) : {};
+  if (local.CLOUDFLARE_API_TOKEN) {
+    const token = local.CLOUDFLARE_API_TOKEN;
+    const account = env.CLOUDFLARE_ACCOUNT_ID ?? local.CLOUDFLARE_ACCOUNT_ID;
+    if (!account) throw new NeedsPerson("add CLOUDFLARE_ACCOUNT_ID to .env.local beside CLOUDFLARE_API_TOKEN");
+    sameAccount(account, configIn(cwd));
+    return { source: ".env.local", account, token: () => token };
+  }
+  const token = () => {
+    const t = wranglerLoginToken(env, wranglerEntry);
+    if (!t)
+      throw new NeedsPerson(
+        "add CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID to .env.local, or run `wrangler login`, then run this again",
+      );
+    return t;
+  };
+  // Asked once here too, so a missing login is the handoff now, never a failed call later (codex code r1).
+  const first = token();
+  const account =
+    env.CLOUDFLARE_ACCOUNT_ID ?? local.CLOUDFLARE_ACCOUNT_ID ?? (await onlyAccount(env, first, fetchImpl));
+  sameAccount(account, configIn(cwd));
+  return { source: "wrangler login", account, token };
+}
+
+/** The store's Wrangler config file, if it has one. */
+function configIn(cwd: string): string | null {
+  for (const f of ["wrangler.jsonc", "wrangler.json"]) if (existsSync(join(cwd, f))) return join(cwd, f);
+  return null;
+}
+
+/**
+ * A Wrangler config's `account_id` wins over `CLOUDFLARE_ACCOUNT_ID` in every
+ * Wrangler run (`getActiveAccountId`, wrangler-dist/cli.js:133664, 4.152.0),
+ * so a config naming another account than the credentials resolved would send
+ * Wrangler's writes there while Kedge's own calls go here (codex code r8).
+ * Which account is the store's is the person's to say.
+ */
+export function sameAccount(account: string, configFile: string | null): void {
+  if (!configFile || !existsSync(configFile)) return;
+  const named = (JSON.parse(jsoncToJson(readFileSync(configFile, "utf8"))) as { account_id?: unknown }).account_id;
+  if (typeof named === "string" && named !== "" && named !== account)
+    throw new NeedsPerson(
+      `${basename(configFile)} names Cloudflare account ${named}, but the credentials are for ${account}: remove its account_id, or use credentials for ${named}, then run this again`,
+    );
+}
+
+const LEGACY_CREDENTIALS = new Set([
+  "CLOUDFLARE_API_TOKEN",
+  "CLOUDFLARE_API_KEY",
+  "CLOUDFLARE_EMAIL",
+  "CF_API_TOKEN",
+  "CF_API_KEY",
+  "CF_EMAIL",
+]);
+
+/** The login's token from Wrangler itself, in the person's own environment; null when there's none. */
+function wranglerLoginToken(env: NodeJS.ProcessEnv, wranglerEntry: string): string | null {
+  // A directory of our own, so Wrangler reads no store's `.env`; HOME stays the person's, where the login is.
+  const dir = mkdtempSync(join(tmpdir(), "kedge-auth-"));
+  try {
+    // Every credential Wrangler would take from the environment goes, its legacy aliases too, so
+    // what answers is the login and nothing else (codex code r5).
+    const rest = Object.fromEntries(Object.entries(env).filter(([k]) => !LEGACY_CREDENTIALS.has(k)));
+    const r = spawnSync(process.execPath, [wranglerEntry, "auth", "token", "--json"], {
+      cwd: dir,
+      encoding: "utf8",
+      env: { ...rest, WRANGLER_SEND_METRICS: "false" },
+    });
+    if (r.status !== 0) return null;
+    const j = JSON.parse(r.stdout) as { type?: unknown; token?: unknown };
+    return j.type === "oauth" && typeof j.token === "string" && j.token ? j.token : null;
+  } catch {
+    return null;
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** The one account a token can reach; more than one is the person's choice. */
+async function onlyAccount(env: NodeJS.ProcessEnv, token: string, fetchImpl: typeof fetch): Promise<string> {
+  const res = await fetchImpl(`${cloudflareBase(env)}/memberships?per_page=50`, {
+    headers: { authorization: `Bearer ${token}` },
+  });
+  const data = (await res.json().catch(() => ({}))) as { result?: { account?: { id?: string; name?: string } }[] };
+  const accounts = (data.result ?? []).map((m) => m.account).filter((a): a is { id: string; name?: string } => !!a?.id);
+  if (accounts.length === 1) return (accounts[0] as { id: string }).id;
+  if (accounts.length === 0) throw new CloudflareError("the login's accounts", res.status, []);
+  throw new NeedsPerson(
+    `this login reaches ${accounts.length} Cloudflare accounts: set CLOUDFLARE_ACCOUNT_ID in .env.local to one of ${accounts.map((a) => `${a.id} (${a.name ?? "?"})`).join(", ")}`,
+  );
+}
+
+type Envelope<T> = {
+  success?: boolean;
+  result?: T;
+  errors?: { code: number; message?: string }[];
+  result_info?: { total_pages?: number };
+};
+
+/** The installed Wrangler's entry: the CLI's own dependency, never the store's code. */
+export function wranglerBin(): string {
+  const require = createRequire(fileURLToPath(import.meta.url));
+  return join(dirname(require.resolve("wrangler/package.json")), "bin", "wrangler.js");
+}
+
+/** A store's Cloudflare, from whichever source resolves (p0.10 §4). */
+export async function cloudflareFor(
+  env: NodeJS.ProcessEnv,
+  cwd: string,
+  fetchImpl: typeof fetch = fetch,
+  wranglerEntry: string = wranglerBin(),
+): Promise<Cloudflare> {
+  return restCloudflare(env, fetchImpl, wranglerEntry, await resolveCloudflare(env, cwd, fetchImpl, wranglerEntry));
+}
+
+export function restCloudflare(
+  env: NodeJS.ProcessEnv,
+  fetchImpl: typeof fetch = fetch,
+  /** The Wrangler entry to run; tests give a stand-in. */
+  wranglerEntry: string = wranglerBin(),
+  /** Resolved credentials; without them, the environment's two variables. */
+  auth?: CloudflareAuth,
+): Cloudflare {
+  const resolved =
+    auth ??
+    (() => {
+      const t = env.CLOUDFLARE_API_TOKEN;
+      const a = env.CLOUDFLARE_ACCOUNT_ID;
+      if (!t || !a) throw new Error("set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID");
+      return { source: "environment" as const, account: a, token: () => t };
+    })();
+  const account = resolved.account;
+  const apiBase = cloudflareBase(env);
+  const base = `${apiBase}/accounts/${account}`;
+
+  async function call<T>(what: string, method: string, path: string, body?: unknown, ok404 = false): Promise<T | null> {
+    // Before the network's catch: a credential that's gone is a handoff, not an unknown outcome.
+    const bearer = resolved.token();
+    let res: Response;
+    try {
+      res = await fetchImpl(`${base}${path}`, {
+        method,
+        headers: {
+          authorization: `Bearer ${bearer}`,
+          ...(body === undefined ? {} : { "content-type": "application/json" }),
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      });
+    } catch {
+      throw new UnknownOutcome(what);
+    }
+    if (ok404 && res.status === 404) return null;
+    let data: Envelope<T>;
+    try {
+      data = (await res.json()) as Envelope<T>;
+    } catch {
+      // A body we can't read isn't an answer: a lookup reading it as "absent" would forget a live resource.
+      if (method === "GET") throw new CloudflareError(what, res.status, []);
+      throw new UnknownOutcome(what);
+    }
+    if (!res.ok || data.success !== true) {
+      if (res.status >= 500 && method !== "GET") throw new UnknownOutcome(what);
+      throw new CloudflareError(
+        what,
+        res.status,
+        (data.errors ?? []).map((e) => e.code),
+        (data.errors ?? []).map((e) => e.message ?? "").filter(Boolean),
+      );
+    }
+    return (data.result ?? null) as T;
+  }
+  const get = <T>(what: string, path: string, ok404 = false) => call<T>(what, "GET", path, undefined, ok404);
+
+  async function all<T>(what: string, path: string): Promise<T[]> {
+    const out: T[] = [];
+    for (let page = 1; page <= 50; page++) {
+      const sep = path.includes("?") ? "&" : "?";
+      const r = await get<T[]>(what, `${path}${sep}page=${page}&per_page=100`);
+      if (!Array.isArray(r)) throw new CloudflareError(`${what}: no list`, 200, []);
+      out.push(...r);
+      if (r.length < 100) return out;
+    }
+    throw new CloudflareError(`${what}: more than 50 pages`, 200, []);
+  }
+
+  function wrangler(
+    args: string[],
+    extra: Record<string, string> = {},
+    input?: string,
+  ): { out: string; outputs: Row[] } {
+    // A fresh directory of our own: Wrangler loads `.env` from its working
+    // directory and honours CLOUDFLARE_API_BASE_URL, so neither the store's
+    // files nor the caller's environment may reach it (§5.3). The base URL
+    // Kedge resolved is passed on explicitly: salve's broker token is valid
+    // only there (p0.10 §4).
+    const dir = mkdtempSync(join(tmpdir(), "kedge-wrangler-"));
+    const envFile = join(dir, "empty.env");
+    const output = join(dir, "output.ndjson");
+    writeFileSync(envFile, "");
+    try {
+      const r = spawnSync(process.execPath, [wranglerEntry, ...args, "--env-file", envFile], {
+        cwd: dir,
+        encoding: "utf8",
+        ...(input === undefined ? {} : { input }),
+        env: {
+          PATH: env.PATH ?? "",
+          HOME: dir,
+          CLOUDFLARE_API_TOKEN: resolved.token(),
+          CLOUDFLARE_ACCOUNT_ID: account,
+          ...(apiBase === API ? {} : { CLOUDFLARE_API_BASE_URL: apiBase }),
+          WRANGLER_SEND_METRICS: "false",
+          WRANGLER_OUTPUT_FILE_PATH: output,
+          CI: "1",
+          ...extra,
+        },
+      });
+      const outputs = existsSync(output)
+        ? readFileSync(output, "utf8")
+            .split("\n")
+            .filter(Boolean)
+            .map((l) => JSON.parse(l) as Row)
+        : [];
+      if (r.status !== 0) {
+        const tail = `${r.stdout}\n${r.stderr}`.trim().split("\n").slice(-15).join("\n");
+        throw new WranglerFailed(`wrangler ${args[0]} ${args[1] ?? ""}`.trim(), tail, outputs);
+      }
+      return { out: r.stdout, outputs };
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+  const versionIdOf = (outputs: Row[], type: string) => {
+    const v = outputs.find((o) => o.type === type)?.version_id;
+    if (typeof v !== "string") throw new UnknownOutcome(`wrangler ${type} gave no version id`);
+    return v;
+  };
+
+  return {
+    account,
+    async findD1(name) {
+      const r = await all<{ uuid: string; name: string }>(
+        "list D1 databases",
+        `/d1/database?name=${encodeURIComponent(name)}`,
+      );
+      return r.find((d) => d.name === name)?.uuid ?? null;
+    },
+    async createD1(name, jurisdiction) {
+      // `jurisdiction` in the create body, the only time it can be set (D1 data location, cited above).
+      const r = await call<{ uuid: string }>(`create D1 ${name}`, "POST", "/d1/database", {
+        name,
+        ...(jurisdiction ? { jurisdiction } : {}),
+      });
+      if (!r?.uuid) throw new UnknownOutcome(`create D1 ${name}`);
+      return r.uuid;
+    },
+    async deleteD1(id) {
+      await call(`delete D1 ${id}`, "DELETE", `/d1/database/${id}`, undefined, true);
+    },
+    async queryD1(id, sql, params = []) {
+      const r = await call<{ results?: Row[] }[]>(`query D1 ${id}`, "POST", `/d1/database/${id}/query`, {
+        sql,
+        params,
+      });
+      return r?.[0]?.results ?? [];
+    },
+    async bookmark(id) {
+      const r = await get<{ bookmark: string }>(`bookmark of ${id}`, `/d1/database/${id}/time_travel/bookmark`);
+      if (!r?.bookmark) throw new CloudflareError(`bookmark of ${id}`, 200, []);
+      return r.bookmark;
+    },
+    async findQueue(name) {
+      const r = await all<{ queue_id: string; queue_name: string }>("list queues", "/queues");
+      return r.find((q) => q.queue_name === name)?.queue_id ?? null;
+    },
+    async createQueue(name) {
+      const r = await call<{ queue_id: string }>(`create queue ${name}`, "POST", "/queues", { queue_name: name });
+      if (!r?.queue_id) throw new UnknownOutcome(`create queue ${name}`);
+      return r.queue_id;
+    },
+    async deleteQueue(id) {
+      await call(`delete queue ${id}`, "DELETE", `/queues/${id}`, undefined, true);
+    },
+    async consumers(queueId) {
+      const r = await get<{ consumer_id: string; script?: string; service?: string }[]>(
+        `consumers of ${queueId}`,
+        `/queues/${queueId}/consumers`,
+      );
+      return (r ?? []).map((c) => ({ id: c.consumer_id, script: c.script ?? c.service ?? "" }));
+    },
+    async deleteConsumer(queueId, consumerId) {
+      await call(
+        `detach consumer ${consumerId}`,
+        "DELETE",
+        `/queues/${queueId}/consumers/${consumerId}`,
+        undefined,
+        true,
+      );
+    },
+    async findWorker(name) {
+      return (await get(`Worker ${name}`, `/workers/scripts/${encodeURIComponent(name)}/settings`, true)) !== null;
+    },
+    async deleteWorker(name) {
+      await call(`delete Worker ${name}`, "DELETE", `/workers/scripts/${encodeURIComponent(name)}`, undefined, true);
+    },
+    async versions(name) {
+      const r = await get<{
+        items?: { id: string; metadata?: { created_on?: string }; annotations?: Record<string, string> }[];
+      }>(`versions of ${name}`, `/workers/scripts/${encodeURIComponent(name)}/versions?per_page=100`);
+      // A version's message is its `workers/message` annotation, as Wrangler reads it (4.152.0, cli.js:168553).
+      return (r?.items ?? []).map((v) => ({
+        id: v.id,
+        created: v.metadata?.created_on ?? "",
+        message: v.annotations?.["workers/message"] ?? null,
+      }));
+    },
+    async deployments(name) {
+      const r = await get<{
+        deployments?: { id: string; versions: Deployment["versions"]; annotations?: Record<string, string> }[];
+      }>(`deployments of ${name}`, `/workers/scripts/${encodeURIComponent(name)}/deployments`);
+      return (r?.deployments ?? []).map((d) => ({
+        id: d.id,
+        versions: d.versions,
+        message: d.annotations?.["workers/message"] ?? null,
+      }));
+    },
+    async activate(name, versionId, message) {
+      await call(
+        `activate ${versionId} on ${name}`,
+        "POST",
+        `/workers/scripts/${encodeURIComponent(name)}/deployments`,
+        {
+          strategy: "percentage",
+          versions: [{ version_id: versionId, percentage: 100 }],
+          // Only `workers/message`: Cloudflare refuses `workers/triggered_by` here (10210, research/26).
+          annotations: { "workers/message": message },
+        },
+      );
+    },
+    async schedules(name) {
+      const r = await get<{ schedules?: { cron: string }[] }>(
+        `schedules of ${name}`,
+        `/workers/scripts/${encodeURIComponent(name)}/schedules`,
+      );
+      return (r?.schedules ?? []).map((s) => s.cron).sort();
+    },
+    async putSchedules(name, crons) {
+      await call(
+        `schedules of ${name}`,
+        "PUT",
+        `/workers/scripts/${encodeURIComponent(name)}/schedules`,
+        crons.map((cron) => ({ cron })),
+      );
+    },
+    async settings(name) {
+      const r = await get<{ logpush?: boolean; observability?: { logs?: { invocation_logs?: boolean } } }>(
+        `settings of ${name}`,
+        `/workers/scripts/${encodeURIComponent(name)}/script-settings`,
+      );
+      return { logpush: r?.logpush ?? false, invocationLogs: r?.observability?.logs?.invocation_logs ?? null };
+    },
+    async patchSettings(name, s) {
+      await call(`settings of ${name}`, "PATCH", `/workers/scripts/${encodeURIComponent(name)}/script-settings`, {
+        logpush: s.logpush,
+        observability: { enabled: true, logs: { enabled: true, invocation_logs: s.invocationLogs ?? false } },
+      });
+    },
+    async secretNames(name) {
+      const r = await get<{ name: string }[]>(
+        `secrets of ${name}`,
+        `/workers/scripts/${encodeURIComponent(name)}/secrets`,
+        true,
+      );
+      return (r ?? []).map((s) => s.name).sort();
+    },
+    async uploadVersion(input) {
+      const { outputs } = wrangler([
+        "versions",
+        "upload",
+        "--no-bundle",
+        "-c",
+        input.config,
+        "--message",
+        input.message,
+        ...(input.secretsFile ? ["--secrets-file", input.secretsFile] : []),
+      ]);
+      return versionIdOf(outputs, "version-upload");
+    },
+    async deployWithClasses(input) {
+      const { outputs } = wrangler([
+        "deploy",
+        "--no-bundle",
+        "-c",
+        input.config,
+        "--message",
+        input.message,
+        ...(input.secretsFile ? ["--secrets-file", input.secretsFile] : []),
+      ]);
+      return versionIdOf(outputs, "deploy");
+    },
+    async applyMigrations(input) {
+      wrangler(["d1", "migrations", "apply", input.database, "--remote", "-c", input.config], {});
+    },
+    async executeD1File(input) {
+      const dir = mkdtempSync(join(tmpdir(), "kedge-sql-"));
+      try {
+        const file = join(dir, "batch.sql");
+        const config = join(dir, "wrangler.json");
+        writeFileSync(file, input.sql, { mode: 0o600 });
+        writeFileSync(
+          config,
+          JSON.stringify({
+            name: "kedge-cli",
+            d1_databases: [{ binding: "DB", database_name: input.database, database_id: input.databaseId }],
+          }),
+        );
+        wrangler(["d1", "execute", "DB", "--remote", "--file", file, "--yes", "-c", config]);
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    },
+    async workersSubdomain() {
+      let r: { subdomain: string } | null;
+      try {
+        r = await get<{ subdomain: string }>("workers.dev subdomain", "/workers/subdomain");
+      } catch (e) {
+        // 10007 is Cloudflare's "no subdomain", as Wrangler reads it (wrangler-dist/cli.js:164937, 4.152.0).
+        if (e instanceof CloudflareError && e.codes.includes(10007)) throw noSubdomain(account);
+        throw e;
+      }
+      if (!r?.subdomain) throw noSubdomain(account);
+      return r.subdomain;
+    },
+    async d1Jurisdiction(id) {
+      // The database's own record (https://developers.cloudflare.com/api/resources/d1/subresources/database/methods/get/);
+      // absent is none.
+      const r = await get<{ jurisdiction?: string | null }>(`D1 ${id}`, `/d1/database/${id}`);
+      const j = r?.jurisdiction ?? "none";
+      if (!isJurisdictionChoice(j)) throw new CloudflareError(`D1 ${id} answered jurisdiction "${j}"`, 200, []);
+      return j;
+    },
+    async readable() {
+      const out: Record<ResourceKind, number | null> = { Workers: null, D1: null, Queues: null };
+      const paths: [ResourceKind, string][] = [
+        ["Workers", "/workers/scripts"],
+        ["D1", "/d1/database"],
+        ["Queues", "/queues"],
+      ];
+      for (const [kind, path] of paths) {
+        try {
+          await get(`list ${kind}`, path);
+        } catch (e) {
+          if (e instanceof CloudflareError) out[kind] = e.status;
+          else if (e instanceof UnknownOutcome) out[kind] = 0;
+          else throw e;
+        }
+      }
+      return out;
+    },
+    async logpushJobs() {
+      try {
+        const r = await get<{ dataset: string; enabled: boolean; output_options?: { field_names?: string[] } }[]>(
+          "Logpush jobs",
+          "/logpush/jobs",
+        );
+        return (r ?? []).map((j) => ({
+          dataset: j.dataset,
+          enabled: j.enabled,
+          fields: j.output_options?.field_names ?? null,
+        }));
+      } catch (e) {
+        if (e instanceof CloudflareError && (e.status === 403 || e.status === 401)) return null;
+        throw e;
+      }
+    },
+    async versionSecret(worker, name, value, message) {
+      const { out } =
+        value === null
+          ? wrangler(["versions", "secret", "delete", name, "--name", worker, "--message", message])
+          : wrangler(["versions", "secret", "put", name, "--name", worker, "--message", message], {}, value);
+      const id = /Created version ([0-9a-f-]{36})/.exec(out)?.[1];
+      if (!id) throw new UnknownOutcome(`versions secret on ${worker} gave no version id`);
+      return id;
+    },
+  };
+}