astroidjs 0.17.0 → 0.19.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

@@ -6,7 +6,7 @@
 //   astroid generate [--config <path>] [--cwd <dir>]   regenerate schema/worker/middleware from the config
 //   astroid doctor   [--config <path>] [--cwd <dir>]   validate config + bindings + generated-file freshness
 //   astroid dev      [...astro args]                   generate, then `astro dev`
-//   astroid build    [...astro args]                   generate, then `astro build`
+//   astroid build    [...astro args]                   generate, `astro build`, then fix the built wrangler.json
 //   astroid deploy   [--dry-run] [--yes] [--local]     provision + migrate + secrets + deploy
 //   astroid ship     production | preview              migrate, then deploy or preview (Workers Builds)
 //
@@ -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") {
@@ -157,6 +173,8 @@ async function cmdDoctor(cwd, flags) {
     astroidUsesQueues,
     astroidCrons,
     checkWranglerPreviews,
+    astroidRunsMigrations,
+    migrationsOwnershipError,
     generateAstroidReleaseWorkflow,
     ASTROID_RELEASE_WORKFLOW_PATH,
   } = await import(GENERATORS_URL);
@@ -194,7 +212,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\`.`);
@@ -326,12 +344,21 @@ async function cmdDoctor(cwd, flags) {
   // 3. migrations directory: the D1 `migrations_dir` wrangler.jsonc declares,
   //    or `migrations/`, the generated default, when it names none. A site that
   //    keeps its migrations under another name (drizzle/) isn't missing them.
+  //    An app with `deploy.migrations: false` applies none, because another
+  //    app owns the database's schema, so it needs no directory. It must not
+  //    name one either: that contradiction means someone expects it to migrate.
   const wranglerText = existsSync(wranglerPath) ? readFileSync(wranglerPath, "utf8") : "";
-  const migrationsDir =
-    wranglerText.match(/"migrations_dir"\s*:\s*"([^"]+)"/)?.[1]?.replace(/\/+$/, "") ??
-    "migrations";
-  if (existsSync(join(cwd, migrationsDir))) ok(`${migrationsDir}/ directory present`);
-  else warn(`no ${migrationsDir}/ directory — create your D1 schema migrations there.`);
+  if (!astroidRunsMigrations(config)) {
+    const ownership = migrationsOwnershipError(config, wranglerText);
+    if (ownership) err(ownership);
+    else ok("deploy.migrations is false: another app migrates this database");
+  } else {
+    const migrationsDir =
+      wranglerText.match(/"migrations_dir"\s*:\s*"([^"]+)"/)?.[1]?.replace(/\/+$/, "") ??
+      "migrations";
+    if (existsSync(join(cwd, migrationsDir))) ok(`${migrationsDir}/ directory present`);
+    else warn(`no ${migrationsDir}/ directory — create your D1 schema migrations there.`);
+  }
 
   // 4. Local secret provisioning—which modules will run dormant under
   //    `astroid dev`, and what to set to wake them.
@@ -398,7 +425,33 @@ async function cmdAstro(cwd, subcommand, flags, rest) {
     );
   }
   const child = spawn(process.execPath, [astroBin, subcommand, ...rest], { stdio: "inherit", cwd });
-  child.on("exit", (code) => process.exit(code ?? 0));
+  child.on("exit", async (code) => {
+    // A failed build keeps its exit code and its output as it left them.
+    if (subcommand === "build" && code === 0) await fixBuiltWranglerConfig(cwd);
+    process.exit(code ?? 0);
+  });
+}
+
+/** Delete `legacy_env` from the built Wrangler config, which current Wrangler
+ *  rejects (see src/project/build-output.ts). Warns rather than failing: the
+ *  build itself succeeded, and an older Wrangler deploys the file as is. */
+async function fixBuiltWranglerConfig(cwd) {
+  const { WRANGLER_DEPLOY_REDIRECT, builtWranglerConfigPath, stripLegacyEnv } = await import(
+    GENERATORS_URL
+  );
+  const redirectPath = join(cwd, WRANGLER_DEPLOY_REDIRECT);
+  const redirect = existsSync(redirectPath) ? readFileSync(redirectPath, "utf8") : null;
+  const configPath = resolve(cwd, builtWranglerConfigPath(redirect));
+  try {
+    const next = stripLegacyEnv(readFileSync(configPath, "utf8"));
+    if (next === null) return;
+    writeFileSync(configPath, next);
+    out(`astroid: removed legacy_env from ${rel(cwd, configPath)}`);
+  } catch (err) {
+    process.stderr.write(
+      `astroid: warning: couldn't check ${rel(cwd, configPath)} for legacy_env: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
 }
 
 /** Resolve a project-local CLI bin (astro, wrangler) to an absolute path via the
@@ -501,7 +554,9 @@ async function cmdDeploy(cwd, flags, rest) {
   const assumeYes = rest.includes("--yes") || rest.includes("-y");
   const remoteArgs = rest.includes("--local") ? [] : ["--remote"];
 
-  await loadConfig(cwd, flags.config); // validates the config (throws on a bad shape)
+  const { config } = await loadConfig(cwd, flags.config); // validates the shape, or throws
+  const { astroidRunsMigrations, ASTROID_SKIP_MIGRATIONS_NOTE } = await import(GENERATORS_URL);
+  const migrate = astroidRunsMigrations(config);
   const wranglerPath = join(cwd, "wrangler.jsonc");
   if (!existsSync(wranglerPath)) fail("wrangler.jsonc not found — run inside an Astroid project.");
 
@@ -521,7 +576,11 @@ async function cmdDeploy(cwd, flags, rest) {
   out("  Provision:");
   if (plan.length === 0) out("    (all bindings already have ids)");
   for (const s of plan) out(`    wrangler ${s.args.join(" ")}`);
-  out(`\n  Migrate:  wrangler d1 migrations apply DB ${remoteArgs.join(" ")}`.trimEnd());
+  out(
+    migrate
+      ? `\n  Migrate:  wrangler d1 migrations apply DB ${remoteArgs.join(" ")}`.trimEnd()
+      : `\n  Migrate:  ${ASTROID_SKIP_MIGRATIONS_NOTE}`,
+  );
   out("  Secrets:  wrangler secret put SESSION_SECRET   (prompted)");
   out("  Deploy:   wrangler deploy\n");
   if (!facts.hasAccount) {
@@ -602,10 +661,14 @@ async function cmdDeploy(cwd, flags, rest) {
     }
   }
 
-  // 2) Migrations.
-  out(`\n▸ wrangler d1 migrations apply DB ${remoteArgs.join(" ")}`.trimEnd());
-  if (runInherit(["d1", "migrations", "apply", "DB", ...remoteArgs]).status !== 0)
-    fail("Migrations failed.");
+  // 2) Migrations, unless another app owns this database's schema.
+  if (!migrate) {
+    out(`\n${ASTROID_SKIP_MIGRATIONS_NOTE}`);
+  } else {
+    out(`\n▸ wrangler d1 migrations apply DB ${remoteArgs.join(" ")}`.trimEnd());
+    if (runInherit(["d1", "migrations", "apply", "DB", ...remoteArgs]).status !== 0)
+      fail("Migrations failed.");
+  }
 
   // 3) Secrets (interactive; wrangler prompts for the value).
   out("\n▸ wrangler secret put SESSION_SECRET");
@@ -657,7 +720,7 @@ Usage:
   astroid generate [--config <path>] [--cwd <dir>]   regenerate src/schema.ts, src/worker.ts, src/middleware.ts
   astroid doctor   [--config <path>] [--cwd <dir>]   validate config, bindings, and generated-file freshness
   astroid dev      [...astro args]                   regenerate, then run \`astro dev\`
-  astroid build    [...astro args]                   regenerate, then run \`astro build\`
+  astroid build    [...astro args]                   regenerate, run \`astro build\`, then drop legacy_env from its Wrangler config
   astroid deploy   [--dry-run] [--yes] [--local]     provision bindings + migrate + secrets + deploy
   astroid ship     production | preview              migrate D1, then deploy or preview (Workers Builds runs this)
   astroid provision [--dry-run] [--yes]              create the resources wrangler.jsonc names by placeholder, staging included
@@ -875,76 +938,45 @@ function listStoreSecrets(wranglerBin, cwd, storeId, secretNamesFromList) {
 // `astroid ship` is what Workers Builds runs, so the deploy logic lives in the
 // repository instead of a dashboard field. An account move once rewrote a
 // site's dashboard deploy command to a bare `wrangler deploy`, and migrations
-// silently stopped. Migrations run first, so new code never meets an old schema.
+// silently stopped. Migrations run first, so new code never meets an old schema,
+// unless `deploy.migrations` is false because another app owns the database.
 //
 //   astroid ship production   the deploy/production build: migrate D1, then deploy
 //   astroid ship preview      every other branch: migrate the staging D1, then
 //                             `wrangler preview`, named for the branch
-async function cmdShip(cwd, target) {
+async function cmdShip(cwd, target, flags) {
   if (target !== "production" && target !== "preview") {
     fail("Usage: astroid ship production | preview");
   }
   const wranglerBin = resolveBin(cwd, "wrangler", "wrangler");
   if (!wranglerBin) fail("Could not find `wrangler` in this project.");
-  const run = (args) => {
-    out(`\n▸ wrangler ${args.join(" ")}`);
-    const res = spawnSync(process.execPath, [wranglerBin, ...args], { cwd, stdio: "inherit" });
-    if (res.status !== 0) process.exit(res.status ?? 1);
-  };
   const wranglerPath = join(cwd, "wrangler.jsonc");
   if (!existsSync(wranglerPath)) fail("wrangler.jsonc not found — run inside an Astroid project.");
 
-  if (target === "production") {
-    run(["d1", "migrations", "apply", "DB", "--remote"]);
-    run(["deploy"]);
-    return;
+  // The plan is pure and tested in src/project/ship.ts; this only runs it.
+  const { astroidShipPlan } = await import(GENERATORS_URL);
+  const { config } = await loadConfig(cwd, flags.config);
+  const steps = astroidShipPlan(target, config, {
+    wrangler: readFileSync(wranglerPath, "utf8"),
+    root: cwd,
+    branch: process.env.WORKERS_CI_BRANCH,
+  });
+  for (const step of steps) {
+    if (step.note) {
+      out(`\n${step.note}`);
+    } else if (step.write) {
+      const abs = join(cwd, step.write.path);
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, step.write.contents);
+    } else {
+      out(`\n▸ wrangler ${step.run.join(" ")}`);
+      const res = spawnSync(process.execPath, [wranglerBin, ...step.run], {
+        cwd,
+        stdio: "inherit",
+      });
+      if (res.status !== 0) process.exit(res.status ?? 1);
+    }
   }
-
-  // The staging database is declared only inside `previews`, and wrangler's
-  // migrations command reads top-level `d1_databases`. So write a throwaway
-  // config naming it, derived from wrangler.jsonc on every run, rather than a
-  // second committed file that could drift from the binding.
-  const { parseJsonc } = await import(GENERATORS_URL);
-  const config = parseJsonc(readFileSync(wranglerPath, "utf8"));
-  const prodDb = (config.d1_databases ?? []).find((d) => d.binding === "DB");
-  const stagingDb = (config.previews?.d1_databases ?? []).find((d) => d.binding === "DB");
-  if (stagingDb && prodDb) {
-    const migrationsDir = resolve(cwd, prodDb.migrations_dir ?? "migrations");
-    const tmp = join(cwd, ".wrangler", "astroid-preview-migrations.jsonc");
-    mkdirSync(dirname(tmp), { recursive: true });
-    writeFileSync(
-      tmp,
-      JSON.stringify(
-        {
-          d1_databases: [
-            {
-              binding: "PREVIEW_DB",
-              database_name: stagingDb.database_name,
-              database_id: stagingDb.database_id,
-              migrations_dir: migrationsDir,
-            },
-          ],
-        },
-        null,
-        2,
-      ),
-    );
-    run(["d1", "migrations", "apply", "PREVIEW_DB", "--remote", "--config", tmp]);
-  } else {
-    out("\n(no staging D1 in `previews`, so no staging migrations to apply)");
-  }
-
-  // Workers Builds names the branch in WORKERS_CI_BRANCH; a Preview name is a
-  // DNS label, so a branch like feature/12-login becomes feature-12-login.
-  const branch = process.env.WORKERS_CI_BRANCH;
-  const name = branch
-    ? branch
-        .toLowerCase()
-        .replace(/[^a-z0-9-]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, 63)
-    : undefined;
-  run(["preview", ...(name ? ["--name", name] : [])]);
 }
 
 async function main() {
@@ -969,7 +1001,7 @@ async function main() {
       await cmdDeploy(cwd, flags, rest);
       break;
     case "ship":
-      await cmdShip(cwd, rest[0]);
+      await cmdShip(cwd, rest[0], flags);
       break;
     case "provision":
       await cmdProvision(cwd, rest);

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/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.
@@ -207,6 +208,12 @@ export interface QueuesConfig {
     cron?: string | false;
     /** Deliveries before Cloudflare routes a message to the DLQ. Default 5. */
     maxRetries?: number;
+    /**
+     * Seconds Cloudflare waits before redelivering a failed message. Default
+     * 30. The queue owns retries, so keep a handler's own client retries off
+     * rather than stacking them on top of these.
+     */
+    retryDelay?: number;
     /** Messages per consumer invocation. Default 10. */
     maxBatchSize?: number;
     /** Seconds the consumer waits to fill a batch. Default 30. */
@@ -317,9 +324,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
@@ -401,8 +408,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—*
@@ -450,17 +457,50 @@ 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
+     * scaffold-once `src/status-checks.ts`: for example, the catalog snapshot's
+     * age, or the last health scan's. The generated worker spreads them after
+     * Astroid's own `d1` and `content` checks.
+     */
+    checks?: boolean;
 }
 export interface DeployConfig {
     platform: "cloudflare";
     /** Media base for R2 + `cf-image` resizing—matches Louise's media route
      *  (`media.<brand>/cdn-cgi/image`). Default `"/media"`. */
     mediaBase?: string;
+    /**
+     * Whether `astroid ship` applies D1 migrations before it deploys. Default
+     * `true`. Set `false` for an app whose database another app migrates, such
+     * as a second Worker in the same repository that binds the first one's D1.
+     * One app owns a database's schema. When both migrate, one release tag runs
+     * two `wrangler d1 migrations apply` at once against one ledger, and a
+     * non-idempotent statement fails the second deploy.
+     */
+    migrations?: boolean;
 }
 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. */
@@ -481,7 +521,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
@@ -531,11 +571,14 @@ export interface AstroidConfig {
     media?: MediaConfig;
     /** The editable `pages` collection's site-owned write hooks. */
     pages?: PagesConfig;
+    /** The public status route's site-owned checks. */
+    status?: StatusConfig;
     /**
      * 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"`. */

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";
@@ -55,6 +55,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 +69,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" },
@@ -109,6 +114,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.
  *
@@ -211,6 +230,7 @@ export function defineAstroid(config) {
     // an answer. Fail loudly, at config load, naming the workaround.
     assertCrons(config);
     assertTenancy(config);
+    assertAllowSlugs(config);
     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 " +

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/build-output.d.ts

@@ -0,0 +1,18 @@
+/** Where `@astrojs/cloudflare` writes the built config when there's no redirect. */
+export declare const ASTROID_BUILT_WRANGLER_CONFIG = "dist/server/wrangler.json";
+/** The redirect file Wrangler reads to find the built config. */
+export declare const WRANGLER_DEPLOY_REDIRECT = ".wrangler/deploy/config.json";
+/**
+ * The built config's path, relative to the project root, found the way
+ * Wrangler finds it: the `configPath` in `.wrangler/deploy/config.json`, which
+ * is relative to that file's own folder, else {@link ASTROID_BUILT_WRANGLER_CONFIG}.
+ * Pass the redirect's text, or `null` when there isn't one.
+ */
+export declare function builtWranglerConfigPath(redirect: string | null): string;
+/**
+ * Remove `legacy_env` from a built Wrangler config. Returns the new text, or
+ * `null` when the field isn't there, so the caller leaves the file untouched.
+ * Keeps the file's indentation and every other key in its order. Throws when
+ * the text isn't a JSON object.
+ */
+export declare function stripLegacyEnv(text: string): string | null;