astroidjs 0.1.2 → 0.3.0

package/dist/portal/session.js

@@ -0,0 +1,86 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Resolving the portal session once per request, and guarding mutations.
+//
+// The middleware resolves it (to gate routes) and so does whatever handler runs
+// next (to know who's asking). Both hitting the session store is a wasted D1
+// round-trip on every authenticated request, so the in-flight promise is shared
+// per request via a `WeakMap` — keyed on the `Request`, which means entries
+// disappear with the request rather than needing eviction.
+//
+// `requireCustomer` then adds the check a session alone doesn't give you:
+// same-origin on mutations. A cookie is attached by the browser to any request
+// to this origin, including one a third-party page triggered — so a session
+// proves identity, and the origin check proves intent.
+const inFlight = new WeakMap();
+/**
+ * Resolve the portal session at most once per request.
+ *
+ * Shares the *promise*, not the result, so two callers racing during the same
+ * request both await one lookup rather than starting a second.
+ */
+export function resolvePortalSession(request, resolve) {
+    const existing = inFlight.get(request);
+    if (existing)
+        return existing;
+    // A rejected lookup degrades to signed-out rather than propagating: missing
+    // bindings under plain `astro preview` shouldn't 500 a public page.
+    const promise = resolve(request).catch(() => null);
+    inFlight.set(request, promise);
+    return promise;
+}
+/** JSON response helper — the shape every portal API route returns. */
+export function json(body, status = 200, headers = {}) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json", ...headers },
+    });
+}
+/** Methods that change state, and therefore need the origin check. */
+const MUTATING = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/** True when the request came from this same origin. */
+export function isSameOrigin(request) {
+    const target = new URL(request.url).origin;
+    const origin = request.headers.get("origin");
+    if (origin)
+        return origin === target;
+    // No Origin header: browsers always send one on cross-origin mutations, so
+    // its absence means a same-origin or non-browser caller. Fall back to Referer
+    // when present, and allow otherwise — being stricter would break legitimate
+    // server-to-server callers without stopping a real CSRF, which always carries
+    // an Origin.
+    const referer = request.headers.get("referer");
+    if (referer) {
+        try {
+            return new URL(referer).origin === target;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Guard a portal API handler: a signed-in user, and — on mutations — a
+ * same-origin request.
+ *
+ * ```ts
+ * const guard = await requireCustomer(request, (req) => portalUser(req));
+ * if (!guard.ok) return guard.response;
+ * // guard.user is signed in and this is a same-origin call
+ * ```
+ *
+ * `roles` narrows further, for a route only some portal users may reach.
+ */
+export async function requireCustomer(request, resolve, options = {}) {
+    if (MUTATING.has(request.method) && !isSameOrigin(request)) {
+        return { ok: false, response: json({ ok: false, error: "Forbidden" }, 403) };
+    }
+    const user = await resolvePortalSession(request, resolve);
+    if (!user)
+        return { ok: false, response: json({ ok: false, error: "Unauthorized" }, 401) };
+    if (options.roles?.length && !options.roles.includes(user.role)) {
+        return { ok: false, response: json({ ok: false, error: "Forbidden" }, 403) };
+    }
+    return { ok: true, user };
+}

package/dist/portfolio/index.d.ts

@@ -0,0 +1 @@
+export { generateAstroidGalleryPage } from "./scaffold.js";

package/dist/portfolio/index.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The `portfolio` archetype's scaffold surface.
+export { generateAstroidGalleryPage } from "./scaffold.js";

package/dist/portfolio/scaffold.d.ts

@@ -0,0 +1,9 @@
+import type { AstroidConfig } from "../config.js";
+/**
+ * `src/pages/work.astro` — the portfolio gallery. Null for any other archetype.
+ *
+ * Intrinsic `width`/`height` are carried through deliberately: they feed the
+ * pre-decode layout, so a library with dimensions recorded lays out correctly on
+ * first paint instead of reflowing once the images decode.
+ */
+export declare function generateAstroidGalleryPage(config: AstroidConfig): string | null;

package/dist/portfolio/scaffold.js

@@ -0,0 +1,93 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The `portfolio` archetype's scaffold-once page: a justified gallery over the
+// media library.
+//
+// Scaffold-once, not regenerated, for the usual reason — this is the first file
+// a portfolio site edits (which assets appear, in what order, whether tiles link
+// to a detail page), so `astroid generate` must never rewrite it.
+//
+// It exists because the primitives alone don't finish the job. `<MediaSlot>` and
+// `<JustifiedGallery>` are archetype-agnostic, but the wiring between them and
+// the media registry — the public URL shape, filtering to images, carrying
+// alt/caption and intrinsic dimensions through so the first paint isn't a guess
+// — is identical every time, and is exactly what the consuming sites hand-wrote.
+/**
+ * `src/pages/work.astro` — the portfolio gallery. Null for any other archetype.
+ *
+ * Intrinsic `width`/`height` are carried through deliberately: they feed the
+ * pre-decode layout, so a library with dimensions recorded lays out correctly on
+ * first paint instead of reflowing once the images decode.
+ */
+export function generateAstroidGalleryPage(config) {
+    if (config.archetype !== "portfolio")
+        return null;
+    const mediaBase = config.deploy?.mediaBase ?? "/media";
+    return [
+        "---",
+        "// The work gallery — a justified grid over the media library.",
+        "//",
+        "// Scaffolded once; yours to edit. The layout primitive is general",
+        "// (astroidjs/components/JustifiedGallery.astro); what lives here is this",
+        "// project's own answer to *which* assets appear and in what order.",
+        "//",
+        "// Rows carry `alt`/`caption` from the media registry, so an editor fixes alt",
+        "// text once in the library and every gallery showing that asset picks it up.",
+        "// Assets missing width/height still render — the client corrects the layout",
+        "// once the image decodes — but they cost a visible reflow, so it's worth",
+        "// backfilling dimensions on older uploads.",
+        'import JustifiedGallery from "astroidjs/components/JustifiedGallery.astro";',
+        'import type { GalleryItem } from "astroidjs/components/justify";',
+        'import { env } from "cloudflare:workers";',
+        'import Site from "../layouts/Site.astro";',
+        "",
+        "export const prerender = false;",
+        "",
+        "interface MediaRow {",
+        "  key: string;",
+        "  alt: string | null;",
+        "  caption: string | null;",
+        "  width: number | null;",
+        "  height: number | null;",
+        "}",
+        "",
+        "let rows: MediaRow[] = [];",
+        "try {",
+        "  const result = await env.DB.prepare(",
+        '    "SELECT key, alt, caption, width, height FROM media" +',
+        "      \" WHERE content_type LIKE 'image/%' ORDER BY uploaded_at DESC LIMIT 120\",",
+        "  ).all<MediaRow>();",
+        "  rows = result.results ?? [];",
+        "} catch {",
+        "  // No DB binding yet (pre-provision) — render the empty state.",
+        "}",
+        "",
+        "const items: GalleryItem[] = rows.map((row) => ({",
+        `  src: \`${mediaBase}/\${row.key}\`,`,
+        '  // An asset with no alt gets "" rather than its filename: an empty alt makes',
+        "  // a screen reader skip a decorative tile, while a filename is read aloud",
+        "  // character by character and tells the listener nothing.",
+        '  alt: row.alt ?? "",',
+        "  ...(row.caption ? { caption: row.caption } : {}),",
+        "  ...(row.width ? { width: row.width } : {}),",
+        "  ...(row.height ? { height: row.height } : {}),",
+        "}));",
+        "---",
+        "",
+        '<Site title="Work">',
+        '  <main class="mx-auto max-w-6xl px-6 py-16">',
+        '    <h1 class="text-4xl font-bold">Work</h1>',
+        "    {",
+        "      items.length > 0 ? (",
+        '        <JustifiedGallery items={items} class="mt-8" />',
+        "      ) : (",
+        '        <p class="mt-6 opacity-70">',
+        "          Upload images in the media library and they&apos;ll appear here.",
+        "        </p>",
+        "      )",
+        "    }",
+        "  </main>",
+        "</Site>",
+        "",
+    ].join("\n");
+}

package/dist/project/actions.d.ts

@@ -0,0 +1,3 @@
+import type { AstroidConfig } from "../config.js";
+/** `src/actions/index.ts` — the typed mutation surface, scaffolded once. */
+export declare function generateAstroidActions(config: AstroidConfig): string;

package/dist/project/actions.js

@@ -0,0 +1,121 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// `src/actions/index.ts` — the Astro-native, typed mutation surface (ADR 0001
+// layer 2), beside the framework-agnostic `/api/louise/*` routes.
+//
+// Astroid generated only the route half. That is not a missing convenience: the
+// two entrypoints write the SAME rows, and the whole reason `louise-toolkit/astro`
+// exposes these factories is that each one shares the raw route's store path —
+// `applyFieldSave`, `applySettingsPatch`, `applySaveDraft`. A project that wired
+// its own Actions by hand would get a second write path, and a second write path
+// is where validation, sanitization, and draft-merge semantics drift apart
+// silently (#138).
+//
+// So this file is SCAFFOLD-ONCE and is meant to be added to — the reference site
+// keeps its own bespoke actions right beside these — but the three below come
+// pre-wired against the same tables and the same collection config the generated
+// worker uses.
+/** `src/actions/index.ts` — the typed mutation surface, scaffolded once. */
+export function generateAstroidActions(config) {
+    const customKeys = config.settings?.customKeys ?? [];
+    const extraImageKeys = config.settings?.imageKeys ?? [];
+    const columnsOverride = config.settings?.columns;
+    // Kept in step with the generated worker's settingsRoute: site-specific keys go
+    // to site_settings.custom, extra image keys widen the media-strict set, a
+    // custom-heavy site can override the base columns. Emitted as literals only
+    // when present, so a stock project's Action is unchanged.
+    const settingsExtra = [
+        columnsOverride
+            ? `        columns: ${JSON.stringify(columnsOverride)},`
+            : "        columns: ASTROID_SETTINGS_COLUMNS,",
+        ...(customKeys.length ? [`        customKeys: ${JSON.stringify(customKeys)},`] : []),
+        extraImageKeys.length
+            ? `        imageKeys: [...ASTROID_SETTINGS_IMAGE_KEYS, ...${JSON.stringify(extraImageKeys)}],`
+            : "        imageKeys: ASTROID_SETTINGS_IMAGE_KEYS,",
+    ];
+    return [
+        "// The typed Astro Actions surface — ADR 0001 layer 2.",
+        "//",
+        "// Scaffolded once and yours to ADD to: put your own `defineAction`s in the",
+        "// `server` object below, alongside these.",
+        "//",
+        "// What matters about the three that ship here is that they are NOT a second",
+        "// implementation. Each factory shares the store path of its raw",
+        "// `/api/louise/*` counterpart (`applyFieldSave`, `applySettingsPatch`,",
+        "// `applySaveDraft`), so a field is validated once and written in exactly one",
+        "// place however it was called. Hand-rolling an Action that writes the same",
+        "// row is how sanitization and draft-merge semantics drift apart without",
+        "// anything failing.",
+        'import { ActionError, defineAction } from "astro:actions";',
+        'import { env } from "cloudflare:workers";',
+        "import {",
+        "  louiseSaveAction,",
+        "  louiseSaveDraftAction,",
+        "  louiseSettingsAction,",
+        '} from "louise-toolkit/astro";',
+        "import {",
+        "  ASTROID_SETTINGS_COLUMNS,",
+        "  ASTROID_SETTINGS_IMAGE_KEYS,",
+        "  astroidPagesCollection,",
+        '} from "astroidjs";',
+        'import astroidConfig from "../../astroid.config.js";',
+        'import { pages, pagesVersions, siteSettings } from "../schema.js";',
+        "",
+        "const pagesCollection = astroidPagesCollection(astroidConfig);",
+        "",
+        "// Astro v6+ removed `Astro.locals.runtime.env`, so the bindings are resolved",
+        "// from `cloudflare:workers` — the same env the raw routes read.",
+        "const getEnv = () => env as unknown as CloudflareEnv;",
+        "",
+        "// `getEditor` is left to its default (`locals.editor`), which the generated",
+        "// middleware sets for a signed-in editor. A falsy result answers 401, so these",
+        "// carry the same gate as the routes rather than a parallel one.",
+        "const deps = { ActionError, getEnv };",
+        "",
+        "export const server = {",
+        "  louise: {",
+        "    // Inline field save (title, SEO) — the live, non-versioned path.",
+        "    save: defineAction(",
+        "      louiseSaveAction({",
+        "        ...deps,",
+        "        collections: {",
+        "          pages: {",
+        "            table: pages,",
+        '            fields: ["title", "seoTitle", "seoDescription"],',
+        "          },",
+        "        },",
+        "      }),",
+        "    ),",
+        "",
+        "    // The versioned body/sections save — stages a DRAFT, exactly as",
+        "    // versionsRoute does, through the same `applySaveDraft`.",
+        "    saveDraft: defineAction(",
+        "      louiseSaveDraftAction({",
+        "        ...deps,",
+        "        table: pages,",
+        "        versionsTable: pagesVersions,",
+        "        config: pagesCollection,",
+        "        // The same KV write-buffer the route uses. Both entrypoints coalesce",
+        "        // through one buffer, so an autosave burst is one D1 write however",
+        "        // the client happened to call in.",
+        "        bufferKv: (e) => e.DRAFTS,",
+        "      }),",
+        "    ),",
+        "",
+        "    // The Settings-panel patch (brand, nav, contact, SEO defaults).",
+        "    settings: defineAction(",
+        "      louiseSettingsAction({",
+        "        ...deps,",
+        "        table: siteSettings,",
+        "        // The SAME allowlist the generated worker enforces, imported rather",
+        "        // than copied — a second literal here is a list that drifts from the",
+        "        // one the routes check against, and nothing would fail when it did.",
+        ...settingsExtra,
+        '        mediaBase: astroidConfig.deploy?.mediaBase ?? "/media",',
+        "      }),",
+        "    ),",
+        "  },",
+        "};",
+        "",
+    ].join("\n");
+}

package/dist/project/generate.d.ts

@@ -12,6 +12,21 @@ export interface GeneratedFile {
  * once files (wrangler.jsonc, astro.config, auth.ts) are NOT here by design.
  */
 export declare function generateAstroidProject(config: AstroidConfig): GeneratedFile[];
+/**
+ * The module-secret block `create-astroid` substitutes into `.env.example`.
+ *
+ * Every name is seeded with the placeholder sentinel rather than left empty,
+ * which is the whole trick behind a scaffold that runs with no accounts: the
+ * bindings all EXIST and all read as unconfigured, so each module takes its
+ * dormant path deliberately instead of hitting an undefined-binding error. The
+ * names come from {@link commerceSecretNames}, the same declaration the runtime
+ * gate and the generated `env.d.ts` read.
+ *
+ * Empty string when the project enables no module that needs credentials — the
+ * core secrets (session, Turnstile, mail) are already in the template file, with
+ * their own prose.
+ */
+export declare function generateAstroidSecretsEnv(config: AstroidConfig): string;
 /**
  * Generate a floor `wrangler.jsonc` from the config: the Worker name + editable
  * bindings a baseline Louise site needs (D1, R2 media, the rate-limit + autosave

package/dist/project/generate.js

@@ -14,6 +14,13 @@
 //      them (fills real binding ids, secrets, account). `astroid generate` must
 //      NEVER clobber them, or it would wipe provisioned ids — so they live in a
 //      separate function the regenerate path doesn't call.
+import { ASTROID_VITALS_BINDING, astroidVitalsDataset, } from "../analytics/index.js";
+import { astroidCheckoutVars } from "../commerce/checkout-scaffold.js";
+import { astroidCommerceProviders } from "../commerce/roles.js";
+import { COMMERCE_PROVIDER_SECRETS, COMMERCE_PROVIDER_SETUP, commerceSecretNames, } from "../commerce/secrets.js";
+import { ASTROID_QUEUE_BINDING, astroidCron, astroidCrons, astroidQueueNames, astroidUsesQueues, } from "../queues/messages.js";
+import { ASTROID_EDIT_SESSION_CLASS, ASTROID_REALTIME_BINDING, ASTROID_REALTIME_MIGRATION_TAG, usesRealtime, } from "../realtime/scaffold.js";
+import { ASTROID_SECRET_PLACEHOLDER } from "../secrets.js";
 import { generateAstroidSchema } from "../schema/generate.js";
 import { generateAstroidMiddleware, generateAstroidWorker } from "../worker/generate.js";
 /**
@@ -29,6 +36,43 @@ export function generateAstroidProject(config) {
         { path: "src/middleware.ts", contents: generateAstroidMiddleware(config) },
     ];
 }
+/**
+ * The module-secret block `create-astroid` substitutes into `.env.example`.
+ *
+ * Every name is seeded with the placeholder sentinel rather than left empty,
+ * which is the whole trick behind a scaffold that runs with no accounts: the
+ * bindings all EXIST and all read as unconfigured, so each module takes its
+ * dormant path deliberately instead of hitting an undefined-binding error. The
+ * names come from {@link commerceSecretNames}, the same declaration the runtime
+ * gate and the generated `env.d.ts` read.
+ *
+ * Empty string when the project enables no module that needs credentials — the
+ * core secrets (session, Turnstile, mail) are already in the template file, with
+ * their own prose.
+ */
+export function generateAstroidSecretsEnv(config) {
+    const providers = astroidCommerceProviders(config.commerce);
+    if (providers.length === 0)
+        return "";
+    const lines = [
+        "",
+        "# --- commerce -------------------------------------------------------------",
+        "#",
+        "# Seeded with the DUMMY_REPLACE_ME sentinel, which reads as NOT CONFIGURED.",
+        "# Commerce is dormant until every value below is real: the D1 catalog mirror",
+        "# still serves whatever it last synced, the webhook receiver answers 503 (so",
+        "# the provider retries rather than dropping events), and checkout is",
+        "# simulated. Nothing calls the provider with a placeholder credential.",
+    ];
+    for (const provider of providers) {
+        const spec = COMMERCE_PROVIDER_SECRETS[provider];
+        lines.push("#", `# ${provider}: ${COMMERCE_PROVIDER_SETUP[provider]}`);
+        for (const name of [...spec.credentials, spec.webhook]) {
+            lines.push(`${name}=${ASTROID_SECRET_PLACEHOLDER}`);
+        }
+    }
+    return lines.join("\n");
+}
 // Pinned compatibility date for the emitted Worker. A literal (Astroid's
 // generators are pure — no `Date.now()`), bumped deliberately when the runtime
 // baseline moves; matches the reference site's wrangler.jsonc.
@@ -73,6 +117,50 @@ export function generateAstroidWrangler(config) {
         p("  // No `hosts` in your config → deploys to <name>.workers.dev. Add a");
         p('  // "routes" block with a custom_domain pattern to serve a real domain.');
     }
+    if (usesRealtime(config)) {
+        // The per-page live editing session (ADR 0002). Two halves, and BOTH are
+        // required — a binding with no migration is a deploy error, and the class
+        // must also be exported from the worker entry (the generated src/worker.ts
+        // re-exports it) or wrangler can't resolve `class_name`.
+        p("  // Durable Object: the per-page live editing session (realtime module).");
+        p('  "durable_objects": {');
+        p(`    "bindings": [{ "name": ${JSON.stringify(ASTROID_REALTIME_BINDING)}, "class_name": ${JSON.stringify(ASTROID_EDIT_SESSION_CLASS)} }]`);
+        p("  },");
+        p("  // A DO class needs a migration tag. `new_sqlite_classes` (NOT");
+        p("  // `new_classes`) because the session keeps its authoritative state in");
+        p("  // `ctx.storage`, which is the SQLite-backed store — and the storage");
+        p("  // backend cannot be changed after the class is first deployed.");
+        p("  \"migrations\": [");
+        p(`    { "tag": ${JSON.stringify(ASTROID_REALTIME_MIGRATION_TAG)}, "new_sqlite_classes": [${JSON.stringify(ASTROID_EDIT_SESSION_CLASS)}] }`);
+        p("  ],");
+    }
+    // Crons. ONE `scheduled` handler receives all of them and tells them apart by
+    // `controller.cron`, so this list and the handler's dispatch must agree
+    // exactly — both come from `astroidCrons`, which is why it exists.
+    //
+    // Daily: the site-health scan (broken links, missing alt text, SEO gaps).
+    // Hourly (commerce only): the catalog re-sync safety net, so a missed or DLQ'd
+    // webhook can only leave the site stale until the next tick.
+    p(`  "triggers": { "crons": ${JSON.stringify(astroidCrons(config))} },`);
+    if (astroidUsesQueues(config)) {
+        const { queue, dlq } = astroidQueueNames(config);
+        p("  // Provider webhooks are verified at the edge, then enqueued here so the");
+        p("  // receiver can return fast. Retries + DLQ routing are Cloudflare's, not");
+        p("  // the consumer's — set them here, not in code.");
+        p(`  // Create both: \`wrangler queues create ${queue}\` and \`… ${dlq}\`.`);
+        p('  "queues": {');
+        p(`    "producers": [{ "queue": ${JSON.stringify(queue)}, "binding": ${JSON.stringify(ASTROID_QUEUE_BINDING)} }],`);
+        p('    "consumers": [');
+        p("      {");
+        p(`        "queue": ${JSON.stringify(queue)},`);
+        p(`        "max_batch_size": ${config.queues?.maxBatchSize ?? 10},`);
+        p(`        "max_batch_timeout": ${config.queues?.maxBatchTimeout ?? 30},`);
+        p(`        "max_retries": ${config.queues?.maxRetries ?? 5},`);
+        p(`        "dead_letter_queue": ${JSON.stringify(dlq)},`);
+        p("      },");
+        p("    ],");
+        p("  },");
+    }
     p("  // D1 holds pages / site_settings / media / inquiries (schema in src/schema.ts,");
     p("  // migrations in ./migrations). Create it: `wrangler d1 create <name>`.");
     p('  "d1_databases": [');
@@ -89,20 +177,74 @@ export function generateAstroidWrangler(config) {
     p("  // Cloudflare Images: the media route reads upload dimensions + backs server-");
     p("  // side re-encode. Also @astrojs/cloudflare's production image service.");
     p('  "images": { "binding": "IMAGES" },');
-    p("  // KV: RL = the security rate limiter; DRAFTS = the autosave write-buffer.");
+    p("  // Analytics Engine: real-visitor Core Web Vitals. Free, and the ingest");
+    p("  // route accepts-and-drops without it, so it costs nothing unused. Reading");
+    p("  // the p75 back out needs CF_ACCOUNT_ID + CF_API_TOKEN (see .env.example) —");
+    p("  // until those are real the Health badge reads 'not measured yet'.");
+    p(`  "analytics_engine_datasets": [{ "binding": ${JSON.stringify(ASTROID_VITALS_BINDING)}, "dataset": ${JSON.stringify(astroidVitalsDataset(config))} }],`);
+    p("  // Workers AI. Powers the editor's rewrite + SEO-suggest buttons and alt-text");
+    p("  // generation on upload — all of which SHIP IN THE EDITOR DRAWER already and,");
+    p("  // without this binding, were permanently invisible: their routes answer 503");
+    p("  // and the client hides the button. No account setup beyond the binding, and");
+    p("  // every call is editor-gated, so a visitor can never spend your AI budget.");
+    p('  "ai": { "binding": "AI" },');
+    p("  // KV: RL = the security rate limiter (it also holds the daily site-health");
+    p("  // summary under its own key — one small singleton blob, not worth a binding");
+    p("  // someone has to remember to provision); DRAFTS = the autosave write-buffer.");
     p("  // Create each: `wrangler kv namespace create <RL|DRAFTS>`.");
     p('  "kv_namespaces": [');
     p('    { "binding": "RL", "id": "<run: wrangler kv namespace create RL>" },');
     p('    { "binding": "DRAFTS", "id": "<run: wrangler kv namespace create DRAFTS>" },');
     p("  ],");
+    // Email Sending. NOT optional decoration: `src/env.d.ts` declares EMAIL as a
+    // required member, and Better Auth's magic-link path console-logs the link in
+    // dev but calls `env.EMAIL.send(...)` unconditionally in production. Without
+    // this binding that call is a TypeError on a binding that was never created —
+    // so sign-in was impossible on every DEPLOYED site, while every local build
+    // and every CI scaffold passed. Nothing in this repo runs a deployed scaffold,
+    // which is why it survived.
+    p("  // Cloudflare Email Sending — magic-link sign-in + inquiry notifications.");
+    p("  // Sign-in DEPENDS on this: in production the magic link is emailed, not logged.");
+    p("  // Enable Email Sending for your zone, then verify the address in MAIL_FROM.");
+    p('  "send_email": [{ "name": "EMAIL" }],');
     p("  // Public base for media URLs; same-origin keeps media self-contained. Read off");
     p("  // the runtime env by the framework-agnostic media route, so it stays a `var`.");
     p('  "vars": {');
     p(`    "MEDIA_URL": ${JSON.stringify(mediaBase)},`);
     p(`    "SITE_URL": ${JSON.stringify(primaryHost ? `https://${primaryHost}` : `https://${key}.workers.dev`)},`);
-    p('    // The editor allowlist / owner. Wire this into your auth seam (src/auth.ts).');
+    p("    // The editor allowlist / owner. Wire this into your auth seam (src/auth.ts).");
     p('    "OWNER_EMAIL": "",');
+    p("    // Edge caching for published pages (ADR 0004). OFF by default, and the");
+    p("    // default is the safe state: with it off every render is `no-store` and");
+    p("    // the Worker cache layer stores nothing.");
+    p("    //");
+    p("    // Turn it on for a PREVIEW deploy first and walk the activation runbook");
+    p("    // (docs/adr/0004-edge-caching.md). `caches.default` is not cleared by");
+    p("    // Cloudflare Dev Mode or Purge Everything, so a bad prod flip is hard to");
+    p("    // undo — this feature was reverted twice for exactly that.");
+    p('    "ASTROID_EDGE_CACHE": "false",');
+    for (const v of astroidCheckoutVars(config)) {
+        // Public, not secret — the app id ships to the browser to mount the card
+        // field, and the environment is a choice. Keeping them out of the secret
+        // roster also keeps them out of the dormancy gate, which asks whether we can
+        // safely CALL Square, not whether a card field can render.
+        p(`    ${JSON.stringify(v.name)}: ${JSON.stringify(v.value)},`);
+    }
     p("  },");
+    // Secrets are NOT vars: they belong in .dev.vars locally and in `wrangler
+    // secret put` / Secrets Store when deployed. Listing the names here is
+    // deliberate — this is the file someone opens when provisioning, and the list
+    // is generated from the same declaration the runtime dormancy gate reads.
+    const secretNames = commerceSecretNames(config.commerce);
+    if (secretNames.length > 0) {
+        p("  // Commerce secrets — set OUTSIDE this file (it's committed):");
+        p("  //   local:    .dev.vars (see .env.example, seeded with DUMMY_REPLACE_ME)");
+        p("  //   deployed: `wrangler secret put <NAME>`, or a Secrets Store binding");
+        p("  // Until each is real, commerce stays dormant: the D1 mirror serves, the");
+        p("  // webhook receiver answers 503, and nothing calls the provider.");
+        for (const name of secretNames)
+            p(`  //   ${name}`);
+    }
     p('  "observability": { "enabled": true },');
     p("}");
     p();

package/dist/project/index.d.ts

@@ -1 +1,3 @@
 export * from "./generate.js";
+export * from "./actions.js";
+export * from "./scaffold.js";

package/dist/project/index.js

@@ -3,3 +3,5 @@
 // Project generation — config → the files the `astroid` CLI writes (the
 // regenerated schema/worker/middleware trio + the scaffold-once wrangler.jsonc).
 export * from "./generate.js";
+export * from "./actions.js";
+export * from "./scaffold.js";

package/dist/project/scaffold.d.ts

@@ -0,0 +1,29 @@
+import type { AstroidConfig } from "../config.js";
+/**
+ * A file written once, then owned by the project.
+ *
+ * `apply` is the whole contract. `"skip"` (the default) leaves an existing file
+ * alone. `"append-once"` is for the files a project accumulates into rather than
+ * owns outright — `public/_headers` gets a stanza per module, and a second
+ * module must not erase the first one's.
+ */
+export interface ScaffoldFile {
+    /** Path relative to the project root, POSIX-separated. */
+    path: string;
+    contents: string;
+    /** What to do when the path already exists. Default `"skip"`. */
+    apply?: "skip" | "append-once";
+    /**
+     * For `"append-once"`: a substring that proves this stanza is already there.
+     * Without it a re-run would append a duplicate every time.
+     */
+    marker?: string;
+}
+/**
+ * Every scaffold-once file this config implies.
+ *
+ * Ordered by module so a `generate` that writes several prints them in a stable
+ * sequence. Returns `[]` for a plain marketing site with no modules — the
+ * baseline floor is entirely the regenerated trio plus the static template.
+ */
+export declare function generateAstroidScaffoldFiles(config: AstroidConfig): ScaffoldFile[];