@kedge/cli 0.9.0 → 0.10.0

package/src/smoke.ts

@@ -0,0 +1,218 @@
+// `kedge smoke` (docs/proposals/p0.10-agent-path.md §6.3): a scripted checkout
+// through the public API with the storefront's key, then Phase 0's staff
+// placement, standing in for payment (D-035), with a CLI session holding
+// `order:place`. It never places a second order by accident: each run has a
+// name the caller keeps, recorded in `.kedge/state.db` before its cart exists,
+// and three moments are each committed before the request they guard: the
+// completion's exact body (a rerun sends it unchanged, never a fresh price),
+// the order's id and token together, and the number once it's read back. A
+// rerun resumes; a finished run answers its order again, writing nothing.
+import type { DatabaseSync } from "node:sqlite";
+import { NeedsPerson } from "./cf";
+import { type SessionDeps, withCliSession } from "./cli-session";
+import { DeployRefused } from "./deploy";
+import { ENV, identityOf, keysSaveHeld } from "./keys-save";
+import { stateDb, withStoreLock } from "./local-state";
+import { storeRequest } from "./store-api";
+import type { StoreTarget } from "./target";
+
+/** The product `kedge seed --sample apparel` makes first, and the currency it's priced in. */
+export const SMOKE_PRODUCT = { handle: "linen-shirt", currency: "USD" } as const;
+
+interface Run {
+  name: string;
+  store: string;
+  storefront_id: string;
+  cart_id: string | null;
+  cart_token: string | null;
+  completion: string | null;
+  order_id: string | null;
+  order_token: string | null;
+  number: string | null;
+  abandoned: string | null;
+}
+
+export interface SmokeDeps {
+  cwd: string;
+  fetch: typeof fetch;
+  session: SessionDeps;
+  log: (s: string) => void;
+  now?: () => number;
+}
+
+export interface SmokeResult {
+  run: string;
+  order_id: string;
+  number: string;
+  status: string;
+}
+
+const table = (db: DatabaseSync) =>
+  db.exec(`CREATE TABLE IF NOT EXISTS smoke_run (
+    name TEXT PRIMARY KEY, store TEXT NOT NULL, storefront_id TEXT NOT NULL,
+    cart_id TEXT, cart_token TEXT, completion TEXT, order_id TEXT, order_token TEXT, number TEXT, abandoned TEXT,
+    created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`);
+
+/** The smoke run `name` on `target`: resumed, or answered again once it has its number. */
+export async function smoke(target: StoreTarget, name: string, d: SmokeDeps): Promise<SmokeResult> {
+  return withStoreLock(d.cwd, "smoke", async () => {
+    const db = stateDb(d.cwd);
+    try {
+      table(db);
+      return await run(db, target, name, d);
+    } finally {
+      db.close();
+    }
+  });
+}
+
+async function run(db: DatabaseSync, target: StoreTarget, name: string, d: SmokeDeps): Promise<SmokeResult> {
+  const now = d.now ?? Date.now;
+  const store = identityOf(target);
+  const get = () => db.prepare("SELECT * FROM smoke_run WHERE name = ?").get(name) as unknown as Run | undefined;
+  const set = (a: Partial<Run>) => {
+    const cols = Object.keys(a);
+    db.prepare(`UPDATE smoke_run SET ${cols.map((c) => `${c} = ?`).join(", ")}, updated_at = ? WHERE name = ?`).run(
+      ...cols.map((c) => (a as Record<string, string | null>)[c] ?? null),
+      now(),
+      name,
+    );
+  };
+
+  let r = get();
+  // A finished run answers its order again, sending nothing: a retried command can't place a second one.
+  if (r?.number && r.order_id) {
+    if (r.store !== store) throw new DeployRefused(`smoke run ${name} belongs to another store (${r.store})`);
+    return { run: name, order_id: r.order_id, number: r.number, status: "open" };
+  }
+  if (r?.abandoned)
+    throw new DeployRefused(`smoke run ${name} was abandoned: ${r.abandoned}. Start another with --run <new name>`);
+
+  // The storefront's key, through the same check `keys create --save` makes every time: a saved key that's
+  // this store's and still works, or a replacement on its recorded storefront (codex code r13).
+  const saved = await keysSaveHeld(
+    target,
+    { kind: "publishable", name: "web", origins: [] },
+    {
+      cwd: d.cwd,
+      fetch: d.fetch,
+      session: d.session,
+      log: d.log,
+    },
+  );
+  const key = saved[ENV.publishable];
+  const storefront = saved[ENV.storefront];
+  if (!key || !storefront) throw new DeployRefused("no storefront key was saved for this store");
+
+  if (!r) {
+    const t = now();
+    db.prepare("INSERT INTO smoke_run (name, store, storefront_id, created_at, updated_at) VALUES (?, ?, ?, ?, ?)").run(
+      name,
+      store,
+      storefront,
+      t,
+      t,
+    );
+    r = get() as Run;
+  }
+  // A cart admits only its own storefront's key: a record for another store or storefront is refused, not reused.
+  if (r.store !== store || r.storefront_id !== storefront)
+    throw new DeployRefused(
+      `smoke run ${name} was made for ${r.store === store ? `storefront ${r.storefront_id}` : r.store}: start another with --run <new name>`,
+    );
+
+  const shop = { "x-kedge-key": key };
+  const req = async (method: string, path: string, headers: Record<string, string>, body?: unknown) => {
+    const res = await storeRequest(d.fetch, new URL(path, target.url), {
+      method,
+      headers: { ...headers, ...(body === undefined ? {} : { "content-type": "application/json" }) },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    return res;
+  };
+  const refused = (what: string, res: { status: number; body: Record<string, unknown> }) =>
+    new DeployRefused(
+      `${what} answered ${res.status} ${String((res.body.error as { code?: string } | undefined)?.code ?? "")}`.trim(),
+    );
+
+  if (!r.order_id) {
+    if (!r.completion) {
+      // Disposable until it's marked completing: a cart from a stopped run is abandoned with its lines.
+      const p = await req("GET", `/store/products/${SMOKE_PRODUCT.handle}?currency=${SMOKE_PRODUCT.currency}`, shop);
+      if (p.status === 404)
+        throw new DeployRefused(`the store has no ${SMOKE_PRODUCT.handle}: run kedge seed --sample apparel first`);
+      if (!p.ok) throw refused("reading the sample product", p);
+      const variant = (p.body.variants as { id?: string }[] | undefined)?.[0]?.id;
+      if (!variant) throw new DeployRefused(`${SMOKE_PRODUCT.handle} has no variant to buy`);
+      const cart = await req("POST", "/store/carts", shop, {
+        currency_code: SMOKE_PRODUCT.currency,
+        email: smokeEmail(target.url),
+      });
+      if (!cart.ok) throw refused("creating the cart", cart);
+      const id = String(cart.body.id);
+      const token = String(cart.body.token);
+      const withCart = { ...shop, "x-cart-token": token };
+      const line = await req("POST", `/store/carts/${id}/lines`, withCart, { variant_id: variant, quantity: 1 });
+      if (!line.ok) throw refused("adding the line", line);
+      const total = (line.body.totals as { total?: { amount?: number } } | null)?.total?.amount;
+      if (typeof total !== "number") throw new DeployRefused("the cart answered no total to complete it with");
+      // Moment 1: the exact completion, before it's sent. It's what every rerun sends.
+      set({ cart_id: id, cart_token: token, completion: JSON.stringify({ expected_total: total }) });
+      r = get() as Run;
+    }
+    // Moment 2: the recorded body, unchanged, with the same token; a completed cart answers the same order.
+    const done = await req(
+      "POST",
+      `/store/carts/${r.cart_id}/complete`,
+      { ...shop, "x-cart-token": r.cart_token as string },
+      JSON.parse(r.completion as string),
+    );
+    const code = (done.body.error as { code?: string } | undefined)?.code;
+    if (code === "CART_TOTAL_CHANGED") {
+      // That refusal creates no order: this run ends, and another prices afresh.
+      set({ abandoned: "the cart's price changed before it completed (CART_TOTAL_CHANGED)" });
+      throw new DeployRefused(
+        `smoke run ${name}: the price changed before completion, so nothing was ordered. Start another with --run <new name>`,
+      );
+    }
+    if (!done.ok || typeof done.body.id !== "string" || typeof done.body.token !== "string")
+      throw refused("completing the cart", done);
+    // Moment 3: the order's id and token, together.
+    set({ order_id: done.body.id, order_token: done.body.token });
+    r = get() as Run;
+  }
+
+  // Placement stands in for payment in Phase 0 (D-035); placing an open order again changes nothing.
+  const orderId = r.order_id as string;
+  await withCliSession(target, ["order:place"], d.session, async (auth) => {
+    const placed = await req("POST", `/admin/orders/${orderId}/place`, auth, {});
+    if (!placed.ok) throw refused("placing the order", placed);
+  });
+  const read = await req("GET", `/store/orders/${orderId}`, { ...shop, "x-order-token": r.order_token as string });
+  if (!read.ok) throw refused("reading the order back", read);
+  const status = String(read.body.status);
+  // The API answers the number as an integer (research/29's first run): kept as text, as shown.
+  const raw = read.body.number;
+  const number = typeof raw === "number" || (typeof raw === "string" && raw) ? String(raw) : null;
+  if (status !== "open" || !number)
+    throw new DeployRefused(
+      `the order is ${status}${number ? ` (${number})` : ", with no number"}, so it isn't placed`,
+    );
+  set({ number });
+  d.log(`order ${number} is open (smoke run ${name})`);
+  return { run: name, order_id: orderId, number, status };
+}
+
+/** `smoke@<the store's host>`, which names it as a test in the admin; a bare host gets `.test` to be an address. */
+export function smokeEmail(url: string): string {
+  const host = new URL(url).hostname;
+  return `smoke@${host.includes(".") ? host : `${host}.test`}`;
+}
+
+/** Whether `url` is a store a smoke run writes to only by someone's choice (§6.3). */
+export function needsLive(target: StoreTarget, live: boolean): void {
+  if (target.kind === "production" && !live)
+    throw new NeedsPerson(
+      `${target.url} is the live store: a test order there is its owner's call, and stays as its first order until P1's order actions can cancel it. With their yes, run this again with --live`,
+    );
+}

package/src/store-api.ts

@@ -0,0 +1,36 @@
+// Requests to a store's own API, as the CLI makes them (p0.10 §5): a write
+// with no answer, or one that can't be read, is an unknown outcome.
+import { UnknownOutcome } from "./cf";
+import { DeployRefused } from "./deploy";
+
+/**
+ * One request to a store's API. A write sent with no answer back, or with an
+ * answer that can't be read, may have committed: its outcome is unknown, never
+ * a failure (p0.10 §5, codex code r8), and says so under `--json`. A readable
+ * refusal is the caller's to word.
+ */
+export async function storeRequest(
+  f: typeof fetch,
+  url: URL,
+  init: RequestInit,
+): Promise<{ status: number; ok: boolean; body: Record<string, unknown> }> {
+  const what = `${init.method ?? "GET"} ${url.pathname}`;
+  const write = (init.method ?? "GET") !== "GET";
+  let r: Response;
+  try {
+    r = await f(url, init);
+  } catch {
+    if (write) throw new UnknownOutcome(what, "the store");
+    throw new DeployRefused(`${what}: the store didn't answer`);
+  }
+  let body: Record<string, unknown>;
+  try {
+    body = (await r.json()) as Record<string, unknown>;
+  } catch {
+    // A refusal Kedge words is JSON; an unreadable success, or a 5xx from in front of the Worker, isn't proof of either.
+    if (write && (r.ok || r.status >= 500))
+      throw new UnknownOutcome(`${what} (answered ${r.status}, unreadable)`, "the store");
+    throw new DeployRefused(`${what} answered ${r.status}, not JSON`);
+  }
+  return { status: r.status, ok: r.ok, body };
+}

package/src/target.ts

@@ -0,0 +1,81 @@
+// Which store a URL is (docs/proposals/p0.10-agent-path.md §4, §6.2). The CLI
+// sends a session, a saved key or a run's record only to a target it can name
+// by identity: production or a preview this store's `<store>-ops` records, or
+// `kedge dev` on this machine. Anything else gets nothing, so an unknown
+// endpoint never receives a token. A store is its account, Worker and
+// database, not its URL: the account's owner can change the workers.dev
+// subdomain, so the URL is computed from the current one on every run.
+import type { Cloudflare } from "./cf";
+import { openOps } from "./deploy";
+import { storeNames } from "./store";
+
+export interface StoreTarget {
+  kind: "production" | "preview" | "local";
+  /** The origin requests go to. */
+  url: string;
+  /** What records bind to: never the URL. A local target's account is `local`. */
+  identity: { account: string; worker: string; database: string };
+  /** Where a CLI session's row is written: that target's own database, and no other. */
+  database: { name: string; id: string | null };
+}
+
+/**
+ * `kedge dev`'s port: the config's `dev.port`, else Wrangler's default 8787
+ * (`DEFAULT_LOCAL_PORT`, wrangler-dist/cli.js:212493, 4.152.0). When 8787 is
+ * taken Wrangler picks another (`memoizeGetPort`, :213241), which then isn't a
+ * target: the command asks for `--key` or `--session` instead.
+ */
+export function devPort(cwd: string): number {
+  const dev = storeNames(cwd).config.dev as { port?: unknown } | undefined;
+  return typeof dev?.port === "number" ? dev.port : 8787;
+}
+
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+/** The target `url` names, or null when it's none this checkout knows. */
+export async function resolveTarget(
+  url: string,
+  cwd: string,
+  cloudflare: () => Promise<Cloudflare>,
+): Promise<StoreTarget | null> {
+  const u = new URL(url);
+  const { names } = storeNames(cwd);
+  if (LOCAL_HOSTS.has(u.hostname)) {
+    if (u.protocol !== "http:" || Number(u.port || 80) !== devPort(cwd)) return null;
+    return {
+      kind: "local",
+      url: u.origin,
+      identity: { account: "local", worker: names.worker, database: "local" },
+      database: { name: names.database, id: null },
+    };
+  }
+  if (u.protocol !== "https:") return null;
+  const cf = await cloudflare();
+  // A lookup, never a create: a store never deployed has no target here.
+  if (!(await cf.findD1(names.ops))) return null;
+  const { ops } = await openOps(cf, names);
+  const host = (worker: string, subdomain: string) => `https://${worker}.${subdomain}.workers.dev`;
+  const subdomain = await cf.workersSubdomain();
+  if (u.origin === host(names.worker, subdomain)) {
+    const db = await ops.resource("d1", names.database);
+    if (!db?.id) return null;
+    return {
+      kind: "production",
+      url: u.origin,
+      identity: { account: cf.account, worker: names.worker, database: db.id },
+      database: { name: names.database, id: db.id },
+    };
+  }
+  // The whole origin, as a preview's is made: a host that only begins with a preview's name isn't it.
+  const rows = await ops.query(
+    "SELECT worker, database_name, database_id FROM preview WHERE state = 'bootstrapped' AND database_id IS NOT NULL",
+  );
+  const p = rows.find((r) => u.origin === host(String(r.worker), subdomain));
+  if (!p) return null;
+  return {
+    kind: "preview",
+    url: u.origin,
+    identity: { account: cf.account, worker: String(p.worker), database: String(p.database_id) },
+    database: { name: String(p.database_name), id: String(p.database_id) },
+  };
+}