create-ailk 0.1.0

package/templates/apps/api/src/__tests__/factories/index.ts

@@ -0,0 +1,70 @@
+/**
+ * @file factories/index.ts
+ * Typed test data factories for apps/api route tests.
+ *
+ * Each factory returns a fully-typed object with all required fields populated.
+ * Pass overrides to vary only the fields relevant to the test case.
+ *
+ * Used by: content, leads, checkout route tests (Issue #507 real-dependency refactor).
+ */
+
+import type { ContentPage } from "@working-theory/content-adapters";
+import type { Lead, LeadCaptureRecord } from "@working-theory/validation";
+
+// ─── Content factories ────────────────────────────────────────────────────────
+
+export type ContentPageOverrides = Partial<ContentPage>;
+
+/**
+ * Build a fully-typed ContentPage. Defaults to a HomePage with deterministic values.
+ */
+export function buildContent(
+  overrides: ContentPageOverrides = {},
+): ContentPage {
+  return {
+    type: "HomePage",
+    slug: "test-page",
+    title: "Test Page Title",
+    description: "A test page description for automated tests.",
+    ...overrides,
+  };
+}
+
+// ─── Lead factories ───────────────────────────────────────────────────────────
+
+export type LeadOverrides = Partial<Lead>;
+
+/**
+ * Build a fully-typed Lead record (as returned by the DB / written to file).
+ */
+export function buildLead(overrides: LeadOverrides = {}): Lead {
+  return {
+    id: "test-lead-id-00000001",
+    siteId: "test-site-abc",
+    source: "contact",
+    email: "test@example.com",
+    payload: { message: "Hello from factory" },
+    createdAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+// ─── LeadCaptureRecord factories ──────────────────────────────────────────────
+
+export type LeadCaptureRecordOverrides = Partial<LeadCaptureRecord>;
+
+/**
+ * Build a fully-typed LeadCaptureRecord (as written to the JSONL capture file).
+ */
+export function buildLeadCaptureRecord(
+  overrides: LeadCaptureRecordOverrides = {},
+): LeadCaptureRecord {
+  return {
+    id: "test-capture-id-00000001",
+    createdAt: new Date().toISOString(),
+    source: "contact",
+    data: { email: "test@example.com" },
+    metadata: {},
+    ...overrides,
+  };
+}

package/templates/apps/api/src/__tests__/factories/lead-fixture.ts

@@ -0,0 +1,82 @@
+/**
+ * @file lead-fixture.ts
+ * Filesystem fixture helpers for leads route tests.
+ *
+ * Sets up per-test temp paths for the real lead-capture-store and
+ * file-fallback modules, so tests can assert on actual file writes
+ * without mocking those internal modules.
+ *
+ * Issue #507: replaces jest.mock("../../../lib/lead-capture-store.js") and
+ * jest.mock("../../../lib/file-fallback.js") in leads route tests.
+ */
+
+import * as fs from "fs/promises";
+import * as os from "os";
+import * as path from "path";
+
+export interface LeadFileFixture {
+  /** Path to the per-test JSONL capture file (LEAD_CAPTURE_FILE). */
+  getCaptureFilePath: () => string;
+  /** Path to the per-test fallback dir (AILK_INBOX_FALLBACK_DIR). */
+  getFallbackDir: () => string;
+  /**
+   * Read and parse the last line written to the capture file.
+   * Throws if the file does not exist or is empty.
+   */
+  readLastCaptureRecord: () => Promise<Record<string, unknown>>;
+}
+
+/**
+ * Register beforeEach/afterEach hooks that create a fresh LEAD_CAPTURE_FILE
+ * path and AILK_INBOX_FALLBACK_DIR per test, then clean up afterward.
+ *
+ * Call at describe-scope. Returns a handle for asserting on file contents.
+ */
+export function setupLeadFileEnv(label = "leads"): LeadFileFixture {
+  let captureFilePath = "";
+  let fallbackDir = "";
+
+  beforeEach(async () => {
+    captureFilePath = path.join(
+      os.tmpdir(),
+      `ailk-test-${label}-${Date.now()}.jsonl`,
+    );
+    process.env.LEAD_CAPTURE_FILE = captureFilePath;
+
+    fallbackDir = await fs.mkdtemp(
+      path.join(os.tmpdir(), `ailk-test-fallback-${label}-`),
+    );
+    process.env.AILK_INBOX_FALLBACK_DIR = fallbackDir;
+  });
+
+  afterEach(async () => {
+    delete process.env.LEAD_CAPTURE_FILE;
+    delete process.env.AILK_INBOX_FALLBACK_DIR;
+
+    // Best-effort cleanup — never fail the test on cleanup errors.
+    try {
+      await fs.unlink(captureFilePath);
+    } catch {
+      // file may not exist if appendLeadRecord was skipped
+    }
+    try {
+      await fs.rm(fallbackDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+
+    captureFilePath = "";
+    fallbackDir = "";
+  });
+
+  return {
+    getCaptureFilePath: () => captureFilePath,
+    getFallbackDir: () => fallbackDir,
+    readLastCaptureRecord: async () => {
+      const content = await fs.readFile(captureFilePath, "utf8");
+      const lines = content.trim().split("\n").filter(Boolean);
+      if (lines.length === 0) throw new Error("Capture file is empty");
+      return JSON.parse(lines[lines.length - 1]) as Record<string, unknown>;
+    },
+  };
+}

package/templates/apps/api/src/__tests__/index.test.ts

@@ -0,0 +1,118 @@
+/**
+ * @file index.test.ts
+ * @description Unit tests for index.ts - Entry point
+ *
+ * Uses jest.spyOn on the real build() function (from ../server) to stub the
+ * server object returned, rather than mocking the server module wholesale.
+ * The real config module is imported directly — PORT and NODE_ENV come from
+ * the test setup env vars.
+ */
+
+import { start } from '../index';
+import * as serverModule from '../server';
+
+// Mock @working-theory/observability so assertions check structured logger calls
+// rather than depending on pino's stdout serialization.
+const mockLoggerInfo = jest.fn();
+const mockLoggerError = jest.fn();
+jest.mock('@working-theory/observability', () => ({
+  logger: {
+    info: (...args: unknown[]) => mockLoggerInfo(...args),
+    error: (...args: unknown[]) => mockLoggerError(...args),
+    warn: jest.fn(),
+    debug: jest.fn(),
+  },
+}));
+
+// @working-theory/email — ESM-only transitive dep (@react-email/components) cannot be
+// resolved by jest-resolve in CommonJS mode. Mock at the package boundary.
+jest.mock('@working-theory/email', () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true }),
+}));
+
+// External Fastify plugins — mocked because they require live infrastructure.
+jest.mock('@fastify/cors', () => jest.fn().mockResolvedValue(undefined));
+jest.mock('@fastify/rate-limit', () => jest.fn().mockResolvedValue(undefined));
+
+describe('Index Entry Point', () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- mockServer holds the Jest-stubbed Fastify instance; typed loosely to avoid importing full FastifyInstance here
+  let mockServer: any;
+  let buildSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockLoggerInfo.mockClear();
+    mockLoggerError.mockClear();
+
+    // Re-establish spies each test so afterEach's restoreAllMocks doesn't leave
+    // process.exit unmocked across tests — the real exit would kill the worker.
+    jest.spyOn(process, 'exit').mockImplementation((() => {
+      throw new Error('Process exit called');
+    }) as never);
+
+    mockServer = {
+      listen: jest.fn().mockResolvedValue(undefined),
+    };
+
+    // Spy on build() from the real server module instead of mocking the module.
+    // This keeps the module graph intact while controlling the returned instance.
+    buildSpy = jest.spyOn(serverModule, 'build').mockResolvedValue(mockServer);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  describe('start function', () => {
+    it('should build server and start listening on configured port', async () => {
+      // ACT
+      await start();
+
+      // ASSERT
+      expect(buildSpy).toHaveBeenCalled();
+      expect(mockServer.listen).toHaveBeenCalledWith({
+        port: 3002,
+        host: '0.0.0.0',
+      });
+    });
+
+    it('should log server startup information', async () => {
+      // ACT
+      await start();
+
+      // ASSERT — single structured info call covers port + env + endpoints.
+      expect(mockLoggerInfo).toHaveBeenCalledTimes(1);
+      const [payload, msg] = mockLoggerInfo.mock.calls[0];
+      expect(msg).toContain('AI Launch Kit API');
+      expect(payload).toMatchObject({
+        port: 3002,
+        env: 'test',
+        endpoints: expect.objectContaining({ auth: expect.stringContaining('/v1/auth/tokens') }),
+      });
+    });
+
+    it('should handle server build failure', async () => {
+      // ARRANGE
+      const buildError = new Error('Build failed');
+      buildSpy.mockRejectedValue(buildError);
+
+      // ACT & ASSERT - process.exit throws due to mock
+      await expect(start()).rejects.toThrow('Process exit called');
+      const [payload, msg] = mockLoggerError.mock.calls[0];
+      expect(msg).toBe('Failed to start server');
+      expect(payload).toMatchObject({ err: expect.any(Error) });
+    });
+
+    it('should handle server listen failure', async () => {
+      // ARRANGE
+      const listenError = new Error('Port already in use');
+      mockServer.listen.mockRejectedValue(listenError);
+
+      // ACT & ASSERT - process.exit throws due to mock
+      await expect(start()).rejects.toThrow('Process exit called');
+      const [payload, msg] = mockLoggerError.mock.calls[0];
+      expect(msg).toBe('Failed to start server');
+      expect(payload).toMatchObject({ err: expect.any(Error) });
+    });
+  });
+});

package/templates/apps/api/src/__tests__/server.test.ts

@@ -0,0 +1,207 @@
+/**
+ * @file server.test.ts
+ * @description Unit tests for server.ts - Server setup
+ *
+ * Uses the real build() function with real route plugins. All internal modules
+ * run real; external boundaries (CORS, rate-limit) are mocked at the plugin
+ * boundary since they would require live network/Redis in production.
+ */
+
+import { build } from '../server';
+
+// External service boundaries — mocked because they require live infrastructure
+// or have ESM-only transitive deps that Jest's CJS preset cannot resolve:
+//   @fastify/cors, @fastify/rate-limit — Fastify plugins that would require
+//     live network infrastructure (CORS policy sync, Redis store) in unit tests.
+//   @working-theory/email — transitive dep on @react-email/components which is ESM-only
+//     and cannot be resolved by jest-resolve in CommonJS mode.
+jest.mock('@fastify/cors', () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock('@fastify/rate-limit', () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock('@working-theory/email', () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true }),
+}));
+
+describe('Server', () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- server is typed via Fastify generics; explicit any avoids pulling in the full FastifyInstance type here
+  let app: any;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+  });
+
+  afterEach(async () => {
+    if (app) {
+      await app.close();
+    }
+  });
+
+  describe('build function', () => {
+    it('should build Fastify server instance', async () => {
+      // ACT
+      app = await build();
+
+      // ASSERT
+      expect(app).toBeDefined();
+      expect(typeof app.inject).toBe('function');
+    });
+
+    it('should register health check route returning static OK without external calls', async () => {
+      // ARRANGE
+      app = await build();
+
+      // ACT
+      const response = await app.inject({
+        method: 'GET',
+        url: '/health',
+      });
+
+      // ASSERT
+      expect(response.statusCode).toBe(200);
+      const body = JSON.parse(response.body);
+      expect(body.status).toBe('healthy');
+      expect(body.timestamp).toBeDefined();
+      // No external dependencies in the health check anymore
+      expect(body.platform).toBeUndefined();
+    });
+
+    it('should register root endpoint', async () => {
+      // ARRANGE
+      app = await build();
+
+      // ACT
+      const response = await app.inject({
+        method: 'GET',
+        url: '/',
+      });
+
+      // ASSERT
+      expect(response.statusCode).toBe(200);
+      const body = JSON.parse(response.body);
+      expect(body.name).toBe('AI Launch Kit API');
+      expect(body.endpoints).toBeDefined();
+    });
+
+    it('should register CORS', async () => {
+      // ACT
+      app = await build();
+
+      // ASSERT - CORS should be registered (no error thrown)
+      expect(app).toBeDefined();
+    });
+
+    it('should register all route plugins', async () => {
+      // ARRANGE
+      app = await build();
+
+      // ACT & ASSERT - Test that routes are registered by checking they don't 404
+      const healthResponse = await app.inject({
+        method: 'GET',
+        url: '/health',
+      });
+      expect(healthResponse.statusCode).toBe(200);
+
+      const rootResponse = await app.inject({
+        method: 'GET',
+        url: '/',
+      });
+      expect(rootResponse.statusCode).toBe(200);
+    });
+
+    it('should include all endpoints in root response', async () => {
+      // ARRANGE
+      app = await build();
+
+      // ACT
+      const response = await app.inject({
+        method: 'GET',
+        url: '/',
+      });
+
+      // ASSERT
+      const body = JSON.parse(response.body);
+      expect(body.endpoints).toHaveProperty('health');
+      expect(body.endpoints).toHaveProperty('tokens');
+      expect(body.endpoints).toHaveProperty('profile');
+    });
+
+    it('startup throws when LEAD_CAPTURE_FILE points at a missing directory', async () => {
+      // ARRANGE — set LEAD_CAPTURE_FILE to a path whose parent dir doesn't exist
+      // so the real validateLeadCaptureDir() throws (AC8). Restore after test.
+      const prior = process.env.LEAD_CAPTURE_FILE;
+      process.env.LEAD_CAPTURE_FILE = '/nonexistent-ailk-test-dir/leads.jsonl';
+
+      try {
+        // ACT & ASSERT
+        await expect(build()).rejects.toThrow(/LEAD_CAPTURE_FILE/);
+      } finally {
+        if (prior === undefined) {
+          delete process.env.LEAD_CAPTURE_FILE;
+        } else {
+          process.env.LEAD_CAPTURE_FILE = prior;
+        }
+      }
+    });
+  });
+});
+
+// ── Bootstrap test: raw-body parser scope encapsulation (AC 13) ──────────────
+//
+// Proves that registering the webhooks plugin (with its raw-body parser scoped
+// to application/json) does NOT leak that parser to other routes. The global
+// Fastify JSON parser must remain active for all non-webhook routes.
+
+import Fastify from 'fastify';
+import { webhooksRoutes } from '../routes/webhooks/index.js';
+
+describe('Parser scope — webhooks raw-body parser does not leak', () => {
+  it('other routes still receive parsed JSON objects after webhooks plugin registers', async () => {
+    // Build a minimal server that mirrors the encapsulation pattern in server.ts:
+    //   1. Register a JSON route that echoes the parsed body.
+    //   2. Register the webhooks plugin inside an encapsulated scope with a
+    //      raw-body (buffer) parser.
+    // If the raw-body parser leaks out of the webhooks scope, the echo route
+    // would receive a Buffer instead of a parsed object.
+
+    const server = Fastify({ logger: false });
+
+    // A simple JSON echo route — simulates any existing JSON-parsed route
+    server.post('/api/echo', async (req) => ({ received: req.body }));
+
+    // Mirror of server.ts registration pattern
+    await server.register(async (webhooksScope) => {
+      webhooksScope.addContentTypeParser(
+        'application/json',
+        { parseAs: 'buffer' },
+        (_req, body, done) => {
+          done(null, body);
+        },
+      );
+      await webhooksScope.register(webhooksRoutes);
+    });
+
+    await server.ready();
+
+    try {
+      const response = await server.inject({
+        method: 'POST',
+        url: '/api/echo',
+        payload: { hello: 'world' },
+        headers: { 'content-type': 'application/json' },
+      });
+
+      expect(response.statusCode).toBe(200);
+      const body = JSON.parse(response.body);
+      // Must be a plain object, not a stringified Buffer
+      expect(body.received).toEqual({ hello: 'world' });
+      expect(Buffer.isBuffer(body.received)).toBe(false);
+    } finally {
+      await server.close();
+    }
+  });
+});

package/templates/apps/api/src/__tests__/services/enrichment-shim.test.ts

@@ -0,0 +1,126 @@
+/**
+ * @file enrichment-shim.test.ts
+ * @description Unit tests for enrichment-shim — license-gated lead enrichment stub.
+ *
+ * Module-state hygiene: proSentinelLogged is module-scoped and persists across calls
+ * within the same module instance. Each test uses jest.isolateModules() to load a
+ * fresh copy of the shim (resetting proSentinelLogged) while keeping the jest.mock
+ * factory active so @working-theory/license is always intercepted.
+ */
+
+import { createHash } from "crypto";
+
+// Stable mock function reference — survives resetModules because it lives in this
+// module's scope, not in the module registry.
+const mockCheckLicense = jest.fn();
+const mockLoggerInfo = jest.fn();
+
+jest.mock("@working-theory/license", () => ({
+  checkLicense: (...args: unknown[]) => mockCheckLicense(...args),
+}));
+
+jest.mock("@working-theory/observability", () => ({
+  logger: {
+    info: (...args: unknown[]) => mockLoggerInfo(...args),
+    warn: jest.fn(),
+    error: jest.fn(),
+    debug: jest.fn(),
+  },
+}));
+
+describe("enrichLead", () => {
+  let enrichLead: (lead: unknown) => Promise<unknown>;
+  const consoleInfoSpy = mockLoggerInfo;
+
+  beforeEach(() => {
+    mockCheckLicense.mockReset();
+    mockLoggerInfo.mockClear();
+
+    // Load a fresh shim module instance per test to reset proSentinelLogged.
+    jest.isolateModules(() => {
+       
+      const shim = require("../../services/enrichment-shim.js") as {
+        enrichLead: (lead: unknown) => Promise<unknown>;
+      };
+      enrichLead = shim.enrichLead;
+    });
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    delete process.env["AILK_LICENSE_KEY"];
+  });
+
+  it("free tier — returns lead unchanged, no sentinel log", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "free",
+      plan: null,
+      features: [],
+      expiresAt: null,
+      revoked: false,
+    });
+    const lead = { email: "test@example.com", name: "Test User" };
+
+    const result = await enrichLead(lead);
+
+    expect(result).toBe(lead);
+    expect(consoleInfoSpy).not.toHaveBeenCalled();
+  });
+
+  it("pro tier (first call) — returns lead unchanged, sentinel logged once with key hash prefix", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "pro",
+      plan: "pro",
+      features: [],
+      expiresAt: null,
+      revoked: false,
+    });
+    process.env["AILK_LICENSE_KEY"] = "test-key-123";
+
+    const expectedPrefix = createHash("sha256")
+      .update("test-key-123")
+      .digest("hex")
+      .substring(0, 8);
+
+    const lead = { email: "test@example.com", name: "Test User" };
+
+    const result = await enrichLead(lead);
+
+    expect(result).toBe(lead);
+    expect(consoleInfoSpy).toHaveBeenCalledTimes(1);
+    // pino convention: logger.info(structuredPayload, message).
+    const [payload] = consoleInfoSpy.mock.calls[0];
+    expect(payload).toMatchObject({ licensePrefix: expectedPrefix });
+  });
+
+  it("pro tier (second call, same module) — sentinel logged only once total", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "pro",
+      plan: "pro",
+      features: [],
+      expiresAt: null,
+      revoked: false,
+    });
+    process.env["AILK_LICENSE_KEY"] = "test-key-123";
+
+    const lead1 = { email: "first@example.com", name: "First" };
+    const lead2 = { email: "second@example.com", name: "Second" };
+
+    const result1 = await enrichLead(lead1);
+    const result2 = await enrichLead(lead2);
+
+    expect(result1).toBe(lead1);
+    expect(result2).toBe(lead2);
+    expect(consoleInfoSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("checkLicense throws — returns lead unchanged, no sentinel, error not propagated", async () => {
+    mockCheckLicense.mockRejectedValue(new Error("network error"));
+    const lead = { email: "test@example.com", name: "Test User" };
+
+    const result = await enrichLead(lead);
+
+    expect(result).toBe(lead);
+    expect(consoleInfoSpy).not.toHaveBeenCalled();
+  });
+});

package/templates/apps/api/src/__tests__/setup.ts

@@ -0,0 +1,24 @@
+/**
+ * Jest Global Setup
+ * Sets required environment variables for all tests
+ */
+
+// Database
+process.env.DATABASE_URL = process.env.DATABASE_URL || 'postgresql://test:test@localhost:5432/test';
+process.env.DATABASE_URL_NON_POOLED = process.env.DATABASE_URL_NON_POOLED || process.env.DATABASE_URL;
+
+// Auth — Better Auth (post-#587). NEXTAUTH_* removed.
+process.env.BETTER_AUTH_SECRET = process.env.BETTER_AUTH_SECRET || 'test-secret-key';
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'test-jwt-secret-min-32-characters-required!!';
+process.env.GOOGLE_OAUTH_CLIENT_ID = process.env.GOOGLE_OAUTH_CLIENT_ID || 'test-google-client-id.apps.googleusercontent.com';
+
+// Stripe
+process.env.STRIPE_SECRET_KEY = process.env.STRIPE_SECRET_KEY || 'sk_test_mock_key';
+process.env.STRIPE_WEBHOOK_SECRET = process.env.STRIPE_WEBHOOK_SECRET || 'whsec_test_webhook_secret';
+process.env.STRIPE_API_VERSION = process.env.STRIPE_API_VERSION || '2023-10-16';
+
+// Frontend
+process.env.FRONTEND_URL = process.env.FRONTEND_URL || 'http://localhost:3001';
+
+// Node environment
+process.env.NODE_ENV = process.env.NODE_ENV || 'test';

package/templates/apps/api/src/cli.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/* istanbul ignore file -- Node CLI bootstrap; import.meta.url is unreachable from Jest CJS.
+   See the JSDoc below and docs at https://jestjs.io/docs/configuration#coverageprovider-string.
+   Real entry-point semantics are integration-tested by running the compiled dist directly. */
+/**
+ * CLI Entry Point
+ *
+ * This file is the actual entry point for running the server from CLI.
+ * Separated from index.ts to allow Jest testing without parsing import.meta.
+ */
+import { pathToFileURL } from 'url';
+
+import { start } from './index.js';
+
+// Only start if this is the main module
+// Check if executed file matches current file using import.meta.url
+if (process.argv[1]) {
+  const isEntryPoint = process.argv[1].endsWith('dist/cli.js') || 
+                       process.argv[1].endsWith('cli.js');
+  
+  if (isEntryPoint) {
+    // ESM-accurate verification using import.meta.url
+    const currentFileUrl = import.meta.url;
+    const executedFileUrl = pathToFileURL(process.argv[1]).href;
+    
+    if (currentFileUrl === executedFileUrl) {
+      void start();
+    }
+  }
+}