astroidjs 0.19.0 → 0.21.0

package/bin/astroid.mjs

@@ -172,6 +172,7 @@ async function cmdDoctor(cwd, flags) {
     generateAstroidScaffoldFiles,
     astroidUsesQueues,
     astroidCrons,
+    astroidHasEditor,
     checkWranglerPreviews,
     astroidRunsMigrations,
     migrationsOwnershipError,
@@ -235,9 +236,15 @@ async function cmdDoctor(cwd, flags) {
     //
     // So check every binding the GENERATED code actually dereferences, not just
     // the three the baseline happens to have.
+    // An app with no editor (`editor: false`) uses none of the editor's
+    // bindings, so it isn't held to them: no draft buffer, no media bucket, and
+    // no mail unless its portal sends password resets.
+    const editor = astroidHasEditor(config);
     const requiredBindings = [
       { name: "RL", what: "KV namespace", why: "the rate limiter in src/middleware.ts" },
-      { name: "DRAFTS", what: "KV namespace", why: "the autosave draft buffer" },
+      ...(editor
+        ? [{ name: "DRAFTS", what: "KV namespace", why: "the autosave draft buffer" }]
+        : []),
       ...(astroidUsesQueues(config)
         ? [
             {
@@ -263,17 +270,24 @@ async function cmdDoctor(cwd, flags) {
     // it: the magic link is console-logged in dev and EMAILED in production, so
     // a missing binding is a site nobody can sign in to—and it fails only once
     // deployed, which is the one place nothing in this repo exercises.
-    if (/"send_email"\s*:/.test(w)) ok("wrangler: Email Sending `EMAIL` binding present");
-    else
+    // An app with no editor and no portal signs nobody in, so it sends no mail.
+    const sendsMail = editor || Boolean(config.portal?.enabled);
+    if (sendsMail && /"send_email"\s*:/.test(w))
+      ok("wrangler: Email Sending `EMAIL` binding present");
+    else if (sendsMail)
       err(
-        "wrangler.jsonc has no `send_email` binding, but production sign-in emails the " +
-          'magic link (it is only console-logged in dev). Add: "send_email": [{ "name": "EMAIL" }]',
+        editor
+          ? "wrangler.jsonc has no `send_email` binding, but production sign-in emails the " +
+              'magic link (it is only console-logged in dev). Add: "send_email": [{ "name": "EMAIL" }]'
+          : "wrangler.jsonc has no `send_email` binding, but the portal emails password resets " +
+              'in production (they are only console-logged in dev). Add: "send_email": [{ "name": "EMAIL" }]',
       );
 
     if (hasBinding("DB")) ok("wrangler: D1 `DB` binding present");
     else err("wrangler.jsonc has no D1 `DB` binding.");
-    if (hasBinding("MEDIA")) ok("wrangler: R2 `MEDIA` binding present");
-    else err("wrangler.jsonc has no R2 `MEDIA` binding.");
+    // An app with no editor has no media library, so no bucket to hold it.
+    if (editor && hasBinding("MEDIA")) ok("wrangler: R2 `MEDIA` binding present");
+    else if (editor) err("wrangler.jsonc has no R2 `MEDIA` binding.");
     if (/"main"\s*:\s*"src\/worker\.ts"/.test(w)) ok("wrangler: `main` → src/worker.ts");
     else warn("wrangler.jsonc `main` does not point at src/worker.ts.");
 
@@ -287,7 +301,17 @@ async function cmdDoctor(cwd, flags) {
     // JSON.parse (comments/trailing commas), matching the binding checks above.
     const expectedCrons = astroidCrons(config);
     const cronsMatch = w.match(/"crons"\s*:\s*\[([^\]]*)\]/);
-    if (!cronsMatch) {
+    const declaredAny = cronsMatch && /"[^"]+"/.test(cronsMatch[1]);
+    if (expectedCrons.length === 0) {
+      // Nothing scheduled, so the generated worker has no `scheduled` handler,
+      // and a declared trigger would fail every time it fired.
+      if (declaredAny)
+        warn(
+          "wrangler.jsonc declares `triggers.crons`, but nothing in your config is scheduled, " +
+            "so the generated worker has no `scheduled` handler for them. Remove the triggers.",
+        );
+      else ok("wrangler: no crons, and nothing is scheduled");
+    } else if (!cronsMatch) {
       err(
         "wrangler.jsonc has no `triggers.crons`, but the generated `scheduled` handler " +
           `dispatches on ${expectedCrons.map((c) => `"${c}"`).join(", ")}. ` +

package/dist/commerce/secrets.d.ts

@@ -50,6 +50,13 @@ export declare function commerceProviderCredentials(provider: CommerceProvider,
  * `.dev.vars` would be a bug rather than a redundancy.
  */
 export declare function commerceSecretNames(commerce: CommerceConfig | undefined): string[];
+/**
+ * The webhook signing secret a provider needs, or none when the project runs no
+ * pipeline (`commerce.pipeline: false`). With no receiver there is nothing to
+ * verify, so requiring the secret would hold checkout dormant for a value no
+ * code reads.
+ */
+export declare function commerceProviderWebhookSecrets(provider: CommerceProvider, commerce: CommerceConfig | undefined): readonly string[];
 /** One provider's resolved gate. */
 export interface ProviderStatus {
     provider: CommerceProvider;

package/dist/commerce/secrets.js

@@ -101,19 +101,28 @@ export function commerceProviderCredentials(provider, commerce) {
 export function commerceSecretNames(commerce) {
     const names = astroidCommerceProviders(commerce).flatMap((provider) => [
         ...commerceProviderCredentials(provider, commerce),
-        COMMERCE_PROVIDER_SECRETS[provider].webhook,
+        ...commerceProviderWebhookSecrets(provider, commerce),
     ]);
     return [...new Set(names)];
 }
+/**
+ * The webhook signing secret a provider needs, or none when the project runs no
+ * pipeline (`commerce.pipeline: false`). With no receiver there is nothing to
+ * verify, so requiring the secret would hold checkout dormant for a value no
+ * code reads.
+ */
+export function commerceProviderWebhookSecrets(provider, commerce) {
+    return commerce?.pipeline === false ? [] : [COMMERCE_PROVIDER_SECRETS[provider].webhook];
+}
 /** Read one provider's secrets off an env-shaped record. */
 async function resolveProvider(provider, roles, env, commerce) {
-    const spec = COMMERCE_PROVIDER_SECRETS[provider];
     const pick = (names) => Object.fromEntries(names.map((n) => [n, env[n]]));
     const [credentials, webhook] = await Promise.all([
         // Config-aware: a multi-location project must not be held dormant waiting
         // for a SQUARE_LOCATION_ID it will never legitimately have.
         resolveModuleSecrets(pick(commerceProviderCredentials(provider, commerce))),
-        resolveModuleSecrets(pick([spec.webhook])),
+        // Empty without a pipeline, which resolves as configured: nothing to verify.
+        resolveModuleSecrets(pick(commerceProviderWebhookSecrets(provider, commerce))),
     ]);
     return {
         provider,

package/dist/config.d.ts

@@ -175,6 +175,18 @@ export interface CommerceConfig {
     catalog?: CatalogMirrorConfig;
     /** Square-specific options. Only meaningful when Square fills some role. */
     square?: SquareCommerceConfig;
+    /**
+     * Whether this project runs the commerce pipeline: the webhook receivers, the
+     * queue consumer that processes them, and the hourly catalog re-sync. Default
+     * `true`.
+     *
+     * Set `false` for a project that only takes payments while another project,
+     * or another Worker in the same repository, runs the pipeline against the
+     * same account. It keeps what a checkout needs, the provider's CSP origins,
+     * the checkout rate rule, and the checkout route, and drops the rest, along
+     * with the webhook signing secret nothing would verify.
+     */
+    pipeline?: boolean;
 }
 export interface SquareCommerceConfig {
     /**
@@ -195,8 +207,9 @@ export interface SquareCommerceConfig {
 export interface QueuesConfig {
     /**
      * Force the queue consumer + cron on or off. Defaults to on whenever
-     * `commerce` is configured: a commerce provider means webhooks, and a webhook
-     * you process inline is a webhook you drop when the provider times out.
+     * `commerce` is configured with its pipeline: a commerce provider means
+     * webhooks, and a webhook you process inline is a webhook you drop when the
+     * provider times out.
      */
     enabled?: boolean;
     /**
@@ -482,6 +495,24 @@ export interface StatusConfig {
      */
     checks?: boolean;
 }
+/**
+ * Incident capture (louise-toolkit ADR 0022). Every Astroid site counts its
+ * failures into its own D1 and an Analytics Engine dataset; these settings add
+ * to that.
+ */
+export interface IncidentsConfig {
+    /**
+     * The failures that should alert: dotted names (`commerce.checkout`) and
+     * path prefixes (`/cart`). A site fact, so there's no default list.
+     */
+    critical?: string[];
+    /**
+     * Also send each incident to Sentry, the operator's issue system for a
+     * Monitored or Supported site. It reads the DSN from the `SENTRY_DSN`
+     * secret, and stays dormant while that's unset or a placeholder.
+     */
+    sentry?: boolean;
+}
 export interface DeployConfig {
     platform: "cloudflare";
     /** Media base for R2 + `cf-image` resizing—matches Louise's media route
@@ -497,6 +528,28 @@ export interface DeployConfig {
      */
     migrations?: boolean;
 }
+/**
+ * A small "Site by …" line the footer renders for the agency that built the
+ * site. A site fact, so it has no default: omit it and nothing renders.
+ */
+export interface CreditConfig {
+    /** Who built the site, for example `"Example Organization"`. */
+    name: string;
+    /** Where the credit links, as an absolute `http` or `https` URL. */
+    href: string;
+    /**
+     * An optional mark shown before the name: a root-relative path (for example
+     * `"/credit-mark.svg"`) or an `https:` URL. It's drawn as a mask filled with
+     * the text color, so one single-color SVG works on every theme. Only its
+     * shape counts; its own fill is ignored.
+     */
+    logo?: string;
+    /** The link's `rel`, for example `"noopener"` or `"noopener nofollow"`. The
+     *  site decides; omitted, the link carries none. */
+    rel?: string;
+    /** The words before the name. Default `"Site by"`. */
+    label?: string;
+}
 export interface AstroidConfig {
     /**
      * Stable project slug—the worker/D1/R2 base name and default subdomain (for example,
@@ -513,6 +566,21 @@ export interface AstroidConfig {
     tenancy?: TenancyConfig;
     /** Starting shape; sets section/module/nav defaults the site can override. */
     archetype: Archetype;
+    /**
+     * Whether the project has a Louise editor. Default `true`.
+     *
+     * Set `false` for an app with no pages to edit, such as an order app whose
+     * menu comes from a commerce provider and whose few settings another site's
+     * editor owns. The generated worker and middleware then carry no editor
+     * routes and no sign-in, the schema carries no content tables, and
+     * `wrangler.jsonc` binds no draft buffer, media bucket, or AI. What stays is
+     * the rate limiter, the CSP, the security headers, the public status route,
+     * and the `portal`, `pwa`, `commerce`, and `tenancy` modules.
+     *
+     * `defineAstroid` refuses every option that configures the editor
+     * alongside it, such as `sections` or `media`, rather than ignore it.
+     */
+    editor?: boolean;
     /** The single brand's theme (display name + color tokens + font). */
     theme: Theme;
     /** The editable home page, top to bottom. Omit to take the archetype default. */
@@ -573,6 +641,8 @@ export interface AstroidConfig {
     pages?: PagesConfig;
     /** The public status route's site-owned checks. */
     status?: StatusConfig;
+    /** Incident capture settings: what alerts, and whether Sentry gets a copy. */
+    incidents?: IncidentsConfig;
     /**
      * Force the contact form + `inquiries` table on or off. Omit to detect from
      * the config (a `contact` section, or a wholesale-inquiry module). Set `true`
@@ -583,6 +653,8 @@ export interface AstroidConfig {
     inquiries?: boolean;
     /** Installable-app settings. Only read when `modules` includes `"pwa"`. */
     pwa?: PwaConfig;
+    /** The agency credit `<Credit>` renders in the footer. Omit for none. */
+    credit?: CreditConfig;
     deploy?: DeployConfig;
 }
 export declare function defineAstroid(config: AstroidConfig): AstroidConfig;

package/dist/config.js

@@ -34,6 +34,7 @@ import { AstroidConfigError } from "./errors.js";
 // type-only, so the cycle erases at build and nothing circular exists at runtime.
 // It is also dependency-free, so `create-astroid`'s graph is unchanged.
 import { ASTROID_HEALTH_CRON, astroidCron, astroidUsesQueues } from "./queues/messages.js";
+import { astroidHasEditor } from "./shape.js";
 /**
  * Each archetype's default home-page sections.
  *
@@ -88,6 +89,13 @@ export const ASTROID_SCAFFOLD_ROUTE_SLUGS = ["contact", "login", "work"];
  * the unreachable-trigger failure `config.crons` exists to prevent.
  */
 function assertCrons(config) {
+    // `queues.cron` schedules the catalog re-sync, which belongs to the pipeline.
+    // Without one it would be accepted and never scheduled.
+    if (config.commerce?.pipeline === false && typeof config.queues?.cron === "string") {
+        throw new AstroidConfigError("`queues.cron` schedules the catalog re-sync, which `commerce.pipeline: false` " +
+            "leaves to the project that runs the pipeline. Remove `queues.cron`, or use " +
+            "`crons` for a job of this project's own.");
+    }
     const crons = config.crons ?? [];
     if (crons.length === 0)
         return;
@@ -96,7 +104,7 @@ function assertCrons(config) {
             "without it the generated handler would `send` to a binding this project never creates. " +
             "Set `queues: { enabled: true }`, or drop the crons.");
     }
-    const seen = new Map([[ASTROID_HEALTH_CRON, "the daily health scan"]]);
+    const seen = new Map(astroidHasEditor(config) ? [[ASTROID_HEALTH_CRON, "the daily health scan"]] : []);
     const catalog = astroidCron(config);
     if (catalog)
         seen.set(catalog, "the catalog re-sync (`queues.cron`)");
@@ -196,6 +204,79 @@ function assertMediaConfig(media) {
             "would fail with an error the media route never sees.");
     }
 }
+/**
+ * A credit that would render as a broken link or an empty mark.
+ *
+ * The logo is limited to a root-relative path or `https:` because it lands in a
+ * CSS `url()`: a `data:` or `javascript:` value there is at best unrenderable,
+ * and a relative one resolves against each page's path rather than the site.
+ */
+function assertCredit(credit) {
+    if (!credit)
+        return;
+    if (!credit.name?.trim()) {
+        throw new AstroidConfigError("`credit.name` is required: the name the footer credits");
+    }
+    let href;
+    try {
+        href = new URL(credit.href);
+    }
+    catch {
+        // Reported below with the value that failed.
+    }
+    if (!href || (href.protocol !== "https:" && href.protocol !== "http:")) {
+        throw new AstroidConfigError(`\`credit.href\` must be an absolute http or https URL, such as "https://example.com", ` +
+            `but it's "${credit.href}"`);
+    }
+    const logo = credit.logo;
+    if (logo !== undefined &&
+        !(logo.startsWith("/") && !logo.startsWith("//")) &&
+        !logo.startsWith("https://")) {
+        throw new AstroidConfigError(`\`credit.logo\` must be a root-relative path such as "/credit-mark.svg" or an ` +
+            `https URL, but it's "${logo}"`);
+    }
+}
+/**
+ * The options an app with no editor can't honor. Each configures the editor, a
+ * table it edits, or a surface only an editor reviews, so accepting one would
+ * be accepting a setting nothing reads.
+ */
+const EDITOR_ONLY_OPTIONS = [
+    ["sections", "the editable home page"],
+    ["sectionCatalog", "the page editor's sections"],
+    ["blockCatalog", "the page editor's blocks"],
+    ["media", "the media library"],
+    ["pages", "the editable pages"],
+    ["settings", "the Settings panel"],
+];
+/** Modules that only work with an editor, and why. */
+const EDITOR_ONLY_MODULES = {
+    realtime: "it syncs editors editing one page",
+    wholesaleInquiry: "its inquiries are reviewed in the editor",
+};
+function assertEditorFree(config) {
+    if (astroidHasEditor(config))
+        return;
+    const without = "An app with `editor: false` has no editor";
+    for (const [key, what] of EDITOR_ONLY_OPTIONS) {
+        if (config[key] !== undefined) {
+            throw new AstroidConfigError(`${without}, so \`${key}\` (${what}) would do nothing. Remove it, or drop \`editor: false\`.`);
+        }
+    }
+    if (config.inquiries === true) {
+        throw new AstroidConfigError(`${without} to review inquiries in, so \`inquiries: true\` would collect messages ` +
+            "nobody reads. Remove it, or drop `editor: false`.");
+    }
+    for (const module of [...(config.modules ?? []), ...(config.portal?.features ?? [])]) {
+        const why = EDITOR_ONLY_MODULES[module];
+        if (why) {
+            throw new AstroidConfigError(`${without}, so the \`${module}\` module can't work: ${why}. Remove it, or drop \`editor: false\`.`);
+        }
+    }
+    if (config.deploy?.mediaBase !== undefined) {
+        throw new AstroidConfigError(`${without} and no media library, so \`deploy.mediaBase\` would do nothing. Remove it.`);
+    }
+}
 export function defineAstroid(config) {
     if (!config.key || config.key.trim().length === 0) {
         throw new AstroidConfigError("Astroid config requires a non-empty `key` (it names the generated worker/D1/R2 bindings)");
@@ -231,6 +312,8 @@ export function defineAstroid(config) {
     assertCrons(config);
     assertTenancy(config);
     assertAllowSlugs(config);
+    assertEditorFree(config);
+    assertCredit(config.credit);
     if (config.portal?.gated) {
         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 " +

package/dist/incidents/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./names.js";
+export * from "./sentry.js";

package/dist/incidents/index.js

@@ -0,0 +1,12 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Incident capture, Astroid's side (louise-toolkit ADR 0022, amended).
+//
+// louise-toolkit counts every failure into the site's own D1 and, optionally,
+// Analytics Engine. What's opinion, and so lives here: that every Astroid site
+// captures incidents by default, the binding and dataset names, the migration
+// an existing site needs, and the Sentry sink. Sentry is the operator's issue
+// system for a Monitored or Supported site; it's never the record, and it's
+// never in louise-toolkit's zero-dependency core (ADR 0016 § 7).
+export * from "./names.js";
+export * from "./sentry.js";

package/dist/incidents/names.d.ts

@@ -0,0 +1,17 @@
+import type { AstroidConfig } from "../config.js";
+/** The Analytics Engine binding incident counts go to. */
+export declare const ASTROID_INCIDENT_EVENTS_BINDING = "INCIDENT_EVENTS";
+/** The version metadata binding a report's `release` comes from. */
+export declare const ASTROID_VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
+/** The binding the Sentry sink reads its DSN from: a Worker secret or a
+ *  Secrets Store binding. This is its name, not the DSN. */
+export declare const ASTROID_SENTRY_DSN_BINDING = "SENTRY_DSN";
+/** The incident counts dataset: `<key>_incidents`, apart from the Core Web Vitals one. */
+export declare function astroidIncidentEventsDataset(config: AstroidConfig): string;
+/**
+ * `migrations/0006_incidents.sql`: the `incidents` and `dead_letters` tables
+ * (louise-toolkit/incidents). The same DDL drizzle-kit writes for them, with
+ * `IF NOT EXISTS`, since a site that already added a table by hand must not
+ * fail on it.
+ */
+export declare const ASTROID_INCIDENTS_MIGRATION: string;

package/dist/incidents/names.js

@@ -0,0 +1,55 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Incident capture's names and migration (louise-toolkit ADR 0022). No
+// runtime imports, so the CLI's generators can read them without loading any
+// louise-toolkit subpath.
+/** The Analytics Engine binding incident counts go to. */
+export const ASTROID_INCIDENT_EVENTS_BINDING = "INCIDENT_EVENTS";
+/** The version metadata binding a report's `release` comes from. */
+export const ASTROID_VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
+/** The binding the Sentry sink reads its DSN from: a Worker secret or a
+ *  Secrets Store binding. This is its name, not the DSN. */
+export const ASTROID_SENTRY_DSN_BINDING = "SENTRY_DSN";
+/** The incident counts dataset: `<key>_incidents`, apart from the Core Web Vitals one. */
+export function astroidIncidentEventsDataset(config) {
+    return `${config.key.replace(/[^a-z0-9_]/gi, "_")}_incidents`;
+}
+/**
+ * `migrations/0006_incidents.sql`: the `incidents` and `dead_letters` tables
+ * (louise-toolkit/incidents). The same DDL drizzle-kit writes for them, with
+ * `IF NOT EXISTS`, since a site that already added a table by hand must not
+ * fail on it.
+ */
+export const ASTROID_INCIDENTS_MIGRATION = [
+    "-- Incidents (louise-toolkit ADR 0022): one row per fingerprint, counted by the",
+    "-- worker's d1Incidents sink and read by the Health panel and Watchtower. Dead",
+    "-- letters: each message a queue gave up on, kept for a runbook to replay.",
+    "-- Scaffolded by astroidjs.",
+    "CREATE TABLE IF NOT EXISTS `incidents` (",
+    "\t`fingerprint` text PRIMARY KEY NOT NULL,",
+    "\t`kind` text NOT NULL,",
+    "\t`name` text NOT NULL,",
+    "\t`code` text,",
+    "\t`message` text NOT NULL,",
+    "\t`path` text,",
+    "\t`host` text,",
+    "\t`release` text,",
+    "\t`critical` integer DEFAULT false NOT NULL,",
+    "\t`count` integer DEFAULT 1 NOT NULL,",
+    "\t`first_seen` integer NOT NULL,",
+    "\t`last_seen` integer NOT NULL,",
+    "\t`resolved_at` integer,",
+    "\t`reopened_at` integer",
+    ");",
+    "CREATE INDEX IF NOT EXISTS `incidents_last_seen` ON `incidents` (`last_seen`);",
+    "CREATE TABLE IF NOT EXISTS `dead_letters` (",
+    "\t`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,",
+    "\t`queue` text NOT NULL,",
+    "\t`message_id` text NOT NULL,",
+    "\t`body` text NOT NULL,",
+    "\t`attempts` integer NOT NULL,",
+    "\t`received_at` integer NOT NULL",
+    ");",
+    "CREATE INDEX IF NOT EXISTS `dead_letters_queue` ON `dead_letters` (`queue`);",
+    "",
+].join("\n");

package/dist/incidents/sentry.d.ts

@@ -0,0 +1,20 @@
+import type { IncidentReport, IncidentSink } from "louise-toolkit/incidents";
+import { type SecretSource } from "../secrets.js";
+export interface SentryIncidentsOptions {
+    /** A tag naming the site, so one Sentry organization can tell sites apart. */
+    site?: string;
+    /** Sentry's `environment`. Default `"production"`. */
+    environment?: string;
+    /** Injected for tests. */
+    fetch?: typeof fetch;
+}
+/** The Sentry event for a report: its redacted message, its fingerprint, and the
+ *  cause's stack frames. Never the raw message, the query string, or a body. */
+export declare function sentryEvent(report: IncidentReport, cause: unknown, options?: Pick<SentryIncidentsOptions, "site" | "environment">): Record<string, unknown>;
+/**
+ * A sink that sends each report to Sentry, through its envelope endpoint, with
+ * no SDK: `sendDefaultPii` has nothing to turn off, because nothing but the
+ * redacted report and the stack's frames is sent. Dormant while the DSN is
+ * unset or a placeholder, like every Astroid module.
+ */
+export declare function sentryIncidents<Env>(dsn: (env: Env) => SecretSource | undefined, options?: SentryIncidentsOptions): IncidentSink<Env>;

package/dist/incidents/sentry.js

@@ -0,0 +1,118 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The Sentry sink (louise-toolkit ADR 0022, amended): Sentry is the operator's
+// issue system for a Monitored or Supported site. It's never the record, and
+// never in louise-toolkit's zero-dependency core (ADR 0016 § 7).
+import { readModuleSecret } from "../secrets.js";
+function parseDsn(dsn) {
+    try {
+        const url = new URL(dsn);
+        const project = url.pathname.replace(/^\/+|\/+$/g, "");
+        if (!url.username || !/^\d+$/.test(project))
+            return null;
+        return { key: url.username, origin: `${url.protocol}//${url.host}`, project };
+    }
+    catch {
+        return null;
+    }
+}
+const V8_FRAME = /^\s*at (?:(.+?) \()?(.+?)(?::(\d+))?(?::(\d+))?\)?$/;
+/** The cause's stack as Sentry frames, oldest call first, or none. Function
+ *  names and file positions only: no message, no values. */
+function frames(cause) {
+    let stack;
+    try {
+        stack = cause?.stack;
+    }
+    catch {
+        return [];
+    }
+    if (typeof stack !== "string")
+        return [];
+    const out = [];
+    for (const line of stack.split("\n")) {
+        if (!line.trimStart().startsWith("at "))
+            continue;
+        const match = V8_FRAME.exec(line);
+        if (!match)
+            continue;
+        const [, fn, filename, lineno, colno] = match;
+        out.push({
+            ...(fn ? { function: fn } : {}),
+            filename: filename,
+            ...(lineno ? { lineno: Number(lineno) } : {}),
+            ...(colno ? { colno: Number(colno) } : {}),
+            in_app: !filename.includes("node_modules"),
+        });
+    }
+    return out.slice(0, 50).reverse();
+}
+/** The Sentry event for a report: its redacted message, its fingerprint, and the
+ *  cause's stack frames. Never the raw message, the query string, or a body. */
+export function sentryEvent(report, cause, options = {}) {
+    const stack = frames(cause);
+    return {
+        event_id: crypto.randomUUID().replace(/-/g, ""),
+        timestamp: report.at / 1000,
+        platform: "javascript",
+        level: report.critical ? "fatal" : "error",
+        logger: "louise",
+        environment: options.environment ?? "production",
+        ...(report.release ? { release: report.release } : {}),
+        // One D1 row, one Sentry issue: Watchtower joins them on this.
+        fingerprint: [report.fingerprint],
+        tags: {
+            louise_fingerprint: report.fingerprint,
+            kind: report.kind,
+            critical: String(report.critical),
+            ...(options.site ? { site: options.site } : {}),
+            ...(report.code ? { code: report.code } : {}),
+        },
+        ...(report.kind === "fetch" && report.host && report.path
+            ? { request: { url: `https://${report.host}${report.path}` } }
+            : {}),
+        ...(report.path ? { transaction: report.path } : {}),
+        exception: {
+            values: [
+                {
+                    type: report.name,
+                    value: report.message,
+                    ...(stack.length > 0 ? { stacktrace: { frames: stack } } : {}),
+                },
+            ],
+        },
+    };
+}
+/**
+ * A sink that sends each report to Sentry, through its envelope endpoint, with
+ * no SDK: `sendDefaultPii` has nothing to turn off, because nothing but the
+ * redacted report and the stack's frames is sent. Dormant while the DSN is
+ * unset or a placeholder, like every Astroid module.
+ */
+export function sentryIncidents(dsn, options = {}) {
+    return async (report, { env, cause }) => {
+        const source = dsn(env);
+        if (source === undefined)
+            return;
+        const value = await readModuleSecret(source);
+        const parsed = value ? parseDsn(value) : null;
+        if (!parsed)
+            return;
+        const event = sentryEvent(report, cause, options);
+        const body = [
+            JSON.stringify({ event_id: event.event_id, sent_at: new Date().toISOString() }),
+            JSON.stringify({ type: "event" }),
+            JSON.stringify(event),
+        ].join("\n");
+        const response = await (options.fetch ?? fetch)(`${parsed.origin}/api/${parsed.project}/envelope/`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/x-sentry-envelope",
+                "x-sentry-auth": `Sentry sentry_version=7, sentry_key=${parsed.key}, sentry_client=astroidjs`,
+            },
+            body,
+        });
+        if (!response.ok)
+            throw new Error(`Sentry answered ${response.status}`);
+    };
+}

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from "./commerce/index.js";
 export * from "./config.js";
 export * from "./email/index.js";
 export * from "./errors.js";
+export * from "./incidents/index.js";
 export * from "./secrets.js";
 export * from "./map/index.js";
 export * from "./portal/index.js";
@@ -15,6 +16,7 @@ export * from "./queues/index.js";
 export * from "./schema/index.js";
 export * from "./security/index.js";
 export * from "./seo/index.js";
+export * from "./shape.js";
 export * from "./status.js";
 export * from "./tenancy/index.js";
 export * from "./worker/index.js";

package/dist/index.js

@@ -9,6 +9,7 @@ export * from "./commerce/index.js";
 export * from "./config.js";
 export * from "./email/index.js";
 export * from "./errors.js";
+export * from "./incidents/index.js";
 export * from "./secrets.js";
 export * from "./map/index.js";
 export * from "./portal/index.js";
@@ -20,6 +21,7 @@ export * from "./queues/index.js";
 export * from "./schema/index.js";
 export * from "./security/index.js";
 export * from "./seo/index.js";
+export * from "./shape.js";
 export * from "./status.js";
 export * from "./tenancy/index.js";
 export * from "./worker/index.js";

package/dist/pages/index.d.ts

@@ -0,0 +1,19 @@
+import type { D1Client } from "louise-toolkit/db";
+import { type DraftBufferKV } from "louise-toolkit/editor";
+import type { AstroidConfig } from "../config.js";
+/** The bindings a page draft read uses: the database, and the draft buffer. */
+export interface AstroidPageDraftEnv {
+    DB: D1Client;
+    /** The draft buffer the generated routes save through, when bound. */
+    DRAFTS?: DraftBufferKV;
+}
+/**
+ * The editor's work-in-progress snapshot of the page with id `pageId`, or
+ * `null` when there's none (render the live row). The buffer comes first, then
+ * the newest pending draft in D1, the same order a save builds on.
+ *
+ * Returns the whole snapshot: which fields a page renders from it (`sections`,
+ * `body`, `title`) is the site's call. Call it only in edit mode; a visitor
+ * sees the live row.
+ */
+export declare function astroidPageDraft(config: AstroidConfig, env: AstroidPageDraftEnv, pageId: number): Promise<Record<string, unknown> | null>;