astroidjs 0.15.0 → 0.17.0

package/dist/project/previews.js

@@ -0,0 +1,215 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The `previews` block check `astroid doctor` runs (louise-toolkit ADR 0017).
+//
+// A site's staging is Cloudflare's Worker Previews: `main` and every pull
+// request run as Previews of the one Worker, with the settings in the
+// `previews` block of `wrangler.jsonc`. Previews inherit NOTHING from the top
+// level, which is the point and also the trap:
+//
+//   - A binding the code reads that the block leaves out is `undefined` on a
+//     Preview, and the Worker throws (Cloudflare's error 1101).
+//   - A binding the block copies verbatim points a Preview at production's
+//     database or bucket, so a branch writes production data. That's the
+//     failure staging exists to prevent, and nothing else would catch it.
+//   - Crons, routes, and queue consumers don't target Previews, so putting
+//     them in the block does nothing and reads as if it did.
+//
+// Pure: text in, findings out, so it's tested directly and the CLI only prints.
+/**
+ * Parse JSONC: strip `//` and block comments outside strings, then trailing
+ * commas. `wrangler.jsonc` is written by hand and commented heavily, which is
+ * why `doctor` reads the rest of it by regex; this check needs the structure.
+ */
+export function parseJsonc(text) {
+    let out = "";
+    let inString = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        const next = text[i + 1];
+        if (inString) {
+            out += c;
+            if (c === "\\")
+                out += text[++i] ?? "";
+            else if (c === '"')
+                inString = false;
+        }
+        else if (c === '"') {
+            inString = true;
+            out += c;
+        }
+        else if (c === "/" && next === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i++;
+            out += "\n";
+        }
+        else if (c === "/" && next === "*") {
+            i += 2;
+            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+                i++;
+            i++;
+        }
+        else {
+            out += c;
+        }
+    }
+    return JSON.parse(out.replace(/,(\s*[}\]])/g, "$1"));
+}
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const list = (v) => (Array.isArray(v) ? v.filter(isObject) : []);
+const STORAGE = [
+    {
+        what: "D1 database",
+        get: (c) => list(c.d1_databases),
+        name: (b) => b.binding,
+        resource: (b) => String(b.database_id ?? b.database_name ?? ""),
+    },
+    {
+        what: "KV namespace",
+        get: (c) => list(c.kv_namespaces),
+        name: (b) => b.binding,
+        resource: (b) => String(b.id ?? ""),
+    },
+    {
+        what: "R2 bucket",
+        get: (c) => list(c.r2_buckets),
+        name: (b) => b.binding,
+        resource: (b) => String(b.bucket_name ?? ""),
+    },
+    {
+        what: "Secrets Store secret",
+        get: (c) => list(c.secrets_store_secrets),
+        name: (b) => b.binding,
+        resource: (b) => `${String(b.store_id ?? "")}/${String(b.secret_name ?? "")}`,
+    },
+    {
+        what: "Analytics Engine dataset",
+        get: (c) => list(c.analytics_engine_datasets),
+        name: (b) => b.binding,
+        resource: (b) => String(b.dataset ?? ""),
+    },
+    {
+        what: "Vectorize index",
+        get: (c) => list(c.vectorize),
+        name: (b) => b.binding,
+        resource: (b) => String(b.index_name ?? ""),
+    },
+    {
+        what: "queue producer",
+        get: (c) => list(isObject(c.queues) ? c.queues.producers : undefined),
+        name: (b) => b.binding,
+        resource: (b) => String(b.queue ?? ""),
+        optional: "queue consumers can't target a Preview, so a Preview leaves the queue unbound and the side effects run inline",
+    },
+    {
+        what: "Workflow",
+        get: (c) => list(c.workflows),
+        name: (b) => b.binding,
+        resource: (b) => String(b.name ?? ""),
+        optional: "a Preview calls the production Workflow's code and bindings, so it leaves the binding out and falls back",
+    },
+];
+/** Bindings with no staging resource behind them: a Preview needs the key, and
+ *  nothing to provision. A Durable Object namespace is one: Cloudflare gives
+ *  each Preview its own instances of the class. */
+const API_BINDINGS = [
+    "ai",
+    "images",
+    "browser",
+    "send_email",
+    "version_metadata",
+    "durable_objects",
+];
+/**
+ * Check the `previews` block of a `wrangler.jsonc` against its production
+ * settings. Returns what passed and what didn't; an error means a Preview
+ * would crash or touch production.
+ */
+export function checkWranglerPreviews(text) {
+    const findings = { ok: [], errors: [], warnings: [] };
+    let config;
+    try {
+        const parsed = parseJsonc(text);
+        if (!isObject(parsed))
+            throw new Error("not an object");
+        config = parsed;
+    }
+    catch (err) {
+        findings.errors.push(`wrangler.jsonc doesn't parse (${err.message}).`);
+        return findings;
+    }
+    const previews = config.previews;
+    if (!isObject(previews)) {
+        findings.warnings.push("wrangler.jsonc has no `previews` block, so this site has no staging. Branch builds " +
+            "either fail or run with production's data (louise-toolkit ADR 0017).");
+        return findings;
+    }
+    for (const key of ["triggers", "routes"]) {
+        if (key in previews) {
+            findings.errors.push(`\`previews.${key}\` does nothing: ${key === "triggers" ? "Cron Triggers" : "routes"} ` +
+                "target production only. Remove it; Preview hosts come from a route with " +
+                "`previews_enabled` at the top level.");
+        }
+    }
+    if (isObject(previews.queues) && "consumers" in previews.queues) {
+        findings.errors.push("`previews.queues.consumers` does nothing: queue consumers can't target a Preview. Remove it.");
+    }
+    for (const kind of STORAGE) {
+        const staging = new Map(kind.get(previews).map((b) => [kind.name(b), b]));
+        for (const prod of kind.get(config)) {
+            const name = String(kind.name(prod));
+            const preview = staging.get(kind.name(prod));
+            if (!preview) {
+                if (kind.optional)
+                    findings.ok.push(`previews: ${kind.what} \`${name}\` left out (${kind.optional})`);
+                else
+                    findings.errors.push(`\`previews\` has no ${kind.what} \`${name}\`. A Preview inherits nothing, so code ` +
+                        `that reads \`env.${name}\` throws there. Bind it to a staging ${kind.what}.`);
+            }
+            else if (kind.resource(preview) === kind.resource(prod)) {
+                findings.errors.push(`\`previews\` binds ${kind.what} \`${name}\` to production's (${kind.resource(prod)}), ` +
+                    "so every branch would read and write production data. Bind it to a staging one.");
+            }
+            else {
+                findings.ok.push(`previews: ${kind.what} \`${name}\` bound to a staging resource`);
+            }
+        }
+    }
+    for (const key of API_BINDINGS) {
+        if (!(key in config))
+            continue;
+        if (key in previews)
+            findings.ok.push(`previews: \`${key}\` binding present`);
+        else
+            findings.errors.push(`\`previews\` has no \`${key}\` binding. A Preview inherits nothing, so code that uses ` +
+                "it throws there. Copy the binding into `previews`; it needs no staging resource.");
+    }
+    const prodVars = isObject(config.vars) ? config.vars : {};
+    const stagingVars = isObject(previews.vars) ? previews.vars : {};
+    const missingVars = Object.keys(prodVars).filter((key) => !(key in stagingVars));
+    if (missingVars.length) {
+        findings.errors.push(`\`previews.vars\` is missing ${missingVars.map((v) => `\`${v}\``).join(", ")}. Vars aren't ` +
+            "inherited, so each is undefined on a Preview. Give each a staging value.");
+    }
+    else if (Object.keys(prodVars).length) {
+        findings.ok.push(`previews: all ${Object.keys(prodVars).length} vars have a staging value`);
+    }
+    for (const key of ["SITE_URL", "MEDIA_URL"]) {
+        const value = prodVars[key];
+        // A path such as `/media` resolves against whichever host serves it, so a
+        // Preview sharing production's path still serves its own bucket.
+        const isOrigin = typeof value === "string" && /^https?:\/\//.test(value);
+        if (key in prodVars && isOrigin && stagingVars[key] === value) {
+            findings.errors.push(`\`previews.vars.${key}\` is production's (${String(prodVars[key])}), so a Preview ` +
+                "links to or serves from production. Point it at staging.");
+        }
+    }
+    const previewHost = list(config.routes).find((r) => r.previews_enabled === true);
+    if (previewHost)
+        findings.ok.push(`previews: served on \`<name>.${String(previewHost.pattern)}\``);
+    else
+        findings.warnings.push("No route has `previews_enabled`, so Previews are reachable only on workers.dev. Add a " +
+            'preview-only custom domain: `{ "pattern": "staging.example.com", "custom_domain": true, ' +
+            '"previews_enabled": true, "enabled": false }`.');
+    return findings;
+}

package/dist/project/provision.d.ts

@@ -0,0 +1,77 @@
+/** One resource to create. `placeholder` is the text its ID replaces. */
+export interface ProvisionStep {
+    kind: "d1" | "kv" | "r2";
+    name: string;
+    /** The `wrangler` arguments that create it. */
+    args: string[];
+    placeholder?: string;
+}
+/**
+ * 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

@@ -0,0 +1,135 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The plan `astroid provision` runs: which Cloudflare resources a site's
+// `wrangler.jsonc` still names by placeholder, and which secrets it binds.
+//
+// A placeholder names the command that creates its resource, such as
+// `<run: wrangler d1 create acme-staging>`, so the plan reads it rather than
+// guessing a name. The same placeholder can stand for two bindings that share
+// one namespace, and replacing the text everywhere it appears fills both.
+// 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 = [];
+    const seen = new Set();
+    for (const match of text.matchAll(PLACEHOLDER)) {
+        const placeholder = match[0];
+        if (seen.has(placeholder))
+            continue;
+        seen.add(placeholder);
+        const name = match[2];
+        steps.push(match[1].startsWith("d1")
+            ? { kind: "d1", name, args: ["d1", "create", name], placeholder }
+            : { kind: "kv", name, args: ["kv", "namespace", "create", name], placeholder });
+    }
+    const config = parseJsonc(text);
+    const top = isObject(config) ? config : {};
+    const previews = isObject(top.previews) ? top.previews : {};
+    const buckets = new Set([...list(top.r2_buckets), ...list(previews.r2_buckets)]
+        .map((b) => b.bucket_name)
+        .filter((name) => typeof name === "string" && !name.startsWith("<")));
+    for (const name of buckets) {
+        steps.push({ kind: "r2", name, args: ["r2", "bucket", "create", name] });
+    }
+    const secrets = [];
+    for (const [environment, section] of [
+        ["production", top],
+        ["staging", previews],
+    ]) {
+        for (const s of list(section.secrets_store_secrets)) {
+            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;
+    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

@@ -0,0 +1,12 @@
+/** The branch Workers Builds deploys to production from. */
+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

@@ -0,0 +1,118 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The release workflow every site runs (louise-toolkit ADR 0017, amended).
+//
+// Releases are trunk-based: a `v<version>` tag on a commit of `main` is the
+// release, and a `release/<version>` branch exists only when a released version
+// needs a patch and `main` has moved on. Workers Builds deploys on branch
+// pushes and can't watch tags, so the tag's workflow moves one branch,
+// `deploy/production`, to the tagged commit, and Workers Builds deploys that.
+// 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.
+/** The branch Workers Builds deploys to production from. */
+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.
+#
+# A release is a tag, v<major>.<minor>.<patch>, on a commit of main, or of a
+# 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 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:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+# One release at a time, in the order the tags arrived.
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+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: |
+          tag="$GITHUB_REF_NAME"
+          if ! [[ "$tag" =~ ^v[0-9]+\\.[0-9]+\\.[0-9]+$ ]]; then
+            echo "::error::A release tag is v<major>.<minor>.<patch>, such as v1.4.0. Got $tag."
+            exit 1
+          fi
+          sha="$(git rev-list -n 1 "$tag")"
+          if git merge-base --is-ancestor "$sha" origin/main; then
+            echo "$tag is on main."
+          elif git branch -r --contains "$sha" | grep -q "origin/release/"; then
+            echo "$tag is on a release branch."
+          else
+            echo "::error::$tag isn't on main or a release/ branch, so it can't be released."
+            exit 1
+          fi
+          echo "SHA=$sha" >> "$GITHUB_ENV"
+
+      - name: Move ${ASTROID_DEPLOY_BRANCH} to the tag
+        run: git push --force origin "$SHA:refs/heads/${ASTROID_DEPLOY_BRANCH}"
+
+      - name: Create the GitHub release
+        env:
+          GH_TOKEN: \${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --verify-tag --generate-notes
+`;
+}

package/dist/queues/scaffold.js

@@ -196,10 +196,14 @@ export function generateAstroidWebhookRoute(config, forProvider) {
         "// Unprovisioned (the secret is absent or still the placeholder) answers 503,",
         "// which keeps the provider retrying—so events delivered before you set the",
         "// secret land afterwards instead of being lost.",
+        "//",
+        "// A staging Preview has no queue, since a consumer can't target one, so",
+        "// there the event runs in the request through the same handler instead.",
         'import type { APIRoute } from "astro";',
         'import { handleWebhook, readModuleSecret } from "astroidjs";',
         'import { env } from "cloudflare:workers";',
         `import { ${p.verifier} } from ${JSON.stringify(p.module)};`,
+        'import { handleQueueMessage } from "../../../queue";',
         "",
         "export const prerender = false;",
         "",
@@ -211,6 +215,7 @@ export function generateAstroidWebhookRoute(config, forProvider) {
         `    provider: ${JSON.stringify(provider)},`,
         `    secret: await readModuleSecret(env.${COMMERCE_PROVIDER_SECRETS[provider].webhook}),`,
         `    queue: env.${ASTROID_QUEUE_BINDING},`,
+        "    inline: (message) => handleQueueMessage(env, message),",
         `    verify: ({ raw, secret }) => ${p.call},`,
         "  });",
         "};",

package/dist/queues/webhook.d.ts

@@ -30,6 +30,22 @@ export interface WebhookRouteOptions {
     verify: (input: WebhookVerifyInput) => boolean | Promise<boolean>;
     /** The queue binding, or null/undefined when Queues aren't provisioned. */
     queue?: QueueProducer | null;
+    /**
+     * Run a message in the request instead, when `queue` is absent. A staging
+     * Preview leaves the queue unbound, because a queue consumer can't target a
+     * Preview (louise-toolkit ADR 0017), so without this every webhook a Preview
+     * receives answers 503 and the provider retries it forever.
+     *
+     * Pass the same handler the queue consumer runs: `(message) =>
+     * handleQueueMessage(env, message)`. Throwing answers 503, so the provider
+     * redelivers, which is the retry the queue would have given it.
+     *
+     * It's a fallback, not an alternative: a sync that outlasts the provider's
+     * delivery timeout reads to the provider as a failure, which is why
+     * production enqueues. On staging, with a sandbox catalog, that's a fair
+     * trade, and the queue wins whenever both are there.
+     */
+    inline?: (message: AstroidQueueMessage) => Promise<void>;
     /**
      * Pull the event type out of the parsed payload. Defaults to a `type` field;
      * override for providers that name it differently (Fourthwall's `testMode`

package/dist/queues/webhook.js

@@ -65,10 +65,27 @@ export async function handleWebhook(request, url, options) {
     if (options.accept && !options.accept(type, payload)) {
         return text("Ignored", 202);
     }
-    if (!options.queue)
-        return text("Queue not configured", 503);
+    const message = {
+        kind: "webhook",
+        provider: options.provider,
+        type,
+        payload,
+    };
+    if (!options.queue) {
+        if (!options.inline)
+            return text("Queue not configured", 503);
+        try {
+            await options.inline(message);
+        }
+        catch {
+            // Same contract as a failed send: the event is real, so ask for it again.
+            return text("Processing failed", 503);
+        }
+        // 200, not 202: the work already happened.
+        return text("Processed", 200);
+    }
     try {
-        await options.queue.send({ kind: "webhook", provider: options.provider, type, payload });
+        await options.queue.send(message);
     }
     catch {
         // The signature was good, so this event is real and worth keeping. 503 asks