create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,141 @@
+/**
+ * @file module-exclusion.test.ts
+ * @description Module-exclusion regression test (S1, #5088).
+ *
+ * Proves the mechanical claim card S1 exists to make true: when a paid
+ * module is excluded (`AILK_ENABLED_MODULES` omits it), none of the HTTP
+ * routes that module contributes register — Fastify's default 404 is the
+ * signal, since a request to an unregistered route always 404s regardless
+ * of auth/validation state, while a registered-but-rejected request 4xxs
+ * with a DIFFERENT code (401/403/400/...). This is the runtime half of "a
+ * route and its MCP tool appear or vanish together" (API↔MCP parity) — see
+ * the sibling `apps/mcp/__tests__/module-exclusion.test.ts`.
+ *
+ * Reverting one of `server.ts`'s `isModuleEnabled(...)` conditionals makes
+ * the matching case below fail RED — see #5088 S1 verification notes.
+ *
+ * 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;
+
+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;
+    }
+  }
+}
+
+// One representative route per module-conditional registration block in
+// server.ts. `always404WhenExcluded` routes are expected to 404 ONLY when
+// their module is absent; every other module stays enabled for each case so
+// a bug that over-excludes (drops an unrelated module's route too) is also
+// caught by the "still registered" assertions below.
+const MODULE_ROUTES: Record<string, { method: 'GET' | 'POST'; url: string }[]> =
+  {
+    'multi-tenant': [
+      { method: 'GET', url: '/v1/workspaces' },
+      { method: 'GET', url: '/v1/billing' },
+      { method: 'GET', url: '/v1/waitlist-experiments' },
+      { method: 'GET', url: '/v1/project-listings' },
+    ],
+    scheduling: [{ method: 'GET', url: '/v1/schedule/availability' }],
+    'content-write': [{ method: 'POST', url: '/v1/content/BlogPosting' }],
+  };
+
+const ALL_MODULES = Object.keys(MODULE_ROUTES);
+
+describe('Module exclusion — registration vanishes with the module (S1, #5088)', () => {
+  let app: App;
+
+  afterEach(async () => {
+    if (app) {
+      await app.close();
+      app = undefined;
+    }
+    delete process.env.AILK_ENABLED_MODULES;
+  });
+
+  it.each(ALL_MODULES)(
+    "excluding '%s' 404s every route it owns, while every OTHER module's routes stay registered",
+    async (excluded) => {
+      const enabled = ALL_MODULES.filter((m) => m !== excluded).join(',');
+      app = await withEnabledModules(enabled, () => build());
+
+      for (const { method, url } of MODULE_ROUTES[excluded]!) {
+        const res = await app.inject({ method, url });
+        expect(res.statusCode).toBe(404);
+      }
+
+      for (const other of ALL_MODULES) {
+        if (other === excluded) continue;
+        for (const { method, url } of MODULE_ROUTES[other]!) {
+          const res = await app.inject({ method, url });
+          expect(res.statusCode).not.toBe(404);
+        }
+      }
+    },
+  );
+
+  it('with every module enabled (the default), every module route registers — no over-exclusion', async () => {
+    app = await build();
+    for (const routes of Object.values(MODULE_ROUTES)) {
+      for (const { method, url } of routes) {
+        const res = await app.inject({ method, url });
+        expect(res.statusCode).not.toBe(404);
+      }
+    }
+    // Free/never-gate surfaces are unaffected by any module exclusion.
+    const health = await app.inject({ method: 'GET', url: '/health' });
+    expect(health.statusCode).toBe(200);
+    const contentTypes = await app.inject({
+      method: 'GET',
+      url: '/v1/content/types',
+    });
+    expect(contentTypes.statusCode).not.toBe(404);
+  });
+
+  it('excluding every paid module at once still serves the free surface', async () => {
+    app = await withEnabledModules('', () => build());
+    const health = await app.inject({ method: 'GET', url: '/health' });
+    expect(health.statusCode).toBe(200);
+    const contentTypes = await app.inject({
+      method: 'GET',
+      url: '/v1/content/types',
+    });
+    expect(contentTypes.statusCode).not.toBe(404);
+
+    for (const routes of Object.values(MODULE_ROUTES)) {
+      for (const { method, url } of routes) {
+        const res = await app.inject({ method, url });
+        expect(res.statusCode).toBe(404);
+      }
+    }
+  });
+});

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

@@ -204,4 +204,50 @@ describe('Parser scope — webhooks raw-body parser does not leak', () => {
       await server.close();
     }
   });
+
+  describe('per-scope rate-limit defaults (#5111, DEF-004)', () => {
+    // Real end-to-end behavior against the real in-house rate-limit
+    // middleware (NOT mocked — this repo's convention is to mock only real
+    // external boundaries, never an internal module, see the file header).
+    // aeoScope's `/v1/aeo/score/example` needs no DB/network (a bundled
+    // example, `loadExampleScore()`); flowsScope's `/v1/flows/:slug` with a
+    // schema-invalid slug returns 400 before any DB access — both let the
+    // onRequest rate-limit hook be the only thing under test, regardless of
+    // the eventual handler status.
+    it('caps aeoScope at the strict pre-#4730 default (10/min) — the 11th request 429s', async () => {
+      app = await build();
+      const ip = '198.51.100.11';
+
+      for (let i = 0; i < 10; i++) {
+        const res = await app.inject({
+          method: 'GET',
+          url: '/v1/aeo/score/example',
+          headers: { 'x-forwarded-for': ip },
+        });
+        expect(res.statusCode).not.toBe(429);
+      }
+
+      const eleventh = await app.inject({
+        method: 'GET',
+        url: '/v1/aeo/score/example',
+        headers: { 'x-forwarded-for': ip },
+      });
+      expect(eleventh.statusCode).toBe(429);
+    });
+
+    it('leaves flowsScope above the strict default — 11 requests never 429', async () => {
+      app = await build();
+      const ip = '198.51.100.12';
+
+      for (let i = 0; i < 11; i++) {
+        const res = await app.inject({
+          method: 'GET',
+          url: '/v1/flows/not-a-real-slug!!!',
+          headers: { 'x-forwarded-for': ip },
+        });
+        // Schema-invalid slug → 400, well before any rate limit or DB call.
+        expect(res.statusCode).toBe(400);
+      }
+    });
+  });
 });

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

@@ -0,0 +1,211 @@
+/**
+ * @file vercel-handler.test.ts
+ * @description Regression coverage for the two independent defects in the
+ * Vercel serverless adapter (#5168):
+ *
+ *  - request side: the adapter forwards the client's original content-length
+ *    verbatim, but the body it hands to inject() is a JS object that
+ *    light-my-request re-serializes itself. light-my-request only computes a
+ *    fresh content-length when the header is ABSENT (it does
+ *    `req.headers['content-length'] = req.headers['content-length'] || ...`)
+ *    — a stale header therefore survives and Fastify's content-length check
+ *    rejects any body whose re-serialized length differs from what the client
+ *    declared for the original bytes (FST_ERR_CTP_INVALID_CONTENT_LENGTH).
+ *  - response side: sending response.body (light-my-request's UTF-8-decoded
+ *    string) instead of response.rawPayload corrupts any non-UTF-8 response
+ *    by substituting U+FFFD for every invalid byte.
+ *
+ * The two request-side tests below drive a REAL minimal Fastify instance
+ * through the handler — the defect lives inside Fastify's own
+ * content-length check, so a mocked inject() cannot fail the way production
+ * fails. The response-side test mocks inject() because the assertion is
+ * about what the adapter forwards to res.send, not about Fastify's own
+ * behavior.
+ *
+ * Each test resets the module registry and re-mocks '../server' itself
+ * (rather than sharing one top-level jest.mock) because the handler
+ * memoizes its built server instance at module scope (getServer()) —
+ * without a fresh module per test, the first test's server would be reused
+ * by every later test regardless of what that test wants build() to return.
+ */
+
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+import Fastify from 'fastify';
+
+// ── Typed request/response stubs ────────────────────────────────────────────
+//
+// Minimal stubs that satisfy only the VercelRequest/VercelResponse surface
+// the handler actually reads/calls, each cast to the real type ONCE at a
+// dedicated boundary function — avoids the `as unknown as <T>` double
+// assertion pattern the rest of the call sites would otherwise repeat
+// (mirrors apps/api/src/lib/__tests__/require-paid-tier.test.ts's
+// `asReply`/`StubReply` pattern).
+
+interface MockVercelRequest {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body: unknown;
+  query: Record<string, string>;
+}
+
+function asRequest(stub: MockVercelRequest): VercelRequest {
+  // @ts-expect-error: stub satisfies the subset of VercelRequest the handler
+  // reads (method/url/headers/body/query); a full VercelRequest (extends
+  // http.IncomingMessage) cannot be constructed without a live connection.
+  return stub;
+}
+
+interface MockRes {
+  headersSent: boolean;
+  _status?: number;
+  _headers: Record<string, string>;
+  _sent?: unknown;
+  status(code: number): MockRes;
+  setHeader(key: string, value: string): MockRes;
+  getHeader(key: string): string | undefined;
+  send(body: unknown): MockRes;
+  json(body: unknown): MockRes;
+}
+
+function asResponse(stub: MockRes): VercelResponse {
+  // @ts-expect-error: stub satisfies the subset of VercelResponse the handler
+  // calls (status/setHeader/getHeader/send/json); a full VercelResponse
+  // (extends http.ServerResponse) cannot be constructed without a live
+  // connection.
+  return stub;
+}
+
+function makeRes(): MockRes {
+  const headers: Record<string, string> = {};
+  const res: MockRes = {
+    headersSent: false,
+    _headers: headers,
+    status(code: number) {
+      res._status = code;
+      return res;
+    },
+    setHeader(key: string, value: string) {
+      headers[key] = value;
+      return res;
+    },
+    getHeader(key: string) {
+      return headers[key];
+    },
+    send(body: unknown) {
+      res._sent = body;
+      return res;
+    },
+    json(body: unknown) {
+      res._sent = body;
+      return res;
+    },
+  };
+  return res;
+}
+
+// Re-required per test (after jest.resetModules()) rather than statically
+// imported — a static import can't reach a freshly reset module.
+function loadHandler(): (req: VercelRequest, res: VercelResponse) => Promise<void> {
+  return require('../vercel-handler').default;
+}
+
+describe('vercel-handler — request side: stale content-length (#5168)', () => {
+  let app: ReturnType<typeof Fastify>;
+
+  beforeEach(async () => {
+    jest.resetModules();
+    app = Fastify();
+    app.post('/echo', async (req) => req.body);
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it('accepts a JSON body serialized with indent=2', async () => {
+    jest.doMock('../server', () => ({ build: jest.fn().mockResolvedValue(app) }));
+    const handler = loadHandler();
+
+    const body = { hello: 'world', nested: { a: 1 } };
+    const pretty = JSON.stringify(body, null, 2);
+    const req: MockVercelRequest = {
+      method: 'POST',
+      url: '/echo',
+      headers: {
+        'content-type': 'application/json',
+        'content-length': String(Buffer.byteLength(pretty)),
+      },
+      body,
+      query: {},
+    };
+    const res = makeRes();
+
+    await handler(asRequest(req), asResponse(res));
+
+    expect(res._status).toBe(200);
+    expect(JSON.parse(res._sent as string)).toEqual(body);
+  });
+
+  it('accepts a compact JSON body plus a single trailing newline', async () => {
+    jest.doMock('../server', () => ({ build: jest.fn().mockResolvedValue(app) }));
+    const handler = loadHandler();
+
+    const body = { hello: 'world' };
+    const compactPlusNewline = JSON.stringify(body) + '\n';
+    const req: MockVercelRequest = {
+      method: 'POST',
+      url: '/echo',
+      headers: {
+        'content-type': 'application/json',
+        'content-length': String(Buffer.byteLength(compactPlusNewline)),
+      },
+      body,
+      query: {},
+    };
+    const res = makeRes();
+
+    await handler(asRequest(req), asResponse(res));
+
+    expect(res._status).toBe(200);
+    expect(JSON.parse(res._sent as string)).toEqual(body);
+  });
+});
+
+describe('vercel-handler — response side: binary round-trip (#5168)', () => {
+  beforeEach(() => {
+    jest.resetModules();
+  });
+
+  it('forwards rawPayload byte-identically for a non-UTF-8 response', async () => {
+    // '%PDF-' header followed by bytes that are invalid UTF-8 on their own
+    // (0x80, 0xFF are continuation/invalid bytes outside any valid sequence).
+    const rawPayload = Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2d, 0x80, 0xff, 0xfe]);
+    // What light-my-request's UTF-8-decoded `.body` would mangle those bytes
+    // into — every invalid byte replaced with U+FFFD.
+    const mangledBody = rawPayload.toString('utf8');
+    const inject = jest.fn().mockResolvedValue({
+      statusCode: 200,
+      headers: { 'content-type': 'application/pdf' },
+      body: mangledBody,
+      rawPayload,
+    });
+    jest.doMock('../server', () => ({ build: jest.fn().mockResolvedValue({ inject }) }));
+    const handler = loadHandler();
+
+    const req: MockVercelRequest = {
+      method: 'GET',
+      url: '/pdf',
+      headers: {},
+      body: undefined,
+      query: {},
+    };
+    const res = makeRes();
+
+    await handler(asRequest(req), asResponse(res));
+
+    expect(Buffer.isBuffer(res._sent)).toBe(true);
+    expect(Buffer.compare(res._sent as Buffer, rawPayload)).toBe(0);
+  });
+});

package/templates/apps/api/src/bin/abandon-sweep.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/* istanbul ignore file -- CLI bootstrap; the underlying runAbandonEmailSweep
+   logic is unit-tested in services/__tests__/abandon-email.test.ts. Mirrors
+   cli.ts's coverage-ignore rationale — real entry-point semantics run the
+   compiled dist directly, on the operator's own cron/scheduler cadence (D1:
+   no queue/timer infrastructure in this repo — an external scheduler runs
+   this command on whatever cadence the deployment chooses). */
+/**
+ * Abandon-email sweep CLI entry (#3962 D1).
+ *
+ * Dev: `pnpm --filter @working-theory/api abandon:sweep` (tsx, this file).
+ * Production: `node dist/bin/abandon-sweep.js` (the compiled entry, run by
+ * any external scheduler — Vercel Cron, GitHub Actions cron, plain crontab).
+ * The sweep is stateless and idempotent (D5), so overlap or a missed tick
+ * is harmless — the delay window is data, not a timer.
+ */
+import { runAbandonEmailSweep } from "../services/abandon-email.js";
+
+async function main(): Promise<void> {
+  const result = await runAbandonEmailSweep();
+
+  if (!result.ok) {
+    console.error(
+      `[abandon-sweep] ${result.error.kind}: ${result.error.message}`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`[abandon-sweep] ${JSON.stringify(result.summary)}`);
+}
+
+main().catch((err: unknown) => {
+  // Belt-and-suspenders (code-review finding on #3962's acceptance PR):
+  // runAbandonEmailSweep already catches internally and returns a
+  // structured `unexpected_error` result, so this path is unreachable in
+  // practice — it exists only to prevent a bare unhandled-rejection crash
+  // if `main` itself ever throws before/around that call.
+  const message = err instanceof Error ? err.message : "Unknown error";
+  console.error(`[abandon-sweep] unexpected_error: ${message}`);
+  process.exitCode = 1;
+});

package/templates/apps/api/src/bin/deliverable-resend.ts

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/* istanbul ignore file -- CLI bootstrap; mirrors abandon-sweep.ts's coverage-ignore
+   rationale — the underlying list/resend logic is unit-tested at the service
+   layer (services/__tests__/deliverable-resend.test.ts), through the same
+   mocked-prisma double the fulfillment service tests already use. This file
+   is a thin entry: parse args, dispatch to list or resend, print, set exit
+   code. */
+/**
+ * Deliverable-grant resend CLI (#3998 D2/D4).
+ *
+ * Dev — list mode (read-only, default):
+ *   `pnpm --filter @working-theory/api deliverable:resend -- --site <siteId>
+ *   [--since <iso>] [--limit <n>]`
+ * Dev — resend mode (one grant):
+ *   `pnpm --filter @working-theory/api deliverable:resend -- --grant <grantId>`
+ * Production: `node dist/bin/deliverable-resend.js <same flags>`.
+ *
+ * No HTTP resend route exists (spec §2.2/D2) — this CLI is the sole recovery
+ * path for a grant whose post-mint send never completed, run by the operator
+ * on their own machine/CI. List mode is the read-only default and can never
+ * send anything. `--grant` is always a deliberate, named, single-grant act
+ * (D4) — there is no bulk/`--all` mode; the operator loops over the list
+ * output if several need resending.
+ */
+import {
+  listSendlessGrants,
+  resendDeliverableGrant,
+} from "../services/deliverable-fulfillment.js";
+
+type ParsedArgs = {
+  site?: string | undefined;
+  since?: string | undefined;
+  limit?: string | undefined;
+  grant?: string | undefined;
+};
+
+/** Minimal `--flag value` parser — no external dependency for a 4-flag CLI. */
+function parseArgs(argv: string[]): ParsedArgs {
+  const out: ParsedArgs = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const flag = argv[i];
+    const value = argv[i + 1];
+    if (flag === "--site") out.site = value;
+    else if (flag === "--since") out.since = value;
+    else if (flag === "--limit") out.limit = value;
+    else if (flag === "--grant") out.grant = value;
+    else continue;
+    i += 1;
+  }
+  return out;
+}
+
+async function runResend(grantId: string): Promise<void> {
+  const result = await resendDeliverableGrant(grantId);
+
+  if (!result.ok) {
+    console.error(
+      `[deliverable-resend] ${result.error.kind}: ${result.error.message}`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(
+    `[deliverable-resend] grant="${grantId}" outcome="${result.outcome}"`,
+  );
+  if (result.outcome !== "sent") {
+    process.exitCode = 1;
+  }
+}
+
+async function runList(args: ParsedArgs): Promise<void> {
+  if (!args.site) {
+    console.error(
+      "[deliverable-resend] usage: --site <siteId> [--since <iso>] [--limit <n>]",
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let since: Date | undefined;
+  if (args.since !== undefined) {
+    since = new Date(args.since);
+    if (Number.isNaN(since.getTime())) {
+      console.error(
+        `[deliverable-resend] invalid --since value: "${args.since}"`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+  } else {
+    // D4: every historical (pre-migration) grant reads sendStatus IS NULL,
+    // so an unfiltered first run on an established site lists every grant
+    // ever minted — most of which were, in fact, delivered via the prior
+    // log-only path. The caveat is printed, not silently assumed away.
+    console.log(
+      "[deliverable-resend] no --since given — listing EVERY sendless grant " +
+        "for this site, including pre-migration rows that predate this " +
+        "column and may already have been delivered.",
+    );
+  }
+
+  let limit: number | undefined;
+  if (args.limit !== undefined) {
+    limit = Number.parseInt(args.limit, 10);
+    if (!Number.isInteger(limit) || limit <= 0) {
+      console.error(
+        `[deliverable-resend] invalid --limit value: "${args.limit}"`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  const rows = await listSendlessGrants({
+    siteId: args.site,
+    ...(since !== undefined && { since }),
+    ...(limit !== undefined && { limit }),
+  });
+
+  for (const row of rows) {
+    console.log(JSON.stringify(row));
+  }
+  console.log(`[deliverable-resend] ${rows.length} sendless grant(s)`);
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.grant) {
+    await runResend(args.grant);
+  } else {
+    await runList(args);
+  }
+}
+
+main().catch((err: unknown) => {
+  // Belt-and-suspenders (mirrors abandon-sweep.ts) — an unexpected throw
+  // (a bad DB connection, etc.) still exits non-zero with a structured
+  // message rather than an unhandled-rejection crash.
+  const message = err instanceof Error ? err.message : "Unknown error";
+  console.error(`[deliverable-resend] unexpected_error: ${message}`);
+  process.exitCode = 1;
+});