astroidjs 0.6.0 → 0.7.1

package/dist/queues/consumer.d.ts

@@ -4,10 +4,30 @@ export interface QueueHandlerOptions {
      * Re-sync whatever the provider owns — the catalog mirror, a cache. Called
      * for a periodic refresh and for webhooks that touched the catalog.
      *
+     * Receives the message that triggered it, so a site running more than one
+     * commerce provider can branch on `message.provider` rather than refreshing
+     * everything for everything. A zero-argument seam stays valid — the parameter
+     * is there to be ignored until it's needed.
+     *
      * Throwing marks the message for retry, which is usually right: a failed
      * refresh means the site is serving stale data.
      */
-    refreshCatalog?: () => void | Promise<void>;
+    refreshCatalog?: (message: AstroidQueueMessage) => void | Promise<void>;
+    /**
+     * Which provider owns the catalog `refreshCatalog` re-syncs. Set it and only
+     * that provider's webhooks trigger a refresh; leave it unset and any
+     * catalog-affecting webhook does, which is correct for the single-provider
+     * case and is what every existing consumer gets.
+     *
+     * This exists because two providers is now a supported configuration, and the
+     * seam is provider-blind by construction: a site can run Fourthwall as its
+     * storefront and Square as its POS, at which point `refreshCatalog` means
+     * "re-pull Fourthwall" while Square emits `inventory.count.updated` on every
+     * single sale. Unscoped, a good Saturday becomes a sync storm against an
+     * unrelated provider's rate limit — and the periodic refresh is unaffected, so
+     * the site looks fine until the day it's busy.
+     */
+    catalogProvider?: string;
     /**
      * Anything else this project queues. Runs for every message, after the
      * catalog dispatch above, so a project can add its own kinds without

package/dist/queues/consumer.js

@@ -25,12 +25,15 @@ import { affectsCatalog } from "./messages.js";
  * ```
  */
 export function astroidQueueHandler(options = {}) {
+    const owns = (provider) => options.catalogProvider === undefined || provider === options.catalogProvider;
     return async (message) => {
         if (message.kind === "catalog_refresh") {
-            await options.refreshCatalog?.();
+            await options.refreshCatalog?.(message);
         }
-        else if (message.kind === "webhook" && affectsCatalog(message.provider, message.type)) {
-            await options.refreshCatalog?.();
+        else if (message.kind === "webhook" &&
+            owns(message.provider) &&
+            affectsCatalog(message.provider, message.type)) {
+            await options.refreshCatalog?.(message);
         }
         await options.onMessage?.(message);
     };

package/dist/queues/messages.js

@@ -44,6 +44,10 @@ export function astroidCrons(config) {
     const catalog = astroidCron(config);
     if (catalog)
         crons.push(catalog);
+    // Project-declared triggers last, so the two derived ones keep their existing
+    // positions and an added cron can't renumber anything.
+    for (const cron of config.crons ?? [])
+        crons.push(cron.expression);
     return crons;
 }
 /** Binding name for the project's queue producer. */

package/dist/queues/scaffold.js

@@ -92,6 +92,10 @@ export function generateAstroidQueueSeam(config) {
     // invoicing-only provider has nothing for this hook to do.
     const provider = astroidCommerceRoles(config.commerce).storefront;
     const table = astroidCatalogMirror(config).table;
+    // Two providers means the catalog belongs to exactly one of them, and the
+    // other one's webhooks must not drag it through a re-sync. Scaffold the scope
+    // in rather than leaving it to be discovered on a busy day (#294).
+    const multiProvider = astroidCommerceProviders(config.commerce).length > 1;
     return [
         "// The queue consumer — what each message actually does.",
         "//",
@@ -110,6 +114,15 @@ export function generateAstroidQueueSeam(config) {
         "  message: AstroidQueueMessage,",
         "): Promise<void> {",
         "  await astroidQueueHandler({",
+        ...(multiProvider && provider
+            ? [
+                `    // This project runs more than one commerce provider, and the catalog is`,
+                `    // ${provider}'s. Scoping the refresh keeps the OTHER provider's webhooks from`,
+                `    // triggering it — Square alone emits an inventory event on every sale, which`,
+                `    // unscoped would re-sync ${provider} once per transaction.`,
+                `    catalogProvider: ${JSON.stringify(provider)},`,
+            ]
+            : []),
         "    refreshCatalog: async () => {",
         provider
             ? `      // TODO: fetch the ${provider} catalog, normalize each item with`
@@ -122,6 +135,22 @@ export function generateAstroidQueueSeam(config) {
         `      //   const r = await astroidCatalogSync(items, { db: env.DB, table: ${JSON.stringify(table)} });`,
         '      //   if (r.failed > 0) console.warn("[catalog] skipped", r.failed, r.errors);',
         "      //",
+        // Nobody is watching a queue message, which flips the retry trade-off that
+        // an attended checkout route settles the other way.
+        ...(provider === "square"
+            ? [
+                "      // Nobody is watching this run, so let the client retry: SquareConfig",
+                "      // takes `retry: { attempts: 3 }`, backing off on 429/5xx inside every",
+                "      // verb. It is off by default because a checkout route has a customer",
+                "      // watching a spinner, and there a fast failure beats a slow one. Here",
+                "      // the opposite holds — a catalog push that gives up halfway is worse.",
+            ]
+            : [
+                "      // Nobody is watching this run, so ask for backoff on 429/5xx wherever",
+                "      // the client offers it. Attended paths are better off failing fast; a",
+                "      // catalog push that gives up halfway is not.",
+            ]),
+        "      //",
         "      // The sync is idempotent (keyed on the provider's id) and never",
         "      // writes an owner-edited column, so it's safe to run on every event.",
         "      //",

package/dist/schema/collections.js

@@ -12,10 +12,15 @@
 // create-astroid's schema generators, which call this function but never run the
 // beforeChange hook below). Both entries are drizzle-free: `content/define` for
 // the config types/builders, and `content/sections` for the write-time section
-// validators. That second entry is what the Rule-evaluator split
-// (louise-toolkit/src/core/content/rule.ts) added, so this hook can import the
-// validators STATICALLY instead of the dynamic `import("louise-toolkit/content")`
-// it used to need to keep the CLI's graph drizzle-free.
+// validators. That second entry is what the Rule-evaluator split added, so this
+// hook can import the validators STATICALLY instead of the dynamic
+// `import("louise-toolkit/content")` it used to need to keep the CLI's graph
+// drizzle-free.
+//
+// Note the entry named here is the PUBLIC subpath. Astroid must never reach into
+// `louise-toolkit/src/...` — that resolves only because the workspace aliases the
+// package to its source, and would break the moment astroid consumes a published
+// tarball (#327).
 import { defineCollection, } from "louise-toolkit/content/define";
 import { assertValidSections, sanitizeSectionsRichText } from "louise-toolkit/content/sections";
 import { sanitizeRichHtml } from "louise-toolkit/security";

package/dist/tenancy/index.d.ts

@@ -0,0 +1,35 @@
+import type { AstroidConfig, TenancyConfig } from "../config.js";
+/** Default internal prefix a tenant request is rewritten to. */
+export declare const ASTROID_TENANT_PREFIX = "/t";
+/**
+ * The Cloudflare zone a wildcard pattern belongs to.
+ *
+ * Defaults to the pattern minus its leading `*.`, which is right whenever the
+ * wildcard sits directly under the apex. A deeper pattern needs `zone` set
+ * explicitly: `*.shop.example.com` is served by the `example.com` zone, and
+ * guessing `shop.example.com` there produces a deploy error naming a zone that
+ * does not exist.
+ */
+export declare function tenancyZone(tenancy: TenancyConfig): string;
+/**
+ * The subdomain label for a host under the wildcard, or `null` when the host is
+ * not a tenant candidate at all.
+ *
+ * `null` covers three distinct cases that all mean "render the ordinary site":
+ * the apex itself (a wildcard does not match its own apex), a host outside the
+ * pattern (a preview domain, `localhost`), and a reserved label.
+ *
+ * Exported and pure so a site can unit-test its own reserved list without
+ * standing up a request.
+ */
+export declare function tenantLabel(host: string, tenancy: TenancyConfig): string | null;
+/**
+ * The scaffold-once `src/tenancy.ts` — the seam holding every decision Astroid
+ * refuses to make for a site.
+ *
+ * Written once and then yours: what a label resolves to, whether the lookup is
+ * cached, and what an unknown label means are all questions with site-specific
+ * answers, and a framework that guessed them would be wrong in a different way
+ * for each project.
+ */
+export declare function generateAstroidTenancy(config: AstroidConfig): string | null;

package/dist/tenancy/index.js

@@ -0,0 +1,101 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Wildcard host dispatch: the parts that are the same for every site, and
+// nothing that decides anything.
+//
+// Astroid owns two things a site cannot own on its own — the wildcard Worker
+// route (`hosts` can only express custom domains) and the single middleware file
+// Astro permits. What a subdomain MEANS, whether the lookup is cached, and what
+// an unknown host should do are all site policy, and live in the scaffolded
+// `src/tenancy.ts`.
+/** Default internal prefix a tenant request is rewritten to. */
+export const ASTROID_TENANT_PREFIX = "/t";
+/**
+ * The Cloudflare zone a wildcard pattern belongs to.
+ *
+ * Defaults to the pattern minus its leading `*.`, which is right whenever the
+ * wildcard sits directly under the apex. A deeper pattern needs `zone` set
+ * explicitly: `*.shop.example.com` is served by the `example.com` zone, and
+ * guessing `shop.example.com` there produces a deploy error naming a zone that
+ * does not exist.
+ */
+export function tenancyZone(tenancy) {
+    return tenancy.zone ?? tenancy.hostPattern.replace(/^\*\./, "");
+}
+/**
+ * The subdomain label for a host under the wildcard, or `null` when the host is
+ * not a tenant candidate at all.
+ *
+ * `null` covers three distinct cases that all mean "render the ordinary site":
+ * the apex itself (a wildcard does not match its own apex), a host outside the
+ * pattern (a preview domain, `localhost`), and a reserved label.
+ *
+ * Exported and pure so a site can unit-test its own reserved list without
+ * standing up a request.
+ */
+export function tenantLabel(host, tenancy) {
+    const suffix = tenancy.hostPattern.replace(/^\*\./, "");
+    // Strip a port: `acme.example.com:8788` under `wrangler dev`.
+    const hostname = host.split(":")[0]?.toLowerCase() ?? "";
+    if (!hostname.endsWith(`.${suffix}`))
+        return null;
+    const label = hostname.slice(0, -(suffix.length + 1));
+    // Only a single label is a tenant. `a.b.example.com` under `*.example.com` is
+    // not `a.b` — Cloudflare's wildcard matches one level, and treating a dotted
+    // string as a slug would put a `/` in a rewrite path.
+    if (!label || label.includes("."))
+        return null;
+    const reserved = tenancy.reserved ?? [];
+    return reserved.includes(label) ? null : label;
+}
+/**
+ * The scaffold-once `src/tenancy.ts` — the seam holding every decision Astroid
+ * refuses to make for a site.
+ *
+ * Written once and then yours: what a label resolves to, whether the lookup is
+ * cached, and what an unknown label means are all questions with site-specific
+ * answers, and a framework that guessed them would be wrong in a different way
+ * for each project.
+ */
+export function generateAstroidTenancy(config) {
+    const tenancy = config.tenancy;
+    if (!tenancy)
+        return null;
+    const prefix = tenancy.rewritePrefix ?? ASTROID_TENANT_PREFIX;
+    const example = (tenancy.hostPattern ?? "*.example.com").replace(/^\*\./, "");
+    return [
+        "// Scaffolded once by astroidjs — yours to edit.",
+        "//",
+        "// What a subdomain MEANS. The generated middleware has already decided this",
+        "// host is a tenant candidate (it matches your wildcard and is not reserved);",
+        "// everything after that is your call.",
+        "//",
+        `// A match rewrites internally to \`${prefix}/<slug>/…\`, so put the pages under`,
+        `// \`src/pages${prefix}/[tenant]/\`. The visitor's URL never changes.`,
+        "",
+        "/** What your pages read off `Astro.locals.tenant`. Widen it freely. */",
+        "export interface Tenant {",
+        "  /** Used to build the internal path, so keep it URL-safe. */",
+        "  slug: string;",
+        "}",
+        "",
+        "/**",
+        " * Resolve a subdomain label to a tenant, or `null` if there isn't one.",
+        " *",
+        " * `null` falls through to the ordinary site — which is a real choice, not a",
+        " * default: a stranger's subdomain then renders your homepage. If that is wrong",
+        " * for this project, return null here and refuse it in the middleware's `guard`",
+        " * with a 404, so an unknown host is unambiguously not a page.",
+        " *",
+        " * This runs on EVERY request to a tenant host, so a database lookup here is a",
+        " * query per request. Cache it — a module-scope Map is enough within an isolate,",
+        " * KV if the tenant set is large or changes without a deploy.",
+        " */",
+        "export async function resolveTenant(label: string): Promise<Tenant | null> {",
+        `  // TODO(astroid): look \`label\` up — a D1 table, a KV entry, or a literal map`,
+        `  // while the set is small. Example: acme.${example} → { slug: "acme" }.`,
+        "  return { slug: label };",
+        "}",
+        "",
+    ].join("\n");
+}

package/dist/worker/generate.js

@@ -17,6 +17,7 @@ import { astroidPortal } from "../portal/config.js";
 import { ASTROID_HEALTH_CRON, astroidCron, 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 { ASTROID_TENANT_PREFIX } from "../tenancy/index.js";
 import { astroidEditorRoutePlan } from "./routes.js";
 // Astroid's default editable site_settings surface — the columns the Settings
 // panel may write, and which of them hold a media-library image URL.
@@ -62,6 +63,8 @@ export function generateAstroidWorker(config) {
     // scaffold, which is exactly how it got caught.
     // Same trap as realtimeRoute: these live outside `louise-toolkit/editor`.
     const realtimeRouteFactories = new Set(["realtimeRoute", "vitalsRoute"]);
+    // The routes that take an AI runner, and so need `aiRunner` imported.
+    const AI_ROUTES = new Set(["ai", "seoFix", "media"]);
     const editorImports = [
         "DEFAULT_PAGE_FIELDS",
         ...new Set(plan.map((route) => route.factory).filter((f) => !realtimeRouteFactories.has(f))),
@@ -112,15 +115,19 @@ export function generateAstroidWorker(config) {
                     : "";
                 return `settingsRoute({ table: siteSettings, resolveEditor, columns: SETTINGS_COLUMNS, imageKeys: SETTINGS_IMAGE_KEYS, mediaBase: MEDIA_BASE${customArg} })`;
             }
+            // `aiRunner` rather than `(env) => env.AI`: it reads the binding AND the
+            // LOUISE_AI kill switch, so all three assists share one definition of
+            // "is generation on?" instead of each re-deriving it. Embeddings keep
+            // binding-presence as their switch — see the helper's comment.
             case "ai":
-                return "aiRoute({ resolveEditor, ai: (env) => env.AI })";
+                return "aiRoute({ resolveEditor, ai: aiRunner })";
             case "seoFix":
-                return "seoFixRoute({ table: pages, resolveEditor, ai: (env) => env.AI })";
+                return "seoFixRoute({ table: pages, resolveEditor, ai: aiRunner })";
             case "media":
                 // `altText` fills a new upload's alt from the image itself. Best-effort
                 // by contract — a model error or a missing binding never fails the
                 // upload — so it costs nothing on a project that doesn't want it.
-                return "mediaRoute({ table: media, resolveEditor, referenceSources: MEDIA_REFERENCE_SOURCES, altText: (env) => env.AI })";
+                return "mediaRoute({ table: media, resolveEditor, referenceSources: MEDIA_REFERENCE_SOURCES, altText: aiRunner })";
             case "editors":
                 // The editor instance's user table is `louise_`-prefixed (the editor
                 // convention — the unprefixed `user` table is left for a second/portal
@@ -159,6 +166,11 @@ export function generateAstroidWorker(config) {
         p('import { defineForm } from "louise-toolkit/forms";');
     if (queues)
         p('import { processBatch } from "louise-toolkit/queues";');
+    // Only when a route actually takes a runner — a project with no AI assists
+    // should not import one, and knip would flag it if it did.
+    if (plan.some((route) => AI_ROUTES.has(route.name))) {
+        p('import { aiRunner } from "louise-toolkit/ai";');
+    }
     p('import { checkLinks } from "louise-toolkit/browser";');
     p('import { readHealthSummary, summarizeHealth, writeHealthSummary } from "louise-toolkit/health";');
     p('import { composeWorker, isEditRequest, type WorkerRoute, withEdgeCache } from "louise-toolkit/worker";');
@@ -393,6 +405,17 @@ export function generateAstroidWorker(config) {
         p("      // serves stale data until a human notices. Enqueued rather than run");
         p("      // inline so it takes the same retry + DLQ path as everything else.");
         p('      ctx.waitUntil(env.COMMERCE_QUEUE.send({ kind: "catalog_refresh" }));');
+        p("      return;");
+        p("    }");
+    }
+    // Project-declared crons (`config.crons`). Emitted from the same list that
+    // feeds `triggers.crons`, so a trigger can't exist with no branch to match it.
+    for (const custom of config.crons ?? []) {
+        p(`    if (controller.cron === ${JSON.stringify(custom.expression)}) {`);
+        p("      // Enqueued, not run inline: same retry + DLQ path as everything");
+        p("      // else, and a slow job can't hold the scheduled handler open.");
+        p(`      ctx.waitUntil(env.COMMERCE_QUEUE.send(${JSON.stringify(custom.message)}));`);
+        p("      return;");
         p("    }");
     }
     p("  },");
@@ -437,6 +460,8 @@ export function generateAstroidMiddleware(config) {
     // inlined @font-face needs no manual `font-src` entry.
     const cspStyleSrc = "'self' 'unsafe-inline'";
     const portal = astroidPortal(config);
+    const tenancy = config.tenancy;
+    const rewritePrefix = tenancy?.rewritePrefix ?? ASTROID_TENANT_PREFIX;
     return [
         "// Generated by astroidjs — do not hand-edit.",
         "// The shared Louise middleware: rate-limit the unauthenticated POST surfaces,",
@@ -446,10 +471,22 @@ export function generateAstroidMiddleware(config) {
         "// styles + inlined data: brand font are allowed.",
         'import { env } from "cloudflare:workers";',
         'import { createLouiseMiddleware } from "louise-toolkit/astro";',
-        portal
-            ? 'import { astroidPortalGuardConfig, astroidRateRules, guardResponse, portalGuard, resolvePortalSession } from "astroidjs";'
-            : 'import { astroidRateRules } from "astroidjs";',
+        // One `astroidjs` import, composed from what this config actually uses —
+        // two import statements for the same module is legal and reads as an
+        // oversight in a file nobody is supposed to hand-edit.
+        `import { ${[
+            ...(portal ? ["astroidPortalGuardConfig"] : []),
+            "astroidRateRules",
+            ...(portal ? ["guardResponse", "portalGuard", "resolvePortalSession"] : []),
+            ...(tenancy ? ["tenantLabel"] : []),
+        ].join(", ")} } from "astroidjs";`,
         'import astroidConfig from "../astroid.config.js";',
+        ...(tenancy
+            ? [
+                "// TODO(astroid): your TENANT seam — what a subdomain maps to (src/tenancy.ts).",
+                'import { resolveTenant } from "./tenancy.js";',
+            ]
+            : []),
         "// TODO(astroid): your AUTH seam — same resolveEditor as the generated worker.ts.",
         'import { resolveEditor } from "./auth.js";',
         // The portal's resolver lives in its OWN module, not the editor's auth
@@ -464,6 +501,14 @@ export function generateAstroidMiddleware(config) {
         "// `env.RL` is read per request (a getter) — a KV binding is only valid in",
         "// request scope.",
         "const RATE_RULES = astroidRateRules(astroidConfig);",
+        ...(tenancy
+            ? [
+                "",
+                "// Read from the config rather than restated here, so the reserved list and",
+                "// the wildcard pattern can't drift from the Worker route generated for them.",
+                "const TENANCY = astroidConfig.tenancy!;",
+            ]
+            : []),
         ...(portal
             ? [
                 "const PORTAL_GUARD = astroidPortalGuardConfig(astroidConfig)!;",
@@ -478,12 +523,31 @@ export function generateAstroidMiddleware(config) {
         "export const onRequest = createLouiseMiddleware({",
         "  resolveEditor: (request) => resolveEditor(request),",
         "  rateLimit: { rules: RATE_RULES, kv: () => env.RL },",
-        ...(portal
+        // `extend` runs once and may need to populate BOTH — a tenanted site with a
+        // portal resolves a tenant and a customer on the same request.
+        ...(portal || tenancy
             ? [
                 "  extend: async (context) => {",
-                "    const user = await resolvePortalSession(context.request, resolvePortalUser);",
-                "    context.locals.portalUser = user;",
+                ...(portal
+                    ? [
+                        "    const user = await resolvePortalSession(context.request, resolvePortalUser);",
+                        "    context.locals.portalUser = user;",
+                    ]
+                    : []),
+                ...(tenancy
+                    ? [
+                        "    // The label, or null for the apex / a reserved label / an off-pattern",
+                        "    // host. `resolveTenant` is yours (src/tenancy.ts): it decides what a",
+                        "    // label maps to and whether that lookup is cached.",
+                        "    const label = tenantLabel(context.url.hostname, TENANCY);",
+                        "    context.locals.tenant = label ? await resolveTenant(label) : null;",
+                    ]
+                    : []),
                 "  },",
+            ]
+            : []),
+        ...(portal
+            ? [
                 "  // Route guard: the declarative prefix→roles table from your config.",
                 "  // An /api/* route always answers in JSON — redirecting fetch() to an",
                 "  // HTML login page returns 200 and markup, which reads as success.",
@@ -499,6 +563,22 @@ export function generateAstroidMiddleware(config) {
                 "  },",
             ]
             : []),
+        ...(tenancy
+            ? [
+                "  // Host dispatch: map the resolved tenant onto an internal path prefix.",
+                "  // Runs after `guard`, so route policy stays written against the PUBLIC",
+                "  // path. The visitor's URL is unchanged — an internal rewrite, not a",
+                "  // redirect — so links built from Astro.url stay correct.",
+                "  //",
+                "  // An unknown subdomain is YOUR decision: `resolveTenant` returning null",
+                "  // falls through to the ordinary site below. Return a 404 from `guard`",
+                "  // instead if a stranger's subdomain should not render your homepage.",
+                "  rewrite: (context) => {",
+                "    const tenant = context.locals.tenant;",
+                `    return tenant ? \`${rewritePrefix}/\${tenant.slug}\${context.url.pathname}\` : undefined;`,
+                "  },",
+            ]
+            : []),
         "  // Rewrite Astro's hash-based style-src (owned by astroidSecurity in",
         '  // astro.config.mjs) to permit Louise\'s data-driven style="" + editor styles.',
         `  cspStyleSrc: ${JSON.stringify(cspStyleSrc)},`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astroidjs",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Astroid — an opinionated meta-framework over Louise Toolkit and Astro for building editable, multi-editor sites on Cloudflare Workers.",
   "keywords": [
     "astro",
@@ -60,19 +60,24 @@
     "access": "public"
   },
   "dependencies": {
-    "louise-toolkit": "0.22.0"
+    "louise-toolkit": "0.24.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "astro": "^7.0.9",
     "solid-js": "^1.9.14",
     "typescript": "^5.8.0",
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
+    "astro": "^7.0.9",
     "solid-js": "^1.9.0"
   },
   "peerDependenciesMeta": {
+    "astro": {
+      "optional": true
+    },
     "solid-js": {
       "optional": true
     }