agentsys 5.14.0 → 6.0.0

package/lib/repo-intel/enrich.js

@@ -0,0 +1,198 @@
+/**
+ * Post-init enrichment helpers.
+ *
+ * The repo-intel skill spawns two Haiku-backed Task subagents after
+ * the deterministic init/update pass:
+ *
+ * 1. `repo-intel-summarizer` reads README + manifests + hotspot
+ *    headers and writes a 3-depth narrative summary.
+ * 2. `repo-intel-weighter` writes 1-2 sentence descriptors for the
+ *    top-N most-active files, used by `find` to add semantic recall.
+ *
+ * The orchestration calls into this module to gather the agents'
+ * inputs, parse their JSON outputs (which arrive between marker
+ * blocks because subagent stdout is otherwise free-form), and pipe
+ * the result back through `repoIntel.applyDescriptors` /
+ * `applySummary`. The Rust binary stores the data; this module
+ * never touches the LLM directly.
+ *
+ * @module lib/repo-intel/enrich
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+/**
+ * Read the README, returning empty string when absent so the
+ * downstream JSON.stringify doesn't break.
+ */
+function readReadme(repoPath) {
+  for (const name of ['README.md', 'README.MD', 'readme.md', 'README.rst', 'README.txt', 'README']) {
+    const candidate = path.join(repoPath, name);
+    if (fs.existsSync(candidate)) {
+      try { return fs.readFileSync(candidate, 'utf8'); } catch { /* fall through */ }
+    }
+  }
+  return '';
+}
+
+/**
+ * Read whichever manifests are present and return them as a parsed
+ * object keyed by manifest filename. Used by the summarizer to
+ * understand what kind of project it's looking at.
+ */
+function readManifests(repoPath) {
+  const manifests = {};
+  for (const name of ['package.json', 'Cargo.toml', 'pyproject.toml', 'go.mod', 'pom.xml', 'build.gradle']) {
+    const p = path.join(repoPath, name);
+    if (fs.existsSync(p)) {
+      try {
+        const text = fs.readFileSync(p, 'utf8');
+        // Don't attempt to parse non-JSON manifests - the summarizer
+        // can read them as plain strings.
+        if (name.endsWith('.json')) {
+          try { manifests[name] = JSON.parse(text); }
+          catch { manifests[name] = text.slice(0, 4000); }
+        } else {
+          manifests[name] = text.slice(0, 4000);
+        }
+      } catch { /* skip on read error */ }
+    }
+  }
+  return manifests;
+}
+
+/**
+ * Pick the top-N files by activity (changes + 2*recent_changes), and
+ * return `{path, head}` for each where `head` is the first 500 chars
+ * of file content. Used as `hotspots` input to the summarizer.
+ *
+ * For the weighter we just want the path list - call `topPaths()`.
+ */
+function topHotspots(repoPath, repoIntelData, n = 10) {
+  const paths = topPaths(repoIntelData, n);
+  return paths.map((p) => {
+    const abs = path.join(repoPath, p);
+    let head = '';
+    try {
+      const buf = fs.readFileSync(abs);
+      head = buf.subarray(0, Math.min(buf.length, 500)).toString('utf8');
+    } catch { /* file missing on disk, skip */ }
+    return { path: p, head };
+  });
+}
+
+/**
+ * Rank file_activity entries by activity score and return the top N
+ * paths. Recent changes are weighted 2x because the agent should
+ * prioritize files that are still being actively touched.
+ */
+function topPaths(repoIntelData, n) {
+  const fa = repoIntelData.fileActivity || {};
+  const scored = Object.entries(fa)
+    .map(([p, a]) => ({
+      path: p,
+      score: (a.changes || 0) + 2 * (a.recentChanges || 0)
+    }))
+    .filter((e) => e.score > 0);
+  scored.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+  return scored.slice(0, n).map((e) => e.path);
+}
+
+/**
+ * Stable hash of the inputs that fed into a summary, so the skill
+ * can decide whether to regenerate. Mirrors what the Rust set-summary
+ * subcommand stores under summary.inputHash.
+ */
+function summaryInputHash(readme, manifests, hotspots) {
+  const h = crypto.createHash('sha256');
+  h.update(readme);
+  h.update(JSON.stringify(manifests));
+  h.update(JSON.stringify(hotspots));
+  return 'sha256:' + h.digest('hex').slice(0, 16);
+}
+
+/**
+ * Extract the JSON object between `=== <name>_START ===` and
+ * `=== <name>_END ===` markers in the agent's output.
+ *
+ * Returns the parsed object, or null if either marker is missing or
+ * the inner text doesn't parse as JSON. Tolerates extra whitespace
+ * and surrounding agent commentary.
+ */
+function parseMarkers(agentOutput, name) {
+  if (typeof agentOutput !== 'string') return null;
+  const startMarker = `=== ${name}_START ===`;
+  const endMarker = `=== ${name}_END ===`;
+  const startIdx = agentOutput.indexOf(startMarker);
+  const endIdx = agentOutput.indexOf(endMarker);
+  if (startIdx < 0 || endIdx < 0 || endIdx <= startIdx) return null;
+  const inner = agentOutput.slice(startIdx + startMarker.length, endIdx).trim();
+  // Inner is usually fenced inside ```json ... ``` or just raw JSON.
+  // Strip code fences if present, then parse.
+  const stripped = inner
+    .replace(/^```(?:json)?\s*/i, '')
+    .replace(/\s*```\s*$/i, '')
+    .trim();
+  try { return JSON.parse(stripped); }
+  catch { return null; }
+}
+
+/**
+ * Build the summarizer prompt - the literal string sent as the Task
+ * `prompt` argument. Kept here so the command markdown stays compact.
+ */
+function buildSummarizerPrompt(repoPath, readme, manifests, hotspots) {
+  return [
+    `Generate a 3-depth summary for the repo at ${repoPath}.`,
+    '',
+    'Inputs:',
+    '```json',
+    JSON.stringify({ repoPath, readme, manifests, hotspots }, null, 2),
+    '```',
+    '',
+    'Return JSON between `=== SUMMARY_START ===` and `=== SUMMARY_END ===` markers as instructed in your system prompt.'
+  ].join('\n');
+}
+
+/**
+ * Build the weighter prompt for one batch of paths.
+ */
+function buildWeighterPrompt(repoPath, paths) {
+  return [
+    `Generate descriptors for the following files in ${repoPath}.`,
+    '',
+    'Inputs:',
+    '```json',
+    JSON.stringify({ repoPath, paths }, null, 2),
+    '```',
+    '',
+    'Return JSON between `=== DESCRIPTORS_START ===` and `=== DESCRIPTORS_END ===` markers as instructed in your system prompt.'
+  ].join('\n');
+}
+
+/**
+ * Split a list into chunks of `size`. Used to keep weighter Task
+ * calls bounded - one big Task with 500 paths would burn context;
+ * 30/batch keeps each call cheap and lets the orchestrator parallelize.
+ */
+function chunk(arr, size) {
+  const out = [];
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
+  return out;
+}
+
+module.exports = {
+  readReadme,
+  readManifests,
+  topHotspots,
+  topPaths,
+  summaryInputHash,
+  parseMarkers,
+  buildSummarizerPrompt,
+  buildWeighterPrompt,
+  chunk
+};

package/lib/repo-intel/index.js

@@ -0,0 +1,370 @@
+'use strict';
+
+/**
+ * Repo Intel - unified repository intelligence over agent-analyzer.
+ *
+ * One surface for the whole pipeline:
+ *   - lifecycle: init / update / status / load / exists  (was lib/repo-map)
+ *   - queries:   typed wrappers over the binary's query subcommands (queries.js)
+ *   - install:   binary availability checks
+ *
+ * The agent-analyzer binary is the engine and is auto-downloaded on first use.
+ * init/update run the binary, persist repo-intel.json (raw), convert to the
+ * repo-map.json view, and cache it. queries.* read the raw repo-intel.json.
+ *
+ * @module lib/repo-intel
+ */
+
+const fs = require('fs');
+const path = require('path');
+const cp = require('child_process');
+const { execFileSync } = cp;
+
+const installer = require('./installer');
+const cache = require('./cache');
+const updater = require('./updater');
+const converter = require('./converter');
+const queries = require('./queries');
+const binary = require('../binary');
+const { getStateDirPath } = require('../platform/state-dir');
+const { writeJsonAtomic } = require('../utils/atomic-write');
+
+const REPO_INTEL_FILENAME = 'repo-intel.json';
+
+function getIntelMapPath(basePath) {
+  return path.join(getStateDirPath(basePath), REPO_INTEL_FILENAME);
+}
+
+/**
+ * Initialize a new repo map (full scan).
+ * @param {string} basePath - Repository root path
+ * @param {Object} options - Options
+ * @param {boolean} options.force - Force rebuild even if map exists
+ * @returns {Promise<{success: boolean, map?: Object, error?: string}>}
+ */
+async function init(basePath, options = {}) {
+  const installed = await installer.checkInstalled();
+  if (!installed.found) {
+    return {
+      success: false,
+      error: 'agent-analyzer binary unavailable: ' + (installed.error || 'unknown error'),
+      installSuggestion: installer.getInstallInstructions()
+    };
+  }
+
+  const existing = cache.load(basePath);
+  if (existing && !options.force) {
+    return {
+      success: false,
+      error: 'Repo map already exists. Use --force to rebuild or update to refresh.',
+      existing: cache.getStatus(basePath)
+    };
+  }
+
+  const startTime = Date.now();
+
+  let intelJson;
+  try {
+    intelJson = await binary.runAnalyzerAsync(['repo-intel', 'init', basePath]);
+  } catch (e) {
+    return { success: false, error: 'agent-analyzer repo-intel init failed: ' + e.message };
+  }
+
+  let intel;
+  try {
+    intel = JSON.parse(intelJson);
+  } catch (e) {
+    return { success: false, error: 'Failed to parse repo-intel output: ' + e.message };
+  }
+
+  // Persist repo-intel.json for future incremental updates
+  const intelPath = getIntelMapPath(basePath);
+  try {
+    writeJsonAtomic(intelPath, intel);
+  } catch {
+    // Non-fatal: update() will fall back to full init
+  }
+
+  const map = converter.convertIntelToRepoMap(intel);
+  map.stats.scanDurationMs = Date.now() - startTime;
+  cache.save(basePath, map);
+
+  return {
+    success: true,
+    map,
+    summary: {
+      files: Object.keys(map.files).length,
+      symbols: map.stats.totalSymbols,
+      languages: map.project.languages,
+      duration: map.stats.scanDurationMs
+    }
+  };
+}
+
+/**
+ * Update an existing repo map (incremental via agent-analyzer).
+ * @param {string} basePath - Repository root path
+ * @param {Object} options - Options
+ * @param {boolean} options.full - Force full rebuild instead of incremental
+ * @returns {Promise<{success: boolean, summary?: Object, error?: string}>}
+ */
+async function update(basePath, options = {}) {
+  const installed = await installer.checkInstalled();
+  if (!installed.found) {
+    return {
+      success: false,
+      error: 'agent-analyzer binary unavailable: ' + (installed.error || 'unknown error'),
+      installSuggestion: installer.getInstallInstructions()
+    };
+  }
+
+  if (!cache.exists(basePath)) {
+    return { success: false, error: 'No repo map found. Run init first.' };
+  }
+
+  if (options.full) {
+    return init(basePath, { force: true });
+  }
+
+  const intelPath = getIntelMapPath(basePath);
+  if (!fs.existsSync(intelPath)) {
+    return init(basePath, { force: true });
+  }
+
+  const startTime = Date.now();
+
+  let intelJson;
+  try {
+    intelJson = await binary.runAnalyzerAsync([
+      'repo-intel', 'update',
+      '--map-file', intelPath,
+      basePath
+    ]);
+  } catch (e) {
+    return { success: false, error: 'agent-analyzer repo-intel update failed: ' + e.message };
+  }
+
+  let intel;
+  try {
+    intel = JSON.parse(intelJson);
+  } catch (e) {
+    return { success: false, error: 'Failed to parse repo-intel update output: ' + e.message };
+  }
+
+  try {
+    writeJsonAtomic(intelPath, intel);
+  } catch {
+    // Non-fatal
+  }
+
+  const map = converter.convertIntelToRepoMap(intel);
+  map.stats.scanDurationMs = Date.now() - startTime;
+  cache.save(basePath, map);
+
+  return {
+    success: true,
+    map,
+    summary: {
+      files: Object.keys(map.files).length,
+      symbols: map.stats.totalSymbols,
+      duration: map.stats.scanDurationMs
+    }
+  };
+}
+
+/**
+ * Get repo map status.
+ * @param {string} basePath - Repository root path
+ * @returns {{exists: boolean, status?: Object}}
+ */
+function status(basePath) {
+  const map = cache.load(basePath);
+  if (!map) {
+    return { exists: false };
+  }
+
+  const staleness = updater.checkStaleness(basePath, map);
+
+  let branch;
+  try {
+    branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: basePath, encoding: 'utf8' }).trim();
+  } catch {
+    // Non-fatal
+  }
+
+  return {
+    exists: true,
+    status: {
+      generated: map.generated,
+      updated: map.updated,
+      commit: map.git?.commit,
+      branch,
+      files: Object.keys(map.files).length,
+      symbols: map.stats?.totalSymbols || 0,
+      languages: map.project?.languages || [],
+      staleness
+    }
+  };
+}
+
+/**
+ * Load repo map (if exists).
+ * @param {string} basePath - Repository root path
+ * @returns {Object|null}
+ */
+function load(basePath) {
+  return cache.load(basePath);
+}
+
+/**
+ * Check if repo map exists.
+ * @param {string} basePath - Repository root path
+ * @returns {boolean}
+ */
+function exists(basePath) {
+  return cache.exists(basePath);
+}
+
+/**
+ * Load the RAW repo-intel.json (the binary's native output: fileActivity,
+ * coupling, symbols, importGraph, ...) — distinct from load(), which returns
+ * the converted repo-map.json view. enrich + any consumer needing raw git/AST
+ * structure uses this; queries.* also read raw under the hood.
+ * @param {string} basePath - Repository root path
+ * @returns {Object|null} parsed raw artifact, or null if absent/unreadable
+ */
+function loadRaw(basePath) {
+  const p = getIntelMapPath(basePath);
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+/**
+ * Spawn the analyzer with a JSON payload on stdin and capture stdout/stderr.
+ *
+ * Used by the post-init agent orchestration: the Haiku weighter and
+ * summarizer write JSON to stdout, the orchestrating skill captures it,
+ * then pipes it into the analyzer via this helper. Replaces what would
+ * otherwise be a tempfile dance.
+ *
+ * @param {string[]} args - subcommand args (must end with `--input -`)
+ * @param {string} stdinJson - the JSON payload to feed to stdin
+ * @returns {Promise<{stdout: string, stderr: string}>}
+ */
+async function runAnalyzerWithStdin(args, stdinJson) {
+  const binPath = await binary.ensureBinary();
+  return new Promise((resolve, reject) => {
+    const proc = cp.spawn(binPath, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true
+    });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
+    proc.stderr.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
+    proc.on('error', reject);
+    proc.on('close', (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr });
+      } else {
+        reject(new Error(
+          `agent-analyzer ${args.join(' ')} exited ${code}: ${stderr.trim() || stdout.trim()}`
+        ));
+      }
+    });
+    proc.stdin.write(stdinJson);
+    proc.stdin.end();
+  });
+}
+
+/**
+ * Merge per-file descriptors (from the `repo-intel-weighter` agent) into the
+ * cached artifact via the binary's set-descriptors subcommand. Partial updates
+ * are safe — entries the agent didn't refresh this run are preserved.
+ *
+ * @param {string} basePath - Repository root path
+ * @param {Object<string, string>} descriptors - {path: descriptor, ...}
+ * @returns {Promise<void>}
+ */
+async function applyDescriptors(basePath, descriptors) {
+  if (!descriptors || typeof descriptors !== 'object') {
+    throw new Error('applyDescriptors requires an object {path: descriptor}');
+  }
+  const mapFile = getIntelMapPath(basePath);
+  if (!fs.existsSync(mapFile)) {
+    throw new Error('No repo-intel artifact for ' + basePath + '; run init first.');
+  }
+  await runAnalyzerWithStdin(
+    ['repo-intel', 'set-descriptors', '--map-file', mapFile, '--input', '-'],
+    JSON.stringify(descriptors)
+  );
+}
+
+/**
+ * Set the 3-depth narrative summary (from the `repo-intel-summarizer` agent)
+ * via the binary's set-summary subcommand. Fully replaces any previous summary.
+ *
+ * @param {string} basePath - Repository root path
+ * @param {{depth1: string, depth3: string, depth10: string, inputHash: string}} summary
+ * @returns {Promise<void>}
+ */
+async function applySummary(basePath, summary) {
+  if (!summary || !summary.depth1 || !summary.depth3 || !summary.depth10) {
+    throw new Error('applySummary requires {depth1, depth3, depth10, inputHash}');
+  }
+  const mapFile = getIntelMapPath(basePath);
+  if (!fs.existsSync(mapFile)) {
+    throw new Error('No repo-intel artifact for ' + basePath + '; run init first.');
+  }
+  await runAnalyzerWithStdin(
+    ['repo-intel', 'set-summary', '--map-file', mapFile, '--input', '-'],
+    JSON.stringify(summary)
+  );
+}
+
+/**
+ * Check if agent-analyzer is available.
+ * @returns {Promise<{found: boolean, version?: string, tool: string}>}
+ */
+async function checkAstGrepInstalled() {
+  return installer.checkInstalled();
+}
+
+/**
+ * Get install instructions.
+ * @returns {string}
+ */
+function getInstallInstructions() {
+  return installer.getInstallInstructions();
+}
+
+module.exports = {
+  // Lifecycle (was lib/repo-map)
+  init,
+  update,
+  status,
+  load,
+  loadRaw,
+  exists,
+  applyDescriptors,
+  applySummary,
+  checkAstGrepInstalled,
+  getInstallInstructions,
+
+  // Typed query wrappers (read the cached repo-intel.json)
+  queries,
+
+  // Submodules for advanced use
+  installer,
+  cache,
+  updater,
+  converter
+};
+
+// Embedder (opt-in, separate agent-analyzer-embed binary). Lazy getter so
+// `require('repo-intel')` for query/lifecycle use never loads the embed binary
+// resolver or its download path — it only materializes when embed is accessed.
+Object.defineProperty(module.exports, 'embed', {
+  enumerable: true,
+  get() { return require('./embed'); }
+});

package/lib/repo-intel/installer.js

@@ -0,0 +1,78 @@
+'use strict';
+
+/**
+ * agent-analyzer binary availability check.
+ *
+ * Replaces the former ast-grep installer. The agent-analyzer binary is
+ * auto-downloaded by agent-core on first use - no manual install required.
+ *
+ * @module lib/repo-intel/installer
+ */
+
+const binary = require('../binary');
+
+/**
+ * Check if agent-analyzer is available (async). Downloads if missing.
+ * @returns {Promise<{found: boolean, version?: string, tool: string}>}
+ */
+async function checkInstalled() {
+  if (binary.isAvailable()) {
+    return { found: true, version: binary.getVersion(), tool: 'agent-analyzer' };
+  }
+  try {
+    await binary.ensureBinary();
+    return { found: true, version: binary.getVersion(), tool: 'agent-analyzer' };
+  } catch (e) {
+    return { found: false, error: e.message, tool: 'agent-analyzer' };
+  }
+}
+
+/**
+ * Check if agent-analyzer is available (sync). Downloads if missing.
+ * @returns {{found: boolean, version?: string, tool: string}}
+ */
+function checkInstalledSync() {
+  if (binary.isAvailable()) {
+    return { found: true, version: binary.getVersion(), tool: 'agent-analyzer' };
+  }
+  try {
+    binary.ensureBinarySync();
+    return { found: true, version: binary.getVersion(), tool: 'agent-analyzer' };
+  } catch (e) {
+    return { found: false, error: e.message, tool: 'agent-analyzer' };
+  }
+}
+
+/**
+ * Version check is handled by the binary module - always true when found.
+ * @returns {boolean}
+ */
+function meetsMinimumVersion() {
+  return true;
+}
+
+/**
+ * Get install instructions (binary is auto-downloaded, but here for compat).
+ * @returns {string}
+ */
+function getInstallInstructions() {
+  return 'agent-analyzer is downloaded automatically on first use from https://github.com/agent-sh/agent-analyzer/releases';
+}
+
+/**
+ * Get minimum version string.
+ * @returns {string}
+ */
+function getMinimumVersion() {
+  return '0.3.0';
+}
+
+module.exports = {
+  checkInstalled,
+  checkInstalledSync,
+  meetsMinimumVersion,
+  getInstallInstructions,
+  getMinimumVersion,
+  // Stub: runner.js references this but is no longer the scan path
+  getCommand: () => null
+};