create-ailk 0.26.0 → 0.28.0

package/dist/body-heading.js

@@ -0,0 +1,394 @@
+/**
+ * The page body owns its H1 (#7495, spec docs/specs/7495-the-page-body-owns-its-spec.md
+ * D3–D5, D8): on a page `apps/web` renders in `bodyMode: "mdx-body"`, the one
+ * `<h1>` a reader sees is the body's `# ` heading — renderPage prints nothing
+ * from frontmatter `title` or `description` there.
+ *
+ * This module is the one owner of that rule, used by `create-ailk update`
+ * (the consumer's migration), `tools/content-compile` (the content check)
+ * and the tests:
+ *
+ * - which pages are mdx-body — read from the site's own `apps/web` routes,
+ *   always or only when frontmatter `sections[]` is empty (`mdxBodyRule`,
+ *   `isMdxBodyPage`);
+ * - how many `# ` headings a body has (`countBodyHeadings`);
+ * - the codemod that gives a page with none `# <title>` and its description
+ *   paragraph (`addBodyHeading`, `planBodyHeadings`, `migrateBodyHeadings`).
+ *   A page with one or more headings is never written.
+ *
+ * Frontmatter is read with a dependency-free subset of YAML for the three
+ * keys it needs — `create-ailk` ships exactly one runtime dependency (`tar`),
+ * the `design-package.ts` posture — and any form the subset does not cover
+ * is refused, never guessed at. No relative imports: `tools/` imports this
+ * file from source.
+ */
+import { existsSync, lstatSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+// The `renderPage({ … })` discovery regexes of `tools/lint-mdx-body-compiles.ts`.
+const RENDER_PAGE_CALL_RE = /renderPage\s*\(\s*\{[\s\S]*?\}\s*\)/g;
+const TYPE_RE = /type\s*:\s*["']([A-Za-z]+)["']/;
+const MDX_BODY_MODE_RE = /bodyMode\s*:\s*["']mdx-body["']/;
+// `...(composed ? {} : { bodyMode: "mdx-body" … })` — the routes' sections test.
+const CONDITIONAL_MDX_BODY_RE = /\?\s*\{\s*\}\s*:\s*\{[^}]*bodyMode\s*:\s*["']mdx-body["']/;
+// A content hub's `HubConfig` (#10121): `hubPageInput` sets `bodyMode` from
+// its `body` — `mdx-body` always, `composed` unless `sections[]` is non-empty.
+// A hub page holds one config, so its one `listType` and one `body` pair in
+// any order; a file with more of either is not read.
+const HUB_INPUT_RE = /\bhubPageInput\s*\(/;
+const HUB_LIST_TYPE_RE = /\blistType\s*:\s*["']([A-Za-z]+)["']/g;
+const HUB_BODY_RE = /\bbody\s*:\s*["'](mdx-body|composed|sections)["']/g;
+const LOCALE_RE = /^[a-z]{2}(-[A-Z]{2})?$/;
+const SKIPPED_DIRS = new Set(["node_modules", ".next", "dist"]);
+function pageFiles(dir, out = []) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (SKIPPED_DIRS.has(entry.name))
+            continue;
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            pageFiles(path, out);
+        else if (entry.isFile() && (entry.name === "page.tsx" || entry.name === "page.ts"))
+            out.push(path);
+    }
+    return out;
+}
+/**
+ * Scan `<appsRoot>/apps/web/app/**\/page.{ts,tsx}` for `renderPage({…})` calls
+ * naming `bodyMode: "mdx-body"`. A call whose `bodyMode` sits in a conditional
+ * spread is `"unless-sections"`, any other `"always"`; `"always"` wins when two
+ * routes name one type. A content hub's `HubConfig` reads the same way, from
+ * its `body`. A missing `apps/web/app` gives an empty map.
+ */
+export function mdxBodyRule(appsRoot) {
+    const rule = new Map();
+    const appDir = join(appsRoot, "apps", "web", "app");
+    if (!existsSync(appDir))
+        return rule;
+    for (const file of pageFiles(appDir)) {
+        const source = readFileSync(file, "utf8");
+        if (HUB_INPUT_RE.test(source)) {
+            const types = [...source.matchAll(HUB_LIST_TYPE_RE)];
+            const bodies = [...source.matchAll(HUB_BODY_RE)];
+            if (types.length === 1 && bodies.length === 1) {
+                const type = types[0][1];
+                const body = bodies[0][1];
+                if (body === "mdx-body")
+                    rule.set(type, "always");
+                else if (body === "composed" && !rule.has(type))
+                    rule.set(type, "unless-sections");
+            }
+        }
+        for (const call of source.matchAll(RENDER_PAGE_CALL_RE)) {
+            const block = call[0];
+            if (!MDX_BODY_MODE_RE.test(block))
+                continue;
+            const type = TYPE_RE.exec(block)?.[1];
+            if (type === undefined)
+                continue;
+            if (CONDITIONAL_MDX_BODY_RE.test(block)) {
+                if (!rule.has(type))
+                    rule.set(type, "unless-sections");
+            }
+            else {
+                rule.set(type, "always");
+            }
+        }
+    }
+    return rule;
+}
+/** The routes' own `composed` test: mdx-body unless `sections` is a non-empty array. */
+export function isMdxBodyPage(type, frontmatter, rule) {
+    const mode = rule.get(type);
+    if (mode === "always")
+        return true;
+    if (mode !== "unless-sections")
+        return false;
+    const sections = frontmatter.sections;
+    return !(Array.isArray(sections) && sections.length > 0);
+}
+// ── The heading count (D4) ───────────────────────────────────────────────────
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
+const ATX_H1_RE = /^ {0,3}# +\S/;
+/**
+ * ATX level-1 headings (`^ {0,3}# +\S`) outside fenced code blocks and
+ * multi-line `{/* … *\/}` comments. `##`, `#text` and Setext headings do not
+ * count. A fence closes, as in CommonMark, on a run of its own character at
+ * least as long as the opening one, with nothing after it.
+ */
+export function countBodyHeadings(body) {
+    let fence;
+    let inComment = false;
+    let count = 0;
+    for (const line of body.split(/\r?\n/)) {
+        if (inComment) {
+            if (line.includes("*/}"))
+                inComment = false;
+            continue;
+        }
+        const fenceMatch = FENCE_RE.exec(line);
+        if (fence !== undefined) {
+            const run = fenceMatch?.[1];
+            if (run !== undefined &&
+                run[0] === fence[0] &&
+                run.length >= fence.length &&
+                line.slice(fenceMatch[0].length).trim() === "") {
+                fence = undefined;
+            }
+            continue;
+        }
+        if (fenceMatch !== null) {
+            fence = fenceMatch[1];
+            continue;
+        }
+        if (ATX_H1_RE.test(line))
+            count += 1;
+        const open = line.lastIndexOf("{/*");
+        if (open !== -1 && !line.includes("*/", open + 3))
+            inComment = true;
+    }
+    return count;
+}
+function splitPage(raw) {
+    const open = /^\uFEFF?---[ \t]*\r?\n/.exec(raw);
+    if (open === null)
+        return undefined;
+    const close = /^---[ \t]*(?:\r?\n|$)/m;
+    const rest = raw.slice(open[0].length);
+    const match = close.exec(rest);
+    if (match === null)
+        return undefined;
+    return {
+        frontmatter: rest.slice(0, match.index).split(/\r?\n/),
+        bodyStart: open[0].length + match.index + match[0].length,
+    };
+}
+class Refused extends Error {
+}
+const refusedKey = (key) => new Refused(`frontmatter the subset reader does not read: ${key}`);
+/** The value after `<key>:` on its top-level line, and the lines after it. */
+function topLevel(lines, key) {
+    const prefix = `${key}:`;
+    const index = lines.findIndex((line) => line.startsWith(prefix));
+    if (index === -1)
+        return undefined;
+    return { value: lines[index].slice(prefix.length).trim(), next: lines.slice(index + 1) };
+}
+const nextNonBlank = (lines) => lines.find((line) => line.trim() !== "");
+/** The key's value goes on below it: its next non-blank line is indented. */
+const continues = (next) => /^[ \t]/.test(nextNonBlank(next) ?? "");
+const YAML_INDICATOR_RE = /^[-?:,[\]{}#&*!|>'"%@`]/;
+/** A single-line plain or double-quoted scalar; `""` for an absent or empty key. */
+function readScalar(lines, key) {
+    const entry = topLevel(lines, key);
+    if (entry === undefined)
+        return "";
+    const { value, next } = entry;
+    if (continues(next))
+        throw refusedKey(key);
+    if (value === "")
+        return "";
+    if (value.startsWith('"')) {
+        try {
+            const decoded = JSON.parse(value);
+            if (typeof decoded === "string")
+                return decoded;
+        }
+        catch {
+            // refused below
+        }
+        throw refusedKey(key);
+    }
+    if (YAML_INDICATOR_RE.test(value) || /\s#/.test(value))
+        throw refusedKey(key);
+    return value;
+}
+/**
+ * `sections` as empty (absent, `[]`) or non-empty: a one-line flow sequence
+ * with content, or an empty value whose next line opens a block sequence
+ * (`- `, indented or not) or, indented, a multi-line flow sequence (`[` and
+ * anything but `]`).
+ */
+function readSectionsNonEmpty(lines) {
+    const entry = topLevel(lines, "sections");
+    if (entry === undefined)
+        return false;
+    const value = entry.value.replace(/\s/g, "");
+    if (value === "[]")
+        return false;
+    if (value.startsWith("[") && value.endsWith("]"))
+        return true;
+    const rest = entry.next.filter((line) => line.trim() !== "");
+    if (value === "" && rest[0] !== undefined) {
+        const first = rest[0].trim();
+        if (first.startsWith("- "))
+            return true;
+        if (/^[ \t]/.test(rest[0])) {
+            if (first.replace(/\s/g, "") === "[]")
+                return false;
+            if (first.startsWith("[")) {
+                const after = first.slice(1).trim() || (rest[1]?.trim() ?? "");
+                if (after !== "" && !after.startsWith("]"))
+                    return true;
+            }
+        }
+    }
+    throw refusedKey("sections");
+}
+// ── Inserting the heading (D5) ───────────────────────────────────────────────
+const MDX_ESCAPED_RE = /[\\{<`*_[]/g;
+/**
+ * Text for an MDX body line: whitespace runs collapsed, trimmed, and every
+ * `\`, `{`, `<`, `` ` ``, `*`, `_` and `[` backslash-escaped.
+ */
+export function mdxText(text) {
+    return text.replace(/\s+/g, " ").trim().replace(MDX_ESCAPED_RE, (char) => `\\${char}`);
+}
+const headingText = (title) => mdxText(title).replace(/#$/, "\\#");
+// A leading block marker would start a heading, list or quote; a leading
+// `import `/`export ` would make the line ESM, so its first letter becomes a
+// character reference that renders as the same letter.
+const paragraphText = (description) => mdxText(description)
+    .replace(/^[#+>-]|^(\d+)([.)])/, (marker, digits, delimiter) => digits === undefined ? `\\${marker}` : `${digits}\\${delimiter}`)
+    .replace(/^(?:import|export)\b/, (word) => `&#${word.charCodeAt(0)};${word.slice(1)}`);
+/** Offset in `body` after leading blank lines and a leading ESM block. */
+function insertionPoint(body) {
+    const lines = body.split(/(?<=\n)/);
+    let at = 0;
+    let i = 0;
+    const blank = (line) => line !== undefined && line.trim() === "";
+    while (blank(lines[i]))
+        at += lines[i++].length;
+    if (!/^(?:import|export) /.test(lines[i] ?? ""))
+        return { at, afterEsm: false };
+    while (i < lines.length && !blank(lines[i]))
+        at += lines[i++].length;
+    const sawBlank = blank(lines[i]);
+    while (blank(lines[i]))
+        at += lines[i++].length;
+    return { at, afterEsm: !sawBlank };
+}
+function planPage(raw, rule, type) {
+    const mode = rule.get(type);
+    if (mode === undefined)
+        return { kind: "skip" };
+    const split = splitPage(raw);
+    const body = split === undefined ? raw : raw.slice(split.bodyStart);
+    if (countBodyHeadings(body) > 0)
+        return { kind: "skip" };
+    if (split === undefined)
+        return { kind: "refuse", reason: "no frontmatter" };
+    try {
+        if (mode === "unless-sections" && readSectionsNonEmpty(split.frontmatter)) {
+            return { kind: "skip" };
+        }
+        const title = readScalar(split.frontmatter, "title");
+        if (title.trim() === "")
+            return { kind: "refuse", reason: "no title" };
+        const description = readScalar(split.frontmatter, "description");
+        if (description.trim() === "")
+            return { kind: "refuse", reason: "no description" };
+        const eol = raw.includes("\r\n") ? "\r\n" : "\n";
+        const { at, afterEsm } = insertionPoint(body);
+        const rest = body.slice(at);
+        const front = raw.slice(0, split.bodyStart);
+        // A file that ends at its closing `---` with no line ending needs one first.
+        const lead = afterEsm
+            ? body.slice(0, at).endsWith("\n") ? eol : eol + eol
+            : front.endsWith("\n") ? "" : eol;
+        const inserted = `${lead}# ${headingText(title)}${eol}${eol}${paragraphText(description)}${eol}` +
+            (rest === "" ? "" : eol);
+        return { kind: "write", text: front + body.slice(0, at) + inserted + rest };
+    }
+    catch (err) {
+        if (err instanceof Refused)
+            return { kind: "refuse", reason: err.message };
+        throw err;
+    }
+}
+/**
+ * The new file text for an mdx-body page with zero `# ` headings — its
+ * `# <title>` and description paragraph inserted at the top of the body —
+ * else `undefined`. A page the subset reader refuses, with no frontmatter, or
+ * with an empty `title` or `description`, is never written.
+ */
+export function addBodyHeading(raw, rule, type) {
+    const plan = planPage(raw, rule, type);
+    return plan.kind === "write" ? plan.text : undefined;
+}
+/**
+ * Every `<contentDir>/<locale>/<Type>/<slug>.mdx` whose `<Type>` the rule
+ * names, sorted. Symlinks are skipped, as `copy.ts` and `update.ts` skip
+ * them, so the codemod never reads or writes outside `contentDir`.
+ */
+function rulePages(contentDir, rule) {
+    if (!existsSync(contentDir))
+        return [];
+    const pages = [];
+    for (const locale of readdirSync(contentDir, { withFileTypes: true })) {
+        if (!locale.isDirectory() || !LOCALE_RE.test(locale.name))
+            continue;
+        for (const type of rule.keys()) {
+            const typeDir = join(contentDir, locale.name, type);
+            if (!existsSync(typeDir) || !lstatSync(typeDir).isDirectory())
+                continue;
+            for (const entry of readdirSync(typeDir, { withFileTypes: true })) {
+                if (entry.isFile() && entry.name.endsWith(".mdx")) {
+                    pages.push({ path: join(typeDir, entry.name), type });
+                }
+            }
+        }
+    }
+    return pages.sort((a, b) => a.path.localeCompare(b.path));
+}
+/** What `migrateBodyHeadings` would write, and the heading-less pages it cannot. Never throws for a page. */
+export function planBodyHeadings(contentDir, rule) {
+    const plan = { writes: [], refused: [] };
+    for (const { path, type } of rulePages(contentDir, rule)) {
+        let page;
+        try {
+            page = planPage(readFileSync(path, "utf8"), rule, type);
+        }
+        catch (err) {
+            plan.refused.push({ path, reason: `could not be read: ${String(err)}` });
+            continue;
+        }
+        if (page.kind === "write")
+            plan.writes.push({ path, text: page.text });
+        else if (page.kind === "refuse")
+            plan.refused.push({ path, reason: page.reason });
+    }
+    return plan;
+}
+/** Every mdx-body page whose body does not have exactly one `# ` heading. */
+export function headingViolations(contentDir, rule) {
+    const violations = [];
+    for (const { path, type } of rulePages(contentDir, rule)) {
+        let raw;
+        try {
+            raw = readFileSync(path, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const split = splitPage(raw);
+        if (rule.get(type) === "unless-sections" && split !== undefined) {
+            try {
+                if (readSectionsNonEmpty(split.frontmatter))
+                    continue;
+            }
+            catch {
+                continue;
+            }
+        }
+        const count = countBodyHeadings(split === undefined ? raw : raw.slice(split.bodyStart));
+        if (count !== 1)
+            violations.push({ path, count });
+    }
+    return violations;
+}
+/** Write each planned page; the paths written and the refused rows. */
+export function migrateBodyHeadings(contentDir, rule) {
+    const { writes, refused } = planBodyHeadings(contentDir, rule);
+    for (const { path, text } of writes)
+        writeFileSync(path, text);
+    return { written: writes.map((write) => write.path), refused };
+}

package/dist/cli.js

@@ -60,7 +60,8 @@ import { withNpmTokenUserConfig } from "./lib/npm-auth.js";
 import { FREE_PREREQUISITES_NOTE, LICENSED_PREREQUISITES_NOTE, isLicensedInstall, proCallout, } from "./lib/pro-callout.js";
 import { LICENSE_SET_HELP, runLicenseSet } from "./license-set.js";
 import { PLUGIN_INSTALL_LINES, helpText, parseCliArgs, parseModules, resolveCliShape, toScaffoldOptions, } from "./parse-args.js";
-import { addModule, formatSurfaceDrift, scaffold, syncArchitectureSync, syncCatalogSync, syncClaudeMdSync, syncRoutesSync, } from "./programmatic.js";
+import { addModule, removeModule, formatSurfaceDrift, scaffold, syncArchitectureSync, syncCatalogSync, syncClaudeMdSync, syncRoutesSync, } from "./programmatic.js";
+import { REMOVE_MODULE_HELP, RemoveModuleRefusedError, formatRemoveModuleReport, parseRemoveModuleArgs, } from "./remove-module.js";
 import { SEED_FLOWS_HELP, SeedFlowsRefusedError, parseSeedFlowsArgs, seedFlows, } from "./seed-flows.js";
 import { CORE_SURFACE_PATHS, SURFACE_ALIASES } from "./surfaces.js";
 import { SYNC_ROUTES_HELP, formatSyncRoutesReport, parseSyncRoutesArgs, } from "./sync-routes.js";
@@ -146,6 +147,32 @@ async function main() {
         }
         process.exit(0);
     }
+    // `remove-module <module> [dir] [--force]` (#10040): the inverse of
+    // add-module for `marketing` and `docs-blog`. A refusal it names (another
+    // module, a spoke, docs-blog still installed, the site's own files in the
+    // set without --force) exits 2 before anything is written.
+    if (argv[0] === "remove-module") {
+        const args = parseRemoveModuleArgs(argv.slice(1));
+        if (args.help || args.module === undefined) {
+            process.stdout.write(REMOVE_MODULE_HELP);
+            process.exit(0);
+        }
+        try {
+            const result = removeModule({
+                targetDir: args.target ?? process.cwd(),
+                moduleName: args.module,
+                force: args.force,
+            });
+            process.stdout.write(formatRemoveModuleReport(result));
+        }
+        catch (err) {
+            if (!(err instanceof RemoveModuleRefusedError))
+                throw err;
+            process.stderr.write(`[create-ailk] ${err.message}\n`);
+            process.exit(err.exitCode);
+        }
+        process.exit(0);
+    }
     // `add-route <route> [dir]` (#6947): add a route surface the site was
     // scaffolded without — add-module's route, architecture and nav steps with
     // no licence and no bundle. A refusal it names (an unknown route, one a

package/dist/content-payloads.js

@@ -29,8 +29,8 @@ export const CONTENT_PAYLOADS = Object.freeze([
         kind: "template-set",
         name: "scaffold-commerce",
         feature: "commerce",
-        version: "1.0.1",
-        digest: "112704a7910dba3275defc0cb86b1b4f33fc8f262f4c09320e8f6b3a8d873916",
+        version: "1.0.2",
+        digest: "af6faf7bd35b4316bfa4bab1560f68c740c27f3ad9cf9dd4feca3187e70c14ad",
         sourceRoot: "packages/create-ailk/module-templates/commerce/.claude/skills/scaffold-commerce",
         files: Object.freeze([
             "references/lookup-keys-template.md",

package/dist/derive-architecture.js

@@ -239,7 +239,11 @@ export function deriveArchitecture(modules = ["marketing"], surfaces, options =
     const spoke = options.topology === "spoke";
     const keepMcp = options.mcp !== false;
     const selected = normalizeModules(modules);
-    const slices = selected.map((m) => MODULE_SLICES[m]);
+    // #10040 D4 — `marketing`'s `webImports` and `packages` are the base web
+    // app's permissions (the `(authed)` pages import `@working-theory/ui` and
+    // `@working-theory/theme` too), so they are composed whatever the selected
+    // set; only the `# Modules:` header and the `surfaces:` block follow it.
+    const slices = normalizeModules(["marketing", ...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
@@ -392,7 +396,9 @@ export function deriveArchitecture(modules = ["marketing"], surfaces, options =
         "# 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(", ")}`,
+        // #10040 — a site that dropped every module (a keyless scaffold minus
+        // `marketing`) still needs a readable header: `none`, never a blank.
+        `# Modules: ${selected.length > 0 ? selected.join(", ") : "none"}`,
         `# Surfaces: ${enabledSurfaces.length > 0 ? enabledSurfaces.join(", ") : "core only"}`,
         ...(spoke ? ["# Topology: spoke"] : []),
         "",

package/dist/index.d.ts

@@ -5,10 +5,11 @@
  */
 export { copyTemplate, type CopyTemplateOptions } from "./copy.js";
 export { parseCliArgs, parseModules, ParseError, helpText, RECOGNIZED_MODULES, type ModuleName, type CliOptions, } from "./parse-args.js";
-export { CATALOG_TARGET_PATH, FREE_MODULES, addModule, LicenseRequiredError, PAID_MODULES, classifyModules, formatSurfaceDrift, scaffold, scaffoldSync, syncArchitectureSync, syncCatalogSync, syncClaudeMdSync, syncRoutesSync, type AddModuleOptions, type ResolvePaidModulesOptions, type ScaffoldOptions, type ScaffoldResult, type SyncArchitectureOptions, type SyncArchitectureResult, type SyncCatalogResult, type SyncClaudeMdResult, type SyncRoutesSyncOptions, } from "./programmatic.js";
+export { CATALOG_TARGET_PATH, FREE_MODULES, addModule, removeModule, LicenseRequiredError, PAID_MODULES, classifyModules, formatSurfaceDrift, scaffold, scaffoldSync, syncArchitectureSync, syncCatalogSync, syncClaudeMdSync, syncRoutesSync, type AddModuleOptions, type RemoveModuleCliOptions, type ResolvePaidModulesOptions, type ScaffoldOptions, type ScaffoldResult, type SyncArchitectureOptions, type SyncArchitectureResult, type SyncCatalogResult, type SyncClaudeMdResult, type SyncRoutesSyncOptions, } from "./programmatic.js";
 export { DEFAULT_AILK_MODULE_REGISTRY_URL, FetchModuleError, fetchModule, type FetchModuleOptions, } from "./lib/fetch-module.js";
 export { extractModuleBundle, type ExistingFilePolicy, type ExtractModuleBundleOptions, type InstallReportRow, } from "./lib/extract-module-bundle.js";
 export { ADD_MODULE_HELP, AddModuleRefusedError, applyModuleToScaffold, formatAddModuleReport, parseAddModuleArgs, type AddModuleReportRow, type AddModuleResult, type ApplyModuleOptions, } from "./add-module.js";
+export { REMOVABLE_MODULES, REMOVE_MODULE_HELP, RemoveModuleRefusedError, formatRemoveModuleReport, parseRemoveModuleArgs, removeModuleFromScaffold, type RemoveModuleOptions, type RemoveModuleResult, } from "./remove-module.js";
 export { APPLY_DESIGN_HELP, UnreadChromeError, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, type ApplyDesignArgs, type ApplyDesignChange, type ApplyDesignOptions, type ApplyDesignResult, } from "./apply-design.js";
 export type { HomeSeedOutcome } from "./design-home.js";
 export { SITE_ROSTER_PATH, readSiteRoster, siteRosterProblems, } from "./site-roster.js";

package/dist/index.js

@@ -5,7 +5,7 @@
  */
 export { copyTemplate } from "./copy.js";
 export { parseCliArgs, parseModules, ParseError, helpText, RECOGNIZED_MODULES, } from "./parse-args.js";
-export { CATALOG_TARGET_PATH, FREE_MODULES, addModule, LicenseRequiredError, PAID_MODULES, classifyModules, formatSurfaceDrift, scaffold, scaffoldSync, syncArchitectureSync, syncCatalogSync, syncClaudeMdSync, syncRoutesSync, } from "./programmatic.js";
+export { CATALOG_TARGET_PATH, FREE_MODULES, addModule, removeModule, LicenseRequiredError, PAID_MODULES, classifyModules, formatSurfaceDrift, scaffold, scaffoldSync, syncArchitectureSync, syncCatalogSync, syncClaudeMdSync, 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.
@@ -14,6 +14,9 @@ export { extractModuleBundle, } from "./lib/extract-module-bundle.js";
 // `create-ailk add-module` (#6653) — apply a purchased module to an existing
 // site in place. The pure core, beside `sync-routes`'s.
 export { ADD_MODULE_HELP, AddModuleRefusedError, applyModuleToScaffold, formatAddModuleReport, parseAddModuleArgs, } from "./add-module.js";
+// `create-ailk remove-module` (#10040) — the inverse of add-module for the
+// marketing and docs-blog modules. The pure core, beside add-module's.
+export { REMOVABLE_MODULES, REMOVE_MODULE_HELP, RemoveModuleRefusedError, formatRemoveModuleReport, parseRemoveModuleArgs, removeModuleFromScaffold, } from "./remove-module.js";
 // `create-ailk apply-design` (#6819) — make an existing site wear a design,
 // changing only its look. The pure core, beside `add-module`'s.
 export { APPLY_DESIGN_HELP, UnreadChromeError, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, } from "./apply-design.js";

package/dist/lib/auth-secret-file.d.ts

@@ -1,6 +1,9 @@
 export declare const AUTH_SECRET_ENV_VAR = "BETTER_AUTH_SECRET";
+export declare const AUTH_URL_ENV_VAR = "BETTER_AUTH_URL";
 /** The files the writer owns, web first. */
 export declare const AUTH_SECRET_ENV_FILES: readonly [string, string];
+/** Each app's loopback origin, in `AUTH_SECRET_ENV_FILES` order. */
+export declare const AUTH_URL_DEFAULTS: readonly ["http://localhost:3000", "http://localhost:3001"];
 /**
  * `.gitignore` lines that already ignore `apps/<app>/.env.local`. An explicit
  * set, never a glob evaluation; `/.env.local` is absent because, anchored to
@@ -13,7 +16,8 @@ export interface WriteAuthSecretOptions {
 }
 /**
  * Give the scaffold at `dir` a `BETTER_AUTH_SECRET` (F1–F4 of the #6107
- * spec). Generates at most one value, and only when no app already has one.
- * Idempotent — a second call changes no byte.
+ * spec) and each app its loopback `BETTER_AUTH_URL` (#8620). Generates at
+ * most one secret, and only when no app already has one. Idempotent — a
+ * second call changes no byte.
  */
 export declare function writeAuthSecretFile(dir: string, opts?: WriteAuthSecretOptions): void;

package/dist/lib/auth-secret-file.js

@@ -1,5 +1,6 @@
 /**
- * Where a scaffold keeps its `BETTER_AUTH_SECRET` (#6107).
+ * Where a scaffold keeps its `BETTER_AUTH_SECRET` (#6107) and its
+ * `BETTER_AUTH_URL` (#8620, spec 9965 D10).
  *
  * `apps/web/auth.ts` refuses to serve in production without the secret
  * (#6044), and so does the Admin app's `auth.ts`. A fresh scaffold therefore
@@ -10,10 +11,15 @@
  *   - `apps/admin/.env.local` — when the scaffold carries `apps/admin`, with
  *     the SAME value (both apps sign cookies for one site).
  *
+ * Both `auth.ts` files also refuse to serve in production without
+ * `BETTER_AUTH_URL`, so each file gets that app's loopback origin too
+ * (`AUTH_URL_DEFAULTS`) — the origin `next start` answers on before the
+ * operator sets a public one.
+ *
  * Never clobber, never shadow: a value already assigned in any env file Next
  * loads for the app under `next start` is kept, and no new `.env.local` is
- * created above it. Never print: no message, log line or return value
- * carries the secret.
+ * created above it — per variable. Never print: no message, log line or
+ * return value carries the secret.
  *
  * Pure module: no `import.meta.url`, so jest imports it directly.
  */
@@ -22,11 +28,17 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { appendLine, writeOwnerOnly } from "./license-key-files.js";
 export const AUTH_SECRET_ENV_VAR = "BETTER_AUTH_SECRET";
+export const AUTH_URL_ENV_VAR = "BETTER_AUTH_URL";
 /** The files the writer owns, web first. */
 export const AUTH_SECRET_ENV_FILES = [
     join("apps", "web", ".env.local"),
     join("apps", "admin", ".env.local"),
 ];
+/** Each app's loopback origin, in `AUTH_SECRET_ENV_FILES` order. */
+export const AUTH_URL_DEFAULTS = [
+    "http://localhost:3000",
+    "http://localhost:3001",
+];
 /**
  * `.gitignore` lines that already ignore `apps/<app>/.env.local`. An explicit
  * set, never a glob evaluation; `/.env.local` is absent because, anchored to
@@ -45,17 +57,20 @@ const NEXT_START_ENV_FILES = [
     ".env.production",
     ".env",
 ];
-/** A line assigning the variable, with or without `export`; group 1 is the value. */
-const ENV_LINE = new RegExp(`^\\s*(?:export\\s+)?${AUTH_SECRET_ENV_VAR}\\s*=(.*)$`);
+/** A line assigning `name`, with or without `export`; group 1 is the value. */
+function envLine(name) {
+    return new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=(.*)$`);
+}
 /**
  * The value `text` assigns — the LAST assignment, as dotenv reads it — or
  * `undefined` when it assigns none. An empty value counts as none, exactly as
  * `auth.ts` treats it.
  */
-function assignedValue(text) {
+function assignedValue(text, name) {
+    const pattern = envLine(name);
     let value;
     for (const line of text.split("\n")) {
-        const m = ENV_LINE.exec(line);
+        const m = pattern.exec(line);
         if (m !== null) {
             const raw = (m[1] ?? "").trim();
             const quoted = /^(["'])(.*)\1$/.exec(raw);
@@ -64,13 +79,13 @@ function assignedValue(text) {
     }
     return value === "" ? undefined : value;
 }
-/** The effective value for the app at `appDir`, by Next's precedence. */
-function effectiveValue(appDir) {
-    for (const name of NEXT_START_ENV_FILES) {
-        const path = join(appDir, name);
+/** The effective value of `name` for the app at `appDir`, by Next's precedence. */
+function effectiveValue(appDir, name) {
+    for (const file of NEXT_START_ENV_FILES) {
+        const path = join(appDir, file);
         if (!existsSync(path))
             continue;
-        const value = assignedValue(readFileSync(path, "utf8"));
+        const value = assignedValue(readFileSync(path, "utf8"), name);
         if (value !== undefined)
             return value;
     }
@@ -78,29 +93,40 @@ function effectiveValue(appDir) {
 }
 /**
  * Give the scaffold at `dir` a `BETTER_AUTH_SECRET` (F1–F4 of the #6107
- * spec). Generates at most one value, and only when no app already has one.
- * Idempotent — a second call changes no byte.
+ * spec) and each app its loopback `BETTER_AUTH_URL` (#8620). Generates at
+ * most one secret, and only when no app already has one. Idempotent — a
+ * second call changes no byte.
  */
 export function writeAuthSecretFile(dir, opts = {}) {
     // Web always; Admin only when the scaffold carries `apps/admin`.
-    const apps = AUTH_SECRET_ENV_FILES.map((file) => ({
+    const apps = AUTH_SECRET_ENV_FILES.map((file, i) => ({
         file: join(dir, file),
         appDir: dirname(join(dir, file)),
+        url: AUTH_URL_DEFAULTS[i],
     })).filter(({ appDir }, i) => i === 0 || existsSync(appDir));
     // An existing value — web's first — is shared; a fresh one is generated
     // only when no app has one.
     let secret = apps
-        .map(({ appDir }) => effectiveValue(appDir))
+        .map(({ appDir }) => effectiveValue(appDir, AUTH_SECRET_ENV_VAR))
         .find((v) => v !== undefined);
     const secretFor = () => {
         secret ??= (opts.randomBytes ?? nodeRandomBytes)(32).toString("base64url");
         return secret;
     };
-    for (const { file, appDir } of apps) {
-        if (effectiveValue(appDir) !== undefined)
+    for (const { file, appDir, url } of apps) {
+        const lines = [];
+        if (effectiveValue(appDir, AUTH_SECRET_ENV_VAR) === undefined) {
+            lines.push(`${AUTH_SECRET_ENV_VAR}=${secretFor()}`);
+        }
+        if (effectiveValue(appDir, AUTH_URL_ENV_VAR) === undefined) {
+            lines.push(`${AUTH_URL_ENV_VAR}=${url}`);
+        }
+        if (lines.length === 0)
             continue;
-        const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
-        writeOwnerOnly(file, appendLine(existing, `${AUTH_SECRET_ENV_VAR}=${secretFor()}`));
+        let text = existsSync(file) ? readFileSync(file, "utf8") : "";
+        for (const line of lines)
+            text = appendLine(text, line);
+        writeOwnerOnly(file, text);
     }
     const ignorePath = join(dir, ".gitignore");
     const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : "";