create-ailk 0.27.0 → 0.28.1

package/README.md

@@ -60,10 +60,20 @@ pnpm create ailk@latest my-site --shape organization-service --license <key>
 `--design minimalism` picks the other look and needs a Pro or Pro Plus key;
 `standard` (the default) needs none of its own (the run itself still needs a
 key while Free is held, above). `--template <alias>` scaffolds one of the
-three named aliases (`marketing-site-free`, `marketing-site`, `saas-product`) —
-each fixes a shape, a design and its own module list — and cannot be combined
-with `--shape` or `--design`; `marketing-site-free` with no key is refused the
-same way while Free is held.
+four named aliases (`marketing-site-free`, `marketing-site`, `saas-product`,
+`hub`) — each fixes a shape, a design and its own module list — and cannot be
+combined with `--shape` or `--design`; `marketing-site-free` with no key is
+refused the same way while Free is held.
+
+`hub` is the starter for a hub (#10040): the `organization-service` shape with
+every public row dropped and no module in its own list, so the scaffold is the
+sign-in pages, the account area, `/privacy`, `/terms` and `/working-agreement`,
+the API and the MCP server — the same tree `remove-module marketing` leaves —
+and the Admin and the rest ride the key's `--modules`:
+
+```bash
+pnpm create ailk@latest my-hub --template hub --modules multi-tenant --license <key>
+```
 
 ### Add a purchased module to an existing site
 
@@ -110,6 +120,58 @@ result of the roster check (`Page roster check: clean`). Running it again
 changes nothing and reports nothing to add.
 Run `pnpm install` afterwards.
 
+### Remove a module from an existing site
+
+`remove-module` is the inverse of `add-module` for the modules whose
+pages are public: `marketing` and `docs-blog` (#10040). A hub — the site
+every spoke of an organization signs in through — needs sign-in, the account
+area, the API and the Admin, and no second copy of the public site:
+
+```bash
+# in an already-scaffolded repo (default target: cwd)
+create-ailk remove-module marketing
+# or point at the repo explicitly, and delete the site's own edits too
+create-ailk remove-module marketing ./my-hub --force
+```
+
+It deletes the module's route directories under `apps/web/app/[locale]/` —
+everything but the `(auth)` and `(authed)` groups and the `/privacy`,
+`/terms` and `/working-agreement` pages the sign-up form links — and the
+seed content under `content/<locale>/` except those three pages' seeds; for
+`docs-blog`, the module's own files and sample content. Then it:
+
+- records every removed app file as **retired** in `.ailk-template-files.json`
+  (its row stays, with the template's hash), so `create-ailk update` reads it
+  as deleted locally and never writes it back, even across a version bump;
+  `sync-routes` and `add-module` stop copying the public tree on a site whose
+  `.ailk-site-manifest.json` lists no `marketing`;
+- keeps any file in a removed directory that a kept file imports — the
+  locale layout reads `contact/site-contact-lines.ts`, and `lib/in-page-magnet.ts`
+  the contact form's action — with its own imports, listed under "Kept — a
+  kept file imports them" with the importer; the directory stays with no
+  page, so its route still 404s;
+- drops the module from `.ailk-site-manifest.json` (its `modules` and the
+  roster rows) and from `architecture.yaml`'s `# Modules:` header, keeping
+  the web app's import permissions;
+- regenerates the module flags, the paid-sections registry and — unless you
+  have edited it — the nav, which links nothing on a site with no public page.
+
+A file the site has edited, or a page the site authored inside a removed
+directory, stops the run before anything is written and is listed; `--force`
+removes those too. Removing `marketing` while `docs-blog` is installed is
+refused — remove `docs-blog` first. A `docs-blog` removal leaves the bundle's
+`package.json`, `next.config.mjs` and `jest.config.cjs` patches in place
+(listed under "Left in place"), so the site still builds; reverse them by
+hand if you want the module's dependencies gone.
+
+A site without `marketing` redirects `/` to `/account` (signed out, on to
+sign-in), serves `robots.txt` disallowing every path, sends
+`X-Robots-Tag: noindex` on every response, and answers 404 at
+`/sitemap.xml` and `/llms.txt`; a site that keeps `marketing` or `docs-blog`
+is byte-identical to today. The route code stays and reads the module list
+(`apps/web/lib/modules.generated.ts`), so nothing needs restoring if a module
+comes back.
+
 ### Apply a design to an existing site
 
 A site that already exists can wear a different design with one command. Name
@@ -362,11 +424,26 @@ it; the merge itself still never loses content.
 never a shell. Fetching an old template version (when it is not the running
 package's own) reads the public npm registry at
 `https://registry.npmjs.org`, overridable with `AILK_NPM_REGISTRY_URL` for a
-mirror. `update` never touches content, env files, `.claude/`, lockfiles or
-any `package.json` — those stay `add-module`'s and the consumer version
-bump's job. Commit before running `update`, and review the diff after: a
+mirror. `update` never touches content, except to give an mdx-body page
+with no `# ` heading its title and description (below), nor env files,
+`.claude/`, lockfiles or any `package.json` — those stay `add-module`'s and
+the consumer version bump's job. Commit before running `update`, and review the diff after: a
 clean merge is still worth reading.
 
+**Page headings (#7495).** A page your `apps/web` renders in
+`bodyMode: "mdx-body"` takes its `<h1>` and intro from its own body: the
+template prints neither frontmatter `title` nor `description` on it. So every
+`update` run, after the template files, gives each such page under
+`content/<locale>/<Type>/` whose body has no `# ` heading its `title` as
+`# <title>` and its `description` as the paragraph under it, inserted at the
+top of the body (after any leading `import`/`export` lines), and lists it
+under **Page heading added**. Nothing else in the file changes. A page with
+one `# ` heading is left exactly as it is; a page with several, or one whose
+`title` or `description` is written in a form `update` does not read (a
+folded `>` block, say), is listed under **Needs review** for you to fix.
+Which pages are mdx-body is read from your own `apps/web/app` routes, and the
+step runs again harmlessly on every update.
+
 ### Adopting an existing site
 
 A site that create-ailk did not scaffold, or that was scaffolded before

package/dist/add-module-core.js

@@ -35,7 +35,8 @@ export function readArchitectureHeader(archYaml) {
     }
     let modules;
     try {
-        modules = normalizeModules(modulesLine.split(","));
+        // `none` is the empty set `deriveArchitecture` writes (#10040).
+        modules = modulesLine.trim() === "none" ? [] : normalizeModules(modulesLine.split(","));
     }
     catch (err) {
         throw new AddModuleRefusedError(`architecture.yaml's \`# Modules:\` header is not a module list: ${err.message}`);

package/dist/add-module.d.ts

@@ -3,6 +3,7 @@ import { type InstallReportRow } from "./lib/extract-module-bundle.js";
 import { type ModulePatch } from "./module-architecture.js";
 import { type ModuleName } from "./parse-args.js";
 import type { MarkerMap, WorkspaceVersionMap } from "./substitute.js";
+import { type RenderNavConfigOptions } from "./surfaces.js";
 import { type SyncRoutesResult } from "./sync-routes.js";
 import { type Topology } from "./topology.js";
 /**
@@ -97,7 +98,7 @@ export declare function isUneditedNav(existing: string, before: string[]): boole
  * (`isUneditedNav`). An edited nav is the customer's file: left as-is and
  * reported `skipped` with the change, like any other.
  */
-export declare function syncNavConfig(targetAbs: string, before: string[], after: string[]): InstallReportRow | undefined;
+export declare function syncNavConfig(targetAbs: string, before: string[], after: string[], renderOptions?: Omit<RenderNavConfigOptions, "serviceSlugs">): InstallReportRow | undefined;
 /** The report `add-module` prints. */
 export declare function formatAddModuleReport(result: AddModuleResult, moduleName: string): string;
 export interface AddModuleArgs {

package/dist/add-module.js

@@ -34,13 +34,14 @@ import { LEGACY_NAV_RENDERERS } from "./legacy-nav-renderers.js";
 import { writeAuthSecretFile } from "./lib/auth-secret-file.js";
 import { appendEnvRows } from "./lib/declared-env.js";
 import { diffTwoStrings, extractModuleBundle, } from "./lib/extract-module-bundle.js";
+import { publicTreeRemoved } from "./lib/site-modules.js";
 import { 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 { writeSpokeFlowsReadme } from "./seed-flows.js";
 import { SITE_ROSTER_PATH, moduleRosterRows, planRosterAppend, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
 import { spokeCheckoutSite, spokeEnvRowOptions, writeSpokeCheckoutSlice, } from "./spoke-checkout.js";
-import { MODULE_SURFACES, NAV_CONFIG_PATH, isUnservedSurfaceContent, readNavConfigStamp, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
+import { MODULE_SURFACES, NAV_CONFIG_PATH, isRemovedPublicRoutePath, isUnservedSurfaceContent, readNavConfigStamp, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
 import { syncRoutes } from "./sync-routes.js";
 import { TopologyError, isSpokeExcluded, readSiteTopology, readSpokeShape, spokeDestination, spokeModuleRefusal, } from "./topology.js";
 /**
@@ -159,8 +160,12 @@ export async function applyModuleToScaffold(opts) {
         // writes a seed under a gateable surface this site's own
         // `architecture.yaml` header (resolved above, into `surfaces`) does
         // not enable.
+        // #10040 D10 — a site that dropped `marketing` carries no public route
+        // tree, so a bundle's file inside one (commerce's dev/purchase launcher,
+        // a flow checkout action) is not written either.
         skip: (destination) => (spoke !== undefined && isSpokeExcluded(destination, spoke)) ||
-            isUnservedSurfaceContent(destination, surfaces),
+            isUnservedSurfaceContent(destination, surfaces) ||
+            (publicTreeRemoved(targetAbs) && isRemovedPublicRoutePath(destination)),
         ...(spoke !== undefined
             ? {
                 // #7876 D10 — a module flow file lands in flows/ as declared data.
@@ -313,7 +318,7 @@ export function isUneditedNav(existing, before) {
  * (`isUneditedNav`). An edited nav is the customer's file: left as-is and
  * reported `skipped` with the change, like any other.
  */
-export function syncNavConfig(targetAbs, before, after) {
+export function syncNavConfig(targetAbs, before, after, renderOptions = {}) {
     const navPath = join(targetAbs, NAV_CONFIG_PATH);
     // #6878 D6 — a finished site already has `content/en/Service` (it exists
     // on ANY site that ever enabled the `services` surface), so read the
@@ -324,7 +329,7 @@ export function syncNavConfig(targetAbs, before, after) {
             .filter((f) => f.endsWith(".mdx"))
             .map((f) => f.slice(0, -".mdx".length))
         : [];
-    const wanted = renderNavConfig(after, { serviceSlugs });
+    const wanted = renderNavConfig(after, { ...renderOptions, serviceSlugs });
     const existing = existsSync(navPath)
         ? readFileSync(navPath, "utf8")
         : undefined;

package/dist/add-route.js

@@ -19,9 +19,12 @@
  *     never over a file the site already has.
  *
  * The result is the site a fresh scaffold with `--surfaces <route>` would
- * have been. That scaffold adds no row to `.ailk-site-manifest.json` for a
- * surface (the roster names only the template's own pages), so neither does
- * this. A route the site already declares is a no-op: a second run changes
+ * have been, with one exception: a surface with generated seeds
+ * (`templates`, #10051 D10) gets them only from `add-route`. A scaffold built
+ * with `--surfaces templates` has the two routes and no seeds, so
+ * `/templates` answers 404 until a hub seed is written. That scaffold adds
+ * no row to `.ailk-site-manifest.json` for a surface (the roster names only
+ * the template's own pages), so neither does this. A route the site already declares is a no-op: a second run changes
  * nothing, even where the site has since deleted a seed.
  *
  * `create-ailk add-route magnet --path <path> --flow <slug>` (#8840 D12) is
@@ -46,6 +49,7 @@ import { substituteMarkers } from "./substitute.js";
 import { GATEABLE_SURFACES, MODULE_SURFACES, parseSurfaces, resolveSurfaces, } from "./surfaces.js";
 import { syncRoutes } from "./sync-routes.js";
 import { BASE_LAYER_DIR } from "./template-manifest.js";
+import { templatePageSeeds } from "./template-pages.js";
 import { TopologyError, readSiteTopology } from "./topology.js";
 /** A refusal the CLI exits 2 on, thrown before anything is written. */
 export class AddRouteRefusedError extends Error {
@@ -115,6 +119,7 @@ export function addRouteToScaffold(opts) {
         forceSurfaces: [route],
     });
     const report = seedSurfaceContent(targetAbs, route, opts);
+    seedGeneratedContent(targetAbs, route, report);
     const navRow = syncNavConfig(targetAbs, current.surfaces, surfaces);
     if (navRow !== undefined)
         report.push(navRow);
@@ -183,25 +188,47 @@ function seedSurfaceContent(targetAbs, route, opts) {
         const wanted = isText
             ? Buffer.from(substituteMarkers(readFileSync(src, "utf8"), opts.markers))
             : readFileSync(src);
-        const dest = join(targetAbs, path);
-        if (existsSync(dest)) {
-            const existing = readFileSync(dest);
-            if (existing.equals(wanted))
-                continue;
-            const encoding = isText ? "utf8" : "latin1";
-            report.push({
-                path,
-                action: "skipped",
-                wanted: diffTwoStrings(path, existing.toString(encoding), wanted.toString(encoding), isText),
-            });
-            continue;
-        }
-        mkdirSync(dirname(dest), { recursive: true });
-        writeFileSync(dest, wanted);
-        report.push({ path, action: "written" });
+        writeSeed(targetAbs, path, wanted, isText, report);
     }
     return report;
 }
+/**
+ * Write one seed file unless the site already has it. Identical bytes are
+ * silent; different bytes are reported `skipped` with the change the seed
+ * wanted, and the site's file is left as it is.
+ */
+function writeSeed(targetAbs, path, wanted, isText, report) {
+    const dest = join(targetAbs, path);
+    if (existsSync(dest)) {
+        const existing = readFileSync(dest);
+        if (existing.equals(wanted))
+            return;
+        const encoding = isText ? "utf8" : "latin1";
+        report.push({
+            path,
+            action: "skipped",
+            wanted: diffTwoStrings(path, existing.toString(encoding), wanted.toString(encoding), isText),
+        });
+        return;
+    }
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, wanted);
+    report.push({ path, action: "written" });
+}
+/**
+ * Seeds a surface derives from a registry rather than copies from a layer
+ * (#10051 D10): the `templates` family seeds one TemplatePage per AILK
+ * template from `TEMPLATE_MANIFESTS`, so a new template never needs a new
+ * seed file. Written after the static seeds, never over a site's file.
+ */
+const GENERATED_SEEDS = {
+    templates: () => templatePageSeeds(),
+};
+function seedGeneratedContent(targetAbs, route, report) {
+    for (const { path, text } of GENERATED_SEEDS[route]?.() ?? []) {
+        writeSeed(targetAbs, path, Buffer.from(text), true, report);
+    }
+}
 /** Every file under `root/dir`, recorded site-relative → absolute source. */
 function collectFiles(root, dir, out) {
     const abs = join(root, dir);

package/dist/body-heading.d.ts

@@ -0,0 +1,56 @@
+/** Per content type: mdx-body always, or only while `sections[]` is empty. */
+export type MdxBodyRule = Map<string, "always" | "unless-sections">;
+/**
+ * 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 declare function mdxBodyRule(appsRoot: string): MdxBodyRule;
+/** The routes' own `composed` test: mdx-body unless `sections` is a non-empty array. */
+export declare function isMdxBodyPage(type: string, frontmatter: Record<string, unknown>, rule: MdxBodyRule): boolean;
+/**
+ * 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 declare function countBodyHeadings(body: string): number;
+/**
+ * Text for an MDX body line: whitespace runs collapsed, trimmed, and every
+ * `\`, `{`, `<`, `` ` ``, `*`, `_` and `[` backslash-escaped.
+ */
+export declare function mdxText(text: string): string;
+/**
+ * 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 declare function addBodyHeading(raw: string, rule: MdxBodyRule, type: string): string | undefined;
+export interface BodyHeadingPlan {
+    writes: Array<{
+        path: string;
+        text: string;
+    }>;
+    refused: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+/** What `migrateBodyHeadings` would write, and the heading-less pages it cannot. Never throws for a page. */
+export declare function planBodyHeadings(contentDir: string, rule: MdxBodyRule): BodyHeadingPlan;
+/** Every mdx-body page whose body does not have exactly one `# ` heading. */
+export declare function headingViolations(contentDir: string, rule: MdxBodyRule): Array<{
+    path: string;
+    count: number;
+}>;
+/** Write each planned page; the paths written and the refused rows. */
+export declare function migrateBodyHeadings(contentDir: string, rule: MdxBodyRule): {
+    written: string[];
+    refused: Array<{
+        path: string;
+        reason: string;
+    }>;
+};