astroidjs 0.15.0 → 0.17.0

package/README.md

@@ -339,11 +339,13 @@ Astro app—in one step.
 
 ## Roadmap
 
-1. ✅ **Config surface** (`defineAstroid`)—single brand per project.
-2. ✅ Config → generated Drizzle schema.
-3. ✅ Config → generated `worker.ts` + middleware (no hand-wired route ordering).
-4. ✅ `<Section>` / `<Editable>` / `<Collection>` component primitives.
-5. ✅ **CLI**—`astroid generate / doctor / dev / build / deploy`; `create-astroid`
+Every item on the first roadmap has shipped:
+
+1. **Config surface** (`defineAstroid`)—single brand per project.
+2. Config → generated Drizzle schema.
+3. Config → generated `worker.ts` + middleware (no hand-wired route ordering).
+4. `<Section>` / `<Editable>` / `<Collection>` component primitives.
+5. **CLI**—`astroid generate / doctor / dev / build / deploy`; `create-astroid`
    scaffold (`pnpm create astroid`).
 
 ## License

package/bin/astroid.mjs

@@ -8,6 +8,7 @@
 //   astroid dev      [...astro args]                   generate, then `astro dev`
 //   astroid build    [...astro args]                   generate, then `astro build`
 //   astroid deploy   [--dry-run] [--yes] [--local]     provision + migrate + secrets + deploy
+//   astroid ship     production | preview              migrate, then deploy or preview (Workers Builds)
 //
 // It loads the project's `astroid.config.ts` with Node's native TypeScript
 // stripping (the config only imports the built `astroidjs`, so it resolves), and
@@ -15,6 +16,7 @@
 // CLI ships in, no dependency on node_modules layout (mirrors the louise bin).
 
 import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join, resolve } from "node:path";
@@ -23,6 +25,16 @@ import { pathToFileURL } from "node:url";
 
 const GENERATORS_URL = new URL("../dist/index.js", import.meta.url).href;
 
+/** The repository root, where `.github/` lives, or null outside a git checkout.
+ *  A site's Astroid project can sit below it (`workers/site`). */
+function gitRoot(cwd) {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" }).trim();
+  } catch {
+    return null;
+  }
+}
+
 // --- tiny arg parser -------------------------------------------------------
 // Splits at the first non-flag token into { command, flags, rest }. `rest` is
 // everything after the command, preserved verbatim so `dev`/`build` can forward
@@ -77,7 +89,12 @@ async function loadConfig(cwd, explicit) {
 
 // --- commands --------------------------------------------------------------
 async function cmdGenerate(cwd, flags, { quiet = false } = {}) {
-  const { generateAstroidProject, generateAstroidScaffoldFiles } = await import(GENERATORS_URL);
+  const {
+    generateAstroidProject,
+    generateAstroidScaffoldFiles,
+    generateAstroidReleaseWorkflow,
+    ASTROID_RELEASE_WORKFLOW_PATH,
+  } = await import(GENERATORS_URL);
   const { config } = await loadConfig(cwd, flags.config);
   const files = generateAstroidProject(config);
   for (const file of files) {
@@ -87,6 +104,16 @@ async function cmdGenerate(cwd, flags, { quiet = false } = {}) {
     if (!quiet) out(`  ✓ ${file.path}`);
   }
 
+  // The release workflow, at the repository root rather than the project,
+  // because GitHub reads workflows only from there. Regenerated like the trio.
+  const root = gitRoot(cwd);
+  if (root) {
+    const abs = join(root, ASTROID_RELEASE_WORKFLOW_PATH);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, generateAstroidReleaseWorkflow());
+    if (!quiet) out(`  ✓ ${ASTROID_RELEASE_WORKFLOW_PATH} (repository root)`);
+  }
+
   // Scaffold-once files for whatever modules the config switched on.
   //
   // Written only when ABSENT—each is a seam the project owns, so overwriting
@@ -124,8 +151,15 @@ async function cmdGenerate(cwd, flags, { quiet = false } = {}) {
 }
 
 async function cmdDoctor(cwd, flags) {
-  const { generateAstroidProject, generateAstroidScaffoldFiles, astroidUsesQueues, astroidCrons } =
-    await import(GENERATORS_URL);
+  const {
+    generateAstroidProject,
+    generateAstroidScaffoldFiles,
+    astroidUsesQueues,
+    astroidCrons,
+    checkWranglerPreviews,
+    generateAstroidReleaseWorkflow,
+    ASTROID_RELEASE_WORKFLOW_PATH,
+  } = await import(GENERATORS_URL);
   const { config, path: configPath } = await loadConfig(cwd, flags.config);
 
   const problems = []; // { level: "error" | "warn", msg }
@@ -264,6 +298,31 @@ async function cmdDoctor(cwd, flags) {
     }
   }
 
+  // 1c. The release workflow at the repository root: a tag on `main` moves
+  //     `deploy/production`, which Workers Builds deploys. Stale is an error for
+  //     the same reason the trio's is: it decides which commits reach production.
+  const root = gitRoot(cwd);
+  if (!root) {
+    warn(`not in a git checkout, so ${ASTROID_RELEASE_WORKFLOW_PATH} can't be checked.`);
+  } else {
+    const abs = join(root, ASTROID_RELEASE_WORKFLOW_PATH);
+    if (!existsSync(abs))
+      err(`${ASTROID_RELEASE_WORKFLOW_PATH} is missing — run \`astroid generate\`.`);
+    else if (readFileSync(abs, "utf8") !== generateAstroidReleaseWorkflow())
+      err(`${ASTROID_RELEASE_WORKFLOW_PATH} is stale — run \`astroid generate\`.`);
+    else ok(`${ASTROID_RELEASE_WORKFLOW_PATH} is up to date`);
+  }
+
+  // 2b. Staging: the `previews` block (louise-toolkit ADR 0017). A Preview
+  //     inherits nothing, so a binding left out crashes it and one copied from
+  //     production writes production data; see src/project/previews.ts.
+  if (existsSync(wranglerPath)) {
+    const previews = checkWranglerPreviews(readFileSync(wranglerPath, "utf8"));
+    for (const m of previews.ok) ok(m);
+    for (const m of previews.warnings) warn(m);
+    for (const m of previews.errors) err(m);
+  }
+
   // 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.
@@ -403,7 +462,10 @@ function provisionPlan(facts) {
   }
   for (const { binding, id } of facts.kv) {
     if (isPlaceholder(id)) {
-      steps.push({ kind: "kv", name: binding, args: ["kv", "namespace", "create", binding] });
+      // The placeholder names the namespace (`<run: wrangler kv namespace
+      // create acme-rl>`); an older one without a name falls back to the binding.
+      const title = id.match(/kv namespace create ([^\s>]+)/)?.[1] ?? binding;
+      steps.push({ kind: "kv", name: title, binding, args: ["kv", "namespace", "create", title] });
     }
   }
   // Queues carry no id, so there's no placeholder to test—creating one that
@@ -531,7 +593,7 @@ async function cmdDeploy(cwd, flags, rest) {
         (rows) => rows.find((r) => typeof r.title === "string" && r.title.endsWith(s.name))?.id,
       );
       if (id) {
-        wrangler = patchKvId(wrangler, s.name, id);
+        wrangler = patchKvId(wrangler, s.binding, id);
         writeFileSync(wranglerPath, wrangler);
         out(`  ↳ ${s.name} id = ${id}`);
       } else {
@@ -597,10 +659,294 @@ Usage:
   astroid dev      [...astro args]                   regenerate, then run \`astro dev\`
   astroid build    [...astro args]                   regenerate, then run \`astro build\`
   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
 
 New project:  pnpm create astroid@latest
 `;
 
+// `astroid provision` creates what `wrangler.jsonc` still names by placeholder,
+// top level and `previews` alike, and writes each new ID back in place of its
+// placeholder. It never deploys, so it's safe to run before a site's first
+// release, and re-running it only creates what's still missing. It creates the
+// staging secrets that need no person (a random SESSION_SECRET and Turnstile's
+// test secret), skipping any the store already has. Every other secret, and
+// dashboard settings, need a person, so it prints those instead.
+//
+// Every wrangler call runs in the site's directory, so wrangler reads the same
+// `wrangler.jsonc` for each and picks the same account: its `account_id`, which
+// wrangler prefers to CLOUDFLARE_ACCOUNT_ID.
+async function cmdProvision(cwd, rest) {
+  const dryRun = rest.includes("--dry-run");
+  const assumeYes = rest.includes("--yes") || rest.includes("-y");
+  const wranglerPath = join(cwd, "wrangler.jsonc");
+  if (!existsSync(wranglerPath)) fail("wrangler.jsonc not found — run inside an Astroid project.");
+
+  const {
+    provisionPlan,
+    applyProvisionedId,
+    stagingSecretSteps,
+    secretNamesFromList,
+    TURNSTILE_TEST_SECRET,
+  } = await import(GENERATORS_URL);
+  let text = readFileSync(wranglerPath, "utf8");
+  const plan = provisionPlan(text);
+  const wranglerBin = resolveBin(cwd, "wrangler", "wrangler");
+
+  // Which staging secrets already exist, per store, so a re-run creates nothing
+  // twice. Listing is read-only, so a dry run does it too.
+  const existing = new Map();
+  if (wranglerBin) {
+    for (const storeId of new Set(plan.secrets.filter((s) => s.create).map((s) => s.storeId))) {
+      const names = listStoreSecrets(wranglerBin, cwd, storeId, secretNamesFromList);
+      if (names) existing.set(storeId, names);
+    }
+  }
+  const secretSteps = stagingSecretSteps(plan.secrets, existing);
+  const toCreate = secretSteps.filter((s) => s.status === "create");
+
+  out("astroid provision — plan:\n");
+  if (plan.steps.length === 0) out("  (nothing to create: every binding has an ID)");
+  for (const s of plan.steps) {
+    const note = s.kind === "r2" ? "   (an existing bucket is fine)" : "";
+    out(`  wrangler ${s.args.join(" ")}${note}`);
+  }
+  const envAccount = process.env.CLOUDFLARE_ACCOUNT_ID;
+  if (!plan.hasAccount && !envAccount) {
+    out(
+      "\n  ! No account_id in wrangler.jsonc and no CLOUDFLARE_ACCOUNT_ID, so wrangler picks one.",
+    );
+  } else if (plan.accountId && envAccount && envAccount !== plan.accountId) {
+    out(
+      `\n  ! wrangler.jsonc's account_id (${plan.accountId}) wins over ` +
+        `CLOUDFLARE_ACCOUNT_ID (${envAccount}), so provision uses ${plan.accountId}.`,
+    );
+  }
+  if (secretSteps.length > 0) {
+    out("\nStaging secrets it creates itself:");
+    for (const { secret, status } of secretSteps) {
+      const what =
+        status === "create"
+          ? `will create, with ${secret.create === "random" ? "a new random value" : "Turnstile's always-passes test secret"}`
+          : status === "exists"
+            ? "exists, so it's left alone"
+            : wranglerBin
+              ? "couldn't list the store, so it's left for you"
+              : "can't check without wrangler, so it's left for you";
+      out(`  [staging] ${secret.secretName} in store ${secret.storeId}: ${what}`);
+    }
+  }
+  // The secrets a person still sets: every one provision doesn't create, and
+  // any it meant to but couldn't.
+  const printSecrets = (failed = []) => {
+    const byHand = [
+      ...plan.secrets.filter((s) => !s.create),
+      ...secretSteps.filter((s) => s.status === "unknown").map((s) => s.secret),
+      ...failed,
+    ];
+    if (byHand.length === 0) return;
+    out("\nSecrets Store secrets it binds; create any that don't exist yet:");
+    for (const s of byHand) {
+      out(
+        `  [${s.environment}] wrangler secrets-store secret create ${s.storeId} ` +
+          `--name ${s.secretName} --scopes workers --remote`,
+      );
+    }
+  };
+
+  if (dryRun) {
+    printSecrets();
+    out("\n(dry run — nothing created)");
+    return;
+  }
+  if ((plan.steps.length > 0 || toCreate.length > 0) && !assumeYes) {
+    if (!process.stdin.isTTY)
+      fail("Refusing to create resources non-interactively. Re-run with --yes.");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = (await rl.question("\nCreate the above? [y/N] ")).trim().toLowerCase();
+    rl.close();
+    if (answer !== "y" && answer !== "yes") {
+      out("Aborted.");
+      return;
+    }
+  }
+
+  if (!wranglerBin) fail("Could not find `wrangler` in this project.");
+  for (const s of plan.steps) {
+    out(`\n▸ wrangler ${s.args.join(" ")}`);
+    // A create that fails because the resource exists is fine: the lookup
+    // below finds it, so a re-run after a partial one picks up where it was.
+    spawnSync(process.execPath, [wranglerBin, ...s.args], { cwd, stdio: "inherit" });
+    if (s.kind === "r2") continue;
+    const id =
+      s.kind === "d1"
+        ? lookupId(
+            wranglerBin,
+            cwd,
+            ["d1", "list", "--json"],
+            (rows) => rows.find((r) => r.name === s.name)?.uuid,
+          )
+        : lookupId(
+            wranglerBin,
+            cwd,
+            ["kv", "namespace", "list"],
+            (rows) => rows.find((r) => r.title === s.name)?.id,
+          );
+    if (!id) fail(`Couldn't find the ID of ${s.name} after creating it. Fill it in by hand.`);
+    text = applyProvisionedId(text, s.placeholder, id);
+    writeFileSync(wranglerPath, text);
+    out(`  ↳ ${s.name} = ${id}`);
+  }
+
+  // The value goes to wrangler as an argument of a direct spawn, never through
+  // a shell, and is never printed: wrangler shows it as REDACTED.
+  const failed = [];
+  for (const { secret } of toCreate) {
+    const args = [
+      "secrets-store",
+      "secret",
+      "create",
+      secret.storeId,
+      "--name",
+      secret.secretName,
+      "--scopes",
+      "workers",
+      "--remote",
+    ];
+    out(`\n▸ wrangler ${args.join(" ")} --value <${secret.create}>`);
+    const value =
+      secret.create === "random" ? randomBytes(48).toString("base64") : TURNSTILE_TEST_SECRET;
+    const res = spawnSync(process.execPath, [wranglerBin, ...args, "--value", value], {
+      cwd,
+      stdio: "inherit",
+    });
+    if (res.status !== 0) failed.push(secret);
+  }
+
+  printSecrets(failed);
+  const unlisted = [
+    ...new Set(secretSteps.filter((s) => s.status === "unknown").map((s) => s.secret.storeId)),
+  ];
+  if (unlisted.length > 0 || failed.length > 0) {
+    if (unlisted.length > 0) {
+      out(
+        `\n✘ Couldn't list Secrets Store ${unlisted.join(", ")}, so its staging secrets ` +
+          "weren't created. Check that the store is in this account, then re-run.",
+      );
+    }
+    if (failed.length > 0) {
+      out(`\n✘ Couldn't create ${failed.map((s) => s.secretName).join(", ")}. Re-run to retry.`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  out("\n✓ Provisioned. Commit wrangler.jsonc; the dashboard steps are in the site's RUNBOOK.");
+}
+
+/**
+ * The secret names in a Secrets Store, or null when it can't be listed. Wrangler
+ * prints a table, a page at a time, and fails on a page with no secrets, which
+ * is how an empty store, or the page after the last one, reads.
+ */
+function listStoreSecrets(wranglerBin, cwd, storeId, secretNamesFromList) {
+  const PER_PAGE = 100; // The API's maximum.
+  const names = new Set();
+  for (let page = 1; page <= 50; page++) {
+    const res = spawnSync(
+      process.execPath,
+      [
+        wranglerBin,
+        ...["secrets-store", "secret", "list", storeId, "--remote"],
+        ...["--per-page", String(PER_PAGE), "--page", String(page)],
+      ],
+      { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] },
+    );
+    if (res.status !== 0) {
+      return `${res.stdout}${res.stderr}`.includes("returned no secrets") ? names : null;
+    }
+    const found = secretNamesFromList(res.stdout);
+    const before = names.size;
+    for (const name of found) names.add(name);
+    if (found.length < PER_PAGE || names.size === before) break;
+  }
+  return names;
+}
+
+// `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.
+//
+//   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) {
+  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 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() {
   const { command, flags, rest } = parseArgs(process.argv.slice(2));
   const cwd = flags.cwd ? resolve(flags.cwd) : process.cwd();
@@ -622,6 +968,12 @@ async function main() {
     case "deploy":
       await cmdDeploy(cwd, flags, rest);
       break;
+    case "ship":
+      await cmdShip(cwd, rest[0]);
+      break;
+    case "provision":
+      await cmdProvision(cwd, rest);
+      break;
     case "help":
     case "--help":
     case "-h":

package/dist/auth/index.js

@@ -50,10 +50,10 @@ export function assertAuthIsolation(config) {
         return;
     if (!portal.cookiePrefix || portal.cookiePrefix === ASTROID_EDITOR_COOKIE_PREFIX) {
         throw new AstroidConfigError(`portal.cookiePrefix must be set and distinct from the editor's (${JSON.stringify(ASTROID_EDITOR_COOKIE_PREFIX)}). Two instances sharing a cookie prefix silently sign you out of one when ` +
-            'you sign into the other. Pick a project-specific prefix (e.g. "acme_shop").');
+            'you sign into the other. Pick a project-specific prefix (for example, "acme_shop").');
     }
     if (portal.tablePrefix === ASTROID_EDITOR_TABLE_PREFIX) {
-        throw new AstroidConfigError(`portal.tablePrefix must differ from the editor's (${JSON.stringify(ASTROID_EDITOR_TABLE_PREFIX)}) — a shared table prefix merges the two instances into one user table. ` +
+        throw new AstroidConfigError(`portal.tablePrefix must differ from the editor's (${JSON.stringify(ASTROID_EDITOR_TABLE_PREFIX)}): a shared table prefix merges the two instances into one user table. ` +
             "Leave it unset (the unprefixed `user`/`session` tables) or use a distinct prefix.");
     }
 }

package/dist/commerce/roles.js

@@ -109,7 +109,7 @@ export function assertCommerceRoles(commerce) {
                 invoicing: "invoicing",
                 pos: "locations/inventory",
             }[role];
-            throw new AstroidConfigError(`commerce: ${provider} can't serve the "${role}" role — its louise-toolkit client has no ${missing} API. Providers that can: ${able.join(", ")}.`);
+            throw new AstroidConfigError(`commerce: ${provider} can't serve the "${role}" role, because its louise-toolkit client has no ${missing} API. Providers that can: ${able.join(", ")}.`);
         }
     };
     // The shorthand assigns itself to a role it can serve, so it only has to be a

package/dist/commerce/sync.js

@@ -145,7 +145,8 @@ export async function astroidCatalogSync(items, options) {
         }
     }
     if (items.length > 0 && result.failed === items.length) {
-        throw new AstroidUsageError(`Catalog sync failed for all ${items.length} item(s) — nothing was written. ` +
+        const scope = items.length === 1 ? "the only item" : `all ${items.length} items`;
+        throw new AstroidUsageError(`Catalog sync failed for ${scope}, so nothing was written. ` +
             `First error: ${result.errors[0]?.message ?? "unknown"}. ` +
             "This is usually an unapplied migration (the catalog table doesn't exist yet) " +
             "or an unavailable D1 binding.");

package/dist/config.js

@@ -102,7 +102,7 @@ function assertCrons(config) {
         }
         const owner = seen.get(expression);
         if (owner) {
-            throw new AstroidConfigError(`Duplicate cron \`${expression}\` — it already belongs to ${owner}. One \`scheduled\` ` +
+            throw new AstroidConfigError(`Duplicate cron \`${expression}\`: it already belongs to ${owner}. One \`scheduled\` ` +
                 "handler dispatches on the expression, so the first branch wins and this one would " +
                 "never run. Use a different minute.");
         }
@@ -123,10 +123,10 @@ function assertTenancy(config) {
         return;
     const pattern = tenancy.hostPattern?.trim();
     if (!pattern) {
-        throw new AstroidConfigError('`tenancy.hostPattern` is required, e.g. `"*.example.com"`');
+        throw new AstroidConfigError('`tenancy.hostPattern` is required: a wildcard such as `"*.example.com"`');
     }
     if (!pattern.startsWith("*.")) {
-        throw new AstroidConfigError(`\`tenancy.hostPattern\` must be a wildcard starting with "*." — got "${pattern}". ` +
+        throw new AstroidConfigError(`\`tenancy.hostPattern\` must be a wildcard starting with "*.", but it's "${pattern}". ` +
             "A fixed host is a custom domain: put it in `hosts` instead.");
     }
     const apex = pattern.slice(2);
@@ -145,17 +145,17 @@ function assertTenancy(config) {
     // that renders the wrong page, with nothing pointing back at the config.
     for (const [label, prefix] of Object.entries(tenancy.apps ?? {})) {
         if (!label || label.includes(".")) {
-            throw new AstroidConfigError(`\`tenancy.apps\` label "${label}" must be a single subdomain label — ` +
-                "Cloudflare's wildcard matches one level.");
+            throw new AstroidConfigError(`\`tenancy.apps\` label "${label}" must be a single subdomain label, ` +
+                "because Cloudflare's wildcard matches one level.");
         }
         if ((tenancy.reserved ?? []).includes(label)) {
             throw new AstroidConfigError(`"${label}" is in both \`tenancy.apps\` and \`tenancy.reserved\`. ` +
-                "An app label is implicitly reserved — keep it in `apps` only, or the " +
+                "An app label is implicitly reserved, so keep it in `apps` only, or the " +
                 "two lists drift and `reserved` silently wins.");
         }
         if (!prefix.startsWith("/") || prefix === "/" || prefix.endsWith("/")) {
             throw new AstroidConfigError(`\`tenancy.apps.${label}\` must be an internal path prefix like "/studio" ` +
-                `(leading slash, no trailing slash, not "/") — got "${prefix}". ` +
+                `(leading slash, no trailing slash, not "/"), but it's "${prefix}". ` +
                 'The rewrite is `prefix + pathname`, so "/" or a trailing slash produces "//…".');
         }
     }
@@ -212,9 +212,9 @@ export function defineAstroid(config) {
     assertCrons(config);
     assertTenancy(config);
     if (config.portal?.gated) {
-        throw new AstroidConfigError("`portal.gated` is not implemented — it is accepted but wires no guard, so the site " +
+        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 " +
-            'listing the prefixes you mean in `portal.routes` (e.g. `[{ prefix: "/" }]` with your ' +
+            'listing the prefixes you mean in `portal.routes` (for example, `[{ prefix: "/" }]` with your ' +
             "login and auth paths ahead of it).");
     }
     return config;

package/dist/portfolio/scaffold.js

@@ -62,8 +62,12 @@ export function generateAstroidGalleryPage(config) {
         "  // No DB binding yet (pre-provision)—render the empty state.",
         "}",
         "",
+        "// This environment's media base: production's, or a staging Preview's own",
+        "// `/media`, where the Preview's uploads live.",
+        `const mediaBase = (env.MEDIA_URL || ${JSON.stringify(mediaBase)}).replace(/\\/+$/, "");`,
+        "",
         "const items: GalleryItem[] = rows.map((row) => ({",
-        `  src: \`${mediaBase}/\${row.key}\`,`,
+        "  src: `${mediaBase}/${row.key}`,",
         '  // An asset with no alt gets "" rather than its filename: an empty alt makes',
         "  // a screen reader skip a decorative tile, while a filename is read aloud",
         "  // character by character and tells the listener nothing.",

package/dist/project/actions.js

@@ -61,6 +61,7 @@ export function generateAstroidActions(config) {
         // as a literal, and an unused import is a lint error in its own file.
         ...(columnsOverride ? [] : ["  ASTROID_SETTINGS_COLUMNS,"]),
         "  ASTROID_SETTINGS_IMAGE_KEYS,",
+        "  astroidMediaBase,",
         "  astroidPagesCollection,",
         '} from "astroidjs";',
         'import astroidConfig from "../../astroid.config.js";',
@@ -117,7 +118,11 @@ export function generateAstroidActions(config) {
         "        // than copied—a second literal here is a list that drifts from the",
         "        // one the routes check against, and nothing would fail when it did.",
         ...settingsExtra,
-        '        mediaBase: astroidConfig.deploy?.mediaBase ?? "/media",',
+        "        // Read on each save, so a staging Preview accepts images from its own",
+        "        // `/media` (see astroidMediaBase).",
+        "        get mediaBase() {",
+        "          return astroidMediaBase(astroidConfig);",
+        "        },",
         "      }),",
         "    ),",
         "  },",

package/dist/project/generate.js

@@ -209,10 +209,11 @@ export function generateAstroidWrangler(config) {
     p("  // KV: RL = the security rate limiter (it also holds the daily site-health");
     p("  // summary under its own key—one small singleton blob, not worth a binding");
     p("  // someone has to remember to provision); DRAFTS = the autosave write-buffer.");
-    p("  // Create each: `wrangler kv namespace create <RL|DRAFTS>`.");
+    p("  // Named for the project, so two sites in one account don't collide.");
+    p("  // `astroid provision` creates each and fills in its id.");
     p('  "kv_namespaces": [');
-    p('    { "binding": "RL", "id": "<run: wrangler kv namespace create RL>" },');
-    p('    { "binding": "DRAFTS", "id": "<run: wrangler kv namespace create DRAFTS>" },');
+    p(`    { "binding": "RL", "id": "<run: wrangler kv namespace create ${key}-rl>" },`);
+    p(`    { "binding": "DRAFTS", "id": "<run: wrangler kv namespace create ${key}-drafts>" },`);
     p("  ],");
     // Email Sending. NOT optional decoration: `src/env.d.ts` declares EMAIL as a
     // required member, and Better Auth's magic-link path console-logs the link in

package/dist/project/index.d.ts

@@ -2,3 +2,6 @@ export * from "./generate.js";
 export * from "./actions.js";
 export * from "./scaffold.js";
 export * from "./seed.js";
+export * from "./previews.js";
+export * from "./release.js";
+export * from "./provision.js";

package/dist/project/index.js

@@ -6,3 +6,6 @@ export * from "./generate.js";
 export * from "./actions.js";
 export * from "./scaffold.js";
 export * from "./seed.js";
+export * from "./previews.js";
+export * from "./release.js";
+export * from "./provision.js";

package/dist/project/previews.d.ts

@@ -0,0 +1,18 @@
+/** One finding, in the order `doctor` prints them. */
+export interface PreviewsFindings {
+    ok: string[];
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Parse JSONC: strip `//` and block comments outside strings, then trailing
+ * commas. `wrangler.jsonc` is written by hand and commented heavily, which is
+ * why `doctor` reads the rest of it by regex; this check needs the structure.
+ */
+export declare function parseJsonc(text: string): unknown;
+/**
+ * Check the `previews` block of a `wrangler.jsonc` against its production
+ * settings. Returns what passed and what didn't; an error means a Preview
+ * would crash or touch production.
+ */
+export declare function checkWranglerPreviews(text: string): PreviewsFindings;