@kedge/cli 0.0.0-stage → 0.9.0

package/src/cf.ts

@@ -0,0 +1,451 @@
+// 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 { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+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) {
+    super(`${what}: no answer from Cloudflare; 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>;
+  createD1(name: string): Promise<string>;
+  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. */
+  workersSubdomain(): Promise<string>;
+  /** 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 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";
+
+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");
+}
+
+export function restCloudflare(
+  env: NodeJS.ProcessEnv,
+  fetchImpl: typeof fetch = fetch,
+  /** The Wrangler entry to run; tests give a stand-in. */
+  wranglerEntry: string = wranglerBin(),
+): Cloudflare {
+  const token = env.CLOUDFLARE_API_TOKEN;
+  const account = env.CLOUDFLARE_ACCOUNT_ID;
+  if (!token || !account) throw new Error("set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID");
+  const base = `${API}/accounts/${account}`;
+
+  async function call<T>(what: string, method: string, path: string, body?: unknown, ok404 = false): Promise<T | null> {
+    let res: Response;
+    try {
+      res = await fetchImpl(`${base}${path}`, {
+        method,
+        headers: {
+          authorization: `Bearer ${token}`,
+          ...(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).
+    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: token as string,
+          CLOUDFLARE_ACCOUNT_ID: account as string,
+          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) {
+      const r = await call<{ uuid: string }>(`create D1 ${name}`, "POST", "/d1/database", { name });
+      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() {
+      const r = await get<{ subdomain: string }>("workers.dev subdomain", "/workers/subdomain");
+      if (!r?.subdomain) throw new CloudflareError("no workers.dev subdomain", 200, []);
+      return r.subdomain;
+    },
+    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;
+    },
+  };
+}

package/src/check.ts

@@ -0,0 +1,44 @@
+// `kedge check` (docs/proposals/p0.8-cli-agent-kit.md §4.4): the guard an agent
+// runs before it stops, in order, stopping at the first failure. `--fast`
+// (the Stop hook's) needs no Cloudflare and finishes in seconds; the full one
+// adds the store's tests in workerd, with the invariant suite after each.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export interface CheckInput {
+  cwd: string;
+  fast: boolean;
+  generate: (cwd: string) => Promise<number>;
+  doctor: (cwd: string) => Promise<number>;
+  /** Runs a tool from the store's node_modules/.bin; tests replace it. */
+  run?: (bin: string, args: string[], cwd: string) => number;
+}
+
+const runBin = (bin: string, args: string[], cwd: string): number => {
+  const path = join(cwd, "node_modules", ".bin", bin);
+  if (!existsSync(path)) {
+    console.error(`${bin} isn't installed in this store: run pnpm install`);
+    return 1;
+  }
+  return spawnSync(path, args, { cwd, stdio: "inherit" }).status ?? 1;
+};
+
+export async function check(input: CheckInput): Promise<number> {
+  const run = input.run ?? runBin;
+  const steps: [string, () => Promise<number> | number][] = [
+    ["typecheck", () => run("tsc", ["--noEmit", "-p", "."], input.cwd)],
+    ["kedge generate --check", () => input.generate(input.cwd)],
+    ["kedge doctor", () => input.doctor(input.cwd)],
+    ...(input.fast ? [] : ([["tests", () => run("vitest", ["run"], input.cwd)]] as [string, () => number][])),
+  ];
+  for (const [name, step] of steps) {
+    const code = await step();
+    if (code !== 0) {
+      console.error(`\nkedge check: ${name} failed. Fix it and run kedge check${input.fast ? " --fast" : ""} again.`);
+      return code;
+    }
+  }
+  console.log(`kedge check${input.fast ? " --fast" : ""} passed`);
+  return 0;
+}