agentsys 5.2.0 → 5.3.0

package/bin/cli.js

@@ -22,7 +22,7 @@ const discovery = require('../lib/discovery');
 const transforms = require('../lib/adapter-transforms');
 
 // Valid tool names
-const VALID_TOOLS = ['claude', 'opencode', 'codex', 'cursor'];
+const VALID_TOOLS = ['claude', 'opencode', 'codex', 'cursor', 'kiro'];
 
 function getInstallDir() {
   const home = process.env.HOME || process.env.USERPROFILE;
@@ -231,18 +231,60 @@ function loadMarketplace() {
 }
 
 /**
- * Resolve the source URL string from a plugin's source field.
- * Handles both legacy string format ("https://...") and the new object
- * format ({ source: "url", url: "https://..." }) from Claude Code plugin schema.
- * Returns null for local/bundled sources or missing values.
+ * Normalize marketplace plugin source entries.
+ *
+ * Supported formats:
+ * - string URL/path (legacy)
+ * - object: { source: "url", url: "..." } (current)
+ * - object: { source: "path", path: "..." } (local/bundled)
+ *
+ * @param {string|Object} source
+ * @returns {{type: 'remote'|'local', value: string}|null}
  */
-function resolveSourceUrl(source) {
-  if (!source) return null;
-  if (typeof source === 'string') return source;
-  if (typeof source === 'object' && source.url) return source.url;
+function resolvePluginSource(source) {
+  if (typeof source === 'string') {
+    const value = source.trim();
+    if (!value) return null;
+    if (value.startsWith('./') || value.startsWith('../')) {
+      return { type: 'local', value };
+    }
+    return { type: 'remote', value };
+  }
+
+  if (!source || typeof source !== 'object') return null;
+
+  const sourceType = typeof source.source === 'string' ? source.source.toLowerCase() : null;
+
+  if ((sourceType === 'path' || sourceType === 'local') && typeof source.path === 'string') {
+    return { type: 'local', value: source.path };
+  }
+
+  if (sourceType === 'url' && typeof source.url === 'string') {
+    return { type: 'remote', value: source.url };
+  }
+
+  // Backward/forward-compatible fallbacks
+  if (typeof source.path === 'string') {
+    return { type: 'local', value: source.path };
+  }
+  if (typeof source.url === 'string') {
+    return { type: 'remote', value: source.url };
+  }
+
   return null;
 }
 
+/**
+ * Backward-compatible helper returning only the source URL/path value.
+ *
+ * @param {string|Object} source
+ * @returns {string|null}
+ */
+function resolveSourceUrl(source) {
+  const normalized = resolvePluginSource(source);
+  return normalized ? normalized.value : null;
+}
+
 /**
  * Resolve plugin dependencies transitively.
  *
@@ -313,45 +355,72 @@ async function fetchPlugin(name, source, version) {
     }
   }
 
+  const parsedSource = parseGitHubSource(source, version, name);
+  const owner = parsedSource.owner;
+  const repo = parsedSource.repo;
+
+  const refCandidates = parsedSource.explicitRef
+    ? [parsedSource.ref]
+    : [parsedSource.ref, version, 'main', 'master'];
+
+  let lastError = null;
+  for (const ref of [...new Set(refCandidates.filter(Boolean))]) {
+    const tarballUrl = `https://api.github.com/repos/${owner}/${repo}/tarball/${ref}`;
+
+    try {
+      console.log(`  Fetching ${name}@${version} from ${owner}/${repo} (${ref})...`);
+
+      // Clean and recreate
+      if (fs.existsSync(pluginDir)) {
+        fs.rmSync(pluginDir, { recursive: true, force: true });
+      }
+      fs.mkdirSync(pluginDir, { recursive: true });
+
+      // Download and extract tarball
+      await downloadAndExtractTarball(tarballUrl, pluginDir);
+
+      // Write version marker
+      fs.writeFileSync(versionFile, version);
+      return pluginDir;
+    } catch (err) {
+      lastError = err;
+      const isNotFound = /HTTP 404/.test(err.message);
+      if (isNotFound && !parsedSource.explicitRef) {
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  throw new Error(
+    `Unable to fetch ${name} from ${owner}/${repo}. Tried refs: ${[...new Set(refCandidates.filter(Boolean))].join(', ')}. Last error: ${lastError ? lastError.message : 'unknown error'}`
+  );
+}
+
+/**
+ * Parse GitHub source URL formats and normalize repo name.
+ *
+ * @param {string} source
+ * @param {string} version
+ * @param {string} [name]
+ * @returns {{owner: string, repo: string, ref: string, explicitRef: boolean}}
+ */
+function parseGitHubSource(source, version, name = 'plugin') {
   // Parse source formats:
   //   "https://github.com/owner/repo" or "https://github.com/owner/repo#ref"
   //   "github:owner/repo" or "github:owner/repo#ref"
-  let owner, repo, ref;
   const urlMatch = source.match(/github\.com\/([^/]+)\/([^/#]+)(?:#(.+))?/);
   const shortMatch = !urlMatch && source.match(/^github:([^/]+)\/([^#]+)(?:#(.+))?$/);
   const match = urlMatch || shortMatch;
   if (!match) {
     throw new Error(`Unsupported source format for ${name}: ${source}`);
   }
-  owner = match[1];
-  repo = match[2].replace(/\.git$/, '');
-  ref = match[3] || `v${version}`;
-
-  console.log(`  Fetching ${name}@${version} from ${owner}/${repo}...`);
-
-  // Clean and recreate
-  if (fs.existsSync(pluginDir)) {
-    fs.rmSync(pluginDir, { recursive: true, force: true });
-  }
-  fs.mkdirSync(pluginDir, { recursive: true });
-
-  // Download and extract tarball, falling back to main branch if version tag 404s
-  const tarballUrl = `https://api.github.com/repos/${owner}/${repo}/tarball/${ref}`;
-  try {
-    await downloadAndExtractTarball(tarballUrl, pluginDir);
-  } catch (err) {
-    if (ref !== 'main' && err.message && err.message.includes('404')) {
-      const mainUrl = `https://api.github.com/repos/${owner}/${repo}/tarball/main`;
-      await downloadAndExtractTarball(mainUrl, pluginDir);
-    } else {
-      throw err;
-    }
-  }
 
-  // Write version marker
-  fs.writeFileSync(versionFile, version);
-
-  return pluginDir;
+  const owner = match[1];
+  const repo = match[2].replace(/\.git$/, '');
+  const explicitRef = Boolean(match[3]);
+  const ref = match[3] || `v${version}`;
+  return { owner, repo, ref, explicitRef };
 }
 
 /**
@@ -470,16 +539,17 @@ async function fetchExternalPlugins(pluginNames, marketplace) {
     const plugin = pluginMap[name];
     if (!plugin) continue;
 
-    // If source is local (starts with ./), plugin is bundled - just use PACKAGE_DIR
-    const sourceUrl = resolveSourceUrl(plugin.source);
-    if (!sourceUrl || sourceUrl.startsWith('./') || sourceUrl.startsWith('../')) {
+    const source = resolvePluginSource(plugin.source);
+
+    // Local/bundled plugin, no external fetch needed
+    if (!source || source.type === 'local') {
       // Bundled plugin, no fetch needed
       fetched.push(name);
       continue;
     }
 
     try {
-      await fetchPlugin(name, sourceUrl, plugin.version);
+      await fetchPlugin(name, source.value, plugin.version);
       fetched.push(name);
     } catch (err) {
       failed.push(name);
@@ -493,6 +563,8 @@ async function fetchExternalPlugins(pluginNames, marketplace) {
       console.error(`\n  [WARN] Missing dependencies: ${missingDeps.join(', ')}`);
       console.error(`  Some plugins may not work correctly without their dependencies.`);
     }
+
+    throw new Error(`Failed to fetch ${failed.length} plugin(s): ${failed.join(', ')}`);
   }
 
   return fetched;
@@ -786,10 +858,13 @@ function loadComponents(pluginDir) {
   if (fs.existsSync(componentsPath)) {
     try {
       const data = JSON.parse(fs.readFileSync(componentsPath, 'utf8'));
+      const normalize = (arr) => (arr || []).map(item =>
+        typeof item === 'string' ? { name: item } : item
+      );
       return {
-        agents: data.agents || [],
-        skills: data.skills || [],
-        commands: data.commands || []
+        agents: normalize(data.agents),
+        skills: normalize(data.skills),
+        commands: normalize(data.commands)
       };
     } catch {
       // Fall through to filesystem scan
@@ -874,6 +949,9 @@ function detectInstalledPlatforms() {
   // Cursor rules are project-scoped; detect only if Cursor rules/commands/skills exist in CWD
   const cursorDir = path.join(process.cwd(), '.cursor');
   if (fs.existsSync(path.join(cursorDir, 'rules')) || fs.existsSync(path.join(cursorDir, 'commands')) || fs.existsSync(path.join(cursorDir, 'skills'))) platforms.push('cursor');
+  // Kiro is project-scoped; detect if .kiro/ directory exists in CWD
+  const kiroDir = path.join(process.cwd(), '.kiro');
+  if (fs.existsSync(path.join(kiroDir, 'steering')) || fs.existsSync(path.join(kiroDir, 'skills')) || fs.existsSync(path.join(kiroDir, 'agents'))) platforms.push('kiro');
   return platforms;
 }
 
@@ -914,12 +992,15 @@ async function installPlugin(nameWithVersion, args) {
   // Fetch all
   for (const depName of toFetch) {
     const dep = pluginMap[depName];
-    const depSourceUrl = resolveSourceUrl(dep && dep.source);
-    if (!dep || !depSourceUrl || depSourceUrl.startsWith('./')) continue;
+    if (!dep) continue;
+
+    const source = resolvePluginSource(dep.source);
+    if (!source || source.type === 'local') continue;
+
     checkCoreCompat(dep);
     const ver = depName === name && requestedVersion ? requestedVersion : dep.version;
     try {
-      await fetchPlugin(depName, depSourceUrl, ver);
+      await fetchPlugin(depName, source.value, ver);
     } catch (err) {
       console.error(`  [ERROR] Failed to fetch ${depName}: ${err.message}`);
     }
@@ -967,7 +1048,7 @@ async function installPlugin(nameWithVersion, args) {
 
   // Use cache as install source
   const installDir = getInstallDir();
-  const needsLocal = platforms.includes('opencode') || platforms.includes('codex') || platforms.includes('cursor');
+  const needsLocal = platforms.includes('opencode') || platforms.includes('codex') || platforms.includes('cursor') || platforms.includes('kiro');
   if (needsLocal && !fs.existsSync(path.join(installDir, 'lib'))) {
     // Need local install for transforms
     cleanOldInstallation(installDir);
@@ -1004,6 +1085,9 @@ async function installPlugin(nameWithVersion, args) {
   if (platforms.includes('cursor') && installDir) {
     installForCursor(installDir, { filter });
   }
+  if (platforms.includes('kiro') && installDir) {
+    installForKiro(installDir, { filter });
+  }
 
   // Record in installed.json
   for (const depName of toFetch) {
@@ -1615,6 +1699,158 @@ function installForCursor(installDir, options = {}) {
   return true;
 }
 
+function installForKiro(installDir, options = {}) {
+  console.log('\n[INSTALL] Installing for Kiro...\n');
+  const { filter = null } = options;
+  const cwd = process.cwd();
+
+  // Create target directories (all project-scoped)
+  const skillsDir = path.join(cwd, '.kiro', 'skills');
+  const steeringDir = path.join(cwd, '.kiro', 'steering');
+  const agentsDir = path.join(cwd, '.kiro', 'agents');
+  fs.mkdirSync(skillsDir, { recursive: true });
+  fs.mkdirSync(steeringDir, { recursive: true });
+  fs.mkdirSync(agentsDir, { recursive: true });
+
+  // Cleanup old agentsys steering files (only those matching known commands)
+  const steeringMappingsForCleanup = discovery.getKiroSteeringMappings(installDir);
+  const knownSteeringFiles = new Set(steeringMappingsForCleanup.map(([name]) => `${name}.md`));
+  for (const f of fs.readdirSync(steeringDir).filter(f => f.endsWith('.md'))) {
+    if (knownSteeringFiles.has(f)) {
+      fs.unlinkSync(path.join(steeringDir, f));
+    }
+  }
+
+  // Collect known skill names from discovery before cleanup
+  const pluginDirs = discovery.discoverPlugins(installDir);
+  const knownSkillNames = new Set();
+  for (const pluginName of pluginDirs) {
+    const srcSkillsDir = path.join(installDir, 'plugins', pluginName, 'skills');
+    if (!fs.existsSync(srcSkillsDir)) continue;
+    for (const d of fs.readdirSync(srcSkillsDir, { withFileTypes: true })) {
+      if (d.isDirectory() && /^[a-zA-Z0-9_-]+$/.test(d.name)) knownSkillNames.add(d.name);
+    }
+  }
+
+  // Cleanup old agentsys skill dirs (only known names, preserve user-created skills)
+  for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+    if (entry.isDirectory() && knownSkillNames.has(entry.name)) {
+      fs.rmSync(path.join(skillsDir, entry.name), { recursive: true, force: true });
+    }
+  }
+
+  // Cleanup old agentsys agent JSON files (only those matching known agents)
+  const knownAgentFiles = new Set();
+  for (const pluginName of pluginDirs) {
+    const srcAgentsDir = path.join(installDir, 'plugins', pluginName, 'agents');
+    if (!fs.existsSync(srcAgentsDir)) continue;
+    for (const f of fs.readdirSync(srcAgentsDir).filter(f => f.endsWith('.md'))) {
+      knownAgentFiles.add(f.replace(/\.md$/, '.json'));
+    }
+  }
+  for (const f of fs.readdirSync(agentsDir).filter(f => f.endsWith('.json'))) {
+    if (knownAgentFiles.has(f)) {
+      fs.unlinkSync(path.join(agentsDir, f));
+    }
+  }
+
+  // Install skills
+  let skillCount = 0;
+  for (const pluginName of pluginDirs) {
+    const srcSkillsDir = path.join(installDir, 'plugins', pluginName, 'skills');
+    if (!fs.existsSync(srcSkillsDir)) continue;
+    const entries = fs.readdirSync(srcSkillsDir, { withFileTypes: true }).filter(d => d.isDirectory());
+    for (const entry of entries) {
+      if (!/^[a-zA-Z0-9_-]+$/.test(entry.name)) continue;
+      if (filter && filter.skills && filter.skills.length > 0 && !filter.skills.includes(entry.name)) continue;
+      const srcPath = path.join(srcSkillsDir, entry.name, 'SKILL.md');
+      if (!fs.existsSync(srcPath)) continue;
+      const destDir = path.join(skillsDir, entry.name);
+      fs.mkdirSync(destDir, { recursive: true });
+      let content = fs.readFileSync(srcPath, 'utf8');
+      content = transforms.transformSkillForKiro(content, {
+        pluginInstallPath: path.join(installDir, 'plugins', pluginName)
+      });
+      fs.writeFileSync(path.join(destDir, 'SKILL.md'), content);
+      skillCount++;
+    }
+  }
+
+  // Install commands as steering files
+  const steeringMappings = discovery.getKiroSteeringMappings(installDir);
+  let steeringCount = 0;
+  for (const [steeringName, plugin, sourceFile, description] of steeringMappings) {
+    if (filter && filter.commands && filter.commands.length > 0) {
+      if (!filter.commands.includes(steeringName)) continue;
+    }
+    const srcPath = path.join(installDir, 'plugins', plugin, 'commands', sourceFile);
+    if (!fs.existsSync(srcPath)) {
+      console.log(`  [WARN] Source file not found: ${srcPath}`);
+      continue;
+    }
+    let content = fs.readFileSync(srcPath, 'utf8');
+    content = transforms.transformCommandForKiro(content, {
+      pluginInstallPath: path.join(installDir, 'plugins', plugin),
+      name: steeringName,
+      description
+    });
+    fs.writeFileSync(path.join(steeringDir, `${steeringName}.md`), content);
+    steeringCount++;
+  }
+
+  // Install agents as JSON files
+  let agentCount = 0;
+  for (const pluginName of pluginDirs) {
+    const srcAgentsDir = path.join(installDir, 'plugins', pluginName, 'agents');
+    if (!fs.existsSync(srcAgentsDir)) continue;
+    const agentFiles = fs.readdirSync(srcAgentsDir).filter(f => f.endsWith('.md'));
+    for (const agentFile of agentFiles) {
+      const agentName = agentFile.replace(/\.md$/, '');
+      if (filter && filter.agents && filter.agents.length > 0 && !filter.agents.includes(agentName)) continue;
+      const srcPath = path.join(srcAgentsDir, agentFile);
+      let content = fs.readFileSync(srcPath, 'utf8');
+      const jsonContent = transforms.transformAgentForKiro(content, {
+        pluginInstallPath: path.join(installDir, 'plugins', pluginName)
+      });
+      fs.writeFileSync(path.join(agentsDir, `${agentName}.json`), jsonContent);
+      agentCount++;
+    }
+  }
+
+  // Generate combined reviewer agents for Kiro's 4-agent experimental limit.
+  // These are fallback agents that merge 2 review passes into 1 agent session.
+  const combinedReviewers = [
+    {
+      name: 'reviewer-quality-security',
+      description: 'Combined code quality and security reviewer for Kiro',
+      roles: [
+        { name: 'Code Quality', focus: 'Error handling, maintainability, naming, duplication, dead code, logging quality' },
+        { name: 'Security', focus: 'Auth vulnerabilities, input validation, injection risks, secrets exposure, OWASP top 10' },
+      ]
+    },
+    {
+      name: 'reviewer-perf-test',
+      description: 'Combined performance and test coverage reviewer for Kiro',
+      roles: [
+        { name: 'Performance', focus: 'Hot paths, algorithmic complexity, unnecessary allocations, N+1 queries, caching opportunities' },
+        { name: 'Test Coverage', focus: 'Missing tests, edge cases, assertion quality, test isolation, mock correctness' },
+      ]
+    },
+  ];
+  for (const cr of combinedReviewers) {
+    const json = transforms.generateCombinedReviewerAgent(cr.roles, cr.name, cr.description);
+    fs.writeFileSync(path.join(agentsDir, `${cr.name}.json`), json);
+    agentCount++;
+  }
+
+  console.log(`\n[OK] Kiro installation complete!`);
+  console.log(`   Skills: ${skillCount} installed to ${skillsDir}`);
+  console.log(`   Steering: ${steeringCount} installed to ${steeringDir}`);
+  console.log(`   Agents: ${agentCount} installed to ${agentsDir} (includes 2 combined reviewers)`);
+  console.log('   All content is project-scoped under .kiro/.\n');
+  return true;
+}
+
 function removeInstallation() {
   const installDir = getInstallDir();
 
@@ -1632,6 +1868,7 @@ function removeInstallation() {
   console.log('  - OpenCode: Remove files under ~/.config/opencode/ (commands/*.md, agents/*.md, skills/*/SKILL.md) and ~/.config/opencode/plugins/agentsys.ts');
   console.log('  - Codex: Remove ~/.codex/skills/*/');
   console.log('  - Cursor: Remove .cursor/skills/, .cursor/commands/, and .cursor/rules/agentsys-*.mdc from your project');
+  console.log('  - Kiro: Remove .kiro/skills/, .kiro/steering/, and .kiro/agents/ from your project');
 }
 
 function printSubcommandHelp(subcommand) {
@@ -1652,7 +1889,7 @@ Examples:
   agentsys install perf@1.2.0            Install perf at version 1.2.0
 
 Options:
-  --tool <name>     Install for a specific platform (claude, opencode, codex, cursor)
+  --tool <name>     Install for a specific platform (claude, opencode, codex, cursor, kiro)
   --tools <list>    Install for multiple platforms (comma-separated)
 
 Notes:
@@ -1746,7 +1983,7 @@ agentsys v${VERSION} - Workflow automation for AI coding assistants
 
 Usage:
   agentsys                    Interactive installer (select platforms)
-  agentsys --tool <name>      Install for single tool (claude, opencode, codex, cursor)
+  agentsys --tool <name>      Install for single tool (claude, opencode, codex, cursor, kiro)
   agentsys --tools <list>     Install for multiple tools (comma-separated)
   agentsys --only <plugins>   Install only specified plugins (comma-separated, resolves deps)
   agentsys --development      Development mode: install to ~/.claude/plugins
@@ -1773,7 +2010,7 @@ Non-Interactive Examples:
   agentsys --tool claude              # Install for Claude Code only
   agentsys --tool opencode            # Install for OpenCode only
   agentsys --tools "claude,opencode"  # Install for both
-  agentsys --tools claude,opencode,codex,cursor  # Install for all
+  agentsys --tools claude,opencode,codex,cursor,kiro  # Install for all
   agentsys --only next-task           # Install next-task + its dependencies
   agentsys --only "next-task,perf"    # Install specific plugins + deps
 
@@ -1793,7 +2030,8 @@ Supported Platforms:
   claude   - Claude Code (marketplace install or development mode)
   opencode - OpenCode (local commands + native plugin)
   codex    - Codex CLI (local skills)
-  cursor   - Cursor (project-scoped .mdc rules)
+  cursor   - Cursor (project-scoped skills + commands)
+  kiro     - Kiro (project-scoped steering + skills + agents)
 
 Install:  npm install -g agentsys && agentsys
 Update:   npm update -g agentsys && agentsys
@@ -1899,7 +2137,8 @@ async function main() {
       { value: 'claude', label: 'Claude Code' },
       { value: 'opencode', label: 'OpenCode' },
       { value: 'codex', label: 'Codex CLI' },
-      { value: 'cursor', label: 'Cursor' }
+      { value: 'cursor', label: 'Cursor' },
+      { value: 'kiro', label: 'Kiro' }
     ];
 
     selected = await multiSelect(
@@ -1928,10 +2167,8 @@ async function main() {
     if (entry) checkCoreCompat(entry);
   }
 
-  await fetchExternalPlugins(pluginNames, marketplace);
-
   // Only copy to ~/.agentsys if OpenCode, Codex, or Cursor selected (they need local files)
-  const needsLocalInstall = selected.includes('opencode') || selected.includes('codex') || selected.includes('cursor');
+  const needsLocalInstall = selected.includes('opencode') || selected.includes('codex') || selected.includes('cursor') || selected.includes('kiro');
   let installDir = null;
 
   if (needsLocalInstall) {
@@ -1941,6 +2178,8 @@ async function main() {
     installDependencies(installDir);
   }
 
+  await fetchExternalPlugins(pluginNames, marketplace);
+
   // Install for each platform
   const failedPlatforms = [];
   for (const platform of selected) {
@@ -1969,6 +2208,11 @@ async function main() {
           failedPlatforms.push('cursor');
         }
         break;
+      case 'kiro':
+        if (!installForKiro(installDir)) {
+          failedPlatforms.push('kiro');
+        }
+        break;
     }
   }
 
@@ -2020,5 +2264,8 @@ module.exports = {
   loadComponents,
   resolveComponent,
   buildFilterFromComponent,
-  installForCursor
+  resolvePluginSource,
+  parseGitHubSource,
+  installForCursor,
+  installForKiro
 };