create-ailk 0.1.0

package/templates/apps/api/src/services/lead-routing.ts

@@ -0,0 +1,338 @@
+/**
+ * @file lead-routing.ts
+ * @description Cross-namespace lead orchestration service (ADR 0009 D3).
+ *
+ * Pipeline: validate → enrich → persist (DB with file fallback) → email.
+ * This is the first implementation of ADR 0009 D3's service-layer pattern.
+ * Future cross-namespace orchestrators in apps/api/src/services/ should mirror
+ * this shape: type-result returns, mocked-dep tests, non-transactional secondary
+ * effects, PII-safe logging.
+ *
+ * PII boundary: only { siteId, kind, ip, persisted, emailKind } appear in logs.
+ * Never log email, phone, name, or payload values.
+ */
+
+import { randomUUID } from "node:crypto";
+
+import type { Prisma } from "@working-theory/database";
+import { sendLeadNotification } from "@working-theory/email";
+import { leadInputSchema } from "@working-theory/validation";
+
+import { writeLeadFallback } from "../lib/file-fallback.js";
+import { appendLeadRecord } from "../lib/lead-capture-store.js";
+import { prisma } from "../lib/prisma.js";
+
+import { enrichLead } from "./enrichment-shim.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type LeadKind = "lead" | "subscribe" | "callback";
+
+export type RouteLeadInput =
+  | {
+      kind: "lead";
+      siteId: string;
+      source: string;
+      email: string;
+      payload: Record<string, unknown>;
+    }
+  | { kind: "subscribe"; siteId: string; email: string; source: string }
+  | {
+      kind: "callback";
+      siteId: string;
+      name: string;
+      phone: string;
+      preferredTime?: string;
+      payload: Record<string, unknown>;
+    };
+
+export type SourceMeta = {
+  ip: string;
+  userAgent: string | undefined;
+  receivedAt: string; // ISO
+};
+
+export type RouteLeadResult =
+  | {
+      ok: true;
+      id: string;
+      persisted: "db" | "file";
+      email:
+        | { ok: true; messageId: string }
+        | { ok: false; error: string }
+        | { skipped: true; reason: string };
+    }
+  | {
+      ok: false;
+      error: {
+        kind: "invalid_input" | "persist_failed" | "config_missing";
+        message: string;
+      };
+    };
+
+// ─── Validation ───────────────────────────────────────────────────────────────
+
+function validateInput(
+  input: RouteLeadInput,
+): { ok: true } | { ok: false; message: string } {
+  const result = leadInputSchema.safeParse(input);
+  if (!result.success) {
+    return {
+      ok: false,
+      message: result.error.issues[0]?.message ?? "invalid input",
+    };
+  }
+  return { ok: true };
+}
+
+// ─── DB persist ───────────────────────────────────────────────────────────────
+
+type DbRow = { id: string };
+type PersistResult =
+  | {
+      ok: true;
+      id: string;
+      source: "db";
+      skipEmail: boolean;
+      skipReason?: string;
+    }
+  | { ok: false; error: string };
+
+async function persistToDb(input: RouteLeadInput): Promise<PersistResult> {
+  if (input.kind === "lead") {
+    const row = (await prisma.lead.create({
+      data: {
+        siteId: input.siteId,
+        source: input.source,
+        email: input.email,
+        payload: input.payload as Prisma.InputJsonValue,
+      },
+      select: { id: true },
+    })) as DbRow;
+    return { ok: true, id: row.id, source: "db", skipEmail: false };
+  }
+
+  if (input.kind === "subscribe") {
+    try {
+      const row = (await prisma.subscriber.create({
+        data: {
+          siteId: input.siteId,
+          email: input.email,
+          source: input.source,
+        },
+        select: { id: true },
+      })) as DbRow;
+      return { ok: true, id: row.id, source: "db", skipEmail: false };
+    } catch (err) {
+      // Handle unique constraint violation (duplicate subscriber)
+      if (
+        err != null &&
+        typeof err === "object" &&
+        "code" in err &&
+        (err as { code: string }).code === "P2002"
+      ) {
+        const existing = (await prisma.subscriber.findUnique({
+          where: { siteId_email: { siteId: input.siteId, email: input.email } },
+          select: { id: true },
+        })) as DbRow | null;
+        const existingId = existing?.id ?? "duplicate-no-id";
+        return {
+          ok: true,
+          id: existingId,
+          source: "db",
+          skipEmail: true,
+          skipReason: "duplicate",
+        };
+      }
+      throw err; // re-throw non-P2002 errors to trigger fallback
+    }
+  }
+
+  // kind === "callback"
+  const row = (await prisma.callback.create({
+    data: {
+      siteId: input.siteId,
+      name: input.name,
+      phone: input.phone,
+      ...(input.preferredTime !== undefined && {
+        preferredTime: input.preferredTime,
+      }),
+      payload: input.payload as Prisma.InputJsonValue,
+    },
+    select: { id: true },
+  })) as DbRow;
+  return { ok: true, id: row.id, source: "db", skipEmail: false };
+}
+
+// ─── Email ────────────────────────────────────────────────────────────────────
+
+type EmailResult =
+  | { ok: true; messageId: string }
+  | { ok: false; error: string }
+  | { skipped: true; reason: string };
+
+async function sendEmail(
+  input: RouteLeadInput,
+  id: string,
+): Promise<EmailResult> {
+  const to = process.env.AILK_LEAD_NOTIFICATION_TO;
+  const from = process.env.AILK_LEAD_NOTIFICATION_FROM;
+
+  if (!to || !from) {
+    return { skipped: true, reason: "env_unset" };
+  }
+
+  const leadForEmail = {
+    id,
+    siteId: input.siteId,
+    source: input.kind === "callback" ? "callback" : input.source,
+    email: input.kind === "callback" ? "" : input.email,
+    payload: input.kind === "subscribe" ? {} : input.payload,
+    createdAt: new Date().toISOString(),
+  };
+
+  const emailResult = await sendLeadNotification({
+    lead: leadForEmail,
+    recipientEmail: to,
+    fromAddress: from,
+  });
+
+  if (emailResult.ok) {
+    return { ok: true, messageId: emailResult.messageId };
+  }
+
+  const { kind, message } = emailResult.error;
+  if (kind === "config_missing") {
+    return { skipped: true, reason: "resend_key_unset" };
+  }
+  return { ok: false, error: `${kind}: ${message}` };
+}
+
+// ─── Main export ──────────────────────────────────────────────────────────────
+
+export async function routeLead(
+  input: RouteLeadInput,
+  sourceMeta: SourceMeta,
+): Promise<RouteLeadResult> {
+  // 1. Validate
+  const validation = validateInput(input);
+  if (!validation.ok) {
+    return {
+      ok: false,
+      error: { kind: "invalid_input", message: validation.message },
+    };
+  }
+
+  // 2. Guard: if file capture is disabled AND no DB is configured, bail early.
+  // Both paths are unavailable — returning a clear error is better than a
+  // misleading 201 or a stack trace from Prisma on a missing DATABASE_URL.
+  if (
+    process.env.LEAD_CAPTURE_FILE_DISABLED === "true" &&
+    !process.env.DATABASE_URL
+  ) {
+    return {
+      ok: false,
+      error: {
+        kind: "config_missing",
+        message: "Lead capture is not configured.",
+      },
+    };
+  }
+
+  // 3. Enrich (reserved for Phase 3 — today returns lead unchanged).
+  // Cast via unknown: enrichLead accepts CreateLead (B3 shim type) but the
+  // pass-through contract means RouteLeadInput is safe here until Phase 3 wires
+  // the real enrichment call with proper type alignment.
+  await enrichLead(input as unknown as Parameters<typeof enrichLead>[0]);
+
+  // 4. Persist primary (DB), fallback to file on error
+  let id: string;
+  let persisted: "db" | "file";
+  let skipEmail = false;
+  let skipReason: string | undefined;
+
+  try {
+    const dbResult = await persistToDb(input);
+    if (!dbResult.ok) {
+      // persistToDb returned ok:false — defensive guard; current impl doesn't reach this
+      return {
+        ok: false,
+        error: { kind: "persist_failed", message: dbResult.error },
+      };
+    }
+    id = dbResult.id;
+    persisted = "db";
+    skipEmail = dbResult.skipEmail;
+    skipReason = dbResult.skipReason;
+  } catch (dbErr) {
+    // 5. File fallback
+    // Include a UUID suffix so concurrent fallbacks produce unique IDs even
+    // within the same millisecond. Format still matches /^[a-z0-9_-]{8,64}$/i.
+    const fallbackLead = {
+      id: `fallback-${Date.now()}-${randomUUID().slice(0, 8)}`,
+      siteId: input.siteId,
+      source: input.kind === "callback" ? "callback" : input.source,
+      email: input.kind === "callback" ? "" : input.email,
+      payload: input.kind === "subscribe" ? {} : input.payload,
+      createdAt: sourceMeta.receivedAt,
+    };
+
+    let fallbackResult;
+    try {
+      fallbackResult = await writeLeadFallback(fallbackLead);
+    } catch {
+      const dbMsg = dbErr instanceof Error ? dbErr.message : String(dbErr);
+      return {
+        ok: false,
+        error: {
+          kind: "persist_failed",
+          message: `db: ${dbMsg}; fallback threw`,
+        },
+      };
+    }
+
+    if (!fallbackResult.ok) {
+      const dbMsg = dbErr instanceof Error ? dbErr.message : String(dbErr);
+      return {
+        ok: false,
+        error: {
+          kind: "persist_failed",
+          message: `db: ${dbMsg}; fallback: ${fallbackResult.error.message}`,
+        },
+      };
+    }
+
+    id = fallbackLead.id;
+    persisted = "file";
+  }
+
+  // 6. Write to lead-capture JSONL (always-on canonical AX surface).
+  // Best-effort — a write failure does NOT roll back persistence or block email.
+  // The file is the agent-readable surface; DB is the transactional record.
+  const captureRecord = {
+    id: id!,
+    createdAt: sourceMeta.receivedAt,
+    source: input.kind === "callback" ? "callback" : input.source,
+    data:
+      input.kind === "callback"
+        ? { name: input.name, phone: input.phone, ...(input.payload ?? {}) }
+        : input.kind === "subscribe"
+          ? { email: input.email }
+          : { email: input.email, ...(input.payload ?? {}) },
+    metadata: {
+      ip: sourceMeta.ip,
+      userAgent: sourceMeta.userAgent,
+    },
+  };
+  await appendLeadRecord(captureRecord);
+
+  // 7. Email notification (best-effort — never rolls back persistence)
+  let emailResult: EmailResult;
+  if (skipEmail) {
+    emailResult = { skipped: true, reason: skipReason ?? "skipped" };
+  } else {
+    emailResult = await sendEmail(input, id!);
+  }
+
+  return { ok: true, id: id!, persisted, email: emailResult };
+}

package/templates/apps/api/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "composite": true,
+    "types": ["node", "jest"]
+  },
+  "include": ["src/**/*"],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/__tests__/**",
+    "**/*.test.ts",
+    "**/*.spec.ts"
+  ],
+  "references": [
+    { "path": "../../packages/analytics" },
+    { "path": "../../packages/common" },
+    { "path": "../../packages/content-adapters" },
+    { "path": "../../packages/content-projection" },
+    { "path": "../../packages/email" },
+    { "path": "../../packages/license" },
+    { "path": "../../packages/observability" },
+    { "path": "../../packages/schema" },
+    { "path": "../../packages/stripe-client" },
+    { "path": "../../packages/validation" }
+  ]
+}

package/templates/apps/api/vercel.json

@@ -0,0 +1,17 @@
+{
+  "version": 2,
+  "ignoreCommand": "git diff --quiet HEAD^ HEAD -- apps/api packages database",
+  "buildCommand": "cd ../.. && pnpm run --filter @ai-launch-kit/backend build:vercel",
+  "installCommand": "cd ../.. && pnpm install --frozen-lockfile",
+  "outputDirectory": "public",
+  "framework": null,
+  "routes": [
+    {
+      "src": "/(.*)",
+      "dest": "/api/index.ts"
+    }
+  ],
+  "env": {
+    "NODE_ENV": "production"
+  }
+}

package/templates/apps/mcp/.env.example

@@ -0,0 +1,52 @@
+# @working-theory/mcp — Environment variables
+#
+# Copy to .env and fill in values for your deployment.
+# All variables are optional; defaults are shown.
+
+# ── Transport selection ────────────────────────────────────────────────────────
+
+# Which transport to boot. "stdio" is the default for local subprocess use
+# (Claude Desktop, Cursor, etc.). "http" enables the network-reachable transport.
+MCP_TRANSPORT=stdio
+
+# ── HTTP transport ─────────────────────────────────────────────────────────────
+# Only read when MCP_TRANSPORT=http.
+
+# Port to bind the HTTP server on.
+MCP_HTTP_PORT=8080
+
+# URL path for the MCP endpoint.
+MCP_HTTP_PATH=/mcp
+
+# Public URL of the HTTP transport (used by /.well-known/mcp.json discovery).
+# Set this to the externally-reachable URL of the MCP server.
+# Example: https://mcp.yourdomain.com
+MCP_PUBLIC_HTTP_URL=
+
+# ── Rate limiting ──────────────────────────────────────────────────────────────
+
+# Max requests per minute per IP for read tools.
+MCP_RATE_LIMIT_READ_PER_MIN=60
+
+# Max requests per minute per IP for write tools (capture_lead, subscribe_newsletter, request_callback).
+MCP_RATE_LIMIT_WRITE_PER_MIN=10
+
+# ── CORS (write tools) ─────────────────────────────────────────────────────────
+# Read tools allow any origin. Write tools require explicit allowlist.
+
+# Comma-separated list of origins allowed to call write tools.
+# Empty = no cross-origin writes (most secure default).
+# Use "*" only in development.
+# Example: https://app.yourdomain.com,https://other.yourdomain.com
+MCP_CORS_WRITE_ALLOWED_ORIGINS=
+
+# ── Abuse protection ───────────────────────────────────────────────────────────
+
+# Maximum number of capture_lead submissions per IP per day.
+MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP=50
+
+# Comma-separated list of User-Agent substrings to block (case-insensitive).
+# Built-in list already blocks curl, wget, python-requests, scrapy, etc.
+# Add extra patterns here as needed.
+# Example: BadBot,EvilCrawler
+MCP_ABUSE_BLOCKED_USER_AGENTS=

package/templates/apps/mcp/CLAUDE.md

@@ -0,0 +1,84 @@
+# apps/mcp — MCP Server
+
+Inherits root `CLAUDE.md`. This file adds MCP-specific rules.
+
+## Stack
+
+- TypeScript, MCP SDK
+- Transport: stdio at launch
+- Discovery: `/.well-known/mcp.json` published from `apps/web`
+
+## Identity-blind by design (hard rule)
+
+- OSS tools accept NO identity argument. No user, no session, no role.
+- Anonymous-agent surface is the wedge. Adding identity to a tool breaks the OSS thesis.
+- Identity-aware behavior (deferred Pro tools) lives behind a paid-tier check in `@working-theory/*` — never in the tool signature itself.
+
+## API ↔ MCP parity (hard rule)
+
+Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change the endpoint in the same PR. CI enforces.
+
+<!-- SOFT_LOCK_OK: doc clarification for issue #2238 — explaining 14 vs 15 vs 18 tool counts in CLAUDE.md (no code or signature changes) -->
+
+## The 14 OSS tools (enabled at launch)
+
+**Read (9):** `list_pages`, `read_content`, `search_content`, `get_site_info`, `get_business_hours`, `get_locations`, `get_offerings`, `get_pricing`, `get_faq`
+**Conversion-write (3):** `capture_lead`, `subscribe_newsletter`, `request_callback`
+**Maintenance (2):** `audit`, `scaffold`
+
+### Why the catalog reports 18 and the server registers 17
+
+- **18 in the catalog / parity test**: the `TOOLS` array in
+  `packages/metadata/src/mcp-tool-catalog.ts` defines 18 tools; the parity
+  test's `tools.size === 18` assertion counts that full catalog.
+- **17 registered at runtime**: `createMcpServer` (`apps/mcp/src/server.ts`)
+  registers `getMcpToolRegistrations()` minus `OSS_DISABLED_TOOLS`, whose only
+  entry is `start_purchase` — so 17 tools are registered on the server.
+- **14 free anonymous tools**: of the 17 registered, three are Pro tools
+  (`create_page`, `update_page`, `delete_page`) gated at call time by
+  `requirePaidTier()`, leaving the 14 free anonymous tools above.
+  `index.ts` is the transport entry point and exports no tools — registration
+  is entirely via `createMcpServer`.
+
+## Pro + disabled tools (not part of the free surface)
+
+- `create_page`, `update_page`, `delete_page` — high-stakes CMS writes,
+  `tier: "pro"`. Registered by `createMcpServer` but gated at call time by
+  `requirePaidTier()` (`apps/mcp/src/lib/require-paid-tier.ts`) — the paid-tier
+  check lives in the handler, never in the tool signature, per the
+  identity-blind rule above.
+- `start_purchase` — transactional, Pro-only; the sole entry in
+  `OSS_DISABLED_TOOLS`, so it is filtered out of catalog registration and the
+  server entirely. Re-enable criteria live at
+  `docs/internal/roadmaps/phase-3-readiness.md`.
+
+Don't add identity logic to any tool signature. Don't remove `start_purchase`
+from `OSS_DISABLED_TOOLS` without satisfying the Phase 3 re-enable criteria.
+
+## Tool implementation pattern
+
+1. Input/output schemas in `@working-theory/validation`.
+2. Tool handler calls the matching `apps/api` endpoint (or shares a service when collocated).
+3. Errors map to MCP error responses using the same code the HTTP endpoint returned.
+
+Never duplicate business logic. The tool is a thin adapter; the endpoint owns the implementation.
+
+## Pro post-processing pattern
+
+Pro features add post-processing behind the **same anonymous tool surface**. Tool signature never changes — what changes is what happens after the call.
+
+Example (lead routing):
+
+- `apps/mcp` tool signature: unchanged
+- `apps/api` endpoint: checks JWT entitlement via `@working-theory/license-client`
+- Pipeline: entirely in `@working-theory/lead-routing`
+
+## What NOT to do
+
+- Don't add identity arguments to OSS tools.
+- Don't expose a Pro tool without its `requirePaidTier()` gate.
+- Don't import `@working-theory/*` from `apps/mcp`.
+- Don't add a tool without the matching `apps/api` endpoint.
+- Don't put business logic in tool handlers — they're adapters.
+
+Last updated: 2026-07-09 — corrected the tool-count explanation (18 catalog → 17 registered → 14 free anonymous) and the Pro-tool gating (registered + `requirePaidTier()`-gated, not `OSS_DISABLED_TOOLS`-disabled).

package/templates/apps/mcp/__tests__/abuse/daily-cap.test.ts

@@ -0,0 +1,52 @@
+/**
+ * Unit tests for abuse/daily-cap.ts
+ *
+ * Verifies per-IP daily cap counter with configurable limit and daily reset.
+ */
+
+import { DailyCapTracker } from "../../src/abuse/daily-cap.js";
+
+describe("DailyCapTracker", () => {
+  it("allows requests below the cap", () => {
+    const tracker = new DailyCapTracker(3);
+    expect(tracker.isAllowed("1.2.3.4")).toBe(true);
+    expect(tracker.isAllowed("1.2.3.4")).toBe(true);
+    expect(tracker.isAllowed("1.2.3.4")).toBe(true);
+  });
+
+  it("blocks requests at and above the cap", () => {
+    const tracker = new DailyCapTracker(2);
+    tracker.isAllowed("1.2.3.4");
+    tracker.isAllowed("1.2.3.4");
+    // Third call should be blocked
+    expect(tracker.isAllowed("1.2.3.4")).toBe(false);
+  });
+
+  it("tracks IPs independently", () => {
+    const tracker = new DailyCapTracker(1);
+    tracker.isAllowed("1.2.3.4");
+    // Exhausted for .4 but .5 is fresh
+    expect(tracker.isAllowed("1.2.3.4")).toBe(false);
+    expect(tracker.isAllowed("1.2.3.5")).toBe(true);
+  });
+
+  it("resets counters after the daily window expires", () => {
+    jest.useFakeTimers();
+    const tracker = new DailyCapTracker(1);
+    tracker.isAllowed("1.2.3.4");
+    expect(tracker.isAllowed("1.2.3.4")).toBe(false);
+
+    // Advance 24 hours + 1ms
+    jest.advanceTimersByTime(24 * 60 * 60 * 1000 + 1);
+    expect(tracker.isAllowed("1.2.3.4")).toBe(true);
+    jest.useRealTimers();
+  });
+
+  it("uses cap=50 when none supplied", () => {
+    const tracker = new DailyCapTracker();
+    for (let i = 0; i < 50; i++) {
+      expect(tracker.isAllowed("9.9.9.9")).toBe(true);
+    }
+    expect(tracker.isAllowed("9.9.9.9")).toBe(false);
+  });
+});

package/templates/apps/mcp/__tests__/abuse/email-validator.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Unit tests for abuse/email-validator.ts
+ *
+ * Verifies RFC 5322-style email format validation used by
+ * capture_lead and subscribe_newsletter abuse rules.
+ */
+
+import { isValidEmail } from "../../src/abuse/email-validator.js";
+
+describe("isValidEmail", () => {
+  it("accepts a well-formed email address", () => {
+    expect(isValidEmail("jane@example.com")).toBe(true);
+  });
+
+  it("accepts email with subdomain", () => {
+    expect(isValidEmail("user@mail.example.com")).toBe(true);
+  });
+
+  it("accepts email with plus addressing", () => {
+    expect(isValidEmail("user+tag@example.com")).toBe(true);
+  });
+
+  it("rejects empty string", () => {
+    expect(isValidEmail("")).toBe(false);
+  });
+
+  it("rejects missing @", () => {
+    expect(isValidEmail("notanemail")).toBe(false);
+  });
+
+  it("rejects missing domain", () => {
+    expect(isValidEmail("user@")).toBe(false);
+  });
+
+  it("rejects missing local part", () => {
+    expect(isValidEmail("@example.com")).toBe(false);
+  });
+
+  it("rejects missing TLD dot", () => {
+    expect(isValidEmail("user@localhost")).toBe(false);
+  });
+
+  it("rejects plainly malformed input", () => {
+    expect(isValidEmail("not@valid@example.com")).toBe(false);
+  });
+});

package/templates/apps/mcp/__tests__/abuse/honeypot.test.ts

@@ -0,0 +1,36 @@
+/**
+ * Unit tests for abuse/honeypot.ts
+ *
+ * Verifies that a non-empty `honeypot` field in tool input triggers rejection.
+ */
+
+import { isHoneypotTripped } from "../../src/abuse/honeypot.js";
+
+describe("isHoneypotTripped", () => {
+  it("returns false when input has no honeypot field", () => {
+    expect(isHoneypotTripped({ name: "Jane", email: "jane@example.com" })).toBe(
+      false,
+    );
+  });
+
+  it("returns false when honeypot field is empty string", () => {
+    expect(isHoneypotTripped({ honeypot: "" })).toBe(false);
+  });
+
+  it("returns true when honeypot field is non-empty", () => {
+    expect(isHoneypotTripped({ honeypot: "bot-filled" })).toBe(true);
+  });
+
+  it("returns true when honeypot field is a space", () => {
+    expect(isHoneypotTripped({ honeypot: " " })).toBe(true);
+  });
+
+  it("returns false for null honeypot", () => {
+    expect(isHoneypotTripped({ honeypot: null })).toBe(false);
+  });
+
+  it("accepts non-string inputs without throwing", () => {
+    expect(() => isHoneypotTripped(null)).not.toThrow();
+    expect(isHoneypotTripped(null)).toBe(false);
+  });
+});