create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/waitlist-scoring.ts

@@ -0,0 +1,166 @@
+/**
+ * @file waitlist-scoring.ts
+ * @description The Prisma-touching glue for the rules-layer scoring engine —
+ * A2 (#4662 D6).
+ *
+ * `scoreCompletedSignup` is the ONE `prisma.waitlistScore.upsert` write path
+ * in `apps/api` — one row per (lead, EXPERIMENT), re-scoring overwrites,
+ * never appends (A1 D3, scoped per experiment by #5036 D6d: a visitor who
+ * joins two founders' waitlists is one lead with two scores, and a
+ * lead-only key let the second silently erase the first). It loads the owning `WaitlistExperiment`, parses its config,
+ * evaluates via the pure `@working-theory/validation` evaluator, and
+ * persists the result. Every failure mode (no experiment row, an invalid
+ * config, an evaluator throw, a Prisma error) returns a typed outcome — it
+ * never throws to its caller (`flow-engine.ts`'s `completeSubmission`, which
+ * wraps the call in its own fail-soft try/catch as a residual net).
+ *
+ * PII boundary: logs carry only `{siteId, experimentKey, leadId, kind}` —
+ * never an answer value or the assembled payload (mirrors
+ * `waitlist-experiments.ts` / `flow-engine.ts`'s boundary).
+ */
+
+import type { Prisma } from "@working-theory/database";
+import { logger } from "@working-theory/observability";
+import {
+  answersFromPayload,
+  evaluateWaitlistScoring,
+  waitlistExperimentConfigSchema,
+  type WaitlistFlags,
+} from "@working-theory/validation";
+
+import { prisma } from "../lib/prisma.js";
+
+import { compileAndStorePlaybook, TARGETING_MATURITY_EXPERIMENT_KEY } from "./playbook-compile.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type ScoreCompletedSignupInput = {
+  siteId: string;
+  leadId: string;
+  experimentKey: string;
+  waitlistKey: string;
+  payload: Record<string, unknown>;
+  flags?: WaitlistFlags;
+};
+
+export type ScoreCompletedSignupSkipReason = "no_experiment" | "no_scoring";
+export type ScoreCompletedSignupErrorKind =
+  | "invalid_config"
+  | "evaluation_failed"
+  | "persist_failed";
+
+export type ScoreCompletedSignupResult =
+  | { ok: true; tier: string }
+  | { ok: true; skipped: ScoreCompletedSignupSkipReason }
+  | { ok: false; error: { kind: ScoreCompletedSignupErrorKind } };
+
+function errKindOf(err: unknown): string {
+  return err instanceof Error ? err.constructor.name : typeof err;
+}
+
+// ─── scoreCompletedSignup — the ONE write path (D6) ─────────────────────────
+
+/**
+ * Load the `[siteId, experimentKey]` `WaitlistExperiment`, evaluate the
+ * signup's answers against its `scoring` register (when declared), and
+ * upsert exactly one `WaitlistScore` row on `[leadId]`.
+ */
+export async function scoreCompletedSignup(
+  input: ScoreCompletedSignupInput,
+): Promise<ScoreCompletedSignupResult> {
+  const { siteId, leadId, experimentKey, waitlistKey, payload, flags } = input;
+
+  const row = await prisma.waitlistExperiment.findUnique({
+    where: { siteId_key: { siteId, key: experimentKey } },
+  });
+  if (!row) {
+    return { ok: true, skipped: "no_experiment" };
+  }
+
+  const parsed = waitlistExperimentConfigSchema.safeParse(row.config);
+  if (!parsed.success) {
+    logger.error(
+      { siteId, experimentKey, leadId, kind: "invalid_config" },
+      "[waitlist-scoring] experiment config failed validation (defensive — the row was validated on write)",
+    );
+    return { ok: false, error: { kind: "invalid_config" } };
+  }
+  const config = parsed.data;
+  if (!config.scoring) {
+    return { ok: true, skipped: "no_scoring" };
+  }
+
+  const answers = answersFromPayload(config.questionSet, payload);
+  let evaluation;
+  try {
+    evaluation = evaluateWaitlistScoring(config.scoring, answers, flags ?? {});
+  } catch (err) {
+    logger.error(
+      { siteId, experimentKey, leadId, kind: "evaluation_failed", errKind: errKindOf(err) },
+      "[waitlist-scoring] evaluation failed",
+    );
+    return { ok: false, error: { kind: "evaluation_failed" } };
+  }
+
+  let scoreRow;
+  try {
+    scoreRow = await prisma.waitlistScore.upsert({
+      where: { leadId_experimentKey: { leadId, experimentKey } },
+      create: {
+        siteId,
+        leadId,
+        experimentKey,
+        waitlistKey,
+        tier: evaluation.tier,
+        score: evaluation.score,
+        categoryScores: evaluation.categoryScores as unknown as Prisma.InputJsonValue,
+        ruleTrace: evaluation.ruleTrace as unknown as Prisma.InputJsonValue,
+      },
+      update: {
+        tier: evaluation.tier,
+        score: evaluation.score,
+        categoryScores: evaluation.categoryScores as unknown as Prisma.InputJsonValue,
+        ruleTrace: evaluation.ruleTrace as unknown as Prisma.InputJsonValue,
+      },
+    });
+  } catch (err) {
+    logger.error(
+      { siteId, experimentKey, leadId, kind: "persist_failed", errKind: errKindOf(err) },
+      "[waitlist-scoring] persist failed",
+    );
+    return { ok: false, error: { kind: "persist_failed" } };
+  }
+
+  // FEAT-074 U4a (#4715): the compile is the next link in this ONE write
+  // path (D4) — gated on experimentKey, fail-soft internally
+  // (compileAndStorePlaybook never throws by contract). The try/catch here
+  // is the residual safety net (mirrors flow-engine.ts's own "swallowed by
+  // design" fulfillment guard) — the score row above is ALREADY persisted,
+  // so a genuine escape here must never turn this already-successful score
+  // into a thrown failure this function's own header promises it never does.
+  if (experimentKey === TARGETING_MATURITY_EXPERIMENT_KEY) {
+    try {
+      await compileAndStorePlaybook({
+        siteId,
+        leadId,
+        experimentKey,
+        scoreId: scoreRow.id,
+        tier: evaluation.tier,
+        ruleTrace: evaluation.ruleTrace,
+      });
+    } catch (err) {
+      logger.error(
+        {
+          siteId,
+          experimentKey,
+          leadId,
+          kind: "playbook_compile_escaped",
+          errKind: errKindOf(err),
+        },
+        "[waitlist-scoring] compileAndStorePlaybook escaped its own fail-soft catch — the score is unaffected",
+      );
+    }
+  }
+
+  return { ok: true, tier: evaluation.tier };
+}

package/templates/apps/api/src/services/waitlist-signups.ts

@@ -0,0 +1,165 @@
+/**
+ * @file waitlist-signups.ts
+ * @description The respondent read (#4731 D2/D3/D4) — `readMySignup`, the
+ * ONLY read path behind `GET /v1/waitlist-signups/me`: a signed-in,
+ * email-verified user reads their OWN newest waitlist signup for one
+ * experiment. Nothing here enumerates, nothing accepts an email, nothing
+ * reads across sites.
+ *
+ * Mirrors `lead-promotion.ts` (ADR 0009 D3 service-layer pattern): the same
+ * `User {id, email, emailVerified}` read, the same verified-email refusal
+ * (D2 there — the consent basis for linking anonymous-lead PII to a user;
+ * here a hard 403, evaluated BEFORE any Lead read), and a scalar-only join
+ * to the inbox namespace by email — `Lead` carries no `@relation` (ADR 0009
+ * invariant #1), so the read is four narrow queries, each scoped to
+ * `currentSiteId()` (#4665 D3: the scope is a parameter of every query,
+ * never a post-filter).
+ *
+ * Email normalization (#4731 D3, the contract's open question): the
+ * respondent email is persisted AS TYPED — `flow-engine.ts`'s
+ * `extractMappedEmail` and `lead-routing.ts`'s `persistToDb` neither trim
+ * nor lower-case it (the boundary validator `z.string().email()` already
+ * rejects surrounding whitespace). So the match is `lower(trim())` on both
+ * sides: `equals` on the trimmed, lower-cased user email with
+ * `mode: "insensitive"` for the stored value.
+ *
+ * PII boundary: logs carry only `{ siteId, experimentKey, leadId, kind }` —
+ * never email, payload, or an answer value.
+ */
+
+import { logger } from "@working-theory/observability";
+import {
+  aeoScoreResultSchema,
+  type WaitlistSignupMeResponse,
+} from "@working-theory/validation";
+
+import { prisma } from "../lib/prisma.js";
+import { currentSiteId } from "../lib/site.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type ReadMySignupResult =
+  | { ok: true; value: WaitlistSignupMeResponse }
+  | {
+      ok: false;
+      error: {
+        kind: "not_found_user" | "email_unverified" | "signup_not_found";
+        message: string;
+      };
+    };
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** A string-valued payload key, or undefined when absent / not a string. */
+function readPayloadString(payload: unknown, key: string): string | undefined {
+  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) return undefined;
+  const value = (payload as Record<string, unknown>)[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+/** A schema-defensive read of the stored `FlowSession.aeoScore` JSON value (mirrors flow-engine.ts). */
+function readAeoScore(value: unknown): WaitlistSignupMeResponse["aeoScore"] {
+  if (value === null || value === undefined) return null;
+  const parsed = aeoScoreResultSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
+
+const SIGNUP_NOT_FOUND: ReadMySignupResult = {
+  ok: false,
+  error: { kind: "signup_not_found", message: "Signup not found" },
+};
+
+// ─── Main export ──────────────────────────────────────────────────────────────
+
+/**
+ * Read the calling user's newest signup for `experimentKey` at the current
+ * site. `userId` is the auth preHandler's `request.userId` — the ONLY
+ * identity input; `experimentKey` is boundary-validated by the route.
+ *
+ * Result kinds (the route maps them to HTTP):
+ *   - `not_found_user`   — no `User` row for `userId` (404 on the wire).
+ *   - `email_unverified` — `User.emailVerified !== true`; refused BEFORE any
+ *                          Lead read (403).
+ *   - `signup_not_found` — no `Lead` at this site with this user's email and
+ *                          this `experimentKey` (or a corrupt row missing
+ *                          `waitlistKey`) (404).
+ */
+export async function readMySignup(
+  userId: string,
+  experimentKey: string,
+): Promise<ReadMySignupResult> {
+  const siteId = currentSiteId();
+
+  // D2 — the exact read lead-promotion.ts performs, mirrored not forked.
+  const user = await prisma.user.findUnique({
+    where: { id: userId },
+    select: { id: true, email: true, emailVerified: true },
+  });
+  if (!user) {
+    return { ok: false, error: { kind: "not_found_user", message: "User not found" } };
+  }
+
+  // D2 — the verified-email gate is a service-level invariant: an unverified
+  // address never reaches a Lead read, whatever the call site.
+  if (user.emailVerified !== true) {
+    return {
+      ok: false,
+      error: { kind: "email_unverified", message: "Verify your email to view your signup" },
+    };
+  }
+
+  // D3 — lower(trim()) on both sides; D4 — scoped, newest wins.
+  const lead = await prisma.lead.findFirst({
+    where: {
+      siteId,
+      email: { equals: user.email.trim().toLowerCase(), mode: "insensitive" },
+      payload: { path: ["experimentKey"], equals: experimentKey },
+    },
+    orderBy: { createdAt: "desc" },
+    select: { id: true, payload: true, createdAt: true },
+  });
+  if (!lead) return SIGNUP_NOT_FOUND;
+
+  // `waitlistKey` is server-written LAST beside `experimentKey` (flow-engine
+  // D4) — a lead carrying one without the other is corrupt data, treated as
+  // not-found rather than emitting an out-of-contract value (the
+  // waitlist-dashboard.ts `getSignup` posture, PR #4687).
+  const waitlistKey = readPayloadString(lead.payload, "waitlistKey");
+  if (!waitlistKey) {
+    logger.warn(
+      { siteId, experimentKey, leadId: lead.id, kind: "missing_waitlist_key" },
+      "[waitlist-signups] signup missing waitlistKey — treating as not_found",
+    );
+    return SIGNUP_NOT_FOUND;
+  }
+
+  // D4 — `@@unique([leadId, experimentKey])` (#5036 D6d); the scope ANDed in,
+  // never a post-filter.
+  const scoreRow = await prisma.waitlistScore.findFirst({
+    where: { leadId: lead.id, siteId, experimentKey },
+    select: { tier: true, score: true },
+  });
+
+  // D4 — the completing session (leadId is stamped in the same completion
+  // call that created the lead). Fallback to Lead.createdAt if absent (D5).
+  const session = await prisma.flowSession.findFirst({
+    where: { leadId: lead.id, siteId, completedAt: { not: null } },
+    orderBy: { completedAt: "desc" },
+    select: { aeoScore: true, completedAt: true },
+  });
+
+  // D5 — seven fields, nothing more. `waitlistKey` and `q3` are the ONLY
+  // payload keys that leave the row.
+  return {
+    ok: true,
+    value: {
+      experimentKey,
+      waitlistKey,
+      completedAt: (session?.completedAt ?? lead.createdAt).toISOString(),
+      tier: scoreRow?.tier ?? null,
+      score: scoreRow?.score ?? null,
+      aeoScore: readAeoScore(session?.aeoScore),
+      answers: { q3: readPayloadString(lead.payload, "q3") ?? null },
+    },
+  };
+}

package/templates/apps/api/src/vercel-handler.ts

@@ -0,0 +1,165 @@
+/**
+ * Vercel Serverless Function Handler for Customer Template Backend
+ * This file wraps the Fastify server for Vercel's serverless functions
+ */
+
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+import { logger } from '@working-theory/observability';
+import type { InjectOptions } from 'fastify';
+
+import type { build as buildServer } from './server.js';
+
+type FastifyServer = Awaited<ReturnType<typeof buildServer>>;
+
+// Import the build function from server
+async function getBuildFunction(): Promise<typeof buildServer> {
+  try {
+    const srcModule = await import('./server.js');
+    logger.info('[Vercel Handler] Using server from src/server.js');
+    return srcModule.build;
+  } catch (srcError) {
+    logger.error(
+      {
+        err: srcError instanceof Error ? srcError.message : String(srcError),
+        stack: srcError instanceof Error ? srcError.stack : undefined,
+      },
+      '[Vercel Handler] Failed to import server',
+    );
+    throw new Error(`Cannot find server module: ${srcError instanceof Error ? srcError.message : String(srcError)}`, { cause: srcError });
+  }
+}
+
+// Initialize build function
+const buildPromise = getBuildFunction();
+let serverInstance: FastifyServer | null = null;
+
+/**
+ * Get or create the Fastify server instance
+ */
+async function getServer() {
+  if (!serverInstance) {
+    logger.info('[Vercel Handler] Building server instance...');
+    const startTime = Date.now();
+
+    try {
+      const buildTimeout = new Promise<never>((_, reject) => {
+        setTimeout(() => reject(new Error('Server build timeout after 10s')), 10000);
+      });
+
+      const build = await Promise.race([buildPromise, buildTimeout]);
+      logger.info('[Vercel Handler] Build function obtained, creating server...');
+
+      const initTimeout = new Promise<never>((_, reject) => {
+        setTimeout(() => reject(new Error('Server initialization timeout after 10s')), 10000);
+      });
+
+      serverInstance = await Promise.race([build(), initTimeout]);
+
+      const buildTime = Date.now() - startTime;
+      logger.info({ buildTime }, '[Vercel Handler] Server built successfully');
+    } catch (error) {
+      const buildTime = Date.now() - startTime;
+      logger.error({ err: error, buildTime }, '[Vercel Handler] Failed to build server');
+      throw new Error(`Server build failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+  }
+  return serverInstance;
+}
+
+/**
+ * Vercel serverless function handler
+ */
+export default async function handler(
+  req: VercelRequest,
+  res: VercelResponse
+): Promise<void> {
+  const timeout = setTimeout(() => {
+    if (!res.headersSent) {
+      logger.error('[Vercel Handler] Request timeout');
+      res.status(504).json({
+        error: 'Gateway Timeout',
+        message: 'Request took too long to process',
+      });
+    }
+  }, 25000);
+
+  try {
+    logger.info({ method: req.method, url: req.url }, '[Vercel Handler] Starting request');
+
+    const server = await getServer();
+
+    const url = new URL(req.url || '/', 'http://localhost');
+    const pathname = url.pathname;
+
+    logger.info({ method: req.method, pathname }, '[Vercel Handler] Processing request');
+
+    // Strip content-length/content-encoding before forwarding. Both
+    // describe the ORIGINAL byte stream the client sent; req.body here is
+    // already the PARSED object, and light-my-request re-serializes it
+    // itself. It only computes a fresh content-length when the header is
+    // absent (`req.headers['content-length'] = req.headers['content-length']
+    // || ...`), so a stale header survives and Fastify's own content-length
+    // check rejects any body whose re-serialized length differs from the
+    // original — e.g. pretty-printed JSON or a trailing newline
+    // (FST_ERR_CTP_INVALID_CONTENT_LENGTH, #5168). Matched case-insensitively
+    // since header casing isn't guaranteed, even though Node lower-cases
+    // incoming header names in practice.
+    const forwardedHeaders = { ...req.headers } as Record<string, string>;
+    for (const key of Object.keys(forwardedHeaders)) {
+      if (key.toLowerCase() === 'content-length' || key.toLowerCase() === 'content-encoding') {
+        delete forwardedHeaders[key];
+      }
+    }
+
+    const fastifyRequest = {
+      method: req.method || 'GET',
+      url: pathname,
+      headers: forwardedHeaders,
+      body: req.body,
+      query: req.query as Record<string, string>,
+    };
+
+    const response = await server.inject(fastifyRequest as InjectOptions);
+
+    logger.info({ status: response.statusCode }, '[Vercel Handler] Response status');
+
+    clearTimeout(timeout);
+
+    res.status(response.statusCode);
+
+    Object.entries(response.headers).forEach(([key, value]) => {
+      if (value !== undefined && !res.headersSent) {
+        const headerValue = Array.isArray(value)
+          ? value.map((v) => String(v)).join(', ')
+          : String(value);
+        res.setHeader(key, headerValue);
+      }
+    });
+
+    if (!res.getHeader('Content-Type') && !res.headersSent) {
+      res.setHeader('Content-Type', 'application/json');
+    }
+
+    if (!res.headersSent) {
+      // Forward the raw bytes light-my-request kept alongside `.body` — the
+      // decoded-as-UTF-8-string form corrupts any non-UTF-8 response (a
+      // generated PDF, any binary payload) by replacing every invalid byte
+      // with U+FFFD before it reaches the wire (salessmyth/samhenry#199).
+      // `rawPayload` is byte-identical to what Fastify sent regardless of
+      // content type, so this also covers the JSON case unchanged.
+      res.send(response.rawPayload);
+      logger.info('[Vercel Handler] Response sent successfully');
+    }
+  } catch (error) {
+    clearTimeout(timeout);
+
+    logger.error({ err: error }, '[Vercel Handler] Error handling request');
+
+    if (!res.headersSent) {
+      res.status(500).json({
+        error: 'Internal Server Error',
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+}

package/templates/apps/api/tsconfig.json

@@ -18,17 +18,5 @@
     "**/__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/mcp/CLAUDE.md

@@ -20,23 +20,25 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
 
 <!-- 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)
+## The free anonymous 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`
+**Flow (2):** `get_flow`, `submit_flow_step`
+**Booking (3):** `list_availability`, `get_event_meta`, `create_booking`
 
-### Why the catalog reports 18 and the server registers 17
+### Why the catalog reports 23 and the server registers 22
 
-- **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`)
+- **23 in the catalog / parity test**: the `TOOLS` array in
+  `packages/metadata/src/mcp-tool-catalog.ts` defines 23 tools; the parity
+  test counts that full catalog.
+- **22 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
+  entry is `start_purchase` — so 22 tools are registered on the server.
+- **19 free anonymous tools**: of the 22 registered, three are Pro tools
   (`create_page`, `update_page`, `delete_page`) gated at call time by
-  `requirePaidTier()`, leaving the 14 free anonymous tools above.
+  `requirePaidTier()`, leaving the 19 free anonymous tools above.
   `index.ts` is the transport entry point and exports no tools — registration
   is entirely via `createMcpServer`.
 
@@ -52,6 +54,10 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
   server entirely. Re-enable criteria live at
   `docs/internal/roadmaps/phase-3-readiness.md`.
 
+**Re-derive these counts rather than trusting them here** — the catalog in
+`packages/metadata/src/mcp-tool-catalog.ts` is the source; free anonymous =
+catalog − `OSS_DISABLED_TOOLS` − `tier: "pro"`.
+
 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.
 
@@ -82,3 +88,7 @@ Example (lead routing):
 - 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).
+
+Last updated: 2026-08-26 — doc-sync: tool-count explanation "18 catalog → 17 registered → 14 free anonymous" → "22 catalog → 21 registered → 18 free anonymous" (derived from `packages/metadata/src/mcp-tool-catalog.ts`: `get_flow`/`submit_flow_step` landed via PR #3973, `list_availability`/`create_booking` landed via PR #4421). Added the Booking category to the free-tool enumeration above. `CLAUDE.md` and `docs/ARCHITECTURE.md` re-verified as non-drift (already correct); `packages/create-ailk/templates/apps/mcp/CLAUDE.md` no longer exists in the scaffolder template tree (structure changed since the count was scoped there).
+
+Last updated: 2026-08-31 — doc-sync: tool counts 22/21/18 → 23/22/19 and Booking (2) → Booking (3): `get_event_meta` added (#4633), the meta-only scheduling read twinning `GET /v1/schedule/event-meta` — derived from `packages/metadata/src/mcp-tool-catalog.ts`.