ast-mcp-server 0.6.0 → 0.7.1

package/dist/services/request-context.js

@@ -0,0 +1,42 @@
+export class RequestContextError extends Error {
+    code;
+    constructor(code) {
+        super(code === "REQUEST_CANCELLED" ? "Request cancelled." : "Operation deadline exceeded.");
+        this.name = "RequestContextError";
+        this.code = code;
+    }
+}
+export function isCooperativeInterruption(error) {
+    const code = error?.code;
+    return code === "REQUEST_CANCELLED" || code === "OPERATION_DEADLINE_EXCEEDED";
+}
+const neverAbortedSignal = new AbortController().signal;
+export const NO_REQUEST_CONTEXT = Object.freeze({
+    signal: neverAbortedSignal,
+    checkpoint() { },
+    enterCompletionCritical() { },
+});
+class ActiveRequestContext {
+    #completionCritical = false;
+    #requestSignal;
+    constructor(requestSignal) {
+        this.#requestSignal = requestSignal;
+    }
+    get signal() {
+        return this.#completionCritical ? neverAbortedSignal : this.#requestSignal;
+    }
+    checkpoint() {
+        if (!this.#completionCritical && this.#requestSignal.aborted) {
+            throw new RequestContextError("REQUEST_CANCELLED");
+        }
+    }
+    enterCompletionCritical() {
+        if (this.#completionCritical)
+            return;
+        this.checkpoint();
+        this.#completionCritical = true;
+    }
+}
+export function createRequestContext(signal) {
+    return signal === undefined ? NO_REQUEST_CONTEXT : new ActiveRequestContext(signal);
+}

package/dist/services/runtime-activity.js

@@ -0,0 +1,65 @@
+export class RuntimeActivityTracker {
+    #admission = "open";
+    #activeRequests = 0;
+    #activeSends = 0;
+    #idleWaiters = new Set();
+    #idleCheck;
+    get admission() {
+        return this.#admission;
+    }
+    prepareForStartup() {
+        if (this.#activeRequests !== 0 || this.#activeSends !== 0 || this.#idleWaiters.size !== 0) {
+            throw new Error("Cannot start runtime activity tracking while work remains active.");
+        }
+        this.#admission = "open";
+    }
+    beginShutdown() {
+        this.#admission = "closed";
+    }
+    async trackRequest(callback) {
+        this.#activeRequests += 1;
+        try {
+            return await callback();
+        }
+        finally {
+            this.#activeRequests -= 1;
+            this.#scheduleIdleCheck();
+        }
+    }
+    async trackSend(callback) {
+        this.#activeSends += 1;
+        try {
+            return await callback();
+        }
+        finally {
+            this.#activeSends -= 1;
+            this.#scheduleIdleCheck();
+        }
+    }
+    waitForIdle() {
+        return new Promise((resolve) => {
+            this.#idleWaiters.add(resolve);
+            this.#scheduleIdleCheck();
+        });
+    }
+    snapshot() {
+        return Object.freeze({
+            admission: this.#admission,
+            active_requests: this.#activeRequests,
+            active_sends: this.#activeSends,
+        });
+    }
+    #scheduleIdleCheck() {
+        if (this.#idleWaiters.size === 0 || this.#idleCheck !== undefined)
+            return;
+        this.#idleCheck = setImmediate(() => {
+            this.#idleCheck = undefined;
+            if (this.#activeRequests !== 0 || this.#activeSends !== 0)
+                return;
+            const waiters = [...this.#idleWaiters];
+            this.#idleWaiters.clear();
+            for (const resolve of waiters)
+                resolve();
+        });
+    }
+}

package/dist/services/runtime-logger.js

@@ -0,0 +1,50 @@
+import { Buffer } from "node:buffer";
+import { INTERNAL_ERROR_MESSAGE, MAX_PUBLIC_ERROR_RESPONSE_BYTES, sanitizePublicText, } from "./public-errors.js";
+export const MAX_RUNTIME_FAILURE_EVENT_BYTES = 8192;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const TOOL_NAME_PATTERN = /^ast_[a-z0-9_]{1,64}$/;
+const PROJECT_ID_PATTERN = /^project_[0-9a-f]{20}$/;
+const CONFIG_ID_PATTERN = /^config_[0-9a-f]{20}$/;
+function normalizeProjectIdentity(identity) {
+    if (identity === undefined || !PROJECT_ID_PATTERN.test(identity.project_id))
+        return {};
+    return {
+        project_id: identity.project_id,
+        ...(identity.config_id !== null && CONFIG_ID_PATTERN.test(identity.config_id)
+            ? { config_id: identity.config_id }
+            : {}),
+    };
+}
+export function renderToolFailureEvent(input) {
+    const identity = normalizeProjectIdentity(input.projectIdentity);
+    const event = {
+        event: "tool_failure",
+        version: 1,
+        correlation_id: UUID_PATTERN.test(input.correlationId)
+            ? input.correlationId
+            : "invalid-correlation-id",
+        tool: TOOL_NAME_PATTERN.test(input.toolName) ? input.toolName : "unknown_tool",
+        code: input.code,
+        message: sanitizePublicText(input.message),
+        ...(identity.project_id === undefined ? {} : { project_id: identity.project_id }),
+        ...(identity.config_id === undefined ? {} : { config_id: identity.config_id }),
+    };
+    let rendered = JSON.stringify(event);
+    if (Buffer.byteLength(rendered, "utf8") + 1 > MAX_RUNTIME_FAILURE_EVENT_BYTES) {
+        rendered = JSON.stringify({ ...event, message: INTERNAL_ERROR_MESSAGE });
+    }
+    if (Buffer.byteLength(rendered, "utf8") + 1 > MAX_RUNTIME_FAILURE_EVENT_BYTES) {
+        return JSON.stringify({
+            event: "tool_failure",
+            version: 1,
+            correlation_id: event.correlation_id,
+            tool: "unknown_tool",
+            code: "INTERNAL_ERROR",
+            message: INTERNAL_ERROR_MESSAGE.slice(0, MAX_PUBLIC_ERROR_RESPONSE_BYTES),
+        });
+    }
+    return rendered;
+}
+export function emitToolFailureEvent(input) {
+    process.stderr.write(`${renderToolFailureEvent(input)}\n`);
+}

package/dist/services/runtime-policy.js

@@ -0,0 +1,47 @@
+export const RUNTIME_POLICY_ENV_KEYS = Object.freeze([
+    "AST_MAX_PROJECT_SESSIONS",
+    "AST_MAX_QUEUED_OPERATIONS_PER_PROJECT",
+    "AST_QUEUE_WAIT_TIMEOUT_MS",
+    "AST_OPERATION_DEADLINE_MS",
+    "AST_SHUTDOWN_DRAIN_TIMEOUT_MS",
+]);
+function parseBoundedInteger(rawValue, defaultValue, minimum, maximum) {
+    if (rawValue === undefined)
+        return { value: defaultValue, reason: "default" };
+    if (typeof rawValue !== "string" || !/^-?\d+$/.test(rawValue)) {
+        return { value: defaultValue, reason: "invalid_integer" };
+    }
+    const value = Number(rawValue);
+    if (!Number.isSafeInteger(value)) {
+        return { value: defaultValue, reason: "invalid_integer" };
+    }
+    if (value < minimum || value > maximum) {
+        return { value: defaultValue, reason: "out_of_range" };
+    }
+    return { value, reason: "configured" };
+}
+export function parseRuntimePolicy(environment) {
+    const maxProjectSessions = parseBoundedInteger(environment.AST_MAX_PROJECT_SESSIONS, 8, 1, 32);
+    const maxQueuedOperationsPerProject = parseBoundedInteger(environment.AST_MAX_QUEUED_OPERATIONS_PER_PROJECT, 32, 1, 256);
+    const queueWaitTimeoutMs = parseBoundedInteger(environment.AST_QUEUE_WAIT_TIMEOUT_MS, 30_000, 100, 300_000);
+    const operationDeadlineMs = parseBoundedInteger(environment.AST_OPERATION_DEADLINE_MS, 120_000, 1_000, 900_000);
+    const shutdownDrainTimeoutMs = parseBoundedInteger(environment.AST_SHUTDOWN_DRAIN_TIMEOUT_MS, 10_000, 100, 60_000);
+    const reasons = Object.freeze({
+        AST_MAX_PROJECT_SESSIONS: maxProjectSessions.reason,
+        AST_MAX_QUEUED_OPERATIONS_PER_PROJECT: maxQueuedOperationsPerProject.reason,
+        AST_QUEUE_WAIT_TIMEOUT_MS: queueWaitTimeoutMs.reason,
+        AST_OPERATION_DEADLINE_MS: operationDeadlineMs.reason,
+        AST_SHUTDOWN_DRAIN_TIMEOUT_MS: shutdownDrainTimeoutMs.reason,
+    });
+    return Object.freeze({
+        maxProjectSessions: maxProjectSessions.value,
+        maxQueuedOperationsPerProject: maxQueuedOperationsPerProject.value,
+        queueWaitTimeoutMs: queueWaitTimeoutMs.value,
+        operationDeadlineMs: operationDeadlineMs.value,
+        shutdownDrainTimeoutMs: shutdownDrainTimeoutMs.value,
+        reasons,
+    });
+}
+export function readRuntimePolicy(environment = process.env) {
+    return parseRuntimePolicy(environment);
+}

package/dist/services/setup-wizard.js

@@ -1,8 +1,5 @@
-export const AGENT_IDS = ["claude", "hermes"];
-const AGENT_LABELS = {
-    claude: "Claude Code",
-    hermes: "Hermes",
-};
+import { AGENT_IDS, getAgentTarget } from "./agent-targets.js";
+export { AGENT_IDS } from "./agent-targets.js";
 function isAgentId(value) {
     return AGENT_IDS.includes(value);
 }
@@ -67,14 +64,14 @@ function renderSelectionQuestion(detections, validationMessage) {
         const detail = item.installed
             ? [item.version, item.executable].filter(Boolean).join(" · ")
             : "not installed";
-        return `  [${marker}] ${index + 1}. ${AGENT_LABELS[item.id]} (${detail})`;
+        return `  [${marker}] ${index + 1}. ${getAgentTarget(item.id).label} (${detail})`;
     })
         .join("\n");
     const validation = validationMessage === undefined ? "" : `\n${validationMessage}\n`;
     return `\nDetected agents (all installed agents are selected):\n${choices}\n${validation}\nEnter agents to deselect by number or name, 'none' to deselect all, or press Enter to keep all:\n> `;
 }
 function renderConfirmation(agents, validationMessage) {
-    const labels = agents.map((agent) => AGENT_LABELS[agent]).join(", ");
+    const labels = agents.map((agent) => getAgentTarget(agent).label).join(", ");
     const validation = validationMessage === undefined ? "" : `\n${validationMessage}\n`;
     return `${validation}\nSetup will install the MCP server and skill for: ${labels}.\nContinue? [Y/n] `;
 }

package/dist/services/shutdown.js

@@ -0,0 +1,93 @@
+function assertDrainTimeout(value) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > 300_000) {
+        throw new RangeError("drainTimeoutMs must be an integer in 1..300000.");
+    }
+}
+function boundedCount(value) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        return 0;
+    return Math.min(value, 2_147_483_647);
+}
+export function renderIncompleteShutdownEvent(trigger, snapshot) {
+    const event = {
+        event: "shutdown_incomplete",
+        version: 1,
+        state: "forced_noncritical",
+        trigger,
+        active_operations: boundedCount(snapshot.active_operations),
+        queued_operations: boundedCount(snapshot.queued_operations),
+        completion_critical_operations: boundedCount(snapshot.completion_critical_operations),
+    };
+    return JSON.stringify(event);
+}
+export function emitIncompleteShutdownEvent(trigger, snapshot) {
+    process.stderr.write(`${renderIncompleteShutdownEvent(trigger, snapshot)}\n`);
+}
+export class ShutdownCoordinator {
+    #options;
+    #completion;
+    constructor(options) {
+        assertDrainTimeout(options.drainTimeoutMs);
+        this.#options = options;
+    }
+    shutdown(trigger) {
+        this.#completion ??= this.#execute(trigger);
+        return this.#completion;
+    }
+    async #execute(trigger) {
+        this.#options.stopAdmissionAndCancel();
+        const drain = this.#options.waitForDrain();
+        while (true) {
+            const drainedWithinGrace = await this.#waitForBoundedDrain(drain);
+            if (drainedWithinGrace)
+                break;
+            const snapshot = this.#options.getDrainSnapshot();
+            if (snapshot.completion_critical_operations === 0) {
+                this.#options.emitIncompleteShutdown(trigger, snapshot);
+                return Object.freeze({ state: "forced_noncritical", trigger });
+            }
+            this.#observeCompletionCriticalWait(snapshot);
+            await this.#options.waitForCompletionCriticalOperationsToDrain();
+        }
+        await this.#closeResources();
+        return Object.freeze({ state: "complete", trigger });
+    }
+    #observeCompletionCriticalWait(snapshot) {
+        try {
+            this.#options.onCompletionCriticalWait?.(snapshot);
+        }
+        catch {
+            // Runtime observation is non-authoritative and must never interrupt shutdown.
+        }
+    }
+    async #waitForBoundedDrain(drain) {
+        let timer;
+        const graceExpired = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(false), this.#options.drainTimeoutMs);
+        });
+        try {
+            return await Promise.race([drain.then(() => true), graceExpired]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    async #closeResources() {
+        let firstError;
+        try {
+            await this.#options.closeMcp();
+        }
+        catch (error) {
+            firstError = error;
+        }
+        try {
+            await this.#options.closeProjects();
+        }
+        catch (error) {
+            firstError ??= error;
+        }
+        if (firstError !== undefined)
+            throw firstError;
+    }
+}

package/dist/services/symbol-index-limits.js

@@ -0,0 +1,5 @@
+export const MAX_SYMBOL_INDEX_QUERY_CANDIDATES = 10_000;
+export const MAX_SYMBOL_INDEX_SCANNED_SYMBOLS = 50_000;
+export const MAX_SYMBOL_INDEX_FILE_ENTRIES = 10_000;
+export const MAX_SYMBOL_INDEX_ROW_PAYLOAD_BYTES = 4 * 1024 * 1024;
+export const MAX_SYMBOL_INDEX_TOTAL_PAYLOAD_BYTES = 64 * 1024 * 1024;

package/dist/services/symbol-index-order.js

@@ -0,0 +1,13 @@
+export function compareSymbolIndexText(left, right) {
+    let leftIndex = 0;
+    let rightIndex = 0;
+    while (leftIndex < left.length && rightIndex < right.length) {
+        const leftCodePoint = left.codePointAt(leftIndex);
+        const rightCodePoint = right.codePointAt(rightIndex);
+        if (leftCodePoint !== rightCodePoint)
+            return leftCodePoint - rightCodePoint;
+        leftIndex += leftCodePoint > 0xffff ? 2 : 1;
+        rightIndex += rightCodePoint > 0xffff ? 2 : 1;
+    }
+    return left.length - right.length;
+}

package/dist/services/symbol-index-policy.js

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+const DEFAULT_BUSY_TIMEOUT_MS = 1_000;
+export const MAX_SYMBOL_INDEX_RUNTIME_COUNT = 1_000_000;
+export function addSymbolIndexRuntimeCount(current, increment = 1) {
+    if (!Number.isSafeInteger(current) || current < 0)
+        return MAX_SYMBOL_INDEX_RUNTIME_COUNT;
+    if (!Number.isSafeInteger(increment) || increment < 0)
+        return MAX_SYMBOL_INDEX_RUNTIME_COUNT;
+    return Math.min(MAX_SYMBOL_INDEX_RUNTIME_COUNT, current + increment);
+}
+export function createInitialSymbolIndexRuntimeObservability(policy = disabledPolicy("default")) {
+    return {
+        policy: policy.mode,
+        policy_reason: policy.reason,
+        backend: policy.backend,
+        state: "disabled",
+        operation: policy.backend === "sqlite" ? "miss" : "disabled",
+        last_operation: policy.backend === "sqlite" ? "miss" : "disabled",
+        loaded_entries: 0,
+        accepted_entries: 0,
+        rejected_entries: 0,
+        cache_hits: 0,
+        cache_misses: 0,
+        fallback_count: 0,
+        migration_count: 0,
+        corruption_count: 0,
+        write_failure_count: 0,
+        rebuilt_files: 0,
+        reused_files: 0,
+        removed_files: 0,
+        last_error: null,
+        last_successful_persistence_at: null,
+    };
+}
+function disabledPolicy(reason) {
+    return {
+        mode: "disabled",
+        backend: "memory",
+        cache_root: null,
+        busy_timeout_ms: DEFAULT_BUSY_TIMEOUT_MS,
+        reason,
+    };
+}
+function readBusyTimeout(value) {
+    if (!value)
+        return DEFAULT_BUSY_TIMEOUT_MS;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 && parsed <= 60_000
+        ? parsed
+        : DEFAULT_BUSY_TIMEOUT_MS;
+}
+export function readSymbolIndexPersistencePolicy(environment = process.env) {
+    const mode = environment.AST_SYMBOL_INDEX_PERSISTENCE ?? "disabled";
+    if (mode === "disabled")
+        return disabledPolicy("default");
+    if (mode === "enabled")
+        return disabledPolicy("enabled_not_released");
+    if (mode !== "canary")
+        return disabledPolicy("invalid_mode");
+    const cacheRoot = environment.AST_SYMBOL_INDEX_CACHE_ROOT;
+    if (!cacheRoot)
+        return disabledPolicy("cache_root_missing");
+    if (!path.isAbsolute(cacheRoot) || path.normalize(cacheRoot) !== cacheRoot) {
+        return disabledPolicy("cache_root_invalid");
+    }
+    return {
+        mode,
+        backend: "sqlite",
+        cache_root: cacheRoot,
+        busy_timeout_ms: readBusyTimeout(environment.AST_SYMBOL_INDEX_BUSY_TIMEOUT_MS),
+        reason: "default",
+    };
+}
+export function symbolIndexPolicyKey(policy) {
+    return [
+        policy.mode,
+        policy.backend,
+        policy.reason,
+        policy.cache_root ?? "",
+        policy.busy_timeout_ms,
+    ].join("\u0000");
+}
+export function symbolIndexCachePath(policy, project) {
+    if (policy.backend !== "sqlite" || !policy.cache_root)
+        return null;
+    const opaqueProjectKey = createHash("sha256")
+        .update(`${project.project_id}\u0000${project.config_id ?? ""}`)
+        .digest("hex");
+    return path.join(policy.cache_root, `symbol-index-${opaqueProjectKey}.sqlite`);
+}