astroidjs 0.20.0 → 0.21.0

package/dist/config.d.ts

@@ -495,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
@@ -623,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`

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";

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";

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

package/dist/pages/index.js

@@ -0,0 +1,34 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// `astroidjs/pages`—the editor's work-in-progress on a page, for a page route
+// in edit mode. A subpath of its own because it reads through louise-toolkit's
+// editor and Drizzle, which the main entry (loaded by astroid.config.ts and the
+// CLI) stays free of.
+//
+// The generated worker saves pages through the DRAFTS buffer, keyed by the pages
+// collection's slug, and flushes to `pages_versions` in D1 behind it. A page
+// route has to read the same way, buffer first, or an editor who reloads before
+// the flush sees an older page than the one they just saved. Every site that
+// read D1 alone hit that, and each wrapped louise-toolkit's `resumeDraft` in the
+// same few lines to fix it. This is those lines, with the slug and the versions
+// table derived from the config rather than restated.
+import { collectionVersionsTable } from "louise-toolkit/content";
+import { resumeDraft } from "louise-toolkit/editor";
+import { astroidPagesCollection } from "../schema/collections.js";
+/**
+ * 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 function astroidPageDraft(config, env, pageId) {
+    const collection = astroidPagesCollection(config);
+    return resumeDraft(env.DB, {
+        versionsTable: collectionVersionsTable(collection),
+        collection: collection.slug,
+        bufferKv: env.DRAFTS,
+    }, { id: pageId });
+}

package/dist/project/generate.js

@@ -18,6 +18,7 @@ import { ASTROID_VITALS_BINDING, astroidVitalsDataset } from "../analytics/index
 import { astroidCheckoutVars } from "../commerce/checkout-scaffold.js";
 import { astroidCommerceProviders } from "../commerce/roles.js";
 import { COMMERCE_PROVIDER_SECRETS, COMMERCE_PROVIDER_SETUP, commerceProviderWebhookSecrets, commerceSecretNames, } from "../commerce/secrets.js";
+import { ASTROID_INCIDENT_EVENTS_BINDING, ASTROID_VERSION_METADATA_BINDING, astroidIncidentEventsDataset, } from "../incidents/names.js";
 import { ASTROID_QUEUE_BINDING, ASTROID_QUEUE_RETRY_DELAY, astroidCrons, astroidQueueNames, astroidUsesQueues, } from "../queues/messages.js";
 import { ASTROID_EDIT_SESSION_CLASS, ASTROID_REALTIME_BINDING, ASTROID_REALTIME_MIGRATION_TAG, usesRealtime, } from "../realtime/scaffold.js";
 import { ASTROID_SECRET_PLACEHOLDER } from "../secrets.js";
@@ -218,6 +219,10 @@ export function generateAstroidWrangler(config) {
         p(`        "retry_delay": ${config.queues?.retryDelay ?? ASTROID_QUEUE_RETRY_DELAY},`);
         p(`        "dead_letter_queue": ${JSON.stringify(dlq)},`);
         p("      },");
+        p("      // The dead-letter queue's own consumer: the worker keeps each message");
+        p("      // in the `dead_letters` table and counts it as an incident, so a");
+        p("      // failed event is never lost unseen. No retries of its own.");
+        p(`      { "queue": ${JSON.stringify(dlq)}, "max_batch_size": 10, "max_retries": 0 },`);
         p("    ],");
         p("  },");
     }
@@ -229,6 +234,13 @@ export function generateAstroidWrangler(config) {
         p("  // D1: this app's tables (src/schema.ts), or the database of the app that");
         p("  // owns the schema, bound by its id. Create one: `wrangler d1 create <name>`.");
     }
+    p("  // The deployed version's ID, which each incident records as its release.");
+    p(`  "version_metadata": { "binding": ${JSON.stringify(ASTROID_VERSION_METADATA_BINDING)} },`);
+    if (!editor) {
+        // The editor shape lists this dataset beside the Core Web Vitals one below.
+        p("  // Analytics Engine: incident counts over time (louise-toolkit ADR 0022).");
+        p(`  "analytics_engine_datasets": [{ "binding": ${JSON.stringify(ASTROID_INCIDENT_EVENTS_BINDING)}, "dataset": ${JSON.stringify(astroidIncidentEventsDataset(config))} }],`);
+    }
     p('  "d1_databases": [');
     p("    {");
     p('      "binding": "DB",');
@@ -250,8 +262,9 @@ export function generateAstroidWrangler(config) {
         p("  // Analytics Engine: real-visitor Core Web Vitals. Free, and the ingest");
         p("  // route accepts-and-drops without it, so it costs nothing unused. Reading");
         p("  // the p75 back out needs CF_ACCOUNT_ID + CF_API_TOKEN (see .env.example)—");
-        p("  // until those are real the Health badge reads 'not measured yet'.");
-        p(`  "analytics_engine_datasets": [{ "binding": ${JSON.stringify(ASTROID_VITALS_BINDING)}, "dataset": ${JSON.stringify(astroidVitalsDataset(config))} }],`);
+        p("  // until those are real the Health badge reads 'not measured yet'. The");
+        p("  // second dataset counts incidents over time (louise-toolkit ADR 0022).");
+        p(`  "analytics_engine_datasets": [{ "binding": ${JSON.stringify(ASTROID_VITALS_BINDING)}, "dataset": ${JSON.stringify(astroidVitalsDataset(config))} }, { "binding": ${JSON.stringify(ASTROID_INCIDENT_EVENTS_BINDING)}, "dataset": ${JSON.stringify(astroidIncidentEventsDataset(config))} }],`);
         p("  // Workers AI. Powers the editor's rewrite + SEO-suggest buttons and alt-text");
         p("  // generation on upload—all of which SHIP IN THE EDITOR DRAWER already and,");
         p("  // without this binding, were permanently invisible: their routes answer 503");

package/dist/project/scaffold.js

@@ -26,6 +26,7 @@
 import { generateAstroidCheckoutRoute, generateAstroidSquareCard, } from "../commerce/checkout-scaffold.js";
 import { generateCatalogMigrationSql } from "../commerce/mirror.js";
 import { generateAstroidVitalsBeacon } from "../analytics/index.js";
+import { ASTROID_INCIDENTS_MIGRATION } from "../incidents/names.js";
 import { generateAstroidActions } from "./actions.js";
 import { cwvBeaconScript } from "louise-toolkit/analytics";
 import { generateMapEmbedComponent, generateMapTileRoute } from "../map/scaffold.js";
@@ -186,6 +187,19 @@ export function generateAstroidScaffoldFiles(config) {
             migration: true,
         });
     }
+    // --- incident capture's tables -------------------------------------------
+    // For every shape: the generated worker counts failures into `incidents`
+    // and keeps dead letters in `dead_letters` (louise-toolkit ADR 0022). Written
+    // into an existing site by `astroid generate`, like the two above, and
+    // renumbered past the site's own migrations. Not when another app migrates
+    // this database (`deploy.migrations: false`); that app owns the tables.
+    if (config.deploy?.migrations !== false) {
+        files.push({
+            path: "migrations/0006_incidents.sql",
+            contents: ASTROID_INCIDENTS_MIGRATION,
+            migration: true,
+        });
+    }
     // --- the CWV beacon -------------------------------------------------------
     // A static file under public/, so it is same-origin and covered by
     // `script-src 'self'`—an inline script carrying generated content could not

package/dist/schema/generate.js

@@ -20,6 +20,23 @@ function catalogBuilders(catalog) {
         builders.push("real");
     return builders.sort();
 }
+/**
+ * The incident tables every shape re-exports (louise-toolkit ADR 0022): the
+ * worker counts failures into `incidents` and keeps dead-lettered messages in
+ * `dead_letters`, so an app owns both, even when it owns nothing else. Not when
+ * another app migrates its database (`deploy.migrations: false`): that app owns
+ * them, and drizzle-kit here must not write migrations for them.
+ */
+function incidentTables(config) {
+    return config.deploy?.migrations === false ? [] : INCIDENT_TABLES;
+}
+const INCIDENT_TABLES = [
+    "// Incident capture's tables (louise-toolkit ADR 0022): the generated worker",
+    "// counts failures into `incidents` and keeps dead-lettered queue messages in",
+    "// `dead_letters`.",
+    'export { deadLetters, incidents } from "louise-toolkit/incidents";',
+    "",
+];
 /**
  * The schema of an app with no editor (`editor: false`): no `pages`, no
  * versions, and no framework tables, because nothing here edits them. What's
@@ -50,6 +67,7 @@ function generateAppSchema(config) {
                 catalog,
             ]
             : [""]),
+        ...incidentTables(config),
         "// Site-owned tables, declared in src/schema.site.ts and re-exported here so",
         "// drizzle-kit and the worker see them. Empty until the app adds one.",
         'export * from "./schema.site.js";',
@@ -97,6 +115,7 @@ export function generateAstroidSchema(config) {
         ...(catalog ? [catalog] : []),
         `export { ${framework.join(", ")} };`,
         "",
+        ...incidentTables(config),
         "// Site-owned tables (the ones Astroid doesn't manage): a project declares",
         "// its own Drizzle tables in src/schema.site.ts and they're re-exported here",
         "// so drizzle-kit sees them and the generated worker can import them. The file",

package/dist/worker/generate.js

@@ -12,9 +12,10 @@
 // beforeChange hook, and pagesRoute (which takes no collection config) through
 // the `astroidPagesWriteHooks` spread, so both write paths enforce one contract.
 import { ASTROID_VITALS_BINDING, generateAstroidCwvQuery } from "../analytics/index.js";
+import { ASTROID_INCIDENT_EVENTS_BINDING, ASTROID_SENTRY_DSN_BINDING, ASTROID_VERSION_METADATA_BINDING, } from "../incidents/names.js";
 import { astroidEditorTable } from "../auth/index.js";
 import { astroidPortal } from "../portal/config.js";
-import { ASTROID_HEALTH_CRON, astroidCron, astroidUsesQueues } from "../queues/messages.js";
+import { ASTROID_HEALTH_CRON, astroidCron, astroidQueueNames, astroidUsesQueues, } from "../queues/messages.js";
 import { ASTROID_EDIT_SESSION_CLASS, ASTROID_REALTIME_BINDING, usesRealtime, } from "../realtime/scaffold.js";
 import { capturesInquiries } from "../schema/framework.js";
 import { astroidCspStyleSrc } from "../security/csp-origins.js";
@@ -208,6 +209,7 @@ export function generateAstroidWorker(config) {
     p('import { cwvSqlQuery, parseCwvRows, summarizeCwv, vitalsRoute } from "louise-toolkit/analytics";');
     if (inquiries)
         p('import { defineForm } from "louise-toolkit/forms";');
+    p(incidentsImport(queues));
     if (queues)
         p('import { processBatch } from "louise-toolkit/queues";');
     // Only when a route actually takes a runner—a project with no AI assists
@@ -230,6 +232,7 @@ export function generateAstroidWorker(config) {
         "setAstroidMediaBase",
         ...(inquiries ? ["sendInquiryMail"] : []),
         ...(queues ? ["type AstroidQueueMessage"] : []),
+        ...(config.incidents?.sentry ? ["sentryIncidents", "type SecretSource"] : []),
     ].sort();
     p(`import { ${astroidImports.join(", ")} } from "astroidjs";`);
     // The config lives at the PROJECT ROOT (create-astroid writes it there); this
@@ -475,6 +478,7 @@ export function generateAstroidWorker(config) {
     p("  return new Response(obj.body, { headers });");
     p("};");
     p();
+    emitIncidentPreamble(p, config, queues);
     // The queue message type parameter is what gives the `queue` consumer below a
     // typed `MessageBatch` instead of `MessageBatch<unknown>`.
     p(queues
@@ -510,13 +514,9 @@ export function generateAstroidWorker(config) {
     p("    // An editor never reads from, and never writes to, the shared entry.");
     p("    bypass: isEditRequest,");
     p("  }),");
-    if (queues) {
-        p("  // Queue consumer. `processBatch` acks or retries each message");
-        p("  // INDEPENDENTLY, so one poisoned message can't block the rest of the");
-        p("  // batch from acking; Cloudflare routes it to the DLQ once it exceeds");
-        p("  // max_retries (see wrangler.jsonc).");
-        p("  queue: (batch, env) => processBatch(batch, (message) => handleQueueMessage(env, message)),");
-    }
+    emitIncidentOption(p, config);
+    if (queues)
+        emitQueueOption(p, config);
     // ONE scheduled handler for every cron, dispatching on `controller.cron`.
     // Cloudflare gives no other way to tell them apart, and the strings here have
     // to match `astroidCrons` exactly—which is why both read the same constants
@@ -589,11 +589,20 @@ function generateAppWorker(config) {
     p("// so it serves no editor routes and resolves no editor session.");
     p('import { handle } from "@astrojs/cloudflare/handler";');
     p('import { d1Check, statusRoute } from "louise-toolkit/editor";');
+    p(incidentsImport(queues));
     if (queues)
         p('import { processBatch } from "louise-toolkit/queues";');
     p('import { composeWorker, type WorkerRoute, withEdgeCache } from "louise-toolkit/worker";');
-    if (queues)
-        p('import type { AstroidQueueMessage } from "astroidjs";');
+    const astroidImports = [
+        ...(queues ? ["type AstroidQueueMessage"] : []),
+        ...(config.incidents?.sentry ? ["sentryIncidents", "type SecretSource"] : []),
+    ].sort();
+    if (astroidImports.length > 0) {
+        const typeOnly = astroidImports.every((name) => name.startsWith("type "));
+        p(typeOnly
+            ? `import type { ${astroidImports.map((name) => name.slice(5)).join(", ")} } from "astroidjs";`
+            : `import { ${astroidImports.join(", ")} } from "astroidjs";`);
+    }
     if (config.status?.checks) {
         p("// Your STATUS seam: the app's own checks for the public status route.");
         p("// Scaffolded once and yours to edit.");
@@ -627,6 +636,7 @@ function generateAppWorker(config) {
     p("  statusRoute({ checks: STATUS_CHECKS, reuseMs: STATUS_REUSE_MS }),");
     p("];");
     p();
+    emitIncidentPreamble(p, config, queues);
     p(queues
         ? "export default composeWorker<CloudflareEnv, AstroidQueueMessage>({"
         : "export default composeWorker<CloudflareEnv>({");
@@ -640,12 +650,9 @@ function generateAppWorker(config) {
     p("  // directive from every other one, so Cloudflare's cookie-blind edge cache");
     p("  // never stores a signed-in customer's page.");
     p("  fetch: withEdgeCache((request, env, ctx) => handle(request, env, ctx)),");
-    if (queues) {
-        p("  // Queue consumer. `processBatch` acks or retries each message");
-        p("  // INDEPENDENTLY, so one poisoned message can't block the rest of the");
-        p("  // batch; Cloudflare routes it to the DLQ once it exceeds max_retries.");
-        p("  queue: (batch, env) => processBatch(batch, (message) => handleQueueMessage(env, message)),");
-    }
+    emitIncidentOption(p, config);
+    if (queues)
+        emitQueueOption(p, config);
     if (scheduled) {
         p("  // Cron. Cloudflare fires this for EVERY trigger in wrangler.jsonc and");
         p("  // identifies which by `controller.cron`, so dispatch on it.");
@@ -897,3 +904,78 @@ export function generateAstroidMiddleware(config) {
         "",
     ].join("\n");
 }
+/** The `louise-toolkit/incidents` import both worker shapes emit. */
+function incidentsImport(queues) {
+    const names = ["analyticsIncidents", "d1Incidents", ...(queues ? ["deadLetterConsumer"] : [])];
+    return `import { ${names.join(", ")} } from "louise-toolkit/incidents";`;
+}
+/**
+ * The declarations incident capture needs ahead of `composeWorker`, shared by
+ * both shapes (louise-toolkit ADR 0022). Its bindings are read through a local
+ * type rather than `CloudflareEnv`, because `src/env.d.ts` is scaffold-once: a
+ * site made before them still type-checks, and each sink skips what isn't bound.
+ */
+function emitIncidentPreamble(p, config, queues) {
+    p("// --- incidents --------------------------------------------------------------");
+    p("// Every failure this worker sees becomes an incident: counted into the site's");
+    p("// own D1 (the `incidents` table), and into Analytics Engine for counts over");
+    p("// time (louise-toolkit ADR 0022). These bindings are optional. A site whose");
+    p("// wrangler.jsonc predates them still type-checks, and a sink skips what isn't");
+    p("// bound.");
+    p("type IncidentBindings = {");
+    p(`  ${ASTROID_INCIDENT_EVENTS_BINDING}?: AnalyticsEngineDataset;`);
+    p(`  ${ASTROID_VERSION_METADATA_BINDING}?: WorkerVersionMetadata;`);
+    if (config.incidents?.sentry)
+        p(`  ${ASTROID_SENTRY_DSN_BINDING}?: SecretSource;`);
+    p("};");
+    p("const incidentBindings = (env: CloudflareEnv) => env as CloudflareEnv & IncidentBindings;");
+    if (queues) {
+        const { dlq } = astroidQueueNames(config);
+        p("// The dead-letter queue's consumer: it keeps each message the queue gave up on");
+        p("// in the `dead_letters` table, counts it as an incident, and acks it, so a");
+        p("// failed webhook event is never lost unseen.");
+        p(`const DEAD_LETTER_QUEUE = ${JSON.stringify(dlq)};`);
+        p("const keepDeadLetters = deadLetterConsumer<CloudflareEnv, AstroidQueueMessage>(");
+        p("  (env) => env.DB,");
+        p(");");
+    }
+    p();
+}
+/** The `onIncident` option both shapes pass `composeWorker`. */
+function emitIncidentOption(p, config) {
+    const critical = config.incidents?.critical ?? [];
+    p("  // Incident capture (louise-toolkit ADR 0022). A throw is reported, then");
+    p("  // re-thrown, so responses don't change; the sinks run after the response.");
+    p("  onIncident: {");
+    p("    sinks: [");
+    p("      // The record: one row per failure, with a count, in the site's own D1.");
+    p("      d1Incidents((env: CloudflareEnv) => env.DB),");
+    p(`      analyticsIncidents((env: CloudflareEnv) => incidentBindings(env).${ASTROID_INCIDENT_EVENTS_BINDING}),`);
+    if (config.incidents?.sentry) {
+        p("      // A copy for the operator's issue system, with the stack. Dormant until");
+        p(`      // the ${ASTROID_SENTRY_DSN_BINDING} secret holds a real DSN.`);
+        p(`      sentryIncidents((env: CloudflareEnv) => incidentBindings(env).${ASTROID_SENTRY_DSN_BINDING}, { site: ${JSON.stringify(config.key)} }),`);
+    }
+    p("    ],");
+    if (critical.length > 0) {
+        p("    // What alerts, from `incidents.critical` in your config.");
+        p(`    critical: ${JSON.stringify(critical)},`);
+    }
+    p(`    release: (env) => incidentBindings(env).${ASTROID_VERSION_METADATA_BINDING}?.id,`);
+    p("  },");
+}
+/** The queue consumer both shapes emit: the dead-letter queue's batches to its
+ *  consumer, and the rest through `processBatch`, which reports a message's
+ *  last failed delivery as an incident. */
+function emitQueueOption(p, config) {
+    p("  // Queue consumer. `processBatch` acks or retries each message");
+    p("  // INDEPENDENTLY, so one poisoned message can't block the rest of the");
+    p("  // batch; Cloudflare routes it to the DLQ once it exceeds max_retries,");
+    p("  // which `maxRetries` matches, so its last failure counts as an incident.");
+    p("  queue: (batch, env, ctx) =>");
+    p("    batch.queue === DEAD_LETTER_QUEUE");
+    p("      ? keepDeadLetters(batch, env, ctx)");
+    p("      : processBatch(batch, (message) => handleQueueMessage(env, message), {");
+    p(`          maxRetries: ${config.queues?.maxRetries ?? 5},`);
+    p("        }),");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astroidjs",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Astroid — an opinionated meta-framework over Louise Toolkit and Astro for building editable, multi-editor sites on Cloudflare Workers.",
   "keywords": [
     "astro",
@@ -37,6 +37,11 @@
       "import": "./dist/astro/index.js",
       "default": "./dist/astro/index.js"
     },
+    "./pages": {
+      "types": "./dist/pages/index.d.ts",
+      "import": "./dist/pages/index.js",
+      "default": "./dist/pages/index.js"
+    },
     "./components/*.astro": "./src/components/*.astro",
     "./components/Collection": {
       "types": "./src/components/Collection.tsx",
@@ -64,6 +69,7 @@
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@vitest/coverage-v8": "4.1.11",
     "astro": "^7.2.9",
+    "drizzle-orm": "^0.45.2",
     "louise-toolkit": "^0.37.0",
     "solid-js": "^1.9.15",
     "typescript": "^6.0.3",
@@ -71,6 +77,7 @@
   },
   "peerDependencies": {
     "astro": "^7.0.9",
+    "drizzle-orm": "^0.45.0",
     "louise-toolkit": "^0.37.0",
     "solid-js": "^1.9.0"
   },