kiro-spec-engine 1.30.0 → 1.32.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.32.0] - 2026-02-10
+
+### Added
+- **Scene Package Info**: Display detailed package information from local registry
+  - `kse scene info --name <packageName>` show package details
+    - `--registry <dir>` custom registry directory
+    - `--json` structured JSON output
+    - `--versions-only` show only version list
+  - Displays package metadata, description, group, all published versions
+  - Shows latest version, total version count, publish dates
+  - Sorted version list (newest first) using `semver.rcompare`
+  - Follows normalize → validate → run → print pattern
+  - Implements Spec 82-00-scene-info
+
+## [1.31.0] - 2026-02-10
+
+### Added
+- **Scene Package Diff**: Compare two versions of a scene package in the local registry
+  - `kse scene diff --name <pkg> --from <v1> --to <v2>` compare package versions
+    - `--registry <dir>` custom registry directory
+    - `--json` structured JSON output
+    - `--stat` show only file change summary
+  - Extracts and decompresses tarballs from registry
+  - Categorizes files as added, removed, modified, or unchanged
+  - Shows changed line counts for modified text files
+  - Shared helper: `buildPackageDiff`
+  - Follows normalize → validate → run → print pattern
+  - Implements Spec 81-00-scene-diff
+
 ## [1.30.0] - 2026-02-10
 
 ### Added

package/lib/commands/scene.js

@@ -547,6 +547,30 @@ function registerSceneCommands(program) {
     .action(async (options) => {
       await runSceneVersionCommand(options);
     });
+
+  sceneCmd
+    .command('diff')
+    .description('Compare two versions of a scene package in the local registry')
+    .requiredOption('-n, --name <name>', 'Package name')
+    .requiredOption('-f, --from <version>', 'Source version')
+    .requiredOption('-t, --to <version>', 'Target version')
+    .option('-r, --registry <path>', 'Registry root directory', '.kiro/registry')
+    .option('--json', 'Print result as JSON')
+    .option('--stat', 'Show only file change summary')
+    .action(async (options) => {
+      await runSceneDiffCommand(options);
+    });
+
+  sceneCmd
+    .command('info')
+    .description('Display detailed information about a scene package in the local registry')
+    .requiredOption('-n, --name <name>', 'Package name')
+    .option('-r, --registry <path>', 'Registry root directory', '.kiro/registry')
+    .option('--json', 'Print result as JSON')
+    .option('--versions-only', 'Show only version list')
+    .action(async (options) => {
+      await runSceneInfoCommand(options);
+    });
 }
 
 function normalizeSourceOptions(options = {}) {
@@ -10435,6 +10459,274 @@ async function runSceneVersionCommand(rawOptions = {}, dependencies = {}) {
   }
 }
 
+function buildPackageDiff(fromFiles, toFiles) {
+  const fromMap = new Map();
+  for (const f of (fromFiles || [])) {
+    fromMap.set(f.relativePath, f.content);
+  }
+  const toMap = new Map();
+  for (const f of (toFiles || [])) {
+    toMap.set(f.relativePath, f.content);
+  }
+
+  const added = [];
+  const removed = [];
+  const modified = [];
+  const unchanged = [];
+
+  for (const [filePath, content] of fromMap) {
+    if (!toMap.has(filePath)) {
+      removed.push(filePath);
+    } else {
+      const toContent = toMap.get(filePath);
+      if (Buffer.compare(content, toContent) === 0) {
+        unchanged.push(filePath);
+      } else {
+        let changedLines = 0;
+        try {
+          const oldLines = content.toString('utf8').split('\n');
+          const newLines = toContent.toString('utf8').split('\n');
+          const maxLen = Math.max(oldLines.length, newLines.length);
+          for (let i = 0; i < maxLen; i++) {
+            if ((oldLines[i] || '') !== (newLines[i] || '')) {
+              changedLines++;
+            }
+          }
+        } catch (_e) {
+          changedLines = -1;
+        }
+        modified.push({ path: filePath, changedLines });
+      }
+    }
+  }
+
+  for (const filePath of toMap.keys()) {
+    if (!fromMap.has(filePath)) {
+      added.push(filePath);
+    }
+  }
+
+  return {
+    added: added.sort(),
+    removed: removed.sort(),
+    modified: modified.sort((a, b) => a.path.localeCompare(b.path)),
+    unchanged: unchanged.sort()
+  };
+}
+
+function normalizeSceneDiffOptions(options = {}) {
+  return {
+    name: options.name ? String(options.name).trim() : undefined,
+    from: options.from ? String(options.from).trim() : undefined,
+    to: options.to ? String(options.to).trim() : undefined,
+    registry: options.registry ? String(options.registry).trim() : '.kiro/registry',
+    json: options.json === true,
+    stat: options.stat === true
+  };
+}
+
+function validateSceneDiffOptions(options) {
+  if (!options.name) return '--name is required';
+  if (!options.from) return '--from is required';
+  if (!options.to) return '--to is required';
+  if (options.from === options.to) return '--from and --to must be different versions';
+  return null;
+}
+
+function printSceneDiffSummary(options, payload, projectRoot = process.cwd()) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log(chalk.blue(`Scene Package Diff: ${payload.name} ${payload.fromVersion} → ${payload.toVersion}`));
+  console.log(`  Added:     ${payload.summary.added} file(s)`);
+  console.log(`  Removed:   ${payload.summary.removed} file(s)`);
+  console.log(`  Modified:  ${payload.summary.modified} file(s)`);
+  console.log(`  Unchanged: ${payload.summary.unchanged} file(s)`);
+
+  if (payload.files.added.length > 0 || payload.files.removed.length > 0 || payload.files.modified.length > 0) {
+    console.log('');
+    for (const f of payload.files.added) {
+      console.log(chalk.green(`  + ${f}`));
+    }
+    for (const f of payload.files.removed) {
+      console.log(chalk.red(`  - ${f}`));
+    }
+    for (const f of payload.files.modified) {
+      const detail = f.changedLines >= 0 ? ` (${f.changedLines} lines changed)` : ' (binary content differs)';
+      console.log(chalk.yellow(`  ~ ${f.path}${detail}`));
+    }
+  }
+}
+
+async function runSceneDiffCommand(rawOptions = {}, dependencies = {}) {
+  const projectRoot = dependencies.projectRoot || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+
+  const options = normalizeSceneDiffOptions(rawOptions);
+  const validationError = validateSceneDiffOptions(options);
+  if (validationError) {
+    console.error(chalk.red(`Scene diff failed: ${validationError}`));
+    process.exitCode = 1;
+    return null;
+  }
+
+  try {
+    const registryRoot = path.isAbsolute(options.registry)
+      ? options.registry
+      : path.join(projectRoot, options.registry);
+
+    const index = await loadRegistryIndex(registryRoot, fileSystem);
+
+    if (!index.packages || !index.packages[options.name]) {
+      throw new Error(`package "${options.name}" not found in registry`);
+    }
+
+    const pkg = index.packages[options.name];
+    if (!pkg.versions || !pkg.versions[options.from]) {
+      throw new Error(`version "${options.from}" not found for package "${options.name}"`);
+    }
+    if (!pkg.versions[options.to]) {
+      throw new Error(`version "${options.to}" not found for package "${options.name}"`);
+    }
+
+    const readFile = typeof fileSystem.readFile === 'function'
+      ? fileSystem.readFile.bind(fileSystem) : fs.readFile.bind(fs);
+
+    const fromTarballPath = path.join(registryRoot, pkg.versions[options.from].tarball);
+    const toTarballPath = path.join(registryRoot, pkg.versions[options.to].tarball);
+
+    const fromGz = await readFile(fromTarballPath);
+    const toGz = await readFile(toTarballPath);
+
+    const fromTar = zlib.gunzipSync(fromGz);
+    const toTar = zlib.gunzipSync(toGz);
+
+    const fromFiles = extractTarBuffer(fromTar);
+    const toFiles = extractTarBuffer(toTar);
+
+    const diff = buildPackageDiff(fromFiles, toFiles);
+
+    const payload = {
+      success: true,
+      name: options.name,
+      fromVersion: options.from,
+      toVersion: options.to,
+      summary: {
+        added: diff.added.length,
+        removed: diff.removed.length,
+        modified: diff.modified.length,
+        unchanged: diff.unchanged.length
+      },
+      files: {
+        added: diff.added,
+        removed: diff.removed,
+        modified: diff.modified,
+        unchanged: options.stat ? diff.unchanged : diff.unchanged
+      }
+    };
+
+    printSceneDiffSummary(options, payload, projectRoot);
+    return payload;
+  } catch (error) {
+    console.error(chalk.red('Scene diff failed:'), error.message);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+function normalizeSceneInfoOptions(options = {}) {
+  return {
+    name: options.name ? String(options.name).trim() : undefined,
+    registry: options.registry ? String(options.registry).trim() : '.kiro/registry',
+    json: options.json === true,
+    versionsOnly: options.versionsOnly === true
+  };
+}
+
+function validateSceneInfoOptions(options) {
+  if (!options.name) return '--name is required';
+  return null;
+}
+
+function printSceneInfoSummary(options, payload, projectRoot = process.cwd()) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  if (options.versionsOnly) {
+    for (const v of payload.versions) {
+      console.log(`${v.version}  ${v.publishedAt}`);
+    }
+    return;
+  }
+
+  console.log(chalk.blue(`Scene Package: ${payload.name}`));
+  console.log(`  Group:       ${payload.group || '(none)'}`);
+  console.log(`  Description: ${payload.description || '(none)'}`);
+  console.log(`  Latest:      ${payload.latest}`);
+  console.log(`  Versions:    ${payload.versionCount}`);
+  console.log('');
+  console.log('  ' + 'VERSION'.padEnd(14) + 'PUBLISHED'.padEnd(26) + 'INTEGRITY');
+  for (const v of payload.versions) {
+    console.log('  ' + v.version.padEnd(14) + (v.publishedAt || '').padEnd(26) + (v.integrity || ''));
+  }
+}
+
+async function runSceneInfoCommand(rawOptions = {}, dependencies = {}) {
+  const projectRoot = dependencies.projectRoot || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+
+  const options = normalizeSceneInfoOptions(rawOptions);
+  const validationError = validateSceneInfoOptions(options);
+  if (validationError) {
+    console.error(chalk.red(`Scene info failed: ${validationError}`));
+    process.exitCode = 1;
+    return null;
+  }
+
+  try {
+    const registryRoot = path.isAbsolute(options.registry)
+      ? options.registry
+      : path.join(projectRoot, options.registry);
+
+    const index = await loadRegistryIndex(registryRoot, fileSystem);
+
+    if (!index.packages || !index.packages[options.name]) {
+      throw new Error(`package "${options.name}" not found in registry`);
+    }
+
+    const pkg = index.packages[options.name];
+    const versionKeys = Object.keys(pkg.versions || {});
+    const sortedVersions = versionKeys.slice().sort(semver.rcompare);
+
+    const versions = sortedVersions.map(v => ({
+      version: v,
+      publishedAt: (pkg.versions[v] && pkg.versions[v].published_at) || '',
+      integrity: (pkg.versions[v] && pkg.versions[v].integrity) || ''
+    }));
+
+    const payload = {
+      success: true,
+      name: pkg.name || options.name,
+      group: pkg.group || '',
+      description: pkg.description || '',
+      latest: pkg.latest || resolveLatestVersion(pkg.versions) || '',
+      versionCount: versionKeys.length,
+      versions
+    };
+
+    printSceneInfoSummary(options, payload, projectRoot);
+    return payload;
+  } catch (error) {
+    console.error(chalk.red('Scene info failed:'), error.message);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
 module.exports = {
   RUN_MODES,
   SCAFFOLD_TYPES,
@@ -10591,5 +10883,14 @@ module.exports = {
   normalizeSceneVersionOptions,
   validateSceneVersionOptions,
   runSceneVersionCommand,
-  printSceneVersionSummary
+  printSceneVersionSummary,
+  buildPackageDiff,
+  normalizeSceneDiffOptions,
+  validateSceneDiffOptions,
+  runSceneDiffCommand,
+  printSceneDiffSummary,
+  normalizeSceneInfoOptions,
+  validateSceneInfoOptions,
+  runSceneInfoCommand,
+  printSceneInfoSummary
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-spec-engine",
-  "version": "1.30.0",
+  "version": "1.32.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": {