create-ailk 0.27.0 → 0.28.0

package/dist/remove-module.js

@@ -0,0 +1,620 @@
+/**
+ * `create-ailk remove-module <marketing|docs-blog>` — the inverse of
+ * `add-module` (#10040): take a module's public pages off a scaffolded site so
+ * they stay off.
+ *
+ * What a run does, in order (spec 10040 D1–D7):
+ *
+ *   1. refuses a module other than `marketing` or `docs-blog` (decision 6), a
+ *      module the site does not carry, a spoke, and `marketing` while the
+ *      site still carries `docs-blog` ("remove docs-blog first", D3);
+ *   2. derives the removal set from the scaffold's own tree, never a list
+ *      (D2): for `marketing`, every directory under `apps/web/app/[locale]/`
+ *      outside `HUB_KEPT_ROUTE_DIRS` and every `content/<locale>/<type>/`
+ *      outside the kept legal types; for `docs-blog`, the slice's
+ *      `ownedFiles` under `apps/web/` and its `pageContributions` content;
+ *   3. classifies every path (D5): an app path whose bytes differ from its
+ *      record row, or from the running template's copy, or that neither the
+ *      template nor a carried module delivers, is the site's own — so is any
+ *      seed content no shipped seed layer renders identically. Those paths
+ *      stop the run (exit 2) before any write unless `--force`;
+ *   4. deletes the set and prunes the directories it emptied;
+ *   5. retires each deleted recordable app path by KEEPING (or adding) its
+ *      `.ailk-template-files.json` row with the template copy's hash (D1):
+ *      `update` then reads it as "deleted locally" and never writes it back;
+ *   6. drops the module from `.ailk-site-manifest.json` (`modules` and the
+ *      roster rows), regenerates `architecture.yaml` (the header without the
+ *      module; `marketing`'s import permissions stay, D4), the module flags,
+ *      the paid-sections registry and — unless the site has edited it — the
+ *      nav, empty on a site without `marketing`.
+ *
+ * Pure module: no `import.meta.url`, so jest can import it directly — the
+ * package-rooted inputs are supplied by `programmatic.ts`'s `removeModule`,
+ * the `add-module.ts` / `addModule` split.
+ */
+import { existsSync, readFileSync, readdirSync, rmSync, rmdirSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { parseArgs } from "node:util";
+import { readArchitectureHeader } from "./add-module-core.js";
+import { syncNavConfig } from "./add-module.js";
+import { renderTemplateFile } from "./copy.js";
+import { deriveArchitecture } from "./derive-architecture.js";
+import { MODULE_SLICES, normalizeModules } from "./module-architecture.js";
+import { MODULE_FLAGS_PATH, PAID_MCP_TOOLS_PATH, PAID_SECTIONS_PATH, writePaidSections, } from "./paid-sections.js";
+import { ParseError, parseModules } from "./parse-args.js";
+import { SITE_ROSTER_PATH, readSiteRoster } from "./site-roster.js";
+import { HUB_KEPT_ROUTE_DIRS, MODULE_SURFACES, ROUTE_ROOT, resolveSurfaces, } from "./surfaces.js";
+import { BASE_LAYER_DIR, templateTreeDir } from "./template-manifest.js";
+import { TEMPLATE_RECORD_PATH, isRecordable, parseTemplateRecord, serializeTemplateRecord, sha256Hex, } from "./template-record.js";
+import { readSiteTopology } from "./topology.js";
+/** The modules `remove-module` takes (decision 6). */
+export const REMOVABLE_MODULES = ["marketing", "docs-blog"];
+/**
+ * The `content/<locale>/<type>/` directories a site keeps when it drops
+ * `marketing`: the seeds of the kept legal pages (`HUB_KEPT_ROUTES`).
+ */
+export const HUB_KEPT_CONTENT_TYPES = [
+    "PrivacyPage",
+    "TermsPage",
+    "WorkingAgreementPage",
+];
+/** The kept legal surfaces, by `GATEABLE_SURFACES` id — the only surfaces a hub's header lists. */
+const HUB_KEPT_SURFACES = ["privacy", "terms", "working-agreement"];
+/** A refusal the CLI exits 2 on — the same shape `add-module` throws. */
+export class RemoveModuleRefusedError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "RemoveModuleRefusedError";
+    }
+}
+// ── The removal set (D2) ─────────────────────────────────────────────────────
+/** Every regular file at or under `abs`, as `/`-separated paths relative to `root`. A symlink is skipped. */
+function filesUnder(root, rel) {
+    const out = [];
+    const stack = [rel];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        const abs = join(root, ...current.split("/"));
+        for (const entry of readdirSync(abs, { withFileTypes: true })) {
+            const next = `${current}/${entry.name}`;
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory())
+                stack.push(next);
+            else if (entry.isFile())
+                out.push(next);
+        }
+    }
+    return out.sort();
+}
+function isDir(abs) {
+    return existsSync(abs) && statSync(abs).isDirectory();
+}
+/** The directories `remove-module marketing` removes: the public route tree and the non-legal seeds. */
+export function marketingRemovalDirs(targetDir) {
+    const dirs = [];
+    const routeRoot = join(targetDir, ...ROUTE_ROOT.split("/"));
+    if (isDir(routeRoot)) {
+        for (const entry of readdirSync(routeRoot, { withFileTypes: true })) {
+            if (!entry.isDirectory() || HUB_KEPT_ROUTE_DIRS.includes(entry.name))
+                continue;
+            dirs.push(`${ROUTE_ROOT}/${entry.name}`);
+        }
+    }
+    const contentRoot = join(targetDir, "content");
+    if (isDir(contentRoot)) {
+        for (const locale of readdirSync(contentRoot, { withFileTypes: true })) {
+            if (!locale.isDirectory())
+                continue;
+            for (const type of readdirSync(join(contentRoot, locale.name), { withFileTypes: true })) {
+                if (!type.isDirectory() || HUB_KEPT_CONTENT_TYPES.includes(type.name))
+                    continue;
+                dirs.push(`content/${locale.name}/${type.name}`);
+            }
+        }
+    }
+    return dirs.sort();
+}
+/**
+ * The removal-set files a KEPT file imports — kept with their own imports,
+ * to a fixed point (#10040). `apps/web/app/[locale]/contact/` holds helpers
+ * the locale layout and `lib/in-page-magnet.ts` import beside its page;
+ * deleting them with the page breaks the kept tree's type-check. Only
+ * `apps/web` code is scanned; a kept file is any `.ts`/`.tsx` outside the
+ * removal set (node_modules, .next and dist excluded).
+ */
+export function importedByKept(targetDir, removal) {
+    const removalSet = new Set(removal);
+    const keptBy = new Map();
+    const scanned = new Set();
+    const queue = [];
+    const webRoot = join(targetDir, "apps", "web");
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name === "node_modules" || entry.name === ".next" || entry.name === "dist")
+                continue;
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(abs);
+            else if (/\.(ts|tsx|mts|mjs|js)$/.test(entry.name)) {
+                const rel = relative(targetDir, abs).split(sep).join("/");
+                if (!removalSet.has(rel))
+                    queue.push(rel);
+            }
+        }
+    };
+    if (isDir(webRoot))
+        walk(webRoot);
+    // `@/*` is apps/web's one tsconfig path alias (`"@/*": ["./*"]`); a bare
+    // package specifier is never a removal-set file, so nothing else resolves.
+    const resolveSpecifier = (fromRel, spec) => {
+        const base = spec.startsWith("@/")
+            ? resolve(webRoot, spec.slice(2))
+            : resolve(targetDir, dirname(fromRel), spec);
+        for (const candidate of [base, `${base}.ts`, `${base}.tsx`, `${base}.mts`, `${base}.mjs`, `${base}.js`, join(base, "index.ts"), join(base, "index.tsx")]) {
+            if (existsSync(candidate) && statSync(candidate).isFile()) {
+                return relative(targetDir, candidate).split(sep).join("/");
+            }
+        }
+        return undefined;
+    };
+    while (queue.length > 0) {
+        const rel = queue.pop();
+        if (scanned.has(rel))
+            continue;
+        scanned.add(rel);
+        const text = readFileSync(join(targetDir, ...rel.split("/")), "utf8");
+        for (const m of text.matchAll(/(?:from\s*|import\s*\(\s*|jest\.mock\(\s*|require\(\s*)["']((?:\.{1,2}|@)\/[^"']+)["']/g)) {
+            const target = resolveSpecifier(rel, m[1]);
+            if (target === undefined || !removalSet.has(target) || keptBy.has(target))
+                continue;
+            keptBy.set(target, rel);
+            queue.push(target);
+        }
+    }
+    return keptBy;
+}
+/** The paths a module's removal deletes, site-relative, only those on disk. */
+export function removalSet(targetDir, moduleName) {
+    if (moduleName === "marketing") {
+        return marketingRemovalDirs(targetDir).flatMap((dir) => filesUnder(targetDir, dir));
+    }
+    const slice = MODULE_SLICES[moduleName];
+    const owned = (slice.ownedFiles ?? []).filter((p) => p.startsWith("apps/web/"));
+    const seeds = (slice.pageContributions ?? []).flatMap((c) => c.content ?? []);
+    return [...new Set([...owned, ...seeds])]
+        .filter((p) => existsSync(join(targetDir, ...p.split("/"))))
+        .sort();
+}
+/** The template's copy of `path`, rendered as `copyTemplate` wrote it, or undefined when the template lacks it. */
+function templateCopy(layers, path) {
+    const abs = join(layers.templatesDir, ...path.split("/"));
+    if (!existsSync(abs) || !statSync(abs).isFile())
+        return undefined;
+    return renderTemplateFile(readFileSync(abs), path, layers.versions, layers.markers);
+}
+/** Whether any seed layer carries `path` at all. */
+function seedLayerHas(layers, path) {
+    return layers.seedRoots.some((root) => {
+        const abs = join(root, ...path.split("/"));
+        return existsSync(abs) && statSync(abs).isFile();
+    });
+}
+/** Whether a seed layer renders `path` byte-identically to the site's copy. */
+function seedMatches(layers, path, disk) {
+    for (const root of layers.seedRoots) {
+        const abs = join(root, ...path.split("/"));
+        if (!existsSync(abs) || !statSync(abs).isFile())
+            continue;
+        const raw = readFileSync(abs);
+        if (raw.equals(disk))
+            return true;
+        if (Buffer.from(renderTemplateFile(raw, path, layers.versions, layers.markers)).equals(disk)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Whether the site has edited `path` (D5): a recorded app path whose bytes
+ * differ from its row; an unrecorded one that differs from the template's
+ * copy; a path neither the template nor a carried module's bundle delivers
+ * (the site's own page); a `content/` seed no shipped layer renders
+ * identically. A carried module's own sample seed is the module's.
+ */
+function isEdited(layers, targetDir, path) {
+    const disk = readFileSync(join(targetDir, ...path.split("/")));
+    // A carried module's own sample seeds are placeholders by contract (the
+    // starter-template contract R2); no shipped layer holds their bytes to
+    // compare, and they are never the site's own page.
+    if (layers.moduleSeeds.has(path) || layers.moduleSeedDirs.some((d) => path.startsWith(d))) {
+        return false;
+    }
+    if (path.startsWith("content/")) {
+        // A seed a shipped layer carries is compared byte for byte; one only the
+        // roster of record declares came from a module bundle with no copy on
+        // this machine, and is a placeholder by contract — never the site's own.
+        if (seedLayerHas(layers, path))
+            return !seedMatches(layers, path, disk);
+        if (layers.rosterSeeds.has(path) || layers.rosterSeedDirs.some((d) => path.startsWith(d))) {
+            return false;
+        }
+        return true;
+    }
+    const row = layers.record?.files[path];
+    if (row !== undefined)
+        return sha256Hex(disk) !== row.sha256;
+    const copy = templateCopy(layers, path);
+    if (copy !== undefined)
+        return !Buffer.from(copy).equals(disk);
+    if (layers.moduleCode.has(path))
+        return false;
+    return true;
+}
+function moduleDeliveries(modules) {
+    const code = new Set();
+    const seeds = new Set();
+    const seedDirs = [];
+    for (const name of modules) {
+        const slice = MODULE_SLICES[name];
+        for (const p of slice.ownedFiles ?? [])
+            code.add(p);
+        for (const dest of Object.values(slice.installMap ?? {})) {
+            if (dest.startsWith("content/"))
+                seeds.add(dest);
+            else
+                code.add(dest);
+        }
+        for (const c of slice.pageContributions ?? []) {
+            for (const p of c.content ?? [])
+                seeds.add(p);
+            if (c.contentDir !== undefined)
+                seedDirs.push(`${c.contentDir}/`);
+        }
+    }
+    return { code, seeds, seedDirs };
+}
+// ── The run ──────────────────────────────────────────────────────────────────
+/** Remove every directory under `root` left empty, then `root` itself if empty and `removeRoot`. */
+function pruneEmpty(abs, removeRoot) {
+    if (!isDir(abs))
+        return;
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+        if (entry.isDirectory())
+            pruneEmpty(join(abs, entry.name), true);
+    }
+    if (removeRoot && readdirSync(abs).length === 0)
+        rmdirSync(abs);
+}
+/** `text` with its `"modules": [...]` value replaced. */
+function withModules(text, modules) {
+    const rendered = modules.length === 0 ? "[]" : `[${modules.map((m) => JSON.stringify(m)).join(", ")}]`;
+    return text.replace(/"modules":\s*\[[^\]]*\]/, `"modules": ${rendered}`);
+}
+/**
+ * Removes one module from a scaffolded site. Every refusal is raised before
+ * the first write; the writes that follow (delete → record → architecture →
+ * manifest → generated files) are not atomic, but each is idempotent on its
+ * own inputs, so a run interrupted mid-way converges on the next invocation —
+ * `--force` is then needed only if the first run needed it.
+ */
+export function removeModuleFromScaffold(opts) {
+    const targetDir = resolve(opts.targetDir);
+    const { moduleName } = opts;
+    // ── Refusals, before the first write ────────────────────────────────────
+    if (!REMOVABLE_MODULES.includes(moduleName)) {
+        throw new RemoveModuleRefusedError(`remove-module takes ${REMOVABLE_MODULES.join(" or ")}, not "${moduleName}" — a paid module's pages stay with its licence; only the public marketing tree and the docs-blog pages can be dropped (#10040)`);
+    }
+    const archPath = join(targetDir, "architecture.yaml");
+    if (!existsSync(archPath)) {
+        throw new RemoveModuleRefusedError(`not a scaffolded repo: no architecture.yaml at ${targetDir}. Run \`create-ailk <target-dir>\` to scaffold first.`);
+    }
+    if (readSiteTopology(targetDir) === "spoke") {
+        throw new RemoveModuleRefusedError("remove-module runs on a hub: a spoke is its public site, so it keeps the marketing module");
+    }
+    const current = readArchitectureHeader(readFileSync(archPath, "utf8"));
+    if (readSiteRoster(targetDir) === undefined) {
+        throw new RemoveModuleRefusedError("remove-module needs the site's roster of record (.ailk-site-manifest.json): the module list it records is what update and sync-routes read afterwards. A template-less scaffold has none.");
+    }
+    if (opts.fromScaffold !== true && !current.modules.includes(moduleName)) {
+        throw new RemoveModuleRefusedError(`this site does not carry "${moduleName}" (architecture.yaml modules: ${current.modules.join(", ")})`);
+    }
+    if (moduleName === "marketing" && current.modules.includes("docs-blog")) {
+        throw new RemoveModuleRefusedError("this site carries docs-blog, whose /docs and /blog pages the marketing removal would delete too — run `create-ailk remove-module docs-blog` first");
+    }
+    const recordPath = join(targetDir, TEMPLATE_RECORD_PATH);
+    const record = existsSync(recordPath)
+        ? parseTemplateRecord(readFileSync(recordPath, "utf8"))
+        : undefined;
+    const siteRoster = readSiteRoster(targetDir);
+    const seedRoots = [
+        opts.templatesDir,
+        join(opts.siteTemplatesDir, BASE_LAYER_DIR),
+        ...(siteRoster !== undefined
+            ? [join(opts.siteTemplatesDir, templateTreeDir(siteRoster.template.name))]
+            : []),
+    ];
+    const deliveries = moduleDeliveries(current.modules);
+    const rosterSeeds = new Set();
+    const rosterSeedDirs = [];
+    for (const row of siteRoster?.rows ?? []) {
+        const content = row.value["content"];
+        if (Array.isArray(content))
+            for (const p of content)
+                if (typeof p === "string")
+                    rosterSeeds.add(p);
+        const seeds = row.value["seeds"];
+        if (Array.isArray(seeds))
+            for (const p of seeds)
+                if (typeof p === "string")
+                    rosterSeeds.add(p);
+        const dir = row.value["contentDir"];
+        if (typeof dir === "string")
+            rosterSeedDirs.push(`${dir}/`);
+    }
+    const layers = {
+        templatesDir: opts.templatesDir,
+        seedRoots,
+        versions: opts.versions,
+        markers: opts.markers,
+        record,
+        moduleCode: deliveries.code,
+        moduleSeeds: deliveries.seeds,
+        moduleSeedDirs: deliveries.seedDirs,
+        rosterSeeds,
+        rosterSeedDirs,
+    };
+    const removable = removalSet(targetDir, moduleName);
+    const keptImports = importedByKept(targetDir, removable);
+    const paths = removable.filter((p) => !keptImports.has(p));
+    const edited = paths.filter((p) => isEdited(layers, targetDir, p));
+    if (edited.length > 0 && opts.force !== true) {
+        throw new RemoveModuleRefusedError([
+            `${edited.length} file(s) in ${moduleName}'s removal set are this site's own — edited, or never delivered by the template or a module bundle. Nothing was removed. Pass --force to delete them too:`,
+            ...edited.map((p) => `  ${p}`),
+        ].join("\n"));
+    }
+    // ── Delete, then prune the directories the deletions emptied ────────────
+    for (const p of paths)
+        rmSync(join(targetDir, ...p.split("/")));
+    if (moduleName === "marketing") {
+        pruneEmpty(join(targetDir, ...ROUTE_ROOT.split("/")), false);
+        pruneEmpty(join(targetDir, "content"), false);
+    }
+    else {
+        for (const p of paths) {
+            let dir = dirname(join(targetDir, ...p.split("/")));
+            while (dir !== targetDir && isDir(dir) && readdirSync(dir).length === 0) {
+                rmdirSync(dir);
+                dir = dirname(dir);
+            }
+        }
+    }
+    // ── Retire: the record row, kept or added (D1) ──────────────────────────
+    const retired = [];
+    if (record !== undefined) {
+        const files = { ...record.files };
+        for (const p of paths) {
+            if (!isRecordable(p))
+                continue;
+            if (files[p] !== undefined) {
+                retired.push(p);
+                continue;
+            }
+            const copy = templateCopy(layers, p);
+            if (copy === undefined)
+                continue; // nothing would ever write it back
+            files[p] = { sha256: sha256Hex(copy), version: opts.version };
+            retired.push(p);
+        }
+        writeFileSync(recordPath, serializeTemplateRecord({ schema: 1, projectName: record.projectName, files }));
+    }
+    // ── The module set, the surfaces, architecture.yaml ─────────────────────
+    const modules = normalizeModules(current.modules.filter((m) => m !== moduleName));
+    const dropSurfaces = new Set(moduleName === "marketing" ? [] : MODULE_SURFACES[moduleName] ?? []);
+    const kept = moduleName === "marketing"
+        ? current.surfaces.filter((s) => HUB_KEPT_SURFACES.includes(s))
+        : current.surfaces.filter((s) => !dropSurfaces.has(s));
+    const surfaces = resolveSurfaces(modules, kept);
+    writeFileSync(archPath, deriveArchitecture(modules, surfaces));
+    // ── The roster of record (.ailk-site-manifest.json) — first: the flags read it ─────────────────────
+    const roster = {
+        state: "none",
+        dropped: [],
+        path: siteRoster?.path ?? SITE_ROSTER_PATH,
+    };
+    if (siteRoster !== undefined) {
+        // A marketing row is dropped when its route's first segment is no
+        // longer a route directory: the kept groups' children (`sign-in`,
+        // `account`, `leads`, …) and the kept legal dirs survive, `/` and every
+        // public page go. A docs-blog row is the module's own contribution.
+        const keptSegments = new Set();
+        for (const dir of HUB_KEPT_ROUTE_DIRS) {
+            const abs = join(targetDir, ...ROUTE_ROOT.split("/"), dir);
+            if (!isDir(abs))
+                continue;
+            if (dir.startsWith("(")) {
+                for (const entry of readdirSync(abs, { withFileTypes: true })) {
+                    if (entry.isDirectory())
+                        keptSegments.add(entry.name);
+                }
+            }
+            else {
+                keptSegments.add(dir);
+            }
+        }
+        const dropRoutes = moduleName === "marketing"
+            ? (route) => !keptSegments.has(route.split("/")[1] ?? "")
+            : (route) => (MODULE_SLICES[moduleName].pageContributions ?? []).some((c) => c.route === route);
+        let text = siteRoster.text;
+        const keptRows = siteRoster.rows.filter((row) => {
+            const route = String(row.value["route"]);
+            const drop = dropRoutes(route);
+            if (drop)
+                roster.dropped.push(route);
+            return !drop;
+        });
+        if (roster.dropped.length > 0) {
+            // Rebuild the rows array from the kept rows' verbatim text, with the
+            // separator the file already uses between its first two rows.
+            const first = siteRoster.rows[0];
+            const second = siteRoster.rows[1];
+            let sep = ",\n    ";
+            if (first !== undefined && second !== undefined) {
+                const a = text.indexOf(first.text, siteRoster.open);
+                const b = text.indexOf(second.text, a + first.text.length);
+                if (a !== -1 && b !== -1)
+                    sep = text.slice(a + first.text.length, b);
+            }
+            const body = keptRows.length === 0
+                ? ""
+                : `${siteRoster.lead}${keptRows.map((r) => r.text).join(sep)}${siteRoster.trail}`;
+            text = `${text.slice(0, siteRoster.open + 1)}${body}${text.slice(siteRoster.close)}`;
+        }
+        const next = withModules(text, modules);
+        if (next !== siteRoster.text) {
+            writeFileSync(join(targetDir, siteRoster.path), next);
+            roster.state = "trimmed";
+        }
+        else {
+            roster.state = "unchanged";
+        }
+    }
+    // ── The generated files that follow the module set ──────────────────────
+    const generated = [PAID_SECTIONS_PATH, MODULE_FLAGS_PATH, PAID_MCP_TOOLS_PATH].map((path) => {
+        const abs = join(targetDir, path);
+        return { path, abs, before: existsSync(abs) ? readFileSync(abs, "utf8") : undefined };
+    });
+    writePaidSections(targetDir);
+    const report = [];
+    for (const { path, abs, before } of generated) {
+        if (existsSync(abs) && readFileSync(abs, "utf8") !== before) {
+            report.push({ path, action: "written" });
+        }
+    }
+    const navRow = syncNavConfig(targetDir, current.surfaces, surfaces, moduleName === "marketing" ? { publicPages: false } : {});
+    if (navRow !== undefined)
+        report.push(navRow);
+    // ── Config patches a module leaves behind (D7) ──────────────────────────
+    const review = [];
+    for (const p of MODULE_SLICES[moduleName].patches ?? []) {
+        const ops = p.ops.map((op) => op.op).join(", ");
+        review.push({
+            path: p.target,
+            reason: `${moduleName}'s ${ops} patch is left in place — the file still builds with it; reverse it by hand if you want the module's dependencies and config gone`,
+        });
+    }
+    return {
+        targetDir,
+        moduleName,
+        modules,
+        removed: paths,
+        retired: retired.sort(),
+        forced: opts.force === true ? edited : [],
+        keptImports: [...keptImports].map(([path, importedBy]) => ({ path, importedBy })).sort((a, b) => a.path.localeCompare(b.path)),
+        review,
+        report,
+        roster,
+    };
+}
+// ── The CLI surface ──────────────────────────────────────────────────────────
+/** The report `remove-module` prints. */
+export function formatRemoveModuleReport(result) {
+    const lines = [`[create-ailk] remove-module ${result.moduleName} → ${result.targetDir}`];
+    if (result.removed.length === 0) {
+        lines.push(`Nothing to remove — the site carries none of ${result.moduleName}'s pages.`);
+    }
+    else {
+        lines.push(`Removed (${result.removed.length}):`);
+        lines.push(...result.removed.map((p) => `  ${p}`));
+    }
+    if (result.forced.length > 0) {
+        lines.push(`Removed under --force, the site's own (${result.forced.length}):`);
+        lines.push(...result.forced.map((p) => `  ${p}`));
+    }
+    if (result.retired.length > 0) {
+        lines.push(`Retired in ${TEMPLATE_RECORD_PATH} (${result.retired.length}): \`create-ailk update\` keeps these deleted.`);
+    }
+    for (const row of result.report) {
+        if (row.action === "written")
+            lines.push(`Regenerated: ${row.path}`);
+        else if (row.action === "skipped") {
+            lines.push(`Needs manual review — the site has edited ${row.path}; the regenerated version would be:`);
+            lines.push(...row.wanted.split("\n").map((l) => `      ${l}`));
+        }
+    }
+    if (result.keptImports.length > 0) {
+        lines.push(`Kept — a kept file imports them (${result.keptImports.length}):`);
+        for (const { path, importedBy } of result.keptImports)
+            lines.push(`  ${path} ← ${importedBy}`);
+    }
+    if (result.review.length > 0) {
+        lines.push(`Left in place (${result.review.length}):`);
+        for (const { path, reason } of result.review)
+            lines.push(`  ${path} — ${reason}`);
+    }
+    lines.push(`architecture.yaml modules: ${result.modules.length > 0 ? result.modules.join(", ") : "(none)"}`);
+    if (result.roster.state === "none") {
+        lines.push(`Page roster: none. This site has no ${SITE_ROSTER_PATH}.`);
+    }
+    else if (result.roster.state === "trimmed") {
+        lines.push(`Page roster: dropped ${result.roster.dropped.length} row(s) from ${result.roster.path}: ${result.roster.dropped.join(", ")}`);
+    }
+    else {
+        lines.push(`Page roster: ${result.roster.path} unchanged`);
+    }
+    return lines.join("\n") + "\n";
+}
+export const REMOVE_MODULE_HELP = `create-ailk remove-module — take a module's public pages off an existing site.
+
+Usage:
+  create-ailk remove-module <module> [<target-dir>] [--force]
+
+Arguments:
+  <module>                 marketing or docs-blog. Nothing else can be removed.
+  <target-dir>             An already-scaffolded repo (contains
+                           architecture.yaml). Defaults to the current dir.
+
+Options:
+  --force                  Also delete files the site has edited or authored
+                           inside the module's pages. Without it, such files
+                           are listed and nothing is removed.
+  --help, -h               Print this message.
+
+Deletes the module's route directories and seed content, drops the module
+from .ailk-site-manifest.json and architecture.yaml, and records every removed
+app file as retired in .ailk-template-files.json, so create-ailk update and
+sync-routes never bring it back. A site without marketing redirects / to
+/account, serves robots.txt disallowing everything, sends noindex on every page
+and answers 404 at sitemap.xml and llms.txt. Removing marketing while docs-blog
+is installed is refused: remove docs-blog first.
+`;
+/** Parse the argv AFTER the `remove-module` word, the `parseAddModuleArgs` shape. */
+export function parseRemoveModuleArgs(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        strict: true,
+        allowPositionals: true,
+        options: {
+            help: { type: "boolean", default: false, short: "h" },
+            force: { type: "boolean", default: false },
+        },
+    });
+    const help = parsed.values.help === true;
+    const force = parsed.values.force === true;
+    const [raw, target, ...rest] = parsed.positionals;
+    if (rest.length > 0) {
+        throw new ParseError(`expected a module and at most one target directory, got ${parsed.positionals.length} arguments`);
+    }
+    if (raw === undefined) {
+        if (help)
+            return { module: undefined, target: undefined, force, help };
+        throw new ParseError("remove-module needs a module name, e.g. `create-ailk remove-module marketing`");
+    }
+    const modules = parseModules(raw);
+    if (modules.length !== 1) {
+        throw new ParseError(`remove-module takes exactly one module, got "${raw}" — run it once per module`);
+    }
+    return { module: modules[0], target, force, help };
+}

package/dist/seed-flows.d.ts

@@ -52,7 +52,7 @@ export interface SeedFlowsResult {
 /** The whole report, one line per row — what `seedFlows` printed as it went. */
 export declare function formatSeedFlowsReport(result: SeedFlowsResult): string;
 export declare function seedFlows(opts: SeedFlowsOptions): Promise<SeedFlowsResult>;
-export declare const SPOKE_FLOWS_README = "# flows/\n\nEach file here is one **declared flow**: `flows/<slug>.json` holds one flow\nconfig, exactly as the hub stores it. This repo owns these configs \u2014 the hub\nruns them for this site.\n\n## What a spoke may declare\n\nA spoke key may seed only what this site's own flow pages show:\n`slug`, `defaultLocale`, `steps`, `thankYou` and `flags`. Anything the\nhub acts on outside these pages \u2014 emails, deliverables, pricing, registers,\nlistings \u2014 is refused (`field_not_seedable`). A flow that needs one of those\nis authored in the hub's Admin instead.\n\nThe file name must be the config's `slug` plus `.json`.\n\n## Seeding them into the hub\n\nRun this as part of each rollout, from the site's root, with the spoke key\nyour hub issued set as `AILK_SPOKE_KEY` in the environment (a shell or CI\nsecret \u2014 never a file in this repo):\n\n    npx create-ailk seed-flows .\n\nThe hub origin comes from `--hub-url`, else `AILK_API_URL`, else the\n`AILK_API_URL=` line of `apps/web/.env.local`. The key is read from the\nenvironment only. Each flow answers `created`, `updated` or `unchanged`,\nso running it again is safe. `--dry-run` checks the files and sends nothing.\n\nThe hub's operator must first turn seeding on (`AILK_SPOKE_FLOW_SEED=true`\non the hub). Until it is on and this command has run, links to these flows\n(`/flows/<slug>`) reach no flow.\n\n## The starter's placeholder flows\n\nThe `signal-collectors` module ships two declared flows here:\n`flows/diagnostic.json` (an email step, then two questions) and\n`flows/join-waitlist.json` (an email and an optional name). Every visible\nstring in both is a `{brace}` placeholder: replace each one with your own\ncopy. Both go live on the hub with the first seed, so each line this command\nprints for them says they still carry placeholder copy.\n\nA flow is reached at `/flows/<slug>`. To give one its own page pair, run:\n\n    npx create-ailk add-route magnet --path /diagnostic --flow diagnostic\n    npx create-ailk add-route magnet --path /waitlist --flow join-waitlist\n\nA job application comes with the `careers` surface. Contact, newsletter and\njob application are the hub's own standard magnets: the hub seeds them in\nevery workspace and refuses a spoke's copy of each, so they need no file\nhere. If the hub's Admin already owns a magnet under one of these two slugs,\nthe hub refuses the seed (`slug_owned`); rename the file and its `slug`.\n\n## Who owns what\n\nThe next seed that differs overwrites the hub's copy of a flow's config, so\nedit flows here, not in the Admin. A flow's status (live or draft) is the\nhub's: switching a seeded flow to draft in the Admin keeps it draft through\nevery later seed. Removing a file here does not delete the hub's flow. If\nthe Admin adds a block only it can author (an email, a deliverable, an\noffer), the hub refuses the next seed of that flow (`slug_owned`) rather\nthan delete the block.\n";
+export declare const SPOKE_FLOWS_README = "# flows/\n\nEach file here is one **declared flow**: `flows/<slug>.json` holds one flow\nconfig, exactly as the hub stores it. This repo owns these configs \u2014 the hub\nruns them for this site.\n\n## What a spoke may declare\n\nA spoke key may seed only what this site's own flow pages show:\n`slug`, `defaultLocale`, `steps`, `thankYou` and `flags`. Anything the\nhub acts on outside these pages \u2014 emails, deliverables, pricing, registers,\nlistings \u2014 is refused (`field_not_seedable`). A flow that needs one of those\nis authored in the hub's Admin instead.\n\nThe file name must be the config's `slug` plus `.json`.\n\n## Seeding them into the hub\n\nRun this as part of each rollout, from the site's root, with the spoke key\nyour hub issued set as `AILK_SPOKE_KEY` in the environment (a shell or CI\nsecret \u2014 never a file in this repo):\n\n    npx create-ailk seed-flows . --hub-url <the hub's origin>\n\nThe hub origin comes from `--hub-url`, else `AILK_API_URL`; the\n`AILK_API_URL=` line of `apps/web/.env.local` is read for `--dry-run`\nonly, and a send whose origin only that file names is refused. The key is\nread from the environment only. Each flow answers `created`, `updated` or `unchanged`,\nso running it again is safe. `--dry-run` checks the files and sends nothing.\n\nThe hub's operator must first turn seeding on (`AILK_SPOKE_FLOW_SEED=true`\non the hub). Until it is on and this command has run, links to these flows\n(`/flows/<slug>`) reach no flow.\n\n## The starter's placeholder flows\n\nThe `signal-collectors` module ships two declared flows here:\n`flows/diagnostic.json` (an email step, then two questions) and\n`flows/join-waitlist.json` (an email and an optional name). Every visible\nstring in both is a `{brace}` placeholder: replace each one with your own\ncopy. Both go live on the hub with the first seed, so each line this command\nprints for them says they still carry placeholder copy.\n\nA flow is reached at `/flows/<slug>`. To give one its own page pair, run:\n\n    npx create-ailk add-route magnet --path /diagnostic --flow diagnostic\n    npx create-ailk add-route magnet --path /waitlist --flow join-waitlist\n\nA job application comes with the `careers` surface. Contact, newsletter and\njob application are the hub's own standard magnets: the hub seeds them in\nevery workspace and refuses a spoke's copy of each, so they need no file\nhere. If the hub's Admin already owns a magnet under one of these two slugs,\nthe hub refuses the seed (`slug_owned`); rename the file and its `slug`.\n\n## Who owns what\n\nThe next seed that differs overwrites the hub's copy of a flow's config, so\nedit flows here, not in the Admin. A flow's status (live or draft) is the\nhub's: switching a seeded flow to draft in the Admin keeps it draft through\nevery later seed. Removing a file here does not delete the hub's flow. If\nthe Admin adds a block only it can author (an email, a deliverable, an\noffer), the hub refuses the next seed of that flow (`slug_owned`) rather\nthan delete the block.\n";
 /**
  * Write `SPOKE_FLOWS_README` to `<targetDir>/flows/README.md` unless that
  * file exists. Returns whether it wrote.
@@ -64,5 +64,5 @@ export interface SeedFlowsArgs {
     dryRun: boolean;
     help: boolean;
 }
-export declare const SEED_FLOWS_HELP = "create-ailk seed-flows \u2014 send a spoke's declared flows to its hub.\n\nUsage:\n  AILK_SPOKE_KEY=<key> create-ailk seed-flows [<dir>] [--hub-url <origin>] [--dry-run]\n\nArguments:\n  <dir>                The spoke site. Defaults to the current dir.\n\nOptions:\n  --hub-url <origin>   The hub's origin. Else AILK_API_URL, else the\n                       AILK_API_URL= line of apps/web/.env.local. https:\n                       only (http: on localhost or 127.0.0.1).\n  --dry-run            Check every flows/*.json and print what would be sent.\n                       Sends nothing and reads no key.\n  -h, --help           Show this help.\n\nEach flows/<slug>.json is sent to PUT <hub>/v1/flows/<slug>/definition with\nthe spoke key, which is read from AILK_SPOKE_KEY only. The hub must have\nAILK_SPOKE_FLOW_SEED=true. Exit 0 when every flow was accepted, 1 when any\nfailed, 2 on a refusal (nothing is sent).\n";
+export declare const SEED_FLOWS_HELP = "create-ailk seed-flows \u2014 send a spoke's declared flows to its hub.\n\nUsage:\n  AILK_SPOKE_KEY=<key> create-ailk seed-flows [<dir>] [--hub-url <origin>] [--dry-run]\n\nArguments:\n  <dir>                The spoke site. Defaults to the current dir.\n\nOptions:\n  --hub-url <origin>   The hub's origin. Else AILK_API_URL. The\n                       AILK_API_URL= line of apps/web/.env.local is read\n                       for --dry-run only. https: only (http: on\n                       localhost or 127.0.0.1).\n  --dry-run            Check every flows/*.json and print what would be sent.\n                       Sends nothing and reads no key.\n  -h, --help           Show this help.\n\nEach flows/<slug>.json is sent to PUT <hub>/v1/flows/<slug>/definition with\nthe spoke key, which is read from AILK_SPOKE_KEY only. The hub must have\nAILK_SPOKE_FLOW_SEED=true. Exit 0 when every flow was accepted, 1 when any\nfailed, 2 on a refusal (nothing is sent).\n";
 export declare function parseSeedFlowsArgs(argv: string[]): SeedFlowsArgs;