@friehub/blueprint 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,122 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - name: System audit
+        run: |
+          node -e "
+            const {loadCatalogFromRoot} = require('./dist/core/load-catalog.js');
+            const {loadAdapters} = require('./dist/core/adapters/load.js');
+            const {validateAdapter} = require('./dist/core/adapters/validate.js');
+
+            async function audit() {
+              let failed = false;
+              const catalog = await loadCatalogFromRoot(process.cwd(), 'loose');
+
+              console.log('Modules:', catalog.value?.modules.length);
+              console.log('Core:', catalog.value?.core.length);
+              console.log('Parse errors:', catalog.issues.filter(i => i.severity === 'error').length);
+
+              const {adapters, errors: loadErrors} = await loadAdapters('./adapters');
+              console.log('Adapters:', adapters.length);
+              console.log('Load errors:', loadErrors.length);
+
+              let validationErrors = 0;
+              for (const adapter of adapters) {
+                const result = validateAdapter(adapter, catalog.value);
+                validationErrors += result.issues.filter(i => i.severity === 'error').length;
+              }
+              console.log('Validation errors:', validationErrors);
+
+              if (catalog.issues.filter(i => i.severity === 'error').length > 0) { console.error('FAIL: parse errors'); failed = true; }
+              if (loadErrors.length > 0) { console.error('FAIL: load errors'); failed = true; }
+              if (validationErrors > 0) { console.error('FAIL: validation errors'); failed = true; }
+              if (catalog.value?.modules.length !== 108) { console.error('FAIL: expect 108 modules, got ' + catalog.value?.modules.length); failed = true; }
+              if (catalog.value?.core.length !== 3) { console.error('FAIL: expect 3 core, got ' + catalog.value?.core.length); failed = true; }
+              if (adapters.length < 82) { console.error('FAIL: expect at least 82 adapters'); failed = true; }
+
+              if (failed) process.exit(1);
+              console.log('AUDIT PASSED');
+            }
+            audit();
+          "
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm test
+
+  integration:
+    runs-on: ubuntu-latest
+    needs: [audit, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - name: Integration test
+        run: |
+          npm run build
+
+          # 1. Select adapters
+          node dist/cli.js adapters add stripe payments
+          node dist/cli.js adapters add redis caching
+          node dist/cli.js adapters add bullmq queues
+
+          # 2. Generate code for selected modules
+          node dist/cli.js generate --lang typescript --module payments --output /tmp/integration
+          node dist/cli.js generate --lang typescript --module caching --output /tmp/integration
+          node dist/cli.js generate --lang typescript --module queues --output /tmp/integration
+
+          # 3. Verify generated files exist
+          test -f /tmp/integration/interfaces/shared.ts || { echo 'FAIL: shared types missing'; exit 1; }
+          test -f /tmp/integration/interfaces/payments.ts || { echo 'FAIL: payments interface missing'; exit 1; }
+          test -f /tmp/integration/adapters/payments/stripe.ts || { echo 'FAIL: stripe adapter missing'; exit 1; }
+          test -f /tmp/integration/adapters/caching/redis.ts || { echo 'FAIL: redis adapter missing'; exit 1; }
+          test -f /tmp/integration/adapters/queues/bullmq.ts || { echo 'FAIL: bullmq adapter missing'; exit 1; }
+
+          # 4. Verify generated adapters implement all contract methods
+          node dist/cli.js verify /tmp/integration/adapters/payments/stripe.ts --module payments
+          node dist/cli.js verify /tmp/integration/adapters/caching/redis.ts --module caching
+          node dist/cli.js verify /tmp/integration/adapters/queues/bullmq.ts --module queues
+
+          # 5. Generate prototype
+          node dist/cli.js prototype --name test-project --output /tmp/test-project
+
+          # 6. Verify prototype files exist
+          test -f /tmp/test-project/package.json || { echo 'FAIL: package.json missing'; exit 1; }
+          test -f /tmp/test-project/tsconfig.json || { echo 'FAIL: tsconfig.json missing'; exit 1; }
+          test -f /tmp/test-project/src/config/adapters.ts || { echo 'FAIL: adapters config missing'; exit 1; }
+
+          # 7. Verify package.json has correct dependencies
+          grep -q "stripe" /tmp/test-project/package.json || { echo 'FAIL: stripe dependency missing'; exit 1; }
+          grep -q "redis" /tmp/test-project/package.json || { echo 'FAIL: redis dependency missing'; exit 1; }
+          grep -q "bullmq" /tmp/test-project/package.json || { echo 'FAIL: bullmq dependency missing'; exit 1; }
+
+          echo "INTEGRATION TESTS PASSED"

package/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+      - name: Publish
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,266 @@
+# Engineering Blueprinter
+
+## A Provider-Agnostic Interface Specification for AI-Assisted Backend Development
+
+Every backend system is an assembly of recurring domain problems: payments, notifications, auth, caching. The implementations differ. The interface does not.
+
+This catalogue defines those interfaces -- function signatures, types, and error contracts for 108 backend domain modules. Each contract is:
+
+- **Provider-agnostic** -- Stripe, Twilio, or S3. Pick any
+- **Language-portable** -- TypeScript types, Rust traits, Python protocols, Go interfaces
+- **AI-consumable** -- no ambiguous prose, just structured data
+- **Versioned** -- semver discipline, adapters declare compatible versions
+
+---
+
+## Why Blueprinter?
+
+| Task | Raw Markdown | Blueprinter |
+|---|---|---|
+| Get module contract | Read 108 `.md` files, parse `→` by eye | `loadCatalog()`, 1 call |
+| Parameter types | Guess from context | `order_id: string`, `amount: number` inferred |
+| Dependencies | Scan prose for "Depends On" | `hardDeps: ["payments", "users"]` resolved |
+| Transitive deps | Trace manually across files | `resolve(["billing"])` walks entire graph |
+| Available providers | Search for "Providers" section | `adapters list payments` shows 3 options |
+| Write types | Manually from scratch | Generated interfaces with full SDK code |
+| Verify completeness | Hope you didn't miss a function | `verify` says "10/10" or "missing: X" |
+| Feed to AI | Paste markdown, hope it parses correctly | `mcp` server, 7 tools, typed JSON over stdio |
+| Project scaffold | Create package.json, tsconfig, dirs | `prototype` generates complete structure |
+
+---
+
+## Quick Start
+
+```bash
+npm install -g engineering-blueprint
+blueprint list
+blueprint inspect billing
+blueprint graph billing
+blueprint resolve --modules billing,payments,users
+```
+
+Or import as a library:
+
+```typescript
+import { loadCatalogFromRoot } from 'engineering-blueprint';
+const catalog = await loadCatalogFromRoot('./contracts');
+```
+
+---
+
+## CLI Reference
+
+### Commands
+
+| Command | Description |
+|---|---|
+| `build` | Load contracts, output catalog.json |
+| `list` | List all modules with deps and adapter status |
+| `search <query>` | Interactive module picker |
+| `inspect <module>` | Full contract for a module |
+| `graph <module>` | ASCII or Mermaid dependency graph |
+| `resolve` | Resolve modules with transitive deps |
+| `adapters` | Manage adapter selections (83 adapters, 35 modules) |
+| `generate` | Generate TypeScript code from contracts |
+| `prototype` | Generate project scaffold with dependencies |
+| `schema` | Export catalog as JSON Schema |
+| `verify <file>` | Check implementation against contract |
+| `implement` | Generate AI prompts for implementation |
+| `mcp` | Start MCP server for AI tools |
+
+### Flags
+
+`--root`, `--strict`, `--output`, `--compact`, `--minimal`, `--quiet`, `--format <ascii|mermaid>`, `--lang <typescript|rust|python|go>`, `--module`, `--modules`, `--name`
+
+---
+
+## Adapter Registry
+
+33 modules with 83 adapters. Bridge between contracts and concrete providers:
+
+| Module | Adapters |
+|---|---|
+| payments | stripe, paystack, adyen |
+| billing | stripe, paddle |
+| subscriptions | stripe, chargebee |
+| emails | resend, sendgrid, mailgun |
+| sms | twilio, vonage |
+| notifications | onesignal, firebase, novu |
+| caching | redis, memcached |
+| storage | s3, gcs, azure-blob |
+| search | algolia, meilisearch, typesense |
+| queues | bullmq, sqs, rabbitmq |
+| auth | clerk, auth0, supertokens |
+| kyc | jumio, onfido |
+| analytics | segment, mixpanel, amplitude |
+| fraud_detection | sift, riskified |
+| error_tracking | sentry, bugsnag |
+| incident_management | pagerduty, opsgenie |
+| trace_query | jaeger, datadog, honeycomb |
+| *and 17 more modules* | |
+
+```bash
+blueprint adapters list
+blueprint adapters add stripe payments
+blueprint adapters verify
+```
+
+---
+
+## Code Generation
+
+Generates TypeScript interfaces, adapter skeletons, and conformance tests from contracts:
+
+```bash
+blueprint generate --lang typescript
+blueprint generate --module billing --lang typescript
+```
+
+Output for payments module:
+
+```typescript
+// generated/interfaces/payments.ts
+export interface PaymentsContract {
+  initiatePayment(orderId: string, amount: number, currency: string, method: string): Promise<Payment>;
+  verifyPayment(paymentId: string): Promise<Payment>;
+  getWallet(userId: string): Promise<Wallet>;
+  // ... 10 functions with inferred types
+}
+
+// generated/adapters/payments/stripe.ts
+import Stripe from 'stripe';
+
+export class StripeAdapter implements PaymentsContract {
+  async initiatePayment(orderId: string, amount: number, currency: string, method: string): Promise<Payment> {
+    const paymentIntent = await this.stripe.paymentIntents.create({
+      amount: Math.round(amount * 100),
+      currency: currency.toLowerCase(),
+      payment_method: method,
+      metadata: { orderId },
+    });
+    return this.toPayment(paymentIntent);
+  }
+  // ... full SDK implementations
+}
+```
+
+Languages supported: TypeScript (full), Rust/Go/Python (planned).
+
+---
+
+## Prototype Generation
+
+Generate a project scaffold with selected adapters and correct dependencies:
+
+```bash
+blueprint adapters add stripe payments
+blueprint adapters add redis caching
+blueprint adapters add bullmq queues
+blueprint prototype --name my-saas
+```
+
+Produces:
+- `package.json` with stripe, redis, bullmq dependencies
+- `tsconfig.json`, `.gitignore`, `.env.example`
+- `src/config/adapters.ts` with working configuration
+- `src/index.ts` with entry point and function list
+
+---
+
+## MCP Server
+
+AI tools (Claude Desktop, Cursor, Copilot) can query the catalog directly via the Model Context Protocol.
+
+**Configuration** -- add to Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "blueprint": {
+      "command": "npx",
+      "args": ["engineering-blueprint", "mcp"]
+    }
+  }
+}
+```
+
+**7 tools exposed:**
+
+| Tool | What it does |
+|---|---|
+| `list_modules` | List all 108 modules with deps |
+| `get_module` | Full contract with functions, types |
+| `search_modules` | Search by name, summary, function |
+| `resolve_deps` | Transitive dependency resolution |
+| `list_adapters` | 83 adapters across 35 modules |
+| `get_adapter` | Adapter details with config |
+| `get_dependency_graph` | Hard/soft deps + reverse deps |
+
+**Start manually:**
+```bash
+blueprint mcp
+# or with a specific root:
+BLUEPRINTER_ROOT=/path/to/project blueprint mcp
+```
+
+---
+
+## Project Structure
+
+```
+engineering-blueprint/
+├── contracts/              # 108 markdown contract files
+│   └── core/               # Global standards, runtime, sagas
+├── adapters/               # 83 YAML adapter definitions
+├── src/
+│   ├── core/               # Parser, resolver, search, adapters
+│   ├── generators/         # Code generation engine
+│   ├── cli.ts              # CLI entrypoint (68 lines)
+│   └── utils/              # Argument parsing
+├── schemas/                # JSON schemas
+├── completions/            # Bash/zsh completions
+└── scripts/                # CI integration tests
+```
+
+---
+
+## Verification
+
+Check that implementations match contracts:
+
+```bash
+blueprint verify ./src/adapters/payments/stripe.ts --module payments
+# All 10 functions implemented. PASS
+```
+
+---
+
+## Production Status
+
+| Check | Result |
+|---|---|
+| 108 contracts parsed | 0 errors, 0 warnings |
+| 83 adapters loaded | 0 errors |
+| Adapter validation | 0 errors, 0 warnings |
+| Tests | 91 passing (58 unit + 25 integration + 8 MCP) |
+| Edge cases | 33 tests covering malformed input, empty state, 50-module chains |
+| CI (Node 18/20/22) | Passing |
+| MCP server | 7 tools, stdio transport |
+| npm publish | On GitHub release |
+
+---
+
+## The Boundary
+
+A module belongs here if:
+
+1. It is a named domain problem (payments, not database transactions)
+2. It recurs across at least three different application types
+3. Its interface is stable across providers
+4. It cannot be trivially derived from a single-table CRUD
+
+The catalogue defines *what* your system does. The prototype generator produces the project structure (*how* you start). Adapter implementations and business logic are yours to write.
+
+---
+
+*Version 0.1.0 -- Production Ready*

package/adapters/analytics/amplitude.yaml

@@ -0,0 +1,44 @@
+name: amplitude
+module: analytics
+version: 1.0.0
+description: Amplitude analytics adapter
+
+implements:
+  - trackEvent
+  - identifyUser
+  - trackPageView
+  - getMetrics
+  - getFunnel
+  - getCohort
+  - getRetention
+
+does_not_implement: []
+
+config:
+  required:
+    - name: api_key
+      type: string
+      description: Amplitude API key
+      secret: false
+    - name: secret_key
+      type: string
+      description: Amplitude secret key
+      secret: true
+  optional:
+    - name: server_url
+      type: string
+      default: https://api.amplitude.com
+      description: Amplitude server URL
+    - name: batch_size
+      type: integer
+      default: 10
+      description: Event batch size
+
+dependencies:
+  - module: audit_log
+    purpose: Log analytics events
+    required: false
+
+metadata:
+  provider_url: https://amplitude.com
+  docs_url: https://docs.amplitude.com

package/adapters/analytics/mixpanel.yaml

@@ -0,0 +1,47 @@
+name: mixpanel
+module: analytics
+version: 1.0.0
+description: Mixpanel analytics adapter
+
+implements:
+  - trackEvent
+  - identifyUser
+  - trackPageView
+  - getMetrics
+  - getFunnel
+  - getCohort
+  - getRetention
+
+does_not_implement: []
+
+config:
+  required:
+    - name: project_token
+      type: string
+      description: Mixpanel project token
+      secret: false
+    - name: secret
+      type: string
+      description: Mixpanel API secret
+      secret: true
+  optional:
+    - name: api_secret
+      type: string
+      description: Mixpanel API secret for data export
+      secret: true
+    - name: service_account_username
+      type: string
+      description: Mixpanel service account username
+    - name: service_account_secret
+      type: string
+      description: Mixpanel service account secret
+      secret: true
+
+dependencies:
+  - module: audit_log
+    purpose: Log analytics events
+    required: false
+
+metadata:
+  provider_url: https://mixpanel.com
+  docs_url: https://docs.mixpanel.com

package/adapters/analytics/segment.yaml

@@ -0,0 +1,40 @@
+name: segment
+module: analytics
+version: 1.0.0
+description: Segment analytics adapter
+
+implements:
+  - trackEvent
+  - identifyUser
+  - trackPageView
+  - getMetrics
+  - getFunnel
+  - getCohort
+  - getRetention
+
+does_not_implement: []
+
+config:
+  required:
+    - name: write_key
+      type: string
+      description: Segment write key
+      secret: true
+  optional:
+    - name: cdn_host
+      type: string
+      default: https://cdn.segment.com
+      description: Segment CDN host
+    - name: flush_interval
+      type: integer
+      default: 1000
+      description: Flush interval in milliseconds
+
+dependencies:
+  - module: audit_log
+    purpose: Log analytics events
+    required: false
+
+metadata:
+  provider_url: https://segment.com
+  docs_url: https://segment.com/docs

package/adapters/auth/auth0.yaml

@@ -0,0 +1,56 @@
+name: auth0
+module: auth
+version: 1.0.0
+description: Auth0 authentication adapter
+
+implements:
+  - signUp
+  - signIn
+  - signInWithProvider
+  - signOut
+  - refreshToken
+  - verifyToken
+  - requestPasswordReset
+  - confirmPasswordReset
+  - verifyEmail
+  - resendVerification
+
+does_not_implement: []
+
+config:
+  required:
+    - name: domain
+      type: string
+      description: Auth0 domain
+      secret: false
+    - name: client_id
+      type: string
+      description: Auth0 client ID
+      secret: false
+    - name: client_secret
+      type: string
+      description: Auth0 client secret
+      secret: true
+    - name: audience
+      type: string
+      description: Auth0 API audience
+      secret: false
+  optional:
+    - name: connection
+      type: string
+      description: Auth0 connection name
+
+dependencies:
+  - module: sessions
+    purpose: Manage user sessions
+    required: true
+  - module: users
+    purpose: User data storage
+    required: true
+  - module: audit_log
+    purpose: Log authentication events
+    required: false
+
+metadata:
+  provider_url: https://auth0.com
+  docs_url: https://auth0.com/docs

package/adapters/auth/clerk.yaml

@@ -0,0 +1,53 @@
+name: clerk
+module: auth
+version: 1.0.0
+description: Clerk authentication adapter
+
+implements:
+  - signUp
+  - signIn
+  - signInWithProvider
+  - signOut
+  - refreshToken
+  - verifyToken
+  - requestPasswordReset
+  - confirmPasswordReset
+  - verifyEmail
+  - resendVerification
+
+does_not_implement: []
+
+config:
+  required:
+    - name: publishable_key
+      type: string
+      description: Clerk publishable key
+      secret: false
+    - name: secret_key
+      type: string
+      description: Clerk secret key
+      secret: true
+    - name: frontend_api
+      type: string
+      description: Clerk frontend API URL
+      secret: false
+  optional:
+    - name: jwt_key
+      type: string
+      description: Clerk JWT key for token verification
+      secret: true
+
+dependencies:
+  - module: sessions
+    purpose: Manage user sessions
+    required: true
+  - module: users
+    purpose: User data storage
+    required: true
+  - module: audit_log
+    purpose: Log authentication events
+    required: false
+
+metadata:
+  provider_url: https://clerk.com
+  docs_url: https://clerk.com/docs