create-ailk 0.6.1 → 0.7.0

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

@@ -100,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"]),
@@ -449,6 +451,12 @@ 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 {
@@ -494,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
@@ -506,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
@@ -553,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,
@@ -564,7 +592,9 @@ 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, markers);
+    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 });
@@ -575,14 +605,25 @@ export function installBundleTree(options) {
         // 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.
-        writeOneFile(resolve(sourceRoot, source), destAbs, [source, destination], markers);
+        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
@@ -598,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
@@ -614,7 +658,7 @@ export function installBundleTree(options) {
  * `markers`, when given, is substituted into every TEXT file on the way
  * through (#6460) — see `InstallBundleTreeOptions.markers`.
  */
-function copyTree(srcRoot, destRoot, excluded = new Set(), markers) {
+function copyTree(srcRoot, destRoot, excluded, markers, policy, report) {
     const stack = [srcRoot];
     while (stack.length > 0) {
         const dir = stack.pop();
@@ -632,7 +676,9 @@ function copyTree(srcRoot, destRoot, excluded = new Set(), markers) {
                 if (excluded.has(rel.split(sep).join("/")))
                     continue;
                 mkdirSync(join(destPath, ".."), { recursive: true });
-                writeOneFile(srcPath, destPath, [rel], markers);
+                const row = writeOneFile(srcPath, destPath, toPosix(rel), [rel], markers, policy);
+                if (row !== undefined)
+                    report.push(row);
             }
             // symlinks: never present — safeExtractTarGz rejects them outright.
         }
@@ -663,15 +709,121 @@ function copyTree(srcRoot, destRoot, excluded = new Set(), markers) {
  * `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, relsForType, markers) {
-    if (markers === undefined || !relsForType.every(isTextFile)) {
+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);
-        return;
     }
-    writeFileSync(destAbs, substituteMarkers(readFileSync(srcAbs, "utf8"), markers), {
-        mode: statSync(srcAbs).mode & 0o777,
-    });
+    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

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/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,10 +5,12 @@
  * 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",
@@ -18,3 +20,24 @@ export function proCallout() {
         "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;
+}

package/dist/license-set.d.ts

@@ -0,0 +1,34 @@
+export interface LicenseSetRunResult {
+    /** Exit status; null when the process never ran or was killed. */
+    status: number | null;
+    /** Set when the process could not be spawned (e.g. `ENOENT`). */
+    error?: NodeJS.ErrnoException;
+}
+/**
+ * Runs `vercel <args>`. The command itself is fixed — a runner is never
+ * handed one to run, per the package's hard-coded-command invariant
+ * (security.test.ts).
+ * `input`, when given, is written to the child's stdin.
+ */
+export type LicenseSetRunner = (args: readonly string[], options: {
+    cwd: string;
+    input?: string;
+}) => LicenseSetRunResult;
+export interface LicenseSetIO {
+    /** Resolves a relative or absent `[dir]`. */
+    cwd: string;
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    /** Reads all of stdin — used only by the `-` form. */
+    readStdin: () => string;
+    /** Defaults to `spawnSync` with `shell: false` (see `defaultRunner`). */
+    runner?: LicenseSetRunner;
+}
+export declare const LICENSE_SET_HELP = "create-ailk license set \u2014 put your licence key into an existing site.\n\nUsage:\n  pnpm create ailk@latest license set <key> [<target-dir>]\n  pnpm create ailk@latest license set - [<target-dir>] < key.txt\n\nArguments:\n  <key>                    Your licence key, or `-` to read it from stdin\n                           (keeps it out of your shell history).\n  <target-dir>             An already-scaffolded repo (contains\n                           architecture.yaml). Defaults to the current dir.\n\nWrites the key to ailk.key and apps/api/.env (owner-only, gitignored). When the\nsite (or apps/api, or apps/web) is linked to Vercel, it also replaces the\nproduction AILK_LICENSE_KEY variable and redeploys.\n";
+/** `spawnSync`, never through a shell; stdin piped only when there is input. */
+export declare const defaultRunner: LicenseSetRunner;
+/**
+ * Run `license set` with `argv` = everything after the `license set` words.
+ * Returns the process exit code; never throws for an expected failure.
+ */
+export declare function runLicenseSet(argv: string[], io: LicenseSetIO): number;