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

@@ -1,7 +1,10 @@
 export * from "./generate.js";
 export * from "./actions.js";
 export * from "./scaffold.js";
+export * from "./migrations.js";
 export * from "./seed.js";
 export * from "./previews.js";
 export * from "./release.js";
 export * from "./provision.js";
+export * from "./ship.js";
+export * from "./build-output.js";

package/dist/project/index.js

@@ -5,7 +5,10 @@
 export * from "./generate.js";
 export * from "./actions.js";
 export * from "./scaffold.js";
+export * from "./migrations.js";
 export * from "./seed.js";
 export * from "./previews.js";
 export * from "./release.js";
 export * from "./provision.js";
+export * from "./ship.js";
+export * from "./build-output.js";

package/dist/project/migrations.d.ts

@@ -0,0 +1,26 @@
+import type { ScaffoldFile } from "./scaffold.js";
+/**
+ * The `DB` binding's `migrations_dir` from `wrangler.jsonc`, or Wrangler's
+ * default `migrations` when the binding sets none or the file is missing.
+ * Returned as written, without a trailing slash.
+ */
+export declare function astroidMigrationsDir(wrangler: string | null | undefined): string;
+/**
+ * Resolve each scaffold file's path against the site's migrations directory.
+ * Files that aren't migrations pass through unchanged. For a migration:
+ *
+ * - **Already there under any number:** the path is that file's, so a caller
+ *   that skips existing files skips it. A site that copied `page_redirects`
+ *   in by hand as `0009_page_redirects.sql` keeps that file and gets no second.
+ * - **Default number free and past the newest migration:** the default, so a
+ *   standard project numbers exactly as before.
+ * - **Otherwise:** the next number after the newest migration, at the same
+ *   width. A migration never takes a number the site already uses, and never
+ *   sorts before one that already ran.
+ *
+ * `existing` is the file names in `migrationsDir`, in any order.
+ */
+export declare function resolveAstroidScaffoldPaths(files: ScaffoldFile[], { migrationsDir, existing }: {
+    migrationsDir: string;
+    existing: string[];
+}): ScaffoldFile[];

package/dist/project/migrations.js

@@ -0,0 +1,78 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Where a scaffolded D1 migration lands in a site. The scaffold names each
+// migration with a default path (`migrations/0004_page_redirects.sql`), but a
+// site can point its `DB` binding at another directory with `migrations_dir`,
+// and it may already number its own migrations past the default. Wrangler
+// applies only the directory in `migrations_dir` and tracks each file by name,
+// so a migration written anywhere else never runs, and one written onto a
+// number the site already uses leaves two files claiming that number.
+import { parseJsonc } from "./previews.js";
+/** Wrangler's own default when a D1 binding sets no `migrations_dir`. */
+const DEFAULT_MIGRATIONS_DIR = "migrations";
+/** `0004_page_redirects.sql` → number `"0004"`, name `page_redirects`. */
+const MIGRATION_FILE = /^(\d+)_(.+)\.sql$/;
+/**
+ * The `DB` binding's `migrations_dir` from `wrangler.jsonc`, or Wrangler's
+ * default `migrations` when the binding sets none or the file is missing.
+ * Returned as written, without a trailing slash.
+ */
+export function astroidMigrationsDir(wrangler) {
+    if (!wrangler)
+        return DEFAULT_MIGRATIONS_DIR;
+    let parsed;
+    try {
+        parsed = parseJsonc(wrangler);
+    }
+    catch {
+        return DEFAULT_MIGRATIONS_DIR;
+    }
+    const dir = (parsed.d1_databases ?? []).find((d) => d.binding === "DB")?.migrations_dir;
+    return dir ? dir.replace(/\/+$/, "") : DEFAULT_MIGRATIONS_DIR;
+}
+/**
+ * Resolve each scaffold file's path against the site's migrations directory.
+ * Files that aren't migrations pass through unchanged. For a migration:
+ *
+ * - **Already there under any number:** the path is that file's, so a caller
+ *   that skips existing files skips it. A site that copied `page_redirects`
+ *   in by hand as `0009_page_redirects.sql` keeps that file and gets no second.
+ * - **Default number free and past the newest migration:** the default, so a
+ *   standard project numbers exactly as before.
+ * - **Otherwise:** the next number after the newest migration, at the same
+ *   width. A migration never takes a number the site already uses, and never
+ *   sorts before one that already ran.
+ *
+ * `existing` is the file names in `migrationsDir`, in any order.
+ */
+export function resolveAstroidScaffoldPaths(files, { migrationsDir, existing }) {
+    const taken = new Map();
+    const byName = new Map();
+    for (const file of existing) {
+        const match = MIGRATION_FILE.exec(file);
+        if (!match)
+            continue;
+        taken.set(Number(match[1]), file);
+        byName.set(match[2], file);
+    }
+    let newest = taken.size ? Math.max(...taken.keys()) : -1;
+    return files.map((file) => {
+        if (!file.migration)
+            return file;
+        const base = file.path.slice(file.path.lastIndexOf("/") + 1);
+        const match = MIGRATION_FILE.exec(base);
+        if (!match)
+            return { ...file, path: `${migrationsDir}/${base}` };
+        const [, digits, name] = match;
+        const present = byName.get(name);
+        if (present)
+            return { ...file, path: `${migrationsDir}/${present}` };
+        const wanted = Number(digits);
+        const number = !taken.has(wanted) && wanted > newest ? wanted : newest + 1;
+        const filename = `${String(number).padStart(digits.length, "0")}_${name}.sql`;
+        taken.set(number, filename);
+        byName.set(name, filename);
+        newest = Math.max(newest, number);
+        return { ...file, path: `${migrationsDir}/${filename}` };
+    });
+}

package/dist/project/scaffold.d.ts

@@ -18,7 +18,30 @@ export interface ScaffoldFile {
      * Without it a re-run would append a duplicate every time.
      */
     marker?: string;
+    /**
+     * A D1 migration. `path` is its default, `migrations/NNNN_name.sql`; the CLI
+     * places it in the `DB` binding's `migrations_dir` and renumbers it past the
+     * site's own migrations with {@link resolveAstroidScaffoldPaths}.
+     */
+    migration?: true;
 }
+/**
+ * `migrations/0004_page_redirects.sql`: the table that keeps a renamed page's
+ * 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 [
@@ -97,8 +160,25 @@ export function generateAstroidScaffoldFiles(config) {
     // scaffolded a `products` table into src/schema.ts that no migration ever
     // created, and the first sync wrote nothing while reporting success.
     const catalogSql = generateCatalogMigrationSql(config);
-    if (catalogSql)
-        files.push({ path: "migrations/0003_catalog.sql", contents: catalogSql });
+    if (catalogSql) {
+        files.push({ path: "migrations/0003_catalog.sql", contents: catalogSql, migration: true });
+    }
+    // --- louise-toolkit 0.35's two schema changes -----------------------------
+    // Numbered after the catalog's 0003, and written into an existing site by
+    // `astroid generate` because a missing scaffold file is always written. The
+    // alt update is a no-op on a fresh database. Wrangler tracks migrations by
+    // filename. The CLI moves each into the site's `migrations_dir` and past
+    // the site's own numbers (see migrations.ts), so a site that already has its
+    // own 0004 gets the next free number instead of a second 0004.
+    files.push({
+        path: "migrations/0004_page_redirects.sql",
+        contents: ASTROID_PAGE_REDIRECTS_MIGRATION,
+        migration: true,
+    }, {
+        path: "migrations/0005_media_alt_undecided.sql",
+        contents: ASTROID_MEDIA_ALT_MIGRATION,
+        migration: true,
+    });
     // --- the CWV beacon -------------------------------------------------------
     // A static file under public/, so it is same-origin and covered by
     // `script-src 'self'`—an inline script carrying generated content could not
@@ -126,6 +206,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 {};

package/dist/project/ship.js

@@ -0,0 +1,115 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// What `astroid ship` runs, as a plan: Workers Builds calls
+// `astroid ship production` on the `deploy/production` build and
+// `astroid ship preview` on every other branch.
+//
+// By default both targets apply D1 migrations first. An app whose database
+// another app migrates sets `deploy.migrations: false`, and then neither target
+// touches the migrations ledger. Two apps on one database that both migrated
+// would race: one release tag deploys both Workers in no guaranteed order,
+// nothing serializes two `wrangler d1 migrations apply` runs, and a
+// non-idempotent statement such as `ALTER TABLE … ADD COLUMN` then fails the
+// second deploy.
+//
+// Pure: config and wrangler.jsonc text in, steps out, so it's tested directly
+// and the CLI only runs them.
+import { parseJsonc } from "./previews.js";
+/** Whether this app applies D1 migrations when it deploys. Default `true`. */
+export function astroidRunsMigrations(config) {
+    return config.deploy?.migrations !== false;
+}
+/** Where `ship preview` writes the config that names the staging database. */
+export const ASTROID_PREVIEW_MIGRATIONS_CONFIG = ".wrangler/astroid-preview-migrations.jsonc";
+/** Printed in place of the migrations step when `deploy.migrations` is `false`. */
+export const ASTROID_SKIP_MIGRATIONS_NOTE = "(deploy.migrations is false, so this app applies no migrations: another app owns this database's schema)";
+/** The steps `astroid ship <target>` runs for a project. */
+export function astroidShipPlan(target, config, { wrangler, root, branch }) {
+    const migrate = astroidRunsMigrations(config);
+    if (target === "production") {
+        return [
+            migrate
+                ? { run: ["d1", "migrations", "apply", "DB", "--remote"] }
+                : { note: ASTROID_SKIP_MIGRATIONS_NOTE },
+            { run: ["deploy"] },
+        ];
+    }
+    const steps = [];
+    if (!migrate) {
+        steps.push({ note: ASTROID_SKIP_MIGRATIONS_NOTE });
+    }
+    else {
+        // 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 parsed = parseJsonc(wrangler);
+        const prodDb = (parsed.d1_databases ?? []).find((d) => d.binding === "DB");
+        const stagingDb = (parsed.previews?.d1_databases ?? []).find((d) => d.binding === "DB");
+        if (stagingDb && prodDb) {
+            steps.push({
+                write: {
+                    path: ASTROID_PREVIEW_MIGRATIONS_CONFIG,
+                    contents: JSON.stringify({
+                        d1_databases: [
+                            {
+                                binding: "PREVIEW_DB",
+                                database_name: stagingDb.database_name,
+                                database_id: stagingDb.database_id,
+                                // Absolute, so it doesn't depend on how Wrangler resolves a
+                                // relative path in a config that lives in `.wrangler/`.
+                                migrations_dir: fromRoot(root, prodDb.migrations_dir ?? "migrations"),
+                            },
+                        ],
+                    }, null, 2),
+                },
+            }, {
+                run: [
+                    "d1",
+                    "migrations",
+                    "apply",
+                    "PREVIEW_DB",
+                    "--remote",
+                    "--config",
+                    ASTROID_PREVIEW_MIGRATIONS_CONFIG,
+                ],
+            });
+        }
+        else {
+            steps.push({ note: "(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 name = branch
+        ? branch
+            .toLowerCase()
+            .replace(/[^a-z0-9-]+/g, "-")
+            .replace(/^-+|-+$/g, "")
+            .slice(0, 63)
+        : undefined;
+    steps.push({ run: ["preview", ...(name ? ["--name", name] : [])] });
+    return steps;
+}
+/** A project-relative path made absolute. An absolute one is kept. */
+function fromRoot(root, path) {
+    if (path.startsWith("/"))
+        return path;
+    const relative = path.replace(/^\.\//, "").replace(/\/+$/, "");
+    return `${root.replace(/\/+$/, "")}/${relative}`;
+}
+/**
+ * `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 function migrationsOwnershipError(config, wrangler) {
+    if (astroidRunsMigrations(config))
+        return null;
+    if (!/"migrations_dir"\s*:/.test(wrangler))
+        return null;
+    return ("astroid.config sets deploy.migrations to false, but wrangler.jsonc still declares a " +
+        "`migrations_dir`. Remove `migrations_dir` if another app owns this database's schema, " +
+        "or drop `migrations: false` if this app does.");
+}

package/dist/queues/index.d.ts

@@ -1,4 +1,4 @@
 export { astroidQueueHandler, type QueueHandlerOptions } from "./consumer.js";
-export { affectsCatalog, ASTROID_DEFAULT_CRON, ASTROID_HEALTH_CRON, ASTROID_QUEUE_BINDING, type AstroidQueueMessage, astroidCron, astroidCrons, astroidQueueNames, astroidUsesQueues, type CatalogRefreshMessage, type WebhookMessage, } from "./messages.js";
+export { affectsCatalog, ASTROID_DEFAULT_CRON, ASTROID_HEALTH_CRON, ASTROID_QUEUE_BINDING, ASTROID_QUEUE_RETRY_DELAY, type AstroidQueueMessage, astroidCron, astroidCrons, astroidQueueNames, astroidUsesQueues, type CatalogRefreshMessage, type WebhookMessage, } from "./messages.js";
 export { generateAstroidEnvBindings, generateAstroidQueueSeam, generateAstroidWebhookRoute, generateAstroidWebhookRoutes, } from "./scaffold.js";
-export { handleWebhook, type QueueProducer, type WebhookRouteOptions, type WebhookVerifyInput, } from "./webhook.js";
+export { astroidQueue, handleWebhook, type QueueProducer, type WebhookRouteOptions, type WebhookVerifyInput, } from "./webhook.js";

package/dist/queues/index.js

@@ -1,5 +1,5 @@
 // Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
 export { astroidQueueHandler } from "./consumer.js";
-export { affectsCatalog, ASTROID_DEFAULT_CRON, ASTROID_HEALTH_CRON, ASTROID_QUEUE_BINDING, astroidCron, astroidCrons, astroidQueueNames, astroidUsesQueues, } from "./messages.js";
+export { affectsCatalog, ASTROID_DEFAULT_CRON, ASTROID_HEALTH_CRON, ASTROID_QUEUE_BINDING, ASTROID_QUEUE_RETRY_DELAY, astroidCron, astroidCrons, astroidQueueNames, astroidUsesQueues, } from "./messages.js";
 export { generateAstroidEnvBindings, generateAstroidQueueSeam, generateAstroidWebhookRoute, generateAstroidWebhookRoutes, } from "./scaffold.js";
-export { handleWebhook, } from "./webhook.js";
+export { astroidQueue, handleWebhook, } from "./webhook.js";

package/dist/queues/messages.d.ts

@@ -31,6 +31,12 @@ export declare const ASTROID_HEALTH_CRON = "17 4 * * *";
 export declare function astroidCrons(config: AstroidConfig): string[];
 /** Binding name for the project's queue producer. */
 export declare const ASTROID_QUEUE_BINDING = "COMMERCE_QUEUE";
+/**
+ * Seconds Cloudflare waits before redelivering a failed message, when the
+ * config sets no `queues.retryDelay`. A consumer that sets its own delay per
+ * message, as `processBatch` can, overrides it.
+ */
+export declare const ASTROID_QUEUE_RETRY_DELAY = 30;
 /** Queue names derived from the project key—the main queue and its DLQ. */
 export declare function astroidQueueNames(config: AstroidConfig): {
     queue: string;

package/dist/queues/messages.js

@@ -52,6 +52,12 @@ export function astroidCrons(config) {
 }
 /** Binding name for the project's queue producer. */
 export const ASTROID_QUEUE_BINDING = "COMMERCE_QUEUE";
+/**
+ * Seconds Cloudflare waits before redelivering a failed message, when the
+ * config sets no `queues.retryDelay`. A consumer that sets its own delay per
+ * message, as `processBatch` can, overrides it.
+ */
+export const ASTROID_QUEUE_RETRY_DELAY = 30;
 /** Queue names derived from the project key—the main queue and its DLQ. */
 export function astroidQueueNames(config) {
     return { queue: `${config.key}-commerce`, dlq: `${config.key}-commerce-dlq` };