create-ailk 0.6.1 → 0.7.0

package/dist/add-module.js

@@ -0,0 +1,334 @@
+/**
+ * `create-ailk add-module <module>` (alias `upgrade`) — apply a purchased
+ * module to a site that was scaffolded without it, in place (#6653).
+ *
+ * A Free customer who buys Pro already has a site. `scaffold()` merges a
+ * module bundle only onto a fresh tree; this merges one onto a tree someone
+ * has lived in, under the plus-config policy (operator-disposed 2026-09-24):
+ *
+ *   - a file the tree lacks is written;
+ *   - a file the tree has is never overwritten — when its bytes differ from
+ *     the bundle's it is reported `skipped` with the exact change the bundle
+ *     wanted (a manual-review item), and when they match it is not reported;
+ *   - the bundle's `patches` are the only edits to an existing file, and only
+ *     to the config allowlist: `package.json` dependency/script keys,
+ *     `next.config.*`, `jest.config.*`.
+ *
+ * Then the module's route surfaces are synced in (`syncRoutes` with the
+ * module's surfaces forced carried), `architecture.yaml` is regenerated from
+ * the site's current module set plus this one, and the generated nav follows
+ * the new surfaces unless the site has edited it. Run twice, the second run
+ * changes nothing and reports nothing.
+ *
+ * Pure module: no `import.meta.url`, so jest can import it directly — the
+ * package-rooted inputs (`templatesDir`, `versions`) and the fetched bundle
+ * bytes are supplied by `programmatic.ts`'s `addModule`, the same split as
+ * `sync-routes.ts` / `syncRoutesSync`.
+ */
+import { existsSync, readFileSync, readdirSync, rmSync, rmdirSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { AddModuleRefusedError, readArchitectureHeader, } from "./add-module-core.js";
+import { deriveArchitecture } from "./derive-architecture.js";
+import { diffTwoStrings, extractModuleBundle, } from "./lib/extract-module-bundle.js";
+import { normalizeModules } from "./module-architecture.js";
+import { ParseError, parseModules } from "./parse-args.js";
+import { SITE_ROSTER_PATH, moduleRosterRows, planRosterAppend, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
+import { MODULE_SURFACES, NAV_CONFIG_PATH, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
+import { syncRoutes } from "./sync-routes.js";
+export { AddModuleRefusedError, readArchitectureHeader };
+/** `package.json` paths a `json` patch may write under the plus-config policy. */
+const PACKAGE_JSON_PATCH_KEYS = new Set([
+    "dependencies",
+    "devDependencies",
+    "scripts",
+]);
+/**
+ * Refuse a bundle whose `patches` reach past the plus-config allowlist
+ * (#6653 D3), matched on the target's basename so any depth qualifies:
+ * `package.json` (only `merge-keys`/`append-unique` on a dependency or script
+ * key), `next.config.*`, `jest.config.*`. Runs inside `installBundleTree`
+ * after the patches validate and before any is computed or written.
+ */
+export function checkPlusConfigPatches(patches) {
+    for (const patch of patches) {
+        const name = basename(patch.target);
+        if (name === "package.json") {
+            for (const op of patch.ops) {
+                const allowed = (op.op === "merge-keys" || op.op === "append-unique") &&
+                    op.path.length > 0 &&
+                    PACKAGE_JSON_PATCH_KEYS.has(op.path[0]);
+                if (!allowed) {
+                    throw new AddModuleRefusedError(`the module bundle patches ${patch.target} outside its dependency and script keys — add-module only patches dependencies, devDependencies and scripts there`);
+                }
+            }
+            continue;
+        }
+        if (/^next\.config\.[^/]+$/.test(name) ||
+            /^jest\.config\.[^/]+$/.test(name)) {
+            continue;
+        }
+        throw new AddModuleRefusedError(`the module bundle patches ${patch.target}, which is outside the config files add-module may edit (package.json, next.config.*, jest.config.*)`);
+    }
+}
+/**
+ * Merge one module's bundle onto an existing site, sync its routes,
+ * regenerate `architecture.yaml` and the nav, then append the module's pages
+ * to the site's roster. Every refusal — an unreadable header or roster, a
+ * module row no shipped manifest carries, a patch outside the allowlist, a
+ * patch conflict, an unsafe bundle — throws before the first write (the header
+ * and roster are read first; `extractModuleBundle` validates and computes
+ * everything before it copies).
+ */
+export async function applyModuleToScaffold(opts) {
+    const targetAbs = resolve(opts.targetDir);
+    const archPath = join(targetAbs, "architecture.yaml");
+    const current = readArchitectureHeader(readFileSync(archPath, "utf8"));
+    const modules = normalizeModules([...current.modules, opts.moduleName]);
+    // Resolved before the first write: a header surface that is unknown, or
+    // belongs to a module the site does not carry, is a refusal with the tree
+    // untouched — not a failure after the bundle has landed.
+    let surfaces;
+    try {
+        surfaces = resolveSurfaces(modules, current.surfaces);
+    }
+    catch (err) {
+        throw new AddModuleRefusedError(`architecture.yaml's \`# Surfaces:\` header cannot be carried forward: ${err.message}`);
+    }
+    // The roster and every module row it may need, likewise before the first
+    // write. A template-less site has no roster and needs none.
+    const siteRoster = readSiteRoster(targetAbs);
+    const references = siteRoster === undefined
+        ? []
+        : modules.flatMap((m) => moduleRosterRows(m, opts.siteTemplatesDir));
+    const { report } = await extractModuleBundle({
+        bytes: opts.bundleBytes,
+        targetDir: targetAbs,
+        moduleName: opts.moduleName,
+        versions: opts.versions,
+        markers: opts.markers,
+        existingFilePolicy: "skip-existing",
+        checkPatches: checkPlusConfigPatches,
+    });
+    const routes = syncRoutes({
+        targetDir: targetAbs,
+        templatesDir: opts.templatesDir,
+        versions: opts.versions,
+        apply: true,
+        forceSurfaces: MODULE_SURFACES[opts.moduleName] ?? [],
+    });
+    // The same composition `syncArchitectureSync` writes — a pure function of
+    // the module set, so an unchanged set rewrites identical bytes.
+    writeFileSync(archPath, deriveArchitecture(modules, surfaces));
+    const rows = [...report];
+    const navRow = syncNavConfig(targetAbs, current.surfaces, surfaces);
+    if (navRow !== undefined)
+        rows.push(navRow);
+    const roster = {
+        state: "none",
+        appended: [],
+        removed: [],
+        problems: [],
+        path: siteRoster?.path ?? SITE_ROSTER_PATH,
+    };
+    if (siteRoster !== undefined) {
+        // After the bundle has landed: a `contentDir` row's form follows the
+        // seeds now on disk.
+        const plan = planRosterAppend({
+            targetDir: targetAbs,
+            roster: siteRoster,
+            modules,
+            references,
+            siteTemplatesDir: opts.siteTemplatesDir,
+            templatesDir: opts.templatesDir,
+            markers: opts.markers,
+        });
+        for (const seed of plan.seeds) {
+            if (seed.remove) {
+                const abs = join(targetAbs, seed.path);
+                rmSync(abs);
+                if (readdirSync(dirname(abs)).length === 0)
+                    rmdirSync(dirname(abs));
+                rows.push({ path: seed.path, action: "removed" });
+                roster.removed.push(seed.path);
+            }
+            else {
+                rows.push({ path: seed.path, action: "skipped", wanted: seed.wanted });
+            }
+        }
+        if (plan.next !== undefined) {
+            writeFileSync(join(targetAbs, siteRoster.path), plan.next);
+            rows.push({
+                path: siteRoster.path,
+                action: "patched",
+                change: diffTwoStrings(siteRoster.path, siteRoster.text, plan.next, true),
+            });
+        }
+        roster.state = plan.next === undefined ? "unchanged" : "appended";
+        roster.appended = plan.appended;
+        roster.problems = siteRosterProblems({
+            targetDir: targetAbs,
+            siteTemplatesDir: opts.siteTemplatesDir,
+            templatesDir: opts.templatesDir,
+        });
+    }
+    return { targetDir: targetAbs, modules, report: rows, routes, roster };
+}
+/**
+ * Regenerate the site nav (`scaffoldSync` writes it from the surface set) for
+ * the new surfaces — but only when the site's copy is still exactly what the
+ * OLD surface set generates. An edited nav is the customer's file: left as-is
+ * and reported `skipped` with the change, like any other.
+ */
+function syncNavConfig(targetAbs, before, after) {
+    const navPath = join(targetAbs, NAV_CONFIG_PATH);
+    const wanted = renderNavConfig(after);
+    const existing = existsSync(navPath)
+        ? readFileSync(navPath, "utf8")
+        : undefined;
+    if (existing === wanted)
+        return undefined;
+    if (existing === undefined || existing === renderNavConfig(before)) {
+        writeFileSync(navPath, wanted);
+        return { path: NAV_CONFIG_PATH, action: "written" };
+    }
+    return {
+        path: NAV_CONFIG_PATH,
+        action: "skipped",
+        wanted: diffTwoStrings(NAV_CONFIG_PATH, existing, wanted, true),
+    };
+}
+/** Indent a multi-line diff under its report row. */
+function indent(text) {
+    return text.split("\n").map((line) => `      ${line}`);
+}
+/** The report `add-module` prints. */
+export function formatAddModuleReport(result, moduleName) {
+    const written = result.report.filter((row) => row.action === "written");
+    const patched = result.report.filter((row) => row.action === "patched");
+    const skipped = result.report.filter((row) => row.action === "skipped");
+    const removed = result.report.filter((row) => row.action === "removed");
+    const lines = [
+        `[create-ailk] add-module ${moduleName} → ${result.targetDir}`,
+    ];
+    if (result.report.length === 0 && result.routes.applied.length === 0) {
+        lines.push(`Nothing to add — the site already carries everything ${moduleName} brings.`);
+    }
+    if (written.length > 0) {
+        lines.push(`Written (${written.length}):`);
+        lines.push(...written.map((row) => `  ${row.path}`));
+    }
+    if (patched.length > 0) {
+        lines.push(`Patched (${patched.length}):`);
+        for (const row of patched) {
+            lines.push(`  ${row.path}`);
+            if (row.action === "patched")
+                lines.push(...indent(row.change));
+        }
+    }
+    if (removed.length > 0) {
+        lines.push(`Removed (${removed.length}):`);
+        lines.push(...removed.map((row) => `  ${row.path}`));
+    }
+    if (skipped.length > 0) {
+        lines.push(`Needs manual review (${skipped.length}) — the site's copy differs from the module's and was left untouched. Apply the change by hand if you want it:`);
+        for (const row of skipped) {
+            lines.push(`  ${row.path}`);
+            if (row.action === "skipped")
+                lines.push(...indent(row.wanted));
+        }
+    }
+    const { routes } = result;
+    if (routes.applied.length > 0) {
+        lines.push(`Routes copied (${routes.applied.length}):`);
+        lines.push(...routes.applied.map((route) => `  ${route}`));
+    }
+    if (routes.appliedDependencies.length > 0) {
+        lines.push(`Also copied ${routes.appliedDependencies.length} file(s) those routes import:`);
+        lines.push(...routes.appliedDependencies.map((dep) => `  ${dep}`));
+    }
+    if (routes.missingMessageNamespaces.length > 0) {
+        lines.push("Also required — message namespace(s) not found in apps/web/messages/en.json (add manually, not auto-merged):");
+        lines.push(...routes.missingMessageNamespaces.map((ns) => `  ${ns}`));
+    }
+    lines.push(`architecture.yaml modules: ${result.modules.join(", ")}`);
+    lines.push(...formatRoster(result.roster, moduleName));
+    if (written.length > 0 || patched.length > 0 || routes.applied.length > 0) {
+        lines.push("Next: pnpm install, then pnpm build.");
+    }
+    return lines.join("\n") + "\n";
+}
+/** The page-roster lines of the report (#6682 D7). */
+function formatRoster(roster, moduleName) {
+    if (roster.state === "none") {
+        return [
+            `Page roster: none. This site was scaffolded without a template, so it has no ${SITE_ROSTER_PATH} to append to.`,
+        ];
+    }
+    const lines = [
+        roster.state === "appended" && roster.appended.length === 0
+            ? `Page roster: reordered ${roster.path}'s rows into template-then-module order`
+            : roster.state === "appended"
+                ? `Page roster: appended ${roster.appended.length} row(s) to ${roster.path}: ${roster.appended.join(", ")}`
+                : `Page roster: ${roster.path} already carries ${moduleName}'s rows`,
+    ];
+    if (roster.problems.length === 0) {
+        lines.push("Page roster check: clean");
+    }
+    else {
+        lines.push(`Page roster check: ${roster.problems.length} problem(s)`);
+        lines.push(...roster.problems.map((p) => `  ${p}`));
+    }
+    return lines;
+}
+export const ADD_MODULE_HELP = `create-ailk add-module — add a purchased module to an existing site.
+
+Usage:
+  create-ailk add-module <module> [<target-dir>]
+  create-ailk upgrade <module> [<target-dir>]
+
+Arguments:
+  <module>                 One paid module, e.g. docs-blog. Needs
+                           AILK_LICENSE_KEY covering it.
+  <target-dir>             An already-scaffolded repo (contains
+                           architecture.yaml). Defaults to the current dir.
+
+Options:
+  --help, -h               Print this message.
+
+Writes the module's files the site lacks and never overwrites one it has: a
+file whose content differs is left as-is and listed for manual review with the
+change the module wanted. Only package.json dependency/script keys,
+next.config.* and jest.config.* are patched. Then copies the module's routes
+and regenerates architecture.yaml. Running it again changes nothing.
+`;
+/**
+ * Parse the argv AFTER the `add-module` / `upgrade` word. Strict
+ * `node:util` parseArgs, like `parseSyncRoutesArgs`; the module is validated
+ * the same way one `--modules` entry is.
+ */
+export function parseAddModuleArgs(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        strict: true,
+        allowPositionals: true,
+        options: {
+            help: { type: "boolean", default: false, short: "h" },
+        },
+    });
+    const help = parsed.values.help === true;
+    const [raw, target, ...rest] = parsed.positionals;
+    if (rest.length > 0) {
+        throw new ParseError(`expected a module and at most one target directory, got ${parsed.positionals.length} arguments`);
+    }
+    if (raw === undefined) {
+        if (help)
+            return { module: undefined, target: undefined, help };
+        throw new ParseError("add-module needs a module name, e.g. `create-ailk add-module docs-blog`");
+    }
+    const modules = parseModules(raw);
+    if (modules.length !== 1) {
+        throw new ParseError(`add-module takes exactly one module, got "${raw}" — run it once per module`);
+    }
+    return { module: modules[0], target, help };
+}

package/dist/category-profile.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The category profile (#6640; starter-template contract § D) — one YAML
+ * document per leaf category slug at `category-profiles/<slug>.yaml`, the data
+ * the `fill-page` skill reads to make one starter speak for one business type.
+ *
+ * Dependency-free by design: `create-ailk` ships `tar` as its only runtime
+ * dependency, so this is a hand-written validator in the style of
+ * `resolveTemplate`/`TemplateError`, not a Zod schema. The caller parses the
+ * YAML and injects the registries (page types, leaf categories); nothing here
+ * imports a workspace package at run time.
+ */
+import type { StarterShape } from "./template-manifest.js";
+/**
+ * The contract's shape table, as data: each shape's primary node, the
+ * secondaries it allows, and whether it is reserved. Keyed by the manifest's
+ * own `StarterShape`, so a shape added there without a row here fails
+ * type-check.
+ */
+export declare const CATEGORY_PROFILE_SHAPES: {
+    readonly "organization-product": {
+        readonly primary: "Organization";
+        readonly secondaries: readonly ["SoftwareApplication"];
+        readonly reserved: false;
+    };
+    readonly "organization-service": {
+        readonly primary: "Organization";
+        readonly secondaries: readonly [];
+        readonly reserved: false;
+    };
+    readonly "local-business-service": {
+        readonly primary: "LocalBusiness";
+        readonly secondaries: readonly ["Person"];
+        readonly reserved: false;
+    };
+    readonly "local-business-product": {
+        readonly primary: "LocalBusiness";
+        readonly secondaries: readonly [];
+        readonly reserved: true;
+    };
+    readonly "person-service": {
+        readonly primary: "Person";
+        readonly secondaries: readonly ["Organization"];
+        readonly reserved: false;
+    };
+};
+/**
+ * schema.org's `LocalBusiness` subtree, `LocalBusiness` itself included — the
+ * closure of the `LocalBusiness` union in `schema-dts`. A literal so `src/`
+ * needs no type package at run time; `category-profile.test.ts` proves it
+ * set-equal to the `schema-dts` closure, so it cannot drift silently.
+ */
+export declare const LOCAL_BUSINESS_TYPES: ReadonlySet<string>;
+export declare const OFFERING_PRICING: readonly ["quote", "fixed", "hourly", "subscription"];
+export declare const PROOF_KINDS: readonly ["credential", "reviews", "before-after", "response-time", "guarantee", "experience"];
+export declare const CONTENT_POSTURES: readonly ["instructions", "sample"];
+export interface CategoryOffering {
+    name: string;
+    job: string;
+    pricing: (typeof OFFERING_PRICING)[number];
+}
+export interface CategoryProof {
+    kind: (typeof PROOF_KINDS)[number];
+    label: string;
+}
+export type CategoryRosterDelta = {
+    op: "add";
+    route: string;
+    pageType: string;
+    reason: string;
+} | {
+    op: "drop";
+    route: string;
+    reason: string;
+};
+export interface CategoryIntakeItem {
+    id: string;
+    ask: string;
+    /** The section types an answer to this question can fill. */
+    fills: string[];
+}
+export interface CategoryProfile {
+    slug: string;
+    shape: StarterShape;
+    /** The schema.org subtype of the primary node; only on `local-business-*`. */
+    subtype?: string;
+    secondary?: string;
+    offerings: CategoryOffering[];
+    proof: CategoryProof[];
+    vocabulary: {
+        problem: string[];
+        service: string[];
+        outcome: string[];
+    };
+    roster: CategoryRosterDelta[];
+    /** Nav label → replacement label. Declared, not yet applied to a scaffold. */
+    nav: Record<string, string>;
+    content_posture: (typeof CONTENT_POSTURES)[number];
+    intake: CategoryIntakeItem[];
+}
+/** A recorded tier-2 intake — `content/_intake.yaml`. */
+export interface CategoryIntake {
+    answers: Record<string, string | string[] | null>;
+}
+export interface ParseCategoryProfileOptions {
+    /** The file's basename without `.yaml`; the profile's `slug` must equal it. */
+    fileSlug: string;
+    /** Registered page-type keys (the schema registry). */
+    pageTypes: ReadonlySet<string>;
+    /** Leaf category slugs (the category registry). */
+    categories: ReadonlySet<string>;
+}
+/** Thrown on an invalid profile or intake; the message names the failing field path. */
+export declare class CategoryProfileError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate a parsed category profile.
+ * @throws CategoryProfileError naming the failing field path.
+ */
+export declare function parseCategoryProfile(raw: unknown, options: ParseCategoryProfileOptions): CategoryProfile;
+/**
+ * Validate a recorded intake (`content/_intake.yaml`) against its profile.
+ * Unknown ids fail; an id the file omits is returned as `null` (unanswered).
+ * @throws CategoryProfileError naming the failing field path.
+ */
+export declare function parseIntake(raw: unknown, profile: CategoryProfile): CategoryIntake;