create-astroid 0.1.2 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@ Scaffold a new **Astroid** site — an editable, multi-editor Astro app on
 Cloudflare Workers — in one command.
 
 ```sh
-npm create astroid my-site
+pnpm create astroid my-site
 ```
 
 > **Status: pre-1.0, experimental.** The scaffold's output will change between
@@ -28,7 +28,7 @@ Anything you don't pass is prompted for. In a non-TTY every prompt takes its
 default, so the command is CI-safe. The target directory must be empty.
 
 ```
-npm create astroid [directory] [options]
+pnpm create astroid [directory] [options]
 
   --dir <path>          Target directory (also the first positional)
   --name <name>         Brand / site name
@@ -36,6 +36,15 @@ npm create astroid [directory] [options]
   --archetype <type>    marketing | storefront | wholesale | portfolio
   --color <hex>         Brand color
   --host <domain>       Primary domain, e.g. example.com
+  --commerce <provider> square | stripe | fourthwall — also adds the queue
+                        consumer, webhook receiver, and cron safety net
+  --map                 Self-hosted PMTiles/MapLibre location map
+  --pwa                 Installable PWA: a scoped service worker that never
+                        caches /api/* or the editor, plus a manifest
+  --portal              Customer/member portal: a second, isolated auth
+                        instance plus role-gated routes
+  --realtime            Live multi-editor editing: a per-page Durable Object
+                        with presence, field sync, and a rich-text soft-lock
   -h, --help            Show help
   -v, --version         Show the version
 ```
@@ -44,13 +53,13 @@ npm create astroid [directory] [options]
 
 ```sh
 cd my-site
-npm install
-npx wrangler d1 create <name>      # then paste the ids into wrangler.jsonc
-npm run doctor                     # validates config, bindings, generated files
-npm run dev
+pnpm install
+pnpm exec wrangler d1 create <name>   # then paste the ids into wrangler.jsonc
+pnpm doctor                           # validates config, bindings, generated files
+pnpm dev
 ```
 
-`npm run doctor` flags any binding id you haven't filled in yet, plus generated
+`pnpm doctor` flags any binding id you haven't filled in yet, plus generated
 files that have drifted from the config.
 
 ## How the pieces relate

package/index.mjs

@@ -3,8 +3,8 @@
 //
 // `create-astroid` — scaffold a new Astroid site in one command:
 //
-//   npm create astroid@latest my-site
-//   npm create astroid@latest my-site -- --key coracle --name "Coracle Coffee" --color "#1f6f78" --host coracle.coffee
+//   pnpm create astroid@latest my-site
+//   pnpm create astroid@latest my-site --key coracle --name "Coracle Coffee" --color "#1f6f78" --host coracle.coffee
 //
 // It writes the floor: the `defineAstroid` config, the generated
 // schema/worker/middleware trio + wrangler.jsonc (via astroidjs), the Better Auth
@@ -14,10 +14,23 @@
 // uses, so a fresh project is already in sync.
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
 import { basename, dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
-import { defineAstroid, generateAstroidProject, generateAstroidWrangler } from "astroidjs";
+import {
+  ASTROID_ARCHETYPE_SECTIONS,
+  ASTROID_MAP_DEPENDENCIES,
+  defineAstroid,
+  generateAstroidEnvBindings,
+  generateAstroidPortalLocals,
+  generateAstroidProject,
+  generateAstroidCheckoutEnv,
+  generateAstroidRealtimeEnv,
+  generateAstroidScaffoldFiles,
+  generateAstroidSecretsEnv,
+  generateAstroidWrangler,
+} from "astroidjs";
 
 const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), "template");
 
@@ -25,15 +38,19 @@ const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), "template");
 // published package, so they ship as `_gitignore` / `_env.example`).
 const DOTFILE_RENAMES = { _gitignore: ".gitignore", "_env.example": ".env.example" };
 
-// Archetype → default editable home sections, when the user doesn't override.
-const ARCHETYPE_SECTIONS = {
-  marketing: ["hero", "featureGrid", "cta", "contact"],
-  storefront: ["hero", "marquee", "featured", "productGrid", "visit", "contact"],
-  wholesale: ["hero", "featureGrid", "story", "contact"],
-  portfolio: ["hero", "gallery", "story", "contact"],
-};
+// Archetype → default editable home sections. Imported from astroidjs rather
+// than duplicated here: as a literal in this file it could name a section that
+// doesn't exist and nothing would say so (it did — `marquee`, `featured`,
+// `story`, and `visit` had no component for months). Over there it's typed
+// against the section catalog, so a stale name fails the build. See #277.
+const ARCHETYPE_SECTIONS = ASTROID_ARCHETYPE_SECTIONS;
 const ARCHETYPES = Object.keys(ARCHETYPE_SECTIONS);
 
+// Commerce backends astroidjs knows how to wire (webhook verifier + catalog
+// event filter). Opt-in via `--commerce`; it also switches on the queue
+// consumer, the webhook receiver, and the cron safety net.
+const COMMERCE_PROVIDERS = ["square", "stripe", "fourthwall"];
+
 // --- args ------------------------------------------------------------------
 function parseArgs(argv) {
   const flags = {};
@@ -53,6 +70,51 @@ function parseArgs(argv) {
 const slugify = (s) =>
   s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
 
+// --- toolkit versions ------------------------------------------------------
+
+/**
+ * The `astroidjs` + `louise-toolkit` ranges to write into the scaffold.
+ *
+ * DERIVED from this package's own resolved dependencies rather than hard-coded
+ * in template/package.json. A literal there is a second place to remember on
+ * every release, and when it rots the failure is silent and total: the template
+ * imported `astroidjs/astro` while pinning `^0.1.0`, a range whose newest match
+ * had no such export, so every scaffolded project died before Astro loaded its
+ * config. CI could not see it — the clean-room smoke test pins both packages to
+ * tarballs via pnpm `overrides`, which is exactly what erases these ranges.
+ *
+ * `pnpm pack` rewrites `workspace:*` to the concrete version, so in a PUBLISHED
+ * create-astroid the declared dep is already exact and we just widen it to a
+ * caret. Run from the workspace it is still `workspace:*`, so fall back to the
+ * version of the copy actually resolved on disk — which is what the scaffold
+ * would install anyway.
+ *
+ * Caret on a 0.x is minor-locked (`^0.2.0` := `>=0.2.0 <0.3.0`), which is the
+ * behaviour we want while the toolkit is pre-1.0 and marks breaking changes as
+ * minors: patches flow, a breaking minor does not.
+ */
+function toolkitRanges() {
+  const req = createRequire(import.meta.url);
+  const self = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));
+  const ranges = {};
+  for (const name of ["astroidjs", "louise-toolkit"]) {
+    const declared = self.dependencies?.[name];
+    let version = declared && !declared.startsWith("workspace:") ? declared : undefined;
+    if (!version) {
+      // Both packages export `./package.json`, so this resolves the real copy.
+      version = JSON.parse(readFileSync(req.resolve(`${name}/package.json`), "utf8")).version;
+    }
+    if (!version) {
+      throw new Error(
+        `create-astroid could not determine the ${name} version to scaffold with. ` +
+          "This is a packaging fault — please file an issue rather than editing the scaffold by hand.",
+      );
+    }
+    ranges[name] = `^${version}`;
+  }
+  return ranges;
+}
+
 async function prompt(question, fallback) {
   if (!process.stdin.isTTY) return fallback;
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -100,6 +162,19 @@ function astroidConfigSource(config) {
     `    colors: { brand: ${JSON.stringify(config.theme.colors.brand)} },`,
     "  },",
     `  sections: ${JSON.stringify(config.sections)},`,
+    ...(config.commerce
+      ? [`  commerce: { provider: ${JSON.stringify(config.commerce.provider)} },`]
+      : []),
+    // Must be emitted, for the same reason the portal is: `astroid generate`
+    // rebuilds the middleware and CSP from THIS file, so a config that dropped
+    // `modules` would regenerate a project missing whatever they contribute —
+    // for the map, a policy without `worker-src blob:`, which renders an empty
+    // canvas with no obvious cause.
+    ...(config.modules?.length ? [`  modules: ${JSON.stringify(config.modules)},`] : []),
+    // Must be emitted: `astroid generate` rebuilds the middleware from THIS
+    // file, so a config that omitted the portal would regenerate a middleware
+    // with no guard while src/portal-auth.ts sat there unused.
+    ...(config.portal?.enabled ? ["  portal: { enabled: true },"] : []),
     '  deploy: { platform: "cloudflare" },',
     "});",
     "",
@@ -116,7 +191,7 @@ function write(destDir, relPath, contents) {
 const USAGE = `Scaffold a new Astroid site — an editable Astro app on Cloudflare Workers.
 
 Usage:
-  npm create astroid [directory] [options]
+  pnpm create astroid [directory] [options]
 
 Options:
   --dir <path>          Target directory (also accepted as the first positional)
@@ -125,6 +200,15 @@ Options:
   --archetype <type>    ${ARCHETYPES.join(" | ")}   (default: marketing)
   --color <hex>         Brand color (default: #5b4bff)
   --host <domain>       Primary domain, e.g. example.com
+  --commerce <provider> ${COMMERCE_PROVIDERS.join(" | ")}
+                        Also adds the queue consumer, webhook receiver, and cron
+  --map                 Add the self-hosted PMTiles/MapLibre location map
+  --pwa                 Add an installable PWA: a scoped service worker that
+                        never caches /api/* or the editor, plus a manifest
+  --realtime            Add live multi-editor editing: a per-page Durable Object
+                        with presence, field sync, and a rich-text soft-lock
+  --portal              Add a customer/member portal: a second, isolated auth
+                        instance plus role-gated routes
   -h, --help            Show this help
   -v, --version         Show the create-astroid version
 
@@ -159,6 +243,33 @@ async function main() {
   const archetype = ARCHETYPES.includes(archetypeRaw) ? archetypeRaw : "marketing";
   const color = flags.color || (await prompt("Brand color (hex)", "#5b4bff"));
   const host = flags.host && flags.host !== true ? flags.host : undefined;
+  // Portal + commerce are opt-in and unprompted: each pulls in real
+  // infrastructure a plain marketing site should not carry.
+  const portal = flags.portal === true || flags.portal === "true";
+  // The map module is opt-in and pulls real weight (maplibre-gl is ~1 MB), so
+  // it is never on by default.
+  const map = flags.map === true || flags.map === "true";
+  // Opt-in: a service worker is a caching layer over a CMS-edited site, so it
+  // is never on unless asked for.
+  const pwa = flags.pwa === true || flags.pwa === "true";
+  // Opt-in: realtime provisions a Durable Object, which is real infrastructure a
+  // single-editor site has no use for.
+  const realtime = flags.realtime === true || flags.realtime === "true";
+  const modules = [
+    ...(map ? ["map"] : []),
+    ...(pwa ? ["pwa"] : []),
+    ...(realtime ? ["realtime"] : []),
+  ];
+  // Commerce is opt-in and unprompted: it pulls in a queue consumer, a webhook
+  // receiver, and a cron, none of which a plain marketing site should carry.
+  const commerceRaw = typeof flags.commerce === "string" ? flags.commerce.toLowerCase() : undefined;
+  const commerce = COMMERCE_PROVIDERS.includes(commerceRaw) ? commerceRaw : undefined;
+  if (commerceRaw && !commerce) {
+    process.stderr.write(
+      `create-astroid: unknown --commerce provider "${commerceRaw}" (expected ${COMMERCE_PROVIDERS.join(" | ")})\n`,
+    );
+    process.exit(1);
+  }
 
   if (existsSync(dir) && readdirSync(dir).length > 0) {
     process.stderr.write(`create-astroid: target directory is not empty: ${dir}\n`);
@@ -172,21 +283,72 @@ async function main() {
     ...(host ? { hosts: [host] } : {}),
     theme: { name, colors: { brand: color } },
     sections: ARCHETYPE_SECTIONS[archetype],
+    ...(commerce ? { commerce: { provider: commerce } } : {}),
+    ...(portal ? { portal: { enabled: true } } : {}),
+    // ONE array, built from every enabled flag. Two separate `...(x ? {modules}
+    // : {})` spreads would let the later one overwrite the earlier, silently
+    // dropping a module whenever both were passed.
+    ...(modules.length > 0 ? { modules } : {}),
     deploy: { platform: "cloudflare" },
   });
 
   const siteUrl = host ? `https://${host}` : `https://${key}.workers.dev`;
+  const envBindings = generateAstroidEnvBindings(config);
+  const portalLocals = generateAstroidPortalLocals(config);
+  // The realtime DO namespace, or nothing — same rule as the queue bindings: a
+  // declaration is a promise, so never type a binding wrangler.jsonc won't create.
+  const realtimeEnv = generateAstroidRealtimeEnv(config);
+  // The Square Web Payments public vars, or nothing.
+  const checkoutEnv = generateAstroidCheckoutEnv(config);
   const tokens = {
     KEY: key,
     BRAND_NAME: name,
     BRAND_COLOR: color,
     ARCHETYPE: archetype,
     SITE_URL: siteUrl,
+    // Extra CloudflareEnv members the queue pipeline needs, or nothing. A
+    // declaration is a promise — a marketing site must not claim a binding its
+    // wrangler.jsonc never creates.
+    ASTROID_ENV_BINDINGS: [envBindings, realtimeEnv, checkoutEnv].filter(Boolean).join("\n")
+      ? `\n${[envBindings, realtimeEnv, checkoutEnv].filter(Boolean).join("\n")}`
+      : "",
+    // The portal session on App.Locals, or nothing — a project that types a
+    // local it never sets invites a null-check nobody needs.
+    ASTROID_PORTAL_LOCALS: portalLocals ? `\n${portalLocals}` : "",
+    // Placeholder-seeded secrets for whichever modules this project enabled, so
+    // a fresh clone has a COMPLETE binding set that all reads as unconfigured —
+    // every module takes its dormant path deliberately rather than tripping over
+    // an undefined binding. Empty for a project with no credentialed module.
+    ASTROID_MODULE_SECRETS: generateAstroidSecretsEnv(config),
   };
 
   // 1. The static floor (Astro app, auth seam, config files) with tokens filled.
   copyTemplate(TEMPLATE_DIR, dir, tokens);
 
+  // 1b. Toolkit versions + module dependencies, merged into the copied package.json.
+  //
+  //     Merged by PARSING the file rather than substituting a token into it:
+  //     a `__TOKEN__` inside a JSON object makes template/package.json invalid
+  //     JSON, and everything that scans a repo for manifests — Snyk, Dependabot,
+  //     editors, workspace tooling — parses it and fails. (It did.)
+  //
+  //     The `astroidjs` / `louise-toolkit` ranges are DERIVED (see
+  //     `toolkitRanges`), never taken from template/package.json — a hand-written
+  //     range there silently rots into a scaffold that can't build. The literals
+  //     it still carries are placeholders that keep the file valid JSON.
+  //
+  //     Only the enabled modules contribute the rest: nobody installs a megabyte
+  //     of mapping library for a site with no map.
+  const extraDeps = { ...toolkitRanges(), ...(map ? ASTROID_MAP_DEPENDENCIES : {}) };
+  {
+    const pkgPath = join(dir, "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    pkg.dependencies = Object.fromEntries(
+      Object.entries({ ...pkg.dependencies, ...extraDeps }).sort(([a], [b]) => a.localeCompare(b)),
+    );
+    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  }
+
   // 2. The typed config the generators + the app read.
   write(dir, "astroid.config.ts", astroidConfigSource(config));
 
@@ -194,6 +356,31 @@ async function main() {
   for (const file of generateAstroidProject(config)) write(dir, file.path, file.contents);
   write(dir, "wrangler.jsonc", generateAstroidWrangler(config));
 
+  // 3b. Every scaffold-once module file this config implies — the queue seam and
+  //     webhook receivers, the portfolio gallery page, the PWA service worker +
+  //     manifest + headers, the map tile route + embed, the portal's second auth
+  //     instance and its mounted catch-all.
+  //
+  //     ONE list, imported from astroidjs, because `astroid generate` writes the
+  //     same files when a config gains a module after scaffold. Hand-listing them
+  //     here was the only way to produce them, so editing the config — the entire
+  //     premise of the framework — regenerated a trio importing `./queue.js` and
+  //     `./portal-auth.js` that nothing had written, and `astroid doctor` called
+  //     it healthy. Sharing the list is what keeps the two paths honest.
+  for (const file of generateAstroidScaffoldFiles(config)) {
+    if (file.apply === "append-once") {
+      // `public/_headers` accumulates a stanza per module rather than being owned
+      // by one, so append instead of overwriting a sibling module's block.
+      const abs = join(dir, file.path);
+      mkdirSync(dirname(abs), { recursive: true });
+      const current = existsSync(abs) ? readFileSync(abs, "utf8") : "";
+      if (file.marker && current.includes(file.marker)) continue;
+      writeFileSync(abs, current + file.contents);
+      continue;
+    }
+    write(dir, file.path, file.contents);
+  }
+
   // 4. The Better Auth migration (louise-toolkit) — auth tables are fenced out of
   //    drizzle-kit, so they're generated rather than diffed from schema.ts. Loaded
   //    dynamically: it pulls in `better-auth` (an optional peer), which may not be
@@ -202,14 +389,40 @@ async function main() {
   let authMigrationOk = false;
   try {
     const { generateAuthSchemaSql } = await import("louise-toolkit/auth");
-    write(dir, "migrations/0001_auth.sql", generateAuthSchemaSql());
+    // The EDITOR instance's tables — `louise_`-prefixed (the editor convention),
+    // leaving the unprefixed `user`/`session` names free for a second/portal
+    // instance. Must match the `tablePrefix` in src/auth.ts and the `louise_user`
+    // table the generated `editorsRoute` reads.
+    write(dir, "migrations/0001_auth.sql", generateAuthSchemaSql({ tablePrefix: "louise_" }));
+    // The portal's own auth tables. A SECOND set, prefixed — the two instances
+    // share one D1 but never a row, so a portal account can't sign into the
+    // studio and an editor doesn't appear in the portal. Without this migration
+    // the portal builds fine and fails on the first sign-in.
+    if (config.portal?.enabled) {
+      write(
+        dir,
+        "migrations/0002_portal_auth.sql",
+        generateAuthSchemaSql({ tablePrefix: "portal_" }),
+      );
+    }
     authMigrationOk = true;
   } catch {
     write(
       dir,
       "migrations/0001_auth.sql",
-      "-- Better Auth tables — generate after install:\n--   npx louise gen-auth-schema --out migrations/0001_auth.sql\n",
+      "-- Better Auth tables (editor, louise_ prefix) — generate after install:\n--   pnpm exec louise gen-auth-schema --table-prefix louise_ --out migrations/0001_auth.sql\n",
     );
+    // Same stub for the portal's prefixed set. Without it a portal scaffold
+    // looks complete, builds, and fails on the first sign-in with a missing
+    // table — the one failure mode a stub exists to prevent.
+    if (config.portal?.enabled) {
+      write(
+        dir,
+        "migrations/0002_portal_auth.sql",
+        "-- Portal Better Auth tables (prefixed) — generate after install:\n" +
+          "--   pnpm exec louise gen-auth-schema --table-prefix portal_ --out migrations/0002_portal_auth.sql\n",
+      );
+    }
   }
 
   const rel = dir === process.cwd() ? "." : basename(dir);
@@ -221,12 +434,32 @@ async function main() {
       "Next steps:",
       `  cd ${rel}`,
       "  pnpm install",
+      // The auth-migration fallback belongs HERE, in sequence, not in a note
+      // printed after the list. It has to run before `d1 migrations apply`, and
+      // a correction that appears below an ordered list is a correction most
+      // people execute the list without reading: the stub left no `user` table,
+      // so `seed:editors` failed with `no such table: user` and the very first
+      // instruction anyone follows was the one that broke.
+      ...(authMigrationOk
+        ? []
+        : [
+            "  # generate the Better Auth migration (it could not be written at scaffold",
+            "  # time — `louise` is on your path once the install above finishes):",
+            "  pnpm exec louise gen-auth-schema --table-prefix louise_ --out migrations/0001_auth.sql",
+            ...(config.portal?.enabled
+              ? [
+                  "  pnpm exec louise gen-auth-schema --table-prefix portal_ \\",
+                  "    --out migrations/0002_portal_auth.sql",
+                ]
+              : []),
+          ]),
       "  # provision the Cloudflare bindings, then fill the ids in wrangler.jsonc:",
       "  wrangler d1 create " + key,
       "  wrangler r2 bucket create " + key + "-media",
       "  wrangler kv namespace create RL && wrangler kv namespace create DRAFTS",
-      "  # apply migrations + seed your first editor:",
+      "  # apply migrations, seed the home page + your first editor:",
       "  wrangler d1 migrations apply DB --remote",
+      "  wrangler d1 execute DB --remote --file seed/home.seed.sql",
       "  OWNER_EMAIL=you@example.com pnpm seed:editors",
       "  # develop / ship:",
       "  pnpm dev            # astroid dev (regenerates, then astro dev)",
@@ -237,8 +470,8 @@ async function main() {
   );
   if (!authMigrationOk) {
     process.stdout.write(
-      "Note: generate the Better Auth migration after install:\n" +
-        "  npx louise gen-auth-schema --out migrations/0001_auth.sql\n\n",
+      "Note: the Better Auth migration is a stub — the `gen-auth-schema` step above\n" +
+        "fills it in. Skipping it leaves no `user` table, and `seed:editors` will fail.\n\n",
     );
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astroid",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Scaffold a new Astroid site — an editable, multi-editor Astro app on Cloudflare Workers — in one command.",
   "keywords": [
     "astro",
@@ -30,8 +30,10 @@
     "access": "public"
   },
   "dependencies": {
-    "astroidjs": "0.1.2",
-    "louise-toolkit": "0.15.0"
+    "@better-auth/passkey": "^1.6.23",
+    "better-auth": "^1.6.23",
+    "louise-toolkit": "0.17.0",
+    "astroidjs": "0.3.0"
   },
   "engines": {
     "node": ">=24.0.0"

package/template/README.md

@@ -16,6 +16,12 @@ cp .env.example .dev.vars   # local secrets for `astro dev`; fill SESSION_SECRET
 pnpm dev                    # astroid dev: regenerate, then astro dev
 ```
 
+> **Previewing the built worker?** `pnpm dev` (astro dev) serves on localhost, so
+> an empty `SESSION_SECRET` is fine there. A local `wrangler dev` against the
+> built `dist/` output routes the request through your `hosts` domain instead of
+> localhost, so the editor routes need a real `SESSION_SECRET` in `.dev.vars` —
+> otherwise sign-in 500s with "SESSION_SECRET is not configured".
+
 ## Deploy
 
 Astroid wrote `wrangler.jsonc` with placeholder binding ids. Pick a path to
@@ -58,6 +64,10 @@ wrangler d1 execute DB --file seed/home.seed.sql --remote
 OWNER_EMAIL=you@example.com pnpm seed:editors
 ```
 
+The seeded page renders immediately. In-editor **search** indexes on publish, so
+a raw-SQL-seeded row isn't searchable until you publish an edit or backfill once
+with `POST /api/louise/pages/reindex` (signed in).
+
 ## Editors & auth
 
 Editors sign in with a magic link (passkeys supported). The allowlist is

package/template/_env.example

@@ -1,7 +1,22 @@
 # Local dev secrets (wrangler reads .dev.vars; copy this there for `astro dev`).
 # In production these are set with `wrangler secret put`, NOT committed.
+#
+# Astroid's convention: an unprovisioned secret leaves its feature DORMANT, never
+# broken. A secret that is empty — or still holds the DUMMY_REPLACE_ME sentinel —
+# reads as "not configured", so a fresh clone boots and runs with no external
+# accounts at all. Replace a value to switch that feature on.
 
 # Signs Better Auth sessions. Generate: `openssl rand -base64 32`.
+#
+# Empty is fine under `pnpm dev` — astro dev serves on localhost, where a fixed
+# dev secret keeps the sign-in → session loop working. Any deployed host fails
+# closed rather than signing sessions with a known value.
+#
+# BUT a local `wrangler dev` preview of the BUILT worker is not localhost as far
+# as the app is concerned: wrangler routes the request through your `hosts`
+# domain (astroid.config.ts), so the dev fallback never fires and every editor
+# route 500s with "SESSION_SECRET is not configured". Set a value here before
+# previewing the built worker that way.
 SESSION_SECRET=
 
 # The first editor's email — seeded as an admin `user` row by `pnpm seed:editors`,
@@ -10,3 +25,24 @@ OWNER_EMAIL=you@example.com
 
 # `from` address for magic-link + notification email (Cloudflare Email Sending).
 MAIL_FROM=no-reply@__KEY__.example
+
+# Turnstile captcha on the magic-link endpoint. Dormant as shipped: the sentinel
+# secret below plus Cloudflare's always-passing TEST site key. Captcha only
+# enforces once BOTH are real — provisioning one half can't lock you out of your
+# own sign-in. Get a real pair at dash.cloudflare.com → Turnstile.
+TURNSTILE_SECRET=DUMMY_REPLACE_ME
+TURNSTILE_SITE_KEY=1x00000000000000000000AA
+__ASTROID_MODULE_SECRETS__
+
+# --- web vitals -----------------------------------------------------------
+#
+# ONLY needed to read Core Web Vitals back out. Collection works without them:
+# the beacon posts to /api/louise/vitals and the Worker writes to the Analytics
+# Engine dataset regardless. Querying the p75 back out goes through the SQL API,
+# which is account-scoped and has no binding — hence a token.
+#
+# Left as the sentinel, the daily health scan simply skips the query and the
+# Health panel shows "not measured yet". Create a token with Account
+# Analytics:Read at dash.cloudflare.com → My Profile → API Tokens.
+CF_ACCOUNT_ID=DUMMY_REPLACE_ME
+CF_API_TOKEN=DUMMY_REPLACE_ME

package/template/astro.config.mjs

@@ -1,8 +1,11 @@
 // @ts-check
 import cloudflare from "@astrojs/cloudflare";
+import { cacheCloudflare } from "@astrojs/cloudflare/cache";
 import solid from "@astrojs/solid-js";
 import tailwindcss from "@tailwindcss/vite";
+import { ASTROID_VITE_BUILD, astroidSecurity } from "astroidjs/astro";
 import { defineConfig } from "astro/config";
+import astroidConfig from "./astroid.config.ts";
 
 // SSR (`output: server`) because Louise renders per-request edit affordances and
 // reads pages from D1. Solid islands power the editor UI (ADR 0001). Tailwind v4 +
@@ -14,17 +17,31 @@ export default defineConfig({
   output: "server",
   adapter: cloudflare(),
   integrations: [solid()],
-  vite: { plugins: [tailwindcss()] },
-  // Content-Security-Policy. Astro hashes every processed script + style and emits
-  // a `content-security-policy` response header on on-demand (SSR) pages — which is
-  // all of ours. The generated src/middleware.ts (createLouiseMiddleware) then
-  // rewrites `style-src` to `'self' 'unsafe-inline'` so Louise's data-driven
-  // `style=""` carriers and the editor's runtime-injected <style> are allowed, and
-  // permits the inlined `data:` brand font. This is why the inline scripts here
-  // (login.astro, LouiseEdit.astro) avoid is:inline/define:vars — those can't be
-  // hashed and would be blocked.
+  vite: {
+    plugins: [tailwindcss()],
+    build: { ...ASTROID_VITE_BUILD },
+  },
+  // Route caching (ADR 0004). This provider is what turns `Astro.cache.set(...)`
+  // into a `Cloudflare-CDN-Cache-Control` header — which the generated worker's
+  // `withEdgeCache` layer reads as its "store this" signal and then STRIPS, so
+  // Cloudflare's own cookie-blind edge cache never sees it.
   //
-  // Using Square Web Payments? Allow its SDK host in script-src:
-  //   security: { csp: { scriptDirective: { resources: ["'self'", "https://web.squarecdn.com"] } } }
-  security: { csp: true },
+  // Opt-in per response: a route that never calls `Astro.cache.set` (or calls
+  // `set(false)`, as an edit-mode render does) goes out `no-store`. Nothing
+  // personalized is ever cached. Published pages opt in from index.astro, gated
+  // on the ASTROID_EDGE_CACHE var — which is "false" until you have walked the
+  // activation runbook on a preview deploy.
+  cache: { provider: cacheCloudflare() },
+  // Content-Security-Policy, composed by Astroid from your config: it derives the
+  // allowed origins from the modules you enabled (commerce provider SDKs,
+  // captcha) and adds the hash of Solid's hydration bootstrap, which Astro does
+  // not hash itself. Astro owns `script-src` (every script it processes is
+  // hashed, so no 'unsafe-inline'); the generated src/middleware.ts rewrites only
+  // `style-src`, because Louise's data-driven `style=""` carriers need
+  // 'unsafe-inline' and a hash in that directive would void it.
+  //
+  // This is why the inline scripts here (login.astro, LouiseEdit.astro) avoid
+  // is:inline/define:vars — those can't be hashed and would be blocked. Need
+  // another origin? Add it to `security.cspOrigins` in astroid.config.ts.
+  security: astroidSecurity(astroidConfig),
 });

package/template/package.json

@@ -16,11 +16,14 @@
     "@astrojs/cloudflare": "^14.1.3",
     "@astrojs/solid-js": "^7.0.1",
     "@better-auth/passkey": "^1.6.23",
+    "@prosekit/pm": "^0.1.18",
+    "@tanstack/solid-query": "^5.101.2",
     "astro": "^7.0.9",
-    "astroidjs": "^0.1.0",
+    "astroidjs": "0.0.0-replaced-at-scaffold",
     "better-auth": "^1.6.23",
     "drizzle-orm": "^0.45.2",
-    "louise-toolkit": "^0.14.0",
+    "louise-toolkit": "0.0.0-replaced-at-scaffold",
+    "prosekit": "^0.21.4",
     "solid-js": "^1.9.14",
     "zod": "^4.4.3"
   },

package/template/pnpm-workspace.yaml

@@ -0,0 +1,38 @@
+# pnpm configuration for this project.
+#
+# Not a workspace — pnpm 10+ reads its settings from THIS file even for a single
+# package, and `overrides` in package.json is silently ignored.
+
+# Postinstall-script approvals. Without these `pnpm install` FAILS outright with
+# ERR_PNPM_IGNORED_BUILDS, because pnpm refuses to run a dependency's build
+# script until you say so — and esbuild and workerd both need theirs. A scaffold
+# whose very first documented command errors is not a scaffold.
+#
+# `sharp: false` denies its heavy native build on purpose. Nothing here imports
+# it: image work goes through the Cloudflare Images binding and the adapter's
+# workerd image service. It arrives only as an OPTIONAL dependency of astro, so
+# denying it skips the build rather than prompting on every install.
+allowBuilds:
+  esbuild: true
+  workerd: true
+  sharp: false
+
+# Two advisories, both reaching a scaffold through `better-auth`'s dev-tooling
+# transitives. Neither shows up in `pnpm audit` (GitHub's DB); Snyk carries them.
+#
+# esbuild — SNYK-JS-ESBUILD-17750822, "resources downloaded over insecure
+# protocol", CVSS 9.2, fixed in 0.28.1. Two paths reach a vulnerable copy:
+# drizzle-kit's own `esbuild ^0.25.4`, and the deprecated `@esbuild-kit/esm-loader`
+# it still ships (whose core-utils pins 0.18.20) — so this is blanket rather than
+# scoped to one parent. Astro and Vite already want 0.28.x, so it unifies the tree
+# rather than forcing an odd version. Verified drizzle-kit still transpiles a
+# TypeScript drizzle.config.ts afterwards.
+#
+# ws — CVE-2026-62389, unbounded resource allocation, CVSS 8.7, fixed in 8.21.1.
+#
+# Drop these once better-auth's transitives move past them.
+#
+# KEEP THIS KEY LAST: the CI smoke test appends its own entries here.
+overrides:
+  esbuild: "^0.28.1"
+  ws: "^8.21.1"