create-ailk 0.6.1 → 0.7.0

package/dist/programmatic.js

@@ -15,21 +15,23 @@
  *   import { scaffoldSync } from './programmatic.js';
  *   const result = scaffoldSync({ targetDir: '/tmp/my-site', projectName: 'my-site' });
  */
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { existsSync, readdirSync, readFileSync, rmdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { AddModuleRefusedError, applyModuleToScaffold, } from "./add-module.js";
 import { CATALOG_TARGET_PATH, writeComponentCatalog, } from "./component-catalog.js";
 import { buildScaffoldMarkers, copyTemplate } from "./copy.js";
 import { deriveArchitecture } from "./derive-architecture.js";
 import { extractModuleBundle, installBundleTree, } from "./lib/extract-module-bundle.js";
 import { fetchTemplate } from "./lib/fetch-template.js";
+import { assertLicenseKeyShape, writeLicenseKeyFiles, } from "./lib/license-key-files.js";
 import { resolvePaidModules } from "./lib/module-license-gate.js";
 import { classifyModules } from "./lib/module-tier.js";
 import { normalizeModules } from "./module-architecture.js";
 import { SITE_CHROME_PATH, renderSiteChrome, resolveSiteChrome, } from "./site-chrome.js";
 import { GATEABLE_SURFACES, MODULE_SURFACES, NAV_CONFIG_PATH, excludedRoutePaths, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
 import { syncRoutes } from "./sync-routes.js";
-import { BASE_LAYER_DIR, mergeRoster, resolveTemplate, resolveTemplateLineage, templateDelivery, } from "./template-manifest.js";
+import { BASE_LAYER_DIR, STARTER_DESIGNS, TemplateError, mergeRoster, resolveTemplate, resolveTemplateLineage, rosterDeclares, templateDelivery, } from "./template-manifest.js";
 import { validateTarget } from "./validate.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const TEMPLATES_DIR = resolve(PKG_ROOT, "templates");
@@ -110,7 +112,7 @@ export function scaffoldSync(opts) {
     // template's `layout` block; a bare `scaffoldSync` call (every existing
     // synchronous caller) writes DEFAULT_SITE_CHROME, byte-identical to the
     // monorepo's own committed apps/web/lib/site-chrome.ts.
-    writeFileSync(join(targetAbs, SITE_CHROME_PATH), renderSiteChrome(resolveSiteChrome(opts.layout)));
+    writeFileSync(join(targetAbs, SITE_CHROME_PATH), renderSiteChrome(resolveSiteChrome(opts.layout, opts.design)));
     // Opt-in only (#4636). Every write above this line is unconditional, so a
     // scaffold with `withCatalog` unset touches exactly the files it did before.
     if (opts.withCatalog === true)
@@ -146,10 +148,21 @@ export function scaffoldSync(opts) {
  * with a paid module in `opts.modules` exercises the gate at all.
  */
 export async function scaffold(opts) {
+    // #6683 D9 — refused before anything is fetched or written, like the
+    // template and design refusals below. The message never repeats the value.
+    if (opts.license !== undefined)
+        assertLicenseKeyShape(opts.license);
+    const licenseKey = opts.license ?? opts.licenseKey;
     // Resolved first, and by the registry rather than re-validated here: the
     // name already passed `parse-args.ts`, and `resolveTemplate` throws a
     // `TemplateError` for a programmatic caller that skipped the parser.
     const template = opts.template !== undefined ? resolveTemplate(opts.template) : undefined;
+    // #6638 — the design this scaffold renders: the caller's override, else the
+    // template's own. Unset for a scaffold naming neither.
+    const design = opts.design ?? template?.design;
+    if (design !== undefined && !STARTER_DESIGNS.includes(design)) {
+        throw new TemplateError(`unknown design "${design}". Declared: ${STARTER_DESIGNS.join(", ")}`);
+    }
     // #5618 D2 — the `extends` chain is resolved in the client registry before
     // any fetch: an unknown parent or a cycle is refused here, with the target
     // still non-existent, like the four refusals below.
@@ -168,7 +181,7 @@ export async function scaffold(opts) {
     const { paid } = classifyModules(modules);
     const bundles = await resolvePaidModules({
         paidModules: paid,
-        licenseKey: opts.licenseKey,
+        licenseKey,
         ...(template !== undefined ? { templateName: template.name } : {}),
         ...(opts.moduleRegistryUrl !== undefined
             ? { registryUrl: opts.moduleRegistryUrl }
@@ -189,7 +202,7 @@ export async function scaffold(opts) {
     const templateBundle = template !== undefined && templateDelivery(template) === "paid"
         ? await fetchTemplate({
             templateName: template.name,
-            token: opts.licenseKey ?? process.env["AILK_LICENSE_KEY"] ?? "",
+            token: licenseKey ?? process.env["AILK_LICENSE_KEY"] ?? "",
             ...(opts.templateRegistryUrl !== undefined
                 ? { registryUrl: opts.templateRegistryUrl }
                 : {}),
@@ -224,9 +237,11 @@ export async function scaffold(opts) {
         ...(surfaces !== undefined ? { surfaces } : {}),
         // #5612 D1/D2 — the code registry's own `layout` block, known
         // synchronously (unlike a bundle's `ailk-template.json`, only readable
-        // after install below). A template declaring none resolves to the same
-        // defaults `scaffoldSync` already writes for a templateless scaffold.
+        // after install below). A template declaring none resolves to its
+        // design's knobs (#6638), and a `standard` one to the same defaults
+        // `scaffoldSync` already writes for a templateless scaffold.
         ...(template?.layout !== undefined ? { layout: template.layout } : {}),
+        ...(design !== undefined ? { design } : {}),
     });
     // Threaded to extractModuleBundle for `package.json` patch targets'
     // `workspace:*` substitution (spec 5418 § 3 D2) — the same version map
@@ -327,11 +342,66 @@ export async function scaffold(opts) {
                 });
             })();
         if (installed.layout !== undefined) {
-            writeFileSync(join(result.targetDir, SITE_CHROME_PATH), renderSiteChrome(resolveSiteChrome(installed.layout)));
+            writeFileSync(join(result.targetDir, SITE_CHROME_PATH), renderSiteChrome(resolveSiteChrome(installed.layout, design)));
         }
+        pruneUnrosteredSeeds(result.targetDir, mergeRoster(template, template.requires), result.surfaces, ownership);
+    }
+    // #6683 D9 — persisted only after every layer landed, and only when the
+    // caller passed `license`: a scaffold without it writes nothing new.
+    if (opts.license !== undefined) {
+        writeLicenseKeyFiles(result.targetDir, opts.license);
     }
     return result;
 }
+/**
+ * The per-row install of the two SHARED seed layers (#6646 D1, disposition
+ * (b)): with every layer landed, remove each `content/en/**.mdx` that the
+ * `templates/` snapshot (the overlay — no `ownership` entry) or the `_base`
+ * layer wrote and no merged roster row names. Those two layers serve every
+ * template, so each carries seeds some templates do not roster (`/pricing`
+ * on a services site); a template's own tree and its modules' bundles are
+ * never pruned — a seed THEY ship without a row is drift, which the manifest
+ * generator's `--check` fails on instead.
+ *
+ * Merged over the template's own `requires`, as `rosterSurfaces` is: the
+ * rows that name shared-layer seeds are the template's own. A seed inside
+ * the content directory of a surface this scaffold ENABLES is kept too, so
+ * an explicit `--surfaces pricing` on a template that does not roster
+ * `/pricing` gets its route and its seed together.
+ */
+function pruneUnrosteredSeeds(targetDir, roster, surfaces, ownership) {
+    // `installBundleTree`'s ownership label for the base layer: it installs
+    // with `templateRequires: []`, so it records as a template. The overlay
+    // (the `templates/` snapshot) records no owner at all.
+    const shared = new Set([undefined, `template "${BASE_LAYER_DIR}"`]);
+    const enabledDirs = GATEABLE_SURFACES.filter((surface) => surfaces.includes(surface.id)).flatMap((surface) => surface.content.map((dir) => `${dir.replace("<locale>", "en")}/`));
+    const root = join(targetDir, "content", "en");
+    if (!existsSync(root))
+        return;
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            break;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(abs);
+                continue;
+            }
+            if (!entry.name.endsWith(".mdx"))
+                continue;
+            const path = relative(targetDir, abs).split(sep).join("/");
+            if (shared.has(ownership.get(path)) &&
+                !rosterDeclares(roster, path) &&
+                !enabledDirs.some((prefix) => path.startsWith(prefix))) {
+                rmSync(abs);
+                if (readdirSync(dir).length === 0)
+                    rmdirSync(dir);
+            }
+        }
+    }
+}
 /**
  * The MODULE-LESS gateable-surface ids a template's merged roster names
  * (#5469 D10): every `GATEABLE_SURFACES` entry no module contributes
@@ -478,6 +548,57 @@ export function syncRoutesSync(opts) {
         versions: readVersionMap(),
     });
 }
+/**
+ * Apply a purchased module to an already-scaffolded site in place
+ * (`create-ailk add-module`, #6653). The thin package-rooted wrapper around
+ * `add-module.ts`'s `applyModuleToScaffold`, the `syncRoutesSync` split:
+ *
+ *   1. the target must be an existing scaffold — the same check as the sync
+ *      subcommands above;
+ *   2. a free module is refused before any key read or network call — it
+ *      ships with every scaffold, there is no bundle to add;
+ *   3. `resolvePaidModules` — the SAME gate `scaffold()` runs, so a missing
+ *      key or a key that does not cover the module is refused with the
+ *      scaffold-time message, before anything is written;
+ *   4. the fetched bundle is merged under the plus-config policy.
+ */
+export async function addModule(opts) {
+    const targetAbs = resolve(opts.targetDir);
+    if (!existsSync(targetAbs)) {
+        throw new Error(`add-module target does not exist: ${targetAbs}. Point add-module at an already-scaffolded repo.`);
+    }
+    if (!statSync(targetAbs).isDirectory()) {
+        throw new Error(`add-module target is not a directory: ${targetAbs}`);
+    }
+    if (!existsSync(join(targetAbs, "architecture.yaml"))) {
+        throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
+    }
+    const { paid } = classifyModules([opts.moduleName]);
+    if (paid.length === 0) {
+        throw new AddModuleRefusedError(`"${opts.moduleName}" ships with every scaffold — there is no module bundle to add`);
+    }
+    const bundles = await resolvePaidModules({
+        paidModules: paid,
+        licenseKey: opts.licenseKey,
+        ...(opts.moduleRegistryUrl !== undefined
+            ? { registryUrl: opts.moduleRegistryUrl }
+            : {}),
+        ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+    });
+    const bundleBytes = bundles.get(opts.moduleName);
+    if (bundleBytes === undefined) {
+        throw new Error(`module "${opts.moduleName}": no bundle was resolved`);
+    }
+    return applyModuleToScaffold({
+        targetDir: targetAbs,
+        moduleName: opts.moduleName,
+        bundleBytes,
+        versions: readVersionMap(),
+        markers: buildScaffoldMarkers(basename(targetAbs)),
+        templatesDir: TEMPLATES_DIR,
+        siteTemplatesDir: SITE_TEMPLATES_DIR,
+    });
+}
 /** Re-exported so the CLI can name the file it wrote without duplicating it. */
 export { CATALOG_TARGET_PATH };
 /**

package/dist/site-chrome.d.ts

@@ -15,11 +15,17 @@
  * `apps/web/lib/site-chrome.ts` every scaffold gets — beside `nav-config.ts`,
  * the same GENERATED-header idiom (`surfaces.ts` `renderNavConfig`).
  *
- * Every field is optional and DEFAULTS to today's render (`full` / `columns`
- * / `true` / `default`) — a scaffold naming no template, or a template naming
- * no `layout` block, gets these defaults written, byte-identical to the
- * monorepo's own committed `apps/web/lib/site-chrome.ts`.
+ * Every field is optional and DEFAULTS to `full` / `columns` / `false` /
+ * `default` — the announcement banner is off unless a template turns it on
+ * (#6469). A scaffold naming no template, or a template naming no `layout`
+ * block, gets these defaults written, byte-identical to the monorepo's own
+ * committed `apps/web/lib/site-chrome.ts`.
+ *
+ * A template's DESIGN supplies layout knobs too (#6638): `DESIGN_LAYOUTS` in
+ * `template-manifest.ts`, read by `resolveSiteChrome`'s optional `design`
+ * argument between an explicit `layout` and these defaults.
  */
+import { type StarterDesign } from "./template-manifest.js";
 /** The `nav` knob's vocabulary. `mark-only` → the layout passes Nav an empty
  *  `navItems` (brand mark + the existing actions/theme/locale controls only). */
 export type SiteChromeNav = "full" | "mark-only";
@@ -47,7 +53,7 @@ export interface ResolvedSiteChrome {
     announcementBanner: boolean;
     home: SiteChromeHome;
 }
-/** Byte-identical-to-today defaults (#5612 D1). */
+/** Defaults (#5612 D1; banner off since #6469). */
 export declare const DEFAULT_SITE_CHROME: ResolvedSiteChrome;
 /** Template-relative path of the generated site-chrome registry — beside `NAV_CONFIG_PATH`. */
 export declare const SITE_CHROME_PATH = "apps/web/lib/site-chrome.ts";
@@ -68,8 +74,13 @@ export declare class TemplateLayoutError extends Error {
  * @param subject Caller-supplied context for the error message (e.g. `template "foo"`).
  */
 export declare function validateTemplateLayout(value: unknown, subject: string): TemplateLayout;
-/** Fill every field a `TemplateLayout` leaves unset with `DEFAULT_SITE_CHROME`'s value. */
-export declare function resolveSiteChrome(layout?: TemplateLayout): ResolvedSiteChrome;
+/**
+ * Fill every field a `TemplateLayout` leaves unset — from `design`'s
+ * `DESIGN_LAYOUTS` entry when one is named (#6638), then from
+ * `DEFAULT_SITE_CHROME`. The explicit `layout` wins field by field, so a
+ * template can wear a design and still override one knob of it.
+ */
+export declare function resolveSiteChrome(layout?: TemplateLayout, design?: StarterDesign): ResolvedSiteChrome;
 /**
  * Render `apps/web/lib/site-chrome.ts` for a resolved layout — the same
  * GENERATED-header idiom `renderNavConfig` uses. `layout.tsx` imports

package/dist/site-chrome.js

@@ -15,16 +15,22 @@
  * `apps/web/lib/site-chrome.ts` every scaffold gets — beside `nav-config.ts`,
  * the same GENERATED-header idiom (`surfaces.ts` `renderNavConfig`).
  *
- * Every field is optional and DEFAULTS to today's render (`full` / `columns`
- * / `true` / `default`) — a scaffold naming no template, or a template naming
- * no `layout` block, gets these defaults written, byte-identical to the
- * monorepo's own committed `apps/web/lib/site-chrome.ts`.
+ * Every field is optional and DEFAULTS to `full` / `columns` / `false` /
+ * `default` — the announcement banner is off unless a template turns it on
+ * (#6469). A scaffold naming no template, or a template naming no `layout`
+ * block, gets these defaults written, byte-identical to the monorepo's own
+ * committed `apps/web/lib/site-chrome.ts`.
+ *
+ * A template's DESIGN supplies layout knobs too (#6638): `DESIGN_LAYOUTS` in
+ * `template-manifest.ts`, read by `resolveSiteChrome`'s optional `design`
+ * argument between an explicit `layout` and these defaults.
  */
-/** Byte-identical-to-today defaults (#5612 D1). */
+import { DESIGN_LAYOUTS, TemplateError, } from "./template-manifest.js";
+/** Defaults (#5612 D1; banner off since #6469). */
 export const DEFAULT_SITE_CHROME = {
     nav: "full",
     footer: "columns",
-    announcementBanner: true,
+    announcementBanner: false,
     home: "default",
 };
 /** Template-relative path of the generated site-chrome registry — beside `NAV_CONFIG_PATH`. */
@@ -85,13 +91,25 @@ export function validateTemplateLayout(value, subject) {
     }
     return result;
 }
-/** Fill every field a `TemplateLayout` leaves unset with `DEFAULT_SITE_CHROME`'s value. */
-export function resolveSiteChrome(layout) {
+/**
+ * Fill every field a `TemplateLayout` leaves unset — from `design`'s
+ * `DESIGN_LAYOUTS` entry when one is named (#6638), then from
+ * `DEFAULT_SITE_CHROME`. The explicit `layout` wins field by field, so a
+ * template can wear a design and still override one knob of it.
+ */
+export function resolveSiteChrome(layout, design) {
+    const fromDesign = design !== undefined ? DESIGN_LAYOUTS[design] : {};
+    // A JS caller (or a cast) can reach here with an undeclared design.
+    if (fromDesign === undefined) {
+        throw new TemplateError(`unknown design "${design}". Declared: ${Object.keys(DESIGN_LAYOUTS).join(", ")}`);
+    }
     return {
-        nav: layout?.nav ?? DEFAULT_SITE_CHROME.nav,
-        footer: layout?.footer ?? DEFAULT_SITE_CHROME.footer,
-        announcementBanner: layout?.announcementBanner ?? DEFAULT_SITE_CHROME.announcementBanner,
-        home: layout?.home ?? DEFAULT_SITE_CHROME.home,
+        nav: layout?.nav ?? fromDesign.nav ?? DEFAULT_SITE_CHROME.nav,
+        footer: layout?.footer ?? fromDesign.footer ?? DEFAULT_SITE_CHROME.footer,
+        announcementBanner: layout?.announcementBanner ??
+            fromDesign.announcementBanner ??
+            DEFAULT_SITE_CHROME.announcementBanner,
+        home: layout?.home ?? fromDesign.home ?? DEFAULT_SITE_CHROME.home,
     };
 }
 /**
@@ -106,8 +124,8 @@ export function renderSiteChrome(resolved) {
 //
 // GENERATED by create-ailk from the declared template's \`layout\` block
 // (#5612). A scaffold with no template, or a template with no \`layout\`
-// block, gets these defaults — byte-identical to every scaffold before this
-// file existed. \`apps/web/app/[locale]/layout.tsx\` reads this to decide:
+// block, gets the defaults below (the announcement banner is off unless a
+// template turns it on, #6469). \`apps/web/app/[locale]/layout.tsx\` reads this to decide:
 //   - nav: "mark-only" → Nav renders the brand mark + right-hand controls
 //     only (no nav links).
 //   - footer: "centered" → Footer renders its existing centered variant.

package/dist/site-roster.d.ts

@@ -0,0 +1,127 @@
+import { type PageRosterRow } from "./module-architecture.js";
+import type { ModuleName } from "./parse-args.js";
+import { type MarkerMap } from "./substitute.js";
+import { type TemplateManifest } from "./template-manifest.js";
+/** The site-root file that is the roster of record (#6658 D7). */
+export declare const SITE_ROSTER_PATH = ".ailk-site-manifest.json";
+/**
+ * Where a site scaffolded before #6658 carries its roster: the template's
+ * manifest copied to the root under its own name. Read only when
+ * `SITE_ROSTER_PATH` is absent, and written back in place.
+ */
+export declare const LEGACY_SITE_ROSTER_PATH = "TEMPLATE-MANIFEST.json";
+/** One `rows[]` element: its parsed value and its verbatim text in the file. */
+export interface RosterRowSlice {
+    value: Record<string, unknown>;
+    text: string;
+}
+/** A parsed manifest file, with the `rows` array located in its text. */
+interface RosterFile {
+    doc: Record<string, unknown>;
+    text: string;
+    rows: RosterRowSlice[];
+    /** Index of the `rows` array's `[`. */
+    open: number;
+    /** Index of the `rows` array's `]`. */
+    close: number;
+    /** The whitespace before the first row and after the last — prettier's. */
+    lead: string;
+    trail: string;
+}
+/** The site's roster of record. */
+export interface SiteRoster extends RosterFile {
+    /** The registry entry the file's `template` names. */
+    template: TemplateManifest;
+    /** The site-relative file it was read from — `SITE_ROSTER_PATH`, or the legacy root name. */
+    path: string;
+}
+/** One module contribution, with the generator's row(s) for its route. */
+export interface ModuleRosterRow {
+    module: ModuleName;
+    contribution: PageRosterRow;
+    /**
+     * The generator's row for the route. For a `contentDir` contribution this
+     * is the code-route form (`kind: "route"`), used where the site has no
+     * seeds under the directory.
+     */
+    row: RosterRowSlice;
+    /** A `contentDir` contribution's seeded page form. */
+    seeded?: RosterRowSlice;
+}
+/**
+ * The site's roster of record, or `undefined` when the site has none (a
+ * scaffold that named no template installs no manifest). A file that is not
+ * a JSON object, has no `rows` array or names a template the registry does
+ * not declare is refused: guessing would silently mis-roster the site.
+ */
+export declare function readSiteRoster(targetDir: string): SiteRoster | undefined;
+/**
+ * The generator's row for each of a module's `pageContributions`, in
+ * declaration order — read from the committed manifest of the first
+ * template (in `TEMPLATE_MANIFESTS` order) that requires the module, ships a
+ * manifest, and carries the route. A `contentDir` contribution resolves both
+ * of its forms. A route no shipped manifest carries is refused.
+ */
+export declare function moduleRosterRows(moduleName: ModuleName, siteTemplatesDir: string): ModuleRosterRow[];
+/** What becomes of a superseded template row's seed file. */
+export type SupersededSeed = {
+    path: string;
+    remove: true;
+} | {
+    path: string;
+    remove: false;
+    wanted: string;
+};
+export interface RosterAppendPlan {
+    /** The rewritten file text, or undefined when the rows are unchanged. */
+    next: string | undefined;
+    /** Routes filled from the shipped reference rows. */
+    appended: string[];
+    /** The seeds of the template rows a module took over. */
+    seeds: SupersededSeed[];
+}
+export interface PlanRosterAppendOptions {
+    targetDir: string;
+    roster: SiteRoster;
+    /** The site's module set after the add. */
+    modules: readonly ModuleName[];
+    /** `moduleRosterRows` of every module in `modules`, resolved up front. */
+    references: readonly ModuleRosterRow[];
+    siteTemplatesDir: string;
+    templatesDir: string;
+    markers: MarkerMap;
+}
+/**
+ * The site roster's next `rows`: the template rows in file order, then each
+ * module's rows in `normalizeModules` order and, within a module, in
+ * `pageContributions` order — `mergeRoster`'s order, so adding A then B
+ * gives the roster adding B then A does.
+ *
+ * A row on a route a module in the set contributes is SUPERSEDED when it is
+ * the site template's own shipped row, untouched (the Free `/blog` teaser
+ * under docs-blog): the module's row takes its place, and its seed is
+ * removed only when its bytes are exactly what the scaffold installed. Any
+ * other row on a contributed route is the site's own and is kept as is.
+ */
+export declare function planRosterAppend(opts: PlanRosterAppendOptions): RosterAppendPlan;
+export interface SiteRosterCheckOptions {
+    targetDir: string;
+    siteTemplatesDir: string;
+    templatesDir: string;
+}
+/**
+ * The site's roster problems — empty means clean. The scaffold-grained twin
+ * of `build-template-manifest.mjs --check`, over the same `rosterDeclares`
+ * predicate:
+ *
+ *   1. a route on more than one row;
+ *   2. a module in the site's set whose contributed row is missing, or is not
+ *      the shipped reference row;
+ *   3. an installed seed — one some layer lands, present in the site — that
+ *      the effective roster does not declare. A page the customer wrote is
+ *      installed by no layer and is never reported.
+ *
+ * A site with no roster (a template-less scaffold) has no problems.
+ */
+export declare function siteRosterProblems(opts: SiteRosterCheckOptions): string[];
+export {};