astroidjs 0.18.0 → 0.20.0

package/README.md

@@ -35,17 +35,16 @@ project:** every site Astroid targets serves a single brand from a single deploy
 so the config describes one brand, not an array. What actually multiplexes is
 _editors_ (Louise's org plugin) and _audiences_ (a gated portal beside the public
 site)—both options on the one brand. The vocabulary is drawn from the real
-sites Astroid targets: a storefront (coracle.coffee), a wholesale front
-(ghostfire.coffee), an artist portfolio (themidwestartist.com), and a plain
-marketing baseline (louise-web).
+sites Astroid was built from: a storefront, a wholesale front, an artist
+portfolio, and a plain marketing baseline.
 
 ```ts
 import { defineAstroid } from "astroidjs";
 
 export default defineAstroid({
-  key: "coracle",
+  key: "example",
   archetype: "storefront",
-  theme: { name: "Coracle Coffee", colors: { brand: "#1f6f78" } },
+  theme: { name: "Example Organization", colors: { brand: "#5b4bff" } },
   sections: ["hero", "banner", "productGrid", "locationHours", "contact"],
   commerce: { provider: "square" },
   deploy: { platform: "cloudflare" },
@@ -56,9 +55,9 @@ A portfolio with a gated client area, for contrast:
 
 ```ts
 export default defineAstroid({
-  key: "megbowen",
+  key: "example-studio",
   archetype: "portfolio",
-  theme: { name: "Meg Bowen Studio", colors: { brand: "#2b2b2b" } },
+  theme: { name: "Example Studio", colors: { brand: "#2b2b2b" } },
   sections: ["hero", "gallery", "aboutIntro", "contact"],
   portal: { enabled: true },
   // The masters ARE the product here: 40 MB camera files upload once and only

package/bin/astroid.mjs

@@ -17,7 +17,7 @@
 
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -87,6 +87,22 @@ async function loadConfig(cwd, explicit) {
   return { config, path };
 }
 
+/**
+ * The scaffold files with each migration placed in the `DB` binding's
+ * `migrations_dir` and numbered past the site's own migrations. Without this a
+ * site whose migrations live elsewhere got files Wrangler never applied.
+ */
+async function scaffoldFilesFor(cwd, files) {
+  const { astroidMigrationsDir, resolveAstroidScaffoldPaths } = await import(GENERATORS_URL);
+  const wranglerPath = join(cwd, "wrangler.jsonc");
+  const migrationsDir = astroidMigrationsDir(
+    existsSync(wranglerPath) ? readFileSync(wranglerPath, "utf8") : null,
+  );
+  const dirPath = join(cwd, migrationsDir);
+  const existing = existsSync(dirPath) ? readdirSync(dirPath) : [];
+  return resolveAstroidScaffoldPaths(files, { migrationsDir, existing });
+}
+
 // --- commands --------------------------------------------------------------
 async function cmdGenerate(cwd, flags, { quiet = false } = {}) {
   const {
@@ -123,7 +139,7 @@ async function cmdGenerate(cwd, flags, { quiet = false } = {}) {
   // regenerated a project that couldn't resolve its own imports. Completing the
   // config change is what makes "one typed config" true.
   const created = [];
-  for (const file of generateAstroidScaffoldFiles(config)) {
+  for (const file of await scaffoldFilesFor(cwd, generateAstroidScaffoldFiles(config))) {
     const abs = join(cwd, file.path);
     const exists = existsSync(abs);
     if (file.apply === "append-once") {
@@ -156,6 +172,7 @@ async function cmdDoctor(cwd, flags) {
     generateAstroidScaffoldFiles,
     astroidUsesQueues,
     astroidCrons,
+    astroidHasEditor,
     checkWranglerPreviews,
     astroidRunsMigrations,
     migrationsOwnershipError,
@@ -196,7 +213,7 @@ async function cmdDoctor(cwd, flags) {
   //     that names a module whose seam was never written produces a project that
   //     cannot resolve its own imports. This is precisely the state that used to
   //     report "healthy" with two warnings and exit 0.
-  for (const file of generateAstroidScaffoldFiles(config)) {
+  for (const file of await scaffoldFilesFor(cwd, generateAstroidScaffoldFiles(config))) {
     if (file.apply === "append-once") continue; // accumulated, not owned—see below
     if (existsSync(join(cwd, file.path))) ok(`${file.path} present`);
     else err(`${file.path} is missing (required by your config) — run \`astroid generate\`.`);
@@ -219,9 +236,15 @@ async function cmdDoctor(cwd, flags) {
     //
     // So check every binding the GENERATED code actually dereferences, not just
     // the three the baseline happens to have.
+    // An app with no editor (`editor: false`) uses none of the editor's
+    // bindings, so it isn't held to them: no draft buffer, no media bucket, and
+    // no mail unless its portal sends password resets.
+    const editor = astroidHasEditor(config);
     const requiredBindings = [
       { name: "RL", what: "KV namespace", why: "the rate limiter in src/middleware.ts" },
-      { name: "DRAFTS", what: "KV namespace", why: "the autosave draft buffer" },
+      ...(editor
+        ? [{ name: "DRAFTS", what: "KV namespace", why: "the autosave draft buffer" }]
+        : []),
       ...(astroidUsesQueues(config)
         ? [
             {
@@ -247,17 +270,24 @@ async function cmdDoctor(cwd, flags) {
     // it: the magic link is console-logged in dev and EMAILED in production, so
     // a missing binding is a site nobody can sign in to—and it fails only once
     // deployed, which is the one place nothing in this repo exercises.
-    if (/"send_email"\s*:/.test(w)) ok("wrangler: Email Sending `EMAIL` binding present");
-    else
+    // An app with no editor and no portal signs nobody in, so it sends no mail.
+    const sendsMail = editor || Boolean(config.portal?.enabled);
+    if (sendsMail && /"send_email"\s*:/.test(w))
+      ok("wrangler: Email Sending `EMAIL` binding present");
+    else if (sendsMail)
       err(
-        "wrangler.jsonc has no `send_email` binding, but production sign-in emails the " +
-          'magic link (it is only console-logged in dev). Add: "send_email": [{ "name": "EMAIL" }]',
+        editor
+          ? "wrangler.jsonc has no `send_email` binding, but production sign-in emails the " +
+              'magic link (it is only console-logged in dev). Add: "send_email": [{ "name": "EMAIL" }]'
+          : "wrangler.jsonc has no `send_email` binding, but the portal emails password resets " +
+              'in production (they are only console-logged in dev). Add: "send_email": [{ "name": "EMAIL" }]',
       );
 
     if (hasBinding("DB")) ok("wrangler: D1 `DB` binding present");
     else err("wrangler.jsonc has no D1 `DB` binding.");
-    if (hasBinding("MEDIA")) ok("wrangler: R2 `MEDIA` binding present");
-    else err("wrangler.jsonc has no R2 `MEDIA` binding.");
+    // An app with no editor has no media library, so no bucket to hold it.
+    if (editor && hasBinding("MEDIA")) ok("wrangler: R2 `MEDIA` binding present");
+    else if (editor) err("wrangler.jsonc has no R2 `MEDIA` binding.");
     if (/"main"\s*:\s*"src\/worker\.ts"/.test(w)) ok("wrangler: `main` → src/worker.ts");
     else warn("wrangler.jsonc `main` does not point at src/worker.ts.");
 
@@ -271,7 +301,17 @@ async function cmdDoctor(cwd, flags) {
     // JSON.parse (comments/trailing commas), matching the binding checks above.
     const expectedCrons = astroidCrons(config);
     const cronsMatch = w.match(/"crons"\s*:\s*\[([^\]]*)\]/);
-    if (!cronsMatch) {
+    const declaredAny = cronsMatch && /"[^"]+"/.test(cronsMatch[1]);
+    if (expectedCrons.length === 0) {
+      // Nothing scheduled, so the generated worker has no `scheduled` handler,
+      // and a declared trigger would fail every time it fired.
+      if (declaredAny)
+        warn(
+          "wrangler.jsonc declares `triggers.crons`, but nothing in your config is scheduled, " +
+            "so the generated worker has no `scheduled` handler for them. Remove the triggers.",
+        );
+      else ok("wrangler: no crons, and nothing is scheduled");
+    } else if (!cronsMatch) {
       err(
         "wrangler.jsonc has no `triggers.crons`, but the generated `scheduled` handler " +
           `dispatches on ${expectedCrons.map((c) => `"${c}"`).join(", ")}. ` +

package/dist/commerce/adapters.js

@@ -2,9 +2,9 @@
 //
 // Provider → `CatalogItem` normalizers.
 //
-// This is the file the whole module exists for. themidwestartist.com's loader
-// says it outright: coracle runs the same helper over Square, "only the
-// content/repo reads differ—issue: repo drift." Two sites, one intent, two
+// This is the file the whole module exists for. One client site's loader says it
+// outright: another site runs the same helper over Square, and only the content
+// and repository reads differ, so the copies drift. Two sites, one intent, two
 // hand-written translations that drifted apart. The translation is mechanical,
 // so it belongs here once.
 //

package/dist/commerce/checkout.js

@@ -3,7 +3,7 @@
 // Server-authoritative checkout.
 //
 // A cart arrives from the browser, so every number in it is a claim, not a fact.
-// The rule this encodes—taken from coracle.coffee's working checkout—is that
+// The rule this encodes—taken from a client site's working checkout—is that
 // the client's price is a **staleness check**, never an input to the charge:
 // look the price up server-side, and if it disagrees with what the customer was
 // shown, refuse rather than silently charging a different amount. Refusing is

package/dist/commerce/mirror.js

@@ -12,7 +12,7 @@
 // What the sites did NOT agree on is how much to store, and it turns out to be
 // one primitive with two settings rather than two designs:
 //
-//   mirror: pulled + owned columns both live in D1 (themidwestartist.com).
+//   mirror: pulled + owned columns both live in D1.
 //              Reads are one local query. The catalog can be stale between syncs.
 //   overlay: only the owned columns live in D1, keyed by the provider's id.
 //              The catalog is read live from the provider and joined at read
@@ -20,9 +20,10 @@
 //              (cache accordingly).
 //   live: Astroid manages NO catalog table at all: the catalog is read live
 //              from the provider (cached), and any owner-side overlay table is
-//              the SITE's own (coracle.coffee's `product_display_meta`, declared
-//              in schema.site.ts and joined in the site's loader). Use when the
-//              existing overlay shape predates Astroid and must be preserved 1:1.
+//              the SITE's own (for example, a `product_display_meta` table
+//              declared in schema.site.ts and joined in the site's loader).
+//              Use when the existing overlay shape predates Astroid and must
+//              be preserved 1:1.
 //
 // `overlay` is just `mirror` with an empty pulled set; `live` emits neither table
 // nor migration. One generator serves all three and a project switches by one word.

package/dist/commerce/roles.js

@@ -9,9 +9,9 @@
 // happens to do both. A single `CommerceProvider` abstraction that assumed
 // catalog + checkout would therefore have a permanent hole wherever Stripe sits.
 //
-// That's not hypothetical. themidwestartist.com runs Stripe for **invoicing**
-// (commissions, originals) alongside Fourthwall for the **storefront**
-// (merch)—two providers, one site, each doing the half it can do.
+// A site that invoices through one provider (commissions, originals) and runs
+// its storefront through another (merch) needs exactly this: two providers,
+// one site, each doing the half it can do.
 //
 // So a project assigns providers to roles, and Astroid validates the assignment
 // against what each provider's client can actually serve.

package/dist/commerce/secrets.d.ts

@@ -50,6 +50,13 @@ export declare function commerceProviderCredentials(provider: CommerceProvider,
  * `.dev.vars` would be a bug rather than a redundancy.
  */
 export declare function commerceSecretNames(commerce: CommerceConfig | undefined): string[];
+/**
+ * The webhook signing secret a provider needs, or none when the project runs no
+ * pipeline (`commerce.pipeline: false`). With no receiver there is nothing to
+ * verify, so requiring the secret would hold checkout dormant for a value no
+ * code reads.
+ */
+export declare function commerceProviderWebhookSecrets(provider: CommerceProvider, commerce: CommerceConfig | undefined): readonly string[];
 /** One provider's resolved gate. */
 export interface ProviderStatus {
     provider: CommerceProvider;

package/dist/commerce/secrets.js

@@ -101,19 +101,28 @@ export function commerceProviderCredentials(provider, commerce) {
 export function commerceSecretNames(commerce) {
     const names = astroidCommerceProviders(commerce).flatMap((provider) => [
         ...commerceProviderCredentials(provider, commerce),
-        COMMERCE_PROVIDER_SECRETS[provider].webhook,
+        ...commerceProviderWebhookSecrets(provider, commerce),
     ]);
     return [...new Set(names)];
 }
+/**
+ * The webhook signing secret a provider needs, or none when the project runs no
+ * pipeline (`commerce.pipeline: false`). With no receiver there is nothing to
+ * verify, so requiring the secret would hold checkout dormant for a value no
+ * code reads.
+ */
+export function commerceProviderWebhookSecrets(provider, commerce) {
+    return commerce?.pipeline === false ? [] : [COMMERCE_PROVIDER_SECRETS[provider].webhook];
+}
 /** Read one provider's secrets off an env-shaped record. */
 async function resolveProvider(provider, roles, env, commerce) {
-    const spec = COMMERCE_PROVIDER_SECRETS[provider];
     const pick = (names) => Object.fromEntries(names.map((n) => [n, env[n]]));
     const [credentials, webhook] = await Promise.all([
         // Config-aware: a multi-location project must not be held dormant waiting
         // for a SQUARE_LOCATION_ID it will never legitimately have.
         resolveModuleSecrets(pick(commerceProviderCredentials(provider, commerce))),
-        resolveModuleSecrets(pick([spec.webhook])),
+        // Empty without a pipeline, which resolves as configured: nothing to verify.
+        resolveModuleSecrets(pick(commerceProviderWebhookSecrets(provider, commerce))),
     ]);
     return {
         provider,

package/dist/config.d.ts

@@ -8,8 +8,8 @@ import type { PwaConfig } from "./pwa/generate.js";
  * The starting shape the front-end takes. Not a fork—each archetype is a preset
  * of defaults (which sections/modules are on, nav shape) that the site then tunes.
  * `marketing` = the lean brochure floor (louise-web, no commerce); `storefront` =
- * DTC shop (coracle); `wholesale` = B2B/private-label (ghostfire); `portfolio` =
- * gallery + prints + client portal (megbowen).
+ * DTC shop; `wholesale` = B2B/private-label; `portfolio` = gallery + prints +
+ * client portal.
  */
 export type Archetype = "marketing" | "storefront" | "wholesale" | "portfolio";
 /**
@@ -56,7 +56,7 @@ export declare const ASTROID_ARCHETYPE_SECTIONS: Record<Archetype, SectionKind[]
  * deploy and notice the absence.
  *
  * They are removed rather than left as TODOs. `orderTracking` in particular has
- * a real implementation waiting—`src/workflow/` is the ghostfire order tracker,
+ * a real implementation waiting—`src/workflow/` is a client site's order tracker,
  * generalized—but it is reached through `defineWorkflow`, not this flag, and
  * pretending otherwise is what made the flag misleading. Re-add each one in the
  * change that wires it.
@@ -152,8 +152,9 @@ export interface CommerceConfig {
     storefront?: CommerceProvider;
     /**
      * Invoices for work that isn't a catalog item—commissions, originals.
-     * Independent of `storefront`: themidwestartist.com runs Stripe here and
-     * Fourthwall as the storefront, because neither can do the other's job.
+     * Independent of `storefront`: a site can invoice through one provider (say,
+     * Stripe) and run its storefront through another (say, Fourthwall), because
+     * neither can do the other's job.
      */
     invoicing?: CommerceProvider;
     /**
@@ -161,7 +162,7 @@ export interface CommerceConfig {
      * counter or a market stall rather than through the site's own cart.
      *
      * Separate from `storefront` because they are genuinely different jobs and a
-     * site commonly runs both. themidwestartist.com sells print-on-demand merch
+     * site commonly runs both. An artist's site might sell print-on-demand merch
      * through Fourthwall (`storefront`) while originals and self-stocked prints
      * live in Square (`pos`) across several shops and galleries—one catalog per
      * rail, neither able to do the other's job.
@@ -174,6 +175,18 @@ export interface CommerceConfig {
     catalog?: CatalogMirrorConfig;
     /** Square-specific options. Only meaningful when Square fills some role. */
     square?: SquareCommerceConfig;
+    /**
+     * Whether this project runs the commerce pipeline: the webhook receivers, the
+     * queue consumer that processes them, and the hourly catalog re-sync. Default
+     * `true`.
+     *
+     * Set `false` for a project that only takes payments while another project,
+     * or another Worker in the same repository, runs the pipeline against the
+     * same account. It keeps what a checkout needs, the provider's CSP origins,
+     * the checkout rate rule, and the checkout route, and drops the rest, along
+     * with the webhook signing secret nothing would verify.
+     */
+    pipeline?: boolean;
 }
 export interface SquareCommerceConfig {
     /**
@@ -194,8 +207,9 @@ export interface SquareCommerceConfig {
 export interface QueuesConfig {
     /**
      * Force the queue consumer + cron on or off. Defaults to on whenever
-     * `commerce` is configured: a commerce provider means webhooks, and a webhook
-     * you process inline is a webhook you drop when the provider times out.
+     * `commerce` is configured with its pipeline: a commerce provider means
+     * webhooks, and a webhook you process inline is a webhook you drop when the
+     * provider times out.
      */
     enabled?: boolean;
     /**
@@ -323,9 +337,9 @@ export interface TenancyConfig {
      * sign-in) instead of JSON, and every data load on that host silently fails
      * while the same code works on the apex.
      *
-     * That is not hypothetical—it is why this default exists (found on
-     * themidwestartist.com's studio, where the whole admin app loaded and then
-     * fetched nothing).
+     * That is not hypothetical—it is why this default exists (found on a client
+     * site's studio host, where the whole admin app loaded and then fetched
+     * nothing).
      *
      * Set `[]` to rewrite everything, or add prefixes for other host-agnostic
      * surfaces (`/_actions`, `/webhooks`). Matching is prefix-based on a path
@@ -407,8 +421,8 @@ export interface SettingsConfig {
      * on top of (or, with `columns: []`, instead of) Astroid's base columns. The
      * generated `settingsRoute` + Action accept these; the Settings panel writes
      * them through the `settingsExtension` groups a site supplies to
-     * `mountSettings`. A site with a rich settings shape (coracle's footer columns,
-     * hours table, ui strings, shop/order config) lists their top-level keys here.
+     * `mountSettings`. A site with a rich settings shape (footer columns, an hours
+     * table, UI strings, shop/order config) lists their top-level keys here.
      */
     customKeys?: string[];
     /** Extra media-library image keys beyond the base logo/favicon/OG defaults—*
@@ -456,7 +470,22 @@ export interface PagesConfig {
      * clamping a title, or filling a new page's defaults.
      */
     hooks?: boolean;
+    /**
+     * Reserved slugs this site serves as pages. `contact` and `login` are
+     * reserved because a new scaffold has file routes there, and `work` because
+     * a portfolio has its gallery there. A site without that file, whose page at
+     * the path comes from its own catch-all route, lists the slug here so the
+     * Pages route accepts it. Only those three can be allowed
+     * ({@link ASTROID_SCAFFOLD_ROUTE_SLUGS}): the platform serves the other
+     * reserved slugs, such as `api` and `sitemap.xml`, before any page.
+     */
+    allowSlugs?: string[];
 }
+/**
+ * The reserved slugs that come from a scaffolded file route rather than the
+ * platform, so a site without that file can allow them with `pages.allowSlugs`.
+ */
+export declare const ASTROID_SCAFFOLD_ROUTE_SLUGS: readonly string[];
 export interface StatusConfig {
     /**
      * Add the site's own checks to the public status route, from the
@@ -481,10 +510,32 @@ export interface DeployConfig {
      */
     migrations?: boolean;
 }
+/**
+ * A small "Site by …" line the footer renders for the agency that built the
+ * site. A site fact, so it has no default: omit it and nothing renders.
+ */
+export interface CreditConfig {
+    /** Who built the site, for example `"Example Organization"`. */
+    name: string;
+    /** Where the credit links, as an absolute `http` or `https` URL. */
+    href: string;
+    /**
+     * An optional mark shown before the name: a root-relative path (for example
+     * `"/credit-mark.svg"`) or an `https:` URL. It's drawn as a mask filled with
+     * the text color, so one single-color SVG works on every theme. Only its
+     * shape counts; its own fill is ignored.
+     */
+    logo?: string;
+    /** The link's `rel`, for example `"noopener"` or `"noopener nofollow"`. The
+     *  site decides; omitted, the link carries none. */
+    rel?: string;
+    /** The words before the name. Default `"Site by"`. */
+    label?: string;
+}
 export interface AstroidConfig {
     /**
      * Stable project slug—the worker/D1/R2 base name and default subdomain (for example,
-     * `"coracle"`). Required and non-empty; it drives the generated binding names.
+     * `"example"`). Required and non-empty; it drives the generated binding names.
      */
     key: string;
     /** Hostnames this site serves (prod + preview), for custom-domain routes. */
@@ -497,6 +548,21 @@ export interface AstroidConfig {
     tenancy?: TenancyConfig;
     /** Starting shape; sets section/module/nav defaults the site can override. */
     archetype: Archetype;
+    /**
+     * Whether the project has a Louise editor. Default `true`.
+     *
+     * Set `false` for an app with no pages to edit, such as an order app whose
+     * menu comes from a commerce provider and whose few settings another site's
+     * editor owns. The generated worker and middleware then carry no editor
+     * routes and no sign-in, the schema carries no content tables, and
+     * `wrangler.jsonc` binds no draft buffer, media bucket, or AI. What stays is
+     * the rate limiter, the CSP, the security headers, the public status route,
+     * and the `portal`, `pwa`, `commerce`, and `tenancy` modules.
+     *
+     * `defineAstroid` refuses every option that configures the editor
+     * alongside it, such as `sections` or `media`, rather than ignore it.
+     */
+    editor?: boolean;
     /** The single brand's theme (display name + color tokens + font). */
     theme: Theme;
     /** The editable home page, top to bottom. Omit to take the archetype default. */
@@ -505,7 +571,7 @@ export interface AstroidConfig {
      * A site-provided section catalog that REPLACES the built-in one for
      * SERVER-side validation + sanitization of `pages.sections` (the generated
      * pages route + versions route). A site with bespoke section designs—its own
-     * `.astro` components and field defs (coracle's 13 sections)—registers them
+     * `.astro` components and field defs (a dozen or more sections)—registers them
      * here so writes to its custom `_type`s validate instead of 422-ing against the
      * built-in vocabulary. The on-canvas editor already uses the site's catalog
      * (its `mountSections` call passes it); this closes the server half so both
@@ -561,11 +627,14 @@ export interface AstroidConfig {
      * Force the contact form + `inquiries` table on or off. Omit to detect from
      * the config (a `contact` section, or a wholesale-inquiry module). Set `true`
      * when a bespoke section captures inquiries under a name Astroid can't see
-     * (coracle's custom `contactForm`); set `false` to suppress it entirely.
+     * (for example, a custom `contactForm` section); set `false` to suppress it
+     * entirely.
      */
     inquiries?: boolean;
     /** Installable-app settings. Only read when `modules` includes `"pwa"`. */
     pwa?: PwaConfig;
+    /** The agency credit `<Credit>` renders in the footer. Omit for none. */
+    credit?: CreditConfig;
     deploy?: DeployConfig;
 }
 export declare function defineAstroid(config: AstroidConfig): AstroidConfig;

package/dist/config.js

@@ -8,8 +8,8 @@
 // the Louise wiring (worker routes, middleware, Drizzle schema, theme tokens) a
 // site would otherwise hand-write per repo.
 //
-// ONE brand per project. Every site Astroid targets (coracle.coffee,
-// ghostfire.coffee, themidwestartist.com, louise-web) serves a single brand from a
+// ONE brand per project. Every site Astroid targets (the client sites its
+// patterns came from, and louise-web) serves a single brand from a
 // single deploy. The axis that genuinely multiplexes is *editors* (Louise's org
 // plugin, #100) and *audiences*—a gated portal alongside the public site, or a
 // per-merchant storefront on its own subdomain (`tenancy`)—not brands. So all
@@ -22,9 +22,9 @@
 // a second project.
 //
 // The vocabulary below is not invented: `Archetype`, `SectionKind`, and
-// `ModuleKind` are extracted from the real sites Astroid targets—a storefront
-// (coracle), a wholesale front (ghostfire), an artist portfolio (megbowen), and a
-// plain marketing baseline (louise-web).
+// `ModuleKind` are extracted from the real sites Astroid targets—a storefront,
+// a wholesale front, an artist portfolio, and a plain marketing baseline
+// (louise-web).
 import { assertAuthIsolation } from "./auth/index.js";
 import { assertCommerceRoles } from "./commerce/roles.js";
 import { AstroidConfigError } from "./errors.js";
@@ -34,6 +34,7 @@ import { AstroidConfigError } from "./errors.js";
 // type-only, so the cycle erases at build and nothing circular exists at runtime.
 // It is also dependency-free, so `create-astroid`'s graph is unchanged.
 import { ASTROID_HEALTH_CRON, astroidCron, astroidUsesQueues } from "./queues/messages.js";
+import { astroidHasEditor } from "./shape.js";
 /**
  * Each archetype's default home-page sections.
  *
@@ -55,6 +56,11 @@ export const ASTROID_ARCHETYPE_SECTIONS = {
     wholesale: ["hero", "featureGrid", "aboutIntro", "contact"],
     portfolio: ["hero", "gallery", "aboutIntro", "contact"],
 };
+/**
+ * The reserved slugs that come from a scaffolded file route rather than the
+ * platform, so a site without that file can allow them with `pages.allowSlugs`.
+ */
+export const ASTROID_SCAFFOLD_ROUTE_SLUGS = ["contact", "login", "work"];
 /**
  * Define an Astroid project. An identity function in the shape of Astro's
  * `defineConfig`: it returns the config verbatim with full type-checking +
@@ -64,9 +70,9 @@ export const ASTROID_ARCHETYPE_SECTIONS = {
  *
  * ```ts
  * export default defineAstroid({
- *   key: "coracle",
+ *   key: "example",
  *   archetype: "storefront",
- *   theme: { name: "Coracle Coffee", colors: { brand: "#1f6f78" } },
+ *   theme: { name: "Example Organization", colors: { brand: "#5b4bff" } },
  *   sections: ["hero", "banner", "productGrid", "locationHours", "contact"],
  *   commerce: { provider: "square" },
  *   deploy: { platform: "cloudflare" },
@@ -83,6 +89,13 @@ export const ASTROID_ARCHETYPE_SECTIONS = {
  * the unreachable-trigger failure `config.crons` exists to prevent.
  */
 function assertCrons(config) {
+    // `queues.cron` schedules the catalog re-sync, which belongs to the pipeline.
+    // Without one it would be accepted and never scheduled.
+    if (config.commerce?.pipeline === false && typeof config.queues?.cron === "string") {
+        throw new AstroidConfigError("`queues.cron` schedules the catalog re-sync, which `commerce.pipeline: false` " +
+            "leaves to the project that runs the pipeline. Remove `queues.cron`, or use " +
+            "`crons` for a job of this project's own.");
+    }
     const crons = config.crons ?? [];
     if (crons.length === 0)
         return;
@@ -91,7 +104,7 @@ function assertCrons(config) {
             "without it the generated handler would `send` to a binding this project never creates. " +
             "Set `queues: { enabled: true }`, or drop the crons.");
     }
-    const seen = new Map([[ASTROID_HEALTH_CRON, "the daily health scan"]]);
+    const seen = new Map(astroidHasEditor(config) ? [[ASTROID_HEALTH_CRON, "the daily health scan"]] : []);
     const catalog = astroidCron(config);
     if (catalog)
         seen.set(catalog, "the catalog re-sync (`queues.cron`)");
@@ -109,6 +122,20 @@ function assertCrons(config) {
         seen.set(expression, "another entry in `crons`");
     }
 }
+/**
+ * `pages.allowSlugs` may only name a slug reserved for a scaffolded file route.
+ * Allowing `api` or `sitemap.xml` would let an editor save a page nobody can
+ * reach, which is the silent failure the reserved list exists to prevent.
+ */
+function assertAllowSlugs(config) {
+    for (const slug of config.pages?.allowSlugs ?? []) {
+        if (!ASTROID_SCAFFOLD_ROUTE_SLUGS.includes(slug)) {
+            throw new AstroidConfigError(`\`pages.allowSlugs\` can't allow "${slug}". Only the slugs reserved for a scaffolded ` +
+                `file route can be allowed (${ASTROID_SCAFFOLD_ROUTE_SLUGS.join(", ")}); the ` +
+                "platform serves the others before any page.");
+        }
+    }
+}
 /**
  * The tenancy misconfigurations that fail late, or not at all.
  *
@@ -177,6 +204,79 @@ function assertMediaConfig(media) {
             "would fail with an error the media route never sees.");
     }
 }
+/**
+ * A credit that would render as a broken link or an empty mark.
+ *
+ * The logo is limited to a root-relative path or `https:` because it lands in a
+ * CSS `url()`: a `data:` or `javascript:` value there is at best unrenderable,
+ * and a relative one resolves against each page's path rather than the site.
+ */
+function assertCredit(credit) {
+    if (!credit)
+        return;
+    if (!credit.name?.trim()) {
+        throw new AstroidConfigError("`credit.name` is required: the name the footer credits");
+    }
+    let href;
+    try {
+        href = new URL(credit.href);
+    }
+    catch {
+        // Reported below with the value that failed.
+    }
+    if (!href || (href.protocol !== "https:" && href.protocol !== "http:")) {
+        throw new AstroidConfigError(`\`credit.href\` must be an absolute http or https URL, such as "https://example.com", ` +
+            `but it's "${credit.href}"`);
+    }
+    const logo = credit.logo;
+    if (logo !== undefined &&
+        !(logo.startsWith("/") && !logo.startsWith("//")) &&
+        !logo.startsWith("https://")) {
+        throw new AstroidConfigError(`\`credit.logo\` must be a root-relative path such as "/credit-mark.svg" or an ` +
+            `https URL, but it's "${logo}"`);
+    }
+}
+/**
+ * The options an app with no editor can't honor. Each configures the editor, a
+ * table it edits, or a surface only an editor reviews, so accepting one would
+ * be accepting a setting nothing reads.
+ */
+const EDITOR_ONLY_OPTIONS = [
+    ["sections", "the editable home page"],
+    ["sectionCatalog", "the page editor's sections"],
+    ["blockCatalog", "the page editor's blocks"],
+    ["media", "the media library"],
+    ["pages", "the editable pages"],
+    ["settings", "the Settings panel"],
+];
+/** Modules that only work with an editor, and why. */
+const EDITOR_ONLY_MODULES = {
+    realtime: "it syncs editors editing one page",
+    wholesaleInquiry: "its inquiries are reviewed in the editor",
+};
+function assertEditorFree(config) {
+    if (astroidHasEditor(config))
+        return;
+    const without = "An app with `editor: false` has no editor";
+    for (const [key, what] of EDITOR_ONLY_OPTIONS) {
+        if (config[key] !== undefined) {
+            throw new AstroidConfigError(`${without}, so \`${key}\` (${what}) would do nothing. Remove it, or drop \`editor: false\`.`);
+        }
+    }
+    if (config.inquiries === true) {
+        throw new AstroidConfigError(`${without} to review inquiries in, so \`inquiries: true\` would collect messages ` +
+            "nobody reads. Remove it, or drop `editor: false`.");
+    }
+    for (const module of [...(config.modules ?? []), ...(config.portal?.features ?? [])]) {
+        const why = EDITOR_ONLY_MODULES[module];
+        if (why) {
+            throw new AstroidConfigError(`${without}, so the \`${module}\` module can't work: ${why}. Remove it, or drop \`editor: false\`.`);
+        }
+    }
+    if (config.deploy?.mediaBase !== undefined) {
+        throw new AstroidConfigError(`${without} and no media library, so \`deploy.mediaBase\` would do nothing. Remove it.`);
+    }
+}
 export function defineAstroid(config) {
     if (!config.key || config.key.trim().length === 0) {
         throw new AstroidConfigError("Astroid config requires a non-empty `key` (it names the generated worker/D1/R2 bindings)");
@@ -211,6 +311,9 @@ export function defineAstroid(config) {
     // an answer. Fail loudly, at config load, naming the workaround.
     assertCrons(config);
     assertTenancy(config);
+    assertAllowSlugs(config);
+    assertEditorFree(config);
+    assertCredit(config.credit);
     if (config.portal?.gated) {
         throw new AstroidConfigError("`portal.gated` is not implemented: it is accepted but wires no guard, so the site " +
             "would be fully public while appearing gated. Remove it, and gate the whole site by " +