create-ailk 0.2.0 → 0.3.0

package/templates/apps/api/src/lib/__tests__/slice-load.test.ts

@@ -0,0 +1,89 @@
+/**
+ * #5334 — `loadSlice()` is the slice-module load boundary.
+ *
+ * The regression that matters most here is the LAST block: a slice that throws
+ * while evaluating must keep its own error object, type and stack. Wrapping it
+ * would turn a real bug in a slice into a misleading "could not be resolved"
+ * report, which is the opposite of what this boundary exists to do.
+ */
+import { loadSlice } from "../slice-load.js";
+
+function moduleNotFound(code: string, message: string): Error {
+  const error = new Error(message) as Error & { code: string };
+  error.code = code;
+  return error;
+}
+
+describe("loadSlice (#5334)", () => {
+  it("passes a resolving thunk's value straight through", async () => {
+    const mod = { workspaceContextRoutes: () => undefined };
+    await expect(loadSlice("./routes/workspaces/index.js", async () => mod))
+      .resolves.toBe(mod);
+  });
+
+  it("awaits the thunk rather than the specifier — the specifier is never imported", async () => {
+    const load = jest.fn(async () => ({ ok: true }));
+    await loadSlice("./never-imported.js", load);
+    expect(load).toHaveBeenCalledTimes(1);
+  });
+
+  describe.each([
+    ["ERR_MODULE_NOT_FOUND", "the ESM resolver's code"],
+    ["MODULE_NOT_FOUND", "the CJS resolver's code"],
+  ])("on %s (%s)", (code) => {
+    const original = moduleNotFound(
+      code,
+      "Cannot find module '/x/apps/api/dist/list.js'",
+    );
+    const failing = async () => {
+      throw original;
+    };
+
+    it("names the specifier in the message", async () => {
+      await expect(loadSlice("./list.js", failing)).rejects.toThrow(
+        /AILK slice module '\.\/list\.js'/,
+      );
+    });
+
+    it("names BOTH causes, so a reader can tell a tracer miss from a bundled build", async () => {
+      const error = await loadSlice("./list.js", failing).catch(
+        (e: unknown) => e as Error,
+      );
+      expect(error.message).toMatch(/not SHIPPED/);
+      expect(error.message).toMatch(/slice-reachability:check/);
+      expect(error.message).toMatch(/BUNDLED/);
+      expect(error.message).toMatch(/apps\/api\/CLAUDE\.md/);
+    });
+
+    it("preserves the original error as `cause`", async () => {
+      const error = await loadSlice("./list.js", failing).catch(
+        (e: unknown) => e as Error,
+      );
+      expect(error.cause).toBe(original);
+    });
+  });
+
+  it("rethrows a non-resolution error IDENTICALLY — same object, not a wrapper", async () => {
+    const boom = new Error("slice blew up while evaluating");
+    const caught = await loadSlice("./list.js", async () => {
+      throw boom;
+    }).catch((e: unknown) => e);
+    expect(caught).toBe(boom);
+    expect((caught as Error).message).toBe("slice blew up while evaluating");
+  });
+
+  it("rethrows an errno-shaped error that is not a module-resolution code", async () => {
+    const denied = moduleNotFound("EACCES", "permission denied");
+    const caught = await loadSlice("./list.js", async () => {
+      throw denied;
+    }).catch((e: unknown) => e);
+    expect(caught).toBe(denied);
+  });
+
+  it("rethrows a non-Error throw untouched", async () => {
+    const caught = await loadSlice("./list.js", async () => {
+      throw "a string, because JavaScript";
+    }).catch((e: unknown) => e);
+    expect(caught).toBe("a string, because JavaScript");
+  });
+});

package/templates/apps/api/src/lib/slice-load.ts

@@ -0,0 +1,90 @@
+/**
+ * Slice-module load boundary (#5334 D4).
+ *
+ * Every paid-module SLICE in `apps/api` is reached through an indirect dynamic
+ * `import()` — a specifier the call site never writes as a literal, because
+ * `tsc` would then resolve it and the OSS strip would break (#5182 D1). #5304
+ * moved those specifiers onto module-level constants, the one shape that is
+ * simultaneously unresolvable to `tsc` and traceable to `@vercel/nft`, so the
+ * files reach a Vercel deployment.
+ *
+ * WHAT THIS FILE IS FOR. That shape is correct for the deploy path the scaffold
+ * ships, and it cannot be made to work under a BUNDLER. esbuild bundles a
+ * dynamic `import()` iff its argument is a string literal at the call site —
+ * exactly the predicate `tsc` resolves on, and exactly the one #5182 D1
+ * requires be false. So in a bundled build the specifier survives verbatim and
+ * Node resolves it against the BUNDLE OUTPUT directory rather than the source
+ * module's: `"./list.js"`, written in `routes/project-listings/index.ts`,
+ * becomes `dist/list.js` and does not exist. `build()` throws during
+ * CONSTRUCTION, so every route 500s rather than one.
+ *
+ * The failure is otherwise silent on every channel: esbuild emits no warning
+ * for the imports it declines to bundle, and a consuming frontend degrades to
+ * an empty list and still answers 200. `salessmyth/samhenry` spent nine hours
+ * on it. This boundary is what turns that into a one-line diagnosis — it does
+ * not make bundling work, because nothing in this file could.
+ *
+ * WHY IT TAKES A THUNK AND NOT A SPECIFIER. `loadSlice("./list.js")` doing the
+ * `import()` in here would be the obvious signature and would silently undo
+ * #5304. `enumerateSliceSpecifiers()` treats a file as an "indirect file" only
+ * if it carries a dynamic `import()` with a non-literal argument; move the call
+ * out of the callers and they stop qualifying, their specifier constants stop
+ * being candidates, and `check-slice-reachability.ts` passes vacuously over an
+ * empty set. Worse, `@vercel/nft` constant-propagates `WORKSPACES_INDEX` into
+ * `import(WORKSPACES_INDEX)` only because the constant and the call sit in one
+ * module — hoist the call and there is nothing to propagate, so every slice
+ * file goes untraced and #5304's outage returns with its own gate green.
+ *
+ * So the `import()` stays at the call site, in the caller's module, and this
+ * function only awaits the thunk and interprets the failure.
+ *
+ * Gated by `scripts/check-bundled-build-diagnoses.ts`, which bundles `apps/api`
+ * and asserts that the boot fails WITH this diagnostic rather than without one.
+ */
+
+/**
+ * Node reports an unresolvable ESM specifier as `ERR_MODULE_NOT_FOUND` and an
+ * unresolvable CJS one as `MODULE_NOT_FOUND`. A bundle can produce either,
+ * since a bundled graph mixes both.
+ */
+const MODULE_NOT_FOUND_CODES = new Set(["ERR_MODULE_NOT_FOUND", "MODULE_NOT_FOUND"]);
+
+function isModuleNotFound(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null | undefined)?.code;
+  return typeof code === "string" && MODULE_NOT_FOUND_CODES.has(code);
+}
+
+/**
+ * Await a slice module's loader thunk, turning an unresolvable module into a
+ * diagnosis instead of a bare `ERR_MODULE_NOT_FOUND` on a path that never
+ * existed.
+ *
+ * Anything that is not a module-resolution failure is rethrown UNTOUCHED — the
+ * same object, not a wrapper. A slice that throws while evaluating is a real
+ * bug in the slice and must keep its own stack and type.
+ *
+ * @param specifier the module specifier the thunk imports, for the message.
+ *   Every call site already has it in scope, so nothing is enumerated here.
+ * @param load the caller's own `() => import(CONST)` thunk. Must close over a
+ *   constant in the CALLER's module — see the file header.
+ */
+export async function loadSlice(
+  specifier: string,
+  load: () => Promise<unknown>,
+): Promise<unknown> {
+  try {
+    return await load();
+  } catch (error) {
+    if (!isModuleNotFound(error)) throw error;
+    throw new Error(
+      `AILK slice module '${specifier}' could not be resolved at runtime. ` +
+        `This throws during server construction, so every route fails, not one. Two causes produce it:\n` +
+        `  1. The module was compiled but not SHIPPED — the deploy-time file tracer did not emit it (#5304). ` +
+        `Check with \`pnpm slice-reachability:check\`.\n` +
+        `  2. This build was BUNDLED. apps/api does not support bundling (#5334): a bundler resolves this ` +
+        `specifier against the bundle's own output directory rather than its source module's, and esbuild ` +
+        `leaves it unbundled without a warning. See apps/api/CLAUDE.md § Deploy path.`,
+      { cause: error },
+    );
+  }
+}

package/templates/apps/api/src/openapi/__tests__/openapi.test.ts

@@ -28,10 +28,10 @@ describe("GET /api/openapi.json", () => {
 
     const spec = JSON.parse(res.body);
     expect(spec.openapi).toBe("3.1.0");
-    expect(spec.info).toMatchObject({
-      title: "AI Launch Kit — Public Content API",
-      version: "1.0.0",
-    });
+    // The title is resolved from the serving site's own `_site.mdx` (#5307),
+    // so assert its SHAPE rather than a literal site name — the same build
+    // serves a different title on every consuming site.
+    expect(spec.info.title).toMatch(/Public Content API$/);
     expect(spec.info.version).toBe("1.0.0");
     expect(typeof spec.paths).toBe("object");
   });
@@ -54,39 +54,59 @@ describe("GET /api/openapi.json", () => {
     );
   });
 
-  it("documents the checkout sessions endpoint with operationId createCheckoutSession", async () => {
-    const res = await app.inject({
-      method: "GET",
-      url: "/v1/openapi.json",
+  // The checkout path's OpenAPI documentation is module-conditional (commerce,
+  // D-47 / #5364) — mirroring the route's own registration gate in server.ts —
+  // so these two assertions need the module enabled, exactly as a real
+  // commerce-installed deployment would have it.
+  describe("checkout endpoint (commerce module enabled)", () => {
+    const PRIOR_ENABLED_MODULES = process.env.AILK_ENABLED_MODULES;
+
+    beforeEach(() => {
+      process.env.AILK_ENABLED_MODULES = "commerce";
     });
 
-    const spec = JSON.parse(res.body);
-    expect(spec.paths["/v1/checkout/sessions"].post.operationId).toBe(
-      "createCheckoutSession",
-    );
-  });
+    afterEach(() => {
+      if (PRIOR_ENABLED_MODULES === undefined) {
+        delete process.env.AILK_ENABLED_MODULES;
+      } else {
+        process.env.AILK_ENABLED_MODULES = PRIOR_ENABLED_MODULES;
+      }
+    });
 
-  it("documents 201, 400, 404, 500, 502 responses for the checkout endpoint", async () => {
-    const res = await app.inject({
-      method: "GET",
-      url: "/v1/openapi.json",
+    it("documents the checkout sessions endpoint with operationId createCheckoutSession", async () => {
+      const res = await app.inject({
+        method: "GET",
+        url: "/v1/openapi.json",
+      });
+
+      const spec = JSON.parse(res.body);
+      expect(spec.paths["/v1/checkout/sessions"].post.operationId).toBe(
+        "createCheckoutSession",
+      );
     });
 
-    const spec = JSON.parse(res.body);
-    const responses = spec.paths["/v1/checkout/sessions"].post.responses;
-    expect(responses["201"].description).toBe("Checkout session created");
-    expect(responses["400"].description).toBe(
-      "Validation error — invalid request body",
-    );
-    expect(responses["404"].description).toBe(
-      "Unknown product code — no active Stripe price for the given productCode",
-    );
-    expect(responses["500"].description).toBe(
-      "Live-mode forbidden — STRIPE_SECRET_KEY is a live key",
-    );
-    expect(responses["502"].description).toBe(
-      "Checkout unavailable — Stripe returned an unexpected error",
-    );
+    it("documents 201, 400, 404, 500, 502 responses for the checkout endpoint", async () => {
+      const res = await app.inject({
+        method: "GET",
+        url: "/v1/openapi.json",
+      });
+
+      const spec = JSON.parse(res.body);
+      const responses = spec.paths["/v1/checkout/sessions"].post.responses;
+      expect(responses["201"].description).toBe("Checkout session created");
+      expect(responses["400"].description).toBe(
+        "Validation error — invalid request body",
+      );
+      expect(responses["404"].description).toBe(
+        "Unknown product code — no active Stripe price for the given productCode",
+      );
+      expect(responses["500"].description).toBe(
+        "Live-mode forbidden — STRIPE_SECRET_KEY is a live key",
+      );
+      expect(responses["502"].description).toBe(
+        "Checkout unavailable — Stripe returned an unexpected error",
+      );
+    });
   });
 
   it("declares query and path parameters for content endpoints", async () => {

package/templates/apps/api/src/openapi/__tests__/spec-identity.test.ts

@@ -0,0 +1,182 @@
+/**
+ * @file spec-identity.test.ts
+ *
+ * The served API's self-description (#5307) and the `servers` block (#5306).
+ *
+ * These assert the BUILDER's output given a config rather than a deployed
+ * response: the defect is that a deployed site serves the kit's identity and
+ * the kit's host, and the builder is the only place that can be proved
+ * without deploying.
+ */
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  API_VERSION,
+  apiDescription,
+  apiDisplayName,
+  buildOpenApiSpec,
+  resetApiIdentity,
+  resolveApiIdentity,
+} from "../spec";
+
+/** Write a throwaway content root carrying the given `_site.mdx` frontmatter. */
+function withContentRoot(frontmatter: string): string {
+  const root = mkdtempSync(join(tmpdir(), "ailk-site-"));
+  mkdirSync(root, { recursive: true });
+  writeFileSync(join(root, "_site.mdx"), `---\n${frontmatter}\n---\n\nbody\n`);
+  return root;
+}
+
+describe("buildOpenApiSpec — site identity (#5307)", () => {
+  it("titles the spec after the site, not after the kit", () => {
+    const spec = buildOpenApiSpec({ siteName: "Sam Henry" });
+
+    expect(spec.info.title).toBe("Sam Henry — Public Content API");
+    expect(JSON.stringify(spec.info)).not.toMatch(/AI Launch Kit|AILK/i);
+  });
+
+  it("degrades to a named neutral title when no site name is resolvable", () => {
+    const spec = buildOpenApiSpec({});
+
+    expect(spec.info.title).toBe("Public Content API");
+    expect(spec.info.title).not.toMatch(/AI Launch Kit|AILK/i);
+  });
+
+  it("asserts no licence over a deployment that has not chosen one", () => {
+    expect(buildOpenApiSpec({ siteName: "Sam Henry" }).info).not.toHaveProperty(
+      "license",
+    );
+  });
+
+  it("keeps API_VERSION as the /v1 contract version", () => {
+    expect(API_VERSION).toBe("1.0.0");
+    expect(buildOpenApiSpec({}).info.version).toBe(API_VERSION);
+  });
+});
+
+describe("buildOpenApiSpec — servers block (#5306)", () => {
+  it("names the deployment's own API origin", () => {
+    const spec = buildOpenApiSpec({ publicApiUrl: "https://api.samhenry.org" });
+
+    expect(spec.servers).toEqual([
+      { url: "https://api.samhenry.org", description: expect.any(String) },
+    ]);
+  });
+
+  it("never serves the kit's own host", () => {
+    const spec = buildOpenApiSpec({
+      siteName: "Sam Henry",
+      publicApiUrl: "https://api.samhenry.org",
+    });
+
+    expect(JSON.stringify(spec)).not.toContain("ailaunchkit.ai");
+  });
+
+  it("normalises a trailing slash", () => {
+    expect(
+      buildOpenApiSpec({ publicApiUrl: "https://api.samhenry.org/" }).servers[0]
+        ?.url,
+    ).toBe("https://api.samhenry.org");
+  });
+
+  it("degrades to a document-relative origin when the value is unset", () => {
+    const spec = buildOpenApiSpec({});
+
+    expect(spec.servers).toHaveLength(1);
+    expect(spec.servers[0]?.url).toBe("/");
+    // The degradation is named in the served document itself, so an agent
+    // reading the spec learns why rather than following a wrong absolute URL.
+    expect(spec.servers[0]?.description).toMatch(/AILK_PUBLIC_API_URL/);
+  });
+
+  it("degrades rather than serving a malformed origin", () => {
+    expect(buildOpenApiSpec({ publicApiUrl: "not-a-url" }).servers[0]?.url).toBe(
+      "/",
+    );
+    expect(
+      buildOpenApiSpec({ publicApiUrl: "ftp://api.example.com" }).servers[0]
+        ?.url,
+    ).toBe("/");
+  });
+});
+
+describe("resolveApiIdentity — reads _site.mdx", () => {
+  const originalContentRoot = process.env.CONTENT_ROOT;
+  let root: string | undefined;
+
+  afterEach(() => {
+    if (originalContentRoot === undefined) delete process.env.CONTENT_ROOT;
+    else process.env.CONTENT_ROOT = originalContentRoot;
+    if (root) rmSync(root, { recursive: true, force: true });
+    root = undefined;
+    resetApiIdentity();
+  });
+
+  it("sources the site name and description from _site.mdx", () => {
+    root = withContentRoot(
+      [
+        'version: "1"',
+        "siteName: Sam Henry",
+        "baseUrl: https://samhenry.org",
+        "siteIdentity:",
+        "  kind: Person",
+        "  name: Sam Henry",
+        "  description: Independent software consultant.",
+      ].join("\n"),
+    );
+    process.env.CONTENT_ROOT = root;
+    resetApiIdentity();
+
+    const identity = resolveApiIdentity();
+
+    expect(identity.siteName).toBe("Sam Henry");
+    expect(identity.siteDescription).toBe("Independent software consultant.");
+    expect(apiDisplayName(identity)).toBe("Sam Henry API");
+    expect(apiDescription(identity)).toBe("Independent software consultant.");
+  });
+
+  // #5306 AC-3 — the trap this card exists to refuse.
+  it("does NOT use _site.mdx baseUrl as the API origin", () => {
+    root = withContentRoot(
+      [
+        'version: "1"',
+        "siteName: Sam Henry",
+        // The SITE origin. The API is deployed on a different host
+        // (api.samhenry.org), so this value must never reach `servers`.
+        "baseUrl: https://samhenry.org",
+      ].join("\n"),
+    );
+    process.env.CONTENT_ROOT = root;
+    resetApiIdentity();
+
+    const identity = resolveApiIdentity();
+    expect(identity.publicApiUrl).not.toBe("https://samhenry.org");
+
+    const spec = buildOpenApiSpec({ ...identity, publicApiUrl: undefined });
+    expect(JSON.stringify(spec.servers)).not.toContain("samhenry.org");
+  });
+
+  it("degrades to a named neutral default when _site.mdx is unreadable", () => {
+    root = mkdtempSync(join(tmpdir(), "ailk-empty-"));
+    process.env.CONTENT_ROOT = root;
+    resetApiIdentity();
+
+    const identity = resolveApiIdentity();
+
+    expect(identity.siteName).toBeUndefined();
+    expect(apiDisplayName(identity)).toBe("Content API");
+    expect(apiDisplayName(identity)).not.toMatch(/AI Launch Kit|AILK/i);
+    expect(buildOpenApiSpec(identity).info.title).toBe("Public Content API");
+  });
+
+  it("degrades when _site.mdx frontmatter is malformed", () => {
+    root = withContentRoot("siteName: [unclosed");
+    process.env.CONTENT_ROOT = root;
+    resetApiIdentity();
+
+    expect(resolveApiIdentity().siteName).toBeUndefined();
+    expect(apiDisplayName(resolveApiIdentity())).toBe("Content API");
+  });
+});