agentsys 5.4.0 → 5.5.0

package/lib/binary/index.js

@@ -0,0 +1,398 @@
+'use strict';
+
+/**
+ * Binary resolver for the agent-analyzer Rust binary.
+ *
+ * Handles lazy downloading and execution. Since Claude Code plugins have no
+ * postinstall hooks, the binary is downloaded at runtime on first use.
+ *
+ * @module lib/binary
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const https = require('https');
+const cp = require('child_process');
+const { promisify } = require('util');
+
+const execFileAsync = promisify(cp.execFile);
+
+const { ANALYZER_MIN_VERSION, BINARY_NAME, GITHUB_REPO } = require('./version');
+
+const PLATFORM_MAP = {
+  'darwin-arm64': 'aarch64-apple-darwin',
+  'darwin-x64':   'x86_64-apple-darwin',
+  'linux-x64':    'x86_64-unknown-linux-gnu',
+  'linux-arm64':  'aarch64-unknown-linux-gnu',
+  'win32-x64':    'x86_64-pc-windows-msvc'
+};
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the expected path to the agent-analyzer binary.
+ * @returns {string}
+ */
+function getBinaryPath() {
+  const ext = process.platform === 'win32' ? '.exe' : '';
+  return path.join(os.homedir(), '.agent-sh', 'bin', BINARY_NAME + ext);
+}
+
+/**
+ * Returns the Rust target triple for the current platform.
+ * @returns {string|null}
+ */
+function getPlatformKey() {
+  const key = process.platform + '-' + process.arch;
+  return PLATFORM_MAP[key] || null;
+}
+
+// ---------------------------------------------------------------------------
+// Version helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Compare a version string against a minimum requirement.
+ * @param {string} version
+ * @param {string} minVersion
+ * @returns {boolean}
+ */
+function meetsMinimumVersion(version, minVersion) {
+  if (!version) return false;
+  const match = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return false;
+  const parts = match.slice(1).map(Number);
+  const req = minVersion.split('.').map(Number);
+  if (parts[0] > req[0]) return true;
+  if (parts[0] < req[0]) return false;
+  if (parts[1] > req[1]) return true;
+  if (parts[1] < req[1]) return false;
+  return parts[2] >= req[2];
+}
+
+/**
+ * Run the binary with --version and return the version string, or null on failure.
+ * @returns {string|null}
+ */
+function getVersion() {
+  const binPath = getBinaryPath();
+  if (!fs.existsSync(binPath)) return null;
+  try {
+    const out = cp.execFileSync(binPath, ['--version'], {
+      timeout: 5000,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true
+    });
+    const match = out.trim().match(/(\d+\.\d+\.\d+)/);
+    return match ? match[1] : out.trim();
+  } catch (e) {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Availability checks
+// ---------------------------------------------------------------------------
+
+/**
+ * Sync check: returns true if the binary exists and meets the minimum version.
+ * Does NOT download.
+ * @returns {boolean}
+ */
+function isAvailable() {
+  const binPath = getBinaryPath();
+  if (!fs.existsSync(binPath)) return false;
+  const ver = getVersion();
+  return meetsMinimumVersion(ver, ANALYZER_MIN_VERSION);
+}
+
+/**
+ * Async check: returns true if the binary exists and meets the minimum version.
+ * Does NOT download.
+ * @returns {Promise<boolean>}
+ */
+async function isAvailableAsync() {
+  return isAvailable();
+}
+
+// ---------------------------------------------------------------------------
+// Download
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the GitHub release download URL.
+ * @param {string} ver
+ * @param {string} platformKey
+ * @returns {string}
+ */
+function buildDownloadUrl(ver, platformKey) {
+  const ext = process.platform === 'win32' ? '.zip' : '.tar.gz';
+  return 'https://github.com/' + GITHUB_REPO + '/releases/download/v' + ver + '/' + BINARY_NAME + '-' + platformKey + ext;
+}
+
+/**
+ * Download a URL to a Buffer, following up to 5 redirects.
+ * Supports GITHUB_TOKEN / GH_TOKEN for auth.
+ * @param {string} url
+ * @returns {Promise<Buffer>}
+ */
+function downloadToBuffer(url) {
+  return new Promise(function(resolve, reject) {
+    const ghToken = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+
+    function request(reqUrl, redirectCount) {
+      if (redirectCount > 5) {
+        reject(new Error('Too many redirects fetching from ' + url));
+        return;
+      }
+      const headers = {
+        'User-Agent': 'agent-core/binary-resolver',
+        'Accept': 'application/octet-stream'
+      };
+      if (ghToken) headers['Authorization'] = 'Bearer ' + ghToken;
+
+      https.get(reqUrl, { headers: headers }, function(res) {
+        const sc = res.statusCode;
+        if (sc === 301 || sc === 302 || sc === 307 || sc === 308) {
+          res.resume();
+          request(res.headers.location, redirectCount + 1);
+          return;
+        }
+        if (sc !== 200) {
+          res.resume();
+          const hint = sc === 403 ? ' (rate limited - set GITHUB_TOKEN env var)' : '';
+          reject(new Error('HTTP ' + sc + hint + ' fetching ' + reqUrl));
+          return;
+        }
+        const chunks = [];
+        res.on('data', function(chunk) { chunks.push(chunk); });
+        res.on('end', function() { resolve(Buffer.concat(chunks)); });
+        res.on('error', reject);
+      }).on('error', reject);
+    }
+
+    request(url, 0);
+  });
+}
+
+/**
+ * Extract a tar.gz buffer into a directory using the system tar command.
+ * @param {Buffer} buf
+ * @param {string} destDir
+ * @returns {Promise<void>}
+ */
+function extractTarGz(buf, destDir) {
+  return new Promise(function(resolve, reject) {
+    const tarDest = process.platform === 'win32' ? destDir.replace(/\\/g, '/') : destDir;
+    const tar = cp.spawn('tar', ['xz', '-C', tarDest], {
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    let stderr = '';
+    tar.stderr.on('data', function(d) { stderr += d; });
+    tar.stdin.write(buf);
+    tar.stdin.end();
+    tar.on('close', function(code) {
+      if (code !== 0) {
+        reject(new Error('tar extraction failed (code ' + code + '): ' + stderr));
+      } else {
+        resolve();
+      }
+    });
+    tar.on('error', reject);
+  });
+}
+
+/**
+ * Extract a zip buffer into a directory using PowerShell Expand-Archive (Windows).
+ * @param {Buffer} buf
+ * @param {string} destDir
+ * @param {string} binaryName
+ * @returns {Promise<void>}
+ */
+function extractZip(buf, destDir, binaryName) {
+  return new Promise(function(resolve, reject) {
+    const tmpZip = path.join(os.tmpdir(), binaryName + '-' + Date.now() + '.zip');
+    fs.writeFileSync(tmpZip, buf);
+    const cmd = 'Expand-Archive -Path \'' + tmpZip + '\' -DestinationPath \'' + destDir + '\' -Force';
+    const ps = cp.spawn('powershell', ['-NoProfile', '-NonInteractive', '-Command', cmd], {
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    let stderr = '';
+    ps.stderr.on('data', function(d) { stderr += d; });
+    ps.on('close', function(code) {
+      try { fs.unlinkSync(tmpZip); } catch (e) { /* ignore */ }
+      if (code !== 0) {
+        reject(new Error('zip extraction failed (code ' + code + '): ' + stderr));
+      } else {
+        resolve();
+      }
+    });
+    ps.on('error', reject);
+  });
+}
+
+/**
+ * Download and install the binary for the current platform into ~/.agent-sh/bin/.
+ * @param {string} ver
+ * @returns {Promise<string>}
+ */
+async function downloadBinary(ver) {
+  const platformKey = getPlatformKey();
+  if (!platformKey) {
+    throw new Error(
+      'Unsupported platform: ' + process.platform + '-' + process.arch + '. ' +
+      'Supported platforms: ' + Object.keys(PLATFORM_MAP).join(', ')
+    );
+  }
+
+  const url = buildDownloadUrl(ver, platformKey);
+  process.stderr.write('Downloading ' + BINARY_NAME + ' v' + ver + ' for ' + platformKey + '...' + '\n');
+
+  const binPath = getBinaryPath();
+  const binDir = path.dirname(binPath);
+  fs.mkdirSync(binDir, { recursive: true });
+
+  let buf;
+  try {
+    buf = await downloadToBuffer(url);
+  } catch (err) {
+    throw new Error(
+      'Failed to download ' + BINARY_NAME + ':\n' +
+      '  URL: ' + url + '\n' +
+      '  Error: ' + err.message + '\n\n' +
+      'To install manually:\n' +
+      '  1. Download: ' + url + '\n' +
+      '  2. Extract the binary to: ' + binDir + '\n' +
+      '  3. Ensure it is named: ' + path.basename(binPath)
+    );
+  }
+
+  if (process.platform === 'win32') {
+    await extractZip(buf, binDir, path.basename(binPath));
+  } else {
+    await extractTarGz(buf, binDir);
+  }
+
+  if (process.platform !== 'win32') {
+    fs.chmodSync(binPath, 0o755);
+  }
+
+  const installedVer = getVersion();
+  if (!installedVer) {
+    throw new Error(
+      BINARY_NAME + ' was downloaded to ' + binPath + ' but could not be executed. ' +
+      'Check the file is a valid binary for this platform.'
+    );
+  }
+
+  return binPath;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Ensure the binary exists and meets the minimum version. Downloads if needed.
+ * @param {Object} [options]
+ * @param {string} [options.version]
+ * @returns {Promise<string>}
+ */
+async function ensureBinary(options) {
+  const opts = options || {};
+  const targetVer = opts.version || ANALYZER_MIN_VERSION;
+  const binPath = getBinaryPath();
+
+  if (fs.existsSync(binPath)) {
+    const ver = getVersion();
+    if (meetsMinimumVersion(ver, ANALYZER_MIN_VERSION)) {
+      return binPath;
+    }
+  }
+
+  return downloadBinary(targetVer);
+}
+
+/**
+ * Sync version of ensureBinary. Downloads if needed via a child node process.
+ * Prefer ensureBinary() unless a sync API is strictly required.
+ * @param {Object} [options]
+ * @param {string} [options.version]
+ * @returns {string}
+ */
+function ensureBinarySync(options) {
+  const binPath = getBinaryPath();
+
+  if (fs.existsSync(binPath)) {
+    const ver = getVersion();
+    if (meetsMinimumVersion(ver, ANALYZER_MIN_VERSION)) {
+      return binPath;
+    }
+  }
+
+  const targetVer = (options && options.version) || ANALYZER_MIN_VERSION;
+  const selfPath = __filename;
+  const helperLines = [
+    'var b = require(' + JSON.stringify(selfPath) + ');',
+    'b.ensureBinary({ version: ' + JSON.stringify(targetVer) + ' })',
+    '  .then(function(p) { process.stdout.write(p); })',
+    '  .catch(function(e) { process.stderr.write(e.message); process.exit(1); });'
+  ];
+
+  try {
+    const result = cp.execFileSync(process.execPath, ['-e', helperLines.join('\n')], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'inherit'],
+      timeout: 120000
+    });
+    return result.trim() || binPath;
+  } catch (err) {
+    throw new Error('Failed to ensure binary (sync): ' + err.message);
+  }
+}
+
+/**
+ * Run agent-analyzer with the given arguments (sync). Downloads binary if needed.
+ * @param {string[]} args
+ * @param {Object} [options]
+ * @returns {string}
+ */
+function runAnalyzer(args, options) {
+  const binPath = ensureBinarySync();
+  const opts = Object.assign({ encoding: 'utf8', windowsHide: true }, options);
+  if (!opts.stdio) opts.stdio = ['pipe', 'pipe', 'pipe'];
+  const result = cp.execFileSync(binPath, args, opts);
+  return typeof result === 'string' ? result : result.toString('utf8');
+}
+
+/**
+ * Run agent-analyzer with the given arguments asynchronously. Downloads binary if needed.
+ * @param {string[]} args
+ * @param {Object} [options]
+ * @returns {Promise<string>}
+ */
+async function runAnalyzerAsync(args, options) {
+  const binPath = await ensureBinary();
+  const opts = Object.assign({ encoding: 'utf8', windowsHide: true }, options);
+  const result = await execFileAsync(binPath, args, opts);
+  return result.stdout;
+}
+
+module.exports = {
+  ensureBinary,
+  ensureBinarySync,
+  runAnalyzer,
+  runAnalyzerAsync,
+  getBinaryPath,
+  getVersion,
+  getPlatformKey,
+  isAvailable,
+  isAvailableAsync,
+  meetsMinimumVersion,
+  buildDownloadUrl,
+  PLATFORM_MAP
+};

package/lib/binary/version.js

@@ -0,0 +1,16 @@
+'use strict';
+
+// Minimum binary version required by this version of agent-core
+const ANALYZER_MIN_VERSION = '0.1.0';
+
+// Binary name
+const BINARY_NAME = 'agent-analyzer';
+
+// GitHub repo for releases
+const GITHUB_REPO = 'agent-sh/agent-analyzer';
+
+module.exports = {
+  ANALYZER_MIN_VERSION,
+  BINARY_NAME,
+  GITHUB_REPO
+};

package/lib/collectors/git.js

@@ -0,0 +1,139 @@
+/**
+ * Git History Collector
+ *
+ * Collects git history analysis data using the agent-analyzer binary.
+ * Runs a full repo-intel init and extracts key metrics for downstream consumers.
+ *
+ * @module lib/collectors/git
+ */
+
+'use strict';
+
+const binary = require('../binary');
+
+const DEFAULT_OPTIONS = {
+  top: 20,
+  adjustForAi: false,
+  cwd: process.cwd()
+};
+
+/**
+ * Collect git history data for the given repository.
+ *
+ * Runs agent-analyzer repo-intel init to produce a full map, then extracts
+ * key metrics (hotspots, bus factor, AI ratio, etc.) from the result.
+ *
+ * @param {Object} [options={}] - Collection options
+ * @param {string} [options.cwd] - Repository path (default: process.cwd())
+ * @param {number} [options.top=20] - Number of hotspots to return
+ * @param {boolean} [options.adjustForAi=false] - Adjust bus factor for AI commits
+ * @returns {Object} Git history metrics
+ */
+function collectGitData(options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const cwd = opts.cwd || process.cwd();
+
+  try {
+    binary.ensureBinarySync();
+  } catch (err) {
+    return {
+      available: false,
+      error: `Binary not available: ${err.message}`
+    };
+  }
+
+  let map;
+  try {
+    const json = binary.runAnalyzer(['repo-intel', 'init', cwd]);
+    map = JSON.parse(json);
+  } catch (err) {
+    return {
+      available: false,
+      error: `Git analysis failed: ${err.message}`
+    };
+  }
+
+  // Extract metrics from the map
+  const fileActivity = map.fileActivity || {};
+  const contributors = map.contributors || {};
+  const aiAttribution = map.aiAttribution || {};
+  const conventions = map.conventions || {};
+  const releases = map.releases || {};
+
+  // Hotspots: sort files by change count
+  const hotspots = Object.entries(fileActivity)
+    .map(([path, activity]) => ({
+      path,
+      changes: activity.totalChanges || 0,
+      recentChanges: activity.recentChanges || 0,
+      authors: activity.authors ? Object.keys(activity.authors).length : 0,
+      lastChanged: activity.lastChanged || null
+    }))
+    .sort((a, b) => b.changes - a.changes)
+    .slice(0, opts.top);
+
+  // Contributors summary
+  const humans = contributors.humans || {};
+  const humanList = Object.entries(humans)
+    .map(([name, data]) => ({
+      name,
+      commits: data.commitCount || 0,
+      firstSeen: data.firstSeen || null,
+      lastSeen: data.lastSeen || null
+    }))
+    .sort((a, b) => b.commits - a.commits);
+
+  // Bus factor: people covering 80% of commits
+  const totalCommits = humanList.reduce((sum, c) => sum + c.commits, 0);
+  let cumulative = 0;
+  let busFactor = 0;
+  for (const contributor of humanList) {
+    cumulative += contributor.commits;
+    busFactor++;
+    if (cumulative >= totalCommits * 0.8) break;
+  }
+
+  // AI ratio
+  const aiTotal = (aiAttribution.attributed || 0) + (aiAttribution.heuristic || 0);
+  const allCommits = map.git?.totalCommitsAnalyzed || totalCommits;
+  const aiRatio = allCommits > 0 ? aiTotal / allCommits : 0;
+
+  return {
+    available: true,
+    health: {
+      active: humanList.length > 0,
+      busFactor,
+      aiRatio: Math.round(aiRatio * 100) / 100,
+      totalCommits: allCommits,
+      totalContributors: humanList.length
+    },
+    hotspots,
+    contributors: humanList.slice(0, 10),
+    aiAttribution: {
+      ratio: Math.round(aiRatio * 100) / 100,
+      attributed: aiAttribution.attributed || 0,
+      heuristic: aiAttribution.heuristic || 0,
+      none: aiAttribution.none || 0,
+      confidence: aiAttribution.confidence || 'low',
+      tools: aiAttribution.tools || {}
+    },
+    busFactor,
+    conventions: {
+      style: conventions.style || null,
+      prefixes: conventions.prefixes || {},
+      usesScopes: conventions.usesScopes || false
+    },
+    releaseInfo: {
+      tagCount: releases.tags ? releases.tags.length : 0,
+      lastRelease: releases.tags && releases.tags.length > 0
+        ? releases.tags[releases.tags.length - 1]
+        : null,
+      cadence: releases.cadence || null
+    }
+  };
+}
+
+module.exports = {
+  collectGitData,
+  DEFAULT_OPTIONS
+};

package/lib/collectors/index.js

@@ -13,6 +13,7 @@ const github = require('./github');
 const documentation = require('./documentation');
 const codebase = require('./codebase');
 const docsPatterns = require('./docs-patterns');
+const git = require('./git');
 
 const DEFAULT_OPTIONS = {
   collectors: ['github', 'docs', 'code'],
@@ -50,7 +51,8 @@ function collect(options = {}) {
     github: null,
     docs: null,
     code: null,
-    docsPatterns: null
+    docsPatterns: null,
+    git: null
   };
 
   // Collect from each enabled collector
@@ -70,6 +72,10 @@ function collect(options = {}) {
     data.docsPatterns = docsPatterns.collect(opts);
   }
 
+  if (collectors.includes('git')) {
+    data.git = git.collectGitData(opts);
+  }
+
   return data;
 }
 
@@ -103,6 +109,7 @@ module.exports = {
   documentation,
   codebase,
   docsPatterns,
+  git,
 
   // Re-export commonly used functions for convenience
   scanGitHubState: github.scanGitHubState,
@@ -121,6 +128,8 @@ module.exports = {
   isInternalExport: docsPatterns.isInternalExport,
   isEntryPoint: docsPatterns.isEntryPoint,
 
+  collectGitData: git.collectGitData,
+
   // Constants
   DEFAULT_OPTIONS
 };

package/lib/cross-platform/index.js

@@ -5,8 +5,6 @@
  * - Claude Code (Anthropic)
  * - OpenCode (multi-model)
  * - Codex CLI (OpenAI)
- * - Cursor (AI-first editor)
- * - Kiro (AWS agentic IDE)
  *
  * Based on research from official documentation:
  * - Anthropic Claude 4 Best Practices
@@ -46,9 +44,7 @@ function compareSemver(a, b) {
 const PLATFORMS = {
   CLAUDE_CODE: 'claude-code',
   OPENCODE: 'opencode',
-  CODEX_CLI: 'codex-cli',
-  CURSOR: 'cursor',
-  KIRO: 'kiro'
+  CODEX_CLI: 'codex-cli'
 };
 
 /**
@@ -58,9 +54,7 @@ const PLATFORMS = {
 const STATE_DIRS = {
   [PLATFORMS.CLAUDE_CODE]: '.claude',
   [PLATFORMS.OPENCODE]: '.opencode',
-  [PLATFORMS.CODEX_CLI]: '.codex',
-  [PLATFORMS.CURSOR]: '.cursor',
-  [PLATFORMS.KIRO]: '.kiro'
+  [PLATFORMS.CODEX_CLI]: '.codex'
 };
 
 /**
@@ -82,8 +76,6 @@ function detectPlatform() {
   const stateDir = process.env.AI_STATE_DIR;
   if (stateDir === '.opencode') return PLATFORMS.OPENCODE;
   if (stateDir === '.codex') return PLATFORMS.CODEX_CLI;
-  if (stateDir === '.cursor') return PLATFORMS.CURSOR;
-  if (stateDir === '.kiro') return PLATFORMS.KIRO;
   return PLATFORMS.CLAUDE_CODE;
 }
 
@@ -491,9 +483,7 @@ enabled = true
 const INSTRUCTION_FILES = {
   [PLATFORMS.CLAUDE_CODE]: ['CLAUDE.md', '.claude/CLAUDE.md'],
   [PLATFORMS.OPENCODE]: ['AGENTS.md', 'CLAUDE.md'],
-  [PLATFORMS.CODEX_CLI]: ['AGENTS.md', 'AGENTS.override.md'],
-  [PLATFORMS.CURSOR]: ['.cursor/rules/*.mdc'],
-  [PLATFORMS.KIRO]: ['AGENTS.md', '.kiro/steering/*.md']
+  [PLATFORMS.CODEX_CLI]: ['AGENTS.md', 'AGENTS.override.md']
 };
 
 /**