@paths.design/caws-cli 3.1.0 → 3.1.1

package/README.md

@@ -1,222 +1,367 @@
 # CAWS CLI
 
-A command-line tool for scaffolding and initializing projects with the **Coding Agent Workflow System (CAWS)**.
+**Command Line Interface for CAWS (Coding Agent Workflow System)**
+
+The CAWS CLI is the primary interface for developers and agents to interact with CAWS quality assurance and workflow management capabilities. It provides comprehensive project scaffolding, validation, and management tools.
+
+## Overview
+
+The CAWS CLI serves as the central control point for:
+
+- **Project Initialization**: Scaffold new projects with CAWS quality gates
+- **Quality Validation**: Run comprehensive validation against working specifications
+- **Agent Integration**: Programmatic APIs for AI agents to evaluate and guide development
+- **Waiver Management**: Fast-lane escape hatches with full audit trails
+- **CI/CD Optimization**: Pipeline generation and optimization tools
+- **Experimental Features**: Dry-run capabilities for cutting-edge functionality
 
 ## Installation
 
+### Global Installation (Recommended)
+
+```bash
+npm install -g @caws/cli
+```
+
+### Local Development
+
 ```bash
-# Install globally from npm registry (recommended)
-npm install -g @paths.design/caws-cli
+# Clone the CAWS monorepo
+git clone https://github.com/paths-design/caws.git
+cd caws
 
-# Install locally in a project
-npm install --save-dev @paths.design/caws-cli
+# Install dependencies
+npm install
+
+# Build all packages
+npm run build
 
-# Or install directly from the caws-cli directory during development
-cd caws-cli
-npm install -g .
+# Use locally
+node packages/caws-cli/dist/index.js --help
 ```
 
-## Usage
+## Core Commands
+
+### Project Management
 
-### Initialize New Project
 ```bash
-# Interactive setup (recommended)
-caws init my-new-project
+# Initialize a new CAWS project
+caws init my-project
+
+# Add CAWS to existing project
+caws scaffold
 
-# Non-interactive with defaults
-caws init my-new-project --non-interactive
+# Validate working specification
+caws validate
 
-# Skip git initialization
-caws init my-new-project --no-git
+# Get help
+caws --help
 ```
 
-### Scaffold Existing Project
+### Agent Integration
+
 ```bash
-# Add CAWS components to existing project
-caws scaffold
+# Evaluate work quality (JSON output for agents)
+caws agent evaluate .caws/working-spec.yaml
 
-# Force overwrite existing files
-caws scaffold --force
+# Get iterative development guidance
+caws agent iterate --current-state "Started implementation" .caws/working-spec.yaml
 ```
 
-### Version Information
+### Waiver Management
+
 ```bash
-caws --version
-caws version
+# Create a waiver for exceptional circumstances
+caws waivers create \
+  --title "Emergency security fix" \
+  --reason emergency_hotfix \
+  --gates coverage_threshold \
+  --expires-at "2025-11-01T00:00:00Z" \
+  --approved-by "security-team"
+
+# List active waivers
+caws waivers list
+
+# Revoke a waiver
+caws waivers revoke WV-0001
 ```
 
-## Commands
+### CI/CD Optimization
 
-### `caws init <project-name>` (alias: `i`)
-Initialize a new project with CAWS scaffolding.
+```bash
+# Analyze project for CI/CD optimizations
+caws cicd analyze
+
+# Generate optimized GitHub Actions workflow
+caws cicd generate github --output .github/workflows/caws-gates.yml
+
+# Smart test selection based on changes
+caws cicd test-selection --from-commit HEAD~1
+```
+
+### Experimental Features
+
+```bash
+# Dry-run validation without side effects
+caws experimental --dry-run validate .caws/working-spec.yaml
+
+# Experimental quality gates
+caws experimental quality-gates .caws/working-spec.yaml --parallel-execution
+```
 
-**Options:**
-- `-i, --interactive`: Run interactive setup (default: true)
-- `-g, --git`: Initialize git repository (default: true)
-- `-n, --non-interactive`: Skip interactive prompts
+### Tool Management
 
-### `caws scaffold` (alias: `s`)
-Add CAWS components to an existing project.
+```bash
+# List available CAWS tools
+caws tools list
 
-**Options:**
-- `-f, --force`: Overwrite existing files
+# Execute specific tool
+caws tools run validate
 
-### `caws version` (alias: `v`)
-Show version and system information.
+# Manage tool configurations
+caws tools --help
+```
 
-## Interactive Setup
+## Architecture
 
-When running `caws init` interactively, you'll be prompted for:
+The CLI is built with a modular architecture:
 
-1. **Project ID**: Ticket system identifier (e.g., FEAT-1234)
-2. **Project Title**: Descriptive name
-3. **Risk Tier**: 1 (critical), 2 (standard), 3 (low risk)
-4. **Mode**: feature, refactor, fix, doc, or chore
-5. **Change Budget**: File and line-of-code limits
-6. **Scope**: What's in/out of scope for the project
-7. **Requirements**: Functional and non-functional requirements
-8. **Contracts**: API specifications and paths
-9. **Observability**: Logging, metrics, and tracing setup
-10. **Migration Plan**: Database and deployment strategy
+```
+caws-cli/
+├── src/
+│   ├── index.js           # Main CLI entry point
+│   ├── waivers-manager.js # Waiver system implementation
+│   ├── cicd-optimizer.js  # CI/CD optimization logic
+│   └── tool-loader.js     # Dynamic tool loading system
+├── templates/             # Project templates
+└── dist/                  # Compiled output
+```
 
-## Project Structure
+### Key Components
 
-The CLI creates a complete CAWS project structure:
+- **Command Parser**: Commander.js-based CLI with subcommands
+- **Tool System**: Dynamic loading of quality gate tools
+- **Waiver Manager**: Fast-lane escape hatch management
+- **CI/CD Optimizer**: Pipeline analysis and generation
+- **Agent Interface**: JSON APIs for programmatic agent integration
+
+## Integration with CAWS Ecosystem
+
+### Relationship to Other Packages
 
 ```
-project-name/
-├── .caws/                          # CAWS configuration
-│   ├── policy/tier-policy.json     # Risk tier definitions
-│   ├── schemas/                    # JSON schemas
-│   ├── templates/                  # PR templates
-│   └── working-spec.yaml          # Project specification
-├── .agent/                         # Provenance artifacts
-├── apps/tools/caws/                # CAWS utilities
-├── codemod/                        # AST transformation scripts
-├── docs/                           # Documentation
-├── tests/                          # Test directories
-├── .github/workflows/caws.yml      # CI/CD pipeline
-├── agents.md                       # CAWS framework guide
-└── README.md                       # Project documentation
+┌─────────────────┐    ┌──────────────────┐
+│   caws-cli      │────│  caws-template   │
+│   (Commands)    │    │  (Tools & Config)│
+└─────────────────┘    └──────────────────┘
+        │                       │
+        └───────────────────────┘
+                │
+        ┌─────────────────┐    ┌──────────────────┐
+        │ caws-mcp-server │────│ caws-vscode-ext  │
+        │ (Agent Bridge)  │    │   (IDE Integration)
+        └─────────────────┘    └──────────────────┘
 ```
 
-## Features
+- **caws-template**: Provides the tools and configurations that CLI manages
+- **caws-mcp-server**: Exposes CLI functionality to AI agents via MCP protocol
+- **caws-vscode-extension**: Provides IDE integration using CLI capabilities
+
+### Quality Gates Integration
+
+The CLI automatically executes quality gates defined in the template:
 
-- 🚀 **Quick Start**: Complete project scaffolding in minutes
-- 🔧 **Interactive Setup**: Guided configuration process with validation
-- 📋 **Template Generation**: Working specifications and PR templates
-- 🛠️ **Tool Integration**: Pre-configured development tools with quality gates
-- 📦 **Provenance Ready**: SBOM and attestation setup with trust scoring
-- 🔒 **Quality Gates**: Pre-configured CI/CD pipelines with automated validation
-- ✅ **Schema Validation**: JSON Schema validation of working specifications
-- 🧪 **Developer Tools**: Linting, testing, and formatting setup
-- 🔍 **Security Scanning**: Prompt linting and secret detection
-- 📊 **Trust Scoring**: Automated quality assessment and scoring
+1. **Spec Validation**: Validates working specifications against schema
+2. **Security Scanning**: Runs security checks and secret detection
+3. **Code Quality**: Executes linting, type checking, and formatting
+4. **Test Execution**: Runs unit, integration, and contract tests
+5. **Performance Checks**: Validates performance budgets and metrics
+
+### Agent Workflow Integration
+
+The CLI provides structured APIs for agents:
+
+```javascript
+// Agent can evaluate work quality
+const result = await runCommand('caws agent evaluate spec.yaml');
+// Returns: { success: true, evaluation: { quality_score: 0.85, ... } }
+
+// Agent can get guidance for next steps
+const guidance = await runCommand('caws agent iterate --current-state "..." spec.yaml');
+// Returns: { guidance: "...", next_steps: [...], confidence: 0.8 }
+```
 
 ## Configuration
 
-### Working Specification
-The CLI generates a comprehensive `.caws/working-spec.yaml` that includes:
-- Project metadata and scope
-- Risk tier and mode classification
-- Change budget constraints
-- Acceptance criteria and invariants
-- Non-functional requirements
-- Observability configuration
-- Migration and rollback strategies
-
-### CI/CD Pipeline
-Includes GitHub Actions workflow with:
-- Scope and budget validation
-- Static analysis and security scanning
-- Unit and integration testing
-- Performance and accessibility checks
-- Provenance and attestation generation
-
-## Examples
-
-### New Feature Project
-```bash
-caws init user-auth-service
-# Follows interactive prompts for authentication service setup
+### Working Specifications
+
+Projects use `.caws/working-spec.yaml` files:
+
+```yaml
+id: PROJ-001
+title: "Feature implementation"
+risk_tier: 2
+mode: feature
+change_budget:
+  max_files: 25
+  max_loc: 1000
+acceptance:
+  - id: "A1"
+    given: "Current state"
+    when: "Feature implemented"
+    then: "Expected behavior"
+```
+
+### Tool Configuration
+
+Tools are configured in `apps/tools/caws/` directory with metadata:
+
+```javascript
+// Tool metadata
+{
+  id: 'validate',
+  name: 'Working Spec Validator',
+  capabilities: ['validation', 'quality-gates'],
+  version: '1.0.0'
+}
 ```
 
-### Refactoring Existing Codebase
+## Development
+
+### Building
+
 ```bash
-caws init legacy-refactor --non-interactive
-# Creates refactor mode specification with appropriate constraints
+cd packages/caws-cli
+npm run build    # Compile TypeScript
+npm run dev      # Development with watch
+npm run lint     # Run ESLint
+npm run test     # Run tests
 ```
 
-### Documentation Project
+### Adding New Commands
+
+1. Add command implementation in `src/index.js`
+2. Update help text and option parsing
+3. Add integration tests
+4. Update documentation
+
+### Tool Development
+
+Tools follow a standardized interface:
+
+```javascript
+class MyTool extends BaseTool {
+  getMetadata() {
+    return {
+      id: 'my-tool',
+      name: 'My Custom Tool',
+      capabilities: ['validation'],
+      version: '1.0.0'
+    };
+  }
+
+  async executeImpl(parameters, context) {
+    // Tool logic here
+    return { success: true, output: result };
+  }
+}
+```
+
+## Testing
+
+### Test Categories
+
+- **Unit Tests**: Individual command and component testing
+- **Integration Tests**: End-to-end command workflows
+- **Contract Tests**: API compatibility testing
+- **Quality Gate Tests**: Tool execution and validation
+
+### Running Tests
+
 ```bash
-caws init api-docs
-# Sets up doc mode with appropriate scope and budget
+npm run test              # All tests
+npm run test:unit         # Unit tests only
+npm run test:integration  # Integration tests
+npm run test:contract     # Contract tests
 ```
 
-## Requirements
+## Security
 
-- **Node.js**: >= 16.0.0
-- **npm**: For package management
-- **Git**: For version control (optional)
+### Tool Validation
 
-## Development
+- All tools are validated against allowlists
+- Security scanning prevents malicious tool execution
+- Sandboxed execution environment
+- Audit trails for all tool usage
+
+### Waiver Security
+
+- Waivers require explicit approval and justification
+- Time-limited validity prevents permanent bypasses
+- Audit logs track all waiver usage
+- High-risk waivers trigger review processes
+
+## Troubleshooting
 
-### Running Locally
+### Common Issues
+
+**Command not found**
 ```bash
-cd caws-cli
-npm install
-npm start init my-test-project
+# Ensure global installation
+npm install -g @caws/cli
+caws --version
+
+# Or use local installation
+node packages/caws-cli/dist/index.js --help
 ```
 
-### Testing
+**Tool loading errors**
 ```bash
-npm test          # Run tests with linting
-npm run test:watch # Run tests in watch mode
+# Check tool directory structure
+ls -la apps/tools/caws/
+
+# Validate tool metadata
+caws tools list
+
+# Check tool permissions
+chmod +x apps/tools/caws/*.js
 ```
 
-### Linting & Formatting
+**Validation failures**
 ```bash
-npm run lint      # Run ESLint
-npm run lint:fix  # Fix ESLint issues
-npm run format    # Format with Prettier
+# Check working spec syntax
+caws validate --suggestions .caws/working-spec.yaml
+
+# Auto-fix common issues
+caws validate --auto-fix .caws/working-spec.yaml
 ```
 
-### Development Tools
-The CLI includes comprehensive development tooling:
-- **ESLint**: Code quality and consistency
-- **Prettier**: Code formatting
-- **Jest**: Unit testing framework
-- **Schema Validation**: JSON Schema validation of working specs
-- **Quality Gates**: Automated trust scoring and validation
+## Contributing
 
-## Architecture
+### Code Standards
 
-The CLI is built with:
-- **Commander.js**: Command-line interface framework
-- **Inquirer.js**: Interactive prompt library
-- **fs-extra**: Enhanced file system operations
-- **js-yaml**: YAML parsing and generation
+- Use async/await for asynchronous operations
+- Provide comprehensive error handling
+- Include detailed help text for all commands
+- Write tests for new functionality
+- Update documentation for API changes
 
-## Contributing
+### Pull Request Process
 
 1. Fork the repository
-2. Create feature branch
+2. Create a feature branch
 3. Add tests for new functionality
-4. Ensure CLI still works with existing templates
-5. Submit pull request
+4. Ensure all tests pass
+5. Update documentation
+6. Submit pull request with working spec
 
 ## License
 
-MIT - see LICENSE file for details.
-
-## Support
-
-- 📖 **Documentation**: See inline help with `caws --help`
-- 🐛 **Issues**: Report bugs or request features
-- 🤝 **Contributing**: See contributing guidelines
+MIT License - see main project LICENSE file.
 
----
+## Links
 
-**Author**: @darianrosebrook
-**Version**: 1.0.0
-**CAWS**: v1.0
+- **Main Project**: https://github.com/paths-design/caws
+- **Documentation**: https://docs.caws.dev
+- **Issues**: https://github.com/paths-design/caws/issues
+- **Discussions**: https://github.com/paths-design/caws/discussions

package/dist/budget-derivation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Derive budget for a working spec based on policy and waivers
+ * @param {Object} spec - Working spec object
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object} Derived budget with baseline and effective limits
+ */
+export function deriveBudget(spec: any, projectRoot?: string): any;
+/**
+ * Load a waiver by ID
+ * @param {string} waiverId - Waiver ID (e.g., WV-0001)
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object|null} Waiver object or null if not found
+ */
+export function loadWaiver(waiverId: string, projectRoot: string): any | null;
+/**
+ * Check if a waiver is currently valid
+ * @param {Object} waiver - Waiver object
+ * @returns {boolean} Whether waiver is valid and active
+ */
+export function isWaiverValid(waiver: any): boolean;
+/**
+ * Check if current changes exceed derived budget
+ * @param {Object} derivedBudget - Budget from deriveBudget()
+ * @param {Object} currentStats - Current change statistics
+ * @returns {Object} Budget check result
+ */
+export function checkBudgetCompliance(derivedBudget: any, currentStats: any): any;
+/**
+ * Generate burn-up report for scope visibility
+ * @param {Object} derivedBudget - Budget from deriveBudget()
+ * @param {Object} currentStats - Current change statistics
+ * @returns {string} Human-readable burn-up report
+ */
+export function generateBurnupReport(derivedBudget: any, currentStats: any): string;
+//# sourceMappingURL=budget-derivation.d.ts.map

package/dist/budget-derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-derivation.d.ts","sourceRoot":"","sources":["../src/budget-derivation.js"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,sDAHW,MAAM,OAuDhB;AAED;;;;;GAKG;AACH,qCAJW,MAAM,eACN,MAAM,GACJ,MAAO,IAAI,CAgBvB;AAED;;;;GAIG;AACH,4CAFa,OAAO,CA4BnB;AAED;;;;;GAKG;AACH,kFA8BC;AAED;;;;;GAKG;AACH,6EAFa,MAAM,CA4BlB"}