create-ailk 0.1.0

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

@@ -0,0 +1,80 @@
+/**
+ * Tests for the get_pricing MCP tool handler.
+ *
+ * Acceptance criteria verified here:
+ * - getPricingInputSchema validates correct inputs (slug optional)
+ * - getPricingInputSchema rejects invalid slugs
+ * - ailkGetPricing returns null for a slug with no content
+ * - ailkGetPricing output shape is correct when data exists
+ * - Output validates against getPricingOutputSchema
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import {
+  ailkGetPricing,
+  getPricingInputSchema,
+  getPricingOutputSchema,
+} from "../src/tools/get_pricing.js";
+
+const REPO_ROOT = resolve(__dirname, "../../..");
+const CONTENT_ROOT = `${REPO_ROOT}/content`;
+
+describe("getPricingInputSchema", () => {
+  it("accepts empty input (slug is optional)", () => {
+    const result = getPricingInputSchema.safeParse({});
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts a valid slug", () => {
+    const result = getPricingInputSchema.safeParse({ slug: "pricing" });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects a slug with path traversal", () => {
+    const result = getPricingInputSchema.safeParse({ slug: "../etc/passwd" });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects a slug with uppercase letters", () => {
+    const result = getPricingInputSchema.safeParse({ slug: "Pricing" });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects an empty slug string", () => {
+    const result = getPricingInputSchema.safeParse({ slug: "" });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("ailkGetPricing handler", () => {
+  it("returns null for a slug with no matching content", async () => {
+    const result = await ailkGetPricing(
+      { slug: "nonexistent-slug-xqz" },
+      CONTENT_ROOT,
+    );
+    expect(result).toBeNull();
+  });
+
+  it("returns an object or null for default slug", async () => {
+    const result = await ailkGetPricing({}, CONTENT_ROOT);
+    expect(result === null || typeof result === "object").toBe(true);
+  });
+
+  it("output validates against getPricingOutputSchema", async () => {
+    const result = await ailkGetPricing({}, CONTENT_ROOT);
+    const parsed = getPricingOutputSchema.safeParse(result);
+    expect(parsed.success).toBe(true);
+  });
+});
+
+describe("architectural guard — no console calls", () => {
+  it("apps/mcp/src/tools/get_pricing.ts does not call console.*", () => {
+    const src = readFileSync(
+      resolve(__dirname, "../src/tools/get_pricing.ts"),
+      "utf-8",
+    );
+    expect(src).not.toMatch(/\bconsole\.(log|warn|error|info|debug)\b/);
+  });
+});

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

@@ -0,0 +1,81 @@
+/**
+ * Tests for the get_site_info MCP tool handler.
+ *
+ * Acceptance criteria verified here:
+ * - getSiteInfoInputSchema validates correct inputs (slug optional)
+ * - getSiteInfoInputSchema rejects invalid slugs (path traversal, uppercase)
+ * - ailkGetSiteInfo returns null for a slug with no content
+ * - ailkGetSiteInfo returns a typed object when content exists
+ * - Output validates against getSiteInfoOutputSchema
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import {
+  ailkGetSiteInfo,
+  getSiteInfoInputSchema,
+  getSiteInfoOutputSchema,
+} from "../src/tools/get_site_info.js";
+
+const REPO_ROOT = resolve(__dirname, "../../..");
+const CONTENT_ROOT = `${REPO_ROOT}/content`;
+
+describe("getSiteInfoInputSchema", () => {
+  it("accepts empty input (slug is optional)", () => {
+    const result = getSiteInfoInputSchema.safeParse({});
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts a valid slug", () => {
+    const result = getSiteInfoInputSchema.safeParse({ slug: "home" });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects a slug with path traversal", () => {
+    const result = getSiteInfoInputSchema.safeParse({ slug: "../etc/passwd" });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects a slug with uppercase letters", () => {
+    const result = getSiteInfoInputSchema.safeParse({ slug: "Home" });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects an empty slug string", () => {
+    const result = getSiteInfoInputSchema.safeParse({ slug: "" });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("ailkGetSiteInfo handler", () => {
+  it("returns null for a slug with no matching content", async () => {
+    const result = await ailkGetSiteInfo(
+      { slug: "nonexistent-slug-xqz" },
+      CONTENT_ROOT,
+    );
+    expect(result).toBeNull();
+  });
+
+  it("returns an object or null for default slug", async () => {
+    const result = await ailkGetSiteInfo({}, CONTENT_ROOT);
+    // May be null if no HomePage/home.mdx exists — both are valid
+    expect(result === null || typeof result === "object").toBe(true);
+  });
+
+  it("output validates against getSiteInfoOutputSchema when non-null", async () => {
+    const result = await ailkGetSiteInfo({}, CONTENT_ROOT);
+    const parsed = getSiteInfoOutputSchema.safeParse(result);
+    expect(parsed.success).toBe(true);
+  });
+});
+
+describe("architectural guard — no console calls", () => {
+  it("apps/mcp/src/tools/get_site_info.ts does not call console.*", () => {
+    const src = readFileSync(
+      resolve(__dirname, "../src/tools/get_site_info.ts"),
+      "utf-8",
+    );
+    expect(src).not.toMatch(/\bconsole\.(log|warn|error|info|debug)\b/);
+  });
+});

package/templates/apps/mcp/__tests__/http-transport.test.ts

@@ -0,0 +1,323 @@
+/**
+ * Integration tests for the MCP HTTP transport.
+ *
+ * Starts a real Fastify server on an ephemeral port (port 0) per test suite
+ * and uses Node's global fetch to send requests. Real TCP sockets avoid the
+ * `socket.destroySoon is not a function` crash that occurs when the MCP SDK's
+ * StreamableHTTPServerTransport receives the mock socket from app.inject().
+ *
+ * Uses stateless transport mode: each request is independent, responses are
+ * plain JSON (no SSE). This is the simplest deployment model and the easiest
+ * to test. Stateful session behaviour is exercised by the SDK's own test suite.
+ *
+ * Acceptance criteria verified here (Layer 2):
+ * - tools/list returns all OSS tools (count matches listRegisteredTools())
+ * - Read-tool call succeeds over HTTP
+ * - Write-tool call from a disallowed origin returns 403
+ * - Rate-limit triggers at configured threshold
+ * - Abuse rules reject invalid email on capture_lead
+ * - Honeypot field rejection on capture_lead
+ * - Blocked UA returns 403
+ */
+
+import type { AddressInfo } from "node:net";
+
+import type { FastifyInstance } from "fastify";
+import { buildHttpTransportApp } from "../src/http-transport.js";
+import { listRegisteredTools } from "../src/server.js";
+
+/** Permissive JSON-RPC 2.0 envelope type for response body assertions. */
+type JsonRpcResponse = {
+  jsonrpc?: string;
+  id?: number | string | null;
+  result?: { tools?: unknown[]; [k: string]: unknown };
+  error?: { code: number; message: string };
+};
+
+const TOOLS_LIST_PAYLOAD = {
+  jsonrpc: "2.0",
+  id: 1,
+  method: "tools/list",
+  params: {},
+};
+
+/** Default config used by most test suites. */
+const DEFAULT_CONFIG = {
+  path: "/mcp",
+  stateless: true,
+  rateLimits: { readPerMin: 60, writePerMin: 10 },
+  cors: { writeAllowedOrigins: [] as string[] },
+  abuse: {
+    captureLeadDailyCapPerIp: 50,
+    blockedUserAgents: "",
+  },
+} as const;
+
+/**
+ * Post a JSON-RPC payload to the server at the given port and return the
+ * fetch Response. Includes the Accept header required by the MCP Streamable
+ * HTTP spec.
+ */
+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,
+    },
+  });
+}
+
+describe("buildHttpTransportApp", () => {
+  let app: FastifyInstance;
+  let port: number;
+
+  beforeEach(async () => {
+    app = await buildHttpTransportApp(DEFAULT_CONFIG);
+    await app.listen({ host: "127.0.0.1", port: 0 });
+    port = (app.server.address() as AddressInfo).port;
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it("starts listening on an ephemeral port without throwing", () => {
+    expect(app.server.listening).toBe(true);
+    expect(port).toBeGreaterThan(0);
+  });
+});
+
+describe("tools/list over HTTP (stateless)", () => {
+  let app: FastifyInstance;
+  let port: number;
+
+  beforeEach(async () => {
+    app = await buildHttpTransportApp(DEFAULT_CONFIG);
+    await app.listen({ host: "127.0.0.1", port: 0 });
+    port = (app.server.address() as AddressInfo).port;
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it("returns 200 for a tools/list request", async () => {
+    const res = await mcpPost(port, TOOLS_LIST_PAYLOAD);
+    expect(res.status).toBe(200);
+  });
+
+  it("tools/list response includes all OSS tools", async () => {
+    const res = await mcpPost(port, TOOLS_LIST_PAYLOAD);
+    expect(res.status).toBe(200);
+
+    const body = (await res.json()) as JsonRpcResponse;
+    expect(body.result).toBeDefined();
+    // body.result is confirmed defined above; non-null assertion is safe
+    expect(Array.isArray(body.result!.tools)).toBe(true);
+
+    const expectedCount = listRegisteredTools().length;
+    expect(body.result!.tools).toHaveLength(expectedCount);
+  });
+});
+
+describe("CORS enforcement on write tools", () => {
+  let app: FastifyInstance;
+  let port: number;
+
+  beforeEach(async () => {
+    app = await buildHttpTransportApp(DEFAULT_CONFIG);
+    await app.listen({ host: "127.0.0.1", port: 0 });
+    port = (app.server.address() as AddressInfo).port;
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it("blocks a tools/call write from a non-allowlisted origin", async () => {
+    const payload = {
+      jsonrpc: "2.0",
+      id: 3,
+      method: "tools/call",
+      params: {
+        name: "capture_lead",
+        arguments: {
+          name: "Bot",
+          email: "bot@evil.com",
+        },
+      },
+    };
+
+    const res = await mcpPost(port, payload, {
+      origin: "https://evil.example.com",
+    });
+
+    expect(res.status).toBe(403);
+  });
+
+  it("allows a tools/call write from an allowlisted origin", async () => {
+    const allowedApp = await buildHttpTransportApp({
+      ...DEFAULT_CONFIG,
+      cors: { writeAllowedOrigins: ["https://allowed.example.com"] },
+    });
+    await allowedApp.listen({ host: "127.0.0.1", port: 0 });
+    const allowedPort = (allowedApp.server.address() as AddressInfo).port;
+
+    try {
+      const payload = {
+        jsonrpc: "2.0",
+        id: 3,
+        method: "tools/call",
+        params: {
+          name: "capture_lead",
+          arguments: {
+            name: "Jane",
+            email: "jane@example.com",
+          },
+        },
+      };
+
+      const res = await mcpPost(allowedPort, payload, {
+        origin: "https://allowed.example.com",
+      });
+
+      // Should NOT be 403 (may be 200 or a tool-level error, but not CORS blocked)
+      expect(res.status).not.toBe(403);
+    } finally {
+      await allowedApp.close();
+    }
+  });
+});
+
+describe("Rate limiting", () => {
+  // Use a very low limit to test without hammering
+  const LOW_RATE_CONFIG = {
+    ...DEFAULT_CONFIG,
+    rateLimits: { readPerMin: 3, writePerMin: 2 },
+  } as const;
+
+  let app: FastifyInstance;
+  let port: number;
+
+  beforeEach(async () => {
+    app = await buildHttpTransportApp(LOW_RATE_CONFIG);
+    await app.listen({ host: "127.0.0.1", port: 0 });
+    port = (app.server.address() as AddressInfo).port;
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it("returns 429 after exceeding the read rate limit", async () => {
+    const payload = {
+      jsonrpc: "2.0",
+      id: 10,
+      method: "tools/list",
+      params: {},
+    };
+
+    let lastStatus = 200;
+    for (let i = 0; i < 5; i++) {
+      const res = await mcpPost(port, payload);
+      lastStatus = res.status;
+    }
+
+    expect(lastStatus).toBe(429);
+  });
+});
+
+describe("Abuse rules", () => {
+  const OPEN_CORS_CONFIG = {
+    ...DEFAULT_CONFIG,
+    cors: { writeAllowedOrigins: ["*"] as string[] },
+  };
+
+  let app: FastifyInstance;
+  let port: number;
+
+  beforeEach(async () => {
+    app = await buildHttpTransportApp(OPEN_CORS_CONFIG);
+    await app.listen({ host: "127.0.0.1", port: 0 });
+    port = (app.server.address() as AddressInfo).port;
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it("rejects capture_lead with malformed email", async () => {
+    const payload = {
+      jsonrpc: "2.0",
+      id: 20,
+      method: "tools/call",
+      params: {
+        name: "capture_lead",
+        arguments: {
+          name: "Spammer",
+          email: "not-an-email",
+        },
+      },
+    };
+
+    const res = await mcpPost(port, payload);
+    expect(res.status).toBe(422);
+  });
+
+  it("rejects capture_lead with honeypot field filled", async () => {
+    const payload = {
+      jsonrpc: "2.0",
+      id: 21,
+      method: "tools/call",
+      params: {
+        name: "capture_lead",
+        arguments: {
+          name: "Bot",
+          email: "bot@example.com",
+          honeypot: "i-am-a-bot",
+        },
+      },
+    };
+
+    const res = await mcpPost(port, payload);
+    expect(res.status).toBe(422);
+  });
+
+  it("blocks requests from blocked user agents", async () => {
+    const blockedApp = await buildHttpTransportApp({
+      ...OPEN_CORS_CONFIG,
+      abuse: {
+        captureLeadDailyCapPerIp: 50,
+        blockedUserAgents: "EvilBot",
+      },
+    });
+    await blockedApp.listen({ host: "127.0.0.1", port: 0 });
+    const blockedPort = (blockedApp.server.address() as AddressInfo).port;
+
+    try {
+      const res = await mcpPost(
+        blockedPort,
+        {
+          jsonrpc: "2.0",
+          id: 22,
+          method: "tools/call",
+          params: {
+            name: "capture_lead",
+            arguments: { name: "Bot", email: "bot@example.com" },
+          },
+        },
+        { "user-agent": "EvilBot/1.0" },
+      );
+      expect(res.status).toBe(403);
+    } finally {
+      await blockedApp.close();
+    }
+  });
+});

package/templates/apps/mcp/__tests__/lib/errors.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Unit tests for the MCP-side canonical error helpers used by D14a content-
+ * write tools. Same shape as the apps/api twin minus the status field — MCP
+ * surfaces errors as the tool result body itself.
+ */
+
+import {
+  conflictError,
+  notFoundError,
+  paymentRequiredError,
+  unauthorizedError,
+  validationError,
+} from "../../src/lib/errors.js";
+
+describe("apps/mcp/lib/errors", () => {
+  it("validationError carries validation_failed code + message", () => {
+    expect(validationError("Invalid input")).toEqual({
+      error: "validation_failed",
+      message: "Invalid input",
+    });
+  });
+
+  it("validationError includes details when provided", () => {
+    expect(
+      validationError("Bad type", { field: "type", received: "Unknown" }),
+    ).toEqual({
+      error: "validation_failed",
+      message: "Bad type",
+      details: { field: "type", received: "Unknown" },
+    });
+  });
+
+  it("validationError omits details key when not provided", () => {
+    const err = validationError("X");
+    expect("details" in err).toBe(false);
+  });
+
+  it("unauthorizedError carries unauthorized code", () => {
+    expect(unauthorizedError("nope")).toEqual({
+      error: "unauthorized",
+      message: "nope",
+    });
+  });
+
+  it("paymentRequiredError carries payment_required code", () => {
+    expect(paymentRequiredError("upgrade")).toEqual({
+      error: "payment_required",
+      message: "upgrade",
+    });
+  });
+
+  it("notFoundError carries not_found code", () => {
+    expect(notFoundError("missing")).toEqual({
+      error: "not_found",
+      message: "missing",
+    });
+  });
+
+  it("conflictError carries conflict code", () => {
+    expect(conflictError("stale")).toEqual({
+      error: "conflict",
+      message: "stale",
+    });
+  });
+
+  it("conflictError includes details (e.g. existing version)", () => {
+    expect(conflictError("Slug exists", { existingVersion: "abc123" })).toEqual(
+      {
+        error: "conflict",
+        message: "Slug exists",
+        details: { existingVersion: "abc123" },
+      },
+    );
+  });
+});

package/templates/apps/mcp/__tests__/lib/require-paid-tier.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Unit tests for the MCP-side require-paid-tier guard.
+ *
+ * Mocks @working-theory/license `checkLicense` and asserts:
+ *   - free tier → returns canonical payment_required body
+ *   - pro tier  → returns null (caller proceeds)
+ *   - checkLicense throws → safe-by-default, returns payment_required
+ */
+
+const mockCheckLicense = jest.fn();
+
+jest.mock("@working-theory/license", () => ({
+  checkLicense: (...args: unknown[]) => mockCheckLicense(...args),
+}));
+
+import { requirePaidTier } from "../../src/lib/require-paid-tier.js";
+
+describe("requirePaidTier (mcp)", () => {
+  beforeEach(() => {
+    mockCheckLicense.mockReset();
+  });
+
+  it("free tier — returns canonical payment_required body", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "free",
+      plan: null,
+      features: [],
+      expiresAt: null,
+      revoked: false,
+    });
+
+    const guard = await requirePaidTier();
+
+    expect(guard).toEqual({
+      error: "payment_required",
+      message: expect.stringContaining("paid license"),
+    });
+  });
+
+  it("pro tier — returns null (caller proceeds)", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "pro",
+      plan: "pro",
+      features: [],
+      expiresAt: null,
+      revoked: false,
+    });
+
+    const guard = await requirePaidTier();
+    expect(guard).toBeNull();
+  });
+
+  it("checkLicense throws — degrades to payment_required (safe default)", async () => {
+    mockCheckLicense.mockRejectedValue(new Error("boom"));
+
+    const guard = await requirePaidTier();
+    expect(guard).toMatchObject({ error: "payment_required" });
+  });
+
+  it("revoked paid license — returns payment_required even though tier is pro (issue #398)", async () => {
+    // After a 403/revoked refresh, checkLicense() returns tier:'pro' until
+    // the existing JWT exp (up to 24h). The revoked flag is the early
+    // signal — we must close the gate now, not wait for exp.
+    mockCheckLicense.mockResolvedValue({
+      tier: "pro",
+      plan: "pro",
+      features: [],
+      expiresAt: null,
+      revoked: true,
+    });
+
+    const guard = await requirePaidTier();
+    expect(guard).toMatchObject({ error: "payment_required" });
+  });
+});