Contract Hub CLI

AI-driven project contract management for design systems and API contracts.

Why Contract Hub?

When using AI coding tools (Cursor, OpenCode, v0), you may encounter these problems:

| Problem | Cause | Solution | |---------|-------|----------| | New pages look different from existing ones | AI lacks design context | Capture design tokens into contract | | API field naming is inconsistent | No unified API convention | Capture API contract | | AI "forgets" project style | Limited context window | Contract as persistent memory | | Frontend/Backend mismatch | No shared contract | Single source of truth |

Core Concept: AI writes -> AI reads -> AI stays consistent

┌─────────────────────────────────────────────────────────────┐
│                    Contract Hub Flow                         │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   [Existing Code]                                            │
│         │                                                    │
│         ▼                                                    │
│   ┌───────────┐    contract update     ┌──────────────┐     │
│   │    AI     │ ──────────────────────▶│  .contract/  │     │
│   │ (Capture) │                        │              │     │
│   └───────────┘                        │ design.json  │     │
│                                        │ api.json     │     │
│   ┌───────────┐    contract get        │ samples/     │     │
│   │    AI     │ ◀──────────────────────│              │     │
│   │  (Apply)  │                        └──────────────┘     │
│   └───────────┘                                              │
│         │                                                    │
│         ▼                                                    │
│   [New Code - Consistent Style]                              │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Installation

npm install -g contract-hub-cli

Quick Start

Step 1: Initialize

cd your-project
contract init --name "My App"

Step 2: Capture Design (Let AI analyze existing pages)

In your AI tool (Cursor/OpenCode/v0), say:

Analyze src/app/dashboard/page.tsx, extract the design tokens (colors, spacing, typography, animations), and save to contract using contract update design --data '{...}'

AI will analyze the code and run:

contract update design --data '{
  "colors": {
    "primary": { "value": "#3B82F6", "usage": "buttons, links" },
    "background": { "value": "#F9FAFB", "usage": "page background" }
  },
  "spacing": { "unit": "4px", "scale": [1, 2, 4, 6, 8] },
  "motions": [
    { "name": "fadeIn", "duration": "200ms", "easing": "ease-out" }
  ]
}'

Step 3: Save Golden Sample

Save dashboard page as a golden sample

contract update sample --name dashboard --file src/app/dashboard/page.tsx

Step 4: Capture API Contract

Analyze the API routes and save the contract

contract update api --data '{
  "conventions": {
    "baseUrl": "/api",
    "naming": { "url": "kebab-case", "fields": "camelCase" }
  },
  "endpoints": [
    { "method": "GET", "path": "/users", "response": "User[]" }
  ]
}'

Step 5: Export Config for Your AI Tool

contract export opencode   # Generate .opencode.yaml
contract export cursor     # Generate .cursorrules

Step 6: Create New Pages (AI reads contract)

Now when you say:

Create a user settings page

AI will:

1. contract get design - Read design tokens
2. contract get sample dashboard - Reference golden sample
3. Generate code that matches your project style!

Commands

contract init

Initialize the contract directory structure.

contract init
contract init --id=proj_abc123  # Specify project ID
contract init --name="My App"    # Specify project name
contract init --force            # Reinitialize

Creates:

.contract/
├── contract.json      # Project metadata
├── design.json        # Design tokens (AI fills this)
├── api.json           # API contract (AI fills this)
├── rules.md           # Development rules
└── samples/           # Golden sample code

contract get [section]

Get contract content (for AI or scripts to read).

contract get              # Get full contract
contract get design       # Get design system
contract get api          # Get API contract
contract get rules        # Get development rules
contract get samples      # List golden samples
contract get samples/dashboard  # Get specific sample

contract export <target>

Export configuration for AI tools.

contract export cursor    # Generate .cursorrules
contract export opencode  # Generate .opencode.yaml
contract export v0        # Generate .v0rules

contract info

Show contract status.

contract info

Output:

Contract Hub
────────────────────────────
ID:       proj_abc123
Name:     My SaaS App
Version:  1.0.0

Design:   ✓ 5 colors, 4 motions, 3 components
API:      ✓ 12 endpoints, 8 types
Rules:    ✓ 15 rules defined
Samples:  ✓ 3 golden samples

contract update <section>

Update contract section. AI uses this to write captured design/API.

# Update design system (merge by default)
contract update design --data '{"colors":{"primary":{"value":"#3B82F6"}}}'

# Update from file
contract update design --file extracted-design.json

# Replace instead of merge
contract update api --file new-api.json --no-merge

# Append rules
contract update rules --data "## New Rule\n- Always use semantic HTML"

# Add/update a golden sample
contract update sample --name dashboard --file src/app/dashboard/page.tsx

# Read from stdin (useful for AI piping)
cat extracted.json | contract update design

contract set <section> <path> <value>

Set a specific field using dot notation.

# Set a single color
contract set design "colors.primary.value" "#3B82F6"

# Set API base URL
contract set api "conventions.baseUrl" "/api/v2"

# Set nested object
contract set design "spacing.unit" "4px"

contract delete <type> <name>

Delete a contract item.

# Delete a golden sample
contract delete sample old-dashboard

AI Workflow

Capturing Design

Tell AI:

"Analyze the dashboard page style and save to contract"

AI will:

1. Read /app/dashboard/page.tsx
2. Extract colors, spacing, typography, motions
3. Write to .contract/design.json
4. Save as golden sample

Capturing API

Tell AI:

"Analyze the API routes and save to contract"

AI will:

1. Read API route files
2. Extract endpoints, types, conventions
3. Write to .contract/api.json

Applying Contract

Tell AI:

"Create a user list page"

AI will:

1. Read .contract/design.json for design tokens
2. Read .contract/api.json for API patterns
3. Read .contract/samples/dashboard.tsx for structure reference
4. Generate code that follows the contract

Contract Files

design.json

{
  "colors": {
    "primary": { "value": "#3B82F6", "usage": "Primary buttons" },
    "background": { "value": "#F9FAFB", "usage": "Page background" }
  },
  "motions": [
    { "name": "fadeIn", "duration": "200ms", "css": "opacity 0 → 1" }
  ],
  "components": {
    "button": {
      "primary": "bg-primary text-white rounded-lg px-4 py-2"
    }
  }
}

api.json

{
  "conventions": {
    "baseUrl": "/api",
    "naming": { "url": "kebab-case", "fields": "camelCase" },
    "responseFormat": {
      "success": { "success": true, "data": "<T>" },
      "error": { "success": false, "error": { "code": "...", "message": "..." } }
    }
  },
  "endpoints": [
    { "method": "GET", "path": "/users", "response": "User[]" }
  ],
  "types": {
    "User": { "id": "string", "email": "string", "name": "string" }
  }
}

Integration with AI Tools

OpenCode

After contract export opencode, your .opencode.yaml will include:

• Context files from .contract/
• Skills for capture/apply actions
• Rules derived from your contract

Cursor

After contract export cursor, your .cursorrules will include:

• Design tokens reference
• API conventions
• Golden samples reference
• Development rules

Example: Full Workflow

# 1. Initialize
contract init --name "E-commerce App"

# 2. AI captures design from your best page
# (AI runs this after analyzing code)
contract update design --data '{
  "colors": {
    "primary": { "value": "#8B5CF6", "usage": "CTAs, highlights" },
    "secondary": { "value": "#10B981", "usage": "success states" },
    "background": { "value": "#FAFAFA" },
    "foreground": { "value": "#18181B" }
  },
  "borderRadius": { "sm": "4px", "md": "8px", "lg": "16px" },
  "motions": [
    { "name": "slideUp", "duration": "300ms", "easing": "cubic-bezier(0.4, 0, 0.2, 1)" }
  ],
  "components": {
    "card": "rounded-lg shadow-sm border border-gray-100 p-6",
    "button": {
      "primary": "bg-primary text-white rounded-md px-4 py-2 hover:opacity-90 transition-opacity",
      "secondary": "bg-gray-100 text-gray-900 rounded-md px-4 py-2 hover:bg-gray-200"
    }
  }
}'

# 3. Save golden samples
contract update sample --name product-card --file src/components/ProductCard.tsx
contract update sample --name checkout --file src/app/checkout/page.tsx

# 4. AI captures API contract
contract update api --data '{
  "conventions": {
    "baseUrl": "/api/v1",
    "responseFormat": {
      "success": { "success": true, "data": "T" },
      "error": { "success": false, "error": { "code": "string", "message": "string" } }
    },
    "pagination": { "query": "?page=1&limit=20", "response": { "data": [], "meta": { "page": 1, "total": 100 } } }
  },
  "endpoints": [
    { "method": "GET", "path": "/products", "response": "Product[]" },
    { "method": "GET", "path": "/products/:id", "response": "Product" },
    { "method": "POST", "path": "/cart/items", "body": "{ productId, quantity }", "response": "CartItem" }
  ],
  "types": {
    "Product": { "id": "string", "name": "string", "price": "number", "image": "string" },
    "CartItem": { "id": "string", "product": "Product", "quantity": "number" }
  }
}'

# 5. Export for your AI tool
contract export opencode

# 6. Check status
contract info

Output of contract info:

Contract Hub
────────────────────────────────────
ID:       proj_a1b2c3d4
Name:     E-commerce App
Path:     /Users/dev/ecommerce-app/.contract

Design:   ✓ 4 colors, 1 motion, 2 components
API:      ✓ 3 endpoints, 2 types
Rules:    ✓ Configured
Samples:  ✓ 2 golden samples (product-card, checkout)

Supported AI Tools

| Tool | Export Command | Config File | |------|---------------|-------------| | OpenCode | contract export opencode | .opencode.yaml | | Cursor | contract export cursor | .cursorrules | | v0 | contract export v0 | .v0rules |

License

MIT