@lssm/app.cli-contractspec 0.0.0-canary-20251221164004

package/.contractsrc.example.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "./contractsrc.schema.json",
+  "aiProvider": "claude",
+  "aiModel": "claude-3-7-sonnet-20250219",
+  "agentMode": "claude-code",
+  "customEndpoint": null,
+  "customApiKey": null,
+  "outputDir": "./src",
+  "conventions": {
+    "operations": "interactions/commands|queries",
+    "events": "events",
+    "presentations": "presentations",
+    "forms": "forms"
+  },
+  "defaultOwners": ["@team"],
+  "defaultTags": ["auto-generated"],
+  
+  "_comments": {
+    "aiProvider": "Options: 'claude', 'openai', 'ollama', 'custom'",
+    "agentMode": "Options: 'simple', 'cursor', 'claude-code', 'openai-codex'. Controls code generation strategy.",
+    "aiModel": "Specific model to use. Defaults vary by provider.",
+    "customEndpoint": "For custom providers. Example: 'https://your-llm-endpoint.com'",
+    "customApiKey": "Optional. Can also use CONTRACTSPEC_LLM_API_KEY env var"
+  }
+}

package/AGENTS.md

@@ -0,0 +1,102 @@
+# AI Agent Guide — `@lssm/app.cli-contractspec`
+
+Scope: `packages/apps/cli-contractspec/*`
+
+This is the ContractSpec CLI (`contractspec`).
+
+## Architecture
+
+The CLI is a **thin wrapper** around business logic in `@lssm/bundle.contractspec-workspace`. The separation is:
+
+### CLI Layer (this package)
+
+- **Commands** (`src/commands/`) - Thin wrappers that call bundle services
+- **Prompts** (`src/commands/create/wizards/`) - Interactive UI using `@inquirer/prompts`
+- **CLI setup** (`src/index.ts`, `src/cli.ts`) - Commander.js configuration
+- **Types** (`src/types.ts`) - CLI-specific types
+
+### Business Logic (bundle)
+
+- **Services** (`@lssm/bundle.contractspec-workspace/services/`) - Core use-cases
+  - `create.ts` - Spec creation logic
+  - `build.ts` - Code generation from specs
+  - `openapi.ts` - OpenAPI export
+  - `registry.ts` - Registry client
+  - `examples.ts` - Examples management
+  - `validate.ts`, `diff.ts`, `deps.ts`, etc.
+- **Templates** (`@lssm/bundle.contractspec-workspace/templates/`) - Spec templates
+- **AI** (`@lssm/bundle.contractspec-workspace/ai/`) - AI agents and prompts
+- **Adapters** (`@lssm/bundle.contractspec-workspace/adapters/`) - Infrastructure
+
+## Build System
+
+The CLI is bundled with `bun build`:
+
+- Single executable output: `dist/cli.js`
+- Target: `bun` runtime
+- Minified for production
+- Type declarations generated separately with `tsc`
+
+## Test System
+
+Tests use `bun:test` (not vitest):
+
+- Run: `bun test`
+- Watch: `bun test --watch`
+- All test files import from `bun:test`
+
+## Docs consumed by MCP
+
+The CLI MCP server serves these markdown files by path:
+
+- `packages/apps/cli-contractspec/QUICK_START.md`
+- `packages/apps/cli-contractspec/QUICK_REFERENCE.md`
+- `packages/apps/cli-contractspec/README.md`
+
+If you rename/move them, update `packages/bundles/contractspec-studio/src/application/mcp/cliMcp.ts` (`CLI_DOC_PATHS`).
+
+## Local commands
+
+- **Dev/watch**: `bun run dev` - Watch mode, rebuilds on changes
+- **Build**: `bun run build` - Bundles CLI + generates types
+- **Test**: `bun test` - Run all tests
+- **Lint**: `bun run lint` - Fix linting issues
+
+## Prompt Library
+
+The CLI uses `@inquirer/prompts` (not legacy `inquirer`):
+
+- `select` - List selection
+- `input` - Text input
+- `confirm` - Yes/no confirmation
+- `number` - Numeric input
+
+## Adding a New Command
+
+1. **Create service in bundle** (`@lssm/bundle.contractspec-workspace/services/`)
+2. **Create CLI wrapper** (`src/commands/new-command.ts`)
+3. **Add to index.ts** (`src/index.ts`)
+4. **Add prompts if needed** (`src/commands/new-command/prompts.ts`)
+5. **Write tests** (`src/commands/new-command/index.test.ts`)
+
+Example CLI wrapper:
+
+```typescript
+import { Command } from 'commander';
+import { myService } from '@lssm/bundle.contractspec-workspace';
+import { createFsAdapter } from '@lssm/bundle.contractspec-workspace/adapters';
+
+export const myCommand = new Command('my-command')
+  .description('Do something')
+  .action(async () => {
+    const fs = createFsAdapter();
+    const logger = createLoggerAdapter();
+
+    await myService(
+      {
+        /* options */
+      },
+      { fs, logger }
+    );
+  });
+```

package/AGENT_MODES.md

@@ -0,0 +1,247 @@
+# 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/CHANGELOG.md

@@ -0,0 +1,277 @@
+# Changelog
+
+## 0.0.0-canary-20251221164004
+
+### Minor Changes
+
+- 66a5dfd: initial release
+
+### Patch Changes
+
+- Updated dependencies [66a5dfd]
+  - @lssm/bundle.contractspec-workspace@0.0.0-canary-20251221164004
+  - @lssm/lib.ai-providers@0.0.0-canary-20251221164004
+  - @lssm/lib.contracts@0.0.0-canary-20251221164004
+  - @lssm/lib.contracts-transformers@0.0.0-canary-20251221164004
+  - @lssm/lib.schema@0.0.0-canary-20251221164004
+  - @lssm/lib.testing@0.0.0-canary-20251221164004
+  - @lssm/module.ai-chat@0.0.0-canary-20251221164004
+  - @lssm/module.contractspec-examples@0.0.0-canary-20251221164004
+
+## 0.12.0
+
+### Minor Changes
+
+- Refactor to be compatible with ai-sdk v6
+
+### Patch Changes
+
+- Updated dependencies
+  - @lssm/app.cli-database@1.12.0
+  - @lssm/lib.contracts@1.12.0
+  - @lssm/lib.schema@1.12.0
+  - @lssm/lib.testing@0.5.0
+
+## 0.11.1
+
+### Patch Changes
+
+- Fix dependencies
+- Updated dependencies
+  - @lssm/app.cli-database@1.11.1
+  - @lssm/lib.contracts@1.11.1
+  - @lssm/lib.schema@1.11.1
+  - @lssm/lib.testing@0.4.1
+
+## 0.11.0
+
+### Minor Changes
+
+- b7621d3: Fix version
+
+### Patch Changes
+
+- Updated dependencies [b7621d3]
+  - @lssm/app.cli-database@1.11.0
+  - @lssm/lib.contracts@1.11.0
+  - @lssm/lib.schema@1.11.0
+  - @lssm/lib.testing@0.4.0
+
+## 0.10.0
+
+### Minor Changes
+
+- fix
+
+### Patch Changes
+
+- Updated dependencies
+  - @lssm/app.cli-database@1.10.0
+  - @lssm/lib.contracts@1.10.0
+  - @lssm/lib.schema@1.10.0
+  - @lssm/lib.testing@0.3.0
+
+## 0.9.2
+
+### Patch Changes
+
+- fix dependencies
+- Updated dependencies
+  - @lssm/lib.testing@0.2.2
+  - @lssm/app.cli-database@1.9.2
+  - @lssm/lib.contracts@1.9.2
+  - @lssm/lib.schema@1.9.2
+
+## 0.9.1
+
+### Patch Changes
+
+- fix
+- Updated dependencies
+  - @lssm/app.cli-database@1.9.1
+  - @lssm/lib.contracts@1.9.1
+  - @lssm/lib.testing@0.2.1
+  - @lssm/lib.schema@1.9.1
+
+## 0.9.0
+
+### Minor Changes
+
+- b1d0876: Managed platform
+
+### Patch Changes
+
+- Updated dependencies [b1d0876]
+  - @lssm/app.cli-database@1.9.0
+  - @lssm/lib.contracts@1.9.0
+  - @lssm/lib.testing@0.2.0
+  - @lssm/lib.schema@1.9.0
+
+## 0.8.0
+
+### Minor Changes
+
+- f1f4ddd: Foundation Hardening
+
+### Patch Changes
+
+- Updated dependencies [f1f4ddd]
+  - @lssm/lib.contracts@1.8.0
+  - @lssm/lib.schema@1.8.0
+
+## 0.7.4
+
+### Patch Changes
+
+- fix typing
+- Updated dependencies
+  - @lssm/lib.contracts@1.7.4
+  - @lssm/lib.schema@1.7.4
+
+## 0.7.3
+
+### Patch Changes
+
+- add right-sidebar
+- Updated dependencies
+  - @lssm/lib.contracts@1.7.3
+  - @lssm/lib.schema@1.7.3
+
+## 0.7.2
+
+### Patch Changes
+
+- fix typing
+- Updated dependencies
+  - @lssm/lib.contracts@1.7.2
+  - @lssm/lib.schema@1.7.2
+
+## 0.7.1
+
+### Patch Changes
+
+- fix typing
+- Updated dependencies
+  - @lssm/lib.contracts@1.7.1
+  - @lssm/lib.schema@1.7.1
+
+## 0.7.0
+
+### Minor Changes
+
+- fixii
+
+### Patch Changes
+
+- Updated dependencies
+  - @lssm/lib.contracts@1.7.0
+  - @lssm/lib.schema@1.7.0
+
+## 0.6.0
+
+### Minor Changes
+
+- fix versionnnn
+
+### Patch Changes
+
+- Updated dependencies
+  - @lssm/lib.contracts@1.6.0
+  - @lssm/lib.schema@1.6.0
+
+## 0.5.0
+
+### Minor Changes
+
+- fix
+
+### Patch Changes
+
+- Updated dependencies
+  - @lssm/lib.contracts@1.5.0
+  - @lssm/lib.schema@1.5.0
+
+## 0.4.0
+
+### Minor Changes
+
+- fix exports
+
+### Patch Changes
+
+- Updated dependencies
+  - @lssm/lib.contracts@1.4.0
+  - @lssm/lib.schema@1.4.0
+
+## 0.3.0
+
+### Minor Changes
+
+- fix it
+
+### Patch Changes
+
+- Updated dependencies
+  - @lssm/lib.contracts@1.3.0
+  - @lssm/lib.schema@1.3.0
+
+## 0.2.0
+
+### Minor Changes
+
+- fix
+
+### Patch Changes
+
+- Updated dependencies
+  - @lssm/lib.contracts@1.2.0
+  - @lssm/lib.schema@1.2.0
+
+## 0.1.0
+
+### Minor Changes
+
+- fix
+- 748b3a2: fix publish
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies [748b3a2]
+  - @lssm/lib.contracts@1.1.0
+  - @lssm/lib.schema@1.1.0
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Initial version
+
+### Added
+
+- Initial release of contracts-cli
+- `contractspec create` command with interactive wizards
+- AI-assisted spec creation using Vercel AI SDK
+- Multi-provider support (Claude, OpenAI, Ollama, custom endpoints)
+- `contractspec build` command for code generation
+- `contractspec validate` command for spec validation
+- TypeScript templates for operations, events, and presentations
+- Handler and component generation
+- Test generation
+- Comprehensive documentation and examples
+- Agent-driven build workflow with automatic fallback to deterministic templates
+- AI-powered implementation validation with consistent agent orchestration
+
+### Features
+
+- Interactive CLI with Commander.js
+- Beautiful terminal output with Chalk and Ora
+- Configuration via `.contractsrc.json`
+- Environment variable support
+- BYOLLM (Bring Your Own LLM) support
+- Validation with detailed error messages
+- Type-safe code generation
+- `contractspec validate` now prompts for spec-only vs implementation validation unless `--check-implementation` is provided

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.