@paths.design/caws-cli 7.0.2 → 8.0.0

package/dist/templates/.windsurf/workflows/caws-guided-development.md

@@ -0,0 +1,92 @@
+# /caws-guided-development
+
+## CAWS-Guided Feature Development Workflow
+
+**Purpose**: Guide agents through feature development with CAWS quality assurance
+
+**Tags**: development, quality, caws, feature
+
+---
+
+### 1. Initialize CAWS Working Spec
+```
+# Create comprehensive working specification
+caws init feature-name --interactive
+
+# Define acceptance criteria, scope, and risk assessment
+# Working spec: .caws/working-spec.yaml
+```
+
+### 2. Plan Implementation Strategy
+```
+# Get CAWS guidance for implementation approach
+caws agent iterate --current-state "Planning phase complete, need implementation strategy"
+
+# CAWS will suggest:
+# - Implementation steps
+# - Quality gates to consider
+# - Risk mitigation strategies
+# - Testing approach
+```
+
+### 3. Implement Core Functionality
+```
+# Start coding with CAWS quality monitoring
+# Real-time feedback via CAWS tools
+
+# Regular quality checks
+caws agent evaluate --quiet
+```
+
+### 4. Quality Assurance Integration
+```
+# Run comprehensive quality gates
+caws validate
+
+# Address any failing gates
+# Create waivers if justified
+caws waivers create --reason emergency_hotfix --gates coverage_threshold
+```
+
+### 5. Testing & Validation
+```
+# Unit tests
+npm run test:unit
+
+# Integration tests
+npm run test:integration
+
+# Contract tests
+npm run test:contract
+```
+
+### 6. Final Quality Review
+```
+# Complete CAWS evaluation
+caws agent evaluate
+
+# Generate provenance report
+caws provenance generate
+
+# Ready for integration
+```
+
+---
+
+**Quality Gates**:
+- ✅ Working spec validation
+- ✅ Code quality standards
+- ✅ Test coverage requirements
+- ✅ Security scanning
+- ✅ Performance budgets
+
+**Success Criteria**:
+- All CAWS quality gates pass
+- Acceptance criteria met
+- No critical security issues
+- Performance requirements satisfied
+
+**Call Other Workflows**:
+- `/caws-testing-workflow` - Comprehensive testing
+- `/caws-security-review` - Security validation
+- `/caws-deployment-checklist` - Deployment preparation

package/dist/templates/COMMIT_CONVENTIONS.md

@@ -0,0 +1,86 @@
+# Commit Message Conventions
+
+This repository uses [Conventional Commits](https://conventionalcommits.org/) for automated versioning and changelog generation.
+
+## Format
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+## Types
+
+- **feat**: A new feature
+- **fix**: A bug fix
+- **docs**: Documentation only changes
+- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+- **refactor**: A code change that neither fixes a bug nor adds a feature
+- **perf**: A code change that improves performance
+- **test**: Adding missing tests or correcting existing tests
+- **build**: Changes that affect the build system or external dependencies
+- **ci**: Changes to our CI configuration files and scripts
+- **chore**: Other changes that don't modify src or test files
+
+## Examples
+
+### Feature
+```
+feat: add user authentication system
+```
+
+### Bug Fix
+```
+fix: resolve memory leak in data processing
+```
+
+### Documentation
+```
+docs: update API documentation for new endpoints
+```
+
+### Refactoring
+```
+refactor: extract user validation logic into separate module
+```
+
+### Breaking Change
+```
+feat!: change API response format for user data
+
+BREAKING CHANGE: The user object now returns additional fields and the format has changed
+```
+
+## Scope
+
+The scope should be the name of the package or module affected by the change:
+
+```
+feat(auth): add OAuth2 authentication
+fix(api): resolve endpoint timeout issue
+docs(cli): update installation instructions
+```
+
+## Automated Publishing
+
+Commits following these conventions will automatically:
+
+1. **Trigger releases** when pushed to `main`
+2. **Generate changelogs** based on commit messages
+3. **Bump versions** according to semantic versioning:
+   - `fix:` → patch release (1.0.0 → 1.0.1)
+   - `feat:` → minor release (1.0.0 → 1.1.0)
+   - `feat!:` → major release (1.0.0 → 2.0.0)
+
+## CI/CD Integration
+
+The automated release process includes:
+- ✅ Linting and testing
+- ✅ Package building
+- ✅ NPM publishing with OIDC authentication
+- ✅ Changelog generation
+- ✅ Git tag creation
+- ✅ Release notes generation

package/dist/templates/OIDC_SETUP.md

@@ -0,0 +1,300 @@
+# OIDC Trusted Publisher Setup
+
+This guide helps you set up OIDC (OpenID Connect) trusted publisher for automated publishing to package registries.
+
+## Overview
+
+OIDC trusted publisher allows you to publish packages without storing long-lived tokens or passwords in your CI/CD environment. Instead, it uses short-lived tokens issued by the OIDC provider.
+
+## Supported Registries
+
+- **npm**: npm Registry
+- **PyPI**: Python Package Index
+- **Maven Central**: Java packages
+- **NuGet**: .NET packages
+
+## Setup Process
+
+### 1. Configure OIDC Provider
+
+Most CI/CD platforms (GitHub Actions, GitLab CI, etc.) provide built-in OIDC support.
+
+**GitHub Actions Example:**
+
+```yaml
+# .github/workflows/publish.yml
+name: Publish Package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      - name: Install dependencies
+        run: npm ci
+      - name: Build package
+        run: npm run build
+      - name: Publish to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+### 2. Registry Configuration
+
+#### npm Registry
+
+1. **Create OIDC Integration**:
+
+   ```bash
+   # Using npm CLI
+   npm profile enable-2fa auth-and-writes
+   ```
+
+2. **Configure Trusted Publisher**:
+   - Go to npmjs.com → Account Settings → Access Tokens
+   - Create "Automation" token
+   - Configure OIDC integration
+
+3. **Repository Settings**:
+   ```json
+   // package.json
+   {
+     "publishConfig": {
+       "registry": "https://registry.npmjs.org/"
+     }
+   }
+   ```
+
+#### PyPI (Python)
+
+1. **Create API Token**:
+
+   ```bash
+   # Using twine
+   twine upload --config-file ~/.pypirc dist/*
+   ```
+
+2. **OIDC Configuration**:
+   ```yaml
+   # .github/workflows/publish.yml
+   - name: Publish to PyPI
+     uses: pypa/gh-action-pypi-publish@release/v1
+     with:
+       password: ${{ secrets.PYPI_API_TOKEN }}
+   ```
+
+### 3. Security Best Practices
+
+#### Token Management
+
+- ✅ **Use short-lived tokens** (1-6 hours)
+- ✅ **Scope tokens to specific repositories**
+- ✅ **Rotate tokens regularly**
+- ❌ **Never store long-lived tokens in code**
+- ❌ **Never commit tokens to version control**
+
+#### Environment Variables
+
+```bash
+# Good: Short-lived, scoped token
+NODE_AUTH_TOKEN=gho_shortlivedtoken123
+
+# Bad: Long-lived, broad token
+NPM_TOKEN=longlivedbroadtoken456
+```
+
+#### Repository Secrets
+
+Store sensitive tokens in repository secrets:
+
+**GitHub**: Settings → Secrets and variables → Actions
+**GitLab**: Settings → CI/CD → Variables
+**Azure DevOps**: Pipelines → Library → Variable groups
+
+### 4. Testing the Setup
+
+#### Local Testing
+
+```bash
+# Test with dry run
+npm publish --dry-run
+
+# Test with local registry
+npm publish --registry http://localhost:4873
+```
+
+#### CI/CD Testing
+
+```yaml
+# Add to your workflow for testing
+- name: Test publish (dry run)
+  run: npm publish --dry-run
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+### 5. Troubleshooting
+
+#### Common Issues
+
+**Token Expired**:
+
+```
+npm ERR! code E401
+npm ERR! Unable to authenticate, need: Basic
+```
+
+**Solution**: Check token expiration and refresh if needed.
+
+**Insufficient Permissions**:
+
+```
+npm ERR! code E403
+npm ERR! Forbidden
+```
+
+**Solution**: Verify token has publish permissions for the package.
+
+**OIDC Provider Issues**:
+
+```
+Error: Failed to get OIDC token
+```
+
+**Solution**: Check OIDC provider configuration and permissions.
+
+#### Debug Mode
+
+Enable debug logging:
+
+```bash
+# npm
+npm config set loglevel verbose
+
+# Python
+export TWINE_VERBOSE=1
+
+# Maven
+mvn deploy -X
+```
+
+### 6. Migration from Legacy Tokens
+
+If you're migrating from username/password or long-lived tokens:
+
+1. **Audit existing tokens**:
+
+   ```bash
+   # npm
+   npm profile get
+
+   # List all tokens
+   npm token list
+   ```
+
+2. **Revoke old tokens**:
+
+   ```bash
+   npm token delete <token-id>
+   ```
+
+3. **Update CI/CD workflows**:
+   - Replace `NPM_TOKEN` with `NODE_AUTH_TOKEN`
+   - Add OIDC permissions
+   - Test in staging environment
+
+### 7. Monitoring and Alerts
+
+Set up monitoring for:
+
+- **Publish failures**: Alert on failed deployments
+- **Token expiration**: Proactive token renewal
+- **Security events**: Unusual publish patterns
+- **Registry status**: External service health
+
+#### Example Monitoring
+
+```yaml
+# .github/workflows/monitor.yml
+name: Monitor Publishing
+
+on:
+  workflow_run:
+    workflows: ['Publish Package']
+    types: [completed]
+
+jobs:
+  monitor:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check publish status
+        if: ${{ github.event.workflow_run.conclusion == 'failure' }}
+        run: |
+          echo "Publish failed! Check logs."
+          # Send alert to Slack/Teams/etc.
+```
+
+## CAWS Integration
+
+For CAWS projects, OIDC setup integrates with:
+
+- **Provenance tracking**: Automatic attestation of published packages
+- **Security scanning**: Validation of published artifacts
+- **Quality gates**: Ensure packages meet standards before publish
+
+### CAWS-Specific Configuration
+
+```yaml
+# .caws/working-spec.yaml
+non_functional:
+  security:
+    - 'oidc-authentication'
+    - 'token-rotation'
+    - 'publish-attestation'
+```
+
+### Automated Provenance
+
+CAWS automatically generates provenance information:
+
+```bash
+# Generate SBOM and attestation
+caws attest --format=slsa
+
+# Validate before publish
+caws validate --security-scan
+```
+
+## Resources
+
+- [npm OIDC Documentation](https://docs.npmjs.com/about-access-tokens)
+- [GitHub Actions OIDC](https://docs.github.com/en/actions/deployment/security/hardening-your-deployments/about-security-hardening-with-openid-connect)
+- [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishing/)
+- [OIDC Specification](https://openid.net/connect/)
+
+## Support
+
+For issues with OIDC setup:
+
+1. Check the troubleshooting section above
+2. Review registry-specific documentation
+3. Open an issue in the CAWS repository
+4. Contact your organization's security team
+
+---
+
+**Note**: This guide provides general OIDC setup instructions. Always follow your organization's specific security policies and procedures.
+