create-ailk 0.2.0 → 0.4.0

package/templates/apps/api/src/__tests__/vercel-handler.test.ts

@@ -32,6 +32,10 @@
 import type { VercelRequest, VercelResponse } from '@vercel/node';
 import Fastify from 'fastify';
 
+jest.mock('@working-theory/observability', () => ({
+  logger: { info: jest.fn(), error: jest.fn(), warn: jest.fn() },
+}));
+
 // ── Typed request/response stubs ────────────────────────────────────────────
 //
 // Minimal stubs that satisfy only the VercelRequest/VercelResponse surface
@@ -209,3 +213,158 @@ describe('vercel-handler — response side: binary round-trip (#5168)', () => {
     expect(Buffer.compare(res._sent as Buffer, rawPayload)).toBe(0);
   });
 });
+
+// ── #5332: one build() per process ──────────────────────────────────────────
+//
+// getServer() used to cache the RESOLVED instance and test it before two
+// awaits, so two invocations overlapping a cold start on one warm container
+// both saw null and both built a complete Fastify server. The fix caches the
+// in-flight promise instead. These tests drive getServer() through the default
+// handler — the handler's exported shape is byte-synced into consuming sites,
+// so getServer() stays module-private rather than being exported for the test.
+
+const COLD_START_REQUEST: MockVercelRequest = {
+  method: 'GET',
+  url: '/health',
+  headers: {},
+  body: undefined,
+  query: {},
+};
+
+function sentMessage(_res: MockRes): string {
+  // Re-required, not imported: jest.resetModules() gives each test a fresh
+  // mock instance, and the handler under test holds that fresh one.
+  const { logger } = require('@working-theory/observability') as {
+    logger: { error: jest.Mock };
+  };
+  const calls = logger.error.mock.calls.filter(
+    ([, msg]) => msg === '[Vercel Handler] Error handling request',
+  );
+  const last = calls[calls.length - 1];
+  return last ? String((last[0] as { err?: Error }).err?.message ?? '') : '';
+}
+
+describe('vercel-handler — one build per process (#5332)', () => {
+  beforeEach(() => {
+    jest.resetModules();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it('builds one server for two invocations that overlap a cold start', async () => {
+    // One shared deferred for both calls, so whichever build() calls happen
+    // all settle together — the assertion is on the CALL COUNT, and a test
+    // that hung when the second call won the cache would obscure it.
+    let resolveServer!: (instance: unknown) => void;
+    const serverReady = new Promise<unknown>((resolve) => {
+      resolveServer = resolve;
+    });
+    const inject = jest.fn().mockResolvedValue({
+      statusCode: 200,
+      headers: {},
+      body: 'ok',
+      rawPayload: Buffer.from('ok'),
+    });
+    const build = jest.fn(() => serverReady);
+    jest.doMock('../server', () => ({ build }));
+    const handler = loadHandler();
+
+    const resA = makeRes();
+    const resB = makeRes();
+    // Both started before either resolves: neither has a server yet.
+    const a = handler(asRequest(COLD_START_REQUEST), asResponse(resA));
+    const b = handler(asRequest(COLD_START_REQUEST), asResponse(resB));
+
+    // Drain the microtask queue so both calls have reached getServer() and
+    // awaited build() before the build is allowed to finish.
+    for (let i = 0; i < 10; i += 1) {
+      await new Promise((resolve) => setImmediate(resolve));
+    }
+
+    resolveServer({ inject });
+    await Promise.all([a, b]);
+
+    expect(build).toHaveBeenCalledTimes(1);
+    expect(resA._status).toBe(200);
+    expect(resB._status).toBe(200);
+  });
+
+  it('retries the build on the next invocation after a failed cold start', async () => {
+    const inject = jest.fn().mockResolvedValue({
+      statusCode: 200,
+      headers: {},
+      body: 'ok',
+      rawPayload: Buffer.from('ok'),
+    });
+    const build = jest
+      .fn()
+      .mockRejectedValueOnce(new Error('prisma connect refused'))
+      .mockResolvedValue({ inject });
+    jest.doMock('../server', () => ({ build }));
+    const handler = loadHandler();
+
+    const failed = makeRes();
+    await handler(asRequest(COLD_START_REQUEST), asResponse(failed));
+    expect(failed._status).toBe(500);
+    expect(sentMessage(failed)).toBe('Server build failed: prisma connect refused');
+
+    // A rejected promise left in the cache would serve this request the same
+    // failure forever without calling build() again.
+    const retried = makeRes();
+    await handler(asRequest(COLD_START_REQUEST), asResponse(retried));
+
+    expect(build).toHaveBeenCalledTimes(2);
+    expect(retried._status).toBe(200);
+  });
+
+  it('does not leak an absolute filesystem path in the 500 body (#5351)', async () => {
+    const leakyPath = '/home/deploy/apps/api/dist/list.js';
+    const build = jest.fn().mockRejectedValue(
+      new Error(`ERR_MODULE_NOT_FOUND file://${leakyPath}`)
+    );
+    jest.doMock('../server', () => ({ build }));
+    const handler = loadHandler();
+
+    const res = makeRes();
+    await handler(asRequest(COLD_START_REQUEST), asResponse(res));
+
+    expect(res._status).toBe(500);
+    expect(JSON.stringify(res._sent)).not.toContain(leakyPath);
+  });
+
+  it('still fires the build timeout with its original message', async () => {
+    jest.useFakeTimers();
+    // A module object carrying its own `then` is assimilated when the
+    // handler's `await import('./server.js')` resolves with it, so the
+    // dynamic import never settles — the production condition the 10s build
+    // timeout guards. `__esModule` keeps ts-jest's __importStar from copying
+    // the object and dropping `then`.
+    jest.doMock('../server', () => ({ __esModule: true, then: () => {} }));
+    const handler = loadHandler();
+
+    const res = makeRes();
+    const pending = handler(asRequest(COLD_START_REQUEST), asResponse(res));
+    await jest.advanceTimersByTimeAsync(10_000);
+    await pending;
+
+    expect(res._status).toBe(500);
+    expect(sentMessage(res)).toBe('Server build failed: Server build timeout after 10s');
+  });
+
+  it('still fires the init timeout with its original message', async () => {
+    jest.useFakeTimers();
+    const build = jest.fn(() => new Promise(() => {}));
+    jest.doMock('../server', () => ({ build }));
+    const handler = loadHandler();
+
+    const res = makeRes();
+    const pending = handler(asRequest(COLD_START_REQUEST), asResponse(res));
+    await jest.advanceTimersByTimeAsync(10_000);
+    await pending;
+
+    expect(res._status).toBe(500);
+    expect(sentMessage(res)).toBe('Server build failed: Server initialization timeout after 10s');
+  });
+});

package/templates/apps/api/src/__tests__/workspace-module-registration.test.ts

@@ -0,0 +1,166 @@
+/**
+ * @file workspace-module-registration.test.ts
+ * @description The `workspace || multi-tenant` registration matrix (#5371 D2).
+ *
+ * `workspace` cannot be folded into the sibling `module-exclusion.test.ts`:
+ * that suite's shape is "excluding module X 404s every route X owns", and the
+ * three routes here register under EITHER module, so excluding `workspace`
+ * while `multi-tenant` is on leaves them registered by design. That is the
+ * whole point of D2's gate, so it gets its own matrix.
+ *
+ * The three cases §5.1 names:
+ *
+ *   1. workspace only      — the three workspace-settings routes resolve for a
+ *                            single-tenant session; billing / workspace-session
+ *                            / org routes stay unregistered.
+ *   2. multi-tenant only   — everything resolves exactly as it did before this
+ *                            change (the regression floor).
+ *   3. both enabled        — each of workspaceConfigRoutes /
+ *                            workspaceGeneralRoutes / workspaceMembersRoutes
+ *                            registers exactly ONCE; Fastify throws on a
+ *                            duplicate route at build() time, so a successful
+ *                            build IS the assertion, backed by an explicit
+ *                            count over the router tree.
+ *
+ * "Resolves" is measured as "not Fastify's own 404". An unauthenticated
+ * request to a registered tenant route answers 401, never 404, so the two
+ * states are unambiguous — the same signal `module-exclusion.test.ts` uses.
+ *
+ * Mirrors `src/__tests__/server.test.ts`'s external-boundary mocks (CORS,
+ * rate-limit, email) — see that file's header for why each is mocked.
+ */
+
+jest.mock('@fastify/cors', () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock('@fastify/rate-limit', () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock('@working-theory/email', () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true }),
+}));
+
+import { build } from '../server';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- server is typed via Fastify generics; explicit any avoids pulling in the full FastifyInstance type here
+type App = any;
+
+const WS = 'wksp_00000000-0000-7000-8000-0000000000aa';
+
+/** The routes the widened gate must serve under EITHER module. */
+const SHARED_TENANT_ROUTES = [
+  { method: 'GET' as const, url: `/v1/workspaces/${WS}/theme` },
+  { method: 'GET' as const, url: `/v1/workspaces/${WS}/identity` },
+  { method: 'GET' as const, url: `/v1/workspaces/${WS}/seo` },
+  { method: 'GET' as const, url: `/v1/workspaces/${WS}/general` },
+  { method: 'GET' as const, url: `/v1/workspaces/${WS}/members` },
+];
+
+/** Routes that must stay multi-tenant-only — the gate's other half. */
+const MULTI_TENANT_ONLY_ROUTES = [
+  { method: 'GET' as const, url: '/v1/workspaces' },
+  { method: 'GET' as const, url: '/v1/billing' },
+  { method: 'GET' as const, url: '/v1/waitlist-experiments' },
+];
+
+async function withEnabledModules<T>(
+  enabled: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const prior = process.env.AILK_ENABLED_MODULES;
+  process.env.AILK_ENABLED_MODULES = enabled;
+  try {
+    return await fn();
+  } finally {
+    if (prior === undefined) {
+      delete process.env.AILK_ENABLED_MODULES;
+    } else {
+      process.env.AILK_ENABLED_MODULES = prior;
+    }
+  }
+}
+
+/** Every (method, path) pair Fastify's router holds, one per line. */
+function routeLines(app: App): string[] {
+  return (app.printRoutes({ commonPrefix: false }) as string)
+    .split('\n')
+    .map((line: string) => line.trim())
+    .filter(Boolean);
+}
+
+describe('workspace-settings registration matrix (#5371 D2)', () => {
+  let app: App;
+
+  afterEach(async () => {
+    if (app) {
+      await app.close();
+      app = undefined;
+    }
+    delete process.env.AILK_ENABLED_MODULES;
+  });
+
+  it("with 'workspace' enabled and 'multi-tenant' disabled, the five settings routes resolve", async () => {
+    app = await withEnabledModules('workspace', () => build());
+
+    for (const { method, url } of SHARED_TENANT_ROUTES) {
+      const res = await app.inject({ method, url });
+      expect({ url, status: res.statusCode }).toEqual({ url, status: 401 });
+    }
+  });
+
+  it("with 'workspace' alone, billing / workspace-session / org routes stay unregistered", async () => {
+    app = await withEnabledModules('workspace', () => build());
+
+    for (const { method, url } of MULTI_TENANT_ONLY_ROUTES) {
+      const res = await app.inject({ method, url });
+      expect({ url, status: res.statusCode }).toEqual({ url, status: 404 });
+    }
+  });
+
+  it("with 'multi-tenant' enabled and 'workspace' disabled, every route resolves as before", async () => {
+    app = await withEnabledModules('multi-tenant', () => build());
+
+    for (const { method, url } of [
+      ...SHARED_TENANT_ROUTES,
+      ...MULTI_TENANT_ONLY_ROUTES,
+    ]) {
+      const res = await app.inject({ method, url });
+      expect({ url, status: res.statusCode }).not.toEqual({ url, status: 404 });
+    }
+  });
+
+  it('with BOTH enabled, each shared route registers exactly once', async () => {
+    // build() itself is the first assertion: Fastify throws
+    // FST_ERR_DUPLICATED_ROUTE at registration time, so a double-registration
+    // never reaches the router tree to be counted.
+    app = await withEnabledModules('workspace,multi-tenant', () => build());
+
+    const lines = routeLines(app);
+    for (const segment of ['theme', 'identity', 'seo', 'general', 'members']) {
+      const matches = lines.filter((line) => line.includes(segment));
+      expect({ segment, count: matches.length }).toEqual({
+        segment,
+        count: 1,
+      });
+    }
+
+    for (const { method, url } of [
+      ...SHARED_TENANT_ROUTES,
+      ...MULTI_TENANT_ONLY_ROUTES,
+    ]) {
+      const res = await app.inject({ method, url });
+      expect({ url, status: res.statusCode }).not.toEqual({ url, status: 404 });
+    }
+  });
+
+  it('with neither enabled, none of the five settings routes registers', async () => {
+    app = await withEnabledModules('', () => build());
+
+    for (const { method, url } of SHARED_TENANT_ROUTES) {
+      const res = await app.inject({ method, url });
+      expect({ url, status: res.statusCode }).toEqual({ url, status: 404 });
+    }
+  });
+});

package/templates/apps/api/src/config/__tests__/modules.test.ts

@@ -0,0 +1,76 @@
+/**
+ * `isModuleEnabled()` default-flip regression test (D-44, #5368).
+ *
+ * Proves the mechanical claim #5368 exists to make true: an UNSET
+ * `AILK_ENABLED_MODULES` now gates every paid module OFF, the same as an
+ * explicit empty string — only an explicit allowlist turns modules on, and
+ * turns on exactly the modules it names.
+ *
+ * Reverting `enabledModules()`'s unset branch back to the `undefined`
+ * sentinel (S1, #5088's original shape) makes the "unset" cases below fail
+ * RED — see #5368 verification notes.
+ */
+
+import { isModuleEnabled } from '../modules';
+
+const RECOGNIZED_MODULES = [
+  'docs',
+  'multi-tenant',
+  'scheduling',
+  'content-write',
+] as const;
+
+describe('isModuleEnabled', () => {
+  const originalEnv = process.env.AILK_ENABLED_MODULES;
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      delete process.env.AILK_ENABLED_MODULES;
+    } else {
+      process.env.AILK_ENABLED_MODULES = originalEnv;
+    }
+  });
+
+  describe('AILK_ENABLED_MODULES unset', () => {
+    it.each(RECOGNIZED_MODULES)('returns false for %s', (moduleName) => {
+      delete process.env.AILK_ENABLED_MODULES;
+      expect(isModuleEnabled(moduleName)).toBe(false);
+    });
+  });
+
+  describe('AILK_ENABLED_MODULES=""', () => {
+    it.each(RECOGNIZED_MODULES)('returns false for %s', (moduleName) => {
+      process.env.AILK_ENABLED_MODULES = '';
+      expect(isModuleEnabled(moduleName)).toBe(false);
+    });
+  });
+
+  describe('AILK_ENABLED_MODULES as an explicit allowlist', () => {
+    it.each(RECOGNIZED_MODULES)(
+      'enables exactly the listed modules — %s on when named',
+      (moduleName) => {
+        process.env.AILK_ENABLED_MODULES = moduleName;
+        expect(isModuleEnabled(moduleName)).toBe(true);
+        for (const other of RECOGNIZED_MODULES) {
+          if (other === moduleName) continue;
+          expect(isModuleEnabled(other)).toBe(false);
+        }
+      },
+    );
+
+    it('enables every module named in a comma list, and no others', () => {
+      process.env.AILK_ENABLED_MODULES = 'multi-tenant,scheduling';
+      expect(isModuleEnabled('multi-tenant')).toBe(true);
+      expect(isModuleEnabled('scheduling')).toBe(true);
+      expect(isModuleEnabled('docs')).toBe(false);
+      expect(isModuleEnabled('content-write')).toBe(false);
+    });
+
+    it('trims whitespace and drops empty entries, same as before the flip', () => {
+      process.env.AILK_ENABLED_MODULES = ' multi-tenant , , scheduling ';
+      expect(isModuleEnabled('multi-tenant')).toBe(true);
+      expect(isModuleEnabled('scheduling')).toBe(true);
+      expect(isModuleEnabled('docs')).toBe(false);
+    });
+  });
+});

package/templates/apps/api/src/config/index.ts

@@ -39,6 +39,21 @@ export interface Config {
   // row's issueUrl stays null for a later retry via the PATCH route.
   AILK_GITHUB_REPO?: string;
   AILK_GITHUB_TOKEN?: string;
+
+  // The public origin this API is reachable at, e.g. https://api.example.com.
+  // Already consumed by the deliverable download link (#3961 D5); the OpenAPI
+  // `servers` block reads it too (#5306), since the spec is byte-synced into
+  // every consuming site and cannot name a host as a literal.
+  //
+  // This is the API's OWN origin, distinct from FRONTEND_URL (the site the
+  // browser loads) and from `_site.mdx`'s `baseUrl` (the site's public web
+  // origin). A deployment typically serves the site from example.com and this
+  // API from api.example.com, so neither of the other two can stand in.
+  //
+  // Optional: unset degrades the `servers` block to a document-relative
+  // origin, which stays correct for any agent that fetched the spec from this
+  // API. See resolveServers() in src/openapi/spec.ts.
+  AILK_PUBLIC_API_URL?: string;
 }
 
 function validateConfig(): Config {
@@ -85,6 +100,10 @@ function validateConfig(): Config {
     ...(process.env.AILK_GITHUB_TOKEN !== undefined && {
       AILK_GITHUB_TOKEN: process.env.AILK_GITHUB_TOKEN,
     }),
+
+    ...(process.env.AILK_PUBLIC_API_URL !== undefined && {
+      AILK_PUBLIC_API_URL: process.env.AILK_PUBLIC_API_URL,
+    }),
   };
 }
 

package/templates/apps/api/src/config/modules.ts

@@ -1,18 +1,18 @@
 /**
  * Paid-module presence — the registration-grain signal used by `server.ts`
  * to decide whether a paid module's routes (and their imports) are wired
- * into this build (S1, #5088).
+ * into this build (S1, #5088; defaulted off by D-44, #5368).
  *
  * `AILK_ENABLED_MODULES` is a comma-separated allowlist (e.g.
- * `"multi-tenant,scheduling"`). Unset means "every module on" — today's
- * behavior, unchanged for every existing deployment; an explicit empty
- * string (`""`) means "no paid modules" (the OSS-strip build target). This
- * mirrors `shouldMountTestAuth()`'s fail-open-by-default / explicit-opt-in
- * shape elsewhere in this file's sibling config.
+ * `"multi-tenant,scheduling"`). Unset means **no paid modules** — installed
+ * modules enable themselves explicitly; an explicit empty string (`""`)
+ * means the same (the OSS-strip build target); a list enables exactly the
+ * modules it names.
  *
- * Recognized module keys: `docs`, `multi-tenant`, `scheduling` (the
- * `ModuleName` vocabulary `packages/create-ailk/src/module-architecture.ts`
- * already models via `MODULE_SLICES`) plus `content-write` — the Pro
+ * Recognized module keys: `docs`, `multi-tenant`, `workspace`, `scheduling`,
+ * `signal-collectors`, `commerce` (the `ModuleName` vocabulary
+ * `packages/create-ailk/src/module-architecture.ts` already models via
+ * `MODULE_SLICES`) plus `content-write` — the Pro
  * content-write surface (`create`/`update`/`delete` under
  * `apps/api/src/routes/content/`). `content-write` is intentionally NOT a
  * `MODULE_SLICES` entry: it is not (yet) a `create-ailk --modules`
@@ -24,9 +24,9 @@
  * create-ailk's module types (outside its package allowlist anyway).
  */
 
-function enabledModules(): Set<string> | undefined {
+function enabledModules(): Set<string> {
   const raw = process.env.AILK_ENABLED_MODULES;
-  if (raw === undefined) return undefined; // undefined sentinel = "all enabled"
+  if (raw === undefined) return new Set(); // unset = no paid modules
   return new Set(
     raw
       .split(',')
@@ -37,7 +37,5 @@ function enabledModules(): Set<string> | undefined {
 
 /** Whether the named paid module's routes should register on this build/boot. */
 export function isModuleEnabled(moduleName: string): boolean {
-  const enabled = enabledModules();
-  if (enabled === undefined) return true;
-  return enabled.has(moduleName);
+  return enabledModules().has(moduleName);
 }

package/templates/apps/api/src/lib/__mocks__/prisma.ts

@@ -194,6 +194,9 @@ export const prisma = {
     findMany: jest.fn(),
     update: jest.fn(),
     updateMany: jest.fn(),
+    // `count` — the resume email's per-recipient send cap (#5406): how many
+    // drafts this address has started on this site inside the rolling window.
+    count: jest.fn(),
   },
   // ── Inbox namespace (WaitlistExperiment — #4661 D5) ──────────────────────
   // `upsert` — the ONLY write path into waitlist_experiments

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");
+  });
+});