astroidjs 0.16.0 → 0.17.0

package/bin/astroid.mjs

@@ -16,6 +16,7 @@
 // CLI ships in, no dependency on node_modules layout (mirrors the louise bin).
 
 import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join, resolve } from "node:path";
@@ -667,17 +668,42 @@ New project:  pnpm create astroid@latest
 // `astroid provision` creates what `wrangler.jsonc` still names by placeholder,
 // top level and `previews` alike, and writes each new ID back in place of its
 // placeholder. It never deploys, so it's safe to run before a site's first
-// release, and re-running it only creates what's still missing. Secrets and
-// dashboard settings need a person, so it prints those instead.
+// release, and re-running it only creates what's still missing. It creates the
+// staging secrets that need no person (a random SESSION_SECRET and Turnstile's
+// test secret), skipping any the store already has. Every other secret, and
+// dashboard settings, need a person, so it prints those instead.
+//
+// Every wrangler call runs in the site's directory, so wrangler reads the same
+// `wrangler.jsonc` for each and picks the same account: its `account_id`, which
+// wrangler prefers to CLOUDFLARE_ACCOUNT_ID.
 async function cmdProvision(cwd, rest) {
   const dryRun = rest.includes("--dry-run");
   const assumeYes = rest.includes("--yes") || rest.includes("-y");
   const wranglerPath = join(cwd, "wrangler.jsonc");
   if (!existsSync(wranglerPath)) fail("wrangler.jsonc not found — run inside an Astroid project.");
 
-  const { provisionPlan, applyProvisionedId } = await import(GENERATORS_URL);
+  const {
+    provisionPlan,
+    applyProvisionedId,
+    stagingSecretSteps,
+    secretNamesFromList,
+    TURNSTILE_TEST_SECRET,
+  } = await import(GENERATORS_URL);
   let text = readFileSync(wranglerPath, "utf8");
   const plan = provisionPlan(text);
+  const wranglerBin = resolveBin(cwd, "wrangler", "wrangler");
+
+  // Which staging secrets already exist, per store, so a re-run creates nothing
+  // twice. Listing is read-only, so a dry run does it too.
+  const existing = new Map();
+  if (wranglerBin) {
+    for (const storeId of new Set(plan.secrets.filter((s) => s.create).map((s) => s.storeId))) {
+      const names = listStoreSecrets(wranglerBin, cwd, storeId, secretNamesFromList);
+      if (names) existing.set(storeId, names);
+    }
+  }
+  const secretSteps = stagingSecretSteps(plan.secrets, existing);
+  const toCreate = secretSteps.filter((s) => s.status === "create");
 
   out("astroid provision — plan:\n");
   if (plan.steps.length === 0) out("  (nothing to create: every binding has an ID)");
@@ -685,15 +711,42 @@ async function cmdProvision(cwd, rest) {
     const note = s.kind === "r2" ? "   (an existing bucket is fine)" : "";
     out(`  wrangler ${s.args.join(" ")}${note}`);
   }
-  if (!plan.hasAccount && !process.env.CLOUDFLARE_ACCOUNT_ID) {
+  const envAccount = process.env.CLOUDFLARE_ACCOUNT_ID;
+  if (!plan.hasAccount && !envAccount) {
     out(
       "\n  ! No account_id in wrangler.jsonc and no CLOUDFLARE_ACCOUNT_ID, so wrangler picks one.",
     );
+  } else if (plan.accountId && envAccount && envAccount !== plan.accountId) {
+    out(
+      `\n  ! wrangler.jsonc's account_id (${plan.accountId}) wins over ` +
+        `CLOUDFLARE_ACCOUNT_ID (${envAccount}), so provision uses ${plan.accountId}.`,
+    );
+  }
+  if (secretSteps.length > 0) {
+    out("\nStaging secrets it creates itself:");
+    for (const { secret, status } of secretSteps) {
+      const what =
+        status === "create"
+          ? `will create, with ${secret.create === "random" ? "a new random value" : "Turnstile's always-passes test secret"}`
+          : status === "exists"
+            ? "exists, so it's left alone"
+            : wranglerBin
+              ? "couldn't list the store, so it's left for you"
+              : "can't check without wrangler, so it's left for you";
+      out(`  [staging] ${secret.secretName} in store ${secret.storeId}: ${what}`);
+    }
   }
-  const printSecrets = () => {
-    if (plan.secrets.length === 0) return;
+  // The secrets a person still sets: every one provision doesn't create, and
+  // any it meant to but couldn't.
+  const printSecrets = (failed = []) => {
+    const byHand = [
+      ...plan.secrets.filter((s) => !s.create),
+      ...secretSteps.filter((s) => s.status === "unknown").map((s) => s.secret),
+      ...failed,
+    ];
+    if (byHand.length === 0) return;
     out("\nSecrets Store secrets it binds; create any that don't exist yet:");
-    for (const s of plan.secrets) {
+    for (const s of byHand) {
       out(
         `  [${s.environment}] wrangler secrets-store secret create ${s.storeId} ` +
           `--name ${s.secretName} --scopes workers --remote`,
@@ -706,7 +759,7 @@ async function cmdProvision(cwd, rest) {
     out("\n(dry run — nothing created)");
     return;
   }
-  if (plan.steps.length > 0 && !assumeYes) {
+  if ((plan.steps.length > 0 || toCreate.length > 0) && !assumeYes) {
     if (!process.stdin.isTTY)
       fail("Refusing to create resources non-interactively. Re-run with --yes.");
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -718,7 +771,6 @@ async function cmdProvision(cwd, rest) {
     }
   }
 
-  const wranglerBin = resolveBin(cwd, "wrangler", "wrangler");
   if (!wranglerBin) fail("Could not find `wrangler` in this project.");
   for (const s of plan.steps) {
     out(`\n▸ wrangler ${s.args.join(" ")}`);
@@ -745,10 +797,81 @@ async function cmdProvision(cwd, rest) {
     writeFileSync(wranglerPath, text);
     out(`  ↳ ${s.name} = ${id}`);
   }
-  printSecrets();
+
+  // The value goes to wrangler as an argument of a direct spawn, never through
+  // a shell, and is never printed: wrangler shows it as REDACTED.
+  const failed = [];
+  for (const { secret } of toCreate) {
+    const args = [
+      "secrets-store",
+      "secret",
+      "create",
+      secret.storeId,
+      "--name",
+      secret.secretName,
+      "--scopes",
+      "workers",
+      "--remote",
+    ];
+    out(`\n▸ wrangler ${args.join(" ")} --value <${secret.create}>`);
+    const value =
+      secret.create === "random" ? randomBytes(48).toString("base64") : TURNSTILE_TEST_SECRET;
+    const res = spawnSync(process.execPath, [wranglerBin, ...args, "--value", value], {
+      cwd,
+      stdio: "inherit",
+    });
+    if (res.status !== 0) failed.push(secret);
+  }
+
+  printSecrets(failed);
+  const unlisted = [
+    ...new Set(secretSteps.filter((s) => s.status === "unknown").map((s) => s.secret.storeId)),
+  ];
+  if (unlisted.length > 0 || failed.length > 0) {
+    if (unlisted.length > 0) {
+      out(
+        `\n✘ Couldn't list Secrets Store ${unlisted.join(", ")}, so its staging secrets ` +
+          "weren't created. Check that the store is in this account, then re-run.",
+      );
+    }
+    if (failed.length > 0) {
+      out(`\n✘ Couldn't create ${failed.map((s) => s.secretName).join(", ")}. Re-run to retry.`);
+    }
+    process.exitCode = 1;
+    return;
+  }
   out("\n✓ Provisioned. Commit wrangler.jsonc; the dashboard steps are in the site's RUNBOOK.");
 }
 
+/**
+ * The secret names in a Secrets Store, or null when it can't be listed. Wrangler
+ * prints a table, a page at a time, and fails on a page with no secrets, which
+ * is how an empty store, or the page after the last one, reads.
+ */
+function listStoreSecrets(wranglerBin, cwd, storeId, secretNamesFromList) {
+  const PER_PAGE = 100; // The API's maximum.
+  const names = new Set();
+  for (let page = 1; page <= 50; page++) {
+    const res = spawnSync(
+      process.execPath,
+      [
+        wranglerBin,
+        ...["secrets-store", "secret", "list", storeId, "--remote"],
+        ...["--per-page", String(PER_PAGE), "--page", String(page)],
+      ],
+      { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] },
+    );
+    if (res.status !== 0) {
+      return `${res.stdout}${res.stderr}`.includes("returned no secrets") ? names : null;
+    }
+    const found = secretNamesFromList(res.stdout);
+    const before = names.size;
+    for (const name of found) names.add(name);
+    if (found.length < PER_PAGE || names.size === before) break;
+  }
+  return names;
+}
+
 // `astroid ship` is what Workers Builds runs, so the deploy logic lives in the
 // repository instead of a dashboard field. An account move once rewrote a
 // site's dashboard deploy command to a bare `wrangler deploy`, and migrations

package/dist/auth/index.js

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

package/dist/commerce/roles.js

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

package/dist/commerce/sync.js

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

package/dist/config.js

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

package/dist/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/worker/generate.js

@@ -68,6 +68,7 @@ export function generateAstroidWorker(config) {
     const AI_ROUTES = new Set(["ai", "seoFix", "media"]);
     const editorImports = [
         "DEFAULT_PAGE_FIELDS",
+        "type PagesWrite",
         ...new Set(plan.map((route) => route.factory).filter((f) => !realtimeRouteFactories.has(f))),
     ].sort();
     const tables = [
@@ -104,8 +105,8 @@ export function generateAstroidWorker(config) {
                 //
                 // `versionsTable` makes a DELETE remove the page's version snapshots,
                 // which have no foreign key to the page and would otherwise orphan.
-                // `afterWrite` rebuilds the search index, which plain CRUD writes leave
-                // stale.
+                // `afterWrite` syncs the written page's search index entry, which plain
+                // CRUD writes leave stale.
                 return 'pagesRoute({ table: pages, versionsTable: pagesVersions, resolveEditor, fields: [...DEFAULT_PAGE_FIELDS, "sections"], ...pagesWriteHooks, afterWrite: reindexPagesSearch })';
             case "save":
                 // No `bufferKv` here, deliberately: `saveRoute` has no such option. It
@@ -175,7 +176,7 @@ export function generateAstroidWorker(config) {
     p('import { env } from "cloudflare:workers";');
     p('import { handle } from "@astrojs/cloudflare/handler";');
     p('import type { EditorSession } from "louise-toolkit/auth";');
-    p('import { createLocalApi } from "louise-toolkit/content";');
+    p('import { reindexDoc } from "louise-toolkit/content";');
     p(inquiries
         ? 'import { db, inquiriesForm } from "louise-toolkit/db";'
         : 'import { db } from "louise-toolkit/db";');
@@ -251,10 +252,12 @@ export function generateAstroidWorker(config) {
         : "const pagesWriteHooks = astroidPagesWriteHooks(astroidConfig);");
     p();
     p("// pagesRoute writes with plain Drizzle, so the full-text index doesn't see a");
-    p("// title or slug change until something rebuilds it. Best-effort: pagesRoute");
-    p("// swallows a throw here, so a stale index never fails the write itself.");
-    p("async function reindexPagesSearch(editor: EditorSession): Promise<void> {");
-    p("  await createLocalApi(db(env.DB), pages, pagesCollection).reindexSearch({ session: editor });");
+    p("// title or slug change until something syncs it. This syncs only the page the");
+    p("// write touched, rather than rebuilding the whole index on every save. After a");
+    p("// delete the row is gone, and reindexDoc removes its entry. Best-effort:");
+    p("// pagesRoute swallows a throw here, so a stale index never fails the write.");
+    p("async function reindexPagesSearch(_editor: EditorSession, { id }: PagesWrite): Promise<void> {");
+    p("  await reindexDoc(db(env.DB), pages, pagesCollection, id);");
     p("}");
     p();
     p("// Editable site_settings columns the Settings panel may write, and which of");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astroidjs",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Astroid — an opinionated meta-framework over Louise Toolkit and Astro for building editable, multi-editor sites on Cloudflare Workers.",
   "keywords": [
     "astro",
@@ -64,14 +64,14 @@
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@vitest/coverage-v8": "4.1.11",
     "astro": "^7.2.9",
-    "louise-toolkit": "^0.33.0",
+    "louise-toolkit": "^0.34.0",
     "solid-js": "^1.9.15",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11"
   },
   "peerDependencies": {
     "astro": "^7.0.9",
-    "louise-toolkit": "^0.33.0",
+    "louise-toolkit": "^0.34.0",
     "solid-js": "^1.9.0"
   },
   "peerDependenciesMeta": {