create-ailk 0.6.0 → 0.7.0

package/dist/category-profile.js

@@ -0,0 +1,262 @@
+/**
+ * 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 const CATEGORY_PROFILE_SHAPES = {
+    "organization-product": {
+        primary: "Organization",
+        secondaries: ["SoftwareApplication"],
+        reserved: false,
+    },
+    "organization-service": {
+        primary: "Organization",
+        secondaries: [],
+        reserved: false,
+    },
+    "local-business-service": {
+        primary: "LocalBusiness",
+        secondaries: ["Person"],
+        reserved: false,
+    },
+    "local-business-product": {
+        primary: "LocalBusiness",
+        secondaries: [],
+        reserved: true,
+    },
+    "person-service": {
+        primary: "Person",
+        secondaries: ["Organization"],
+        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 const LOCAL_BUSINESS_TYPES = new Set([
+    "AccountingService", "AdultEntertainment", "AmusementPark", "AnimalShelter",
+    "ArchiveOrganization", "ArtGallery", "Attorney", "AutoBodyShop", "AutoDealer",
+    "AutoPartsStore", "AutoRental", "AutoRepair", "AutoWash", "AutomatedTeller",
+    "AutomotiveBusiness", "Bakery", "BankOrCreditUnion", "BarOrPub", "BeautySalon",
+    "BedAndBreakfast", "BikeStore", "BookStore", "BowlingAlley", "Brewery",
+    "CafeOrCoffeeShop", "Campground", "Casino", "ChildCare", "ClothingStore",
+    "ComedyClub", "CommunityHealth", "ComputerStore", "ConvenienceStore",
+    "CovidTestingFacility", "DaySpa", "Dentist", "DepartmentStore", "Dermatology",
+    "DietNutrition", "Distillery", "DryCleaningOrLaundry", "Electrician",
+    "ElectronicsStore", "Emergency", "EmergencyService", "EmploymentAgency",
+    "EntertainmentBusiness", "ExerciseGym", "FastFoodRestaurant", "FinancialService",
+    "FireStation", "Florist", "FoodEstablishment", "FurnitureStore", "GardenStore",
+    "GasStation", "GeneralContractor", "Geriatric", "GolfCourse", "GovernmentOffice",
+    "GroceryStore", "Gynecologic", "HVACBusiness", "HairSalon", "HardwareStore",
+    "HealthAndBeautyBusiness", "HealthClub", "HobbyShop", "HomeAndConstructionBusiness",
+    "HomeGoodsStore", "Hospital", "Hostel", "Hotel", "HousePainter", "IceCreamShop",
+    "IndividualPhysician", "InsuranceAgency", "InternetCafe", "JewelryStore",
+    "LegalService", "Library", "LiquorStore", "LocalBusiness", "Locksmith",
+    "LodgingBusiness", "MedicalBusiness", "MedicalClinic", "MensClothingStore",
+    "Midwifery", "MobilePhoneStore", "Motel", "MotorcycleDealer", "MotorcycleRepair",
+    "MovieRentalStore", "MovieTheater", "MovingCompany", "MusicStore", "NailSalon",
+    "NightClub", "Notary", "Nursing", "Obstetric", "OfficeEquipmentStore", "Oncologic",
+    "Optician", "Optometric", "Otolaryngologic", "OutletStore", "PawnShop", "Pediatric",
+    "PetStore", "Pharmacy", "Physician", "PhysiciansOffice", "Physiotherapy",
+    "PlasticSurgery", "Plumber", "Podiatric", "PoliceStation", "PostOffice",
+    "PrimaryCare", "ProfessionalService", "Psychiatric", "PublicHealth",
+    "PublicSwimmingPool", "RadioStation", "RealEstateAgent", "RecyclingCenter",
+    "Resort", "Restaurant", "RoofingContractor", "SelfStorage", "ShoeStore",
+    "ShoppingCenter", "SkiResort", "SportingGoodsStore", "SportsActivityLocation",
+    "SportsClub", "StadiumOrArena", "Store", "TattooParlor", "TelevisionStation",
+    "TennisComplex", "TireShop", "TouristInformationCenter", "ToyStore",
+    "TravelAgency", "VacationRental", "WholesaleStore", "Winery",
+]);
+export const OFFERING_PRICING = ["quote", "fixed", "hourly", "subscription"];
+export const PROOF_KINDS = [
+    "credential",
+    "reviews",
+    "before-after",
+    "response-time",
+    "guarantee",
+    "experience",
+];
+export const CONTENT_POSTURES = ["instructions", "sample"];
+/** Thrown on an invalid profile or intake; the message names the failing field path. */
+export class CategoryProfileError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CategoryProfileError";
+    }
+}
+function fail(path, message) {
+    throw new CategoryProfileError(`${path}: ${message}`);
+}
+function object(value, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        fail(path, "must be a mapping");
+    }
+    return value;
+}
+function keys(value, path, required, optional = []) {
+    const allowed = new Set([...required, ...optional]);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            fail(path === "" ? key : `${path}.${key}`, "unknown key");
+    }
+    for (const key of required) {
+        if (!(key in value))
+            fail(path === "" ? key : `${path}.${key}`, "is required");
+    }
+}
+function string(value, path) {
+    if (typeof value !== "string" || value.trim() === "")
+        fail(path, "must be a non-empty string");
+    return value;
+}
+function oneOf(value, allowed, path) {
+    if (!allowed.includes(value)) {
+        fail(path, `must be one of ${allowed.join(", ")} (got ${JSON.stringify(value)})`);
+    }
+    return value;
+}
+function list(value, path, nonEmpty) {
+    if (!Array.isArray(value))
+        fail(path, "must be a list");
+    if (nonEmpty && value.length === 0)
+        fail(path, "must not be empty");
+    return value;
+}
+function strings(value, path) {
+    return list(value, path, true).map((item, i) => string(item, `${path}[${i}]`));
+}
+/**
+ * Validate a parsed category profile.
+ * @throws CategoryProfileError naming the failing field path.
+ */
+export function parseCategoryProfile(raw, options) {
+    const doc = object(raw, "(profile)");
+    keys(doc, "", ["slug", "shape", "offerings", "proof", "vocabulary", "roster", "nav", "content_posture", "intake"], ["subtype", "secondary"]);
+    const slug = string(doc.slug, "slug");
+    if (!options.categories.has(slug))
+        fail("slug", `"${slug}" is not a leaf category slug`);
+    if (slug !== options.fileSlug) {
+        fail("slug", `"${slug}" does not match its file name "${options.fileSlug}.yaml"`);
+    }
+    const shapes = Object.keys(CATEGORY_PROFILE_SHAPES);
+    const shape = oneOf(doc.shape, shapes, "shape");
+    const shapeRow = CATEGORY_PROFILE_SHAPES[shape];
+    if (shapeRow.reserved)
+        fail("shape", `"${shape}" is reserved and not yet built`);
+    let subtype;
+    if (shapeRow.primary === "LocalBusiness") {
+        subtype = string(doc.subtype, "subtype");
+        if (!LOCAL_BUSINESS_TYPES.has(subtype)) {
+            fail("subtype", `"${subtype}" is not a schema.org LocalBusiness subtype`);
+        }
+    }
+    else if (doc.subtype !== undefined) {
+        fail("subtype", `is only valid on a local-business-* shape, not "${shape}"`);
+    }
+    let secondary;
+    if (doc.secondary !== undefined) {
+        if (shapeRow.secondaries.length === 0)
+            fail("secondary", `is not allowed on "${shape}"`);
+        secondary = oneOf(doc.secondary, shapeRow.secondaries, "secondary");
+    }
+    const offerings = list(doc.offerings, "offerings", true).map((item, i) => {
+        const path = `offerings[${i}]`;
+        const o = object(item, path);
+        keys(o, path, ["name", "job", "pricing"]);
+        return {
+            name: string(o.name, `${path}.name`),
+            job: string(o.job, `${path}.job`),
+            pricing: oneOf(o.pricing, OFFERING_PRICING, `${path}.pricing`),
+        };
+    });
+    const proof = list(doc.proof, "proof", true).map((item, i) => {
+        const path = `proof[${i}]`;
+        const p = object(item, path);
+        keys(p, path, ["kind", "label"]);
+        return { kind: oneOf(p.kind, PROOF_KINDS, `${path}.kind`), label: string(p.label, `${path}.label`) };
+    });
+    const vocab = object(doc.vocabulary, "vocabulary");
+    keys(vocab, "vocabulary", ["problem", "service", "outcome"]);
+    const vocabulary = {
+        problem: strings(vocab.problem, "vocabulary.problem"),
+        service: strings(vocab.service, "vocabulary.service"),
+        outcome: strings(vocab.outcome, "vocabulary.outcome"),
+    };
+    const roster = list(doc.roster ?? [], "roster", false).map((item, i) => {
+        const path = `roster[${i}]`;
+        const r = object(item, path);
+        const op = oneOf(r.op, ["add", "drop"], `${path}.op`);
+        const route = string(r.route, `${path}.route`);
+        if (!route.startsWith("/"))
+            fail(`${path}.route`, `must start with "/"`);
+        if (op === "drop") {
+            keys(r, path, ["op", "route", "reason"]);
+            return { op, route, reason: string(r.reason, `${path}.reason`) };
+        }
+        keys(r, path, ["op", "route", "pageType", "reason"]);
+        const pageType = string(r.pageType, `${path}.pageType`);
+        if (!options.pageTypes.has(pageType)) {
+            fail(`${path}.pageType`, `"${pageType}" is not a registered page type`);
+        }
+        return { op, route, pageType, reason: string(r.reason, `${path}.reason`) };
+    });
+    const navDoc = doc.nav === null ? {} : object(doc.nav, "nav");
+    const nav = Object.fromEntries(Object.entries(navDoc).map(([from, to]) => [from, string(to, `nav.${from}`)]));
+    const ids = new Set();
+    const intake = list(doc.intake, "intake", true).map((item, i) => {
+        const path = `intake[${i}]`;
+        const q = object(item, path);
+        keys(q, path, ["id", "ask", "fills"]);
+        const id = string(q.id, `${path}.id`);
+        if (ids.has(id))
+            fail(`${path}.id`, `"${id}" is not unique`);
+        ids.add(id);
+        return { id, ask: string(q.ask, `${path}.ask`), fills: strings(q.fills, `${path}.fills`) };
+    });
+    return {
+        slug,
+        shape,
+        ...(subtype !== undefined ? { subtype } : {}),
+        ...(secondary !== undefined ? { secondary } : {}),
+        offerings,
+        proof,
+        vocabulary,
+        roster,
+        nav,
+        content_posture: oneOf(doc.content_posture, CONTENT_POSTURES, "content_posture"),
+        intake,
+    };
+}
+/**
+ * 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 function parseIntake(raw, profile) {
+    const doc = object(raw, "(intake)");
+    keys(doc, "", ["answers"]);
+    const given = doc.answers === null ? {} : object(doc.answers, "answers");
+    const known = new Set(profile.intake.map((q) => q.id));
+    for (const id of Object.keys(given)) {
+        if (!known.has(id))
+            fail(`answers.${id}`, "is not an intake id of this profile");
+    }
+    const answers = {};
+    for (const { id } of profile.intake) {
+        const value = given[id];
+        const path = `answers.${id}`;
+        if (value === undefined || value === null)
+            answers[id] = null;
+        else if (typeof value === "string")
+            answers[id] = value.trim() === "" ? null : value;
+        else if (Array.isArray(value))
+            answers[id] = value.map((v, i) => string(v, `${path}[${i}]`));
+        else
+            fail(path, "must be a string, a list of strings, or null");
+    }
+    return { answers };
+}

package/dist/cli.js

@@ -3,8 +3,12 @@
  * `create-ailk` — entry point.
  *
  * Orchestration:
- *   0. on a `sync-routes` subcommand: parse its own argv, run syncRoutesSync(),
+ *   0. on an `add-module` / `upgrade` subcommand: parse its own argv, run
+ *      addModule(), print the report, exit (2 on a refusal it names)
+ *      on a `sync-routes` subcommand: parse its own argv, run syncRoutesSync(),
  *      print the report, exit (1 iff routes are missing in check mode)
+ *      on a `license set` subcommand: write the key into the scaffold, push it
+ *      to a linked Vercel project and redeploy, exit (#6683 D9)
  *   1. parse argv → CliOptions
  *   2. on --help: print helpText, exit 0
  *   3. on --version: print version, exit 0
@@ -30,9 +34,11 @@ import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { proCallout } from "./lib/pro-callout.js";
+import { ADD_MODULE_HELP, AddModuleRefusedError, formatAddModuleReport, parseAddModuleArgs, } from "./add-module.js";
+import { FREE_PREREQUISITES_NOTE, LICENSED_PREREQUISITES_NOTE, isLicensedInstall, proCallout, } from "./lib/pro-callout.js";
+import { LICENSE_SET_HELP, runLicenseSet } from "./license-set.js";
 import { helpText, parseCliArgs, parseModules } from "./parse-args.js";
-import { formatSurfaceDrift, scaffold, syncArchitectureSync, syncCatalogSync, syncRoutesSync, } from "./programmatic.js";
+import { addModule, formatSurfaceDrift, scaffold, syncArchitectureSync, syncCatalogSync, syncRoutesSync, } from "./programmatic.js";
 import { CORE_SURFACE_PATHS, SURFACE_ALIASES } from "./surfaces.js";
 import { SYNC_ROUTES_HELP, formatSyncRoutesReport, parseSyncRoutesArgs, } from "./sync-routes.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -52,8 +58,63 @@ function readRawFlagValue(argv, flag) {
     }
     return undefined;
 }
+/**
+ * The prerequisites a freshly-scaffolded starter ACTUALLY has before
+ * `pnpm dev` / `pnpm build` will run (#6440 AC4).
+ *
+ * Read back off the scaffold that was just written rather than hard-coded
+ * here, so the printed floors can never drift from the ones the scaffold's own
+ * `engines` / `packageManager` fields enforce. Both fields are optional in
+ * principle; a missing one is simply not named, since naming a prerequisite
+ * the scaffold does not enforce is the other half of the defect this fixes.
+ */
+function readScaffoldPrerequisites(targetAbs) {
+    try {
+        const pkg = JSON.parse(readFileSync(resolve(targetAbs, "package.json"), "utf8"));
+        const node = pkg.engines?.node;
+        // `packageManager` is "pnpm@<version>[+<integrity>]" — the version only.
+        const pnpm = pkg.packageManager?.startsWith("pnpm@")
+            ? pkg.packageManager.slice("pnpm@".length).split("+")[0]
+            : undefined;
+        return {
+            ...(node !== undefined ? { node } : {}),
+            ...(pnpm !== undefined ? { pnpm } : {}),
+        };
+    }
+    catch {
+        // A scaffold with no readable root package.json is a bug the copy step
+        // would already have thrown on; next-steps is not the place to fail.
+        return {};
+    }
+}
 async function main() {
     const argv = process.argv.slice(2);
+    // `add-module` (alias `upgrade`, #6653): apply a purchased module to an
+    // existing site. Its own argv shape, like `sync-routes` below. A refusal it
+    // names (a free module, a patch outside the config allowlist, an unreadable
+    // architecture.yaml) exits 2; anything else — the licence gate included —
+    // falls through to the top-level catch, exit 1, as a scaffold would.
+    if (argv[0] === "add-module" || argv[0] === "upgrade") {
+        const args = parseAddModuleArgs(argv.slice(1));
+        if (args.help || args.module === undefined) {
+            process.stdout.write(ADD_MODULE_HELP);
+            process.exit(0);
+        }
+        try {
+            const result = await addModule({
+                targetDir: args.target ?? process.cwd(),
+                moduleName: args.module,
+            });
+            process.stdout.write(formatAddModuleReport(result, args.module));
+        }
+        catch (err) {
+            if (!(err instanceof AddModuleRefusedError))
+                throw err;
+            process.stderr.write(`[create-ailk] ${err.message}\n`);
+            process.exit(err.exitCode);
+        }
+        process.exit(0);
+    }
     // Subcommand dispatch, ahead of the flag parser: `sync-routes` has its own
     // argv shape (#4986). Check mode exits 1 iff a template route is missing;
     // locally modified routes are reported but do not fail; --apply exits 0.
@@ -70,6 +131,16 @@ async function main() {
         process.stdout.write(formatSyncRoutesReport(result, args.apply));
         process.exit(!args.apply && result.missing.length > 0 ? 1 : 0);
     }
+    // `license set <key|-> [dir]` (#6683 D9): its own argv shape, ahead of the
+    // flag parser like `sync-routes`. The key reaches `vercel` on stdin only.
+    if (argv[0] === "license" && argv[1] === "set") {
+        process.exit(runLicenseSet(argv.slice(2), {
+            cwd: process.cwd(),
+            stdout: (text) => process.stdout.write(text),
+            stderr: (text) => process.stderr.write(text),
+            readStdin: () => readFileSync(0, "utf8"),
+        }));
+    }
     const opts = parseCliArgs(argv);
     // Deprecation notice for a retired `--surfaces` id (#5563 D2). `surfaces.ts`
     // stays pure — `canonicalizeSurface` only resolves the alias — so this is
@@ -89,7 +160,13 @@ async function main() {
         }
     }
     if (opts.help) {
-        process.stdout.write(helpText + "\n" + SYNC_ROUTES_HELP);
+        process.stdout.write(helpText +
+            "\n" +
+            SYNC_ROUTES_HELP +
+            "\n" +
+            ADD_MODULE_HELP +
+            "\n" +
+            LICENSE_SET_HELP);
         process.exit(0);
     }
     if (opts.version) {
@@ -147,6 +224,7 @@ async function main() {
         // hands `scaffold()` exactly the option object it got before the flag
         // existed (spec 5481 § 3 DD3's byte-identity floor).
         ...(opts.template !== undefined ? { template: opts.template } : {}),
+        ...(opts.license !== undefined ? { license: opts.license } : {}),
     });
     if (opts.install) {
         // Hard-coded argv. User input only flows through `cwd`, never the command.
@@ -159,33 +237,66 @@ async function main() {
             throw new Error(`pnpm install failed in ${targetAbs} (exit ${result.status}). Run it manually after fixing the issue.`);
         }
     }
-    // Next-steps message.
+    // Next-steps message. A licensed install (#6480) is not told it needs no
+    // licence key, and is not pitched the Pro tier it already owns.
+    const licensed = isLicensedInstall({
+        ...(opts.template !== undefined ? { template: opts.template } : {}),
+        modules: opts.modules,
+    });
     const lines = [
         "",
         opts.template !== undefined
             ? `Scaffolded AI Launch Kit starter from the "${opts.template}" template.`
             : "Scaffolded AI Launch Kit starter.",
         "",
-        "Next steps:",
-        `  cd ${targetAbs}`,
     ];
-    if (!opts.install)
-        lines.push("  pnpm install");
-    lines.push("  pnpm dev");
+    // Prerequisites (#6440 AC4) — every one the scaffold enforces, and nothing
+    // it does not. A starter reaches `pnpm dev` AND `pnpm build` on a toolchain
+    // alone: the Prisma client is generated by `database`'s own `postinstall`,
+    // so there is no generator step to remember, and no database or vendor API
+    // key gates either command (a free install also says no licence key does;
+    // a licensed one, #6480, does not). Saying so is the point — the previous
+    // output named no prerequisites at all, which left a customer to discover
+    // the toolchain floor from a failure.
+    const prereqs = readScaffoldPrerequisites(targetAbs);
+    const toolchain = [
+        prereqs.node !== undefined ? `Node.js ${prereqs.node}` : undefined,
+        prereqs.pnpm !== undefined ? `pnpm ${prereqs.pnpm}` : "pnpm",
+    ].filter((part) => part !== undefined);
+    if (toolchain.length > 0) {
+        lines.push(`Prerequisites: ${toolchain.join(" and ")} — that is all.`);
+        lines.push(licensed ? LICENSED_PREREQUISITES_NOTE : FREE_PREREQUISITES_NOTE);
+        lines.push("");
+    }
+    // Only when asked for (#6683 D9) — a run without --license is unchanged.
+    if (opts.license !== undefined) {
+        lines.push("Licence key written to apps/api/.env and ailk.key (owner-only, gitignored).");
+        lines.push("");
+    }
+    lines.push("Next steps:");
+    lines.push(`  cd ${targetAbs}`);
+    if (!opts.install) {
+        lines.push("  pnpm install     # also generates the Prisma client");
+    }
+    lines.push("  pnpm dev         # http://localhost:3000");
+    lines.push("  pnpm build       # production build, when you are ready to deploy");
     lines.push("");
     lines.push("Open http://localhost:3000 to see the home page.");
+    lines.push("Adding auth, saved flows, checkout or database-backed content later? README.md \u00a7 \"When you need a database\" has the one-command setup.");
     lines.push("");
     lines.push(`Route surfaces: ${CORE_SURFACE_PATHS.join(", ")}` +
         (surfaces.length > 0 ? ` + ${surfaces.join(", ")}` : ""));
-    lines.push("Add another with the `scaffold-page` skill, or re-run with --surfaces <id>.");
+    lines.push("Add another with the `add-page` skill, or re-run with --surfaces <id>.");
     // Only when asked for. The default scaffold's output is unchanged.
     if (opts.withCatalog) {
         lines.push("Component catalog: COMPONENT-CATALOG.md — search it by capability before building a component.");
     }
     lines.push("Reference: ADR 0007 — pnpm create ailk@latest is the canonical install path.");
     lines.push("");
-    lines.push(proCallout());
-    lines.push("");
+    if (!licensed) {
+        lines.push(proCallout());
+        lines.push("");
+    }
     process.stdout.write(lines.join("\n"));
 }
 main().catch((err) => {

package/dist/copy.d.ts

@@ -1,4 +1,12 @@
 import { type MarkerMap, type WorkspaceVersionMap } from "./substitute.js";
+/**
+ * THE marker map every layer of a scaffold substitutes with (#6460) — the base
+ * `templates/` copy below, and (threaded through `installBundleTree`) the base
+ * layer and site-template trees that land on top of it. One definition, so a
+ * `{{MARKER}}` resolves to the same value whichever layer authored the file it
+ * sits in; a second copy would let the two drift silently.
+ */
+export declare function buildScaffoldMarkers(projectName: string): MarkerMap;
 export interface CopyTemplateOptions {
     templatesDir: string;
     targetDir: string;
@@ -12,4 +20,10 @@ export interface CopyTemplateOptions {
      */
     excludePaths?: string[];
 }
+/**
+ * Whether a scaffolded path's content is text we run markers over. Exported
+ * because the template/base layer (`installBundleTree`) substitutes with the
+ * same classifier — one definition, not two (#6460).
+ */
+export declare function isTextFile(relativePath: string): boolean;
 export declare function copyTemplate(opts: CopyTemplateOptions): void;

package/dist/copy.js

@@ -20,7 +20,39 @@
  */
 import { copyFileSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
 import { extname, join, relative, resolve, sep } from "node:path";
+import pkg from "../package.json" with { type: "json" };
 import { substituteMarkers, substituteWorkspaceVersions, } from "./substitute.js";
+/**
+ * This package's own `package.json` `"version"` — the value the
+ * `{{CREATE_AILK_VERSION}}` marker is stamped with at scaffold time (#6460).
+ * Deliberately a static JSON import rather than `import.meta.url` +
+ * `fileURLToPath`, for the reason `lib/fetch-module.ts`'s own
+ * `CREATE_AILK_VERSION` doc records: `copy.ts` is loaded directly by
+ * `copy.test.ts`, and `import.meta` is a SyntaxError under ts-jest's CommonJS
+ * transform.
+ */
+const CREATE_AILK_VERSION = pkg.version;
+/**
+ * THE marker map every layer of a scaffold substitutes with (#6460) — the base
+ * `templates/` copy below, and (threaded through `installBundleTree`) the base
+ * layer and site-template trees that land on top of it. One definition, so a
+ * `{{MARKER}}` resolves to the same value whichever layer authored the file it
+ * sits in; a second copy would let the two drift silently.
+ */
+export function buildScaffoldMarkers(projectName) {
+    return {
+        PROJECT_NAME: projectName,
+        COMPANY_NAME: "Your Company",
+        COMPANY_DOMAIN: "example.com",
+        // The social-profile handle the Free chrome's footer links carry
+        // (`https://x.com/{{COMPANY_HANDLE}}`, #5469 D5) — a placeholder the
+        // site owner replaces, never the kit vendor's own handle.
+        COMPANY_HANDLE: "yourcompany",
+        // Stamped into each DESIGN.md header so an installed scaffold records the
+        // create-ailk it was generated by (#6460).
+        CREATE_AILK_VERSION,
+    };
+}
 /**
  * Whether a walked template-relative path is inside (or equal to) an excluded
  * directory. Compares `/`-normalized paths so the check holds on Windows, and
@@ -65,7 +97,12 @@ const DOTFILES_AS_TEXT = new Set([
     ".prettierrc",
     ".eslintrc",
 ]);
-function isTextFile(relativePath) {
+/**
+ * Whether a scaffolded path's content is text we run markers over. Exported
+ * because the template/base layer (`installBundleTree`) substitutes with the
+ * same classifier — one definition, not two (#6460).
+ */
+export function isTextFile(relativePath) {
     const ext = extname(relativePath);
     if (TEXT_EXTS.has(ext))
         return true;

package/dist/index.d.ts

@@ -5,9 +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, LicenseRequiredError, PAID_MODULES, classifyModules, formatSurfaceDrift, scaffold, scaffoldSync, syncArchitectureSync, syncCatalogSync, syncRoutesSync, 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, syncRoutesSync, type AddModuleOptions, type ResolvePaidModulesOptions, type ScaffoldOptions, type ScaffoldResult, type SyncArchitectureOptions, type SyncArchitectureResult, type SyncCatalogResult, type SyncRoutesSyncOptions, } from "./programmatic.js";
 export { DEFAULT_AILK_MODULE_REGISTRY_URL, FetchModuleError, fetchModule, type FetchModuleOptions, } from "./lib/fetch-module.js";
-export { extractModuleBundle, type ExtractModuleBundleOptions, } from "./lib/extract-module-bundle.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 { 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";
 export { CORE_ROUTE_DIRS, CORE_SURFACE_PATHS, NAV_CONFIG_PATH, GATEABLE_SURFACES, MODULE_SURFACES, RECOGNIZED_SURFACES, ROUTE_SINCE, SurfaceError, excludedContentPaths, excludedRoutePaths, parseSurfaces, renderNavConfig, resolveSurfaces, surfaceForRouteDir, type Surface, } from "./surfaces.js";

package/dist/index.js

@@ -5,12 +5,17 @@
  */
 export { copyTemplate } from "./copy.js";
 export { parseCliArgs, parseModules, ParseError, helpText, RECOGNIZED_MODULES, } from "./parse-args.js";
-export { CATALOG_TARGET_PATH, FREE_MODULES, 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, 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.
 export { DEFAULT_AILK_MODULE_REGISTRY_URL, FetchModuleError, fetchModule, } from "./lib/fetch-module.js";
 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";
+// 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.
 // The pure module is exported so tooling can run it against any template dir.
 export { SYNC_ROUTES_HELP, formatSyncRoutesReport, listTemplateRouteDirs, parseSyncRoutesArgs, syncRoutes, } from "./sync-routes.js";