@lssm/app.cli-contractspec 0.0.0-canary-20251221165922 → 0.0.0-canary-20251221185840

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 0.0.0-canary-20251221165922
+## 0.0.0-canary-20251221185840
 
 ### Minor Changes
 
@@ -9,14 +9,14 @@
 ### Patch Changes
 
 - Updated dependencies [66a5dfd]
-  - @lssm/bundle.contractspec-workspace@0.0.0-canary-20251221165922
-  - @lssm/lib.ai-providers@0.0.0-canary-20251221165922
-  - @lssm/lib.contracts@0.0.0-canary-20251221165922
-  - @lssm/lib.contracts-transformers@0.0.0-canary-20251221165922
-  - @lssm/lib.schema@0.0.0-canary-20251221165922
-  - @lssm/lib.testing@0.0.0-canary-20251221165922
-  - @lssm/module.ai-chat@0.0.0-canary-20251221165922
-  - @lssm/module.contractspec-examples@0.0.0-canary-20251221165922
+  - @lssm/bundle.contractspec-workspace@0.0.0-canary-20251221185840
+  - @lssm/lib.ai-providers@0.0.0-canary-20251221185840
+  - @lssm/lib.contracts@0.0.0-canary-20251221185840
+  - @lssm/lib.contracts-transformers@0.0.0-canary-20251221185840
+  - @lssm/lib.schema@0.0.0-canary-20251221185840
+  - @lssm/lib.testing@0.0.0-canary-20251221185840
+  - @lssm/module.ai-chat@0.0.0-canary-20251221185840
+  - @lssm/module.contractspec-examples@0.0.0-canary-20251221185840
 
 ## 0.12.0
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/app.cli-contractspec",
-  "version": "0.0.0-canary-20251221165922",
+  "version": "0.0.0-canary-20251221185840",
   "description": "CLI tool for creating, building, and validating contract specifications",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,14 +34,14 @@
     "@ai-sdk/mistral": "beta",
     "@ai-sdk/openai": "beta",
     "ollama-ai-provider": "^1.2.0",
-    "@lssm/bundle.contractspec-workspace": "0.0.0-canary-20251221165922",
-    "@lssm/lib.ai-providers": "0.0.0-canary-20251221165922",
-    "@lssm/lib.contracts": "0.0.0-canary-20251221165922",
-    "@lssm/lib.contracts-transformers": "0.0.0-canary-20251221165922",
-    "@lssm/lib.testing": "0.0.0-canary-20251221165922",
-    "@lssm/lib.schema": "0.0.0-canary-20251221165922",
-    "@lssm/module.ai-chat": "0.0.0-canary-20251221165922",
-    "@lssm/module.contractspec-examples": "0.0.0-canary-20251221165922",
+    "@lssm/bundle.contractspec-workspace": "0.0.0-canary-20251221185840",
+    "@lssm/lib.ai-providers": "0.0.0-canary-20251221185840",
+    "@lssm/lib.contracts": "0.0.0-canary-20251221185840",
+    "@lssm/lib.contracts-transformers": "0.0.0-canary-20251221185840",
+    "@lssm/lib.testing": "0.0.0-canary-20251221185840",
+    "@lssm/lib.schema": "0.0.0-canary-20251221185840",
+    "@lssm/module.ai-chat": "0.0.0-canary-20251221185840",
+    "@lssm/module.contractspec-examples": "0.0.0-canary-20251221185840",
     "glob": "^13.0.0",
     "commander": "^14.0.2",
     "@inquirer/prompts": "^8.1.0",
@@ -51,8 +51,8 @@
     "zod": "^4.1.13"
   },
   "devDependencies": {
-    "@lssm/tool.tsdown": "0.0.0-canary-20251221165922",
-    "@lssm/tool.typescript": "0.0.0-canary-20251221165922",
+    "@lssm/tool.tsdown": "0.0.0-canary-20251221185840",
+    "@lssm/tool.typescript": "0.0.0-canary-20251221185840",
     "@types/node": "^22.10.2",
     "rimraf": "^6.1.2",
     "eslint": "^9.39.2"

package/AGENT_MODES.md

@@ -1,247 +0,0 @@
-# AI Agent Modes
-
-The contracts-cli supports multiple AI agent modes for code generation and validation. Each mode offers different capabilities and trade-offs.
-
-## Available Agent Modes
-
-### 1. Simple Mode (Default)
-- **Mode**: `simple`
-- **Description**: Direct LLM API calls for code generation
-- **Best For**: Quick prototyping, basic implementations
-- **Requirements**: API key for your chosen provider (Claude, OpenAI, Ollama)
-- **Speed**: Fast
-- **Quality**: Good baseline quality
-
-**Example:**
-```bash
-contractspec build spec.contracts.ts --agent-mode simple
-```
-
-### 2. Cursor Agent Mode
-- **Mode**: `cursor`
-- **Description**: Leverages Windsurf/Cursor's agentic capabilities
-- **Best For**: Complex implementations, iterative development
-- **Requirements**: Running in Windsurf/Cursor environment
-- **Speed**: Moderate
-- **Quality**: High quality with context awareness
-
-**Example:**
-```bash
-contractspec build spec.contracts.ts --agent-mode cursor
-```
-
-**Note**: This mode requires Windsurf/Cursor CLI access. If not available, falls back to simple mode.
-
-### 3. Claude Code Mode
-- **Mode**: `claude-code`
-- **Description**: Uses Anthropic's Claude with extended thinking for code generation
-- **Best For**: Production-quality code, complex logic, thorough validation
-- **Requirements**: `ANTHROPIC_API_KEY` environment variable
-- **Speed**: Moderate to slow
-- **Quality**: Very high quality, excellent for validation
-
-**Features:**
-- Extended context understanding
-- Detailed code review capabilities
-- Comprehensive validation reports
-- Best for critical implementations
-
-**Example:**
-```bash
-export ANTHROPIC_API_KEY=your_key
-contractspec build spec.contracts.ts --agent-mode claude-code
-```
-
-### 4. OpenAI Codex Mode
-- **Mode**: `openai-codex`
-- **Description**: Uses OpenAI's GPT-4o and o1 models for code generation
-- **Best For**: Complex algorithms, optimization tasks
-- **Requirements**: `OPENAI_API_KEY` environment variable
-- **Speed**: Fast (GPT-4o) to slow (o1 reasoning)
-- **Quality**: High quality, excellent for algorithmic problems
-
-**Features:**
-- Automatically selects o1 for complex tasks
-- Uses GPT-4o for standard generation
-- Strong at optimization and algorithms
-
-**Example:**
-```bash
-export OPENAI_API_KEY=your_key
-contractspec build spec.contracts.ts --agent-mode openai-codex
-```
-
-## Configuring Agent Modes
-
-### Via Configuration File
-
-Add to `.contractsrc.json`:
-
-```json
-{
-  "aiProvider": "claude",
-  "agentMode": "claude-code",
-  "aiModel": "claude-3-7-sonnet-20250219"
-}
-```
-
-### Via Environment Variables
-
-```bash
-export CONTRACTSPEC_AGENT_MODE=claude-code
-export CONTRACTSPEC_AI_PROVIDER=claude
-export ANTHROPIC_API_KEY=your_key
-```
-
-### Via CLI Options
-
-```bash
-contractspec build spec.ts --agent-mode claude-code --provider claude
-```
-
-## Agent Mode Comparison
-
-| Feature | Simple | Cursor | Claude Code | OpenAI Codex |
-|---------|--------|--------|-------------|--------------|
-| Speed | ⚡⚡⚡ | ⚡⚡ | ⚡⚡ | ⚡⚡⚡ |
-| Quality | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
-| Validation | Basic | Good | Excellent | Good |
-| Setup | Easy | Moderate | Easy | Easy |
-| Cost | Low | N/A | Moderate | Low-Moderate |
-
-## Fallback Behavior
-
-The CLI automatically falls back to simpler modes if the primary mode fails:
-
-1. **cursor** → **claude-code** → **openai-codex** → **simple**
-2. **claude-code** → **openai-codex** → **simple**
-3. **openai-codex** → **simple**
-4. **simple** → Basic templates (no AI)
-
-## Usage Examples
-
-### Build with Agent Mode
-
-```bash
-# Use Claude Code for high-quality generation
-contractspec build user.contracts.ts --agent-mode claude-code
-
-# Use OpenAI for algorithmic code
-contractspec build optimizer.contracts.ts --agent-mode openai-codex
-
-# Disable AI entirely
-contractspec build simple.contracts.ts --no-agent
-```
-
-### Validate with Agent Mode
-
-```bash
-# Validate implementation with AI
-contractspec validate user.contracts.ts --check-implementation --agent-mode claude-code
-
-# Interactive validation
-contractspec validate user.contracts.ts -i --agent-mode claude-code
-
-# Specify implementation path
-contractspec validate user.contracts.ts \
-  --check-implementation \
-  --implementation-path ./handlers/user.handler.ts \
-  --agent-mode claude-code
-```
-
-## Best Practices
-
-### For Development
-- Use **simple** mode for rapid iteration
-- Use **cursor** mode if working in Windsurf/Cursor
-
-### For Production
-- Use **claude-code** for critical implementations
-- Always validate with `--check-implementation`
-- Review AI-generated code before committing
-
-### For Complex Logic
-- Use **openai-codex** for algorithmic problems
-- Use **claude-code** for comprehensive validation
-
-### For CI/CD
-- Use **simple** mode for speed
-- Configure via environment variables
-- Set up validation in pre-commit hooks
-
-## Troubleshooting
-
-### Agent Mode Not Working
-
-Check:
-1. API keys are set correctly
-2. Network connectivity to AI providers
-3. Provider quotas and rate limits
-
-### Fallback to Simple Mode
-
-This happens when:
-- API key is missing
-- Provider is unavailable
-- Agent cannot handle the task
-
-The CLI will show warnings explaining why.
-
-### Poor Quality Output
-
-Try:
-1. Using a more powerful agent mode
-2. Adding more context to your spec
-3. Reviewing and refining the spec structure
-
-## Environment Variables Reference
-
-```bash
-# Provider selection
-CONTRACTSPEC_AI_PROVIDER=claude|openai|ollama|custom
-
-# Agent mode
-CONTRACTSPEC_AGENT_MODE=simple|cursor|claude-code|openai-codex
-
-# Model selection
-CONTRACTSPEC_AI_MODEL=claude-3-7-sonnet-20250219
-
-# API Keys
-ANTHROPIC_API_KEY=your_anthropic_key
-OPENAI_API_KEY=your_openai_key
-
-# Custom endpoints
-CONTRACTSPEC_LLM_ENDPOINT=https://your-custom-endpoint
-CONTRACTSPEC_LLM_API_KEY=your_custom_key
-```
-
-## Advanced Configuration
-
-### Custom Agent Priorities
-
-You can configure fallback priorities in `.contractsrc.json`:
-
-```json
-{
-  "agentMode": "claude-code",
-  "aiProvider": "claude",
-  "aiModel": "claude-3-7-sonnet-20250219",
-  "outputDir": "./src",
-  "defaultOwners": ["@team"],
-  "defaultTags": ["auto-generated"]
-}
-```
-
-### Multi-Model Strategy
-
-Use different models for different tasks:
-
-```bash
-# Use Claude for generation
-contractspec build spec.ts --agent-mode claude-code
-
-# Use OpenAI for validation
-contractspec validate spec.ts \
-  --check-implementation \
-  --agent-mode openai-codex
-```

package/QUICK_REFERENCE.md

@@ -1,209 +0,0 @@
-# Quick Reference Guide
-
-## New Commands Overview
-
-```bash
-# Discovery & Management
-contractspec list                           # List all contracts
-contractspec list --type operation         # Filter contracts
-contractspec list --pattern 'src/**/*.ts'  # Custom discovery pattern
-contractspec list --deep                   # Load spec modules (richer metadata)
-contractspec deps                          # Analyze dependencies
-contractspec deps --circular               # Find circular deps
-contractspec deps --format dot > deps.dot  # GraphViz dot output
-
-# Development Workflow
-contractspec watch --build                # Auto-build on changes
-contractspec watch --validate             # Auto-validate on changes
-contractspec watch --on-start both         # Run on startup too
-contractspec watch --continue-on-error     # Keep watching even on failures
-
-# Maintenance & Comparison
-contractspec clean                        # Clean generated files
-contractspec clean --dry-run              # Preview cleanup
-contractspec diff spec1.ts spec2.ts       # Compare specs
-contractspec diff spec.ts spec.ts --baseline main  # Compare with git baseline
-contractspec sync                         # Build all discovered specs
-contractspec sync --buckets api,ui        # Repeat builds into ./generated/<bucket>/
-
-# Validation & Testing
-contractspec validate '**/*.ts'           # Validate all specs
-contractspec validate spec.ts --check-implementation
-```
-
-## Agent Modes at a Glance
-
-```bash
-# Simple (default) - Fast, basic quality
-contractspec build spec.ts
-
-# Claude Code - Best quality, production-ready
-contractspec build spec.ts --agent-mode claude-code
-
-# OpenAI Codex - Best for algorithms
-contractspec build spec.ts --agent-mode openai-codex
-
-# Cursor - IDE-integrated (Windsurf/Cursor)
-contractspec build spec.ts --agent-mode cursor
-
-# No AI - Templates only
-contractspec build spec.ts --no-agent
-```
-
-## Build Examples
-
-```bash
-# Basic build
-contractspec build user.contracts.ts
-# (Falls back to templates automatically if the requested agent is unavailable)
-
-# Production build with tests
-contractspec build user.contracts.ts --agent-mode claude-code
-
-# Fast build without tests
-contractspec build user.contracts.ts --no-tests
-
-# Custom output directory
-contractspec build user.contracts.ts -o ./src/handlers
-```
-
-## Validation Examples
-
-```bash
-# Validate spec only
-contractspec validate user.contracts.ts
-
-# Validate implementation with AI
-contractspec validate user.contracts.ts --check-implementation
-
-# Interactive validation
-contractspec validate user.contracts.ts -i
-
-# Default prompt (no flags): choose spec-only vs spec+implementation
-contractspec validate user.contracts.ts
-
-# Validate with specific implementation
-contractspec validate user.contracts.ts \
-  --check-implementation \
-  --implementation-path ./handlers/user.handler.ts \
-  --agent-mode claude-code
-```
-
-## Configuration
-
-### Minimal .contractsrc.json
-```json
-{
-  "aiProvider": "claude",
-  "agentMode": "claude-code",
-  "outputDir": "./src"
-}
-```
-
-### Environment Variables
-```bash
-# Required for Claude
-export ANTHROPIC_API_KEY=sk-ant-...
-
-# Required for OpenAI
-export OPENAI_API_KEY=sk-...
-
-# Agent mode (optional)
-export CONTRACTSPEC_AGENT_MODE=claude-code
-```
-
-## Common Workflows
-
-### Development Flow
-```bash
-# 1. Create spec
-contractspec create --type operation --ai
-
-# 2. Generate implementation
-contractspec build spec.contracts.ts --agent-mode claude-code
-
-# 3. Validate
-contractspec validate spec.contracts.ts --check-implementation
-```
-
-### CI/CD Flow
-```bash
-# Fast validation in CI
-contractspec validate '**/*.contracts.ts' --agent-mode simple
-
-# Validate implementations (skip prompt)
-contractspec validate '**/*.contracts.ts' --check-implementation
-```
-
-### Multi-Provider Strategy
-```bash
-# Draft with local model (free)
-contractspec create --ai --provider ollama
-
-# Build with Claude (quality)
-contractspec build spec.ts --agent-mode claude-code
-
-# Validate with OpenAI (cost-effective)
-contractspec validate spec.ts --check-implementation --agent-mode openai-codex
-```
-
-## Troubleshooting
-
-### AI Not Working
-```bash
-# Check API key
-echo $ANTHROPIC_API_KEY
-
-# Use simple mode as fallback
-contractspec build spec.ts --agent-mode simple
-
-# Disable AI completely
-contractspec build spec.ts --no-agent
-```
-
-### Wrong Implementation Path
-```bash
-# Specify path explicitly
-contractspec validate spec.contracts.ts \
-  --check-implementation \
-  --implementation-path ./custom/path/handler.ts
-```
-
-### Slow Generation
-```bash
-# Use faster agent mode
-contractspec build spec.ts --agent-mode simple
-
-# Skip tests
-contractspec build spec.ts --no-tests
-```
-
-## Best Practices
-
-✅ **DO:**
-- Use `claude-code` for production implementations
-- Validate with `--check-implementation` before committing
-- Set agent mode in `.contractsrc.json` for consistency
-- Use environment variables for API keys
-
-❌ **DON'T:**
-- Commit AI-generated code without review
-- Use expensive agents in CI/CD unnecessarily
-- Store API keys in `.contractsrc.json`
-- Skip validation for critical code
-
-## Performance Tips
-
-| Task | Recommended Agent | Speed | Quality |
-|------|------------------|-------|---------|
-| Prototyping | simple | ⚡⚡⚡ | ⭐⭐⭐ |
-| Production | claude-code | ⚡⚡ | ⭐⭐⭐⭐⭐ |
-| Algorithms | openai-codex | ⚡⚡⚡ | ⭐⭐⭐⭐ |
-| CI/CD | simple | ⚡⚡⚡ | ⭐⭐⭐ |
-| Validation | claude-code | ⚡⚡ | ⭐⭐⭐⭐⭐ |
-
-## More Information
-
-- Full documentation: [README.md](./README.md)
-- Agent modes guide: [AGENT_MODES.md](./AGENT_MODES.md)
-- Quick start: [QUICK_START.md](./QUICK_START.md)

package/QUICK_START.md

@@ -1,174 +0,0 @@
-# Quick Start Guide
-
-Get started with contracts-cli in 5 minutes.
-
-## Installation
-
-```bash
-cd packages/lssm/tools/contracts-cli
-pnpm install
-pnpm build
-```
-
-## First Spec
-
-### 1. Create a spec interactively
-
-```bash
-pnpm exec contractspec create
-```
-
-Follow the prompts:
-- Choose "Operation (Command/Query)"
-- Select "Command"
-- Name: `user.signup`
-- Fill in description, goal, context
-- Set auth to `anonymous`
-- Add owners: `@team`
-
-This creates: `src/interactions/commands/user-signup.contracts.ts`
-
-### 2. Or use AI assistance
-
-```bash
-export ANTHROPIC_API_KEY=your-key-here
-pnpm exec contractspec create --ai
-```
-
-Describe what you want:
-> "Create a command for user signup that takes an email and sends a magic link"
-
-Review and accept the AI-generated spec!
-
-### 3. Generate handler
-
-```bash
-pnpm exec contractspec build src/interactions/commands/user-signup.contracts.ts
-```
-
-This generates:
-- `src/handlers/user-signup.handler.ts` - Implementation stub
-- `src/handlers/user-signup.handler.test.ts` - Tests
-
-### 4. Validate
-
-```bash
-pnpm exec contractspec validate src/interactions/commands/user-signup.contracts.ts
-# You'll be prompted to validate the spec only or the implementation as well.
-```
-
-## Using Local Models (Free!)
-
-### Install Ollama
-
-```bash
-# macOS
-brew install ollama
-
-# Start Ollama
-ollama serve
-
-# Pull a model
-ollama pull codellama
-```
-
-### Generate with Ollama
-
-```bash
-pnpm exec contractspec create --ai --provider ollama --model codellama
-```
-
-No API keys needed! Everything runs locally.
-
-## Configuration
-
-Create `.contractsrc.json` in your project root:
-
-```json
-{
-  "aiProvider": "claude",
-  "outputDir": "./src",
-  "defaultOwners": ["@my-team"],
-  "conventions": {
-    "operations": "interactions/commands|queries",
-    "events": "events"
-  }
-}
-```
-
-Now commands use these defaults:
-
-```bash
-# Uses Claude from config
-pnpm exec contractspec create --ai
-
-# Override with Ollama
-pnpm exec contractspec create --ai --provider ollama
-```
-
-## Next Steps
-
-1. **Complete the TODO items** in generated files
-2. **Implement handler logic** with real business rules
-3. **Run tests**: `pnpm test`
-4. **Validate**: `pnpm exec contractspec validate src/**/*.contracts.ts`
-5. **Register in registry** and mount REST/GraphQL adapters
-
-## Common Workflows
-
-### Create Event
-
-```bash
-pnpm exec contractspec create --type event
-```
-
-### Build Presentation Component
-
-```bash
-pnpm exec contractspec create --type presentation
-pnpm exec contractspec build src/presentations/user-profile.presentation.ts
-```
-
-### Multi-Spec Workflow
-
-```bash
-# Create operation spec
-pnpm exec contractspec create --type operation --ai
-
-# Create related event spec
-pnpm exec contractspec create --type event --ai
-
-# Generate all implementations
-pnpm exec contractspec build src/contracts/**/*.ts
-```
-
-## Tips
-
-- Use `--ai` for faster spec creation
-- Use Ollama for free local generation
-- Use Claude/GPT-4 for production-quality code
-- Always validate before committing
-- Keep specs close to implementations
-
-## Troubleshooting
-
-**No AI provider?**
-```bash
-# Use interactive wizard instead
-pnpm exec contractspec create
-```
-
-**Can't find contractspec?**
-```bash
-# Use pnpm exec
-pnpm exec contractspec --help
-```
-
-**Import errors?**
-```bash
-# Install dependencies
-pnpm add @lssm/lib.contracts @lssm/lib.schema
-```
-
-Happy contract authoring! 🎉
-