astroidjs 0.16.0 → 0.18.0

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

@@ -6,21 +6,72 @@ export interface ProvisionStep {
     args: string[];
     placeholder?: string;
 }
-/** A Secrets Store secret the config binds, which only a person can set. */
+/**
+ * The value provision gives a staging secret it creates: `random` is a fresh
+ * random value for each site, and `turnstile-test` is
+ * {@link TURNSTILE_TEST_SECRET}.
+ */
+export type StagingSecretValue = "random" | "turnstile-test";
+/**
+ * The staging secrets provision creates, by the binding name in the `previews`
+ * block. Nothing else is created: a secret with any other binding, and every
+ * production secret, is left for a person.
+ */
+export declare const ASTROID_STAGING_SECRET_VALUES: Readonly<Record<string, StagingSecretValue>>;
+/**
+ * Cloudflare's Turnstile test secret key, which passes every token. Staging
+ * uses it so a Preview's forms and sign-in work without a real widget.
+ */
+export declare const TURNSTILE_TEST_SECRET = "1x0000000000000000000000000000000AA";
+/** A Secrets Store secret the config binds. */
 export interface ProvisionSecret {
     binding: string;
     storeId: string;
     secretName: string;
     /** `production` for a top-level binding, `staging` for one in `previews`. */
     environment: "production" | "staging";
+    /**
+     * Set when provision creates the secret itself, and says what value it gets.
+     * Absent means only a person can set it.
+     */
+    create?: StagingSecretValue;
 }
 export interface ProvisionPlan {
     steps: ProvisionStep[];
     secrets: ProvisionSecret[];
     /** Whether `account_id` is set, so wrangler doesn't have to pick one. */
     hasAccount: boolean;
+    /**
+     * The `account_id` from `wrangler.jsonc`, when it's set. Wrangler prefers it
+     * to `CLOUDFLARE_ACCOUNT_ID`, so every command provision runs uses it.
+     */
+    accountId?: string;
 }
 /** Build the plan from a `wrangler.jsonc`, top level and `previews` alike. */
 export declare function provisionPlan(text: string): ProvisionPlan;
 /** Put a created resource's ID in place of its placeholder, everywhere. */
 export declare function applyProvisionedId(text: string, placeholder: string, id: string): string;
+/** What provision does with a staging secret it creates itself. */
+export interface StagingSecretStep {
+    secret: ProvisionSecret & {
+        create: StagingSecretValue;
+    };
+    /**
+     * `create` when the store doesn't have it, and `exists` when it does, so a
+     * re-run leaves it alone. `unknown` when the store couldn't be listed, so
+     * provision can't tell and creates nothing.
+     */
+    status: "create" | "exists" | "unknown";
+}
+/**
+ * Decide, for each staging secret provision creates, whether it still needs
+ * creating. `existing` maps a store ID to the secret names already in it; a
+ * store missing from the map couldn't be listed.
+ */
+export declare function stagingSecretSteps(secrets: readonly ProvisionSecret[], existing: ReadonlyMap<string, ReadonlySet<string>>): StagingSecretStep[];
+/**
+ * The secret names in the output of `wrangler secrets-store secret list`.
+ * Wrangler prints a table rather than JSON, with the name in the first column,
+ * so this reads the first cell of each row and drops the header.
+ */
+export declare function secretNamesFromList(output: string): string[];

package/dist/project/provision.js

@@ -10,11 +10,35 @@
 // Buckets carry a name instead of an ID, so every bucket the file names is
 // created, and one that already exists is fine.
 //
+// Two staging secrets need no person, so the plan marks them for provision to
+// create: the session secret, which can be any random value as long as it isn't
+// production's, and the Turnstile secret, which is Cloudflare's test secret that
+// always passes. Every other secret, and every production one, still needs a
+// person, so the CLI prints those instead.
+//
 // Pure: text in, plan out, so it's tested directly and the CLI only runs it.
 import { parseJsonc } from "./previews.js";
+/**
+ * The staging secrets provision creates, by the binding name in the `previews`
+ * block. Nothing else is created: a secret with any other binding, and every
+ * production secret, is left for a person.
+ */
+export const ASTROID_STAGING_SECRET_VALUES = {
+    SESSION_SECRET: "random",
+    // deepcode ignore HardcodedNonCryptoSecret: A value kind, not a credential.
+    TURNSTILE_SECRET: "turnstile-test",
+};
+/**
+ * Cloudflare's Turnstile test secret key, which passes every token. Staging
+ * uses it so a Preview's forms and sign-in work without a real widget.
+ */
+// deepcode ignore HardcodedNonCryptoSecret: Cloudflare's public Turnstile test secret, not a credential.
+export const TURNSTILE_TEST_SECRET = "1x0000000000000000000000000000000AA";
 const PLACEHOLDER = /<run:\s*wrangler\s+(d1\s+create|kv\s+namespace\s+create)\s+([^\s>]+)\s*>/g;
 const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 const list = (v) => (Array.isArray(v) ? v.filter(isObject) : []);
+/** Whether a config value is filled in, rather than empty or a `<...>` placeholder. */
+const isReal = (v) => v.length > 0 && !v.startsWith("<");
 /** Build the plan from a `wrangler.jsonc`, top level and `previews` alike. */
 export function provisionPlan(text) {
     const steps = [];
@@ -44,22 +68,68 @@ export function provisionPlan(text) {
         ["staging", previews],
     ]) {
         for (const s of list(section.secrets_store_secrets)) {
-            secrets.push({
+            const secret = {
                 binding: String(s.binding ?? ""),
                 storeId: String(s.store_id ?? ""),
                 secretName: String(s.secret_name ?? ""),
                 environment,
-            });
+            };
+            const create = Object.hasOwn(ASTROID_STAGING_SECRET_VALUES, secret.binding)
+                ? ASTROID_STAGING_SECRET_VALUES[secret.binding]
+                : undefined;
+            // Only staging, and only against a real store and name: a placeholder
+            // can't be created against, so it's left for a person.
+            if (environment === "staging" &&
+                create &&
+                isReal(secret.storeId) &&
+                isReal(secret.secretName)) {
+                secret.create = create;
+            }
+            secrets.push(secret);
         }
     }
     const account = top.account_id;
-    return {
-        steps,
-        secrets,
-        hasAccount: typeof account === "string" && account.length > 0 && !account.startsWith("<"),
-    };
+    const hasAccount = typeof account === "string" && isReal(account);
+    return { steps, secrets, hasAccount, ...(hasAccount ? { accountId: account } : {}) };
 }
 /** Put a created resource's ID in place of its placeholder, everywhere. */
 export function applyProvisionedId(text, placeholder, id) {
     return text.split(placeholder).join(id);
 }
+/**
+ * Decide, for each staging secret provision creates, whether it still needs
+ * creating. `existing` maps a store ID to the secret names already in it; a
+ * store missing from the map couldn't be listed.
+ */
+export function stagingSecretSteps(secrets, existing) {
+    const steps = [];
+    for (const secret of secrets) {
+        if (!secret.create)
+            continue;
+        const names = existing.get(secret.storeId);
+        steps.push({
+            secret: { ...secret, create: secret.create },
+            status: !names ? "unknown" : names.has(secret.secretName) ? "exists" : "create",
+        });
+    }
+    return steps;
+}
+// Wrangler colors the table on a terminal: an escape, then `[`, digits, and `m`.
+const ANSI_COLOR = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+/**
+ * The secret names in the output of `wrangler secrets-store secret list`.
+ * Wrangler prints a table rather than JSON, with the name in the first column,
+ * so this reads the first cell of each row and drops the header.
+ */
+export function secretNamesFromList(output) {
+    const names = [];
+    for (const line of output.replace(ANSI_COLOR, "").split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("│"))
+            continue;
+        const name = trimmed.split("│")[1]?.trim();
+        if (name && name !== "Name")
+            names.push(name);
+    }
+    return names;
+}

package/dist/project/release.d.ts

@@ -2,5 +2,11 @@
 export declare const ASTROID_DEPLOY_BRANCH = "deploy/production";
 /** Where the workflow lives, relative to the repository root. */
 export declare const ASTROID_RELEASE_WORKFLOW_PATH = ".github/workflows/release.yml";
+/** The Actions variable that holds the release app's App ID. */
+export declare const ASTROID_RELEASE_APP_ID_VAR = "RELEASE_APP_ID";
+/** The Actions secret that holds the release app's private key. */
+export declare const ASTROID_RELEASE_APP_KEY_SECRET = "RELEASE_APP_PRIVATE_KEY";
+/** Where the one-time release setup is written down. */
+export declare const ASTROID_RELEASE_SETUP_URL = "https://docs.astroidjs.org/guide/releases/";
 /** The release workflow's contents. Pure, and the same for every site. */
 export declare function generateAstroidReleaseWorkflow(): string;

package/dist/project/release.js

@@ -10,6 +10,12 @@
 // Nobody commits to the branch; it's a tag carried as a branch, and GitHub never
 // holds a Cloudflare credential.
 //
+// The push uses a GitHub App's token, not the workflow's own `GITHUB_TOKEN`. A
+// repository ruleset keeps everyone else off `deploy/production`, and GitHub
+// rejects the GitHub Actions app as a ruleset bypass actor, so a ruleset that
+// guards the branch blocks `GITHUB_TOKEN` too. A GitHub App can be the bypass
+// actor. The setup is in the docs site's Releases guide.
+//
 // A regenerated file, like the worker trio: `astroid generate` rewrites it and
 // `astroid doctor` fails when it drifts, so a hand edit can't quietly change
 // which commits reach production.
@@ -17,8 +23,16 @@
 export const ASTROID_DEPLOY_BRANCH = "deploy/production";
 /** Where the workflow lives, relative to the repository root. */
 export const ASTROID_RELEASE_WORKFLOW_PATH = ".github/workflows/release.yml";
+/** The Actions variable that holds the release app's App ID. */
+export const ASTROID_RELEASE_APP_ID_VAR = "RELEASE_APP_ID";
+/** The Actions secret that holds the release app's private key. */
+export const ASTROID_RELEASE_APP_KEY_SECRET = "RELEASE_APP_PRIVATE_KEY";
+/** Where the one-time release setup is written down. */
+export const ASTROID_RELEASE_SETUP_URL = "https://docs.astroidjs.org/guide/releases/";
 /** The release workflow's contents. Pure, and the same for every site. */
 export function generateAstroidReleaseWorkflow() {
+    const appId = ASTROID_RELEASE_APP_ID_VAR;
+    const appKey = ASTROID_RELEASE_APP_KEY_SECRET;
     return `# Generated by astroid. Don't edit: \`astroid generate\` rewrites this file and
 # \`astroid doctor\` fails when it drifts.
 #
@@ -26,8 +40,14 @@ export function generateAstroidReleaseWorkflow() {
 # release/<version> branch when a released version needs a patch. This moves
 # ${ASTROID_DEPLOY_BRANCH} to the tagged commit, and Workers Builds deploys it to
 # production. Nobody commits to ${ASTROID_DEPLOY_BRANCH}; a repository ruleset lets
-# only this workflow update it. To roll back, tag the earlier commit with the
-# next patch version.
+# only the release GitHub App update it. To roll back, tag the earlier commit
+# with the next patch version.
+#
+# The push uses the release app's token, from the ${appId} variable and
+# the ${appKey} secret. The workflow's own GITHUB_TOKEN can't push:
+# GitHub rejects the GitHub Actions app as a ruleset bypass actor, so the
+# ruleset blocks it too. One-time setup, the app and the ruleset:
+# ${ASTROID_RELEASE_SETUP_URL}
 name: Release
 
 on:
@@ -46,9 +66,28 @@ jobs:
   release:
     runs-on: ubuntu-latest
     steps:
+      - name: Check the release app
+        env:
+          APP_ID: \${{ vars.${appId} }}
+          APP_KEY: \${{ secrets.${appKey} }}
+        run: |
+          if [ -z "$APP_ID" ] || [ -z "$APP_KEY" ]; then
+            echo "::error::Releasing needs the ${appId} variable and the ${appKey} secret, from the GitHub App that the ${ASTROID_DEPLOY_BRANCH} ruleset lets through. Set them up as ${ASTROID_RELEASE_SETUP_URL} describes."
+            exit 1
+          fi
+
+      - name: Mint the release app's token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: \${{ vars.${appId} }}
+          private-key: \${{ secrets.${appKey} }}
+
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          # The push below uses the credentials checkout leaves in place.
+          token: \${{ steps.app-token.outputs.token }}
 
       - name: Check the tag
         run: |

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 {};