create-ailk 0.6.1 → 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)), "..");
@@ -83,6 +89,32 @@ function readScaffoldPrerequisites(targetAbs) {
 }
 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.
@@ -99,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
@@ -118,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) {
@@ -176,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.
@@ -188,7 +237,12 @@ 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
@@ -199,8 +253,9 @@ async function main() {
     // 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, licence key or
-    // vendor API key gates either command. Saying so is the point — the previous
+    // 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);
@@ -210,7 +265,12 @@ async function main() {
     ].filter((part) => part !== undefined);
     if (toolchain.length > 0) {
         lines.push(`Prerequisites: ${toolchain.join(" and ")} — that is all.`);
-        lines.push("No database, no licence key and no vendor API key are needed to run or build this site.");
+        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:");
@@ -226,15 +286,17 @@ async function main() {
     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/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";

package/dist/lib/extract-module-bundle.d.ts

@@ -1,3 +1,4 @@
+import { type ModulePatch } from "../module-architecture.js";
 import { type TemplateLayout } from "../site-chrome.js";
 import { type MarkerMap, type WorkspaceVersionMap } from "../substitute.js";
 /** Exported for `fetch-template.ts`/`fetch-module.ts`'s Content-Length guard (#5514) — one cap, not two literals. */
@@ -44,6 +45,10 @@ export interface ExtractModuleBundleOptions {
     ownership?: LayerOwnership;
     /** The scaffold's marker map (#6460). See `InstallBundleTreeOptions`. */
     markers?: MarkerMap;
+    /** What to do with a destination that already exists (#6653 D3). See `InstallBundleTreeOptions`. */
+    existingFilePolicy?: ExistingFilePolicy;
+    /** A caller check on the manifest's `patches` (#6653 D3). See `InstallBundleTreeOptions`. */
+    checkPatches?: (patches: readonly ModulePatch[]) => void;
 }
 /**
  * Extract a fetched module bundle into `targetDir`, merging its files onto
@@ -108,8 +113,47 @@ export interface InstallBundleTreeOptions {
      * files; `substituteMarkers` leaves every other `{{KEY}}` alone.
      */
     markers?: MarkerMap;
+    /**
+     * What to do with a destination that already exists (#6653 D3). Default
+     * `"overwrite"` — the scaffold's layer-over-layer behaviour, unchanged.
+     * `"skip-existing"` — the `add-module` merge onto a tree a customer has
+     * lived in: an existing file is never written; when its bytes differ from
+     * what this install would write it is reported `skipped` with the change
+     * the bundle wanted, and when they are equal it is not reported at all.
+     * `patches` are NOT gated by it — they are the one mechanism designed to
+     * edit an existing file, and they are already idempotent.
+     */
+    existingFilePolicy?: ExistingFilePolicy;
+    /**
+     * Run against the manifest's `patches` after they validate and BEFORE any
+     * of them is computed or anything is written (#6653 D3) — a throw rejects
+     * the tree with `targetDir` untouched. `add-module` uses it to hold a
+     * bundle's patches to the plus-config allowlist.
+     */
+    checkPatches?: (patches: readonly ModulePatch[]) => void;
 }
-/** `installBundleTree`'s result — presently only the template-only `layout` knobs. */
+/** See `InstallBundleTreeOptions.existingFilePolicy`. */
+export type ExistingFilePolicy = "overwrite" | "skip-existing";
+/**
+ * One file this install landed, patched, or declined to land (#6653 D3). A
+ * destination whose bytes already equal the install's produces no row.
+ * `change` / `wanted` is a unified diff (`diffTwoStrings`) — for `skipped`,
+ * the exact edit the bundle wanted, so the row is a manual-review item and
+ * never a bare path.
+ */
+export type InstallReportRow = {
+    path: string;
+    action: "written";
+} | {
+    path: string;
+    action: "patched";
+    change: string;
+} | {
+    path: string;
+    action: "skipped";
+    wanted: string;
+};
+/** `installBundleTree`'s result. */
 export interface InstallBundleTreeResult {
     /**
      * The installed template's validated `layout` block (#5612 D1), unresolved
@@ -117,6 +161,8 @@ export interface InstallBundleTreeResult {
      * module install, or a template whose manifest declares no `layout`.
      */
     layout?: TemplateLayout;
+    /** One row per file written, patched or skipped, in install order (#6653 D3). */
+    report: InstallReportRow[];
 }
 /**
  * Apply one resolved manifest's `installMap`, plain content and `patches`
@@ -129,3 +175,12 @@ export interface InstallBundleTreeResult {
  * rejected tree leaves `targetDir` exactly as it was.
  */
 export declare function installBundleTree(options: InstallBundleTreeOptions): InstallBundleTreeResult;
+/**
+ * A unified diff of `before` → `after` for the report (#6653 D3) — the one
+ * helper behind both a `skipped` row's `wanted` and a `patched` row's
+ * `change`. Line-based LCS; the inputs are config and content files, small
+ * enough that the quadratic table is not a concern. `isText` false yields the
+ * binary summary instead, reading each string's length as its byte count
+ * (the caller decodes binary content as latin1).
+ */
+export declare function diffTwoStrings(path: string, before: string, after: string, isText: boolean): string;