token-pilot 0.12.0 → 0.14.1

package/dist/handlers/find-usages.js

@@ -1,3 +1,4 @@
+import { assessConfidence, formatConfidence } from '../core/confidence.js';
 /**
  * Escape special regex characters in a string.
  */
@@ -33,10 +34,16 @@ const LANG_EXT_MAP = {
  */
 export async function handleFindUsages(args, astIndex) {
     if (astIndex.isDisabled() || astIndex.isOversized()) {
-        return { content: [{ type: 'text', text: 'find_usages is disabled: ' + (astIndex.isDisabled()
+        return {
+            content: [{
+                    type: 'text',
+                    text: 'find_usages is disabled: ' + (astIndex.isDisabled()
                         ? 'project root not detected. Call smart_read() on any project file first — this auto-detects the project root and enables ast-index tools.'
-                        : 'ast-index built >50k files (likely includes node_modules). Ensure node_modules is in .gitignore.') +
-                        '\nAlternative: use grep_search to find symbol references.' }] };
+                        : 'ast-index built >50k files (likely includes node_modules). Ensure node_modules is in .gitignore.')
+                        + '\nAlternative: use grep_search to find symbol references.',
+                }],
+            meta: { files: [], definitions: 0, imports: 0, usages: 0, total: 0 },
+        };
     }
     // Run refs + search in parallel
     const [refs, searchResults] = await Promise.all([
@@ -129,7 +136,10 @@ export async function handleFindUsages(args, astIndex) {
         if (!astIndex.isAvailable()) {
             hints.push('WARNING: ast-index is not available.');
         }
-        return { content: [{ type: 'text', text: hints.join('\n') }] };
+        return {
+            content: [{ type: 'text', text: hints.join('\n') }],
+            meta: { files: [], definitions: 0, imports: 0, usages: 0, total: 0 },
+        };
     }
     // Build header with active filters
     const filterHints = [];
@@ -169,6 +179,27 @@ export async function handleFindUsages(args, astIndex) {
         lines.push('');
     }
     lines.push('HINT: Use read_symbol() or read_range() to load specific results.');
-    return { content: [{ type: 'text', text: lines.join('\n') }] };
+    // Confidence metadata
+    const confidenceMeta = assessConfidence({
+        refsFound: totalCount > 0,
+        astAvailable: astIndex.isAvailable(),
+        symbolResolved: definitions.length > 0,
+    });
+    lines.push(formatConfidence(confidenceMeta));
+    const files = Array.from(new Set([
+        ...definitions.map((d) => d.file),
+        ...allImports.map((i) => i.file),
+        ...allUsages.map((u) => u.file),
+    ])).sort();
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        meta: {
+            files,
+            definitions: definitions.length,
+            imports: allImports.length,
+            usages: allUsages.length,
+            total: totalCount,
+        },
+    };
 }
 //# sourceMappingURL=find-usages.js.map

package/dist/handlers/module-info.d.ts

@@ -5,5 +5,8 @@ export declare function handleModuleInfo(args: ModuleInfoArgs, projectRoot: stri
         type: 'text';
         text: string;
     }>;
+    meta: {
+        files: string[];
+    };
 }>;
 //# sourceMappingURL=module-info.d.ts.map

package/dist/handlers/module-info.js

@@ -8,6 +8,7 @@ export async function handleModuleInfo(args, projectRoot, astIndex) {
                     text: '⚠ ast-index unavailable — module_info requires ast-index.\n' +
                         'DEGRADED: Use find_usages() + related_files() as alternatives for dependency analysis.',
                 }],
+            meta: { files: [] },
         };
     }
     const check = args.check ?? 'all';
@@ -36,7 +37,7 @@ export async function handleModuleInfo(args, projectRoot, astIndex) {
             sections.push('No modules detected. ast-index module analysis requires a modular project structure.');
             sections.push('HINT: Use find_usages() for cross-file symbol references, related_files() for import graphs.');
         }
-        return { content: [{ type: 'text', text: sections.join('\n') }] };
+        return { content: [{ type: 'text', text: sections.join('\n') }], meta: { files: [] } };
     }
     sections.push('');
     // Run requested checks in parallel
@@ -115,7 +116,26 @@ export async function handleModuleInfo(args, projectRoot, astIndex) {
         }
     }
     sections.push('HINT: Use smart_read() on module files, find_usages() for cross-module references.');
-    return { content: [{ type: 'text', text: sections.join('\n') }] };
+    // Collect files from results for analytics
+    const metaFiles = [];
+    for (const r of results) {
+        if (r.status !== 'fulfilled')
+            continue;
+        const { type, data } = r.value;
+        switch (type) {
+            case 'api':
+                for (const a of data)
+                    metaFiles.push(a.file);
+                break;
+            case 'deps':
+            case 'dependents':
+            case 'unused-deps':
+                for (const d of data)
+                    metaFiles.push(d.path);
+                break;
+        }
+    }
+    return { content: [{ type: 'text', text: sections.join('\n') }], meta: { files: [...new Set(metaFiles)] } };
 }
 function rel(projectRoot, absPath) {
     return relative(projectRoot, absPath) || absPath;

package/dist/handlers/project-overview.d.ts

@@ -1,6 +1,6 @@
 import type { AstIndexClient } from '../ast-index/client.js';
 import type { ProjectOverviewArgs } from '../core/validation.js';
-export declare function handleProjectOverview(args: ProjectOverviewArgs, projectRoot: string, astIndex: AstIndexClient): Promise<{
+export declare function handleProjectOverview(args: ProjectOverviewArgs, projectRoot: string, astIndex: AstIndexClient, appVersion?: string): Promise<{
     content: Array<{
         type: 'text';
         text: string;

package/dist/handlers/project-overview.js

@@ -1,6 +1,13 @@
 import { detectProject } from '../core/project-detector.js';
-export async function handleProjectOverview(args, projectRoot, astIndex) {
+import { loadFingerprint, saveFingerprint, buildFingerprint, formatCachedFingerprint, } from '../core/architecture-fingerprint.js';
+export async function handleProjectOverview(args, projectRoot, astIndex, appVersion) {
     const lines = [];
+    // Check for cached fingerprint
+    const cachedFp = await loadFingerprint(projectRoot);
+    if (cachedFp) {
+        lines.push(formatCachedFingerprint(cachedFp));
+        lines.push('');
+    }
     // 1. Dual detection: ast-index + config scanner
     let astIndexType;
     let mapData = null;
@@ -117,7 +124,16 @@ export async function handleProjectOverview(args, projectRoot, astIndex) {
         lines.push('');
     }
     lines.push('HINT: Use smart_read() on files, find_usages() for symbol references, outline() for directory overview.');
-    return { content: [{ type: 'text', text: lines.join('\n') }] };
+    // Save fingerprint for next session
+    const outputText = lines.join('\n');
+    try {
+        const fp = buildFingerprint(outputText, appVersion ?? 'unknown');
+        await saveFingerprint(projectRoot, fp);
+    }
+    catch {
+        // Non-critical — don't fail the handler
+    }
+    return { content: [{ type: 'text', text: outputText }] };
 }
 // ──────────────────────────────────────────────
 // Formatters

package/dist/handlers/read-for-edit.d.ts

@@ -7,6 +7,9 @@ export interface ReadForEditArgs {
     symbol?: string;
     line?: number;
     context?: number;
+    include_callers?: boolean;
+    include_tests?: boolean;
+    include_changes?: boolean;
 }
 export declare function handleReadForEdit(args: ReadForEditArgs, projectRoot: string, symbolResolver: SymbolResolver, fileCache: FileCache, contextRegistry: ContextRegistry, astIndex: AstIndexClient): Promise<{
     content: Array<{

package/dist/handlers/read-for-edit.js

@@ -1,7 +1,12 @@
-import { readFile, stat } from 'node:fs/promises';
+import { readFile, stat, access } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
 import { createHash } from 'node:crypto';
+import { relative, join } from 'node:path';
 import { estimateTokens } from '../core/token-estimator.js';
 import { resolveSafePath } from '../core/validation.js';
+import { assessConfidence, formatConfidence } from '../core/confidence.js';
+const execFileAsync = promisify(execFile);
 const DEFAULT_CONTEXT = 5;
 export async function handleReadForEdit(args, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex) {
     const absPath = resolveSafePath(projectRoot, args.path);
@@ -91,7 +96,7 @@ export async function handleReadForEdit(args, projectRoot, symbolResolver, fileC
     const rangeCount = rangeEnd - rangeStart + 1;
     // Extract RAW code (no line number prefixes — ready for Edit old_string)
     const rawCode = lines.slice(rangeStart - 1, rangeEnd).join('\n');
-    const output = [
+    const outputLines = [
         `--- EDIT CONTEXT ---`,
         `FILE: ${args.path}`,
         `TARGET: ${targetLabel}`,
@@ -103,7 +108,54 @@ export async function handleReadForEdit(args, projectRoot, symbolResolver, fileC
         '',
         `To edit: use exact text above as old_string in Edit tool.`,
         `For Read requirement: Read("${args.path}", offset=${rangeStart}, limit=${rangeCount})`,
-    ].join('\n');
+    ];
+    // --- Optional enrichment sections ---
+    // include_callers: compact caller list via ast-index refs
+    if (args.include_callers && args.symbol && !astIndex.isDisabled()) {
+        try {
+            const refs = await astIndex.refs(args.symbol, 10);
+            const callers = refs.usages.slice(0, 5);
+            if (callers.length > 0) {
+                outputLines.push('');
+                outputLines.push(`CALLERS (${callers.length}):`);
+                for (const c of callers) {
+                    const relPath = relative(projectRoot, c.path);
+                    const ctx = c.context ? ` — ${c.context.trim().slice(0, 80)}` : '';
+                    outputLines.push(`  ${relPath}:${c.line}${ctx}`);
+                }
+            }
+            else {
+                outputLines.push('');
+                outputLines.push('CALLERS: none found');
+            }
+        }
+        catch {
+            // ast-index unavailable — skip silently
+        }
+    }
+    // include_tests: find related test file and list test names
+    if (args.include_tests) {
+        const testSection = await findTestSection(absPath, args.path, projectRoot, astIndex);
+        outputLines.push('');
+        outputLines.push(...testSection);
+    }
+    // include_changes: git diff filtered to target region
+    if (args.include_changes) {
+        const diffSection = await findChangesSection(absPath, projectRoot, rangeStart, rangeEnd);
+        outputLines.push('');
+        outputLines.push(...diffSection);
+    }
+    // Confidence metadata
+    const confidenceMeta = assessConfidence({
+        symbolResolved: !!args.symbol && startLine > 0,
+        fullFile: false,
+        truncated: false,
+        hasCallers: args.include_callers ?? false,
+        hasTests: args.include_tests ?? false,
+        astAvailable: true,
+    });
+    outputLines.push(formatConfidence(confidenceMeta));
+    const output = outputLines.join('\n');
     const tokens = estimateTokens(output);
     // Track in context
     contextRegistry.trackLoad(absPath, {
@@ -115,4 +167,134 @@ export async function handleReadForEdit(args, projectRoot, symbolResolver, fileC
     });
     return { content: [{ type: 'text', text: output }] };
 }
+// --- Helper: find related test file and extract test names ---
+async function findTestSection(absPath, relPath, projectRoot, astIndex) {
+    // Derive test file path from source path using common conventions
+    // src/handlers/foo.ts → tests/handlers/foo.test.ts
+    // src/core/bar.ts → tests/core/bar.test.ts
+    const srcPrefix = 'src/';
+    let testRelPath;
+    if (relPath.startsWith(srcPrefix)) {
+        const rest = relPath.slice(srcPrefix.length);
+        const ext = rest.match(/\.[^.]+$/)?.[0] ?? '.ts';
+        const base = rest.replace(/\.[^.]+$/, '');
+        testRelPath = `tests/${base}.test${ext}`;
+    }
+    else {
+        const ext = relPath.match(/\.[^.]+$/)?.[0] ?? '.ts';
+        const base = relPath.replace(/\.[^.]+$/, '');
+        testRelPath = `${base}.test${ext}`;
+    }
+    const testAbsPath = join(projectRoot, testRelPath);
+    try {
+        await access(testAbsPath);
+    }
+    catch {
+        return [`TESTS: none found (expected at ${testRelPath})`];
+    }
+    // Test file exists — try to get outline for test names
+    const lines = [`TESTS: ${testRelPath}`];
+    if (!astIndex.isDisabled()) {
+        try {
+            const outline = await astIndex.outline(testAbsPath);
+            if (outline?.symbols && outline.symbols.length > 0) {
+                for (const sym of outline.symbols) {
+                    lines.push(`  ${sym.kind} ${sym.name}`);
+                    if (sym.children) {
+                        for (const child of sym.children) {
+                            lines.push(`    ${child.kind} ${child.name}`);
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // outline failed — just show file path
+        }
+    }
+    return lines;
+}
+// --- Helper: git diff filtered to target region ---
+async function findChangesSection(absPath, projectRoot, rangeStart, rangeEnd) {
+    const MAX_DIFF_LINES = 30;
+    try {
+        // Try unstaged changes first
+        let diffOutput = '';
+        let diffLabel = 'unstaged';
+        try {
+            const { stdout } = await execFileAsync('git', ['diff', 'HEAD', '--', absPath], {
+                cwd: projectRoot,
+                timeout: 5000,
+            });
+            diffOutput = stdout;
+        }
+        catch {
+            // git not available or not a repo
+            return ['RECENT CHANGES: unavailable (not a git repo)'];
+        }
+        // If no unstaged changes, try last commit
+        if (!diffOutput.trim()) {
+            try {
+                const { stdout } = await execFileAsync('git', ['diff', 'HEAD~1', '--', absPath], {
+                    cwd: projectRoot,
+                    timeout: 5000,
+                });
+                diffOutput = stdout;
+                diffLabel = 'last commit';
+            }
+            catch {
+                // no previous commit
+            }
+        }
+        if (!diffOutput.trim()) {
+            return ['RECENT CHANGES: none (file unchanged)'];
+        }
+        // Filter hunks to those overlapping with target range
+        const relevantLines = filterDiffHunks(diffOutput, rangeStart, rangeEnd);
+        if (relevantLines.length === 0) {
+            return ['RECENT CHANGES: none in target region'];
+        }
+        const lines = [`RECENT CHANGES (${diffLabel}):`];
+        const trimmed = relevantLines.slice(0, MAX_DIFF_LINES);
+        for (const line of trimmed) {
+            lines.push(`  ${line}`);
+        }
+        if (relevantLines.length > MAX_DIFF_LINES) {
+            lines.push(`  ... ${relevantLines.length - MAX_DIFF_LINES} more lines`);
+        }
+        return lines;
+    }
+    catch {
+        return ['RECENT CHANGES: unavailable'];
+    }
+}
+/** Filter diff output to only hunks overlapping [rangeStart, rangeEnd]. */
+function filterDiffHunks(diff, rangeStart, rangeEnd) {
+    const allLines = diff.split('\n');
+    const result = [];
+    let inRelevantHunk = false;
+    for (const line of allLines) {
+        // Hunk header: @@ -a,b +c,d @@
+        const hunkMatch = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+        if (hunkMatch) {
+            const hunkStart = parseInt(hunkMatch[1], 10);
+            const hunkLen = parseInt(hunkMatch[2] ?? '1', 10);
+            const hunkEnd = hunkStart + hunkLen - 1;
+            // Check overlap with target range
+            inRelevantHunk = hunkStart <= rangeEnd && hunkEnd >= rangeStart;
+            if (inRelevantHunk) {
+                result.push(line);
+            }
+            continue;
+        }
+        // Skip diff metadata lines (diff --git, index, ---, +++)
+        if (line.startsWith('diff ') || line.startsWith('index ') || line.startsWith('--- ') || line.startsWith('+++ ')) {
+            continue;
+        }
+        if (inRelevantHunk && (line.startsWith('+') || line.startsWith('-') || line.startsWith(' '))) {
+            result.push(line);
+        }
+    }
+    return result;
+}
 //# sourceMappingURL=read-for-edit.js.map

package/dist/handlers/read-range.d.ts

@@ -5,7 +5,7 @@ export interface ReadRangeArgs {
     start_line: number;
     end_line: number;
 }
-export declare function handleReadRange(args: ReadRangeArgs, projectRoot: string, fileCache: FileCache, contextRegistry: ContextRegistry): Promise<{
+export declare function handleReadRange(args: ReadRangeArgs, projectRoot: string, fileCache: FileCache, contextRegistry: ContextRegistry, advisoryReminders?: boolean): Promise<{
     content: Array<{
         type: 'text';
         text: string;

package/dist/handlers/read-range.js

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { estimateTokens } from '../core/token-estimator.js';
 import { resolveSafePath } from '../core/validation.js';
-export async function handleReadRange(args, projectRoot, fileCache, contextRegistry) {
+export async function handleReadRange(args, projectRoot, fileCache, contextRegistry, advisoryReminders = true) {
     const absPath = resolveSafePath(projectRoot, args.path);
     // Get lines
     const cached = fileCache.get(absPath);
@@ -13,6 +13,18 @@ export async function handleReadRange(args, projectRoot, fileCache, contextRegis
         const content = await readFile(absPath, 'utf-8');
         lines = content.split('\n');
     }
+    // Dedup: check if full file is already in context and unchanged
+    if (advisoryReminders) {
+        const hash = cached?.hash;
+        if (hash && !contextRegistry.isStale(absPath, hash)) {
+            if (contextRegistry.isFullyLoaded(absPath)) {
+                const reminder = contextRegistry.rangeReminder(absPath, args.start_line, args.end_line);
+                if (reminder) {
+                    return { content: [{ type: 'text', text: reminder }] };
+                }
+            }
+        }
+    }
     const start = Math.max(0, args.start_line - 1);
     const end = Math.min(lines.length, args.end_line);
     if (start >= lines.length || start >= end) {
@@ -39,6 +51,9 @@ export async function handleReadRange(args, projectRoot, fileCache, contextRegis
         endLine: args.end_line,
         tokens,
     });
+    if (cached?.hash) {
+        contextRegistry.setContentHash(absPath, cached.hash);
+    }
     return { content: [{ type: 'text', text: output }] };
 }
 //# sourceMappingURL=read-range.js.map

package/dist/handlers/read-symbol.d.ts

@@ -9,7 +9,7 @@ export interface ReadSymbolArgs {
     context_after?: number;
     show?: 'full' | 'head' | 'tail' | 'outline';
 }
-export declare function handleReadSymbol(args: ReadSymbolArgs, projectRoot: string, symbolResolver: SymbolResolver, fileCache: FileCache, contextRegistry: ContextRegistry, astIndex?: AstIndexClient): Promise<{
+export declare function handleReadSymbol(args: ReadSymbolArgs, projectRoot: string, symbolResolver: SymbolResolver, fileCache: FileCache, contextRegistry: ContextRegistry, astIndex?: AstIndexClient, advisoryReminders?: boolean): Promise<{
     content: Array<{
         type: 'text';
         text: string;

package/dist/handlers/read-symbol.js

@@ -1,7 +1,8 @@
 import { readFile } from 'node:fs/promises';
 import { estimateTokens } from '../core/token-estimator.js';
 import { resolveSafePath } from '../core/validation.js';
-export async function handleReadSymbol(args, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex) {
+import { assessConfidence, formatConfidence } from '../core/confidence.js';
+export async function handleReadSymbol(args, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex, advisoryReminders = true) {
     const absPath = resolveSafePath(projectRoot, args.path);
     // Get file content
     const cached = fileCache.get(absPath);
@@ -13,6 +14,18 @@ export async function handleReadSymbol(args, projectRoot, symbolResolver, fileCa
         const content = await readFile(absPath, 'utf-8');
         lines = content.split('\n');
     }
+    // Dedup: check if content already in context and unchanged
+    if (advisoryReminders) {
+        const hash = cached?.hash;
+        if (hash && !contextRegistry.isStale(absPath, hash)) {
+            if (contextRegistry.isFullyLoaded(absPath) || contextRegistry.isSymbolLoaded(absPath, args.symbol)) {
+                const reminder = contextRegistry.symbolReminder(absPath, args.symbol);
+                if (reminder) {
+                    return { content: [{ type: 'text', text: reminder }] };
+                }
+            }
+        }
+    }
     // Resolve symbol — auto-fetch structure if not cached
     let structure = cached?.structure;
     if (!structure && astIndex) {
@@ -116,6 +129,17 @@ export async function handleReadSymbol(args, projectRoot, symbolResolver, fileCa
         endLine: resolved.endLine,
         tokens,
     });
-    return { content: [{ type: 'text', text: output }] };
+    if (cached?.hash) {
+        contextRegistry.setContentHash(absPath, cached.hash);
+    }
+    // Confidence metadata
+    const confidenceMeta = assessConfidence({
+        symbolResolved: true,
+        truncated,
+        fullFile: false,
+        hasCallers: resolved.symbol.references.length > 0,
+        astAvailable: !!structure,
+    });
+    return { content: [{ type: 'text', text: output + formatConfidence(confidenceMeta) }] };
 }
 //# sourceMappingURL=read-symbol.js.map

package/dist/handlers/related-files.d.ts

@@ -2,10 +2,21 @@ import type { AstIndexClient } from '../ast-index/client.js';
 export interface RelatedFilesArgs {
     path: string;
 }
+export interface RelatedFilesMeta {
+    imports: string[];
+    importedBy: string[];
+    tests: string[];
+    ranked: {
+        high: string[];
+        medium: string[];
+        low: string[];
+    };
+}
 export declare function handleRelatedFiles(args: RelatedFilesArgs, projectRoot: string, astIndex: AstIndexClient): Promise<{
     content: Array<{
         type: 'text';
         text: string;
     }>;
+    meta: RelatedFilesMeta;
 }>;
 //# sourceMappingURL=related-files.d.ts.map