create-ailk 0.23.0 → 0.24.0

package/README.md

@@ -214,9 +214,9 @@ as-is, they never fail the check, and `--apply` never overwrites them.
 
 `--apply` only creates route directories that are absent, through the same
 copier a fresh scaffold uses (so the copied files are byte-identical to a fresh
-scaffold's). It never rewrites or deletes an existing file, never writes
-outside `apps/web/app/[locale]/`, runs no install, and a second run is a
-no-op. `--apply` exits 0 on success.
+scaffold's). It never rewrites or deletes an existing file, writes nothing
+outside `apps/web/app/[locale]/` except the local modules those routes import
+(below), runs no install, and a second run is a no-op. `--apply` exits 0 on success.
 
 **Scope.** Every core route (`about`, `contact`, `faq`, `thanks/[slug]`,
 `sign-in`) is always checked, and so is the `(authed)` route GROUP —
@@ -232,17 +232,30 @@ gated off at scaffold time is listed as skipped, not missing — its absence is
 deliberate, not drift. Add a surface with `--sync-architecture` and the
 `add-page` skill, not with `sync-routes`.
 
-**The lib-and-messages dependency contract (#5014).** Some routes import
-files OUTSIDE their own route directory — `sign-in/page.tsx` imports
-`apps/web/lib/auth-env.ts` and `lib/site-brand.tsx`; the `(authed)` group's
-`layout.tsx` imports `apps/web/auth.ts`; `(authed)/account/page.tsx` imports
-`lib/account-config.ts`, `lib/server-api.ts`, and two files from its
-`(authed)/waitlist` sibling (`components/ForbiddenState.tsx`, `format.ts`).
-Copying a route's directory alone would leave those imports dangling in an
-older consumer that never had them. `ROUTE_DEPENDENCIES` in `src/surfaces.ts`
-declares them per route; `sync-routes` copies each one `--apply` finds
-missing (never overwriting — the same rule routes themselves follow) and
-reports it in check mode under an `Also required` heading. `ROUTE_MESSAGE_NAMESPACES`
+**The local-module dependency contract (#5014, #9406).** Some routes import
+files OUTSIDE their own route directory — `purchase/success/page.tsx` imports
+`apps/web/src/lib/commerce-claim.ts`; the `(authed)` group's `layout.tsx`
+imports `apps/web/auth.ts`. Copying a route's directory alone would leave those
+imports dangling in an older consumer that never had them. So `sync-routes`
+resolves every relative import (`./`, `../`) of every file the route would
+copy, and of every helper that brings in turn, against the site first and then
+the template. `ROUTE_DEPENDENCIES` in `src/surfaces.ts` is a declared
+supplement, unioned with what the resolver finds. Each imported module has one
+of three outcomes:
+
+- **Copied** — the site lacks it and the template has it: `--apply` copies it
+  (never overwriting) and check mode lists it under `copies:` and `Also
+  required`.
+- **Left as-is** — the site has it and its copy differs from the template's:
+  it is named under `left as-is (differs from the template)` and never
+  written. The route is still copied; run your type-check afterwards.
+- **Refused** — the import resolves to no file in the site or the template,
+  only to a spoke-excluded file, or to a surface the site does not carry: the
+  route is listed under `cannot resolve:` and `--apply` does not write it, nor
+  its sub-routes, nor a route that imports from it. Its ancestor route is still
+  copied without the refused sub-tree.
+
+`ROUTE_MESSAGE_NAMESPACES`
 does the same for the i18n namespaces a route's copy needs
 (`signIn`, `account`, `waitlistDashboard.gate`) — but CHECK-ONLY: a
 consumer's `apps/web/messages/<locale>.json` already exists and may carry

package/dist/add-module.js

@@ -351,7 +351,9 @@ export function formatAddModuleReport(result, moduleName) {
     const lines = [
         `[create-ailk] add-module ${moduleName} → ${result.targetDir}`,
     ];
-    if (result.report.length === 0 && result.routes.applied.length === 0) {
+    if (result.report.length === 0 &&
+        result.routes.applied.length === 0 &&
+        result.routes.refused.length === 0) {
         lines.push(`Nothing to add — the site already carries everything ${moduleName} brings.`);
     }
     if (written.length > 0) {
@@ -387,6 +389,9 @@ export function formatAddModuleReport(result, moduleName) {
         lines.push(`Also copied ${routes.appliedDependencies.length} file(s) those routes import:`);
         lines.push(...routes.appliedDependencies.map((dep) => `  ${dep}`));
     }
+    if (routes.refused.length > 0) {
+        lines.push(`Routes not copied (${routes.refused.length}) — an import does not resolve (run create-ailk sync-routes for the paths): ${routes.refused.join(", ")}`);
+    }
     if (routes.missingMessageNamespaces.length > 0) {
         lines.push("Also required — message namespace(s) not found in apps/web/messages/en.json (add manually, not auto-merged):");
         lines.push(...routes.missingMessageNamespaces.map((ns) => `  ${ns}`));

package/dist/add-route.js

@@ -226,13 +226,16 @@ export function formatAddRouteReport(result) {
     const skipped = result.report.filter((row) => row.action === "skipped");
     const routes = result.routes ?? {
         applied: [],
+        refused: [],
         appliedDependencies: [],
         missingMessageNamespaces: [],
     };
     const lines = [
         `[create-ailk] add-route ${result.route} → ${result.targetDir}`,
     ];
-    if (result.report.length === 0 && routes.applied.length === 0) {
+    if (result.report.length === 0 &&
+        routes.applied.length === 0 &&
+        routes.refused.length === 0) {
         lines.push(`Nothing to add — the site already carries the ${result.route} route.`);
     }
     if (routes.applied.length > 0) {
@@ -243,6 +246,9 @@ export function formatAddRouteReport(result) {
         lines.push(`Also copied ${routes.appliedDependencies.length} file(s) those routes import:`);
         lines.push(...routes.appliedDependencies.map((dep) => `  ${dep}`));
     }
+    if (routes.refused.length > 0) {
+        lines.push(`Routes not copied (${routes.refused.length}) — an import does not resolve (run create-ailk sync-routes for the paths): ${routes.refused.join(", ")}`);
+    }
     if (written.length > 0) {
         lines.push(`Written (${written.length}):`);
         lines.push(...written.map((row) => `  ${row.path}`));

package/dist/derive-architecture.js

@@ -15,6 +15,8 @@
  */
 import { ARCHITECTURE_BASE, MODULE_SLICES, normalizeModules, } from "./module-architecture.js";
 import { CORE_SURFACE_PATHS, RECOGNIZED_SURFACES, resolveSurfaces, } from "./surfaces.js";
+/** The npm scope a site consumes and never forks (#9191). */
+const PACKAGE_SCOPE = "@working-theory/";
 /** A spoke's composition tiers (#7426 D8): its data and API are the hub's. */
 const SPOKE_TIERS = {
     data: "none — the hub's database",
@@ -314,6 +316,20 @@ export function deriveArchitecture(modules = ["marketing"], surfaces, options =
     for (const s of slices)
         extraForbidden.push(...(s.forbiddenPatterns ?? []));
     const forbidden = mergeForbidden([...ARCHITECTURE_BASE.forbiddenPatterns], extraForbidden).map(scoped);
+    // The upgradeable-consumer rules (#9191): the workspaces this scaffold
+    // creates and the in-scope package names it gives them. The site lint
+    // reads this block to refuse a forked, patched or pinned-off package.
+    // Every app the scaffold ships is named `@working-theory/<dir>`.
+    const upgradeableConsumer = {
+        package_scope: PACKAGE_SCOPE,
+        workspaces: spoke ? ["apps/*"] : ["apps/*", "database"],
+        scaffold_packages: [
+            ...(spoke ? [] : ["database"]),
+            ...Object.keys(apps),
+        ]
+            .map((dir) => `${PACKAGE_SCOPE}${dir}`)
+            .sort(),
+    };
     const doc = {
         version: ARCHITECTURE_BASE.version,
         ...(spoke ? { topology: "spoke" } : {}),
@@ -330,6 +346,7 @@ export function deriveArchitecture(modules = ["marketing"], surfaces, options =
         apps,
         ...(nsSlice ? { namespaces: namespacesToYaml(nsSlice) } : {}),
         forbidden_patterns: forbidden.map(forbiddenToYaml),
+        upgradeable_consumer: upgradeableConsumer,
     };
     const header = [
         "# Architecture Boundaries — AI Launch Kit site",

package/dist/lib/scaffold-render-sweep.d.ts

@@ -21,6 +21,39 @@ export declare const MAX_REDIRECTS = 5;
  * so each entry must answer exactly 404. A 200 means the gate stopped gating.
  */
 export declare const CLAIM_GATED_ROUTES: Readonly<Record<string, string>>;
+/**
+ * Routes whose answer depends on whether the site has a hub to ask (#9423),
+ * and the flow each one sells. With no API origin configured the flow read
+ * is `not-configured` and the route must answer exactly 404 — the no-hub
+ * 404 where the module that owns it is installed, Next's own 404 where it
+ * is not. With one configured it must render its own content.
+ */
+export declare const HUB_GATED_ROUTES: Readonly<Record<string, string>>;
+/**
+ * The API origin names `apps/web` reads, in step with `apiOriginConfigured()`
+ * in `apps/web/app/[locale]/flows/[slug]/magnet-page.tsx`.
+ */
+export declare const HUB_ORIGIN_ENV_NAMES: readonly ["AILK_API_URL", "NEXT_PUBLIC_AILK_API_URL", "NEXT_PUBLIC_API_URL"];
+/**
+ * Whether a served `apps/web` has an API origin: a non-empty value for one
+ * of `HUB_ORIGIN_ENV_NAMES` in the serve environment or assigned in one of
+ * the env files Next loads (`envFileTexts`).
+ */
+export declare function hubOriginConfigured(env: Readonly<Record<string, string | undefined>>, envFileTexts: string[]): boolean;
+/**
+ * A `HUB_GATED_ROUTES` entry. Hub configured: the page must render its own
+ * content (`assessPageRender`). No hub: exactly 404 with no redirect — a 200
+ * means the no-hub branch stopped running.
+ */
+export declare function assessHubGatedRoute(input: {
+    route: string;
+    hubConfigured: boolean;
+    hops: RedirectHop[];
+    status: number | null;
+    contentType: string | null;
+    html: string;
+    locale: string;
+}): SweepVerdict;
 /**
  * A route whose live page needs an env var the driver never sets (#6146).
  * While it is unset the route serves its Free placeholder seed instead

package/dist/lib/scaffold-render-sweep.js

@@ -37,6 +37,51 @@ export const CLAIM_GATED_ROUTES = {
     "/purchase/success": "commerce",
     "/purchase/cancel": "commerce",
 };
+/**
+ * Routes whose answer depends on whether the site has a hub to ask (#9423),
+ * and the flow each one sells. With no API origin configured the flow read
+ * is `not-configured` and the route must answer exactly 404 — the no-hub
+ * 404 where the module that owns it is installed, Next's own 404 where it
+ * is not. With one configured it must render its own content.
+ */
+export const HUB_GATED_ROUTES = {
+    "/trial": "trial",
+};
+/**
+ * The API origin names `apps/web` reads, in step with `apiOriginConfigured()`
+ * in `apps/web/app/[locale]/flows/[slug]/magnet-page.tsx`.
+ */
+export const HUB_ORIGIN_ENV_NAMES = ["AILK_API_URL", "NEXT_PUBLIC_AILK_API_URL", "NEXT_PUBLIC_API_URL"];
+/**
+ * Whether a served `apps/web` has an API origin: a non-empty value for one
+ * of `HUB_ORIGIN_ENV_NAMES` in the serve environment or assigned in one of
+ * the env files Next loads (`envFileTexts`).
+ */
+export function hubOriginConfigured(env, envFileTexts) {
+    if (HUB_ORIGIN_ENV_NAMES.some((name) => Boolean(env[name])))
+        return true;
+    return envFileTexts.some((text) => HUB_ORIGIN_ENV_NAMES.some((name) => new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=\\s*["']?[^\\s"'#]`, "m").test(text)));
+}
+/**
+ * A `HUB_GATED_ROUTES` entry. Hub configured: the page must render its own
+ * content (`assessPageRender`). No hub: exactly 404 with no redirect — a 200
+ * means the no-hub branch stopped running.
+ */
+export function assessHubGatedRoute(input) {
+    const { route, hubConfigured, hops, status, contentType, html, locale } = input;
+    const flow = HUB_GATED_ROUTES[route];
+    if (hubConfigured) {
+        const rendered = assessPageRender({ route, hops, status, contentType, html, locale });
+        return { ok: rendered.ok, reason: `${rendered.reason} (hub-gated: ${flow}, hub configured)` };
+    }
+    if (hops.length > 0 || status !== 404) {
+        const first = hops[0];
+        const seen = first ? `${first.status} redirect` : `status ${status}`;
+        const why = status === 200 ? "rendered with no hub to ask" : `expected 404, got ${seen}`;
+        return { ok: false, reason: `${route} -> ${why} (hub-gated: ${flow}, no hub)` };
+    }
+    return { ok: true, reason: `404 (hub-gated: ${flow}, no hub)` };
+}
 /**
  * A route whose live page needs an env var the driver never sets (#6146).
  * While it is unset the route serves its Free placeholder seed instead

package/dist/module-architecture.js

@@ -863,6 +863,13 @@ export const MODULE_SLICES = {
             // tenant-db.ts import, co-owned with `workspace` for the same reason.
             "apps/api/src/routes/workspaces/orders.ts",
             "apps/api/src/services/inbox-orders.ts",
+            // #9254 DD5 — the Inbox callbacks read: the same gate and the same
+            // tenant-db.ts import, co-owned with `workspace` for the same reason.
+            "apps/api/src/routes/workspaces/callbacks.ts",
+            // #9287 DD2 — Start, Get and Extend trial: the same gate and the same
+            // tenant-db.ts import, co-owned with `workspace` for the same reason.
+            "apps/api/src/routes/workspaces/trial.ts",
+            "apps/api/src/services/trial.ts",
             // #852 D8 — the People reads: the same workspace||multi-tenant gate and
             // the same tenant-db.ts import, co-owned with `workspace` for the same
             // reason.
@@ -1035,6 +1042,11 @@ export const MODULE_SLICES = {
             // Co-owned with `multi-tenant` (#9170), as the reads above.
             "apps/api/src/routes/workspaces/orders.ts",
             "apps/api/src/services/inbox-orders.ts",
+            // Co-owned with `multi-tenant` (#9254 DD5), as the reads above.
+            "apps/api/src/routes/workspaces/callbacks.ts",
+            // Co-owned with `multi-tenant` (#9287 DD2), as the reads above.
+            "apps/api/src/routes/workspaces/trial.ts",
+            "apps/api/src/services/trial.ts",
             // Co-owned with `multi-tenant` (#852 D8), as the reads above.
             "apps/api/src/routes/workspaces/people.ts",
             // Co-owned with `multi-tenant` (#7877 D9, D11) — see that slice's entry.
@@ -1719,6 +1731,11 @@ export const MODULE_SLICES = {
             // its siblings (the note above).
             "apps/web/app/[locale]/careers/apply/page.tsx",
             "apps/web/app/[locale]/careers/[slug]/apply/page.tsx",
+            // #9287 DD10 — the trial magnet pair. Its own `trial` route segment,
+            // which no surface gates, so `ownedFiles` keeps both pages out of a
+            // keyless scaffold, beside the careers walks.
+            "apps/web/app/[locale]/trial/page.tsx",
+            "apps/web/app/[locale]/trial/request/page.tsx",
             // #5581 U4 — the eleven signal-collectors components + the slice's own
             // re-export entry point moved to packages-paid/ui-signal-collectors;
             // the package is delivered to a keyed scaffold via `patches` below,

package/dist/sync-routes.d.ts

@@ -49,12 +49,23 @@ export interface SyncRoutesResult {
     missing: RouteReport[];
     /** Route dirs present but with a direct file absent or changed, sorted. */
     modified: RouteReport[];
-    /** Route dirs copied this run (the missing list when applying, else empty). */
+    /** Route dirs copied this run (the missing list minus `refused` when applying, else empty). */
     applied: string[];
     /**
-     * `ROUTE_DEPENDENCIES` files, of any route in `missing`, absent from the
-     * target — copied when `apply` is set (never overwriting), else reported
-     * only. Sorted, deduplicated.
+     * Missing routes `--apply` does not write because an import does not
+     * resolve (#9406 DD4) — reported in check mode too. Sorted.
+     */
+    refused: string[];
+    /**
+     * Per missing route, the local modules its files import (#9406 DD5): one
+     * entry per route with any non-empty list, sorted by route.
+     */
+    routeImports: RouteImportReport[];
+    /**
+     * Files, of any route in `missing` not `refused`, absent from the target:
+     * its `ROUTE_DEPENDENCIES` entries unioned with the `copies` its imports
+     * resolve to (#9406). Copied when `apply` is set (never overwriting), else
+     * reported only. Sorted, deduplicated.
      */
     missingDependencies: string[];
     /** Dependency files copied this run. Sorted. */
@@ -96,6 +107,21 @@ export interface RetiredCheckoutReport {
     /** Generated files rewritten (without `apply`: to rewrite) — the billing action. */
     rewritten: string[];
 }
+/** One missing route's site-local imports (#9406 DD5) — see `walkRouteImports`. */
+export interface RouteImportReport {
+    /** ROUTE_ROOT-relative, `/`-separated. */
+    route: string;
+    /** Template files the route reaches that the site lacks — copied with `--apply`. Sorted. */
+    copies: string[];
+    /** Files the route reaches that the site has, whose bytes differ from the template's — never written. Sorted. */
+    differs: string[];
+    /** Imports that resolve nowhere this sync can write; any entry refuses the route. Sorted by `from`, then `specifier`. */
+    unresolved: Array<{
+        specifier: string;
+        from: string;
+        reason: string;
+    }>;
+}
 /** One `NO_STRUCTURED_DATA_ROUTES` element: its source text, dedented, and the routes it exempts. */
 interface StructuredDataExemption {
     route: string;