create-ailk 0.23.0 → 0.24.0

package/dist/sync-routes.js

@@ -36,14 +36,13 @@
  */
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, dirname, join, resolve, sep } from "node:path";
+import { basename, dirname, join, posix, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
-import { copyTemplate } from "./copy.js";
+import { copyTemplate, renderTemplateFile } from "./copy.js";
 import { SPOKE_BILLING_ACTION_PATH } from "./derive-architecture.js";
 import { appendEnvRows } from "./lib/declared-env.js";
 import { ENV_CATALOG } from "./lib/env-catalog.js";
 import { BILLING_ACTION, BILLING_ACTION_MARKER, RETIRED_CHECKOUT_E2E_MARKER, RETIRED_CHECKOUT_E2E_WORKFLOW_PATH, RETIRED_SPOKE_CHECKOUT_PATHS, } from "./spoke-checkout.js";
-import { substituteMarkers } from "./substitute.js";
 import { GATEABLE_SURFACES, NON_ROUTE_DIRS, ROUTE_DEPENDENCIES, ROUTE_MESSAGE_NAMESPACES, ROUTE_SINCE, surfaceForRouteDir, } from "./surfaces.js";
 import { TEMPLATE_RECORD_PATH, parseTemplateRecord, serializeTemplateRecord, sha256Hex, } from "./template-record.js";
 import { SPOKE_SEAM_FILES, isSpokeExcluded, readSpokeShape, } from "./topology.js";
@@ -70,6 +69,171 @@ const NESTED_FOREIGN_MODULE_ENTRIES = new Set([
     "careers/apply",
     "careers/[slug]",
 ]);
+/** Extensions whose files are scanned for import specifiers (#9406 DD1). */
+const SOURCE_FILE = /\.(?:ts|tsx|js|jsx|mjs|mts)$/;
+/**
+ * Static import and re-export (`import … from`, `export … from`), side-effect
+ * (`import "…"`) and dynamic (`import("…")`) specifiers (#9406 DD1). Matched
+ * over the whole text: `[^'"]*?` spans newlines, so a multi-line
+ * `import {\n  a,\n} from "…"` is caught from its `import` line.
+ */
+const IMPORT_PATTERNS = [
+    /^\s*(?:import|export)\b[^'"]*?\bfrom\s*['"]([^'"]+)['"]/gm,
+    /^\s*import\s*['"]([^'"]+)['"]/gm,
+    /\bimport\(\s*['"]([^'"]+)['"]\s*\)/g,
+];
+/** The site-local (`./`, `../`) import specifiers of a source text, deduplicated. */
+function relativeImportSpecifiers(text) {
+    const out = new Set();
+    for (const pattern of IMPORT_PATTERNS) {
+        for (const match of text.matchAll(pattern)) {
+            const specifier = match[1];
+            if (specifier !== undefined && (specifier.startsWith("./") || specifier.startsWith("../"))) {
+                out.add(specifier);
+            }
+        }
+    }
+    return [...out];
+}
+/**
+ * The scaffold-relative files `specifier`, imported from `importer`, may name —
+ * in #9406 DD2's probe order: a `.js`/`.jsx` specifier's `.ts`/`.tsx` spelling
+ * first, then the exact path, the extension probes and the directory index.
+ * Empty when the path climbs out of the scaffold root.
+ */
+function importCandidates(importer, specifier) {
+    const base = posix.normalize(posix.join(posix.dirname(importer), specifier));
+    if (base === ".." || base.startsWith("../"))
+        return [];
+    const out = [];
+    const js = /\.(jsx?)$/.exec(base);
+    if (js !== null) {
+        const stem = base.slice(0, -js[0].length);
+        if (js[1] === "js")
+            out.push(`${stem}.ts`);
+        out.push(`${stem}.tsx`);
+    }
+    out.push(base);
+    for (const ext of [".ts", ".tsx", ".js", ".jsx", ".mjs"])
+        out.push(base + ext);
+    out.push(`${base}/index.ts`, `${base}/index.tsx`);
+    return out;
+}
+/** Whether `root`/`rel` (`/`-separated) is an existing regular file. */
+function isRegularFile(root, rel) {
+    try {
+        return statSync(join(root, ...rel.split("/"))).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The deepest route in `missingRoutes` a scaffold-relative path sits under —
+ * the route whose own copy writes it — or undefined.
+ */
+function ownerRoute(path, missingRoutes) {
+    if (!path.startsWith(`${ROUTE_ROOT}/`))
+        return undefined;
+    const rel = path.slice(ROUTE_ROOT.length + 1);
+    let owner;
+    for (const m of missingRoutes) {
+        if (rel.startsWith(`${m}/`) && (owner === undefined || m.length > owner.length))
+            owner = m;
+    }
+    return owner;
+}
+/**
+ * Resolve the site-local imports of every file `route`'s own copy writes, and
+ * transitively of every helper that brings (#9406 DD1–DD3). Each import is
+ * resolved against the site first, then the template. A file the site has
+ * ends the walk there (the site owns its closure); a file another missing
+ * route's copy brings is recorded for DD4's propagation; a file only the
+ * template has is a copy — unless the spoke drops it or its surface is not
+ * carried, which refuses the route.
+ */
+function walkRouteImports(route, ctx) {
+    const inScratch = (path) => path.startsWith(`${ROUTE_ROOT}/`) ? path.slice(ROUTE_ROOT.length + 1) : undefined;
+    const templateHas = (path) => {
+        const rel = inScratch(path);
+        return rel !== undefined
+            ? isRegularFile(ctx.scratch, rel)
+            : isRegularFile(ctx.templatesDir, path);
+    };
+    // The bytes `copyTemplate` (a route file) or `copyDependencyFile` (any
+    // other) would write for `path`.
+    const templateBytes = (path) => {
+        const rel = inScratch(path);
+        if (rel !== undefined)
+            return readFileSync(join(ctx.scratch, ...rel.split("/")));
+        return Buffer.from(renderTemplateFile(readFileSync(join(ctx.templatesDir, ...path.split("/"))), path, ctx.versions, ctx.markers));
+    };
+    const copies = new Set();
+    const differs = new Set();
+    const unresolved = [];
+    const reached = [];
+    const queue = regularFilesUnder(ctx.scratch, route)
+        .map((rel) => `${ROUTE_ROOT}/${rel}`)
+        .filter((path) => ownerRoute(path, ctx.missingRoutes) === route);
+    const visited = new Set(queue);
+    for (let from = queue.shift(); from !== undefined; from = queue.shift()) {
+        if (!SOURCE_FILE.test(from))
+            continue;
+        const importer = from;
+        for (const specifier of relativeImportSpecifiers(templateBytes(importer).toString("utf8"))) {
+            const candidates = importCandidates(importer, specifier);
+            const inSite = candidates.find((c) => isRegularFile(ctx.targetAbs, c));
+            const path = inSite ?? candidates.find(templateHas);
+            if (path === undefined) {
+                unresolved.push({ specifier, from: importer, reason: "not in the template" });
+                continue;
+            }
+            const owner = ownerRoute(path, ctx.missingRoutes);
+            if (owner !== undefined) {
+                if (owner !== route)
+                    reached.push({ path, owner, specifier, from: importer });
+                continue;
+            }
+            if (inSite !== undefined) {
+                const siteBytes = readFileSync(join(ctx.targetAbs, ...path.split("/")));
+                if (templateHas(path) && !templateBytes(path).equals(siteBytes))
+                    differs.add(path);
+                continue;
+            }
+            if (ctx.spoke !== undefined && isSpokeExcluded(path, ctx.spoke)) {
+                unresolved.push({ specifier, from: importer, reason: "the spoke does not carry it" });
+                continue;
+            }
+            const routeRel = inScratch(path);
+            const surface = routeRel === undefined ? "core" : surfaceForRouteDir(routeRel);
+            if (surface === undefined || !ctx.carried.has(surface)) {
+                unresolved.push({
+                    specifier,
+                    from: importer,
+                    reason: `its surface (${surface ?? "none"}) is not carried by this site`,
+                });
+                continue;
+            }
+            copies.add(path);
+            if (!visited.has(path)) {
+                visited.add(path);
+                queue.push(path);
+            }
+        }
+    }
+    return {
+        route,
+        copies: [...copies].sort(),
+        differs: [...differs].sort(),
+        unresolved: sortUnresolved(unresolved),
+        reached,
+    };
+}
+/** `unresolved` rows sorted by `from`, then `specifier`. */
+function sortUnresolved(rows) {
+    const key = (row) => `${row.from}\u0000${row.specifier}`;
+    return [...rows].sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+}
 /**
  * The elements of `source`'s `NO_STRUCTURED_DATA_ROUTES` array literal, by a
  * brace scan that skips string literals and comments. Empty when the
@@ -462,6 +626,7 @@ export function syncRoutes(opts) {
     const targetRouteRoot = join(targetAbs, ROUTE_ROOT);
     const missing = [];
     const modified = [];
+    let walks = [];
     const scratch = mkdtempSync(join(tmpdir(), "ailk-sync-routes-"));
     try {
         copyTemplate({
@@ -479,18 +644,73 @@ export function syncRoutes(opts) {
                 modified.push(report);
             }
         }
+        // #9406 — resolve each missing route's site-local imports while the
+        // scratch render is still on disk.
+        walks = missing.map((r) => walkRouteImports(r.route, {
+            scratch,
+            templatesDir: opts.templatesDir,
+            targetAbs,
+            missingRoutes: missing.map((m) => m.route),
+            versions: opts.versions,
+            markers,
+            spoke,
+            carried: new Set(["core", "authed", ...carried]),
+        }));
     }
     finally {
         rmSync(scratch, { recursive: true, force: true });
     }
+    // #9406 DD4 — a route refuses when an import resolves nowhere; refusal
+    // inherits to its sub-routes and to any route importing a file only a
+    // refused route's copy would write, iterated to a fixpoint. Never upward:
+    // an ancestor is still copied without the refused sub-tree.
+    const missingRoutes = missing.map((r) => r.route);
+    const refusedSet = new Set(walks.filter((w) => w.unresolved.length > 0).map((w) => w.route));
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const walk of walks) {
+            if (refusedSet.has(walk.route))
+                continue;
+            if (missingRoutes.some((a) => refusedSet.has(a) && walk.route.startsWith(`${a}/`))) {
+                refusedSet.add(walk.route);
+                changed = true;
+                continue;
+            }
+            const dangling = walk.reached.filter((r) => refusedSet.has(r.owner));
+            if (dangling.length > 0) {
+                walk.unresolved = sortUnresolved([
+                    ...walk.unresolved,
+                    ...dangling.map(({ path, owner, specifier, from }) => ({
+                        specifier,
+                        from,
+                        reason: `${path} is brought by ${owner}, which is refused`,
+                    })),
+                ]);
+                refusedSet.add(walk.route);
+                changed = true;
+            }
+        }
+    }
+    const refused = missingRoutes.filter((r) => refusedSet.has(r)).sort();
+    const routeImports = walks
+        .filter((w) => w.copies.length + w.differs.length + w.unresolved.length > 0)
+        .map(({ route, copies, differs, unresolved }) => ({ route, copies, differs, unresolved }))
+        .sort((a, b) => (a.route < b.route ? -1 : a.route > b.route ? 1 : 0));
     // #5014 third clause: a route's ROUTE_DEPENDENCIES files must exist in the
     // target too, or `--apply` leaves a route that cannot compile. Computed
     // from `missing` only — a route already present is assumed to already have
     // brought its own dependencies along (or the site owner has otherwise
     // satisfied them); re-checking every IN-SCOPE route's dependencies on every
     // run would report a pre-existing, unrelated gap as if this sync caused it.
+    // #9406 — unioned with the copies each route's imports resolve to, and
+    // never for a refused route: its helpers are neither required nor copied.
     const missingDependencies = [
-        ...new Set(missing.flatMap((r) => r.dependencies.filter((dep) => !existsSync(join(targetAbs, dep))))),
+        ...new Set(missing
+            .filter((r) => !refusedSet.has(r.route))
+            .flatMap((r) => [
+            ...r.dependencies.filter((dep) => !existsSync(join(targetAbs, dep))),
+            ...(walks.find((w) => w.route === r.route)?.copies ?? []),
+        ])),
     ].sort();
     const missingMessageNamespaces = [
         ...new Set(missing.flatMap((r) => r.messageNamespaces.filter((ns) => !hasMessageNamespace(targetAbs, ns)))),
@@ -498,11 +718,11 @@ export function syncRoutes(opts) {
     const applied = [];
     const appliedDependencies = [];
     if (opts.apply === true) {
-        const missingRoutes = missing.map((r) => r.route);
-        for (const route of missingRoutes) {
+        const writable = missingRoutes.filter((r) => !refusedSet.has(r));
+        for (const route of writable) {
             applied.push(route);
             // An ancestor route dir's subtree copy already brings this one.
-            if (missingRoutes.some((m) => route.startsWith(m + "/")))
+            if (writable.some((m) => route.startsWith(m + "/")))
                 continue;
             const dst = resolve(join(targetRouteRoot, route));
             if (!dst.startsWith(targetAbs + sep)) {
@@ -513,6 +733,10 @@ export function syncRoutes(opts) {
                 targetDir: dst,
                 versions: opts.versions,
                 markers,
+                // #9406 DD4 — hold back each refused sub-route from the ancestor's copy.
+                excludePaths: refused
+                    .filter((r) => r.startsWith(route + "/"))
+                    .map((r) => r.slice(route.length + 1)),
             });
         }
         for (const dep of missingDependencies) {
@@ -520,7 +744,7 @@ export function syncRoutes(opts) {
             if (!dst.startsWith(targetAbs + sep)) {
                 throw new Error(`refusing to write outside target dir: ${dst}`);
             }
-            copyDependencyFile(join(opts.templatesDir, dep), dst, markers);
+            copyDependencyFile(opts.templatesDir, dep, dst, opts.versions, markers);
             appliedDependencies.push(dep);
         }
         // #7874 D9 — a spoke declares what the copied routes read, as the last
@@ -536,6 +760,8 @@ export function syncRoutes(opts) {
         missing,
         modified,
         applied,
+        refused,
+        routeImports,
         missingDependencies,
         appliedDependencies,
         missingMessageNamespaces,
@@ -572,19 +798,20 @@ function hasMessageNamespace(targetAbs, namespace) {
     }
 }
 /**
- * Copy one dependency file from the template into the target, applying the
- * same marker substitution `copyTemplate` applies to text files — every
- * `ROUTE_DEPENDENCIES` entry is `.ts`/`.tsx`, always text. Never overwrites:
- * the caller (`syncRoutes`) only calls this for a path already confirmed
- * absent from the target, but the check is repeated here so this helper is
- * safe to call on its own.
+ * Copy one dependency file (`rel`, template-relative) from the template into
+ * the target through `renderTemplateFile` — the renderer `copyTemplate` uses,
+ * so a text file gets its markers and a non-text asset an import reached
+ * (`./logo.png`, #9406) is copied byte-for-byte. Never overwrites: the caller
+ * (`syncRoutes`) only calls this for a path already confirmed absent from the
+ * target, but the check is repeated here so this helper is safe to call on
+ * its own.
  */
-function copyDependencyFile(src, dst, markers) {
+function copyDependencyFile(templatesDir, rel, dst, versions, markers) {
     if (existsSync(dst))
         return;
     mkdirSync(dirname(dst), { recursive: true });
-    const text = readFileSync(src, "utf8");
-    writeFileSync(dst, substituteMarkers(text, markers));
+    const bytes = readFileSync(join(templatesDir, ...rel.split("/")));
+    writeFileSync(dst, renderTemplateFile(bytes, rel, versions, markers));
 }
 /** Render the report the CLI prints after a run. Ends with a newline. */
 export function formatSyncRoutesReport(result, apply) {
@@ -598,7 +825,7 @@ export function formatSyncRoutesReport(result, apply) {
     }
     else if (apply) {
         lines.push(`[create-ailk] Copied ${result.applied.length} route(s):`);
-        lines.push(...result.missing.map(entry));
+        lines.push(...result.missing.filter((r) => result.applied.includes(r.route)).map(entry));
     }
     else {
         lines.push(`[create-ailk] ${result.missing.length} template route(s) missing:`);
@@ -611,6 +838,32 @@ export function formatSyncRoutesReport(result, apply) {
     if (result.skippedSurfaces.length > 0) {
         lines.push(`[create-ailk] Surfaces this site does not carry (skipped): ${result.skippedSurfaces.join(", ")}`);
     }
+    // #9406 DD5 — per missing route, what its imports copy, leave, or cannot
+    // resolve; then the routes a dangling import holds back.
+    if (result.routeImports.length > 0) {
+        lines.push("[create-ailk] Local modules the missing route(s) import:");
+        for (const { route, copies, differs, unresolved } of result.routeImports) {
+            lines.push(`  ${route}`);
+            if (copies.length > 0) {
+                lines.push("    copies:");
+                lines.push(...copies.map((path) => `      ${path}`));
+            }
+            if (differs.length > 0) {
+                lines.push("    left as-is (differs from the template):");
+                lines.push(...differs.map((path) => `      ${path}`));
+            }
+            if (unresolved.length > 0) {
+                lines.push("    cannot resolve:");
+                lines.push(...unresolved.map(({ specifier, from, reason }) => `      ${specifier} (from ${from}): ${reason}`));
+            }
+        }
+    }
+    if (result.refused.length > 0) {
+        lines.push(apply
+            ? `[create-ailk] ${result.refused.length} route(s) not copied — an import does not resolve:`
+            : `[create-ailk] ${result.refused.length} route(s) would not be copied — an import does not resolve:`);
+        lines.push(...result.refused.map((route) => `  ${route}`));
+    }
     // #5014 third clause: the routes/messages/lib a synced route needs to
     // compile, reported (and, for lib files, applied) alongside the route.
     if (result.missingDependencies.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.23.0",
+  "version": "0.24.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.44.0",
-    "@working-theory/templates": "0.44.0"
+    "@working-theory/schema": "0.45.0",
+    "@working-theory/templates": "0.45.0"
   },
   "repository": {
     "type": "git",

package/templates/.env.example

@@ -446,6 +446,10 @@ CONTENT_ADAPTER=mdx
 # that database. Rotation and the rekey bin: apps/api/.env.example.
 # STRIPE_CONNECTION_KEY=
 # STRIPE_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.
+# 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
 # nothing — the same fail-closed posture an unset STRIPE_WEBHOOK_SECRET has.

package/templates/CLAUDE.md

@@ -25,8 +25,10 @@ content/          Site settings (_site.mdx) and MDX pages (en/<TypeName>/)
 tools/            This repo's own checks (architecture, CLAUDE.md drift)
 ```
 
-You consume `@working-theory/*` packages from npm. Treat each one as a
-third-party dependency: read its README or its types, not its source.
+You consume `@working-theory/*` packages from npm: read a README or types,
+not the source. Build on one by composing, wrapping or configuring it via
+its documented extension points. Never copy it out of `node_modules`, fork,
+patch or pin it: a copy stops taking fixes. `pnpm architecture` refuses each.
 <!-- /ailk:template id="repo-shape" -->
 
 <!-- ailk:template id="architecture" -->

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

@@ -125,6 +125,13 @@ STRIPE_WEBHOOK_SECRET=whsec_xxx
 # STRIPE_CONNECTION_KEY=
 # STRIPE_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.
+# STRIPE_ENV_ORGANIZATION_ID=
+#
 # The booking webhook receiver (#6085) — a SEPARATE credential from the
 # three above: it verifies POST /v1/webhooks/calcom's x-cal-signature-256
 # header, it does not call the provider. Unset makes the receiver answer 503