create-ailk 0.3.0 → 0.5.0

package/dist/cli.js

@@ -9,8 +9,9 @@
  *   2. on --help: print helpText, exit 0
  *   3. on --version: print version, exit 0
  *   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
+ *      requested paid module (K1, #5089 — Flavor 3) and any named site
+ *      template's own bundle (#5481), then validates + copies the local
+ *      template, then merges each fetched bundle in, the site template last
  *   5. when --install: spawn `pnpm install` (cwd = target, hard-coded argv)
  *   6. print next-steps message
  *
@@ -32,7 +33,7 @@ import { fileURLToPath } from "node:url";
 import { proCallout } from "./lib/pro-callout.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 { 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)), "..");
 const PKG_JSON = resolve(PKG_ROOT, "package.json");
@@ -40,6 +41,17 @@ function readPackageVersion() {
     const raw = readFileSync(PKG_JSON, "utf8");
     return JSON.parse(raw).version;
 }
+/** Raw value of a `--flag <value>` or `--flag=<value>` argv entry, if present. */
+function readRawFlagValue(argv, flag) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === flag)
+            return argv[i + 1];
+        if (arg?.startsWith(`${flag}=`))
+            return arg.slice(flag.length + 1);
+    }
+    return undefined;
+}
 async function main() {
     const argv = process.argv.slice(2);
     // Subcommand dispatch, ahead of the flag parser: `sync-routes` has its own
@@ -59,6 +71,23 @@ async function main() {
         process.exit(!args.apply && result.missing.length > 0 ? 1 : 0);
     }
     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
+    // the one place that prints: compare the raw `--surfaces` argv token
+    // against SURFACE_ALIASES rather than diffing the (already-canonical)
+    // parsed result.
+    const rawSurfaces = readRawFlagValue(argv, "--surfaces");
+    if (rawSurfaces !== undefined) {
+        for (const token of rawSurfaces
+            .split(",")
+            .map((s) => s.trim().toLowerCase())
+            .filter(Boolean)) {
+            const canonical = SURFACE_ALIASES[token];
+            if (canonical !== undefined) {
+                process.stdout.write(`[create-ailk] "--surfaces ${token}" is retired; using "${canonical}" (#5563).\n`);
+            }
+        }
+    }
     if (opts.help) {
         process.stdout.write(helpText + "\n" + SYNC_ROUTES_HELP);
         process.exit(0);
@@ -100,17 +129,24 @@ async function main() {
             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`).
+    // scaffold() gates + fetches any requested paid module (K1, #5089) and any
+    // named site template's own bundle (#5481), then validates and copies the
+    // local template — throws ValidationError or LicenseRequiredError on
+    // rejection (caught at top level below). Neither AILK_LICENSE_KEY nor
+    // either registry URL is read, and no network call is made, when the
+    // effective module set names no paid module — the regression floor, which
+    // `--template marketing-site-free` deliberately rides (record D11): its
+    // `requires` is all-free, so it installs from the shipped
+    // `site-templates/` tree with no key and no request.
     const { targetDir: targetAbs, surfaces } = await scaffold({
         targetDir: opts.target,
         modules: opts.modules,
         surfaces: opts.surfaces,
         withCatalog: opts.withCatalog,
+        // Spread rather than passed as `undefined` so a run naming no template
+        // 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 } : {}),
     });
     if (opts.install) {
         // Hard-coded argv. User input only flows through `cwd`, never the command.
@@ -126,7 +162,9 @@ async function main() {
     // Next-steps message.
     const lines = [
         "",
-        "Scaffolded AI Launch Kit starter.",
+        opts.template !== undefined
+            ? `Scaffolded AI Launch Kit starter from the "${opts.template}" template.`
+            : "Scaffolded AI Launch Kit starter.",
         "",
         "Next steps:",
         `  cd ${targetAbs}`,

package/dist/derive-architecture.js

@@ -181,11 +181,14 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
             forbidden_patterns: ARCHITECTURE_BASE.web.forbidden_patterns.map(forbiddenToYaml),
         },
     };
-    // Additional apps (api, mcp, workspace) in canonical order.
+    // Additional apps (api, mcp, admin) in canonical order. `admin` was
+    // `workspace` until #5637 renamed the owner surface; the slice's key was
+    // renamed there and this list was not, which dropped the Admin app from
+    // every derived architecture without failing anything but its own test.
     const extraApps = {};
     for (const s of slices)
         Object.assign(extraApps, s.apps ?? {});
-    for (const key of ["api", "mcp", "workspace"]) {
+    for (const key of ["api", "mcp", "admin"]) {
         const a = extraApps[key];
         if (a)
             apps[key] = appToYaml(a);

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

@@ -1,4 +1,23 @@
+import { type TemplateLayout } from "../site-chrome.js";
 import type { WorkspaceVersionMap } from "../substitute.js";
+/** Exported for `fetch-template.ts`/`fetch-module.ts`'s Content-Length guard (#5514) — one cap, not two literals. */
+export declare const MAX_TOTAL_SIZE_BYTES: number;
+/**
+ * The file-grain ownership registry (#5618 D4): scaffold-relative destination
+ * → the layer that wrote it (a `subject` string — `template "_base"`,
+ * `module "docs-blog"`, `template "marketing-site"`). Caller-owned and
+ * CALL-SCOPED: `scaffold()` constructs one per call and threads it through
+ * every `installBundleTree` of that scaffold, so two `scaffold()` calls in
+ * one process share no state (the frozen-registry posture of #5507). It is
+ * the third ownership view beside `ownedFiles` (which repo file a module
+ * physically owns) and `pageContributions` (which route+content it brings):
+ * which scaffold destination a LAYER wrote at install time.
+ *
+ * Layer 0 — the `templates/` snapshot — is deliberately outside it: the
+ * registry starts empty at the base-layer boundary, so a destination it does
+ * not hold is the snapshot's, which a module may freely add to and patch.
+ */
+export type LayerOwnership = Map<string, string>;
 export interface ExtractModuleBundleOptions {
     /** The fetched bundle bytes (a gzipped tar archive). */
     bytes: Uint8Array;
@@ -13,6 +32,16 @@ export interface ExtractModuleBundleOptions {
      * (a bundle with no `patches`, or none using `workspace:*`, needs nothing).
      */
     versions?: WorkspaceVersionMap;
+    /**
+     * Present ⟹ `moduleName` names a SITE TEMPLATE, not a module, and the
+     * archive's root manifest is `ailk-template.json` cross-checked against
+     * this list (record D10, DD4). See `InstallBundleTreeOptions`.
+     */
+    templateRequires?: readonly string[];
+    /** The registry's `extends` for this template (#5618 D2). See `InstallBundleTreeOptions`. */
+    templateExtends?: string;
+    /** The call-scoped ownership registry (#5618 D4). See `InstallBundleTreeOptions`. */
+    ownership?: LayerOwnership;
 }
 /**
  * Extract a fetched module bundle into `targetDir`, merging its files onto
@@ -22,4 +51,62 @@ export interface ExtractModuleBundleOptions {
  * those cases: validation AND patch computation both complete before any
  * file is copied or written into place.
  */
-export declare function extractModuleBundle(options: ExtractModuleBundleOptions): Promise<void>;
+export declare function extractModuleBundle(options: ExtractModuleBundleOptions): Promise<InstallBundleTreeResult>;
+export interface InstallBundleTreeOptions {
+    /**
+     * The validated tree whose files land in the scaffold. Two source roots,
+     * one install step (spec 5481 § 3 DD7): the staging dir
+     * `extractModuleBundle` above produced, or `site-templates/<name>/` read
+     * straight off disk on the keyless Free path.
+     */
+    sourceRoot: string;
+    /** The already-scaffolded target directory the files land in. */
+    targetDir: string;
+    /** The module or template name — error messages and nothing else. */
+    name: string;
+    /**
+     * Present ⟹ this tree is a SITE TEMPLATE's: the root manifest is
+     * `ailk-template.json`, it MUST be present and parseable, and its
+     * `requires` must agree with this list — the client registry's own
+     * (record D10, DD4). Absent ⟹ a module bundle, read exactly as before.
+     */
+    templateRequires?: readonly string[];
+    /**
+     * Template trees only (#5618 D2): the client registry's `extends` for this
+     * template, which the tree's `ailk-template.json` must declare verbatim —
+     * the sibling of the `requires` cross-check above. Absent for the base
+     * layer itself (the chain's terminus declares no parent) and for a module.
+     */
+    templateExtends?: string;
+    /**
+     * The call-scoped ownership registry (#5618 D4) — destination → the layer
+     * that wrote it. Present ⟹ this install is one layer of a composed
+     * scaffold: a MODULE tree is refused (before its first write) for any
+     * destination an earlier layer owns unless it is a declared `patches`
+     * target, and every layer records its destinations on success. Absent ⟹
+     * the pre-#5618 single-tree behaviour, unchecked and unrecorded.
+     */
+    ownership?: LayerOwnership;
+    /** Canonical `@working-theory/*` versions for `workspace:*` substitution in patch targets. */
+    versions?: WorkspaceVersionMap;
+}
+/** `installBundleTree`'s result — presently only the template-only `layout` knobs. */
+export interface InstallBundleTreeResult {
+    /**
+     * The installed template's validated `layout` block (#5612 D1), unresolved
+     * (defaults NOT filled — `resolveSiteChrome` does that). `undefined` for a
+     * module install, or a template whose manifest declares no `layout`.
+     */
+    layout?: TemplateLayout;
+}
+/**
+ * Apply one resolved manifest's `installMap`, plain content and `patches`
+ * from `sourceRoot` into `targetDir`.
+ *
+ * Extracted from `extractModuleBundle` so the Free template path — which has
+ * no archive to unpack, only a local tree — runs the SAME step (DD7). The
+ * atomicity guarantee is this function's, not its callers': validation AND
+ * patch computation both complete before the first byte is written, so a
+ * rejected tree leaves `targetDir` exactly as it was.
+ */
+export declare function installBundleTree(options: InstallBundleTreeOptions): InstallBundleTreeResult;