create-ailk 0.20.0 → 0.22.0

package/dist/apply-design.d.ts

@@ -42,6 +42,11 @@ export type ApplyDesignChange = {
     kind: "home";
     action: "seeded" | "restored";
     fields: string[];
+} | {
+    path: string;
+    kind: "contact";
+    action: "seeded" | "restored";
+    fields: string[];
 } | {
     path: string;
     kind: "manifest";
@@ -57,6 +62,10 @@ export interface ApplyDesignResult {
     home: HomeSeedOutcome;
     /** #7743 D7 — the design ships a home arc for this site, so a home it leaves alone is reported. */
     homeArc?: true;
+    /** #8661 D11 — what the design did to the contact page's sections and title. */
+    contact: HomeSeedOutcome;
+    /** #8661 D11 — the design ships a contact page for this site, so a contact page it leaves alone is reported. */
+    contactSeed?: true;
     /** The site-relative roster file, when there is one. */
     rosterPath?: string;
     /** #7720 D4.2 — the distinct families written to site-fonts.ts, display first; set only when faces are written. */

package/dist/apply-design.js

@@ -19,7 +19,7 @@ import { dirname, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { planDesignMd } from "./apply-design-md.js";
 import { compileDesignFonts, compileDesignTheme } from "./design-compile.js";
-import { HOME_PAGE_PATH, designHomeSeeds, planDesignHome, shapeHomePath, shippedHomeSeeds, } from "./design-home.js";
+import { CONTACT_PAGE_PATH, DESIGN_SEED_PAGES, HOME_PAGE_PATH, designHomeSeeds, planDesignHome, shapeHomePath, shippedHomeSeeds, siteIdentityName, } from "./design-home.js";
 import { applyDesignPresets, readSectionLookCatalog, shippedPageTypes, validateDesignPresets, } from "./design-presets.js";
 import { resolveDesign, spliceThemeBlock } from "./design-scaffold.js";
 import { chromeKnobReaders, unreadChromeKnobs } from "./lib/chrome-readers.js";
@@ -194,6 +194,9 @@ export async function applyDesign(opts) {
     // #7743 D7 — the home seeds (the design's and every shipped design's), validated beside the presets.
     const designSeeds = designHomeSeeds(resolved, { designsDir: opts.designsDir, catalog });
     const shippedSeeds = shippedHomeSeeds({ designsDir: opts.designsDir, catalog });
+    // #8661 D11 — and the contact seeds, the same way.
+    const contactSeeds = designHomeSeeds(resolved, { designsDir: opts.designsDir, catalog, page: "contact" });
+    const shippedContactSeeds = shippedHomeSeeds({ designsDir: opts.designsDir, catalog, page: "contact" });
     // C5 — the design gate, fed the site's own key (D6). A Free design reads no key.
     if (!resolved.free) {
         const key = readSiteKey(targetAbs, env);
@@ -243,28 +246,44 @@ export async function applyDesign(opts) {
     const designMdNext = planDesignMd(resolved.dir, targetAbs);
     // #7743 D7 — the home is planned before the presets, so a seeded home is
     // written once, carrying both. The one `planDesignHome` call site here.
+    // #8661 D11 — the contact page is planned right after it, its heading named
+    // from the site's `siteIdentity.name`.
     const shape = roster?.template.shape;
-    const target = designSeeds.find((seed) => seed.shape === shape);
-    // The arc this site would take: the shape's seed, or (with no shape to pick one) any seed at all.
-    const homeArc = target !== undefined || (shape === undefined && designSeeds.length > 0);
-    const homePath = join(targetAbs, ...HOME_PAGE_PATH.split("/"));
-    const current = existsSync(homePath) ? readFileSync(homePath, "utf8") : undefined;
-    const homePlan = planDesignHome({
-        current,
-        shape,
-        target,
-        shapeHome: shape === undefined || current === undefined
-            ? ""
-            : readFileSync(shapeHomePath(shape, {
-                siteTemplatesDir: opts.siteTemplatesDir,
-                templatesDir,
-            }), "utf8"),
-        shippedSeeds,
-        catalog: catalog(),
+    const siteName = siteIdentityName(siteMdxCurrent);
+    const plans = [
+        ["home", designSeeds, shippedSeeds],
+        ["contact", contactSeeds, shippedContactSeeds],
+    ].map(([page, pageSeeds, shippedPageSeeds]) => {
+        const target = pageSeeds.find((seed) => seed.shape === shape);
+        const path = join(targetAbs, ...DESIGN_SEED_PAGES[page].path.split("/"));
+        const current = existsSync(path) ? readFileSync(path, "utf8") : undefined;
+        const plan = planDesignHome({
+            page,
+            siteName,
+            current,
+            shape,
+            target,
+            shapeHome: shape === undefined || current === undefined
+                ? ""
+                : readFileSync(shapeHomePath(shape, { siteTemplatesDir: opts.siteTemplatesDir, templatesDir, page }), "utf8"),
+            shippedSeeds: shippedPageSeeds,
+            catalog: catalog(),
+        });
+        // The page this site would take: the shape's seed, or (with no shape to pick one) any seed at all.
+        const offered = target !== undefined || (shape === undefined && pageSeeds.length > 0);
+        const action = plan.outcome === "seeded" || plan.outcome === "restored" ? plan.outcome : undefined;
+        return { path, plan, offered, action };
     });
-    const homeAction = homePlan.outcome === "seeded" || homePlan.outcome === "restored" ? homePlan.outcome : undefined;
+    const [homeSeeding, contactSeeding] = plans;
+    const homePlan = homeSeeding.plan;
+    const homeArc = homeSeeding.offered;
+    const homePath = homeSeeding.path;
+    const homeAction = homeSeeding.action;
+    const contactPlan = contactSeeding.plan;
+    const contactPath = contactSeeding.path;
+    const contactAction = contactSeeding.action;
     const pageWrites = [];
-    if (roster !== undefined && (hasPresets || homeAction !== undefined)) {
+    if (roster !== undefined && (hasPresets || homeAction !== undefined || contactAction !== undefined)) {
         const pageTypes = new Set();
         for (const row of roster.rows) {
             const pageType = row.value["pageType"];
@@ -274,11 +293,17 @@ export async function applyDesign(opts) {
         const contentDir = join(targetAbs, "content");
         // An authored home kept from a design's arc is reported as kept, so no preset dresses it either (D3, F4).
         const homeKept = homePlan.outcome === "authored" && homeArc;
+        // #8661 D11 — likewise an authored contact page kept from the design's own.
+        const contactKept = contactPlan.outcome === "authored" && contactSeeding.offered;
         const pages = listMdxFiles(contentDir)
-            .filter((path) => path !== siteMdxPath && !(homeKept && path === homePath))
+            .filter((path) => path !== siteMdxPath && !(homeKept && path === homePath) && !(contactKept && path === contactPath))
             .map((path) => ({
             path,
-            text: path === homePath && homePlan.text !== undefined ? homePlan.text : readFileSync(path, "utf8"),
+            text: path === homePath && homePlan.text !== undefined
+                ? homePlan.text
+                : path === contactPath && contactPlan.text !== undefined
+                    ? contactPlan.text
+                    : readFileSync(path, "utf8"),
         }));
         const presetResult = hasPresets
             ? applyDesignPresets(pages, pkg.sections, { pageTypes })
@@ -286,14 +311,21 @@ export async function applyDesign(opts) {
         for (const page of pages) {
             const preset = presetResult.pages.find((p) => p.path === page.path);
             const home = page.path === homePath ? homeAction : undefined;
-            if (preset === undefined && home === undefined)
+            const contact = page.path === contactPath ? contactAction : undefined;
+            if (preset === undefined && home === undefined && contact === undefined)
                 continue;
             const fields = [
                 ...new Set(presetResult.applied
                     .filter((a) => a.path === page.path)
                     .map((a) => `${a.sectionType}.${a.field}`)),
             ].sort();
-            pageWrites.push({ path: page.path, text: preset?.text ?? page.text, fields, ...(home !== undefined ? { home } : {}) });
+            pageWrites.push({
+                path: page.path,
+                text: preset?.text ?? page.text,
+                fields,
+                ...(home !== undefined ? { home } : {}),
+                ...(contact !== undefined ? { contact } : {}),
+            });
         }
     }
     let manifest = "no-roster";
@@ -303,10 +335,14 @@ export async function applyDesign(opts) {
         if (roster.path === SITE_ROSTER_PATH) {
             manifestNext = planSiteManifestDesign(readFileSync(rosterAbs, "utf8"), { design: resolved.recorded, layout: chrome, theme }, rosterAbs);
             // #7743 D6 — the `/` row records the home as written, in the same single write.
-            const home = pageWrites.find((page) => page.home !== undefined);
-            if (home !== undefined) {
+            // #8661 — and the `/contact` row the contact page.
+            for (const page of ["home", "contact"]) {
+                const written = pageWrites.find((write) => write[page] !== undefined);
+                if (written === undefined)
+                    continue;
                 manifestNext =
-                    planHomeRecord(manifestNext ?? readFileSync(rosterAbs, "utf8"), home.text, catalog()) ?? manifestNext;
+                    planHomeRecord(manifestNext ?? readFileSync(rosterAbs, "utf8"), written.text, catalog(), page) ??
+                        manifestNext;
             }
             manifest = manifestNext === undefined ? "unchanged" : "recorded";
         }
@@ -321,7 +357,9 @@ export async function applyDesign(opts) {
         const path = siteRelative(targetAbs, page.path);
         changes.push(page.home !== undefined
             ? { path, kind: "home", action: page.home, fields: page.fields }
-            : { path, kind: "preset", fields: page.fields });
+            : page.contact !== undefined
+                ? { path, kind: "contact", action: page.contact, fields: page.fields }
+                : { path, kind: "preset", fields: page.fields });
     }
     if (chromeNext !== chromeCurrent) {
         mkdirSync(dirname(chromePath), { recursive: true });
@@ -353,6 +391,8 @@ export async function applyDesign(opts) {
         manifest,
         home: homePlan.outcome,
         ...(homeArc ? { homeArc: true } : {}),
+        contact: contactPlan.outcome,
+        ...(contactSeeding.offered ? { contactSeed: true } : {}),
         ...(roster !== undefined ? { rosterPath: roster.path } : {}),
         ...(fontFamilies !== undefined ? { fonts: fontFamilies } : {}),
         ...(fontsUnwired ? { fontsUnwired: true } : {}),
@@ -370,16 +410,20 @@ export function formatApplyDesignReport(result) {
         for (const change of result.changes) {
             const suffix = change.kind === "preset"
                 ? ` (${change.fields.join(", ")})`
-                : change.kind === "home"
+                : change.kind === "home" || change.kind === "contact"
                     ? ` (${[change.action, change.fields.join(", ")].filter((part) => part !== "").join("; ")})`
                     : "";
             lines.push(`  ${change.kind.padEnd(8)}  ${change.path}${suffix}`);
         }
         const n = result.changes.length;
         const homeWritten = result.changes.some((change) => change.kind === "home");
+        const contactWritten = result.changes.some((change) => change.kind === "contact");
+        const contactNote = "the contact page's sections and title were replaced.";
         lines.push(`${n} file${n === 1 ? "" : "s"} changed. ${homeWritten
-            ? "Routes are unchanged; the home page's sections were replaced."
-            : "Routes and structured data are unchanged."}`);
+            ? `Routes are unchanged; the home page's sections were replaced.${contactWritten ? ` And ${contactNote}` : ""}`
+            : contactWritten
+                ? `Routes are unchanged; ${contactNote}`
+                : "Routes and structured data are unchanged."}`);
     }
     if (result.home === "authored" && result.homeArc === true) {
         lines.push(`home kept: ${HOME_PAGE_PATH} has authored sections — the ${result.design} home arc was not applied`);
@@ -387,6 +431,9 @@ export function formatApplyDesignReport(result) {
     else if (result.home === "no-shape" && result.homeArc === true) {
         lines.push("home not seeded: the site records no shape");
     }
+    if (result.contact === "authored" && result.contactSeed === true) {
+        lines.push(`contact kept: ${CONTACT_PAGE_PATH} has an authored title or sections — the ${result.design} contact page was not applied`);
+    }
     if (result.fonts !== undefined) {
         lines.push(`fonts: ${result.fonts.join(", ")} load at next build through next/font/google — a family that is not a variable Google font fails there`);
     }

package/dist/derive-architecture.d.ts

@@ -28,7 +28,14 @@ export interface DeriveArchitectureOptions {
  * hub — the billing action (#8217 D9, a reviewed change to the #7873 rule).
  */
 export declare const SPOKE_CHECKOUT_ROUTE_FILES: readonly string[];
-/** The forbidden patterns a spoke's apps/web carries (#7873, brief Part 2 §2). */
+/**
+ * The spoke files that may import @working-theory/spoke-checkout to READ a
+ * paid session, and nothing else: the thank-you page's `readPaidCheckoutEmail`
+ * (#8757 D13). Kept apart from SPOKE_CHECKOUT_ROUTE_FILES so it does not
+ * also admit them to `lib/checkout`, the one file that fulfils an order.
+ */
+export declare const SPOKE_CHECKOUT_READER_FILES: readonly string[];
+/** The forbidden patterns a spoke's apps/web carries (#7873, brief Part 2 §2; #8748). */
 export declare const SPOKE_WEB_FORBIDDEN_PATTERNS: readonly ForbiddenPattern[];
 /** The same three for a spoke's kept apps/mcp — no MCP file may import the package (#7873). */
 export declare const SPOKE_MCP_FORBIDDEN_PATTERNS: readonly ForbiddenPattern[];

package/dist/derive-architecture.js

@@ -37,6 +37,15 @@ export const SPOKE_CHECKOUT_ROUTE_FILES = Object.freeze([
     "apps/web/app/api/webhooks/stripe/route.ts",
     "apps/web/app/[locale]/(authed)/account/billing/spoke-billing.action.ts",
 ]);
+/**
+ * The spoke files that may import @working-theory/spoke-checkout to READ a
+ * paid session, and nothing else: the thank-you page's `readPaidCheckoutEmail`
+ * (#8757 D13). Kept apart from SPOKE_CHECKOUT_ROUTE_FILES so it does not
+ * also admit them to `lib/checkout`, the one file that fulfils an order.
+ */
+export const SPOKE_CHECKOUT_READER_FILES = Object.freeze([
+    "apps/web/app/[locale]/checkout/thank-you/page.tsx",
+]);
 /**
  * A line-level regex for an import of `specifier` or one of its subpaths, in
  * every form the line can take: `from "…"` (a static or re-export, including
@@ -53,7 +62,7 @@ function specifierForm(specifier) {
 /** P1 with no exclusions — a kept apps/mcp's form; apps/web adds the route files. */
 const SPOKE_CHECKOUT_PATTERN = Object.freeze({
     pattern: specifierForm("@working-theory/spoke-checkout"),
-    reason: "Spoke checkout: only the buy route, the webhook route and the billing action may import @working-theory/spoke-checkout (brief Part 2 §2, #7873, #8217)",
+    reason: "Spoke checkout: only the buy route, the webhook route, the billing action and the thank-you page may import @working-theory/spoke-checkout (brief Part 2 §2, #7873, #8217, #8757)",
 });
 const STRIPE_CLIENT_PATTERN = Object.freeze({
     pattern: specifierForm("@working-theory/stripe-client"),
@@ -63,11 +72,37 @@ const STRIPE_SDK_PATTERN = Object.freeze({
     pattern: specifierForm("stripe"),
     reason: "A spoke never imports the stripe SDK directly — it reaches Stripe only through @working-theory/spoke-checkout (#7873)",
 });
-/** The forbidden patterns a spoke's apps/web carries (#7873, brief Part 2 §2). */
+/**
+ * The standard spoke checkout's fulfilment (`lib/checkout.ts`) sends the one
+ * `Idempotency-Key` the hub reads as a purchase, so only the files allowed to
+ * import the package may reach it (#8748 D3, SEC-8748-A): any relative or
+ * `@/`-aliased import (apps/web's tsconfig maps `@/*` to the app root) whose
+ * last segment is `checkout` (with or without a `.js`/`.ts`-family
+ * extension, which `bundler` resolution maps to the same file), in every form
+ * `specifierForm` covers. The
+ * closing quote straight after `checkout` keeps `checkout-config` and
+ * `checkout.actions` out of it. The checkout tests the writer copies are
+ * excluded too: the scaffold's lint reads test files.
+ */
+const SPOKE_FULFILMENT_PATTERN = Object.freeze({
+    pattern: "\\b(?:from|import|require)\\s*\\(?\\s*['\"`](?:(?:\\.{1,2}/)+|@/)(?:[^'\"`]*/)?checkout(?:\\.[cm]?[jt]sx?)?['\"`]",
+    paths_excluded: [
+        ...SPOKE_CHECKOUT_ROUTE_FILES,
+        "apps/web/app/api/checkout/__tests__/**",
+        "apps/web/app/api/webhooks/stripe/__tests__/**",
+        "apps/web/lib/__tests__/checkout.test.ts",
+    ],
+    reason: "Spoke checkout: only the buy route, the webhook route and the billing action may import lib/checkout, the one file that sends the hub an Idempotency-Key (#8748)",
+});
+/** The forbidden patterns a spoke's apps/web carries (#7873, brief Part 2 §2; #8748). */
 export const SPOKE_WEB_FORBIDDEN_PATTERNS = Object.freeze([
-    Object.freeze({ ...SPOKE_CHECKOUT_PATTERN, paths_excluded: [...SPOKE_CHECKOUT_ROUTE_FILES] }),
+    Object.freeze({
+        ...SPOKE_CHECKOUT_PATTERN,
+        paths_excluded: [...SPOKE_CHECKOUT_ROUTE_FILES, ...SPOKE_CHECKOUT_READER_FILES],
+    }),
     STRIPE_CLIENT_PATTERN,
     STRIPE_SDK_PATTERN,
+    SPOKE_FULFILMENT_PATTERN,
 ]);
 /** The same three for a spoke's kept apps/mcp — no MCP file may import the package (#7873). */
 export const SPOKE_MCP_FORBIDDEN_PATTERNS = Object.freeze([

package/dist/design-home.d.ts

@@ -2,7 +2,26 @@ import { type SectionLookCatalog } from "./design-presets.js";
 import type { ResolvedDesign } from "./design-scaffold.js";
 /** Where a site's home page lives, site-relative. */
 export declare const HOME_PAGE_PATH = "content/en/HomePage/home.mdx";
-/** One `home/<shape>.mdx` file of a design package (D1). */
+/** Where a site's contact page lives, site-relative (#8661 D11). */
+export declare const CONTACT_PAGE_PATH = "content/en/ContactPage/contact.mdx";
+/**
+ * The pages a design may seed (#8661 D11), keyed by the design-package
+ * directory that holds their seeds (`home/<shape>.mdx`, `contact/<shape>.mdx`).
+ */
+export declare const DESIGN_SEED_PAGES: {
+    readonly home: {
+        readonly pageType: "HomePage";
+        readonly path: "content/en/HomePage/home.mdx";
+        readonly route: "/";
+    };
+    readonly contact: {
+        readonly pageType: "ContactPage";
+        readonly path: "content/en/ContactPage/contact.mdx";
+        readonly route: "/contact";
+    };
+};
+export type DesignSeedPage = keyof typeof DESIGN_SEED_PAGES;
+/** One `home/<shape>.mdx` (or `contact/<shape>.mdx`, #8661 D11) file of a design package (D1). */
 export interface HomeSeed {
     readonly shape: string;
     /** Absolute path, for refusals. */
@@ -11,34 +30,46 @@ export interface HomeSeed {
 }
 export type HomeSeedOutcome = "seeded" | "restored" | "unchanged" | "authored" | "no-shape" | "no-home";
 /**
- * Read and validate `<dir>/home/*` (D1). Refuses with a `DesignPackageError`
- * naming the file, before any write: a basename that is not a recognized
- * shape, a page whose `type` is not `HomePage`, `sections` that cannot be
- * located (or are not in the flow form a carry can splice), a section type
- * the catalog does not carry, or a `logoCloud` whose `logos` is not `[]`.
+ * Read and validate `<dir>/home/*` (D1), or `<dir>/contact/*` for
+ * `page: "contact"` (#8661 D11). Refuses with a `DesignPackageError` naming
+ * the file, before any write: a basename that is not a recognized shape, a
+ * page whose `type` is not the page's (`HomePage`, `ContactPage`), `sections`
+ * that cannot be located (or are not in the flow form a carry can splice), a
+ * section type the catalog does not carry, or a `logoCloud` whose `logos` is
+ * not `[]`.
  */
 export declare function readDesignHomeSeeds(dir: string, opts: {
     catalog: () => SectionLookCatalog;
+    page?: DesignSeedPage;
 }): HomeSeed[];
 /**
- * The seeds a resolved design uses (D1): its own `home/`, else — a
- * byte-identical copy of a shipped design IS that design — the shipped
- * design's, else none.
+ * The seeds a resolved design uses (D1): its own `home/` (or `contact/`),
+ * else — a byte-identical copy of a shipped design IS that design — the
+ * shipped design's, else none.
  */
 export declare function designHomeSeeds(resolved: ResolvedDesign, opts: {
     designsDir: string;
     catalog: () => SectionLookCatalog;
+    page?: DesignSeedPage;
 }): HomeSeed[];
 /** Every shipped design's seeds (D3's placeholder set reads them all). */
 export declare function shippedHomeSeeds(opts: {
     designsDir: string;
     catalog: () => SectionLookCatalog;
+    page?: DesignSeedPage;
 }): HomeSeed[];
-/** The shape's own home: its shape tree's, else the overlay's (spec § 1.4). */
+/** The shape's own home (or contact page): its shape tree's, else the overlay's (spec § 1.4). */
 export declare function shapeHomePath(shape: string, opts: {
     siteTemplatesDir: string;
     templatesDir: string;
+    page?: DesignSeedPage;
 }): string;
+/**
+ * A site's `siteIdentity.name` (#8661 D11, C8): the first `name:` line
+ * indented directly under `siteIdentity:` in `content/_site.mdx`'s front
+ * matter, quotes stripped. Undefined when there is no such line.
+ */
+export declare function siteIdentityName(siteMdx: string | undefined): string | undefined;
 /**
  * A home's content fingerprint (D3): per section in order, its type and its
  * non-look `data` entries as `[key, normalized raw value]`, sorted by key.
@@ -55,9 +86,21 @@ export declare function applySeed(home: string, seed: HomeSeed, file?: string):
 /**
  * Plan a site home under a design (D3). Writes nothing: `text` is the new
  * home when the outcome is `seeded` or `restored`, and absent otherwise.
+ *
+ * `page: "contact"` (#8661 D11) plans the contact page instead. The seeds'
+ * `{{SITE_NAME}}` is filled with `siteName` (absent: `{Your Name}`) before
+ * anything is compared; the shape's own page is read with the scaffold
+ * markers substituted, as a scaffold installed it; the page is a placeholder
+ * only while its title is one too (the shape's own, or a seed's); and a write
+ * replaces the `title:` line as well as the sections, and the `description:`
+ * line while it is still a placeholder (the shape's own, or a seed's).
  */
 export declare function planDesignHome(opts: {
-    /** The site's content/en/HomePage/home.mdx, if any. */
+    /** The page planned (#8661 D11). Default `"home"`. */
+    page?: DesignSeedPage;
+    /** The site's name, for a contact seed's `{{SITE_NAME}}` (#8661 D11). */
+    siteName?: string | undefined;
+    /** The site's content/en/HomePage/home.mdx (or ContactPage/contact.mdx), if any. */
     current: string | undefined;
     /** The roster's template shape. */
     shape: string | undefined;