projscan 0.6.0 → 0.8.0

package/dist/core/searchIndex.js

@@ -0,0 +1,268 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Lightweight BM25-ranked inverted index over source files.
+ *
+ * We index three fields per file with different weights:
+ *   - content (body tokens, BM25 baseline)
+ *   - symbols (export names — most informative for code search)
+ *   - path (file path tokens)
+ *
+ * Scoring:
+ *   score(file, query) = BM25(content) + 2.0 * hits(symbols) + 0.5 * hits(path)
+ *
+ * This intentionally beats pure substring matching while staying
+ * zero-dependency and fast enough for sub-second queries on 10k-file repos.
+ */
+const MAX_FILE_SIZE = 512 * 1024;
+const STOPWORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'not', 'of', 'to', 'in', 'is', 'it', 'for', 'on', 'with',
+    'this', 'that', 'by', 'as', 'at', 'be', 'are', 'was', 'were', 'has', 'have', 'had',
+]);
+const TS_KEYWORDS = new Set([
+    'const', 'let', 'var', 'function', 'return', 'if', 'else', 'while', 'for', 'do', 'break',
+    'continue', 'switch', 'case', 'default', 'new', 'class', 'extends', 'implements',
+    'interface', 'type', 'enum', 'public', 'private', 'protected', 'static', 'readonly',
+    'async', 'await', 'try', 'catch', 'finally', 'throw', 'import', 'export', 'from', 'as',
+    'typeof', 'instanceof', 'void', 'null', 'undefined', 'true', 'false', 'this', 'super',
+    'yield', 'delete', 'in', 'of', 'any', 'never', 'unknown', 'string', 'number', 'boolean',
+    'object', 'symbol', 'bigint',
+]);
+export async function buildSearchIndex(rootPath, files, graph) {
+    const indexed = new Map();
+    const postings = new Map();
+    const parseable = files.filter((f) => f.sizeBytes <= MAX_FILE_SIZE && isIndexable(f.relativePath));
+    await Promise.all(parseable.map(async (file) => {
+        const abs = path.isAbsolute(file.absolutePath)
+            ? file.absolutePath
+            : path.resolve(rootPath, file.relativePath);
+        let content;
+        try {
+            content = await fs.readFile(abs, 'utf-8');
+        }
+        catch {
+            return;
+        }
+        const contentTokens = tokenize(content);
+        const pathTokens = tokenize(file.relativePath);
+        const symbols = (graph?.files.get(file.relativePath)?.exports ?? []).map((e) => e.name.toLowerCase());
+        const entry = {
+            relativePath: file.relativePath,
+            content: contentTokens,
+            symbols: symbols.flatMap((s) => tokenize(s)),
+            pathTokens,
+            length: contentTokens.length,
+        };
+        indexed.set(file.relativePath, entry);
+        // Build postings from content tokens
+        const termCounts = new Map();
+        for (const tok of contentTokens) {
+            termCounts.set(tok, (termCounts.get(tok) ?? 0) + 1);
+        }
+        for (const [tok, count] of termCounts) {
+            if (!postings.has(tok))
+                postings.set(tok, new Map());
+            postings.get(tok).set(file.relativePath, count);
+        }
+    }));
+    const totalLength = [...indexed.values()].reduce((sum, f) => sum + f.length, 0);
+    const avgDocLength = indexed.size > 0 ? totalLength / indexed.size : 1;
+    return {
+        files: indexed,
+        postings,
+        avgDocLength,
+        docCount: indexed.size,
+    };
+}
+export function search(index, query, options = {}) {
+    const limit = Math.max(1, Math.min(500, options.limit ?? 30));
+    const symbolWeight = options.symbolWeight ?? 2.0;
+    const pathWeight = options.pathWeight ?? 0.5;
+    const queryTokens = expandQuery(query);
+    if (queryTokens.length === 0)
+        return [];
+    // BM25 parameters
+    const k1 = 1.5;
+    const b = 0.75;
+    const scores = new Map();
+    for (const qTok of queryTokens) {
+        const postings = index.postings.get(qTok);
+        if (!postings)
+            continue;
+        const df = postings.size;
+        const idf = Math.log(1 + (index.docCount - df + 0.5) / (df + 0.5));
+        for (const [file, tf] of postings) {
+            const doc = index.files.get(file);
+            if (!doc)
+                continue;
+            const dl = doc.length;
+            const norm = tf * (k1 + 1) / (tf + k1 * (1 - b + b * (dl / index.avgDocLength)));
+            const bm25 = idf * norm;
+            const existing = scores.get(file);
+            if (existing) {
+                existing.score += bm25;
+                existing.matched.add(qTok);
+            }
+            else {
+                scores.set(file, { score: bm25, matched: new Set([qTok]) });
+            }
+        }
+    }
+    // Apply symbol + path boosts
+    for (const [file, entry] of index.files) {
+        const symbolHits = countHits(entry.symbols, queryTokens);
+        const pathHits = countHits(entry.pathTokens, queryTokens);
+        if (symbolHits > 0 || pathHits > 0) {
+            const current = scores.get(file) ?? { score: 0, matched: new Set() };
+            current.score += symbolHits * symbolWeight + pathHits * pathWeight;
+            for (const qt of queryTokens) {
+                if (entry.symbols.includes(qt) || entry.pathTokens.includes(qt)) {
+                    current.matched.add(qt);
+                }
+            }
+            scores.set(file, current);
+        }
+    }
+    if (scores.size === 0)
+        return [];
+    // Sort by score, take top limit
+    const ranked = [...scores.entries()]
+        .sort((a, b) => b[1].score - a[1].score)
+        .slice(0, limit);
+    return ranked.map(([file, info]) => {
+        const entry = index.files.get(file);
+        const symbolMatch = queryTokens.some((t) => entry.symbols.includes(t));
+        const pathMatch = queryTokens.some((t) => entry.pathTokens.includes(t));
+        return {
+            file,
+            score: Math.round(info.score * 100) / 100,
+            matched: [...info.matched],
+            symbolMatch,
+            pathMatch,
+            excerpt: '',
+            line: 0,
+        };
+    });
+}
+/**
+ * Attach a one-line excerpt to each hit, reading the file to find the first
+ * matching line. This is a separate pass to avoid paying the I/O cost when
+ * the caller only wants paths (e.g., an agent filtering before fetching).
+ */
+export async function attachExcerpts(rootPath, hits, queryTokens) {
+    const qLower = queryTokens.map((t) => t.toLowerCase());
+    return Promise.all(hits.map(async (hit) => {
+        const abs = path.resolve(rootPath, hit.file);
+        try {
+            const content = await fs.readFile(abs, 'utf-8');
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                const lower = lines[i].toLowerCase();
+                if (qLower.some((t) => lower.includes(t))) {
+                    return { ...hit, line: i + 1, excerpt: lines[i].trim().slice(0, 200) };
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+        return hit;
+    }));
+}
+/**
+ * Tokenize a string for indexing/querying:
+ *   - lowercase
+ *   - split on non-identifier chars
+ *   - split camelCase and snake_case
+ *   - drop tokens shorter than 2 chars, stopwords, TS keywords
+ *   - apply basic stem (drop trailing s / ing / ed)
+ */
+export function tokenize(input) {
+    const out = [];
+    // Split on non-identifier boundaries. Keep original case so we can also
+    // split on camelCase boundaries below.
+    const rawTokens = input.match(/[A-Za-z0-9_]+/g) ?? [];
+    for (const raw of rawTokens) {
+        // Split on underscore and camelCase. camelCase: insert a boundary before
+        // each uppercase that follows a lowercase or digit (OR before runs of
+        // uppercase followed by lowercase to handle acronyms like "XMLParser").
+        const camelSplit = raw
+            .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+            .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2');
+        const parts = camelSplit.split(/[_\s]+/).filter(Boolean);
+        for (const part of parts) {
+            // Split embedded digits from letters — e.g. "v1api" → "v", "1", "api"
+            const subparts = part.split(/(\d+)/).filter(Boolean);
+            for (const sp of subparts) {
+                const lower = sp.toLowerCase();
+                const stemmed = stem(lower);
+                if (!keepToken(stemmed))
+                    continue;
+                out.push(stemmed);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Expand a user query into a set of candidate tokens. Same rules as tokenize
+ * plus: if the raw query has no hits, try progressively looser tokenization.
+ */
+export function expandQuery(query) {
+    const tokens = tokenize(query);
+    return [...new Set(tokens)];
+}
+function stem(token) {
+    if (token.length <= 3)
+        return token;
+    if (token.endsWith('ing'))
+        return token.slice(0, -3);
+    if (token.endsWith('ed') && token.length > 4)
+        return token.slice(0, -2);
+    if (token.endsWith('es') && token.length > 4)
+        return token.slice(0, -2);
+    if (token.endsWith('s') && !token.endsWith('ss'))
+        return token.slice(0, -1);
+    return token;
+}
+function keepToken(token) {
+    if (token.length < 2)
+        return false;
+    if (STOPWORDS.has(token))
+        return false;
+    if (TS_KEYWORDS.has(token))
+        return false;
+    return true;
+}
+function countHits(tokens, query) {
+    let count = 0;
+    const set = new Set(tokens);
+    for (const q of query)
+        if (set.has(q))
+            count++;
+    return count;
+}
+function isIndexable(relativePath) {
+    const ext = path.extname(relativePath).toLowerCase();
+    // Index source and markup/docs where it's likely useful
+    return (ext === '.ts' ||
+        ext === '.tsx' ||
+        ext === '.js' ||
+        ext === '.jsx' ||
+        ext === '.mjs' ||
+        ext === '.cjs' ||
+        ext === '.mts' ||
+        ext === '.cts' ||
+        ext === '.py' ||
+        ext === '.go' ||
+        ext === '.rb' ||
+        ext === '.java' ||
+        ext === '.rs' ||
+        ext === '.php' ||
+        ext === '.cs' ||
+        ext === '.swift' ||
+        ext === '.kt' ||
+        ext === '.md' ||
+        ext === '.mdx');
+}
+//# sourceMappingURL=searchIndex.js.map

package/dist/core/searchIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchIndex.js","sourceRoot":"","sources":["../../src/core/searchIndex.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -15,6 +15,10 @@ export { parseSource, isParseable } from './core/ast.js';
 export { buildCodeGraph, filesImportingFile, filesImportingPackage, filesDefiningSymbol, exportsOf, importsOf, importersOf, } from './core/codeGraph.js';
 export { loadCachedGraph, saveCachedGraph, invalidateCache } from './core/indexCache.js';
 export { applyBudget, estimateTokens } from './mcp/tokenBudget.js';
+export { paginate, encodeCursor, decodeCursor, listChecksum, readPageParams } from './mcp/pagination.js';
+export { toContentBlocks } from './mcp/chunker.js';
+export { emitProgress, withProgress } from './mcp/progress.js';
+export { buildSearchIndex, search, tokenize, expandQuery, attachExcerpts, } from './core/searchIndex.js';
 export { findDependencyLines } from './utils/packageJsonLocator.js';
 export { parse as parseSemver, compare as compareSemver, drift as semverDrift } from './utils/semver.js';
 export { walkFiles } from './utils/fileWalker.js';

package/dist/index.js

@@ -15,6 +15,10 @@ export { parseSource, isParseable } from './core/ast.js';
 export { buildCodeGraph, filesImportingFile, filesImportingPackage, filesDefiningSymbol, exportsOf, importsOf, importersOf, } from './core/codeGraph.js';
 export { loadCachedGraph, saveCachedGraph, invalidateCache } from './core/indexCache.js';
 export { applyBudget, estimateTokens } from './mcp/tokenBudget.js';
+export { paginate, encodeCursor, decodeCursor, listChecksum, readPageParams } from './mcp/pagination.js';
+export { toContentBlocks } from './mcp/chunker.js';
+export { emitProgress, withProgress } from './mcp/progress.js';
+export { buildSearchIndex, search, tokenize, expandQuery, attachExcerpts, } from './core/searchIndex.js';
 export { findDependencyLines } from './utils/packageJsonLocator.js';
 export { parse as parseSemver, compare as compareSemver, drift as semverDrift } from './utils/semver.js';
 export { walkFiles } from './utils/fileWalker.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvG,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,SAAS,EACT,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACzF,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,OAAO,IAAI,aAAa,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACzG,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvG,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,SAAS,EACT,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACzF,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACzG,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EACL,gBAAgB,EAChB,MAAM,EACN,QAAQ,EACR,WAAW,EACX,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,OAAO,IAAI,aAAa,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACzG,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/mcp/chunker.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Split large tool responses into multiple MCP `content` blocks so agents
+ * that consume them streaming-style can process results incrementally.
+ *
+ * MCP content is `[{ type: "text", text: string }, ...]`. Current strategy:
+ *   - If the payload has a primary array field (hotspots, entries, findings,
+ *     packages, matches), emit one header block with scalar fields, then
+ *     emit chunk blocks each containing a slice of the array.
+ *   - Otherwise, emit a single block.
+ *
+ * Chunk size defaults to 20 records per block — small enough to be a
+ * meaningful streaming unit, big enough to avoid pathological block counts.
+ */
+export interface ContentBlock {
+    type: 'text';
+    text: string;
+}
+export interface ChunkOptions {
+    chunkSize?: number;
+    /** Only chunk when the primary array has at least this many items. */
+    minItemsToChunk?: number;
+}
+export declare function toContentBlocks(value: unknown, options?: ChunkOptions): ContentBlock[];

package/dist/mcp/chunker.js

@@ -0,0 +1,67 @@
+/**
+ * Split large tool responses into multiple MCP `content` blocks so agents
+ * that consume them streaming-style can process results incrementally.
+ *
+ * MCP content is `[{ type: "text", text: string }, ...]`. Current strategy:
+ *   - If the payload has a primary array field (hotspots, entries, findings,
+ *     packages, matches), emit one header block with scalar fields, then
+ *     emit chunk blocks each containing a slice of the array.
+ *   - Otherwise, emit a single block.
+ *
+ * Chunk size defaults to 20 records per block — small enough to be a
+ * meaningful streaming unit, big enough to avoid pathological block counts.
+ */
+const DEFAULT_CHUNK_SIZE = 20;
+const PRIMARY_ARRAY_KEYS = [
+    'hotspots',
+    'entries',
+    'findings',
+    'packages',
+    'matches',
+    'importers',
+    'files',
+    'definedIn',
+];
+export function toContentBlocks(value, options = {}) {
+    const chunkSize = Math.max(1, options.chunkSize ?? DEFAULT_CHUNK_SIZE);
+    const minItemsToChunk = options.minItemsToChunk ?? chunkSize;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return [{ type: 'text', text: safeStringify(value) }];
+    }
+    const obj = value;
+    const primaryKey = PRIMARY_ARRAY_KEYS.find((k) => Array.isArray(obj[k]) && obj[k].length >= minItemsToChunk);
+    if (!primaryKey) {
+        return [{ type: 'text', text: safeStringify(value) }];
+    }
+    const items = obj[primaryKey];
+    const header = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (k === primaryKey)
+            continue;
+        header[k] = v;
+    }
+    header[`${primaryKey}Preview`] = {
+        totalItems: items.length,
+        chunkedInto: Math.ceil(items.length / chunkSize),
+        chunkSize,
+    };
+    const blocks = [{ type: 'text', text: safeStringify(header) }];
+    for (let i = 0; i < items.length; i += chunkSize) {
+        const chunkIndex = Math.floor(i / chunkSize);
+        const chunkPayload = {
+            _chunk: { index: chunkIndex, offset: i, size: items.slice(i, i + chunkSize).length },
+            [primaryKey]: items.slice(i, i + chunkSize),
+        };
+        blocks.push({ type: 'text', text: safeStringify(chunkPayload) });
+    }
+    return blocks;
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=chunker.js.map

package/dist/mcp/chunker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.js","sourceRoot":"","sources":["../../src/mcp/chunker.ts"],"names":[],"mappings":"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"}

package/dist/mcp/pagination.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Cursor-based pagination for MCP tool responses.
+ *
+ * Cursors are opaque base64-encoded JSON objects containing an integer
+ * offset plus an optional checksum of the result-set shape so we can
+ * detect when the underlying data has shifted between paginated calls.
+ *
+ * Agents pass `cursor` back to the same tool to fetch the next page.
+ * When no more results exist, the response omits `nextCursor`.
+ */
+export interface PageRequest {
+    cursor?: string;
+    pageSize?: number;
+}
+export interface Page<T> {
+    items: T[];
+    nextCursor?: string;
+    total: number;
+}
+/**
+ * Slice an array into a page. `checksum` should be a cheap identifier of
+ * the result-set shape (e.g., `items.length`) — if it mismatches a cursor's
+ * captured checksum we treat the page as fresh (offset=0) rather than risk
+ * returning stale offsets.
+ */
+export declare function paginate<T>(items: T[], request: PageRequest, checksum: string): Page<T>;
+interface DecodedCursor {
+    offset: number;
+    checksum: string;
+}
+export declare function encodeCursor(cursor: DecodedCursor): string;
+export declare function decodeCursor(cursor?: string): DecodedCursor | null;
+/**
+ * Compute a lightweight checksum for a list. Deliberately weak — we want
+ * cursor invalidation on shape changes (length) but not on micro-changes
+ * within items (scores that shift slightly between runs). Agents already
+ * handle eventual consistency.
+ */
+export declare function listChecksum(items: unknown[]): string;
+/** Extract pageSize + cursor from MCP args, defaulting conservatively. */
+export declare function readPageParams(args: Record<string, unknown>): PageRequest;
+export {};

package/dist/mcp/pagination.js

@@ -0,0 +1,66 @@
+/**
+ * Cursor-based pagination for MCP tool responses.
+ *
+ * Cursors are opaque base64-encoded JSON objects containing an integer
+ * offset plus an optional checksum of the result-set shape so we can
+ * detect when the underlying data has shifted between paginated calls.
+ *
+ * Agents pass `cursor` back to the same tool to fetch the next page.
+ * When no more results exist, the response omits `nextCursor`.
+ */
+const DEFAULT_PAGE_SIZE = 50;
+const MAX_PAGE_SIZE = 500;
+/**
+ * Slice an array into a page. `checksum` should be a cheap identifier of
+ * the result-set shape (e.g., `items.length`) — if it mismatches a cursor's
+ * captured checksum we treat the page as fresh (offset=0) rather than risk
+ * returning stale offsets.
+ */
+export function paginate(items, request, checksum) {
+    const size = Math.max(1, Math.min(MAX_PAGE_SIZE, request.pageSize ?? DEFAULT_PAGE_SIZE));
+    const decoded = decodeCursor(request.cursor);
+    const offset = decoded && decoded.checksum === checksum ? decoded.offset : 0;
+    const slice = items.slice(offset, offset + size);
+    const nextOffset = offset + slice.length;
+    const hasMore = nextOffset < items.length;
+    return {
+        items: slice,
+        nextCursor: hasMore ? encodeCursor({ offset: nextOffset, checksum }) : undefined,
+        total: items.length,
+    };
+}
+export function encodeCursor(cursor) {
+    const json = JSON.stringify(cursor);
+    return Buffer.from(json, 'utf-8').toString('base64');
+}
+export function decodeCursor(cursor) {
+    if (!cursor || typeof cursor !== 'string')
+        return null;
+    try {
+        const json = Buffer.from(cursor, 'base64').toString('utf-8');
+        const parsed = JSON.parse(json);
+        if (typeof parsed.offset !== 'number' || typeof parsed.checksum !== 'string') {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compute a lightweight checksum for a list. Deliberately weak — we want
+ * cursor invalidation on shape changes (length) but not on micro-changes
+ * within items (scores that shift slightly between runs). Agents already
+ * handle eventual consistency.
+ */
+export function listChecksum(items) {
+    return `len:${items.length}`;
+}
+/** Extract pageSize + cursor from MCP args, defaulting conservatively. */
+export function readPageParams(args) {
+    const cursor = typeof args.cursor === 'string' ? args.cursor : undefined;
+    const pageSize = typeof args.page_size === 'number' ? args.page_size : undefined;
+    return { cursor, pageSize };
+}
+//# sourceMappingURL=pagination.js.map

package/dist/mcp/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/mcp/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAaH,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAC7B,MAAM,aAAa,GAAG,GAAG,CAAC;AAE1B;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAU,EACV,OAAoB,EACpB,QAAgB;IAEhB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAC,CAAC,CAAC;IACzF,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,OAAO,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7E,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACjD,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IACzC,MAAM,OAAO,GAAG,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC;IAE1C,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS;QAChF,KAAK,EAAE,KAAK,CAAC,MAAM;KACpB,CAAC;AACJ,CAAC;AAOD,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACpC,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAe;IAC1C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAkB,CAAC;QACjD,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC7E,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAgB;IAC3C,OAAO,OAAO,KAAK,CAAC,MAAM,EAAE,CAAC;AAC/B,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,IAA6B;IAC1D,MAAM,MAAM,GAAG,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IACzE,MAAM,QAAQ,GAAG,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IACjF,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC9B,CAAC"}

package/dist/mcp/progress.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Progress notification plumbing for long-running MCP tools.
+ *
+ * Per MCP spec, a client that wants progress sets `_meta.progressToken` on
+ * the tool-call request. We capture it at dispatch time and expose a
+ * `notify(progress, total?)` callback to the tool handler via the rootPath
+ * extension — which is awkward but keeps the handler signature unchanged
+ * for tools that don't care.
+ *
+ * The notification wire format (MCP 2024-11-05 + 2025-03-26):
+ *   { "jsonrpc": "2.0", "method": "notifications/progress",
+ *     "params": { "progressToken": <token>, "progress": <n>, "total"?: <n>, "message"?: "..." } }
+ */
+export type ProgressEmitter = (progress: number, total?: number, message?: string) => void;
+declare const NOOP: ProgressEmitter;
+export declare function withProgress<T>(emit: ProgressEmitter | undefined, fn: () => Promise<T>): Promise<T>;
+export declare function emitProgress(progress: number, total?: number, message?: string): void;
+export { NOOP };

package/dist/mcp/progress.js

@@ -0,0 +1,47 @@
+/**
+ * Progress notification plumbing for long-running MCP tools.
+ *
+ * Per MCP spec, a client that wants progress sets `_meta.progressToken` on
+ * the tool-call request. We capture it at dispatch time and expose a
+ * `notify(progress, total?)` callback to the tool handler via the rootPath
+ * extension — which is awkward but keeps the handler signature unchanged
+ * for tools that don't care.
+ *
+ * The notification wire format (MCP 2024-11-05 + 2025-03-26):
+ *   { "jsonrpc": "2.0", "method": "notifications/progress",
+ *     "params": { "progressToken": <token>, "progress": <n>, "total"?: <n>, "message"?: "..." } }
+ */
+const NOOP = () => { };
+/**
+ * AsyncLocalStorage-style context. We stash the current emitter on a
+ * module-level WeakMap keyed by a symbol to survive `await` points.
+ * Simpler than pulling in `node:async_hooks`.
+ */
+const emitters = new Map();
+export function withProgress(emit, fn) {
+    if (!emit)
+        return fn();
+    const key = Symbol('progress');
+    emitters.set(key, emit);
+    currentKey = key;
+    return fn().finally(() => {
+        emitters.delete(key);
+        currentKey = null;
+    });
+}
+let currentKey = null;
+export function emitProgress(progress, total, message) {
+    if (!currentKey)
+        return;
+    const emit = emitters.get(currentKey);
+    if (!emit)
+        return;
+    try {
+        emit(progress, total, message);
+    }
+    catch {
+        // progress is best-effort; never throw back into user code
+    }
+}
+export { NOOP };
+//# sourceMappingURL=progress.js.map

package/dist/mcp/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../src/mcp/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,IAAI,GAAoB,GAAG,EAAE,GAAE,CAAC,CAAC;AAEvC;;;;GAIG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;AAEpD,MAAM,UAAU,YAAY,CAC1B,IAAiC,EACjC,EAAoB;IAEpB,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,EAAE,CAAC;IACvB,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IAC/B,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACxB,UAAU,GAAG,GAAG,CAAC;IACjB,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;QACvB,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,UAAU,GAAG,IAAI,CAAC;IACpB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,IAAI,UAAU,GAAkB,IAAI,CAAC;AAErC,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,KAAc,EAAE,OAAgB;IAC7E,IAAI,CAAC,UAAU;QAAE,OAAO;IACxB,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACtC,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,IAAI,CAAC;QACH,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,2DAA2D;IAC7D,CAAC;AACH,CAAC;AAED,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/mcp/server.d.ts

@@ -1,5 +1,13 @@
 export interface McpServerHandle {
     handleMessage(line: string): Promise<string | null>;
 }
-export declare function createMcpServer(rootPath: string): McpServerHandle;
+export interface McpServerOptions {
+    /**
+     * Called when the server wants to emit a JSON-RPC notification (e.g.,
+     * `notifications/progress`) out of band from the normal request/response
+     * cycle. The transport layer is responsible for writing the payload.
+     */
+    notify?: (payload: string) => void;
+}
+export declare function createMcpServer(rootPath: string, options?: McpServerOptions): McpServerHandle;
 export declare function runMcpServer(rootPath: string): Promise<void>;