@paths.design/caws-cli 3.2.4 → 3.3.1

package/dist/scaffold/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scaffold/index.js"],"names":[],"mappings":"AAkKA;;;GAGG;AACH,6DA6TC;AAhdD;;;;GAIG;AACH,mDAHW,MAAM;;;GA8HhB;AAMD;;;GAGG;AACH,yDAGC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scaffold/index.js"],"names":[],"mappings":"AAkKA;;;GAGG;AACH,6DA0UC;AA7dD;;;;GAIG;AACH,mDAHW,MAAM;;;GA8HhB;AAMD;;;GAGG;AACH,yDAGC"}

package/dist/scaffold/index.js

@@ -320,6 +320,19 @@ async function scaffoldProject(options) {
       });
     }
 
+    // Add AGENTS.md guide for agent workflow instructions
+    if (
+      !fs.existsSync(path.join(currentDir, 'agents.md')) &&
+      !fs.existsSync(path.join(currentDir, 'AGENTS.md')) &&
+      !fs.existsSync(path.join(currentDir, 'caws.md'))
+    ) {
+      enhancements.push({
+        name: 'agents.md',
+        description: 'CAWS agent workflow guide',
+        required: false,
+      });
+    }
+
     // Add OIDC setup guide if requested or not minimal
     if (
       (options.withOidc || (!options.minimal && !options.withOidc)) &&

package/dist/utils/typescript-detector.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Detect if project is using TypeScript
+ * @param {string} projectDir - Project directory path
+ * @returns {Object} TypeScript detection result
+ */
+export function detectTypeScript(projectDir?: string): any;
+/**
+ * Detect testing framework in use
+ * @param {string} projectDir - Project directory path
+ * @param {Object} packageJson - Parsed package.json (optional)
+ * @returns {Object} Testing framework detection result
+ */
+export function detectTestFramework(projectDir?: string, packageJson?: any): any;
+/**
+ * Check if TypeScript project needs test configuration
+ * @param {string} projectDir - Project directory path
+ * @returns {Object} Configuration status
+ */
+export function checkTypeScriptTestConfig(projectDir?: string): any;
+/**
+ * Generate configuration recommendations
+ * @param {Object} tsDetection - TypeScript detection result
+ * @param {Object} testDetection - Test framework detection result
+ * @returns {string[]} Array of recommendations
+ */
+export function generateRecommendations(tsDetection: any, testDetection: any): string[];
+/**
+ * Display TypeScript detection results
+ * @param {Object} detection - Detection result from checkTypeScriptTestConfig
+ */
+export function displayTypeScriptDetection(detection: any): void;
+//# sourceMappingURL=typescript-detector.d.ts.map

package/dist/utils/typescript-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript-detector.d.ts","sourceRoot":"","sources":["../../src/utils/typescript-detector.js"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,8CAHW,MAAM,OAkChB;AAED;;;;;GAKG;AACH,iDAJW,MAAM,0BAkDhB;AAED;;;;GAIG;AACH,uDAHW,MAAM,OAiBhB;AAED;;;;;GAKG;AACH,+EAFa,MAAM,EAAE,CAuBpB;AAED;;;GAGG;AACH,iEAoBC"}

package/dist/utils/typescript-detector.js

@@ -0,0 +1,185 @@
+/**
+ * @fileoverview TypeScript Project Detection and Configuration
+ * Auto-detects TypeScript projects and configures testing frameworks
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * Detect if project is using TypeScript
+ * @param {string} projectDir - Project directory path
+ * @returns {Object} TypeScript detection result
+ */
+function detectTypeScript(projectDir = process.cwd()) {
+  const tsconfigPath = path.join(projectDir, 'tsconfig.json');
+  const packageJsonPath = path.join(projectDir, 'package.json');
+
+  const hasTsConfig = fs.existsSync(tsconfigPath);
+
+  let hasTypeScriptDep = false;
+  let packageJson = null;
+
+  if (fs.existsSync(packageJsonPath)) {
+    try {
+      packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+      const allDeps = {
+        ...packageJson.dependencies,
+        ...packageJson.devDependencies,
+      };
+      hasTypeScriptDep = 'typescript' in allDeps;
+    } catch (error) {
+      // Ignore parse errors
+    }
+  }
+
+  const isTypeScript = hasTsConfig || hasTypeScriptDep;
+
+  return {
+    isTypeScript,
+    hasTsConfig,
+    hasTypeScriptDep,
+    packageJson,
+    tsconfigPath: hasTsConfig ? tsconfigPath : null,
+  };
+}
+
+/**
+ * Detect testing framework in use
+ * @param {string} projectDir - Project directory path
+ * @param {Object} packageJson - Parsed package.json (optional)
+ * @returns {Object} Testing framework detection result
+ */
+function detectTestFramework(projectDir = process.cwd(), packageJson = null) {
+  if (!packageJson) {
+    const packageJsonPath = path.join(projectDir, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+      packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    }
+  }
+
+  const hasJestConfig =
+    fs.existsSync(path.join(projectDir, 'jest.config.js')) ||
+    fs.existsSync(path.join(projectDir, 'jest.config.ts')) ||
+    fs.existsSync(path.join(projectDir, 'jest.config.json')) ||
+    packageJson?.jest;
+
+  const hasVitestConfig =
+    fs.existsSync(path.join(projectDir, 'vitest.config.js')) ||
+    fs.existsSync(path.join(projectDir, 'vitest.config.ts'));
+
+  const allDeps = {
+    ...packageJson?.dependencies,
+    ...packageJson?.devDependencies,
+  };
+
+  const hasJestDep = 'jest' in allDeps || '@types/jest' in allDeps;
+  const hasVitestDep = 'vitest' in allDeps;
+  const hasTsJest = 'ts-jest' in allDeps;
+
+  let framework = 'none';
+  let isConfigured = false;
+
+  if (hasJestConfig || hasJestDep) {
+    framework = 'jest';
+    isConfigured = hasJestConfig;
+  } else if (hasVitestConfig || hasVitestDep) {
+    framework = 'vitest';
+    isConfigured = hasVitestConfig;
+  }
+
+  return {
+    framework,
+    isConfigured,
+    hasJest: hasJestDep,
+    hasVitest: hasVitestDep,
+    hasTsJest,
+    needsTypeScriptConfig: false, // Will be set by checkTypeScriptTestConfig
+  };
+}
+
+/**
+ * Check if TypeScript project needs test configuration
+ * @param {string} projectDir - Project directory path
+ * @returns {Object} Configuration status
+ */
+function checkTypeScriptTestConfig(projectDir = process.cwd()) {
+  const tsDetection = detectTypeScript(projectDir);
+  const testDetection = detectTestFramework(projectDir, tsDetection.packageJson);
+
+  const needsConfig =
+    tsDetection.isTypeScript && testDetection.framework === 'jest' && !testDetection.hasTsJest;
+
+  return {
+    ...tsDetection,
+    testFramework: testDetection,
+    needsJestConfig: tsDetection.isTypeScript && !testDetection.isConfigured,
+    needsTsJest: needsConfig,
+    recommendations: generateRecommendations(tsDetection, testDetection),
+  };
+}
+
+/**
+ * Generate configuration recommendations
+ * @param {Object} tsDetection - TypeScript detection result
+ * @param {Object} testDetection - Test framework detection result
+ * @returns {string[]} Array of recommendations
+ */
+function generateRecommendations(tsDetection, testDetection) {
+  const recommendations = [];
+
+  if (tsDetection.isTypeScript && testDetection.framework === 'none') {
+    recommendations.push('No testing framework detected');
+    recommendations.push('Recommended: Install Jest with ts-jest');
+    recommendations.push('Run: npm install --save-dev jest @types/jest ts-jest');
+  }
+
+  if (tsDetection.isTypeScript && testDetection.framework === 'jest' && !testDetection.hasTsJest) {
+    recommendations.push('Jest detected but missing TypeScript support');
+    recommendations.push('Install ts-jest: npm install --save-dev ts-jest');
+    recommendations.push('Or run: caws diagnose to auto-configure');
+  }
+
+  if (tsDetection.isTypeScript && !testDetection.isConfigured) {
+    recommendations.push('Testing framework not configured');
+    recommendations.push('Run: caws scaffold to add test configuration');
+  }
+
+  return recommendations;
+}
+
+/**
+ * Display TypeScript detection results
+ * @param {Object} detection - Detection result from checkTypeScriptTestConfig
+ */
+function displayTypeScriptDetection(detection) {
+  if (!detection.isTypeScript) {
+    return;
+  }
+
+  console.log(chalk.cyan('\n📦 TypeScript Project Detected'));
+  console.log(chalk.gray(`   tsconfig.json: ${detection.hasTsConfig ? '✅' : '❌'}`));
+  console.log(chalk.gray(`   typescript dependency: ${detection.hasTypeScriptDep ? '✅' : '❌'}`));
+
+  if (detection.testFramework.framework !== 'none') {
+    console.log(chalk.gray(`   Test framework: ${detection.testFramework.framework}`));
+    console.log(chalk.gray(`   Configured: ${detection.testFramework.isConfigured ? '✅' : '❌'}`));
+  }
+
+  if (detection.recommendations.length > 0) {
+    console.log(chalk.yellow('\n💡 Recommendations:'));
+    detection.recommendations.forEach((rec) => {
+      console.log(chalk.yellow(`   ${rec}`));
+    });
+  }
+}
+
+module.exports = {
+  detectTypeScript,
+  detectTestFramework,
+  checkTypeScriptTestConfig,
+  generateRecommendations,
+  displayTypeScriptDetection,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "3.2.4",
+  "version": "3.3.1",
   "description": "CAWS CLI - Coding Agent Workflow System command line tools",
   "main": "dist/index.js",
   "bin": {
@@ -52,9 +52,11 @@
   },
   "dependencies": {
     "ajv": "^8.12.0",
+    "chalk": "4.1.2",
     "commander": "^11.0.0",
     "fs-extra": "^11.0.0",
-    "inquirer": "8.2.7"
+    "inquirer": "8.2.7",
+    "js-yaml": "4.1.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",
@@ -66,10 +68,8 @@
     "@types/inquirer": "^8.2.6",
     "@types/js-yaml": "^4.0.0",
     "@types/node": "^20.0.0",
-    "chalk": "4.1.2",
     "eslint": "^9.0.0",
     "jest": "30.1.3",
-    "js-yaml": "4.1.0",
     "lint-staged": "15.5.2",
     "prettier": "^3.0.0",
     "semantic-release": "25.0.0-beta.6",

package/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.
+