astroidjs 0.1.2 → 0.2.0

package/README.md

@@ -46,7 +46,7 @@ export default defineAstroid({
   key: "coracle",
   archetype: "storefront",
   theme: { name: "Coracle Coffee", colors: { brand: "#1f6f78" } },
-  sections: ["hero", "marquee", "featured", "productGrid", "visit"],
+  sections: ["hero", "banner", "productGrid", "locationHours", "contact"],
   commerce: { provider: "square" },
   deploy: { platform: "cloudflare" },
 });
@@ -59,12 +59,247 @@ export default defineAstroid({
   key: "megbowen",
   archetype: "portfolio",
   theme: { name: "Meg Bowen Studio", colors: { brand: "#2b2b2b" } },
-  sections: ["hero", "gallery", "story", "contact"],
-  portal: { enabled: true, gated: true },
+  sections: ["hero", "gallery", "aboutIntro", "contact"],
+  portal: { enabled: true },
   deploy: { platform: "cloudflare" },
 });
 ```
 
+## Commerce
+
+**Providers fill roles.** Not "the commerce provider" — the toolkit's clients
+make that impossible: `commerce/stripe` has no catalog API, `commerce/fourthwall`
+has no invoicing, Square does both. So `storefront` and `invoicing` are assigned
+independently, and a provider put in a role it can't serve fails at config load
+rather than at runtime on the first invoice.
+
+```ts
+commerce: { storefront: "fourthwall", invoicing: "stripe" }   // two providers
+commerce: { provider: "square" }                              // shorthand → storefront
+```
+
+**The catalog is mirrored with a pulled/owned split.** The provider is the source
+of truth; D1 holds the owner's edits. `mode: "mirror"` keeps the catalog fields
+in D1 (fast reads, briefly stale); `mode: "overlay"` keeps only the owner's
+columns (never stale, one provider round-trip per read). The sync **never writes
+an owned column** — a sync that does silently reverts the owner's work, and
+they find out days later. `slug` is owned for that reason: it's the public URL,
+so a provider rename must not break links.
+
+```ts
+commerce: {
+  provider: "square",
+  catalog: { owned: { tone: { type: "text", values: ["cream", "teal"] } } },
+}
+```
+
+Everything else follows from that table. `astroidCatalogLoaderConfig` reads it
+for the Live Content Collection, and the adapters normalize before the row is
+written — so one loader definition serves a Square site and a Fourthwall site,
+which is the drift the module exists to kill.
+
+**Checkout is server-authoritative.** `verifyCheckout` treats the client's price
+as a staleness check, never an input to the charge: re-price server-side, refuse
+on mismatch. `checkoutIdempotencyKey` derives a stable key from the verified cart
+**and a required `identity`**, so a double-clicked Pay button charges once —
+while two customers buying the same thing stay two charges.
+
+```ts
+const key = await checkoutIdempotencyKey(check, "order", cartId);
+```
+
+Pass something stable across a retry of this attempt and distinct between buyers
+(a cart id, checkout-session id, or portal user id). It is required, and empty is
+refused, because a key derived from cart contents alone collides between
+customers: providers scope idempotency keys per account for ~24h, so the second
+buyer's charge is deduped into the first buyer's order and never happens.
+
+## The webhook pipeline
+
+Configure `commerce` and the generated worker stops being fetch-only: it composes
+Astro's SSR handler with a **queue consumer** and a **cron**, and the scaffold
+gains a webhook receiver plus a consumer seam. `--commerce <provider>` on
+`pnpm create astroid` sets it all up.
+
+The receiver's ordering is the part worth knowing. `handleWebhook` verifies the
+HMAC over the **raw body before anything parses it** — parse first and an
+unauthenticated caller reaches the JSON parser and everything downstream, and
+re-serializing a parsed body to check a signature is how signature checks quietly
+stop checking anything. It then enqueues and returns, so the response doesn't
+wait on the work.
+
+Status codes are the only backpressure signal a provider gives you, so each one
+is picked for what it tells the sender to do:
+
+| Situation | Code | Why |
+|---|---|---|
+| Secret unprovisioned | 503 | Dormant is temporary — keep retrying so events delivered before you set the secret still land |
+| Bad / missing signature | 401 | Terminal. It won't verify on retry either, and retrying turns a misconfiguration into a flood |
+| Body isn't JSON | 400 | Terminal for the same reason |
+| Enqueue failed | 503 | The signature checked out, so the event is real — ask for redelivery |
+| Enqueued | 202 | Accepted, not done. That's the point of a queue |
+
+On the consumer side `astroidQueueHandler` owns the dispatch every site wrote: a
+periodic refresh re-syncs, a webhook re-syncs *only* if it touched the catalog,
+and everything else acks as a no-op. That last part matters — order and payment
+events arrive in volume and have nothing local to update, so treating them as
+actionable turns a busy sales day into a refresh storm.
+
+The cron **enqueues** rather than running inline, so the safety-net re-sync takes
+the same retry and DLQ path as everything else. Retries and DLQ routing live in
+`wrangler.jsonc`, because they're Cloudflare's job, not the consumer's.
+
+## Transactional email
+
+Four templates — sign-in link, password reset, and the inquiry pair (notify the
+owner, confirm to the sender) — over the toolkit's email shell. Each renders HTML
+**and** plaintext from one definition: a message with no text/plain part scores
+worse with spam filters, and for a sign-in link the plaintext body is what a
+terminal client shows and what the dev log prints.
+
+`astroidMailTheme(config)` derives the whole mail theme from `theme.colors`.
+Neutrals stay fixed (they're typography choices, not brand ones); what varies is
+the accent and the five-cell masthead band, built as a ramp so it reads as
+designed whether you configured one brand colour or three. The accent is
+**contrast-corrected** — a brand yellow used verbatim as 11px uppercase text on a
+near-white card is unreadable, and mail clients have no dark-mode escape hatch.
+Pass overrides for any slot you want to own.
+
+Delivery is best-effort and never throws. Mail here is always the notification of
+something already durable — the inquiry row is inserted, the account exists — so
+a failure must not fail the request that caused it, and messages send
+independently so the owner's copy still arrives when a visitor typos their
+address. With no `EMAIL` binding the mailer is **dormant**: it logs the rendered
+message instead of dropping it, which is what makes "click the magic link" work
+under `wrangler dev`.
+
+```ts
+formRoute({
+  form: contactForm,
+  // Fires after the insert, off the response path — store-and-forward.
+  onSubmit: (values, env) => sendInquiryMail(astroidConfig, env, values),
+});
+```
+
+## SEO
+
+A settings-driven head, structured data, and the two crawler files — first-party,
+no `astro-seo` dependency.
+
+`<Seo>` resolves three levels (page override → the page's own default →
+`site_settings`) with one rule worth knowing: an **empty string is unset**, so
+clearing a field in the editor falls back instead of publishing a blank `<meta>`.
+The title template applies only when a page supplies its own title, so the home
+page reads `Acme Coffee`, not `Acme Coffee | Acme Coffee`. `disableIndexing` in
+settings is a site-wide kill switch that beats any page asking to be indexed —
+useful for staging.
+
+`<StructuredData>` emits a schema.org `@graph`: the business, the `WebSite`, and
+optionally the entity the page is *about* (a Product, a VisualArtwork). The
+business `@type` comes from the archetype (`storefront` → `Store`, `portfolio` →
+`Person`); set `seo.businessType` to a narrower subtype whenever you know one.
+The payload is escaped with `escapeJsonLd`, not `JSON.stringify` — `stringify`
+doesn't escape `<`, so an editor-authored value containing `</script>` would
+close the tag early and inject markup into `<head>`.
+
+`robots.txt` and `sitemap.xml` derive their disallow list from the same config
+(`astroidNoindexPaths`), so the two files can't disagree about what's crawlable.
+Both are **origin-aware** — built from the serving origin rather than a
+configured domain, because a preview deploy advertising the production host
+invites its content to be indexed under the real domain.
+
+## Security defaults
+
+Two stack-wide concerns every site was re-deriving by hand, moved into the
+framework.
+
+**Rate-limit rules are data, derived from the config.** The generated middleware
+calls `astroidRateRules(config)`: the editor magic-link always (the
+email-bombing target, so the tightest budget in the set), the portal's
+credential surfaces when `portal.enabled`, checkout when `commerce` is set. The
+session-gated editor API stays out on purpose — a limiter that can lock the
+owner out of their own studio is worse than the abuse it stops. Add or override
+via `security.rateRules`, which is matched *before* the defaults, so you replace
+one budget rather than the whole set.
+
+**The CSP is composed, and it's split for a reason.** `astroidSecurity(config)`
+gives `astro.config.mjs` its `security` block. Astro owns `script-src` — it
+hashes every script it processes, so the policy needs no `'unsafe-inline'` — and
+Astroid adds the one hash Astro can't produce itself: Solid's hydration
+bootstrap, injected by `@astrojs/solid-js` on every page with an island.
+Computing it from `generateHydrationScript()` means it tracks solid-js upgrades
+instead of going stale as a copy-pasted literal. Meanwhile the generated
+middleware rewrites *only* `style-src`, because Louise's data-driven `style=""`
+carriers need `'unsafe-inline'` and a single hash in that directive would void
+it per spec — the two cannot share one directive.
+
+```js
+// astro.config.mjs
+import { ASTROID_VITE_BUILD, astroidSecurity } from "astroidjs/astro";
+import astroidConfig from "./astroid.config.ts";
+
+export default defineConfig({
+  security: astroidSecurity(astroidConfig),
+  vite: { build: { ...ASTROID_VITE_BUILD } },  // assetsInlineLimit: 0 — an
+});                                            // inlined asset can't be hashed
+```
+
+Enabled modules contribute their own origins (a commerce provider's SDK hosts,
+the captcha frame); `security.cspOrigins` adds anything Astroid can't see.
+
+## Modules are dormant, not broken
+
+Astroid's optional modules are opt-in at the *config* level, never at the
+*account* level: switching commerce on must not require a Square account before
+`pnpm dev` will boot. So a module whose secrets aren't provisioned is **dormant**
+— it renders, it serves, it says out loud that it's simulated, and it never calls
+upstream with a dummy credential. A fresh clone runs with zero external accounts.
+
+`create-astroid` seeds every module secret with one loud sentinel,
+`DUMMY_REPLACE_ME`, so a scaffold has a complete and valid binding set and no
+real credentials. Reading a secret back that still holds the sentinel — or that
+is absent, empty, or bound to an unprovisioned store — yields `null`:
+
+```ts
+import { resolveModuleSecrets, describeModuleStatus } from "astroidjs";
+
+const secrets = await resolveModuleSecrets({
+  SQUARE_ACCESS_TOKEN: env.SQUARE_ACCESS_TOKEN,
+  SQUARE_WEBHOOK_SECRET: env.SQUARE_WEBHOOK_SECRET,
+});
+
+if (!secrets.configured) {
+  console.warn(describeModuleStatus("commerce", secrets));
+  // → commerce: dormant (simulated) — unprovisioned secret(s): SQUARE_WEBHOOK_SECRET
+  return simulatedCheckout();
+}
+```
+
+Partial provisioning counts as dormant. A half-configured integration fails
+mid-checkout rather than at boot, which is precisely the failure this convention
+exists to prevent.
+
+The scaffold ships one worked example: Turnstile captcha on the **editor
+sign-in**, seeded with the sentinel secret plus Cloudflare's always-passing test
+site key, enforcing only once **both** halves are real — so provisioning one of
+them can't lock you out of your own sign-in.
+
+Both halves matter, and the second one is the reason this is worth spelling out.
+`getLouiseAuth` registers Better Auth's captcha plugin on `/sign-in/magic-link`
+as soon as the pair is real, and that plugin rejects any request without an
+`x-captcha-response` header. So the login page renders the widget under exactly
+the same condition the server arms the check — `turnstileSiteKey` returns null
+for the test key, the same test `activeCaptchaSecret` applies — and forwards the
+token in that header. A gate that turns on server-side while the page keeps
+posting without a token is not a half-configured integration; it is a locked
+door with the owner outside.
+
+The **public contact form** is a separate surface and is not captcha-gated: its
+spam defence is the honeypot, the minimum time-to-submit, and the rate limit.
+`FormSpamConfig.turnstile` exists in the toolkit if you want to add it, but
+`formRoute` is generated without `turnstileSecret`, so switching the flag on
+alone would not enforce anything.
+
 ## CLI
 
 The `astroid` command turns the config into the Louise wiring and keeps it in
@@ -87,7 +322,7 @@ The generated trio carries a "do not hand-edit" banner — `generate` (and
 config to catch drift. Your `wrangler.jsonc` is scaffolded once and then yours to
 edit (real binding ids, secrets); `generate` never touches it.
 
-New projects come from the `create-astroid` scaffold (`npm create astroid`), which
+New projects come from the `create-astroid` scaffold (`pnpm create astroid`), which
 writes the floor — config, the generated trio, `wrangler.jsonc`, and the baseline
 Astro app — in one step.
 
@@ -98,7 +333,7 @@ Astro app — in one step.
 3. ✅ Config → generated `worker.ts` + middleware (no hand-wired route ordering).
 4. ✅ `<Section>` / `<Editable>` / `<Collection>` component primitives.
 5. ✅ **CLI** — `astroid generate / doctor / dev / build / deploy`; `create-astroid`
-   scaffold (`npm create astroid`).
+   scaffold (`pnpm create astroid`).
 
 ## License
 

package/bin/astroid.mjs

@@ -77,7 +77,7 @@ async function loadConfig(cwd, explicit) {
 
 // --- commands --------------------------------------------------------------
 async function cmdGenerate(cwd, flags, { quiet = false } = {}) {
-  const { generateAstroidProject } = await import(GENERATORS_URL);
+  const { generateAstroidProject, generateAstroidScaffoldFiles } = await import(GENERATORS_URL);
   const { config } = await loadConfig(cwd, flags.config);
   const files = generateAstroidProject(config);
   for (const file of files) {
@@ -86,12 +86,46 @@ async function cmdGenerate(cwd, flags, { quiet = false } = {}) {
     writeFileSync(abs, file.contents);
     if (!quiet) out(`  ✓ ${file.path}`);
   }
-  if (!quiet) out(`Generated ${files.length} file(s) from your defineAstroid config.`);
+
+  // Scaffold-once files for whatever modules the config switched on.
+  //
+  // Written only when ABSENT — each is a seam the project owns, so overwriting
+  // one would destroy the edit it exists to hold. But a MISSING one is not a
+  // choice the user made: the trio above emits static imports of `./queue.js`
+  // and `./portal-auth.js`, so a config that gained a module after scaffold
+  // regenerated a project that couldn't resolve its own imports. Completing the
+  // config change is what makes "one typed config" true.
+  const created = [];
+  for (const file of generateAstroidScaffoldFiles(config)) {
+    const abs = join(cwd, file.path);
+    const exists = existsSync(abs);
+    if (file.apply === "append-once") {
+      const current = exists ? readFileSync(abs, "utf8") : "";
+      if (file.marker && current.includes(file.marker)) continue;
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, current + file.contents);
+      created.push(file.path);
+      continue;
+    }
+    if (exists) continue;
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, file.contents);
+    created.push(file.path);
+  }
+  for (const path of created) if (!quiet) out(`  + ${path} (scaffolded — yours to edit)`);
+
+  if (!quiet) {
+    out(`Generated ${files.length} file(s) from your defineAstroid config.`);
+    if (created.length > 0) {
+      out(`Scaffolded ${created.length} new module file(s); existing ones were left alone.`);
+    }
+  }
   return files;
 }
 
 async function cmdDoctor(cwd, flags) {
-  const { generateAstroidProject } = await import(GENERATORS_URL);
+  const { generateAstroidProject, generateAstroidScaffoldFiles, astroidUsesQueues } =
+    await import(GENERATORS_URL);
   const { config, path: configPath } = await loadConfig(cwd, flags.config);
 
   const problems = []; // { level: "error" | "warn", msg }
@@ -99,6 +133,8 @@ async function cmdDoctor(cwd, flags) {
   const warn = (msg) => problems.push({ level: "warn", msg });
   const oks = [];
   const ok = (msg) => oks.push(msg);
+  // Neither pass nor problem: informational lines about what's switched on.
+  const notes = [];
 
   ok(`config loads and validates (${rel(cwd, configPath)})`);
 
@@ -108,12 +144,28 @@ async function cmdDoctor(cwd, flags) {
     if (!existsSync(abs)) {
       err(`${file.path} is missing — run \`astroid generate\`.`);
     } else if (readFileSync(abs, "utf8") !== file.contents) {
-      warn(`${file.path} is stale (out of sync with your config) — run \`astroid generate\`.`);
+      // An ERROR, not a warning. These three carry a "do not hand-edit" banner
+      // and are a pure function of the config, so "stale" means the project on
+      // disk is not the project the config describes — which is the single
+      // condition doctor exists to catch. As a warning it printed "healthy" and
+      // exited 0, so `pnpm doctor` could not gate CI on it.
+      err(`${file.path} is stale (out of sync with your config) — run \`astroid generate\`.`);
     } else {
       ok(`${file.path} is up to date`);
     }
   }
 
+  // 1b. Scaffold-once module files. A missing one is an ERROR: the trio above
+  //     emits static imports of `./queue.js` / `./portal-auth.js`, so a config
+  //     that names a module whose seam was never written produces a project that
+  //     cannot resolve its own imports. This is precisely the state that used to
+  //     report "healthy, 2 warning(s)" and exit 0.
+  for (const file of generateAstroidScaffoldFiles(config)) {
+    if (file.apply === "append-once") continue; // accumulated, not owned — see below
+    if (existsSync(join(cwd, file.path))) ok(`${file.path} present`);
+    else err(`${file.path} is missing (required by your config) — run \`astroid generate\`.`);
+  }
+
   // 2. wrangler.jsonc bindings — presence checks + placeholder detection. Read as
   //    text (JSONC with comments/trailing commas) rather than parse, to stay robust.
   const wranglerPath = join(cwd, "wrangler.jsonc");
@@ -122,6 +174,50 @@ async function cmdDoctor(cwd, flags) {
   } else {
     const w = readFileSync(wranglerPath, "utf8");
     const hasBinding = (name) => new RegExp(`"binding"\\s*:\\s*"${name}"`).test(w);
+
+    // wrangler.jsonc is scaffold-once (so a provisioned binding id is never
+    // clobbered), which means a config change can never update it. Nothing
+    // detected the resulting drift: switching on commerce made the generated
+    // worker call `env.COMMERCE_QUEUE.send()` against a wrangler.jsonc with no
+    // queues block at all, and both doctor and deploy reported success.
+    //
+    // So check every binding the GENERATED code actually dereferences, not just
+    // the three the baseline happens to have.
+    const requiredBindings = [
+      { name: "RL", what: "KV namespace", why: "the rate limiter in src/middleware.ts" },
+      { name: "DRAFTS", what: "KV namespace", why: "the autosave draft buffer" },
+      ...(astroidUsesQueues(config)
+        ? [
+            {
+              name: "COMMERCE_QUEUE",
+              what: "Queue",
+              why: "the webhook producer in src/worker.ts",
+            },
+          ]
+        : []),
+    ];
+    for (const b of requiredBindings) {
+      if (hasBinding(b.name)) ok(`wrangler: ${b.what} \`${b.name}\` binding present`);
+      else
+        err(
+          `wrangler.jsonc has no ${b.what} \`${b.name}\` binding, but ${b.why} uses it. ` +
+            "Your config gained a module after this file was scaffolded — add the binding by hand " +
+            "(wrangler.jsonc is never regenerated, so provisioned ids are never clobbered).",
+        );
+    }
+
+    // Email Sending declares its binding as `"name"`, not `"binding"`, so the
+    // regex above cannot see it. Checked separately because sign-in depends on
+    // it: the magic link is console-logged in dev and EMAILED in production, so
+    // a missing binding is a site nobody can sign in to — and it fails only once
+    // deployed, which is the one place nothing in this repo exercises.
+    if (/"send_email"\s*:/.test(w)) ok("wrangler: Email Sending `EMAIL` binding present");
+    else
+      err(
+        "wrangler.jsonc has no `send_email` binding, but production sign-in emails the " +
+          "magic link (it is only console-logged in dev). Add: \"send_email\": [{ \"name\": \"EMAIL\" }]",
+      );
+
     if (hasBinding("DB")) ok("wrangler: D1 `DB` binding present");
     else err("wrangler.jsonc has no D1 `DB` binding.");
     if (hasBinding("MEDIA")) ok("wrangler: R2 `MEDIA` binding present");
@@ -141,8 +237,45 @@ async function cmdDoctor(cwd, flags) {
   if (existsSync(join(cwd, "migrations"))) ok("migrations/ directory present");
   else warn("no migrations/ directory — create your D1 schema migrations there.");
 
+  // 4. Local secret provisioning — which modules will run dormant under
+  //    `astroid dev`, and what to set to wake them.
+  //
+  //    Scoped deliberately to SECRETS, read from .dev.vars. Doctor is a static
+  //    CLI: it cannot see runtime bindings (EMAIL, the queue), so claiming
+  //    "email is dormant" here would be reporting its own blindness as the
+  //    project's state. What it CAN say for certain is whether a value is still
+  //    the placeholder — and that is the half developers actually forget.
+  //
+  //    A dormant module is never an error. It is the documented default, and a
+  //    fresh scaffold is expected to report every module dormant.
+  const { astroidSecretNames, ASTROID_SECRET_PLACEHOLDER } = await import(GENERATORS_URL);
+  const devVarsPath = join(cwd, ".dev.vars");
+  const devVars = existsSync(devVarsPath) ? parseDotEnv(readFileSync(devVarsPath, "utf8")) : null;
+
+  if (!devVars) {
+    warn(
+      "no .dev.vars — every module runs dormant (simulated) locally. " +
+        "Copy .env.example to .dev.vars to change that.",
+    );
+  }
+  for (const [moduleName, names] of Object.entries(astroidSecretNames(config))) {
+    if (names.length === 0) continue;
+    const unset = names.filter((name) => {
+      const value = (devVars?.[name] ?? "").trim();
+      return value === "" || value === ASTROID_SECRET_PLACEHOLDER;
+    });
+    // `core` is not a module — its secrets each gate their own thing (sessions
+    // fail closed off localhost, Turnstile needs a matched pair), so a blanket
+    // "dormant" line would be wrong. Report it as provisioning, not dormancy.
+    if (unset.length === 0) ok(`${moduleName}: all secrets provisioned in .dev.vars`);
+    else if (moduleName === "core")
+      notes.push(`core: ${unset.length} secret(s) unset locally (${unset.join(", ")})`);
+    else notes.push(`${moduleName}: dormant (simulated) — unprovisioned: ${unset.join(", ")}`);
+  }
+
   // --- report ---
   for (const m of oks) out(`  ✓ ${m}`);
+  for (const n of notes) out(`  · ${n}`);
   for (const p of problems) {
     if (p.level === "warn") out(`  ! ${p.msg}`);
     else out(`  ✗ ${p.msg}`);
@@ -206,6 +339,15 @@ function readWranglerFacts(text) {
       binding: m[1],
       id: m[2],
     })),
+    // Queue names, from the producer + the consumer's dead_letter_queue. Unlike
+    // D1/R2/KV these are referenced BY NAME, so there's no id to patch back —
+    // creating them is the whole job.
+    queues: [
+      ...new Set([
+        ...[...text.matchAll(/"queue":\s*"([^"]+)"/g)].map((m) => m[1]),
+        ...[...text.matchAll(/"dead_letter_queue":\s*"([^"]+)"/g)].map((m) => m[1]),
+      ]),
+    ],
     // Real (uncommented) account_id line, filled in?
     hasAccount: /^\s*"account_id":\s*"[^<][^"]*"/m.test(text),
   };
@@ -225,6 +367,11 @@ function provisionPlan(facts) {
       steps.push({ kind: "kv", name: binding, args: ["kv", "namespace", "create", binding] });
     }
   }
+  // Queues carry no id, so there's no placeholder to test — creating one that
+  // already exists just errors, which the runner tolerates (same as R2).
+  for (const queue of facts.queues) {
+    steps.push({ kind: "queue", name: queue, args: ["queues", "create", queue] });
+  }
   return steps;
 }
 
@@ -255,8 +402,12 @@ async function cmdDeploy(cwd, flags, rest) {
   const wranglerPath = join(cwd, "wrangler.jsonc");
   if (!existsSync(wranglerPath)) fail("wrangler.jsonc not found — run inside an Astroid project.");
 
-  // Regenerate so the shipped worker/schema always match the config.
-  await cmdGenerate(cwd, flags, { quiet: true });
+  // Regenerate so the shipped worker/schema always match the config — but NOT
+  // on a dry run. This used to sit above the `--dry-run` guard, so a command
+  // that ends by printing "(dry run — nothing executed)" had already rewritten
+  // three files and silently discarded any local edits to them. Probing the
+  // plan on a working branch is exactly when someone has local edits.
+  if (!dryRun) await cmdGenerate(cwd, flags, { quiet: true });
 
   let wrangler = readFileSync(wranglerPath, "utf8");
   const facts = readWranglerFacts(wrangler);
@@ -301,8 +452,11 @@ async function cmdDeploy(cwd, flags, rest) {
   for (const s of plan) {
     out(`\n▸ wrangler ${s.args.join(" ")}`);
     const res = runInherit(s.args);
-    // R2 bucket create is idempotent-ish (an existing bucket errors) — tolerate it.
-    if (res.status !== 0 && s.kind !== "r2") fail(`Provisioning failed at: wrangler ${s.args.join(" ")}`);
+    // R2 bucket + queue creates are idempotent-ish (an existing one errors) —
+    // tolerate those so a re-run of `astroid deploy` isn't a hard stop.
+    if (res.status !== 0 && s.kind !== "r2" && s.kind !== "queue") {
+      fail(`Provisioning failed at: wrangler ${s.args.join(" ")}`);
+    }
 
     if (s.kind === "d1") {
       const id = lookupId(wranglerBin, cwd, ["d1", "list", "--json"], (rows) => rows.find((r) => r.name === s.name)?.uuid);
@@ -342,6 +496,28 @@ async function cmdDeploy(cwd, flags, rest) {
 }
 
 // --- helpers ---------------------------------------------------------------
+/**
+ * Minimal KEY=VALUE reader for .dev.vars. Not a dotenv implementation — doctor
+ * only needs to know whether a value is absent, empty, or the placeholder, so
+ * expansion, multiline values, and `export` prefixes are out of scope. Quotes
+ * are stripped because wrangler accepts them and a quoted placeholder must
+ * still read as a placeholder.
+ */
+function parseDotEnv(text) {
+  const vars = {};
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq < 1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (value.length >= 2 && /^(".*"|'.*')$/s.test(value)) value = value.slice(1, -1);
+    vars[key] = value;
+  }
+  return vars;
+}
+
 function out(s) {
   process.stdout.write(`${s}\n`);
 }
@@ -362,7 +538,7 @@ Usage:
   astroid build    [...astro args]                   regenerate, then run \`astro build\`
   astroid deploy   [--dry-run] [--yes] [--local]     provision bindings + migrate + secrets + deploy
 
-New project:  npm create astroid@latest
+New project:  pnpm create astroid@latest
 `;
 
 async function main() {

package/dist/analytics/index.d.ts

@@ -0,0 +1,37 @@
+import type { AstroidConfig } from "../config.js";
+/** The Analytics Engine dataset binding name. */
+export declare const ASTROID_VITALS_BINDING = "VITALS";
+/** The dataset name, derived from the project key so two Astroid sites on one
+ *  account don't write into the same table. */
+export declare function astroidVitalsDataset(config: AstroidConfig): string;
+/**
+ * Credentials the CWV READ-BACK needs — not the collection.
+ *
+ * The Analytics Engine SQL API is account-scoped and has no binding, so a token
+ * is unavoidable. Both are required together: an account id without a token (or
+ * vice versa) can't query, so partial provisioning reads as dormant exactly like
+ * every other Astroid module.
+ */
+export declare const ASTROID_VITALS_SECRET_NAMES: readonly ["CF_ACCOUNT_ID", "CF_API_TOKEN"];
+/**
+ * The public beacon, as a static `public/vitals.js`.
+ *
+ * A FILE rather than an inline script, and that is a CSP decision, not a style
+ * one: Astro hashes the scripts it processes into `script-src`, and an
+ * `is:inline` script carrying generated content cannot be hashed — it would be
+ * blocked. Served from `public/`, it is same-origin and covered by
+ * `script-src 'self'` with no policy change at all.
+ */
+export declare function generateAstroidVitalsBeacon(config: AstroidConfig, beacon: string): {
+    path: string;
+    contents: string;
+};
+/**
+ * The health scan's CWV read-back, as source for the generated worker.
+ *
+ * Returns `undefined` — so the badge stays "not measured yet" — when the API
+ * credentials aren't set, the query fails, or there is no field data yet. Never
+ * throws: a failed vitals query must not take down the rest of the health scan,
+ * which is mostly cheap COUNTs that have nothing to do with it.
+ */
+export declare function generateAstroidCwvQuery(config: AstroidConfig): string[];