sigmap 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -6,6 +6,54 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [2.4.0] — 2026-04-05
+
+### Added
+- **`packages/core/`** — new `sigmap-core` package exposing a stable programmatic API: `{ extract, rank, buildSigIndex, scan, score }`. Third-party tools can now `require('sigmap')` and use all extraction/retrieval/security/health APIs without spawning a CLI process.
+- **`packages/cli/`** — new `sigmap-cli` thin wrapper that exposes `{ CLI_ENTRY, run }` for programmatic CLI invocation and forward-compat with the v3.0 adapter architecture.
+- **`packages/core/README.md`** — full programmatic API reference with usage examples for all five exported functions.
+- **`exports` field in `package.json`** — `require('sigmap')` resolves to `packages/core/index.js`; `require('sigmap/cli')` resolves to `packages/cli/index.js`.
+- **`test/integration/core-api.test.js`** — 15 integration tests covering: all exports present, `extract` for JS/TS/Python, file-path extension detection, unknown language returns `[]`, never throws on bad input, `rank` with empty map, `rank` sorted shape, `scan` clean/redact, `score` shape, `buildSigIndex` returns Map, CLI `--version` backward compat, CLI `--help` no crash.
+
+### Changed
+- `package.json` `"version"` bumped to `2.4.0`.
+- `package.json` `"files"` — added `"packages/"` so `sigmap-core` and `sigmap-cli` are published with the root package.
+- `gen-context.js` `VERSION` constant bumped to `2.4.0`.
+- `src/mcp/server.js` `SERVER_INFO.version` bumped to `2.4.0`.
+
+### Validation gate
+- 21/21 extractor unit tests passed
+- 21/21 integration suites passed (0 failures, including new `core-api.test.js`)
+- `node gen-context.js --version` → `2.4.0`
+- `node -e "const { extract } = require('.'); console.log(extract('function hello(){}', 'javascript').length > 0 ? 'OK' : 'FAIL')"` → `OK`
+- `require('sigmap')` works from any directory
+
+---
+
+## [2.3.0] — 2026-04-07
+
+### Added
+- **Query-aware retrieval** — `src/retrieval/tokenizer.js` and `src/retrieval/ranker.js`: zero-dependency relevance ranker that scores every file against a free-text query by exact token, symbol, prefix, path, and recency signals.
+- **`--query "<text>"` CLI flag** — ranks all context files by relevance and prints a scored table (Rank | File | Score | Sigs | Tokens) plus the top-3 signature blocks; `--query "<text>" --json` for machine-readable output; `--query "<text>" --top <n>` to limit result set.
+- **`query_context` MCP tool** — 8th MCP tool; accepts `{ query: string, topK?: number }` and returns the same ranked table as the `--query` CLI flag; live within any running MCP session.
+- **Retrieval config** — `config.retrieval.topK` (default 10) and `config.retrieval.recencyBoost` (default 1.5×) added to `src/config/defaults.js`.
+- **`test/integration/retrieval.test.js`** — 23 integration tests covering tokenizer unit tests, ranker sorting/scoring/topK/empty-query, `formatRankTable`, `formatRankJSON`, CLI `--query` flags, and MCP `query_context`.
+
+### Changed
+- `src/mcp/server.js` version bumped to `2.3.0`.
+- `test/integration/mcp-server.test.js` and `mcp-v14.test.js` updated to assert 8 tools.
+- `test/integration/analyze.test.js` version assertion updated to `2.3.0`.
+
+### Validation gate
+- 21/21 extractor unit tests passed
+- 20/20 integration suites passed (0 failures)
+- `node gen-context.js --version` → `2.3.0`
+- `node gen-context.js --query "python extractor"` → `src/extractors/python.js` in top-3
+- `node gen-context.js --query "fix secret scanning" --json` → valid JSON
+- MCP `tools/list` → 8 tools including `query_context`
+
+---
+
 ## [2.2.0] — 2026-04-06
 
 ### Added

package/README.md

@@ -11,7 +11,7 @@
 
 <!-- Status -->
 [![npm version](https://img.shields.io/npm/v/sigmap?color=7c6af7&label=latest&logo=npm)](https://www.npmjs.com/package/sigmap)
-[![Tests](https://img.shields.io/badge/tests-262%20passing-22c55e)](https://github.com/manojmallick/sigmap/tree/main/test)
+[![Tests](https://img.shields.io/badge/tests-325%20passing-22c55e)](https://github.com/manojmallick/sigmap/tree/main/test)
 [![Zero deps](https://img.shields.io/badge/dependencies-zero-22c55e)](package.json)
 [![Last commit](https://img.shields.io/github/last-commit/manojmallick/sigmap?color=7c6af7)](https://github.com/manojmallick/sigmap/commits/main)
 
@@ -41,7 +41,7 @@
 | [VS Code extension](#-vs-code-extension) | Status bar, stale alerts, commands |
 | [Languages supported](#-languages-supported) | 21 languages |
 | [Context strategies](#-context-strategies) | full / per-module / hot-cold |
-| [MCP server](#-mcp-server) | 7 on-demand tools |
+| [MCP server](#-mcp-server) | 8 on-demand tools |
 | [CLI reference](#-cli-reference) | All flags |
 | [Configuration](#-configuration) | Config file + .contextignore |
 | [Observability](#-observability) | Health score, reports, CI |
@@ -86,20 +86,18 @@ AI agent session starts with full context
 
 ---
 
-## 🆕 What's new in 2.0
+## 🆕 What's new in 2.3
 
 | Feature | Description |
 |---|---|
-| **Enriched signatures** | Return types, type hints, and schema field collapse (Python `@dataclass` / `BaseModel`) |
-| **Dependency map** | Compact import dependency section at the top of output (~50–100 extra tokens) |
-| **TODO/FIXME section** | Auto-harvested TODO/FIXME/HACK/XXX comments (max 20 entries) |
-| **Recent changes section** | Git-based recent changes summary in output |
-| **Test coverage markers** | Per-function `✓`/`✗` hints by scanning test directories |
-| **Structural diff mode** | `--diff <base-ref>` writes a signature-level diff section |
-| **Impact radius hints** | Reverse dependency annotations (used by: ...) |
-| **New helper extractors** | `deps.js`, `todos.js`, `coverage.js`, `prdiff.js` |
+| **`--query "<text>"` CLI** | Rank all context files by relevance to a free-text query — scored table + top-3 signature blocks |
+| **`--query --json`** | Machine-readable ranked results (`{ query, results[], totalResults }`) |
+| **`--query --top <n>`** | Limit results (default 10, configurable via `retrieval.topK`) |
+| **`query_context` MCP tool** | 8th MCP tool — `{ query, topK? }` returns ranked file list, usable live in any MCP session |
+| **`--analyze` / `--diagnose-extractors`** | Per-file breakdown of sigs/tokens/extractor/coverage; self-tests all 21 extractors (v2.2) |
+| **`--benchmark` / `--eval`** | Measure hit@5 and MRR retrieval quality against a JSONL task file (v2.1) |
 
-Several v2 enhancements (deps map, TODOs, recent changes) are enabled by default. All v2 sections can be tuned or disabled via `gen-context.config.json`.
+> **Previous v2.0 additions:** enriched signatures, dependency map, TODO/FIXME section, test coverage markers, structural diff mode, impact radius hints. See [CHANGELOG.md](CHANGELOG.md) for the full history.
 
 ---
 
@@ -258,7 +256,7 @@ Recently committed files are **hot** (auto-injected). Everything else is **cold*
 
 ## 🔌 MCP server
 
-> Introduced in v0.3, expanded to 7 tools through v1.4.
+> Introduced in v0.3, expanded to 8 tools through v2.3.
 
 Start the MCP server on stdio:
 
@@ -277,6 +275,7 @@ node gen-context.js --mcp
 | `list_modules` | — | Token-count table of all top-level module directories |
 | `create_checkpoint` | `{ summary: string }` | Write a session checkpoint to `.context/` |
 | `get_routing` | — | Full model routing table |
+| `query_context` | `{ query: string, topK?: number }` | Files ranked by relevance to the query (v2.3) |
 
 Reads files on every call — no stale state, no restart needed.
 
@@ -296,6 +295,19 @@ node gen-context.js --diff                    Generate context for git-changed f
 node gen-context.js --diff --staged           Staged files only (pre-commit check)
 node gen-context.js --mcp                     Start MCP server on stdio
 
+node gen-context.js --query "<text>"          Rank files by relevance to a query
+node gen-context.js --query "<text>" --json   Ranked results as JSON
+node gen-context.js --query "<text>" --top <n> Limit results to top N files (default 10)
+
+node gen-context.js --analyze                 Per-file breakdown (sigs / tokens / extractor / coverage)
+node gen-context.js --analyze --json          Analysis as JSON
+node gen-context.js --analyze --slow          Include extraction timing per file
+node gen-context.js --diagnose-extractors     Self-test all 21 extractors against fixtures
+
+node gen-context.js --benchmark               Run retrieval quality benchmark (hit@5 / MRR)
+node gen-context.js --benchmark --json        Benchmark results as JSON
+node gen-context.js --eval                    Alias for --benchmark
+
 node gen-context.js --report                  Token reduction stats
 node gen-context.js --report --json           Structured JSON report (exits 1 if over budget)
 node gen-context.js --report --history        Usage log summary
@@ -435,6 +447,31 @@ node gen-context.js --format cache
 
 ---
 
+## 📦 Programmatic API (v2.4+)
+
+Use SigMap as a library — no CLI subprocess needed:
+
+```js
+const { extract, rank, buildSigIndex, scan, score } = require('sigmap');
+
+// Extract signatures from source code
+const sigs = extract('function hello() {}', 'javascript');
+
+// Build an index and rank files by query
+const index = buildSigIndex('/path/to/project');
+const results = rank('authentication middleware', index);
+
+// Scan signatures for secrets before storing
+const { safe, redacted } = scan(sigs, 'src/config.ts');
+
+// Get a composite health score for a project
+const health = score('/path/to/project');
+```
+
+📖 Full API reference: [packages/core/README.md](packages/core/README.md)
+
+---
+
 ## 🧪 Testing
 
 ```bash
@@ -464,7 +501,7 @@ grep "require(" gen-context.js | grep -v "^.*//.*require"
 
 # Gate 3 — MCP server responds correctly
 echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node gen-context.js --mcp
-# Expected: valid JSON with 7 tools
+# Expected: valid JSON with 8 tools
 
 # Gate 4 — npm artifact is clean
 npm pack --dry-run
@@ -481,9 +518,16 @@ sigmap/
 ├── gen-context.js               ← PRIMARY ENTRY POINT — single file, zero deps
 ├── gen-project-map.js           ← import graph, class hierarchy, route table
 │
+├── packages/
+│   ├── core/                    ← programmatic API — require('sigmap') (v2.4)
+│   │   └── index.js             ← extract, rank, buildSigIndex, scan, score
+│   └── cli/                     ← thin CLI wrapper / v3 compat shim (v2.4)
+│
 ├── src/
 │   ├── extractors/              ← 21 language extractors (one file per language)
-│   ├── mcp/                     ← MCP stdio server — 7 tools
+│   ├── retrieval/               ← query-aware ranker + tokenizer (v2.3)
+│   ├── eval/                    ← benchmark runner + scorer (v2.1), analyzer (v2.2)
+│   ├── mcp/                     ← MCP stdio server — 8 tools
 │   ├── security/                ← secret scanner — 10 patterns
 │   ├── routing/                 ← model routing hints
 │   ├── tracking/                ← NDJSON usage logger
@@ -499,7 +543,7 @@ sigmap/
 │   ├── fixtures/                ← one source file per language
 │   ├── expected/                ← expected extractor output
 │   ├── run.js                   ← zero-dep test runner
-│   └── integration/             ← 17 integration test files (241 tests)
+│   └── integration/             ← 20 integration test files (304 tests)
 │
 ├── docs/                        ← documentation site (GitHub Pages)
 │   ├── index.html               ← homepage

package/gen-context.js

@@ -2879,7 +2879,23 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
     ].join('\n');
   }
   
-  module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules };
+  function queryContext(args, cwd) {
+    if (!args || !args.query) return 'Missing required argument: query';
+    const contextPath = path.join(cwd, CONTEXT_FILE);
+    if (!fs.existsSync(contextPath)) return 'No context file found. Run: node gen-context.js';
+    try {
+      const { rank, buildSigIndex, formatRankTable } = __require('./src/retrieval/ranker');
+      const index = buildSigIndex(cwd);
+      if (index.size === 0) return 'No signatures indexed. Run: node gen-context.js';
+      const topK = Math.min(Math.max(1, parseInt(args.topK, 10) || 10), 25);
+      const results = rank(args.query, index, { topK });
+      return formatRankTable(results, args.query);
+    } catch (err) {
+      return `_query_context failed: ${err.message}_`;
+    }
+  }
+  
+  module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext };
 };
 
 // ── ./src/mcp/server ──
@@ -2899,7 +2915,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
   
   const readline = require('readline');
   const { TOOLS } = __require('./src/mcp/tools');
-  const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules } = __require('./src/mcp/handlers');
+  const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext } = __require('./src/mcp/handlers');
   
   const SERVER_INFO = {
     name: 'sigmap',
@@ -2958,6 +2974,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
         else if (name === 'get_routing') text = getRouting(args, cwd);
         else if (name === 'explain_file') text = explainFile(args, cwd);
         else if (name === 'list_modules') text = listModules(args, cwd);
+        else if (name === 'query_context') text = queryContext(args, cwd);
         else {
           respondError(id, -32601, `Unknown tool: ${name}`);
           return;
@@ -3137,6 +3154,30 @@ __factories["./src/mcp/tools"] = function(module, exports) {
         required: [],
       },
     },
+    {
+      name: 'query_context',
+      description:
+        'Rank and return the most relevant files for a specific task or question. ' +
+        'Uses keyword + symbol + path scoring to surface only the top-K files relevant ' +
+        'to the query — much cheaper than reading all context. ' +
+        'Returns ranked file list with signatures and relevance scores.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description:
+              'Natural language task description or keyword(s) to rank files against. ' +
+              'E.g. "add a new language extractor", "fix secret scanning", "auth module".',
+          },
+          topK: {
+            type: 'number',
+            description: 'Maximum number of files to return (default: 10, max: 25).',
+          },
+        },
+        required: ['query'],
+      },
+    },
   ];
   
   module.exports = { TOOLS };
@@ -3570,6 +3611,120 @@ __factories["./src/tracking/logger"] = function(module, exports) {
   
 };
 
+// ── ./src/retrieval/tokenizer ──
+__factories["./src/retrieval/tokenizer"] = function(module, exports) {
+  'use strict';
+  const STOP_WORDS = new Set([
+    'the', 'a', 'an', 'in', 'of', 'to', 'for', 'and', 'or', 'is', 'are',
+    'that', 'this', 'it', 'with', 'from', 'by', 'be', 'as', 'on', 'at',
+    'do', 'not', 'use', 'get', 'set', 'up', 'if', 'no', 'so', 'we',
+  ]);
+  function tokenize(text, opts) {
+    if (!text || typeof text !== 'string') return [];
+    const removeStop = opts && opts.removeStopWords === false ? false : true;
+    const minLen = (opts && opts.minLength) || 2;
+    const tokens = text
+      .replace(/\.\w{1,6}(?=\s|\/|$)/g, ' ')
+      .replace(/([a-z])([A-Z])/g, '$1 $2')
+      .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+      .replace(/[_\-\.\/]/g, ' ')
+      .replace(/[^\w\s]/g, ' ')
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((t) => t.length >= minLen);
+    if (!removeStop) return [...new Set(tokens)];
+    return [...new Set(tokens.filter((t) => !STOP_WORDS.has(t)))];
+  }
+  module.exports = { tokenize, STOP_WORDS };
+};
+
+// ── ./src/retrieval/ranker ──
+__factories["./src/retrieval/ranker"] = function(module, exports) {
+  'use strict';
+  const { tokenize, STOP_WORDS } = __require('./src/retrieval/tokenizer');
+  const DEFAULT_WEIGHTS = {
+    exactToken: 1.0, symbolMatch: 0.5, prefixMatch: 0.3, pathMatch: 0.8, recencyBoost: 1.5,
+  };
+  function scoreFile(filePath, sigs, queryTokens, weights) {
+    if (!sigs || sigs.length === 0) return 0;
+    const w = weights || DEFAULT_WEIGHTS;
+    const sigTokenSet = new Set(tokenize(sigs.join(' ')));
+    const pathTokenSet = new Set(tokenize(filePath));
+    let score = 0;
+    for (const qt of queryTokens) {
+      if (STOP_WORDS.has(qt)) continue;
+      if (sigTokenSet.has(qt)) {
+        score += w.exactToken;
+        if (sigs.some((sig) => tokenize(sig.replace(/[^a-zA-Z0-9_\s]/g, ' ')).includes(qt))) score += w.symbolMatch;
+      }
+      if (qt.length >= 4) {
+        for (const st of sigTokenSet) {
+          if (st !== qt && st.startsWith(qt)) { score += w.prefixMatch; break; }
+        }
+      }
+      if (pathTokenSet.has(qt)) score += w.pathMatch;
+    }
+    return score;
+  }
+  function rank(query, sigIndex, opts) {
+    if (!query || typeof query !== 'string') return [];
+    if (!sigIndex || !(sigIndex instanceof Map) || sigIndex.size === 0) return [];
+    const topK = (opts && opts.topK) || 10;
+    const recencyMultiplier = (opts && opts.recencyBoost) || DEFAULT_WEIGHTS.recencyBoost;
+    const recencySet = (opts && opts.recencySet) || null;
+    const weights = (opts && opts.weights) ? Object.assign({}, DEFAULT_WEIGHTS, opts.weights) : DEFAULT_WEIGHTS;
+    const queryTokens = tokenize(query);
+    if (queryTokens.length === 0) {
+      const all = [];
+      for (const [file, sigs] of sigIndex.entries()) all.push({ file, score: sigs.length, sigs, tokens: Math.ceil(sigs.join('\n').length / 4) });
+      all.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
+      return all.slice(0, topK);
+    }
+    const scored = [];
+    for (const [file, sigs] of sigIndex.entries()) {
+      let score = scoreFile(file, sigs, queryTokens, weights);
+      if (recencySet && recencySet.has(file) && score > 0) score *= recencyMultiplier;
+      scored.push({ file, score, sigs, tokens: Math.ceil(sigs.join('\n').length / 4) });
+    }
+    scored.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
+    return scored.slice(0, topK);
+  }
+  function buildSigIndex(cwd) {
+    const fs = require('fs'); const path = require('path');
+    const contextPath = path.join(cwd, '.github', 'copilot-instructions.md');
+    const index = new Map();
+    if (!fs.existsSync(contextPath)) return index;
+    const content = fs.readFileSync(contextPath, 'utf8');
+    const lines = content.split('\n');
+    let currentFile = null; let inBlock = false; let sigs = [];
+    for (const line of lines) {
+      const hm = line.match(/^###\s+(\S+)\s*$/);
+      if (hm) { if (currentFile !== null) index.set(currentFile, sigs); currentFile = hm[1]; sigs = []; inBlock = false; continue; }
+      if (line.startsWith('```')) { inBlock = !inBlock; continue; }
+      if (inBlock && currentFile && line.trim()) sigs.push(line.trim());
+    }
+    if (currentFile !== null) index.set(currentFile, sigs);
+    return index;
+  }
+  function formatRankTable(results, query) {
+    if (!results || results.length === 0) return `No matching files found for query: "${query}"\n`;
+    const lines = [`## Query: ${query}`, '', '| Rank | File | Score | Sigs | Tokens |', '|------|------|-------|------|--------|',
+      ...results.map((r, i) => `| ${i + 1} | ${r.file} | ${r.score.toFixed(2)} | ${r.sigs.length} | ${r.tokens} |`), ''];
+    for (const r of results.slice(0, 3)) {
+      if (r.sigs.length > 0) {
+        lines.push(`### ${r.file}`, '```', ...r.sigs.slice(0, 10));
+        if (r.sigs.length > 10) lines.push(`... (${r.sigs.length - 10} more)`);
+        lines.push('```', '');
+      }
+    }
+    return lines.join('\n');
+  }
+  function formatRankJSON(results, query) {
+    return { query, results: (results || []).map((r, i) => ({ rank: i + 1, file: r.file, score: r.score, sigs: r.sigs, tokens: r.tokens })), totalResults: (results || []).length };
+  }
+  module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS };
+};
+
 // ── ./src/eval/scorer ──
 __factories["./src/eval/scorer"] = function(module, exports) {
   'use strict';
@@ -3936,7 +4091,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '2.2.0';
+const VERSION = '2.4.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -5149,6 +5304,9 @@ Usage:
   node gen-context.js --analyze --json                  Breakdown as JSON
   node gen-context.js --analyze --slow                  Re-time each extractor; flag files >50ms
   node gen-context.js --diagnose-extractors             Run all 21 extractors vs fixtures; show pass/fail + diff
+  node gen-context.js --query "<text>"                  Rank files by relevance to a query
+  node gen-context.js --query "<text>" --json           Ranked results as JSON
+  node gen-context.js --query "<text>" --top <n>        Limit results to top N files (default 10)
   node gen-context.js --init                            Write example config + .contextignore scaffold
   node gen-context.js --help                            Show this message
   node gen-context.js --version                         Show version
@@ -5435,6 +5593,38 @@ function main() {
     }
   }
 
+  if (args.includes('--query')) {
+    try {
+      const qIdx = args.indexOf('--query');
+      const query = (args[qIdx + 1] || '').trim();
+      if (!query || query.startsWith('--')) {
+        console.error('[sigmap] --query requires a search string');
+        console.error('  Example: node gen-context.js --query "add a new language extractor"');
+        process.exit(1);
+      }
+      const { rank, buildSigIndex, formatRankTable, formatRankJSON } = requireSourceOrBundled('./src/retrieval/ranker');
+      const index = buildSigIndex(cwd);
+      if (index.size === 0) {
+        console.error('[sigmap] no context file found. Run: node gen-context.js');
+        process.exit(1);
+      }
+      const topIdx = args.indexOf('--top');
+      const topK = topIdx >= 0 ? Math.min(Math.max(1, parseInt(args[topIdx + 1], 10) || 10), 25)
+                               : ((config && config.retrieval && config.retrieval.topK) || 10);
+      const recencyBoost = (config && config.retrieval && config.retrieval.recencyBoost) || 1.5;
+      const results = rank(query, index, { topK, recencyBoost });
+      if (args.includes('--json')) {
+        process.stdout.write(JSON.stringify(formatRankJSON(results, query)) + '\n');
+      } else {
+        process.stdout.write(formatRankTable(results, query));
+      }
+    } catch (err) {
+      console.error(`[sigmap] query error: ${err.message}`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
   if (args.includes('--report')) {
     if (args.includes('--history')) {
       try {

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "sigmap",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Zero-dependency AI context engine — 97% token reduction. No npm install. Runs on Node 18+.",
   "main": "gen-context.js",
+  "exports": {
+    ".": "./packages/core/index.js",
+    "./cli": "./packages/cli/index.js",
+    "./core": "./packages/core/index.js"
+  },
   "bin": {
     "sigmap": "./gen-context.js",
     "gen-context": "./gen-context.js",
@@ -26,6 +31,7 @@
     "gen-context.js",
     "gen-project-map.js",
     "src/",
+    "packages/",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",

package/packages/cli/index.js

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * sigmap-cli — thin CLI wrapper around sigmap-core.
+ *
+ * This module is required by the root gen-context.js entry point.
+ * All --flag handling lives here; business logic lives in src/ or packages/core.
+ *
+ * NOTE: This file intentionally does NOT duplicate business logic.
+ * It re-exports the entry-point function from gen-context.js so that
+ * `require('sigmap-cli')` can be used by tooling that wraps SigMap.
+ *
+ * In v2.4 the root gen-context.js is kept fully intact for backward compat.
+ * packages/cli is a forward-compat shim for the v3.0 adapter architecture.
+ */
+
+const path = require('path');
+
+/**
+ * The CLI entry point path.
+ * External tools can use this to spawn the CLI as a child process.
+ */
+const CLI_ENTRY = path.resolve(__dirname, '..', '..', 'gen-context.js');
+
+/**
+ * Run the SigMap CLI programmatically with the given argv array.
+ *
+ * @param {string[]} [argv]  - Arguments to pass (default: process.argv)
+ * @param {string}   [cwd]   - Working directory (default: process.cwd())
+ * @returns {void}
+ *
+ * @example
+ *   const { run } = require('sigmap-cli');
+ *   run(['--report'], '/path/to/project');
+ */
+function run(argv, cwd) {
+  const origArgv = process.argv;
+  const origCwd = process.cwd();
+
+  if (cwd) {
+    try { process.chdir(cwd); } catch (_) {}
+  }
+
+  if (argv) {
+    process.argv = [process.argv[0], CLI_ENTRY, ...argv];
+  }
+
+  try {
+    require(CLI_ENTRY);
+  } finally {
+    process.argv = origArgv;
+    if (cwd) {
+      try { process.chdir(origCwd); } catch (_) {}
+    }
+  }
+}
+
+module.exports = {
+  /** Absolute path to the gen-context.js entry point */
+  CLI_ENTRY,
+  /** Run the SigMap CLI programmatically */
+  run,
+};

package/packages/cli/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "sigmap-cli",
+  "version": "2.4.0",
+  "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
+  "main": "index.js",
+  "keywords": [
+    "sigmap",
+    "cli",
+    "ai-context",
+    "code-signatures"
+  ],
+  "author": {
+    "name": "Manoj Mallick",
+    "url": "https://github.com/manojmallick"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/manojmallick/sigmap.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://manojmallick.github.io/sigmap/",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}