kiro-spec-engine 1.27.0 → 1.29.0

package/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.29.0] - 2026-02-10
+
+### Added
+- **Scene Registry Query**: List and search scene packages in local registry
+  - `kse scene list` list all packages in registry
+    - `--registry <dir>` custom registry directory
+    - `--json` structured JSON output
+  - `kse scene search --query <term>` search packages by keyword
+    - Case-insensitive substring matching on name, description, and group
+    - `--registry <dir>` custom registry directory
+    - `--json` structured JSON output
+  - Shared helpers: `buildRegistryPackageList`, `filterRegistryPackages`
+  - Follows normalize → validate → run → print pattern
+  - Implements Spec 79-00-scene-registry-query
+
+## [1.28.0] - 2026-02-10
+
+### Added
+- **Scene Package Install**: Install published scene packages from local registry
+  - `kse scene install --name <packageName>` install scene package from registry
+    - `--version <version>` exact version or omit for latest
+    - `--out <dir>` custom target directory (default: `./{packageName}`)
+    - `--registry <dir>` custom registry directory
+    - `--force` overwrite existing installation
+    - `--dry-run` preview without writing files
+    - `--json` structured JSON output
+  - SHA-256 integrity verification before extraction
+  - Tarball decompression and file extraction preserving relative paths
+  - Install manifest (`scene-install-manifest.json`) with package metadata, timestamp, file list
+  - Automatic latest version resolution from registry index
+  - Completes publish → install lifecycle for scene packages
+  - Implements Spec 78-00-scene-package-install
+
 ## [1.27.0] - 2026-02-10
 
 ### Added

package/lib/commands/scene.js

@@ -503,6 +503,39 @@ function registerSceneCommands(program) {
     .action(async (options) => {
       await runSceneUnpublishCommand(options);
     });
+
+  sceneCmd
+    .command('install')
+    .description('Install scene package from local registry')
+    .requiredOption('-n, --name <name>', 'Package name to install')
+    .option('-v, --version <version>', 'Package version (default: latest)')
+    .option('-o, --out <dir>', 'Target output directory')
+    .option('-r, --registry <path>', 'Registry root directory', '.kiro/registry')
+    .option('--force', 'Overwrite existing installation')
+    .option('--dry-run', 'Preview install without writing files')
+    .option('--json', 'Print install payload as JSON')
+    .action(async (options) => {
+      await runSceneInstallCommand(options);
+    });
+
+  sceneCmd
+    .command('list')
+    .description('List all packages in the local scene registry')
+    .option('-r, --registry <path>', 'Registry root directory', '.kiro/registry')
+    .option('--json', 'Print result as JSON')
+    .action(async (options) => {
+      await runSceneListCommand(options);
+    });
+
+  sceneCmd
+    .command('search')
+    .description('Search packages in the local scene registry')
+    .requiredOption('-q, --query <term>', 'Search term (substring match on name, description, group)')
+    .option('-r, --registry <path>', 'Registry root directory', '.kiro/registry')
+    .option('--json', 'Print result as JSON')
+    .action(async (options) => {
+      await runSceneSearchCommand(options);
+    });
 }
 
 function normalizeSourceOptions(options = {}) {
@@ -9847,6 +9880,358 @@ function validateSceneUnpublishOptions(options) {
   return null;
 }
 
+function normalizeSceneInstallOptions(options = {}) {
+  return {
+    name: options.name ? String(options.name).trim() : undefined,
+    version: options.version ? String(options.version).trim() : undefined,
+    out: options.out ? String(options.out).trim() : undefined,
+    registry: options.registry ? String(options.registry).trim() : '.kiro/registry',
+    force: options.force === true,
+    dryRun: options.dryRun === true,
+    json: options.json === true
+  };
+}
+
+function validateSceneInstallOptions(options) {
+  if (!options.name || typeof options.name !== 'string') {
+    return '--name is required';
+  }
+  if (options.version && options.version !== 'latest' && !semver.valid(options.version)) {
+    return `--version "${options.version}" is not valid semver`;
+  }
+  return null;
+}
+
+function buildInstallManifest(packageName, version, registryDir, integrity, files) {
+  return {
+    packageName,
+    version,
+    installedAt: new Date().toISOString(),
+    registryDir,
+    integrity,
+    files
+  };
+}
+
+function printSceneInstallSummary(options, payload, projectRoot = process.cwd()) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  const dryRunLabel = payload.dry_run ? chalk.yellow(' [dry-run]') : '';
+  console.log(chalk.blue('Scene Package Install') + dryRunLabel);
+  console.log(`  Package: ${payload.coordinate}`);
+  console.log(`  Target: ${chalk.gray(payload.target_dir)}`);
+  console.log(`  Files: ${payload.file_count}`);
+  console.log(`  Integrity: ${payload.integrity}`);
+  if (payload.overwritten) {
+    console.log(`  Overwritten: ${chalk.yellow('yes')}`);
+  }
+}
+
+async function runSceneInstallCommand(rawOptions = {}, dependencies = {}) {
+  const projectRoot = dependencies.projectRoot || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+
+  const options = normalizeSceneInstallOptions(rawOptions);
+  const validationError = validateSceneInstallOptions(options);
+
+  if (validationError) {
+    console.error(chalk.red(`Scene package install failed: ${validationError}`));
+    process.exitCode = 1;
+    return null;
+  }
+
+  const readFile = typeof fileSystem.readFile === 'function'
+    ? fileSystem.readFile.bind(fileSystem)
+    : fs.readFile.bind(fs);
+
+  try {
+    // 1. Resolve registry root
+    const registryRoot = path.isAbsolute(options.registry)
+      ? options.registry
+      : path.join(projectRoot, options.registry);
+
+    // 2. Load registry index
+    const index = await loadRegistryIndex(registryRoot, fileSystem);
+
+    // 3. Resolve package in index
+    if (!index.packages || !index.packages[options.name]) {
+      throw new Error(`package "${options.name}" not found in registry`);
+    }
+    const pkg = index.packages[options.name];
+
+    // 4. Resolve version (default to latest)
+    const version = (!options.version || options.version === 'latest')
+      ? pkg.latest
+      : options.version;
+
+    if (!version) {
+      throw new Error(`no latest version found for package "${options.name}"`);
+    }
+
+    if (!pkg.versions || !pkg.versions[version]) {
+      throw new Error(`version "${version}" not found for package "${options.name}"`);
+    }
+    const versionEntry = pkg.versions[version];
+
+    // 5. Read tarball from disk
+    const tarballRelativePath = buildRegistryTarballPath(options.name, version);
+    const tarballAbsolutePath = path.join(registryRoot, tarballRelativePath);
+    const tarballBuffer = await readFile(tarballAbsolutePath);
+
+    // 6. Verify integrity
+    const computedHash = 'sha256-' + crypto.createHash('sha256').update(tarballBuffer).digest('hex');
+    if (computedHash !== versionEntry.integrity) {
+      throw new Error(`integrity verification failed: expected ${versionEntry.integrity}, got ${computedHash}`);
+    }
+
+    // 7. Resolve target directory
+    const targetDir = options.out
+      ? (path.isAbsolute(options.out) ? options.out : path.join(projectRoot, options.out))
+      : path.join(projectRoot, options.name);
+
+    // 8. Decompress and extract tarball
+    const decompressed = zlib.gunzipSync(tarballBuffer);
+    const files = extractTarBuffer(decompressed);
+    const fileNames = files.map(f => f.relativePath);
+
+    // 9. Build coordinate
+    const coordinate = `kse.scene/${options.name}@${version}`;
+
+    // 10. Dry-run: build payload without writing, print, return
+    if (options.dryRun) {
+      const payload = {
+        installed: false,
+        dry_run: true,
+        overwritten: false,
+        coordinate,
+        package: {
+          name: options.name,
+          version
+        },
+        target_dir: formatScenePackagePath(projectRoot, targetDir),
+        file_count: fileNames.length,
+        files: fileNames,
+        integrity: computedHash,
+        registry: {
+          index_path: formatScenePackagePath(projectRoot, path.join(registryRoot, 'registry-index.json'))
+        }
+      };
+
+      printSceneInstallSummary(options, payload, projectRoot);
+      return payload;
+    }
+
+    // 11. Check target dir conflict (unless --force)
+    const ensureDirSync = typeof fileSystem.ensureDirSync === 'function'
+      ? fileSystem.ensureDirSync.bind(fileSystem)
+      : fs.ensureDirSync.bind(fs);
+    const writeFileSync = typeof fileSystem.writeFileSync === 'function'
+      ? fileSystem.writeFileSync.bind(fileSystem)
+      : fs.writeFileSync.bind(fs);
+    const pathExistsSync = typeof fileSystem.pathExistsSync === 'function'
+      ? fileSystem.pathExistsSync.bind(fileSystem)
+      : fs.pathExistsSync.bind(fs);
+
+    const targetExists = pathExistsSync(targetDir);
+    if (targetExists && !options.force) {
+      throw new Error(`target directory already exists: ${formatScenePackagePath(projectRoot, targetDir)} (use --force to overwrite)`);
+    }
+
+    // 12. Write extracted files preserving relative paths
+    ensureDirSync(targetDir);
+    for (const file of files) {
+      const filePath = path.join(targetDir, file.relativePath);
+      ensureDirSync(path.dirname(filePath));
+      writeFileSync(filePath, file.content);
+    }
+
+    // 13. Write install manifest
+    const manifest = buildInstallManifest(options.name, version, options.registry, computedHash, fileNames);
+    const manifestPath = path.join(targetDir, 'scene-install-manifest.json');
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+    // 14. Build payload
+    const payload = {
+      installed: true,
+      dry_run: false,
+      overwritten: targetExists && options.force,
+      coordinate,
+      package: {
+        name: options.name,
+        version
+      },
+      target_dir: formatScenePackagePath(projectRoot, targetDir),
+      file_count: fileNames.length,
+      files: fileNames,
+      integrity: computedHash,
+      registry: {
+        index_path: formatScenePackagePath(projectRoot, path.join(registryRoot, 'registry-index.json'))
+      }
+    };
+
+    printSceneInstallSummary(options, payload, projectRoot);
+    return payload;
+  } catch (error) {
+    console.error(chalk.red('Scene package install failed:'), error.message);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+// --- Scene Registry Query Helpers ---
+
+function buildRegistryPackageList(registryPackages) {
+  return Object.values(registryPackages || {})
+    .map(pkg => ({
+      name: pkg.name || '',
+      group: pkg.group || '',
+      description: pkg.description || '',
+      latest: pkg.latest || '',
+      version_count: Object.keys(pkg.versions || {}).length
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function filterRegistryPackages(packageList, query) {
+  if (!query) return packageList;
+  const lowerQuery = query.toLowerCase();
+  return packageList.filter(pkg =>
+    pkg.name.toLowerCase().includes(lowerQuery) ||
+    pkg.description.toLowerCase().includes(lowerQuery) ||
+    pkg.group.toLowerCase().includes(lowerQuery)
+  );
+}
+
+// --- Scene List Command ---
+
+function normalizeSceneListOptions(options = {}) {
+  return {
+    registry: options.registry ? String(options.registry).trim() : '.kiro/registry',
+    json: options.json === true
+  };
+}
+
+function validateSceneListOptions(options) {
+  return null;
+}
+
+async function runSceneListCommand(rawOptions = {}, dependencies = {}) {
+  const projectRoot = dependencies.projectRoot || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+
+  const options = normalizeSceneListOptions(rawOptions);
+  const validationError = validateSceneListOptions(options);
+
+  if (validationError) {
+    console.error(chalk.red(`Scene list 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);
+    const packages = buildRegistryPackageList(index.packages);
+    const payload = { packages, total: packages.length };
+
+    printSceneListSummary(options, payload, projectRoot);
+    return payload;
+  } catch (error) {
+    console.error(chalk.red('Scene list failed:'), error.message);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+function printSceneListSummary(options, payload, projectRoot = process.cwd()) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  if (payload.total === 0) {
+    console.log('No packages found');
+    return;
+  }
+
+  console.log(chalk.blue(`Scene Registry (${payload.total} package${payload.total !== 1 ? 's' : ''})`));
+  for (const pkg of payload.packages) {
+    console.log(`  ${pkg.name.padEnd(20)} ${pkg.latest.padEnd(10)} ${String(pkg.version_count).padEnd(10)} ${pkg.description}`);
+  }
+}
+
+function normalizeSceneSearchOptions(options = {}) {
+  return {
+    query: options.query ? String(options.query).trim() : '',
+    registry: options.registry ? String(options.registry).trim() : '.kiro/registry',
+    json: options.json === true
+  };
+}
+
+function validateSceneSearchOptions(options) {
+  return null; // Empty query is valid (returns all)
+}
+
+async function runSceneSearchCommand(rawOptions = {}, dependencies = {}) {
+  const projectRoot = dependencies.projectRoot || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+
+  const options = normalizeSceneSearchOptions(rawOptions);
+  const validationError = validateSceneSearchOptions(options);
+
+  if (validationError) {
+    console.error(chalk.red(`Scene search 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);
+    const allPackages = buildRegistryPackageList(index.packages);
+    const packages = filterRegistryPackages(allPackages, options.query);
+    const payload = { query: options.query, packages, total: packages.length };
+
+    printSceneSearchSummary(options, payload, projectRoot);
+    return payload;
+  } catch (error) {
+    console.error(chalk.red('Scene search failed:'), error.message);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+function printSceneSearchSummary(options, payload, projectRoot = process.cwd()) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  if (payload.total === 0) {
+    if (payload.query) {
+      console.log(`No packages matching '${payload.query}'`);
+    } else {
+      console.log('No packages found');
+    }
+    return;
+  }
+
+  const matchLabel = payload.total === 1 ? 'match' : 'matches';
+  console.log(chalk.blue(`Scene Search: "${payload.query}" (${payload.total} ${matchLabel})`));
+  for (const pkg of payload.packages) {
+    console.log(`  ${pkg.name.padEnd(20)} ${pkg.latest.padEnd(10)} ${String(pkg.version_count).padEnd(10)} ${pkg.description}`);
+  }
+}
+
 function printSceneUnpublishSummary(options, payload, projectRoot = process.cwd()) {
   if (options.json) {
     console.log(JSON.stringify(payload, null, 2));
@@ -10070,5 +10455,20 @@ module.exports = {
   normalizeSceneUnpublishOptions,
   validateSceneUnpublishOptions,
   printSceneUnpublishSummary,
-  runSceneUnpublishCommand
+  runSceneUnpublishCommand,
+  buildInstallManifest,
+  normalizeSceneInstallOptions,
+  printSceneInstallSummary,
+  runSceneInstallCommand,
+  validateSceneInstallOptions,
+  buildRegistryPackageList,
+  filterRegistryPackages,
+  normalizeSceneListOptions,
+  validateSceneListOptions,
+  runSceneListCommand,
+  printSceneListSummary,
+  normalizeSceneSearchOptions,
+  validateSceneSearchOptions,
+  runSceneSearchCommand,
+  printSceneSearchSummary
 };

package/package.json

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