@paths.design/caws-cli 6.0.0 → 7.0.0

package/dist/commands/quality-gates.js

@@ -51,9 +51,9 @@ async function qualityGatesCommand(options = {}) {
         ? path.join(vscodeExtensionPath, 'bundled', 'quality-gates', 'run-quality-gates.mjs')
         : null;
 
-      // Option 3: Check node_modules for quality-gates package
+      // Option 3: Check node_modules for quality-gates package (prioritize published package)
       const nodeModulesPaths = [
-        path.join(projectRoot, 'node_modules', '@caws', 'quality-gates', 'run-quality-gates.mjs'),
+        // Published npm package (priority)
         path.join(
           projectRoot,
           'node_modules',
@@ -61,6 +61,8 @@ async function qualityGatesCommand(options = {}) {
           'quality-gates',
           'run-quality-gates.mjs'
         ),
+        // Legacy monorepo local copy (fallback)
+        path.join(projectRoot, 'node_modules', '@caws', 'quality-gates', 'run-quality-gates.mjs'),
         path.join(projectRoot, 'node_modules', 'quality-gates', 'run-quality-gates.mjs'),
       ];
 

package/dist/index.js

@@ -138,7 +138,7 @@ program
   .option('--json', 'Output machine-readable JSON to stdout', false)
   .option(
     '--gates <gates>',
-    'Run only specific gates (comma-separated: naming,code_freeze,duplication,god_objects,documentation)',
+    'Run only specific gates (comma-separated: naming,code_freeze,duplication,god_objects,hidden-todo,documentation,placeholders)',
     ''
   )
   .option('--fix', 'Attempt automatic fixes (experimental)', false)
@@ -168,7 +168,9 @@ VALID GATES:
   code_freeze      Enforce code freeze compliance
   duplication      Detect functional duplication
   god_objects      Prevent oversized files
+  hidden-todo      Detect hidden incomplete implementations
   documentation    Check documentation quality
+  placeholders     Placeholder governance (explicit degradations)
 
 EXAMPLES:
   # Run all gates in development mode

package/dist/scaffold/git-hooks.js

@@ -147,10 +147,36 @@ fi
 
 QUALITY_GATES_RAN=false
 
-# Option 1: Node.js quality gates script
-if [ -f "scripts/quality-gates/run-quality-gates.js" ]; then
+# Option 1: Quality gates package (installed via npm)
+if [ -f "node_modules/@paths.design/quality-gates/run-quality-gates.mjs" ]; then
   if command -v node >/dev/null 2>&1; then
-    echo "📁 Running Node.js quality gates script..."
+    echo "📁 Running quality gates package..."
+    if node node_modules/@paths.design/quality-gates/run-quality-gates.mjs --ci; then
+      echo "✅ Quality gates passed"
+      QUALITY_GATES_RAN=true
+    else
+      echo "❌ Quality gates failed - commit blocked"
+      echo "💡 Fix the violations above before committing"
+      exit 1
+    fi
+  fi
+# Option 1b: Quality gates package (monorepo/local copy)
+elif [ -f "node_modules/@caws/quality-gates/run-quality-gates.mjs" ]; then
+  if command -v node >/dev/null 2>&1; then
+    echo "📁 Running quality gates package (local)..."
+    if node node_modules/@caws/quality-gates/run-quality-gates.mjs --ci; then
+      echo "✅ Quality gates passed"
+      QUALITY_GATES_RAN=true
+    else
+      echo "❌ Quality gates failed - commit blocked"
+      echo "💡 Fix the violations above before committing"
+      exit 1
+    fi
+  fi
+# Option 2: Legacy Node.js quality gates script (deprecated)
+elif [ -f "scripts/quality-gates/run-quality-gates.js" ]; then
+  if command -v node >/dev/null 2>&1; then
+    echo "📁 Running legacy Node.js quality gates script..."
     if node scripts/quality-gates/run-quality-gates.js; then
       echo "✅ Quality gates passed"
       QUALITY_GATES_RAN=true
@@ -160,7 +186,7 @@ if [ -f "scripts/quality-gates/run-quality-gates.js" ]; then
       exit 1
     fi
   fi
-# Option 2: CAWS CLI validation
+# Option 3: CAWS CLI validation
 elif command -v caws >/dev/null 2>&1; then
   echo "📋 Running CAWS CLI validation..."
   if caws validate --quiet 2>/dev/null; then
@@ -195,16 +221,48 @@ elif [ -f "scripts/simple_gates.py" ] && command -v python3 >/dev/null 2>&1; the
 else
   echo "⚠️  Quality gates not available - skipping"
   echo "💡 Available options:"
-  echo "   • Install: npm install -g @paths.design/caws-cli"
+  echo "   • Install quality gates: npm install --save-dev @paths.design/quality-gates"
+  echo "   • Install CAWS CLI: npm install -g @paths.design/caws-cli"
   echo "   • Use Python: python3 scripts/simple_gates.py"
   echo "   • Use Makefile: make caws-gates"
   QUALITY_GATES_RAN=true
 fi
 
-# Run hidden TODO analysis on staged files only (if Python available)
+# Run hidden TODO analysis on staged files only (if available)
 if [ "$QUALITY_GATES_RAN" = true ]; then
   echo "🔍 Checking for hidden TODOs in staged files..."
-  if command -v python3 >/dev/null 2>&1 && [ -f "scripts/v3/analysis/todo_analyzer.py" ]; then
+  # Try quality gates package TODO analyzer first (published package)
+  if [ -f "node_modules/@paths.design/quality-gates/todo-analyzer.mjs" ]; then
+    if command -v node >/dev/null 2>&1; then
+      if node node_modules/@paths.design/quality-gates/todo-analyzer.mjs --staged-only --ci-mode --min-confidence 0.8 >/dev/null 2>&1; then
+        echo "✅ No critical hidden TODOs found in staged files"
+      else
+        echo "❌ Critical hidden TODOs detected in staged files - commit blocked"
+        echo "💡 Fix stub implementations and placeholder code before committing"
+        echo "📖 See docs/PLACEHOLDER-DETECTION-GUIDE.md for classification"
+        echo ""
+        echo "🔍 Running detailed analysis on staged files..."
+        node node_modules/@paths.design/quality-gates/todo-analyzer.mjs --staged-only --min-confidence 0.8
+        exit 1
+      fi
+    fi
+  # Try quality gates package TODO analyzer (monorepo/local copy)
+  elif [ -f "node_modules/@caws/quality-gates/todo-analyzer.mjs" ]; then
+    if command -v node >/dev/null 2>&1; then
+      if node node_modules/@caws/quality-gates/todo-analyzer.mjs --staged-only --ci-mode --min-confidence 0.8 >/dev/null 2>&1; then
+        echo "✅ No critical hidden TODOs found in staged files"
+      else
+        echo "❌ Critical hidden TODOs detected in staged files - commit blocked"
+        echo "💡 Fix stub implementations and placeholder code before committing"
+        echo "📖 See docs/PLACEHOLDER-DETECTION-GUIDE.md for classification"
+        echo ""
+        echo "🔍 Running detailed analysis on staged files..."
+        node node_modules/@caws/quality-gates/todo-analyzer.mjs --staged-only --min-confidence 0.8
+        exit 1
+      fi
+    fi
+  # Fallback to legacy Python analyzer
+  elif command -v python3 >/dev/null 2>&1 && [ -f "scripts/v3/analysis/todo_analyzer.py" ]; then
     if python3 scripts/v3/analysis/todo_analyzer.py --staged-only --ci-mode --min-confidence 0.8 >/dev/null 2>&1; then
       echo "✅ No critical hidden TODOs found in staged files"
     else

package/dist/scaffold/index.js

@@ -10,6 +10,7 @@ const chalk = require('chalk');
 
 // Import detection utilities
 const { detectCAWSSetup } = require('../utils/detection');
+const { detectsPublishing } = require('../utils/project-analysis');
 
 // Import git hooks scaffolding
 const { scaffoldGitHooks } = require('./git-hooks');
@@ -311,47 +312,152 @@ async function scaffoldProject(options) {
       },
     });
 
-    // Add quality gates scripts for staged file analysis
-    enhancements.push({
-      name: 'scripts/quality-gates/run-quality-gates.js',
-      description: 'Quality gates runner for staged files',
-      required: false,
-    });
+    // Add quality gates package and configuration if requested
+    // Note: These are optional - git hooks fall back to CAWS CLI if package isn't installed
+    if (options.withQualityGates) {
+      // Copy quality gates configuration files from templates
+      enhancements.push({
+        name: 'duplication.qualitygatesrc.yaml',
+        description: 'Duplication gate configuration',
+        required: false,
+        sourcePath: path.join(
+          __dirname,
+          '../../quality-gates/templates/duplication.qualitygatesrc.yaml'
+        ),
+      });
 
-    enhancements.push({
-      name: 'scripts/quality-gates/check-god-objects.js',
-      description: 'God object detector for staged files',
-      required: false,
-    });
+      enhancements.push({
+        name: 'godObject.qualitygatesrc.yaml',
+        description: 'God objects gate configuration',
+        required: false,
+        sourcePath: path.join(
+          __dirname,
+          '../../quality-gates/templates/godObject.qualitygatesrc.yaml'
+        ),
+      });
 
-    enhancements.push({
-      name: 'scripts/v3/analysis/todo_analyzer.py',
-      description: 'Advanced hidden TODO analyzer with dependency resolution',
-      required: false,
-    });
+      // Create docs-status directory structure
+      enhancements.push({
+        name: 'docs-status',
+        description: 'Quality gates status directory',
+        required: false,
+        customHandler: async (targetDir) => {
+          const docsStatusDir = path.join(targetDir, 'docs-status');
+          await fs.ensureDir(docsStatusDir);
+
+          // Copy template files from quality-gates package
+          const qualityGatesTemplates = path.join(
+            __dirname,
+            '../../quality-gates/templates/docs-status'
+          );
+          if (fs.existsSync(qualityGatesTemplates)) {
+            await fs.copy(qualityGatesTemplates, docsStatusDir);
+            return { added: 1, skipped: 0 };
+          }
+          return { added: 1, skipped: 0 };
+        },
+      });
 
-    // Install quality gates package if requested
-    if (options.withQualityGates) {
-      console.log(chalk.blue('\n📦 Installing quality gates package...'));
+      // Install quality gates package
+      console.log(chalk.blue('\n📦 Setting up quality gates package...'));
       try {
         const { execSync } = require('child_process');
-        const npmCommand = fs.existsSync(path.join(currentDir, 'package.json'))
-          ? 'npm install --save-dev @paths.design/quality-gates'
-          : 'npm install -g @paths.design/quality-gates';
-
-        console.log(chalk.gray(`   Running: ${npmCommand}`));
-        execSync(npmCommand, {
-          cwd: currentDir,
-          stdio: 'inherit',
-        });
-        console.log(chalk.green('✅ Quality gates package installed'));
-        console.log(chalk.blue('💡 You can now use: caws quality-gates'));
+
+        // Check if we're in monorepo (can copy files directly) or need npm install
+        const qualityGatesPath = path.resolve(__dirname, '../../../quality-gates');
+        const isMonorepo = fs.existsSync(qualityGatesPath);
+
+        if (isMonorepo && fs.existsSync(path.join(currentDir, 'package.json'))) {
+          // In monorepo - copy files directly instead of installing package
+          console.log(
+            chalk.gray('   Detected monorepo structure - copying quality gates files...')
+          );
+
+          const qualityGatesDest = path.join(currentDir, 'node_modules', '@caws', 'quality-gates');
+          await fs.ensureDir(qualityGatesDest);
+
+          // Copy all .mjs files
+          const mjsFiles = fs.readdirSync(qualityGatesPath).filter((f) => f.endsWith('.mjs'));
+          for (const file of mjsFiles) {
+            await fs.copy(path.join(qualityGatesPath, file), path.join(qualityGatesDest, file));
+          }
+
+          // Copy templates directory
+          if (fs.existsSync(path.join(qualityGatesPath, 'templates'))) {
+            await fs.copy(
+              path.join(qualityGatesPath, 'templates'),
+              path.join(qualityGatesDest, 'templates')
+            );
+          }
+
+          // Copy package.json for dependencies
+          await fs.copy(
+            path.join(qualityGatesPath, 'package.json'),
+            path.join(qualityGatesDest, 'package.json')
+          );
+
+          // Install dependencies
+          console.log(chalk.gray('   Installing quality gates dependencies...'));
+          execSync('npm install --production --no-audit --no-fund', {
+            cwd: qualityGatesDest,
+            stdio: 'inherit',
+          });
+
+          console.log(chalk.green('✅ Quality gates files copied and dependencies installed'));
+        } else if (fs.existsSync(path.join(currentDir, 'package.json'))) {
+          // Regular project - try to install from npm (when published)
+          console.log(chalk.gray('   Installing @paths.design/quality-gates package...'));
+
+          try {
+            const npmCommand = 'npm install --save-dev @paths.design/quality-gates';
+            execSync(npmCommand, {
+              cwd: currentDir,
+              stdio: 'inherit',
+            });
+            console.log(chalk.green('✅ Quality gates package installed from npm'));
+          } catch (npmError) {
+            console.log(
+              chalk.yellow('⚠️  Package not found on npm - quality gates will use local files')
+            );
+            console.log(
+              chalk.gray(
+                '   Package will be available once published as @paths.design/quality-gates'
+              )
+            );
+            console.log(
+              chalk.gray('   For now, quality gates will work via CAWS CLI or local scripts')
+            );
+          }
+        } else {
+          // No package.json - suggest global install or manual setup
+          console.log(chalk.yellow('⚠️  No package.json found - skipping package installation'));
+          console.log(chalk.gray('   Options:'));
+          console.log(
+            chalk.gray('   • Install globally: npm install -g @paths.design/quality-gates')
+          );
+          console.log(
+            chalk.gray(
+              '   • Create package.json and run: npm install --save-dev @paths.design/quality-gates'
+            )
+          );
+          console.log(chalk.gray('   • Use CAWS CLI: caws quality-gates'));
+        }
+
+        console.log(
+          chalk.blue(
+            '💡 You can now use: node node_modules/@paths.design/quality-gates/run-quality-gates.mjs'
+          )
+        );
+        console.log(chalk.blue('   Or: caws quality-gates'));
       } catch (error) {
-        console.log(chalk.yellow(`⚠️  Failed to install quality gates package: ${error.message}`));
+        console.log(chalk.yellow(`⚠️  Failed to set up quality gates package: ${error.message}`));
         console.log(
-          chalk.gray('   You can install manually: npm install -g @paths.design/quality-gates')
+          chalk.gray(
+            '   You can install manually: npm install --save-dev @paths.design/quality-gates'
+          )
         );
-        console.log(chalk.gray('   Or use Python scripts: python3 scripts/simple_gates.py'));
+        console.log(chalk.gray('   Or globally: npm install -g @paths.design/quality-gates'));
+        console.log(chalk.gray('   Or use CAWS CLI: caws quality-gates'));
       }
     }
 
@@ -377,16 +483,26 @@ async function scaffoldProject(options) {
       });
     }
 
-    // Add OIDC setup guide if requested or not minimal
-    if (
-      (options.withOidc || (!options.minimal && !options.withOidc)) &&
-      (!setup.isEnhanced || !fs.existsSync(path.join(currentDir, 'OIDC_SETUP.md')))
-    ) {
+    // Add OIDC setup guide only if:
+    // 1. Explicitly requested with --with-oidc flag, OR
+    // 2. Project detects publishing configuration (package.json with publishConfig, pyproject.toml, etc.)
+    const needsOidc = options.withOidc || detectsPublishing(currentDir);
+    const oidcExists = fs.existsSync(path.join(currentDir, 'OIDC_SETUP.md'));
+
+    if (needsOidc && !oidcExists) {
       enhancements.push({
         name: 'OIDC_SETUP.md',
         description: 'OIDC trusted publisher setup guide',
         required: false,
       });
+    } else if (needsOidc && oidcExists) {
+      console.log(chalk.gray('⏭️  Skipped OIDC_SETUP.md (already exists)'));
+    } else if (!needsOidc && !options.minimal) {
+      // Inform user that OIDC is available but not needed
+      console.log(
+        chalk.blue('ℹ️  OIDC setup skipped (project does not appear to publish packages)')
+      );
+      console.log(chalk.gray('   Add --with-oidc flag if you plan to publish packages later'));
     }
 
     // For enhanced setups, preserve existing tools
@@ -424,13 +540,20 @@ async function scaffoldProject(options) {
         continue;
       }
 
-      if (!setup?.templateDir) {
+      // Handle custom sourcePath (for quality gates configs from monorepo)
+      const sourcePath = enhancement.sourcePath
+        ? enhancement.sourcePath
+        : setup?.templateDir
+          ? path.join(setup.templateDir, enhancement.name)
+          : null;
+
+      if (!sourcePath && !enhancement.sourcePath) {
         console.warn(
           chalk.yellow(`⚠️  Template directory not available for enhancement: ${enhancement.name}`)
         );
         continue;
       }
-      const sourcePath = path.join(setup.templateDir, enhancement.name);
+
       const destPath = path.join(currentDir, enhancement.name);
 
       if (!fs.existsSync(destPath)) {
@@ -497,6 +620,10 @@ async function scaffoldProject(options) {
 
       // Check if OIDC was added
       const oidcAdded = addedFiles.some((file) => file.includes('OIDC_SETUP'));
+      const qualityGatesAdded = addedFiles.some(
+        (file) => file.includes('quality-gates') || file.includes('todo_analyzer')
+      );
+
       if (oidcAdded) {
         console.log('2. Set up OIDC trusted publisher (see OIDC_SETUP.md)');
         console.log('3. Push to trigger automated publishing');
@@ -504,7 +631,18 @@ async function scaffoldProject(options) {
       } else {
         console.log('2. Customize your working spec in .caws/working-spec.yaml');
         console.log('3. Run validation: caws validate --suggestions');
-        console.log('4. Your existing CAWS tools remain unchanged');
+        if (!qualityGatesAdded && !options.minimal) {
+          console.log(
+            chalk.gray('4. Note: Quality gates scripts skipped (git hooks use CAWS CLI by default)')
+          );
+          console.log(
+            chalk.gray(
+              '   Add --with-quality-gates flag if you want local scripts without global CLI'
+            )
+          );
+        } else {
+          console.log('4. Your existing CAWS tools remain unchanged');
+        }
       }
     }
 

package/dist/utils/project-analysis.js

@@ -99,7 +99,110 @@ function shouldInitInCurrentDirectory(projectName, currentDir) {
   return hasProjectIndicators;
 }
 
+/**
+ * Detect if project publishes packages to registries
+ * Checks for publishing configuration in package.json, pyproject.toml, etc.
+ * @param {string} cwd - Current working directory
+ * @returns {boolean} Whether project appears to publish packages
+ */
+function detectsPublishing(cwd = process.cwd()) {
+  const files = fs.readdirSync(cwd);
+
+  // Check package.json for npm publishing
+  if (files.includes('package.json')) {
+    try {
+      const packageJson = JSON.parse(
+        fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')
+      );
+
+      // Indicators of publishing:
+      // - Has publishConfig
+      // - Has scripts that include "publish"
+      // - Has name that suggests it's a published package
+      // - Has repository field (often indicates published package)
+      const hasPublishConfig = packageJson.publishConfig;
+      const hasPublishScript =
+        packageJson.scripts &&
+        Object.keys(packageJson.scripts).some((key) =>
+          key.toLowerCase().includes('publish')
+        );
+      const hasScopedName = packageJson.name && packageJson.name.startsWith('@');
+      const hasRepository = packageJson.repository;
+
+      if (hasPublishConfig || hasPublishScript || (hasScopedName && hasRepository)) {
+        return true;
+      }
+    } catch (e) {
+      // Ignore parse errors
+    }
+  }
+
+  // Check pyproject.toml for PyPI publishing
+  if (files.includes('pyproject.toml')) {
+    try {
+      const pyprojectContent = fs.readFileSync(
+        path.join(cwd, 'pyproject.toml'),
+        'utf8'
+      );
+
+      // Check for build system and project metadata (indicates publishable package)
+      const hasBuildSystem = pyprojectContent.includes('[build-system]');
+      const hasProjectMetadata = pyprojectContent.includes('[project]');
+      const hasToolPublish = pyprojectContent.includes('[tool.publish]') ||
+                            pyprojectContent.includes('[tool.twine]');
+
+      if ((hasBuildSystem && hasProjectMetadata) || hasToolPublish) {
+        return true;
+      }
+    } catch (e) {
+      // Ignore read errors
+    }
+  }
+
+  // Check for Maven publishing (pom.xml)
+  if (files.includes('pom.xml')) {
+    return true; // Maven projects typically publish
+  }
+
+  // Check for .csproj (NuGet publishing)
+  const csprojFiles = files.filter((f) => f.endsWith('.csproj'));
+  if (csprojFiles.length > 0) {
+    return true; // .NET projects typically publish
+  }
+
+  // Check for GitHub Actions workflows that publish
+  const workflowsPath = path.join(cwd, '.github', 'workflows');
+  if (fs.existsSync(workflowsPath)) {
+    try {
+      const workflowFiles = fs.readdirSync(workflowsPath);
+      for (const workflowFile of workflowFiles) {
+        if (workflowFile.endsWith('.yml') || workflowFile.endsWith('.yaml')) {
+          const workflowContent = fs.readFileSync(
+            path.join(workflowsPath, workflowFile),
+            'utf8'
+          );
+          // Check for common publishing actions/commands
+          if (
+            workflowContent.includes('npm publish') ||
+            workflowContent.includes('pypa/gh-action-pypi-publish') ||
+            workflowContent.includes('publish-to-npm') ||
+            workflowContent.includes('semantic-release') ||
+            workflowContent.includes('publish')
+          ) {
+            return true;
+          }
+        }
+      }
+    } catch (e) {
+      // Ignore read errors
+    }
+  }
+
+  return false;
+}
+
 module.exports = {
   detectProjectType,
   shouldInitInCurrentDirectory,
+  detectsPublishing,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "6.0.0",
+  "version": "7.0.0",
   "description": "CAWS CLI - Coding Agent Workflow System command line tools",
   "main": "dist/index.js",
   "bin": {