create-ailk 0.1.0

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

@@ -0,0 +1,129 @@
+/**
+ * Unit tests for the require-paid-tier Fastify preHandler.
+ *
+ * Mocks @working-theory/license `checkLicense` and asserts:
+ *   - free tier → reply.status(402).send(payment_required canonical body)
+ *   - pro tier  → preHandler returns void (handler proceeds)
+ *   - checkLicense throws → safe-by-default 402 (no false-positive proceed)
+ */
+
+const mockCheckLicense = jest.fn();
+
+jest.mock("@working-theory/license", () => ({
+  checkLicense: (...args: unknown[]) => mockCheckLicense(...args),
+}));
+
+import type { FastifyReply, FastifyRequest } from "fastify";
+
+import { requirePaidTier } from "../require-paid-tier.js";
+
+// ── Typed reply builder ───────────────────────────────────────────────────────
+//
+// A minimal Fastify reply stub that satisfies the FastifyReply interface surface
+// used by requirePaidTier (status + send chain). Using a properly typed factory
+// avoids the `as unknown as FastifyReply` double assertion pattern.
+
+interface StubReply {
+  statusCalled: number | null;
+  sendCalled: unknown;
+  status: jest.MockedFunction<(code: number) => StubReply>;
+  send: jest.MockedFunction<(body: unknown) => StubReply>;
+}
+
+function makeReply(): StubReply {
+  const reply: StubReply = {
+    statusCalled: null,
+    sendCalled: undefined,
+    status: jest.fn(),
+    send: jest.fn(),
+  };
+  reply.status.mockImplementation((code: number) => {
+    reply.statusCalled = code;
+    return reply;
+  });
+  reply.send.mockImplementation((body: unknown) => {
+    reply.sendCalled = body;
+    return reply;
+  });
+  return reply;
+}
+
+// Cast the stub to FastifyReply once, at a typed boundary, so all call-sites
+// use the actual StubReply type rather than repeating the double assertion.
+function asReply(stub: StubReply): FastifyReply {
+  // @ts-expect-error: StubReply satisfies the status+send surface used by requirePaidTier;
+  // a full Fastify reply cannot be constructed without a live server instance in unit tests.
+  return stub;
+}
+
+const fakeRequest = {} as FastifyRequest;
+
+describe("requirePaidTier", () => {
+  beforeEach(() => {
+    mockCheckLicense.mockReset();
+  });
+
+  it("free tier — replies 402 with canonical payment_required body", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "free",
+      plan: null,
+      features: [],
+      expiresAt: null,
+      revoked: false,
+    });
+    const reply = makeReply();
+
+    await requirePaidTier(fakeRequest, asReply(reply));
+
+    expect(reply.statusCalled).toBe(402);
+    expect(reply.sendCalled).toEqual({
+      error: "payment_required",
+      message: expect.stringContaining("paid license"),
+    });
+  });
+
+  it("pro tier — proceeds without calling reply.status/send", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "pro",
+      plan: "pro",
+      features: [],
+      expiresAt: null,
+      revoked: false,
+    });
+    const reply = makeReply();
+
+    await requirePaidTier(fakeRequest, asReply(reply));
+
+    expect(reply.status).not.toHaveBeenCalled();
+    expect(reply.send).not.toHaveBeenCalled();
+  });
+
+  it("checkLicense throws — degrades to 402 (safe default)", async () => {
+    mockCheckLicense.mockRejectedValue(new Error("boom"));
+    const reply = makeReply();
+
+    await requirePaidTier(fakeRequest, asReply(reply));
+
+    expect(reply.statusCalled).toBe(402);
+    expect(reply.sendCalled).toMatchObject({ error: "payment_required" });
+  });
+
+  it("revoked paid license — replies 402 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 reply = makeReply();
+
+    await requirePaidTier(fakeRequest, asReply(reply));
+
+    expect(reply.statusCalled).toBe(402);
+    expect(reply.sendCalled).toMatchObject({ error: "payment_required" });
+  });
+});

package/templates/apps/api/src/lib/__tests__/stripe.test.ts

@@ -0,0 +1,74 @@
+/**
+ * apps/api stripe shim — surface-drift smoke tests.
+ *
+ * Ensures apps/api/src/lib/stripe.ts re-exports exactly what
+ * @working-theory/stripe-client exports, with no surface drift.
+ */
+
+jest.mock("@working-theory/stripe-client", () => ({
+  getStripeClient: jest.fn(),
+  assertSandboxKey: jest.fn(),
+  verifyWebhookSignature: jest.fn(),
+  createCheckoutSession: jest.fn(),
+  STRIPE_API_VERSION: "2023-10-16",
+  WEBHOOK_TOLERANCE_SECONDS: 300,
+  StripeConfigError: class StripeConfigError extends Error {},
+  StripeWebhookSignatureError: class StripeWebhookSignatureError extends Error {},
+  UnknownProductCodeError: class UnknownProductCodeError extends Error {},
+}));
+
+// Import the shim (not the wrapper directly)
+import * as stripeShim from "../stripe.js";
+import * as stripeClient from "@working-theory/stripe-client";
+
+describe("apps/api/src/lib/stripe — surface re-exports", () => {
+  it("exports getStripeClient as a function", () => {
+    expect(typeof stripeShim.getStripeClient).toBe("function");
+  });
+
+  it("exports assertSandboxKey as a function", () => {
+    expect(typeof stripeShim.assertSandboxKey).toBe("function");
+  });
+
+  it("exports verifyWebhookSignature as a function", () => {
+    expect(typeof stripeShim.verifyWebhookSignature).toBe("function");
+  });
+
+  it("exports createCheckoutSession as a function", () => {
+    expect(typeof stripeShim.createCheckoutSession).toBe("function");
+  });
+
+  it("exports STRIPE_API_VERSION", () => {
+    expect(stripeShim.STRIPE_API_VERSION).toBe("2023-10-16");
+  });
+
+  it("exports WEBHOOK_TOLERANCE_SECONDS", () => {
+    expect(stripeShim.WEBHOOK_TOLERANCE_SECONDS).toBe(300);
+  });
+
+  it("exports StripeConfigError as a constructor producing Error instances", () => {
+    expect(typeof stripeShim.StripeConfigError).toBe("function");
+    expect(new stripeShim.StripeConfigError()).toBeInstanceOf(Error);
+  });
+
+  it("exports StripeWebhookSignatureError as a constructor producing Error instances", () => {
+    expect(typeof stripeShim.StripeWebhookSignatureError).toBe("function");
+    expect(new stripeShim.StripeWebhookSignatureError()).toBeInstanceOf(Error);
+  });
+
+  it("exports UnknownProductCodeError as a constructor producing Error instances", () => {
+    expect(typeof stripeShim.UnknownProductCodeError).toBe("function");
+    expect(new stripeShim.UnknownProductCodeError()).toBeInstanceOf(Error);
+  });
+
+  it("shim functions are the same references as @working-theory/stripe-client exports", () => {
+    expect(stripeShim.getStripeClient).toBe(stripeClient.getStripeClient);
+    expect(stripeShim.assertSandboxKey).toBe(stripeClient.assertSandboxKey);
+    expect(stripeShim.verifyWebhookSignature).toBe(
+      stripeClient.verifyWebhookSignature,
+    );
+    expect(stripeShim.createCheckoutSession).toBe(
+      stripeClient.createCheckoutSession,
+    );
+  });
+});

package/templates/apps/api/src/lib/content-adapter.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared content adapter singleton for apps/api.
+ *
+ * The MDX adapter is the v1 default. Set `CONTENT_ADAPTER=projection` to opt
+ * into the build-time projection adapter backed by a compiled manifest.
+ *
+ * Adapter selection:
+ *   - (unset or any value other than "projection") → MDX adapter
+ *   - "projection" → projection adapter (requires compiled manifest)
+ *
+ * Content-root resolution order:
+ *   1. `CONTENT_ROOT` env var (explicit override — recommended for production)
+ *   2. `<cwd>/content` (works when the server is started from the repo root)
+ *   3. `<cwd>/../../content` (works when started from `apps/api/` via pnpm)
+ *
+ * Manifest-path resolution (projection only):
+ *   1. `MANIFEST_PATH` env var (explicit override)
+ *   2. `<content-root>/.compiled/manifest.json` (default)
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+import {
+  createMdxAdapter,
+  type ContentAdapter,
+  type MdxContentAdapter,
+} from "@working-theory/content-adapters";
+import { createProjectionAdapter } from "@working-theory/content-projection";
+import { loadManifestFromDisk } from "@working-theory/content-projection/node";
+
+import { readDefaultLocale } from "./locales.js";
+
+let cachedAdapter: ContentAdapter | undefined;
+
+/**
+ * Resolve the content root. Honours `CONTENT_ROOT` env first, then probes the
+ * cwd-relative candidates above.
+ */
+export function getContentRoot(): string {
+  if (process.env.CONTENT_ROOT) return process.env.CONTENT_ROOT;
+
+  const cwd = process.cwd();
+  const cwdContent = resolve(cwd, "content");
+  const repoContent = resolve(cwd, "../../content");
+  if (existsSync(cwdContent)) return cwdContent;
+  if (existsSync(repoContent)) return repoContent;
+  // Last resort — cwd-relative, even if missing. The adapter will return
+  // null/empty for missing pages; routes will surface 404s.
+  return cwdContent;
+}
+
+/**
+ * Returns the process-wide content adapter, lazily constructed on first use.
+ * Safe to call repeatedly. Adapter type is determined by `CONTENT_ADAPTER` env.
+ */
+export function getContentAdapter(): ContentAdapter {
+  if (!cachedAdapter) {
+    cachedAdapter = buildAdapter();
+  }
+  return cachedAdapter;
+}
+
+function buildAdapter(): ContentAdapter {
+  const contentRoot = getContentRoot();
+
+  if (process.env.CONTENT_ADAPTER === "projection") {
+    const manifestPath =
+      process.env.MANIFEST_PATH ??
+      resolve(contentRoot, ".compiled", "manifest.json");
+
+    const manifest = loadManifestFromDisk(manifestPath);
+    return createProjectionAdapter({ manifest });
+  }
+
+  return createMdxAdapter({ contentRoot, defaultLocale: readDefaultLocale() });
+}
+
+/**
+ * Test/utility helper — drop the cached adapter so the next call rebuilds
+ * with current env. Not used in production.
+ */
+export function resetContentAdapter(): void {
+  cachedAdapter = undefined;
+}
+
+export type { MdxContentAdapter };

package/templates/apps/api/src/lib/error-serializer.ts

@@ -0,0 +1,77 @@
+/**
+ * Fastify error-serializer — prevents internal error detail from leaking to clients.
+ *
+ * Fastify's default error handler echoes `err.message` (and in dev,
+ * `err.stack`) in the response body. For internal errors (DB failures, SDK
+ * exceptions, unhandled throws) that's sensitive: connection strings, host
+ * names, schema hints, internal paths. This handler:
+ *
+ *   - Maps any 5xx-class internal Error to `{ error: "internal_error" }`
+ *     with no detail
+ *   - Logs the full Error (message, stack, request context) to pino at
+ *     error level
+ *   - Lets Fastify's built-in 4xx validation errors flow through
+ *     (their `validation` payload is safe to surface — it describes the
+ *     client's input, not server internals)
+ *   - Leaves replies that handlers already committed (explicit status + body)
+ *     untouched
+ */
+import type { FastifyError, FastifyInstance } from "fastify";
+
+const GENERIC_INTERNAL_BODY = { error: "internal_error" } as const;
+
+export function registerErrorSerializer(server: FastifyInstance): void {
+  server.setErrorHandler(async (err: FastifyError, request, reply) => {
+    // Validation errors (Fastify's schema validator) — keep structured detail.
+    // These describe the client request, not server internals.
+    if (err.validation) {
+      const status = err.statusCode ?? 400;
+      request.log.warn(
+        {
+          method: request.method,
+          path: request.url,
+          validation: err.validation,
+        },
+        "request validation failed",
+      );
+      return reply.code(status).send({
+        error: "validation-error",
+        details: err.validation,
+      });
+    }
+
+    // Explicit 4xx errors thrown by handlers (e.g. fastify.httpErrors.notFound)
+    // also flow through — they're a deliberate boundary signal, not an
+    // internal leak.
+    const status = err.statusCode ?? 500;
+    if (status >= 400 && status < 500) {
+      request.log.info(
+        {
+          method: request.method,
+          path: request.url,
+          statusCode: status,
+          errName: err.name,
+        },
+        "request returned 4xx",
+      );
+      // Don't echo err.message — handlers that want a structured body should
+      // call reply.code().send() directly. This branch is the safe fallback.
+      return reply.code(status).send({ error: err.code ?? "client_error" });
+    }
+
+    // 5xx — log everything, return nothing identifying.
+    request.log.error(
+      {
+        method: request.method,
+        path: request.url,
+        errName: err.name,
+        errMessage: err.message,
+        errStack: err.stack,
+        errCode: err.code,
+      },
+      "internal server error",
+    );
+
+    return reply.code(500).send(GENERIC_INTERNAL_BODY);
+  });
+}

package/templates/apps/api/src/lib/errors.ts

@@ -0,0 +1,95 @@
+/**
+ * Canonical error shape for apps/api content-write routes (D14a Stage 0).
+ *
+ * Every error response from create/update/delete content routes returns this
+ * shape as the JSON body, paired with the appropriate HTTP status. The MCP
+ * twin (`apps/mcp/src/lib/errors.ts`) returns the same shape sans `status` —
+ * MCP carries the error in the tool result body itself.
+ *
+ * Codes are a closed set; consumers can switch on them to drive UI / retry
+ * logic without parsing free-form `message` text. New codes get added here
+ * before any route uses them.
+ *
+ * Usage:
+ *   const err = validationError("Invalid type or slug", { field: "type" });
+ *   return reply.status(err.status).send(err.body);
+ */
+import { mapAdapterError } from "@working-theory/content-adapters";
+
+export type ErrorCode =
+  | "validation_failed"
+  | "not_found"
+  | "conflict"
+  | "payment_required"
+  | "unauthorized";
+
+export interface ErrorBody {
+  error: ErrorCode;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export interface ErrorResponse {
+  status: number;
+  body: ErrorBody;
+}
+
+function makeBody(
+  code: ErrorCode,
+  message: string,
+  details?: Record<string, unknown>,
+): ErrorBody {
+  if (details === undefined) {
+    return { error: code, message };
+  }
+  return { error: code, message, details };
+}
+
+export function validationError(
+  message: string,
+  details?: Record<string, unknown>,
+): ErrorResponse {
+  return { status: 400, body: makeBody("validation_failed", message, details) };
+}
+
+export function unauthorizedError(message: string): ErrorResponse {
+  return { status: 401, body: makeBody("unauthorized", message) };
+}
+
+export function paymentRequiredError(message: string): ErrorResponse {
+  return { status: 402, body: makeBody("payment_required", message) };
+}
+
+export function notFoundError(message: string): ErrorResponse {
+  return { status: 404, body: makeBody("not_found", message) };
+}
+
+export function conflictError(
+  message: string,
+  details?: Record<string, unknown>,
+): ErrorResponse {
+  return { status: 409, body: makeBody("conflict", message, details) };
+}
+
+/**
+ * Route-layer adapter for `mapAdapterError` from `@working-theory/content-adapters`.
+ * The package emits a canonical `{error, message, details?}` body but
+ * cannot know the HTTP status (it has no app dependency). This helper
+ * pairs the body with the right status. Returns `null` if the error
+ * wasn't an `AdapterWriteError` (caller should treat as 500).
+ */
+export function adapterErrorResponse(
+  err: unknown,
+  ctx: { type: string; slug: string },
+): ErrorResponse | null {
+  const body = mapAdapterError(err, ctx);
+  if (body === null) return null;
+  switch (body.error) {
+    case "conflict":
+      return { status: 409, body };
+    case "not_found":
+      return { status: 404, body };
+    case "validation_failed":
+      return { status: 400, body };
+  }
+}

package/templates/apps/api/src/lib/file-fallback.ts

@@ -0,0 +1,87 @@
+/**
+ * File-fallback writer for the AILK inbox.
+ *
+ * Writes a Lead to ${AILK_INBOX_FALLBACK_DIR ?? '.ailk/inbox'}/<ISO-ts>-<lead.id>.json
+ * when the database is unavailable. Engaged by B6's lead-routing service on DB failure.
+ *
+ * Path-traversal-safe by construction:
+ *  1. lead.id is validated against /^[a-z0-9_-]{8,64}$/i before any fs operation.
+ *  2. The resolved write path is checked to be strictly inside targetDir.
+ *
+ * No quota / count cap. Operators running with this fallback engaged for extended periods
+ * should monitor disk usage and replay leads back to DB once it returns.
+ *
+ * Module is import-side-effect-free. No env reads at module-load time.
+ */
+
+import * as fs from "fs/promises";
+import * as path from "path";
+
+import type { Lead } from "@working-theory/validation";
+
+export type FallbackLead = Lead;
+
+export type FallbackResult =
+  | { ok: true; path: string }
+  | {
+      ok: false;
+      error: {
+        kind: "invalid_id" | "path_escape" | "fs_error";
+        message: string;
+      };
+    };
+
+const LEAD_ID_RE = /^[a-z0-9_-]{8,64}$/i;
+
+export async function writeLeadFallback(
+  lead: FallbackLead,
+): Promise<FallbackResult> {
+  if (!LEAD_ID_RE.test(lead.id)) {
+    return {
+      ok: false,
+      error: { kind: "invalid_id", message: `Invalid lead id: ${lead.id}` },
+    };
+  }
+
+  // Resolve target directory — read env inside the function (no module-level side effects)
+  const envDir = process.env.AILK_INBOX_FALLBACK_DIR ?? ".ailk/inbox";
+  const targetDir = path.resolve(process.cwd(), envDir);
+
+  const rawTs = isValidIso(lead.createdAt)
+    ? lead.createdAt
+    : new Date().toISOString();
+  // Replace colons with hyphens for Windows filesystem compatibility
+  const ts = rawTs.replace(/:/g, "-");
+
+  const filename = `${ts}-${lead.id}.json`;
+  const resolved = path.resolve(targetDir, filename);
+
+  // Path-escape check: relative path must not start with '..' or be absolute
+  const rel = path.relative(targetDir, resolved);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    return {
+      ok: false,
+      error: {
+        kind: "path_escape",
+        message: `Path escape detected: ${resolved}`,
+      },
+    };
+  }
+
+  try {
+    await fs.mkdir(targetDir, { recursive: true });
+    await fs.writeFile(resolved, JSON.stringify(lead, null, 2));
+    return { ok: true, path: resolved };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: { kind: "fs_error", message } };
+  }
+}
+
+// Require YYYY-MM-DD prefix before accepting as ISO — rejects slash-dates, traversal strings, etc.
+const ISO_RE = /^\d{4}-\d{2}-\d{2}(T[\d:.Z+-]*)?$/;
+
+function isValidIso(value: string): boolean {
+  if (!value || !ISO_RE.test(value)) return false;
+  return !isNaN(new Date(value).getTime());
+}

package/templates/apps/api/src/lib/lead-capture-store.ts

@@ -0,0 +1,110 @@
+/**
+ * Lead capture store — always-on JSONL writer (Issue #27 Unit 1).
+ *
+ * Appends one JSON line per successful lead submission to apps/api/leads.jsonl
+ * (or LEAD_CAPTURE_FILE if set). Uses fs.appendFile with flag:'a' which maps to
+ * POSIX O_APPEND — the kernel guarantees atomicity for writes ≤ PIPE_BUF on
+ * local filesystems, making this safe for concurrent processes/requests.
+ *
+ * Semantic difference from B6 file-fallback:
+ *   B6 file-fallback (.ailk/inbox/) — engaged only when the DB throws (salvage path)
+ *   This module — always-on canonical AX surface; disabled explicitly via env, not by DB presence
+ *
+ * Env vars (all read inside function bodies — module is import-side-effect-free):
+ *   LEAD_CAPTURE_FILE            — output path (default: apps/api/leads.jsonl relative to cwd)
+ *   LEAD_CAPTURE_FILE_DISABLED   — set to "true" to skip writes (opt-out)
+ *   LEAD_CAPTURE_INCLUDE_IP      — set to "true" to include metadata.ip in the record
+ *
+ * PII discipline:
+ *   IP is excluded from the written record by default.
+ *   No other PII is filtered — `data` carries whatever the route gave us.
+ *   Callers are responsible for what they put in `data`.
+ */
+
+import * as fs from "fs/promises";
+import * as path from "path";
+
+import type { LeadCaptureRecord } from "@working-theory/validation";
+
+// Re-export so consumers can import from one place.
+export type { LeadCaptureRecord };
+
+export type AppendResult =
+  | { ok: true; skipped?: true }
+  | { ok: false; error: string };
+
+/**
+ * Append one lead record as a JSONL line.
+ *
+ * Always resolves — never throws. Returns ok:false on fs errors so the caller
+ * can log and continue without crashing the request.
+ */
+export async function appendLeadRecord(
+  record: LeadCaptureRecord,
+): Promise<AppendResult> {
+  // Read env inside the function — no module-level side effects.
+  const disabled = process.env.LEAD_CAPTURE_FILE_DISABLED === "true";
+  if (disabled) {
+    return { ok: true, skipped: true };
+  }
+
+  const includeIp = process.env.LEAD_CAPTURE_INCLUDE_IP === "true";
+  const outputPath = resolveOutputPath();
+
+  // Strip IP from metadata unless explicitly opted in.
+  const cleanMeta = includeIp
+    ? record.metadata
+    : Object.fromEntries(
+        Object.entries(record.metadata).filter(([k]) => k !== "ip"),
+      );
+
+  const line = JSON.stringify({ ...record, metadata: cleanMeta }) + "\n";
+
+  try {
+    await fs.appendFile(outputPath, line, { flag: "a", encoding: "utf8" });
+    return { ok: true };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: message };
+  }
+}
+
+/**
+ * Startup-time validation: if LEAD_CAPTURE_FILE points at a path whose parent
+ * directory does not exist, throw immediately so the server fails fast rather
+ * than erroring on first write.
+ *
+ * Call from server.ts build() before registering routes.
+ * No-op when LEAD_CAPTURE_FILE is unset or LEAD_CAPTURE_FILE_DISABLED=true.
+ */
+export async function validateLeadCaptureDir(): Promise<void> {
+  const disabled = process.env.LEAD_CAPTURE_FILE_DISABLED === "true";
+  const filePath = process.env.LEAD_CAPTURE_FILE;
+
+  if (!filePath || disabled) {
+    return;
+  }
+
+  const dir = path.dirname(path.resolve(filePath));
+
+  try {
+    await fs.access(dir);
+  } catch {
+    throw new Error(
+      `LEAD_CAPTURE_FILE directory does not exist: "${dir}". ` +
+        `Create the directory or unset LEAD_CAPTURE_FILE.`,
+    );
+  }
+}
+
+// ─── Internal ─────────────────────────────────────────────────────────────────
+
+function resolveOutputPath(): string {
+  const envPath = process.env.LEAD_CAPTURE_FILE;
+  if (envPath) {
+    return path.resolve(envPath);
+  }
+  // Default: apps/api/leads.jsonl relative to the process cwd.
+  // In production (Vercel function or Node standalone), cwd is the project root.
+  return path.resolve(process.cwd(), "apps/api/leads.jsonl");
+}