create-ailk 0.19.1 → 0.21.0

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/cli.js

@@ -19,6 +19,9 @@
  *      to a linked Vercel project and redeploy, exit (#6683 D9)
  *      on an `apply-design` subcommand: rewrite an existing site's look,
  *      print the changed-file report, exit (#6819)
+ *      on an `update` subcommand: bring template fixes into a site's
+ *      already-copied apps/web, apps/api and apps/mcp code, print the
+ *      per-file report, exit (2 on a refusal it names) (#8522)
  *   1. parse argv → CliOptions
  *   2. on --help: print helpText, exit 0
  *   3. on --version: print version, exit 0
@@ -58,6 +61,7 @@ import { addModule, formatSurfaceDrift, scaffold, syncArchitectureSync, syncCata
 import { SEED_FLOWS_HELP, SeedFlowsRefusedError, parseSeedFlowsArgs, seedFlows, } from "./seed-flows.js";
 import { CORE_SURFACE_PATHS, SURFACE_ALIASES } from "./surfaces.js";
 import { SYNC_ROUTES_HELP, formatSyncRoutesReport, parseSyncRoutesArgs, } from "./sync-routes.js";
+import { UPDATE_HELP, UpdateRefusedError, formatUpdateReport, parseUpdateArgs, updateSite, } from "./update.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const PKG_JSON = resolve(PKG_ROOT, "package.json");
 function readPackageVersion() {
@@ -272,6 +276,35 @@ async function main() {
         process.stdout.write(formatApplyDesignReport(result));
         process.exit(0);
     }
+    // `update [<target-dir>]` (#8522): bring template fixes into a site's
+    // already-copied apps/web, apps/api and apps/mcp code. A refusal it names
+    // (no record and no patternVersion, an unparseable record, a downgrade, an
+    // unreadable architecture.yaml or manifest topology, a backfill whose
+    // fetch fails) exits 2 before anything is written. A clean run exits 0
+    // even when it lists files under "Needs review" — the review list is the
+    // hand-off, not a failure.
+    if (argv[0] === "update") {
+        const args = parseUpdateArgs(argv.slice(1));
+        if (args.help) {
+            process.stdout.write(UPDATE_HELP);
+            process.exit(0);
+        }
+        try {
+            const result = await updateSite({
+                targetDir: args.target ?? process.cwd(),
+                templatesDir: resolve(PKG_ROOT, "templates"),
+                version: readPackageVersion(),
+            });
+            process.stdout.write(formatUpdateReport(result));
+        }
+        catch (err) {
+            if (!(err instanceof UpdateRefusedError))
+                throw err;
+            process.stderr.write(`[create-ailk] ${err.message}\n`);
+            process.exit(err.exitCode);
+        }
+        process.exit(0);
+    }
     // No silent default (#6754 D2/D3): a scaffold run naming neither --shape
     // nor --template asks for a shape on a terminal and is refused without one.
     // A --design or --modules outside the release scope is refused before that
@@ -317,6 +350,8 @@ async function main() {
             "\n" +
             APPLY_DESIGN_HELP +
             "\n" +
+            UPDATE_HELP +
+            "\n" +
             LICENSE_SET_HELP);
         process.exit(0);
     }

package/dist/copy.d.ts

@@ -19,11 +19,52 @@ export interface CopyTemplateOptions {
      * `.../services` never excludes a sibling `.../services-extra`.
      */
     excludePaths?: string[];
+    /**
+     * Called once per file actually written, with its `/`-separated
+     * destination path (relative to `targetDir`) and the exact bytes written
+     * (#8522 D2) — `create-ailk update`'s per-file record is built from these
+     * calls. No existing caller passes this, so their behaviour is unchanged.
+     */
+    onWrite?: (relPath: string, bytes: Uint8Array) => void;
 }
+/**
+ * Whether a walked template-relative path is inside (or equal to) an excluded
+ * directory. Compares `/`-normalized paths so the check holds on Windows, and
+ * only at a directory boundary — a prefix that stops mid-segment is no match.
+ * Exported (#8522 D3) so `create-ailk update` applies the same surface-gating
+ * boundary to a candidate new file.
+ */
+export declare function isExcluded(relativePath: string, excluded: readonly string[]): boolean;
+/**
+ * The pack-safe name `build-templates.mjs` ships each snapshot `.gitignore`
+ * under (#7366 D1) — npm and pnpm strip a file literally named `.gitignore`
+ * from a packed tarball, but keep one named `_gitignore`. One definition,
+ * imported by `build-templates.mjs` (from the compiled `dist/copy.js`) and
+ * by `copyTemplate` below, so the two can never spell it differently.
+ */
+export declare const PACKED_GITIGNORE_NAME = "_gitignore";
 /**
  * Whether a scaffolded path's content is text we run markers over. Exported
  * because the template/base layer (`installBundleTree`) substitutes with the
  * same classifier — one definition, not two (#6460).
  */
 export declare function isTextFile(relativePath: string): boolean;
+/**
+ * The destination path a template-relative path (`/`-separated) copies to —
+ * `undefined` for a packaging-only `.gitkeep` or `.npmignore` (never a
+ * scaffold file), and a final `PACKED_GITIGNORE_NAME` restored to
+ * `.gitignore` in the same directory otherwise (#7366 D3) — so a scaffold
+ * never carries the packaging-only name. Exported (#8522 D3) as the one
+ * renderer of "the template's copy", shared by `copyTemplate` and by
+ * `create-ailk update`'s render of a running or an old template version.
+ */
+export declare function templateDestination(rel: string): string | undefined;
+/**
+ * The bytes a template-relative file copies as, at its destination path
+ * (#8522 D3): workspace versions plus markers for `package.json`, markers
+ * for `isTextFile`, raw bytes otherwise. Exported so `copyTemplate`'s walk
+ * and `create-ailk update`'s render of a running or an old template version
+ * share the one renderer — nothing about the copy itself changes.
+ */
+export declare function renderTemplateFile(bytes: Uint8Array, destRel: string, versions: WorkspaceVersionMap, markers: MarkerMap): Uint8Array;
 export declare function copyTemplate(opts: CopyTemplateOptions): void;

package/dist/copy.js

@@ -17,8 +17,23 @@
  *     alike. Symlinks are skipped outright (never followed, never copied) —
  *     the snapshotted templates/ tree is built without symlinks; any symlink
  *     present at scaffold time is treated as a packaging accident and ignored.
+ *
+ * Packed ignore files (#7366):
+ *   - npm and pnpm strip every file literally named `.gitignore` from a
+ *     packed tarball, so `build-templates.mjs` ships each snapshot
+ *     `.gitignore` under `PACKED_GITIGNORE_NAME` (`_gitignore`) instead. A
+ *     file named `PACKED_GITIGNORE_NAME` is restored to `.gitignore` in the
+ *     same directory on the way into a scaffold, classified and
+ *     marker-substituted exactly as a `.gitignore` is today (its destination
+ *     relative path, not its source name, drives `isTextFile`). A directory
+ *     carrying both `.gitignore` and `PACKED_GITIGNORE_NAME` is refused
+ *     outright, before either is written, rather than resolved by
+ *     `readdir()` order. `.npmignore` — the packaging-only sibling
+ *     `build-templates.mjs` writes beside each `PACKED_GITIGNORE_NAME` to
+ *     keep pack-time exclusions working — is skipped like `.gitkeep`: it
+ *     never belongs in a scaffold.
  */
-import { copyFileSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { extname, join, relative, resolve, sep } from "node:path";
 import pkg from "../package.json" with { type: "json" };
 import { substituteMarkers, substituteWorkspaceVersions, } from "./substitute.js";
@@ -57,8 +72,10 @@ export function buildScaffoldMarkers(projectName) {
  * Whether a walked template-relative path is inside (or equal to) an excluded
  * directory. Compares `/`-normalized paths so the check holds on Windows, and
  * only at a directory boundary — a prefix that stops mid-segment is no match.
+ * Exported (#8522 D3) so `create-ailk update` applies the same surface-gating
+ * boundary to a candidate new file.
  */
-function isExcluded(relativePath, excluded) {
+export function isExcluded(relativePath, excluded) {
     if (excluded.length === 0)
         return false;
     const rel = relativePath.split(sep).join("/");
@@ -71,6 +88,14 @@ function isExcluded(relativePath, excluded) {
     }
     return false;
 }
+/**
+ * The pack-safe name `build-templates.mjs` ships each snapshot `.gitignore`
+ * under (#7366 D1) — npm and pnpm strip a file literally named `.gitignore`
+ * from a packed tarball, but keep one named `_gitignore`. One definition,
+ * imported by `build-templates.mjs` (from the compiled `dist/copy.js`) and
+ * by `copyTemplate` below, so the two can never spell it differently.
+ */
+export const PACKED_GITIGNORE_NAME = "_gitignore";
 /** File extensions whose content we treat as text (and run markers over). */
 const TEXT_EXTS = new Set([
     ".md",
@@ -113,6 +138,46 @@ function isPackageJson(relativePath) {
     const base = relativePath.split(/[\\/]/).pop() ?? "";
     return base === "package.json";
 }
+/**
+ * The destination path a template-relative path (`/`-separated) copies to —
+ * `undefined` for a packaging-only `.gitkeep` or `.npmignore` (never a
+ * scaffold file), and a final `PACKED_GITIGNORE_NAME` restored to
+ * `.gitignore` in the same directory otherwise (#7366 D3) — so a scaffold
+ * never carries the packaging-only name. Exported (#8522 D3) as the one
+ * renderer of "the template's copy", shared by `copyTemplate` and by
+ * `create-ailk update`'s render of a running or an old template version.
+ */
+export function templateDestination(rel) {
+    const parts = rel.split("/");
+    const last = parts.length - 1;
+    if (last < 0)
+        return undefined;
+    if (parts[last] === ".gitkeep" || parts[last] === ".npmignore") {
+        return undefined;
+    }
+    if (parts[last] === PACKED_GITIGNORE_NAME) {
+        parts[last] = ".gitignore";
+    }
+    return parts.join("/");
+}
+/**
+ * The bytes a template-relative file copies as, at its destination path
+ * (#8522 D3): workspace versions plus markers for `package.json`, markers
+ * for `isTextFile`, raw bytes otherwise. Exported so `copyTemplate`'s walk
+ * and `create-ailk update`'s render of a running or an old template version
+ * share the one renderer — nothing about the copy itself changes.
+ */
+export function renderTemplateFile(bytes, destRel, versions, markers) {
+    if (isPackageJson(destRel)) {
+        const text = Buffer.from(bytes).toString("utf8");
+        return Buffer.from(substituteMarkers(substituteWorkspaceVersions(text, versions), markers), "utf8");
+    }
+    if (isTextFile(destRel)) {
+        const text = Buffer.from(bytes).toString("utf8");
+        return Buffer.from(substituteMarkers(text, markers), "utf8");
+    }
+    return Buffer.from(bytes);
+}
 export function copyTemplate(opts) {
     const templatesAbs = resolve(opts.templatesDir);
     const targetAbs = resolve(opts.targetDir);
@@ -124,19 +189,30 @@ export function copyTemplate(opts) {
         if (dir === undefined)
             break;
         const entries = readdirSync(dir, { withFileTypes: true });
+        // A directory carrying both the live name and the packed name would
+        // otherwise resolve by `readdir()` order — refuse outright, before
+        // writing either (#7366 D3).
+        const names = new Set(entries.map((entry) => entry.name));
+        if (names.has(".gitignore") && names.has(PACKED_GITIGNORE_NAME)) {
+            throw new Error(`templates directory carries both .gitignore and ${PACKED_GITIGNORE_NAME}: ${dir}`);
+        }
         for (const entry of entries) {
-            // .gitkeep is a packaging artifact for the empty-templates state in git;
-            // never propagate it to scaffolder output.
-            if (entry.name === ".gitkeep")
-                continue;
             const srcPath = join(dir, entry.name);
-            const rel = relative(templatesAbs, srcPath);
+            const rel = relative(templatesAbs, srcPath).split(sep).join("/");
             // Surface gating (#4154): a route directory belonging to a surface the
             // declared architecture does not carry is skipped outright — the route is
             // ABSENT from the scaffold, not present-and-serving-a-placeholder.
             if (isExcluded(rel, excluded))
                 continue;
-            const dstPath = join(targetAbs, rel);
+            // The destination path: `undefined` drops a packaging-only .gitkeep /
+            // .npmignore (#7366 D3); otherwise a packed .gitignore's name is
+            // restored. Everything below — the path-safety check, text
+            // classification, and marker substitution — runs on THIS path, never
+            // the source name.
+            const destRel = templateDestination(rel);
+            if (destRel === undefined)
+                continue;
+            const dstPath = join(targetAbs, destRel);
             // Path-safety guard: dstPath MUST be within targetAbs. Use `path.sep`
             // so the check holds on Windows (`\\`) as well as POSIX (`/`).
             const resolvedDst = resolve(dstPath);
@@ -152,19 +228,9 @@ export function copyTemplate(opts) {
                 stack.push(srcPath);
                 continue;
             }
-            if (isPackageJson(rel)) {
-                const text = readFileSync(srcPath, "utf8");
-                const transformed = substituteMarkers(substituteWorkspaceVersions(text, opts.versions), opts.markers);
-                writeFileSync(dstPath, transformed);
-            }
-            else if (isTextFile(rel)) {
-                const text = readFileSync(srcPath, "utf8");
-                writeFileSync(dstPath, substituteMarkers(text, opts.markers));
-            }
-            else {
-                // Binary or unknown — copy verbatim.
-                copyFileSync(srcPath, dstPath);
-            }
+            const rendered = renderTemplateFile(readFileSync(srcPath), destRel, opts.versions, opts.markers);
+            writeFileSync(dstPath, rendered);
+            opts.onWrite?.(destRel, rendered);
         }
     }
 }

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;