create-ailk 0.1.0

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

@@ -0,0 +1,195 @@
+/**
+ * Tests for the update_page MCP tool handler.
+ *
+ * D14a Stage 1 Unit C — Layer 1 / Layer 2 acceptance criteria mapped here:
+ *   - Free tier → payment_required, no adapter call.
+ *   - Missing ifMatch → validation_failed (caught by input schema).
+ *   - Stale ifMatch → conflict body with details.currentVersion echoed.
+ *   - Slug not found → not_found body.
+ *   - Bad frontmatter → validation_failed, no adapter call.
+ *   - Pro + valid + matching ifMatch → { page, version } success body.
+ */
+
+import { AdapterWriteError, type ContentAdapter } from "@working-theory/content-adapters";
+
+const mockCheckLicense = jest.fn();
+
+jest.mock("@working-theory/license", () => ({
+  checkLicense: (...args: unknown[]) => mockCheckLicense(...args),
+}));
+
+import { ailkUpdatePage } from "../src/tools/update_page.js";
+
+function makeAdapter(
+  overrides: Partial<{
+    updatePage: jest.Mock;
+  }> = {},
+): ContentAdapter {
+  // eslint-disable-next-line no-restricted-syntax -- #506/#507: pre-existing test-hygiene violation
+  return {
+    getPageBySlug: jest.fn().mockResolvedValue(null),
+    listPages: jest.fn().mockResolvedValue([]),
+    getDetailBySlug: jest.fn().mockResolvedValue(null),
+    listDetail: jest.fn().mockResolvedValue([]),
+    searchPages: jest.fn().mockResolvedValue([]),
+    extractStructuredData: jest.fn().mockResolvedValue(null),
+    createPage: jest.fn(),
+    updatePage: overrides.updatePage ?? jest.fn(),
+    deletePage: jest.fn(),
+    getPageVersion: jest.fn(),
+  } as unknown as ContentAdapter;
+}
+
+const VALID_INPUT = {
+  type: "Product" as const,
+  slug: "widget-pro",
+  page: {
+    title: "Widget Pro v2",
+    description: "Updated.",
+  },
+  body: "# Widget Pro v2\n",
+  ifMatch: "v1",
+};
+
+describe("ailkUpdatePage", () => {
+  beforeEach(() => {
+    mockCheckLicense.mockReset();
+  });
+
+  it("returns payment_required for free tier; adapter not called", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "free",
+      plan: null,
+      features: [],
+      expiresAt: null,
+      revoked: false,
+    });
+    const adapter = makeAdapter();
+
+    const result = await ailkUpdatePage(VALID_INPUT, adapter);
+
+    expect(result).toMatchObject({ error: "payment_required" });
+    expect(adapter.updatePage).not.toHaveBeenCalled();
+  });
+
+  it("returns validation_failed when ifMatch is missing", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "pro",
+      plan: "pro",
+      features: [],
+      expiresAt: null,
+      revoked: false,
+    });
+    const adapter = makeAdapter();
+    const { ifMatch: _ignored, ...inputNoIfMatch } = VALID_INPUT;
+
+    const result = await ailkUpdatePage(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      inputNoIfMatch as any,
+      adapter,
+    );
+
+    expect(result).toMatchObject({ error: "validation_failed" });
+    expect(adapter.updatePage).not.toHaveBeenCalled();
+  });
+
+  it("returns conflict with details.currentVersion on stale ifMatch", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "pro",
+      plan: "pro",
+      features: [],
+      expiresAt: null,
+      revoked: false,
+    });
+    const adapter = makeAdapter({
+      updatePage: jest
+        .fn()
+        .mockRejectedValue(
+          new AdapterWriteError(
+            "conflict",
+            "Version mismatch on Product/widget-pro.mdx",
+            { currentVersion: "v9" },
+          ),
+        ),
+    });
+
+    const result = await ailkUpdatePage(VALID_INPUT, adapter);
+
+    expect(result).toMatchObject({
+      error: "conflict",
+      details: { currentVersion: "v9" },
+    });
+  });
+
+  it("returns not_found when adapter signals missing slug", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "pro",
+      plan: "pro",
+      features: [],
+      expiresAt: null,
+      revoked: false,
+    });
+    const adapter = makeAdapter({
+      updatePage: jest
+        .fn()
+        .mockRejectedValue(
+          new AdapterWriteError(
+            "not_found",
+            "No page at Product/widget-pro.mdx",
+          ),
+        ),
+    });
+
+    const result = await ailkUpdatePage(VALID_INPUT, adapter);
+
+    expect(result).toMatchObject({ error: "not_found" });
+  });
+
+  it("returns validation_failed when frontmatter is bad", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "pro",
+      plan: "pro",
+      features: [],
+      expiresAt: null,
+      revoked: false,
+    });
+    const adapter = makeAdapter();
+
+    const result = await ailkUpdatePage(
+      { ...VALID_INPUT, page: { title: "Missing description" } },
+      adapter,
+    );
+
+    expect(result).toMatchObject({ error: "validation_failed" });
+    expect(adapter.updatePage).not.toHaveBeenCalled();
+  });
+
+  it("returns { page, version } on happy path", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "pro",
+      plan: "pro",
+      features: [],
+      expiresAt: null,
+      revoked: false,
+    });
+    const persistedPage = {
+      type: "Product" as const,
+      slug: "widget-pro",
+      title: "Widget Pro v2",
+      description: "Updated.",
+    };
+    const adapter = makeAdapter({
+      updatePage: jest
+        .fn()
+        .mockResolvedValue({ page: persistedPage, version: "v2" }),
+    });
+
+    const result = await ailkUpdatePage(VALID_INPUT, adapter);
+
+    expect(result).toEqual({ page: persistedPage, version: "v2" });
+    const callArgs = (adapter.updatePage as jest.Mock).mock.calls[0];
+    expect(callArgs[0]).toBe("Product");
+    expect(callArgs[1]).toBe("widget-pro");
+    expect(callArgs[3]).toEqual({ ifMatch: "v1" });
+  });
+});

package/templates/apps/mcp/jest.config.cjs

@@ -0,0 +1,82 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  // Workaround: @hono/node-server@1.19.14 (transitive via
+  // @modelcontextprotocol/sdk's StreamableHTTPServerTransport) calls
+  // socket.destroySoon() at shutdown, which throws on Node 20.x. Tests pass;
+  // only the post-test process teardown fails. forceExit lets Jest exit
+  // cleanly after all tests have reported, bypassing the broken handle
+  // cleanup. Revisit when @hono/node-server publishes a Node-20-compatible fix.
+  forceExit: true,
+  roots: ['<rootDir>/__tests__'],
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  moduleNameMapper: {
+    // Mock server-only in Jest environments — the package throws by design
+    // outside Next.js. The real guard runs in production Next.js builds.
+    '^server-only$': '<rootDir>/../../__mocks__/server-only.ts',
+    // Map workspace packages to their TypeScript source so ts-jest compiles them
+    // directly (the published dist is ESM, which Jest's CJS preset can't load).
+    '^@working-theory/aeo$': '<rootDir>/../../packages/aeo/src/index.ts',
+    '^@working-theory/common$': '<rootDir>/../../packages/common/src/index.ts',
+    '^@working-theory/aeo/(.*)$': '<rootDir>/../../packages/aeo/src/$1',
+    '^@working-theory/content-adapters$': '<rootDir>/../../packages/content-adapters/src/index.ts',
+    '^@working-theory/content-adapters/(.*)$': '<rootDir>/../../packages/content-adapters/src/$1',
+    '^@working-theory/license$': '<rootDir>/../../packages/license/src/index.ts',
+    '^@working-theory/metadata$': '<rootDir>/../../packages/metadata/src/index.ts',
+    '^@working-theory/schema$': '<rootDir>/../../packages/schema/src/index.ts',
+    '^@working-theory/schema/(.*)$': '<rootDir>/../../packages/schema/src/$1',
+    '^@working-theory/schema-validator$': '<rootDir>/../../packages/schema-validator/src/index.ts',
+    '^@working-theory/schema-pack-registry$': '<rootDir>/../../packages/schema-pack-registry/src/index.ts',
+    '^@working-theory/validation$': '<rootDir>/../../packages/validation/src/index.ts',
+    '^@working-theory/api-client$': '<rootDir>/../../packages/api-client/src/index.ts',
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.d.ts'],
+  transformIgnorePatterns: [
+    '/node_modules/(?!(\\.pnpm/)?jose@?[^/]*?(/|$))',
+  ],
+  transform: {
+    '^.+\\.(tsx?|jsx?|mjs)$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          target: 'es2016',
+          module: 'commonjs',
+          lib: ['es2016'],
+          declaration: false,
+          strict: true,
+          esModuleInterop: true,
+          skipLibCheck: true,
+          ignoreDeprecations: '6.0',
+          allowJs: true,
+          // paths must mirror moduleNameMapper above so ts-jest's TypeScript
+          // type-checker can resolve workspace package imports during compile.
+          // Jest's moduleNameMapper handles runtime resolution; TS uses paths.
+          baseUrl: '.',
+          paths: {
+            '@working-theory/aeo': ['../../packages/aeo/src/index.ts'],
+            '@working-theory/common': ['../../packages/common/src/index.ts'],
+            '@working-theory/aeo/*': ['../../packages/aeo/src/*'],
+            '@working-theory/api-client': ['../../packages/api-client/src/index.ts'],
+            '@working-theory/content-adapters': ['../../packages/content-adapters/src/index.ts'],
+            '@working-theory/content-adapters/*': ['../../packages/content-adapters/src/*'],
+            '@working-theory/license': ['../../packages/license/src/index.ts'],
+            '@working-theory/metadata': ['../../packages/metadata/src/index.ts'],
+            '@working-theory/schema': ['../../packages/schema/src/index.ts'],
+            '@working-theory/schema/*': ['../../packages/schema/src/*'],
+            '@working-theory/schema-validator': ['../../packages/schema-validator/src/index.ts'],
+            '@working-theory/schema-pack-registry': ['../../packages/schema-pack-registry/src/index.ts'],
+            '@working-theory/validation': ['../../packages/validation/src/index.ts'],
+          },
+        },
+        // Suppress "import.meta only allowed in ESM modules" — source is ESM,
+        // but ts-jest compiles to CommonJS for Jest. The import.meta fallback
+        // path is never exercised in tests (contentRoot is always passed explicitly).
+        diagnostics: {
+          ignoreCodes: [1343],
+        },
+      },
+    ],
+  },
+};

package/templates/apps/mcp/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@working-theory/mcp",
+  "version": "0.0.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc -b",
+    "type-check": "tsc --noEmit",
+    "dev": "node --experimental-vm-modules dist/index.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
+  "dependencies": {
+    "@working-theory/aeo": "workspace:*",
+    "@working-theory/api-client": "workspace:*",
+    "@working-theory/content-adapters": "workspace:*",
+    "@working-theory/license": "workspace:*",
+    "@working-theory/metadata": "workspace:*",
+    "@working-theory/schema": "workspace:*",
+    "@working-theory/validation": "workspace:*",
+    "@fastify/cors": "^11.2.0",
+    "@fastify/rate-limit": "^10.3.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "fastify": "^5.7.2",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.20.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "typescript": "^6.0.3"
+  }
+}

package/templates/apps/mcp/src/abuse/daily-cap.ts

@@ -0,0 +1,47 @@
+/**
+ * Per-IP daily cap counter.
+ *
+ * Tracks how many times each IP has triggered a capped action within a
+ * 24-hour rolling window. Uses an in-memory Map — loss on restart is
+ * acceptable for OSS. The paid layer replaces this with a durable store
+ * (Redis or the lead-routing service).
+ */
+
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_CAP = 50;
+
+interface Entry {
+  count: number;
+  windowStart: number;
+}
+
+export class DailyCapTracker {
+  private readonly cap: number;
+  private readonly counters = new Map<string, Entry>();
+
+  constructor(cap: number = DEFAULT_CAP) {
+    this.cap = cap;
+  }
+
+  /**
+   * Returns true if the given IP is below the daily cap (and increments the
+   * counter). Returns false if the cap has already been reached today.
+   */
+  isAllowed(ip: string): boolean {
+    const now = Date.now();
+    const entry = this.counters.get(ip);
+
+    if (!entry || now - entry.windowStart >= ONE_DAY_MS) {
+      // Fresh window
+      this.counters.set(ip, { count: 1, windowStart: now });
+      return true;
+    }
+
+    if (entry.count >= this.cap) {
+      return false;
+    }
+
+    entry.count += 1;
+    return true;
+  }
+}

package/templates/apps/mcp/src/abuse/email-validator.ts

@@ -0,0 +1,25 @@
+/**
+ * RFC 5322-style email format validation for abuse rules.
+ *
+ * Validates that a string is a plausibly well-formed email address.
+ * This is intentionally lenient — the goal is to reject obviously malformed
+ * values (missing @, missing domain, missing TLD) rather than to implement
+ * the full RFC 5322 grammar.
+ *
+ * Paid-layer (lead-routing.ts) adds real deliverability checks via an
+ * external service; OSS gets basic format protection.
+ */
+
+// Requires: local@domain.tld — at least one dot in the domain part.
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * Returns true if `email` passes the basic format check.
+ * Returns false for empty strings, missing @, missing domain, or missing TLD.
+ */
+export function isValidEmail(email: string): boolean {
+  if (!email || typeof email !== "string") return false;
+  // Reject multiple @ characters
+  if ((email.match(/@/g) ?? []).length !== 1) return false;
+  return EMAIL_RE.test(email);
+}

package/templates/apps/mcp/src/abuse/honeypot.ts

@@ -0,0 +1,21 @@
+/**
+ * Honeypot field check for abuse rules.
+ *
+ * If the tool input contains a `honeypot` field with any non-empty value,
+ * the request is rejected as bot traffic. Legitimate human-driven agents
+ * never populate hidden honeypot fields.
+ */
+
+/**
+ * Returns true if the honeypot field is present and non-empty in `input`.
+ * Treats missing, null, or empty-string honeypot as clean.
+ */
+export function isHoneypotTripped(input: unknown): boolean {
+  if (!input || typeof input !== "object") return false;
+  const rec = input as Record<string, unknown>;
+  if (!("honeypot" in rec)) return false;
+  const val = rec["honeypot"];
+  if (val === null || val === undefined) return false;
+  if (typeof val === "string" && val.length === 0) return false;
+  return true;
+}

package/templates/apps/mcp/src/abuse/index.ts

@@ -0,0 +1,111 @@
+/**
+ * Abuse rule orchestrator for MCP write tools.
+ *
+ * Runs all in-process heuristics for the three anonymous write tools:
+ * capture_lead, subscribe_newsletter, request_callback.
+ *
+ * Rules applied (in order):
+ *   1. User-Agent deny list (applies to all write tools)
+ *   2. Honeypot field check (applies to all write tools)
+ *   3. Email format validation (capture_lead, subscribe_newsletter)
+ *   4. Per-IP daily cap (capture_lead only)
+ *
+ * The paid layer (lead-routing.ts) extends with real abuse-protection
+ * services. OSS gets basic heuristics that stop obvious bots.
+ */
+
+import type { FastifyRequest } from "fastify";
+
+import { DailyCapTracker } from "./daily-cap.js";
+import { isValidEmail } from "./email-validator.js";
+import { isHoneypotTripped } from "./honeypot.js";
+import { buildDenyList, isUserAgentBlocked } from "./user-agent-deny.js";
+
+/** Tools that require email format validation on their input. */
+const EMAIL_VALIDATED_TOOLS = new Set(["capture_lead", "subscribe_newsletter"]);
+
+/** Tools that apply the per-IP daily cap. */
+const DAILY_CAPPED_TOOLS = new Set(["capture_lead"]);
+
+export interface AbuseConfig {
+  /** Per-IP daily cap for capture_lead. Default 50. */
+  captureLeadDailyCapPerIp: number;
+  /** Comma-separated extra UA substrings to block. */
+  blockedUserAgents: string;
+}
+
+export interface AbuseResult {
+  allowed: boolean;
+  reason?: string;
+}
+
+export class AbuseGuard {
+  private readonly denyList: RegExp[];
+  private readonly captureLeadCap: DailyCapTracker;
+
+  constructor(config: AbuseConfig) {
+    this.denyList = buildDenyList(config.blockedUserAgents);
+    this.captureLeadCap = new DailyCapTracker(config.captureLeadDailyCapPerIp);
+  }
+
+  /**
+   * Validates all abuse rules for the given tool call.
+   *
+   * @param toolName - MCP tool name (e.g. "capture_lead")
+   * @param input    - Parsed tool arguments object
+   * @param request  - Fastify request (for IP + UA extraction)
+   */
+  validate(
+    toolName: string,
+    input: unknown,
+    request: FastifyRequest,
+  ): AbuseResult {
+    const ua = request.headers["user-agent"];
+    const ip = request.ip;
+
+    // Rule 1: User-Agent deny list
+    if (isUserAgentBlocked(ua, this.denyList)) {
+      return { allowed: false, reason: "blocked user agent" };
+    }
+
+    // Rule 2: Honeypot
+    if (isHoneypotTripped(input)) {
+      return { allowed: false, reason: "honeypot field filled" };
+    }
+
+    // Rule 3: Email format validation
+    if (EMAIL_VALIDATED_TOOLS.has(toolName)) {
+      const rec = input as Record<string, unknown>;
+      const email = rec["email"];
+      if (typeof email === "string" && !isValidEmail(email)) {
+        return { allowed: false, reason: "invalid email format" };
+      }
+    }
+
+    // Rule 4: Per-IP daily cap
+    if (DAILY_CAPPED_TOOLS.has(toolName)) {
+      if (!this.captureLeadCap.isAllowed(ip)) {
+        return {
+          allowed: false,
+          reason: "daily capture_lead cap reached for this IP",
+        };
+      }
+    }
+
+    return { allowed: true };
+  }
+}
+
+/**
+ * Convenience function for constructing an AbuseGuard from env vars.
+ * Reads MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP and MCP_ABUSE_BLOCKED_USER_AGENTS.
+ */
+export function createAbuseGuardFromEnv(): AbuseGuard {
+  return new AbuseGuard({
+    captureLeadDailyCapPerIp: parseInt(
+      process.env["MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP"] ?? "50",
+      10,
+    ),
+    blockedUserAgents: process.env["MCP_ABUSE_BLOCKED_USER_AGENTS"] ?? "",
+  });
+}

package/templates/apps/mcp/src/abuse/user-agent-deny.ts

@@ -0,0 +1,58 @@
+/**
+ * User-Agent deny list for abuse rules.
+ *
+ * Built-in list blocks well-known script-runner and scraper UAs.
+ * Additional patterns can be provided via MCP_ABUSE_BLOCKED_USER_AGENTS
+ * (comma-separated substrings; case-insensitive prefix/infix match).
+ */
+
+/**
+ * Built-in patterns for well-known bot/script user agents.
+ * Each is a case-insensitive regex that matches a substring of the UA string.
+ */
+const BUILTIN_PATTERNS: RegExp[] = [
+  /python-requests/i,
+  /curl\//i,
+  /wget\//i,
+  /scrapy/i,
+  /go-http-client/i,
+  /libwww-perl/i,
+  /java\//i,
+  /httpx/i,
+  /aiohttp/i,
+  /node-fetch/i,
+  /axios/i,
+];
+
+/**
+ * Build the full deny list by merging built-in patterns with any
+ * comma-separated substrings from `extraPatterns` (e.g., from env).
+ */
+export function buildDenyList(extraPatterns?: string): RegExp[] {
+  const list = [...BUILTIN_PATTERNS];
+
+  if (extraPatterns) {
+    for (const raw of extraPatterns.split(",")) {
+      const trimmed = raw.trim();
+      if (trimmed.length > 0) {
+        // Escape special regex chars so literal substrings match correctly
+        const escaped = trimmed.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        list.push(new RegExp(escaped, "i"));
+      }
+    }
+  }
+
+  return list;
+}
+
+/**
+ * Returns true if the user agent string matches any pattern in the deny list,
+ * or if the UA is missing/empty (headless script behaviour).
+ */
+export function isUserAgentBlocked(
+  ua: string | null | undefined,
+  denyList: RegExp[],
+): boolean {
+  if (!ua || ua.trim().length === 0) return true;
+  return denyList.some((pattern) => pattern.test(ua));
+}