npm - create-ailk - Versions diffs - 0.1.0 - Mend

create-ailk 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (533) hide show

package/templates/README.md ADDED Viewed

@@ -0,0 +1,110 @@
+<!--
+  This README ships with every site scaffolded by `pnpm create ailk@latest`.
+  Substitution markers — search-and-replace these or let `create-ailk`
+  substitute on first run:
+    {{PROJECT_NAME}}    — the directory name you scaffolded into
+    {{COMPANY_NAME}}    — the legal/marketing name of the entity behind the site
+    {{COMPANY_DOMAIN}}  — the canonical domain for the site (e.g. acme.example)
+-->
+# {{PROJECT_NAME}}
+Built with [AI Launch Kit](https://ailaunchkit.ai). AI Launch Kit (AILK) is an agent-first OSS template — every page emits clean schema.org JSON-LD, every server action has a matching MCP tool, and every install is one command. This site is yours; you can edit it like any other repo.
+## Run
+```bash
+pnpm install
+pnpm dev
+```
+Open <http://localhost:3000>. The home page renders from `content/en/HomePage/home.mdx` with valid JSON-LD already in the `<head>`.
+To verify everything is wired before committing or deploying:
+```bash
+pnpm preflight   # architecture + types + lint + build
+pnpm build       # production build
+```
+> Requires Node.js 20+ and `pnpm`. No vendor API keys are required for first boot — Stripe, Anthropic, and email-provider integrations are opt-in.
+## Content
+The `content/` directory is locale-prefixed: every page lives at `content/<locale>/<type>/<slug>.mdx`. The default locale is `en` (English); the AILK scaffold ships English content only. Each subdirectory under `content/en/` is a schema-typed page surface — HomePage, AboutPage, ContactPage, FAQPage, Products, Services, Projects, BlogList, BlogPosting, and friends. The filename is the slug.
+To customize the home page, edit [`content/en/HomePage/home.mdx`](./content/en/HomePage/home.mdx). Save and reload the dev server. No build step.
+To add a new page, copy an existing MDX file in the matching directory and edit the frontmatter (`type`, `slug`, `title`, `description`).
+> `content/_site.mdx` stays at the top level (not under `content/en/`) — site identity is locale-blind.
+## Theme
+Design tokens live in [`packages/theme`](https://www.npmjs.com/package/@working-theory/theme) (consumed from npm; no source edits needed). Components in [`packages/ui`](https://www.npmjs.com/package/@working-theory/ui) read from those tokens.
+To swap the brand color, override the `theme.brand` token at the consumer site by extending the theme in your root layout. Example:
+```ts
+// app/layout.tsx (sketch)
+import { theme } from "@working-theory/theme";
+const myTheme = {
+  ...theme,
+  brand: { ...theme.brand, primary: "#0a84ff" },
+};
+```
+Apply `myTheme` via the provider you use to wrap children. The full extension surface is documented at <https://ailaunchkit.ai/theme>.
+## Environment
+Copy `.env.example` to `.env` and fill in only what you need. Most variables are optional. A complete reference:
+| Variable                           | Purpose                                                                                                                   |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `AILK_LICENSE_KEY`                 | Optional. JWT issued by ailaunchkit.ai; verified locally to unlock Pro features. Get one at <https://ailaunchkit.ai/pro>. |
+| `NEXT_PUBLIC_STREAMING_AI_ENABLED` | Optional. Set to `true` to enable the opt-in streaming AI assist UI. Off by default.                                      |
+| `ANTHROPIC_API_KEY`                | Required only when `NEXT_PUBLIC_STREAMING_AI_ENABLED=true`. Used by the AI assist surface only.                           |
+| `AILK_LOCAL_LEAD_CAPTURE`          | Optional. When `true`, leads from the contact form are written to a local file instead of an API.                         |
+| `AILK_LEADS_API_URL`               | Optional. Override the upstream that receives lead-capture submissions.                                                   |
+See [`.env.example`](./.env.example) for the full template with comments. Per-app overrides (e.g. `apps/api/.env`) are honored alongside the root `.env`.
+## AI assist (optional)
+The site ships with an opt-in streaming AI assist. It is **off by default**. To turn it on, set `NEXT_PUBLIC_STREAMING_AI_ENABLED=true` in `.env` and provide an `ANTHROPIC_API_KEY`. The assist runs server-side so the API key never reaches the browser. With both unset, the chat UI is hidden and no AI traffic flows.
+## Deploy
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/{{COMPANY_NAME}}/{{PROJECT_NAME}})
+Or from the project root:
+```bash
+pnpm vercel
+```
+The `vercel.json` files inside `apps/web` and `apps/api` configure each surface as an independent Vercel project. Connect both, set the env vars listed above, and ship.
+## Upgrading
+This site consumes versioned `@working-theory/*` packages from npm. To pull upstream changes:
+```bash
+pnpm update '@working-theory/*'
+```
+That's the entire upgrade flow. There is no `git pull upstream`, no codemod, no fork-and-merge. Breaking changes ship in major-version bumps of the relevant `@working-theory/*` package; release notes call them out explicitly.
+If you need to override a section component, swap its registration in the section registry (see <https://ailaunchkit.ai/sections>). Framework code stays out of your tree.
+## License & contributing
+Your project — `{{PROJECT_NAME}}`, owned by {{COMPANY_NAME}} ({{COMPANY_DOMAIN}}) — is yours. Pick whatever license suits you.
+The AI Launch Kit framework upstream is **Apache 2.0** — see <https://github.com/tailwind-ai/ai-launch-kit/blob/main/LICENSE>. Contributions are welcome at the upstream repo; start with the [contributing guide](https://github.com/tailwind-ai/ai-launch-kit/blob/main/CONTRIBUTING.md).
+For the full handbook, examples, and Pro features: <https://ailaunchkit.ai>.

package/templates/apps/api/.env.example ADDED Viewed

@@ -0,0 +1,40 @@
+# =============================================================================
+# AI Launch Kit API Configuration
+# =============================================================================
+# Local-only backend:
+# - Handles local auth (sessions, API tokens)
+# - Reserves Stripe webhook secret for future use
+# =============================================================================
+# Server
+# =============================================================================
+NODE_ENV=development
+PORT=3002
+# =============================================================================
+# Frontend URL (for CORS)
+# =============================================================================
+FRONTEND_URL=http://localhost:3000
+# =============================================================================
+# Local Database (REQUIRED)
+# =============================================================================
+# For auth only: User, Session, ApiToken, etc.
+DATABASE_URL="postgresql://user:password@localhost:5432/customer_template"
+# =============================================================================
+# Stripe (Optional)
+# =============================================================================
+# Consumed by apps/api/src/lib/stripe.ts via @working-theory/stripe-client wrapper.
+# Use sandbox keys only — live-mode keys are rejected at runtime.
+STRIPE_SECRET_KEY=sk_test_xxx
+STRIPE_WEBHOOK_SECRET=whsec_xxx
+# =============================================================================
+# Internal service-to-service auth (#935)
+# =============================================================================
+# When set, POST /v1/checkout/sessions requires the X-Internal-Auth header
+# to match this value. Unset for OSS standalone deployments (no gate applied).
+# Must match OSS_API_INTERNAL_SECRET in apps-paid/marketing-api/.env.local.
+# Generate with: openssl rand -hex 32
+# OSS_API_INTERNAL_SECRET=your-shared-secret-here

package/templates/apps/api/CLAUDE.md ADDED Viewed

@@ -0,0 +1,63 @@
+# apps/api — Fastify REST API
+Inherits root `CLAUDE.md`. This file adds API-specific rules.
+## Stack
+- Fastify, TypeScript
+- Persistence: configurable adapter (default DB; file fallback so OSS works without DB config)
+- Email: operator-notification stub at OSS; routing pipeline at Pro (in `@working-theory/*`)
+## API ↔ MCP parity (hard rule)
+Every endpoint here has a 1:1 MCP tool in `apps/mcp`. When you add, change, or remove an endpoint, update the MCP tool in the same PR. CI enforces — broken parity fails the build.
+## Endpoint conventions
+Routes are versioned under `/v1/*`:
+- `/v1/leads/{submit,subscribe,callback}` — lead capture, newsletter subscription, callback request
+- `/v1/content/{types,:type,:type/:slug}` — public content reads
+- `/v1/auth/tokens`, `/v1/user/{profile,data/:key}` — local auth + user data
+- `/v1/checkout/sessions` — start a Stripe checkout
+AEO Layer 1 scoring runs locally as a CLI command (`ailk audit`), not an HTTP endpoint.
+JSON in, JSON out. Validate inputs with `@working-theory/validation`. Response envelope:
+- Success: `{ ok: true, data }`
+- Error: `{ ok: false, error: { code, message } }`
+Use HTTP status codes — never 200 with `ok: false`.
+## Lead capture pipeline (OSS scope)
+Capture → persist (DB or file) → notify operator → return success. That's the entire OSS pipeline.
+Routing rules, enrichment, dedupe, webhook fan-out, CRM integration live in `@working-theory/lead-routing`, loaded via JWT entitlement check. Never hardcode routing logic here — the boundary is what makes paid additive.
+## Persistence
+- DB adapter is the default. File fallback exists for zero-config OSS use.
+- Don't assume a DB is configured. Read `AILK_DB_URL` and degrade gracefully.
+- Migrations in `database/migrations`. Never edit a shipped migration — add a new one.
+## Error handling
+- Never leak stack traces in responses. Log them, return a code.
+- 4xx for client errors, 5xx for server errors.
+- Errors emitted here must map to MCP error responses with the same code (parity).
+## BYO Stripe
+- `@working-theory/stripe-client` wraps Stripe. Credentials come from customer env vars.
+- Don't assume Stripe is configured. Read at startup; if missing, disable commerce endpoints and log a warning.
+- Never log secret keys, even at debug.
+## What NOT to do
+- Don't import `@working-theory/*` from `apps/api`. Paid features run via JWT checks inside paid packages.
+- Don't add an endpoint without the matching MCP tool.
+- Don't return 200 with `{ ok: false }`.
+- Don't read MDX directly — use `@working-theory/content-adapters`.
+- Don't put session state in `apps/api`. It's stateless.

package/templates/apps/api/api/index.ts ADDED Viewed

@@ -0,0 +1,144 @@
+/**
+ * Vercel Serverless Function Handler for Customer Template Backend
+ * This file wraps the Fastify server for Vercel's serverless functions
+ */
+import { logger } from '@working-theory/observability';
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+import type { build as buildServer } from '../src/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('../src/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');
+    const fastifyRequest = {
+      method: req.method || 'GET',
+      url: pathname,
+      headers: req.headers as Record<string, string>,
+      body: req.body,
+      query: req.query as Record<string, string>,
+    };
+    const response = await server.inject(fastifyRequest);
+    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) {
+      const body = typeof response.body === 'string'
+        ? response.body
+        : JSON.stringify(response.body);
+      res.send(body);
+      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/jest.config.cjs ADDED Viewed

@@ -0,0 +1,74 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/__tests__/**/*.test.ts', '**/?(*.)+(test).ts'],
+  testPathIgnorePatterns: ['/node_modules/', '.*\\.spec\\.ts$'],
+  // Ignore node_modules except jose (ESM-only, loaded transitively via @working-theory/license → @working-theory/schema-pack-registry → @working-theory/schema).
+  transformIgnorePatterns: ['/node_modules/(?!(\\.pnpm/)?jose@?[^/]*?(/|$))'],
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  setupFilesAfterEnv: ['<rootDir>/src/__tests__/setup.ts'],
+  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.d.ts', '!src/__tests__/**'],
+  // Use v8 coverage provider for better async code tracking (route handlers via Fastify inject)
+  coverageProvider: 'v8',
+  coverageThreshold: {
+    global: {
+      lines: 85,
+      functions: 88, // Lowered from 90% due to technical limitations (index.ts, prisma.ts, stripe.ts preParsing hook)
+      branches: 85,
+      statements: 85,
+    },
+  },
+  moduleNameMapper: {
+    // Mock server-only in Jest environments — the package throws by design
+    // outside Next.js. The real guard runs in production Next.js builds.
+    '^server-only$': '<rootDir>/../../__mocks__/server-only.ts',
+    // Map Prisma client import for testing (must come before the generic .js stripper).
+    // Phase C (#710): the v7 prisma-client generator emits TypeScript source files
+    // (client.ts) that use `import.meta.url`, which Jest's CommonJS preset can't
+    // load directly. apps/api now imports from @working-theory/database; tests mock both
+    // forms to the same shared mock.
+    '^@working-theory/database$': '<rootDir>/src/lib/__mocks__/prisma-client.js',
+    '^.*database/generated/client/(index|client)\\.(js|ts)$': '<rootDir>/src/lib/__mocks__/prisma-client.js',
+    // Map workspace packages to their TypeScript source so ts-jest compiles them
+    // directly (the published dist is ESM, which Jest's CJS preset can't load).
+    '^@working-theory/analytics/server$': '<rootDir>/../../packages/analytics/src/server/index.ts',
+    '^@vercel/analytics/server$': '<rootDir>/../../packages/analytics/__mocks__/vercel-analytics-server.ts',
+    '^@working-theory/common$': '<rootDir>/../../packages/common/src/index.ts',
+    '^@working-theory/content-adapters$': '<rootDir>/../../packages/content-adapters/src/index.ts',
+    '^@working-theory/content-projection$': '<rootDir>/../../packages/content-projection/src/index.ts',
+    '^@working-theory/content-projection/node$': '<rootDir>/../../packages/content-projection/src/node.ts',
+    '^@working-theory/email$': '<rootDir>/../../packages/email/src/index.ts',
+    '^@working-theory/license$': '<rootDir>/../../packages/license/src/index.ts',
+    '^@working-theory/observability$': '<rootDir>/../../packages/observability/src/index.ts',
+    '^@working-theory/schema/faq$': '<rootDir>/../../packages/schema/src/faq.ts',
+    '^@working-theory/schema$': '<rootDir>/../../packages/schema/src/index.ts',
+    '^@working-theory/schema-pack-registry$': '<rootDir>/../../packages/schema-pack-registry/src/index.ts',
+    '^@working-theory/stripe-client$': '<rootDir>/../../packages/stripe-client/src/index.ts',
+    '^@working-theory/validation$': '<rootDir>/../../packages/validation/src/index.ts',
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  transform: {
+    '^.+\\.(tsx?|jsx?|mjs)$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          module: 'commonjs', // Jest runs in CommonJS
+          target: 'ES2020',
+          lib: ['ES2020'],
+          allowJs: true,
+          declaration: false,
+          strict: true,
+          esModuleInterop: true,
+          skipLibCheck: true,
+          ignoreDeprecations: '6.0',
+          forceConsistentCasingInFileNames: true,
+        },
+        // Allow import.meta syntax to be parsed (source is ESM, but we compile to CommonJS)
+        diagnostics: {
+          ignoreCodes: [1343], // Ignore "import.meta only allowed in ESM modules" error
+        },
+      },
+    ],
+  },
+};

package/templates/apps/api/package.json ADDED Viewed

@@ -0,0 +1,54 @@
+{
+  "name": "@working-theory/api",
+  "version": "1.0.0",
+  "description": "AI Launch Kit API — Fastify routes + services",
+  "private": true,
+  "license": "Apache-2.0",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/cli.ts",
+    "build": "tsc",
+    "build:vercel": "cd ../../database && pnpm exec prisma generate && cd ../.. && pnpm --filter @working-theory/validation build && pnpm --filter @working-theory/api build && mkdir -p apps/api/public && echo '{}' > apps/api/public/.vercel",
+    "start": "node dist/cli.js",
+    "lint": "eslint src --ext .ts",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "db:generate": "cd ../../database && prisma generate",
+    "db:push": "cd ../../database && prisma db push",
+    "db:migrate": "cd ../../database && prisma migrate dev",
+    "db:studio": "cd ../../database && prisma studio"
+  },
+  "dependencies": {
+    "@working-theory/analytics": "workspace:*",
+    "@working-theory/common": "workspace:*",
+    "@working-theory/content-adapters": "workspace:*",
+    "@working-theory/content-projection": "workspace:*",
+    "@working-theory/database": "workspace:*",
+    "@working-theory/email": "workspace:*",
+    "@working-theory/license": "workspace:*",
+    "@working-theory/observability": "workspace:*",
+    "@working-theory/schema": "workspace:*",
+    "@working-theory/stripe-client": "workspace:*",
+    "@working-theory/validation": "workspace:*",
+    "@fastify/cors": "^11.2.0",
+    "@fastify/rate-limit": "^10.3.0",
+    "@prisma/adapter-pg": "^7.8.0",
+    "@prisma/client": "^7.8.0",
+    "dotenv": "^17.4.2",
+    "fastify": "^5.7.2",
+    "pg": "^8.22.0",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.20.0",
+    "@types/pg": "^8.20.0",
+    "@vercel/node": "^5.8.22",
+    "jest": "^30.4.2",
+    "prisma": "^7.8.0",
+    "ts-jest": "^29.4.11",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  }
+}

package/templates/apps/api/src/__tests__/factories/content-fixture.ts ADDED Viewed

@@ -0,0 +1,138 @@
+/**
+ * @file content-fixture.ts
+ * Filesystem fixture helpers for content route tests.
+ *
+ * Creates a per-test temp directory with minimal MDX fixture content,
+ * points the content adapter at it via CONTENT_ROOT env, and cleans up
+ * in afterEach. This allows content route tests to exercise the real
+ * content adapter stack without mocking internal modules.
+ *
+ * Usage:
+ *   import { setupContentFixture } from "../../__tests__/factories/content-fixture";
+ *
+ *   const { getContentRoot } = setupContentFixture();
+ *
+ * The setup/teardown hooks register themselves — call setupContentFixture()
+ * at describe-scope and the beforeEach/afterEach run automatically.
+ *
+ * Issue #507: replaces jest.mock("../../../lib/content-adapter.js") in
+ * content route tests.
+ */
+import * as fs from "fs/promises";
+import * as os from "os";
+import * as path from "path";
+import { resetContentAdapter } from "../../lib/content-adapter.js";
+export interface ContentFixture {
+  /** Returns the current temp content root (changes per test). */
+  getContentRoot: () => string;
+  /**
+   * Write an additional MDX file into the fixture dir.
+   * type and slug are used to construct the path: <root>/<type>/<slug>.mdx
+   */
+  writeFixturePage: (
+    type: string,
+    slug: string,
+    frontmatter: Record<string, string>,
+    body?: string,
+  ) => Promise<void>;
+}
+/**
+ * Register beforeEach/afterEach hooks that create a fresh temp dir per test,
+ * set CONTENT_ROOT, and reset the adapter singleton.
+ *
+ * Returns a fixture handle for writing additional content from within tests.
+ */
+export function setupContentFixture(): ContentFixture {
+  let contentRoot = "";
+  beforeEach(async () => {
+    contentRoot = await fs.mkdtemp(
+      path.join(os.tmpdir(), "ailk-api-content-test-"),
+    );
+    // Seed one fixture page per supported type so the adapter is not empty.
+    // Tests that need specific pages call writeFixturePage() themselves.
+    await Promise.all([
+      writeDefaultFixture(contentRoot, "HomePage", "home"),
+      writeDefaultFixture(contentRoot, "AboutPage", "about"),
+      writeDefaultFixture(contentRoot, "Product", "test-product"),
+    ]);
+    process.env.CONTENT_ROOT = contentRoot;
+    resetContentAdapter();
+  });
+  afterEach(async () => {
+    delete process.env.CONTENT_ROOT;
+    resetContentAdapter();
+    // Best-effort cleanup — don't fail the test if temp dir can't be removed.
+    try {
+      await fs.rm(contentRoot, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+    contentRoot = "";
+  });
+  return {
+    getContentRoot: () => contentRoot,
+    writeFixturePage: (type, slug, frontmatter, body = "") =>
+      writeFixturePage(contentRoot, type, slug, frontmatter, body),
+  };
+}
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+async function writeDefaultFixture(
+  root: string,
+  type: string,
+  slug: string,
+): Promise<void> {
+  await writeFixturePage(
+    root,
+    type,
+    slug,
+    {
+      type,
+      slug,
+      title: `${type} ${slug} title`,
+      description: `${type} ${slug} description`,
+    },
+    `Default fixture body for ${type}/${slug}.`,
+  );
+}
+async function writeFixturePage(
+  root: string,
+  type: string,
+  slug: string,
+  frontmatter: Record<string, string>,
+  body = "",
+): Promise<void> {
+  // Write the fixture in TWO places:
+  //   1. <root>/en/<type>/<slug>.mdx — post-S2 locale-prefixed read path
+  //      (callers passing an explicit locale find pages here).
+  //   2. <root>/<type>/<slug>.mdx — legacy write path. The adapter's write
+  //      methods (createPage/updatePage/deletePage) still write here in
+  //      Phase 3 S3 per the S1 spec ("locale-aware writes deferred"), so
+  //      write-route tests assert against this layout.
+  // Duplicating the fixture keeps both read and write test paths happy until
+  // write tools learn the locale-prefixed layout.
+  const fmLines = Object.entries(frontmatter)
+    .map(([k, v]) => `${k}: "${v}"`)
+    .join("\n");
+  const content = `---\n${fmLines}\n---\n\n${body}\n`;
+  const localeDir = path.join(root, "en", type);
+  await fs.mkdir(localeDir, { recursive: true });
+  await fs.writeFile(path.join(localeDir, `${slug}.mdx`), content, "utf8");
+  const legacyDir = path.join(root, type);
+  await fs.mkdir(legacyDir, { recursive: true });
+  await fs.writeFile(path.join(legacyDir, `${slug}.mdx`), content, "utf8");
+}