@paths.design/caws-cli 9.3.2 → 10.0.1

package/dist/utils/spec-resolver.js

@@ -13,6 +13,34 @@ const chalk = require('chalk');
 // Import SPEC_TYPES from constants for consistent display
 const { SPEC_TYPES } = require('../constants/spec-types');
 const { findProjectRoot } = require('./detection');
+const { createValidator, getSchemaPath } = require('./schema-validator');
+
+/**
+ * Validate a spec object against the working-spec schema.
+ * Throws with schema errors included in the message.
+ * @param {Object} spec - Parsed spec object
+ * @param {string} specPath - Path to the spec file (for error context)
+ */
+function validateSpecSchema(spec, specPath) {
+  try {
+    const schemaPath = getSchemaPath('working-spec.schema.json', getProjectRoot());
+    const validate = createValidator(schemaPath);
+    const result = validate(spec);
+    if (!result.valid) {
+      const errorDetails = result.errors
+        .map(e => `  ${e.path}: ${e.message}`)
+        .join('\n');
+      // Schema violations are warnings, not fatal — the spec is still loadable.
+      // Commands like validate will report these; other commands shouldn't be blocked.
+      if (process.env.CAWS_QUIET !== '1') {
+        console.warn(`Schema warnings for ${specPath}:\n${errorDetails}`);
+      }
+    }
+  } catch (schemaErr) {
+    // Schema loading/compilation errors are non-fatal — warn and continue
+    console.warn('Could not validate spec schema:', schemaErr.message);
+  }
+}
 
 /**
  * Spec resolution priority:
@@ -42,10 +70,11 @@ function getProjectRoot() {
  * @param {string} [options.specFile] - Explicit file path override
  * @param {boolean} [options.warnLegacy=true] - Warn when falling back to legacy spec
  * @param {boolean} [options.interactive=false] - Use interactive spec selection for multiple specs
+ * @param {boolean} [options.quiet=false] - Suppress informational logging for machine-readable output
  * @returns {Promise<{path: string, type: 'feature' | 'legacy', spec: Object}>}
  */
 async function resolveSpec(options = {}) {
-  const { specId, specFile, warnLegacy = true, interactive = false } = options;
+  const { specId, specFile, warnLegacy = true, interactive = false, quiet = false } = options;
 
   // 1. Explicit file path takes highest priority
   if (specFile) {
@@ -54,7 +83,13 @@ async function resolveSpec(options = {}) {
     if (await fs.pathExists(explicitPath)) {
       const yaml = require('js-yaml');
       const content = await fs.readFile(explicitPath, 'utf8');
-      const spec = yaml.load(content);
+      let spec;
+      try {
+        spec = yaml.load(content);
+      } catch (yamlError) {
+        throw new Error(`Invalid YAML in spec file ${explicitPath}: ${yamlError.message}`);
+      }
+      validateSpecSchema(spec, explicitPath);
 
       return {
         path: explicitPath,
@@ -74,8 +109,11 @@ async function resolveSpec(options = {}) {
       const yaml = require('js-yaml');
       const content = await fs.readFile(featurePath, 'utf8');
       const spec = yaml.load(content);
+      validateSpecSchema(spec, featurePath);
 
-      console.log(chalk.green(`Using feature-specific spec: ${specId}`));
+      if (!quiet) {
+        console.log(chalk.green(`Using feature-specific spec: ${specId}`));
+      }
 
       return {
         path: featurePath,
@@ -102,8 +140,11 @@ async function resolveSpec(options = {}) {
       const yaml = require('js-yaml');
       const content = await fs.readFile(singleSpecPath, 'utf8');
       const spec = yaml.load(content);
+      validateSpecSchema(spec, singleSpecPath);
 
-      console.log(chalk.blue(`Auto-detected single spec: ${singleSpecId}`));
+      if (!quiet) {
+        console.log(chalk.blue(`Auto-detected single spec: ${singleSpecId}`));
+      }
 
       return {
         path: singleSpecPath,
@@ -113,19 +154,23 @@ async function resolveSpec(options = {}) {
     }
   } else if (specIds.length > 1) {
     // Multiple specs - require explicit selection with enhanced guidance
-    console.error(chalk.red('Multiple specs detected. Please specify which one:'));
+    if (!quiet) {
+      console.error(chalk.red('Multiple specs detected. Please specify which one:'));
+    }
 
     // Show specs with details
     const specsInfo = [];
     for (const id of specIds) {
-      const specPath = path.join(SPECS_DIR, registry.specs[id].path);
+      const specPath = path.join(getProjectRoot(), SPECS_DIR, registry.specs[id].path);
       try {
         const content = await fs.readFile(specPath, 'utf8');
         let spec;
         try {
           spec = yaml.load(content);
         } catch (yamlError) {
-          console.log(chalk.yellow(`   - ${id} (YAML syntax error: ${yamlError.message})`));
+          if (!quiet) {
+            console.log(chalk.yellow(`   - ${id} (YAML syntax error: ${yamlError.message})`));
+          }
           specsInfo.push({ id, type: 'unknown', status: 'unknown', title: 'YAML error' });
           continue;
         }
@@ -135,14 +180,18 @@ async function resolveSpec(options = {}) {
           status === 'active' ? chalk.green : status === 'completed' ? chalk.blue : chalk.yellow;
         const typeColor = SPEC_TYPES[type] ? SPEC_TYPES[type].color : chalk.white;
 
-        console.log(
-          chalk.yellow(
-            `   - ${id} ${typeColor(`(${type})`)} ${statusColor(`[${status}]`)} - ${spec.title || 'Untitled'}`
-          )
-        );
+        if (!quiet) {
+          console.log(
+            chalk.yellow(
+              `   - ${id} ${typeColor(`(${type})`)} ${statusColor(`[${status}]`)} - ${spec.title || 'Untitled'}`
+            )
+          );
+        }
         specsInfo.push({ id, type, status, title: spec.title || 'Untitled' });
       } catch (error) {
-        console.log(chalk.yellow(`   - ${id} (error loading details: ${error.message})`));
+        if (!quiet) {
+          console.log(chalk.yellow(`   - ${id} (error loading details: ${error.message})`));
+        }
         specsInfo.push({ id, type: 'unknown', status: 'unknown', title: 'Error loading' });
       }
     }
@@ -157,14 +206,17 @@ async function resolveSpec(options = {}) {
           specId: selectedSpecId,
           warnLegacy,
           interactive: false, // Prevent infinite recursion
+          quiet,
         });
       } catch (error) {
         throw new Error(`Interactive selection failed: ${error.message}`);
       }
     }
 
-    console.log(chalk.blue('\n   Usage: caws <command> --spec-id <spec-id>'));
-    console.log(chalk.gray(`   Example: caws validate --spec-id ${specIds[0]}`));
+    if (!quiet) {
+      console.log(chalk.blue('\n   Usage: caws <command> --spec-id <spec-id>'));
+      console.log(chalk.gray(`   Example: caws validate --spec-id ${specIds[0]}`));
+    }
 
     // Suggest most likely spec (active first, then by type priority)
     const priorityOrder = { active: 0, draft: 1, completed: 2 };
@@ -182,11 +234,15 @@ async function resolveSpec(options = {}) {
       return aTypePriority - bTypePriority;
     });
 
-    console.log(chalk.green('\nQuick suggestion:'));
-    console.log(chalk.gray(`   Try: caws <command> --spec-id ${sortedSpecs[0]}`));
+    if (!quiet) {
+      console.log(chalk.green('\nQuick suggestion:'));
+      console.log(chalk.gray(`   Try: caws <command> --spec-id ${sortedSpecs[0]}`));
+    }
 
     // Interactive mode suggestion
-    console.log(chalk.blue('\n   Interactive mode: caws <command> --interactive-spec-selection'));
+    if (!quiet) {
+      console.log(chalk.blue('\n   Interactive mode: caws <command> --interactive-spec-selection'));
+    }
 
     throw new Error('Spec ID required when multiple specs exist');
   }
@@ -198,8 +254,9 @@ async function resolveSpec(options = {}) {
     const yaml = require('js-yaml');
     const content = await fs.readFile(legacyPath, 'utf8');
     const spec = yaml.load(content);
+    validateSpecSchema(spec, legacyPath);
 
-    if (warnLegacy) {
+    if (warnLegacy && !quiet) {
       console.log(chalk.yellow('Using legacy working-spec.yaml'));
       console.log(chalk.gray('   For multi-agent workflows, use feature-specific specs:'));
       console.log(chalk.blue('   caws specs create <feature-id>'));
@@ -236,7 +293,19 @@ async function loadSpecsRegistry() {
 
   try {
     const registry = await fs.readJson(registryPath);
-    return registry;
+    const sanitizedSpecs = {};
+
+    for (const [id, entry] of Object.entries(registry.specs || {})) {
+      const specPath = path.join(getProjectRoot(), SPECS_DIR, entry.path);
+      if (await fs.pathExists(specPath)) {
+        sanitizedSpecs[id] = entry;
+      }
+    }
+
+    return {
+      ...registry,
+      specs: sanitizedSpecs,
+    };
   } catch (error) {
     return {
       version: '1.0.0',
@@ -379,7 +448,10 @@ async function checkScopeConflicts(specIds) {
 
   // Load all specs and their scopes
   for (const id of specIds) {
-    const specPath = path.join(SPECS_DIR, registry.specs[id].path);
+    const entry = registry.specs[id];
+    if (!entry) continue;
+
+    const specPath = path.join(getProjectRoot(), SPECS_DIR, entry.path);
 
     try {
       const content = await fs.readFile(specPath, 'utf8');