ast-mcp-server 0.11.1 → 0.12.0

package/dist/tools/scaffold_class.js

@@ -3,6 +3,7 @@ import { prepareScaffoldClass } from "../services/operations.js";
 import { createRequestContext } from "../services/request-context.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 import { PreparedOperationOutputSchema, serializePreparedOperation } from "./operation-schema.js";
+const TOOL_NAME = "ast_scaffold_class";
 const IdentifierSchema = z.string().min(1).max(200);
 const TypeTextSchema = z.string().min(1).max(10_000);
 const AccessSchema = z.enum(["public", "protected", "private"]);
@@ -111,7 +112,7 @@ export function registerScaffoldClass(server) {
     // The SDK compatibility overload exceeds TypeScript's instantiation depth for this schema.
     // Keep the complete runtime schema and isolate only the registrar type.
     const registerTool = server.registerTool.bind(server);
-    registerTool("ast_scaffold_class", {
+    registerTool(TOOL_NAME, {
         title: "Prepare Class Scaffold",
         description: "Prepares a hash-bound new TypeScript class file without writing it. Each method body throws an explicit not-implemented error. Review the diff, then apply the returned operation_id and plan_hash with ast_apply_operation.",
         inputSchema: ScaffoldClassInputSchema,
@@ -141,7 +142,9 @@ export function registerScaffoldClass(server) {
             return structuredResult(structuredContent);
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_scaffold_class", args.project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, args.project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerScaffoldClass, compatibility: "required", effect: "prepare", batch: "prepare", directOutputFormats: Object.freeze(["json"]) });

package/dist/tools/search_symbols.js

@@ -4,6 +4,7 @@ import { withProject, reportSymbolIndexFailure } from "../services/project.js";
 import { createRequestContext } from "../services/request-context.js";
 import { searchProjectSymbolsPage, searchProjectSymbolsPageWithIndex, } from "../services/symbols.js";
 import { createToolErrorContext, errorResult, formattedResult, ToolOutputFormatInputSchema, } from "./result.js";
+const TOOL_NAME = "ast_search_symbols";
 const SEARCH_DEFAULT_LIMIT = 20;
 const SearchDetailSchema = z.enum(["selectors", "summary", "full"]).default("summary");
 const AstSearchSymbolsInputSchema = z.object({
@@ -77,7 +78,7 @@ function projectSymbols(detail, symbols) {
     return symbols.map(({ file, selector, kind }) => ({ file, selector, kind }));
 }
 export function registerSearchSymbols(server) {
-    server.registerTool("ast_search_symbols", {
+    server.registerTool(TOOL_NAME, {
         title: "Search project symbols",
         description: "Ranks structural declarations and returns exact file/symbol selectors for downstream AST tools.",
         inputSchema: AstSearchSymbolsInputSchema,
@@ -108,7 +109,9 @@ export function registerSearchSymbols(server) {
             return formattedResult(outputSchema, structuredContent, output_format);
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_search_symbols", project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerSearchSymbols, compatibility: "required", effect: "read", batch: "read", directOutputFormats: Object.freeze(["json", "toon"]) });

package/dist/worker-runtime.js

@@ -0,0 +1,126 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+import { beginProjectShutdown, closeDrainedProjectSessions, getProjectRuntimeShutdownSnapshot, prepareProjectRuntimeForStartup, waitForProjectCompletionCriticalOperationsToDrain, waitForProjectOperationsToDrain, } from "./services/project.js";
+import { RuntimeActivityTracker } from "./services/runtime-activity.js";
+import { readRuntimePolicy } from "./services/runtime-policy.js";
+import { emitIncompleteShutdownEvent, ShutdownCoordinator, } from "./services/shutdown.js";
+function emitShutdownFailureEvent() {
+    process.stderr.write(`${JSON.stringify({ event: "shutdown_failed", version: 1 })}\n`);
+}
+export async function runStdioServer(options = {}) {
+    if (options.server && !options.runtimeActivity) {
+        throw new Error("An injected MCP server requires its runtime activity tracker.");
+    }
+    prepareProjectRuntimeForStartup();
+    const runtimeActivity = options.runtimeActivity ?? new RuntimeActivityTracker();
+    runtimeActivity.prepareForStartup();
+    const server = options.server ?? createServer({ runtimeActivity });
+    const transport = options.transport ?? new StdioServerTransport();
+    const send = transport.send.bind(transport);
+    transport.send = (message, sendOptions) => runtimeActivity.trackSend(() => send(message, sendOptions));
+    const runtimePolicy = options.runtimePolicy ?? readRuntimePolicy();
+    const installProcessHandlers = options.installProcessHandlers ?? true;
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const protocol = server.server;
+    const previousTransportClose = protocol.onclose;
+    let listenersInstalled = false;
+    let terminalHandlerInstalled = false;
+    const onSigint = () => requestFromRuntime("sigint");
+    const onSigterm = () => requestFromRuntime("sigterm");
+    const onStdinEnd = () => requestFromRuntime("stdin_eof");
+    const onStdinClose = () => requestFromRuntime("stdin_eof");
+    const onTransportClose = () => {
+        previousTransportClose?.();
+        requestFromRuntime("transport_closed");
+    };
+    const removeLifecycleListeners = () => {
+        if (listenersInstalled) {
+            process.off("SIGINT", onSigint);
+            process.off("SIGTERM", onSigterm);
+            process.stdin.off("end", onStdinEnd);
+            process.stdin.off("close", onStdinClose);
+            listenersInstalled = false;
+        }
+        if (protocol.onclose === onTransportClose)
+            protocol.onclose = previousTransportClose;
+    };
+    const coordinator = new ShutdownCoordinator({
+        drainTimeoutMs: runtimePolicy.shutdownDrainTimeoutMs,
+        stopAdmissionAndCancel: () => {
+            runtimeActivity.beginShutdown();
+            return beginProjectShutdown();
+        },
+        getDrainSnapshot: getProjectRuntimeShutdownSnapshot,
+        waitForDrain: async () => {
+            await Promise.all([waitForProjectOperationsToDrain(), runtimeActivity.waitForIdle()]);
+        },
+        waitForCompletionCriticalOperationsToDrain: waitForProjectCompletionCriticalOperationsToDrain,
+        closeMcp: async () => {
+            await server.close();
+        },
+        closeProjects: closeDrainedProjectSessions,
+        emitIncompleteShutdown: emitIncompleteShutdownEvent,
+        onCompletionCriticalWait: options.onCompletionCriticalWait,
+    });
+    let lifecycleCompletion;
+    function requestShutdown(trigger) {
+        lifecycleCompletion ??= coordinator.shutdown(trigger).finally(removeLifecycleListeners);
+        return lifecycleCompletion;
+    }
+    function requestFromRuntime(trigger) {
+        try {
+            options.onRuntimeTrigger?.(trigger);
+        }
+        catch {
+            // Runtime observation is non-authoritative and must never interrupt shutdown.
+        }
+        const completion = requestShutdown(trigger);
+        if (terminalHandlerInstalled)
+            return;
+        terminalHandlerInstalled = true;
+        void completion
+            .then((result) => {
+            if (result.state === "forced_noncritical")
+                exit(1);
+        })
+            .catch(() => {
+            emitShutdownFailureEvent();
+            exit(1);
+        });
+    }
+    protocol.onclose = onTransportClose;
+    if (installProcessHandlers) {
+        process.on("SIGINT", onSigint);
+        process.on("SIGTERM", onSigterm);
+        process.stdin.once("end", onStdinEnd);
+        process.stdin.once("close", onStdinClose);
+        listenersInstalled = true;
+    }
+    try {
+        await server.connect(transport);
+    }
+    catch (error) {
+        await requestShutdown("requested").catch(() => undefined);
+        throw error;
+    }
+    if (options.logStartup ?? true)
+        process.stderr.write("ast-mcp-server running over stdio.\n");
+    return Object.freeze({
+        shutdown: (trigger = "requested") => requestShutdown(trigger),
+        shutdownGraceMs: runtimePolicy.shutdownDrainTimeoutMs,
+        snapshot: () => {
+            const runtime = runtimeActivity.snapshot(), project = getProjectRuntimeShutdownSnapshot();
+            return Object.freeze({
+                runtime_admission: runtime.admission,
+                active_requests: runtime.active_requests,
+                active_sends: runtime.active_sends,
+                project_admission: project.admission,
+                session_count: project.session_count,
+                active_operations: project.active_operations,
+                queued_operations: project.queued_operations,
+                completion_critical_operations: project.completion_critical_operations,
+                mutation_history: project.mutation_history,
+            });
+        },
+    });
+}

package/docs/support.md

@@ -1,20 +1,20 @@
 # Support policy
 
-This document defines the supported platform, runtime, persistence, and operational boundary for published `ast-mcp-server` v0.10.0 and the local `0.11.1` recovery candidate.
+This document defines the supported platform, runtime, persistence, and operational boundary for published `ast-mcp-server` v0.11.2 and the local `0.12.0` release candidate.
 
 ## Supported release target
 
 | Environment                                                                   | Status      | Contract                                                                                      |
 | ----------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------- |
 | Linux x64 with required GNU coreutils and procfs, Node.js 22.5.0              | Historical  | Immutable v0.8.1 release evidence; not the runtime floor of the published or candidate lines. |
-| Linux x64 with required GNU coreutils and procfs, exact Node.js 22.13.0       | Supported   | Published v0.10.0 and local 0.11.1 matrices, each bound to its own package and tree bytes.    |
-| Linux x64 with required GNU coreutils and procfs, current Node.js 24 line     | Supported   | Published v0.10.0 and local 0.11.1 matrices, each bound to its own package and tree bytes.    |
+| Linux x64 with required GNU coreutils and procfs, exact Node.js 22.13.0       | Supported   | Published v0.11.2 and local 0.12.0 matrices, each bound to its own package and tree bytes.    |
+| Linux x64 with required GNU coreutils and procfs, current Node.js 24 line     | Supported   | Published v0.11.2 and local 0.12.0 matrices, each bound to its own package and tree bytes.    |
 | Other Linux architectures or systems without the required filesystem features | Unverified  | Not supported until equivalent architecture, mutation, and filesystem-publication gates pass. |
 | macOS                                                                         | Unverified  | Not supported until equivalent filesystem, process, package, mutation, and canary gates pass. |
 | Windows                                                                       | Unverified  | Not supported until equivalent filesystem, process, package, mutation, and canary gates pass. |
 | Remote, untrusted, or multi-tenant service use                                | Unsupported | No network authentication, sandbox, or tenant-isolation boundary is provided.                 |
 
-The local `0.11.1` recovery candidate requires Node.js `>=22.13.0`; its matrix targets exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.10.0 retains its immutable `>=22.13.0` metadata and exact Node.js 22.13.0/24 release evidence. The earlier v0.8.1 Node.js 22.5.0/24 matrix remains historical evidence for those bytes only. A future runtime satisfying an engine range is not automatically a verified release target.
+The local `0.12.0` release candidate requires Node.js `>=22.13.0`; its matrix targets exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.11.2 retains its immutable `>=22.13.0` metadata and exact Node.js 22.13.0/24 release evidence. The earlier v0.8.1 Node.js 22.5.0/24 matrix remains historical evidence for those bytes only. A future runtime satisfying an engine range is not automatically a verified release target.
 
 The checked-evidence freezer requires GNU coreutils 9.7 `mv` with `--update=none-fail`, `--no-copy`, and `--no-target-directory`. Managed setup-file mutation additionally requires that same `mv` with `--exchange`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, `O_DIRECTORY`, and `O_NOFOLLOW`. It fails closed when any verified Linux primitive is unavailable. Equivalent publication, exchange, descriptor-link, and descriptor-relative mutation semantics have not been verified on other operating systems or architectures.
 
@@ -32,9 +32,25 @@ The server does not provide:
 
 Operation locks coordinate cooperating same-user processes. They do not stop editors, network filesystems, or hostile same-user writers. Report-set freezer coordination likewise assumes cooperating same-UID processes and cannot defend checked evidence against a malicious process with the same filesystem authority. The freezer guarantees no-replace atomic visibility of the checked directory; it does not claim persistence across sudden power loss because parent-directory `fsync` durability is not established.
 
+## Optional supervised compiler worker
+
+The default and rollback remain `AST_COMPILER_WORKER_MODE=in_process`. Explicit `supervised` mode keeps one lightweight stdio parent connected to one disposable compiler child per connection:
+
+```bash
+AST_COMPILER_WORKER_MODE=supervised \
+AST_COMPILER_WORKER_IDLE_TTL_MS=60000 \
+ast-mcp-server
+```
+
+The parent waits for `ready` before replaying bounded initialization state. Generation-affine forwarding and cancellation reject stale settlements and do not retry forwarded calls. Recycling requires stable parent and child quiescence; mutation history, live leases, and completion-critical work keep the child pinned. Parent death closes admission and permits only completion-critical drain before exit.
+
+Set the TTL to `0` to disable recycling without removing the relay, or select `in_process` to remove the worker boundary. No shared daemon, pool, cross-client deduplication, default promotion, or automatic mutation-plan repair is provided.
+
+The scoped Linux evidence passed on exact Node.js 22.13.0 and the governed Node.js 24 line: three parents each completed three load/idle/respawn cycles with at least 80% PSS-delta reclamation and no upward trend. Respawns retained the compiler fingerprint, recorded six SQLite hits, reused exactly 400 files, rebuilt zero, and returned equivalent reads. Diagnostics remained bounded and redacted, and parent-death inspection found zero orphan processes. These results do not establish support for macOS, Windows, or other Linux environments.
+
 ## Symbol-index persistence
 
-Published v0.10.0 and the local `0.11.1` recovery candidate select native SQLite when the persistence setting is absent or explicitly `enabled`; operators requiring no persistent index state must set `disabled` explicitly:
+Published v0.11.2 and the local `0.12.0` release candidate select native SQLite when the persistence setting is absent or explicitly `enabled`; operators requiring no persistent index state must set `disabled` explicitly:
 
 ```bash
 AST_SYMBOL_INDEX_PERSISTENCE=disabled \
@@ -64,7 +80,7 @@ Both commands are bounded and path-free. Clear preflights the tree, refuses unsa
 
 ## Production-readiness acceptance
 
-The four retained Linux x64 production-readiness reports cover `ast-mcp-server` and `x-scraper` under Node.js 22.5.0 and Node.js 24 for package version 0.6.0, commit `2d0b21bbb80fae1acfca6a85d5891d87e68b59c1`, and tree `af931d49769fabdf06f623965a6cfe1f9afb8a81`. They are historical integration evidence only: they are not reattributed to v0.8.1, published-next v0.9.0 or v0.9.1, the local 0.9.2 candidate, published v0.10.0, published-next v0.11.0, or the local v0.11.1 recovery candidate. The exact 0.9.0 and 0.9.1 release matrices remain historical evidence for their immutable published-next bytes, the exact 0.9.2 matrix remains historical local-candidate evidence, the exact 0.10.0 matrix remains historical published-release evidence, and the exact 0.11.0 matrix remains historical evidence for its immutable published-next bytes before registry verification exposed verifier drift. A separate exact 0.11.1 release matrix is the recovery-candidate gate for current repository bytes under both supported runtime lines, including local-registry managed-asset verification; none of these matrices rebinds the older retained reports. MCP-PROD-404 remains normative for admission:
+The four retained Linux x64 production-readiness reports cover `ast-mcp-server` and `x-scraper` under Node.js 22.5.0 and Node.js 24 for package version 0.6.0, commit `2d0b21bbb80fae1acfca6a85d5891d87e68b59c1`, and tree `af931d49769fabdf06f623965a6cfe1f9afb8a81`. They are historical integration evidence only: they are not reattributed to v0.8.1, published-next v0.9.0 or v0.9.1, the local 0.9.2 candidate, published v0.10.0, published-next v0.11.0 or v0.11.1, published v0.11.2, or the local v0.12.0 release candidate. The exact 0.9.0 and 0.9.1 release matrices remain historical evidence for their immutable published-next bytes, the exact 0.9.2 matrix remains historical local-candidate evidence, the exact 0.10.0 matrix remains historical published-release evidence, the exact 0.11.0 and 0.11.1 matrices remain historical evidence for their immutable published-next bytes before public-registry verification exposed their distinct verifier defects, and the exact 0.11.2 matrix remains historical published-release evidence. A separate exact 0.12.0 release matrix is the release-candidate gate for current repository bytes under both supported runtime lines, including bounded diagnostic aggregates, catalog-derived tool capability projections, and their independent release oracles; none of these matrices rebinds the older retained reports. MCP-PROD-404 remains normative for admission:
 
 - zero semantic mismatches across disabled, cold, warm, restart, and rollback reads;
 - byte-identical real-repository status and worktree trees;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-mcp-server",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
   "keywords": [
     "mcp",
@@ -49,7 +49,7 @@
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
-    "test": "vitest run",
+    "test": "vitest run --exclude test/supervised-worker.integration.test.ts && yarn build && vitest run test/supervised-worker.integration.test.ts --no-file-parallelism",
     "test:watch": "vitest",
     "test:mcp": "yarn build && node scripts/mcp-smoke.mjs",
     "test:lifecycle": "yarn build && node scripts/mcp-lifecycle-smoke.mjs",
@@ -97,5 +97,5 @@
     "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"
   },
-  "gitHead": "7aee46639d887a406c20c10fd66de7fa179d9e92"
+  "gitHead": "3991d0a74e672c6c4d3fbd1c8bbb1a60009515ec"
 }

package/skills/structural-code-editing/SKILL.md

@@ -4,7 +4,7 @@ description: "Trigger: navegar, analizar o editar TypeScript/JavaScript con el c
 license: "ISC"
 metadata:
   author: "yail"
-  version: "4.5.0"
+  version: "4.6.0"
   hermes:
     tags: ["typescript", "javascript", "ast", "refactoring", "mcp"]
     homepage: "https://github.com/yailPeralta/ast-mcp-server"
@@ -18,7 +18,7 @@ Cargar este skill antes de navegar semánticamente, analizar impacto o referenci
 
 No forzar un roundtrip AST para Markdown, configuración, comentarios ni una edición textual trivial en un archivo ya conocido. Si las tools `ast_*` no están disponibles, declarar el fallback y no presentar búsquedas textuales como evidencia compiler-backed.
 
-The local 0.11.1 recovery candidate requires Node.js `>=22.13.0` and is verified with exact Node.js 22.13.0 plus the governed Node.js 24 line. Published v0.10.0 retains its immutable Node.js 22.13.0/24 release evidence.
+The local 0.12.0 release candidate requires Node.js `>=22.13.0` and is verified with exact Node.js 22.13.0 plus the governed Node.js 24 line. Published v0.11.2 retains its immutable Node.js 22.13.0/24 release evidence.
 
 ## Hard Rules
 
@@ -29,6 +29,18 @@ The local 0.11.1 recovery candidate requires Node.js `>=22.13.0` and is verified
 - Nunca reconstruir postimages desde un diff; después del apply, ejecutar el gate canónico del proyecto.
 - Conservar `correlation_id` en errores públicos sin exponer source, paths absolutos, argumentos, environment, cache, stacks ni credenciales.
 
+## Diagnostic aggregates
+
+`ast_get_diagnostics` keeps its existing response shape unless `include_aggregates: true` is requested. Enabled summaries cover the complete normalized snapshot, not only the selected raw page, and cap both code and file groups at 20.
+
+For each dimension, `groups.length + omitted_group_count = total_group_count` and group counts sum to `covered_diagnostic_count`. Code coverage plus omitted diagnostics equals the total; file coverage additionally includes `unfiled_diagnostic_count`. File groups expose normalized project-relative paths only and may include paths absent from the raw page.
+
+## Contributor contract
+
+Al agregar o modificar una tool, mantener schemas, metadata, annotations, handler, errores y serialización en su módulo. Exportar un descriptor congelado y ubicarlo deliberadamente en `src/tools/catalog.ts`; el catálogo solo admite hechos estáticos de efecto, batch, compatibilidad y formatos directos.
+
+Las expectativas de `tools/list` deben seguir siendo independientes: revisar el inventario y metadata completos antes de actualizar sus hashes, sin importar ni derivar valores desde el catálogo.
+
 ## Decision Gates
 
 | Situación                              | Acción                                                                 |

package/skills/structural-code-editing/releases.json

@@ -2,11 +2,11 @@
   "schema_version": 2,
   "algorithm": "sha256",
   "current": {
-    "version": "4.5.0",
+    "version": "4.6.0",
     "files": [
       {
         "path": "SKILL.md",
-        "sha256": "2729b30ff6b7344e6680c7ee02ab540bc6db9774ad7111f091cd356f8cc9d4ce"
+        "sha256": "d0048ffd9a585d00791540c6fa5e0bec91ff95b1448479678f85702e6b09be8a"
       },
       {
         "path": "references/operations.md",
@@ -79,6 +79,21 @@
       "version": "4.4.0",
       "sha256": "253b588c56d44c8f5565db3f33ce227d80c7c29aa6604d362844f44b1278385a",
       "npm_versions": ["0.10.0"]
+    },
+    {
+      "version": "4.5.0",
+      "sha256": "be757e8bd98733c7ee952d63a2805dcd9877becf651b4fcb6ab63d20f6546f21",
+      "npm_versions": ["0.11.0"]
+    },
+    {
+      "version": "4.5.0",
+      "sha256": "2729b30ff6b7344e6680c7ee02ab540bc6db9774ad7111f091cd356f8cc9d4ce",
+      "npm_versions": ["0.11.1"]
+    },
+    {
+      "version": "4.5.0",
+      "sha256": "18132b4b747d135e4ccfbca9e2190a9afb41e144cc06c31c5e6bc0f1571e11da",
+      "npm_versions": ["0.11.2"]
     }
   ]
 }