create-ailk 0.7.0 → 0.9.0

package/dist/design-package.js

@@ -0,0 +1,468 @@
+/**
+ * The design package (#6812, spec docs/specs/6812-the-design-package-design-md-spec.md
+ * D1/D2/D3/D5): a design is read from ONE file, `<dir>/DESIGN.md`, whose
+ * frontmatter is its whole authored schema.
+ *
+ * The dials decision: a design's authored data is its DESIGN.md frontmatter alone
+ * (Sam Henry, 2026-09-26, rel-023 plan §8). There is no separate dial file;
+ * the Markdown body is generated from the frontmatter in marked regions
+ * (`scripts/build-design-md.mjs`).
+ *
+ * `readDesignPackage` parses the frontmatter with a dependency-free subset of
+ * YAML 1.2 (D5) — `create-ailk` ships exactly one runtime dependency (`tar`,
+ * § 1.5), and this reader runs at scaffold time, so it cannot import the
+ * `yaml` package used elsewhere in this repo's build scripts. The subset
+ * never accepts an input the real YAML 1.2 core schema would read
+ * differently: anything the subset does not explicitly cover is refused
+ * rather than guessed at.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { TemplateLayoutError, validateTemplateLayout, } from "./site-chrome.js";
+// ── Public types ─────────────────────────────────────────────────────────────
+/** The closed colour key set (D3) — 13 required, 5 optional dark fallbacks. */
+export const DESIGN_COLOR_KEYS_REQUIRED = [
+    "bg",
+    "fg",
+    "surface",
+    "surface-secondary",
+    "border",
+    "text-muted",
+    "brand",
+    "fg-on-brand",
+    "accent",
+    "bg-dark",
+    "fg-dark",
+    "border-dark",
+    "brand-dark",
+];
+export const DESIGN_COLOR_KEYS_OPTIONAL = [
+    "surface-dark",
+    "surface-secondary-dark",
+    "text-muted-dark",
+    "fg-on-brand-dark",
+    "accent-dark",
+];
+/** Duplicated from `SiteThemeSchema`'s colour regex (D3) — proven equal by test. */
+export const DESIGN_COLOR_REGEX = /^(#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|rgb\(.+\)|rgba\(.+\)|hsl\(.+\)|hsla\(.+\)|var\(--[^)]+\))$/;
+/** Duplicated from `SiteThemeSchema`'s enums (D3) — proven equal by test. */
+export const DESIGN_CORNERS_VALUES = ["rounded", "square"];
+export const DESIGN_EYEBROW_CASE_VALUES = ["upper", "sentence"];
+export const DESIGN_PLACEHOLDERS_VALUES = ["outline", "fill"];
+export const DESIGN_CHECKMARKS_VALUES = ["circle", "plain"];
+/** The closed copy-density enum (spec 6892 D4). */
+export const DESIGN_COPY_DENSITY_VALUES = ["standard", "sparse"];
+/**
+ * Thrown by `readDesignPackage` on any malformed package (D2) — never thrown
+ * after a write; every refusal happens before any I/O beyond reading
+ * `DESIGN.md` itself.
+ */
+export class DesignPackageError extends Error {
+    file;
+    field;
+    constructor(file, field, reason) {
+        super(`${file}: ${field} — ${reason}`);
+        this.name = "DesignPackageError";
+        this.file = file;
+        this.field = field;
+    }
+}
+function refuse(file, field, reason) {
+    throw new DesignPackageError(file, field, reason);
+}
+function refuseFrontmatter(file, lineNo, reason) {
+    refuse(file, "frontmatter", `line ${lineNo}: ${reason}`);
+}
+/** Split frontmatter text into significant lines, refusing tabs as we go. */
+function toSignificantLines(text, file) {
+    const lines = [];
+    const rawLines = text.split("\n");
+    for (let i = 0; i < rawLines.length; i += 1) {
+        const lineNo = i + 1;
+        const raw = rawLines[i] ?? "";
+        if (raw.includes("\t")) {
+            refuseFrontmatter(file, lineNo, "tabs are not allowed");
+        }
+        const trimmed = raw.replace(/\s+$/, "");
+        if (trimmed === "")
+            continue;
+        const indent = /^ */.exec(trimmed)[0].length;
+        const content = trimmed.slice(indent);
+        if (content.startsWith("#"))
+            continue;
+        lines.push({ lineNo, indent, content });
+    }
+    return lines;
+}
+const KEY_RE = /^([A-Za-z0-9_-]+):(.*)$/;
+function parseDoubleQuoted(raw, lineNo, file) {
+    const m = /^"((?:\\.|[^"\\])*)"$/.exec(raw);
+    if (!m) {
+        refuseFrontmatter(file, lineNo, "unterminated or malformed double-quoted string");
+    }
+    const body = m[1] ?? "";
+    let result = "";
+    for (let i = 0; i < body.length; i += 1) {
+        const ch = body[i];
+        if (ch === "\\") {
+            const next = body[i + 1];
+            if (next === '"' || next === "\\") {
+                result += next;
+                i += 1;
+            }
+            else {
+                refuseFrontmatter(file, lineNo, `unsupported escape "\\${next ?? ""}"`);
+            }
+        }
+        else {
+            result += ch;
+        }
+    }
+    return result;
+}
+function parseSingleQuoted(raw, lineNo, file) {
+    const m = /^'((?:''|[^'])*)'$/.exec(raw);
+    if (!m) {
+        refuseFrontmatter(file, lineNo, "unterminated or malformed single-quoted string");
+    }
+    return (m[1] ?? "").replace(/''/g, "'");
+}
+const RESERVED_BOOLEAN_CASE_RE = /^(?:True|TRUE|False|FALSE)$/;
+const RESERVED_NULL_RE = /^(?:null|Null|NULL|~)$/;
+const RESERVED_INF_NAN_RE = /^[+-]?\.(?:inf|nan)$/i;
+const HEX_OCTAL_RE = /^[+-]?0[xXoO][0-9a-fA-F]+$/;
+const INT_RE = /^-?(?:0|[1-9][0-9]*)$/;
+const FLOAT_RE = /^-?(?:0|[1-9][0-9]*)\.[0-9]+$/;
+const EXPONENT_RE = /^-?[0-9]+(?:\.[0-9]+)?[eE][+-]?[0-9]+$/;
+const LEADING_ZERO_INT_RE = /^-?0[0-9]+$/;
+const LEADING_DOT_FLOAT_RE = /^[+-]?\.[0-9]+$/;
+function parsePlainScalar(raw, lineNo, file) {
+    if (raw.includes(": ") || raw.includes(" #") || raw.startsWith("#")) {
+        refuseFrontmatter(file, lineNo, 'a plain scalar must not contain ": " or " #"');
+    }
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    if (RESERVED_BOOLEAN_CASE_RE.test(raw)) {
+        refuseFrontmatter(file, lineNo, `"${raw}" is a reserved boolean literal — use lowercase true/false, or quote it`);
+    }
+    if (RESERVED_NULL_RE.test(raw)) {
+        refuseFrontmatter(file, lineNo, `"${raw}" is a reserved null literal — quote it if a string is meant`);
+    }
+    if (RESERVED_INF_NAN_RE.test(raw)) {
+        refuseFrontmatter(file, lineNo, `"${raw}" is a reserved inf/nan literal — quote it if a string is meant`);
+    }
+    if (HEX_OCTAL_RE.test(raw)) {
+        refuseFrontmatter(file, lineNo, `"${raw}" is a hex/octal literal, not supported — quote it if a string is meant`);
+    }
+    if (raw.startsWith("+")) {
+        refuseFrontmatter(file, lineNo, `"${raw}" has a leading "+", not supported — quote it if a string is meant`);
+    }
+    if (INT_RE.test(raw))
+        return Number(raw);
+    if (FLOAT_RE.test(raw))
+        return Number(raw);
+    if (EXPONENT_RE.test(raw)) {
+        refuseFrontmatter(file, lineNo, `"${raw}" is an exponent-form number, not supported — quote it if a string is meant`);
+    }
+    if (LEADING_ZERO_INT_RE.test(raw)) {
+        refuseFrontmatter(file, lineNo, `"${raw}" is a leading-zero integer, not supported — quote it if a string is meant`);
+    }
+    if (LEADING_DOT_FLOAT_RE.test(raw)) {
+        refuseFrontmatter(file, lineNo, `"${raw}" is a bare leading-dot float, not supported — quote it, or add a leading 0 before the "."`);
+    }
+    return raw;
+}
+function parseScalar(raw, lineNo, file) {
+    if (raw.startsWith('"'))
+        return parseDoubleQuoted(raw, lineNo, file);
+    if (raw.startsWith("'"))
+        return parseSingleQuoted(raw, lineNo, file);
+    if (/^[[{&*!|>]/.test(raw)) {
+        refuseFrontmatter(file, lineNo, "flow collections, anchors, aliases, tags and block scalars are not supported");
+    }
+    return parsePlainScalar(raw, lineNo, file);
+}
+/** Parse a block mapping starting at `pos.i`, whose keys sit at `indent`. */
+function parseMapping(lines, pos, indent, file) {
+    const result = {};
+    while (pos.i < lines.length && lines[pos.i].indent === indent) {
+        const line = lines[pos.i];
+        if (line.content === "-" || line.content.startsWith("- ")) {
+            refuseFrontmatter(file, line.lineNo, "sequences are not supported");
+        }
+        const m = KEY_RE.exec(line.content);
+        if (!m) {
+            refuseFrontmatter(file, line.lineNo, `expected "key: value", got "${line.content}"`);
+        }
+        const key = m[1];
+        const rawRest = m[2];
+        if (Object.hasOwn(result, key)) {
+            refuseFrontmatter(file, line.lineNo, `duplicate key "${key}"`);
+        }
+        pos.i += 1;
+        if (rawRest === "") {
+            const next = lines[pos.i];
+            if (next !== undefined && next.indent > indent) {
+                if (next.indent !== indent + 2) {
+                    refuseFrontmatter(file, next.lineNo, `bad indentation — expected ${indent + 2} spaces, got ${next.indent}`);
+                }
+                result[key] = parseMapping(lines, pos, next.indent, file);
+            }
+            else {
+                refuseFrontmatter(file, line.lineNo, `"${key}" has an empty value`);
+            }
+            continue;
+        }
+        if (!rawRest.startsWith(" ")) {
+            refuseFrontmatter(file, line.lineNo, 'expected a single space after ":"');
+        }
+        const rest = rawRest.slice(1);
+        if (rest === "" || rest.startsWith(" ")) {
+            refuseFrontmatter(file, line.lineNo, `"${key}" has an empty value`);
+        }
+        result[key] = parseScalar(rest, line.lineNo, file);
+        const next = lines[pos.i];
+        if (next !== undefined && next.indent > indent) {
+            refuseFrontmatter(file, next.lineNo, `unexpected indentation after "${key}"'s scalar value`);
+        }
+    }
+    return result;
+}
+/** Parse `<dir>/DESIGN.md`'s frontmatter into a plain object tree (D5). */
+function parseFrontmatter(text, file) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n[\s\S]*)?$/.exec(text);
+    if (!m) {
+        refuse(file, "frontmatter", "no closing --- found");
+    }
+    const lines = toSignificantLines(m[1] ?? "", file);
+    const pos = { i: 0 };
+    const result = parseMapping(lines, pos, 0, file);
+    if (pos.i < lines.length) {
+        const stray = lines[pos.i];
+        refuseFrontmatter(file, stray.lineNo, "unexpected indentation at the top level");
+    }
+    return result;
+}
+// ── Group validators (D2/D3) ────────────────────────────────────────────────
+function requireString(value, file, field) {
+    if (typeof value !== "string" || value.length === 0) {
+        refuse(file, field, "must be a non-empty string");
+    }
+    return value;
+}
+function requireObject(value, file, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        refuse(file, field, "must be an object");
+    }
+    return value;
+}
+function validateColors(raw, file) {
+    const obj = requireObject(raw, file, "colors");
+    const allowed = new Set([...DESIGN_COLOR_KEYS_REQUIRED, ...DESIGN_COLOR_KEYS_OPTIONAL]);
+    for (const key of Object.keys(obj)) {
+        if (!allowed.has(key)) {
+            refuse(file, `colors.${key}`, "is not a recognized colour key");
+        }
+    }
+    for (const key of DESIGN_COLOR_KEYS_REQUIRED) {
+        if (!(key in obj)) {
+            refuse(file, `colors.${key}`, "is required");
+        }
+    }
+    const result = {};
+    for (const key of Object.keys(obj)) {
+        const value = obj[key];
+        if (typeof value !== "string" || !DESIGN_COLOR_REGEX.test(value)) {
+            refuse(file, `colors.${key}`, "must be a hex/rgb()/rgba()/hsl()/hsla()/var(--…) colour string");
+        }
+        result[key] = value;
+    }
+    return result;
+}
+const TYPOGRAPHY_ROLE_KEYS = ["fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing"];
+function validateTypographyRole(raw, file, role) {
+    const obj = requireObject(raw, file, `typography.${role}`);
+    for (const key of Object.keys(obj)) {
+        if (!TYPOGRAPHY_ROLE_KEYS.includes(key)) {
+            refuse(file, `typography.${role}.${key}`, "is not a recognized typography field");
+        }
+    }
+    if (!("fontSize" in obj)) {
+        refuse(file, `typography.${role}.fontSize`, "is required");
+    }
+    const result = { fontSize: "" };
+    for (const [key, value] of Object.entries(obj)) {
+        const field = `typography.${role}.${key}`;
+        if (key === "fontFamily" || key === "fontSize" || key === "letterSpacing") {
+            if (typeof value !== "string")
+                refuse(file, field, "must be a string");
+            if (key === "fontFamily")
+                result.fontFamily = value;
+            else if (key === "fontSize")
+                result.fontSize = value;
+            else
+                result.letterSpacing = value;
+        }
+        else if (key === "fontWeight" || key === "lineHeight") {
+            if (typeof value !== "number")
+                refuse(file, field, "must be a number");
+            if (key === "fontWeight")
+                result.fontWeight = value;
+            else
+                result.lineHeight = value;
+        }
+    }
+    return result;
+}
+function validateTypography(raw, file) {
+    const obj = requireObject(raw, file, "typography");
+    const result = {};
+    for (const [role, value] of Object.entries(obj)) {
+        result[role] = validateTypographyRole(value, file, role);
+    }
+    return result;
+}
+function validateStringMap(raw, file, field) {
+    const obj = requireObject(raw, file, field);
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (typeof value !== "string") {
+            refuse(file, `${field}.${key}`, "must be a string");
+        }
+        result[key] = value;
+    }
+    return result;
+}
+const LAYOUT_KEYS = ["nav", "footer", "announcementBanner", "home"];
+function validateLayout(raw, file) {
+    const obj = requireObject(raw, file, "layout");
+    for (const key of Object.keys(obj)) {
+        if (!LAYOUT_KEYS.includes(key)) {
+            refuse(file, `layout.${key}`, "is not a recognized layout key");
+        }
+    }
+    for (const key of LAYOUT_KEYS) {
+        if (!(key in obj)) {
+            refuse(file, `layout.${key}`, "is required");
+        }
+    }
+    try {
+        return validateTemplateLayout(obj, "design package");
+    }
+    catch (error) {
+        if (error instanceof TemplateLayoutError) {
+            const match = /: (layout\.[A-Za-z]+) must /.exec(error.message);
+            refuse(file, match?.[1] ?? "layout", error.message);
+        }
+        throw error;
+    }
+}
+const TREATMENTS_ENUMS = {
+    corners: DESIGN_CORNERS_VALUES,
+    eyebrowCase: DESIGN_EYEBROW_CASE_VALUES,
+    placeholders: DESIGN_PLACEHOLDERS_VALUES,
+    checkmarks: DESIGN_CHECKMARKS_VALUES,
+};
+function validateTreatments(raw, file) {
+    const obj = requireObject(raw, file, "treatments");
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const values = TREATMENTS_ENUMS[key];
+        if (values === undefined) {
+            refuse(file, `treatments.${key}`, "is not a recognized treatment");
+        }
+        if (typeof value !== "string" || !values.includes(value)) {
+            refuse(file, `treatments.${key}`, `must be one of ${values.join(", ")}`);
+        }
+        result[key] = value;
+    }
+    return result;
+}
+function validateSections(raw, file) {
+    const obj = requireObject(raw, file, "sections");
+    const result = {};
+    for (const [pageType, value] of Object.entries(obj)) {
+        result[pageType] = requireObject(value, file, `sections.${pageType}`);
+    }
+    return result;
+}
+function validateCopy(raw, file) {
+    const obj = requireObject(raw, file, "copy");
+    for (const key of Object.keys(obj)) {
+        if (key !== "density") {
+            refuse(file, `copy.${key}`, "is not a recognized copy key");
+        }
+    }
+    const density = obj["density"];
+    if (typeof density !== "string" ||
+        !DESIGN_COPY_DENSITY_VALUES.includes(density)) {
+        refuse(file, "copy.density", `must be one of ${DESIGN_COPY_DENSITY_VALUES.join(", ")}`);
+    }
+    return { density: density };
+}
+const TOP_LEVEL_KEYS = [
+    "name",
+    "description",
+    "colors",
+    "typography",
+    "rounded",
+    "spacing",
+    "layout",
+    "treatments",
+    "sections",
+    "copy",
+];
+const REQUIRED_TOP_LEVEL_KEYS = [
+    "name",
+    "description",
+    "colors",
+    "typography",
+    "rounded",
+    "spacing",
+    "layout",
+];
+function validatePackage(raw, file) {
+    for (const key of Object.keys(raw)) {
+        if (!TOP_LEVEL_KEYS.includes(key)) {
+            refuse(file, key, "is not a recognized design-package key");
+        }
+    }
+    for (const key of REQUIRED_TOP_LEVEL_KEYS) {
+        if (!(key in raw)) {
+            refuse(file, key, "is required");
+        }
+    }
+    const pkg = {
+        name: requireString(raw.name, file, "name"),
+        description: requireString(raw.description, file, "description"),
+        colors: validateColors(raw.colors, file),
+        typography: validateTypography(raw.typography, file),
+        rounded: validateStringMap(raw.rounded, file, "rounded"),
+        spacing: validateStringMap(raw.spacing, file, "spacing"),
+        layout: validateLayout(raw.layout, file),
+        sections: "sections" in raw ? validateSections(raw.sections, file) : {},
+        copy: "copy" in raw ? validateCopy(raw.copy, file) : { density: "standard" },
+    };
+    if ("treatments" in raw) {
+        pkg.treatments = validateTreatments(raw.treatments, file);
+    }
+    return pkg;
+}
+/**
+ * Read and validate `<dir>/DESIGN.md`'s frontmatter into a typed
+ * `DesignPackage` (D1/D2). Refuses — naming the file and the field — on any
+ * malformed package: a missing file, an unknown key, a wrong type, an
+ * unknown layout value. Nothing is written; this function has no side
+ * effects beyond the one read.
+ */
+export function readDesignPackage(dir) {
+    const file = join(dir, "DESIGN.md");
+    if (!existsSync(file)) {
+        refuse(file, "DESIGN.md", "file does not exist");
+    }
+    const text = readFileSync(file, "utf8");
+    const raw = parseFrontmatter(text, file);
+    return validatePackage(raw, file);
+}

package/dist/design-presets.d.ts

@@ -0,0 +1,86 @@
+import { type DesignSections } from "./design-package.js";
+export interface SectionLookCatalogEntry {
+    /** The look group, in registry order (D2). */
+    readonly look: readonly string[];
+    /** The type's `data` JSON Schema `properties` (the catalog's `schema.properties`). */
+    readonly properties: Readonly<Record<string, unknown>>;
+}
+export type SectionLookCatalog = Readonly<Record<string, SectionLookCatalogEntry>>;
+/** Read `<pkgRoot>/component-catalog.json` into the look catalog. Throws naming the file on a missing `look` or `schema`. */
+export declare function readSectionLookCatalog(catalogPath: string): SectionLookCatalog;
+/**
+ * Every `pageType` named by a row of a shipped `TEMPLATE-MANIFEST.json` under
+ * `<siteTemplatesDir>/*`, `<siteTemplatesDir>/shapes/*`, and — a treeless
+ * alias's own GENERATED record (spec 6892 D1/D5), which has no directory of
+ * its own — every `<siteTemplatesDir>/aliases/*.TEMPLATE-MANIFEST.json` file.
+ */
+export declare function shippedPageTypes(siteTemplatesDir: string): ReadonlySet<string>;
+/**
+ * Refuse, with a `DesignPackageError` whose `field` names the page type, the
+ * section type and the field, the first preset (key order) that names a page
+ * type no shipped roster places, an unregistered section type, a field
+ * outside the type's look group, or a value outside that field's schema
+ * (D3's table, R1–R5b). A valid block returns without effect. Pure.
+ */
+export declare function validateDesignPresets(sections: DesignSections, opts: {
+    catalog: SectionLookCatalog;
+    pageTypes: ReadonlySet<string>;
+    file: string;
+}): void;
+/** One `data` entry: its key and the `[valueStart, valueEnd)` span of its value. */
+export interface LocatedDataEntry {
+    readonly key: string;
+    readonly valueStart: number;
+    readonly valueEnd: number;
+}
+/** One `sections[]` element, located in the page text. */
+export interface LocatedSection {
+    readonly type: string;
+    readonly form: "flow" | "block";
+    /** Flow: the index of `data`'s `{`. Block: the end of the `data:` line (before its newline). */
+    readonly dataOpen: number;
+    /** Flow: the index of `data`'s `}`. Block: `dataOpen`. */
+    readonly dataClose: number;
+    /** Block only: the column `data`'s entries sit at. */
+    readonly entryColumn: number;
+    readonly entries: readonly LocatedDataEntry[];
+}
+/**
+ * Locate a page's `sections[]` in its frontmatter — the prettier-formatted
+ * flow form (`sections:\n  [ { "id": …, "type": …, "data": { … } }, … ]`)
+ * or the block form (`  - id: …\n    type: …\n    data:\n      key: value`).
+ * Undefined when the page has no frontmatter or no column-0 `sections:` key.
+ * Any other shape throws `TemplateError` naming the element (D5).
+ */
+export declare function locatePageSections(text: string, file: string): LocatedSection[] | undefined;
+export interface PresetPage {
+    readonly path: string;
+    readonly text: string;
+}
+export interface PresetApplication {
+    readonly path: string;
+    readonly pageType: string;
+    readonly index: number;
+    readonly sectionType: string;
+    readonly field: string;
+}
+/**
+ * Set one look field on section `index` of a page, splicing only its value
+ * span (D5): an existing value is replaced; an absent field is inserted as
+ * `data`'s first entry. Throws `TemplateError` when the page cannot be located.
+ */
+export declare function setSectionLookField(text: string, file: string, index: number, field: string, value: unknown): string;
+/**
+ * Write a validated preset block's look fields onto the sections a page
+ * already places, for the pages whose `type:` is in `opts.pageTypes` (the
+ * roster's placed set) and has a preset. Never adds, removes, reorders,
+ * retypes or re-ids a section; never changes a byte outside the value it
+ * sets. Returns only the pages whose text changed. Pure; trusts its input to
+ * have passed `validateDesignPresets`.
+ */
+export declare function applyDesignPresets(pages: readonly PresetPage[], sections: DesignSections, opts: {
+    pageTypes: ReadonlySet<string>;
+}): {
+    pages: PresetPage[];
+    applied: PresetApplication[];
+};