create-ailk 0.1.1 → 0.3.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", () => ({
@@ -190,6 +200,17 @@ function installStore(): void {
     },
   );
 
+  // #5275 — the grant write `start` makes after the row. Append-only; it only
+  // needs to resolve here (drafts.test.ts asserts on what it is called with).
+  (prisma.consentGrant.createMany as jest.Mock).mockImplementation(
+    ({ data }: { data: Row[] }) => Promise.resolve({ count: data.length }),
+  );
+
+  // #5275 — `start` writes the row and its grant in one interactive
+  // transaction; the mock hands the same store-backed client through.
+  (prisma.$transaction as jest.Mock).mockImplementation(
+    async (fn: (tx: typeof prisma) => Promise<unknown>) => fn(prisma),
+  );
   (prisma.projectListing.create as jest.Mock).mockImplementation(({ data }: { data: Row }) => {
     const now = new Date();
     const row: Row = {
@@ -206,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", () => ({
@@ -52,8 +62,15 @@ jest.mock("@working-theory/license", () => ({
   }),
 }));
 
+import {
+  resolveConsentStatement,
+  SITE_CONSENT_CONFIG_DEFAULTS,
+} from "@working-theory/validation";
+
 import { prisma } from "../../../lib/prisma.js";
 import { setupLeadFileEnv } from "../../../__tests__/factories/lead-fixture";
+import {
+  MAX_CONSENT_KEYS, UNRECOVERABLE_CONSENT_STATEMENT } from "../../../services/consent.js";
 import { patchProjectListingDraftRoute } from "../patch-draft.js";
 import { startProjectListingRoute } from "../start.js";
 import { submitProjectListingRoute } from "../submit.js";
@@ -164,6 +181,11 @@ function installStore(): void {
     },
   );
 
+  // #5275 — `start` writes the row and its grant in one interactive
+  // transaction; the mock hands the same store-backed client through.
+  (prisma.$transaction as jest.Mock).mockImplementation(
+    async (fn: (tx: typeof prisma) => Promise<unknown>) => fn(prisma),
+  );
   (prisma.projectListing.create as jest.Mock).mockImplementation(
     ({ data }: { data: Row }) => {
       const now = new Date();
@@ -181,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,
@@ -226,6 +255,12 @@ function installStore(): void {
       return Promise.resolve({ count: matched.length });
     },
   );
+
+  // #5275 — the grant write `start` now makes. Append-only, so the mock only
+  // needs to resolve; the start tests below assert on what it was called with.
+  (prisma.consentGrant.createMany as jest.Mock).mockImplementation(
+    ({ data }: { data: Row[] }) => Promise.resolve({ count: data.length }),
+  );
 }
 
 // ─── Helpers ────────────────────────────────────────────────────────────────
@@ -335,6 +370,115 @@ describe("the draft lifecycle (#5036 D1)", () => {
     expect(rows).toHaveLength(0);
   });
 
+  // ── start: the consent grant (#5275 D7/D11) ──
+
+  it.each([
+    ["DECLINES the required purpose", { service_terms: false }],
+    ["is EMPTY beside the literal", {}],
+    ["OMITS the required purpose", { marketing: true }],
+  ])(
+    "start: a consents map that %s is a 400 and creates no row and no grant",
+    async (_label, consents) => {
+      const res = await app.inject({
+        method: "POST",
+        url: "/v1/project-listings",
+        payload: { ...START_PAYLOAD, consents, locale: "en" },
+      });
+      expect(res.statusCode).toBe(400);
+      const body = res.json() as { ok: boolean; error: { code: string; message: string } };
+      expect(body.ok).toBe(false);
+      expect(body.error.code).toBe("invalid_input");
+      expect(body.error.message).toMatch(/service_terms/);
+      expect(rows).toHaveLength(0);
+      expect(prisma.consentGrant.createMany).not.toHaveBeenCalled();
+    },
+  );
+
+  it("start: a consents map with more than MAX_CONSENT_KEYS purposes is a 400", async () => {
+    const consents: Record<string, boolean> = { service_terms: true };
+    for (let i = 0; i < MAX_CONSENT_KEYS; i += 1) consents[`junk_${i}`] = true;
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/project-listings",
+      payload: { ...START_PAYLOAD, consents, locale: "en" },
+    });
+    expect(res.statusCode).toBe(400);
+    expect(rows).toHaveLength(0);
+  });
+
+  it("start: a grant write that fails takes the row with it — one transaction, no stranded listing", async () => {
+    (prisma.$transaction as jest.Mock).mockImplementation(
+      async (fn: (tx: typeof prisma) => Promise<unknown>) => {
+        const before = rows.length;
+        try {
+          return await fn(prisma);
+        } catch (err) {
+          rows.splice(before); // roll back the in-memory store
+          throw err;
+        }
+      },
+    );
+    (prisma.consentGrant.createMany as jest.Mock).mockRejectedValueOnce(new Error("db down"));
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/project-listings",
+      payload: { ...START_PAYLOAD, consents: { service_terms: true }, locale: "en" },
+    });
+    expect(res.statusCode).toBe(500);
+    expect(rows).toHaveLength(0);
+  });
+
+  it("start: a body carrying consents records one grant per purpose with the DEFAULT statement text", async () => {
+    const { id } = await startDraft(app, { consents: { service_terms: true }, locale: "en" });
+
+    // The expected wording is DERIVED from the registry the server resolves
+    // from, never retyped — the whole point is that the row carries the string
+    // the renderer showed, not a string this test happens to agree with.
+    const purpose = SITE_CONSENT_CONFIG_DEFAULTS.purposes[0]!;
+    const { statement } = resolveConsentStatement(purpose, "en");
+
+    expect(prisma.consentGrant.createMany).toHaveBeenCalledTimes(1);
+    const { data } = (prisma.consentGrant.createMany as jest.Mock).mock.calls[0]![0] as {
+      data: Row[];
+    };
+    expect(data).toHaveLength(1);
+    expect(data[0]).toMatchObject({
+      siteId: SITE_ID,
+      subjectType: "project_listing",
+      subjectId: id,
+      purposeId: "service_terms",
+      granted: true,
+      locale: "en",
+      statement,
+      statementHash: sha256(statement),
+    });
+    expect(data[0]!["statement"]).not.toBe(UNRECOVERABLE_CONSENT_STATEMENT);
+    // The row's own consentAt is untouched by the grant write (spec §2.3).
+    expect(rows[0]!["consentAt"]).toBeInstanceOf(Date);
+  });
+
+  it("start: a body carrying only the legacy literal records ONE grant marked unrecoverable", async () => {
+    const { id } = await startDraft(app);
+
+    expect(prisma.consentGrant.createMany).toHaveBeenCalledTimes(1);
+    const { data } = (prisma.consentGrant.createMany as jest.Mock).mock.calls[0]![0] as {
+      data: Row[];
+    };
+    expect(data).toHaveLength(1);
+    expect(data[0]).toMatchObject({
+      siteId: SITE_ID,
+      subjectType: "project_listing",
+      subjectId: id,
+      purposeId: "service_terms",
+      granted: true,
+      locale: "und",
+      statement: UNRECOVERABLE_CONSENT_STATEMENT,
+      statementHash: sha256(UNRECOVERABLE_CONSENT_STATEMENT),
+    });
+    // Never today's wording for a legacy call — that would fabricate evidence (D11).
+    expect(data[0]!["statement"]).not.toContain("You agree to being contacted");
+  });
+
   // ── patch ──
 
   it("patch: a SINGLE-field patch round-trips", async () => {