astroidjs 0.18.0 → 0.20.0

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export * from "./queues/index.js";
 export * from "./schema/index.js";
 export * from "./security/index.js";
 export * from "./seo/index.js";
+export * from "./shape.js";
 export * from "./status.js";
 export * from "./tenancy/index.js";
 export * from "./worker/index.js";

package/dist/index.js

@@ -20,6 +20,7 @@ export * from "./queues/index.js";
 export * from "./schema/index.js";
 export * from "./security/index.js";
 export * from "./seo/index.js";
+export * from "./shape.js";
 export * from "./status.js";
 export * from "./tenancy/index.js";
 export * from "./worker/index.js";

package/dist/portal/guard.js

@@ -2,7 +2,7 @@
 //
 // Role-gated routing for the portal.
 //
-// coracle and ghostfire independently built the same thing: a declarative table
+// Two client sites independently built the same thing: a declarative table
 // of `prefix → roles`, walked once per request. Declarative rather than a guard
 // call inside each page, because a guard you have to remember to write is a
 // guard someone eventually forgets—and the page that forgets it is the one

package/dist/project/generate.js

@@ -17,10 +17,11 @@
 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 { COMMERCE_PROVIDER_SECRETS, COMMERCE_PROVIDER_SETUP, commerceProviderWebhookSecrets, commerceSecretNames, } from "../commerce/secrets.js";
 import { ASTROID_QUEUE_BINDING, ASTROID_QUEUE_RETRY_DELAY, 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 { astroidHasEditor } from "../shape.js";
 import { tenancyZone } from "../tenancy/index.js";
 import { generateAstroidSchema } from "../schema/generate.js";
 import { ASTROID_AI_GATEWAY_VAR } from "../worker/gateway.js";
@@ -93,7 +94,10 @@ export function generateAstroidSecretsEnv(config) {
     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]) {
+        for (const name of [
+            ...spec.credentials,
+            ...commerceProviderWebhookSecrets(provider, config.commerce),
+        ]) {
             lines.push(`${name}=${ASTROID_SECRET_PLACEHOLDER}`);
         }
     }
@@ -116,6 +120,12 @@ const COMPATIBILITY_DATE = "2026-06-20";
  */
 export function generateAstroidWrangler(config) {
     const key = config.key;
+    // An app with no editor binds none of what the editor uses: the media bucket
+    // and Images, the draft buffer, Workers AI, and the CWV dataset. It sends mail
+    // only for a portal's password resets.
+    const editor = astroidHasEditor(config);
+    const mail = editor || Boolean(config.portal?.enabled);
+    const crons = astroidCrons(config);
     const mediaBase = config.deploy?.mediaBase ?? "/media";
     const hosts = config.hosts ?? [];
     const primaryHost = hosts[0];
@@ -184,7 +194,10 @@ export function generateAstroidWrangler(config) {
     // 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))} },`);
+    // None at all for an app with nothing scheduled: a trigger with no handler
+    // is an invocation that fails every time it fires.
+    if (crons.length > 0)
+        p(`  "triggers": { "crons": ${JSON.stringify(crons)} },`);
     if (astroidUsesQueues(config)) {
         const { queue, dlq } = astroidQueueNames(config);
         p("  // Provider webhooks are verified at the edge, then enqueued here so the");
@@ -208,41 +221,59 @@ export function generateAstroidWrangler(config) {
         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>`.");
+    if (editor) {
+        p("  // D1 holds pages / site_settings / media / inquiries (schema in src/schema.ts,");
+        p("  // migrations in ./migrations). Create it: `wrangler d1 create <name>`.");
+    }
+    else {
+        p("  // D1: this app's tables (src/schema.ts), or the database of the app that");
+        p("  // owns the schema, bound by its id. Create one: `wrangler d1 create <name>`.");
+    }
     p('  "d1_databases": [');
     p("    {");
     p('      "binding": "DB",');
     p(`      "database_name": ${JSON.stringify(key)},`);
     p('      "database_id": "<run: wrangler d1 create ' + key + '>",');
-    p('      "migrations_dir": "migrations",');
+    // Left out when another app migrates this database (`deploy.migrations:
+    // false`), which `astroid doctor` would otherwise report as a contradiction.
+    if (config.deploy?.migrations !== false)
+        p('      "migrations_dir": "migrations",');
     p("    },");
     p("  ],");
-    p("  // R2 bucket for uploaded media, streamed back through the Worker at MEDIA_URL");
-    p("  // (no public bucket). Create it: `wrangler r2 bucket create <name>-media`.");
-    p(`  "r2_buckets": [{ "binding": "MEDIA", "bucket_name": ${JSON.stringify(`${key}-media`)} }],`);
-    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("  // 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("  // Named for the project, so two sites in one account don't collide.");
-    p("  // `astroid provision` creates each and fills in its id.");
+    if (editor) {
+        p("  // R2 bucket for uploaded media, streamed back through the Worker at MEDIA_URL");
+        p("  // (no public bucket). Create it: `wrangler r2 bucket create <name>-media`.");
+        p(`  "r2_buckets": [{ "binding": "MEDIA", "bucket_name": ${JSON.stringify(`${key}-media`)} }],`);
+        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("  // 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("  // Named for the project, so two sites in one account don't collide.");
+        p("  // `astroid provision` creates each and fills in its id.");
+    }
+    else {
+        p("  // KV: RL = the security rate limiter. Named for the project, so two apps in");
+        p("  // one account don't collide. `astroid provision` creates it and fills in");
+        p("  // its id.");
+    }
     p('  "kv_namespaces": [');
     p(`    { "binding": "RL", "id": "<run: wrangler kv namespace create ${key}-rl>" },`);
-    p(`    { "binding": "DRAFTS", "id": "<run: wrangler kv namespace create ${key}-drafts>" },`);
+    if (editor) {
+        p(`    { "binding": "DRAFTS", "id": "<run: wrangler kv namespace create ${key}-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
@@ -251,31 +282,44 @@ export function generateAstroidWrangler(config) {
     // 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`.");
+    if (editor) {
+        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.");
+    }
+    else if (mail) {
+        p("  // Cloudflare Email Sending—the portal's password-reset mail, which is");
+        p("  // logged in dev and emailed in production.");
+    }
+    if (mail) {
+        p("  // Enable Email Sending for your zone, then verify the address in MAIL_FROM.");
+        p('  "send_email": [{ "name": "EMAIL" }],');
+    }
+    if (editor) {
+        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)},`);
+    if (editor)
+        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('    "OWNER_EMAIL": "",');
-    p("    // AI Gateway for the editor's AI assists: request logs, latency and error");
-    p("    // rates, and caching. Empty calls Workers AI directly. Create a gateway,");
-    p("    // put its id here, and first say on the privacy page that its log holds");
-    p("    // the text editors send to the assists.");
-    p(`    "${ASTROID_AI_GATEWAY_VAR}": "",`);
-    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",');
+    if (editor) {
+        p("    // The editor allowlist / owner. Wire this into your auth seam (src/auth.ts).");
+        p('    "OWNER_EMAIL": "",');
+        p("    // AI Gateway for the editor's AI assists: request logs, latency and error");
+        p("    // rates, and caching. Empty calls Workers AI directly. Create a gateway,");
+        p("    // put its id here, and first say on the privacy page that its log holds");
+        p("    // the text editors send to the assists.");
+        p(`    "${ASTROID_AI_GATEWAY_VAR}": "",`);
+        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

package/dist/project/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./generate.js";
 export * from "./actions.js";
 export * from "./scaffold.js";
+export * from "./migrations.js";
 export * from "./seed.js";
 export * from "./previews.js";
 export * from "./release.js";

package/dist/project/index.js

@@ -5,6 +5,7 @@
 export * from "./generate.js";
 export * from "./actions.js";
 export * from "./scaffold.js";
+export * from "./migrations.js";
 export * from "./seed.js";
 export * from "./previews.js";
 export * from "./release.js";

package/dist/project/migrations.d.ts

@@ -0,0 +1,26 @@
+import type { ScaffoldFile } from "./scaffold.js";
+/**
+ * The `DB` binding's `migrations_dir` from `wrangler.jsonc`, or Wrangler's
+ * default `migrations` when the binding sets none or the file is missing.
+ * Returned as written, without a trailing slash.
+ */
+export declare function astroidMigrationsDir(wrangler: string | null | undefined): string;
+/**
+ * Resolve each scaffold file's path against the site's migrations directory.
+ * Files that aren't migrations pass through unchanged. For a migration:
+ *
+ * - **Already there under any number:** the path is that file's, so a caller
+ *   that skips existing files skips it. A site that copied `page_redirects`
+ *   in by hand as `0009_page_redirects.sql` keeps that file and gets no second.
+ * - **Default number free and past the newest migration:** the default, so a
+ *   standard project numbers exactly as before.
+ * - **Otherwise:** the next number after the newest migration, at the same
+ *   width. A migration never takes a number the site already uses, and never
+ *   sorts before one that already ran.
+ *
+ * `existing` is the file names in `migrationsDir`, in any order.
+ */
+export declare function resolveAstroidScaffoldPaths(files: ScaffoldFile[], { migrationsDir, existing }: {
+    migrationsDir: string;
+    existing: string[];
+}): ScaffoldFile[];

package/dist/project/migrations.js

@@ -0,0 +1,78 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Where a scaffolded D1 migration lands in a site. The scaffold names each
+// migration with a default path (`migrations/0004_page_redirects.sql`), but a
+// site can point its `DB` binding at another directory with `migrations_dir`,
+// and it may already number its own migrations past the default. Wrangler
+// applies only the directory in `migrations_dir` and tracks each file by name,
+// so a migration written anywhere else never runs, and one written onto a
+// number the site already uses leaves two files claiming that number.
+import { parseJsonc } from "./previews.js";
+/** Wrangler's own default when a D1 binding sets no `migrations_dir`. */
+const DEFAULT_MIGRATIONS_DIR = "migrations";
+/** `0004_page_redirects.sql` → number `"0004"`, name `page_redirects`. */
+const MIGRATION_FILE = /^(\d+)_(.+)\.sql$/;
+/**
+ * The `DB` binding's `migrations_dir` from `wrangler.jsonc`, or Wrangler's
+ * default `migrations` when the binding sets none or the file is missing.
+ * Returned as written, without a trailing slash.
+ */
+export function astroidMigrationsDir(wrangler) {
+    if (!wrangler)
+        return DEFAULT_MIGRATIONS_DIR;
+    let parsed;
+    try {
+        parsed = parseJsonc(wrangler);
+    }
+    catch {
+        return DEFAULT_MIGRATIONS_DIR;
+    }
+    const dir = (parsed.d1_databases ?? []).find((d) => d.binding === "DB")?.migrations_dir;
+    return dir ? dir.replace(/\/+$/, "") : DEFAULT_MIGRATIONS_DIR;
+}
+/**
+ * Resolve each scaffold file's path against the site's migrations directory.
+ * Files that aren't migrations pass through unchanged. For a migration:
+ *
+ * - **Already there under any number:** the path is that file's, so a caller
+ *   that skips existing files skips it. A site that copied `page_redirects`
+ *   in by hand as `0009_page_redirects.sql` keeps that file and gets no second.
+ * - **Default number free and past the newest migration:** the default, so a
+ *   standard project numbers exactly as before.
+ * - **Otherwise:** the next number after the newest migration, at the same
+ *   width. A migration never takes a number the site already uses, and never
+ *   sorts before one that already ran.
+ *
+ * `existing` is the file names in `migrationsDir`, in any order.
+ */
+export function resolveAstroidScaffoldPaths(files, { migrationsDir, existing }) {
+    const taken = new Map();
+    const byName = new Map();
+    for (const file of existing) {
+        const match = MIGRATION_FILE.exec(file);
+        if (!match)
+            continue;
+        taken.set(Number(match[1]), file);
+        byName.set(match[2], file);
+    }
+    let newest = taken.size ? Math.max(...taken.keys()) : -1;
+    return files.map((file) => {
+        if (!file.migration)
+            return file;
+        const base = file.path.slice(file.path.lastIndexOf("/") + 1);
+        const match = MIGRATION_FILE.exec(base);
+        if (!match)
+            return { ...file, path: `${migrationsDir}/${base}` };
+        const [, digits, name] = match;
+        const present = byName.get(name);
+        if (present)
+            return { ...file, path: `${migrationsDir}/${present}` };
+        const wanted = Number(digits);
+        const number = !taken.has(wanted) && wanted > newest ? wanted : newest + 1;
+        const filename = `${String(number).padStart(digits.length, "0")}_${name}.sql`;
+        taken.set(number, filename);
+        byName.set(name, filename);
+        newest = Math.max(newest, number);
+        return { ...file, path: `${migrationsDir}/${filename}` };
+    });
+}

package/dist/project/scaffold.d.ts

@@ -18,6 +18,12 @@ export interface ScaffoldFile {
      * Without it a re-run would append a duplicate every time.
      */
     marker?: string;
+    /**
+     * A D1 migration. `path` is its default, `migrations/NNNN_name.sql`; the CLI
+     * places it in the `DB` binding's `migrations_dir` and renumbers it past the
+     * site's own migrations with {@link resolveAstroidScaffoldPaths}.
+     */
+    migration?: true;
 }
 /**
  * `migrations/0004_page_redirects.sql`: the table that keeps a renamed page's

package/dist/project/scaffold.js

@@ -31,6 +31,7 @@ import { cwvBeaconScript } from "louise-toolkit/analytics";
 import { generateMapEmbedComponent, generateMapTileRoute } from "../map/scaffold.js";
 import { generateAstroidGalleryPage } from "../portfolio/scaffold.js";
 import { astroidPortal } from "../portal/config.js";
+import { astroidHasEditor } from "../shape.js";
 import { generateAstroidPortalAuth, generateAstroidPortalAuthRoute } from "../portal/scaffold.js";
 import { generateAstroidTenancy } from "../tenancy/index.js";
 import { generateAstroidEditSession } from "../realtime/scaffold.js";
@@ -154,26 +155,45 @@ function generateAstroidSettingsHooks() {
  */
 export function generateAstroidScaffoldFiles(config) {
     const files = [];
+    // An app with no editor gets none of the editor's files: the content
+    // migrations, the CWV beacon its Health panel reads, the Actions surface
+    // over pages and settings, and the gallery page over the media library.
+    const editor = astroidHasEditor(config);
     // --- commerce: the catalog table's migration ------------------------------
     // Numbered 0003 so it lands after the template's 0000_content and the auth
     // pair (0001, 0002) that `create-astroid` writes. Without it `--commerce`
     // scaffolded a `products` table into src/schema.ts that no migration ever
     // created, and the first sync wrote nothing while reporting success.
     const catalogSql = generateCatalogMigrationSql(config);
-    if (catalogSql)
-        files.push({ path: "migrations/0003_catalog.sql", contents: catalogSql });
+    if (catalogSql) {
+        files.push({ path: "migrations/0003_catalog.sql", contents: catalogSql, migration: true });
+    }
     // --- louise-toolkit 0.35's two schema changes -----------------------------
     // Numbered after the catalog's 0003, and written into an existing site by
     // `astroid generate` because a missing scaffold file is always written. The
     // alt update is a no-op on a fresh database. Wrangler tracks migrations by
-    // filename, so a site that already has its own 0004 keeps both.
-    files.push({ path: "migrations/0004_page_redirects.sql", contents: ASTROID_PAGE_REDIRECTS_MIGRATION }, { path: "migrations/0005_media_alt_undecided.sql", contents: ASTROID_MEDIA_ALT_MIGRATION });
+    // filename. The CLI moves each into the site's `migrations_dir` and past
+    // the site's own numbers (see migrations.ts), so a site that already has its
+    // own 0004 gets the next free number instead of a second 0004.
+    if (editor) {
+        files.push({
+            path: "migrations/0004_page_redirects.sql",
+            contents: ASTROID_PAGE_REDIRECTS_MIGRATION,
+            migration: true,
+        }, {
+            path: "migrations/0005_media_alt_undecided.sql",
+            contents: ASTROID_MEDIA_ALT_MIGRATION,
+            migration: true,
+        });
+    }
     // --- the CWV beacon -------------------------------------------------------
     // A static file under public/, so it is same-origin and covered by
     // `script-src 'self'`—an inline script carrying generated content could not
     // be hashed into the CSP and would be blocked.
-    const beacon = generateAstroidVitalsBeacon(config, cwvBeaconScript());
-    files.push({ path: beacon.path, contents: beacon.contents });
+    if (editor) {
+        const beacon = generateAstroidVitalsBeacon(config, cwvBeaconScript());
+        files.push({ path: beacon.path, contents: beacon.contents });
+    }
     // --- site-owned schema tables --------------------------------------------
     // Always: the generated src/schema.ts re-exports `./schema.site.js`, so the
     // file must exist even when empty. A project declares tables Astroid doesn't
@@ -207,10 +227,12 @@ export function generateAstroidScaffoldFiles(config) {
         files.push({ path: "src/settings-hooks.ts", contents: generateAstroidSettingsHooks() });
     }
     // --- the typed Astro Actions surface --------------------------------------
-    // Always: every project has editable pages, and the routes alone leave the
-    // Astro-native half of ADR 0001 unbuilt. Scaffold-once because it is meant to
-    // be added to.
-    files.push({ path: "src/actions/index.ts", contents: generateAstroidActions(config) });
+    // Every project with an editor: it has editable pages, and the routes alone
+    // leave the Astro-native half of ADR 0001 unbuilt. Scaffold-once because it
+    // is meant to be added to.
+    if (editor) {
+        files.push({ path: "src/actions/index.ts", contents: generateAstroidActions(config) });
+    }
     // --- commerce: the server-authoritative payment seam ----------------------
     // Scaffold-once: a real store adds shipping, tax, an order row, a receipt.
     // What's fixed is the sequence that keeps a charge correct.
@@ -232,7 +254,7 @@ export function generateAstroidScaffoldFiles(config) {
     }
     // --- portfolio: the gallery page -----------------------------------------
     // "Which assets appear, in what order" is the first thing a portfolio changes.
-    const gallery = generateAstroidGalleryPage(config);
+    const gallery = editor ? generateAstroidGalleryPage(config) : null;
     if (gallery)
         files.push({ path: "src/pages/work.astro", contents: gallery });
     // --- pwa: the service worker, manifest, and its headers -------------------

package/dist/queues/index.d.ts

@@ -1,4 +1,4 @@
 export { astroidQueueHandler, type QueueHandlerOptions } from "./consumer.js";
-export { affectsCatalog, ASTROID_DEFAULT_CRON, ASTROID_HEALTH_CRON, ASTROID_QUEUE_BINDING, ASTROID_QUEUE_RETRY_DELAY, type AstroidQueueMessage, astroidCron, astroidCrons, astroidQueueNames, astroidUsesQueues, type CatalogRefreshMessage, type WebhookMessage, } from "./messages.js";
+export { affectsCatalog, ASTROID_DEFAULT_CRON, ASTROID_HEALTH_CRON, ASTROID_QUEUE_BINDING, ASTROID_QUEUE_RETRY_DELAY, type AstroidQueueMessage, astroidCommercePipeline, astroidCron, astroidCrons, astroidQueueNames, astroidUsesQueues, type CatalogRefreshMessage, type WebhookMessage, } from "./messages.js";
 export { generateAstroidEnvBindings, generateAstroidQueueSeam, generateAstroidWebhookRoute, generateAstroidWebhookRoutes, } from "./scaffold.js";
 export { astroidQueue, handleWebhook, type QueueProducer, type WebhookRouteOptions, type WebhookVerifyInput, } from "./webhook.js";

package/dist/queues/index.js

@@ -1,5 +1,5 @@
 // Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
 export { astroidQueueHandler } from "./consumer.js";
-export { affectsCatalog, ASTROID_DEFAULT_CRON, ASTROID_HEALTH_CRON, ASTROID_QUEUE_BINDING, ASTROID_QUEUE_RETRY_DELAY, astroidCron, astroidCrons, astroidQueueNames, astroidUsesQueues, } from "./messages.js";
+export { affectsCatalog, ASTROID_DEFAULT_CRON, ASTROID_HEALTH_CRON, ASTROID_QUEUE_BINDING, ASTROID_QUEUE_RETRY_DELAY, astroidCommercePipeline, astroidCron, astroidCrons, astroidQueueNames, astroidUsesQueues, } from "./messages.js";
 export { generateAstroidEnvBindings, generateAstroidQueueSeam, generateAstroidWebhookRoute, generateAstroidWebhookRoutes, } from "./scaffold.js";
 export { astroidQueue, handleWebhook, } from "./webhook.js";

package/dist/queues/messages.d.ts

@@ -7,6 +7,12 @@ import type { AstroidConfig } from "../config.js";
  * provider's delivery timeout is shorter than your catalog sync.
  */
 export declare function astroidUsesQueues(config: AstroidConfig): boolean;
+/**
+ * Whether this project runs the commerce pipeline: the webhook receivers and the
+ * catalog re-sync. On whenever commerce is configured, unless the config sets
+ * `commerce.pipeline: false` because another project runs it.
+ */
+export declare function astroidCommercePipeline(config: AstroidConfig): boolean;
 /** Hourly. Frequent enough that stale data has a bounded lifetime, rare enough
  *  to be free. */
 export declare const ASTROID_DEFAULT_CRON = "0 * * * *";

package/dist/queues/messages.js

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
 //
 // What flows through the project's queue, and when it matters.
+import { astroidHasEditor } from "../shape.js";
 /**
  * Whether this project runs a queue consumer + cron.
  *
@@ -9,7 +10,15 @@
  * provider's delivery timeout is shorter than your catalog sync.
  */
 export function astroidUsesQueues(config) {
-    return config.queues?.enabled ?? Boolean(config.commerce);
+    return config.queues?.enabled ?? astroidCommercePipeline(config);
+}
+/**
+ * Whether this project runs the commerce pipeline: the webhook receivers and the
+ * catalog re-sync. On whenever commerce is configured, unless the config sets
+ * `commerce.pipeline: false` because another project runs it.
+ */
+export function astroidCommercePipeline(config) {
+    return Boolean(config.commerce) && config.commerce?.pipeline !== false;
 }
 /** Hourly. Frequent enough that stale data has a bounded lifetime, rare enough
  *  to be free. */
@@ -18,6 +27,10 @@ export const ASTROID_DEFAULT_CRON = "0 * * * *";
 export function astroidCron(config) {
     if (!astroidUsesQueues(config))
         return null;
+    // The re-sync is part of the pipeline, so a project that leaves the pipeline
+    // to another one leaves this to it too, even when its queue runs for crons.
+    if (config.commerce && !astroidCommercePipeline(config))
+        return null;
     const cron = config.queues?.cron;
     if (cron === false)
         return null;
@@ -40,7 +53,9 @@ export const ASTROID_HEALTH_CRON = "17 4 * * *";
  * agree exactly, and a mismatch is a job that silently never runs.
  */
 export function astroidCrons(config) {
-    const crons = [ASTROID_HEALTH_CRON];
+    // The health scan reports to the editor's Health panel, over the editor's
+    // pages and media, so an app with no editor has nothing to scan or show.
+    const crons = astroidHasEditor(config) ? [ASTROID_HEALTH_CRON] : [];
     const catalog = astroidCron(config);
     if (catalog)
         crons.push(catalog);

package/dist/queues/scaffold.js

@@ -11,7 +11,7 @@
 import { astroidCatalogMirror } from "../commerce/mirror.js";
 import { astroidCommerceProviders, astroidCommerceRoles } from "../commerce/roles.js";
 import { COMMERCE_PROVIDER_SECRETS } from "../commerce/secrets.js";
-import { ASTROID_QUEUE_BINDING } from "./messages.js";
+import { ASTROID_QUEUE_BINDING, astroidCommercePipeline } from "./messages.js";
 /**
  * Per-provider webhook facts: the header, the verifier, and how it's called.
  *
@@ -244,6 +244,10 @@ export function generateAstroidWebhookRoute(config, forProvider) {
  * two roles still has one endpoint and one secret.
  */
 export function generateAstroidWebhookRoutes(config) {
+    // A project that leaves the pipeline to another one receives no webhooks: the
+    // provider delivers each event to one endpoint, and it's the other project's.
+    if (!astroidCommercePipeline(config))
+        return [];
     return astroidCommerceProviders(config.commerce).flatMap((provider) => {
         const contents = generateAstroidWebhookRoute(config, provider);
         return contents ? [{ path: `src/pages/api/webhooks/${provider}.ts`, contents }] : [];

package/dist/schema/collections.d.ts

@@ -69,6 +69,12 @@ export interface AstroidPagesHooks {
  * with a 422 instead.
  */
 export declare const ASTROID_RESERVED_SLUGS: readonly string[];
+/**
+ * The reserved slugs for this config: {@link ASTROID_RESERVED_SLUGS}, plus the
+ * file routes a module scaffolds, minus any in `pages.allowSlugs`. A
+ * portfolio's gallery is `src/pages/work.astro`.
+ */
+export declare function astroidReservedSlugs(config: AstroidConfig): string[];
 export declare function astroidPagesWriteHooks(config: AstroidConfig, site?: AstroidPagesHooks): {
     sanitize: (html: string) => string;
     transform: (data: Record<string, unknown>, ctx: AstroidPagesWriteContext) => Promise<Record<string, unknown>>;

package/dist/schema/collections.js

@@ -47,7 +47,7 @@ const pageMediaBase = astroidMediaBase;
  * The section catalog a `pages` write is validated + sanitized against: the
  * site's own (`config.sectionCatalog`) when it registered bespoke sections, else
  * Astroid's built-in vocabulary. This is what lets a site with its own section
- * designs (coracle's 13) keep the same write contract as a stock Astroid site.
+ * designs keep the same write contract as a stock Astroid site.
  */
 function resolveSectionCatalog(config) {
     return config.sectionCatalog ?? astroidSectionCatalog;
@@ -109,9 +109,21 @@ export const ASTROID_RESERVED_SLUGS = [
     "_astro",
     "api",
     "cdn-cgi",
+    // The scaffold's own file routes, which every site has.
+    "contact",
+    "login",
     "robots.txt",
     "sitemap.xml",
 ];
+/**
+ * The reserved slugs for this config: {@link ASTROID_RESERVED_SLUGS}, plus the
+ * file routes a module scaffolds, minus any in `pages.allowSlugs`. A
+ * portfolio's gallery is `src/pages/work.astro`.
+ */
+export function astroidReservedSlugs(config) {
+    const allowed = new Set(config.pages?.allowSlugs ?? []);
+    return [...ASTROID_RESERVED_SLUGS, ...(config.archetype === "portfolio" ? ["work"] : [])].filter((slug) => !allowed.has(slug));
+}
 export function astroidPagesWriteHooks(config, site = {}) {
     return {
         // `body` is a richField, so it goes through pagesRoute's own sanitize seam—with
@@ -127,7 +139,7 @@ export function astroidPagesWriteHooks(config, site = {}) {
             await site.validate?.(data, ctx);
             await assertAstroidPageSections(config, data, ctx.operation);
         },
-        reservedSlugs: [...ASTROID_RESERVED_SLUGS, ...(site.reservedSlugs ?? [])],
+        reservedSlugs: [...astroidReservedSlugs(config), ...(site.reservedSlugs ?? [])],
     };
 }
 export function astroidPagesCollection(config) {