create-ailk 0.8.0 → 0.10.0

package/dist/add-module.d.ts

@@ -71,6 +71,26 @@ export interface AddModuleResult {
  * everything before it copies).
  */
 export declare function applyModuleToScaffold(opts: ApplyModuleOptions): Promise<AddModuleResult>;
+/**
+ * Whether an existing nav-config.ts is still unedited (#6908 D3), so
+ * `syncNavConfig` may safely overwrite it with the new surface set's render.
+ *
+ * A valid self-hashing stamp (`readNavConfigStamp`, surfaces.ts D1) proves
+ * the file unedited whatever generator wrote it — F2. A stamp that fails its
+ * hash is edited and never also tried against the legacy renders (F4). With
+ * no stamp at all, the file is unedited only when it byte-equals (after CRLF
+ * folding) one of the closed set of published pre-stamp generators'
+ * `before`-surface renders (F3) — the only sites this branch can ever apply
+ * to, since every nav a stamped generator writes carries a stamp.
+ */
+export declare function isUneditedNav(existing: string, before: string[]): boolean;
+/**
+ * Regenerate the site nav (`scaffoldSync` writes it from the surface set) for
+ * the new surfaces — but only when the site's copy is still unedited
+ * (`isUneditedNav`). An edited nav is the customer's file: left as-is and
+ * reported `skipped` with the change, like any other.
+ */
+export declare function syncNavConfig(targetAbs: string, before: string[], after: string[]): InstallReportRow | undefined;
 /** The report `add-module` prints. */
 export declare function formatAddModuleReport(result: AddModuleResult, moduleName: string): string;
 export interface AddModuleArgs {

package/dist/add-module.js

@@ -30,11 +30,13 @@ import { basename, dirname, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { AddModuleRefusedError, readArchitectureHeader, } from "./add-module-core.js";
 import { deriveArchitecture } from "./derive-architecture.js";
+import { LEGACY_NAV_RENDERERS } from "./legacy-nav-renderers.js";
+import { writeAuthSecretFile } from "./lib/auth-secret-file.js";
 import { diffTwoStrings, extractModuleBundle, } from "./lib/extract-module-bundle.js";
 import { normalizeModules } from "./module-architecture.js";
 import { ParseError, parseModules } from "./parse-args.js";
 import { SITE_ROSTER_PATH, moduleRosterRows, planRosterAppend, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
-import { MODULE_SURFACES, NAV_CONFIG_PATH, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
+import { MODULE_SURFACES, NAV_CONFIG_PATH, readNavConfigStamp, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
 import { syncRoutes } from "./sync-routes.js";
 export { AddModuleRefusedError, readArchitectureHeader };
 /** `package.json` paths a `json` patch may write under the plus-config policy. */
@@ -117,6 +119,10 @@ export async function applyModuleToScaffold(opts) {
         apply: true,
         forceSurfaces: MODULE_SURFACES[opts.moduleName] ?? [],
     });
+    // #6107 D8 — a module that brings `apps/admin` brings its auth hard-fail;
+    // the Admin app gets the web app's effective secret, and a secret already
+    // held in any Next-loaded env file is never shadowed.
+    writeAuthSecretFile(targetAbs);
     // The same composition `syncArchitectureSync` writes — a pure function of
     // the module set, so an unchanged set rewrites identical bytes.
     writeFileSync(archPath, deriveArchitecture(modules, surfaces));
@@ -174,21 +180,51 @@ export async function applyModuleToScaffold(opts) {
     }
     return { targetDir: targetAbs, modules, report: rows, routes, roster };
 }
+/**
+ * Whether an existing nav-config.ts is still unedited (#6908 D3), so
+ * `syncNavConfig` may safely overwrite it with the new surface set's render.
+ *
+ * A valid self-hashing stamp (`readNavConfigStamp`, surfaces.ts D1) proves
+ * the file unedited whatever generator wrote it — F2. A stamp that fails its
+ * hash is edited and never also tried against the legacy renders (F4). With
+ * no stamp at all, the file is unedited only when it byte-equals (after CRLF
+ * folding) one of the closed set of published pre-stamp generators'
+ * `before`-surface renders (F3) — the only sites this branch can ever apply
+ * to, since every nav a stamped generator writes carries a stamp.
+ */
+export function isUneditedNav(existing, before) {
+    const stamp = readNavConfigStamp(existing);
+    if (stamp === "valid")
+        return true;
+    if (stamp === "invalid")
+        return false;
+    const folded = existing.replace(/\r\n/g, "\n");
+    return LEGACY_NAV_RENDERERS.some((r) => folded === r.render(before));
+}
 /**
  * Regenerate the site nav (`scaffoldSync` writes it from the surface set) for
- * the new surfaces — but only when the site's copy is still exactly what the
- * OLD surface set generates. An edited nav is the customer's file: left as-is
- * and reported `skipped` with the change, like any other.
+ * the new surfaces — but only when the site's copy is still unedited
+ * (`isUneditedNav`). An edited nav is the customer's file: left as-is and
+ * reported `skipped` with the change, like any other.
  */
-function syncNavConfig(targetAbs, before, after) {
+export function syncNavConfig(targetAbs, before, after) {
     const navPath = join(targetAbs, NAV_CONFIG_PATH);
-    const wanted = renderNavConfig(after);
+    // #6878 D6 — a finished site already has `content/en/Service` (it exists
+    // on ANY site that ever enabled the `services` surface), so read the
+    // SAME service slugs for the `wanted` render.
+    const serviceContentDir = join(targetAbs, "content", "en", "Service");
+    const serviceSlugs = existsSync(serviceContentDir)
+        ? readdirSync(serviceContentDir)
+            .filter((f) => f.endsWith(".mdx"))
+            .map((f) => f.slice(0, -".mdx".length))
+        : [];
+    const wanted = renderNavConfig(after, { serviceSlugs });
     const existing = existsSync(navPath)
         ? readFileSync(navPath, "utf8")
         : undefined;
     if (existing === wanted)
         return undefined;
-    if (existing === undefined || existing === renderNavConfig(before)) {
+    if (existing === undefined || isUneditedNav(existing, before)) {
         writeFileSync(navPath, wanted);
         return { path: NAV_CONFIG_PATH, action: "written" };
     }

package/dist/add-route.d.ts

@@ -0,0 +1,56 @@
+import { type InstallReportRow } from "./lib/extract-module-bundle.js";
+import type { MarkerMap, WorkspaceVersionMap } from "./substitute.js";
+import { type SyncRoutesResult } from "./sync-routes.js";
+/** A refusal the CLI exits 2 on, thrown before anything is written. */
+export declare class AddRouteRefusedError extends Error {
+    readonly exitCode = 2;
+    constructor(message: string);
+}
+export interface AddRouteOptions {
+    /** The already-scaffolded site. */
+    targetDir: string;
+    /** The route family to add — one `--surfaces` id, e.g. `pricing`. */
+    route: string;
+    /** Workspace version map, for the route copy. */
+    versions: WorkspaceVersionMap;
+    /** The scaffold's marker map (`buildScaffoldMarkers`). */
+    markers: MarkerMap;
+    /** The package's `templates/` dir — the route source and the overlay's seeds. */
+    templatesDir: string;
+    /** The package's `site-templates/` dir — the `_base` layer's seeds. */
+    siteTemplatesDir: string;
+}
+export interface AddRouteResult {
+    /** Resolved absolute path to the site. */
+    targetDir: string;
+    /** The canonical route id added. */
+    route: string;
+    /** The surface set `architecture.yaml` now declares. */
+    surfaces: string[];
+    /** One row per seed or nav written or skipped — empty when nothing changed. */
+    report: InstallReportRow[];
+    /** The route sync run over the surface — absent when the site already declares it. */
+    routes?: SyncRoutesResult;
+}
+/**
+ * Add one gateable route surface to an existing site. Every refusal — an
+ * unknown route, a route another module delivers, an unreadable header —
+ * throws before the first write.
+ */
+export declare function addRouteToScaffold(opts: AddRouteOptions): AddRouteResult;
+/** The report `add-route` prints. */
+export declare function formatAddRouteReport(result: AddRouteResult): string;
+export interface AddRouteArgs {
+    /** The route to add; undefined only with `help`. */
+    route: string | undefined;
+    /** Positional target directory; undefined = the caller's cwd. */
+    target: string | undefined;
+    help: boolean;
+}
+export declare const ADD_ROUTE_HELP = "create-ailk add-route \u2014 add a route family to an existing site.\n\nUsage:\n  create-ailk add-route <route> [<target-dir>]\n\nArguments:\n  <route>                  One route family, named as --surfaces names it,\n                           e.g. pricing.\n  <target-dir>             An already-scaffolded repo (contains\n                           architecture.yaml). Defaults to the current dir.\n\nOptions:\n  --help, -h               Print this message.\n\nCopies the route's pages, writes its seed content, declares it in\narchitecture.yaml and adds its link to the generated nav \u2014 the site a fresh\nscaffold with --surfaces <route> would have been. A file the site already has\nis never overwritten: one whose content differs, a hand-edited nav included,\nis left as-is and listed for manual review with the change the route wanted.\nLike add-module, it also restores any other page route the site carries but\nlacks. A route a module delivers (blog and docs come with docs-blog) is\nrefused; add that module with create-ailk add-module. Running it again changes\nnothing.\n";
+/**
+ * Parse the argv AFTER the `add-route` word. Strict `node:util` parseArgs,
+ * like `parseAddModuleArgs`; the route itself is validated by
+ * `addRouteToScaffold`, which refuses an unknown one naming the recognized.
+ */
+export declare function parseAddRouteArgs(argv: string[]): AddRouteArgs;

package/dist/add-route.js

@@ -0,0 +1,286 @@
+/**
+ * `create-ailk add-route <route> [<target-dir>]` — add a route family the
+ * site was scaffolded without, in place (#6947).
+ *
+ * A site gets only the route surfaces its shape and level declared at
+ * scaffold time: `sync-routes` skips a surface gated off then, and
+ * `add-module` adds only a paid module's surfaces. So nothing else can give
+ * a person-service site `/pricing`. This is `add-module`'s machinery minus the
+ * licence and the bundle:
+ *
+ *   - `architecture.yaml`'s header is read, and the new surface resolved
+ *     against the site's module set — a route another module delivers is
+ *     refused, naming the module and `add-module`, before any write;
+ *   - the surface's route dirs are synced in (`syncRoutes` with it forced
+ *     carried), `architecture.yaml` is regenerated with it declared, and the
+ *     nav follows unless the site has edited it (`syncNavConfig`);
+ *   - the surface's seed content is written from the two shared layers a
+ *     fresh scaffold keeps it from (the `templates/` overlay, then `_base`),
+ *     never over a file the site already has.
+ *
+ * The result is the site a fresh scaffold with `--surfaces <route>` would
+ * have been. That scaffold adds no row to `.ailk-site-manifest.json` for a
+ * surface (the roster names only the template's own pages), so neither does
+ * this. A route the site already declares is a no-op: a second run changes
+ * nothing, even where the site has since deleted a seed.
+ *
+ * Pure module: no `import.meta.url`, so jest can import it directly — the
+ * package-rooted inputs are supplied by the CLI, the `add-module.ts` split.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { AddModuleRefusedError, readArchitectureHeader, syncNavConfig, } from "./add-module.js";
+import { isTextFile } from "./copy.js";
+import { deriveArchitecture } from "./derive-architecture.js";
+import { diffTwoStrings, } from "./lib/extract-module-bundle.js";
+import { ParseError } from "./parse-args.js";
+import { substituteMarkers } from "./substitute.js";
+import { GATEABLE_SURFACES, MODULE_SURFACES, parseSurfaces, resolveSurfaces, } from "./surfaces.js";
+import { syncRoutes } from "./sync-routes.js";
+import { BASE_LAYER_DIR } from "./template-manifest.js";
+/** A refusal the CLI exits 2 on, thrown before anything is written. */
+export class AddRouteRefusedError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "AddRouteRefusedError";
+    }
+}
+/**
+ * Add one gateable route surface to an existing site. Every refusal — an
+ * unknown route, a route another module delivers, an unreadable header —
+ * throws before the first write.
+ */
+export function addRouteToScaffold(opts) {
+    const targetAbs = resolve(opts.targetDir);
+    if (!existsSync(targetAbs)) {
+        throw new Error(`add-route target does not exist: ${targetAbs}. Point add-route at an already-scaffolded repo.`);
+    }
+    if (!statSync(targetAbs).isDirectory()) {
+        throw new Error(`add-route target is not a directory: ${targetAbs}`);
+    }
+    const archPath = join(targetAbs, "architecture.yaml");
+    if (!existsSync(archPath)) {
+        throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
+    }
+    const route = canonicalRoute(opts.route);
+    const owner = Object.entries(MODULE_SURFACES).find(([, surfaces]) => surfaces.includes(route))?.[0];
+    let current;
+    try {
+        current = readArchitectureHeader(readFileSync(archPath, "utf8"));
+    }
+    catch (err) {
+        if (err instanceof AddModuleRefusedError) {
+            throw new AddRouteRefusedError(err.message);
+        }
+        throw err;
+    }
+    if (owner !== undefined &&
+        !current.modules.includes(owner)) {
+        throw new AddRouteRefusedError(`route "${route}" is delivered by the "${owner}" module, which this site does not carry — add it with \`create-ailk add-module ${owner}\``);
+    }
+    let declared;
+    let surfaces;
+    try {
+        declared = resolveSurfaces(current.modules, current.surfaces);
+        surfaces = resolveSurfaces(current.modules, [...current.surfaces, route]);
+    }
+    catch (err) {
+        throw new AddRouteRefusedError(`architecture.yaml's \`# Surfaces:\` header cannot be carried forward: ${err.message}`);
+    }
+    if (declared.includes(route)) {
+        return { targetDir: targetAbs, route, surfaces, report: [] };
+    }
+    // add-module's sync: every in-scope route dir the site lacks is copied,
+    // not only this surface's — a fresh site lacks none but this one.
+    const routes = syncRoutes({
+        targetDir: targetAbs,
+        templatesDir: opts.templatesDir,
+        versions: opts.versions,
+        apply: true,
+        forceSurfaces: [route],
+    });
+    const report = seedSurfaceContent(targetAbs, route, opts);
+    const navRow = syncNavConfig(targetAbs, current.surfaces, surfaces);
+    if (navRow !== undefined)
+        report.push(navRow);
+    // Last: the declared header is what makes a rerun a no-op, so it is
+    // written only once every other step has landed.
+    writeFileSync(archPath, deriveArchitecture(current.modules, surfaces));
+    return { targetDir: targetAbs, route, surfaces, report, routes };
+}
+/** The canonical id for one route argument, refusing an unknown one. */
+function canonicalRoute(raw) {
+    let parsed;
+    try {
+        parsed = parseSurfaces(raw);
+    }
+    catch (err) {
+        throw new AddRouteRefusedError(err.message.replace(/^unknown surface/, "unknown route"));
+    }
+    const [route] = parsed;
+    if (route === undefined) {
+        throw new AddRouteRefusedError(`"${raw}" is not a route add-route can add`);
+    }
+    return route;
+}
+/**
+ * Write the surface's seed content the way a fresh `--surfaces <route>`
+ * scaffold keeps it: every file under the surface's content dirs in the
+ * `templates/` overlay, then in the `_base` layer (a later layer wins, as in
+ * `scaffold()`), with the scaffold's markers. A file the site already has is
+ * never overwritten — when its bytes differ it is reported `skipped` with the
+ * change the seed wanted.
+ */
+function seedSurfaceContent(targetAbs, route, opts) {
+    const dirs = (GATEABLE_SURFACES.find((s) => s.id === route)?.content ?? []).map((dir) => dir.replace("<locale>", "en"));
+    const sources = new Map();
+    for (const root of [
+        opts.templatesDir,
+        join(opts.siteTemplatesDir, BASE_LAYER_DIR),
+    ]) {
+        for (const dir of dirs)
+            collectFiles(root, dir, sources);
+    }
+    const report = [];
+    for (const [path, src] of [...sources].sort(([a], [b]) => a.localeCompare(b))) {
+        const isText = isTextFile(path);
+        const wanted = isText
+            ? Buffer.from(substituteMarkers(readFileSync(src, "utf8"), opts.markers))
+            : readFileSync(src);
+        const dest = join(targetAbs, path);
+        if (existsSync(dest)) {
+            const existing = readFileSync(dest);
+            if (existing.equals(wanted))
+                continue;
+            const encoding = isText ? "utf8" : "latin1";
+            report.push({
+                path,
+                action: "skipped",
+                wanted: diffTwoStrings(path, existing.toString(encoding), wanted.toString(encoding), isText),
+            });
+            continue;
+        }
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, wanted);
+        report.push({ path, action: "written" });
+    }
+    return report;
+}
+/** Every file under `root/dir`, recorded site-relative → absolute source. */
+function collectFiles(root, dir, out) {
+    const abs = join(root, dir);
+    if (!existsSync(abs))
+        return;
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+        const rel = `${dir}/${entry.name}`;
+        if (entry.isDirectory())
+            collectFiles(root, rel, out);
+        else if (entry.isFile() && entry.name !== ".gitkeep") {
+            out.set(rel, join(root, rel));
+        }
+    }
+}
+/** Indent a multi-line diff under its report row. */
+function indent(text) {
+    return text.split("\n").map((line) => `      ${line}`);
+}
+/** The report `add-route` prints. */
+export function formatAddRouteReport(result) {
+    const written = result.report.filter((row) => row.action === "written");
+    const skipped = result.report.filter((row) => row.action === "skipped");
+    const routes = result.routes ?? {
+        applied: [],
+        appliedDependencies: [],
+        missingMessageNamespaces: [],
+    };
+    const lines = [
+        `[create-ailk] add-route ${result.route} → ${result.targetDir}`,
+    ];
+    if (result.report.length === 0 && routes.applied.length === 0) {
+        lines.push(`Nothing to add — the site already carries the ${result.route} route.`);
+    }
+    if (routes.applied.length > 0) {
+        lines.push(`Routes copied (${routes.applied.length}):`);
+        lines.push(...routes.applied.map((route) => `  ${route}`));
+    }
+    if (routes.appliedDependencies.length > 0) {
+        lines.push(`Also copied ${routes.appliedDependencies.length} file(s) those routes import:`);
+        lines.push(...routes.appliedDependencies.map((dep) => `  ${dep}`));
+    }
+    if (written.length > 0) {
+        lines.push(`Written (${written.length}):`);
+        lines.push(...written.map((row) => `  ${row.path}`));
+    }
+    if (skipped.length > 0) {
+        lines.push(`Needs manual review (${skipped.length}) — the site's copy differs from the one this route brings and was left untouched. Apply the change by hand if you want it:`);
+        for (const row of skipped) {
+            lines.push(`  ${row.path}`);
+            if (row.action === "skipped")
+                lines.push(...indent(row.wanted));
+        }
+    }
+    if (routes.missingMessageNamespaces.length > 0) {
+        lines.push("Also required — message namespace(s) not found in apps/web/messages/en.json (add manually, not auto-merged):");
+        lines.push(...routes.missingMessageNamespaces.map((ns) => `  ${ns}`));
+    }
+    lines.push(`architecture.yaml surfaces: ${result.surfaces.length > 0 ? result.surfaces.join(", ") : "core only"}`);
+    if (written.length > 0 || routes.applied.length > 0) {
+        lines.push("Next: pnpm build.");
+    }
+    return lines.join("\n") + "\n";
+}
+export const ADD_ROUTE_HELP = `create-ailk add-route — add a route family to an existing site.
+
+Usage:
+  create-ailk add-route <route> [<target-dir>]
+
+Arguments:
+  <route>                  One route family, named as --surfaces names it,
+                           e.g. pricing.
+  <target-dir>             An already-scaffolded repo (contains
+                           architecture.yaml). Defaults to the current dir.
+
+Options:
+  --help, -h               Print this message.
+
+Copies the route's pages, writes its seed content, declares it in
+architecture.yaml and adds its link to the generated nav — the site a fresh
+scaffold with --surfaces <route> would have been. A file the site already has
+is never overwritten: one whose content differs, a hand-edited nav included,
+is left as-is and listed for manual review with the change the route wanted.
+Like add-module, it also restores any other page route the site carries but
+lacks. A route a module delivers (blog and docs come with docs-blog) is
+refused; add that module with create-ailk add-module. Running it again changes
+nothing.
+`;
+/**
+ * Parse the argv AFTER the `add-route` word. Strict `node:util` parseArgs,
+ * like `parseAddModuleArgs`; the route itself is validated by
+ * `addRouteToScaffold`, which refuses an unknown one naming the recognized.
+ */
+export function parseAddRouteArgs(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        strict: true,
+        allowPositionals: true,
+        options: {
+            help: { type: "boolean", default: false, short: "h" },
+        },
+    });
+    const help = parsed.values.help === true;
+    const [route, target, ...rest] = parsed.positionals;
+    if (rest.length > 0) {
+        throw new ParseError(`expected a route and at most one target directory, got ${parsed.positionals.length} arguments`);
+    }
+    if (route === undefined) {
+        if (help)
+            return { route: undefined, target: undefined, help };
+        throw new ParseError("add-route needs a route name, e.g. `create-ailk add-route pricing`");
+    }
+    if (route.includes(",")) {
+        throw new ParseError(`add-route takes exactly one route, got "${route}" — run it once per route`);
+    }
+    return { route, target, help };
+}

package/dist/apply-design-md.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The text `<siteDir>/DESIGN.md` should hold to wear the design in
+ * `designDir`: the design's DESIGN.md under the site's own header lines. A
+ * header line the site carries and the design does not goes in a comment
+ * block after the frontmatter.
+ */
+export declare function planDesignMd(designDir: string, siteDir: string): string;

package/dist/apply-design-md.js

@@ -0,0 +1,50 @@
+/**
+ * A site's root `DESIGN.md` is the design it wears (#6939). `scaffold()` and
+ * `apply-design` both replace it with the resolved design's own DESIGN.md.
+ *
+ * Every shipped copy of a design's DESIGN.md differs only in its "Source
+ * template" line (and its `{{CREATE_AILK_VERSION}}` stamp), so the site keeps
+ * its own copy of those two header lines: upgrade-plan's `readSite` reads the
+ * site's template from "Source template", and "Version" records the
+ * create-ailk that generated the site. The design's own values never stand in
+ * for the site's: a "Source template" line the site lacks is dropped (the
+ * design's `designs/<name>` is not a template), and a "Version" line is
+ * stamped with this create-ailk.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import pkg from "../package.json" with { type: "json" };
+/** The two header lines a site's DESIGN.md keeps across a design change. */
+const SOURCE_TEMPLATE_LINE = /^[ \t]*Source template:.*$/m;
+const VERSION_LINE = /^[ \t]*Version:.*$/m;
+/**
+ * The text `<siteDir>/DESIGN.md` should hold to wear the design in
+ * `designDir`: the design's DESIGN.md under the site's own header lines. A
+ * header line the site carries and the design does not goes in a comment
+ * block after the frontmatter.
+ */
+export function planDesignMd(designDir, siteDir) {
+    const sitePath = join(siteDir, "DESIGN.md");
+    const current = existsSync(sitePath) ? readFileSync(sitePath, "utf8") : "";
+    let next = readFileSync(join(designDir, "DESIGN.md"), "utf8").replaceAll("{{CREATE_AILK_VERSION}}", pkg.version);
+    const missing = [];
+    for (const line of [SOURCE_TEMPLATE_LINE, VERSION_LINE]) {
+        const kept = line.exec(current)?.[0];
+        if (kept === undefined) {
+            if (line === SOURCE_TEMPLATE_LINE)
+                next = next.replace(/^[ \t]*Source template:.*\n/m, "");
+        }
+        else if (line.test(next)) {
+            next = next.replace(line, () => kept);
+        }
+        else {
+            missing.push(kept);
+        }
+    }
+    if (missing.length === 0)
+        return next;
+    const close = next.startsWith("---\n") ? next.indexOf("\n---\n", 4) : -1;
+    const at = close === -1 ? 0 : close + "\n---\n".length;
+    const block = `\n<!--\n${missing.join("\n")}\n-->\n`;
+    return `${next.slice(0, at)}${block}${next.slice(at)}`;
+}

package/dist/apply-design.d.ts

@@ -0,0 +1,64 @@
+export interface ApplyDesignOptions {
+    /** The design: a shipped name, or a directory holding a DESIGN.md. */
+    design: string;
+    /** The existing site (absolute or relative). */
+    targetDir: string;
+    /** Package-rooted inputs, supplied by the caller (cli.ts from its PKG_ROOT). */
+    designsDir: string;
+    siteTemplatesDir: string;
+    catalogPath: string;
+    /** Where a relative design path resolves from. Default process.cwd(). */
+    cwd?: string;
+    /** Read for AILK_LICENSE_KEY only (D6). Default process.env. */
+    env?: NodeJS.ProcessEnv;
+    /** Forwarded to deriveLevel. Tests inject; the CLI leaves them unset. */
+    registryUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+export type ApplyDesignChange = {
+    path: string;
+    kind: "theme";
+} | {
+    path: string;
+    kind: "layout";
+} | {
+    path: string;
+    kind: "design";
+} | {
+    path: string;
+    kind: "preset";
+    fields: string[];
+} | {
+    path: string;
+    kind: "manifest";
+};
+export interface ApplyDesignResult {
+    targetDir: string;
+    design: string;
+    display: string;
+    /** In write order (D4); [] when nothing changed. */
+    changes: ApplyDesignChange[];
+    manifest: "recorded" | "unchanged" | "no-roster" | "legacy-roster";
+    /** The site-relative roster file, when there is one. */
+    rosterPath?: string;
+}
+export interface ApplyDesignArgs {
+    design: string | undefined;
+    target: string | undefined;
+    help: boolean;
+}
+export declare const APPLY_DESIGN_HELP = "create-ailk apply-design \u2014 make an existing site wear a design.\n\nUsage:\n  create-ailk apply-design <name> [--target <site-dir>]\n  create-ailk apply-design <path> [--target <site-dir>]\n\nArguments:\n  <name|path>              A shipped design (standard, minimalism), or a\n                           directory holding a DESIGN.md. A relative path\n                           resolves from the current directory.\n\nOptions:\n  --target <site-dir>      An already-scaffolded repo (contains\n                           architecture.yaml). Defaults to the current dir.\n  --help, -h               Print this message.\n\nWrites only the look: DESIGN.md (replaced whole by the design's, keeping the\nsite's Source template and Version lines), the theme: block of\ncontent/_site.mdx, the generated apps/web/lib/site-chrome.ts, the look fields\nof sections the site's pages already place, and the design/layout/theme record\nin .ailk-site-manifest.json.\nNever adds, removes or renames a route or page, never touches a content field\nor the brand: block, and leaves every page's structured data unchanged.\n\nA design other than standard needs a Pro or Pro Plus key: the site's own\nailk.key (put one there with create-ailk license set <key>), else\nAILK_LICENSE_KEY. A malformed package, a preset the validator refuses or a\nmissing key is refused before any file is written.\n\nA preset sets the look fields it names and never unsets one: a field it does\nnot name keeps whatever value the page has. Running it again changes nothing.\n";
+/**
+ * Parse the argv AFTER the `apply-design` word (D1). Strict `node:util`
+ * parseArgs, like `parseSyncRoutesArgs`: exactly one positional, the design
+ * reference, and an optional `--target`.
+ */
+export declare function parseApplyDesignArgs(argv: string[]): ApplyDesignArgs;
+/**
+ * Apply a design to an existing site (D2–D7). Refuses before any write
+ * (C1–C6); otherwise writes only the files whose text changes — page files,
+ * `site-chrome.ts`, `DESIGN.md`, `_site.mdx`, then the manifest last.
+ */
+export declare function applyDesign(opts: ApplyDesignOptions): Promise<ApplyDesignResult>;
+/** The changed-file report (D9). */
+export declare function formatApplyDesignReport(result: ApplyDesignResult): string;