@objectifthunes/create-sandstone 0.1.0 → 1.0.0

package/dist/templates/claude-md.js

@@ -0,0 +1,853 @@
+export function claudeMdTemplate(config) {
+    const frameworkName = config.framework === 'express' ? 'Express' : 'Hono';
+    const lines = [];
+    // Title & What This Is
+    lines.push(`# ${config.name}`);
+    lines.push('');
+    lines.push('## What This Is');
+    lines.push(`Built with \`@objectifthunes/sandstone-sdk\` — a hexagonal-architecture backend toolkit.`);
+    lines.push(`Framework: ${frameworkName}. Database: PostgreSQL.`);
+    lines.push('');
+    // Architecture
+    lines.push('## Architecture');
+    lines.push('');
+    lines.push('- `src/infrastructure.ts` — all adapter wiring (database, auth, email, etc.)');
+    lines.push(`- \`src/main.ts\` — HTTP server entry point (${frameworkName})`);
+    if (config.graphql) {
+        lines.push('- `src/schema.ts` — GraphQL schema definition');
+    }
+    lines.push('- `migrations/` — SQL migrations (.up.sql / .down.sql)');
+    lines.push('- `scripts/migrate.ts` — migration runner script');
+    if (config.tests) {
+        lines.push('- `tests/` — test setup with in-memory adapters');
+    }
+    lines.push('');
+    // Stack table
+    lines.push('## Stack');
+    lines.push('');
+    lines.push('| Concern | Adapter | Import path |');
+    lines.push('|---------|---------|-------------|');
+    if (config.devMode) {
+        lines.push('| Database | In-memory (dev) | `@objectifthunes/sandstone-sdk/dev` |');
+        lines.push('| Logger | Console (dev) | `@objectifthunes/sandstone-sdk/dev` |');
+        lines.push('| Tokens | In-memory (dev) | `@objectifthunes/sandstone-sdk/dev` |');
+        if (config.email) {
+            lines.push('| Email | Console (dev) | `@objectifthunes/sandstone-sdk/dev` |');
+        }
+        if (config.sms) {
+            lines.push('| SMS | In-memory (dev) | `@objectifthunes/sandstone-sdk/dev` |');
+        }
+        if (config.push) {
+            lines.push('| Push | In-memory (dev) | `@objectifthunes/sandstone-sdk/dev` |');
+        }
+        if (config.realtime) {
+            lines.push('| Realtime | In-memory (dev) | `@objectifthunes/sandstone-sdk/dev` |');
+        }
+        if (config.search) {
+            lines.push('| Search | In-memory (dev) | `@objectifthunes/sandstone-sdk/dev` |');
+        }
+        if (config.queue) {
+            lines.push('| Queue | In-memory (dev) | `@objectifthunes/sandstone-sdk/dev` |');
+        }
+        if (config.scheduler) {
+            lines.push('| Scheduler | In-memory tick source (dev) | `@objectifthunes/sandstone-sdk/dev` |');
+        }
+        if (config.flags) {
+            lines.push('| Feature Flags | In-memory (dev) | `@objectifthunes/sandstone-sdk/dev` |');
+        }
+        if (config.tracing) {
+            lines.push('| Tracing | No-op (dev) | `@objectifthunes/sandstone-sdk/dev` |');
+        }
+        if (config.audit) {
+            lines.push('| Audit | In-memory (dev) | built-in |');
+        }
+        if (config.authz) {
+            lines.push('| Authorization | In-memory (dev) | `@objectifthunes/sandstone-sdk/dev` |');
+        }
+        if (config.cache) {
+            lines.push('| Cache | In-memory (dev) | `@objectifthunes/sandstone-sdk/dev` |');
+        }
+        if (config.dashboard) {
+            lines.push('| Dashboard | Built-in | built-in |');
+        }
+        if (config.auth === 'otp') {
+            lines.push('| Auth | OTP (magic link / code) | built-in |');
+        }
+        if (config.graphql) {
+            lines.push('| GraphQL | graphql-js | built-in |');
+        }
+    }
+    else {
+        if (config.database === 'supabase') {
+            lines.push('| Database | Supabase (PostgreSQL) | `@objectifthunes/sandstone-sdk/supabase` |');
+        }
+        else {
+            lines.push('| Database | PostgreSQL (`pg`) | `@objectifthunes/sandstone-sdk/pg` |');
+        }
+        lines.push('| Logger | Pino | `@objectifthunes/sandstone-sdk/pino` |');
+        lines.push('| Tokens | JOSE (JWT) | `@objectifthunes/sandstone-sdk/jose` |');
+        if (config.email === 'resend') {
+            lines.push('| Email | Resend | `@objectifthunes/sandstone-sdk/resend` |');
+        }
+        else if (config.email === 'nodemailer') {
+            lines.push('| Email | Nodemailer (SMTP) | `@objectifthunes/sandstone-sdk/nodemailer` |');
+        }
+        if (config.auth === 'otp') {
+            lines.push('| Auth | OTP (magic link / code) | built-in |');
+        }
+        else if (config.auth === 'password+otp') {
+            lines.push('| Auth | Password + OTP | built-in + `@objectifthunes/sandstone-sdk/argon2` |');
+        }
+        else if (config.auth === 'oauth+otp') {
+            lines.push('| Auth | OAuth (Google) + OTP | built-in + `@objectifthunes/sandstone-sdk/oauth-google` |');
+        }
+        else if (config.auth === 'all') {
+            lines.push('| Auth | Password + OTP + OAuth | built-in + `@objectifthunes/sandstone-sdk/argon2` + `@objectifthunes/sandstone-sdk/oauth-google` |');
+        }
+        if (config.payments === 'stripe') {
+            lines.push('| Payments | Stripe | `@objectifthunes/sandstone-sdk/stripe` |');
+        }
+        else if (config.payments === 'revenuecat') {
+            lines.push('| Payments | RevenueCat | `@objectifthunes/sandstone-sdk/revenuecat` |');
+        }
+        else if (config.payments === 'paddle') {
+            lines.push('| Payments | Paddle | `@objectifthunes/sandstone-sdk/paddle` |');
+        }
+        else if (config.payments === 'lemonsqueezy') {
+            lines.push('| Payments | Lemon Squeezy | `@objectifthunes/sandstone-sdk/lemonsqueezy` |');
+        }
+        if (config.storage === 's3') {
+            lines.push('| Storage | AWS S3 | `@objectifthunes/sandstone-sdk/s3` |');
+        }
+        else if (config.storage === 'r2') {
+            lines.push('| Storage | Cloudflare R2 | `@objectifthunes/sandstone-sdk/r2` |');
+        }
+        else if (config.storage === 'local') {
+            lines.push('| Storage | Local filesystem | `@objectifthunes/sandstone-sdk/local-storage` |');
+        }
+        if (config.cache === 'upstash') {
+            lines.push('| Cache | Upstash Redis | `@objectifthunes/sandstone-sdk/upstash` |');
+        }
+        else if (config.cache === 'redis') {
+            lines.push('| Cache | Redis (ioredis) | `@objectifthunes/sandstone-sdk/redis` |');
+        }
+        else if (config.cache === 'memory') {
+            lines.push('| Cache | In-memory LRU | `@objectifthunes/sandstone-sdk/memory` |');
+        }
+        if (config.sms === 'twilio') {
+            lines.push('| SMS | Twilio | `@objectifthunes/sandstone-sdk/twilio` |');
+        }
+        else if (config.sms === 'sns') {
+            lines.push('| SMS | AWS SNS | `@objectifthunes/sandstone-sdk/sns` |');
+        }
+        if (config.push === 'fcm') {
+            lines.push('| Push | Firebase Cloud Messaging | `@objectifthunes/sandstone-sdk/fcm` |');
+        }
+        else if (config.push === 'apns') {
+            lines.push('| Push | Apple Push Notification service | `@objectifthunes/sandstone-sdk/apns` |');
+        }
+        else if (config.push === 'both') {
+            lines.push('| Push | FCM + APNs | `@objectifthunes/sandstone-sdk/fcm` + `@objectifthunes/sandstone-sdk/apns` |');
+        }
+        if (config.realtime === 'socketio') {
+            lines.push('| Realtime | Socket.io | `@objectifthunes/sandstone-sdk/socketio` |');
+        }
+        else if (config.realtime === 'pusher') {
+            lines.push('| Realtime | Pusher Channels | `@objectifthunes/sandstone-sdk/pusher` |');
+        }
+        else if (config.realtime === 'ably') {
+            lines.push('| Realtime | Ably | `@objectifthunes/sandstone-sdk/ably` |');
+        }
+        if (config.search === 'meilisearch') {
+            lines.push('| Search | Meilisearch | `@objectifthunes/sandstone-sdk/meilisearch` |');
+        }
+        else if (config.search === 'typesense') {
+            lines.push('| Search | Typesense | `@objectifthunes/sandstone-sdk/typesense` |');
+        }
+        else if (config.search === 'pg-search') {
+            lines.push('| Search | PostgreSQL full-text | `@objectifthunes/sandstone-sdk/pg-search` |');
+        }
+        if (config.queue === 'bullmq') {
+            lines.push('| Queue | BullMQ (Redis) | `@objectifthunes/sandstone-sdk/bullmq` |');
+        }
+        else if (config.queue === 'pg-boss') {
+            lines.push('| Queue | pg-boss (PostgreSQL) | `@objectifthunes/sandstone-sdk/pg-boss` |');
+        }
+        if (config.scheduler) {
+            lines.push('| Scheduler | node-cron | `@objectifthunes/sandstone-sdk/node-cron` |');
+        }
+        if (config.flags === 'pg-flags') {
+            lines.push('| Feature Flags | PostgreSQL | `@objectifthunes/sandstone-sdk/pg-flags` |');
+        }
+        else if (config.flags === 'env-flags') {
+            lines.push('| Feature Flags | Environment variables | `@objectifthunes/sandstone-sdk/env-flags` |');
+        }
+        else if (config.flags === 'launchdarkly') {
+            lines.push('| Feature Flags | LaunchDarkly | `@objectifthunes/sandstone-sdk/launchdarkly` |');
+        }
+        if (config.tracing) {
+            lines.push('| Tracing | OpenTelemetry | `@objectifthunes/sandstone-sdk/otel` |');
+        }
+        if (config.audit) {
+            lines.push('| Audit | Built-in (DB-backed) | built-in |');
+        }
+        if (config.authz === 'pg-authz') {
+            lines.push('| Authorization | PostgreSQL | `@objectifthunes/sandstone-sdk/pg-authz` |');
+        }
+        else if (config.authz === 'casbin') {
+            lines.push('| Authorization | Casbin | `@objectifthunes/sandstone-sdk/casbin` |');
+        }
+        if (config.dashboard) {
+            lines.push('| Dashboard | Built-in | built-in |');
+        }
+        if (config.graphql) {
+            lines.push('| GraphQL | graphql-js | built-in |');
+        }
+    }
+    lines.push('');
+    // Key Files
+    lines.push('## Key Files');
+    lines.push('');
+    lines.push('### `src/infrastructure.ts`');
+    lines.push('Wires all adapters together and exports the `app` instance created by `createApp()`.');
+    lines.push('This is the single place to swap adapters — change a provider here and the rest of the codebase is unaffected.');
+    lines.push('');
+    lines.push('### `src/main.ts`');
+    lines.push(`Starts the ${frameworkName} HTTP server. Runs migrations on startup, registers route handlers via the framework adapter, and handles graceful shutdown on SIGTERM.`);
+    lines.push('');
+    if (config.graphql) {
+        lines.push('### `src/schema.ts`');
+        lines.push('Defines the GraphQL schema using `graphql-js`. Add new types, queries, and mutations here.');
+        lines.push('');
+    }
+    lines.push('### `migrations/`');
+    lines.push('Plain SQL files named `NNN_description.up.sql` / `.down.sql`. Run with `npm run db:migrate`.');
+    lines.push('');
+    if (config.tests) {
+        lines.push('### `tests/setup.ts`');
+        lines.push('Vitest test setup. Uses in-memory adapters so tests run without external services.');
+        lines.push('');
+    }
+    if (config.dashboard) {
+        lines.push('- Dashboard available at `/_dashboard` — shows port wiring, health, queue stats, flags, audit trail');
+        lines.push('');
+    }
+    // SDK Reference
+    lines.push('## SDK Reference');
+    lines.push('');
+    lines.push('**Core concepts:**');
+    lines.push('');
+    lines.push('- **Port** — an interface that defines a capability (e.g., `EmailPort`, `StoragePort`). The SDK ships ports for every concern.');
+    lines.push('- **Adapter** — a concrete implementation of a port (e.g., `createResendTransport` implements `EmailPort`).');
+    lines.push('- **`createApp(options)`** — assembles all adapters into a single `app` object that exposes typed handler factories, the `db` client, `logger`, and a `shutdown()` method.');
+    lines.push('- **`runMigrations(db)`** — applies pending SQL migrations from `migrations/`.');
+    lines.push('');
+    lines.push('**Error types** (import from `@objectifthunes/sandstone-sdk`):');
+    lines.push('');
+    lines.push('- `NotFoundError` — resource not found (maps to HTTP 404)');
+    lines.push('- `UnauthorizedError` — missing/invalid credentials (maps to HTTP 401)');
+    lines.push('- `ForbiddenError` — insufficient permissions (maps to HTTP 403)');
+    lines.push('- `ValidationError` — invalid input (maps to HTTP 422)');
+    lines.push('- `ConflictError` — duplicate resource (maps to HTTP 409)');
+    lines.push('');
+    lines.push('**Docs:** https://maxoujs.github.io/sandstone-sdk/');
+    lines.push('');
+    // Common Tasks
+    lines.push('## Common Tasks');
+    lines.push('');
+    lines.push('- **Add a new entity:** create a migration in `migrations/`, add a repository using `app.db`, wire it into a handler.');
+    if (config.graphql) {
+        lines.push('- **Add a GraphQL type/query/mutation:** edit `src/schema.ts` and add the resolver logic.');
+    }
+    if (config.auth) {
+        lines.push('- **Configure authentication:** adjust the `auth` options in `src/infrastructure.ts`.');
+    }
+    if (config.email) {
+        lines.push('- **Change email provider:** swap the transport import in `src/infrastructure.ts` and update `.env`.');
+    }
+    if (config.payments) {
+        lines.push('- **Change payment provider:** swap the provider import in `src/infrastructure.ts` and update `.env`.');
+    }
+    if (config.storage) {
+        lines.push('- **Change storage provider:** swap the storage import in `src/infrastructure.ts` and update `.env`.');
+    }
+    if (config.sms) {
+        lines.push("- **Send an SMS:** `await app.sms!.send({ to: '+1234567890', body: 'Hello' })`");
+    }
+    if (config.push) {
+        lines.push("- **Send a push notification:** `await app.push!.send(deviceToken, { title: 'Hello', body: 'World' })`");
+    }
+    if (config.realtime) {
+        lines.push("- **Publish a realtime event:** `await app.realtime!.publish('channel', 'event', { data })`");
+    }
+    if (config.search) {
+        lines.push("- **Index documents:** `await app.search!.index('products', [{ id: '1', document: { name: 'Widget' } }])`");
+        lines.push("- **Search:** `await app.search!.search('products', 'widget')`");
+    }
+    if (config.queue) {
+        lines.push("- **Enqueue a job:** `await app.queue!.enqueue('emails', { to: 'user@test.com' })`");
+    }
+    if (config.flags) {
+        lines.push("- **Check a feature flag:** `await app.flags!.isEnabled('new-ui', { userId: '123' })`");
+    }
+    if (config.audit) {
+        lines.push("- **Log an audit entry:** `await app.audit!.log({ actor: userId, action: 'update', resource: 'post', resourceId: postId })`");
+    }
+    if (config.authz) {
+        lines.push("- **Check permission:** `await app.authz!.can('user:123', 'edit', 'post', postId)`");
+        lines.push("- **Grant permission:** `await app.authz!.grant('user:123', 'edit', 'post')`");
+    }
+    if (config.dashboard) {
+        lines.push('- **Access dashboard:** visit `http://localhost:3000/_dashboard`');
+    }
+    if (config.tracing) {
+        lines.push("- **Create a trace span:** `await app.tracer.withSpan('operation', async (span) => { ... })`");
+    }
+    lines.push('- **Run migrations:** `npm run db:migrate`');
+    lines.push('- **Add a migration:** create `migrations/NNN_description.up.sql` (and `.down.sql`).');
+    lines.push('');
+    // Commands
+    lines.push('## Commands');
+    lines.push('');
+    lines.push('```sh');
+    lines.push('npm run dev          # start dev server with hot-reload');
+    lines.push('npm run build        # compile TypeScript to dist/');
+    lines.push('npm start            # run compiled output');
+    lines.push('npm run lint         # type-check without emitting');
+    lines.push('npm run db:migrate   # run pending SQL migrations');
+    if (config.tests) {
+        lines.push('npm test             # run unit tests (vitest)');
+        lines.push('npm run test:watch   # run tests in watch mode');
+    }
+    if (config.e2e) {
+        lines.push('npm run test:e2e     # run end-to-end tests');
+    }
+    lines.push('```');
+    lines.push('');
+    // Environment Variables
+    lines.push('## Environment Variables');
+    lines.push('');
+    if (config.devMode) {
+        lines.push('This project uses `./dev` imports — **no env vars required** to start.');
+        lines.push('');
+        lines.push('| Variable | Required | Description |');
+        lines.push('|----------|----------|-------------|');
+        lines.push('| `PORT` | No | HTTP port (default: 3000) |');
+        lines.push('| `LOG_LEVEL` | No | Log level (default: `info`) |');
+        lines.push('');
+    }
+    else {
+        lines.push('Copy `.env.example` to `.env` and fill in the values.');
+        lines.push('');
+        lines.push('| Variable | Required | Description |');
+        lines.push('|----------|----------|-------------|');
+        lines.push('| `PORT` | No | HTTP port (default: 3000) |');
+        lines.push('| `NODE_ENV` | No | `development` or `production` |');
+        lines.push('| `LOG_LEVEL` | No | Pino log level (default: `info`) |');
+        if (config.database === 'supabase') {
+            lines.push('| `DATABASE_URL` | **Yes** | Supabase PostgreSQL connection string |');
+        }
+        else {
+            lines.push('| `DATABASE_URL` | **Yes** | PostgreSQL connection string |');
+        }
+        lines.push('| `JWT_SECRET` | **Yes** | Secret for signing JWT tokens (min 32 chars) |');
+        if (config.email === 'resend') {
+            lines.push('| `RESEND_API_KEY` | **Yes** | Resend API key |');
+            lines.push('| `EMAIL_FROM` | No | Sender address (default: `noreply@example.com`) |');
+        }
+        else if (config.email === 'nodemailer') {
+            lines.push('| `SMTP_HOST` | No | SMTP host (default: `localhost`) |');
+            lines.push('| `SMTP_PORT` | No | SMTP port (default: `1025`) |');
+            lines.push('| `SMTP_USER` | No | SMTP username |');
+            lines.push('| `SMTP_PASS` | No | SMTP password |');
+            lines.push('| `EMAIL_FROM` | No | Sender address (default: `noreply@example.com`) |');
+        }
+        if (config.auth === 'oauth+otp' || config.auth === 'all') {
+            lines.push('| `GOOGLE_CLIENT_ID` | **Yes** | Google OAuth client ID |');
+            lines.push('| `GOOGLE_CLIENT_SECRET` | **Yes** | Google OAuth client secret |');
+            lines.push('| `GOOGLE_REDIRECT_URI` | **Yes** | Google OAuth redirect URI |');
+        }
+        if (config.payments === 'stripe') {
+            lines.push('| `STRIPE_SECRET_KEY` | **Yes** | Stripe secret key |');
+            lines.push('| `STRIPE_WEBHOOK_SECRET` | **Yes** | Stripe webhook signing secret |');
+        }
+        else if (config.payments === 'revenuecat') {
+            lines.push('| `REVENUECAT_API_KEY` | **Yes** | RevenueCat API key |');
+            lines.push('| `REVENUECAT_WEBHOOK_SECRET` | **Yes** | RevenueCat webhook secret |');
+        }
+        else if (config.payments === 'paddle') {
+            lines.push('| `PADDLE_API_KEY` | **Yes** | Paddle API key |');
+            lines.push('| `PADDLE_WEBHOOK_SECRET` | **Yes** | Paddle webhook signing secret |');
+            lines.push('| `PADDLE_ENVIRONMENT` | No | `sandbox` or `production` (default: `sandbox`) |');
+        }
+        else if (config.payments === 'lemonsqueezy') {
+            lines.push('| `LEMONSQUEEZY_API_KEY` | **Yes** | Lemon Squeezy API key |');
+            lines.push('| `LEMONSQUEEZY_WEBHOOK_SECRET` | **Yes** | Lemon Squeezy webhook secret |');
+        }
+        if (config.storage === 's3') {
+            lines.push('| `S3_BUCKET` | **Yes** | S3 bucket name |');
+            lines.push('| `S3_REGION` | **Yes** | AWS region |');
+            lines.push('| `S3_ACCESS_KEY_ID` | **Yes** | AWS access key ID |');
+            lines.push('| `S3_SECRET_ACCESS_KEY` | **Yes** | AWS secret access key |');
+        }
+        else if (config.storage === 'r2') {
+            lines.push('| `R2_ACCOUNT_ID` | **Yes** | Cloudflare account ID |');
+            lines.push('| `R2_ACCESS_KEY_ID` | **Yes** | R2 access key ID |');
+            lines.push('| `R2_SECRET_ACCESS_KEY` | **Yes** | R2 secret access key |');
+            lines.push('| `R2_BUCKET` | **Yes** | R2 bucket name |');
+        }
+        else if (config.storage === 'local') {
+            lines.push('| `LOCAL_STORAGE_DIR` | No | Upload directory (default: `./uploads`) |');
+        }
+        if (config.cache === 'upstash') {
+            lines.push('| `UPSTASH_REDIS_URL` | **Yes** | Upstash Redis REST URL |');
+            lines.push('| `UPSTASH_REDIS_TOKEN` | **Yes** | Upstash Redis REST token |');
+        }
+        else if (config.cache === 'redis') {
+            lines.push('| `REDIS_URL` | **Yes** | Redis connection URL |');
+        }
+        if (config.sms === 'twilio') {
+            lines.push('| `TWILIO_ACCOUNT_SID` | **Yes** | Twilio account SID |');
+            lines.push('| `TWILIO_AUTH_TOKEN` | **Yes** | Twilio auth token |');
+            lines.push('| `TWILIO_FROM_NUMBER` | **Yes** | Twilio sender phone number (E.164) |');
+        }
+        else if (config.sms === 'sns') {
+            lines.push('| `AWS_REGION` | **Yes** | AWS region for SNS |');
+            lines.push('| `AWS_ACCESS_KEY_ID` | **Yes** | AWS access key ID |');
+            lines.push('| `AWS_SECRET_ACCESS_KEY` | **Yes** | AWS secret access key |');
+        }
+        if (config.push === 'fcm' || config.push === 'both') {
+            lines.push('| `FCM_PROJECT_ID` | **Yes** | Firebase project ID |');
+            lines.push('| `FCM_SERVICE_ACCOUNT_KEY` | **Yes** | Firebase service account JSON key (base64) |');
+        }
+        if (config.push === 'apns' || config.push === 'both') {
+            lines.push('| `APNS_KEY_ID` | **Yes** | APNs key ID |');
+            lines.push('| `APNS_TEAM_ID` | **Yes** | Apple Developer team ID |');
+            lines.push('| `APNS_PRIVATE_KEY` | **Yes** | APNs private key (.p8, base64) |');
+            lines.push('| `APNS_BUNDLE_ID` | **Yes** | App bundle ID |');
+        }
+        if (config.realtime === 'pusher') {
+            lines.push('| `PUSHER_APP_ID` | **Yes** | Pusher app ID |');
+            lines.push('| `PUSHER_KEY` | **Yes** | Pusher key |');
+            lines.push('| `PUSHER_SECRET` | **Yes** | Pusher secret |');
+            lines.push('| `PUSHER_CLUSTER` | **Yes** | Pusher cluster (e.g., `us2`) |');
+        }
+        else if (config.realtime === 'ably') {
+            lines.push('| `ABLY_API_KEY` | **Yes** | Ably API key |');
+        }
+        if (config.search === 'meilisearch') {
+            lines.push('| `MEILISEARCH_URL` | **Yes** | Meilisearch host URL |');
+            lines.push('| `MEILISEARCH_API_KEY` | **Yes** | Meilisearch API key |');
+        }
+        else if (config.search === 'typesense') {
+            lines.push('| `TYPESENSE_URL` | **Yes** | Typesense host URL |');
+            lines.push('| `TYPESENSE_API_KEY` | **Yes** | Typesense API key |');
+        }
+        if (config.queue === 'bullmq') {
+            lines.push('| `BULLMQ_REDIS_URL` | **Yes** | Redis URL for BullMQ |');
+        }
+        if (config.flags === 'launchdarkly') {
+            lines.push('| `LAUNCHDARKLY_SDK_KEY` | **Yes** | LaunchDarkly SDK key |');
+        }
+        if (config.tracing) {
+            lines.push('| `OTEL_EXPORTER_OTLP_ENDPOINT` | No | OpenTelemetry collector endpoint |');
+            lines.push('| `OTEL_SERVICE_NAME` | No | Service name for traces |');
+        }
+        if (config.authz === 'casbin') {
+            lines.push('| `CASBIN_MODEL_PATH` | **Yes** | Path to Casbin model file |');
+            lines.push('| `CASBIN_POLICY_PATH` | **Yes** | Path to Casbin policy file |');
+        }
+        if (config.dashboard) {
+            lines.push('| `DASHBOARD_SECRET` | No | Shared secret to protect the dashboard |');
+        }
+        lines.push('');
+    }
+    // Active Port Interfaces
+    lines.push('## Active Port Interfaces');
+    lines.push('');
+    lines.push('### DatabaseClient');
+    lines.push('```ts');
+    lines.push('db.query<T>(text: string, values?: unknown[]): Promise<QueryResult<T>>');
+    lines.push('db.transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>');
+    lines.push('db.healthCheck(): Promise<void>');
+    lines.push('db.close(): Promise<void>');
+    lines.push('```');
+    lines.push('');
+    lines.push('### Logger');
+    lines.push('```ts');
+    lines.push('logger.info(msg: string, data?: Record<string, unknown>): void');
+    lines.push('logger.warn/error/debug(msg: string, data?: Record<string, unknown>): void');
+    lines.push('logger.child(bindings: Record<string, unknown>): Logger');
+    lines.push('```');
+    lines.push('');
+    lines.push('### TokenSigner');
+    lines.push('```ts');
+    lines.push('tokens.sign(payload: TokenPayload, expiresIn: string): Promise<string>');
+    lines.push('tokens.verify(token: string): Promise<TokenPayload>');
+    lines.push('tokens.signPair(payload: TokenPayload, accessTTL: string, refreshTTL: string): Promise<TokenPair>');
+    lines.push('```');
+    lines.push('');
+    if (config.email) {
+        lines.push('### EmailTransport');
+        lines.push('```ts');
+        lines.push('transport.send(message: EmailMessage): Promise<{ messageId: string }>');
+        lines.push('// EmailMessage: { to, subject, html, text?, from?, replyTo?, attachments? }');
+        lines.push('```');
+        lines.push('');
+    }
+    if (config.payments) {
+        lines.push('### PaymentProvider');
+        lines.push('```ts');
+        lines.push('payments.customers.create(params): Promise<PaymentCustomer>');
+        lines.push('payments.customers.get(id): Promise<PaymentCustomer | null>');
+        lines.push('payments.customers.update(id, params): Promise<PaymentCustomer>');
+        lines.push('payments.customers.delete(id): Promise<void>');
+        lines.push('payments.subscriptions.create(params): Promise<PaymentSubscription>');
+        lines.push('payments.subscriptions.get(id): Promise<PaymentSubscription | null>');
+        lines.push('payments.subscriptions.cancel(id, params?): Promise<PaymentSubscription>');
+        lines.push('payments.subscriptions.listByCustomer(customerId): Promise<PaymentSubscription[]>');
+        lines.push('payments.invoices.get(id): Promise<PaymentInvoice | null>');
+        lines.push('payments.invoices.listByCustomer(customerId): Promise<PaymentInvoice[]>');
+        lines.push('payments.webhooks.verify(body, headers): WebhookEvent');
+        lines.push('```');
+        lines.push('');
+    }
+    if (config.storage) {
+        lines.push('### StorageProvider');
+        lines.push('```ts');
+        lines.push('storage.upload(params: { key, body, contentType }): Promise<StorageObject>');
+        lines.push('storage.download(key): Promise<{ body: ReadableStream, contentType? }>');
+        lines.push('storage.delete(key): Promise<void>');
+        lines.push('storage.getSignedUrl(key, expiresIn): Promise<string>');
+        lines.push('storage.exists(key): Promise<boolean>');
+        lines.push('```');
+        lines.push('');
+    }
+    if (config.cache) {
+        lines.push('### CacheProvider');
+        lines.push('```ts');
+        lines.push('cache.get<T>(key: string): Promise<T | null>');
+        lines.push('cache.set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>');
+        lines.push('cache.delete(key: string): Promise<void>');
+        lines.push('cache.flush(): Promise<void>');
+        lines.push('cache.increment(key: string, ttlSeconds?: number): Promise<number>');
+        lines.push('```');
+        lines.push('');
+    }
+    if (config.auth === 'password+otp' || config.auth === 'all') {
+        lines.push('### PasswordHasher');
+        lines.push('```ts');
+        lines.push('hasher.hash(password: string): Promise<string>');
+        lines.push('hasher.verify(password: string, hash: string): Promise<boolean>');
+        lines.push('```');
+        lines.push('');
+    }
+    if (config.auth === 'oauth+otp' || config.auth === 'all') {
+        lines.push('### OAuthProvider');
+        lines.push('```ts');
+        lines.push('oauth.getAuthUrl(params: { redirectUri, state?, scopes? }): string');
+        lines.push('oauth.handleCallback(params: { code, redirectUri }): Promise<OAuthProfile>');
+        lines.push('// OAuthProfile: { id, email, name?, avatarUrl?, raw }');
+        lines.push('```');
+        lines.push('');
+    }
+    if (config.sms) {
+        lines.push('### SmsTransport');
+        lines.push('```ts');
+        lines.push('sms.send(message: SmsMessage): Promise<{ messageId: string }>');
+        lines.push('// SmsMessage: { to: string, body: string, from?: string }');
+        lines.push('```');
+        lines.push('');
+    }
+    if (config.push) {
+        lines.push('### PushTransport');
+        lines.push('```ts');
+        lines.push('push.send(token: string, payload: PushPayload): Promise<PushResult>');
+        lines.push('push.sendMany(tokens: string[], payload: PushPayload): Promise<PushResult[]>');
+        lines.push('// PushPayload: { title, body, data?, badge?, sound?, imageUrl? }');
+        lines.push('```');
+        lines.push('');
+    }
+    if (config.realtime) {
+        lines.push('### RealtimeProvider');
+        lines.push('```ts');
+        lines.push('realtime.publish(channel: string, event: string, data: unknown): Promise<void>');
+        lines.push('realtime.getChannels(): Promise<RealtimeChannel[]>');
+        lines.push('realtime.getSubscriberCount(channel: string): Promise<number>');
+        lines.push('```');
+        lines.push('');
+    }
+    if (config.search) {
+        lines.push('### SearchProvider');
+        lines.push('```ts');
+        lines.push('search.index<T>(indexName: string, documents: SearchDocument<T>[]): Promise<IndexResult>');
+        lines.push('search.search<T>(indexName: string, query: string, options?: SearchOptions): Promise<SearchResult<T>>');
+        lines.push('search.delete(indexName: string, documentIds: string[]): Promise<void>');
+        lines.push('```');
+        lines.push('');
+    }
+    if (config.queue) {
+        lines.push('### QueueProvider');
+        lines.push('```ts');
+        lines.push('queue.enqueue<T>(queue: string, payload: T, options?: JobOptions): Promise<Job<T>>');
+        lines.push('queue.process<T>(queue: string, handler: JobHandler<T>, options?: ProcessorOptions): Promise<void>');
+        lines.push('queue.getJob<T>(jobId: string): Promise<Job<T> | null>');
+        lines.push('queue.cancel(jobId: string): Promise<void>');
+        lines.push('```');
+        lines.push('');
+    }
+    if (config.flags) {
+        lines.push('### FeatureFlagProvider');
+        lines.push('```ts');
+        lines.push('flags.isEnabled(flag: string, context?: FlagContext): Promise<boolean>');
+        lines.push('flags.getValue<T>(flag: string, defaultValue: T, context?: FlagContext): Promise<T>');
+        lines.push('flags.getAllFlags(context?: FlagContext): Promise<Record<string, unknown>>');
+        lines.push('```');
+        lines.push('');
+    }
+    if (config.tracing) {
+        lines.push('### Tracer');
+        lines.push('```ts');
+        lines.push('tracer.startSpan(name: string, options?: SpanOptions): Span');
+        lines.push('tracer.withSpan<T>(name: string, fn: (span: Span) => Promise<T>): Promise<T>');
+        lines.push('```');
+        lines.push('');
+    }
+    if (config.authz) {
+        lines.push('### AuthorizationProvider');
+        lines.push('```ts');
+        lines.push('authz.can(subject: string, action: string, resource: string, resourceId?: string): Promise<boolean>');
+        lines.push('authz.authorize(subject: string, action: string, resource: string, resourceId?: string): Promise<void>');
+        lines.push('authz.grant(subject: string, action: string, resource: string, resourceId?: string): Promise<void>');
+        lines.push('authz.revoke(subject: string, action: string, resource: string, resourceId?: string): Promise<void>');
+        lines.push('authz.listPermissions(subject: string): Promise<Permission[]>');
+        lines.push('```');
+        lines.push('');
+    }
+    if (config.audit) {
+        lines.push('### AuditLogger');
+        lines.push('```ts');
+        lines.push('audit.log(entry: AuditEntry): Promise<AuditRecord>');
+        lines.push('audit.query(filters: AuditQueryFilters): Promise<AuditRecord[]>');
+        lines.push('audit.count(filters: AuditQueryFilters): Promise<number>');
+        lines.push('```');
+        lines.push('');
+    }
+    // Recipe: Add a New Entity
+    lines.push('## Recipe: Add a New Entity');
+    lines.push('');
+    lines.push('1. Create `migrations/NNN_create_<table>.up.sql`:');
+    lines.push('```sql');
+    lines.push('CREATE TABLE <table_name> (');
+    lines.push('  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),');
+    lines.push('  -- your columns here');
+    lines.push('  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),');
+    lines.push('  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()');
+    lines.push(');');
+    lines.push('```');
+    lines.push('');
+    lines.push('2. Create `migrations/NNN_create_<table>.down.sql`:');
+    lines.push('```sql');
+    lines.push('DROP TABLE IF EXISTS <table_name>;');
+    lines.push('```');
+    lines.push('');
+    lines.push('3. Define a TypeScript interface for the entity');
+    lines.push('');
+    lines.push('4. Create a repository:');
+    lines.push('```ts');
+    lines.push("const repo = createRepository<MyEntity>('table_name', { primaryKey: 'id', softDelete: true });");
+    lines.push('```');
+    lines.push('');
+    lines.push('5. All repo methods take `db: Queryable` as first arg (explicit dependency injection):');
+    lines.push('```ts');
+    lines.push('await repo.findById(db, id);');
+    lines.push('await repo.create(db, { name, email });');
+    lines.push('await repo.paginate(db, { page: 1, perPage: 20 });');
+    lines.push('// Inside a transaction:');
+    lines.push('await db.transaction(async (tx) => {');
+    lines.push('  await repo.create(tx, data);');
+    lines.push('  await otherRepo.update(tx, id, changes);');
+    lines.push('});');
+    lines.push('```');
+    lines.push('');
+    if (config.graphql) {
+        lines.push('6. Add a GraphQL type to `src/schema.ts` using `buildObjectType()`');
+        lines.push('');
+        lines.push('7. Create a dataloader for batched lookups: `createLoaderFromRepo(repo, db)`');
+        lines.push('');
+    }
+    // Error Types
+    lines.push('## Error Types');
+    lines.push('');
+    lines.push('| Error | Code | HTTP | When to throw |');
+    lines.push('|---|---|---|---|');
+    lines.push('| `NotFoundError(resource, id?)` | NOT_FOUND | 404 | Resource not found |');
+    lines.push('| `UnauthorizedError(msg?)` | UNAUTHORIZED | 401 | Missing/invalid auth |');
+    lines.push('| `ForbiddenError(msg?)` | FORBIDDEN | 403 | Insufficient permissions |');
+    lines.push('| `ValidationError(msg, details?)` | VALIDATION_ERROR | 400 | Bad input data |');
+    lines.push('| `ConflictError(msg, details?)` | CONFLICT | 409 | Duplicate resource |');
+    lines.push('| `RateLimitError(retryAfter?)` | RATE_LIMITED | 429 | Too many requests |');
+    lines.push('| `InternalError(msg?)` | INTERNAL_ERROR | 500 | Unexpected failure |');
+    lines.push('');
+    lines.push('All errors accept a `details` object. Include `fix` for LLM diagnostics:');
+    lines.push('```ts');
+    lines.push("throw new ValidationError('Bad input', { field: 'email', fix: 'Provide a valid email address' });");
+    lines.push('```');
+    lines.push('');
+    // Testing Recipe
+    if (config.tests) {
+        lines.push('## Testing');
+        lines.push('');
+        lines.push('Test setup is in `tests/setup.ts`. It creates in-memory adapters:');
+        lines.push('```ts');
+        lines.push("import { createTestApp } from './tests/setup.js';");
+        lines.push('');
+        lines.push('const { app, db, email } = await createTestApp();');
+        lines.push('// app is a real App instance with in-memory adapters');
+        lines.push('// db, email, tokens, logger are direct references for assertions');
+        lines.push('```');
+        lines.push('');
+        lines.push('Run tests: `npm test`');
+        lines.push('Watch mode: `npm run test:watch`');
+        lines.push('');
+    }
+    // Switching to Production (devMode only)
+    if (config.devMode) {
+        lines.push('## Switching to Production');
+        lines.push('');
+        lines.push('This project was scaffolded in **prototype mode**: all adapters come from `@objectifthunes/sandstone-sdk/dev` and require zero config. When you are ready to deploy for real, follow these steps:');
+        lines.push('');
+        lines.push('### 1. Swap imports in `src/infrastructure.ts`');
+        lines.push('');
+        lines.push('Replace every `@objectifthunes/sandstone-sdk/dev` import with the real adapter subpath:');
+        lines.push('');
+        lines.push('| `./dev` factory | Real import path | Config needed |');
+        lines.push('|-----------------|------------------|---------------|');
+        lines.push('| `createPgClient()` | `@objectifthunes/sandstone-sdk/pg` | `{ connectionString: process.env.DATABASE_URL! }` |');
+        lines.push('| `createPinoLogger()` | `@objectifthunes/sandstone-sdk/pino` | `{ level: process.env.LOG_LEVEL ?? \'info\' }` |');
+        lines.push('| `createJoseSigner()` | `@objectifthunes/sandstone-sdk/jose` | `{ secret: process.env.JWT_SECRET! }` |');
+        lines.push('| `createNodemailerTransport()` | `@objectifthunes/sandstone-sdk/nodemailer` | SMTP options or swap for `resend` |');
+        lines.push('');
+        lines.push('### 2. Add environment variables');
+        lines.push('');
+        lines.push('Copy `.env.example` and add the required values:');
+        lines.push('');
+        lines.push('```sh');
+        lines.push('DATABASE_URL=postgresql://postgres:postgres@localhost:5432/' + config.name);
+        lines.push('JWT_SECRET=change-me-to-a-random-secret-at-least-32-chars');
+        lines.push('# plus any email / payment / storage keys');
+        lines.push('```');
+        lines.push('');
+        lines.push('### 3. Add docker-compose for Postgres');
+        lines.push('');
+        lines.push('Create a `docker-compose.yml` for local development:');
+        lines.push('');
+        lines.push('```yaml');
+        lines.push('services:');
+        lines.push('  postgres:');
+        lines.push('    image: postgres:16-alpine');
+        lines.push('    ports:');
+        lines.push("      - '5432:5432'");
+        lines.push('    environment:');
+        lines.push(`      POSTGRES_DB: ${config.name}`);
+        lines.push('      POSTGRES_USER: postgres');
+        lines.push('      POSTGRES_PASSWORD: postgres');
+        lines.push('    volumes:');
+        lines.push('      - pgdata:/var/lib/postgresql/data');
+        lines.push('volumes:');
+        lines.push('  pgdata:');
+        lines.push('```');
+        lines.push('');
+        lines.push('Then run `docker compose up -d` before `npm run dev`.');
+        lines.push('');
+    }
+    // Custom Adapters
+    lines.push('## Custom Adapters');
+    lines.push('');
+    lines.push('The SDK defines port interfaces (contracts) for every infrastructure concern. You can build a custom adapter for any port by implementing the interface and swapping it in `src/infrastructure.ts`.');
+    lines.push('');
+    lines.push('### Port Interfaces');
+    lines.push('');
+    lines.push('| Port | Interface | Methods |');
+    lines.push('|------|-----------|---------|');
+    lines.push('| Database | `DatabaseClient` | `query(text, values?)`, `transaction(fn)`, `healthCheck()`, `close()`, `getPoolStats?()` |');
+    lines.push('| Logging | `Logger` | `info(msg, data?)`, `warn(msg, data?)`, `error(msg, data?)`, `debug(msg, data?)`, `child(bindings)` |');
+    lines.push('| Tokens | `TokenSigner` | `sign(payload, expiresIn)`, `verify(token)`, `signPair(payload, accessTTL, refreshTTL)` |');
+    lines.push('| Email | `EmailTransport` | `send(message)` |');
+    lines.push('| Payments | `PaymentProvider` | `customers.create/get/update/delete`, `subscriptions.create/get/cancel/listByCustomer`, `invoices.get/listByCustomer`, `webhooks.verify` |');
+    lines.push('| Storage | `StorageProvider` | `upload(params)`, `download(key)`, `delete(key)`, `getSignedUrl(key, expiresIn)`, `exists(key)` |');
+    lines.push('| Cache | `CacheProvider` | `get(key)`, `set(key, value, ttl?)`, `delete(key)`, `flush()`, `increment(key, ttl?)` |');
+    lines.push('| Passwords | `PasswordHasher` | `hash(password)`, `verify(password, hash)` |');
+    lines.push('| OAuth | `OAuthProvider` | `getAuthUrl(params)`, `handleCallback(params)` |');
+    lines.push('| SMS | `SmsTransport` | `send(message)` |');
+    lines.push('| Push | `PushTransport` | `send(token, payload)`, `sendMany(tokens, payload)` |');
+    lines.push('| Realtime | `RealtimeProvider` | `publish(channel, event, data)`, `getChannels()`, `getSubscriberCount(channel)` |');
+    lines.push('| Search | `SearchProvider` | `index(indexName, documents)`, `search(indexName, query, options?)`, `delete(indexName, ids)` |');
+    lines.push('| Queue | `QueueProvider` | `enqueue(queue, payload, options?)`, `process(queue, handler)`, `getJob(id)`, `cancel(id)` |');
+    lines.push('| Feature Flags | `FeatureFlagProvider` | `isEnabled(flag, context?)`, `getValue(flag, default, context?)`, `getAllFlags(context?)` |');
+    lines.push('| Tracing | `Tracer` | `startSpan(name, options?)`, `withSpan(name, fn)` |');
+    lines.push('| Authorization | `AuthorizationProvider` | `can(subject, action, resource)`, `authorize(...)`, `grant(...)`, `revoke(...)`, `listPermissions(subject)` |');
+    lines.push('| Audit | `AuditLogger` | `log(entry)`, `query(filters)`, `count(filters)` |');
+    lines.push('');
+    lines.push('### The Pattern');
+    lines.push('');
+    lines.push('1. Import the port type: `import type { EmailTransport } from \'@objectifthunes/sandstone-sdk\'`');
+    lines.push('2. Write a factory function that returns an object implementing the interface');
+    lines.push('3. Swap it into `src/infrastructure.ts`');
+    lines.push('');
+    lines.push('### Example: Custom Email Adapter (SendGrid)');
+    lines.push('');
+    lines.push('```ts');
+    lines.push('// src/adapters/sendgrid.ts');
+    lines.push("import type { EmailTransport, EmailMessage } from '@objectifthunes/sandstone-sdk';");
+    lines.push('');
+    lines.push('export function createSendGridTransport(apiKey: string): EmailTransport {');
+    lines.push('  return {');
+    lines.push('    async send(message: EmailMessage) {');
+    lines.push("      const response = await fetch('https://api.sendgrid.com/v3/mail/send', {");
+    lines.push("        method: 'POST',");
+    lines.push('        headers: {');
+    lines.push('          Authorization: `Bearer ${apiKey}`,');
+    lines.push("          'Content-Type': 'application/json',");
+    lines.push('        },');
+    lines.push('        body: JSON.stringify({');
+    lines.push('          personalizations: [{');
+    lines.push("            to: (Array.isArray(message.to) ? message.to : [message.to]).map(e => ({ email: e })),");
+    lines.push('          }],');
+    lines.push("          from: { email: message.from ?? 'noreply@example.com' },");
+    lines.push('          subject: message.subject,');
+    lines.push("          content: [{ type: 'text/html', value: message.html }],");
+    lines.push('        }),');
+    lines.push('      });');
+    lines.push('');
+    lines.push('      if (!response.ok) {');
+    lines.push('        throw new Error(`SendGrid error: ${response.status}`);');
+    lines.push('      }');
+    lines.push('');
+    lines.push("      return { messageId: response.headers.get('x-message-id') ?? crypto.randomUUID() };");
+    lines.push('    },');
+    lines.push('  };');
+    lines.push('}');
+    lines.push('```');
+    lines.push('');
+    lines.push('Then in `src/infrastructure.ts`:');
+    lines.push('');
+    lines.push('```ts');
+    lines.push("import { createSendGridTransport } from './adapters/sendgrid.js';");
+    lines.push('');
+    lines.push('const app = await createApp({');
+    lines.push('  db,');
+    lines.push('  logger,');
+    lines.push('  tokens,');
+    lines.push('  email: {');
+    lines.push('    transport: createSendGridTransport(process.env.SENDGRID_API_KEY!),');
+    lines.push("    defaultFrom: 'noreply@myapp.com',");
+    lines.push('  },');
+    lines.push('});');
+    lines.push('```');
+    lines.push('');
+    lines.push('Full guide with every port interface: https://maxoujs.github.io/sandstone-sdk/guides/custom-adapters/');
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=claude-md.js.map