create-ailk 0.27.0 → 0.28.0

package/dist/template-pages.js

@@ -0,0 +1,129 @@
+/**
+ * The templates route family's generated seeds (#10051 D10) — the /templates
+ * hub seed plus one placeholder TemplatePage per AILK template, derived from
+ * `TEMPLATE_MANIFESTS` so a new template never needs a hand-written seed.
+ * `add-route templates` writes them (`GENERATED_SEEDS` in `add-route.ts`);
+ * the site then edits or deletes them like any content.
+ *
+ * A seed never invents a fact: its copy is placeholder (`placeholder: true`,
+ * renderPage's replace-before-launch label), it has no thumbnail, and its Get
+ * it action is `/contact`. Only a template whose `templateDelivery` is
+ * `"free"` gets `price: 0` — a paid template's price is the site's to set.
+ *
+ * Pure (no fs). create-ailk has no YAML dependency by design, so every
+ * frontmatter value is written as `JSON.stringify(value)` — a JSON scalar,
+ * array or object is valid YAML flow syntax (the `derive-architecture.ts`
+ * precedent).
+ */
+import { RECOGNIZED_MODULES } from "./parse-args.js";
+import { TEMPLATE_MANIFESTS, templateDelivery, } from "./template-manifest.js";
+/** What every template carries whatever its modules: the base site. */
+export const BASE_INCLUDE = {
+    title: "The base site",
+    description: "Your pages with structured data on every one, plus an API and an MCP server agents can read.",
+};
+/** One row per module, typed exhaustively so a new module fails type-check. */
+export const MODULE_INCLUDES = {
+    marketing: {
+        title: "Marketing pages",
+        description: "The pages a marketing site needs, with lead capture.",
+    },
+    "docs-blog": {
+        title: "Docs and blog",
+        description: "A documentation section and a blog, written as content files.",
+    },
+    "multi-tenant": {
+        title: "Organizations and workspaces",
+        description: "Many customers on one deployment, each with their own members.",
+    },
+    workspace: {
+        title: "Admin",
+        description: "Your own signed-in area to edit pages, manage assets and review submissions.",
+    },
+    scheduling: {
+        title: "Scheduling",
+        description: "Booking pages visitors use to schedule time with you.",
+    },
+    "signal-collectors": {
+        title: "Quizzes and reports",
+        description: "Assessments and downloadable reports that capture interested visitors.",
+    },
+    commerce: {
+        title: "Checkout",
+        description: "Take payment through your own Stripe account.",
+    },
+};
+const HUB_SEED_PATH = "content/en/TemplatesList/templates.mdx";
+/** Words a naive capitalisation would mis-case in a template name. */
+const WORD_CASING = { saas: "SaaS" };
+/** `marketing-site-free` → `Marketing Site Free`; `saas-product` → `SaaS Product`. */
+function titleCase(name) {
+    return name
+        .split("-")
+        .map((word) => WORD_CASING[word] ?? word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+}
+/** A seed file: a JSON-valued YAML frontmatter block and a placeholder body. */
+function mdx(frontmatter, body) {
+    const lines = Object.entries(frontmatter).map(([key, value]) => `${key}: ${JSON.stringify(value)}`);
+    return `---\n${lines.join("\n")}\n---\n\n${body}\n`;
+}
+function templateSeed(name, manifest) {
+    const title = titleCase(name);
+    const includes = [
+        BASE_INCLUDE,
+        ...RECOGNIZED_MODULES.filter((module) => manifest.requires.includes(module)).map((module) => MODULE_INCLUDES[module]),
+    ];
+    const free = templateDelivery(manifest) === "free";
+    return {
+        path: `content/en/TemplatePage/${name}.mdx`,
+        text: mdx({
+            type: "TemplatePage",
+            slug: name,
+            title,
+            description: `Replace with a one-sentence description of the ${title} template.`,
+            summary: `Replace with what a site built on ${title} gives a customer.`,
+            placeholder: true,
+            template: name,
+            categories: [...manifest.categories],
+            includes,
+            demoUrl: `https://${name}.salessmyth.com`,
+            getItUrl: "/contact",
+            ...(free && { price: 0, priceCurrency: "USD" }),
+        }, `{/* Placeholder: /templates/${name} renders its hero and "What's included" from the frontmatter above. Replace the copy, add a thumbnail and set getItUrl to your buy link before launch. */}`),
+    };
+}
+/**
+ * The hub seed, then one TemplatePage seed per manifest, sorted by name.
+ * `manifests` defaults to the frozen registry; a test may pass its own.
+ */
+export function templatePageSeeds(manifests = TEMPLATE_MANIFESTS) {
+    const description = "Replace with a one-sentence description of the templates you sell.";
+    const hub = {
+        path: HUB_SEED_PATH,
+        text: mdx({
+            type: "TemplatesList",
+            slug: "templates",
+            title: "Templates",
+            description,
+            placeholder: true,
+            // A tight hero keeps the first cards — the hub's actions — inside
+            // the first screen (design review round 1, B1).
+            sections: [
+                {
+                    id: "templates-hero",
+                    type: "hero",
+                    data: {
+                        headline: "Templates",
+                        subheadline: description,
+                        gapBelow: "tight",
+                    },
+                },
+            ],
+        }, "{/* Placeholder: /templates lists every TemplatePage automatically. Replace the description before launch. */}"),
+    };
+    const pages = Object.keys(manifests)
+        .sort()
+        .map((name) => templateSeed(name, manifests[name]));
+    return [hub, ...pages];
+}

package/dist/topology.d.ts

@@ -32,7 +32,8 @@ export declare const SPOKE_EXCLUDED_MODULE_PATHS: readonly string[];
  * The `(authed)` seeds of the sign-in-through-the-hub mode (#7894 D9): the
  * whole `(authed)` group goes in the default mode; in the hub mode its account
  * area, layout and gate seam stay, and only these go — the operator surfaces,
- * the Better Auth gate and the suites that mock `auth.ts` by path.
+ * the Better Auth gate, the hub's own consent page (#9966 D2, a 404 on a
+ * spoke) and the suites that mock `auth.ts` by path.
  */
 export declare const HUB_MODE_AUTHED_SEEDS: readonly string[];
 /** The generated seam files (D5; #7874 D12). A seam is rewritten, never removed. */

package/dist/topology.js

@@ -86,11 +86,13 @@ export const SPOKE_EXCLUDED_MODULE_PATHS = [
  * The `(authed)` seeds of the sign-in-through-the-hub mode (#7894 D9): the
  * whole `(authed)` group goes in the default mode; in the hub mode its account
  * area, layout and gate seam stay, and only these go — the operator surfaces,
- * the Better Auth gate and the suites that mock `auth.ts` by path.
+ * the Better Auth gate, the hub's own consent page (#9966 D2, a 404 on a
+ * spoke) and the suites that mock `auth.ts` by path.
  */
 export const HUB_MODE_AUTHED_SEEDS = [
     "apps/web/app/[locale]/(authed)/__tests__",
     "apps/web/app/[locale]/(authed)/account/__tests__",
+    "apps/web/app/[locale]/(authed)/account/connect",
     "apps/web/app/[locale]/(authed)/admin",
     "apps/web/app/[locale]/(authed)/appointments",
     "apps/web/app/[locale]/(authed)/edit",
@@ -154,7 +156,7 @@ export function spokeRemovedRoots(opts) {
 }
 /**
  * The seeds that apply — an mcp seed is moot when `apps/mcp` itself goes; in
- * the hub sign-in mode the `(authed)` seed is replaced by eight (#7894 D9).
+ * the hub sign-in mode the `(authed)` seed is replaced by nine (#7894 D9).
  */
 function spokeSeeds(opts) {
     return modeSeeds(opts.signIn).filter((seed) => opts.mcp || !underPrefix(seed, SPOKE_MCP_ROOT));

package/dist/update.d.ts

@@ -45,6 +45,8 @@ export interface UpdateResult {
         file: string;
         tests: string[];
     }>;
+    /** The mdx-body pages under `content/` given a `# ` heading this run (#7495). */
+    headingsAdded: string[];
     backfilled?: {
         version: string;
         files: number;
@@ -57,6 +59,6 @@ export interface UpdateArgs {
     target: string | undefined;
     help: boolean;
 }
-export declare const UPDATE_HELP = "create-ailk update \u2014 bring template fixes into a site's copied app code.\n\nUsage:\n  create-ailk update [<target-dir>]\n\nArguments:\n  <target-dir>             The existing site. Defaults to the current dir.\n\nOptions:\n  --help, -h               Print this message.\n\nReads .ailk-template-files.json (written beside .ailk-site-manifest.json by\nevery template scaffold) to tell an untouched copy from an edit. An\nuntouched apps/web, apps/api or apps/mcp file, or a root tools/jest file the\napp jest configs require, whose template copy changed is overwritten. An\nedited file whose template copy also changed is three-way merged with\n`git` (git must be on PATH); a conflict leaves the file alone and is\nlisted under \"Needs review\". Every template test that imports a file\nleft under \"Needs review\" or \"Skipped\" (by a relative import) is held at the\nsite's version with it, its record entry is not advanced, and it is listed\nunder \"Held back with <file>\" \u2014 reconcile the file, then run update again to\nbring its tests forward. Every other file in the run still updates.\nA site with no record gets one on its first run, from the version its\n.ailk-site-manifest.json already records. A site scaffolded before\n@working-theory/mcp-server has its copied apps/mcp moved to the boot set:\nthe server and each module's paid MCP pack join apps/mcp/package.json, the\ncopied server files go, and apps/mcp/src/lib/paid-tools.generated.ts is\nrewritten on every run. A site scaffolded before @working-theory/api has its\ncopied apps/api moved to the boot file: the app becomes @working-theory/app-api,\nthe package and the six @working-theory/api-<module> packages join\napps/api/package.json, its bins and build:vercel delegate to the package, and\nthe copied server files go. Run `pnpm install` after either move, since the\napp's package.json gained dependencies. Commit before running, and review the\ndiff after.\n";
+export declare const UPDATE_HELP = "create-ailk update \u2014 bring template fixes into a site's copied app code.\n\nUsage:\n  create-ailk update [<target-dir>]\n\nArguments:\n  <target-dir>             The existing site. Defaults to the current dir.\n\nOptions:\n  --help, -h               Print this message.\n\nReads .ailk-template-files.json (written beside .ailk-site-manifest.json by\nevery template scaffold) to tell an untouched copy from an edit. An\nuntouched apps/web, apps/api or apps/mcp file, or a root tools/jest file the\napp jest configs require, whose template copy changed is overwritten. An\nedited file whose template copy also changed is three-way merged with\n`git` (git must be on PATH); a conflict leaves the file alone and is\nlisted under \"Needs review\". Every template test that imports a file\nleft under \"Needs review\" or \"Skipped\" (by a relative import) is held at the\nsite's version with it, its record entry is not advanced, and it is listed\nunder \"Held back with <file>\" \u2014 reconcile the file, then run update again to\nbring its tests forward. Every other file in the run still updates.\nA site with no record gets one on its first run, from the version its\n.ailk-site-manifest.json already records. A site scaffolded before\n@working-theory/mcp-server has its copied apps/mcp moved to the boot set:\nthe server and each module's paid MCP pack join apps/mcp/package.json, the\ncopied server files go, and apps/mcp/src/lib/paid-tools.generated.ts is\nrewritten on every run. A site scaffolded before @working-theory/api has its\ncopied apps/api moved to the boot file: the app becomes @working-theory/app-api,\nthe package and the six @working-theory/api-<module> packages join\napps/api/package.json, its bins and build:vercel delegate to the package, and\nthe copied server files go. Run `pnpm install` after either move, since the\napp's package.json gained dependencies. Each mdx-body page in content/ with no\n'# ' heading gets its title and description written into its body as its\nheading and intro, listed under \"Page heading added\"; a page with one heading\nis left as it is, and one with several, or one whose frontmatter it cannot\nread, is listed under \"Needs review\". Commit before running, and review the\ndiff after.\n";
 /** Parse the argv AFTER the `update` word. Strict `node:util` parseArgs, like `parseAdoptArgs`. */
 export declare function parseUpdateArgs(argv: string[]): UpdateArgs;

package/dist/update.js

@@ -27,24 +27,29 @@
  * (#9566): the record retires the copied server files and lands the boot
  * files; the app's rename, its dependencies and delegating scripts, and the
  * bundle-delivered module files are planned here. Every refusal throws
- * before the first write.
+ * before the first write. Last, every mdx-body page in the site's `content/`
+ * with no `# ` heading gets its title and description written into its body
+ * (#7495, `body-heading.ts`); a page with one or more headings is never
+ * touched, and `content/` is never recorded.
  *
  * Pure module: no `import.meta.url` — the CLI supplies `templatesDir`, the
  * `adopt.ts` / `add-route.ts` split.
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, rmdirSync, writeFileSync, } from "node:fs";
-import { dirname, join, resolve, sep } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { AddModuleRefusedError, readArchitectureHeader } from "./add-module-core.js";
+import { headingViolations, mdxBodyRule, migrateBodyHeadings } from "./body-heading.js";
 import { buildScaffoldMarkers, isExcluded, isTextFile, renderTemplateFile, templateDestination } from "./copy.js";
 import { fetchTemplateSnapshot } from "./lib/fetch-template-snapshot.js";
 import { mergeThreeWay } from "./lib/merge-three-way.js";
+import { publicTreeRemoved } from "./lib/site-modules.js";
 import { MODULE_SLICES } from "./module-architecture.js";
 import { MODULE_FLAGS_PATH, PAID_MCP_TOOLS_PATH, writeModuleFlags, writePaidMcpTools, } from "./paid-sections.js";
 import { ParseError } from "./parse-args.js";
 import { SITE_ROSTER_PATH } from "./site-roster.js";
 import { SPOKE_CHECKOUT_TEMPLATE_PATHS } from "./spoke-checkout.js";
-import { excludedRoutePaths } from "./surfaces.js";
+import { excludedRoutePaths, isRemovedPublicRoutePath } from "./surfaces.js";
 import { DATABASE_BOOT_FILES, ROOT_TOOL_FILES, TEMPLATE_RECORD_PATH, isRecordable, parseTemplateRecord, serializeTemplateRecord, sha256Hex, } from "./template-record.js";
 import { MCP_SEAM_PATH, MCP_SERVER_HUB, TopologyError, isSpokeExcluded, readSpokeShape, spokeExclusions, } from "./topology.js";
 /** A refusal the CLI exits 2 on, thrown before anything is written. */
@@ -1091,10 +1096,17 @@ export async function updateSite(opts) {
     // module object at a boot-set path goes before the writes below, and the
     // template's re-export lands there as an added file.
     const retired = new Set(apiMove?.deletes ?? []);
+    // #10040 D10 — a site that dropped `marketing` never gains a public route
+    // file from a newer template, tombstone or not.
+    const marketingRemoved = publicTreeRemoved(targetDir);
     const knownPaths = new Set([...Object.keys(record.files), ...(knownSnapshotPaths ?? [])]);
     for (const path of [...newMap.keys()].sort()) {
         if (Object.prototype.hasOwnProperty.call(record.files, path))
             continue;
+        if (marketingRemoved && isRemovedPublicRoutePath(path)) {
+            skipped.push({ path, reason: "marketing removed" });
+            continue;
+        }
         // The guard runs before the disk check, so a full-copy site's boot path
         // reads as guarded, never as "exists, not in the record" (#9569 DD8).
         if (bootFileGuarded(path)) {
@@ -1250,6 +1262,21 @@ export async function updateSite(opts) {
         writeFileSync(join(targetDir, ...WEB_PACKAGE_JSON.split("/")), webPackageJson);
         moved.updated.push(WEB_PACKAGE_JSON);
     }
+    // #7495 D6 — the page body owns its H1: give every heading-less mdx-body
+    // page its title and description, read the rule after the writes so a
+    // route this run added counts. Its rows join `review` after `heldFiles`
+    // was computed, so a content path never holds a template test back.
+    const contentDir = join(targetDir, "content");
+    const rule = mdxBodyRule(targetDir);
+    const sitePath = (abs) => relative(targetDir, abs).split(sep).join("/");
+    const headings = migrateBodyHeadings(contentDir, rule);
+    for (const { path, count } of headingViolations(contentDir, rule)) {
+        if (count > 1)
+            review.push({ path: sitePath(path), reason: `${count} '# ' headings; keep one` });
+    }
+    for (const { path, reason } of headings.refused) {
+        review.push({ path: sitePath(path), reason: `no '# ' heading added: ${reason}` });
+    }
     return {
         targetDir,
         version,
@@ -1257,6 +1284,7 @@ export async function updateSite(opts) {
         review,
         skipped,
         heldBack,
+        headingsAdded: headings.written.map(sitePath),
         ...(backfilled !== undefined ? { backfilled } : {}),
     };
 }
@@ -1272,6 +1300,7 @@ export function formatUpdateReport(result) {
         ["Added", result.added],
         ["Removed", result.removed],
         ["Already current", result.current],
+        ["Page heading added", result.headingsAdded],
     ];
     for (const [label, paths] of sections) {
         if (paths.length === 0)
@@ -1297,6 +1326,7 @@ export function formatUpdateReport(result) {
         result.added.length === 0 &&
         result.removed.length === 0 &&
         result.current.length === 0 &&
+        result.headingsAdded.length === 0 &&
         result.review.length === 0 &&
         result.skipped.length === 0;
     if (nothingHappened) {
@@ -1344,7 +1374,11 @@ copied apps/api moved to the boot file: the app becomes @working-theory/app-api,
 the package and the six @working-theory/api-<module> packages join
 apps/api/package.json, its bins and build:vercel delegate to the package, and
 the copied server files go. Run \`pnpm install\` after either move, since the
-app's package.json gained dependencies. Commit before running, and review the
+app's package.json gained dependencies. Each mdx-body page in content/ with no
+'# ' heading gets its title and description written into its body as its
+heading and intro, listed under "Page heading added"; a page with one heading
+is left as it is, and one with several, or one whose frontmatter it cannot
+read, is listed under "Needs review". Commit before running, and review the
 diff after.
 `;
 /** Parse the argv AFTER the `update` word. Strict `node:util` parseArgs, like `parseAdoptArgs`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Scaffolder for AI Launch Kit — `pnpm create ailk@latest <dir>` produces a starter repo consuming @working-theory/* from npm (per ADR 0007).",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,8 +28,8 @@
     "tar": "^7.5.21"
   },
   "devDependencies": {
-    "@working-theory/schema": "0.49.0",
-    "@working-theory/templates": "0.49.0"
+    "@working-theory/schema": "0.50.0",
+    "@working-theory/templates": "0.50.0"
   },
   "repository": {
     "type": "git",

package/release-scope.json

@@ -2,7 +2,8 @@
   "templates": {
     "marketing-site-free": "released",
     "marketing-site": "released",
-    "saas-product": "gated"
+    "saas-product": "gated",
+    "hub": "released"
   },
   "shapes": {
     "organization-product": "released",

package/site-templates/aliases/hub.TEMPLATE-MANIFEST.json

@@ -0,0 +1,115 @@
+{
+  "template": "hub",
+  "requires": [],
+  "categories": ["accounting", "legal", "real-estate"],
+  "shape": "organization-service",
+  "design": "standard",
+  "generatedHash": "7386e7f6ebcd8d291b75c265a428dec50612d25ae522cae1be611c4089a217a1",
+  "layout": {
+    "nav": "full",
+    "footer": "columns",
+    "announcementBanner": false,
+    "home": "default"
+  },
+  "theme": {
+    "corners": "square",
+    "eyebrowCase": "sentence",
+    "placeholders": "fill",
+    "checkmarks": "plain",
+    "colors": {
+      "light": {
+        "bg": "#ffffff",
+        "bgMuted": "#ffffff",
+        "surface": "#ffffff",
+        "border": "#000000",
+        "text": "#000000",
+        "textMuted": "#333333",
+        "primary": "#000000",
+        "primaryFg": "#ffffff",
+        "accent": "#000000"
+      },
+      "dark": {
+        "bg": "#000000",
+        "bgMuted": "#000000",
+        "surface": "#000000",
+        "border": "#ffffff",
+        "text": "#ffffff",
+        "textMuted": "#cccccc",
+        "primary": "#ffffff",
+        "primaryFg": "#000000",
+        "accent": "#ffffff"
+      }
+    }
+  },
+  "rows": [
+    {
+      "route": "/sign-in",
+      "kind": "route",
+      "pageType": null,
+      "schema": null,
+      "shell": "MarketingShell",
+      "chrome": "on",
+      "sections": []
+    },
+    {
+      "route": "/sign-up",
+      "kind": "route",
+      "pageType": null,
+      "schema": null,
+      "shell": "MarketingShell",
+      "chrome": "on",
+      "sections": []
+    },
+    {
+      "route": "/privacy",
+      "kind": "page",
+      "pageType": "PrivacyPage",
+      "schema": "PrivacyPage",
+      "shell": "MarketingShell",
+      "chrome": "on",
+      "sections": [
+        {
+          "type": "document-chassis",
+          "component": "DocumentChassis",
+          "options": {
+            "layout": "article"
+          }
+        }
+      ]
+    },
+    {
+      "route": "/terms",
+      "kind": "page",
+      "pageType": "TermsPage",
+      "schema": "TermsPage",
+      "shell": "MarketingShell",
+      "chrome": "on",
+      "sections": [
+        {
+          "type": "document-chassis",
+          "component": "DocumentChassis",
+          "options": {
+            "layout": "article"
+          }
+        }
+      ]
+    },
+    {
+      "route": "/working-agreement",
+      "kind": "page",
+      "pageType": "WorkingAgreementPage",
+      "schema": "WorkingAgreementPage",
+      "shell": "MarketingShell",
+      "chrome": "on",
+      "sections": [
+        {
+          "type": "document-chassis",
+          "component": "DocumentChassis",
+          "options": {
+            "layout": "article"
+          }
+        }
+      ]
+    }
+  ]
+}

package/templates/.env.example

@@ -462,8 +462,11 @@ CONTENT_ADAPTER=mdx
 # SLACK_CONNECTION_KEY=
 # SLACK_CONNECTION_KEY_PREVIOUS=
 # The Organization that owns STRIPE_SECRET_KEY (#9285): with the multi-tenant
-# module only the Organization whose id is named here sells through it; unset
-# means nobody. Without the module the single Organization owns it.
+# module selected in AILK_ENABLED_MODULES, only the Organization whose id is
+# named here sells through it; unset means nobody. That holds whether or not
+# the licence claims the module (#9968), so a downgraded deployment that still
+# selects it must set this too. Without the module the single Organization
+# owns it.
 # STRIPE_ENV_ORGANIZATION_ID=
 # HMAC-SHA256 key POST /v1/webhooks/calcom verifies the x-cal-signature-256
 # header against (#6085). Unset makes the receiver answer 503 and accept

package/templates/apps/api/.env.example

@@ -146,11 +146,15 @@ STRIPE_WEBHOOK_SECRET=whsec_xxx
 # SLACK_CONNECTION_KEY=
 # SLACK_CONNECTION_KEY_PREVIOUS=
 #
-# The Organization that owns STRIPE_SECRET_KEY (#9285). On a deployment with
-# the multi-tenant module, only the Organization whose id is named here sees
-# that key as its Stripe connection and sells its Offerings through it; unset,
-# blank or naming no Organization, nobody owns it. Without the multi-tenant
-# module the deployment's single Organization owns it and this is not read.
+# The Organization that owns STRIPE_SECRET_KEY (#9285). On a deployment whose
+# AILK_ENABLED_MODULES selects the multi-tenant module, only the Organization
+# whose id is named here sees that key as its Stripe connection and sells its
+# Offerings through it; unset, blank or naming no Organization, nobody owns it.
+# The selection decides, not the licence (#9968): a deployment that selects
+# multi-tenant must set this for any Organization to own the key, including a
+# downgraded one whose licence no longer claims the module. Without the
+# multi-tenant module selected the deployment's single Organization owns it
+# and this is not read.
 # STRIPE_ENV_ORGANIZATION_ID=
 #
 # The booking webhook receiver (#6085) — a SEPARATE credential from the