create-ailk 0.4.0 → 0.6.0

package/dist/lib/fetch-guard.js

@@ -0,0 +1,101 @@
+/**
+ * Shared network-safety guards for `fetch-template.ts` / `fetch-module.ts`
+ * (issue #5514, Lows 2 and 5 — a post-merge backstop on #5510's
+ * `create-ailk --template` feature).
+ *
+ * A plain internal helper module, not a shared package: both callers already
+ * state at length (see their file docs) why `create-ailk` — the one package
+ * in this monorepo published to public npm — cannot take a runtime
+ * dependency on anything `restricted`-tier. A sibling file inside
+ * `packages/create-ailk/src/lib/` carries no such dependency and is exactly
+ * the right place for logic the two fetchers would otherwise duplicate a
+ * second time.
+ *
+ * Three guards live here:
+ *   - `REQUEST_TIMEOUT_MS` / `fetchTimeoutSignal()` — neither fetcher had a
+ *     request timeout before this; a hung or slow-drip response could block
+ *     `create-ailk` forever.
+ *   - `assertHttpsRegistryUrl()` — neither fetcher validated the scheme of
+ *     the registry URL (env-var-overridable) it was about to send a bearer
+ *     JWT to. Rejects any non-`https:` origin, UNLESS the test-mode seam
+ *     (`NODE_ENV === "test"`) is active — the same seam
+ *     `template-scaffold.test.ts`'s `run()` helper already relies on when it
+ *     spreads `process.env` into the CLI subprocess it spawns against the
+ *     loopback mock registry (`http://127.0.0.1:<port>`). Confirmed
+ *     empirically: Jest sets `NODE_ENV=test` for its own process (and thus
+ *     every child it spawns, since `run()` inherits `process.env`) whenever
+ *     the ambient environment does not already set it — there is no other
+ *     test-mode flag anywhere in this codebase (`AILK_ALLOW*`, `insecure`,
+ *     `__TEST__`, etc. do not exist).
+ *   - `assertContentLengthWithinLimit()` — neither fetcher checked a
+ *     response's declared size against `MAX_TOTAL_SIZE_BYTES` before buffering
+ *     the WHOLE body via `.arrayBuffer()`. That cap was previously enforced
+ *     only downstream, against tar entries, in
+ *     `extract-module-bundle.ts`'s `safeExtractTarGz` — too late to stop an
+ *     oversized response from being held in memory first.
+ */
+import { MAX_TOTAL_SIZE_BYTES } from "./extract-module-bundle.js";
+/**
+ * Per-request timeout applied to every template/module registry fetch.
+ * 30s is generous for a small tarball fetch over a real network while still
+ * bounding a hung connection or slow-drip response.
+ */
+export const REQUEST_TIMEOUT_MS = 30_000;
+/** `AbortSignal.timeout(REQUEST_TIMEOUT_MS)` — one call site, one constant. */
+export function fetchTimeoutSignal() {
+    return AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+}
+/**
+ * `true` iff `hostname` is a loopback host — the ONLY hosts a plain `http:`
+ * registry URL is accepted for. The test suite spawns its mock registry on
+ * `127.0.0.1`; nothing else needs cleartext. (An earlier revision keyed this
+ * on `NODE_ENV=test`, an ambient variable any environment can export — a
+ * security control in a public npm package must not carry a kill switch.)
+ */
+function isLoopbackHost(hostname) {
+    return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "[::1]" || hostname === "::1";
+}
+/**
+ * Reject a registry URL whose origin is not `https:`, unless its host is
+ * loopback (above) — the mock registry the test suite spawns is deliberately
+ * plain `http://127.0.0.1:<port>`. `ErrorCtor` lets each
+ * caller throw its own error class (`FetchTemplateError` / `FetchModuleError`)
+ * so this is a new FAILURE MODE, never a new error type from the caller's
+ * point of view — and never a licence error (`isLicenseError` stays false).
+ */
+export function assertHttpsRegistryUrl(registryUrl, ErrorCtor) {
+    let scheme;
+    let hostname;
+    try {
+        const parsed = new URL(registryUrl);
+        scheme = parsed.protocol;
+        hostname = parsed.hostname;
+    }
+    catch {
+        throw new ErrorCtor(`refusing to use registry URL "${registryUrl}": not a valid URL`);
+    }
+    if (scheme !== "https:" && !isLoopbackHost(hostname)) {
+        throw new ErrorCtor(`refusing to use registry URL "${registryUrl}": scheme must be https:, got "${scheme}"`);
+    }
+}
+/**
+ * Reject a `Response` whose `Content-Length` header declares a size larger
+ * than `MAX_TOTAL_SIZE_BYTES` — called by the caller right after its
+ * existing status-code checks succeed, BEFORE `.arrayBuffer()` ever runs, so
+ * an oversized body is never buffered into memory. A missing or unparseable
+ * `Content-Length` is not itself a violation (a chunked/streamed response may
+ * omit it) — this is defense in depth against a declared size, not a
+ * replacement for the tar-entry cumulative-size cap `extract-module-bundle.ts`
+ * still enforces downstream.
+ */
+export function assertContentLengthWithinLimit(response, ErrorCtor) {
+    const header = response.headers.get("content-length");
+    if (header === null)
+        return;
+    const declared = Number(header);
+    if (!Number.isFinite(declared))
+        return;
+    if (declared > MAX_TOTAL_SIZE_BYTES) {
+        throw new ErrorCtor(`refusing response: declared Content-Length ${declared} exceeds the ${MAX_TOTAL_SIZE_BYTES}-byte limit`);
+    }
+}

package/dist/lib/fetch-module.js

@@ -36,6 +36,7 @@
  * exit uniformly.
  */
 import pkg from "../../package.json" with { type: "json" };
+import { assertContentLengthWithinLimit, assertHttpsRegistryUrl, fetchTimeoutSignal, } from "./fetch-guard.js";
 export const DEFAULT_AILK_MODULE_REGISTRY_URL = "https://ailaunchkit.ai/api/modules";
 /**
  * This package's own `package.json` `"version"`. Deliberately a static JSON
@@ -79,6 +80,7 @@ export async function fetchModule(options) {
     const registryUrl = options.registryUrl ??
         process.env["AILK_MODULE_REGISTRY_URL"] ??
         DEFAULT_AILK_MODULE_REGISTRY_URL;
+    assertHttpsRegistryUrl(registryUrl, FetchModuleError);
     const url = buildUrl(registryUrl, moduleName, version);
     const fetchImpl = options.fetchImpl ?? globalThis.fetch;
     let response;
@@ -90,6 +92,7 @@ export async function fetchModule(options) {
                 Accept: "application/gzip, application/octet-stream",
             },
             redirect: "error",
+            signal: fetchTimeoutSignal(),
         });
     }
     catch (err) {
@@ -111,6 +114,7 @@ export async function fetchModule(options) {
         const body = await safeReadBody(response);
         throw new FetchModuleError(`module registry returned ${response.status} for "${moduleName}": ${body}`);
     }
+    assertContentLengthWithinLimit(response, FetchModuleError);
     const buf = await response.arrayBuffer();
     return new Uint8Array(buf);
 }

package/dist/lib/fetch-template.js

@@ -26,6 +26,7 @@
  * gate the paid path. The registry's own 401 IS the licence verdict.
  */
 import pkg from "../../package.json" with { type: "json" };
+import { assertContentLengthWithinLimit, assertHttpsRegistryUrl, fetchTimeoutSignal, } from "./fetch-guard.js";
 export const DEFAULT_AILK_TEMPLATE_REGISTRY_URL = "https://ailaunchkit.ai/api/templates";
 /**
  * This package's own `package.json` `"version"` — a static JSON import for
@@ -66,6 +67,7 @@ export async function fetchTemplate(options) {
     const registryUrl = options.registryUrl ??
         process.env["AILK_TEMPLATE_REGISTRY_URL"] ??
         DEFAULT_AILK_TEMPLATE_REGISTRY_URL;
+    assertHttpsRegistryUrl(registryUrl, FetchTemplateError);
     const url = buildUrl(registryUrl, templateName, version);
     const fetchImpl = options.fetchImpl ?? globalThis.fetch;
     let response;
@@ -77,6 +79,7 @@ export async function fetchTemplate(options) {
                 Accept: "application/gzip, application/octet-stream",
             },
             redirect: "error",
+            signal: fetchTimeoutSignal(),
         });
     }
     catch (err) {
@@ -98,6 +101,7 @@ export async function fetchTemplate(options) {
         const body = await safeReadBody(response);
         throw new FetchTemplateError(`template registry returned ${response.status} for "${templateName}": ${body}`);
     }
+    assertContentLengthWithinLimit(response, FetchTemplateError);
     const buf = await response.arrayBuffer();
     return new Uint8Array(buf);
 }

package/dist/lib/import-graph.d.ts

@@ -0,0 +1,29 @@
+export declare const SOURCE_EXTS: string[];
+/** Every source file under the given repo-relative roots, as "/"-joined paths. */
+export declare function listFilesUnder(repoRoot: string, roots: string[]): Set<string>;
+/** The relative import specifiers a source file names (static imports + re-exports). */
+export declare function relativeImportsOf(absPath: string): string[];
+/**
+ * Resolve a relative specifier against the candidate set. TypeScript ESM writes
+ * `./x.js` for `./x.ts`, so the `.js` → `.ts`/`.tsx` rewrite is the common case.
+ */
+export declare function resolveRelativeImport(fromFile: string, spec: string, candidates: Set<string>): string | undefined;
+/**
+ * The companion closure of `seeds` under `roots`: the seeds themselves plus
+ * every source file under `roots` that reaches one transitively through a
+ * relative import, to a fixed point.
+ *
+ * This is the shape both consumers need, and the reason the walk is shared
+ * rather than copied. `paidModuleTemplateExclusions()` seeds it with every
+ * paid module's `ownedFiles` to get the files a keyless starter must not
+ * carry; `tools/lint-slice-registration.ts` seeds it with the same set to
+ * derive, by subtraction, the files a scaffold ships UNCONDITIONALLY.
+ *
+ * Never a filename-stem rule (#5182 D7), which misses eleven files and
+ * over-marks three.
+ *
+ * @param repoRoot absolute path to the tree being walked.
+ * @param roots repo-relative roots the walk is confined to.
+ * @param seeds repo-relative, "/"-separated files the closure starts from.
+ */
+export declare function importClosure(repoRoot: string, roots: readonly string[], seeds: Iterable<string>): Set<string>;

package/dist/lib/import-graph.js

@@ -0,0 +1,140 @@
+/**
+ * The relative-import graph walker over a repo-relative source tree.
+ *
+ * Extracted from `module-architecture.ts` (#5701) so the two consumers that
+ * need this resolution share ONE implementation rather than two that can
+ * disagree:
+ *
+ * - `paidModuleTemplateExclusions()` (module-architecture.ts) walks it to take
+ *   the companion closure of every paid module's `ownedFiles` — the files that
+ *   would ship dangling into a keyless starter.
+ * - `tools/lint-slice-registration.ts` walks it to close over the specifiers an
+ *   `isModuleEnabled("X")` branch in `apps/api/src/server.ts` loads, and to
+ *   check every reached file against what module X's slice delivers.
+ *
+ * Both questions are "which files does this one reach through relative
+ * imports", and the answer must be the same function in both mouths: a lint
+ * that resolved specifiers differently from the exclusion set it checks
+ * against would pass on a tree the scaffold cannot boot.
+ *
+ * The resolution is deliberately TEXTUAL — a regex over import/export
+ * specifiers plus a candidate-set lookup, no type-checker and no bundler — so
+ * it runs inside `pnpm preflight`'s memory budget.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+export const SOURCE_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+/** Every source file under the given repo-relative roots, as "/"-joined paths. */
+export function listFilesUnder(repoRoot, roots) {
+    const out = new Set();
+    const skip = new Set(["node_modules", ".next", "dist", ".turbo", ".source"]);
+    const stack = roots.map((r) => r);
+    while (stack.length > 0) {
+        const rel = stack.pop();
+        const abs = join(repoRoot, rel);
+        let entries;
+        try {
+            entries = readdirSync(abs, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (skip.has(entry.name))
+                continue;
+            const childRel = `${rel}/${entry.name}`;
+            if (entry.isDirectory())
+                stack.push(childRel);
+            else if (SOURCE_EXTS.some((e) => entry.name.endsWith(e)))
+                out.add(childRel);
+        }
+    }
+    return out;
+}
+/** The relative import specifiers a source file names (static imports + re-exports). */
+export function relativeImportsOf(absPath) {
+    let src;
+    try {
+        src = readFileSync(absPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const m of src.matchAll(/(?:^|\n)\s*(?:import|export)[\s\S]{0,400}?from\s*["'](\.[^"']*)["']/g))
+        out.push(m[1]);
+    for (const m of src.matchAll(/\bimport\s*\(\s*["'](\.[^"']*)["']\s*\)/g))
+        out.push(m[1]);
+    return out;
+}
+/**
+ * Resolve a relative specifier against the candidate set. TypeScript ESM writes
+ * `./x.js` for `./x.ts`, so the `.js` → `.ts`/`.tsx` rewrite is the common case.
+ */
+export function resolveRelativeImport(fromFile, spec, candidates) {
+    const base = posixJoin(dirname(fromFile.split("/").join(sep)), spec);
+    const stem = base.replace(/\.(js|jsx|mjs|cjs)$/, "");
+    for (const cand of [
+        base,
+        ...SOURCE_EXTS.map((e) => stem + e),
+        ...SOURCE_EXTS.map((e) => `${stem}/index${e}`),
+    ])
+        if (candidates.has(cand))
+            return cand;
+    return undefined;
+}
+/** Join and normalize a "/"-separated path, resolving `.` and `..` segments. */
+function posixJoin(dir, spec) {
+    const parts = `${dir.split(sep).join("/")}/${spec}`.split("/");
+    const out = [];
+    for (const part of parts) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..")
+            out.pop();
+        else
+            out.push(part);
+    }
+    return out.join("/");
+}
+/**
+ * The companion closure of `seeds` under `roots`: the seeds themselves plus
+ * every source file under `roots` that reaches one transitively through a
+ * relative import, to a fixed point.
+ *
+ * This is the shape both consumers need, and the reason the walk is shared
+ * rather than copied. `paidModuleTemplateExclusions()` seeds it with every
+ * paid module's `ownedFiles` to get the files a keyless starter must not
+ * carry; `tools/lint-slice-registration.ts` seeds it with the same set to
+ * derive, by subtraction, the files a scaffold ships UNCONDITIONALLY.
+ *
+ * Never a filename-stem rule (#5182 D7), which misses eleven files and
+ * over-marks three.
+ *
+ * @param repoRoot absolute path to the tree being walked.
+ * @param roots repo-relative roots the walk is confined to.
+ * @param seeds repo-relative, "/"-separated files the closure starts from.
+ */
+export function importClosure(repoRoot, roots, seeds) {
+    const closed = new Set(seeds);
+    const candidates = listFilesUnder(repoRoot, [...roots]);
+    for (;;) {
+        let grew = false;
+        for (const file of candidates) {
+            if (closed.has(file))
+                continue;
+            const imports = relativeImportsOf(join(repoRoot, file));
+            for (const spec of imports) {
+                const target = resolveRelativeImport(file, spec, candidates);
+                if (target !== undefined && closed.has(target)) {
+                    closed.add(file);
+                    grew = true;
+                    break;
+                }
+            }
+        }
+        if (!grew)
+            break;
+    }
+    return closed;
+}

package/dist/module-architecture.d.ts

@@ -58,7 +58,7 @@ export interface PageRosterRow {
     route: string;
     /**
      * Repo-relative seed content this row renders. Absent for an API-backed row
-     * (`/schedule` renders from the scheduling API, not from an MDX file).
+     * (`/meet` renders from the scheduling API, not from an MDX file).
      */
     content?: readonly string[];
 }
@@ -105,7 +105,7 @@ export interface ModuleSlice {
      * disappears just because one module's slice of it does).
      *
      * One entry in the arrays below is deliberately a GLOB
-     * (`"apps-paid/workspace/**"`) rather than enumerated file-by-file — a
+     * (`"apps-paid/admin/**"`) rather than enumerated file-by-file — a
      * whole app with dozens of files, owned outright by one module; every other
      * entry is a literal file
      * path. A file that a module's own docs mention but that lives inside a
@@ -128,7 +128,7 @@ export interface ModuleSlice {
      *     app, never a customer opt-in (see `apps/api/src/config/modules.ts`).
      *   - Two are this-list-only and the manifest simply never recorded them:
      *     `apps/web/app/[locale]/docs/[[...slug]]/page.tsx` and
-     *     `apps/web/app/[locale]/schedule/confirmed/page.tsx`.
+     *     `apps/web/app/[locale]/meet/confirmed/page.tsx`.
      *
      * A file's TEST and STORY companions are never listed here (the
      * SOURCE-files-only rule above still holds) but DO carry the marker. They
@@ -167,13 +167,37 @@ export interface ModuleSlice {
      * Every source must be a file the validated tar extraction produced in the
      * bundle producer's staging directory — repo-relative, coinciding with the
      * `ownedFiles`/`installMap`-source paths this module's producer step
-     * stages at, by construction. `extractModuleBundle` applies this map after
-     * the tar entries are validated: an absolute path, a `..` segment, or a
-     * path absent from staging rejects the whole bundle, as does a destination
-     * that resolves outside the scaffold. A mapped source is copied to its
-     * destination only, never also to its original path.
+     * stages at, by construction. ONE exception: `build-module-bundles.mjs`
+     * also stages the proprietary licence-client LICENSE at the archive root
+     * as `LICENSE` and adds its own `installMap["LICENSE"]` entry (never a
+     * slice field — the producer adds it uniformly, #5552 D1), so a slice's
+     * own `installMap` must not declare a `"LICENSE"` key. `extractModuleBundle`
+     * applies this map after the tar entries are validated: an absolute path, a
+     * `..` segment, or a path absent from staging rejects the whole bundle, as
+     * does a destination that resolves outside the scaffold. A mapped source is
+     * copied to its destination only, never also to its original path.
      */
     installMap?: Record<string, string>;
+    /**
+     * Rename root for this slice's whole-app glob `ownedFiles` entry(ies)
+     * (a `"<dir>/**"` entry — see `ownedFiles`'s own doc above) — the glob
+     * sibling of `installMap` (#5644 D1). Every file `expandEntry` yields
+     * under `<dir>/` installs at `installRoot + <rel-path-under-dir>` instead
+     * of its repo-relative path. `build-module-bundles.mjs`'s
+     * `deriveGlobInstallMap` derives one `installMap` entry per file from this
+     * rule at bundle-build time, and the mock registry fixture
+     * (`__tests__/fixtures/mock-module-registry-server.mjs`) calls the SAME
+     * function so its served manifest cannot drift from the producer's.
+     * Undefined for a slice with no glob `ownedFiles` entry, or one whose glob
+     * files install unchanged at their repo-relative path.
+     *
+     * `installMap` above stays the mechanism for hand-enumerated, non-glob
+     * remaps (see `commerce.installMap`) — a literal map is fine there because
+     * enumerating ten skill files costs ten lines; a whole app's worth of
+     * files committed one line per file into this OSS-shipped source is the
+     * leak class `scripts/check-oss-strip.sh` exists to catch (#5644).
+     */
+    installRoot?: string;
     /**
      * Plain text `extractModuleBundle` prints to stdout after a successful
      * merge, with C0/C1 control characters (other than newline) stripped
@@ -346,4 +370,32 @@ export declare function normalizeModules(modules: string[]): ModuleName[];
  *   Passed in rather than derived from `import.meta.url`, which ts-jest cannot
  *   load — the same reason `sync-routes.ts` documents for staying pure.
  */
+/**
+ * Scaffold destinations that MORE THAN ONE module's `ownedFiles` declares —
+ * the co-ownership the `#5618 D4` install-time ownership registry must treat
+ * as intentional rather than as an overwrite (#5702 follow-up).
+ *
+ * Co-ownership is how a file reaches a scaffold under either of two modules
+ * without being transferred away from the other. #5677 needed it for the
+ * submissions review surface: the routes register under
+ * `multi-tenant || signal-collectors`, so BOTH bundles must be able to
+ * deliver them, or the module that lacks them throws
+ * `ERR_MODULE_NOT_FOUND` during `build()`.
+ *
+ * `validateLayerOwnership` (`lib/extract-module-bundle.ts`) refuses a
+ * destination an earlier layer already wrote, because a silent
+ * last-writer-wins between two modules that disagree is the bug `#5618 D4`
+ * exists to catch. Two modules that both DECLARE the same repo file are not
+ * that case: they stage the same bytes from the same source, so whichever
+ * lands second writes what is already there. Without this allowance a
+ * scaffold selecting both modules — `saas-product`, whose `requires` names
+ * `signal-collectors` AND `multi-tenant` — aborts mid-install, after the
+ * first module's files are on disk.
+ *
+ * Only a DECLARED overlap is allowed. A destination two layers collide on
+ * without both naming it in `ownedFiles` is still refused, which is the
+ * whole invariant.
+ */
+export declare function coOwnedModuleDestinations(): ReadonlySet<string>;
+export declare const EXCLUDE_TEMPLATE_DIRS: readonly string[];
 export declare function paidModuleTemplateExclusions(snapshotRoots: readonly string[], repoRoot: string): string[];