create-ailk 0.7.0 → 0.9.0

package/dist/apply-design.js

@@ -0,0 +1,273 @@
+/**
+ * `create-ailk apply-design <name|path> [--target <site-dir>]` — make an
+ * existing site wear a design, changing only how it LOOKS (#6819, spec
+ * docs/specs/6819-apply-design-name-path-one-spec.md).
+ *
+ * Composes four already-shipped units and edits none of them: #6813's
+ * resolver and theme splicer, #6816's preset validator and applier, #6760's
+ * design gate and #6813's manifest writer. Every refusal happens before the
+ * first write (D3); every new text is planned in memory, then written in one
+ * pass (D4). Routes, content fields, `brand:` and structured data never move.
+ *
+ * Reads no module URL of its own — every package directory it reads is passed in
+ * — so Jest's CJS transform can import it, unlike `programmatic.ts`.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { parseArgs } from "node:util";
+import { planDesignMd } from "./apply-design-md.js";
+import { compileDesignTheme } from "./design-compile.js";
+import { applyDesignPresets, readSectionLookCatalog, shippedPageTypes, validateDesignPresets, } from "./design-presets.js";
+import { resolveDesign, spliceThemeBlock } from "./design-scaffold.js";
+import { LICENSE_KEY_FILE } from "./lib/license-key-files.js";
+import { CONVERSION_HINT_URL, LicenseRequiredError, assertDesignAllowed, deriveLevel, } from "./lib/module-license-gate.js";
+import { LEVEL_LABEL } from "./lib/module-tier.js";
+import { ParseError } from "./parse-args.js";
+import { SITE_CHROME_PATH, renderSiteChrome, resolveSiteChrome, } from "./site-chrome.js";
+import { SITE_ROSTER_PATH, planSiteManifestDesign, readSiteRoster, } from "./site-roster.js";
+export const APPLY_DESIGN_HELP = `create-ailk apply-design — make an existing site wear a design.
+
+Usage:
+  create-ailk apply-design <name> [--target <site-dir>]
+  create-ailk apply-design <path> [--target <site-dir>]
+
+Arguments:
+  <name|path>              A shipped design (standard, minimalism), or a
+                           directory holding a DESIGN.md. A relative path
+                           resolves from the current directory.
+
+Options:
+  --target <site-dir>      An already-scaffolded repo (contains
+                           architecture.yaml). Defaults to the current dir.
+  --help, -h               Print this message.
+
+Writes only the look: DESIGN.md (replaced whole by the design's, keeping the
+site's Source template and Version lines), the theme: block of
+content/_site.mdx, the generated apps/web/lib/site-chrome.ts, the look fields
+of sections the site's pages already place, and the design/layout/theme record
+in .ailk-site-manifest.json.
+Never adds, removes or renames a route or page, never touches a content field
+or the brand: block, and leaves every page's structured data unchanged.
+
+A design other than standard needs a Pro or Pro Plus key: the site's own
+ailk.key (put one there with create-ailk license set <key>), else
+AILK_LICENSE_KEY. A malformed package, a preset the validator refuses or a
+missing key is refused before any file is written.
+
+A preset sets the look fields it names and never unsets one: a field it does
+not name keeps whatever value the page has. Running it again changes nothing.
+`;
+/**
+ * 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 function parseApplyDesignArgs(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        strict: true,
+        allowPositionals: true,
+        options: {
+            target: { type: "string" },
+            help: { type: "boolean", default: false, short: "h" },
+        },
+    });
+    const help = parsed.values.help === true;
+    if (parsed.positionals.length > 1) {
+        throw new ParseError(`expected one design (a name or a directory), got ${parsed.positionals.length} arguments`);
+    }
+    const design = parsed.positionals[0];
+    if (design === undefined && !help) {
+        throw new ParseError("apply-design needs a design. Usage: create-ailk apply-design <name|path> [--target <site-dir>]");
+    }
+    return { design, target: parsed.values.target, help };
+}
+/** `abs` relative to `root`, with `/` separators. */
+function siteRelative(root, abs) {
+    return relative(root, abs).split(sep).join("/");
+}
+/** Every `.mdx` under `dir`, sorted by path (D4 step 3). */
+function listMdxFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    const stack = [dir];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            const abs = join(current, entry.name);
+            if (entry.isDirectory())
+                stack.push(abs);
+            else if (entry.name.endsWith(".mdx"))
+                out.push(abs);
+        }
+    }
+    return out.sort();
+}
+/** The site's own key (D6): `<target>/ailk.key`, else `AILK_LICENSE_KEY`, else none. */
+function readSiteKey(targetAbs, env) {
+    const keyPath = join(targetAbs, LICENSE_KEY_FILE);
+    if (existsSync(keyPath)) {
+        const key = readFileSync(keyPath, "utf8").trim();
+        if (key.length > 0)
+            return key;
+    }
+    const fromEnv = env["AILK_LICENSE_KEY"];
+    return fromEnv !== undefined && fromEnv.length > 0 ? fromEnv : undefined;
+}
+/**
+ * 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 async function applyDesign(opts) {
+    const targetAbs = resolve(opts.targetDir);
+    const env = opts.env ?? process.env;
+    // C1 — a scaffolded repo (the `addModule` wording).
+    if (!existsSync(targetAbs)) {
+        throw new Error(`apply-design target does not exist: ${targetAbs}. Point apply-design at an already-scaffolded repo.`);
+    }
+    if (!statSync(targetAbs).isDirectory()) {
+        throw new Error(`apply-design 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.`);
+    }
+    // C2 — the site config the theme lives in.
+    const siteMdxPath = join(targetAbs, "content", "_site.mdx");
+    if (!existsSync(siteMdxPath)) {
+        throw new Error(`no content/_site.mdx at ${targetAbs}: there is no theme to replace`);
+    }
+    // C3 — resolve (a malformed package throws DesignPackageError, naming the field).
+    const resolved = resolveDesign(opts.design, {
+        designsDir: opts.designsDir,
+        cwd: opts.cwd ?? process.cwd(),
+    });
+    const { pkg } = resolved;
+    const hasPresets = Object.keys(pkg.sections).length > 0;
+    // C4 — the presets, validated exactly as scaffold() validates them.
+    if (hasPresets) {
+        validateDesignPresets(pkg.sections, {
+            catalog: readSectionLookCatalog(opts.catalogPath),
+            pageTypes: shippedPageTypes(opts.siteTemplatesDir),
+            file: join(resolved.dir, "DESIGN.md"),
+        });
+    }
+    // C5 — the design gate, fed the site's own key (D6). A Free design reads no key.
+    if (!resolved.free) {
+        const key = readSiteKey(targetAbs, env);
+        const { level } = await deriveLevel({
+            licenseKey: key ?? "",
+            ...(opts.registryUrl !== undefined ? { registryUrl: opts.registryUrl } : {}),
+            ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+        });
+        try {
+            assertDesignAllowed(resolved.display, level, false);
+        }
+        catch (err) {
+            if (!(err instanceof LicenseRequiredError))
+                throw err;
+            throw new LicenseRequiredError(`design "${resolved.display}" is a Pro feature — this site's licence level is ${LEVEL_LABEL[level]}; put a Pro or Pro Plus key in the site with create-ailk license set <key>, or set AILK_LICENSE_KEY → ${CONVERSION_HINT_URL}`);
+        }
+    }
+    // C6 / D4 — plan every write in memory.
+    const theme = compileDesignTheme(pkg);
+    const siteMdxCurrent = readFileSync(siteMdxPath, "utf8");
+    const siteMdxNext = spliceThemeBlock(siteMdxCurrent, theme, siteMdxPath);
+    const roster = readSiteRoster(targetAbs);
+    const chrome = resolveSiteChrome(roster?.template.layout, pkg.layout);
+    const chromePath = join(targetAbs, SITE_CHROME_PATH);
+    const chromeCurrent = existsSync(chromePath) ? readFileSync(chromePath, "utf8") : undefined;
+    const chromeNext = renderSiteChrome(chrome);
+    const designMdPath = join(targetAbs, "DESIGN.md");
+    const designMdCurrent = existsSync(designMdPath) ? readFileSync(designMdPath, "utf8") : undefined;
+    const designMdNext = planDesignMd(resolved.dir, targetAbs);
+    const pageWrites = [];
+    if (hasPresets && roster !== undefined) {
+        const pageTypes = new Set();
+        for (const row of roster.rows) {
+            const pageType = row.value["pageType"];
+            if (typeof pageType === "string")
+                pageTypes.add(pageType);
+        }
+        const contentDir = join(targetAbs, "content");
+        const pages = listMdxFiles(contentDir)
+            .filter((path) => path !== siteMdxPath)
+            .map((path) => ({ path, text: readFileSync(path, "utf8") }));
+        const presetResult = applyDesignPresets(pages, pkg.sections, { pageTypes });
+        for (const page of presetResult.pages) {
+            const fields = [
+                ...new Set(presetResult.applied
+                    .filter((a) => a.path === page.path)
+                    .map((a) => `${a.sectionType}.${a.field}`)),
+            ].sort();
+            pageWrites.push({ path: page.path, text: page.text, fields });
+        }
+    }
+    let manifest = "no-roster";
+    let manifestNext;
+    const rosterAbs = roster !== undefined ? join(targetAbs, roster.path) : undefined;
+    if (roster !== undefined && rosterAbs !== undefined) {
+        if (roster.path === SITE_ROSTER_PATH) {
+            manifestNext = planSiteManifestDesign(readFileSync(rosterAbs, "utf8"), { design: resolved.recorded, layout: chrome, theme }, rosterAbs);
+            manifest = manifestNext === undefined ? "unchanged" : "recorded";
+        }
+        else {
+            manifest = "legacy-roster";
+        }
+    }
+    // Write — page files, site-chrome.ts, DESIGN.md, _site.mdx, the manifest last (D4).
+    const changes = [];
+    for (const page of pageWrites) {
+        writeFileSync(page.path, page.text);
+        changes.push({ path: siteRelative(targetAbs, page.path), kind: "preset", fields: page.fields });
+    }
+    if (chromeNext !== chromeCurrent) {
+        mkdirSync(dirname(chromePath), { recursive: true });
+        writeFileSync(chromePath, chromeNext);
+        changes.push({ path: SITE_CHROME_PATH, kind: "layout" });
+    }
+    if (designMdNext !== designMdCurrent) {
+        writeFileSync(designMdPath, designMdNext);
+        changes.push({ path: "DESIGN.md", kind: "design" });
+    }
+    if (siteMdxNext !== siteMdxCurrent) {
+        writeFileSync(siteMdxPath, siteMdxNext);
+        changes.push({ path: "content/_site.mdx", kind: "theme" });
+    }
+    if (manifestNext !== undefined && rosterAbs !== undefined) {
+        writeFileSync(rosterAbs, manifestNext);
+        changes.push({ path: SITE_ROSTER_PATH, kind: "manifest" });
+    }
+    return {
+        targetDir: targetAbs,
+        design: resolved.recorded,
+        display: resolved.display,
+        changes,
+        manifest,
+        ...(roster !== undefined ? { rosterPath: roster.path } : {}),
+    };
+}
+/** The changed-file report (D9). */
+export function formatApplyDesignReport(result) {
+    const lines = [];
+    if (result.changes.length === 0) {
+        lines.push(`[create-ailk] The site already wears design "${result.design}" — no file changed.`);
+    }
+    else {
+        lines.push(`[create-ailk] Applied design "${result.design}" to ${result.targetDir}`);
+        for (const change of result.changes) {
+            const suffix = change.kind === "preset" ? ` (${change.fields.join(", ")})` : "";
+            lines.push(`  ${change.kind.padEnd(8)}  ${change.path}${suffix}`);
+        }
+        const n = result.changes.length;
+        lines.push(`${n} file${n === 1 ? "" : "s"} changed. Routes, page content and structured data are unchanged.`);
+    }
+    if (result.manifest === "legacy-roster") {
+        lines.push(`manifest not recorded: ${result.rosterPath} predates the design record`);
+    }
+    else if (result.manifest === "no-roster") {
+        lines.push(`manifest not recorded: the site has no ${SITE_ROSTER_PATH}`);
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/claude-md.d.ts

@@ -0,0 +1,111 @@
+/** The drift check a scaffold ships (`template-overlay/tools/`). */
+export declare const CLAUDE_MD_CHECK_PATH = "tools/check-claude-md.ts";
+/**
+ * SHA-256 of every `templates/CLAUDE.md` a published create-ailk shipped
+ * before markers existed, with `{{PROJECT_NAME}}` unsubstituted (spec § 1.7,
+ * D4). An unmarked scaffold `CLAUDE.md` that hashes to one of these after
+ * undoing the name substitution was never edited by its owner.
+ */
+export declare const LEGACY_TEMPLATE_SHA256: readonly string[];
+export interface ClaudeMdRegion {
+    id: string;
+    /** The recorded hash, or undefined when the begin marker carries none. */
+    sha256: string | undefined;
+    /** Index of the begin line's first character. */
+    start: number;
+    /** Index just past the end line's newline (or end of text). */
+    end: number;
+    /** Every character between the begin line's newline and the end line. */
+    body: string;
+}
+export interface ParsedClaudeMd {
+    regions: ClaudeMdRegion[];
+    /** Index of the first `<!-- ailk:site -->` line, when there is one. */
+    siteStart: number | undefined;
+    /** Structural faults, in file order. Empty for a well-formed file. */
+    faults: string[];
+    /** True when the file carries any region or site marker at all. */
+    marked: boolean;
+}
+/** SHA-256, lowercase hex, of a region body with every CRLF folded to LF (D2). */
+export declare function hashBody(body: string): string;
+/** Parse a `CLAUDE.md` against the D1 grammar. Never throws. */
+export declare function parseClaudeMd(text: string): ParsedClaudeMd;
+/**
+ * Render the committed template for a project (D2): substitute the scaffold
+ * markers, then stamp each begin marker with its body's hash. LF output.
+ *
+ * @throws Error when the template is malformed or a begin marker already
+ *   carries a hash — a hash is never committed by hand.
+ */
+export declare function renderClaudeMd(templateText: string, projectName: string): string;
+export interface ClaudeMdDrift {
+    /** No file, a file with no markers at all, or a marked one. */
+    state: "missing" | "unmarked" | "marked";
+    /** Ids of regions whose body no longer matches the recorded hash. */
+    edited: string[];
+    /** Structural faults, including a begin marker with no sha256. */
+    faults: string[];
+}
+/**
+ * The drift verdict for a rendered file (D6). `undefined` = no file. The
+ * reference implementation `tools/check-claude-md.ts` is held to.
+ */
+export declare function findDrift(text: string | undefined): ClaudeMdDrift;
+/** The drift check's output lines; empty means the file passes. */
+export declare function formatDrift(drift: ClaudeMdDrift): string[];
+export interface ClaudeMdMerge {
+    text: string;
+    /** Regions whose bytes the sync changed. */
+    updated: string[];
+    /** Regions the current template has and the file lacked. */
+    added: string[];
+    /** Regions the file had and the current template retired. */
+    removed: string[];
+    /** Regions whose hand-edited body the sync replaced. */
+    overwritten: string[];
+}
+/**
+ * Rewrite a marked file's template-owned regions to a rendered template (D3).
+ * Every character outside a region — the gaps and the whole site section —
+ * is copied through unchanged, except the one blank line a retired region
+ * takes with it. Regions and inserted separators are written in the file's
+ * own line ending, so a CRLF checkout stays CRLF and syncs idempotently.
+ *
+ * @throws Error naming the fault when the file is structurally malformed.
+ */
+export declare function mergeClaudeMd(fileText: string, renderedText: string): ClaudeMdMerge;
+/**
+ * True when an unmarked `CLAUDE.md` is a published template the owner never
+ * changed (D4): with some candidate project name un-substituted, it hashes to
+ * a `LEGACY_TEMPLATE_SHA256` entry. A miss is always safe — it refuses.
+ */
+export declare function isUneditedLegacy(text: string, names: string[]): boolean;
+export interface SyncClaudeMdResult {
+    /** Resolved absolute path to the synced directory. */
+    targetDir: string;
+    /** Absolute path of the `CLAUDE.md` read and (maybe) written. */
+    claudeMdPath: string;
+    /**
+     * `created` — there was no file; `replaced-legacy` — an unedited pre-marker
+     * template was replaced; `updated` / `unchanged` — a marked file was synced.
+     */
+    action: "created" | "replaced-legacy" | "updated" | "unchanged";
+    updated: string[];
+    added: string[];
+    removed: string[];
+    overwritten: string[];
+    /** True when the site lacks `tools/check-claude-md.ts` or its script. */
+    missingDriftCheck: boolean;
+}
+/**
+ * `--sync-claude-md` (D3): the `syncCatalogSync` shape — validate the target
+ * is an existing scaffold, write at most its `CLAUDE.md`, spawn nothing. An
+ * unmarked file is replaced only when it is an unedited published template
+ * (D4); anything else unmarked, or a structural fault, is refused with
+ * nothing written.
+ */
+export declare function syncClaudeMd(opts: {
+    targetDir: string;
+    templateText: string;
+}): SyncClaudeMdResult;