create-ailk 0.1.0

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

@@ -0,0 +1,97 @@
+// Mock dotenv
+jest.mock('dotenv', () => ({
+  config: jest.fn(),
+}));
+
+// Mock the observability logger so assertions don't depend on pino's stdout serialization.
+const mockLoggerError = jest.fn();
+jest.mock('@working-theory/observability', () => ({
+  logger: {
+    error: (...args: unknown[]) => mockLoggerError(...args),
+    warn: jest.fn(),
+    info: jest.fn(),
+    debug: jest.fn(),
+  },
+}));
+
+describe('Config', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    jest.resetModules();
+    process.env = { ...originalEnv };
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it('should load environment variables', () => {
+    // ARRANGE
+    process.env.DATABASE_URL = 'postgresql://test:test@localhost/test';
+
+    // ACT — require dotenv after resetModules so we observe the same mock
+    // instance the freshly-required config module will use.
+    const dotenv = require('dotenv');
+    const { config } = require('../index');
+
+    // ASSERT
+    expect(config.DATABASE_URL).toBe('postgresql://test:test@localhost/test');
+    expect(dotenv.config).toHaveBeenCalled();
+  });
+
+  it('should exit on missing DATABASE_URL', () => {
+    // ARRANGE
+    delete process.env.DATABASE_URL;
+
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit called');
+    });
+    mockLoggerError.mockClear();
+
+    // ACT & ASSERT
+    expect(() => {
+      require('../index');
+    }).toThrow('Process exit called');
+
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(mockLoggerError).toHaveBeenCalled();
+
+    exitSpy.mockRestore();
+  });
+
+  it('should not require any external-platform forwarding env vars', () => {
+    // ARRANGE — only DATABASE_URL set; legacy forwarding vars explicitly absent
+    process.env.DATABASE_URL = 'postgresql://test:test@localhost/test';
+    const legacyVars = ['THEORY' + '_API_URL', 'THEORY' + '_API_KEY'];
+    legacyVars.forEach((k) => {
+      delete process.env[k];
+    });
+
+    // ACT
+    const { config } = require('../index');
+
+    // ASSERT — config loads without error and exposes no legacy forwarding keys
+    expect(config.DATABASE_URL).toBe('postgresql://test:test@localhost/test');
+    legacyVars.forEach((k) => {
+      expect((config as Record<string, unknown>)[k]).toBeUndefined();
+    });
+  });
+
+  it('should set default values for optional config', () => {
+    // ARRANGE
+    process.env.DATABASE_URL = 'postgresql://test:test@localhost/test';
+    delete process.env.NODE_ENV;
+    delete process.env.PORT;
+    delete process.env.FRONTEND_URL;
+
+    // ACT
+    const { config } = require('../index');
+
+    // ASSERT
+    expect(config.NODE_ENV).toBe('development');
+    expect(config.PORT).toBe(3002);
+    expect(config.FRONTEND_URL).toBe('http://localhost:3000');
+  });
+});

package/templates/apps/api/src/config/index.ts

@@ -0,0 +1,56 @@
+/**
+ * AI Launch Kit API Configuration
+ *
+ * Local-only backend (auth + sessions). External-platform forwarding has been
+ * removed; AILK-native routes will be added in subsequent issues.
+ */
+import { logger } from '@working-theory/observability';
+import * as dotenv from 'dotenv';
+
+dotenv.config();
+
+export interface Config {
+  // Server
+  NODE_ENV: 'development' | 'production' | 'test';
+  PORT: number;
+  FRONTEND_URL: string;
+
+  // Local Database (for auth: User, Session, ApiToken, etc.)
+  DATABASE_URL: string;
+
+  // Stripe — consumed by apps/api/src/lib/stripe.ts via @working-theory/stripe-client wrapper
+  STRIPE_SECRET_KEY?: string;
+  STRIPE_WEBHOOK_SECRET?: string;
+}
+
+function validateConfig(): Config {
+  const errors: string[] = [];
+
+  // Required: Local database for auth
+  if (!process.env.DATABASE_URL) {
+    errors.push('DATABASE_URL is required for authentication');
+  }
+
+  // Exit on errors
+  if (errors.length > 0) {
+    logger.error({ errors }, '❌ Configuration validation failed');
+    process.exit(1);
+  }
+
+  return {
+    NODE_ENV: (process.env.NODE_ENV || 'development') as Config['NODE_ENV'],
+    PORT: parseInt(process.env.PORT || '3002', 10),
+    FRONTEND_URL: process.env.FRONTEND_URL || 'http://localhost:3000',
+
+    DATABASE_URL: process.env.DATABASE_URL!,
+
+    ...(process.env.STRIPE_SECRET_KEY !== undefined && {
+      STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
+    }),
+    ...(process.env.STRIPE_WEBHOOK_SECRET !== undefined && {
+      STRIPE_WEBHOOK_SECRET: process.env.STRIPE_WEBHOOK_SECRET,
+    }),
+  };
+}
+
+export const config = validateConfig();

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

@@ -0,0 +1,32 @@
+/**
+ * AI Launch Kit API - Server Initialization
+ *
+ * Exports the start() function for starting the Fastify server.
+ * For CLI usage, see cli.ts
+ * For Vercel deployment, see api/index.ts which uses the build() function.
+ */
+import { logger } from '@working-theory/observability';
+
+import { config } from './config/index.js';
+import { build } from './server.js';
+
+export async function start() {
+  try {
+    const server = await build();
+
+    // Start server
+    await server.listen({ port: config.PORT, host: '0.0.0.0' });
+
+    logger.info(
+      {
+        port: config.PORT,
+        env: config.NODE_ENV,
+        endpoints: { auth: '/v1/auth/tokens, /v1/user/*' },
+      },
+      '🚀 AI Launch Kit API listening',
+    );
+  } catch (err) {
+    logger.error({ err }, 'Failed to start server');
+    process.exit(1);
+  }
+}

package/templates/apps/api/src/lib/__mocks__/prisma-client.js

@@ -0,0 +1,15 @@
+/**
+ * Mock PrismaClient for testing
+ */
+
+const MockPrismaClient = jest.fn().mockImplementation((options) => ({
+  $connect: jest.fn(),
+  $disconnect: jest.fn(),
+  user: {},
+  apiToken: {},
+  userData: {},
+}));
+
+module.exports = {
+  PrismaClient: MockPrismaClient,
+};

package/templates/apps/api/src/lib/__mocks__/prisma.ts

@@ -0,0 +1,45 @@
+/**
+ * Manual mock for prisma.ts
+ * Used by Jest when jest.mock('../../lib/prisma.js') is called.
+ *
+ * Covers all models accessed in route tests:
+ *   auth models (user, apiToken, userData) — used by auth route tests
+ *   inbox models (lead, subscriber, callback) — used by leads route tests (#507)
+ *
+ * Per-test return values: import `prisma` from this module and call
+ *   (prisma.lead.create as jest.Mock).mockResolvedValue({ id: "..." })
+ */
+
+export const prisma = {
+  // ── Auth namespace ──────────────────────────────────────────────────────────
+  user: {
+    findUnique: jest.fn(),
+    findFirst: jest.fn(),
+    update: jest.fn(),
+    create: jest.fn(),
+  },
+  apiToken: {
+    create: jest.fn(),
+    findMany: jest.fn(),
+    updateMany: jest.fn(),
+  },
+  userData: {
+    findUnique: jest.fn(),
+    upsert: jest.fn(),
+    deleteMany: jest.fn(),
+  },
+  // ── Inbox namespace (Lead, Subscriber, Callback) ─────────────────────────
+  lead: {
+    create: jest.fn(),
+  },
+  subscriber: {
+    create: jest.fn(),
+    findUnique: jest.fn(),
+  },
+  callback: {
+    create: jest.fn(),
+  },
+  // ── Lifecycle ────────────────────────────────────────────────────────────
+  $connect: jest.fn(),
+  $disconnect: jest.fn(),
+};

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

@@ -0,0 +1,178 @@
+/**
+ * Tests for apps/api/src/lib/content-adapter.ts factory.
+ *
+ * Covers:
+ *   (a) CONTENT_ADAPTER unset → MDX adapter (existing behavior preserved)
+ *   (b) CONTENT_ADAPTER=projection + valid manifest → projection adapter, read parity vs MDX
+ *   (c) CONTENT_ADAPTER=projection + missing manifest → clear actionable error at construction
+ */
+import { join, resolve } from "node:path";
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+
+import {
+  getContentAdapter,
+  getContentRoot,
+  resetContentAdapter,
+} from "../content-adapter.js";
+
+// Local fixture: a minimal content root with one HomePage page.
+const FIXTURE_ROOT = resolve(__dirname, "fixtures");
+
+// The matching manifest for the local fixture.
+const FIXTURE_MANIFEST =
+  JSON.stringify(
+    {
+      HomePage: [
+        {
+          type: "HomePage",
+          slug: "home",
+          title: "AI Launch Kit",
+          description:
+            "AX-first OSS template for shipping software with API and MCP.",
+        },
+      ],
+    },
+    null,
+    2,
+  ) + "\n";
+
+describe("getContentAdapter() factory", () => {
+  const savedEnv: Record<string, string | undefined> = {};
+
+  beforeEach(() => {
+    savedEnv.CONTENT_ADAPTER = process.env.CONTENT_ADAPTER;
+    savedEnv.CONTENT_ROOT = process.env.CONTENT_ROOT;
+    savedEnv.MANIFEST_PATH = process.env.MANIFEST_PATH;
+    resetContentAdapter();
+  });
+
+  afterEach(() => {
+    if (savedEnv.CONTENT_ADAPTER === undefined) {
+      delete process.env.CONTENT_ADAPTER;
+    } else {
+      process.env.CONTENT_ADAPTER = savedEnv.CONTENT_ADAPTER;
+    }
+    if (savedEnv.CONTENT_ROOT === undefined) {
+      delete process.env.CONTENT_ROOT;
+    } else {
+      process.env.CONTENT_ROOT = savedEnv.CONTENT_ROOT;
+    }
+    if (savedEnv.MANIFEST_PATH === undefined) {
+      delete process.env.MANIFEST_PATH;
+    } else {
+      process.env.MANIFEST_PATH = savedEnv.MANIFEST_PATH;
+    }
+    resetContentAdapter();
+  });
+
+  describe("(a) CONTENT_ADAPTER unset → MDX adapter", () => {
+    test("returns an adapter that reads fixture pages via MDX", async () => {
+      delete process.env.CONTENT_ADAPTER;
+      process.env.CONTENT_ROOT = FIXTURE_ROOT;
+
+      const adapter = getContentAdapter();
+      expect(adapter).toBeDefined();
+      const page = await adapter.getPageBySlug("HomePage", "home");
+      expect(page).not.toBeNull();
+      expect(page?.title).toBe("AI Launch Kit");
+    });
+  });
+
+  describe("(b) CONTENT_ADAPTER=projection + valid manifest → projection adapter", () => {
+    let tmpDir: string;
+    let manifestPath: string;
+
+    beforeEach(() => {
+      tmpDir = join(tmpdir(), `ailk-adapter-test-${Date.now()}`);
+      mkdirSync(tmpDir, { recursive: true });
+      manifestPath = join(tmpDir, "manifest.json");
+      writeFileSync(manifestPath, FIXTURE_MANIFEST, "utf8");
+    });
+
+    afterEach(() => {
+      rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    test("returns projection adapter when CONTENT_ADAPTER=projection", async () => {
+      process.env.CONTENT_ADAPTER = "projection";
+      process.env.MANIFEST_PATH = manifestPath;
+
+      const adapter = getContentAdapter();
+      const page = await adapter.getPageBySlug("HomePage", "home");
+      expect(page).not.toBeNull();
+      expect(page?.title).toBe("AI Launch Kit");
+    });
+
+    test("read parity: projection adapter listPages matches MDX adapter against same fixture", async () => {
+      // MDX adapter against local fixture
+      delete process.env.CONTENT_ADAPTER;
+      process.env.CONTENT_ROOT = FIXTURE_ROOT;
+      const mdxAdapter = getContentAdapter();
+      const mdxPages = await mdxAdapter.listPages("HomePage");
+      resetContentAdapter();
+
+      // Projection adapter backed by manifest matching same fixture
+      process.env.CONTENT_ADAPTER = "projection";
+      process.env.MANIFEST_PATH = manifestPath;
+      const projAdapter = getContentAdapter();
+      const projPages = await projAdapter.listPages("HomePage");
+
+      const sortBySlug = (a: { slug: string }, b: { slug: string }) =>
+        a.slug.localeCompare(b.slug);
+      expect(projPages.sort(sortBySlug)).toEqual(mdxPages.sort(sortBySlug));
+    });
+
+    test("projection adapter write methods throw read-only error", async () => {
+      process.env.CONTENT_ADAPTER = "projection";
+      process.env.MANIFEST_PATH = manifestPath;
+
+      const adapter = getContentAdapter();
+      await expect(
+        adapter.createPage("HomePage", "new", {
+          type: "HomePage",
+          slug: "new",
+          title: "New",
+          description: "Desc",
+          body: "body",
+        }),
+      ).rejects.toThrow("read-only");
+    });
+  });
+
+  describe("(c) CONTENT_ADAPTER=projection + missing manifest → clear actionable error", () => {
+    test("throws at getContentAdapter() call time naming the missing path and instructing compile step", () => {
+      process.env.CONTENT_ADAPTER = "projection";
+      process.env.MANIFEST_PATH = "/nonexistent/path/manifest.json";
+
+      expect(() => getContentAdapter()).toThrow(
+        "/nonexistent/path/manifest.json",
+      );
+      expect(() => getContentAdapter()).toThrow("pnpm content:compile");
+    });
+  });
+});
+
+describe("getContentRoot()", () => {
+  const savedContentRoot = process.env.CONTENT_ROOT;
+
+  afterEach(() => {
+    if (savedContentRoot === undefined) {
+      delete process.env.CONTENT_ROOT;
+    } else {
+      process.env.CONTENT_ROOT = savedContentRoot;
+    }
+  });
+
+  test("returns CONTENT_ROOT env when set", () => {
+    process.env.CONTENT_ROOT = "/explicit/content/root";
+    expect(getContentRoot()).toBe("/explicit/content/root");
+  });
+
+  test("returns a string path when env is unset", () => {
+    delete process.env.CONTENT_ROOT;
+    const root = getContentRoot();
+    expect(typeof root).toBe("string");
+    expect(root.length).toBeGreaterThan(0);
+  });
+});

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

@@ -0,0 +1,100 @@
+/**
+ * error-serializer — Fastify error handler that prevents internal-error leaks.
+ *
+ * Internal exceptions (DB errors, third-party SDK errors, unhandled throws)
+ * must NOT echo their `.message` or stack trace to the client. Clients see a
+ * generic `internal_error`; the full detail goes to pino at error level.
+ *
+ * Validation errors (Fastify's built-in 400 with FST_ERR_VALIDATION) keep
+ * their structured detail because schemas are safe to surface.
+ *
+ * Explicitly-set HTTP statuses (`reply.code(404).send(...)`) flow through
+ * untouched.
+ */
+import Fastify, { type FastifyInstance } from "fastify";
+
+import { registerErrorSerializer } from "../error-serializer.js";
+
+describe("error-serializer", () => {
+  let server: FastifyInstance;
+  const logLines: Array<Record<string, unknown>> = [];
+
+  beforeEach(async () => {
+    logLines.length = 0;
+    server = Fastify({
+      logger: {
+        level: "error",
+        stream: {
+          write(msg: string) {
+            logLines.push(JSON.parse(msg) as Record<string, unknown>);
+          },
+        },
+      },
+    });
+
+    registerErrorSerializer(server);
+
+    server.get("/boom", async () => {
+      throw new Error(
+        "internal-detail: connection refused at db host secret.host.internal:5432",
+      );
+    });
+
+    server.get("/explicit-400", async (_req, reply) => {
+      await reply.code(400).send({ error: "validation-error" });
+    });
+
+    server.get("/explicit-404", async (_req, reply) => {
+      await reply.code(404).send({ error: "not-found" });
+    });
+
+    await server.ready();
+  });
+
+  afterEach(async () => {
+    await server.close();
+  });
+
+  it("returns generic internal_error on uncaught throw — no detail in body", async () => {
+    const response = await server.inject({ method: "GET", url: "/boom" });
+
+    expect(response.statusCode).toBe(500);
+    const body = JSON.parse(response.body) as Record<string, unknown>;
+    expect(body).toEqual({ error: "internal_error" });
+    expect(JSON.stringify(body)).not.toContain("connection refused");
+    expect(JSON.stringify(body)).not.toContain("secret.host.internal");
+    expect(JSON.stringify(body)).not.toContain("stack");
+  });
+
+  it("logs full error detail to pino at error level", async () => {
+    await server.inject({ method: "GET", url: "/boom" });
+
+    const text = JSON.stringify(logLines);
+    expect(text).toContain("connection refused");
+  });
+
+  it("does NOT include stack traces in response body", async () => {
+    const response = await server.inject({ method: "GET", url: "/boom" });
+
+    expect(response.body).not.toMatch(/at\s+\w+\s+\(/); // typical stack frame
+    expect(response.body).not.toContain("Error:");
+  });
+
+  it("leaves explicit 4xx replies untouched", async () => {
+    const r400 = await server.inject({ method: "GET", url: "/explicit-400" });
+    expect(r400.statusCode).toBe(400);
+    expect(JSON.parse(r400.body)).toEqual({ error: "validation-error" });
+
+    const r404 = await server.inject({ method: "GET", url: "/explicit-404" });
+    expect(r404.statusCode).toBe(404);
+    expect(JSON.parse(r404.body)).toEqual({ error: "not-found" });
+  });
+
+  it("doesn't leak the Error.message via the default 'message' field", async () => {
+    const response = await server.inject({ method: "GET", url: "/boom" });
+    const body = JSON.parse(response.body) as Record<string, unknown>;
+
+    expect(body["message"]).toBeUndefined();
+    expect(body["statusCode"]).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,94 @@
+/**
+ * Unit tests for the canonical error helpers used by D14a content-write
+ * routes. Asserts each helper returns the right status + canonical body shape
+ * with the correct machine code.
+ */
+
+import {
+  conflictError,
+  notFoundError,
+  paymentRequiredError,
+  unauthorizedError,
+  validationError,
+} from "../errors.js";
+
+describe("apps/api/lib/errors", () => {
+  describe("validationError", () => {
+    it("returns status 400 with validation_failed code", () => {
+      const err = validationError("Invalid input");
+      expect(err.status).toBe(400);
+      expect(err.body).toEqual({
+        error: "validation_failed",
+        message: "Invalid input",
+      });
+    });
+
+    it("includes details when provided", () => {
+      const err = validationError("Invalid type or slug", {
+        field: "type",
+        received: "Unknown",
+      });
+      expect(err.body).toEqual({
+        error: "validation_failed",
+        message: "Invalid type or slug",
+        details: { field: "type", received: "Unknown" },
+      });
+    });
+
+    it("omits details key entirely when not provided", () => {
+      const err = validationError("Bad input");
+      expect("details" in err.body).toBe(false);
+    });
+  });
+
+  describe("unauthorizedError", () => {
+    it("returns status 401 with unauthorized code", () => {
+      const err = unauthorizedError("Missing or invalid token");
+      expect(err.status).toBe(401);
+      expect(err.body).toEqual({
+        error: "unauthorized",
+        message: "Missing or invalid token",
+      });
+    });
+  });
+
+  describe("paymentRequiredError", () => {
+    it("returns status 402 with payment_required code", () => {
+      const err = paymentRequiredError("Pro license required");
+      expect(err.status).toBe(402);
+      expect(err.body).toEqual({
+        error: "payment_required",
+        message: "Pro license required",
+      });
+    });
+  });
+
+  describe("notFoundError", () => {
+    it("returns status 404 with not_found code", () => {
+      const err = notFoundError("Page not found");
+      expect(err.status).toBe(404);
+      expect(err.body).toEqual({
+        error: "not_found",
+        message: "Page not found",
+      });
+    });
+  });
+
+  describe("conflictError", () => {
+    it("returns status 409 with conflict code", () => {
+      const err = conflictError("Stale version token");
+      expect(err.status).toBe(409);
+      expect(err.body).toEqual({
+        error: "conflict",
+        message: "Stale version token",
+      });
+    });
+
+    it("includes details (e.g. existing version) when provided", () => {
+      const err = conflictError("Slug already exists", {
+        existingVersion: "abc123",
+      });
+      expect(err.body.details).toEqual({ existingVersion: "abc123" });
+    });
+  });
+});