create-ailk 0.16.0 → 0.18.0

package/templates/apps/mcp/__tests__/app-entry.test.ts

@@ -0,0 +1,325 @@
+/**
+ * The Vercel entry (#8070 D2, D5).
+ *
+ * `src/app.ts` awaits the boot at module level, which ts-jest's CommonJS
+ * compile cannot load — so, like `index.test.ts`, its shape is checked as
+ * source text, and its behaviour is exercised through `serverless-app.ts`,
+ * the part it delegates to.
+ *
+ * Acceptance criteria verified here (spec docs/specs/8070-spoke-mcp-vercel-backend-spec.md):
+ * - AC-4 (amendment 2): app.ts imports Fastify, caps a request with
+ *   `export const config = { maxDuration: 30 }`, builds the app from
+ *   SERVERLESS_FASTIFY_OPTIONS, configures it, awaits `app.ready()`, default-exports
+ *   `serverlessHandler(app)` (the `(req, res)` function Vercel's Node runtime
+ *   calls — a Fastify instance is not a shape it accepts) and never listens; the
+ *   options are `{ logger: false, trustProxy: trustOneHop }` — the spec's
+ *   `trustProxy: 1` is a no-op on Fastify 5.12 (pinned below), so the same
+ *   one-hop trust is expressed as a function; an `http.createServer` serving
+ *   `serverlessHandler(app)` answers `initialize` and a session-less `tools/list`
+ *   with MCP_HTTP_STATELESS unset.
+ * - AC-5: on the serverless app the daily cap keys on the LAST
+ *   X-Forwarded-For hop; the long-running app ignores the header.
+ * - AC-13: tsconfig.json names `module` and `moduleResolution`, and there is
+ *   no vercel.json.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { resolve } from "node:path";
+
+import Fastify, { type FastifyInstance } from "fastify";
+
+import { buildHttpTransportApp } from "../src/http-transport.js";
+import {
+  configureServerlessApp,
+  SERVERLESS_FASTIFY_OPTIONS,
+  serverlessHandler,
+  trustOneHop,
+} from "../src/serverless-app.js";
+
+// The hub call capture_lead makes after the guard is stubbed, as
+// http-transport.test.ts stubs checkout: only the guard's verdict is asserted.
+jest.mock("@working-theory/api-client", () => {
+  const actual = jest.requireActual("@working-theory/api-client");
+  return {
+    ...actual,
+    apiClient: {
+      ...actual.apiClient,
+      leads: {
+        ...actual.apiClient.leads,
+        submit: jest.fn().mockResolvedValue({
+          ok: true,
+          body: {
+            id: "lead_00000000-0000-7000-8000-000000008070",
+            persisted: "db",
+          },
+        }),
+      },
+    },
+  };
+});
+
+const VARS = [
+  "MCP_HTTP_STATELESS",
+  "MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP",
+  "MCP_CORS_WRITE_ALLOWED_ORIGINS",
+] as const;
+
+const saved: Partial<Record<(typeof VARS)[number], string | undefined>> = {};
+
+beforeEach(() => {
+  for (const name of VARS) {
+    saved[name] = process.env[name];
+    delete process.env[name];
+  }
+});
+
+afterEach(() => {
+  for (const name of VARS) {
+    const value = saved[name];
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+});
+
+async function mcpPost(
+  port: number,
+  payload: object,
+  headers: Record<string, string> = {},
+): Promise<Response> {
+  return fetch(`http://127.0.0.1:${port}/mcp`, {
+    method: "POST",
+    body: JSON.stringify(payload),
+    headers: {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+      ...headers,
+    },
+  });
+}
+
+async function listen(app: FastifyInstance): Promise<number> {
+  await app.listen({ host: "127.0.0.1", port: 0 });
+  return (app.server.address() as AddressInfo).port;
+}
+
+/** The app src/app.ts builds, minus the boot and the default export. */
+async function serverlessApp(): Promise<FastifyInstance> {
+  const app = Fastify(SERVERLESS_FASTIFY_OPTIONS);
+  await configureServerlessApp(app);
+  await app.ready();
+  return app;
+}
+
+/** Serve the app through the exact function Vercel's Node runtime calls. */
+async function serveHandler(
+  app: FastifyInstance,
+): Promise<{ server: Server; port: number }> {
+  const server = createServer(serverlessHandler(app));
+  await new Promise<void>((done) => server.listen(0, "127.0.0.1", done));
+  return { server, port: (server.address() as AddressInfo).port };
+}
+
+async function stop(server: Server | undefined): Promise<void> {
+  if (!server) return;
+  await new Promise<void>((done) => server.close(() => done()));
+}
+
+function captureLead(id: number, name: string): object {
+  return {
+    jsonrpc: "2.0",
+    id,
+    method: "tools/call",
+    params: {
+      name: "capture_lead",
+      arguments: {
+        name,
+        email: `${name.toLowerCase()}@example.com`,
+        message: "Interested in your services.",
+      },
+    },
+  };
+}
+
+describe("AC-4 — src/app.ts, read as source text", () => {
+  const src = readFileSync(resolve(__dirname, "../src/app.ts"), "utf-8");
+
+  it("imports Fastify by value, so Vercel's Node-backend detection finds it", () => {
+    expect(src).toContain('import Fastify from "fastify"');
+  });
+
+  it("awaits the shared boot, builds Fastify from the serverless options and configures it", () => {
+    expect(src).toContain("await bootMcp()");
+    expect(src).toContain("Fastify(SERVERLESS_FASTIFY_OPTIONS)");
+    expect(src).toContain("configureServerlessApp(app)");
+  });
+
+  it("boots before it builds the app, and readies it before it exports", () => {
+    expect(src.indexOf("await bootMcp()")).toBeLessThan(
+      src.indexOf("Fastify(SERVERLESS_FASTIFY_OPTIONS)"),
+    );
+    expect(src).toContain("await app.ready()");
+    expect(src.indexOf("configureServerlessApp(app)")).toBeLessThan(
+      src.indexOf("await app.ready()"),
+    );
+  });
+
+  it("caps one request at 30 s with a literal exported config Vercel reads statically", () => {
+    expect(src).toContain("export const config = { maxDuration: 30 }");
+  });
+
+  it("default-exports the handler, not the app, and never listens", () => {
+    expect(src).toContain("export default serverlessHandler(app)");
+    expect(src).not.toContain("export default app;");
+    expect(src).not.toContain("listen(");
+  });
+});
+
+describe("AC-13 — Vercel's type-check keeps strict", () => {
+  it("tsconfig.json names module and moduleResolution, so @vercel/node's fixConfig leaves strict alone", () => {
+    const tsconfig = JSON.parse(
+      readFileSync(resolve(__dirname, "../tsconfig.json"), "utf-8"),
+    ) as { compilerOptions: Record<string, unknown> };
+    expect(tsconfig.compilerOptions["module"]).toBe("ESNext");
+    expect(tsconfig.compilerOptions["moduleResolution"]).toBe("bundler");
+  });
+
+  it("there is no vercel.json (its functions pattern is rejected for the fastify builder)", () => {
+    expect(existsSync(resolve(__dirname, "../vercel.json"))).toBe(false);
+  });
+});
+
+describe("AC-4 — the serverless options and the configured app", () => {
+  let app: FastifyInstance | undefined;
+  let server: Server | undefined;
+  let port = 0;
+
+  afterEach(async () => {
+    await stop(server);
+    await app?.close();
+    app = undefined;
+    server = undefined;
+  });
+
+  it("SERVERLESS_FASTIFY_OPTIONS is { logger: false, trustProxy: trustOneHop }", () => {
+    expect(SERVERLESS_FASTIFY_OPTIONS).toEqual({
+      logger: false,
+      trustProxy: trustOneHop,
+    });
+  });
+
+  it("trustOneHop trusts the immediate peer (hop 0) and nothing behind it, whatever its address", () => {
+    expect(trustOneHop("127.0.0.1", 0)).toBe(true);
+    expect(trustOneHop("10.0.0.1", 0)).toBe(true);
+    expect(trustOneHop("9.9.9.9", 1)).toBe(false);
+    expect(trustOneHop("1.1.1.1", 2)).toBe(false);
+  });
+
+  it("why not trustProxy: 1 — this Fastify treats a numeric hop count as trust-nothing", async () => {
+    const numeric = Fastify({ logger: false, trustProxy: 1 });
+    numeric.get("/ip", async (request) => ({ ip: request.ip }));
+    const res = await numeric.inject({
+      url: "/ip",
+      remoteAddress: "127.0.0.1",
+      headers: { "x-forwarded-for": "3.3.3.3, 8.8.8.8" },
+    });
+    await numeric.close();
+
+    // Every caller would key on the edge's address.
+    expect(res.json()).toEqual({ ip: "127.0.0.1" });
+  });
+
+  it("serverlessHandler(app) is a (req, res) function", async () => {
+    app = await serverlessApp();
+    expect(typeof serverlessHandler(app)).toBe("function");
+  });
+
+  it("with MCP_HTTP_STATELESS unset, an http.createServer serving serverlessHandler(app) answers initialize and then a session-less tools/list", async () => {
+    app = await serverlessApp();
+    ({ server, port } = await serveHandler(app));
+
+    const init = await mcpPost(port, {
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2025-03-26",
+        capabilities: {},
+        clientInfo: { name: "app-entry-test", version: "1.0.0" },
+      },
+    });
+    expect(init.status).toBe(200);
+    const initBody = (await init.json()) as {
+      result?: { serverInfo?: { name?: string } };
+    };
+    expect(initBody.result?.serverInfo).toMatchObject({ name: "ailk" });
+
+    const list = await mcpPost(port, {
+      jsonrpc: "2.0",
+      id: 2,
+      method: "tools/list",
+      params: {},
+    });
+    expect(list.status).toBe(200);
+  });
+});
+
+describe("AC-5 — the daily cap keys on the last X-Forwarded-For hop", () => {
+  let app: FastifyInstance | undefined;
+  let server: Server | undefined;
+
+  afterEach(async () => {
+    await stop(server);
+    await app?.close();
+    app = undefined;
+    server = undefined;
+  });
+
+  it("serverless app: two callers sharing a last hop are one caller; a different last hop is another", async () => {
+    process.env["MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP"] = "1";
+    // Set explicitly so the write-origin check is never what refuses a call.
+    process.env["MCP_CORS_WRITE_ALLOWED_ORIGINS"] = "*";
+    app = await serverlessApp();
+    const { server: served, port } = await serveHandler(app);
+    server = served;
+
+    const first = await mcpPost(port, captureLead(10, "First"), {
+      "x-forwarded-for": "1.1.1.1, 9.9.9.9",
+    });
+    expect(first.status).toBe(200);
+
+    const second = await mcpPost(port, captureLead(11, "Second"), {
+      "x-forwarded-for": "2.2.2.2, 9.9.9.9",
+    });
+    expect(second.status).toBe(403);
+    const refusal = (await second.json()) as { error?: string };
+    expect(refusal.error).toBe("daily capture_lead cap reached for this IP");
+
+    const third = await mcpPost(port, captureLead(12, "Third"), {
+      "x-forwarded-for": "3.3.3.3, 8.8.8.8",
+    });
+    expect(third.status).toBe(200);
+  });
+
+  it("long-running app (no trustProxy): the header is ignored — every call is the socket's address", async () => {
+    app = await buildHttpTransportApp({
+      path: "/mcp",
+      stateless: true,
+      rateLimits: { readPerMin: 60, writePerMin: 10 },
+      cors: { writeAllowedOrigins: ["*"] },
+      abuse: { captureLeadDailyCapPerIp: 1, blockedUserAgents: "" },
+    });
+    const port = await listen(app);
+
+    const first = await mcpPost(port, captureLead(20, "First"), {
+      "x-forwarded-for": "3.3.3.3",
+    });
+    expect(first.status).toBe(200);
+
+    const second = await mcpPost(port, captureLead(21, "Second"), {
+      "x-forwarded-for": "4.4.4.4",
+    });
+    expect(second.status).toBe(403);
+  });
+});

package/templates/apps/mcp/__tests__/boot.test.ts

@@ -0,0 +1,203 @@
+/**
+ * The shared boot module (#8070 D1, D2): `readStatelessEnv` and
+ * `httpTransportConfigFromEnv`, which both entrypoints read the environment
+ * through.
+ *
+ * Acceptance criteria verified here (spec docs/specs/8070-spoke-mcp-vercel-backend-spec.md):
+ * - AC-1: MCP_HTTP_STATELESS=true selects the stateless transport — a
+ *   session-less tools/list answers 200 and lists list_pages.
+ * - AC-2: each entry's default, and the accepted spellings.
+ * - AC-3: a bad value throws naming the variable; a blank per-minute rate
+ *   falls back to its default rather than disabling the limit.
+ *
+ * Real sockets on port 0, the pattern of `http-transport.test.ts`.
+ */
+
+import type { AddressInfo } from "node:net";
+
+import type { FastifyInstance } from "fastify";
+
+import { httpTransportConfigFromEnv, readStatelessEnv } from "../src/boot.js";
+import { buildHttpTransportApp } from "../src/http-transport.js";
+
+const VARS = [
+  "MCP_HTTP_STATELESS",
+  "MCP_HTTP_PORT",
+  "MCP_HTTP_PATH",
+  "MCP_RATE_LIMIT_READ_PER_MIN",
+  "MCP_RATE_LIMIT_WRITE_PER_MIN",
+  "MCP_CORS_WRITE_ALLOWED_ORIGINS",
+  "MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP",
+  "MCP_ABUSE_START_PURCHASE_DAILY_CAP",
+  "MCP_ABUSE_BLOCKED_USER_AGENTS",
+] as const;
+
+const saved: Partial<Record<(typeof VARS)[number], string | undefined>> = {};
+
+beforeEach(() => {
+  for (const name of VARS) {
+    saved[name] = process.env[name];
+    delete process.env[name];
+  }
+});
+
+afterEach(() => {
+  for (const name of VARS) {
+    const value = saved[name];
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+});
+
+const TOOLS_LIST = { jsonrpc: "2.0", id: 1, method: "tools/list", params: {} };
+
+async function listen(app: FastifyInstance): Promise<number> {
+  await app.listen({ host: "127.0.0.1", port: 0 });
+  return (app.server.address() as AddressInfo).port;
+}
+
+async function postToolsList(port: number): Promise<Response> {
+  return fetch(`http://127.0.0.1:${port}/mcp`, {
+    method: "POST",
+    body: JSON.stringify(TOOLS_LIST),
+    headers: {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+    },
+  });
+}
+
+/** The app the long-running entry builds, from the environment as it stands. */
+async function appFromEnv(defaultStateless: boolean): Promise<FastifyInstance> {
+  const { port: _port, ...config } = httpTransportConfigFromEnv();
+  return buildHttpTransportApp({
+    ...config,
+    stateless: readStatelessEnv(defaultStateless),
+  });
+}
+
+describe("AC-1 — MCP_HTTP_STATELESS=true selects the stateless transport", () => {
+  let app: FastifyInstance | undefined;
+
+  afterEach(async () => {
+    await app?.close();
+    app = undefined;
+  });
+
+  it("answers a tools/list with no Mcp-Session-Id with 200, listing list_pages", async () => {
+    process.env["MCP_HTTP_STATELESS"] = "true";
+    app = await appFromEnv(false);
+    const port = await listen(app);
+
+    const res = await postToolsList(port);
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      result?: { tools?: Array<{ name: string }> };
+    };
+    const names = (body.result?.tools ?? []).map((tool) => tool.name);
+    expect(names).toContain("list_pages");
+  });
+});
+
+describe("AC-2 — each entry's default, and the accepted spellings", () => {
+  let app: FastifyInstance | undefined;
+
+  afterEach(async () => {
+    await app?.close();
+    app = undefined;
+  });
+
+  it("unset, the long-running default is false — and a session-less tools/list is 400 (today's stateful behaviour)", async () => {
+    expect(readStatelessEnv(false)).toBe(false);
+
+    app = await appFromEnv(false);
+    const port = await listen(app);
+
+    const res = await postToolsList(port);
+    expect(res.status).toBe(400);
+  });
+
+  it("unset, the serverless default is true", () => {
+    expect(readStatelessEnv(true)).toBe(true);
+  });
+
+  it("an empty value takes the default", () => {
+    process.env["MCP_HTTP_STATELESS"] = "";
+    expect(readStatelessEnv(true)).toBe(true);
+    expect(readStatelessEnv(false)).toBe(false);
+  });
+
+  it.each(["false", "0", "FALSE"])("%s reads as false", (value) => {
+    process.env["MCP_HTTP_STATELESS"] = value;
+    expect(readStatelessEnv(true)).toBe(false);
+  });
+
+  it.each(["1", "True"])("%s reads as true", (value) => {
+    process.env["MCP_HTTP_STATELESS"] = value;
+    expect(readStatelessEnv(false)).toBe(true);
+  });
+
+  it("surrounding whitespace is trimmed", () => {
+    process.env["MCP_HTTP_STATELESS"] = "  true ";
+    expect(readStatelessEnv(false)).toBe(true);
+  });
+});
+
+describe("AC-3 — a bad value fails the boot; a blank rate does not disable the limit", () => {
+  it("a value outside the four spellings throws an Error naming MCP_HTTP_STATELESS", () => {
+    process.env["MCP_HTTP_STATELESS"] = "yes";
+    expect(() => readStatelessEnv(true)).toThrow(Error);
+    expect(() => readStatelessEnv(true)).toThrow(/MCP_HTTP_STATELESS/);
+  });
+
+  it("MCP_RATE_LIMIT_READ_PER_MIN='' yields the default 60, never NaN", () => {
+    process.env["MCP_RATE_LIMIT_READ_PER_MIN"] = "";
+    expect(httpTransportConfigFromEnv().rateLimits.readPerMin).toBe(60);
+  });
+
+  it("MCP_RATE_LIMIT_WRITE_PER_MIN='' yields the default 10, never NaN", () => {
+    process.env["MCP_RATE_LIMIT_WRITE_PER_MIN"] = "";
+    expect(httpTransportConfigFromEnv().rateLimits.writePerMin).toBe(10);
+  });
+});
+
+describe("httpTransportConfigFromEnv — today's reading of every other variable", () => {
+  it("unset, it returns today's defaults", () => {
+    expect(httpTransportConfigFromEnv()).toEqual({
+      port: 8080,
+      path: "/mcp",
+      rateLimits: { readPerMin: 60, writePerMin: 10 },
+      cors: { writeAllowedOrigins: [] },
+      abuse: {
+        captureLeadDailyCapPerIp: 50,
+        startPurchaseDailyCapPerIp: 20,
+        blockedUserAgents: "",
+      },
+    });
+  });
+
+  it("set, it reads each variable as src/index.ts did", () => {
+    process.env["MCP_HTTP_PORT"] = "9090";
+    process.env["MCP_HTTP_PATH"] = "/agents";
+    process.env["MCP_RATE_LIMIT_READ_PER_MIN"] = "120";
+    process.env["MCP_RATE_LIMIT_WRITE_PER_MIN"] = "5";
+    process.env["MCP_CORS_WRITE_ALLOWED_ORIGINS"] =
+      "https://a.example, https://b.example";
+    process.env["MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP"] = "3";
+    process.env["MCP_ABUSE_START_PURCHASE_DAILY_CAP"] = "2";
+    process.env["MCP_ABUSE_BLOCKED_USER_AGENTS"] = "BadBot";
+
+    expect(httpTransportConfigFromEnv()).toEqual({
+      port: 9090,
+      path: "/agents",
+      rateLimits: { readPerMin: 120, writePerMin: 5 },
+      cors: { writeAllowedOrigins: ["https://a.example", "https://b.example"] },
+      abuse: {
+        captureLeadDailyCapPerIp: 3,
+        startPurchaseDailyCapPerIp: 2,
+        blockedUserAgents: "BadBot",
+      },
+    });
+  });
+});