astroidjs 0.18.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

@@ -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") {
@@ -196,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\`.`);

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.
@@ -323,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
@@ -407,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—*
@@ -456,7 +457,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
@@ -484,7 +500,7 @@ export interface DeployConfig {
 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. */
@@ -505,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
@@ -561,7 +577,8 @@ 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"`. */

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/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

@@ -160,14 +160,25 @@ export function generateAstroidScaffoldFiles(config) {
     // 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.
+    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

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) {

package/dist/schema/framework.js

@@ -10,7 +10,7 @@
  *  (the worker route plan). */
 export function capturesInquiries(config) {
     // Explicit override wins—a site whose inquiry surface is a bespoke section
-    // (coracle's custom `contactForm`) can't be detected from the built-in
+    // (a custom `contactForm`, say) can't be detected from the built-in
     // vocabulary, so it says so directly.
     if (typeof config.inquiries === "boolean")
         return config.inquiries;

package/dist/workflow/advance.js

@@ -10,7 +10,7 @@
 // expected—`UPDATE … SET stage = ? WHERE id = ? AND stage = ?`—and treat "0 rows
 // changed" as the conflict signal rather than checking first and hoping.
 //
-// ORDERING MATTERS, and the reference gets it wrong. ghostfire's floor route
+// ORDERING MATTERS, and the reference gets it wrong. Its floor route
 // inserts the sign-off row and THEN runs the guarded update, so a double submit
 // writes two audit rows even though only one advance lands. Here the guarded
 // update goes first and the audit row is written only if it actually moved the

package/dist/workflow/config.js

@@ -2,7 +2,7 @@
 //
 // `defineWorkflow`—staged, audited pipelines.
 //
-// The shape this generalizes is ghostfire.coffee's production floor, and the
+// The shape this generalizes is a client site's production floor, and the
 // framing correction in #256 is the important part: despite the name "order
 // tracker", it is NOT queue- or Durable-Object-driven. It is a synchronous SSR
 // + D1 state machine—an integer `stage` column advanced by sign-off rows,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astroidjs",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Astroid — an opinionated meta-framework over Louise Toolkit and Astro for building editable, multi-editor sites on Cloudflare Workers.",
   "keywords": [
     "astro",

package/src/components/StageBar.astro

@@ -1,7 +1,7 @@
 ---
 // `<StageBar>`—a pipeline's progress as a segmented bar.
 //
-// Generalized from ghostfire's six-stage floor tracker, which hard-coded the
+// Generalized from a client site's six-stage floor tracker, which hard-coded the
 // segment count, the corner radii, the brand hex codes, and a mascot image.
 // Here the stage list drives everything and the colours are theme tokens, so a
 // four-stage onboarding flow and an eight-stage production line both work and

package/src/components/media-meta.ts

@@ -9,7 +9,7 @@
 //
 // So the whole page is resolved in ONE bounded `IN (...)` lookup before anything
 // renders, and the result is threaded down as `mediaMeta`. This is the pattern
-// ghostfire's `Sections.astro` arrived at independently, generalized.
+// a client site's `Sections.astro` arrived at independently, generalized.
 //
 // The collection step is SCHEMA-DRIVEN: it walks the catalog looking for fields
 // of `type: "image"` rather than hardcoding field names. That's what keeps it