astroidjs 0.1.1 → 0.2.0

package/dist/config.js

@@ -19,7 +19,29 @@
 // `ModuleKind` are extracted from the real sites Astroid targets — a storefront
 // (coracle), a wholesale front (ghostfire), an artist portfolio (megbowen), and a
 // plain marketing baseline (louise-web).
+import { assertCommerceRoles } from "./commerce/roles.js";
 import { AstroidConfigError } from "./errors.js";
+/**
+ * Each archetype's default home-page sections.
+ *
+ * Lives here, in TypeScript, rather than in `create-astroid`'s plain JS — the
+ * other half of #277. As a JS object literal it could name a section that
+ * didn't exist and nothing would say so; typed against {@link SectionKind}
+ * (itself derived from the catalog) a stale name is a compile error, and CI
+ * type-checks this package.
+ *
+ * The four kinds this used to name — `marquee`, `featured`, `story`, `visit` —
+ * had no catalog entry or component and could never render. Each is replaced by
+ * the real section that does its job: a marquee is a `banner`, curated picks
+ * are a `productGrid`, a brand-origin block is `aboutIntro`, and "visit" is
+ * exactly `locationHours`.
+ */
+export const ASTROID_ARCHETYPE_SECTIONS = {
+    marketing: ["hero", "featureGrid", "cta", "contact"],
+    storefront: ["hero", "banner", "productGrid", "locationHours", "contact"],
+    wholesale: ["hero", "featureGrid", "aboutIntro", "contact"],
+    portfolio: ["hero", "gallery", "aboutIntro", "contact"],
+};
 /**
  * Define an Astroid project. An identity function in the shape of Astro's
  * `defineConfig`: it returns the config verbatim with full type-checking +
@@ -32,7 +54,7 @@ import { AstroidConfigError } from "./errors.js";
  *   key: "coracle",
  *   archetype: "storefront",
  *   theme: { name: "Coracle Coffee", colors: { brand: "#1f6f78" } },
- *   sections: ["hero", "marquee", "featured", "productGrid", "visit"],
+ *   sections: ["hero", "banner", "productGrid", "locationHours", "contact"],
  *   commerce: { provider: "square" },
  *   deploy: { platform: "cloudflare" },
  * });
@@ -48,5 +70,25 @@ export function defineAstroid(config) {
     if (!config.theme.colors || !config.theme.colors.brand) {
         throw new AstroidConfigError("Astroid config requires `theme.colors.brand` (the primary brand color)");
     }
+    // A provider assigned to a role its client can't serve (invoicing over
+    // Fourthwall, a storefront over Stripe) fails here rather than at runtime on
+    // the first invoice, as a missing function.
+    assertCommerceRoles(config.commerce);
+    // `portal.gated` is declared and resolved but read by NOTHING — the guard
+    // table is built from `portal.routes` alone, and `portalGuard` allows any
+    // unmatched path. So a site that set it believed the whole site sat behind a
+    // login (a pre-launch client gallery) while every page outside /portal was
+    // public, and it type-checked.
+    //
+    // Refusing the flag is the only safe state until it's implemented. A security
+    // control that silently does nothing is strictly worse than one that isn't
+    // offered: the first gives false confidence, the second sends you looking for
+    // an answer. Fail loudly, at config load, naming the workaround.
+    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 " +
+            "listing the prefixes you mean in `portal.routes` (e.g. `[{ prefix: \"/\" }]` with your " +
+            "login and auth paths ahead of it).");
+    }
     return config;
 }

package/dist/email/index.d.ts

@@ -0,0 +1,4 @@
+export { astroidMailTheme, type MailThemeOverrides } from "./theme.js";
+export { type AstroidMailEnv, sendInquiryMail } from "./inquiry.js";
+export { createMailer, type DeliveryResult, EMAIL_SECRET_NAMES, type EmailSender, type MailerEnv, type MailerOptions, type MailerStatus, type OutgoingMail, resolveMailer, resolveMailerStatus, sendTransactional, } from "./send.js";
+export { type InquiryDetails, inquiryConfirmationEmail, inquiryNotificationEmail, magicLinkEmail, type MailContent, type MailTheme, passwordResetEmail, } from "./templates.js";

package/dist/email/index.js

@@ -0,0 +1,5 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+export { astroidMailTheme } from "./theme.js";
+export { sendInquiryMail } from "./inquiry.js";
+export { createMailer, EMAIL_SECRET_NAMES, resolveMailer, resolveMailerStatus, sendTransactional, } from "./send.js";
+export { inquiryConfirmationEmail, inquiryNotificationEmail, magicLinkEmail, passwordResetEmail, } from "./templates.js";

package/dist/email/inquiry.d.ts

@@ -0,0 +1,33 @@
+import type { AstroidConfig } from "../config.js";
+import type { SecretSource } from "../secrets.js";
+import type { EmailSender } from "./send.js";
+import { type DeliveryResult } from "./send.js";
+import { type MailThemeOverrides } from "./theme.js";
+/** The bindings the inquiry hook reads. All optional — an unprovisioned mail
+ *  setup logs instead of sending, per the dormant-until-provisioned convention. */
+export interface AstroidMailEnv {
+    /** Cloudflare Email Sending binding. */
+    EMAIL?: EmailSender;
+    /**
+     * Envelope sender; its domain must be onboarded for Email Sending. A
+     * `SecretSource` rather than a plain string so a Secrets Store binding works
+     * here too — and so the placeholder sentinel reads as unconfigured.
+     */
+    MAIL_FROM?: SecretSource;
+    /** Where owner notifications go. Also the first editor's address. */
+    OWNER_EMAIL?: string;
+}
+/**
+ * Send the notify + confirm pair for one contact-form submission.
+ *
+ * Wire it into the generated worker's form route:
+ *
+ * ```ts
+ * formRoute({ form: contactForm, onSubmit: (values, env) => sendInquiryMail(config, env, values) })
+ * ```
+ *
+ * Each half is skipped when its recipient is unknown rather than failing the
+ * batch: no `OWNER_EMAIL` means no notification to send, and a submission whose
+ * email didn't validate still deserves to reach the owner.
+ */
+export declare function sendInquiryMail(config: AstroidConfig, env: AstroidMailEnv, values: Record<string, unknown>, overrides?: MailThemeOverrides): Promise<DeliveryResult[]>;

package/dist/email/inquiry.js

@@ -0,0 +1,63 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The inquiry pair, wired to the contact form.
+//
+// `formRoute` fires `onSubmit` AFTER the row is inserted and off the response
+// path (`waitUntil`), which is exactly the store-and-forward shape this wants:
+// the submission is already durable, so mail is a notification of something that
+// already happened and can fail without the visitor ever knowing.
+//
+// Two messages, not one — every site converged on the pair. The owner needs the
+// message; the visitor needs to know it arrived, because a contact form with no
+// acknowledgement is indistinguishable from one that's broken.
+import { resolveMailer, sendTransactional } from "./send.js";
+import { inquiryConfirmationEmail, inquiryNotificationEmail } from "./templates.js";
+import { astroidMailTheme } from "./theme.js";
+/** Trimmed string, or undefined for anything else. */
+const str = (v) => {
+    const s = typeof v === "string" ? v.trim() : "";
+    return s || undefined;
+};
+/**
+ * Send the notify + confirm pair for one contact-form submission.
+ *
+ * Wire it into the generated worker's form route:
+ *
+ * ```ts
+ * formRoute({ form: contactForm, onSubmit: (values, env) => sendInquiryMail(config, env, values) })
+ * ```
+ *
+ * Each half is skipped when its recipient is unknown rather than failing the
+ * batch: no `OWNER_EMAIL` means no notification to send, and a submission whose
+ * email didn't validate still deserves to reach the owner.
+ */
+export async function sendInquiryMail(config, env, values, overrides) {
+    const theme = astroidMailTheme(config, overrides);
+    const details = {
+        name: [str(values.firstName), str(values.lastName)].filter(Boolean).join(" "),
+        email: str(values.email) ?? "",
+        regarding: str(values.regarding),
+        message: str(values.message) ?? "",
+    };
+    const owner = str(env.OWNER_EMAIL);
+    const mails = [
+        ...(owner
+            ? [
+                {
+                    to: owner,
+                    content: inquiryNotificationEmail(theme, details),
+                    // So the owner can answer by hitting reply, rather than copying an
+                    // address out of the body.
+                    ...(details.email ? { replyTo: details.email } : {}),
+                },
+            ]
+            : []),
+        ...(details.email
+            ? [{ to: details.email, content: inquiryConfirmationEmail(theme, details) }]
+            : []),
+    ];
+    // One resolver decides dormancy for the whole module: no binding, no sender
+    // address, or a sender still holding the placeholder sentinel all come back
+    // as `logOnly`, so nothing hands the Email API a dummy envelope.
+    return sendTransactional(await resolveMailer(env), mails);
+}

package/dist/email/send.d.ts

@@ -0,0 +1,120 @@
+import type { EmailSender, MailContent } from "louise-toolkit/email";
+import { type ModuleSecrets, type SecretSource } from "../secrets.js";
+export type { EmailSender };
+/**
+ * The secrets the mailer needs. Just the envelope sender: the EMAIL binding is a
+ * binding, not a secret, so it's gated by presence rather than by value.
+ *
+ * Named here so `astroid doctor` and the scaffold's `.dev.vars` seed read the
+ * same list the runtime gate does.
+ */
+export declare const EMAIL_SECRET_NAMES: readonly ["MAIL_FROM"];
+/**
+ * The mailer's resolved gate. Deliberately NOT `ModuleSecrets<"MAIL_FROM">`:
+ * `missing` here can name `EMAIL`, which is a binding rather than a secret, so
+ * the key type is widened to plain strings.
+ */
+export interface MailerStatus {
+    /** True only when a binding AND a real sender address are both present. */
+    configured: boolean;
+    values: ModuleSecrets<"MAIL_FROM">["values"];
+    /** What's unprovisioned — secret names and/or `"EMAIL"`. */
+    missing: string[];
+    /** Whether an Email Sending binding is present at all. */
+    hasBinding: boolean;
+}
+/** The env members the mailer reads. Structural, so a project's env fits. */
+export interface MailerEnv {
+    EMAIL?: EmailSender | null;
+    MAIL_FROM?: SecretSource;
+}
+/**
+ * Resolve the email module's dormancy.
+ *
+ * Both halves are required, and for the same reason: a binding with no sender
+ * address can't build an envelope, and a sender address with no binding has
+ * nothing to send through. Either one missing means log-and-continue, which
+ * under `wrangler dev` (no EMAIL binding at all) is the normal case — and the
+ * reason the magic-link flow is still workable locally.
+ */
+export declare function resolveMailerStatus(env: MailerEnv): Promise<MailerStatus>;
+/**
+ * Build `MailerOptions` from an env, with dormancy already decided.
+ *
+ * The point of routing through {@link resolveMailerStatus} rather than checking
+ * `!env.EMAIL` inline is that the placeholder sentinel counts: a scaffold seeds
+ * `MAIL_FROM=DUMMY_REPLACE_ME`, and handing that to the Email API as an
+ * envelope sender is exactly the "called upstream with a dummy credential"
+ * failure the convention exists to prevent.
+ */
+export declare function resolveMailer(env: MailerEnv, overrides?: Partial<Omit<MailerOptions, "binding" | "from">>): Promise<MailerOptions & {
+    status: MailerStatus;
+}>;
+/** One message queued for delivery. */
+export interface OutgoingMail {
+    to: string;
+    content: MailContent;
+    /** Reply-To — for an inquiry notification, the visitor's own address, so the
+     *  owner can just hit reply. */
+    replyTo?: string;
+}
+/** What happened to one message. Never an exception. */
+export interface DeliveryResult {
+    to: string;
+    subject: string;
+    delivered: boolean;
+    messageId?: string;
+    /** Why it wasn't delivered — `"not-configured"`, `"log-only"`, or the error. */
+    reason?: string;
+}
+export interface MailerOptions {
+    /**
+     * The Cloudflare Email Sending binding. Absent or null → the mailer is
+     * dormant: messages are logged, and every result comes back
+     * `delivered: false, reason: "not-configured"`.
+     */
+    binding?: EmailSender | null;
+    /** Envelope sender. Its domain must be onboarded for Email Sending. */
+    from: string | {
+        email: string;
+        name?: string;
+    };
+    /** Log instead of sending even when a binding exists (a dry run). */
+    logOnly?: boolean;
+    /** Sink for the dev log. Defaults to `console.info`; pass one in a test. */
+    log?: (message: string) => void;
+    /**
+     * Print the message BODY when a send is skipped.
+     *
+     * The body carries single-use sign-in and password-reset links, so it is only
+     * printed where we can tell we're in development. Set this explicitly when the
+     * detection can't (a local `wrangler dev` against a real account, a test). Do
+     * not set it on a deployed Worker: the log is `wrangler tail` and Logpush.
+     */
+    devLog?: boolean;
+}
+/**
+ * Send a batch of transactional messages, best effort.
+ *
+ * Delivery runs concurrently and independently: an inquiry sends a notification
+ * to the owner and a confirmation to the visitor, and the owner's copy must
+ * still arrive when the visitor typo'd their address. Callers get a result per
+ * message and decide whether to care.
+ *
+ * ```ts
+ * const results = await sendTransactional(
+ *   { binding: env.EMAIL, from: env.MAIL_FROM },
+ *   [
+ *     { to: owner, content: inquiryNotificationEmail(theme, i), replyTo: i.email },
+ *     { to: i.email, content: inquiryConfirmationEmail(theme, i) },
+ *   ],
+ * );
+ * ```
+ */
+export declare function sendTransactional(options: MailerOptions, mails: OutgoingMail[]): Promise<DeliveryResult[]>;
+/**
+ * Bind a mailer's options once so call sites read as `mailer([...])`. Useful
+ * where the binding and sender are resolved per request but the sends are
+ * scattered (an inquiry hook, an auth callback).
+ */
+export declare function createMailer(options: MailerOptions): (mails: OutgoingMail[]) => Promise<DeliveryResult[]>;

package/dist/email/send.js

@@ -0,0 +1,196 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Best-effort delivery.
+//
+// Transactional mail in this stack is always store-and-forward: the inquiry row
+// is already in D1, the account already exists. Mail is the *notification* of
+// something that happened, so a mail failure must never fail the request that
+// caused it — and never throw into a `waitUntil` where it becomes an unhandled
+// rejection. Every path here resolves.
+//
+// The second job is the dev story. There is no EMAIL binding under `wrangler
+// dev`, and the single most common local task is "click the magic link" — so an
+// unconfigured mailer LOGS the message instead of silently dropping it, and it
+// logs the plaintext body, which is where the link is. That is the whole reason
+// every template renders a text alternative.
+//
+// This is the email module's half of the dormant-until-provisioned convention:
+// no binding means dormant and loudly simulated, not broken.
+import { sendEmail } from "louise-toolkit/email";
+import { resolveModuleSecrets } from "../secrets.js";
+/**
+ * The secrets the mailer needs. Just the envelope sender: the EMAIL binding is a
+ * binding, not a secret, so it's gated by presence rather than by value.
+ *
+ * Named here so `astroid doctor` and the scaffold's `.dev.vars` seed read the
+ * same list the runtime gate does.
+ */
+export const EMAIL_SECRET_NAMES = ["MAIL_FROM"];
+/**
+ * Resolve the email module's dormancy.
+ *
+ * Both halves are required, and for the same reason: a binding with no sender
+ * address can't build an envelope, and a sender address with no binding has
+ * nothing to send through. Either one missing means log-and-continue, which
+ * under `wrangler dev` (no EMAIL binding at all) is the normal case — and the
+ * reason the magic-link flow is still workable locally.
+ */
+export async function resolveMailerStatus(env) {
+    const secrets = await resolveModuleSecrets({ MAIL_FROM: env.MAIL_FROM });
+    const hasBinding = Boolean(env.EMAIL);
+    return {
+        configured: secrets.configured && hasBinding,
+        values: secrets.values,
+        missing: hasBinding ? [...secrets.missing] : [...secrets.missing, "EMAIL"],
+        hasBinding,
+    };
+}
+/**
+ * Build `MailerOptions` from an env, with dormancy already decided.
+ *
+ * The point of routing through {@link resolveMailerStatus} rather than checking
+ * `!env.EMAIL` inline is that the placeholder sentinel counts: a scaffold seeds
+ * `MAIL_FROM=DUMMY_REPLACE_ME`, and handing that to the Email API as an
+ * envelope sender is exactly the "called upstream with a dummy credential"
+ * failure the convention exists to prevent.
+ */
+export async function resolveMailer(env, overrides = {}) {
+    const status = await resolveMailerStatus(env);
+    return {
+        ...overrides,
+        binding: env.EMAIL ?? null,
+        from: status.values.MAIL_FROM ?? "noreply@localhost",
+        logOnly: overrides.logOnly || !status.configured,
+        status,
+    };
+}
+/**
+ * The console rendering of an unsent message.
+ *
+ * The body is the whole point in dev — that's where a sign-in link actually is,
+ * and printing it is what lets you sign in with no mail provider configured.
+ *
+ * It is also a credential. `logOnly` turns on whenever `MAIL_FROM` is unset, and
+ * that can happen in PRODUCTION — a secret that didn't get set, or a Secrets
+ * Store read that failed. The body then went to `console.info`, which means
+ * `wrangler tail` and every Logpush sink, carrying live single-use magic links
+ * and password-reset URLs. Anyone with read access to observability could take
+ * over an editor or portal account.
+ *
+ * So the body is printed only when we can see we're in development. Everywhere
+ * else the log still records that a message went unsent, and why, but not the
+ * credential inside it.
+ */
+function describe(mail, reason, includeBody) {
+    const head = [
+        `[astroid:email] ${reason} — not sent`,
+        `  to:      ${mail.to}`,
+        `  subject: ${mail.content.subject}`,
+    ];
+    if (!includeBody) {
+        return [
+            ...head,
+            "  (body withheld — it can contain a single-use sign-in or reset link, and this",
+            "   does not look like a development environment. Set MAIL_FROM and the EMAIL",
+            "   binding to deliver it, or pass `devLog: true` if this really is local.)",
+        ].join("\n");
+    }
+    return [...head, "  ---", ...mail.content.text.split("\n").map((line) => `  ${line}`), "  ---"].join("\n");
+}
+/**
+ * Best-effort "are we in development?".
+ *
+ * Deliberately conservative — it decides whether a credential is printed, so an
+ * unknown environment must read as production. Workers has no `NODE_ENV`, so we
+ * look at the signals that do exist and let a caller override explicitly.
+ */
+function looksLikeDev() {
+    // Vite/Astro define this at build time; `import.meta.env` is absent in a plain
+    // Worker, hence the guarded read.
+    const viteDev = import.meta.env?.DEV;
+    if (typeof viteDev === "boolean")
+        return viteDev;
+    const nodeEnv = globalThis.process
+        ?.env?.NODE_ENV;
+    if (typeof nodeEnv === "string")
+        return nodeEnv !== "production";
+    return false;
+}
+/**
+ * Send a batch of transactional messages, best effort.
+ *
+ * Delivery runs concurrently and independently: an inquiry sends a notification
+ * to the owner and a confirmation to the visitor, and the owner's copy must
+ * still arrive when the visitor typo'd their address. Callers get a result per
+ * message and decide whether to care.
+ *
+ * ```ts
+ * const results = await sendTransactional(
+ *   { binding: env.EMAIL, from: env.MAIL_FROM },
+ *   [
+ *     { to: owner, content: inquiryNotificationEmail(theme, i), replyTo: i.email },
+ *     { to: i.email, content: inquiryConfirmationEmail(theme, i) },
+ *   ],
+ * );
+ * ```
+ */
+export async function sendTransactional(options, mails) {
+    const log = options.log ?? ((message) => console.info(message));
+    const dormant = !options.binding || options.logOnly;
+    if (dormant) {
+        const reason = options.binding ? "log-only" : "not-configured";
+        const includeBody = options.devLog ?? looksLikeDev();
+        for (const mail of mails)
+            log(describe(mail, reason, includeBody));
+        return mails.map((mail) => ({
+            to: mail.to,
+            subject: mail.content.subject,
+            delivered: false,
+            reason,
+        }));
+    }
+    const binding = options.binding;
+    const settled = await Promise.allSettled(mails.map((mail) => sendEmail(binding, {
+        from: options.from,
+        to: mail.to,
+        subject: mail.content.subject,
+        html: mail.content.html,
+        text: mail.content.text,
+        ...(mail.replyTo ? { replyTo: mail.replyTo } : {}),
+    })));
+    return settled.map((result, i) => {
+        const mail = mails[i];
+        if (result.status === "fulfilled") {
+            return {
+                to: mail.to,
+                subject: mail.content.subject,
+                delivered: true,
+                messageId: result.value.messageId,
+            };
+        }
+        // A genuine delivery failure is LOGGED, not just returned.
+        //
+        // The result array was the only record of it, and the one caller that
+        // matters — the generated inquiry handler — discards it by design (the row
+        // is already durable, and the visitor must not see a 500 because the owner's
+        // notification bounced). So a dead Email Sending domain or an exhausted
+        // quota produced silence everywhere: a success page for the visitor, nothing
+        // for the owner, and nothing in `wrangler tail`. Weeks later someone asks
+        // why the contact form stopped working.
+        //
+        // Logged here rather than left to callers because this is the only place
+        // that knows a send was attempted and failed; `log` is already injectable
+        // for tests and for routing somewhere other than console.
+        const reason = result.reason instanceof Error ? result.reason.message : String(result.reason);
+        log(`[astroid:email] delivery FAILED to ${mail.to} (${mail.content.subject}): ${reason}`);
+        return { to: mail.to, subject: mail.content.subject, delivered: false, reason };
+    });
+}
+/**
+ * Bind a mailer's options once so call sites read as `mailer([...])`. Useful
+ * where the binding and sender are resolved per request but the sends are
+ * scattered (an inquiry hook, an auth callback).
+ */
+export function createMailer(options) {
+    return (mails) => sendTransactional(options, mails);
+}

package/dist/email/templates.d.ts

@@ -0,0 +1,24 @@
+import { type MailContent, type MailTheme } from "louise-toolkit/email";
+export type { MailContent, MailTheme };
+/** Editor sign-in magic link. */
+export declare function magicLinkEmail(theme: MailTheme, params: {
+    url: string;
+    toEmail: string;
+}): MailContent;
+/** Password-reset link (the portal's credential flow). */
+export declare function passwordResetEmail(theme: MailTheme, params: {
+    url: string;
+    toEmail: string;
+}): MailContent;
+/** The fields an inquiry contributes to both halves of the pair. */
+export interface InquiryDetails {
+    name: string;
+    email: string;
+    /** Subject line the visitor picked, if the form offers one. */
+    regarding?: string;
+    message: string;
+}
+/** Owner-facing notification for a new contact-form submission. */
+export declare function inquiryNotificationEmail(theme: MailTheme, i: InquiryDetails): MailContent;
+/** Confirmation back to whoever submitted the contact form. */
+export declare function inquiryConfirmationEmail(theme: MailTheme, i: InquiryDetails): MailContent;