create-ailk 0.6.0 → 0.7.0

package/dist/site-roster.js

@@ -0,0 +1,494 @@
+/**
+ * The site's page roster of record — `<site>/.ailk-site-manifest.json` — and
+ * the append `add-module` makes to it (#6682).
+ *
+ * A template scaffold carries its template's generated manifest at the site
+ * root, landed by the template's `installMap` as `.ailk-site-manifest.json`
+ * (#6658 D7); a site scaffolded before that carries the same JSON as a root
+ * `TEMPLATE-MANIFEST.json`, which is read (and appended to) in its place. When a purchased module
+ * lands on that site, the module's `pageContributions` must join the roster,
+ * or the site no longer satisfies the one-roster contract a fresh scaffold
+ * does (#6646). This module owns every read and write of that file:
+ *
+ *   - `readSiteRoster` — the file, or `undefined` for a template-less site;
+ *   - `moduleRosterRows` — a module's rows, read from the generator's own
+ *     output in the shipped template manifests (never re-derived: the
+ *     derivation needs a YAML parser the package does not ship, and would be
+ *     a second authority beside `build-template-manifest.mjs`);
+ *   - `planRosterAppend` — the next `rows`, spliced into the file's text so
+ *     every untouched byte stays prettier's;
+ *   - `siteRosterProblems` — the scaffold-grained twin of the generator's
+ *     `--check`, which cannot target a site.
+ *
+ * Pure module: no `import.meta.url`. Package-rooted directories are supplied
+ * by the caller, the same split as `add-module.ts` / `programmatic.ts`.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { AddModuleRefusedError, readArchitectureHeader, } from "./add-module-core.js";
+import { diffTwoStrings } from "./lib/extract-module-bundle.js";
+import { MODULE_SLICES, normalizeModules, } from "./module-architecture.js";
+import { substituteMarkers } from "./substitute.js";
+import { BASE_LAYER_DIR, TEMPLATE_MANIFESTS, resolveTemplate, rosterDeclares, } from "./template-manifest.js";
+/** The site-root file that is the roster of record (#6658 D7). */
+export 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 const LEGACY_SITE_ROSTER_PATH = "TEMPLATE-MANIFEST.json";
+/** A template tree's own generated manifest — the file the site copy is made from. */
+const SHIPPED_MANIFEST_PATH = "TEMPLATE-MANIFEST.json";
+/** Prettier's default print width — the generator formats the manifest with it. */
+const PRINT_WIDTH = 80;
+// ── A string-aware JSON scanner, for the text splice ──────────────────────
+function skipWhitespace(text, i) {
+    while (i < text.length && /\s/.test(text[i]))
+        i++;
+    return i;
+}
+/** The index just past the JSON value that starts at `i`. */
+function endOfValue(text, i) {
+    const first = text[i];
+    if (first === '"') {
+        let j = i + 1;
+        while (j < text.length && text[j] !== '"')
+            j += text[j] === "\\" ? 2 : 1;
+        return j + 1;
+    }
+    if (first === "{" || first === "[") {
+        let depth = 0;
+        let j = i;
+        while (j < text.length) {
+            const c = text[j];
+            if (c === '"') {
+                j = endOfValue(text, j);
+                continue;
+            }
+            if (c === "{" || c === "[")
+                depth++;
+            else if (c === "}" || c === "]") {
+                depth--;
+                if (depth === 0)
+                    return j + 1;
+            }
+            j++;
+        }
+        return j;
+    }
+    let j = i;
+    while (j < text.length && !/[\s,\]}]/.test(text[j]))
+        j++;
+    return j;
+}
+/** Where a key of the object starting at `objStart` sits, or undefined. */
+function findKey(text, objStart, key) {
+    let i = skipWhitespace(text, objStart + 1);
+    while (i < text.length && text[i] === '"') {
+        const keyEnd = endOfValue(text, i);
+        const name = JSON.parse(text.slice(i, keyEnd));
+        const valueStart = skipWhitespace(text, skipWhitespace(text, keyEnd) + 1);
+        if (name === key)
+            return { keyStart: i, valueStart };
+        i = skipWhitespace(text, endOfValue(text, valueStart));
+        if (text[i] !== ",")
+            return undefined;
+        i = skipWhitespace(text, i + 1);
+    }
+    return undefined;
+}
+/** The `[start, end)` span of each element of the array opening at `open`, and its `]`. */
+function arrayElements(text, open) {
+    const spans = [];
+    let i = skipWhitespace(text, open + 1);
+    while (i < text.length && text[i] !== "]") {
+        const end = endOfValue(text, i);
+        spans.push([i, end]);
+        i = skipWhitespace(text, end);
+        if (text[i] === ",")
+            i = skipWhitespace(text, i + 1);
+    }
+    return { spans, close: i };
+}
+/**
+ * Parse a manifest file and locate its `rows` array in the text. The element
+ * spans are cross-checked against `JSON.parse`, so a splice can only ever
+ * move bytes the parser agrees are those rows.
+ */
+function parseRosterFile(text, label) {
+    const refuse = (why) => new AddModuleRefusedError(`${label} ${why}, so the page roster is unknown`);
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch (err) {
+        throw refuse(`is not JSON (${err.message})`);
+    }
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
+        throw refuse("is not a JSON object");
+    }
+    const parsed = doc;
+    if (!Array.isArray(parsed["rows"]))
+        throw refuse("has no `rows` array");
+    const at = findKey(text, text.indexOf("{"), "rows");
+    if (at === undefined || text[at.valueStart] !== "[") {
+        throw refuse("has a `rows` key the scanner cannot locate");
+    }
+    const { spans, close } = arrayElements(text, at.valueStart);
+    const rows = spans.map(([start, end]) => ({
+        value: JSON.parse(text.slice(start, end)),
+        text: text.slice(start, end),
+    }));
+    if (!isDeepStrictEqual(rows.map((r) => r.value), parsed["rows"])) {
+        throw refuse("has a `rows` array the scanner reads differently");
+    }
+    const first = spans[0];
+    const last = spans[spans.length - 1];
+    return {
+        doc: parsed,
+        text,
+        rows,
+        open: at.valueStart,
+        close,
+        lead: first ? text.slice(at.valueStart + 1, first[0]) : "\n    ",
+        trail: last ? text.slice(last[1], close) : "\n  ",
+    };
+}
+// ── D1: the site roster ───────────────────────────────────────────────────
+/**
+ * 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 function readSiteRoster(targetDir) {
+    const path = [SITE_ROSTER_PATH, LEGACY_SITE_ROSTER_PATH].find((name) => existsSync(join(targetDir, name)));
+    if (path === undefined)
+        return undefined;
+    const file = parseRosterFile(readFileSync(join(targetDir, path), "utf8"), path);
+    const name = file.doc["template"];
+    let template;
+    try {
+        template = resolveTemplate(String(name));
+    }
+    catch (err) {
+        throw new AddModuleRefusedError(`${path} names no declared template (${err.message}), so the page roster is unknown`);
+    }
+    return { ...file, template, path };
+}
+// ── D2: a module's rows, from the shipped manifests ───────────────────────
+/** A template's shipped manifest, or undefined when its tree ships none. */
+function readShippedManifest(siteTemplatesDir, templateName) {
+    const path = join(siteTemplatesDir, templateName, SHIPPED_MANIFEST_PATH);
+    if (!existsSync(path))
+        return undefined;
+    return parseRosterFile(readFileSync(path, "utf8"), `site-templates/${templateName}/${SHIPPED_MANIFEST_PATH}`);
+}
+/**
+ * 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 function moduleRosterRows(moduleName, siteTemplatesDir) {
+    const contributions = MODULE_SLICES[moduleName].pageContributions ?? [];
+    if (contributions.length === 0)
+        return [];
+    const manifests = Object.values(TEMPLATE_MANIFESTS)
+        .filter((m) => m.requires.includes(moduleName))
+        .flatMap((m) => readShippedManifest(siteTemplatesDir, m.name) ?? []);
+    const find = (route, kind) => {
+        for (const manifest of manifests) {
+            const row = manifest.rows.find((r) => r.value["route"] === route &&
+                (kind === undefined || r.value["kind"] === kind));
+            if (row !== undefined)
+                return row;
+        }
+        return undefined;
+    };
+    return contributions.map((contribution) => {
+        const isDir = contribution.contentDir !== undefined;
+        const row = find(contribution.route, isDir ? "route" : undefined);
+        const seeded = isDir ? find(contribution.route, "page") : undefined;
+        if (row === undefined || (isDir && seeded === undefined)) {
+            throw new AddModuleRefusedError(`module "${moduleName}" contributes ${contribution.route}, but no shipped template manifest carries ${isDir ? "both forms of " : ""}its row, so it cannot be added to ${SITE_ROSTER_PATH}`);
+        }
+        return { module: moduleName, contribution, row, ...(seeded && { seeded }) };
+    });
+}
+/**
+ * Every `.mdx` under `dir`, as `/`-separated paths relative to `base`. Walked
+ * by hand: `Dirent.parentPath` and a reliable recursive `readdirSync` post-date
+ * the `node >=20.0.0` floor.
+ */
+function listMdx(dir, base) {
+    const out = [];
+    const stack = existsSync(dir) ? [dir] : [];
+    for (let cur = stack.pop(); cur !== undefined; cur = stack.pop()) {
+        for (const entry of readdirSync(cur, { withFileTypes: true })) {
+            const abs = join(cur, entry.name);
+            if (entry.isDirectory())
+                stack.push(abs);
+            else if (entry.isFile() && entry.name.endsWith(".mdx")) {
+                out.push(relative(base, abs).split(sep).join("/"));
+            }
+        }
+    }
+    return out.sort();
+}
+/** Render a string array the way prettier prints it at a key starting at `column`. */
+function renderStringArray(items, column, inlinePrefixWidth) {
+    if (items.length === 0)
+        return "[]";
+    const inline = `[${items.map((s) => JSON.stringify(s)).join(", ")}]`;
+    if (column + inlinePrefixWidth + inline.length <= PRINT_WIDTH)
+        return inline;
+    const pad = " ".repeat(column);
+    return `[\n${items.map((s) => `${pad}  ${JSON.stringify(s)}`).join(",\n")}\n${pad}]`;
+}
+/** A row slice with its `seeds` replaced, in value and in text. */
+function withSeeds(row, seeds) {
+    const at = findKey(row.text, 0, "seeds");
+    if (at === undefined)
+        return row;
+    const end = endOfValue(row.text, at.valueStart);
+    const column = at.keyStart - (row.text.lastIndexOf("\n", at.keyStart) + 1);
+    const trailingComma = row.text[end] === "," ? 1 : 0;
+    const rendered = renderStringArray(seeds, column, at.valueStart - at.keyStart + trailingComma);
+    return {
+        value: { ...row.value, seeds },
+        text: row.text.slice(0, at.valueStart) + rendered + row.text.slice(end),
+    };
+}
+/**
+ * The row the site's roster should carry for one contribution. A
+ * `contentDir` row takes its seeded page form, listing the site's own seeds
+ * as the generator computes them, when the site has any; its code-route form
+ * otherwise.
+ */
+function expectedRow(ref, targetDir) {
+    const dir = ref.contribution.contentDir;
+    if (dir === undefined || ref.seeded === undefined)
+        return ref.row;
+    const seeds = listMdx(join(targetDir, dir), targetDir);
+    return seeds.length > 0 ? withSeeds(ref.seeded, seeds) : ref.row;
+}
+/** The bytes a scaffold installed at `path` from the template, base or overlay layer. */
+function installedSeed(opts, path) {
+    const layers = [
+        join(opts.siteTemplatesDir, opts.roster.template.name),
+        join(opts.siteTemplatesDir, BASE_LAYER_DIR),
+        opts.templatesDir,
+    ];
+    for (const layer of layers) {
+        const abs = join(layer, path);
+        if (existsSync(abs)) {
+            return substituteMarkers(readFileSync(abs, "utf8"), opts.markers);
+        }
+    }
+    return undefined;
+}
+/**
+ * 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 function planRosterAppend(opts) {
+    const { roster, targetDir } = opts;
+    const inSet = new Set(opts.modules);
+    const refs = opts.references.filter((ref) => inSet.has(ref.module));
+    const contributed = new Set(refs.map((ref) => ref.contribution.route));
+    const shipped = readShippedManifest(opts.siteTemplatesDir, roster.template.name);
+    const templateRows = [];
+    const moduleRows = new Map();
+    const superseded = [];
+    for (const row of roster.rows) {
+        const route = row.value["route"];
+        if (!contributed.has(route)) {
+            templateRows.push(row);
+            continue;
+        }
+        const own = roster.template.roster.find((r) => r.route === route);
+        const shippedRow = shipped?.rows.find((r) => r.value["route"] === route);
+        if (own !== undefined &&
+            shippedRow !== undefined &&
+            isDeepStrictEqual(row.value, shippedRow.value)) {
+            superseded.push(own);
+            continue;
+        }
+        moduleRows.set(route, [...(moduleRows.get(route) ?? []), row]);
+    }
+    const next = [...templateRows];
+    const appended = [];
+    for (const moduleName of normalizeModules([...opts.modules])) {
+        for (const ref of refs.filter((r) => r.module === moduleName)) {
+            const route = ref.contribution.route;
+            const kept = moduleRows.get(route);
+            if (kept !== undefined) {
+                next.push(...kept);
+            }
+            else {
+                next.push(expectedRow(ref, targetDir));
+                appended.push(route);
+            }
+        }
+    }
+    const seeds = [];
+    for (const row of superseded) {
+        for (const path of row.content ?? []) {
+            const abs = join(targetDir, path);
+            if (!existsSync(abs))
+                continue;
+            const existing = readFileSync(abs, "utf8");
+            if (existing === installedSeed(opts, path)) {
+                seeds.push({ path, remove: true });
+            }
+            else {
+                seeds.push({
+                    path,
+                    remove: false,
+                    wanted: diffTwoStrings(path, existing, "", true),
+                });
+            }
+        }
+    }
+    const unchanged = isDeepStrictEqual(next.map((r) => r.value), roster.rows.map((r) => r.value));
+    return {
+        next: unchanged ? undefined : spliceRows(roster, next),
+        appended,
+        seeds,
+    };
+}
+/**
+ * The file with its `rows` array's elements replaced — every byte outside the
+ * brackets verbatim, each row its own verbatim slice, joined the way
+ * prettier separates them.
+ */
+function spliceRows(file, rows) {
+    const { text, open, close, lead, trail } = file;
+    const body = rows.length === 0
+        ? ""
+        : `${lead}${rows.map((r) => r.text).join(`,${lead}`)}${trail}`;
+    return text.slice(0, open + 1) + body + text.slice(close);
+}
+/** Every `content/en/**.mdx` some layer installs into a site of this template and module set. */
+function layerInstalledSeeds(template, modules, opts) {
+    const out = new Set();
+    for (const root of [
+        opts.templatesDir,
+        join(opts.siteTemplatesDir, BASE_LAYER_DIR),
+    ]) {
+        for (const path of listMdx(join(root, "content", "en"), root))
+            out.add(path);
+    }
+    // The template's own tree, as the generator's `ownedContent` reads it: an
+    // `installMap` source lands at its mapped destination instead.
+    const ownRoot = join(opts.siteTemplatesDir, template.name);
+    const ownManifest = join(ownRoot, "ailk-template.json");
+    const ownMap = existsSync(ownManifest)
+        ? (JSON.parse(readFileSync(ownManifest, "utf8")).installMap ?? {})
+        : {};
+    const destinations = Object.values(ownMap);
+    for (const path of listMdx(join(ownRoot, "content", "en"), ownRoot)) {
+        if (!(path in ownMap))
+            out.add(path);
+    }
+    for (const moduleName of modules) {
+        const slice = MODULE_SLICES[moduleName];
+        for (const row of slice.pageContributions ?? []) {
+            for (const path of row.content ?? [])
+                out.add(path);
+        }
+        destinations.push(...Object.values(slice.installMap ?? {}));
+    }
+    for (const to of destinations) {
+        if (to.startsWith("content/en/") && to.endsWith(".mdx"))
+            out.add(to);
+    }
+    return out;
+}
+/**
+ * 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 function siteRosterProblems(opts) {
+    const roster = readSiteRoster(opts.targetDir);
+    if (roster === undefined)
+        return [];
+    const { modules } = readArchitectureHeader(readFileSync(join(opts.targetDir, "architecture.yaml"), "utf8"));
+    const problems = [];
+    const routes = roster.rows.map((r) => r.value["route"]);
+    const seen = new Set();
+    for (const route of routes) {
+        if (seen.has(route))
+            problems.push(`${route}: appears on more than one row`);
+        seen.add(route);
+    }
+    const contributions = new Map();
+    for (const moduleName of modules) {
+        let refs;
+        try {
+            refs = moduleRosterRows(moduleName, opts.siteTemplatesDir);
+        }
+        catch (err) {
+            problems.push(err.message);
+            continue;
+        }
+        for (const ref of refs) {
+            const route = ref.contribution.route;
+            contributions.set(route, ref.contribution);
+            const wanted = expectedRow(ref, opts.targetDir).value;
+            const rows = roster.rows.filter((r) => r.value["route"] === route);
+            if (rows.length === 0) {
+                problems.push(`${route}: no row, but module "${moduleName}" contributes it`);
+            }
+            else if (!rows.some((r) => isDeepStrictEqual(r.value, wanted))) {
+                problems.push(`${route}: the row differs from module "${moduleName}"'s shipped row`);
+            }
+        }
+    }
+    const effective = roster.rows.map((row) => {
+        const route = row.value["route"];
+        const registry = contributions.get(route) ??
+            roster.template.roster.find((r) => r.route === route);
+        const contentDir = row.value["contentDir"];
+        return {
+            route,
+            ...(registry?.content !== undefined && { content: registry.content }),
+            ...(typeof contentDir === "string"
+                ? { contentDir }
+                : registry?.contentDir !== undefined && {
+                    contentDir: registry.contentDir,
+                }),
+        };
+    });
+    const installed = [...layerInstalledSeeds(roster.template, modules, opts)]
+        .filter((path) => existsSync(join(opts.targetDir, path)))
+        .sort();
+    for (const path of installed) {
+        if (!rosterDeclares(effective, path)) {
+            problems.push(`${path}: installed but not declared by any roster row`);
+        }
+    }
+    return problems;
+}

package/dist/surfaces.d.ts

@@ -57,6 +57,14 @@ export declare const RECOGNIZED_SURFACES: readonly string[];
  * comment on that row. Resolving through an alias prints a deprecation notice.
  */
 export declare const SURFACE_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Surface ids that became core routes (#6658 D3: `software` — the product's
+ * own page is in every scaffold). Accepted and dropped wherever a surface list
+ * is read — a `--surfaces` value or an existing site's `# Surfaces:` header —
+ * so a site scaffolded with `--surfaces software` keeps working: its route
+ * is copied regardless.
+ */
+export declare const CORE_PROMOTED_SURFACES: ReadonlySet<string>;
 /**
  * Surfaces each recognized module contributes.
  *
@@ -183,19 +191,24 @@ export declare const NAV_CONFIG_PATH = "apps/web/lib/nav-config.ts";
  * surface set for the same reason the route tree does.
  *
  * The base items are the Free marketing-site chrome (#5469 D5, the approved
- * chrome diff recorded on that card):
- * a Product flyout (How it works · Features · FAQ), then How it works, Pricing
- * and About. Every one of those pages is in EVERY scaffold — the four core
- * routes plus the `[slug]` route over the overlay's LandingPage MDX — except
- * Pricing, which is a gateable surface: its item is emitted only when the
- * `pricing` surface is enabled (a template roster enables it, #5469 D10), so
- * the nav still never links a page the scaffold does not carry.
+ * chrome diff recorded on that card, re-pointed by #6658 D8):
+ * a Product flyout (Use cases · Features · FAQ), then Use cases, Blog, Pricing
+ * and About. Features links the product's own page (`/software/product`), a
+ * core route like `/faq` and `/about`; `/blog` is always linked (the teaser or
+ * the docs-blog module serves it). Use cases and Pricing are gateable
+ * surfaces: each item is emitted only when its surface is enabled (a template
+ * roster enables it, #5469 D10), so the nav still never links a page the
+ * scaffold does not carry.
  *
  * Only gateable surfaces carrying a `navLabelKey` are linked after the base
  * items, because a nav entry needs a translated label. Emitting an entry whose
  * `labelKey` has no translation would trade a dead link for a missing-message
  * error.
  *
+ * The same file carries `footerColumns`, the footer's column groups (#6468):
+ * label keys and paths only, under the same gates, so the footer links every
+ * seed page the header does not.
+ *
  * Deterministic: gateable entries follow GATEABLE_SURFACES order (alphabetical
  * by id), after the fixed base items.
  */