create-ailk 0.1.0 → 0.2.0

package/dist/cli.js

@@ -3,43 +3,114 @@
  * `create-ailk` — entry point.
  *
  * Orchestration:
+ *   0. on a `sync-routes` subcommand: parse its own argv, run syncRoutesSync(),
+ *      print the report, exit (1 iff routes are missing in check mode)
  *   1. parse argv → CliOptions
  *   2. on --help: print helpText, exit 0
  *   3. on --version: print version, exit 0
- *   4. delegate to scaffoldSync() in programmatic.ts (validates + copies template)
+ *   4. delegate to scaffold() in programmatic.ts — gates + fetches any
+ *      requested paid module (K1, #5089 — Flavor 3), then validates + copies
+ *      the local template, then merges each fetched bundle in
  *   5. when --install: spawn `pnpm install` (cwd = target, hard-coded argv)
  *   6. print next-steps message
  *
- * Any thrown error (parse failure, validation failure, copy failure) is
- * caught at the top level: stderr "[create-ailk] <message>", exit non-zero.
+ * Any thrown error (parse failure, validation failure, copy failure,
+ * `LicenseRequiredError`) is caught at the top level: stderr
+ * "[create-ailk] <message>", exit non-zero. `LicenseRequiredError` is not
+ * special-cased — its message already states which honest state fired (no
+ * key / licence does not cover this module), so the existing single
+ * error-handling path is the whole contract.
+ *
+ * `main()` is async ONLY because Deliverable 2 needs to `await` the paid-
+ * module network round trip; every other branch below is exactly as
+ * synchronous as before.
  */
 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 { helpText, parseCliArgs } from "./parse-args.js";
-import { scaffoldSync } from "./programmatic.js";
+import { helpText, parseCliArgs, parseModules } from "./parse-args.js";
+import { formatSurfaceDrift, scaffold, syncArchitectureSync, syncCatalogSync, syncRoutesSync, } from "./programmatic.js";
+import { CORE_SURFACE_PATHS } from "./surfaces.js";
+import { SYNC_ROUTES_HELP, formatSyncRoutesReport, parseSyncRoutesArgs, } from "./sync-routes.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const PKG_JSON = resolve(PKG_ROOT, "package.json");
 function readPackageVersion() {
     const raw = readFileSync(PKG_JSON, "utf8");
     return JSON.parse(raw).version;
 }
-function main() {
-    const opts = parseCliArgs(process.argv.slice(2));
+async function main() {
+    const argv = process.argv.slice(2);
+    // 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.
+    if (argv[0] === "sync-routes") {
+        const args = parseSyncRoutesArgs(argv.slice(1));
+        if (args.help) {
+            process.stdout.write(SYNC_ROUTES_HELP);
+            process.exit(0);
+        }
+        const result = syncRoutesSync({
+            targetDir: args.target ?? process.cwd(),
+            apply: args.apply,
+        });
+        process.stdout.write(formatSyncRoutesReport(result, args.apply));
+        process.exit(!args.apply && result.missing.length > 0 ? 1 : 0);
+    }
+    const opts = parseCliArgs(argv);
     if (opts.help) {
-        process.stdout.write(helpText);
+        process.stdout.write(helpText + "\n" + SYNC_ROUTES_HELP);
         process.exit(0);
     }
     if (opts.version) {
         process.stdout.write(readPackageVersion() + "\n");
         process.exit(0);
     }
-    // scaffoldSync() validates and copies the template — throws ValidationError
-    // on rejection (caught at top level below).
-    const { targetDir: targetAbs } = scaffoldSync({
+    // Catalog-sync mode: refresh COMPONENT-CATALOG.md in an already-scaffolded
+    // repo, then exit — the `--sync-architecture` shape with a different artifact
+    // (#4636). Data-only: one file rewritten, no template copy, no install.
+    if (opts.syncCatalog) {
+        const { catalogPath } = syncCatalogSync({
+            targetDir: opts.target ?? process.cwd(),
+        });
+        process.stdout.write(`[create-ailk] Wrote ${catalogPath}\n` +
+            `[create-ailk] Search it by CAPABILITY before building a component — it indexes every @working-theory/ui section, block and chrome component by what it does.\n`);
+        process.exit(0);
+    }
+    // Sync mode: regenerate architecture.yaml in an already-scaffolded repo from
+    // the module set, then exit — bypassing the scaffold / --install / next-steps
+    // path entirely (spec #3561 D2). Data-only and non-destructive: only
+    // architecture.yaml is rewritten. The value was already validated at parse
+    // time; re-parse it through the SAME parseModules to the module list.
+    if (opts.syncArchitecture !== undefined) {
+        const modules = parseModules(opts.syncArchitecture);
+        const targetDir = opts.target ?? process.cwd();
+        const { targetDir: targetAbs, surfaces, undeclared, } = syncArchitectureSync({
+            targetDir,
+            modules,
+            surfaces: opts.surfaces,
+        });
+        process.stdout.write(`[create-ailk] Regenerated architecture.yaml in ${targetAbs} from modules: ${modules.join(", ")}\n`);
+        process.stdout.write(`[create-ailk] Declared route surfaces: ${surfaces.length > 0 ? surfaces.join(", ") : "core only"}\n`);
+        // Surface drift is advisory, never fatal and never auto-removed (#4154 D5):
+        // the operator deletes the named paths in their own reviewable commit.
+        const drift = formatSurfaceDrift(undeclared);
+        if (drift)
+            process.stdout.write(drift);
+        process.exit(0);
+    }
+    // scaffold() gates + fetches any requested paid module (K1, #5089), then
+    // validates and copies the local template — throws ValidationError or
+    // LicenseRequiredError on rejection (caught at top level below). Neither
+    // AILK_LICENSE_KEY nor AILK_MODULE_REGISTRY_URL is read, and no network
+    // call is made, when `opts.modules` names no paid module — the regression
+    // floor (see `resolvePaidModules` in `lib/module-license-gate.ts`).
+    const { targetDir: targetAbs, surfaces } = await scaffold({
         targetDir: opts.target,
+        modules: opts.modules,
+        surfaces: opts.surfaces,
+        withCatalog: opts.withCatalog,
     });
     if (opts.install) {
         // Hard-coded argv. User input only flows through `cwd`, never the command.
@@ -65,16 +136,21 @@ function main() {
     lines.push("  pnpm dev");
     lines.push("");
     lines.push("Open http://localhost:3000 to see the home page.");
+    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>.");
+    // 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("");
     process.stdout.write(lines.join("\n"));
 }
-try {
-    main();
-}
-catch (err) {
+main().catch((err) => {
     process.stderr.write(`[create-ailk] ${err.message}\n`);
     process.exit(1);
-}
+});

package/dist/component-catalog.d.ts

@@ -0,0 +1,11 @@
+/** Where the catalog lands in a consuming repo. The address is the contract. */
+export declare const CATALOG_TARGET_PATH = "COMPONENT-CATALOG.md";
+/**
+ * Copy the shipped catalog to `<targetAbs>/COMPONENT-CATALOG.md`, overwriting
+ * any previous copy. Returns the absolute path written.
+ *
+ * Throws when the package carries no catalog — that means `build-catalog` never
+ * ran, and writing nothing silently would leave the consuming repo believing it
+ * has an inventory it does not have.
+ */
+export declare function writeComponentCatalog(targetAbs: string): string;

package/dist/component-catalog.js

@@ -0,0 +1,39 @@
+/**
+ * Distribution of the generated component catalog into a consuming repo.
+ *
+ * The catalog (`component-catalog.md`, generated by
+ * `scripts/build-component-catalog.mjs` and shipped in this package's tarball)
+ * answers "what component gives me a modal form on a dimmed backdrop?" with
+ * `FormLightbox`. It is only useful where the person asking that question is,
+ * which is a scaffolded site's own repo — a cloud session there is single-repo
+ * by construction and cannot reach AILK (#4636 cause 1: no address).
+ *
+ * The file lands at the TARGET ROOT, beside `CLAUDE.md`, `CONVENTIONS.md` and
+ * `project.yaml`. Root rather than `docs/`: a scaffold has no `docs/` today,
+ * and the whole failure being fixed is that the inventory had no address a
+ * worker could resolve — the root is the one place every reader already looks.
+ */
+import { copyFileSync, existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+/** The catalog as shipped in this package (generated at `prepublishOnly`). */
+const CATALOG_SOURCE = join(PKG_ROOT, "component-catalog.md");
+/** Where the catalog lands in a consuming repo. The address is the contract. */
+export const CATALOG_TARGET_PATH = "COMPONENT-CATALOG.md";
+/**
+ * Copy the shipped catalog to `<targetAbs>/COMPONENT-CATALOG.md`, overwriting
+ * any previous copy. Returns the absolute path written.
+ *
+ * Throws when the package carries no catalog — that means `build-catalog` never
+ * ran, and writing nothing silently would leave the consuming repo believing it
+ * has an inventory it does not have.
+ */
+export function writeComponentCatalog(targetAbs) {
+    if (!existsSync(CATALOG_SOURCE)) {
+        throw new Error(`no component catalog in this create-ailk install (${CATALOG_SOURCE}). Run \`pnpm --filter create-ailk run build-catalog\` first.`);
+    }
+    const dest = join(targetAbs, CATALOG_TARGET_PATH);
+    copyFileSync(CATALOG_SOURCE, dest);
+    return dest;
+}

package/dist/copy.d.ts

@@ -4,5 +4,12 @@ export interface CopyTemplateOptions {
     targetDir: string;
     versions: WorkspaceVersionMap;
     markers: MarkerMap;
+    /**
+     * Template-relative directory paths to SKIP entirely — the route directories
+     * of gateable surfaces the declared architecture does not carry (spec #4154).
+     * Forward-slash separated. Matching is anchored at a directory boundary, so
+     * `.../services` never excludes a sibling `.../services-extra`.
+     */
+    excludePaths?: string[];
 }
 export declare function copyTemplate(opts: CopyTemplateOptions): void;

package/dist/copy.js

@@ -21,6 +21,24 @@
 import { copyFileSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
 import { extname, join, relative, resolve, sep } from "node:path";
 import { substituteMarkers, substituteWorkspaceVersions, } from "./substitute.js";
+/**
+ * Whether a walked template-relative path is inside (or equal to) an excluded
+ * directory. Compares `/`-normalized paths so the check holds on Windows, and
+ * only at a directory boundary — a prefix that stops mid-segment is no match.
+ */
+function isExcluded(relativePath, excluded) {
+    if (excluded.length === 0)
+        return false;
+    const rel = relativePath.split(sep).join("/");
+    for (const raw of excluded) {
+        const ex = raw.replace(/\/+$/, "");
+        if (ex.length === 0)
+            continue;
+        if (rel === ex || rel.startsWith(ex + "/"))
+            return true;
+    }
+    return false;
+}
 /** File extensions whose content we treat as text (and run markers over). */
 const TEXT_EXTS = new Set([
     ".md",
@@ -61,6 +79,7 @@ function isPackageJson(relativePath) {
 export function copyTemplate(opts) {
     const templatesAbs = resolve(opts.templatesDir);
     const targetAbs = resolve(opts.targetDir);
+    const excluded = opts.excludePaths ?? [];
     mkdirSync(targetAbs, { recursive: true });
     const stack = [templatesAbs];
     while (stack.length > 0) {
@@ -75,6 +94,11 @@ export function copyTemplate(opts) {
                 continue;
             const srcPath = join(dir, entry.name);
             const rel = relative(templatesAbs, srcPath);
+            // Surface gating (#4154): a route directory belonging to a surface the
+            // declared architecture does not carry is skipped outright — the route is
+            // ABSENT from the scaffold, not present-and-serving-a-placeholder.
+            if (isExcluded(rel, excluded))
+                continue;
             const dstPath = join(targetAbs, rel);
             // Path-safety guard: dstPath MUST be within targetAbs. Use `path.sep`
             // so the check holds on Windows (`\\`) as well as POSIX (`/`).

package/dist/derive-architecture.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Derive the `architecture.yaml` document for a module set.
+ *
+ * @param modules the selected module names (any order; deduped). Defaults to
+ *   the same set `parse-args` defaults to when omitted (`['marketing']`).
+ * @param surfaces the enabled gateable route surfaces. Omitted ⟹ derived from
+ *   the module set alone (`resolveSurfaces`), so a caller that passes only
+ *   modules gets exactly what the modules imply.
+ * @returns the complete `architecture.yaml` file content (a deterministic
+ *   function of the module SET and the surface SET).
+ * @throws Error on an unrecognized module (defensive; parse-args rejects first).
+ */
+export declare function deriveArchitecture(modules?: string[], surfaces?: string[]): string;

package/dist/derive-architecture.js

@@ -0,0 +1,238 @@
+/**
+ * Derive a scaffolded site's `architecture.yaml` from its selected module set.
+ *
+ * `deriveArchitecture(modules)` composes the module-independent BASE
+ * (module-architecture.ts `ARCHITECTURE_BASE`) with the selected module slices
+ * into ONE deterministic `architecture.yaml` document string. The module set is
+ * the single source of truth for the result — same set → byte-identical output
+ * (no timestamps, stable key/array ordering), so the derivation doubles as the
+ * re-runnable sync path (add a module, re-derive, the file updates; re-deriving
+ * an unchanged set is a no-op).
+ *
+ * Zero runtime dependencies (create-ailk is a published, standalone CLI): the
+ * YAML is emitted by a small, purpose-built deterministic serializer over the
+ * fixed document shape this module produces — no `yaml`/`js-yaml` dependency.
+ */
+import { ARCHITECTURE_BASE, MODULE_SLICES, normalizeModules, } from "./module-architecture.js";
+import { CORE_SURFACE_PATHS, RECOGNIZED_SURFACES, resolveSurfaces, } from "./surfaces.js";
+function isScalar(v) {
+    return typeof v === "string" || typeof v === "number";
+}
+/** A bare (unquoted-safe) scalar: identifier chars only, not a YAML keyword/number. */
+function isBareSafe(s) {
+    if (s === "")
+        return false;
+    if (!/^[A-Za-z0-9._-]+$/.test(s))
+        return false;
+    if (/^[0-9]/.test(s))
+        return false; // avoid numeric-looking bare scalars
+    if (/^(true|false|null|yes|no|on|off|~)$/i.test(s))
+        return false;
+    return true;
+}
+function scalar(v) {
+    if (typeof v === "number")
+        return String(v);
+    return isBareSafe(v) ? v : JSON.stringify(v); // double-quoted, correctly escaped
+}
+function emitSeq(arr, indent) {
+    const pad = " ".repeat(indent);
+    const lines = [];
+    for (const item of arr) {
+        if (isScalar(item)) {
+            lines.push(`${pad}- ${scalar(item)}`);
+        }
+        else if (Array.isArray(item)) {
+            // Nested sequence — not produced by our shapes, but handled for safety.
+            lines.push(`${pad}-`);
+            lines.push(...emitSeq(item, indent + 2));
+        }
+        else {
+            const inner = emitMap(item, indent + 2);
+            // Splice the "- " marker onto the first line of the mapping block.
+            const first = inner[0] ?? "";
+            inner[0] = `${pad}- ${first.slice(indent + 2)}`;
+            lines.push(...inner);
+        }
+    }
+    return lines;
+}
+function emitMap(obj, indent) {
+    const pad = " ".repeat(indent);
+    const lines = [];
+    for (const [k, v] of Object.entries(obj)) {
+        if (isScalar(v)) {
+            lines.push(`${pad}${k}: ${scalar(v)}`);
+        }
+        else if (Array.isArray(v)) {
+            if (v.length === 0) {
+                lines.push(`${pad}${k}: []`);
+            }
+            else {
+                lines.push(`${pad}${k}:`);
+                lines.push(...emitSeq(v, indent + 2));
+            }
+        }
+        else {
+            lines.push(`${pad}${k}:`);
+            lines.push(...emitMap(v, indent + 2));
+        }
+    }
+    return lines;
+}
+function emitDocument(doc) {
+    return emitMap(doc, 0).join("\n") + "\n";
+}
+// ── Deterministic set helpers ──────────────────────────────────────────────
+/** Sorted unique union of string arrays (a set → a stable, ordered list). */
+function sortedUnion(...lists) {
+    const set = new Set();
+    for (const list of lists)
+        for (const s of list ?? [])
+            set.add(s);
+    return [...set].sort();
+}
+/** Union of forbidden patterns, deduped by `pattern`, base-first then sorted. */
+function mergeForbidden(base, extra) {
+    const seen = new Set();
+    const out = [];
+    for (const p of base) {
+        if (!seen.has(p.pattern)) {
+            seen.add(p.pattern);
+            out.push(p);
+        }
+    }
+    const sortedExtra = [...extra].sort((a, b) => a.pattern < b.pattern ? -1 : a.pattern > b.pattern ? 1 : 0);
+    for (const p of sortedExtra) {
+        if (!seen.has(p.pattern)) {
+            seen.add(p.pattern);
+            out.push(p);
+        }
+    }
+    return out;
+}
+function forbiddenToYaml(p) {
+    const m = { pattern: p.pattern, reason: p.reason };
+    if (p.paths_excluded && p.paths_excluded.length > 0) {
+        m.paths_excluded = [...p.paths_excluded].sort();
+    }
+    return m;
+}
+function appToYaml(app) {
+    const m = {
+        path: app.path,
+        description: app.description,
+        may_import_from: [...app.may_import_from].sort(),
+        may_not_import_from: [...app.may_not_import_from].sort(),
+    };
+    if (app.forbidden_patterns && app.forbidden_patterns.length > 0) {
+        m.forbidden_patterns = app.forbidden_patterns.map(forbiddenToYaml);
+    }
+    return m;
+}
+function packageToYaml(pkg) {
+    return {
+        description: pkg.description,
+        may_import_from: [...pkg.may_import_from].sort(),
+    };
+}
+function namespacesToYaml(ns) {
+    const members = {};
+    const sortedMembers = Object.entries(ns.members).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    for (const [key, mem] of sortedMembers) {
+        members[key] = { path: mem.path, description: mem.description };
+    }
+    return {
+        description: ns.description,
+        members,
+        rules: [...ns.rules],
+    };
+}
+/**
+ * Derive the `architecture.yaml` document for a module set.
+ *
+ * @param modules the selected module names (any order; deduped). Defaults to
+ *   the same set `parse-args` defaults to when omitted (`['marketing']`).
+ * @param surfaces the enabled gateable route surfaces. Omitted ⟹ derived from
+ *   the module set alone (`resolveSurfaces`), so a caller that passes only
+ *   modules gets exactly what the modules imply.
+ * @returns the complete `architecture.yaml` file content (a deterministic
+ *   function of the module SET and the surface SET).
+ * @throws Error on an unrecognized module (defensive; parse-args rejects first).
+ */
+export function deriveArchitecture(modules = ["marketing"], surfaces) {
+    const selected = normalizeModules(modules);
+    const slices = selected.map((m) => MODULE_SLICES[m]);
+    // The declared route surface (#4154). A scaffold's live-route set is a
+    // function of this list; the `surfaces:` block below is its machine-readable
+    // record, so "which routes does this site declare" is answerable without
+    // walking the app directory.
+    const enabledSurfaces = surfaces === undefined
+        ? resolveSurfaces(selected)
+        : [...new Set(surfaces)].sort();
+    // apps/web (BASE) — may_import_from filled from the selected modules' webImports.
+    const webImports = sortedUnion(...slices.map((s) => s.webImports));
+    const apps = {
+        web: {
+            path: ARCHITECTURE_BASE.web.path,
+            description: ARCHITECTURE_BASE.web.description,
+            may_import_from: webImports,
+            may_not_import_from: [...ARCHITECTURE_BASE.web.may_not_import_from].sort(),
+            forbidden_patterns: ARCHITECTURE_BASE.web.forbidden_patterns.map(forbiddenToYaml),
+        },
+    };
+    // Additional apps (api, mcp, workspace) in canonical order.
+    const extraApps = {};
+    for (const s of slices)
+        Object.assign(extraApps, s.apps ?? {});
+    for (const key of ["api", "mcp", "workspace"]) {
+        const a = extraApps[key];
+        if (a)
+            apps[key] = appToYaml(a);
+    }
+    // packages — sorted union across the selected slices.
+    const packagesRaw = {};
+    for (const s of slices)
+        Object.assign(packagesRaw, s.packages ?? {});
+    const packages = {};
+    const sortedPackages = Object.entries(packagesRaw).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    for (const [key, pkg] of sortedPackages) {
+        packages[key] = packageToYaml(pkg);
+    }
+    // namespaces — present only if a data-tier module contributes one.
+    const nsSlice = slices.find((s) => s.namespaces)?.namespaces;
+    // forbidden_patterns — base floor first, then the selected modules' patterns.
+    const extraForbidden = [];
+    for (const s of slices)
+        extraForbidden.push(...(s.forbiddenPatterns ?? []));
+    const forbidden = mergeForbidden([...ARCHITECTURE_BASE.forbiddenPatterns], extraForbidden);
+    const doc = {
+        version: ARCHITECTURE_BASE.version,
+        composition_model: {
+            reference: ARCHITECTURE_BASE.composition_model.reference,
+            tiers: { ...ARCHITECTURE_BASE.composition_model.tiers },
+        },
+        surfaces: {
+            core: [...CORE_SURFACE_PATHS],
+            enabled: enabledSurfaces,
+            available: [...RECOGNIZED_SURFACES],
+        },
+        apps,
+        packages,
+        ...(nsSlice ? { namespaces: namespacesToYaml(nsSlice) } : {}),
+        forbidden_patterns: forbidden.map(forbiddenToYaml),
+    };
+    const header = [
+        "# Architecture Boundaries — AI Launch Kit site",
+        "#",
+        "# GENERATED by create-ailk from the selected module set (--modules).",
+        "# The module set is the single source of truth for these boundaries.",
+        "# To change them, re-run create-ailk (or re-derive) with the new module",
+        "# set — do NOT hand-edit. Enforced by tools/lint-architecture.ts.",
+        "#",
+        `# Modules: ${selected.join(", ")}`,
+        `# Surfaces: ${enabledSurfaces.length > 0 ? enabledSurfaces.join(", ") : "core only"}`,
+        "",
+    ].join("\n");
+    return header + emitDocument(doc);
+}

package/dist/index.d.ts

@@ -4,7 +4,12 @@
  * `dist/cli.js` (per `bin` in package.json).
  */
 export { copyTemplate, type CopyTemplateOptions } from "./copy.js";
-export { parseCliArgs, ParseError, helpText, type CliOptions, } from "./parse-args.js";
-export { scaffold, scaffoldSync, type ScaffoldOptions, type ScaffoldResult, } from "./programmatic.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 { 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 { 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";
 export { substituteMarkers, substituteWorkspaceVersions, type MarkerMap, type WorkspaceVersionMap, } from "./substitute.js";
 export { validateTarget, ValidationError } from "./validate.js";

package/dist/index.js

@@ -4,7 +4,24 @@
  * `dist/cli.js` (per `bin` in package.json).
  */
 export { copyTemplate } from "./copy.js";
-export { parseCliArgs, ParseError, helpText, } from "./parse-args.js";
-export { scaffold, scaffoldSync, } from "./programmatic.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";
+// 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 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";
+// The module-set → architecture.yaml derivation. Exported so the sync path
+// (re-derive after a module is added) can re-run it (spec #3787 §2.1). The
+// module→slice registry it composes is an internal detail, deliberately not
+// re-exported.
+export { deriveArchitecture } from "./derive-architecture.js";
+// The route-surface registry (#4154) — which public routes a scaffold carries.
+// Exported so tooling can answer "what surfaces does this site declare" without
+// re-parsing architecture.yaml.
+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, } from "./surfaces.js";
 export { substituteMarkers, substituteWorkspaceVersions, } from "./substitute.js";
 export { validateTarget, ValidationError } from "./validate.js";

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

@@ -0,0 +1,16 @@
+export interface ExtractModuleBundleOptions {
+    /** The fetched bundle bytes (a gzipped tar archive). */
+    bytes: Uint8Array;
+    /** The already-scaffolded target directory the module's files land in. */
+    targetDir: string;
+    /** The module name — used only for error messages and staging dir naming. */
+    moduleName: string;
+}
+/**
+ * Extract a fetched module bundle into `targetDir`, merging its files onto
+ * the tree `copyTemplate` already wrote. Throws on any unsafe entry,
+ * decompress error, or limit overrun — `targetDir` is left untouched on
+ * failure (validation completes in a throwaway staging dir before any file
+ * is copied into place).
+ */
+export declare function extractModuleBundle(options: ExtractModuleBundleOptions): Promise<void>;