kiro-spec-engine 1.32.0 → 1.33.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.33.0] - 2026-02-10
+
+### Added
+- **Scene Package Directory Validation**: Comprehensive validation for scene package directories
+  - `kse scene package-validate --package <dir>` now supports directory-level validation
+    - `--strict` treat warnings as errors (exit code 1)
+    - `--json` structured JSON output
+  - Validates `scene-package.json` existence and required fields
+  - Contract-level validation via `validateScenePackageContract`
+  - Semver validation for `metadata.version` using `semver.valid`
+  - File existence checks for `artifacts.entry_scene` and `artifacts.generates`
+  - Template variable schema validation if `variables` present
+  - Collects all errors/warnings (no early exit)
+  - New `validateScenePackageDirectory` helper for programmatic use
+  - Follows normalize → validate → run → print pattern
+  - Implements Spec 83-00-scene-validate
+
 ## [1.32.0] - 2026-02-10
 
 ### Added

package/lib/commands/scene.js

@@ -367,6 +367,7 @@ function registerSceneCommands(program) {
     .option('-p, --package <path>', 'Path to scene package contract JSON')
     .option('--spec-package <relative-path>', 'Package path inside spec folder', 'custom/scene-package.json')
     .option('--json', 'Print validation payload as JSON')
+    .option('--strict', 'Treat warnings as errors')
     .action(async (options) => {
       await runScenePackageValidateCommand(options);
     });
@@ -801,7 +802,8 @@ function normalizeScenePackageValidateOptions(options = {}) {
     spec: options.spec ? String(options.spec).trim() : undefined,
     packagePath: options.package ? String(options.package).trim() : undefined,
     specPackage: normalizeRelativePath(options.specPackage || 'custom/scene-package.json') || 'custom/scene-package.json',
-    json: options.json === true
+    json: options.json === true,
+    strict: options.strict === true
   };
 }
 
@@ -5890,6 +5892,12 @@ function printScenePackageValidateSummary(options, payload, projectRoot = proces
   const statusLabel = payload.valid ? chalk.green('valid') : chalk.red('invalid');
   console.log(chalk.blue('Scene Package Validate'));
   console.log(`  Status: ${statusLabel}`);
+  if (payload.strict) {
+    console.log(`  Mode: ${chalk.yellow('strict')}`);
+  }
+  if (payload.input && payload.input.mode) {
+    console.log(`  Validation: ${payload.input.mode}`);
+  }
   console.log(`  Source: ${chalk.gray(resolvePath(projectRoot, payload.input.path))}`);
 
   if (payload.summary.coordinate) {
@@ -5899,6 +5907,10 @@ function printScenePackageValidateSummary(options, payload, projectRoot = proces
   console.log(`  Kind: ${payload.summary.kind || 'unknown'}`);
   console.log(`  Parameters: ${payload.summary.parameter_count}`);
 
+  if (typeof payload.summary.files_checked === 'number') {
+    console.log(`  Files checked: ${payload.summary.files_checked}, missing: ${payload.summary.files_missing}`);
+  }
+
   if (Array.isArray(payload.errors) && payload.errors.length > 0) {
     console.log(chalk.red('  Errors:'));
     for (const error of payload.errors) {
@@ -6831,6 +6843,105 @@ async function runScenePackageTemplateCommand(rawOptions = {}, dependencies = {}
   }
 }
 
+async function validateScenePackageDirectory(packageDir, fileSystem) {
+  const _fs = fileSystem || fs;
+  const readJson = typeof _fs.readJson === 'function' ? _fs.readJson.bind(_fs) : fs.readJson.bind(fs);
+  const errors = [];
+  const warnings = [];
+  const fileChecks = { checked: 0, missing: 0 };
+
+  // Read scene-package.json
+  const manifestPath = path.join(packageDir, 'scene-package.json');
+  let contract;
+  try {
+    contract = await readJson(manifestPath);
+  } catch (err) {
+    return {
+      valid: false,
+      contract: null,
+      errors: [`scene-package.json not found or not valid JSON in ${packageDir}: ${err.message}`],
+      warnings: [],
+      fileChecks: { checked: 0, missing: 0 },
+      summary: { coordinate: null, kind: null, parameter_count: 0, provides_count: 0, requires_count: 0, file_count: 0, files_checked: 0, files_missing: 0 }
+    };
+  }
+
+  // Contract-level validation
+  const contractResult = validateScenePackageContract(contract);
+  errors.push(...contractResult.errors);
+  warnings.push(...contractResult.warnings);
+
+  // Semver validation (more precise than contract regex)
+  const metadata = isPlainObject(contract.metadata) ? contract.metadata : {};
+  const version = String(metadata.version || '').trim();
+  if (version && !semver.valid(version)) {
+    const hasSemverError = errors.some(e => e.includes('metadata.version'));
+    if (!hasSemverError) {
+      errors.push(`metadata.version "${version}" is not valid semver`);
+    }
+  }
+
+  // File existence checks
+  const artifacts = isPlainObject(contract.artifacts) ? contract.artifacts : {};
+  const filesToCheck = [];
+  if (typeof artifacts.entry_scene === 'string' && artifacts.entry_scene.trim()) {
+    filesToCheck.push(artifacts.entry_scene.trim());
+  }
+  if (Array.isArray(artifacts.generates)) {
+    for (const g of artifacts.generates) {
+      if (typeof g === 'string' && g.trim()) {
+        filesToCheck.push(g.trim());
+      }
+    }
+  }
+
+  for (const filePath of filesToCheck) {
+    fileChecks.checked++;
+    const fullPath = path.join(packageDir, filePath);
+    try {
+      const stat = typeof _fs.stat === 'function' ? _fs.stat.bind(_fs) : fs.stat.bind(fs);
+      await stat(fullPath);
+    } catch (_e) {
+      fileChecks.missing++;
+      errors.push(`referenced file not found: ${filePath}`);
+    }
+  }
+
+  // Template variable schema validation
+  if (Array.isArray(contract.variables) && contract.variables.length > 0) {
+    const varResult = validateTemplateVariableSchema(contract.variables);
+    errors.push(...varResult.errors);
+    warnings.push(...varResult.warnings);
+  }
+  if (Array.isArray(contract.parameters)) {
+    for (const [index, param] of contract.parameters.entries()) {
+      if (!isPlainObject(param)) continue;
+      if (!String(param.id || '').trim()) {
+        const hasIdError = errors.some(e => e.includes(`parameters[${index}].id`));
+        if (!hasIdError) errors.push(`parameters[${index}].id is required`);
+      }
+      if (!String(param.type || '').trim()) {
+        const hasTypeError = errors.some(e => e.includes(`parameters[${index}].type`));
+        if (!hasTypeError) errors.push(`parameters[${index}].type is required`);
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    contract,
+    errors,
+    warnings,
+    fileChecks,
+    summary: {
+      ...contractResult.summary,
+      file_count: filesToCheck.length,
+      files_checked: fileChecks.checked,
+      files_missing: fileChecks.missing
+    }
+  };
+}
+
 async function runScenePackageValidateCommand(rawOptions = {}, dependencies = {}) {
   const projectRoot = dependencies.projectRoot || process.cwd();
   const fileSystem = dependencies.fileSystem || fs;
@@ -6850,6 +6961,50 @@ async function runScenePackageValidateCommand(rawOptions = {}, dependencies = {}
 
   try {
     const inputPath = resolveScenePackageValidateInputPath(options, projectRoot);
+
+    // Detect if input is a directory for comprehensive validation
+    let isDirectory = false;
+    try {
+      const statFn = typeof fileSystem.stat === 'function' ? fileSystem.stat.bind(fileSystem) : fs.stat.bind(fs);
+      const stat = await statFn(inputPath);
+      isDirectory = stat.isDirectory();
+    } catch (_e) {
+      // Not a directory or doesn't exist — fall through to file-based validation
+    }
+
+    if (isDirectory) {
+      const dirResult = await validateScenePackageDirectory(inputPath, fileSystem);
+
+      // Strict mode: promote warnings to errors
+      if (options.strict && dirResult.warnings.length > 0) {
+        dirResult.errors.push(...dirResult.warnings);
+        dirResult.warnings = [];
+        dirResult.valid = dirResult.errors.length === 0;
+      }
+
+      const payload = {
+        valid: dirResult.valid,
+        input: {
+          spec: options.spec || null,
+          path: inputPath,
+          spec_package: null,
+          mode: 'directory'
+        },
+        summary: dirResult.summary,
+        errors: dirResult.errors,
+        warnings: dirResult.warnings,
+        strict: options.strict
+      };
+
+      printScenePackageValidateSummary(options, payload, projectRoot);
+
+      if (!dirResult.valid) {
+        process.exitCode = 1;
+      }
+
+      return payload;
+    }
+
     const packageContract = await readJson(inputPath);
     const validation = validateScenePackageContract(packageContract);
 
@@ -6858,16 +7013,24 @@ async function runScenePackageValidateCommand(rawOptions = {}, dependencies = {}
       input: {
         spec: options.spec || null,
         path: inputPath,
-        spec_package: options.spec ? options.specPackage : null
+        spec_package: options.spec ? options.specPackage : null,
+        mode: 'file'
       },
       summary: validation.summary,
       errors: validation.errors,
       warnings: validation.warnings
     };
 
+    // Strict mode for file-based validation too
+    if (options.strict && payload.warnings.length > 0) {
+      payload.errors.push(...payload.warnings);
+      payload.warnings = [];
+      payload.valid = payload.errors.length === 0;
+    }
+
     printScenePackageValidateSummary(options, payload, projectRoot);
 
-    if (!validation.valid) {
+    if (!payload.valid) {
       process.exitCode = 1;
     }
 
@@ -10892,5 +11055,6 @@ module.exports = {
   normalizeSceneInfoOptions,
   validateSceneInfoOptions,
   runSceneInfoCommand,
-  printSceneInfoSummary
+  printSceneInfoSummary,
+  validateScenePackageDirectory
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-spec-engine",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "description": "kiro-spec-engine (kse) - A CLI tool and npm package for spec-driven development with AI coding assistants. NOT the Kiro IDE desktop application.",
   "main": "index.js",
   "bin": {