create-ailk 0.2.0 → 0.4.0

package/templates/apps/api/src/openapi/surface-drift.ts

@@ -0,0 +1,195 @@
+/**
+ * The comparison instrument for #5314 — diffs the routes the server ACTUALLY
+ * registers against each surface that claims to describe them.
+ *
+ * Two surfaces describe this API's endpoints: the root index `endpoints`
+ * object (`server.ts`) and the OpenAPI `paths` object (`spec.ts`). Before
+ * #5314 both were hand-maintained literals, and both had drifted — 11 and 7
+ * entries against 68 registered routes, with `/v1/project-listings/public`
+ * missing from both and `/v1/billing/usage` missing from the root index.
+ *
+ * This module only COMPARES. The derivation that keeps the surfaces honest
+ * lives in `spec.ts` beside the shapes it produces; keeping the comparison
+ * separate is what lets the gate assert against a surface it did not build.
+ *
+ * Deliberately free of any `fastify` or `spec.ts` import: it takes plain data,
+ * so the gate can feed it a SERVED document (fetched over `inject`) rather
+ * than the object the code under test just returned.
+ */
+
+/** One route as Fastify registered it. `url` is Fastify-shaped (`:param`). */
+export interface RegisteredRoute {
+  /** Uppercase HTTP method. HEAD is excluded — Fastify derives it from GET. */
+  method: string;
+  /** Fastify path, e.g. `/v1/content/:type/:slug`. */
+  url: string;
+}
+
+/** One surface's disagreement with the registered route table. */
+export interface SurfaceDiff {
+  /** Which surface this diff describes. */
+  surface: "openapi-paths" | "root-index-endpoints";
+  /** `METHOD /path` registered by the server but absent from the surface. */
+  missingFromSurface: string[];
+  /** `METHOD /path` named by the surface but not registered by the server. */
+  orphanedInSurface: string[];
+}
+
+/**
+ * Fastify path → OpenAPI path template: `/v1/content/:type` becomes
+ * `/v1/content/{type}`. OpenAPI 3.1 has no `:param` form, so a document that
+ * published the Fastify string would be describing a path no client can build.
+ */
+export function toOpenApiPath(fastifyPath: string): string {
+  return fastifyPath
+    .split("/")
+    .map((segment) =>
+      segment.startsWith(":") ? `{${segment.slice(1)}}` : segment,
+    )
+    .join("/");
+}
+
+/** The comparison key both sides normalise to: `GET /v1/content/types`. */
+export function routeKey(method: string, path: string): string {
+  return `${method.toUpperCase()} ${path}`;
+}
+
+/** Registered routes as OpenAPI-shaped comparison keys. */
+function registeredOpenApiKeys(routes: RegisteredRoute[]): Set<string> {
+  return new Set(routes.map((r) => routeKey(r.method, toOpenApiPath(r.url))));
+}
+
+/** Registered routes as Fastify-shaped comparison keys. */
+function registeredFastifyKeys(routes: RegisteredRoute[]): Set<string> {
+  return new Set(routes.map((r) => routeKey(r.method, r.url)));
+}
+
+/**
+ * The OpenAPI methods a path item declares. Non-method keys an OpenAPI path
+ * item may legally carry (`parameters`, `summary`, `description`, `servers`,
+ * `$ref`) are not operations and must not be compared as if they were.
+ */
+const OPENAPI_METHODS = new Set([
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace",
+]);
+
+/**
+ * Comparison keys a served OpenAPI `paths` object claims.
+ *
+ * Takes the served document's `paths` as plain data so the gate can compare
+ * what an agent would actually fetch, not what the builder returned.
+ */
+export function openApiSurfaceKeys(
+  paths: Record<string, Record<string, unknown>>,
+): Set<string> {
+  const keys = new Set<string>();
+  for (const [path, item] of Object.entries(paths ?? {})) {
+    for (const method of Object.keys(item ?? {})) {
+      if (!OPENAPI_METHODS.has(method.toLowerCase())) continue;
+      if (method.toLowerCase() === "head") continue;
+      keys.add(routeKey(method, path));
+    }
+  }
+  return keys;
+}
+
+/**
+ * Comparison keys a root-index `endpoints` object claims.
+ *
+ * Each value is `"METHOD[/METHOD...] /path"` — the shape the hand-authored
+ * object already used (`"GET/PATCH /v1/user/profile"`), preserved so no
+ * published entry changes shape. A value that does not parse is reported as
+ * an orphan rather than skipped: an unparseable entry is precisely the kind
+ * of hand-edit this instrument exists to catch.
+ */
+export function rootIndexSurfaceKeys(
+  endpoints: Record<string, string>,
+): Set<string> {
+  const keys = new Set<string>();
+  for (const value of Object.values(endpoints ?? {})) {
+    const match = /^([A-Za-z/]+)\s+(\S+)$/.exec(value ?? "");
+    if (!match?.[1] || !match[2]) {
+      keys.add(`UNPARSEABLE ${value}`);
+      continue;
+    }
+    for (const method of match[1].split("/")) {
+      if (!method) continue;
+      if (method.toUpperCase() === "HEAD") continue;
+      keys.add(routeKey(method, match[2]));
+    }
+  }
+  return keys;
+}
+
+function diff(registered: Set<string>, surface: Set<string>) {
+  return {
+    missingFromSurface: [...registered].filter((k) => !surface.has(k)).sort(),
+    orphanedInSurface: [...surface].filter((k) => !registered.has(k)).sort(),
+  };
+}
+
+/**
+ * Diff the registered route table against both surfaces.
+ *
+ * `paths` is the served OpenAPI `paths` object (OpenAPI-templated); `endpoints`
+ * is the served root-index `endpoints` object (Fastify-shaped, matching the
+ * strings that surface has always published). Each is compared in its own
+ * vocabulary so neither surface is judged against a shape it never used.
+ */
+export function compareSurfaces(
+  registered: RegisteredRoute[],
+  paths: Record<string, Record<string, unknown>>,
+  endpoints: Record<string, string>,
+): SurfaceDiff[] {
+  return [
+    {
+      surface: "openapi-paths",
+      ...diff(registeredOpenApiKeys(registered), openApiSurfaceKeys(paths)),
+    },
+    {
+      surface: "root-index-endpoints",
+      ...diff(
+        registeredFastifyKeys(registered),
+        rootIndexSurfaceKeys(endpoints),
+      ),
+    },
+  ];
+}
+
+/** Whether any surface disagrees with the registered route table. */
+export function hasDrift(diffs: SurfaceDiff[]): boolean {
+  return diffs.some(
+    (d) => d.missingFromSurface.length > 0 || d.orphanedInSurface.length > 0,
+  );
+}
+
+/**
+ * Render the drift for a failing assertion, or `""` when there is none.
+ *
+ * A surface that agrees contributes nothing, so the empty string means "no
+ * drift" and can be asserted against directly. Counts come first so a reader
+ * sees the scale before the list, then EVERY entry — a truncated drift report
+ * is how a gate teaches people to ignore it.
+ */
+export function formatSurfaceDrift(diffs: SurfaceDiff[]): string {
+  const lines: string[] = [];
+  for (const d of diffs) {
+    if (d.missingFromSurface.length === 0 && d.orphanedInSurface.length === 0) {
+      continue;
+    }
+    lines.push(
+      `${d.surface}: ${d.missingFromSurface.length} registered route(s) missing from the surface, ` +
+        `${d.orphanedInSurface.length} surface entr(ies) with no registered route`,
+    );
+    for (const k of d.missingFromSurface) lines.push(`  missing:  ${k}`);
+    for (const k of d.orphanedInSurface) lines.push(`  orphaned: ${k}`);
+  }
+  return lines.join("\n");
+}

package/templates/apps/api/src/routes/content/__tests__/create.test.ts

@@ -61,14 +61,28 @@ const validBody = {
 
 describe("POST /api/content/:type", () => {
   let app: FastifyInstance;
+  // The write handlers only register when content-write is enabled
+  // (routes/content/index.ts's isModuleEnabled('content-write') gate); an
+  // unset AILK_ENABLED_MODULES no longer defaults to every module on
+  // (D-44, #5368), so this suite enables it explicitly.
+  const priorEnabledModules = process.env.AILK_ENABLED_MODULES;
 
   beforeEach(async () => {
+    process.env.AILK_ENABLED_MODULES = "content-write";
     app = require("fastify")();
     await app.register(contentRoutes);
     jest.clearAllMocks();
     mockCheckLicense.mockReset();
   });
 
+  afterAll(() => {
+    if (priorEnabledModules === undefined) {
+      delete process.env.AILK_ENABLED_MODULES;
+    } else {
+      process.env.AILK_ENABLED_MODULES = priorEnabledModules;
+    }
+  });
+
   afterEach(async () => {
     await app.close();
   });

package/templates/apps/api/src/routes/content/__tests__/delete.test.ts

@@ -49,14 +49,28 @@ function freeLicense() {
 
 describe("DELETE /api/content/:type/:slug", () => {
   let app: FastifyInstance;
+  // The write handlers only register when content-write is enabled
+  // (routes/content/index.ts's isModuleEnabled('content-write') gate); an
+  // unset AILK_ENABLED_MODULES no longer defaults to every module on
+  // (D-44, #5368), so this suite enables it explicitly.
+  const priorEnabledModules = process.env.AILK_ENABLED_MODULES;
 
   beforeEach(async () => {
+    process.env.AILK_ENABLED_MODULES = "content-write";
     app = require("fastify")();
     await app.register(contentRoutes);
     jest.clearAllMocks();
     mockCheckLicense.mockReset();
   });
 
+  afterAll(() => {
+    if (priorEnabledModules === undefined) {
+      delete process.env.AILK_ENABLED_MODULES;
+    } else {
+      process.env.AILK_ENABLED_MODULES = priorEnabledModules;
+    }
+  });
+
   afterEach(async () => {
     await app.close();
   });

package/templates/apps/api/src/routes/content/__tests__/update.test.ts

@@ -61,14 +61,28 @@ const validBody = {
 
 describe("PATCH /api/content/:type/:slug", () => {
   let app: FastifyInstance;
+  // The write handlers only register when content-write is enabled
+  // (routes/content/index.ts's isModuleEnabled('content-write') gate); an
+  // unset AILK_ENABLED_MODULES no longer defaults to every module on
+  // (D-44, #5368), so this suite enables it explicitly.
+  const priorEnabledModules = process.env.AILK_ENABLED_MODULES;
 
   beforeEach(async () => {
+    process.env.AILK_ENABLED_MODULES = "content-write";
     app = require("fastify")();
     await app.register(contentRoutes);
     jest.clearAllMocks();
     mockCheckLicense.mockReset();
   });
 
+  afterAll(() => {
+    if (priorEnabledModules === undefined) {
+      delete process.env.AILK_ENABLED_MODULES;
+    } else {
+      process.env.AILK_ENABLED_MODULES = priorEnabledModules;
+    }
+  });
+
   afterEach(async () => {
     await app.close();
   });

package/templates/apps/api/src/routes/content/index.ts

@@ -24,25 +24,52 @@
 import type { FastifyPluginAsync } from "fastify";
 
 import { isModuleEnabled } from "../../config/modules.js";
+import { loadSlice } from "../../lib/slice-load.js";
 
 import { getPageRoute } from "./get-page.js";
 import { listPagesRoute } from "./list-pages.js";
 import { listTypesRoute } from "./list-types.js";
 
 /**
- * Content-write slice entry points, as { specifier, exportName }.
+ * Content-write slice entry points, as { specifier, exportName, load }.
  *
  * What defeats `tsc`'s resolution is the INDIRECTION, not the type: TypeScript
  * resolves `import("...")` only when the argument is a string-literal
- * EXPRESSION written at the call site. Reading the specifier from a variable
- * makes it unresolvable regardless of whether that variable's type is `string`
- * or a literal (verified both ways). `string` is used here for readability, not
- * because a literal type would leak.
+ * EXPRESSION written at the call site.
+ *
+ * WHICH indirection matters, and #5304 is the correction. This table used to
+ * hold the specifier as a string and the loop read it out per iteration — a
+ * shape `@vercel/nft` cannot evaluate either, so the deploy-time tracer did not
+ * emit these files and a deployed site shipped without them. A module-level
+ * constant dereferenced into `import()` is unresolvable to `tsc` and traceable
+ * to `nft`, so the strip and the deployment are both satisfied. `specifier` is
+ * carried for the drift message below and reads the same constant as `load`, so
+ * the two cannot disagree.
  */
-const WRITE_ROUTES: ReadonlyArray<{ specifier: string; exportName: string }> = [
-  { specifier: "./create.js", exportName: "createPageRoute" },
-  { specifier: "./update.js", exportName: "updatePageRoute" },
-  { specifier: "./delete.js", exportName: "deletePageRoute" },
+const CREATE_ROUTE = "./create.js";
+const UPDATE_ROUTE = "./update.js";
+const DELETE_ROUTE = "./delete.js";
+
+const WRITE_ROUTES: ReadonlyArray<{
+  specifier: string;
+  exportName: string;
+  load: () => Promise<unknown>;
+}> = [
+  {
+    specifier: CREATE_ROUTE,
+    exportName: "createPageRoute",
+    load: () => import(CREATE_ROUTE),
+  },
+  {
+    specifier: UPDATE_ROUTE,
+    exportName: "updatePageRoute",
+    load: () => import(UPDATE_ROUTE),
+  },
+  {
+    specifier: DELETE_ROUTE,
+    exportName: "deletePageRoute",
+    load: () => import(DELETE_ROUTE),
+  },
 ];
 
 export const contentRoutes: FastifyPluginAsync = async (fastify) => {
@@ -51,8 +78,8 @@ export const contentRoutes: FastifyPluginAsync = async (fastify) => {
   await fastify.register(getPageRoute);
 
   if (isModuleEnabled("content-write")) {
-    for (const { specifier, exportName } of WRITE_ROUTES) {
-      const mod = (await import(specifier)) as Record<
+    for (const { specifier, exportName, load } of WRITE_ROUTES) {
+      const mod = (await loadSlice(specifier, load)) as Record<
         string,
         FastifyPluginAsync | undefined
       >;

package/templates/apps/api/src/routes/project-listings/__tests__/configured-application.test.ts

@@ -1,3 +1,6 @@
+// Not marked oss: false (D-48/#5366 escalation) — tests the
+// always-shipping project-listings anonymous surface; see
+// routes/project-listings/me.ts's header comment.
 /**
  * @file configured-application.test.ts
  *
@@ -43,6 +46,13 @@ jest.mock("../../../lib/prisma.js");
 
 jest.mock("@working-theory/email", () => ({
   sendLeadNotification: jest.fn().mockResolvedValue({ ok: true, messageId: "msg-test" }),
+  // #5406 — `start` now reaches the resume email. Declared here for the reason
+  // docs/lessons/project-listings/04 records: a mock factory that omits an
+  // export the code under test calls leaves it `undefined` at the callsite.
+  // These suites configure no `resumeEmail`, so the send short-circuits before
+  // this is reached; it is declared so a future fixture that DOES configure
+  // one fails on its assertion rather than on a missing mock.
+  sendListingResumeEmail: jest.fn().mockResolvedValue({ ok: true, messageId: "msg-resume" }),
 }));
 
 jest.mock("@working-theory/license", () => ({
@@ -217,6 +227,13 @@ function installStore(): void {
       anythingElse: null,
       address: null,
       questions: null,
+      // #5407 — a row written before the columns existed, and a freshly
+      // started draft on a site that asks for one name line: parts null,
+      // no phone, no verification stamp.
+      founderFirstName: null,
+      founderLastName: null,
+      founderPhone: null,
+      emailVerifiedAt: null,
       founderCompany: null,
       leadId: null,
       headline: null,

package/templates/apps/api/src/routes/project-listings/__tests__/drafts.test.ts

@@ -1,3 +1,6 @@
+// Not marked oss: false (D-48/#5366 escalation) — tests the
+// always-shipping project-listings anonymous surface; see
+// routes/project-listings/me.ts's header comment.
 /**
  * @file drafts.test.ts
  *
@@ -40,6 +43,13 @@ jest.mock("../../../lib/prisma.js");
 
 jest.mock("@working-theory/email", () => ({
   sendLeadNotification: jest.fn().mockResolvedValue({ ok: true, messageId: "msg-test" }),
+  // #5406 — `start` now reaches the resume email. Declared here for the reason
+  // docs/lessons/project-listings/04 records: a mock factory that omits an
+  // export the code under test calls leaves it `undefined` at the callsite.
+  // These suites configure no `resumeEmail`, so the send short-circuits before
+  // this is reached; it is declared so a future fixture that DOES configure
+  // one fails on its assertion rather than on a missing mock.
+  sendListingResumeEmail: jest.fn().mockResolvedValue({ ok: true, messageId: "msg-resume" }),
 }));
 
 jest.mock("@working-theory/license", () => ({
@@ -193,6 +203,13 @@ function installStore(): void {
         anythingElse: null,
         address: null,
         questions: null,
+        // #5407 — a row written before the columns existed, and a freshly
+        // started draft on a site that asks for one name line: parts null,
+        // no phone, no verification stamp.
+        founderFirstName: null,
+        founderLastName: null,
+        founderPhone: null,
+        emailVerifiedAt: null,
         founderCompany: null,
         leadId: null,
         headline: null,