create-ailk 0.8.0 → 0.10.0

package/dist/design-scaffold.d.ts

@@ -0,0 +1,76 @@
+import { type CompiledDesignTheme } from "./design-compile.js";
+import { type DesignPackage } from "./design-package.js";
+import type { LayerOwnership } from "./lib/extract-module-bundle.js";
+/** One resolved `--design` reference (D2). */
+export interface ResolvedDesign {
+    /** "name" when the reference was a registry name, "path" when a directory. */
+    kind: "name" | "path";
+    /** Absolute directory holding the DESIGN.md. */
+    dir: string;
+    pkg: DesignPackage;
+    /** What the site records: the registry name when `pkg` deep-equals a shipped design's package, else `pkg.name`. */
+    recorded: string;
+    /** What a refusal names: the name, or the absolute directory. */
+    display: string;
+    /** True iff `recorded` is in `FREE_DESIGNS` by the identity rule below (D2). */
+    free: boolean;
+}
+/**
+ * Resolve a design reference to its package (D2). Classification mirrors
+ * `parse-args.ts`'s `parseDesign` (D1) exactly, so a programmatic caller
+ * accepts the same inputs the CLI does: a value with no `/` or `\` that
+ * names a recognized design resolves to `<designsDir>/<name>`; otherwise, if
+ * it names an existing directory (relative to `opts.cwd`), it resolves as a
+ * path; otherwise it is refused. A value with a separator is always a path.
+ *
+ * A path's package is compared, by deep equality, against each shipped
+ * design's own package: a byte-identical copy of a shipped design IS that
+ * design (`recorded`/`free` follow the shipped name), and any authored
+ * change makes it a distinct, non-Free design named by its own `pkg.name`.
+ *
+ * @throws TemplateError on an unrecognized bare name or a missing directory.
+ * @throws DesignPackageError (from `readDesignPackage`, never caught here) on
+ *   a malformed package — naming the file and the field.
+ */
+export declare function resolveDesign(ref: string, opts: {
+    designsDir: string;
+    cwd?: string;
+}): ResolvedDesign;
+/**
+ * Render a compiled theme's `theme:` frontmatter block (D5) — `theme:`, each
+ * treatment present as a bare `key: value`, then `colors:` with `light:`/
+ * `dark:` sub-blocks, each colour slot as `slot: <JSON.stringify(value)>` in
+ * `DESIGN_COLOR_MAP`'s order. Ends with a trailing newline.
+ */
+export declare function renderThemeBlock(theme: CompiledDesignTheme): string;
+/**
+ * Splice a compiled theme into `text`'s frontmatter `theme:` block (D5),
+ * replacing an existing one in place or inserting a fresh one immediately
+ * before the closing `---` when the frontmatter carries none. Nothing
+ * outside the block moves — for every committed `_site.mdx` and its own
+ * design, this is the identity function (byte-identity floor, AC-4).
+ *
+ * @throws TemplateError when `text` carries no frontmatter to write into.
+ */
+export declare function spliceThemeBlock(text: string, theme: CompiledDesignTheme, file: string): string;
+/**
+ * Install a design's `sample/` directory onto a scaffold (spec 6892 D4) — a
+ * FIXED, undeclared convention, not a design-package field: `sample/content/**`
+ * lands at the scaffold's `content/**`, `sample/public/**` at
+ * `apps/web/public/**`. A design with no `sample/` directory (e.g. `standard`)
+ * installs nothing.
+ *
+ * Refuses — before its first write, so a refused sample leaves `targetDir`
+ * untouched — any file outside those two roots, or any `.ts`/`.tsx`/`.js`/
+ * `.mjs` file (content only, the template §5.2 rule this design package
+ * amendment carries over). Every installed file's destination is recorded in
+ * `ownership` as `design:<name>` (`readDesignPackage(designDir).name`), the
+ * same call-scoped registry `installBundleTree` writes into.
+ *
+ * @throws Error on a file outside `content/`/`public/`, or a forbidden extension.
+ */
+export declare function installDesignSample(opts: {
+    designDir: string;
+    targetDir: string;
+    ownership: LayerOwnership;
+}): void;

package/dist/design-scaffold.js

@@ -0,0 +1,220 @@
+/**
+ * Resolve a `--design` reference (a shipped name, or a directory holding a
+ * `DESIGN.md`) to its design package, and splice the compiled theme it
+ * produces into a scaffold's `content/_site.mdx` (#6813, spec
+ * docs/specs/6813-design-accepts-a-package-path-spec.md D2/D5).
+ *
+ * `resolveDesign` is the one resolver every front door (the CLI, `scaffold()`,
+ * `verify-scaffold.mjs`) passes a design reference through, before any
+ * network request or write (D8). It never touches `import.meta.url` — every
+ * directory it reads is supplied by the caller — so it stays importable from
+ * Jest's CJS transform, unlike `programmatic.ts`.
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync, } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { DESIGN_COLOR_MAP } from "./design-compile.js";
+import { readDesignPackage } from "./design-package.js";
+import { FREE_DESIGNS } from "./lib/module-license-gate.js";
+import { STARTER_DESIGNS, TemplateError } from "./template-manifest.js";
+/** `path` is an existing DIRECTORY — a file at `path` is not (mirrors `parse-args.ts`'s own helper). */
+function isExistingDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve a design reference to its package (D2). Classification mirrors
+ * `parse-args.ts`'s `parseDesign` (D1) exactly, so a programmatic caller
+ * accepts the same inputs the CLI does: a value with no `/` or `\` that
+ * names a recognized design resolves to `<designsDir>/<name>`; otherwise, if
+ * it names an existing directory (relative to `opts.cwd`), it resolves as a
+ * path; otherwise it is refused. A value with a separator is always a path.
+ *
+ * A path's package is compared, by deep equality, against each shipped
+ * design's own package: a byte-identical copy of a shipped design IS that
+ * design (`recorded`/`free` follow the shipped name), and any authored
+ * change makes it a distinct, non-Free design named by its own `pkg.name`.
+ *
+ * @throws TemplateError on an unrecognized bare name or a missing directory.
+ * @throws DesignPackageError (from `readDesignPackage`, never caught here) on
+ *   a malformed package — naming the file and the field.
+ */
+export function resolveDesign(ref, opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const hasSeparator = ref.includes("/") || ref.includes("\\");
+    if (!hasSeparator && STARTER_DESIGNS.includes(ref)) {
+        const dir = join(opts.designsDir, ref);
+        return {
+            kind: "name",
+            dir,
+            pkg: readDesignPackage(dir),
+            recorded: ref,
+            display: ref,
+            free: FREE_DESIGNS.includes(ref),
+        };
+    }
+    const dir = resolve(cwd, ref);
+    if (!isExistingDir(dir)) {
+        throw new TemplateError(hasSeparator
+            ? `design directory "${ref}" does not exist`
+            : `unknown design "${ref}". Declared: ${STARTER_DESIGNS.join(", ")}`);
+    }
+    const pkg = readDesignPackage(dir);
+    for (const name of STARTER_DESIGNS) {
+        if (isDeepStrictEqual(pkg, readDesignPackage(join(opts.designsDir, name)))) {
+            return {
+                kind: "path",
+                dir,
+                pkg,
+                recorded: name,
+                display: dir,
+                free: FREE_DESIGNS.includes(name),
+            };
+        }
+    }
+    return { kind: "path", dir, pkg, recorded: pkg.name, display: dir, free: false };
+}
+/** The runtime colour slots, in `DESIGN_COLOR_MAP`'s light-mode row order — the order every committed `theme:` block uses. */
+const RUNTIME_COLOR_SLOT_ORDER = DESIGN_COLOR_MAP.filter((row) => row.mode === "light").map((row) => row.runtime);
+/**
+ * Render a compiled theme's `theme:` frontmatter block (D5) — `theme:`, each
+ * treatment present as a bare `key: value`, then `colors:` with `light:`/
+ * `dark:` sub-blocks, each colour slot as `slot: <JSON.stringify(value)>` in
+ * `DESIGN_COLOR_MAP`'s order. Ends with a trailing newline.
+ */
+export function renderThemeBlock(theme) {
+    const lines = ["theme:"];
+    if (theme.corners !== undefined)
+        lines.push(`  corners: ${theme.corners}`);
+    if (theme.eyebrowCase !== undefined)
+        lines.push(`  eyebrowCase: ${theme.eyebrowCase}`);
+    if (theme.placeholders !== undefined)
+        lines.push(`  placeholders: ${theme.placeholders}`);
+    if (theme.checkmarks !== undefined)
+        lines.push(`  checkmarks: ${theme.checkmarks}`);
+    lines.push("  colors:");
+    for (const mode of ["light", "dark"]) {
+        lines.push(`    ${mode}:`);
+        const palette = theme.colors[mode];
+        for (const slot of RUNTIME_COLOR_SLOT_ORDER) {
+            lines.push(`      ${slot}: ${JSON.stringify(palette[slot])}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Splice a compiled theme into `text`'s frontmatter `theme:` block (D5),
+ * replacing an existing one in place or inserting a fresh one immediately
+ * before the closing `---` when the frontmatter carries none. Nothing
+ * outside the block moves — for every committed `_site.mdx` and its own
+ * design, this is the identity function (byte-identity floor, AC-4).
+ *
+ * @throws TemplateError when `text` carries no frontmatter to write into.
+ */
+export function spliceThemeBlock(text, theme, file) {
+    const lines = text.split("\n");
+    let closeIdx = -1;
+    if (lines[0] === "---") {
+        for (let i = 1; i < lines.length; i += 1) {
+            if (lines[i] === "---") {
+                closeIdx = i;
+                break;
+            }
+        }
+    }
+    if (closeIdx === -1) {
+        throw new TemplateError(`${file}: no frontmatter to write the theme into`);
+    }
+    const rendered = renderThemeBlock(theme).split("\n");
+    rendered.pop(); // drop the trailing "" the render's final "\n" split off
+    let themeStart = -1;
+    let themeEnd = -1;
+    for (let i = 1; i < closeIdx; i += 1) {
+        if (lines[i] === "theme:") {
+            themeStart = i;
+            let j = i + 1;
+            while (j < closeIdx && (lines[j] === "" || lines[j].startsWith(" "))) {
+                j += 1;
+            }
+            themeEnd = j;
+            break;
+        }
+    }
+    const next = themeStart === -1
+        ? [...lines.slice(0, closeIdx), ...rendered, ...lines.slice(closeIdx)]
+        : [...lines.slice(0, themeStart), ...rendered, ...lines.slice(themeEnd)];
+    return next.join("\n");
+}
+/** Forbidden extensions for a design sample's files (spec 6892 D4) — content only, never code. */
+const SAMPLE_FORBIDDEN_EXTENSIONS = [".ts", ".tsx", ".js", ".mjs"];
+function hasSampleForbiddenExtension(p) {
+    return SAMPLE_FORBIDDEN_EXTENSIONS.some((ext) => p.toLowerCase().endsWith(ext));
+}
+/** Every file under `dir`, as `/`-separated paths relative to `dir`. */
+function listFiles(dir) {
+    const out = [];
+    const stack = [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())
+                out.push(relative(dir, abs).split(sep).join("/"));
+        }
+    }
+    return out;
+}
+/** Where one `sample/` file lands on a scaffold (spec 6892 D4's fixed convention). */
+function sampleDestination(rel) {
+    if (rel.startsWith("content/"))
+        return rel;
+    return `apps/web/public/${rel.slice("public/".length)}`;
+}
+/**
+ * Install a design's `sample/` directory onto a scaffold (spec 6892 D4) — a
+ * FIXED, undeclared convention, not a design-package field: `sample/content/**`
+ * lands at the scaffold's `content/**`, `sample/public/**` at
+ * `apps/web/public/**`. A design with no `sample/` directory (e.g. `standard`)
+ * installs nothing.
+ *
+ * Refuses — before its first write, so a refused sample leaves `targetDir`
+ * untouched — any file outside those two roots, or any `.ts`/`.tsx`/`.js`/
+ * `.mjs` file (content only, the template §5.2 rule this design package
+ * amendment carries over). Every installed file's destination is recorded in
+ * `ownership` as `design:<name>` (`readDesignPackage(designDir).name`), the
+ * same call-scoped registry `installBundleTree` writes into.
+ *
+ * @throws Error on a file outside `content/`/`public/`, or a forbidden extension.
+ */
+export function installDesignSample(opts) {
+    const sampleDir = join(opts.designDir, "sample");
+    if (!existsSync(sampleDir))
+        return;
+    const name = readDesignPackage(opts.designDir).name;
+    const subject = `design:${name}`;
+    // README.md at the sample root is the ONE documented exception (spec 6892
+    // D5: "the narrative sections move to designs/<name>/sample/README.md,
+    // which is not installed") — every other file is real content and is
+    // validated against the two roots below.
+    const files = listFiles(sampleDir).filter((rel) => rel !== "README.md");
+    for (const rel of files) {
+        if (!rel.startsWith("content/") && !rel.startsWith("public/")) {
+            throw new Error(`${subject}: sample file "${rel}" is outside content/ and public/ (spec 6892 D4)`);
+        }
+        if (hasSampleForbiddenExtension(rel)) {
+            throw new Error(`${subject}: sample file "${rel}" is a code file — a design sample is content only (spec 6892 D4)`);
+        }
+    }
+    for (const rel of files) {
+        const destinationRel = sampleDestination(rel);
+        const destinationAbs = resolve(opts.targetDir, destinationRel);
+        mkdirSync(join(destinationAbs, ".."), { recursive: true });
+        copyFileSync(join(sampleDir, rel), destinationAbs);
+        opts.ownership.set(destinationRel, subject);
+    }
+}

package/dist/index.d.ts

@@ -5,10 +5,11 @@
  */
 export { copyTemplate, type CopyTemplateOptions } from "./copy.js";
 export { parseCliArgs, parseModules, ParseError, helpText, RECOGNIZED_MODULES, type ModuleName, type CliOptions, } from "./parse-args.js";
-export { CATALOG_TARGET_PATH, FREE_MODULES, addModule, LicenseRequiredError, PAID_MODULES, classifyModules, formatSurfaceDrift, scaffold, scaffoldSync, syncArchitectureSync, syncCatalogSync, syncRoutesSync, type AddModuleOptions, type ResolvePaidModulesOptions, type ScaffoldOptions, type ScaffoldResult, type SyncArchitectureOptions, type SyncArchitectureResult, type SyncCatalogResult, type SyncRoutesSyncOptions, } from "./programmatic.js";
+export { CATALOG_TARGET_PATH, FREE_MODULES, addModule, LicenseRequiredError, PAID_MODULES, classifyModules, formatSurfaceDrift, scaffold, scaffoldSync, syncArchitectureSync, syncCatalogSync, syncClaudeMdSync, syncRoutesSync, type AddModuleOptions, type ResolvePaidModulesOptions, type ScaffoldOptions, type ScaffoldResult, type SyncArchitectureOptions, type SyncArchitectureResult, type SyncCatalogResult, type SyncClaudeMdResult, type SyncRoutesSyncOptions, } from "./programmatic.js";
 export { DEFAULT_AILK_MODULE_REGISTRY_URL, FetchModuleError, fetchModule, type FetchModuleOptions, } from "./lib/fetch-module.js";
 export { extractModuleBundle, type ExistingFilePolicy, type ExtractModuleBundleOptions, type InstallReportRow, } from "./lib/extract-module-bundle.js";
 export { ADD_MODULE_HELP, AddModuleRefusedError, applyModuleToScaffold, formatAddModuleReport, parseAddModuleArgs, type AddModuleReportRow, type AddModuleResult, type ApplyModuleOptions, } from "./add-module.js";
+export { APPLY_DESIGN_HELP, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, type ApplyDesignArgs, type ApplyDesignChange, type ApplyDesignOptions, type ApplyDesignResult, } from "./apply-design.js";
 export { SITE_ROSTER_PATH, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
 export { SYNC_ROUTES_HELP, formatSyncRoutesReport, listTemplateRouteDirs, parseSyncRoutesArgs, syncRoutes, type RouteReport, type SyncRoutesOptions, type SyncRoutesResult, } from "./sync-routes.js";
 export { deriveArchitecture } from "./derive-architecture.js";

package/dist/index.js

@@ -5,7 +5,7 @@
  */
 export { copyTemplate } from "./copy.js";
 export { parseCliArgs, parseModules, ParseError, helpText, RECOGNIZED_MODULES, } from "./parse-args.js";
-export { CATALOG_TARGET_PATH, FREE_MODULES, addModule, LicenseRequiredError, PAID_MODULES, classifyModules, formatSurfaceDrift, scaffold, scaffoldSync, syncArchitectureSync, syncCatalogSync, syncRoutesSync, } from "./programmatic.js";
+export { CATALOG_TARGET_PATH, FREE_MODULES, addModule, LicenseRequiredError, PAID_MODULES, classifyModules, formatSurfaceDrift, scaffold, scaffoldSync, syncArchitectureSync, syncCatalogSync, syncClaudeMdSync, syncRoutesSync, } from "./programmatic.js";
 // The paid-module fetch/extract primitives (K1, #5089 — Flavor 3). Exported
 // so tooling (and this repo's own evidence-run scripts) can drive the fetch
 // path directly without re-implementing its shape.
@@ -14,6 +14,9 @@ export { extractModuleBundle, } from "./lib/extract-module-bundle.js";
 // `create-ailk add-module` (#6653) — apply a purchased module to an existing
 // site in place. The pure core, beside `sync-routes`'s.
 export { ADD_MODULE_HELP, AddModuleRefusedError, applyModuleToScaffold, formatAddModuleReport, parseAddModuleArgs, } from "./add-module.js";
+// `create-ailk apply-design` (#6819) — make an existing site wear a design,
+// changing only its look. The pure core, beside `add-module`'s.
+export { APPLY_DESIGN_HELP, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, } from "./apply-design.js";
 // The site's page roster of record and its install-diff check (#6682).
 export { SITE_ROSTER_PATH, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
 // `create-ailk sync-routes` (#4986) — the template-route drift check + copy.

package/dist/legacy-nav-renderers.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Frozen, published-generator `renderNavConfig` bodies (#6908 D2) — one per
+ * era a create-ailk release ever shipped (E1–E4, `docs/specs/6908-add-module-
+ * treats-every-pre-spec.md` § 1.2). `surfaces.ts`'s own `renderNavConfig`
+ * self-hashes its output (D1) so a nav it wrote can always prove itself; a
+ * nav written before the stamp existed carries none, and this module is the
+ * only way `add-module` can still recognize it as unedited.
+ *
+ * Each `render` below is copied VERBATIM from the named tag's own
+ * `packages/create-ailk/src/surfaces.ts`, at the named commit, with exactly
+ * two changes from the original:
+ *
+ *   - `GATEABLE_SURFACES` is replaced by a frozen `{ id, navLabelKey }` table
+ *     of that tag's own entries, in that tag's own order (the era's own
+ *     `<era>_SURFACES` constant below) — so a later change to today's
+ *     `GATEABLE_SURFACES` can never move a byte of a legacy render.
+ *   - the `@working-theory/ui` import line stays fragment-assembled, exactly
+ *     as the original does, so THIS file never contains the literal import
+ *     string either (`tools/lint-architecture.ts` matches source text; see
+ *     the comment on each `navItemImport` below).
+ *
+ * The list is CLOSED (D2): after D1 ships, every published generator is
+ * unstamped only up to 0.8.0 (E4), so a future generator change never needs a
+ * fifth entry. Fixtures produced by each tag's own code (never by this
+ * vendored copy) pin these bodies exactly — see
+ * `__tests__/fixtures/legacy-nav/index.json`.
+ */
+/** One published nav-generator era, and the renderer that reproduces it byte-for-byte. */
+export interface LegacyNavRenderer {
+    /** Era label, E1–E4 (spec § 1.2). */
+    era: string;
+    /** Every published create-ailk tag that shipped this exact `renderNavConfig` body. */
+    tags: readonly string[];
+    /** The representative tag commit the body and fixtures were taken from. */
+    commit: string;
+    /** Render this era's nav for an enabled surface set — no `options`; no published era before #6878 D6 took one. */
+    render(enabled: readonly string[]): string;
+}
+/**
+ * The closed set of published, pre-stamp `renderNavConfig` bodies (D2).
+ * `add-module`'s `isUneditedNav` tries these, in order, against an unstamped
+ * nav (`surfaces.ts` `readNavConfigStamp` returning `"absent"`) before giving
+ * up and reporting it as customer-edited.
+ */
+export declare const LEGACY_NAV_RENDERERS: readonly LegacyNavRenderer[];