astroidjs 0.17.0 → 0.18.0

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)
 //
@@ -157,6 +157,8 @@ async function cmdDoctor(cwd, flags) {
     astroidUsesQueues,
     astroidCrons,
     checkWranglerPreviews,
+    astroidRunsMigrations,
+    migrationsOwnershipError,
     generateAstroidReleaseWorkflow,
     ASTROID_RELEASE_WORKFLOW_PATH,
   } = await import(GENERATORS_URL);
@@ -326,12 +328,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 +409,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 +538,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 +560,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 +645,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 +704,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 +922,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 +985,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/config.d.ts

@@ -207,6 +207,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. */
@@ -451,11 +457,29 @@ export interface PagesConfig {
      */
     hooks?: boolean;
 }
+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 {
     /**
@@ -531,6 +555,8 @@ 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`

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;

package/dist/project/build-output.js

@@ -0,0 +1,64 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The post-build fix `astroid build` applies to the Worker config that
+// `@astrojs/cloudflare` writes.
+//
+// The adapter writes the built config from the Wrangler version it bundles, and
+// some of those versions include `legacy_env: true`. Current Wrangler rejects
+// the field, so a Workers Builds deploy running a newer Wrangler fails on the
+// build's own output. `true` was always the default, so deleting the field
+// changes nothing else.
+//
+// Pure: text in, text out, so it's tested directly and the CLI only does I/O.
+/** Where `@astrojs/cloudflare` writes the built config when there's no redirect. */
+export const ASTROID_BUILT_WRANGLER_CONFIG = "dist/server/wrangler.json";
+/** The redirect file Wrangler reads to find the built config. */
+export 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 function builtWranglerConfigPath(redirect) {
+    if (redirect === null)
+        return ASTROID_BUILT_WRANGLER_CONFIG;
+    let configPath;
+    try {
+        configPath = JSON.parse(redirect).configPath;
+    }
+    catch {
+        return ASTROID_BUILT_WRANGLER_CONFIG;
+    }
+    if (typeof configPath !== "string" || !configPath)
+        return ASTROID_BUILT_WRANGLER_CONFIG;
+    if (configPath.startsWith("/"))
+        return configPath;
+    // Resolved against `.wrangler/deploy/`, the redirect's folder.
+    const parts = [".wrangler", "deploy"];
+    for (const segment of configPath.split("/")) {
+        if (segment === "..")
+            parts.pop();
+        else if (segment !== "." && segment !== "")
+            parts.push(segment);
+    }
+    return parts.join("/");
+}
+/**
+ * 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 function stripLegacyEnv(text) {
+    const config = JSON.parse(text);
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+        throw new TypeError("The built Wrangler config isn't a JSON object.");
+    }
+    if (!Object.hasOwn(config, "legacy_env"))
+        return null;
+    const { legacy_env: _removed, ...rest } = config;
+    const indent = /^\{\r?\n([ \t]+)"/.exec(text)?.[1] ?? "";
+    const trailing = /\r?\n$/.exec(text)?.[0] ?? "";
+    return JSON.stringify(rest, null, indent) + trailing;
+}

package/dist/project/generate.d.ts

@@ -5,6 +5,25 @@ export interface GeneratedFile {
     path: string;
     contents: string;
 }
+/**
+ * The paths of the regenerated trio, relative to the project root. Astroid's
+ * code, tested here, not the site's: spread it into a site's
+ * `coverage.exclude` so an Astroid upgrade that adds lines to them doesn't
+ * move the site's coverage.
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { ASTROID_GENERATED_FILES } from "astroidjs";
+ *
+ * export default defineConfig({
+ *   test: { coverage: { exclude: [...ASTROID_GENERATED_FILES] } },
+ * });
+ * ```
+ *
+ * A site that lists them by hand would miss a generated file a later release
+ * adds; this list gains it.
+ */
+export declare const ASTROID_GENERATED_FILES: readonly ["src/schema.ts", "src/worker.ts", "src/middleware.ts"];
 /**
  * The regenerated trio—the files that are a pure function of the Astroid config
  * and carry a "do not hand-edit" banner. `astroid generate` writes exactly these,

package/dist/project/generate.js

@@ -18,12 +18,36 @@ import { ASTROID_VITALS_BINDING, astroidVitalsDataset } from "../analytics/index
 import { astroidCheckoutVars } from "../commerce/checkout-scaffold.js";
 import { astroidCommerceProviders } from "../commerce/roles.js";
 import { COMMERCE_PROVIDER_SECRETS, COMMERCE_PROVIDER_SETUP, commerceSecretNames, } from "../commerce/secrets.js";
-import { ASTROID_QUEUE_BINDING, astroidCrons, astroidQueueNames, astroidUsesQueues, } from "../queues/messages.js";
+import { ASTROID_QUEUE_BINDING, ASTROID_QUEUE_RETRY_DELAY, astroidCrons, astroidQueueNames, astroidUsesQueues, } from "../queues/messages.js";
 import { ASTROID_EDIT_SESSION_CLASS, ASTROID_REALTIME_BINDING, ASTROID_REALTIME_MIGRATION_TAG, usesRealtime, } from "../realtime/scaffold.js";
 import { ASTROID_SECRET_PLACEHOLDER } from "../secrets.js";
 import { tenancyZone } from "../tenancy/index.js";
 import { generateAstroidSchema } from "../schema/generate.js";
+import { ASTROID_AI_GATEWAY_VAR } from "../worker/gateway.js";
 import { generateAstroidMiddleware, generateAstroidWorker } from "../worker/generate.js";
+/**
+ * The paths of the regenerated trio, relative to the project root. Astroid's
+ * code, tested here, not the site's: spread it into a site's
+ * `coverage.exclude` so an Astroid upgrade that adds lines to them doesn't
+ * move the site's coverage.
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { ASTROID_GENERATED_FILES } from "astroidjs";
+ *
+ * export default defineConfig({
+ *   test: { coverage: { exclude: [...ASTROID_GENERATED_FILES] } },
+ * });
+ * ```
+ *
+ * A site that lists them by hand would miss a generated file a later release
+ * adds; this list gains it.
+ */
+export const ASTROID_GENERATED_FILES = [
+    "src/schema.ts",
+    "src/worker.ts",
+    "src/middleware.ts",
+];
 /**
  * The regenerated trio—the files that are a pure function of the Astroid config
  * and carry a "do not hand-edit" banner. `astroid generate` writes exactly these,
@@ -31,10 +55,11 @@ import { generateAstroidMiddleware, generateAstroidWorker } from "../worker/gene
  * once files (wrangler.jsonc, astro.config, auth.ts) are NOT here by design.
  */
 export function generateAstroidProject(config) {
+    const [schema, worker, middleware] = ASTROID_GENERATED_FILES;
     return [
-        { path: "src/schema.ts", contents: generateAstroidSchema(config) },
-        { path: "src/worker.ts", contents: generateAstroidWorker(config) },
-        { path: "src/middleware.ts", contents: generateAstroidMiddleware(config) },
+        { path: schema, contents: generateAstroidSchema(config) },
+        { path: worker, contents: generateAstroidWorker(config) },
+        { path: middleware, contents: generateAstroidMiddleware(config) },
     ];
 }
 /**
@@ -174,6 +199,10 @@ export function generateAstroidWrangler(config) {
         p(`        "max_batch_size": ${config.queues?.maxBatchSize ?? 10},`);
         p(`        "max_batch_timeout": ${config.queues?.maxBatchTimeout ?? 30},`);
         p(`        "max_retries": ${config.queues?.maxRetries ?? 5},`);
+        // A wait between deliveries, so a failed message doesn't hit a provider
+        // that's already failing or rate limiting again the same second. The queue
+        // owns retries (the consumer seam says so), so it owns the backoff too.
+        p(`        "retry_delay": ${config.queues?.retryDelay ?? ASTROID_QUEUE_RETRY_DELAY},`);
         p(`        "dead_letter_queue": ${JSON.stringify(dlq)},`);
         p("      },");
         p("    ],");
@@ -233,6 +262,11 @@ export function generateAstroidWrangler(config) {
     p(`    "SITE_URL": ${JSON.stringify(primaryHost ? `https://${primaryHost}` : `https://${key}.workers.dev`)},`);
     p("    // The editor allowlist / owner. Wire this into your auth seam (src/auth.ts).");
     p('    "OWNER_EMAIL": "",');
+    p("    // AI Gateway for the editor's AI assists: request logs, latency and error");
+    p("    // rates, and caching. Empty calls Workers AI directly. Create a gateway,");
+    p("    // put its id here, and first say on the privacy page that its log holds");
+    p("    // the text editors send to the assists.");
+    p(`    "${ASTROID_AI_GATEWAY_VAR}": "",`);
     p("    // Edge caching for published pages (ADR 0004). OFF by default, and the");
     p("    // default is the safe state: with it off every render is `no-store` and");
     p("    // the Worker cache layer stores nothing.");

package/dist/project/index.d.ts

@@ -5,3 +5,5 @@ export * from "./seed.js";
 export * from "./previews.js";
 export * from "./release.js";
 export * from "./provision.js";
+export * from "./ship.js";
+export * from "./build-output.js";

package/dist/project/index.js

@@ -9,3 +9,5 @@ export * from "./seed.js";
 export * from "./previews.js";
 export * from "./release.js";
 export * from "./provision.js";
+export * from "./ship.js";
+export * from "./build-output.js";

package/dist/project/scaffold.d.ts

@@ -19,6 +19,23 @@ export interface ScaffoldFile {
      */
     marker?: string;
 }
+/**
+ * `migrations/0004_page_redirects.sql`: the table that keeps a renamed page's
+ * old URL working (louise-toolkit's `pageRedirects`). The same DDL drizzle-kit
+ * writes for it, with `IF NOT EXISTS`, since a site that already added the
+ * table by hand must not fail on it.
+ */
+export declare const ASTROID_PAGE_REDIRECTS_MIGRATION: string;
+/**
+ * `migrations/0005_media_alt_undecided.sql`: the one-time data migration for
+ * the three alt text states. Before louise-toolkit 0.35, an empty alt meant
+ * both "not written" and "cleared", so an existing `''` is ambiguous. This
+ * makes each one "not written" (NULL), so nothing silently becomes decorative,
+ * and the owner marks what is. The statement is louise-toolkit's
+ * `MEDIA_ALT_UNDECIDED_SQL("media")`, written out rather than imported so the
+ * CLI doesn't load `louise-toolkit/editor` and its drizzle-orm peer.
+ */
+export declare const ASTROID_MEDIA_ALT_MIGRATION: string;
 /**
  * Every scaffold-once file this config implies.
  *

package/dist/project/scaffold.js

@@ -58,6 +58,69 @@ function generateAstroidPagesHooks() {
         "",
     ].join("\n");
 }
+/** `src/status-checks.ts`—the site's own status checks, scaffolded once. */
+function generateAstroidStatusChecks() {
+    return [
+        "// The site's own checks for the public status route (GET /api/louise/status),",
+        "// which an outside probe reads. The generated worker spreads `statusChecks`",
+        "// after Astroid's own `d1` and `content` checks. Scaffolded once and yours to",
+        "// edit.",
+        "//",
+        "// A check gets `env` and an abort signal, and returns true, false, or",
+        "// `{ ok, ageMs }`. Keep each one cheap: anyone can make it run. Its name is",
+        "// in the public response, so don't put anything in one you wouldn't publish.",
+        'import type { StatusCheck } from "louise-toolkit/editor";',
+        "",
+        "export const statusChecks: Record<string, StatusCheck<CloudflareEnv>> = {",
+        "  // For example, fail when the daily health scan is over 36 hours old:",
+        "  //",
+        '  //   import { ageCheck } from "louise-toolkit/editor";',
+        '  //   import { readHealthSummary } from "louise-toolkit/health";',
+        "  //",
+        "  //   healthScan: ageCheck(",
+        "  //     async (env) => (await readHealthSummary(env.RL))?.checkedAt,",
+        "  //     36 * 60 * 60 * 1000,",
+        "  //   ),",
+        "};",
+        "",
+    ].join("\n");
+}
+/**
+ * `migrations/0004_page_redirects.sql`: the table that keeps a renamed page's
+ * old URL working (louise-toolkit's `pageRedirects`). The same DDL drizzle-kit
+ * writes for it, with `IF NOT EXISTS`, since a site that already added the
+ * table by hand must not fail on it.
+ */
+export const ASTROID_PAGE_REDIRECTS_MIGRATION = [
+    "-- Page redirects: a renamed page's old URL answers a 301 to the new one.",
+    "-- pagesRoute and versionsRoute record `/old → /new` when a slug changes, and",
+    "-- the middleware's redirectFor serves them. Scaffolded by astroidjs.",
+    "CREATE TABLE IF NOT EXISTS `page_redirects` (",
+    "\t`from_path` text PRIMARY KEY NOT NULL,",
+    "\t`to_path` text NOT NULL,",
+    "\t`code` integer DEFAULT 301 NOT NULL,",
+    "\t`created_at` integer",
+    ");",
+    "",
+].join("\n");
+/**
+ * `migrations/0005_media_alt_undecided.sql`: the one-time data migration for
+ * the three alt text states. Before louise-toolkit 0.35, an empty alt meant
+ * both "not written" and "cleared", so an existing `''` is ambiguous. This
+ * makes each one "not written" (NULL), so nothing silently becomes decorative,
+ * and the owner marks what is. The statement is louise-toolkit's
+ * `MEDIA_ALT_UNDECIDED_SQL("media")`, written out rather than imported so the
+ * CLI doesn't load `louise-toolkit/editor` and its drizzle-orm peer.
+ */
+export const ASTROID_MEDIA_ALT_MIGRATION = [
+    "-- Alt text has three states: NULL is not written yet, '' is decorative (an",
+    "-- image the owner marked for screen readers to skip), and anything else is",
+    "-- the description. An existing '' predates the decorative state, so it's",
+    '-- ambiguous; this makes each one "not written". It runs once, before the',
+    "-- health scan starts counting only NULL as missing. Scaffolded by astroidjs.",
+    'UPDATE "media" SET "alt" = NULL WHERE "alt" = \'\';',
+    "",
+].join("\n");
 /** `src/settings-hooks.ts`—the site's settings sanitizers, scaffolded once. */
 function generateAstroidSettingsHooks() {
     return [
@@ -99,6 +162,12 @@ export function generateAstroidScaffoldFiles(config) {
     const catalogSql = generateCatalogMigrationSql(config);
     if (catalogSql)
         files.push({ path: "migrations/0003_catalog.sql", contents: catalogSql });
+    // --- 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 });
     // --- 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
@@ -126,6 +195,10 @@ export function generateAstroidScaffoldFiles(config) {
     if (config.pages?.hooks) {
         files.push({ path: "src/pages-hooks.ts", contents: generateAstroidPagesHooks() });
     }
+    // --- status: the site's own probe checks -----------------------------------
+    if (config.status?.checks) {
+        files.push({ path: "src/status-checks.ts", contents: generateAstroidStatusChecks() });
+    }
     // --- settings: the sanitize + read seam ------------------------------------
     // Only when asked for (settings.hooks): the generated worker and the Actions
     // surface both import it, so it must exist whenever either does. Scaffolded

package/dist/project/ship.d.ts

@@ -0,0 +1,42 @@
+import type { AstroidConfig } from "../config.js";
+/** Whether this app applies D1 migrations when it deploys. Default `true`. */
+export declare function astroidRunsMigrations(config: AstroidConfig): boolean;
+/** One step of a ship, in order. */
+export type ShipStep = 
+/** Run `wrangler` with these arguments; a non-zero exit stops the ship. */
+{
+    run: string[];
+}
+/** Print a line. */
+ | {
+    note: string;
+}
+/** Write a file, relative to the project root, before the next step. */
+ | {
+    write: {
+        path: string;
+        contents: string;
+    };
+};
+/** Where `ship preview` writes the config that names the staging database. */
+export declare const ASTROID_PREVIEW_MIGRATIONS_CONFIG = ".wrangler/astroid-preview-migrations.jsonc";
+/** Printed in place of the migrations step when `deploy.migrations` is `false`. */
+export declare const ASTROID_SKIP_MIGRATIONS_NOTE = "(deploy.migrations is false, so this app applies no migrations: another app owns this database's schema)";
+interface ShipContext {
+    /** The project's `wrangler.jsonc` text. */
+    wrangler: string;
+    /** The project root's absolute path. */
+    root: string;
+    /** Workers Builds' `WORKERS_CI_BRANCH`, which names the Preview. */
+    branch?: string;
+}
+/** The steps `astroid ship <target>` runs for a project. */
+export declare function astroidShipPlan(target: "production" | "preview", config: AstroidConfig, { wrangler, root, branch }: ShipContext): ShipStep[];
+/**
+ * `astroid doctor`'s check on who migrates this app's database. Returns an
+ * error when `deploy.migrations` is `false` but `wrangler.jsonc` still names a
+ * `migrations_dir` for `DB`, since that contradiction means someone expects
+ * this app to migrate. `null` when there's nothing to report.
+ */
+export declare function migrationsOwnershipError(config: AstroidConfig, wrangler: string): string | null;
+export {};