ast-mcp-server 0.6.0 → 0.7.0

package/dist/services/agent-targets.js

@@ -0,0 +1,122 @@
+export const MCP_SERVER_NAME = "ast";
+const EXPECTED_HERMES_TOOLS = [
+    "ast_list_files",
+    "ast_get_outline",
+    "ast_get_symbol_source",
+    "ast_search_symbols",
+    "ast_find_references",
+    "ast_get_diagnostics",
+    "ast_rename_symbol",
+    "ast_replace_symbol_body",
+    "ast_scaffold_class",
+    "ast_get_operation_preview",
+    "ast_apply_operation",
+];
+function isMissingClaudeMcp(output) {
+    return (/\bno\s+mcp\s+server\b/i.test(output) &&
+        /(?:\bfound\b|\bnamed?\b)/i.test(output) &&
+        /\bast\b/i.test(output));
+}
+function inspectClaudeFields(stdout) {
+    const fields = new Map();
+    for (const line of stdout.split(/\r?\n/)) {
+        const match = line.match(/^\s*(Status|Type|Command|Args):\s*(.*)$/i);
+        if (match !== null)
+            fields.set(match[1].toLowerCase(), match[2].trim());
+    }
+    return fields;
+}
+const claudeMcp = {
+    async inspect(runtime, context) {
+        const result = await runtime.run(["mcp", "get", MCP_SERVER_NAME]);
+        const output = `${result.stdout}\n${result.stderr}`;
+        if (result.exitCode !== 0) {
+            return isMissingClaudeMcp(output)
+                ? { status: "missing" }
+                : { status: "error", operation: "MCP inspection", result };
+        }
+        const fields = inspectClaudeFields(result.stdout);
+        const current = /connected/i.test(fields.get("status") ?? "") &&
+            fields.get("type")?.toLowerCase() === "stdio" &&
+            fields.get("command") === context.nodeExecutable &&
+            fields.get("args") === context.serverEntryPath;
+        return current
+            ? { status: "current" }
+            : {
+                status: "conflict",
+                detail: "The existing user-scoped 'ast' registration does not match this package.",
+            };
+    },
+    register(runtime, context) {
+        return runtime.run([
+            "mcp",
+            "add",
+            "--scope",
+            "user",
+            "--transport",
+            "stdio",
+            MCP_SERVER_NAME,
+            "--",
+            context.nodeExecutable,
+            context.serverEntryPath,
+        ]);
+    },
+    registrationAccepted(result) {
+        return result.exitCode === 0;
+    },
+};
+const hermesMcp = {
+    async inspect(runtime) {
+        const listed = await runtime.run(["mcp", "list"]);
+        if (listed.exitCode !== 0) {
+            return { status: "error", operation: "MCP list", result: listed };
+        }
+        if (!/^\s*ast(?:\s|$)/im.test(listed.stdout))
+            return { status: "missing" };
+        const tested = await runtime.run(["mcp", "test", MCP_SERVER_NAME]);
+        const current = tested.exitCode === 0 && EXPECTED_HERMES_TOOLS.every((tool) => tested.stdout.includes(tool));
+        return current
+            ? { status: "current" }
+            : {
+                status: "conflict",
+                detail: "The existing 'ast' registration does not expose the expected structural tools.",
+            };
+    },
+    register(runtime, context) {
+        return runtime.run([
+            "mcp",
+            "add",
+            MCP_SERVER_NAME,
+            "--command",
+            context.nodeExecutable,
+            "--args",
+            context.serverEntryPath,
+        ], "\n");
+    },
+    registrationAccepted(result) {
+        return result.exitCode === 0 && /saved\s+'ast'/i.test(result.stdout);
+    },
+};
+export const AGENT_TARGETS = [
+    {
+        id: "claude",
+        label: "Claude Code",
+        command: "claude",
+        skillTarget: "claude",
+        mcp: claudeMcp,
+    },
+    {
+        id: "hermes",
+        label: "Hermes",
+        command: "hermes",
+        skillTarget: "hermes",
+        mcp: hermesMcp,
+    },
+];
+export const AGENT_IDS = AGENT_TARGETS.map((target) => target.id);
+export function getAgentTarget(id) {
+    const target = AGENT_TARGETS.find((candidate) => candidate.id === id);
+    if (target === undefined)
+        throw new Error(`Unsupported agent target: ${id}`);
+    return target;
+}

package/dist/services/context-builder.js

@@ -2,9 +2,10 @@ import { Buffer } from "node:buffer";
 import path from "node:path";
 import { buildFileOutline, nodeSourceWithLocation } from "./outline.js";
 import { paginate } from "./pagination.js";
-import { findDeclarationByName, getSourceFileOrThrow } from "./project.js";
+import { isCooperativeInterruption, NO_REQUEST_CONTEXT, } from "./request-context.js";
+import { findDeclarationByName, getSourceFileOrThrow, reportSymbolIndexFailure, } from "./project.js";
 import { collectSymbolReferences } from "./references.js";
-import { searchProjectSymbols, sourceFileSymbols, symbolMatchRank, } from "./symbols.js";
+import { searchProjectSymbolsPage, searchProjectSymbolsPageWithIndex, sourceFileSymbols, symbolMatchRank, } from "./symbols.js";
 export const EXPLORE_DEFAULT_LIMIT = 20;
 export const EXPLORE_DEFAULT_REFERENCE_LIMIT = 20;
 export const EXPLORE_DEFAULT_MAX_BYTES = 64 * 1024;
@@ -48,14 +49,14 @@ function recordFromOutlineSymbol(sourceFile, projectRoot, symbol) {
         signature: symbol.signature,
     };
 }
-function fileRecords(sourceFile, projectRoot) {
-    const outline = buildFileOutline(sourceFile);
+function fileRecords(sourceFile, projectRoot, requestContext) {
+    const outline = buildFileOutline(sourceFile, requestContext);
     if (outline.symbols.length > 0) {
         return outline.symbols.map((symbol) => recordFromOutlineSymbol(sourceFile, projectRoot, symbol));
     }
-    return sourceFileSymbols(sourceFile, projectRoot);
+    return sourceFileSymbols(sourceFile, projectRoot, requestContext);
 }
-function projectRecords(context, request) {
+async function projectRecords(context, request, requestContext) {
     const { project, projectRoot } = context;
     if (request.filePath) {
         const sourceFile = getSourceFileOrThrow(project, request.filePath);
@@ -63,7 +64,7 @@ function projectRecords(context, request) {
         const requestedSymbolPath = request.symbolPath;
         if (requestedSymbolPath) {
             const node = findDeclarationByName(sourceFile, requestedSymbolPath);
-            const record = fileRecords(sourceFile, projectRoot).find((candidate) => candidate.symbol_path === requestedSymbolPath ||
+            const record = fileRecords(sourceFile, projectRoot, requestContext).find((candidate) => candidate.symbol_path === requestedSymbolPath ||
                 candidate.selector === requestedSymbolPath ||
                 (candidate.symbol_path === requestedSymbolPath.split("@")[0] &&
                     candidate.line === node.getStartLineNumber()));
@@ -71,29 +72,47 @@ function projectRecords(context, request) {
                 throw new Error(`Symbol "${requestedSymbolPath}" could not be projected from ${file}.`);
             }
             return {
+                context,
                 route: "symbol",
                 file,
                 symbol: record.selector,
                 records: [record],
             };
         }
-        const records = fileRecords(sourceFile, projectRoot)
+        const records = fileRecords(sourceFile, projectRoot, requestContext)
             .filter((record) => !request.query || matchesQuery(record, request.query))
             .filter((record) => !request.kinds || request.kinds.includes(record.kind));
-        return { route: "file", file, symbol: null, records: sortRecords(records, request.query) };
+        return {
+            context,
+            route: "file",
+            file,
+            symbol: null,
+            records: sortRecords(records, request.query),
+        };
     }
     if (!request.query) {
         throw new Error("ast_explore requires query, file_path, or both file_path and symbol_path.");
     }
+    let effectiveContext = context;
+    const indexedPage = await searchProjectSymbolsPageWithIndex(project, projectRoot, context.status.project, context.symbolIndex, context.symbolIndexReady, {
+        query: request.query,
+        kinds: request.kinds,
+        fileFilter: request.fileFilter,
+    }, request.offset, request.limit, async (reason) => {
+        effectiveContext = (await reportSymbolIndexFailure(projectRoot, reason)) ?? effectiveContext;
+    }, requestContext);
     return {
+        context: effectiveContext,
         route: "query",
         file: null,
         symbol: null,
-        records: searchProjectSymbols(project, projectRoot, {
-            query: request.query,
-            kinds: request.kinds,
-            fileFilter: request.fileFilter,
-        }),
+        page: indexedPage ??
+            searchProjectSymbolsPage(effectiveContext.project, effectiveContext.projectRoot, {
+                query: request.query,
+                kinds: request.kinds,
+                fileFilter: request.fileFilter,
+            }, request.offset, request.limit, requestContext),
+        records: [],
     };
 }
 function projectSymbol(detail, record) {
@@ -120,16 +139,20 @@ function effectiveExpansion(request) {
         references: request.includeReferences ?? request.detail === "full",
     };
 }
-export function buildExploreContext(context, request) {
-    const routed = projectRecords(context, request);
-    const page = paginate(routed.records, request.offset, request.limit);
+export async function buildExploreContext(context, request, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    const routed = await projectRecords(context, request, requestContext);
+    requestContext.checkpoint();
+    const effectiveContext = routed.context;
+    const page = routed.page ?? paginate(routed.records, request.offset, request.limit);
     const expansion = effectiveExpansion(request);
     const unresolved = [];
     const evidence = [];
     for (const record of page.items) {
+        requestContext.checkpoint();
         let sourceFile;
         try {
-            sourceFile = getSourceFileOrThrow(context.project, record.file);
+            sourceFile = getSourceFileOrThrow(effectiveContext.project, record.file);
         }
         catch {
             unresolved.push({ selector: record.selector, reason: "source_unresolved" });
@@ -145,13 +168,16 @@ export function buildExploreContext(context, request) {
         }
         let source;
         let references;
-        if (expansion.source)
-            source = nodeSourceWithLocation(node, context.projectRoot);
+        if (expansion.source) {
+            source = nodeSourceWithLocation(node, effectiveContext.projectRoot, requestContext);
+        }
         if (expansion.references) {
             try {
-                references = collectSymbolReferences(node, context.projectRoot, record.selector, true, request.referenceDetail, 0, request.referenceLimit);
+                references = collectSymbolReferences(node, effectiveContext.projectRoot, record.selector, true, request.referenceDetail, 0, request.referenceLimit, requestContext);
             }
-            catch {
+            catch (error) {
+                if (isCooperativeInterruption(error))
+                    throw error;
                 unresolved.push({ selector: record.selector, reason: "references_unresolved" });
             }
         }
@@ -167,9 +193,10 @@ export function buildExploreContext(context, request) {
     let returnedSymbols = [...symbols];
     let returnedEvidence = [...evidence];
     let reason = page.has_more ? "record_limit" : null;
-    let result = createResult(context, request, routed.route, routed.file, routed.symbol, returnedSymbols, returnedEvidence, page.total, unresolved, reason);
+    let result = createResult(effectiveContext, request, routed.route, routed.file, routed.symbol, returnedSymbols, returnedEvidence, page.total, unresolved, reason);
     while (jsonBytes(result) > request.maxBytes &&
         (returnedEvidence.length > 0 || returnedSymbols.length > 0)) {
+        requestContext.checkpoint();
         reason = "byte_limit";
         if (returnedEvidence.length > 0) {
             returnedEvidence = returnedEvidence.slice(0, -1);
@@ -179,8 +206,9 @@ export function buildExploreContext(context, request) {
             const selectors = new Set(returnedSymbols.map((symbol) => symbol.selector));
             returnedEvidence = returnedEvidence.filter((item) => selectors.has(item.selector));
         }
-        result = createResult(context, request, routed.route, routed.file, routed.symbol, returnedSymbols, returnedEvidence, page.total, unresolved, reason);
+        result = createResult(effectiveContext, request, routed.route, routed.file, routed.symbol, returnedSymbols, returnedEvidence, page.total, unresolved, reason);
     }
+    requestContext.checkpoint();
     const usedBytes = jsonBytes(result);
     return {
         ...result,

package/dist/services/diagnostics.js

@@ -1,6 +1,8 @@
 import path from "node:path";
 import { DiagnosticCategory, ts } from "ts-morph";
-export function normalizeDiagnostic(diagnostic, projectRoot) {
+import { NO_REQUEST_CONTEXT } from "./request-context.js";
+export function normalizeDiagnostic(diagnostic, projectRoot, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
     const sourceFile = diagnostic.getSourceFile();
     const start = diagnostic.getStart();
     const location = sourceFile && start !== undefined ? sourceFile.getLineAndColumnAtPos(start) : undefined;
@@ -21,14 +23,16 @@ function identity(diagnostic) {
         diagnostic.message,
     ]);
 }
-function subtract(candidates, baseline) {
+function subtract(candidates, baseline, requestContext) {
     const counts = new Map();
     for (const diagnostic of baseline) {
+        requestContext.checkpoint();
         const key = identity(diagnostic);
         counts.set(key, (counts.get(key) ?? 0) + 1);
     }
     const difference = [];
     for (const diagnostic of candidates) {
+        requestContext.checkpoint();
         const key = identity(diagnostic);
         const remaining = counts.get(key) ?? 0;
         if (remaining > 0) {
@@ -40,9 +44,10 @@ function subtract(candidates, baseline) {
     }
     return difference;
 }
-export function compareDiagnostics(before, after) {
-    const added = subtract(after, before);
-    const removed = subtract(before, after);
+export function compareDiagnostics(before, after, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    const added = subtract(after, before, requestContext);
+    const removed = subtract(before, after, requestContext);
     return {
         added,
         removed,

package/dist/services/file-fingerprints.js

@@ -0,0 +1,104 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+function isMissingFileError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        (error.code === "ENOENT" || error.code === "ENOTDIR"));
+}
+function resolveCandidatePath(filePath) {
+    try {
+        return fs.realpathSync(filePath);
+    }
+    catch (error) {
+        if (!isMissingFileError(error))
+            throw error;
+        return path.resolve(filePath);
+    }
+}
+function assertRegularFile(filePath) {
+    const stats = fs.statSync(filePath, { bigint: true });
+    if (!stats.isFile()) {
+        throw new Error(`Cannot fingerprint non-file path: ${filePath}`);
+    }
+    return stats;
+}
+function metadataMatches(previous, current) {
+    return (previous.size_bytes === current.size_bytes &&
+        previous.mtime_ns === current.mtime_ns &&
+        previous.device === current.device &&
+        previous.inode === current.inode);
+}
+export function hashBytes(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export function captureFileFingerprint(filePath, previous, options = {}) {
+    const canonicalPath = fs.realpathSync(filePath);
+    const stats = assertRegularFile(canonicalPath);
+    const metadata = {
+        size_bytes: Number(stats.size),
+        mtime_ns: stats.mtimeNs.toString(),
+        device: stats.dev.toString(),
+        inode: stats.ino.toString(),
+    };
+    if (!Number.isSafeInteger(metadata.size_bytes)) {
+        throw new Error(`File size is outside the safe integer range: ${canonicalPath}`);
+    }
+    if (previous && metadataMatches(previous, metadata) && !options.verifyContentHash) {
+        return {
+            ...previous,
+            file_path: canonicalPath,
+        };
+    }
+    return {
+        file_path: canonicalPath,
+        ...metadata,
+        content_hash: hashBytes(fs.readFileSync(canonicalPath)),
+    };
+}
+export function collectFileFingerprints(filePaths, previous = new Map(), options = {}) {
+    const files = new Map();
+    const missing = new Set();
+    for (const filePath of new Set(filePaths)) {
+        const candidatePath = resolveCandidatePath(filePath);
+        try {
+            const previousFingerprint = previous.get(candidatePath);
+            const fingerprint = captureFileFingerprint(candidatePath, previousFingerprint, options);
+            files.set(fingerprint.file_path, fingerprint);
+        }
+        catch (error) {
+            if (!isMissingFileError(error))
+                throw error;
+            missing.add(candidatePath);
+        }
+    }
+    return {
+        files,
+        missing: [...missing].sort(),
+    };
+}
+export function compareFileFingerprints(previous, current) {
+    const added = [];
+    const changed = [];
+    const deleted = [];
+    const unchanged = [];
+    const paths = [...new Set([...previous.keys(), ...current.keys()])].sort();
+    for (const filePath of paths) {
+        const before = previous.get(filePath);
+        const after = current.get(filePath);
+        if (!before && after) {
+            added.push(filePath);
+        }
+        else if (before && !after) {
+            deleted.push(filePath);
+        }
+        else if (before && after && before.content_hash !== after.content_hash) {
+            changed.push(filePath);
+        }
+        else {
+            unchanged.push(filePath);
+        }
+    }
+    return { added, changed, deleted, unchanged };
+}

package/dist/services/file-snapshot.js

@@ -2,6 +2,7 @@ import { TextDecoder } from "node:util";
 import { lstat, readFile, realpath } from "node:fs/promises";
 import path from "node:path";
 import { getSourceFileOrThrow } from "./project.js";
+import { NO_REQUEST_CONTEXT } from "./request-context.js";
 import { hashBytes } from "./workspace.js";
 export const DEFAULT_FILE_LINE_LIMIT = 200;
 export const MAX_FILE_LINE_LIMIT = 500;
@@ -58,27 +59,33 @@ function compilerSnapshotHashes(sourceText) {
     }
     return hashes;
 }
-export async function readFileSnapshot(project, projectRoot, filePath, options) {
+export async function readFileSnapshot(project, projectRoot, filePath, options, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
     assertBoundedRange(options);
     rejectTraversalPath(filePath);
     const sourceFile = getSourceFileOrThrow(project, filePath);
+    requestContext.checkpoint();
     const canonicalRoot = await realpath(projectRoot);
     const sourcePath = sourceFile.getFilePath();
     const canonicalFile = await realpath(sourcePath);
+    requestContext.checkpoint();
     if (!isContained(canonicalRoot, canonicalFile)) {
         throw new Error("Source file resolves outside the configured project root.");
     }
     const stat = await lstat(canonicalFile);
+    requestContext.checkpoint();
     if (!stat.isFile()) {
         throw new Error("Source file is not a regular file.");
     }
     const bytes = await readFile(canonicalFile);
+    requestContext.checkpoint();
     const source = decodeUtf8(bytes, projectRelative(canonicalRoot, canonicalFile));
     const fileHash = hashBytes(bytes);
     const compilerHashes = compilerSnapshotHashes(sourceFile.getFullText());
     const snapshotState = compilerHashes.includes(fileHash) ? "fresh" : "stale";
     const allLines = splitLines(source);
     const selectedLines = allLines.slice(options.offset, options.offset + options.limit);
+    requestContext.checkpoint();
     return {
         file: projectRelative(canonicalRoot, canonicalFile),
         range: {