create-ailk 0.6.0 → 0.7.0

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

@@ -1,5 +1,6 @@
+import { type ModulePatch } from "../module-architecture.js";
 import { type TemplateLayout } from "../site-chrome.js";
-import type { WorkspaceVersionMap } from "../substitute.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. */
 export declare const MAX_TOTAL_SIZE_BYTES: number;
 /**
@@ -42,6 +43,12 @@ export interface ExtractModuleBundleOptions {
     templateExtends?: string;
     /** The call-scoped ownership registry (#5618 D4). See `InstallBundleTreeOptions`. */
     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
@@ -89,8 +96,64 @@ export interface InstallBundleTreeOptions {
     ownership?: LayerOwnership;
     /** Canonical `@working-theory/*` versions for `workspace:*` substitution in patch targets. */
     versions?: WorkspaceVersionMap;
+    /**
+     * The scaffold's marker map (#6460) — `copy.ts`'s `buildScaffoldMarkers`,
+     * the SAME object `copyTemplate` substituted the base `templates/` copy
+     * with, threaded here so a `{{MARKER}}` resolves to the same value whichever
+     * layer authored the file it sits in. Applied by `copyTree` and the
+     * installMap loop below, to text files only (`copy.ts`'s own `isTextFile`),
+     * so the classifier is one definition rather than two. Absent ⟹ files land
+     * byte-for-byte as committed, the pre-#6460 behaviour.
+     *
+     * EVERY layer that lands on the snapshot gets it, modules included — not
+     * just the base layer and the site template. A bundle fetched by version
+     * from the paid registry may have been produced by an older create-ailk
+     * that never saw this pass, so a bundle author should know that the five
+     * mapped keys, and only those, now resolve in their `.md`/`.json`/`.ts`
+     * 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
@@ -98,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`
@@ -110,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;

package/dist/lib/extract-module-bundle.js

@@ -83,8 +83,10 @@ import { isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { createGunzip } from "node:zlib";
 import * as tar from "tar";
+import { isTextFile } from "../copy.js";
 import { coOwnedModuleDestinations, } from "../module-architecture.js";
 import { validateTemplateLayout, } from "../site-chrome.js";
+import { substituteMarkers, } from "../substitute.js";
 import { computeModulePatches, writeModulePatches } from "./apply-module-patches.js";
 /** Soft limits to prevent decompression-bomb / zip-bomb attacks. Same values as extractBundle. */
 const MAX_ENTRIES = 1000;
@@ -98,6 +100,8 @@ const AILK_MODULE_JSON = "ailk-module.json";
  * Never copied into the scaffold either.
  */
 const AILK_TEMPLATE_JSON = "ailk-template.json";
+/** A template's hand-and-generated roster document — never installed (#6658 D7). */
+const TEMPLATE_MANIFEST_MD = "TEMPLATE-MANIFEST.md";
 /** The op names valid for each patch `kind` (spec 5418 § 3 D1's ModulePatchOp union, partitioned). */
 const VALID_OPS_BY_KIND = {
     json: new Set(["merge-keys", "append-unique"]),
@@ -446,6 +450,13 @@ export async function extractModuleBundle(options) {
                 : {}),
             ...(options.ownership !== undefined ? { ownership: options.ownership } : {}),
             ...(options.versions !== undefined ? { versions: options.versions } : {}),
+            ...(options.markers !== undefined ? { markers: options.markers } : {}),
+            ...(options.existingFilePolicy !== undefined
+                ? { existingFilePolicy: options.existingFilePolicy }
+                : {}),
+            ...(options.checkPatches !== undefined
+                ? { checkPatches: options.checkPatches }
+                : {}),
         });
     }
     finally {
@@ -463,7 +474,7 @@ export async function extractModuleBundle(options) {
  * rejected tree leaves `targetDir` exactly as it was.
  */
 export function installBundleTree(options) {
-    const { sourceRoot, name, templateRequires, templateExtends, ownership } = options;
+    const { sourceRoot, name, templateRequires, templateExtends, ownership, markers } = options;
     const targetAbs = resolve(options.targetDir);
     const isTemplate = templateRequires !== undefined;
     const subject = isTemplate ? `template "${name}"` : `module "${name}"`;
@@ -491,6 +502,7 @@ export function installBundleTree(options) {
         throw new Error(`${subject}: a template must not carry patches — content, never code (spec 5462 D9)`);
     }
     validatePatches(patches, targetAbs, subject);
+    options.checkPatches?.(patches);
     // The exclusion set copyTree/the content-only guard both use — built from
     // NORMALIZED installMap keys (#5514) so a "./x" key excludes the same
     // string `rel`'s traversal below computes, rather than colliding with it
@@ -503,6 +515,11 @@ export function installBundleTree(options) {
         ...Object.keys(installMap).map((key) => normalize(key).split(sep).join("/")),
     ]);
     if (isTemplate) {
+        // #6658 D7 — a template's roster of record lands as JSON, through its
+        // `installMap` (`TEMPLATE-MANIFEST.json` → `.ailk-site-manifest.json`).
+        // The Markdown is the template's own documentation: bundles still carry
+        // it, but it never reaches a scaffold's root.
+        excluded.add(TEMPLATE_MANIFEST_MD);
         validateTemplateContentOnly(sourceRoot, excluded, subject);
     }
     // #5618 D4 — the additive-overlap check, at the same seam as the
@@ -526,6 +543,17 @@ export function installBundleTree(options) {
     // installMap destination) is read from the STAGED tree here, since
     // targetDir would not have it yet at this point.
     const installMapDestinationToSource = new Map(Object.entries(installMap).map(([source, destination]) => [destination, source]));
+    // #6460 — a patch target is read RAW from the staged tree here, while
+    // `copyTree` below writes the same path SUBSTITUTED, and
+    // `writeModulePatches` runs after `copyTree`. So a file a bundle both
+    // delivers as plain content AND patches would end up carrying unsubstituted
+    // markers. Unreachable today and asserted as such rather than guarded: the
+    // only patch targets any slice declares are `apps/web/package.json`,
+    // `next.config.mjs` and `jest.config.cjs`, all three delivered by the base
+    // `templates/` snapshot rather than by a bundle — so this reader falls
+    // through to the `targetAbs` branch and reads already-substituted bytes —
+    // and a template is refused `patches` outright above. A bundle that starts
+    // delivering one of its own patch targets must substitute here too.
     const readPatchTarget = (target) => {
         const mappedSource = installMapDestinationToSource.get(target);
         if (mappedSource !== undefined) {
@@ -539,6 +567,20 @@ export function installBundleTree(options) {
         const targetAbsPath = resolve(targetAbs, target);
         return existsSync(targetAbsPath) ? readFileSync(targetAbsPath, "utf8") : undefined;
     };
+    // #6653 — under skip-existing, a patch target the tree ALSO delivers would be
+    // computed from the bundle's copy and written over the site's file, which
+    // the policy exists to leave alone. No slice does this today; refuse it.
+    if (options.existingFilePolicy === "skip-existing") {
+        for (const patch of patches) {
+            const target = toPosix(patch.target);
+            const staged = resolve(sourceRoot, patch.target);
+            const delivered = [...installMapDestinationToSource.keys()].some((d) => toPosix(d) === target) ||
+                (!excluded.has(target) && existsSync(staged) && statSync(staged).isFile());
+            if (delivered) {
+                throw new Error(`${subject}: patch target ${target} is also delivered by the bundle — refused, because it would replace the site's own file`);
+            }
+        }
+    }
     const computedPatches = computeModulePatches(patches, {
         versions: options.versions ?? {},
         readTarget: readPatchTarget,
@@ -550,18 +592,38 @@ export function installBundleTree(options) {
     // every installMap source are excluded from the whole-tree copy — the
     // manifest never lands in the scaffold, and a mapped source lands ONLY
     // at its mapped destination, never also at its original path.
-    copyTree(sourceRoot, targetAbs, excluded);
+    const report = [];
+    const policy = options.existingFilePolicy ?? "overwrite";
+    copyTree(sourceRoot, targetAbs, excluded, markers, policy, report);
     for (const [source, destination] of Object.entries(installMap)) {
         const destAbs = resolve(targetAbs, destination);
         mkdirSync(join(destAbs, ".."), { recursive: true });
-        copyFileSync(resolve(sourceRoot, source), destAbs);
+        // BOTH ends decide text-ness (#6460), because an installMap entry is free
+        // to rename across the boundary and the two mismatches are not
+        // symmetric: a text source landing at a binary name merely misses a
+        // substitution, while a BINARY source landing at a text name would be
+        // read as utf8 and rewritten, turning every invalid byte sequence into
+        // U+FFFD — silent, unrecoverable corruption. Requiring both makes the
+        // safe direction structural rather than a property of today's manifests.
+        const row = writeOneFile(resolve(sourceRoot, source), destAbs, toPosix(destination), [source, destination], markers, policy);
+        if (row !== undefined)
+            report.push(row);
     }
     // patches write AFTER every file the tree brought is in place (D5) —
     // after installMap, before postInstall — so a patch can never race a
     // file its own ownedFiles/installMap just delivered, and (since it was
     // COMPUTED above, before either ran) overwrites rather than conflicts
     // with content copyTree/installMap just placed at the same path.
+    // computeModulePatches already dropped every already-applied target, so an
+    // idempotent replay produces no `patched` row. Diffed before the write, while
+    // `readPatchTarget` still returns the pre-patch bytes.
+    const patchedRows = computedPatches.map(({ target, content }) => ({
+        path: toPosix(target),
+        action: "patched",
+        change: diffTwoStrings(toPosix(target), readPatchTarget(target) ?? "", content, true),
+    }));
     writeModulePatches(computedPatches, targetAbs);
+    report.push(...patchedRows);
     // #5618 D4 — record this layer's destinations only now that every one of
     // them is in place (a later layer's overwrite is judged against the layer
     // that actually wrote the bytes). Patch targets are NOT recorded: a patch
@@ -577,9 +639,12 @@ export function installBundleTree(options) {
     // validateTemplateLayout); returned as-is (defaults unfilled) for the
     // caller to resolve alongside whatever the code registry's own
     // `TemplateManifest.layout` says.
-    return isTemplate && manifest?.layout !== undefined
-        ? { layout: manifest.layout }
-        : {};
+    return {
+        report,
+        ...(isTemplate && manifest?.layout !== undefined
+            ? { layout: manifest.layout }
+            : {}),
+    };
 }
 /**
  * Recursively copy every file from `srcRoot` into `destRoot`, creating parent
@@ -589,8 +654,11 @@ export function installBundleTree(options) {
  * `safeExtractTarGz` has validated every entry, so no additional
  * path-safety check is needed here — `srcRoot` is our own staging tree, not
  * attacker-controlled input.
+ *
+ * `markers`, when given, is substituted into every TEXT file on the way
+ * through (#6460) — see `InstallBundleTreeOptions.markers`.
  */
-function copyTree(srcRoot, destRoot, excluded = new Set()) {
+function copyTree(srcRoot, destRoot, excluded, markers, policy, report) {
     const stack = [srcRoot];
     while (stack.length > 0) {
         const dir = stack.pop();
@@ -608,12 +676,155 @@ function copyTree(srcRoot, destRoot, excluded = new Set()) {
                 if (excluded.has(rel.split(sep).join("/")))
                     continue;
                 mkdirSync(join(destPath, ".."), { recursive: true });
-                copyFileSync(srcPath, destPath);
+                const row = writeOneFile(srcPath, destPath, toPosix(rel), [rel], markers, policy);
+                if (row !== undefined)
+                    report.push(row);
             }
             // symlinks: never present — safeExtractTarGz rejects them outright.
         }
     }
 }
+/**
+ * Land one file at `destAbs`, substituting `markers` into it when EVERY path
+ * in `relsForType` is text by `copy.ts`'s own `isTextFile` (#6460) — the
+ * source's relative path alone for a plain-content copy, source AND
+ * destination for an installMap entry, which may rename across the
+ * text/binary boundary. Unanimity rather than either-or, so binary content is
+ * never round-tripped through a utf8 string by construction; see the
+ * installMap loop for why the two mismatch directions are not symmetric.
+ *
+ * With no `markers`, or with any non-text path, this is exactly the
+ * `copyFileSync` it replaced.
+ *
+ * `isTextFile` is an allowlist of extensions, NOT "anything that parses as
+ * text": `.css`, `.html`, `.svg`, `.sh`, `.toml` and `.sql` are outside it, so
+ * a marker authored in one of those survives verbatim. That is pre-existing
+ * `copyTemplate` behaviour, deliberately shared rather than forked here.
+ *
+ * The source's mode rides along, because `copyFileSync` preserves it and
+ * `writeFileSync` does not: no tree this installs carries an executable file
+ * today, but a module slice is free to ship one, and a substituted `.mjs`
+ * silently losing its `+x` surfaces as "the scaffold builds but the hook never
+ * runs". Masked to the permission bits — `statSync().mode` carries the
+ * `S_IFREG` type bits too, which `open(2)` ignores but which have no business
+ * being passed. Like `copyFileSync`, this only sets the mode when the file is
+ * CREATED: an overwrite (the layer-over-layer case) keeps the existing one.
+ *
+ * `policy` (#6653 D3) is checked here, once, so `copyTree` and the installMap
+ * loop cannot diverge. Under `"skip-existing"` an existing destination is
+ * compared against the bytes this call WOULD write (post-substitution): equal
+ * → no row, nothing written; different → a `skipped` row carrying the diff.
+ * `path` is the scaffold-relative name the returned row carries.
+ */
+function writeOneFile(srcAbs, destAbs, path, relsForType, markers, policy) {
+    const isText = relsForType.every(isTextFile);
+    const substitute = markers !== undefined && isText;
+    if (policy === "skip-existing" && existsSync(destAbs)) {
+        const wanted = substitute
+            ? Buffer.from(substituteMarkers(readFileSync(srcAbs, "utf8"), markers))
+            : readFileSync(srcAbs);
+        const existing = readFileSync(destAbs);
+        if (existing.equals(wanted))
+            return undefined;
+        // latin1 keeps one char per byte, so a binary pair's lengths stay byte counts.
+        const encoding = isText ? "utf8" : "latin1";
+        return {
+            path,
+            action: "skipped",
+            wanted: diffTwoStrings(path, existing.toString(encoding), wanted.toString(encoding), isText),
+        };
+    }
+    if (!substitute) {
+        copyFileSync(srcAbs, destAbs);
+    }
+    else {
+        writeFileSync(destAbs, substituteMarkers(readFileSync(srcAbs, "utf8"), markers), {
+            mode: statSync(srcAbs).mode & 0o777,
+        });
+    }
+    return { path, action: "written" };
+}
+function toPosix(rel) {
+    return normalize(rel).split(sep).join("/");
+}
+/** Lines of context around each change in `diffTwoStrings`'s hunks. */
+const DIFF_CONTEXT = 3;
+/**
+ * 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 function diffTwoStrings(path, before, after, isText) {
+    if (!isText) {
+        return `binary content differs (${before.length} bytes existing vs ${after.length} bytes bundle)`;
+    }
+    // A final newline terminates the last line; it is not an empty line after it.
+    const lines = (text) => (text.endsWith("\n") ? text.slice(0, -1) : text).split("\n");
+    const a = before === "" ? [] : lines(before);
+    const b = after === "" ? [] : lines(after);
+    // lcs[i][j] = LCS length of a[i..] and b[j..].
+    const lcs = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--) {
+            lcs[i][j] =
+                a[i] === b[j]
+                    ? lcs[i + 1][j + 1] + 1
+                    : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length || j < b.length) {
+        if (i < a.length && j < b.length && a[i] === b[j]) {
+            ops.push({ kind: " ", line: a[i], ai: i + 1, bi: j + 1 });
+            i++;
+            j++;
+        }
+        else if (i < a.length && (j === b.length || lcs[i + 1][j] >= lcs[i][j + 1])) {
+            ops.push({ kind: "-", line: a[i], ai: i + 1, bi: j });
+            i++;
+        }
+        else {
+            ops.push({ kind: "+", line: b[j], ai: i, bi: j + 1 });
+            j++;
+        }
+    }
+    const out = [`--- a/${path}`, `+++ b/${path}`];
+    if (ops.every((op) => op.kind === " ")) {
+        out.push("(the files differ only in their final newline)");
+        return out.join("\n");
+    }
+    let k = 0;
+    while (k < ops.length) {
+        if (ops[k].kind === " ") {
+            k++;
+            continue;
+        }
+        // Grow a hunk from this change until DIFF_CONTEXT*2 unchanged lines separate it from the next.
+        const start = Math.max(0, k - DIFF_CONTEXT);
+        let end = k;
+        let unchanged = 0;
+        while (end < ops.length && unchanged <= DIFF_CONTEXT * 2) {
+            unchanged = ops[end].kind === " " ? unchanged + 1 : 0;
+            end++;
+        }
+        end = Math.min(ops.length, end - Math.max(0, unchanged - DIFF_CONTEXT));
+        const hunk = ops.slice(start, end);
+        const oldLines = hunk.filter((op) => op.kind !== "+").length;
+        const newLines = hunk.filter((op) => op.kind !== "-").length;
+        const oldStart = hunk.find((op) => op.kind !== "+")?.ai ?? hunk[0].ai;
+        const newStart = hunk.find((op) => op.kind !== "-")?.bi ?? hunk[0].bi;
+        out.push(`@@ -${oldStart},${oldLines} +${newStart},${newLines} @@`);
+        for (const op of hunk)
+            out.push(`${op.kind}${op.line}`);
+        k = end;
+    }
+    return out.join("\n");
+}
 /**
  * `extractBundle`'s validating-filter tar extraction, ported verbatim (see
  * file doc for why this is a port and not an import). Extracts `tarGzPath`

package/dist/lib/license-key-files.d.ts

@@ -0,0 +1,15 @@
+export declare const LICENSE_KEY_FILE = "ailk.key";
+export declare const LICENSE_ENV_FILE: string;
+export declare const LICENSE_ENV_VAR = "AILK_LICENSE_KEY";
+/**
+ * Throws unless `key` is 1–4096 characters of `[A-Za-z0-9._-]`. The message
+ * describes the rule, never the value.
+ */
+export declare function assertLicenseKeyShape(key: string): void;
+/**
+ * Persist `key` into the scaffold at `dir`: `ailk.key` (0600), the
+ * `apps/api/.env` line (0600, other lines kept), and a `.gitignore` entry for
+ * `ailk.key` when no existing line covers it. Idempotent — a second call with
+ * the same key changes no byte.
+ */
+export declare function writeLicenseKeyFiles(dir: string, key: string): void;

package/dist/lib/license-key-files.js

@@ -0,0 +1,102 @@
+/**
+ * Where a scaffold keeps its licence key (#6683 § 3 D9).
+ *
+ * Two copies, both owner-only and both gitignored:
+ *
+ *   - `ailk.key` at the scaffold root — the key on its own, for a person or a
+ *     tool that needs it again (`license set` re-pushes it to Vercel);
+ *   - `apps/api/.env` — one `AILK_LICENSE_KEY=<key>` line, because `apps/api`
+ *     is the scaffold's runtime reader and loads `.env` from its own directory.
+ *
+ * `assertLicenseKeyShape` is the ONE validator every entry point calls
+ * (`--license`, `license set <key>`, `license set -`): a compact JWS is
+ * base64url segments joined by dots, so anything else — whitespace, a newline
+ * that would inject a second `.env` line — is refused, and the refusal never
+ * repeats the value (it may be a real key in a shell history or a CI log).
+ *
+ * Pure module: no `import.meta.url`, so jest imports it directly.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+export const LICENSE_KEY_FILE = "ailk.key";
+export const LICENSE_ENV_FILE = join("apps", "api", ".env");
+export const LICENSE_ENV_VAR = "AILK_LICENSE_KEY";
+const KEY_SHAPE = /^[A-Za-z0-9._-]{1,4096}$/;
+/** `.gitignore` lines that already ignore a root `ailk.key`. */
+const KEY_IGNORE_LINES = new Set([
+    "ailk.key",
+    "/ailk.key",
+    "**/ailk.key",
+    "*.key",
+    "/*.key",
+    "**/*.key",
+]);
+/** A line assigning the variable, with or without `export`. */
+const ENV_LINE = new RegExp(`^\\s*(?:export\\s+)?${LICENSE_ENV_VAR}\\s*=`);
+/**
+ * Throws unless `key` is 1–4096 characters of `[A-Za-z0-9._-]`. The message
+ * describes the rule, never the value.
+ */
+export function assertLicenseKeyShape(key) {
+    if (!KEY_SHAPE.test(key)) {
+        throw new Error("the licence key is malformed: expected 1-4096 characters of A-Z a-z 0-9 . _ - (a compact JWS, no whitespace or newline). Copy it again from your welcome page.");
+    }
+}
+/**
+ * Write `content` only when it differs, with mode 0600 either way. An existing
+ * file is tightened BEFORE the write — `mode` applies only on creation, so a
+ * looser pre-existing `.env` would otherwise hold the key for a moment at its
+ * old permissions.
+ */
+function writeOwnerOnly(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    if (existsSync(path))
+        chmodSync(path, 0o600);
+    if (!existsSync(path) || readFileSync(path, "utf8") !== content) {
+        writeFileSync(path, content, { mode: 0o600 });
+    }
+    chmodSync(path, 0o600);
+}
+/** `text` plus `line`, starting on a fresh line. */
+function appendLine(text, line) {
+    const sep = text.length === 0 || text.endsWith("\n") ? "" : "\n";
+    return `${text}${sep}${line}\n`;
+}
+/** Replace the first assignment line, drop any later duplicate, else append. */
+function upsertEnvLine(existing, key) {
+    const line = `${LICENSE_ENV_VAR}=${key}`;
+    const lines = existing.split("\n");
+    let seen = false;
+    const out = [];
+    for (const l of lines) {
+        if (ENV_LINE.test(l)) {
+            if (!seen)
+                out.push(line);
+            seen = true;
+        }
+        else {
+            out.push(l);
+        }
+    }
+    return seen ? out.join("\n") : appendLine(existing, line);
+}
+/**
+ * Persist `key` into the scaffold at `dir`: `ailk.key` (0600), the
+ * `apps/api/.env` line (0600, other lines kept), and a `.gitignore` entry for
+ * `ailk.key` when no existing line covers it. Idempotent — a second call with
+ * the same key changes no byte.
+ */
+export function writeLicenseKeyFiles(dir, key) {
+    assertLicenseKeyShape(key);
+    writeOwnerOnly(join(dir, LICENSE_KEY_FILE), `${key}\n`);
+    const envPath = join(dir, LICENSE_ENV_FILE);
+    const env = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+    writeOwnerOnly(envPath, upsertEnvLine(env, key));
+    const ignorePath = join(dir, ".gitignore");
+    const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : "";
+    const covered = ignore
+        .split("\n")
+        .some((l) => KEY_IGNORE_LINES.has(l.trim()));
+    if (!covered)
+        writeFileSync(ignorePath, appendLine(ignore, LICENSE_KEY_FILE));
+}

package/dist/lib/module-license-gate.d.ts

@@ -18,7 +18,12 @@
  * gate (K1's regression floor).
  */
 import type { ModuleName } from "../parse-args.js";
-export declare const CONVERSION_HINT_URL = "https://ailaunchkit.ai/pro";
+/**
+ * Where a refused run sends the buyer. `/pricing`, not `/pro`: there is no
+ * `/pro` route and there will not be one (#6439, operator decision OD-2) —
+ * pricing is where every level and the commerce add-on are actually listed.
+ */
+export declare const CONVERSION_HINT_URL = "https://ailaunchkit.ai/pricing";
 /**
  * Thrown for both honest-denial states (no key, and an invalid/lapsed key).
  * The CLI does not distinguish them in its exit code — both are "this run

package/dist/lib/module-license-gate.js

@@ -1,5 +1,10 @@
 import { FetchModuleError, fetchModule } from "./fetch-module.js";
-export const CONVERSION_HINT_URL = "https://ailaunchkit.ai/pro";
+/**
+ * Where a refused run sends the buyer. `/pricing`, not `/pro`: there is no
+ * `/pro` route and there will not be one (#6439, operator decision OD-2) —
+ * pricing is where every level and the commerce add-on are actually listed.
+ */
+export const CONVERSION_HINT_URL = "https://ailaunchkit.ai/pricing";
 /**
  * Thrown for both honest-denial states (no key, and an invalid/lapsed key).
  * The CLI does not distinguish them in its exit code — both are "this run

package/dist/lib/pro-callout.d.ts

@@ -1,12 +1,18 @@
+export declare function proCallout(): string;
+/** The closing prerequisites note on a free install (#6440 AC4). */
+export declare const FREE_PREREQUISITES_NOTE = "No database, no licence key and no vendor API key are needed to run or build this site.";
 /**
- * `proCallout()` — the AI-guided setup conversion message appended to
- * `pnpm create ailk-app`'s closing summary.
- *
- * Wording is locked in `docs/internal/specs/ailk-onboard-site-spec.md` §2.1 and
- * `docs/internal/specs/ailk-onboard-site-spec.md` §5.1 (Sam-verifiable AC).
- *
- * The message is always shown — no flags, no env gating. Free-tier users
- * see it as a discovery surface for Pro; Pro users see it as a reminder
- * of the `/onboard-site` skill they can install.
+ * The same note on a licensed install (#6480): it drops the licence-key claim,
+ * which would contradict the key the customer just installed with.
  */
-export declare function proCallout(): string;
+export declare const LICENSED_PREREQUISITES_NOTE = "No database and no vendor API key are needed to run or build this site.";
+/**
+ * Whether an install delivered paid content — any paid module in the effective
+ * module set, `union(template.requires, --modules)`, the same union
+ * `scaffold()` gates on. A paid template is covered by that union too:
+ * `templateDelivery` derives "paid" from `requires` alone.
+ */
+export declare function isLicensedInstall(opts: {
+    template?: string;
+    modules?: string[];
+}): boolean;

package/dist/lib/pro-callout.js

@@ -5,16 +5,39 @@
  * Wording is locked in `docs/internal/specs/ailk-onboard-site-spec.md` §2.1 and
  * `docs/internal/specs/ailk-onboard-site-spec.md` §5.1 (Sam-verifiable AC).
  *
- * The message is always shown — no flags, no env gating. Free-tier users
- * see it as a discovery surface for Pro; Pro users see it as a reminder
- * of the `/onboard-site` skill they can install.
+ * Shown on a free install only (#6480): it is a discovery surface for Pro,
+ * and a licensed install already owns the tier it pitches.
  */
+import { normalizeModules } from "../module-architecture.js";
+import { resolveTemplate } from "../template-manifest.js";
+import { classifyModules } from "./module-tier.js";
 export function proCallout() {
     return [
         "Want AI-guided setup? Pro's `/onboard-site` interviews you about",
         "your business, generates a vertical-aware page plan, configures",
         "Stripe / auth / lead routing / analytics, and sets up your",
         "GitHub→Vercel deploy — all in one orchestrated flow. Or invoke the",
-        "free scaffolders one at a time → ailaunchkit.ai/pro",
+        "free scaffolders one at a time → ailaunchkit.ai/pricing",
     ].join("\n");
 }
+/** The closing prerequisites note on a free install (#6440 AC4). */
+export const FREE_PREREQUISITES_NOTE = "No database, no licence key and no vendor API key are needed to run or build this site.";
+/**
+ * The same note on a licensed install (#6480): it drops the licence-key claim,
+ * which would contradict the key the customer just installed with.
+ */
+export const LICENSED_PREREQUISITES_NOTE = "No database and no vendor API key are needed to run or build this site.";
+/**
+ * Whether an install delivered paid content — any paid module in the effective
+ * module set, `union(template.requires, --modules)`, the same union
+ * `scaffold()` gates on. A paid template is covered by that union too:
+ * `templateDelivery` derives "paid" from `requires` alone.
+ */
+export function isLicensedInstall(opts) {
+    const requires = opts.template !== undefined ? resolveTemplate(opts.template).requires : [];
+    const modules = normalizeModules([
+        ...requires,
+        ...(opts.modules ?? ["marketing"]),
+    ]);
+    return classifyModules(modules).paid.length > 0;
+}