create-ailk 0.23.0 → 0.24.0

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

@@ -2,15 +2,22 @@
  * Tests for the list_pages MCP tool handler.
  *
  * Acceptance criteria verified here:
- * - listPagesInputSchema validates correct inputs (optional type filter)
- * - listPagesInputSchema rejects unknown type values
- * - ailkListPages with a type arg returns pages for that type
- * - ailkListPages with no type arg returns pages across all SCHEMA_ORG_TYPES
- * - Output validates against listPagesOutputSchema
+ * - contentListParamsSchema requires `type` and rejects unknown type values
+ * - contentListQuerySchema takes an optional `page` / `pageSize` window
+ * - ailkListPages returns the route's paginated ItemList for a type
+ * - ailkListPages defaults the window to page 1 / pageSize 20 and clamps
+ *   pageSize to 100, as the route does
+ * - Output validates against contentListResultSchema
  * - No console.* calls in handler (structural test)
+ *
+ * #7168 (the operator's decision of 2026-10-19): the tool adopted its route's
+ * arguments (`type` required, `page`/`pageSize`) and result (the paginated
+ * `ItemList`, not `{ pages }`); the all-types fan-out is gone with the
+ * optional `type`.
  */
 
-import { readFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { resolve, join } from "node:path";
 
 import {
@@ -20,8 +27,9 @@ import {
 
 import {
   ailkListPages,
-  listPagesInputSchema,
-  listPagesOutputSchema,
+  contentListParamsSchema,
+  contentListQuerySchema,
+  contentListResultSchema,
 } from "../src/tools/list_pages.js";
 import {
   __setMcpPublicWorkspaceForTest,
@@ -93,80 +101,111 @@ function makeArtifactPrismaClientStub(): ArtifactPrismaClient {
   };
 }
 
-describe("listPagesInputSchema", () => {
-  it("accepts empty input (type is optional)", () => {
-    const result = listPagesInputSchema.safeParse({});
-    expect(result.success).toBe(true);
+describe("contentListParamsSchema", () => {
+  it("requires type (#7168 — the route's required param)", () => {
+    const result = contentListParamsSchema.safeParse({});
+    expect(result.success).toBe(false);
   });
 
   it("accepts a valid SchemaOrgType", () => {
-    const result = listPagesInputSchema.safeParse({ type: "HomePage" });
+    const result = contentListParamsSchema.safeParse({ type: "HomePage" });
     expect(result.success).toBe(true);
   });
 
   it("accepts HomePage", () => {
-    const result = listPagesInputSchema.safeParse({ type: "HomePage" });
+    const result = contentListParamsSchema.safeParse({ type: "HomePage" });
     expect(result.success).toBe(true);
   });
 
   it("rejects an unknown type string", () => {
-    const result = listPagesInputSchema.safeParse({ type: "NotAType" });
+    const result = contentListParamsSchema.safeParse({ type: "NotAType" });
     expect(result.success).toBe(false);
   });
 
   it("rejects a numeric type", () => {
-    const result = listPagesInputSchema.safeParse({ type: 42 });
+    const result = contentListParamsSchema.safeParse({ type: 42 });
     expect(result.success).toBe(false);
   });
 });
 
+describe("contentListQuerySchema", () => {
+  it("accepts an empty window (page and pageSize are optional)", () => {
+    const result = contentListQuerySchema.safeParse({});
+    expect(result.success).toBe(true);
+  });
+
+  it("coerces a string page and pageSize, as the route's query string parses", () => {
+    const result = contentListQuerySchema.safeParse({ page: "2", pageSize: "5" });
+    expect(result.success).toBe(true);
+    expect(result.data).toEqual({ page: 2, pageSize: 5 });
+  });
+
+  it("rejects page 0 and pageSize 0", () => {
+    expect(contentListQuerySchema.safeParse({ page: 0 }).success).toBe(false);
+    expect(contentListQuerySchema.safeParse({ pageSize: 0 }).success).toBe(false);
+  });
+
+  it("admits pageSize 500 — the clamp to 100 is the builder's, not a 400 (AC-13)", () => {
+    expect(contentListQuerySchema.safeParse({ pageSize: 500 }).success).toBe(true);
+  });
+});
+
 describe("ailkListPages handler", () => {
-  it("returns pages array for a specific type", async () => {
+  it("returns the route's paginated ItemList for a specific type", async () => {
     const result = await ailkListPages({ type: "HomePage" }, CONTENT_ROOT);
 
-    expect(Array.isArray(result.pages)).toBe(true);
+    expect(result["@context"]).toBe("https://schema.org");
+    expect(result["@type"]).toBe("ItemList");
+    expect(result.type).toBe("HomePage");
+    expect(Array.isArray(result.items)).toBe(true);
     // The real content/ tree has at least one HomePage
-    expect(result.pages.length).toBeGreaterThan(0);
-    for (const page of result.pages) {
+    expect(result.items.length).toBeGreaterThan(0);
+    for (const page of result.items) {
       expect(page.type).toBe("HomePage");
       expect(typeof page.slug).toBe("string");
       expect(typeof page.title).toBe("string");
     }
   });
 
-  it("returns empty pages array for a type with no content", async () => {
-    // FAQPage has no files in content/ by default
-    const result = await ailkListPages({ type: "FAQPage" }, CONTENT_ROOT);
-    expect(Array.isArray(result.pages)).toBe(true);
+  it("defaults the window to page 1 / pageSize 20, as the route does", async () => {
+    const result = await ailkListPages({ type: "HomePage" }, CONTENT_ROOT);
+    expect(result.pagination).toEqual({
+      page: 1,
+      pageSize: 20,
+      totalItems: result.items.length,
+      totalPages: 1,
+    });
   });
 
-  it("returns pages across all SCHEMA_ORG_TYPES when type is omitted", async () => {
-    const result = await ailkListPages({}, CONTENT_ROOT);
-    expect(Array.isArray(result.pages)).toBe(true);
-    // Should include at least one page (we know HomePage has content)
-    expect(result.pages.length).toBeGreaterThan(0);
+  it("returns an empty ItemList for a type with no content", async () => {
+    // An empty content root of its own (#9422): a scaffold's content/ seeds
+    // TeamMember placeholders (#8850), so the repo's tree cannot stand in.
+    const emptyRoot = mkdtempSync(join(tmpdir(), "list-pages-empty-"));
+    const result = await ailkListPages({ type: "TeamMember" }, emptyRoot);
+    rmSync(emptyRoot, { recursive: true, force: true });
+    expect(result.items).toEqual([]);
+    expect(result.pagination.totalItems).toBe(0);
+    expect(result.pagination.totalPages).toBe(1);
   });
 
-  it("output shape has required slug + type + title fields", async () => {
-    const result = await ailkListPages({ type: "HomePage" }, CONTENT_ROOT);
-
-    for (const page of result.pages) {
-      expect(typeof page.slug).toBe("string");
-      expect(typeof page.type).toBe("string");
-      expect(typeof page.title).toBe("string");
-    }
+  it("clamps pageSize 500 to 100 in pagination.pageSize (AC-13)", async () => {
+    const result = await ailkListPages(
+      { type: "HomePage", pageSize: 500 },
+      CONTENT_ROOT,
+    );
+    expect(result.pagination.pageSize).toBe(100);
   });
 
-  it("output validates against listPagesOutputSchema", async () => {
+  it("output validates against contentListResultSchema", async () => {
     const result = await ailkListPages({ type: "HomePage" }, CONTENT_ROOT);
-    const parsed = listPagesOutputSchema.safeParse(result);
+    const parsed = contentListResultSchema.safeParse(result);
     expect(parsed.success).toBe(true);
   });
 });
 
-describe("listPagesInputSchema — Zod boundary security", () => {
+describe("contentListParamsSchema — Zod boundary security", () => {
   it("rejects input with path traversal characters in type", () => {
-    const result = listPagesInputSchema.safeParse({ type: "../etc/passwd" });
+    const result = contentListParamsSchema.safeParse({ type: "../etc/passwd" });
     expect(result.success).toBe(false);
   });
 });
@@ -196,7 +235,7 @@ describe("ailkListPages — CONTENT_ADAPTER=database (#5876)", () => {
 
     const result = await ailkListPages({ type: "HomePage" });
 
-    expect(result.pages).toEqual([
+    expect(result.items).toEqual([
       expect.objectContaining({ slug: "home", type: "HomePage" }),
     ]);
     expect(stub.artifact.findMany).toHaveBeenCalledWith(
@@ -206,13 +245,14 @@ describe("ailkListPages — CONTENT_ADAPTER=database (#5876)", () => {
     );
   });
 
-  it("AC-2: returns { pages: [] } when the workspace is unresolved, with no query", async () => {
+  it("AC-2: returns the empty ItemList when the workspace is unresolved, with no query", async () => {
     const stub = makeArtifactPrismaClientStub();
     __setMcpPublicWorkspaceForTest({ kind: "unresolved", reason: "ambiguous" });
 
     const result = await ailkListPages({ type: "HomePage" });
 
-    expect(result.pages).toEqual([]);
+    expect(result.items).toEqual([]);
+    expect(result.pagination.totalItems).toBe(0);
     expect(stub.artifact.findMany).not.toHaveBeenCalled();
   });
 });

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

@@ -5,7 +5,11 @@
  * - read_content accepts an optional `locale` parameter
  * - list_pages accepts an optional `locale` parameter
  * - search_content accepts an optional `locale` parameter
- * - Tool schemas accept BCP-47 tags and reject malformed values
+ * - Tool schemas accept any string `locale`, as the routes' do — the
+ *   allowlist is the handler's `resolveLocale`, never the schema (#7167 DD1,
+ *   the operator's decision of 2026-10-19: the tool adopted the API's
+ *   arguments, so a malformed tag falls back silently instead of being
+ *   refused)
  * - Tool handlers return data when valid locale is passed (back-compat)
  * - Invalid/unknown locales silently fall back to default (AC-i18n-07)
  */
@@ -13,9 +17,11 @@
 import { resolve, join } from "node:path";
 
 import {
-  listPagesInputSchema,
-  readContentInputSchema,
-  searchContentInputSchema,
+  contentListParamsSchema,
+  contentListQuerySchema,
+  contentPageParamsSchema,
+  contentPageQuerySchema,
+  contentSearchQuerySchema,
 } from "@working-theory/validation";
 
 import { ailkListPages } from "../src/tools/list_pages.js";
@@ -26,61 +32,42 @@ const REPO_ROOT = resolve(__dirname, "../../..");
 const CONTENT_ROOT = join(REPO_ROOT, "content");
 
 describe("locale parameter — input schemas", () => {
-  it("readContentInputSchema accepts a valid BCP-47 tag", () => {
-    const r = readContentInputSchema.safeParse({
-      type: "HomePage",
-      slug: "home",
-      locale: "en",
-    });
-    expect(r.success).toBe(true);
+  it("contentPageParamsSchema + contentPageQuerySchema accept a valid BCP-47 tag", () => {
+    expect(
+      contentPageParamsSchema.safeParse({ type: "HomePage", slug: "home" }).success,
+    ).toBe(true);
+    expect(contentPageQuerySchema.safeParse({ locale: "en" }).success).toBe(true);
   });
 
-  it("readContentInputSchema accepts region-tagged BCP-47 (zh-CN)", () => {
-    const r = readContentInputSchema.safeParse({
-      type: "HomePage",
-      slug: "home",
-      locale: "zh-CN",
-    });
-    expect(r.success).toBe(true);
+  it("contentPageQuerySchema accepts region-tagged BCP-47 (zh-CN)", () => {
+    expect(contentPageQuerySchema.safeParse({ locale: "zh-CN" }).success).toBe(true);
   });
 
-  it("readContentInputSchema rejects malformed locale (uppercase)", () => {
-    const r = readContentInputSchema.safeParse({
-      type: "HomePage",
-      slug: "home",
-      locale: "EN",
-    });
-    expect(r.success).toBe(false);
+  // #7167 DD1 — the route's `locale` is a bare optional string, and the tool
+  // parses the same export: a malformed tag is admitted here and falls back
+  // silently in the handler (`resolveLocale`), as it does on the route.
+  it("contentPageQuerySchema admits a malformed locale (uppercase) — the handler falls back", () => {
+    expect(contentPageQuerySchema.safeParse({ locale: "EN" }).success).toBe(true);
   });
 
-  it("readContentInputSchema rejects path-traversal locale", () => {
-    const r = readContentInputSchema.safeParse({
-      type: "HomePage",
-      slug: "home",
-      locale: "../../etc/passwd",
-    });
-    expect(r.success).toBe(false);
+  it("contentPageQuerySchema admits a path-traversal-shaped locale — the handler falls back, never the filesystem", () => {
+    expect(
+      contentPageQuerySchema.safeParse({ locale: "../../etc/passwd" }).success,
+    ).toBe(true);
   });
 
-  it("readContentInputSchema accepts absent locale (optional)", () => {
-    const r = readContentInputSchema.safeParse({
-      type: "HomePage",
-      slug: "home",
-    });
-    expect(r.success).toBe(true);
+  it("contentPageQuerySchema accepts absent locale (optional)", () => {
+    expect(contentPageQuerySchema.safeParse({}).success).toBe(true);
   });
 
-  it("listPagesInputSchema accepts a valid locale", () => {
-    const r = listPagesInputSchema.safeParse({
-      type: "HomePage",
-      locale: "en",
-    });
-    expect(r.success).toBe(true);
+  it("contentListParamsSchema + contentListQuerySchema accept a valid locale", () => {
+    expect(contentListParamsSchema.safeParse({ type: "HomePage" }).success).toBe(true);
+    expect(contentListQuerySchema.safeParse({ locale: "en" }).success).toBe(true);
   });
 
-  it("searchContentInputSchema accepts a valid locale", () => {
-    const r = searchContentInputSchema.safeParse({
-      query: "foo",
+  it("contentSearchQuerySchema accepts a valid locale", () => {
+    const r = contentSearchQuerySchema.safeParse({
+      q: "foo",
       locale: "en",
     });
     expect(r.success).toBe(true);
@@ -93,8 +80,7 @@ describe("locale parameter — handler behavior (real adapter)", () => {
       { type: "HomePage", slug: "home", locale: "en" },
       CONTENT_ROOT,
     );
-    expect(result).not.toBeNull();
-    expect(result!.slug).toBe("home");
+    expect(result).toHaveProperty("page", expect.objectContaining({ slug: "home" }));
   });
 
   it("ailkReadContent silently falls back when locale=zz (unknown)", async () => {
@@ -103,8 +89,7 @@ describe("locale parameter — handler behavior (real adapter)", () => {
       CONTENT_ROOT,
     );
     // AC-i18n-07: silent fallback to default locale's content.
-    expect(result).not.toBeNull();
-    expect(result!.slug).toBe("home");
+    expect(result).toHaveProperty("page", expect.objectContaining({ slug: "home" }));
   });
 
   it("ailkListPages returns pages when locale=en", async () => {
@@ -112,8 +97,8 @@ describe("locale parameter — handler behavior (real adapter)", () => {
       { type: "HomePage", locale: "en" },
       CONTENT_ROOT,
     );
-    expect(Array.isArray(result.pages)).toBe(true);
-    expect(result.pages.length).toBeGreaterThan(0);
+    expect(Array.isArray(result.items)).toBe(true);
+    expect(result.items.length).toBeGreaterThan(0);
   });
 
   it("ailkListPages silently falls back when locale=zz", async () => {
@@ -122,14 +107,14 @@ describe("locale parameter — handler behavior (real adapter)", () => {
       CONTENT_ROOT,
     );
     // Falls back to default-locale list.
-    expect(Array.isArray(result.pages)).toBe(true);
+    expect(Array.isArray(result.items)).toBe(true);
   });
 
   it("ailkSearchContent returns results when locale=en", async () => {
     const result = await ailkSearchContent(
-      { query: "AI", locale: "en" },
+      { q: "AI", locale: "en" },
       CONTENT_ROOT,
     );
-    expect(Array.isArray(result.results)).toBe(true);
+    expect(Array.isArray(result.items)).toBe(true);
   });
 });

package/templates/apps/mcp/__tests__/rate-limit-write.test.ts

@@ -0,0 +1,189 @@
+/**
+ * The write-tool per-minute rate limit (#9251).
+ *
+ * `MCP_RATE_LIMIT_WRITE_PER_MIN` (`config.rateLimits.writePerMin`) used to be
+ * parsed and ignored: one app-wide @fastify/rate-limit bucket at `readPerMin`
+ * counted every request, and the TODO in the write preHandler deferred the
+ * tighter write bucket. These tests pin what the transport now enforces:
+ *
+ * - with `writePerMin: 2`, the third anonymous write-tool call from one IP
+ *   inside a minute is refused with the limiter's 429 shape — the same body
+ *   and headers the read ceiling emits — before the tool (and so the hub) is
+ *   reached, while reads from that IP keep answering 200;
+ * - the write bucket counts ONLY write-tool calls: reads spend none of it;
+ * - a JSON-RPC batch of N write calls spends N units, not one.
+ *
+ * Same harness as http-transport.test.ts: a real Fastify server on an
+ * ephemeral port, stateless mode, and the hub stubbed through
+ * `apiClient.leads.submit` so an allowed `capture_lead` succeeds.
+ */
+
+import type { AddressInfo } from "node:net";
+
+import type { FastifyInstance } from "fastify";
+import { apiClient } from "@working-theory/api-client";
+
+import { buildHttpTransportApp } from "../src/http-transport.js";
+
+type RateLimitErrorBody = {
+  statusCode?: number;
+  error?: string;
+  message?: string;
+};
+
+const WRITE_LIMITED_CONFIG = {
+  path: "/mcp",
+  stateless: true,
+  rateLimits: { readPerMin: 60, writePerMin: 2 },
+  cors: { writeAllowedOrigins: [] as string[] },
+  abuse: {
+    captureLeadDailyCapPerIp: 50,
+    blockedUserAgents: "",
+  },
+} as const;
+
+const TOOLS_LIST_PAYLOAD = {
+  jsonrpc: "2.0",
+  id: 1,
+  method: "tools/list",
+  params: {},
+};
+
+function captureLead(id: number) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    method: "tools/call",
+    params: {
+      name: "capture_lead",
+      arguments: {
+        source: "mcp",
+        email: `jane${id}@example.com`,
+        payload: { name: "Jane" },
+      },
+    },
+  };
+}
+
+async function mcpPost(port: number, payload: object): 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",
+    },
+  });
+}
+
+async function listen(
+  config: Parameters<typeof buildHttpTransportApp>[0],
+): Promise<{ app: FastifyInstance; port: number }> {
+  const app = await buildHttpTransportApp(config);
+  await app.listen({ host: "127.0.0.1", port: 0 });
+  return { app, port: (app.server.address() as AddressInfo).port };
+}
+
+describe("MCP_RATE_LIMIT_WRITE_PER_MIN is enforced on the write tools (#9251)", () => {
+  let app: FastifyInstance;
+  let port: number;
+  let submitSpy: jest.SpiedFunction<typeof apiClient.leads.submit>;
+
+  beforeEach(async () => {
+    submitSpy = jest.spyOn(apiClient.leads, "submit").mockResolvedValue({
+      ok: true,
+      body: {
+        id: "lead_1",
+        persisted: "db",
+        email: { ok: true, messageId: "msg_1" },
+      },
+    });
+    ({ app, port } = await listen(WRITE_LIMITED_CONFIG));
+  });
+
+  afterEach(async () => {
+    await app.close();
+    submitSpy.mockRestore();
+  });
+
+  it("refuses the third write call from one IP within a minute with the limiter's 429, while reads continue", async () => {
+    expect((await mcpPost(port, captureLead(1))).status).toBe(200);
+    expect((await mcpPost(port, captureLead(2))).status).toBe(200);
+
+    const refused = await mcpPost(port, captureLead(3));
+
+    expect(refused.status).toBe(429);
+    const body = (await refused.json()) as RateLimitErrorBody;
+    expect(body).toEqual({
+      statusCode: 429,
+      error: "Too Many Requests",
+      message: expect.stringMatching(/^Rate limit exceeded, retry in /),
+    });
+    expect(refused.headers.get("x-ratelimit-limit")).toBe("2");
+    expect(refused.headers.get("x-ratelimit-remaining")).toBe("0");
+    expect(refused.headers.get("x-ratelimit-reset")).toMatch(/^\d+$/);
+    expect(refused.headers.get("retry-after")).toMatch(/^\d+$/);
+    // Refused in the preHandler: the tool never ran, so the hub saw two calls.
+    expect(submitSpy).toHaveBeenCalledTimes(2);
+
+    const read = await mcpPost(port, TOOLS_LIST_PAYLOAD);
+    expect(read.status).toBe(200);
+  });
+
+  it("counts only write-tool calls — reads spend none of the write bucket", async () => {
+    for (let i = 0; i < 10; i += 1) {
+      expect((await mcpPost(port, TOOLS_LIST_PAYLOAD)).status).toBe(200);
+    }
+
+    expect((await mcpPost(port, captureLead(11))).status).toBe(200);
+    expect((await mcpPost(port, captureLead(12))).status).toBe(200);
+    expect((await mcpPost(port, captureLead(13))).status).toBe(429);
+  });
+
+  it("a batch of N write calls spends N units, not one", async () => {
+    const res = await mcpPost(port, [
+      captureLead(21),
+      captureLead(22),
+      captureLead(23),
+    ]);
+
+    expect(res.status).toBe(429);
+    expect(submitSpy).not.toHaveBeenCalled();
+  });
+
+  it("emits the same 429 shape as the read ceiling", async () => {
+    const readLimited = await listen({
+      ...WRITE_LIMITED_CONFIG,
+      rateLimits: { readPerMin: 1, writePerMin: 2 },
+    });
+    try {
+      await mcpPost(readLimited.port, TOOLS_LIST_PAYLOAD);
+      const readRefusal = await mcpPost(readLimited.port, TOOLS_LIST_PAYLOAD);
+      expect(readRefusal.status).toBe(429);
+
+      await mcpPost(port, captureLead(31));
+      await mcpPost(port, captureLead(32));
+      const writeRefusal = await mcpPost(port, captureLead(33));
+      expect(writeRefusal.status).toBe(429);
+
+      const readBody = (await readRefusal.json()) as RateLimitErrorBody;
+      const writeBody = (await writeRefusal.json()) as RateLimitErrorBody;
+      expect(Object.keys(writeBody).sort()).toEqual(
+        Object.keys(readBody).sort(),
+      );
+      expect(writeBody.error).toBe(readBody.error);
+      expect(writeBody.message).toBe(readBody.message);
+      for (const header of [
+        "x-ratelimit-limit",
+        "x-ratelimit-remaining",
+        "x-ratelimit-reset",
+        "retry-after",
+      ]) {
+        expect(readRefusal.headers.has(header)).toBe(true);
+        expect(writeRefusal.headers.has(header)).toBe(true);
+      }
+    } finally {
+      await readLimited.app.close();
+    }
+  });
+});