ast-mcp-server 0.10.0 → 0.11.0

package/dist/services/upgrade-runtime.js

@@ -0,0 +1,157 @@
+import { execFile } from "node:child_process";
+import { chmod, copyFile, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rm, writeFile, } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { promisify } from "node:util";
+export class UpgradeCleanupError extends Error {
+    primaryCode;
+    code = "UPGRADE_CLEANUP_FAILED";
+    constructor(primaryCode) {
+        super("Upgrade temporary files could not be removed safely.");
+        this.primaryCode = primaryCode;
+        this.name = "UpgradeCleanupError";
+    }
+}
+const executeFile = promisify(execFile);
+async function npmCliFor(node, platform) {
+    const p = platform === "win32" ? path.win32 : path.posix;
+    const root = platform === "win32" ? p.dirname(node) : p.resolve(p.dirname(node), "..");
+    const candidates = platform === "win32"
+        ? [p.join(root, "node_modules", "npm", "bin", "npm-cli.js")]
+        : [
+            p.join(p.dirname(node), "npm"),
+            p.join(root, "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+        ];
+    for (const candidate of candidates) {
+        try {
+            const resolved = await realpath(candidate);
+            if ((await lstat(resolved)).isFile())
+                return resolved;
+        }
+        catch {
+            // Try the next layout owned by this Node installation.
+        }
+    }
+    return;
+}
+async function copyUserConfig(environment, destination) {
+    const source = environment.npm_config_userconfig ??
+        environment.NPM_CONFIG_USERCONFIG ??
+        path.join(environment.HOME ?? os.homedir(), ".npmrc");
+    try {
+        await copyFile(source, destination);
+        await chmod(destination, 0o600);
+    }
+    catch {
+        await writeFile(destination, "", { encoding: "utf8", mode: 0o600 });
+    }
+}
+async function restoreOwnerAccess(value) {
+    const info = await lstat(value);
+    if (info.isSymbolicLink())
+        return;
+    await chmod(value, info.isDirectory() ? 0o700 : 0o600);
+    if (info.isDirectory())
+        for (const child of await readdir(value))
+            await restoreOwnerAccess(path.join(value, child));
+}
+async function cleanupBoundary(boundary, removeTree = (value) => rm(value, { recursive: true, force: true })) {
+    try {
+        await restoreOwnerAccess(boundary);
+        await removeTree(boundary);
+    }
+    catch {
+        throw new UpgradeCleanupError();
+    }
+    try {
+        await lstat(boundary);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw new UpgradeCleanupError();
+    }
+    throw new UpgradeCleanupError();
+}
+export async function createUpgradeRuntime(executable, options = {}) {
+    const environment = options.environment ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const nodeExecutable = options.nodeExecutable ?? process.execPath;
+    const execute = options.execute ?? executeFile;
+    const boundary = await mkdtemp(path.join(options.temporaryParent ?? os.tmpdir(), "ast-tool-upgrade-"));
+    try {
+        const cache = path.join(boundary, "cache");
+        const logs = path.join(boundary, "logs");
+        const userConfig = path.join(boundary, "npmrc");
+        await Promise.all([mkdir(cache), mkdir(logs), copyUserConfig(environment, userConfig)]);
+        const npmEnvironment = {
+            ...environment,
+            npm_config_cache: cache,
+            npm_config_logs_dir: logs,
+            npm_config_userconfig: userConfig,
+            npm_config_update_notifier: "false",
+            npm_config_audit: "false",
+            npm_config_fund: "false",
+        };
+        const run = async (file, args) => (await execute(file, args, { encoding: "utf8", windowsHide: true, env: npmEnvironment }))
+            .stdout;
+        const cliExecutable = await realpath(executable);
+        const packageRoot = path.resolve(path.dirname(cliExecutable), "..");
+        const npmCliExecutable = await npmCliFor(nodeExecutable, platform);
+        const p = platform === "win32" ? path.win32 : path.posix;
+        const voltaExecutable = environment.VOLTA_HOME
+            ? p.resolve(environment.VOLTA_HOME, "bin", platform === "win32" ? "volta.exe" : "volta")
+            : undefined;
+        const runtime = {
+            packageRoot,
+            cliExecutable,
+            nodeExecutable,
+            ...(npmCliExecutable ? { npmCliExecutable } : {}),
+            ...(voltaExecutable ? { voltaExecutable } : {}),
+            platform,
+            realpath,
+            directDirectory: async (value) => {
+                const info = await lstat(value).catch(() => undefined);
+                return info?.isDirectory() === true && info.isSymbolicLink() === false;
+            },
+            readPackage: async (root) => JSON.parse(await readFile(path.join(root, "package.json"), "utf8")),
+            latestVersion: async (provenance) => {
+                const stdout = provenance === "volta"
+                    ? await run(voltaExecutable, [
+                        "run",
+                        "npm",
+                        "view",
+                        "ast-mcp-server@latest",
+                        "version",
+                        "--json",
+                    ])
+                    : await run(nodeExecutable, [
+                        npmCliExecutable,
+                        "view",
+                        "ast-mcp-server@latest",
+                        "version",
+                        "--json",
+                    ]);
+                const value = JSON.parse(stdout);
+                if (typeof value !== "string")
+                    throw new Error("invalid registry response");
+                return value;
+            },
+            run,
+        };
+        return {
+            runtime,
+            dispose: () => cleanupBoundary(boundary, options.removeTree),
+        };
+    }
+    catch (error) {
+        try {
+            await cleanupBoundary(boundary, options.removeTree);
+        }
+        catch {
+            throw new UpgradeCleanupError("UPGRADE_RUNTIME_CREATION_FAILED");
+        }
+        throw error;
+    }
+}

package/dist/services/upgrade.js

@@ -0,0 +1,232 @@
+import path from "node:path";
+const PACKAGE = "ast-mcp-server";
+const CONTINUATION = "After reinstalling through its owning toolchain, run: ast-tool upgrade --check";
+export class UpgradeError extends Error {
+    code;
+    continuation;
+    constructor(code, message, continuation = CONTINUATION) {
+        super(message);
+        this.code = code;
+        this.continuation = continuation;
+        this.name = "UpgradeError";
+    }
+}
+function fail(code, message) {
+    throw new UpgradeError(code, message);
+}
+function paths(platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
+function same(a, b, platform) {
+    return platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+function inside(root, target, platform) {
+    const p = paths(platform);
+    const relative = p.relative(root, target);
+    return relative !== ".." && !relative.startsWith(`..${p.sep}`) && !p.isAbsolute(relative);
+}
+async function canonical(runtime, value) {
+    return runtime
+        .realpath(value)
+        .catch(() => fail("UPGRADE_PROVENANCE_UNSUPPORTED", "Package ownership could not be proven."));
+}
+function packageFields(record, platform) {
+    const bins = record.bin;
+    if (record.name !== PACKAGE ||
+        typeof record.version !== "string" ||
+        !record.version ||
+        !bins ||
+        typeof bins["ast-tool"] !== "string" ||
+        typeof bins["ast-mcp-server"] !== "string") {
+        fail("UPGRADE_PROVENANCE_UNSUPPORTED", "Package identity or bins are unsupported.");
+    }
+    const p = paths(platform);
+    for (const value of [bins["ast-tool"], bins["ast-mcp-server"]]) {
+        if (p.isAbsolute(value) || p.normalize(value).startsWith(`..${p.sep}`)) {
+            fail("UPGRADE_PROVENANCE_UNSUPPORTED", "Package executable location is unsafe.");
+        }
+    }
+    return { version: record.version, cli: bins["ast-tool"], server: bins["ast-mcp-server"] };
+}
+async function readPackage(runtime, root) {
+    try {
+        return packageFields(await runtime.readPackage(root), runtime.platform);
+    }
+    catch (error) {
+        if (error instanceof UpgradeError)
+            throw error;
+        fail("UPGRADE_PROVENANCE_UNSUPPORTED", "Package metadata could not be verified.");
+    }
+}
+async function proveNpm(runtime, packageRoot) {
+    if (!runtime.npmCliExecutable)
+        return;
+    const p = paths(runtime.platform);
+    try {
+        const node = await canonical(runtime, runtime.nodeExecutable);
+        const npmCli = await canonical(runtime, runtime.npmCliExecutable);
+        const toolchainRoot = runtime.platform === "win32" ? p.dirname(node) : p.resolve(p.dirname(node), "..");
+        if (p.basename(npmCli).toLowerCase() !== "npm-cli.js" ||
+            !inside(toolchainRoot, npmCli, runtime.platform))
+            return;
+        const [rootText, prefixText] = await Promise.all([
+            runtime.run(runtime.nodeExecutable, [npmCli, "root", "--global"]),
+            runtime.run(runtime.nodeExecutable, [npmCli, "prefix", "--global"]),
+        ]);
+        const lexicalRoot = p.resolve(rootText.trim());
+        const lexicalPackage = p.join(lexicalRoot, PACKAGE);
+        if (!p.isAbsolute(rootText.trim()) || !(await runtime.directDirectory(lexicalPackage)))
+            return;
+        const root = await canonical(runtime, lexicalRoot);
+        const prefix = await canonical(runtime, prefixText.trim());
+        const expectedRoot = await canonical(runtime, runtime.platform === "win32"
+            ? p.join(prefix, "node_modules")
+            : p.join(prefix, "lib", "node_modules"));
+        const expectedPackage = await canonical(runtime, lexicalPackage);
+        if (!same(root, expectedRoot, runtime.platform) ||
+            !same(expectedPackage, packageRoot, runtime.platform))
+            return;
+        return {
+            kind: "npm",
+            executable: runtime.nodeExecutable,
+            args: [npmCli, "install", "--global", `${PACKAGE}@latest`, "--ignore-scripts"],
+        };
+    }
+    catch {
+        return;
+    }
+}
+async function proveVolta(runtime) {
+    if (!runtime.voltaExecutable)
+        return;
+    try {
+        const [tool, node] = await Promise.all([
+            runtime.run(runtime.voltaExecutable, ["which", "ast-tool"]),
+            runtime.run(runtime.voltaExecutable, ["which", "node"]),
+        ]);
+        if (!same(await canonical(runtime, tool.trim()), await canonical(runtime, runtime.cliExecutable), runtime.platform) ||
+            !same(await canonical(runtime, node.trim()), await canonical(runtime, runtime.nodeExecutable), runtime.platform))
+            return;
+        return {
+            kind: "volta",
+            executable: runtime.voltaExecutable,
+            args: ["install", `${PACKAGE}@latest`],
+        };
+    }
+    catch {
+        return;
+    }
+}
+function versionParts(value) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.exec(value);
+    return match ? [+match[1], +match[2], +match[3], match[4] ?? ""] : undefined;
+}
+function updateAvailable(current, latest) {
+    const left = versionParts(current);
+    const right = versionParts(latest);
+    if (!left || !right)
+        fail("UPGRADE_INSPECTION_FAILED", "Package version is invalid.");
+    for (let index = 0; index < 3; index++) {
+        if (left[index] !== right[index])
+            return left[index] < right[index];
+    }
+    if (!left[3] || !right[3])
+        return Boolean(left[3]);
+    return left[3].localeCompare(right[3], "en", { numeric: true }) < 0;
+}
+export async function planUpgrade(runtime) {
+    const p = paths(runtime.platform);
+    const root = await canonical(runtime, runtime.packageRoot);
+    const current = await readPackage(runtime, root);
+    const cli = await canonical(runtime, p.resolve(root, current.cli));
+    const server = await canonical(runtime, p.resolve(root, current.server));
+    if (!inside(root, cli, runtime.platform) ||
+        !inside(root, server, runtime.platform) ||
+        !same(cli, await canonical(runtime, runtime.cliExecutable), runtime.platform)) {
+        fail("UPGRADE_PROVENANCE_UNSUPPORTED", "The running CLI does not belong to this package.");
+    }
+    const proofs = (await Promise.all([proveNpm(runtime, root), proveVolta(runtime)])).filter((proof) => proof !== undefined);
+    if (proofs.length !== 1)
+        fail("UPGRADE_PROVENANCE_UNSUPPORTED", "Package ownership is ambiguous or unsupported.");
+    const proof = proofs[0];
+    let latest;
+    try {
+        latest = await runtime.latestVersion(proof.kind);
+    }
+    catch {
+        fail("UPGRADE_INSPECTION_FAILED", "Latest package version could not be verified.");
+    }
+    const update = updateAvailable(current.version, latest);
+    return {
+        version: 1,
+        status: "ok",
+        current_version: current.version,
+        latest_version: latest,
+        provenance: proof.kind,
+        update_available: update,
+        action: "ast-tool upgrade",
+        restart_required: update,
+        package_root: root,
+        cli_executable: cli,
+        install_executable: proof.executable,
+        install_args: proof.args,
+    };
+}
+export async function inspectUpgrade(runtime) {
+    const plan = await planUpgrade(runtime);
+    return {
+        version: plan.version,
+        status: plan.status,
+        current_version: plan.current_version,
+        latest_version: plan.latest_version,
+        provenance: plan.provenance,
+        update_available: plan.update_available,
+        action: plan.action,
+        restart_required: plan.restart_required,
+    };
+}
+export async function performUpgrade(runtime) {
+    const planned = await planUpgrade(runtime);
+    if (!planned.update_available) {
+        return {
+            ...inspectionFrom(planned),
+            status: "current",
+            installed_version: planned.current_version,
+            new_cli: planned.cli_executable,
+        };
+    }
+    try {
+        await runtime.run(planned.install_executable, planned.install_args);
+    }
+    catch {
+        fail("UPGRADE_VERIFICATION_FAILED", "Package update command failed.");
+    }
+    let installed;
+    try {
+        installed = await planUpgrade(runtime);
+    }
+    catch {
+        fail("UPGRADE_VERIFICATION_FAILED", "Updated package verification failed.");
+    }
+    if (installed.current_version !== installed.latest_version || installed.update_available) {
+        fail("UPGRADE_VERIFICATION_FAILED", "Updated package does not match refreshed latest.");
+    }
+    return {
+        ...inspectionFrom(installed),
+        status: "updated",
+        restart_required: true,
+        installed_version: installed.current_version,
+        new_cli: installed.cli_executable,
+    };
+}
+function inspectionFrom(plan) {
+    return {
+        version: plan.version,
+        current_version: plan.current_version,
+        latest_version: plan.latest_version,
+        provenance: plan.provenance,
+        update_available: plan.update_available,
+        action: plan.action,
+        restart_required: plan.restart_required,
+    };
+}

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.8.1 and the local `0.10.0` release candidate.
+This document defines the supported platform, runtime, persistence, and operational boundary for published `ast-mcp-server` v0.10.0 and the local `0.11.0` release candidate.
 
 ## Supported release target
 
-| Environment                                                                   | Status      | Contract                                                                                        |
-| ----------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
-| Linux x64 with required GNU coreutils and procfs, Node.js 22.5.0              | Published   | Immutable v0.8.1 release matrix; not the runtime floor of the current development tree.         |
-| Linux x64 with required GNU coreutils and procfs, exact Node.js 22.13.0       | Supported   | Local 0.10.0 candidate package, persistence, MCP/CLI/package, lifecycle and mutation matrix.    |
-| Linux x64 with required GNU coreutils and procfs, current Node.js 24 line     | Supported   | Published v0.8.1 and local 0.10.0 candidate matrices, each bound to its own package/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.                   |
+| 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.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.10.0 and local 0.11.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.10.0` 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.8.1 retains its immutable `>=22.5.0` metadata and exact Node.js 22.5.0/24 release evidence. A future runtime satisfying an engine range is not automatically a verified release target.
+The local `0.11.0` 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 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.
 
@@ -34,7 +34,7 @@ Operation locks coordinate cooperating same-user processes. They do not stop edi
 
 ## Symbol-index persistence
 
-Published v0.8.1 remains memory-default. In the local `0.10.0` candidate, absence and explicit `enabled` select native SQLite; operators requiring no persistent index state must set `disabled` explicitly:
+Published v0.10.0 and the local `0.11.0` 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 +64,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, or the local 0.9.2 candidate. The exact 0.9.0 and 0.9.1 release matrices remain historical evidence for their immutable published-next bytes, and the exact 0.9.2 release matrix remains historical local-candidate evidence for its own bytes. A separate exact 0.10.0 release matrix is the candidate-specific gate for current repository bytes under both supported runtime lines, including managed setup; 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, or the local v0.11.0 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, and the exact 0.10.0 matrix remains historical published-release evidence for its own bytes. A separate exact 0.11.0 release matrix is the candidate-specific gate for current repository bytes under both supported runtime lines, including managed setup; 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.10.0",
+  "version": "0.11.0",
   "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
   "keywords": [
     "mcp",
@@ -97,5 +97,5 @@
     "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"
   },
-  "gitHead": "7f97830d82d086e1a7ceafb84a8bc795be57039a"
+  "gitHead": "f0c8a66d72db71ffdf8ef0014f4b7b28f1d8852e"
 }