chore: release v5.8.6 (#344)

* chore: release v5.8.6

* fix(repo-intel/queries): wrap errors with query context, add validation, add tests

Addresses six reviewer comments on PR #344:

1. Wrap runQuery's `JSON.parse` and `binary.runAnalyzer` exceptions so
   the failing query name + an output preview surface in the error
   message instead of bubbling raw `SyntaxError: Unexpected token`.
2. Pre-flight check for the cached repo-intel artifact via
   `fs.existsSync(mapFilePath)`. Throws a typed `RepoIntelMissingError`
   (with `.code = 'REPO_INTEL_MISSING'`) so callers can branch instead
   of parsing a string.
3. `communityHealth`: validate `id` is a non-negative integer. The old
   `String(undefined)` -> "undefined" would have made the binary
   complain about an invalid arg, with no useful error context.
4. `diffRisk`: validate the `files` argument shape and refuse calls
   where the joined `--files` argument exceeds 30 KB (the platform-safe
   cap, tightest on Windows). Better than letting `execFileSync` fail
   with E2BIG/ENAMETOOLONG that looks like a binary crash.
5. Export `RepoIntelMissingError` from the queries module so consumer
   plugins can write `if (err.code === 'REPO_INTEL_MISSING') ...`.
6. New test file `__tests__/repo-intel-queries.test.js` (20 tests):
   verifies argv construction for every flag-bearing query (existing +
   the 4 graph), the input-validation paths, and the three error
   wrappers (missing artifact, binary failure, non-JSON output incl.
   preview truncation). The binary itself is mocked via jest.mock so
   tests run hermetically.

* fix(@agentsys/lib): add ./repo-intel to package exports map

Cursor Bugbot caught: the new lib/repo-intel module wasn't in the
`exports` map of lib/package.json, so direct subpath imports
`require('@agentsys/lib/repo-intel')` would fail with
ERR_PACKAGE_PATH_NOT_EXPORTED. Top-level `require('@agentsys/lib').repoIntel`
worked but subpath imports (the pattern used elsewhere in the codebase
for cross-platform, collectors, enhance, etc.) didn't.

Adds two entries:
- ./repo-intel        -> ./repo-intel/index.js
- ./repo-intel/queries -> ./repo-intel/queries.js

Verified both subpath imports resolve cleanly.

Author: avifenesh

.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "name": "agentsys",
   "description": "19 specialized plugins for AI workflow automation - task orchestration, PR workflow, slop detection, code review, drift detection, enhancement analysis, documentation sync, unified static analysis, perf investigations, topic research, agent config linting, cross-tool AI consultation, structured AI debate, workflow pattern learning, codebase onboarding, and contributor guidance",
-  "version": "5.8.5",
+  "version": "5.8.6",
   "owner": {
     "name": "Avi Fenesh",
     "url": "https://github.com/avifenesh"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentsys",
-  "version": "5.8.5",
+  "version": "5.8.6",
   "description": "Professional-grade slash commands for Claude Code with cross-platform support",
   "keywords": [
     "workflow",

CHANGELOG.md

@@ -9,6 +9,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.8.6] - 2026-04-23
+
+### Added
+- **`@agentsys/lib`'s `repoIntel.queries` module** - typed wrappers over every `agent-analyzer repo-intel query <type>` subcommand (28 functions). Consumer plugins can now call `require('@agentsys/lib').repoIntel.queries.hotspots(cwd, { limit: 20 })` instead of constructing raw CLI argv themselves. Functions returned in JSON match the binary's output shape per query.
+- **4 new graph-derived query wrappers** for the analyzer-graph crate landed in agent-analyzer v0.4.0:
+  - `communities(cwd)` - lists Louvain-discovered file clusters (the natural feature areas, independent of directory layout)
+  - `boundaries(cwd, { limit })` - files bridging multiple communities by betweenness centrality (architectural seams - highest-leverage files for refactoring)
+  - `areaOf(cwd, file)` - which community a file belongs to
+  - `communityHealth(cwd, id)` - composite per-community roll-up (size, total/recent changes, bug-fix rate, AI ratio, stale-owner count)
+
+### Changed
+- **`ANALYZER_MIN_VERSION` bumped 0.3.0 -> 0.4.0** to match agent-analyzer v0.4.0 which adds the graph subcommands. Older binaries get auto-upgraded on first call by `lib/binary.ensureBinary()`.
+
 ## [5.8.5] - 2026-04-23
 
 ### Fixed

__tests__/repo-intel-queries.test.js

@@ -0,0 +1,245 @@
+/**
+ * Tests for lib/repo-intel/queries - typed wrappers over agent-analyzer
+ * `repo-intel query <type>` subcommands.
+ *
+ * Verifies argv construction (the contract with the binary), error wrapping
+ * (parse failures, missing artifact), and input validation. The binary
+ * itself is mocked so these run hermetically in CI.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Mock the binary module so runAnalyzer doesn't actually shell out.
+jest.mock('../lib/binary', () => ({
+  runAnalyzer: jest.fn(),
+}));
+
+const binary = require('../lib/binary');
+const queries = require('../lib/repo-intel/queries');
+
+describe('lib/repo-intel/queries', () => {
+  let tempDir;
+  let mapFilePath;
+
+  beforeEach(() => {
+    binary.runAnalyzer.mockReset();
+    // Build a fake repo with the state dir + map file the queries look for.
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'repo-intel-queries-test-'));
+    fs.mkdirSync(path.join(tempDir, '.claude'), { recursive: true });
+    mapFilePath = path.join(tempDir, '.claude', 'repo-intel.json');
+    fs.writeFileSync(mapFilePath, '{}');
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  // ─── Argv construction ────────────────────────────────────────────────────
+  // For each query, we mock the binary to return a known JSON value, call
+  // the wrapper, then assert the exact argv passed through. This is the
+  // load-bearing contract with the agent-analyzer CLI.
+
+  describe('argv construction', () => {
+    test('hotspots without limit', () => {
+      binary.runAnalyzer.mockReturnValue('[]');
+      queries.hotspots(tempDir);
+      const args = binary.runAnalyzer.mock.calls[0][0];
+      expect(args.slice(0, 3)).toEqual(['repo-intel', 'query', 'hotspots']);
+      expect(args).toContain('--map-file');
+      expect(args).toContain(mapFilePath);
+      expect(args).toContain(tempDir);
+      expect(args).not.toContain('--top');
+    });
+
+    test('hotspots with limit adds --top', () => {
+      binary.runAnalyzer.mockReturnValue('[]');
+      queries.hotspots(tempDir, { limit: 25 });
+      const args = binary.runAnalyzer.mock.calls[0][0];
+      expect(args).toContain('--top');
+      expect(args[args.indexOf('--top') + 1]).toBe('25');
+    });
+
+    test('coupling forwards file argument', () => {
+      binary.runAnalyzer.mockReturnValue('[]');
+      queries.coupling(tempDir, 'src/auth.js');
+      const args = binary.runAnalyzer.mock.calls[0][0];
+      expect(args.slice(0, 4)).toEqual(['repo-intel', 'query', 'coupling', 'src/auth.js']);
+    });
+
+    test('busFactor with adjustForAi adds --adjust-for-ai', () => {
+      binary.runAnalyzer.mockReturnValue('{}');
+      queries.busFactor(tempDir, { adjustForAi: true });
+      const args = binary.runAnalyzer.mock.calls[0][0];
+      expect(args).toContain('--adjust-for-ai');
+    });
+
+    test('testGaps with limit + minChanges adds both flags', () => {
+      binary.runAnalyzer.mockReturnValue('[]');
+      queries.testGaps(tempDir, { limit: 5, minChanges: 3 });
+      const args = binary.runAnalyzer.mock.calls[0][0];
+      expect(args[args.indexOf('--top') + 1]).toBe('5');
+      expect(args[args.indexOf('--min-changes') + 1]).toBe('3');
+    });
+
+    test('aiRatio with pathFilter adds --path-filter', () => {
+      binary.runAnalyzer.mockReturnValue('{}');
+      queries.aiRatio(tempDir, { pathFilter: 'src/' });
+      const args = binary.runAnalyzer.mock.calls[0][0];
+      expect(args[args.indexOf('--path-filter') + 1]).toBe('src/');
+    });
+
+    test('diffRisk joins files with comma', () => {
+      binary.runAnalyzer.mockReturnValue('[]');
+      queries.diffRisk(tempDir, ['a.js', 'b.js', 'c.js']);
+      const args = binary.runAnalyzer.mock.calls[0][0];
+      expect(args[args.indexOf('--files') + 1]).toBe('a.js,b.js,c.js');
+    });
+
+    test('dependents with file scope adds --file', () => {
+      binary.runAnalyzer.mockReturnValue('{}');
+      queries.dependents(tempDir, 'createUser', 'src/users.js');
+      const args = binary.runAnalyzer.mock.calls[0][0];
+      expect(args).toContain('createUser');
+      expect(args[args.indexOf('--file') + 1]).toBe('src/users.js');
+    });
+  });
+
+  // ─── Phase 5 graph queries ────────────────────────────────────────────────
+
+  describe('graph queries (Phase 5.1)', () => {
+    test('communities sends "communities" subcommand', () => {
+      binary.runAnalyzer.mockReturnValue('[]');
+      queries.communities(tempDir);
+      const args = binary.runAnalyzer.mock.calls[0][0];
+      expect(args.slice(0, 3)).toEqual(['repo-intel', 'query', 'communities']);
+    });
+
+    test('boundaries with limit adds --top', () => {
+      binary.runAnalyzer.mockReturnValue('[]');
+      queries.boundaries(tempDir, { limit: 8 });
+      const args = binary.runAnalyzer.mock.calls[0][0];
+      expect(args.slice(0, 3)).toEqual(['repo-intel', 'query', 'boundaries']);
+      expect(args[args.indexOf('--top') + 1]).toBe('8');
+    });
+
+    test('areaOf forwards file argument', () => {
+      binary.runAnalyzer.mockReturnValue('{}');
+      queries.areaOf(tempDir, 'src/foo.js');
+      const args = binary.runAnalyzer.mock.calls[0][0];
+      expect(args.slice(0, 4)).toEqual(['repo-intel', 'query', 'area-of', 'src/foo.js']);
+    });
+
+    test('communityHealth forwards id as string', () => {
+      binary.runAnalyzer.mockReturnValue('{}');
+      queries.communityHealth(tempDir, 7);
+      const args = binary.runAnalyzer.mock.calls[0][0];
+      expect(args.slice(0, 4)).toEqual(['repo-intel', 'query', 'community-health', '7']);
+    });
+  });
+
+  // ─── Input validation ─────────────────────────────────────────────────────
+
+  describe('input validation', () => {
+    test('communityHealth rejects non-integer id', () => {
+      expect(() => queries.communityHealth(tempDir, 'foo')).toThrow(TypeError);
+      expect(() => queries.communityHealth(tempDir, null)).toThrow(TypeError);
+      expect(() => queries.communityHealth(tempDir, 1.5)).toThrow(TypeError);
+      expect(() => queries.communityHealth(tempDir, -1)).toThrow(TypeError);
+      expect(binary.runAnalyzer).not.toHaveBeenCalled();
+    });
+
+    test('diffRisk rejects non-array files', () => {
+      expect(() => queries.diffRisk(tempDir, 'a.js')).toThrow(TypeError);
+      expect(() => queries.diffRisk(tempDir, [1, 2, 3])).toThrow(TypeError);
+      expect(binary.runAnalyzer).not.toHaveBeenCalled();
+    });
+
+    test('diffRisk rejects oversized file argument', () => {
+      // 1000 paths × 50 chars each = 50000 chars, exceeds 30000 cap.
+      const huge = Array.from({ length: 1000 }, (_, i) => `path/that/is/about/fifty-chars-long/file${i}.js`);
+      expect(() => queries.diffRisk(tempDir, huge)).toThrow(RangeError);
+      expect(binary.runAnalyzer).not.toHaveBeenCalled();
+    });
+
+    test('diffRisk accepts a normal-sized file argument', () => {
+      binary.runAnalyzer.mockReturnValue('[]');
+      queries.diffRisk(tempDir, ['a.js', 'b.js']);
+      expect(binary.runAnalyzer).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  // ─── Error wrapping ───────────────────────────────────────────────────────
+
+  describe('error wrapping', () => {
+    test('throws RepoIntelMissingError when artifact is absent', () => {
+      // Use a fresh dir with no .claude/repo-intel.json.
+      const emptyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'repo-intel-empty-'));
+      try {
+        let caught;
+        try {
+          queries.hotspots(emptyDir);
+        } catch (err) {
+          caught = err;
+        }
+        expect(caught).toBeInstanceOf(queries.RepoIntelMissingError);
+        expect(caught.code).toBe('REPO_INTEL_MISSING');
+        expect(caught.mapFile).toContain('repo-intel.json');
+        expect(binary.runAnalyzer).not.toHaveBeenCalled();
+      } finally {
+        fs.rmSync(emptyDir, { recursive: true, force: true });
+      }
+    });
+
+    test('wraps binary failure with query context', () => {
+      binary.runAnalyzer.mockImplementation(() => {
+        throw new Error('binary blew up');
+      });
+      let caught;
+      try {
+        queries.bugspots(tempDir, { limit: 5 });
+      } catch (err) {
+        caught = err;
+      }
+      expect(caught).toBeInstanceOf(Error);
+      expect(caught.message).toContain('repo-intel query failed');
+      expect(caught.message).toContain('bugspots');
+      expect(caught.message).toContain('binary blew up');
+      expect(caught.cause).toBeDefined();
+    });
+
+    test('wraps non-JSON output with preview', () => {
+      binary.runAnalyzer.mockReturnValue('not actually json');
+      let caught;
+      try {
+        queries.health(tempDir);
+      } catch (err) {
+        caught = err;
+      }
+      expect(caught).toBeInstanceOf(Error);
+      expect(caught.message).toContain('non-JSON output');
+      expect(caught.message).toContain('health');
+      expect(caught.message).toContain('not actually json');
+    });
+
+    test('non-JSON output preview is truncated', () => {
+      // 500 chars - should be truncated to 200 in the message.
+      const big = 'x'.repeat(500);
+      binary.runAnalyzer.mockReturnValue(big);
+      let caught;
+      try {
+        queries.health(tempDir);
+      } catch (err) {
+        caught = err;
+      }
+      // The message contains exactly 200 x's, not 500.
+      const xCount = (caught.message.match(/x/g) || []).length;
+      expect(xCount).toBe(200);
+    });
+  });
+});

lib/binary/version.js

@@ -1,7 +1,7 @@
 'use strict';
 
 // Minimum binary version required by this version of agent-core
-const ANALYZER_MIN_VERSION = '0.3.0';
+const ANALYZER_MIN_VERSION = '0.4.0';
 
 // Binary name
 const BINARY_NAME = 'agent-analyzer';

lib/index.js

@@ -30,6 +30,7 @@ const perf = require('./perf');
 const collectors = require('./collectors');
 const discoveryModule = require('./discovery');
 const binary = require('./binary');
+const repoIntel = require('./repo-intel');
 
 /**
  * Platform detection and verification utilities
@@ -255,6 +256,7 @@ module.exports = {
   collectors,
   discovery,
   binary,
+  repoIntel,
 
   // Direct module access for backward compatibility
   detectPlatform,

lib/package.json

@@ -13,6 +13,8 @@
     "./discovery": "./discovery/index.js",
     "./enhance": "./enhance/index.js",
     "./perf": "./perf/index.js",
+    "./repo-intel": "./repo-intel/index.js",
+    "./repo-intel/queries": "./repo-intel/queries.js",
     "./repo-map": "./repo-map/index.js",
     "./collectors/codebase": "./collectors/codebase.js",
     "./collectors/docs-patterns": "./collectors/docs-patterns.js",

lib/repo-intel/index.js

@@ -0,0 +1,21 @@
+/**
+ * Repo intel module - typed wrappers over agent-analyzer's repo-intel
+ * subcommands. Consumers can import via:
+ *
+ *   const { repoIntel } = require('@agentsys/lib');
+ *   const hot = repoIntel.queries.hotspots(cwd, { limit: 20 });
+ *   const communities = repoIntel.queries.communities(cwd);
+ *
+ * The Rust binary is downloaded lazily on first call by lib/binary; this
+ * module just constructs the right argv and parses the JSON output.
+ *
+ * @module lib/repo-intel
+ */
+
+'use strict';
+
+const queries = require('./queries');
+
+module.exports = {
+  queries,
+};