kiro-spec-engine 1.36.0 → 1.38.0

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.38.0] - 2026-02-10
+
+### Added
+- **Scene Registry Statistics**: Dashboard for local scene package registry metrics
+  - `kse scene stats` show aggregate statistics (packages, versions, tags, ownership, deprecation, last publish)
+    - `--registry <dir>` custom registry directory
+    - `--json` structured JSON output
+- **Scene Version Locking**: Protect specific package versions from accidental unpublish
+  - `kse scene lock set --name <pkg> --version <ver>` lock a version
+  - `kse scene lock rm --name <pkg> --version <ver>` unlock a version
+  - `kse scene lock ls --name <pkg>` list locked versions
+    - `--registry <dir>` custom registry directory
+    - `--json` structured JSON output
+  - Lock state stored as `locked: true` on version entries in `registry-index.json`
+
+## [1.37.0] - 2026-02-10
+
+### Added
+- **Scene Distribution Tags**: Manage distribution tags on scene packages in local registry
+  - `kse scene tag add --name <pkg> --tag <tag> --version <ver>` add a distribution tag
+  - `kse scene tag rm --name <pkg> --tag <tag>` remove a distribution tag
+  - `kse scene tag ls --name <pkg>` list all tags and latest version
+    - `--registry <dir>` custom registry directory
+    - `--json` structured JSON output
+  - Tags stored as `tags` object on package entry, separate from `latest` field
+  - "latest" tag is protected — managed automatically by publish
+
 ## [1.36.0] - 2026-02-10
 
 ### Added

package/lib/commands/scene.js

@@ -643,6 +643,91 @@ function registerSceneCommands(program) {
     .action(async (options) => {
       await runSceneOwnerCommand({ ...options, action: 'transfer' });
     });
+
+  // ── scene tag ──
+  const tagCmd = sceneCmd
+    .command('tag')
+    .description('Manage distribution tags on scene packages');
+
+  tagCmd
+    .command('add')
+    .description('Add a distribution tag to a package version')
+    .requiredOption('-n, --name <name>', 'Package name')
+    .requiredOption('-t, --tag <tag>', 'Tag name')
+    .requiredOption('-v, --version <version>', 'Version to tag')
+    .option('-r, --registry <path>', 'Registry root directory', '.kiro/registry')
+    .option('--json', 'Print result as JSON')
+    .action(async (options) => {
+      await runSceneTagCommand({ ...options, action: 'add' });
+    });
+
+  tagCmd
+    .command('rm')
+    .description('Remove a distribution tag from a package')
+    .requiredOption('-n, --name <name>', 'Package name')
+    .requiredOption('-t, --tag <tag>', 'Tag name to remove')
+    .option('-r, --registry <path>', 'Registry root directory', '.kiro/registry')
+    .option('--json', 'Print result as JSON')
+    .action(async (options) => {
+      await runSceneTagCommand({ ...options, action: 'rm' });
+    });
+
+  tagCmd
+    .command('ls')
+    .description('List all distribution tags for a package')
+    .requiredOption('-n, --name <name>', 'Package name')
+    .option('-r, --registry <path>', 'Registry root directory', '.kiro/registry')
+    .option('--json', 'Print result as JSON')
+    .action(async (options) => {
+      await runSceneTagCommand({ ...options, action: 'ls' });
+    });
+
+  // ── scene stats ──
+  sceneCmd
+    .command('stats')
+    .description('Show aggregate statistics about the local scene package registry')
+    .option('-r, --registry <path>', 'Registry root directory', '.kiro/registry')
+    .option('--json', 'Print result as JSON')
+    .action(async (options) => {
+      await runSceneStatsCommand(options);
+    });
+
+  // ── scene lock ──
+  const lockCmd = sceneCmd
+    .command('lock')
+    .description('Manage version locks on scene packages');
+
+  lockCmd
+    .command('set')
+    .description('Lock a specific version of a package')
+    .requiredOption('-n, --name <name>', 'Package name')
+    .requiredOption('-v, --version <version>', 'Version to lock')
+    .option('-r, --registry <path>', 'Registry root directory', '.kiro/registry')
+    .option('--json', 'Print result as JSON')
+    .action(async (options) => {
+      await runSceneLockCommand({ ...options, action: 'set' });
+    });
+
+  lockCmd
+    .command('rm')
+    .description('Unlock a specific version of a package')
+    .requiredOption('-n, --name <name>', 'Package name')
+    .requiredOption('-v, --version <version>', 'Version to unlock')
+    .option('-r, --registry <path>', 'Registry root directory', '.kiro/registry')
+    .option('--json', 'Print result as JSON')
+    .action(async (options) => {
+      await runSceneLockCommand({ ...options, action: 'rm' });
+    });
+
+  lockCmd
+    .command('ls')
+    .description('List all locked versions for a package')
+    .requiredOption('-n, --name <name>', 'Package name')
+    .option('-r, --registry <path>', 'Registry root directory', '.kiro/registry')
+    .option('--json', 'Print result as JSON')
+    .action(async (options) => {
+      await runSceneLockCommand({ ...options, action: 'ls' });
+    });
 }
 
 function normalizeSourceOptions(options = {}) {
@@ -11516,6 +11601,398 @@ function printSceneOwnerSummary(options, payload) {
   }
 }
 
+// ── Scene Tag ──────────────────────────────────────────────────────────────
+
+function normalizeSceneTagOptions(options = {}) {
+  return {
+    action: options.action ? String(options.action).trim() : undefined,
+    name: options.name ? String(options.name).trim() : undefined,
+    tag: options.tag ? String(options.tag).trim() : undefined,
+    version: options.version ? String(options.version).trim() : undefined,
+    registry: options.registry ? String(options.registry).trim() : '.kiro/registry',
+    json: options.json === true
+  };
+}
+
+function validateSceneTagOptions(options) {
+  if (!options.action) return '--action is required';
+  const validActions = ['add', 'rm', 'ls'];
+  if (!validActions.includes(options.action)) return `invalid action "${options.action}"`;
+
+  if (options.action === 'add') {
+    if (!options.name) return '--name is required';
+    if (!options.tag) return '--tag is required';
+    if (!options.version) return '--version is required';
+    if (options.tag === 'latest') return '"latest" tag is managed automatically by publish';
+  }
+  if (options.action === 'rm') {
+    if (!options.name) return '--name is required';
+    if (!options.tag) return '--tag is required';
+    if (options.tag === 'latest') return '"latest" tag is managed automatically by publish';
+  }
+  if (options.action === 'ls') {
+    if (!options.name) return '--name is required';
+  }
+  return null;
+}
+
+async function runSceneTagCommand(rawOptions = {}, dependencies = {}) {
+  const projectRoot = dependencies.projectRoot || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+
+  const options = normalizeSceneTagOptions(rawOptions);
+  const validationError = validateSceneTagOptions(options);
+
+  if (validationError) {
+    console.error(chalk.red(`Scene tag 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 = index.packages || {};
+    let payload;
+
+    if (options.action === 'add') {
+      if (!packages[options.name]) {
+        throw new Error(`package "${options.name}" not found in registry`);
+      }
+      const pkg = packages[options.name];
+      if (!pkg.versions || !pkg.versions[options.version]) {
+        throw new Error(`version "${options.version}" not found for package "${options.name}"`);
+      }
+      if (!pkg.tags) pkg.tags = {};
+      pkg.tags[options.tag] = options.version;
+      await saveRegistryIndex(registryRoot, index, fileSystem);
+      payload = {
+        success: true,
+        action: 'add',
+        package: options.name,
+        tag: options.tag,
+        version: options.version,
+        registry: options.registry
+      };
+    } else if (options.action === 'rm') {
+      if (!packages[options.name]) {
+        throw new Error(`package "${options.name}" not found in registry`);
+      }
+      const pkg = packages[options.name];
+      if (!pkg.tags || !pkg.tags[options.tag]) {
+        throw new Error(`tag "${options.tag}" not found for package "${options.name}"`);
+      }
+      delete pkg.tags[options.tag];
+      await saveRegistryIndex(registryRoot, index, fileSystem);
+      payload = {
+        success: true,
+        action: 'rm',
+        package: options.name,
+        tag: options.tag,
+        registry: options.registry
+      };
+    } else if (options.action === 'ls') {
+      if (!packages[options.name]) {
+        throw new Error(`package "${options.name}" not found in registry`);
+      }
+      const pkg = packages[options.name];
+      const tags = { ...(pkg.tags || {}) };
+      payload = {
+        success: true,
+        action: 'ls',
+        package: options.name,
+        latest: pkg.latest || null,
+        tags,
+        registry: options.registry
+      };
+    }
+
+    printSceneTagSummary(options, payload);
+    return payload;
+  } catch (error) {
+    console.error(chalk.red('Scene tag failed:'), error.message);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+function printSceneTagSummary(options, payload) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  if (payload.action === 'add') {
+    console.log(chalk.green(`Tag "${payload.tag}" set to version "${payload.version}" for package "${payload.package}"`));
+  } else if (payload.action === 'rm') {
+    console.log(chalk.green(`Tag "${payload.tag}" removed from package "${payload.package}"`));
+  } else if (payload.action === 'ls') {
+    const tagEntries = Object.entries(payload.tags);
+    if (tagEntries.length === 0 && !payload.latest) {
+      console.log(`No tags set for package "${payload.package}"`);
+    } else {
+      console.log(`Tags for package "${payload.package}":`);
+      if (payload.latest) {
+        console.log(`  latest: ${payload.latest}`);
+      }
+      for (const [tag, version] of tagEntries) {
+        console.log(`  ${tag}: ${version}`);
+      }
+    }
+  }
+}
+
+// ── Scene Stats ───────────────────────────────────────────────────────────
+
+function normalizeSceneStatsOptions(options = {}) {
+  return {
+    registry: options.registry ? String(options.registry).trim() : '.kiro/registry',
+    json: options.json === true
+  };
+}
+
+function validateSceneStatsOptions(options) {
+  return null;
+}
+
+async function runSceneStatsCommand(rawOptions = {}, dependencies = {}) {
+  const projectRoot = dependencies.projectRoot || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+
+  const options = normalizeSceneStatsOptions(rawOptions);
+  const validationError = validateSceneStatsOptions(options);
+
+  if (validationError) {
+    console.error(chalk.red(`Scene stats 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 = index.packages || {};
+    const packageNames = Object.keys(packages);
+
+    let totalVersions = 0;
+    let totalTags = 0;
+    let packagesWithOwner = 0;
+    let deprecatedPackages = 0;
+    let mostRecent = null;
+
+    for (const name of packageNames) {
+      const pkg = packages[name];
+      const versions = pkg.versions || {};
+      const versionKeys = Object.keys(versions);
+      totalVersions += versionKeys.length;
+      totalTags += Object.keys(pkg.tags || {}).length;
+
+      if (pkg.owner && String(pkg.owner).trim() !== '') {
+        packagesWithOwner++;
+      }
+      if (pkg.deprecated) {
+        deprecatedPackages++;
+      }
+
+      for (const ver of versionKeys) {
+        const publishedAt = versions[ver].published_at;
+        if (publishedAt && (!mostRecent || publishedAt > mostRecent.publishedAt)) {
+          mostRecent = { package: name, version: ver, publishedAt };
+        }
+      }
+    }
+
+    const payload = {
+      success: true,
+      totalPackages: packageNames.length,
+      totalVersions,
+      totalTags,
+      packagesWithOwner,
+      packagesWithoutOwner: packageNames.length - packagesWithOwner,
+      deprecatedPackages,
+      mostRecentlyPublished: mostRecent,
+      registry: options.registry
+    };
+
+    printSceneStatsSummary(options, payload);
+    return payload;
+  } catch (error) {
+    console.error(chalk.red('Scene stats failed:'), error.message);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+function printSceneStatsSummary(options, payload) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold('Registry Statistics'));
+  console.log(`  Packages:    ${payload.totalPackages}`);
+  console.log(`  Versions:    ${payload.totalVersions}`);
+  console.log(`  Tags:        ${payload.totalTags}`);
+  console.log(`  With owner:  ${payload.packagesWithOwner}`);
+  console.log(`  No owner:    ${payload.packagesWithoutOwner}`);
+  console.log(`  Deprecated:  ${payload.deprecatedPackages}`);
+
+  if (payload.mostRecentlyPublished) {
+    const mr = payload.mostRecentlyPublished;
+    console.log(`  Last publish: ${mr.package}@${mr.version} (${mr.publishedAt})`);
+  } else {
+    console.log('  Last publish: (none)');
+  }
+}
+
+// ── Scene Lock ────────────────────────────────────────────────────────────
+
+function normalizeSceneLockOptions(options = {}) {
+  return {
+    action: options.action ? String(options.action).trim() : undefined,
+    name: options.name ? String(options.name).trim() : undefined,
+    version: options.version ? String(options.version).trim() : undefined,
+    registry: options.registry ? String(options.registry).trim() : '.kiro/registry',
+    json: options.json === true
+  };
+}
+
+function validateSceneLockOptions(options) {
+  if (!options.action) return '--action is required';
+  const validActions = ['set', 'rm', 'ls'];
+  if (!validActions.includes(options.action)) return `invalid action "${options.action}"`;
+
+  if (options.action === 'set') {
+    if (!options.name) return '--name is required';
+    if (!options.version) return '--version is required';
+  }
+  if (options.action === 'rm') {
+    if (!options.name) return '--name is required';
+    if (!options.version) return '--version is required';
+  }
+  if (options.action === 'ls') {
+    if (!options.name) return '--name is required';
+  }
+  return null;
+}
+
+async function runSceneLockCommand(rawOptions = {}, dependencies = {}) {
+  const projectRoot = dependencies.projectRoot || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+
+  const options = normalizeSceneLockOptions(rawOptions);
+  const validationError = validateSceneLockOptions(options);
+
+  if (validationError) {
+    console.error(chalk.red(`Scene lock 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 = index.packages || {};
+    let payload;
+
+    if (options.action === 'set') {
+      if (!packages[options.name]) {
+        throw new Error(`package "${options.name}" not found in registry`);
+      }
+      const pkg = packages[options.name];
+      if (!pkg.versions || !pkg.versions[options.version]) {
+        throw new Error(`version "${options.version}" not found for package "${options.name}"`);
+      }
+      const versionEntry = pkg.versions[options.version];
+      if (versionEntry.locked === true) {
+        throw new Error(`version "${options.version}" of package "${options.name}" is already locked`);
+      }
+      versionEntry.locked = true;
+      await saveRegistryIndex(registryRoot, index, fileSystem);
+      payload = {
+        success: true,
+        action: 'set',
+        package: options.name,
+        version: options.version,
+        registry: options.registry
+      };
+    } else if (options.action === 'rm') {
+      if (!packages[options.name]) {
+        throw new Error(`package "${options.name}" not found in registry`);
+      }
+      const pkg = packages[options.name];
+      if (!pkg.versions || !pkg.versions[options.version]) {
+        throw new Error(`version "${options.version}" not found for package "${options.name}"`);
+      }
+      const versionEntry = pkg.versions[options.version];
+      if (!versionEntry.locked) {
+        throw new Error(`version "${options.version}" of package "${options.name}" is not locked`);
+      }
+      delete versionEntry.locked;
+      await saveRegistryIndex(registryRoot, index, fileSystem);
+      payload = {
+        success: true,
+        action: 'rm',
+        package: options.name,
+        version: options.version,
+        registry: options.registry
+      };
+    } else if (options.action === 'ls') {
+      if (!packages[options.name]) {
+        throw new Error(`package "${options.name}" not found in registry`);
+      }
+      const pkg = packages[options.name];
+      const versions = pkg.versions || {};
+      const lockedVersions = Object.keys(versions).filter(v => versions[v].locked === true);
+      payload = {
+        success: true,
+        action: 'ls',
+        package: options.name,
+        lockedVersions,
+        registry: options.registry
+      };
+    }
+
+    printSceneLockSummary(options, payload);
+    return payload;
+  } catch (error) {
+    console.error(chalk.red('Scene lock failed:'), error.message);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+function printSceneLockSummary(options, payload) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  if (payload.action === 'set') {
+    console.log(chalk.green(`Version "${payload.version}" of package "${payload.package}" is now locked`));
+  } else if (payload.action === 'rm') {
+    console.log(chalk.green(`Version "${payload.version}" of package "${payload.package}" is now unlocked`));
+  } else if (payload.action === 'ls') {
+    if (payload.lockedVersions.length === 0) {
+      console.log(`No locked versions for package "${payload.package}"`);
+    } else {
+      console.log(`Locked versions for package "${payload.package}":`);
+      for (const version of payload.lockedVersions) {
+        console.log(`  ${version}`);
+      }
+    }
+  }
+}
+
 module.exports = {
   RUN_MODES,
   SCAFFOLD_TYPES,
@@ -11696,5 +12173,17 @@ module.exports = {
   normalizeSceneOwnerOptions,
   validateSceneOwnerOptions,
   runSceneOwnerCommand,
-  printSceneOwnerSummary
+  printSceneOwnerSummary,
+  normalizeSceneTagOptions,
+  validateSceneTagOptions,
+  runSceneTagCommand,
+  printSceneTagSummary,
+  normalizeSceneStatsOptions,
+  validateSceneStatsOptions,
+  runSceneStatsCommand,
+  printSceneStatsSummary,
+  normalizeSceneLockOptions,
+  validateSceneLockOptions,
+  runSceneLockCommand,
+  printSceneLockSummary
 };

package/package.json

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