astroidjs 0.1.1 → 0.2.0

package/dist/seo/routes.js

@@ -0,0 +1,104 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// `robots.txt` + `sitemap.xml` builders.
+//
+// Both are ORIGIN-AWARE rather than built against a configured `site` URL, and
+// that's deliberate: a project serves from several hosts (`*.workers.dev`, a
+// preview subdomain, the custom domain), and a sitemap that advertises the
+// canonical host from a preview deploy invites the preview's content to be
+// indexed under the real domain. Deriving the origin from the request means each
+// host describes only itself.
+//
+// The disallow list is derived from the config for the same reason the rate
+// rules are: which routes exist is a function of which modules are enabled, and
+// a hand-maintained list drifts the moment someone turns a portal on.
+import { ASTROID_PORTAL_BASE_PATH } from "../security/rate-rules.js";
+/**
+ * Paths that must never be indexed, derived from the config: the editor and its
+ * API always, plus the portal's account + auth surfaces and checkout when those
+ * are enabled.
+ *
+ * These are *prefixes* — `robots.txt` matches by prefix, so `/api/` covers every
+ * endpoint beneath it.
+ */
+export function astroidNoindexPaths(config) {
+    const paths = [
+        // Every worker route (editor CRUD, media, forms) and Better Auth.
+        "/api/",
+        // The editor entry point.
+        "/louise",
+    ];
+    if (config.portal?.enabled) {
+        paths.push(ASTROID_PORTAL_BASE_PATH, "/account", "/login", "/register", "/reset-password");
+    }
+    if (config.commerce) {
+        // The checkout PAGE, not `ASTROID_CHECKOUT_PATH` — that's the POST endpoint,
+        // already covered by the `/api/` prefix. What a crawler would actually reach
+        // is the UI route.
+        paths.push("/checkout", "/cart");
+    }
+    return [...new Set(paths)].sort();
+}
+/** Render `robots.txt`, pointing at the sitemap on the SAME origin. */
+export function astroidRobotsTxt(config, options) {
+    const origin = options.origin.replace(/\/$/, "");
+    if (options.disableIndexing) {
+        return ["User-agent: *", "Disallow: /", ""].join("\n");
+    }
+    const disallow = options.disallow ?? astroidNoindexPaths(config);
+    return [
+        "User-agent: *",
+        "Allow: /",
+        ...disallow.map((path) => `Disallow: ${path}`),
+        "",
+        `Sitemap: ${origin}/sitemap.xml`,
+        "",
+    ].join("\n");
+}
+const XML_ESCAPES = {
+    "&": "&",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&apos;",
+};
+const escapeXml = (value) => value.replace(/[&<>"']/g, (c) => XML_ESCAPES[c] ?? c);
+/**
+ * Render `sitemap.xml` from a set of paths.
+ *
+ * Entries are de-duplicated and sorted (a stable document diffs cleanly and
+ * caches predictably), excluded paths are dropped by prefix, and every `loc` is
+ * XML-escaped — a slug containing `&` would otherwise produce a malformed
+ * document that search engines reject wholesale.
+ */
+export function astroidSitemapXml(config, entries, options) {
+    const origin = options.origin.replace(/\/$/, "");
+    const exclude = options.exclude ?? astroidNoindexPaths(config);
+    const seen = new Map();
+    for (const raw of entries) {
+        const entry = typeof raw === "string" ? { path: raw } : raw;
+        const path = entry.path.startsWith("/") ? entry.path : `/${entry.path}`;
+        if (exclude.some((prefix) => path.startsWith(prefix)))
+            continue;
+        if (!seen.has(path))
+            seen.set(path, { ...entry, path });
+    }
+    const urls = [...seen.values()]
+        .sort((a, b) => a.path.localeCompare(b.path))
+        .map((entry) => {
+        const lastmod = entry.lastmod instanceof Date
+            ? entry.lastmod.toISOString()
+            : typeof entry.lastmod === "string"
+                ? entry.lastmod
+                : undefined;
+        const loc = `<loc>${escapeXml(`${origin}${entry.path}`)}</loc>`;
+        return `  <url>${loc}${lastmod ? `<lastmod>${escapeXml(lastmod)}</lastmod>` : ""}</url>`;
+    });
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+        ...urls,
+        "</urlset>",
+        "",
+    ].join("\n");
+}

package/dist/seo/structured-data.d.ts

@@ -0,0 +1,51 @@
+import type { Archetype, AstroidConfig } from "../config.js";
+import type { AstroidSeoSettings } from "./resolve.js";
+/** JSON-LD is a plain JSON tree; this is as much typing as it deserves. */
+export type JsonLdNode = Record<string, unknown>;
+/**
+ * The schema.org `@type` each archetype describes its owner with. These are
+ * intentionally the broad parent types: pick a subtype (`CafeOrCoffeeShop`,
+ * `ArtGallery`, `HomeAndConstructionBusiness`) via `seo.businessType` when you
+ * know one — a more specific type is strictly better for rich results.
+ */
+export declare const ARCHETYPE_BUSINESS_TYPE: Record<Archetype, string>;
+export interface StructuredDataInput {
+    config: AstroidConfig;
+    settings: AstroidSeoSettings & {
+        logoUrl?: string | null;
+        contactEmail?: string | null;
+        contactPhone?: string | null;
+        contactAddress?: string | null;
+        /** Profile URLs, as stored in `site_settings.social_links`. */
+        socialLinks?: unknown;
+    };
+    /** Absolute origin serving this page (the canonical host). */
+    siteUrl: string;
+    /**
+     * An extra node for the thing this page is *about* — a Product, a
+     * VisualArtwork, an Article. Joined into the same `@graph` so crawlers see
+     * one connected description rather than three unrelated blobs.
+     */
+    entity?: JsonLdNode;
+}
+/**
+ * Build the JSON-LD `@graph` for a page: the business node, a `WebSite` node,
+ * and the page's own entity when there is one.
+ *
+ * The business gets a stable `@id` (`<origin>/#business`) so other nodes — a
+ * product's `seller`, a future `Article` author — can reference it by id
+ * instead of restating it.
+ */
+export declare function astroidStructuredData(input: StructuredDataInput): JsonLdNode;
+/**
+ * Serialize JSON-LD for injection into a `<script type="application/ld+json">`.
+ *
+ * `application/ld+json` is data, not executable script, so `script-src` doesn't
+ * govern it and no CSP hash is needed. But `JSON.stringify` does **not** escape
+ * `<`, so any value folded into the graph that contains a literal `</script>` —
+ * a product description, an artist statement, anything editor-authored — would
+ * close the tag early and inject markup straight into `<head>`. Escaping the
+ * HTML-significant characters as `\uXXXX` keeps the payload valid JSON while
+ * making it impossible to break out of the element.
+ */
+export declare function escapeJsonLd(value: unknown): string;

package/dist/seo/structured-data.js

@@ -0,0 +1,105 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// JSON-LD structured data — the `@graph` that describes the business to rich
+// results and AI answer surfaces.
+//
+// Everything here is generic except the business `@type`, which is the one thing
+// that genuinely differs per site — so it comes from the archetype, with a
+// config escape hatch for the many cases where schema.org has a more specific
+// subtype (a coffee shop is a `CafeOrCoffeeShop`, not a bare `Store`).
+/**
+ * The schema.org `@type` each archetype describes its owner with. These are
+ * intentionally the broad parent types: pick a subtype (`CafeOrCoffeeShop`,
+ * `ArtGallery`, `HomeAndConstructionBusiness`) via `seo.businessType` when you
+ * know one — a more specific type is strictly better for rich results.
+ */
+export const ARCHETYPE_BUSINESS_TYPE = {
+    marketing: "Organization",
+    storefront: "Store",
+    wholesale: "Organization",
+    // A portfolio site is a person's body of work far more often than a company's.
+    portfolio: "Person",
+};
+/** Absolute URL, or undefined when the value is empty or unparseable. */
+function absolute(value, base) {
+    const raw = value?.trim();
+    if (!raw)
+        return undefined;
+    try {
+        return new URL(raw, base).toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Pull profile URLs out of `socialLinks`, which the editor stores as either a
+ *  `{ instagram: "…" }` map or a plain array. */
+function sameAs(links) {
+    const values = Array.isArray(links)
+        ? links
+        : links && typeof links === "object"
+            ? Object.values(links)
+            : [];
+    return values
+        .filter((v) => typeof v === "string")
+        .map((v) => v.trim())
+        .filter((v) => /^https?:\/\//.test(v));
+}
+/**
+ * Build the JSON-LD `@graph` for a page: the business node, a `WebSite` node,
+ * and the page's own entity when there is one.
+ *
+ * The business gets a stable `@id` (`<origin>/#business`) so other nodes — a
+ * product's `seller`, a future `Article` author — can reference it by id
+ * instead of restating it.
+ */
+export function astroidStructuredData(input) {
+    const { config, settings, siteUrl, entity } = input;
+    const origin = siteUrl.replace(/\/$/, "");
+    const businessId = `${origin}/#business`;
+    const name = settings.siteName?.trim() || config.theme.name;
+    const profiles = sameAs(settings.socialLinks);
+    const image = absolute(settings.defaultOgImageUrl, siteUrl) ?? absolute(settings.logoUrl, siteUrl);
+    const business = {
+        "@type": config.seo?.businessType ?? ARCHETYPE_BUSINESS_TYPE[config.archetype],
+        "@id": businessId,
+        name,
+        url: origin,
+        ...(settings.tagline?.trim() ? { description: settings.tagline.trim() } : {}),
+        ...(image ? { image, logo: image } : {}),
+        ...(settings.contactEmail?.trim() ? { email: settings.contactEmail.trim() } : {}),
+        ...(settings.contactPhone?.trim() ? { telephone: settings.contactPhone.trim() } : {}),
+        ...(settings.contactAddress?.trim()
+            ? { address: { "@type": "PostalAddress", streetAddress: settings.contactAddress.trim() } }
+            : {}),
+        ...(profiles.length ? { sameAs: profiles } : {}),
+    };
+    const website = {
+        "@type": "WebSite",
+        "@id": `${origin}/#website`,
+        url: origin,
+        name,
+        publisher: { "@id": businessId },
+    };
+    return {
+        "@context": "https://schema.org",
+        "@graph": entity ? [business, website, entity] : [business, website],
+    };
+}
+/**
+ * Serialize JSON-LD for injection into a `<script type="application/ld+json">`.
+ *
+ * `application/ld+json` is data, not executable script, so `script-src` doesn't
+ * govern it and no CSP hash is needed. But `JSON.stringify` does **not** escape
+ * `<`, so any value folded into the graph that contains a literal `</script>` —
+ * a product description, an artist statement, anything editor-authored — would
+ * close the tag early and inject markup straight into `<head>`. Escaping the
+ * HTML-significant characters as `\uXXXX` keeps the payload valid JSON while
+ * making it impossible to break out of the element.
+ */
+export function escapeJsonLd(value) {
+    return JSON.stringify(value)
+        .replace(/</g, "\\u003c")
+        .replace(/>/g, "\\u003e")
+        .replace(/&/g, "\\u0026");
+}

package/dist/status.d.ts

@@ -0,0 +1,51 @@
+import type { AstroidConfig } from "./config.js";
+import { type MailerEnv } from "./email/send.js";
+import type { SecretSource } from "./secrets.js";
+/**
+ * Secrets every Astroid site has, independent of which modules are on.
+ *
+ * `SESSION_SECRET` is here but is NOT a dormancy gate — it fails closed off
+ * localhost (see `getSessionSecret`), because an unsigned session isn't a
+ * feature to switch off. It's listed so the scaffold seeds and types it.
+ */
+export declare const ASTROID_CORE_SECRET_NAMES: readonly ["SESSION_SECRET", "TURNSTILE_SECRET", "TURNSTILE_SITE_KEY"];
+/** One module's line in the report. */
+export interface AstroidModuleReport {
+    /** Module name, as a developer would say it: `"commerce"`, `"email"`. */
+    module: string;
+    /** Whether the project switched this module on at all. */
+    enabled: boolean;
+    /** Whether it has everything it needs to run live. */
+    configured: boolean;
+    /** Unprovisioned secret/binding names, in declaration order. */
+    missing: string[];
+    /** What the module does in this state — the sentence a banner prints. */
+    detail: string;
+}
+/**
+ * Every secret name this config implies, grouped by module.
+ *
+ * The scaffold uses this twice: to seed `.dev.vars`/`.env.example` with the
+ * placeholder sentinel, and to type the matching `CloudflareEnv` members. A
+ * module that isn't enabled contributes nothing — a declaration is a promise,
+ * and a marketing site shouldn't be told to provision a Square token.
+ */
+export declare function astroidSecretNames(config: AstroidConfig): Record<string, string[]>;
+/** The env shape the status report reads. Structural; a real `env` fits. */
+export type AstroidStatusEnv = MailerEnv & Record<string, SecretSource | unknown>;
+/**
+ * Resolve every enabled module's gate.
+ *
+ * ```ts
+ * // src/pages/api/_astroid/status.ts, or a dev-only banner
+ * const report = await astroidModuleStatus(config, env);
+ * console.info(describeAstroidStatus(report));
+ * ```
+ */
+export declare function astroidModuleStatus(config: AstroidConfig, env: AstroidStatusEnv): Promise<AstroidModuleReport[]>;
+/**
+ * The report as a printable block. One line per module, missing names spelled
+ * out — "commerce is off" sends someone reading source; "commerce is dormant —
+ * set SQUARE_ACCESS_TOKEN" does not.
+ */
+export declare function describeAstroidStatus(reports: AstroidModuleReport[]): string;

package/dist/status.js

@@ -0,0 +1,113 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The module status report — "what is actually switched on right now".
+//
+// `secrets.ts` gives one module its gate. This composes every enabled module's
+// gate into one answer, which is what the dormant-until-provisioned convention
+// needs to be usable rather than merely available: a fresh scaffold boots with
+// nothing provisioned, and the failure mode that convention exists to avoid is
+// not a crash — it's a developer wondering for twenty minutes why the contact
+// form "works" but no mail arrives.
+//
+// So the deal is: dormant is fine, dormant AND SILENT is not. Two consumers of
+// this, both cheap:
+//
+//   • `astroid doctor` / a dev-server banner prints `describeAstroidStatus`.
+//   • `astroidSecretNames` drives what the scaffold seeds and types, so the
+//     list a developer is told to fill is generated from the same declaration
+//     the runtime gate reads. They cannot drift.
+import { commerceSecretNames, resolveCommerceStatus } from "./commerce/secrets.js";
+import { ASTROID_VITALS_SECRET_NAMES } from "./analytics/index.js";
+import { EMAIL_SECRET_NAMES, resolveMailerStatus } from "./email/send.js";
+/**
+ * Secrets every Astroid site has, independent of which modules are on.
+ *
+ * `SESSION_SECRET` is here but is NOT a dormancy gate — it fails closed off
+ * localhost (see `getSessionSecret`), because an unsigned session isn't a
+ * feature to switch off. It's listed so the scaffold seeds and types it.
+ */
+export const ASTROID_CORE_SECRET_NAMES = [
+    "SESSION_SECRET",
+    "TURNSTILE_SECRET",
+    "TURNSTILE_SITE_KEY",
+];
+/**
+ * Every secret name this config implies, grouped by module.
+ *
+ * The scaffold uses this twice: to seed `.dev.vars`/`.env.example` with the
+ * placeholder sentinel, and to type the matching `CloudflareEnv` members. A
+ * module that isn't enabled contributes nothing — a declaration is a promise,
+ * and a marketing site shouldn't be told to provision a Square token.
+ */
+export function astroidSecretNames(config) {
+    const groups = {
+        core: [...ASTROID_CORE_SECRET_NAMES],
+        email: [...EMAIL_SECRET_NAMES],
+    };
+    const commerce = commerceSecretNames(config.commerce);
+    if (commerce.length > 0)
+        groups.commerce = commerce;
+    // The CWV read-back's API credentials. Collection needs none of this — only
+    // querying the p75 back out does, because the Analytics Engine SQL API is
+    // account-scoped and has no binding.
+    groups.vitals = [...ASTROID_VITALS_SECRET_NAMES];
+    return groups;
+}
+/**
+ * Resolve every enabled module's gate.
+ *
+ * ```ts
+ * // src/pages/api/_astroid/status.ts, or a dev-only banner
+ * const report = await astroidModuleStatus(config, env);
+ * console.info(describeAstroidStatus(report));
+ * ```
+ */
+export async function astroidModuleStatus(config, env) {
+    const secretEnv = env;
+    const [commerce, mailer] = await Promise.all([
+        resolveCommerceStatus(config.commerce, secretEnv),
+        resolveMailerStatus(env),
+    ]);
+    const reports = [
+        {
+            module: "email",
+            enabled: true,
+            configured: mailer.configured,
+            missing: mailer.missing,
+            detail: mailer.configured
+                ? "sending through the EMAIL binding"
+                : // Naming the log is the useful part: the magic link IS in the console,
+                    // and someone who doesn't know that concludes sign-in is broken.
+                    "dormant — messages are logged to the console (the magic link is in the log), not sent",
+        },
+    ];
+    if (commerce.enabled) {
+        reports.push({
+            module: "commerce",
+            enabled: true,
+            configured: commerce.configured,
+            missing: commerce.missing,
+            detail: commerce.configured
+                ? `live via ${commerce.providers.map((p) => p.provider).join(" + ")}`
+                : "dormant — the D1 catalog mirror still serves, but nothing syncs from the provider and checkout is simulated",
+        });
+    }
+    return reports;
+}
+/**
+ * The report as a printable block. One line per module, missing names spelled
+ * out — "commerce is off" sends someone reading source; "commerce is dormant —
+ * set SQUARE_ACCESS_TOKEN" does not.
+ */
+export function describeAstroidStatus(reports) {
+    if (reports.length === 0)
+        return "[astroid] no optional modules enabled";
+    return [
+        "[astroid] module status",
+        ...reports.map((r) => {
+            const head = `  ${r.module}: ${r.configured ? "configured" : "dormant (simulated)"}`;
+            const why = r.missing.length > 0 ? ` — unprovisioned: ${r.missing.join(", ")}` : "";
+            return `${head}${why}\n    ${r.detail}`;
+        }),
+    ].join("\n");
+}

package/dist/worker/generate.d.ts

@@ -1,4 +1,6 @@
 import type { AstroidConfig } from "../config.js";
+export declare const ASTROID_SETTINGS_COLUMNS: string[];
+export declare const ASTROID_SETTINGS_IMAGE_KEYS: string[];
 /**
  * Generate the Worker entrypoint (`worker.ts`) from an Astroid config: the editor
  * routes in collision-free order, an R2 media-asset route, and the `composeWorker`
@@ -10,15 +12,21 @@ export declare function generateAstroidWorker(config: AstroidConfig): string;
  * Generate the Astro middleware (`middleware.ts`) from an Astroid config: the
  * shared Louise flow (rate-limit the unauthenticated POST surface → resolve editor
  * session + sticky `?louise` edit mode → content-freshness + security headers) via
- * `createLouiseMiddleware`. The default rate rule caps `POST /api/auth/*` (magic-link
- * sign-in) against the provisioned `RL` KV; auth is the same seam as the worker.
+ * `createLouiseMiddleware`.
  *
- * CSP: `astro.config.mjs` enables `security.csp`, so Astro emits a hash-based
- * `content-security-policy` response header on every SSR page. The `cspStyleSrc`
- * below tells `createLouiseMiddleware` to rewrite that header's `style-src` to
- * `'self' 'unsafe-inline'` — the hash-based `style-src` Astro emits would block
- * Louise's data-driven `style=""` carriers and the editor's runtime-injected
- * `<style>`. Script hashes are left verbatim (the template's inline scripts are
- * kept hashable), and the inlined `data:` brand font is auto-allowed.
+ * The rate rules are NOT emitted as literals here — the file calls
+ * `astroidRateRules(astroidConfig)`, so the set stays real data in the package
+ * (testable, and a `match` predicate survives, which a serialized literal could
+ * not). Enabling a portal or commerce in the config adds that surface's rules
+ * with no regeneration of this file at all.
+ *
+ * CSP: `astro.config.mjs` enables `security.csp` (via `astroidSecurity`), so
+ * Astro emits a hash-based `content-security-policy` response header on every SSR
+ * page and owns `script-src`. The `cspStyleSrc` below tells
+ * `createLouiseMiddleware` to rewrite that header's `style-src` to
+ * `'self' 'unsafe-inline'` — a hash-based `style-src` would, per spec, void the
+ * `'unsafe-inline'` that Louise's data-driven `style=""` carriers and the
+ * editor's runtime-injected `<style>` require. Script hashes are left verbatim,
+ * and the inlined `data:` brand font is auto-allowed.
  */
-export declare function generateAstroidMiddleware(_config: AstroidConfig): string;
+export declare function generateAstroidMiddleware(config: AstroidConfig): string;