anhedral 0.1.0

package/dist/templates/backend.js

@@ -0,0 +1,2337 @@
+import path from 'node:path';
+import { writeFile, exec } from '../util.js';
+import { getBackendInstallCommands } from '../commands.js';
+export async function scaffoldBackend(root, { projectName, displayName, frontendUrl }) {
+    const dir = path.join(root, 'backend');
+    // writeFile creates parent dirs automatically via mkdirSync
+    writePackageJson(dir, projectName);
+    writeTsConfig(dir);
+    writeEslintConfig(dir);
+    writeGitignore(dir);
+    writeEnvExample(dir, frontendUrl);
+    writeEnvFile(dir, frontendUrl);
+    writeDrizzleConfig(dir);
+    writeVitestConfig(dir);
+    writeVercelJson(dir);
+    writeTypes(dir);
+    writeDbFiles(dir);
+    writeErrorFiles(dir);
+    writeLibFiles(dir);
+    writePlugins(dir);
+    writeConfig(dir);
+    writeRepositories(dir);
+    writeRoutes(dir, displayName);
+    writeAppAndIndex(dir, displayName);
+    writeVercelEntry(dir);
+    writeTestFiles(dir);
+    for (const command of getBackendInstallCommands()) {
+        exec(command.cmd, dir);
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Config files
+// ═══════════════════════════════════════════════════════════════════════════
+function writePackageJson(dir, projectName) {
+    writeFile(path.join(dir, 'package.json'), JSON.stringify({
+        name: projectName + '-backend',
+        version: '1.0.0',
+        description: `${projectName} Backend`,
+        type: 'module',
+        scripts: {
+            dev: 'tsx --env-file=.env --watch src/index.ts',
+            build: 'pnpm typecheck',
+            typecheck: 'tsc --noEmit',
+            'db:generate': 'drizzle-kit generate',
+            'db:migrate': 'pnpm tsx --env-file=.env src/db/migrate.ts',
+            'db:studio': 'drizzle-kit studio',
+            'db:push': 'drizzle-kit push',
+            lint: 'eslint . --ext .js,.ts',
+            test: 'vitest run',
+            'test:watch': 'vitest',
+        },
+        keywords: [],
+        license: 'MIT',
+    }, null, 2) + '\n');
+}
+function writeTsConfig(dir) {
+    writeFile(path.join(dir, 'tsconfig.json'), JSON.stringify({
+        compilerOptions: {
+            target: 'ESNext',
+            module: 'NodeNext',
+            moduleResolution: 'NodeNext',
+            skipLibCheck: true,
+            rootDir: '.',
+            outDir: 'dist',
+            lib: ['ESNext', 'DOM', 'DOM.Iterable'],
+            types: ['node'],
+            sourceMap: true,
+            declaration: true,
+            declarationMap: true,
+            strict: true,
+            noUncheckedIndexedAccess: true,
+            verbatimModuleSyntax: true,
+            isolatedModules: true,
+            esModuleInterop: true,
+            resolveJsonModule: true,
+        },
+        include: ['src/**/*', 'api/**/*'],
+        exclude: ['node_modules'],
+    }, null, 2) + '\n');
+}
+function writeEslintConfig(dir) {
+    writeFile(path.join(dir, 'eslint.config.mjs'), `import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  { ignores: ['dist/', 'node_modules/'] },
+  { languageOptions: { globals: globals.node } },
+  ...tseslint.configs.recommended,
+);
+`);
+}
+function writeGitignore(dir) {
+    writeFile(path.join(dir, '.gitignore'), `node_modules/
+dist/
+.env
+.env.*
+!.env.example
+*.log
+*.tsbuildinfo
+`);
+}
+function writeEnvExample(dir, frontendUrl = 'http://localhost:8081') {
+    writeFile(path.join(dir, '.env.example'), `# Server
+PORT=8787
+NODE_ENV=development
+LOG_LEVEL=info
+
+# Database (NeonDB)
+DATABASE_URL="postgresql://neondb_owner:***@***.neon.tech/neondb?sslmode=require"
+
+# Clerk
+CLERK_PUBLISHABLE_KEY="pk_test_***"
+CLERK_SECRET_KEY="sk_test_***"
+
+# CORS
+FRONTEND_URL=${frontendUrl}
+EXTENSION_ORIGINS=
+
+# Cloudflare R2
+R2_ACCOUNT_ID=
+R2_ACCESS_KEY_ID=
+R2_SECRET_ACCESS_KEY=
+R2_BUCKET=
+
+# RevenueCat
+RC_SECRET_API_KEY=
+RC_WEBHOOK_SECRET=
+RC_ENTITLEMENT_ID=pro
+RC_OFFERING_ID=default
+`);
+}
+function writeEnvFile(dir, frontendUrl = 'http://localhost:8081') {
+    writeFile(path.join(dir, '.env'), `# Server
+PORT=8787
+NODE_ENV=development
+LOG_LEVEL=info
+
+# Database (NeonDB)
+DATABASE_URL="postgresql://user:pass@localhost:5432/app?sslmode=disable"
+
+# Clerk
+CLERK_PUBLISHABLE_KEY=""
+CLERK_SECRET_KEY=""
+
+# CORS
+FRONTEND_URL=${frontendUrl}
+EXTENSION_ORIGINS=
+
+# Cloudflare R2
+R2_ACCOUNT_ID=
+R2_ACCESS_KEY_ID=
+R2_SECRET_ACCESS_KEY=
+R2_BUCKET=
+
+# RevenueCat
+RC_SECRET_API_KEY=
+RC_WEBHOOK_SECRET=
+RC_ENTITLEMENT_ID=pro
+RC_OFFERING_ID=default
+`);
+}
+function writeDrizzleConfig(dir) {
+    writeFile(path.join(dir, 'drizzle.config.ts'), `import type { Config } from 'drizzle-kit';
+export default {
+  schema: './src/db/schema.ts',
+  out: './src/db/migrations',
+  dialect: 'postgresql',
+  dbCredentials: { url: process.env.DATABASE_URL! }
+} satisfies Config;
+`);
+}
+function writeVitestConfig(dir) {
+    writeFile(path.join(dir, 'vitest.config.ts'), `import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    setupFiles: ['./test/setup.ts'],
+    fileParallelism: false,
+    maxWorkers: 1,
+    testTimeout: 30000,
+  },
+});
+`);
+}
+function writeVercelJson(dir) {
+    writeFile(path.join(dir, 'vercel.json'), JSON.stringify({
+        version: 2,
+        builds: [{ src: 'api/index.ts', use: '@vercel/node' }],
+        routes: [{ src: '/(.*)', dest: 'api/index.ts' }],
+    }, null, 2) + '\n');
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════════════════════════════════════
+function writeTypes(dir) {
+    writeFile(path.join(dir, 'src/types/index.ts'), `import type { SubscriptionTier, SubscriptionStatus } from '../db/schema.js';
+
+export interface AppUser {
+  id: string;
+  subscriptionTier?: SubscriptionTier;
+  subscriptionStatus?: SubscriptionStatus;
+}
+
+export interface AppEnv {
+  PORT: number;
+  NODE_ENV: string;
+  LOG_LEVEL: string;
+  CLERK_PUBLISHABLE_KEY?: string | null;
+  CLERK_SECRET_KEY?: string | null;
+  FRONTEND_URL?: string | null;
+  EXTENSION_ORIGINS?: string | null;
+  DATABASE_URL?: string | null;
+  R2_ACCOUNT_ID?: string | null;
+  R2_ACCESS_KEY_ID?: string | null;
+  R2_SECRET_ACCESS_KEY?: string | null;
+  R2_BUCKET?: string | null;
+  RC_SECRET_API_KEY: string;
+  RC_WEBHOOK_SECRET: string;
+  RC_ENTITLEMENT_ID: string;
+  RC_OFFERING_ID: string;
+}
+`);
+    writeFile(path.join(dir, 'src/types/fastify-env.d.ts'), `import 'fastify';
+import type { AppEnv } from '../types/index.js';
+
+type FastifyReplyType = import('fastify').FastifyReply;
+type FastifyRequestType = import('fastify').FastifyRequest;
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    env: AppEnv;
+    authenticate?: (req: FastifyRequestType, reply: FastifyReplyType) => Promise<void> | void;
+  }
+
+  interface FastifyRequest {
+    _startedAt?: number;
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/types/fastify.d.ts'), `import 'fastify';
+import type { AppConfig } from '../config/index.js';
+import type { Repositories } from '../repositories/index.js';
+import type { AppUser } from '../types/index.js';
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    authenticate: (req: import('fastify').FastifyRequest, reply: import('fastify').FastifyReply) => Promise<void>;
+    config: AppConfig;
+    repos: Repositories;
+  }
+
+  interface FastifyRequest {
+    user?: AppUser;
+    _startedAt?: number;
+    waitUntil?: (promise: Promise<unknown>) => void;
+  }
+}
+
+export {};
+`);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Database
+// ═══════════════════════════════════════════════════════════════════════════
+function writeDbFiles(dir) {
+    writeFile(path.join(dir, 'src/db/index.ts'), `import { drizzle } from 'drizzle-orm/neon-http';
+import { neon } from '@neondatabase/serverless';
+
+if (!process.env.DATABASE_URL) {
+  throw new Error('DATABASE_URL is not defined');
+}
+
+const sql = neon(process.env.DATABASE_URL);
+export const db = drizzle(sql);
+export type Database = typeof db;
+`);
+    writeFile(path.join(dir, 'src/db/schema.ts'), `import { pgTable, text, timestamp, boolean, integer, index, jsonb } from 'drizzle-orm/pg-core';
+import type { InferSelectModel, InferInsertModel } from 'drizzle-orm';
+
+export const SUBSCRIPTION_TIERS = ['free', 'pro'] as const;
+export type SubscriptionTier = (typeof SUBSCRIPTION_TIERS)[number];
+
+export const SUBSCRIPTION_STATUSES = ['active', 'expired', 'canceled'] as const;
+export type SubscriptionStatus = (typeof SUBSCRIPTION_STATUSES)[number];
+
+export const SUBSCRIPTION_METHODS = ['trialing', 'redeemed', 'paid'] as const;
+export type SubscriptionMethod = (typeof SUBSCRIPTION_METHODS)[number];
+
+export const SUBSCRIPTION_ORIGINS = ['web', 'apple', 'google'] as const;
+export type SubscriptionOrigin = (typeof SUBSCRIPTION_ORIGINS)[number];
+
+export const SUBSCRIPTION_EVENT_TYPES = [
+  'trial_started', 'trial_converted', 'trial_expired',
+  'initial_purchase', 'renewal', 'product_change',
+  'cancellation_scheduled', 'cancellation_unscheduled', 'subscription_expired', 'subscription_canceled',
+  'promo_redeemed', 'billing_issue', 'billing_recovered',
+] as const;
+export type SubscriptionEventType = (typeof SUBSCRIPTION_EVENT_TYPES)[number];
+
+export type SubscriptionMetadata = {
+  revenueCatProductId?: string; lastWebhookUpdate?: string; cancelReason?: string;
+  redeemCode?: string; redeemCodeRedeemedAt?: string;
+};
+
+export type SubscriptionEventMetadata = {
+  revenueCatEventType?: string; revenueCatProductId?: string; promoCode?: string;
+  billingPeriod?: string; price?: { amount: number; currency: string };
+  store?: string; transactionId?: string; reason?: string;
+};
+
+export const PROMO_CODE_DURATIONS = [1, 6, 12] as const;
+export type PromoCodeDuration = (typeof PROMO_CODE_DURATIONS)[number];
+
+export const users = pgTable('users', {
+  id: text('id').primaryKey(),
+  email: text('email').notNull().unique(),
+  displayName: text('display_name'),
+  lastLoginAt: timestamp('last_login_at'),
+  profileImageUrl: text('profile_image_url'),
+  avatarObjectKey: text('avatar_object_key'),
+  avatarMimeType: text('avatar_mime_type'),
+  creditsBalance: integer('credits_balance').notNull().default(250),
+  createdAt: timestamp('created_at').$defaultFn(() => new Date()).notNull(),
+});
+
+export const subscriptions = pgTable('subscriptions', {
+  id: text('id').primaryKey(),
+  userId: text('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }).unique(),
+  tier: text('tier').$type<SubscriptionTier>().notNull().default('free'),
+  status: text('status').$type<SubscriptionStatus>().notNull().default('active'),
+  method: text('method').$type<SubscriptionMethod>(),
+  origin: text('origin').$type<SubscriptionOrigin>(),
+  billingPeriod: text('billing_period'),
+  currentPeriodStart: timestamp('current_period_start'),
+  currentPeriodEnd: timestamp('current_period_end'),
+  canceledAt: timestamp('canceled_at'),
+  cancelAtPeriodEnd: boolean('cancel_at_period_end').notNull().default(false),
+  trialStart: timestamp('trial_start'),
+  trialEnd: timestamp('trial_end'),
+  dailyLimit: integer('daily_limit'),
+  metadata: jsonb('metadata').$type<SubscriptionMetadata>(),
+  createdAt: timestamp('created_at').$defaultFn(() => new Date()).notNull(),
+  updatedAt: timestamp('updated_at').$defaultFn(() => new Date()).notNull(),
+}, (t) => [
+  index('subscriptions_user_idx').on(t.userId),
+  index('subscriptions_status_idx').on(t.status),
+  index('subscriptions_tier_idx').on(t.tier),
+  index('subscriptions_period_end_idx').on(t.currentPeriodEnd),
+]);
+
+export const subscriptionEvents = pgTable('subscription_events', {
+  id: text('id').primaryKey(),
+  userId: text('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
+  subscriptionId: text('subscription_id').references(() => subscriptions.id, { onDelete: 'set null' }),
+  eventType: text('event_type').$type<SubscriptionEventType>().notNull(),
+  previousTier: text('previous_tier').$type<SubscriptionTier>(),
+  previousStatus: text('previous_status').$type<SubscriptionStatus>(),
+  previousMethod: text('previous_method').$type<SubscriptionMethod>(),
+  newTier: text('new_tier').$type<SubscriptionTier>(),
+  newStatus: text('new_status').$type<SubscriptionStatus>(),
+  newMethod: text('new_method').$type<SubscriptionMethod>(),
+  revenueCatEventType: text('revenuecat_event_type'),
+  revenueCatProductId: text('revenuecat_product_id'),
+  origin: text('origin').$type<SubscriptionOrigin>(),
+  periodStart: timestamp('period_start'),
+  periodEnd: timestamp('period_end'),
+  metadata: jsonb('metadata').$type<SubscriptionEventMetadata>(),
+  createdAt: timestamp('created_at').$defaultFn(() => new Date()).notNull(),
+}, (t) => [
+  index('sub_events_user_idx').on(t.userId),
+  index('sub_events_user_created_idx').on(t.userId, t.createdAt),
+  index('sub_events_type_idx').on(t.eventType),
+]);
+
+export const trialClaims = pgTable('trial_claims', {
+  id: text('id').primaryKey(),
+  userId: text('user_id').references(() => users.id, { onDelete: 'set null' }),
+  email: text('email').notNull().unique(),
+  claimedAt: timestamp('claimed_at').$defaultFn(() => new Date()).notNull(),
+}, (t) => [index('trial_claims_email_idx').on(t.email)]);
+
+export const promoCodes = pgTable('promo_codes', {
+  id: text('id').primaryKey(),
+  code: text('code').notNull().unique(),
+  months: integer('months').$type<PromoCodeDuration>().notNull(),
+  maxRedemptions: integer('max_redemptions').notNull().default(1),
+  redeemedCount: integer('redeemed_count').notNull().default(0),
+  expiresAt: timestamp('expires_at'),
+  createdAt: timestamp('created_at').$defaultFn(() => new Date()).notNull(),
+}, (t) => [index('promo_codes_code_idx').on(t.code)]);
+
+export const promoRedemptions = pgTable('promo_redemptions', {
+  id: text('id').primaryKey(),
+  promoCodeId: text('promo_code_id').notNull().references(() => promoCodes.id, { onDelete: 'cascade' }),
+  userId: text('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
+  redeemedAt: timestamp('redeemed_at').$defaultFn(() => new Date()).notNull(),
+  entitlementExpiresAt: timestamp('entitlement_expires_at').notNull(),
+}, (t) => [
+  index('promo_redemptions_user_idx').on(t.userId),
+  index('promo_redemptions_code_idx').on(t.promoCodeId),
+]);
+
+export type Users = InferSelectModel<typeof users>;
+export type NewUsers = InferInsertModel<typeof users>;
+export type Subscriptions = InferSelectModel<typeof subscriptions>;
+export type NewSubscriptions = InferInsertModel<typeof subscriptions>;
+export type SubscriptionEvents = InferSelectModel<typeof subscriptionEvents>;
+export type NewSubscriptionEvents = InferInsertModel<typeof subscriptionEvents>;
+export type TrialClaims = InferSelectModel<typeof trialClaims>;
+export type NewTrialClaims = InferInsertModel<typeof trialClaims>;
+export type PromoCodes = InferSelectModel<typeof promoCodes>;
+export type NewPromoCodes = InferInsertModel<typeof promoCodes>;
+export type PromoRedemptions = InferSelectModel<typeof promoRedemptions>;
+export type NewPromoRedemptions = InferInsertModel<typeof promoRedemptions>;
+`);
+    writeFile(path.join(dir, 'src/db/migrate.ts'), `import { drizzle } from 'drizzle-orm/neon-http';
+import { migrate } from 'drizzle-orm/neon-http/migrator';
+import { neon } from '@neondatabase/serverless';
+import dotenv from 'dotenv';
+
+dotenv.config({ quiet: true });
+
+const runMigrate = async () => {
+  if (!process.env.DATABASE_URL) {
+    throw new Error('DATABASE_URL is not defined');
+  }
+
+  const client = neon(process.env.DATABASE_URL);
+  const db = drizzle(client);
+
+  console.log('⏳ Running migrations...');
+  const start = Date.now();
+  await migrate(db, { migrationsFolder: './src/db/migrations' });
+  console.log('✅ Migrations completed in', Date.now() - start, 'ms');
+  process.exit(0);
+};
+
+runMigrate().catch((err) => {
+  console.error('❌ Migration failed');
+  console.error(err);
+  process.exit(1);
+});
+`);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Errors
+// ═══════════════════════════════════════════════════════════════════════════
+function writeErrorFiles(dir) {
+    writeFile(path.join(dir, 'src/errors/AppError.ts'), `export class AppError extends Error {
+  constructor(
+    public readonly code: string,
+    public readonly statusCode: number,
+    message: string,
+    public readonly details?: unknown
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  toJSON() {
+    const json: { error: string; message: string; details?: unknown } = {
+      error: this.code,
+      message: this.message,
+    };
+    if (this.details !== undefined) json.details = this.details;
+    return json;
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/errors/AuthError.ts'), `import { AppError } from './AppError.js';
+
+export class AuthError extends AppError {
+  constructor(code: string, message: string, details?: unknown, statusCode: number = 401) {
+    super(code, statusCode, message, details);
+  }
+
+  static missingAuthorization() {
+    return new AuthError('missing_authorization', 'Authorization header is required');
+  }
+
+  static invalidAuthorization() {
+    return new AuthError('invalid_authorization', 'Invalid authorization credentials');
+  }
+
+  static invalidToken() {
+    return new AuthError('invalid_session_token', 'Invalid or malformed authentication token');
+  }
+
+  static tokenExpired() {
+    return new AuthError('token_expired', 'Authentication token has expired');
+  }
+
+  static userRequired() {
+    return new AuthError('user_authentication_required', 'This endpoint requires user authentication (JWT token)');
+  }
+
+  static unauthorized() {
+    return new AuthError('unauthorized', 'Authentication required');
+  }
+
+  static forbidden() {
+    return new AuthError('forbidden', 'Insufficient permissions', undefined, 403);
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/errors/ValidationError.ts'), `import { AppError } from './AppError.js';
+
+export class ValidationError extends AppError {
+  constructor(message: string, details?: unknown) {
+    super('validation_error', 400, message, details);
+  }
+
+  static missingField(field: string) {
+    return new ValidationError(\`Required field is missing: \${field}\`, { field });
+  }
+
+  static invalidFormat(field: string, expected: string) {
+    return new ValidationError(\`Invalid format for \${field}. Expected: \${expected}\`, { field, expected });
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/errors/NotFoundError.ts'), `import { AppError } from './AppError.js';
+
+export class NotFoundError extends AppError {
+  constructor(resource: string) {
+    super('not_found', 404, \`\${resource} not found\`);
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/errors/RateLimitError.ts'), `import { AppError } from './AppError.js';
+
+export class RateLimitError extends AppError {
+  constructor(message: string, details?: unknown) {
+    super('rate_limited', 429, message, details);
+  }
+
+  static dailyLimit(resource: string, limit: number) {
+    return new RateLimitError(
+      \`Daily \${resource} limit reached (\${limit} requests per day)\`,
+      { resource, limit, window: '24h' }
+    );
+  }
+
+  static tooManyRequests(retryAfter?: number) {
+    return new RateLimitError('Too many requests. Please try again later.', { retryAfter });
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/errors/ServerError.ts'), `import { AppError } from './AppError.js';
+
+export class ServerError extends AppError {
+  constructor(message: string, details?: unknown) {
+    super('server_error', 500, message, details);
+  }
+
+  static generic(details?: unknown) {
+    return new ServerError('An internal server error occurred', details);
+  }
+
+  static missingConfiguration(key: string) {
+    return new ServerError(\`Server misconfiguration: \${key} is not defined\`, { missingKey: key });
+  }
+
+  static databaseError(operation: string, error?: unknown) {
+    return new ServerError(\`Database operation failed: \${operation}\`, { operation, error });
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/errors/errorHandler.ts'), `import type { FastifyError, FastifyReply, FastifyRequest } from 'fastify';
+import { AppError } from './AppError.js';
+
+export function errorHandler(
+  error: Error | FastifyError,
+  req: FastifyRequest,
+  reply: FastifyReply
+) {
+  const isProduction = process.env.NODE_ENV === 'production';
+  const statusCode =
+    error instanceof AppError
+      ? error.statusCode
+      : ('statusCode' in error && typeof error.statusCode === 'number')
+          ? error.statusCode
+          : ('validation' in error && (error as FastifyError).validation)
+              ? 400
+              : 500;
+
+  const logPayload = {
+    msg: '[error_handler]',
+    id: req.id,
+    method: req.method,
+    url: req.url,
+    statusCode,
+    errorName: error.name,
+    errorMessage: error.message,
+    errorCode: (error as AppError).code,
+    ...(isProduction && statusCode < 500 ? {} : { stack: error.stack }),
+  };
+
+  if (statusCode < 500) {
+    req.log.warn(logPayload);
+  } else {
+    req.log.error(logPayload);
+  }
+
+  if (error instanceof AppError) {
+    return reply.status(error.statusCode).send(error.toJSON());
+  }
+
+  if ('validation' in error && error.validation) {
+    const validation = error.validation as Array<{ instancePath?: string; params?: { missingProperty?: string }; keyword?: string }>;
+    const missingField = validation.find(v => v.keyword === 'required');
+    if (missingField && missingField.params?.missingProperty) {
+      return reply.status(400).send({
+        error: 'missing_field',
+        message: \`Required field is missing: \${missingField.params.missingProperty}\`,
+        details: { field: missingField.params.missingProperty },
+      });
+    }
+    return reply.status(400).send({
+      error: 'validation_error',
+      message: 'Invalid request',
+      details: isProduction ? undefined : error.validation,
+    });
+  }
+
+  if ('statusCode' in error && typeof error.statusCode === 'number') {
+    return reply.status(error.statusCode).send({
+      error: error.name || 'error',
+      message: error.message,
+    });
+  }
+
+  return reply.status(500).send({ error: 'server_error', message: 'An unexpected error occurred' });
+}
+`);
+    writeFile(path.join(dir, 'src/errors/index.ts'), `export { AppError } from './AppError.js';
+export { AuthError } from './AuthError.js';
+export { ValidationError } from './ValidationError.js';
+export { NotFoundError } from './NotFoundError.js';
+export { RateLimitError } from './RateLimitError.js';
+export { ServerError } from './ServerError.js';
+export { errorHandler } from './errorHandler.js';
+`);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Lib
+// ═══════════════════════════════════════════════════════════════════════════
+function writeLibFiles(dir) {
+    writeFile(path.join(dir, 'src/lib/routeHelpers.ts'), `import type { FastifyRequest, FastifyReply, FastifyInstance } from 'fastify';
+import { AuthError } from '../errors/index.js';
+
+export function createAuthHook(fastify: FastifyInstance) {
+  return async (req: FastifyRequest, reply: FastifyReply) => {
+    if (typeof fastify.authenticate === 'function') {
+      await fastify.authenticate(req, reply);
+    } else {
+      throw AuthError.unauthorized();
+    }
+  };
+}
+
+export function runBackgroundTask(
+  req: FastifyRequest,
+  task: Promise<unknown>,
+  label?: string
+): void {
+  const wrapped = task.catch((error) => {
+    req.log.warn({
+      msg: '[background_task_failed]',
+      label,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  });
+
+  if (typeof req.waitUntil === 'function') {
+    req.waitUntil(wrapped);
+  } else {
+    void wrapped;
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/lib/lruCache.ts'), `interface CacheEntry<T> {
+  value: T;
+  expiresAt: number;
+}
+
+export class LRUCache<T> {
+  private cache = new Map<string, CacheEntry<T>>();
+  private maxSize: number;
+  private ttlMs: number;
+  private pruneIntervalMs: number;
+  private lastPruneAt = 0;
+
+  constructor(opts: { maxSize: number; ttlMs: number; pruneIntervalMs?: number }) {
+    this.maxSize = opts.maxSize;
+    this.ttlMs = opts.ttlMs;
+    this.pruneIntervalMs = opts.pruneIntervalMs ?? Math.max(opts.ttlMs * 2, 60_000);
+  }
+
+  get(key: string): T | undefined {
+    const entry = this.cache.get(key);
+    if (!entry) return undefined;
+    if (entry.expiresAt <= Date.now()) {
+      this.cache.delete(key);
+      return undefined;
+    }
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    return entry.value;
+  }
+
+  set(key: string, value: T): void {
+    this.cache.delete(key);
+    this.cache.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    this.evictIfNeeded();
+    this.maybePrune();
+  }
+
+  invalidate(key: string): void {
+    this.cache.delete(key);
+  }
+
+  private evictIfNeeded(): void {
+    while (this.cache.size > this.maxSize) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== undefined) this.cache.delete(oldest);
+      else break;
+    }
+  }
+
+  private maybePrune(): void {
+    const now = Date.now();
+    if (now - this.lastPruneAt < this.pruneIntervalMs) return;
+    this.lastPruneAt = now;
+    const expired: string[] = [];
+    for (const [key, entry] of this.cache.entries()) {
+      if (entry.expiresAt <= now) expired.push(key);
+    }
+    for (const key of expired) this.cache.delete(key);
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/lib/fetchWithTimeout.ts'), `export interface FetchWithTimeoutOptions extends RequestInit {
+  timeout?: number;
+}
+
+export async function fetchWithTimeout(
+  url: string,
+  options: FetchWithTimeoutOptions = {}
+): Promise<Response> {
+  const { timeout = 60000, ...fetchOptions } = options;
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetch(url, { ...fetchOptions, signal: controller.signal });
+    return response;
+  } catch (error) {
+    if (error instanceof Error && error.name === 'AbortError') {
+      throw new Error(\`Request timeout after \${timeout}ms: \${url}\`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+export async function fetchWithTimeoutAndRetry(
+  url: string,
+  options: FetchWithTimeoutOptions = {},
+  retries = 0
+): Promise<Response> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return await fetchWithTimeout(url, options);
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (attempt < retries) {
+        const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  throw lastError || new Error('Request failed');
+}
+`);
+    writeFile(path.join(dir, 'src/lib/constants.ts'), `export {
+  SUBSCRIPTION_TIERS, SUBSCRIPTION_STATUSES, SUBSCRIPTION_METHODS, SUBSCRIPTION_ORIGINS,
+  type SubscriptionTier, type SubscriptionStatus, type SubscriptionMethod, type SubscriptionOrigin,
+} from '../db/schema.js';
+
+export const TIER_LIMITS = {
+  free: { tier: 'free' as const, dailyLimit: 0 },
+  pro:  { tier: 'pro'  as const, dailyLimit: null },
+} as const;
+
+export const TIER_PRICING = {
+  free: { tier: 'free' as const, priceMonthly: 0,  priceYearly: 0,  currency: 'USD', displayName: 'Free', description: 'Get started for free' },
+  pro:  { tier: 'pro'  as const, priceMonthly: 5,  priceYearly: 54, currency: 'USD', displayName: 'Pro',  description: 'Unlimited access' },
+} as const;
+
+export const CACHE_SECONDS = {
+  SUBSCRIPTIONS_PRICING: 60,
+} as const;
+`);
+    writeFile(path.join(dir, 'src/lib/revenuecat.ts'), `import { createHmac } from 'node:crypto';
+import { fetchWithTimeout } from './fetchWithTimeout.js';
+import { LRUCache } from './lruCache.js';
+
+export interface RevenueCatEntitlement {
+  pro: boolean;
+  expiresAt?: string;
+  purchaseDate?: string;
+  managementUrl?: string;
+  cancelAtPeriodEnd?: boolean;
+}
+
+export interface GrantPromoResult {
+  success: boolean;
+  expiresAt: Date;
+}
+
+const RC_CACHE_TTL_MS = process.env.NODE_ENV === 'production' ? 60_000 : 10_000;
+const rcEntitlementCache = new LRUCache<RevenueCatEntitlement>({ maxSize: 100_000, ttlMs: RC_CACHE_TTL_MS });
+const inflightCached = new Map<string, Promise<RevenueCatEntitlement>>();
+const inflightForced  = new Map<string, Promise<RevenueCatEntitlement>>();
+
+export function invalidateRcEntitlementCache(appUserId: string, entitlementId: string): void {
+  rcEntitlementCache.invalidate(\`\${entitlementId}:\${appUserId}\`);
+}
+
+function addMonthsClamped(date: Date, months: number): Date {
+  const m = Number.isFinite(months) ? months : 0;
+  if (m === 0) return new Date(date.getTime());
+  const yr = date.getFullYear(), mo = date.getMonth(), day = date.getDate();
+  const targetMo = mo + m;
+  const targetYr = yr + Math.floor(targetMo / 12);
+  const finalMo  = ((targetMo % 12) + 12) % 12;
+  const lastDay  = new Date(targetYr, finalMo + 1, 0).getDate();
+  return new Date(targetYr, finalMo, Math.min(day, lastDay), date.getHours(), date.getMinutes(), date.getSeconds(), date.getMilliseconds());
+}
+
+interface RcSubscriberResponse {
+  subscriber?: {
+    entitlements?: Record<string, { expires_date?: string; purchase_date?: string; product_identifier?: string; will_renew?: boolean | null; unsubscribe_detected_at?: string | null }>;
+    subscriptions?: Record<string, { expires_date?: string; management_url?: string; unsubscribe_detected_at?: string | null }>;
+    management_url?: string;
+  };
+}
+
+export async function getRcEntitlement(
+  appUserId: string, entitlementId: string, apiKey: string, opts?: { bypassCache?: boolean }
+): Promise<RevenueCatEntitlement> {
+  const cacheKey = \`\${entitlementId}:\${appUserId}\`;
+  const bypass = opts?.bypassCache === true;
+
+  if (!bypass) {
+    const cached = rcEntitlementCache.get(cacheKey);
+    if (cached) return cached;
+    const inflight = inflightCached.get(cacheKey);
+    if (inflight) return inflight;
+  } else {
+    const inflight = inflightForced.get(cacheKey);
+    if (inflight) return inflight;
+  }
+
+  const map = bypass ? inflightForced : inflightCached;
+  const p = (async (): Promise<RevenueCatEntitlement> => {
+    const res = await fetchWithTimeout(\`https://api.revenuecat.com/v1/subscribers/\${encodeURIComponent(appUserId)}\`, {
+      headers: { Authorization: \`Bearer \${apiKey}\` }, timeout: 60_000,
+    });
+    if (res.status === 404) return { pro: false };
+    if (!res.ok) throw new Error(\`RevenueCat API error: \${res.status}\`);
+
+    const data = (await res.json()) as RcSubscriberResponse;
+    const now  = new Date();
+    const ent  = data.subscriber?.entitlements?.[entitlementId];
+    const entExpires = ent?.expires_date ? new Date(ent.expires_date) : null;
+    const entActive  = entExpires ? entExpires > now : false;
+
+    const subs = data.subscriber?.subscriptions ?? {};
+    let bestSub: { expires_date?: string; management_url?: string; unsubscribe_detected_at?: string | null } | undefined;
+    let bestSubExpires: Date | null = null;
+    for (const sub of Object.values(subs)) {
+      const d = sub?.expires_date ? new Date(sub.expires_date) : null;
+      if (!d || !Number.isFinite(d.getTime())) continue;
+      if (!bestSubExpires || d > bestSubExpires) { bestSubExpires = d; bestSub = sub; }
+    }
+
+    const pro = entActive || (bestSubExpires ? bestSubExpires > now : false);
+    const productId = ent?.product_identifier;
+    const entSub    = productId ? data.subscriber?.subscriptions?.[productId] : undefined;
+    const managementUrl = entSub?.management_url || bestSub?.management_url || data.subscriber?.management_url;
+    const cancelAtPeriodEnd = ent?.will_renew === false || ent?.unsubscribe_detected_at != null
+      || (entSub?.unsubscribe_detected_at ?? bestSub?.unsubscribe_detected_at) != null;
+
+    const entMs = entExpires?.getTime() ?? 0;
+    const subMs = bestSubExpires?.getTime() ?? 0;
+    const bestMs = Math.max(entMs, subMs);
+    const expiresAt = bestMs ? new Date(bestMs).toISOString() : undefined;
+
+    return { pro, expiresAt, purchaseDate: ent?.purchase_date, managementUrl, cancelAtPeriodEnd };
+  })();
+
+  map.set(cacheKey, p);
+  try {
+    const value = await p;
+    if (!bypass && value.pro) rcEntitlementCache.set(cacheKey, value);
+    return value;
+  } finally {
+    map.delete(cacheKey);
+  }
+}
+
+export function verifyRevenueCatWebhook(payload: string, signature: string | undefined, secret: string): boolean {
+  if (!signature) return false;
+  try {
+    const parts = signature.split('=');
+    if (parts.length !== 2 || parts[0] !== 'v1' || !parts[1]) return false;
+    const hmac = createHmac('sha256', secret);
+    hmac.update(payload);
+    const computed = hmac.digest('hex');
+    const a = Buffer.from(computed, 'hex');
+    const b = Buffer.from(parts[1], 'hex');
+    if (a.length !== b.length) return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++) result |= (a[i] ?? 0) ^ (b[i] ?? 0);
+    return result === 0;
+  } catch { return false; }
+}
+
+export function verifyRevenueCatWebhookAuthorization(authHeader: string | undefined, secret: string): boolean {
+  if (!authHeader) return false;
+  const normalize = (v: string) => v.trim().replace(/^bearer\\s+/i, '');
+  return normalize(authHeader) === normalize(secret);
+}
+
+export async function grantPromotionalEntitlement(
+  appUserId: string, entitlementId: string, months: number, apiKey: string
+): Promise<GrantPromoResult> {
+  const safeMonths = Number.isFinite(months) && months > 0 ? months : 1;
+  const startsAt  = new Date();
+  const expiresAt = addMonthsClamped(startsAt, safeMonths);
+  const url = \`https://api.revenuecat.com/v1/subscribers/\${encodeURIComponent(appUserId)}/entitlements/\${encodeURIComponent(entitlementId)}/promotional\`;
+  const res = await fetchWithTimeout(url, {
+    method: 'POST',
+    headers: { Accept: 'application/json', 'Content-Type': 'application/json', Authorization: \`Bearer \${apiKey}\` },
+    body: JSON.stringify({ duration: \`\${safeMonths}m\`, end_time_ms: expiresAt.getTime() }),
+    timeout: 60_000,
+  });
+  if (!res.ok) throw new Error(\`RevenueCat promo grant failed: \${res.status} \${await res.text()}\`);
+  return { success: true, expiresAt };
+}
+`);
+    writeFile(path.join(dir, 'src/lib/r2.ts'), `import { GetObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+
+type UploadAvatarInput = {
+  objectKey: string;
+  body: Buffer;
+  contentType: string;
+};
+
+function hasR2Config() {
+  return Boolean(
+    process.env.R2_ACCOUNT_ID
+    && process.env.R2_ACCESS_KEY_ID
+    && process.env.R2_SECRET_ACCESS_KEY
+    && process.env.R2_BUCKET
+  );
+}
+
+function getR2Client() {
+  if (!hasR2Config()) {
+    throw new Error('R2 is not configured');
+  }
+
+  return new S3Client({
+    region: 'auto',
+    endpoint: \`https://\${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com\`,
+    credentials: {
+      accessKeyId: process.env.R2_ACCESS_KEY_ID ?? '',
+      secretAccessKey: process.env.R2_SECRET_ACCESS_KEY ?? '',
+    },
+  });
+}
+
+function getBucket() {
+  if (!process.env.R2_BUCKET) {
+    throw new Error('R2_BUCKET is not configured');
+  }
+
+  return process.env.R2_BUCKET;
+}
+
+export function isR2Configured() {
+  return hasR2Config();
+}
+
+export async function uploadAvatarToR2(input: UploadAvatarInput) {
+  const client = getR2Client();
+  const bucket = getBucket();
+
+  await client.send(new PutObjectCommand({
+    Bucket: bucket,
+    Key: input.objectKey,
+    Body: input.body,
+    ContentType: input.contentType,
+  }));
+
+  return {
+    bucket,
+    objectKey: input.objectKey,
+  };
+}
+
+export async function createSignedAvatarUrl(objectKey: string) {
+  const client = getR2Client();
+  return getSignedUrl(client, new GetObjectCommand({
+    Bucket: getBucket(),
+    Key: objectKey,
+  }), { expiresIn: 60 * 10 });
+}
+`);
+    writeFile(path.join(dir, 'src/services/SubscriptionService.ts'), `import type { FastifyInstance, FastifyRequest } from 'fastify';
+import { getRcEntitlement, invalidateRcEntitlementCache } from '../lib/revenuecat.js';
+import { TIER_PRICING, TIER_LIMITS } from '../lib/constants.js';
+import type { Subscriptions, SubscriptionEventType } from '../db/schema.js';
+import type { RecordEventParams } from '../repositories/index.js';
+import { runBackgroundTask } from '../lib/routeHelpers.js';
+
+export interface EntitlementWithTrial {
+  tier: 'free' | 'pro';
+  pro: boolean;
+  inTrial: boolean;
+  trialEndsAt?: string;
+  expiresAt?: string;
+  periodStart?: string;
+  periodEnd?: string;
+  method?: 'trialing' | 'redeemed' | 'paid' | null;
+  managementUrl?: string;
+  cancelAtPeriodEnd?: boolean;
+}
+
+export class SubscriptionService {
+  constructor(private fastify: FastifyInstance) {}
+
+  private async recordEvent(req: FastifyRequest | undefined, params: RecordEventParams, label: string): Promise<void> {
+    const task = this.fastify.repos.subscriptionEvents.recordEvent(params);
+    if (req) { runBackgroundTask(req, task, label); return; }
+    await task;
+  }
+
+  async getPricing() {
+    return {
+      tiers: [
+        { tier: TIER_PRICING.free.tier, displayName: TIER_PRICING.free.displayName, description: TIER_PRICING.free.description, priceMonthly: TIER_PRICING.free.priceMonthly, priceYearly: TIER_PRICING.free.priceYearly, currency: TIER_PRICING.free.currency, limits: { dailyLimit: TIER_LIMITS.free.dailyLimit } },
+        { tier: TIER_PRICING.pro.tier,  displayName: TIER_PRICING.pro.displayName,  description: TIER_PRICING.pro.description,  priceMonthly: TIER_PRICING.pro.priceMonthly,  priceYearly: TIER_PRICING.pro.priceYearly,  currency: TIER_PRICING.pro.currency,  limits: { dailyLimit: TIER_LIMITS.pro.dailyLimit }, paymentInfo: { revenueCatEntitlementId: this.fastify.env.RC_ENTITLEMENT_ID, revenueCatOfferingId: this.fastify.env.RC_OFFERING_ID } },
+      ],
+    };
+  }
+
+  private async getEntitlement(appUserId: string, opts?: { bypassCache?: boolean }) {
+    const key = this.fastify.env.RC_SECRET_API_KEY;
+    if (!key) throw new Error('RevenueCat not configured');
+    return getRcEntitlement(appUserId, this.fastify.env.RC_ENTITLEMENT_ID || 'pro', key, { bypassCache: opts?.bypassCache });
+  }
+
+  async getEntitlementWithTrial(appUserId: string, opts?: { refreshRevenueCat?: boolean }, req?: FastifyRequest): Promise<EntitlementWithTrial> {
+    const forceRefresh = opts?.refreshRevenueCat === true;
+    let subscription = await this.fastify.repos.subscriptions.findByUserId(appUserId);
+    if (!subscription) {
+      try { subscription = await this.fastify.repos.subscriptions.getOrCreate(appUserId, { allowTrial: true }); } catch {}
+    }
+
+    const now = new Date();
+    const hasRC = Boolean(this.fastify.env.RC_SECRET_API_KEY);
+    const periodEndMs = subscription?.currentPeriodEnd?.getTime();
+    const nearPeriodEnd = typeof periodEndMs === 'number' && periodEndMs - now.getTime() <= 12 * 60 * 60 * 1000;
+    const isPaidOrRedeemed = subscription?.method === 'paid' || subscription?.method === 'redeemed';
+
+    const shouldSyncRC = hasRC && (forceRefresh || !subscription || subscription.status !== 'active' || subscription.method === 'trialing' || nearPeriodEnd);
+
+    let rcEnt: Awaited<ReturnType<SubscriptionService['getEntitlement']>> | null = null;
+    let rcFailed = false;
+    if (shouldSyncRC) {
+      try { rcEnt = await this.getEntitlement(appUserId, { bypassCache: forceRefresh }); }
+      catch { rcFailed = true; }
+    }
+
+    // RC says pro → trust it, sync DB
+    if (rcEnt?.pro) {
+      const rcEnd   = rcEnt.expiresAt   ? new Date(rcEnt.expiresAt)   : null;
+      const rcStart = rcEnt.purchaseDate ? new Date(rcEnt.purchaseDate) : null;
+      const method: 'paid' | 'redeemed' = subscription?.method === 'redeemed' ? 'redeemed' : 'paid';
+      const cancelAtPeriodEnd = rcEnt.cancelAtPeriodEnd ?? subscription?.cancelAtPeriodEnd ?? false;
+      const needsUpdate = subscription?.method !== method || subscription?.status !== 'active' || subscription?.tier !== 'pro'
+        || (rcEnd && subscription?.currentPeriodEnd?.getTime() !== rcEnd.getTime())
+        || (subscription?.cancelAtPeriodEnd ?? false) !== cancelAtPeriodEnd;
+
+      if (needsUpdate) {
+        const wasNotPaid = subscription?.method !== method || subscription?.status !== 'active';
+        await this.fastify.repos.subscriptions.upsert(appUserId, {
+          tier: 'pro', status: 'active', method, cancelAtPeriodEnd, trialStart: null, trialEnd: null,
+          ...(rcStart ? { currentPeriodStart: rcStart } : {}),
+          ...(rcEnd   ? { currentPeriodEnd:   rcEnd   } : {}),
+        });
+        if (wasNotPaid) {
+          const eventType: SubscriptionEventType = subscription?.method === 'trialing' ? 'trial_converted' : 'initial_purchase';
+          await this.recordEvent(req, { userId: appUserId, subscriptionId: subscription?.id, eventType, previousState: { tier: subscription?.tier, status: subscription?.status, method: subscription?.method }, newState: { tier: 'pro', status: 'active', method }, periodStart: rcStart, periodEnd: rcEnd }, eventType);
+        }
+      }
+      return { tier: 'pro', pro: true, inTrial: false, expiresAt: rcEnt.expiresAt, periodStart: rcStart?.toISOString() ?? subscription?.currentPeriodStart?.toISOString(), periodEnd: rcEnt.expiresAt ?? subscription?.currentPeriodEnd?.toISOString(), method, managementUrl: rcEnt.managementUrl, cancelAtPeriodEnd };
+    }
+
+    // Expire paid if RC confirmed not-pro on forced refresh
+    if (forceRefresh && !rcFailed && rcEnt && !rcEnt.pro && subscription?.tier === 'pro' && subscription.status === 'active' && isPaidOrRedeemed) {
+      await this.expirePaidSubscription(appUserId, rcEnt.expiresAt, req);
+      subscription = await this.fastify.repos.subscriptions.findByUserId(appUserId);
+    }
+
+    // Trial handling
+    if (subscription?.method === 'trialing' && subscription.trialEnd) {
+      if (subscription.trialEnd > now) {
+        return { tier: 'pro', pro: true, inTrial: true, trialEndsAt: subscription.trialEnd.toISOString(), periodStart: subscription.trialStart?.toISOString(), periodEnd: subscription.trialEnd.toISOString(), method: 'trialing', cancelAtPeriodEnd: false };
+      }
+      if (subscription.status !== 'expired') {
+        await this.expireTrial(appUserId, req);
+        subscription = await this.fastify.repos.subscriptions.findByUserId(appUserId);
+      }
+    }
+
+    // DB says active pro
+    if (subscription?.tier === 'pro' && subscription.status === 'active') {
+      return { tier: 'pro', pro: true, inTrial: false, expiresAt: subscription.currentPeriodEnd?.toISOString(), periodStart: subscription.currentPeriodStart?.toISOString(), periodEnd: subscription.currentPeriodEnd?.toISOString(), method: subscription.method, cancelAtPeriodEnd: subscription.cancelAtPeriodEnd };
+    }
+
+    return { tier: 'free', pro: false, inTrial: false, periodStart: subscription?.currentPeriodStart?.toISOString() ?? subscription?.trialStart?.toISOString(), periodEnd: subscription?.currentPeriodEnd?.toISOString() ?? subscription?.trialEnd?.toISOString(), method: subscription?.method, cancelAtPeriodEnd: false };
+  }
+
+  async expireTrial(appUserId: string, req?: FastifyRequest): Promise<void> {
+    const sub = await this.fastify.repos.subscriptions.findByUserId(appUserId);
+    await this.fastify.repos.subscriptions.updateByUserId(appUserId, { tier: 'free', status: 'expired' });
+    await this.recordEvent(req, { userId: appUserId, subscriptionId: sub?.id, eventType: 'trial_expired', previousState: { tier: sub?.tier, status: sub?.status, method: sub?.method }, newState: { tier: 'free', status: 'expired', method: sub?.method }, periodStart: sub?.trialStart, periodEnd: sub?.trialEnd }, 'trial_expired');
+  }
+
+  async expirePaidSubscription(appUserId: string, expiresAt?: string, req?: FastifyRequest): Promise<void> {
+    const sub = await this.fastify.repos.subscriptions.findByUserId(appUserId);
+    const expiresDate = expiresAt ? new Date(expiresAt) : sub?.currentPeriodEnd ?? null;
+    await this.fastify.repos.subscriptions.updateByUserId(appUserId, { tier: 'free', status: 'expired', cancelAtPeriodEnd: false, ...(expiresDate ? { currentPeriodEnd: expiresDate } : {}) });
+    await this.recordEvent(req, { userId: appUserId, subscriptionId: sub?.id, eventType: 'subscription_expired', previousState: { tier: sub?.tier, status: sub?.status, method: sub?.method }, newState: { tier: 'free', status: 'expired', method: sub?.method }, periodStart: sub?.currentPeriodStart, periodEnd: expiresDate }, 'subscription_expired');
+  }
+
+  async handleRevenueCatWebhook(event: Record<string, unknown>, req?: FastifyRequest): Promise<void> {
+    const appUserId = event.app_user_id as string | undefined;
+    if (!appUserId) return;
+
+    const rcEventType   = event.type as string | undefined;
+    const entitlementId = this.fastify.env.RC_ENTITLEMENT_ID || 'pro';
+    const entIds        = event.entitlement_ids as unknown;
+    const entIdSingle   = event.entitlement_id as string | null | undefined;
+    const hasEnt = Array.isArray(entIds) ? entIds.some(x => x === entitlementId) : entIdSingle === entitlementId;
+
+    const expirationMs = event.expiration_at_ms as number | undefined;
+    const expiresAt    = typeof expirationMs === 'number' ? new Date(expirationMs) : null;
+    if (expiresAt && isNaN(expiresAt.getTime())) return;
+
+    const now      = new Date();
+    const isActive = hasEnt && (expiresAt ? expiresAt > now : false);
+    const tier     = isActive ? 'pro' : 'free';
+    const status   = isActive ? 'active' : 'expired';
+    const method   = isActive ? 'paid' : null;
+
+    const purchasedMs  = event.purchased_at_ms as number | undefined;
+    const periodStart  = typeof purchasedMs === 'number' ? new Date(purchasedMs) : null;
+    const validStart   = periodStart && !isNaN(periodStart.getTime()) ? periodStart : null;
+    const storeRaw     = event.store as string | undefined;
+    const storeNorm    = storeRaw?.toLowerCase();
+    const willRenew    = event.will_renew as boolean | undefined;
+    const cancelReason = event.cancel_reason as string | undefined;
+    const price        = event.price as number | undefined;
+    const currency     = event.currency as string | undefined;
+    const transactionId = event.transaction_id as string | undefined;
+    const productId    = event.product_id as string | undefined;
+    const origin       = storeNorm === 'app_store' ? 'apple' : storeNorm === 'play_store' ? 'google' : (storeNorm === 'stripe' || storeNorm === 'rc_billing') ? 'web' : undefined;
+
+    const currentSub = await this.fastify.repos.subscriptions.findByUserId(appUserId);
+    await this.fastify.repos.subscriptions.upsert(appUserId, {
+      tier: tier as 'free' | 'pro', status: status as 'active' | 'expired', method,
+      origin: origin as 'web' | 'apple' | 'google' | undefined,
+      currentPeriodStart: validStart, currentPeriodEnd: expiresAt,
+      billingPeriod: (event.period_type as string | undefined) ?? null,
+      canceledAt: (rcEventType === 'CANCELLATION' || rcEventType === 'EXPIRATION') ? new Date() : null,
+      cancelAtPeriodEnd: willRenew === false && isActive,
+      trialStart: null, trialEnd: null,
+      metadata: { ...(productId ? { revenueCatProductId: productId } : {}), ...(cancelReason ? { cancelReason } : {}), lastWebhookUpdate: new Date().toISOString() },
+    });
+
+    invalidateRcEntitlementCache(appUserId, entitlementId);
+
+    const eventMap: Record<string, string> = {
+      INITIAL_PURCHASE: 'initial_purchase', RENEWAL: 'renewal', PRODUCT_CHANGE: 'product_change',
+      CANCELLATION: 'cancellation_scheduled', UNCANCELLATION: 'cancellation_unscheduled',
+      EXPIRATION: 'subscription_expired', BILLING_ISSUE: 'billing_issue', BILLING_ISSUE_RESOLVED: 'billing_recovered',
+    };
+    const mappedType = rcEventType ? (eventMap[rcEventType] ?? (!isActive ? 'subscription_expired' : 'renewal')) : null;
+    if (mappedType) {
+      await this.recordEvent(req, {
+        userId: appUserId, subscriptionId: currentSub?.id, eventType: mappedType as SubscriptionEventType,
+        previousState: { tier: currentSub?.tier, status: currentSub?.status, method: currentSub?.method },
+        newState: { tier: tier as 'free' | 'pro', status: status as 'active' | 'expired', method },
+        revenueCatEventType: rcEventType, revenueCatProductId: productId,
+        origin: origin as 'web' | 'apple' | 'google' | undefined,
+        periodStart: validStart, periodEnd: expiresAt,
+        metadata: { ...(rcEventType ? { revenueCatEventType: rcEventType } : {}), ...(productId ? { revenueCatProductId: productId } : {}), ...(storeRaw ? { store: storeRaw } : {}), ...(transactionId ? { transactionId } : {}), ...(price !== undefined && currency ? { price: { amount: price, currency } } : {}) },
+      }, 'revenuecat_event');
+    }
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/lib/requestUtils.ts'), `import type { FastifyRequest } from 'fastify';
+
+export function extractDeviceType(userAgent: string | null | undefined): string | null {
+  if (!userAgent) return null;
+  const ua = userAgent.toLowerCase();
+  if (ua.includes('mobile') || ua.includes('android') || ua.includes('iphone')) return 'mobile';
+  if (ua.includes('tablet') || ua.includes('ipad')) return 'tablet';
+  if (ua.includes('chrome-extension') || ua.includes('firefox-extension')) return 'extension';
+  return 'desktop';
+}
+
+export function extractIpAddress(req: FastifyRequest): string | null {
+  const realIp = req.headers['x-real-ip'] as string | undefined;
+  if (realIp) return realIp;
+  const forwardedFor = req.headers['x-forwarded-for'] as string | undefined;
+  if (forwardedFor) {
+    const firstIp = forwardedFor.split(',')[0]?.trim();
+    if (firstIp) return firstIp;
+  }
+  return req.ip || null;
+}
+
+export function extractDeviceInfo(req: FastifyRequest) {
+  const userAgent = req.headers['user-agent'] || null;
+  const deviceType = extractDeviceType(userAgent);
+  const rawIp = extractIpAddress(req);
+  const ipAddress = anonymizeIp(rawIp);
+  return { deviceType, userAgent, ipAddress };
+}
+
+export function sanitizeEmail(email: unknown): string {
+  return String(email || '').toLowerCase().trim();
+}
+
+export function maskEmail(email: string): string {
+  if (!email || !email.includes('@')) return '***';
+  const [local, domain] = email.split('@');
+  if (!local || !domain) return '***';
+  const maskedLocal = local.length > 0 ? \`\${local[0]}***\` : '***';
+  return \`\${maskedLocal}@\${domain}\`;
+}
+
+export function anonymizeIp(ip: string | null): string | null {
+  if (!ip) return null;
+  if (ip.includes('.') && !ip.includes(':')) {
+    const parts = ip.split('.');
+    if (parts.length === 4) { parts[3] = '0'; return parts.join('.'); }
+  }
+  if (ip.includes(':')) {
+    const parts = ip.split(':');
+    if (parts.length >= 3) return \`\${parts.slice(0, 3).join(':')}::\`;
+  }
+  return ip;
+}
+`);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Plugins
+// ═══════════════════════════════════════════════════════════════════════════
+function writePlugins(dir) {
+    writeFile(path.join(dir, 'src/plugins/env.ts'), `import type { FastifyInstance, FastifyPluginAsync } from 'fastify';
+import fastifyEnv from '@fastify/env';
+import fp from 'fastify-plugin';
+
+const configPlugin: FastifyPluginAsync = async (fastify: FastifyInstance) => {
+  const schema = {
+    type: 'object',
+    required: ['PORT', 'DATABASE_URL'],
+    properties: {
+      PORT: { type: 'number' },
+      NODE_ENV: { type: 'string', default: 'development' },
+      LOG_LEVEL: { type: 'string', default: 'info' },
+      CLERK_PUBLISHABLE_KEY: { type: 'string', nullable: true },
+      CLERK_SECRET_KEY: { type: 'string', nullable: true },
+      FRONTEND_URL: { type: 'string', nullable: true },
+      EXTENSION_ORIGINS: { type: 'string', nullable: true },
+      DATABASE_URL: { type: 'string' },
+      R2_ACCOUNT_ID: { type: 'string', nullable: true },
+      R2_ACCESS_KEY_ID: { type: 'string', nullable: true },
+      R2_SECRET_ACCESS_KEY: { type: 'string', nullable: true },
+      R2_BUCKET: { type: 'string', nullable: true },
+      RC_SECRET_API_KEY: { type: 'string', default: '' },
+      RC_WEBHOOK_SECRET: { type: 'string', default: '' },
+      RC_ENTITLEMENT_ID: { type: 'string', default: 'pro' },
+      RC_OFFERING_ID: { type: 'string', default: 'default' },
+    },
+  } as const;
+
+  await fastify.register(fastifyEnv as unknown as FastifyPluginAsync, {
+    schema,
+    dotenv: !process.env.VERCEL,
+    confKey: 'env',
+  } as unknown as Record<string, unknown>);
+};
+
+export default fp(configPlugin, { name: 'env-config', fastify: '5.x' });
+`);
+    writeFile(path.join(dir, 'src/plugins/clerkAuth.ts'), `import type { FastifyInstance, FastifyPluginAsync, FastifyRequest, FastifyReply } from 'fastify';
+import fp from 'fastify-plugin';
+import { clerkPlugin, getAuth, clerkClient } from '@clerk/fastify';
+import { AuthError } from '../errors/index.js';
+import { runBackgroundTask } from '../lib/routeHelpers.js';
+import type { AppUser } from '../types/index.js';
+import crypto from 'node:crypto';
+import { LRUCache } from '../lib/lruCache.js';
+
+export const clerkAuthPlugin: FastifyPluginAsync = async (fastify: FastifyInstance) => {
+  await fastify.register(clerkPlugin);
+
+  const trackedSessions = new LRUCache<number>({ maxSize: 50_000, ttlMs: 24 * 60 * 60 * 1000 });
+
+  type ClerkUser = Awaited<ReturnType<(typeof clerkClient.users)['getUser']>>;
+  const CLERK_USER_CACHE = new LRUCache<ClerkUser>({
+    maxSize: 50_000,
+    ttlMs: fastify.env?.NODE_ENV === 'production' ? 300_000 : 60_000,
+  });
+  const INFLIGHT_CLERK_USER = new Map<string, Promise<ClerkUser>>();
+
+  const getClerkUser = async (userId: string): Promise<ClerkUser> => {
+    const cached = CLERK_USER_CACHE.get(userId);
+    if (cached) return cached;
+    const existing = INFLIGHT_CLERK_USER.get(userId);
+    if (existing) return existing;
+    const p = (async () => {
+      try {
+        const user = await clerkClient.users.getUser(userId);
+        CLERK_USER_CACHE.set(userId, user);
+        return user;
+      } finally {
+        INFLIGHT_CLERK_USER.delete(userId);
+      }
+    })();
+    INFLIGHT_CLERK_USER.set(userId, p);
+    return p;
+  };
+
+  fastify.addHook('onRequest', async (req) => { req._startedAt = Date.now(); });
+
+  const authenticate = async (req: FastifyRequest, _reply: FastifyReply) => {
+    if (req.method === 'OPTIONS' || req.url.startsWith('/health')) return;
+
+    const authHeader = req.headers.authorization;
+    if (!authHeader?.startsWith('Bearer ')) throw AuthError.unauthorized();
+
+    const jwtToken = authHeader.slice('Bearer '.length).trim();
+    if (!jwtToken) throw AuthError.unauthorized();
+
+    try {
+      const auth = getAuth(req);
+      if (!auth.userId) throw AuthError.unauthorized();
+
+      const userId = auth.userId as string;
+      const clerkUser = await getClerkUser(userId);
+      if (!clerkUser) throw AuthError.unauthorized();
+
+      let userData = await fastify.repos.users.getAuthDataForPlugin(userId);
+
+      if (!userData) {
+        const primaryEmail = clerkUser.emailAddresses.find(
+          (e: { id: string }) => e.id === clerkUser.primaryEmailAddressId
+        );
+        const displayName = [clerkUser.firstName, clerkUser.lastName]
+          .filter(Boolean).join(' ').trim() || (primaryEmail?.emailAddress?.split('@')[0] ?? '');
+
+        await fastify.repos.users.createIfMissing({
+          id: userId,
+          email: primaryEmail?.emailAddress || '',
+          displayName,
+          profileImageUrl: clerkUser.imageUrl || null,
+        });
+
+        await fastify.repos.subscriptions.createIfMissing({
+          id: crypto.randomUUID(),
+          userId,
+          tier: 'free',
+          status: 'active',
+        });
+
+        userData = await fastify.repos.users.getAuthDataForPlugin(userId);
+      } else {
+        const sessionKey = auth.sessionId ?? userId;
+        if (trackedSessions.get(sessionKey) === undefined) {
+          trackedSessions.set(sessionKey, Date.now());
+          runBackgroundTask(req, fastify.repos.users.updateLastLogin(userId), 'session_sync');
+        }
+      }
+
+      if (!userData) throw AuthError.unauthorized();
+
+      const userObj: AppUser = { id: userId };
+      if (userData.subscriptionTier) userObj.subscriptionTier = userData.subscriptionTier;
+      if (userData.subscriptionStatus) userObj.subscriptionStatus = userData.subscriptionStatus;
+      req.user = userObj;
+    } catch (err) {
+      if (err instanceof AuthError) throw err;
+      req.log.error({ msg: '[clerk-auth:error]', error: (err as Error).message });
+      throw err;
+    }
+  };
+
+  fastify.decorate('authenticate', authenticate);
+};
+
+export default fp(clerkAuthPlugin, { name: 'clerk-auth-plugin', fastify: '5.x' });
+`);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Config
+// ═══════════════════════════════════════════════════════════════════════════
+function writeConfig(dir) {
+    writeFile(path.join(dir, 'src/config/index.ts'), `import type { AppEnv } from '../types/index.js';
+import { ServerConfig } from './server.js';
+import { DatabaseConfig } from './database.js';
+import { CorsConfig } from './cors.js';
+
+export class AppConfig {
+  readonly server: ServerConfig;
+  readonly database: DatabaseConfig;
+  readonly cors: CorsConfig;
+
+  constructor(env: AppEnv) {
+    this.server = new ServerConfig(env);
+    this.database = new DatabaseConfig(env);
+    this.cors = new CorsConfig(env);
+  }
+
+  static fromEnv(env: AppEnv): AppConfig {
+    return new AppConfig(env);
+  }
+}
+
+export { ServerConfig } from './server.js';
+export { DatabaseConfig } from './database.js';
+export { CorsConfig } from './cors.js';
+`);
+    writeFile(path.join(dir, 'src/config/server.ts'), `import type { AppEnv } from '../types/index.js';
+
+export class ServerConfig {
+  readonly port: number;
+  readonly host: string;
+  readonly nodeEnv: string;
+  readonly isDevelopment: boolean;
+  readonly isProduction: boolean;
+
+  constructor(env: AppEnv) {
+    this.port = env.PORT;
+    this.host = '0.0.0.0';
+    this.nodeEnv = env.NODE_ENV;
+    this.isDevelopment = env.NODE_ENV === 'development';
+    this.isProduction = env.NODE_ENV === 'production';
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/config/database.ts'), `import type { AppEnv } from '../types/index.js';
+
+export class DatabaseConfig {
+  readonly url: string;
+
+  constructor(env: AppEnv) {
+    if (!env.DATABASE_URL) throw new Error('DATABASE_URL is required');
+    this.url = env.DATABASE_URL;
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/config/cors.ts'), `import type { AppEnv } from '../types/index.js';
+
+export class CorsConfig {
+  readonly frontendUrl?: string;
+  readonly extensionOrigins: string[];
+  readonly restrictedOrigins: string[];
+
+  constructor(env: AppEnv) {
+    if (env.FRONTEND_URL) this.frontendUrl = env.FRONTEND_URL;
+    this.extensionOrigins = String(env.EXTENSION_ORIGINS || '')
+      .split(',').map(o => o.trim()).filter(o => o.length > 0);
+    this.restrictedOrigins = [
+      ...new Set([
+        ...(this.frontendUrl ? [this.frontendUrl] : []),
+        ...this.extensionOrigins,
+      ]),
+    ];
+  }
+
+  getRestrictedOrigins(): string[] | false {
+    return this.restrictedOrigins.length > 0 ? this.restrictedOrigins : false;
+  }
+}
+`);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Repositories
+// ═══════════════════════════════════════════════════════════════════════════
+function writeRepositories(dir) {
+    writeFile(path.join(dir, 'src/repositories/UserRepository.ts'), `import { eq } from 'drizzle-orm';
+import type { Database } from '../db/index.js';
+import { users } from '../db/schema.js';
+import type { NewUsers, SubscriptionStatus, SubscriptionTier } from '../db/schema.js';
+import { LRUCache } from '../lib/lruCache.js';
+import { subscriptions } from '../db/schema.js';
+
+export type UserAuthData = {
+  id: string;
+  email: string;
+  subscriptionTier?: SubscriptionTier | null;
+  subscriptionStatus?: SubscriptionStatus | null;
+};
+
+const authPluginCache = new LRUCache<UserAuthData>({
+  maxSize: 50_000,
+  ttlMs: 60_000,
+});
+
+export function invalidateAuthPluginCache(userId: string): void {
+  authPluginCache.invalidate(\`auth:\${userId}\`);
+}
+
+export class UserRepository {
+  constructor(private db: Database) {}
+
+  async getAuthDataForPlugin(userId: string): Promise<UserAuthData | null> {
+    const cached = authPluginCache.get(\`auth:\${userId}\`);
+    if (cached) return cached;
+
+    const rows = await this.db
+      .select({
+        id: users.id,
+        email: users.email,
+        subscriptionTier: subscriptions.tier,
+        subscriptionStatus: subscriptions.status,
+      })
+      .from(users)
+      .leftJoin(subscriptions, eq(users.id, subscriptions.userId))
+      .where(eq(users.id, userId))
+      .limit(1);
+
+    const row = rows[0] ?? null;
+    if (row) authPluginCache.set(\`auth:\${userId}\`, row);
+    return row;
+  }
+
+  async findById(userId: string) {
+    const rows = await this.db.select().from(users).where(eq(users.id, userId)).limit(1);
+    return rows[0] ?? null;
+  }
+
+  async findByEmail(email: string) {
+    const rows = await this.db.select().from(users).where(eq(users.email, email)).limit(1);
+    return rows[0] ?? null;
+  }
+
+  async createIfMissing(data: NewUsers): Promise<{ created: boolean }> {
+    const existing = await this.findById(data.id);
+    if (existing) return { created: false };
+    await this.db.insert(users).values(data).onConflictDoNothing();
+    return { created: true };
+  }
+
+  async updateAvatar(userId: string, input: {
+    avatarObjectKey: string;
+    avatarMimeType: string;
+  }): Promise<void> {
+    await this.db.update(users).set({
+      avatarObjectKey: input.avatarObjectKey,
+      avatarMimeType: input.avatarMimeType,
+    }).where(eq(users.id, userId));
+    authPluginCache.invalidate(\`auth:\${userId}\`);
+  }
+
+  async getDashboardProfile(userId: string) {
+    const rows = await this.db
+      .select({
+        id: users.id,
+        email: users.email,
+        displayName: users.displayName,
+        profileImageUrl: users.profileImageUrl,
+        avatarObjectKey: users.avatarObjectKey,
+        avatarMimeType: users.avatarMimeType,
+        creditsBalance: users.creditsBalance,
+        subscriptionTier: subscriptions.tier,
+        subscriptionStatus: subscriptions.status,
+      })
+      .from(users)
+      .leftJoin(subscriptions, eq(users.id, subscriptions.userId))
+      .where(eq(users.id, userId))
+      .limit(1);
+
+    return rows[0] ?? null;
+  }
+
+  async updateLastLogin(userId: string): Promise<void> {
+    await this.db.update(users).set({ lastLoginAt: new Date() }).where(eq(users.id, userId));
+    authPluginCache.invalidate(\`auth:\${userId}\`);
+  }
+
+  async deleteById(userId: string): Promise<void> {
+    await this.db.delete(users).where(eq(users.id, userId));
+    authPluginCache.invalidate(\`auth:\${userId}\`);
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/repositories/SubscriptionRepository.ts'), `import crypto from 'node:crypto';
+import { eq } from 'drizzle-orm';
+import type { Database } from '../db/index.js';
+import { subscriptions } from '../db/schema.js';
+import type { Subscriptions, NewSubscriptions } from '../db/schema.js';
+import { LRUCache } from '../lib/lruCache.js';
+import { invalidateAuthPluginCache } from './UserRepository.js';
+
+const subscriptionCache = new LRUCache<Subscriptions>({ maxSize: 50_000, ttlMs: 30_000 });
+
+export class SubscriptionRepository {
+  constructor(private db: Database) {}
+
+  async findByUserId(userId: string): Promise<Subscriptions | null> {
+    const cached = subscriptionCache.get(\`sub:\${userId}\`);
+    if (cached !== undefined) return cached;
+    const [row] = await this.db.select().from(subscriptions)
+      .where(eq(subscriptions.userId, userId)).limit(1);
+    const result = row || null;
+    if (result) subscriptionCache.set(\`sub:\${userId}\`, result);
+    return result;
+  }
+
+  async createIfMissing(data: NewSubscriptions): Promise<{ subscription: Subscriptions; created: boolean }> {
+    try {
+      const [inserted] = await this.db.insert(subscriptions).values(data)
+        .onConflictDoNothing({ target: subscriptions.userId }).returning();
+      if (inserted) {
+        subscriptionCache.set(\`sub:\${inserted.userId}\`, inserted);
+        return { subscription: inserted, created: true };
+      }
+    } catch {}
+    const existing = await this.findByUserId(data.userId);
+    if (existing) return { subscription: existing, created: false };
+    throw new Error(\`Failed to create subscription for user \${data.userId}\`);
+  }
+
+  async upsert(userId: string, data: Partial<Omit<NewSubscriptions, 'id' | 'userId'>>): Promise<Subscriptions> {
+    const insertData: NewSubscriptions = {
+      id: crypto.randomUUID(), userId,
+      tier: data.tier ?? 'free',
+      status: data.status ?? 'active',
+      method: data.method ?? null,
+      origin: data.origin ?? null,
+      billingPeriod: data.billingPeriod ?? null,
+      currentPeriodStart: data.currentPeriodStart ?? null,
+      currentPeriodEnd: data.currentPeriodEnd ?? null,
+      canceledAt: data.canceledAt ?? null,
+      cancelAtPeriodEnd: data.cancelAtPeriodEnd ?? false,
+      trialStart: data.trialStart ?? null,
+      trialEnd: data.trialEnd ?? null,
+      dailyLimit: data.dailyLimit ?? null,
+      metadata: data.metadata ?? null,
+    };
+    const updateData = Object.fromEntries(
+      Object.entries({ ...data, updatedAt: new Date() }).filter(([, v]) => v !== undefined)
+    ) as Partial<Subscriptions>;
+    const [row] = await this.db.insert(subscriptions).values(insertData)
+      .onConflictDoUpdate({ target: subscriptions.userId, set: updateData }).returning();
+    if (!row) throw new Error(\`Failed to upsert subscription for user \${userId}\`);
+    subscriptionCache.set(\`sub:\${userId}\`, row);
+    invalidateAuthPluginCache(userId);
+    return row;
+  }
+
+  async updateByUserId(userId: string, data: Partial<Subscriptions>): Promise<Subscriptions | null> {
+    const [updated] = await this.db.update(subscriptions)
+      .set({ ...data, updatedAt: new Date() })
+      .where(eq(subscriptions.userId, userId)).returning();
+    if (updated) subscriptionCache.set(\`sub:\${userId}\`, updated);
+    else subscriptionCache.invalidate(\`sub:\${userId}\`);
+    invalidateAuthPluginCache(userId);
+    return updated || null;
+  }
+
+  async getOrCreate(userId: string, options?: { allowTrial?: boolean }): Promise<Subscriptions> {
+    const existing = await this.findByUserId(userId);
+    if (existing) return existing;
+    const allowTrial = options?.allowTrial ?? true;
+    const now = new Date();
+    const trialEnd = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000);
+    const { subscription } = await this.createIfMissing(allowTrial
+      ? { id: crypto.randomUUID(), userId, tier: 'pro', status: 'active', method: 'trialing', trialStart: now, trialEnd }
+      : { id: crypto.randomUUID(), userId, tier: 'free', status: 'active', method: null, trialStart: null, trialEnd: null }
+    );
+    return subscription;
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/repositories/SubscriptionEventRepository.ts'), `import { eq, desc, and, inArray, sql } from 'drizzle-orm';
+import crypto from 'node:crypto';
+import type { Database } from '../db/index.js';
+import {
+  subscriptionEvents,
+  type SubscriptionEvents, type NewSubscriptionEvents,
+  type SubscriptionEventType, type SubscriptionTier, type SubscriptionStatus,
+  type SubscriptionMethod, type SubscriptionOrigin, type SubscriptionEventMetadata,
+} from '../db/schema.js';
+
+export interface RecordEventParams {
+  userId: string;
+  subscriptionId?: string | null;
+  eventType: SubscriptionEventType;
+  previousState?: { tier?: SubscriptionTier | null; status?: SubscriptionStatus | null; method?: SubscriptionMethod | null };
+  newState?: { tier?: SubscriptionTier | null; status?: SubscriptionStatus | null; method?: SubscriptionMethod | null };
+  revenueCatEventType?: string;
+  revenueCatProductId?: string;
+  origin?: SubscriptionOrigin;
+  periodStart?: Date | null;
+  periodEnd?: Date | null;
+  metadata?: SubscriptionEventMetadata;
+}
+
+export class SubscriptionEventRepository {
+  constructor(private db: Database) {}
+
+  async recordEvent(params: RecordEventParams): Promise<SubscriptionEvents> {
+    const data: NewSubscriptionEvents = {
+      id: crypto.randomUUID(),
+      userId: params.userId,
+      subscriptionId: params.subscriptionId ?? null,
+      eventType: params.eventType,
+      previousTier: params.previousState?.tier ?? null,
+      previousStatus: params.previousState?.status ?? null,
+      previousMethod: params.previousState?.method ?? null,
+      newTier: params.newState?.tier ?? null,
+      newStatus: params.newState?.status ?? null,
+      newMethod: params.newState?.method ?? null,
+      revenueCatEventType: params.revenueCatEventType ?? null,
+      revenueCatProductId: params.revenueCatProductId ?? null,
+      origin: params.origin ?? null,
+      periodStart: params.periodStart ?? null,
+      periodEnd: params.periodEnd ?? null,
+      metadata: params.metadata ?? null,
+    };
+    const [event] = await this.db.insert(subscriptionEvents).values(data).returning();
+    return event!;
+  }
+
+  async getEventHistory(userId: string, opts: { limit?: number; offset?: number; eventTypes?: SubscriptionEventType[] } = {}): Promise<SubscriptionEvents[]> {
+    const { limit = 50, offset = 0, eventTypes } = opts;
+    const conditions = [eq(subscriptionEvents.userId, userId)];
+    if (eventTypes?.length) conditions.push(inArray(subscriptionEvents.eventType, eventTypes));
+    return this.db.select().from(subscriptionEvents)
+      .where(and(...conditions))
+      .orderBy(desc(subscriptionEvents.createdAt))
+      .limit(limit).offset(offset);
+  }
+
+  async getEventCountByType(userId: string): Promise<Record<string, number>> {
+    const results = await this.db
+      .select({ eventType: subscriptionEvents.eventType, count: sql<number>\`count(*)::int\` })
+      .from(subscriptionEvents).where(eq(subscriptionEvents.userId, userId))
+      .groupBy(subscriptionEvents.eventType);
+    return results.reduce((acc, r) => { acc[r.eventType] = r.count; return acc; }, {} as Record<string, number>);
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/repositories/PromoCodeRepository.ts'), `import { eq, and, lt, sql } from 'drizzle-orm';
+import crypto from 'node:crypto';
+import type { Database } from '../db/index.js';
+import { promoCodes, promoRedemptions } from '../db/schema.js';
+import type { PromoCodes } from '../db/schema.js';
+
+export interface ValidateCodeResult {
+  valid: boolean;
+  error?: string;
+  promoCode?: PromoCodes;
+}
+
+export class PromoCodeRepository {
+  constructor(private db: Database) {}
+
+  async validateCode(code: string, userId: string): Promise<ValidateCodeResult> {
+    const [promoCode] = await this.db.select().from(promoCodes)
+      .where(eq(promoCodes.code, code.toUpperCase())).limit(1);
+    if (!promoCode) return { valid: false, error: 'invalid_code' };
+
+    const now = new Date();
+    if (promoCode.expiresAt && promoCode.expiresAt < now) return { valid: false, error: 'code_expired' };
+    if (promoCode.redeemedCount >= promoCode.maxRedemptions) return { valid: false, error: 'code_fully_used' };
+
+    const [existing] = await this.db.select().from(promoRedemptions)
+      .where(and(eq(promoRedemptions.promoCodeId, promoCode.id), eq(promoRedemptions.userId, userId))).limit(1);
+    if (existing) return { valid: false, error: 'already_redeemed' };
+
+    return { valid: true, promoCode };
+  }
+
+  async recordRedemption(promoCodeId: string, userId: string, entitlementExpiresAt: Date): Promise<void> {
+    await this.db.insert(promoRedemptions).values({
+      id: crypto.randomUUID(), promoCodeId, userId, entitlementExpiresAt,
+    });
+    await this.db.update(promoCodes)
+      .set({ redeemedCount: sql\`\${promoCodes.redeemedCount} + 1\` })
+      .where(eq(promoCodes.id, promoCodeId));
+  }
+
+  async findExpiredRedemptions(userId: string): Promise<typeof promoRedemptions.$inferSelect[]> {
+    return this.db.select().from(promoRedemptions)
+      .where(and(eq(promoRedemptions.userId, userId), lt(promoRedemptions.entitlementExpiresAt, new Date())));
+  }
+}
+`);
+    writeFile(path.join(dir, 'src/repositories/index.ts'), `import type { Database } from '../db/index.js';
+import { UserRepository } from './UserRepository.js';
+import { SubscriptionRepository } from './SubscriptionRepository.js';
+import { SubscriptionEventRepository } from './SubscriptionEventRepository.js';
+import { PromoCodeRepository } from './PromoCodeRepository.js';
+
+export class Repositories {
+  public readonly users: UserRepository;
+  public readonly subscriptions: SubscriptionRepository;
+  public readonly subscriptionEvents: SubscriptionEventRepository;
+  public readonly promoCodes: PromoCodeRepository;
+
+  constructor(db: Database) {
+    this.users = new UserRepository(db);
+    this.subscriptions = new SubscriptionRepository(db);
+    this.subscriptionEvents = new SubscriptionEventRepository(db);
+    this.promoCodes = new PromoCodeRepository(db);
+  }
+}
+
+export { UserRepository } from './UserRepository.js';
+export { SubscriptionRepository } from './SubscriptionRepository.js';
+export { SubscriptionEventRepository } from './SubscriptionEventRepository.js';
+export { PromoCodeRepository } from './PromoCodeRepository.js';
+export type { UserAuthData } from './UserRepository.js';
+export type { RecordEventParams } from './SubscriptionEventRepository.js';
+`);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Routes
+// ═══════════════════════════════════════════════════════════════════════════
+function writeRoutes(dir, displayName) {
+    writeFile(path.join(dir, 'src/routes/health.ts'), `import type { FastifyInstance, FastifyPluginAsync } from 'fastify';
+
+const healthRoutes: FastifyPluginAsync = async (fastify: FastifyInstance) => {
+  fastify.get('', async (_req, reply) => {
+    return reply.send({
+      ok: true,
+      timestamp: new Date().toISOString(),
+      uptime: process.uptime(),
+    });
+  });
+
+  fastify.get('/ready', async (_req, reply) => {
+    try {
+      await fastify.repos.users.findByEmail('health-check@test.invalid');
+      return reply.send({ ok: true, database: 'connected' });
+    } catch {
+      return reply.status(503).send({ ok: false, error: 'Database connection failed' });
+    }
+  });
+};
+
+export default healthRoutes;
+`);
+    writeFile(path.join(dir, 'src/routes/auth.ts'), `import type { FastifyInstance, FastifyPluginAsync, FastifyRequest, FastifyReply } from 'fastify';
+import { clerkClient } from '@clerk/fastify';
+import { AuthError } from '../errors/index.js';
+import { createAuthHook } from '../lib/routeHelpers.js';
+import { createSignedAvatarUrl, isR2Configured, uploadAvatarToR2 } from '../lib/r2.js';
+
+function getDisplayName(input: {
+  firstName?: string | null;
+  lastName?: string | null;
+  email?: string | null;
+  fallback?: string | null;
+}) {
+  return [input.firstName, input.lastName].filter(Boolean).join(' ').trim()
+    || input.fallback
+    || (input.email ? input.email.split('@')[0] : 'Builder');
+}
+
+async function resolveAvatarUrl(input: {
+  avatarObjectKey?: string | null;
+  fallbackUrl?: string | null;
+}) {
+  if (input.avatarObjectKey && isR2Configured()) {
+    try {
+      return await createSignedAvatarUrl(input.avatarObjectKey);
+    } catch {
+      return input.fallbackUrl ?? null;
+    }
+  }
+
+  return input.fallbackUrl ?? null;
+}
+
+function sanitizeFileName(fileName: string) {
+  return fileName
+    .toLowerCase()
+    .replace(/[^a-z0-9.-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+const authRoutes: FastifyPluginAsync = async (fastify: FastifyInstance) => {
+  fastify.get('/me', {
+    preHandler: createAuthHook(fastify),
+  }, async (req: FastifyRequest, reply: FastifyReply) => {
+    if (!req.user?.id) throw AuthError.unauthorized();
+
+    const clerkUser = await clerkClient.users.getUser(req.user.id);
+    const userData = await fastify.repos.users.getDashboardProfile(req.user.id);
+    const primaryEmail = clerkUser.emailAddresses.find(
+      (e: { id: string }) => e.id === clerkUser.primaryEmailAddressId
+    );
+    const email = primaryEmail?.emailAddress ?? '';
+    const displayName = getDisplayName({
+      firstName: clerkUser.firstName,
+      lastName: clerkUser.lastName,
+      email,
+      fallback: userData?.displayName ?? null,
+    });
+    const avatarUrl = await resolveAvatarUrl({
+      avatarObjectKey: userData?.avatarObjectKey ?? null,
+      fallbackUrl: userData?.profileImageUrl ?? clerkUser.imageUrl ?? null,
+    });
+
+    return reply.send({
+      user: {
+        id: clerkUser.id,
+        email,
+        firstName: clerkUser.firstName,
+        lastName: clerkUser.lastName,
+        displayName,
+        imageUrl: userData?.profileImageUrl ?? clerkUser.imageUrl,
+        avatarUrl,
+        creditsBalance: userData?.creditsBalance ?? 250,
+        subscriptionTier: userData?.subscriptionTier || 'free',
+        subscriptionStatus: userData?.subscriptionStatus || 'active',
+      },
+    });
+  });
+
+  fastify.post('/signout', {
+    preHandler: createAuthHook(fastify),
+  }, async (req: FastifyRequest, reply: FastifyReply) => {
+    if (!req.user?.id) throw AuthError.unauthorized();
+    return reply.send({ success: true });
+  });
+
+  fastify.post<{ Body: { base64: string; mimeType: string; fileName?: string } }>('/avatar', {
+    preHandler: createAuthHook(fastify),
+  }, async (req, reply) => {
+    if (!req.user?.id) throw AuthError.unauthorized();
+    if (!isR2Configured()) {
+      return reply.code(500).send({ error: 'r2_not_configured', message: 'Configure Cloudflare R2 before uploading avatars.' });
+    }
+
+    const { base64, mimeType, fileName } = req.body;
+    if (!base64 || !mimeType) {
+      return reply.code(400).send({ error: 'invalid_payload', message: 'Avatar payload is incomplete.' });
+    }
+    if (!mimeType.startsWith('image/')) {
+      return reply.code(400).send({ error: 'invalid_mime_type', message: 'Only image uploads are supported.' });
+    }
+
+    const normalizedBase64 = base64.includes(',') ? (base64.split(',')[1] ?? '') : base64;
+    const buffer = Buffer.from(normalizedBase64, 'base64');
+    if (buffer.length === 0) {
+      return reply.code(400).send({ error: 'invalid_payload', message: 'Avatar payload is empty.' });
+    }
+    if (buffer.length > 5 * 1024 * 1024) {
+      return reply.code(400).send({ error: 'file_too_large', message: 'Avatar uploads are capped at 5MB.' });
+    }
+
+    const safeName = sanitizeFileName(fileName || 'avatar');
+    const objectKey = \`avatars/\${req.user.id}/\${Date.now()}-\${safeName || 'avatar'}\`;
+    await uploadAvatarToR2({
+      objectKey,
+      body: buffer,
+      contentType: mimeType,
+    });
+
+    await fastify.repos.users.updateAvatar(req.user.id, {
+      avatarObjectKey: objectKey,
+      avatarMimeType: mimeType,
+    });
+
+    const avatarUrl = await createSignedAvatarUrl(objectKey);
+    return reply.send({ ok: true, avatarUrl });
+  });
+
+  fastify.delete('/account', {
+    preHandler: createAuthHook(fastify),
+  }, async (req: FastifyRequest, reply: FastifyReply) => {
+    if (!req.user?.id) throw AuthError.unauthorized();
+    await clerkClient.users.deleteUser(req.user.id);
+    await fastify.repos.users.deleteById(req.user.id);
+    return reply.code(204).send();
+  });
+};
+
+export default authRoutes;
+`);
+    writeFile(path.join(dir, 'src/routes/subscriptions.ts'), `import type { FastifyInstance, FastifyPluginAsync, FastifyRequest } from 'fastify';
+import clerkAuthPlugin from '../plugins/clerkAuth.js';
+import { SubscriptionService } from '../services/SubscriptionService.js';
+import { AuthError } from '../errors/index.js';
+import { verifyRevenueCatWebhook, verifyRevenueCatWebhookAuthorization, grantPromotionalEntitlement } from '../lib/revenuecat.js';
+import { createAuthHook, runBackgroundTask } from '../lib/routeHelpers.js';
+import { CACHE_SECONDS } from '../lib/constants.js';
+
+const subscriptionRoutes: FastifyPluginAsync = async (fastify: FastifyInstance) => {
+  const service = new SubscriptionService(fastify);
+
+  fastify.get('/pricing', async (_req, reply) => {
+    const data = await service.getPricing();
+    reply.header('Cache-Control', \`private, max-age=\${CACHE_SECONDS.SUBSCRIPTIONS_PRICING}\`);
+    return reply.send(data);
+  });
+
+  await fastify.register(async (app) => {
+    await app.register(clerkAuthPlugin);
+
+    app.get<{ Querystring: { refresh?: boolean } }>('/entitlements/me', {
+      preHandler: createAuthHook(app),
+    }, async (req, reply) => {
+      const userId = req.user?.id;
+      if (!userId) throw AuthError.unauthorized();
+      const refreshRaw = (req.query as unknown as { refresh?: unknown }).refresh;
+      const requestedRefresh = refreshRaw === true || refreshRaw === 'true' || refreshRaw === 1 || refreshRaw === '1';
+      const forceRefresh = Boolean(app.env.RC_SECRET_API_KEY) && requestedRefresh;
+      const data = await service.getEntitlementWithTrial(userId, { refreshRevenueCat: forceRefresh }, req);
+      reply.header('Cache-Control', 'private, no-store');
+      return reply.send(data);
+    });
+
+    app.post<{ Body: { code: string } }>('/redeem', {
+      preHandler: createAuthHook(app),
+    }, async (req, reply) => {
+      const userId = req.user?.id;
+      if (!userId) throw AuthError.unauthorized();
+      const { code } = req.body;
+      const validation = await app.repos.promoCodes.validateCode(code, userId);
+      if (!validation.valid || !validation.promoCode) {
+        const msgs: Record<string, string> = { invalid_code: 'This code is not valid.', code_expired: 'This code has expired.', code_fully_used: 'This code has already been used.', already_redeemed: 'You have already redeemed this code.' };
+        return reply.code(400).send({ error: validation.error, message: msgs[validation.error!] || 'Invalid code.' });
+      }
+      const rcKey = app.env.RC_SECRET_API_KEY;
+      if (!rcKey) return reply.code(500).send({ error: 'configuration_error', message: 'Subscription service not configured.' });
+
+      const { promoCode } = validation;
+      const entitlementId = app.env.RC_ENTITLEMENT_ID || 'pro';
+      try {
+        const currentSub = await app.repos.subscriptions.findByUserId(userId);
+        const result = await grantPromotionalEntitlement(userId, entitlementId, promoCode.months, rcKey);
+        await app.repos.promoCodes.recordRedemption(promoCode.id, userId, result.expiresAt);
+        const now = new Date();
+        await app.repos.subscriptions.upsert(userId, {
+          tier: 'pro', status: 'active', method: 'redeemed',
+          currentPeriodStart: now, currentPeriodEnd: result.expiresAt,
+          trialStart: null, trialEnd: null,
+          metadata: { redeemCode: promoCode.code, redeemCodeRedeemedAt: now.toISOString() },
+        });
+        runBackgroundTask(req, app.repos.subscriptionEvents.recordEvent({
+          userId, subscriptionId: currentSub?.id, eventType: 'promo_redeemed',
+          previousState: { tier: currentSub?.tier, status: currentSub?.status, method: currentSub?.method },
+          newState: { tier: 'pro', status: 'active', method: 'redeemed' },
+          periodStart: now, periodEnd: result.expiresAt,
+          metadata: { promoCode: promoCode.code },
+        }), 'promo_redeemed_event');
+        return { ok: true, expiresAt: result.expiresAt.toISOString() };
+      } catch (err) {
+        app.log.error({ msg: '[redeem:failed]', userId, error: (err as Error).message });
+        return reply.code(500).send({ error: 'redemption_failed', message: 'Failed to redeem code. Please try again.' });
+      }
+    });
+  });
+
+  await fastify.register(async (app) => {
+    app.addContentTypeParser('application/json', { parseAs: 'string' }, (req, body, done) => {
+      try {
+        const raw = typeof body === 'string' ? body : body.toString();
+        (req as unknown as { rawBody?: string }).rawBody = raw;
+        done(null, raw.trim().length === 0 ? {} : JSON.parse(raw));
+      } catch (err) { done(err as Error, undefined); }
+    });
+
+    app.post('/webhooks/revenuecat', async (req: FastifyRequest, reply) => {
+      const rawBody = (req as unknown as { rawBody?: string }).rawBody;
+      const bodyString = rawBody ?? (typeof req.body === 'string' ? req.body : '');
+      const signature = req.headers['x-revenuecat-signature'] as string | undefined;
+      const authorization = req.headers.authorization as string | undefined;
+      const webhookSecret = fastify.env.RC_WEBHOOK_SECRET;
+
+      if (!webhookSecret && fastify.env.NODE_ENV === 'production') {
+        return reply.code(500).send({ ok: false, error: 'webhook_not_configured' });
+      }
+      if (webhookSecret) {
+        if (!bodyString) return reply.code(400).send({ ok: false, error: 'invalid_body' });
+        const verifiedByAuth = verifyRevenueCatWebhookAuthorization(authorization, webhookSecret);
+        const verifiedBySig  = signature ? verifyRevenueCatWebhook(bodyString, signature, webhookSecret) : false;
+        if (!verifiedByAuth && !verifiedBySig) return reply.code(401).send({ ok: false, error: 'invalid_signature' });
+      }
+
+      const parsed = req.body as Record<string, unknown>;
+      const event  = (parsed?.event && typeof parsed.event === 'object') ? (parsed.event as Record<string, unknown>) : parsed;
+      try { await service.handleRevenueCatWebhook(event, req); } catch (err) {
+        fastify.log.error({ msg: '[webhook:revenuecat_failed]', error: (err as Error).message });
+      }
+      return { ok: true };
+    });
+  });
+
+};
+
+export default subscriptionRoutes;
+`);
+    writeFile(path.join(dir, 'src/routes/index.ts'), `import type { FastifyInstance, FastifyPluginAsync } from 'fastify';
+import clerkAuthPlugin from '../plugins/clerkAuth.js';
+import health from './health.js';
+import auth from './auth.js';
+import subscriptions from './subscriptions.js';
+import cors from '@fastify/cors';
+
+const routes: FastifyPluginAsync = async (fastify: FastifyInstance) => {
+  const FRONTEND_URL = fastify.env?.FRONTEND_URL;
+  const extensionOrigins = String(fastify.env?.EXTENSION_ORIGINS ?? '')
+    .split(',').map(o => o.trim()).filter(o => o.length > 0);
+  const restrictedOrigins = [...new Set([
+    ...(FRONTEND_URL ? [FRONTEND_URL] : []),
+    ...extensionOrigins,
+  ])];
+  const restrictedCorsOrigin = restrictedOrigins.length > 0 ? restrictedOrigins : false;
+
+  await fastify.register(async (app) => {
+    await app.register(cors, { origin: restrictedCorsOrigin, maxAge: 86_400, methods: ['GET', 'OPTIONS'], allowedHeaders: ['Content-Type'] });
+    await app.register(health);
+  }, { prefix: '/health' });
+
+  await fastify.register(async (app) => {
+    await app.register(cors, { origin: restrictedCorsOrigin, maxAge: 86_400, methods: ['GET', 'POST', 'DELETE', 'OPTIONS'], allowedHeaders: ['Authorization', 'Content-Type', 'X-Platform'] });
+    await app.register(clerkAuthPlugin);
+    await app.register(auth);
+  }, { prefix: '/auth' });
+
+  await fastify.register(async (app) => {
+    await app.register(cors, { origin: restrictedCorsOrigin, maxAge: 86_400, methods: ['GET', 'POST', 'OPTIONS'], allowedHeaders: ['Authorization', 'Content-Type', 'X-Platform', 'X-RevenueCat-Signature'] });
+    await app.register(subscriptions);
+  }, { prefix: '/subscriptions' });
+};
+
+export default routes;
+`);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// App + Index + Vercel entry
+// ═══════════════════════════════════════════════════════════════════════════
+function writeAppAndIndex(dir, displayName) {
+    writeFile(path.join(dir, 'src/app.ts'), `import Fastify from 'fastify';
+import type { FastifyInstance } from 'fastify';
+import routes from './routes/index.js';
+import envConfig from './plugins/env.js';
+import helmet from '@fastify/helmet';
+import compress from '@fastify/compress';
+import rateLimit from '@fastify/rate-limit';
+import { errorHandler } from './errors/index.js';
+import { AppConfig } from './config/index.js';
+import { Repositories } from './repositories/index.js';
+import { db } from './db/index.js';
+
+const isProduction = process.env.NODE_ENV === 'production';
+
+function createBaseApp(): FastifyInstance {
+  return Fastify({
+    trustProxy: true,
+    logger: {
+      level: process.env.LOG_LEVEL ?? (isProduction ? 'warn' : 'info'),
+      redact: ['req.headers.authorization'],
+      ...(isProduction ? {} : {
+        transport: { target: 'pino-pretty', options: { translateTime: 'HH:MM:ss Z', ignore: 'pid,hostname' } },
+      }),
+    },
+    bodyLimit: 12 * 1024 * 1024,
+    disableRequestLogging: isProduction,
+  });
+}
+
+export async function buildApp(): Promise<FastifyInstance> {
+  const app = createBaseApp();
+
+  if (!isProduction && !process.env.VERCEL) {
+    await import('dotenv/config');
+  }
+
+  await app.register(envConfig);
+
+  const config = AppConfig.fromEnv(app.env!);
+  app.decorate('config', config);
+
+  const repos = new Repositories(db);
+  app.decorate('repos', repos);
+
+  await app.register(compress, { global: true, threshold: 512, encodings: ['br', 'gzip', 'deflate'] });
+  app.setErrorHandler(errorHandler);
+
+  const isDevelopment = app.env?.NODE_ENV === 'development';
+
+  await app.register(helmet, {
+    contentSecurityPolicy: isDevelopment ? false : undefined,
+    crossOriginEmbedderPolicy: false,
+  });
+
+  await app.register(rateLimit, {
+    max: 120,
+    timeWindow: '1 minute',
+    allowList: isDevelopment ? ['127.0.0.1'] : [],
+  });
+
+  if (isDevelopment) {
+    const [{ default: swagger }, { default: swaggerUI }] = await Promise.all([
+      import('@fastify/swagger'),
+      import('@fastify/swagger-ui'),
+    ]);
+    await app.register(swagger, {
+      openapi: {
+        info: { title: '${displayName} API', version: '1.0.0' },
+        servers: [{ url: \`http://localhost:\${app.env?.PORT ?? 3000}\` }],
+        components: { securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' } } },
+      },
+    });
+    await app.register(swaggerUI, { routePrefix: '/docs' });
+  }
+
+  await app.register(routes);
+
+  return app;
+}
+`);
+    writeFile(path.join(dir, 'src/index.ts'), `import { buildApp } from './app.js';
+
+async function main() {
+  const fastify = await buildApp();
+  const PORT = fastify.env?.PORT ?? 0;
+  if (!Number.isFinite(PORT) || Number(PORT) <= 0) {
+    throw new Error(\`PORT must be set and be a positive number. Got: \${PORT}\`);
+  }
+  await fastify.listen({ port: Number(PORT), host: '0.0.0.0' });
+  fastify.log.info({ msg: '[startup]', addr: \`http://0.0.0.0:\${PORT}\` });
+}
+
+main().catch((err) => {
+  console.error('Failed to start server', err);
+  process.exit(1);
+});
+`);
+}
+function writeVercelEntry(dir) {
+    writeFile(path.join(dir, 'api/index.ts'), `import type { VercelRequest, VercelResponse } from '@vercel/node';
+import type { FastifyInstance } from 'fastify';
+import { buildApp } from '../src/app.js';
+
+let appReadyPromise: Promise<FastifyInstance> | undefined;
+
+async function getApp(): Promise<FastifyInstance> {
+  if (!appReadyPromise) {
+    appReadyPromise = (async () => {
+      const app = await buildApp();
+      await app.ready();
+      return app;
+    })().catch((err) => {
+      appReadyPromise = undefined;
+      throw err;
+    });
+  }
+  return appReadyPromise;
+}
+
+export default async function handler(req: VercelRequest, res: VercelResponse) {
+  const app = await getApp();
+  app.server.emit('request', req, res);
+}
+`);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Tests
+// ═══════════════════════════════════════════════════════════════════════════
+function writeTestFiles(dir) {
+    writeFile(path.join(dir, 'test/setup.ts'), `import dotenv from 'dotenv';
+dotenv.config();
+`);
+    writeFile(path.join(dir, 'test/health.test.ts'), `import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { buildApp } from '../src/app.js';
+import type { FastifyInstance } from 'fastify';
+
+let app: FastifyInstance;
+
+beforeAll(async () => {
+  app = await buildApp();
+  await app.ready();
+});
+
+afterAll(async () => {
+  await app.close();
+});
+
+describe('Health Routes', () => {
+  it('GET /health returns ok', async () => {
+    const res = await app.inject({ method: 'GET', url: '/health' });
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.payload);
+    expect(body.ok).toBe(true);
+  });
+});
+`);
+}