contractspec 1.52.0 → 1.53.0

package/AGENT_MODES.md

@@ -5,6 +5,7 @@ The contracts-cli supports multiple AI agent modes for code generation and valid
 ## Available Agent Modes
 
 ### 1. Simple Mode (Default)
+
 - **Mode**: `simple`
 - **Description**: Direct LLM API calls for code generation
 - **Best For**: Quick prototyping, basic implementations
@@ -13,11 +14,13 @@ The contracts-cli supports multiple AI agent modes for code generation and valid
 - **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
@@ -26,6 +29,7 @@ contractspec build spec.contracts.ts --agent-mode simple
 - **Quality**: High quality with context awareness
 
 **Example:**
+
 ```bash
 contractspec build spec.contracts.ts --agent-mode cursor
 ```
@@ -33,6 +37,7 @@ 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
@@ -41,18 +46,21 @@ contractspec build spec.contracts.ts --agent-mode cursor
 - **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
@@ -61,16 +69,33 @@ contractspec build spec.contracts.ts --agent-mode claude-code
 - **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
 ```
 
+### 5. OpenCode SDK Mode
+
+- **Mode**: `opencode` (alias for `opencode-sdk`)
+- **Description**: Uses the OpenCode SDK for self-hosted AI backends
+- **Best For**: Teams running open, self-hosted agent infrastructure
+- **Requirements**: `@opencode-ai/sdk` and a running OpenCode server
+- **Speed**: Moderate
+- **Quality**: High quality with self-hosted control
+
+**Example:**
+
+```bash
+contractspec build spec.contracts.ts --agent-mode opencode
+```
+
 ## Configuring Agent Modes
 
 ### Via Configuration File
@@ -101,22 +126,23 @@ 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 |
+| Feature    | Simple | Cursor   | Claude Code | OpenAI Codex | OpenCode       |
+| ---------- | ------ | -------- | ----------- | ------------ | -------------- |
+| Speed      | ⚡⚡⚡ | ⚡⚡     | ⚡⚡        | ⚡⚡⚡       | ⚡⚡           |
+| Quality    | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐  | ⭐⭐⭐⭐     | ⭐⭐⭐⭐       |
+| Validation | Basic  | Good     | Excellent   | Good         | Good           |
+| Setup      | Easy   | Moderate | Easy        | Easy         | Moderate       |
+| Cost       | Low    | N/A      | Moderate    | Low-Moderate | Infrastructure |
 
 ## 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)
+1. **opencode** → **claude-code** → **openai-codex** → **simple**
+2. **cursor** → **claude-code** → **openai-codex** → **simple**
+3. **claude-code** → **openai-codex** → **simple**
+4. **openai-codex** → **simple**
+5. **simple** → Basic templates (no AI)
 
 ## Usage Examples
 
@@ -129,6 +155,9 @@ contractspec build user.contracts.ts --agent-mode claude-code
 # Use OpenAI for algorithmic code
 contractspec build optimizer.contracts.ts --agent-mode openai-codex
 
+# Use OpenCode for self-hosted backends
+contractspec build spec.contracts.ts --agent-mode opencode
+
 # Disable AI entirely
 contractspec build simple.contracts.ts --no-agent
 ```
@@ -142,6 +171,9 @@ contractspec validate user.contracts.ts --check-implementation --agent-mode clau
 # Interactive validation
 contractspec validate user.contracts.ts -i --agent-mode claude-code
 
+# Validate with OpenCode
+contractspec validate user.contracts.ts --check-implementation --agent-mode opencode
+
 # Specify implementation path
 contractspec validate user.contracts.ts \
   --check-implementation \
@@ -152,19 +184,27 @@ contractspec validate user.contracts.ts \
 ## 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 Self-Hosted Backends
+
+- Use **opencode** when running an OpenCode server
+
 ### For CI/CD
+
 - Use **simple** mode for speed
 - Configure via environment variables
 - Set up validation in pre-commit hooks
@@ -174,6 +214,7 @@ contractspec validate user.contracts.ts \
 ### Agent Mode Not Working
 
 Check:
+
 1. API keys are set correctly
 2. Network connectivity to AI providers
 3. Provider quotas and rate limits
@@ -181,6 +222,7 @@ Check:
 ### Fallback to Simple Mode
 
 This happens when:
+
 - API key is missing
 - Provider is unavailable
 - Agent cannot handle the task
@@ -190,6 +232,7 @@ 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
@@ -201,7 +244,7 @@ Try:
 CONTRACTSPEC_AI_PROVIDER=claude|openai|ollama|custom
 
 # Agent mode
-CONTRACTSPEC_AGENT_MODE=simple|cursor|claude-code|openai-codex
+CONTRACTSPEC_AGENT_MODE=simple|cursor|claude-code|openai-codex|opencode
 
 # Model selection
 CONTRACTSPEC_AI_MODEL=claude-3-7-sonnet-20250219

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # contractspec
 
+## 1.53.0
+
+### Minor Changes
+
+- f4180d4: fix: performance improvement
+
+### Patch Changes
+
+- cd7f418: Move ContractSpec automation into reusable actions and ship typed report generators.
+- 1484fa6: Add reusable ContractSpec workflows with shared reporting and document the new automation guidance.
+- 5b371b1: Expose OpenCode agent mode in the CLI and workspace validation with updated docs and examples.
+- Updated dependencies [5b371b1]
+- Updated dependencies [f4180d4]
+  - @contractspec/app.cli-contractspec@1.53.0
+
 ## 1.52.0
 
 ### Minor Changes

package/README.md

@@ -4,10 +4,8 @@
 [![npm downloads](https://img.shields.io/npm/dt/contractspec)](https://www.npmjs.com/package/contractspec)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/lssm-tech/contractspec)
 
-
 Website: https://contractspec.io/
 
-
 **Stabilize your AI-generated code** — Define contracts once, generate consistent code across API, DB, UI, and events. Safe regeneration. No lock-in.
 
 CLI tool for creating, building, and validating contract specifications.
@@ -41,6 +39,7 @@ contractspec validate src/contracts/mySpec.ts
 List all contract specifications in the project with filtering options.
 
 **Options:**
+
 - `--pattern <pattern>` - File pattern to search (glob)
 - `--deep` - Load spec modules to extract richer metadata (executes spec modules)
 - `--type <type>` - Filter by spec type (operation, event, presentation, etc.)
@@ -70,6 +69,7 @@ contractspec list --json
 Watch contract specifications and auto-regenerate on changes.
 
 **Options:**
+
 - `--pattern <pattern>` - File pattern to watch (default: `**/*.contracts.ts`)
 - `--build` - Auto-run build command on changes
 - `--validate` - Auto-run validate command on changes
@@ -95,6 +95,7 @@ contractspec watch --pattern 'src/**/*.ts' --debounce 1000
 Sync contracts by building all discovered specs.
 
 **Options:**
+
 - `--pattern <pattern>` - File pattern to search (glob)
 - `--buckets <buckets>` - Optional output buckets (comma-separated). Builds repeat into `./generated/<bucket>/`
 - `--surfaces <surfaces>` - (deprecated) Alias for `--buckets`
@@ -119,6 +120,7 @@ contractspec sync --dry-run
 Clean generated files and build artifacts.
 
 **Options:**
+
 - `--dry-run` - Show what would be deleted without deleting
 - `--generated-only` - Only clean generated directories (generated/, dist/, .turbo/, outputDir artifacts)
 - `--older-than <days>` - Only clean files older than specified days
@@ -146,6 +148,7 @@ contractspec clean --git-clean
 Analyze contract dependencies and relationships.
 
 **Options:**
+
 - `--pattern <pattern>` - File pattern to search (glob)
 - `--entry <name>` - Focus on a specific contract name
 - `--format <format>` - text|json|dot (default: text)
@@ -175,9 +178,11 @@ contractspec deps --format dot > deps.dot
 Compare contract specifications and show differences.
 
 **Arguments:**
+
 - `<spec1> <spec2>` - Two spec files to compare
 
 **Options:**
+
 - `--breaking` - Only show breaking changes
 - `--semantic` - Show semantic differences (not just text)
 - `--json` - Output as JSON for scripting
@@ -204,6 +209,7 @@ contractspec diff spec1.ts spec2.ts --semantic
 Interactive wizard to create contract specifications.
 
 **Options:**
+
 - `--type <type>` - Spec type: operation, event, presentation, form, feature
 - `--ai` - Use AI to generate spec from description
 - `--provider <provider>` - AI provider: claude, openai, ollama, custom
@@ -227,10 +233,11 @@ contractspec create --ai --provider ollama --model codellama
 Generate implementation code from contract specs using AI agents with automatic fallbacks.
 
 **Options:**
+
 - `--output-dir <dir>` - Output directory (default: ./generated)
 - `--provider <provider>` - AI provider: claude, openai, ollama, custom
 - `--model <model>` - AI model to use
-- `--agent-mode <mode>` - Agent mode: simple, cursor, claude-code, openai-codex
+- `--agent-mode <mode>` - Agent mode: simple, cursor, claude-code, openai-codex, opencode
 - `--no-tests` - Skip test generation
 - `--no-agent` - Disable AI (use basic templates)
 
@@ -257,9 +264,10 @@ contractspec build src/contracts/simple.contracts.ts --no-agent
 Validate contract specifications and optionally verify implementations against specs using AI.
 
 **Options:**
+
 - `--check-implementation` - Validate implementation against spec using AI
 - `--implementation-path <path>` - Path to implementation (auto-detected if not specified)
-- `--agent-mode <mode>` - Agent mode for validation: simple, claude-code, openai-codex
+- `--agent-mode <mode>` - Agent mode for validation: simple, claude-code, openai-codex, opencode
 - `--check-handlers` - Verify handler implementations exist
 - `--check-tests` - Verify test coverage
 - `-i, --interactive` - Interactive mode - prompt for what to validate
@@ -290,6 +298,7 @@ contractspec validate src/contracts/signup.contracts.ts \
 Run all validation checks for CI/CD pipelines with machine-readable output formats.
 
 **Options:**
+
 - `--pattern <glob>` - Glob pattern for spec discovery
 - `--format <format>` - Output format: text, json, sarif (default: text)
 - `--output <file>` - Write results to file
@@ -301,6 +310,7 @@ Run all validation checks for CI/CD pipelines with machine-readable output forma
 - `--verbose` - Verbose output
 
 **Available Checks:**
+
 - `structure` - Spec structure validation (meta, io, policy)
 - `integrity` - Contract integrity (orphaned specs, broken refs)
 - `deps` - Dependency analysis (circular deps, missing refs)
@@ -309,6 +319,7 @@ Run all validation checks for CI/CD pipelines with machine-readable output forma
 - `tests` - Test file existence
 
 **Exit Codes:**
+
 - `0` - All checks passed
 - `1` - Errors found
 - `2` - Warnings found (with `--fail-on-warnings`)
@@ -366,6 +377,7 @@ The CLI supports multiple AI agent modes for different use cases:
 - **cursor** - Leverages Windsurf/Cursor agentic capabilities (requires Cursor environment)
 - **claude-code** - Uses Claude with extended thinking, best for production code and validation
 - **openai-codex** - Uses GPT-4o/o1 models, excellent for algorithms and optimization
+- **opencode** (alias for opencode-sdk) - Uses OpenCode SDK for self-hosted backends (requires `@opencode-ai/sdk`)
 
 See [AGENT_MODES.md](./AGENT_MODES.md) for detailed comparison and usage guide.
 
@@ -536,16 +548,19 @@ src/
 ### "Provider not available" error
 
 **Claude:**
+
 ```bash
 export ANTHROPIC_API_KEY=sk-ant-...
 ```
 
 **OpenAI:**
+
 ```bash
 export OPENAI_API_KEY=sk-...
 ```
 
 **Ollama:**
+
 ```bash
 # Install Ollama from https://ollama.ai
 ollama serve
@@ -555,11 +570,13 @@ ollama pull codellama
 ### Slow generation
 
 For faster local generation, use smaller models:
+
 ```bash
 contractspec create --ai --provider ollama --model codellama:7b
 ```
 
 For cloud, use faster models:
+
 ```bash
 contractspec build spec.ts --provider openai --model gpt-3.5-turbo
 ```
@@ -567,6 +584,7 @@ contractspec build spec.ts --provider openai --model gpt-3.5-turbo
 ### Import errors in generated code
 
 Make sure `@contractspec/lib.contracts` and `@contractspec/lib.schema` are installed:
+
 ```bash
 bun add @contractspec/lib.contracts @contractspec/lib.schema
 ```
@@ -585,23 +603,27 @@ Contributions welcome! Please:
 ### When to Use Each Mode
 
 **Simple Mode** - Default, good for:
+
 - Rapid prototyping
 - Basic implementations
 - Quick iterations
 - CI/CD pipelines (fast)
 
 **Cursor Mode** - Best for:
+
 - Working in Windsurf/Cursor IDE
 - Complex, iterative development
 - Context-aware code generation
 
 **Claude Code Mode** - Best for:
+
 - Production-quality implementations
 - Critical business logic
 - Comprehensive code validation
 - Detailed code reviews
 
 **OpenAI Codex Mode** - Best for:
+
 - Algorithmic problems
 - Performance optimization
 - Mathematical computations
@@ -612,7 +634,7 @@ For more details, see [AGENT_MODES.md](./AGENT_MODES.md).
 ## Roadmap
 
 - [x] AI-powered code generation
-- [x] Multiple agent modes (simple, cursor, claude-code, openai-codex)
+- [x] Multiple agent modes (simple, cursor, claude-code, openai-codex, opencode)
 - [x] AI-powered implementation validation
 - [x] Contract listing and discovery (`contractspec list`)
 - [x] Watch mode for auto-regeneration (`contractspec watch`)
@@ -633,4 +655,3 @@ For more details, see [AGENT_MODES.md](./AGENT_MODES.md).
 ## License
 
 MIT
-

package/bin/contractspec.mjs

@@ -1,3 +1,3 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 // One bin, picks the right runtime via conditional exports.
-import "@contractspec/app.cli-contractspec/run";
+import '@contractspec/app.cli-contractspec/run';

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "contractspec",
-  "version": "1.52.0",
+  "version": "1.53.0",
   "description": "CLI tool for creating, building, and validating contract specifications",
   "bin": {
     "contractspec": "./bin/contractspec.mjs"
   },
   "dependencies": {
-    "@contractspec/app.cli-contractspec": "1.52.0"
+    "@contractspec/app.cli-contractspec": "1.53.0"
   },
   "scripts": {
     "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",