ast-mcp-server 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -6,7 +6,42 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-## [0.8.0] — release candidate (unreleased, 2026-08-14)
+## [0.9.0] — local release candidate, pending release (2026-08-16)
+
+### Added
+
+- Added bounded `ast-tool cache inspect` and confirmation-gated `ast-tool cache clear --yes`; both avoid host paths, reject unsafe trees, preserve unknown files, and perform no automatic garbage collection.
+
+### Changed
+
+- Native SQLite is now the requested symbol-index backend when `AST_SYMBOL_INDEX_PERSISTENCE` is absent or `enabled`; explicit `disabled` remains the immediate memory-only rollback, and `canary` still requires an explicit safe root.
+- The current development-line engine floor and lower evidence lane are Node.js `>=22.13.0` and exact `v22.13.0` respectively; Node.js 24 remains governed by major, and active harnesses no longer use `--experimental-sqlite`.
+- Default persistence resolves through an explicit override, XDG cache home, then HOME, while invalid explicit overrides fail closed instead of being hidden by another root.
+- Integration, package, CLI and consumer harnesses now exercise default SQLite, restart reuse, explicit rollback, mutation-only cache isolation and private artifacts.
+
+### Fixed
+
+- Promotion now tolerates bounded npm dist-tag propagation lag while revalidating package version, `gitHead`, integrity, provenance, and the complete `next`/`latest` state on every readback.
+
+### Security
+
+- Package-created cache directories use `0700`; SQLite main, WAL, SHM and quarantine artifacts use `0600` on supported Linux, with no-follow, ownership, link-count and device/inode validation around database open, quarantine and cleanup.
+
+### Release status
+
+- This local candidate is pending exact-tree CI and the repository's separately authorized delivery sequence. It has not been published to npm, assigned to `next` or `latest`, tagged in Git, or released on GitHub; registry and GitHub readbacks remain authoritative.
+
+## [0.8.1] — published to `latest` and `next`, registry verified (2026-08-14)
+
+### Fixed
+
+- Public-registry verification now prepares the pinned GNU coreutils 9.7 `mv` primitive before running the managed-setup consumer smoke, and workflow policy rejects removal or reordering of that prerequisite.
+
+### Release status
+
+- npm published these immutable bytes under `next` with provenance and the expected Git commit. Public-consumer verification passed, `latest` and `next` both resolve to `0.8.1`, and the annotated `v0.8.1` tag plus GitHub Release resolve to the same release commit.
+
+## [0.8.0] — published to `next`, verification failed, not promoted (2026-08-14)
 
 ### Fixed
 
@@ -25,9 +60,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Release status
 
-- This version is bound to exact-SHA CI and the repository's staged `next` publication, public-registry verification, `latest` promotion, annotated-tag, and hosted-release sequence. npm registry and GitHub readbacks remain authoritative for those external transitions.
+- npm published these immutable bytes under `next` with provenance and the expected Git commit. Public-consumer verification stopped during managed setup because the verification workflow had not prepared its required GNU coreutils 9.7 `mv`; the package was never promoted to `latest`, tagged, or released on GitHub. Version `0.8.1` superseded it after verified publication.
 
-## [0.7.2] — published to `latest` and `next`, registry verified (2026-08-13)
+## [0.7.2] — published to `latest`, registry verified (2026-08-13)
 
 ### Fixed
 
@@ -41,7 +76,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Release status
 
-- npm exposes the immutable published `0.7.2` bytes under both `latest` and `next`. The `0.8.0` section above describes distinct release bytes and cannot be attributed to that package version.
+- npm promoted the immutable `0.7.2` bytes to `latest`. Later `next` assignments do not alter those bytes, and the `0.8.x` sections above describe distinct package versions that cannot be attributed to `0.7.2`.
 
 ## [0.7.1] — published to `next`, verified, not promoted (2026-08-12)
 

package/README.md

@@ -6,7 +6,7 @@
 
 [![CI](https://github.com/yailPeralta/ast-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/yailPeralta/ast-mcp-server/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/ast-mcp-server.svg)](https://www.npmjs.com/package/ast-mcp-server)
-[![Node.js 22.5+](https://img.shields.io/badge/Node.js-22.5%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Node.js 22.13+](https://img.shields.io/badge/Node.js-22.13%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
 
 `ast-mcp-server` gives coding agents compact, type-aware access to TypeScript and JavaScript projects. It uses the real compiler project model through `ts-morph`, so declarations, references, rename locations, and diagnostics come from the AST instead of text-search guesses.
@@ -76,17 +76,26 @@ The included batch benchmark records a 50% reduction in model round-trips and a
 
 ## Requirements
 
-- Node.js 22.5.0 or newer
+- Node.js 22.13.0 or newer
 - Corepack with Yarn 4.15.0 (pinned by `packageManager`)
 - A target project with a `tsconfig.json`
 
 ## Supported environment and trust boundary
 
-The package engine floor remains Node.js `>=22.5.0`. The v0.8.0 release matrix covers Linux x64 under exact Node.js 22.5.0 and the current Node.js 24 line, including managed setup-file publication. That mutation additionally requires GNU coreutils 9.7 `mv` supporting `--update=none-fail`, `--exchange`, `--no-copy`, and `--no-target-directory`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, and `O_DIRECTORY`/`O_NOFOLLOW`. Other Linux architectures or systems without those filesystem primitives, macOS, and Windows remain unverified until equivalent exact-tree gates pass.
+The local `0.9.0` release candidate requires Node.js `>=22.13.0`; its evidence matrix targets exact Node.js 22.13.0 and the current Node.js 24 line. Published v0.8.1 retains its immutable historical Node.js 22.5.0/24 evidence. Managed setup-file publication additionally requires GNU coreutils 9.7 `mv` supporting `--update=none-fail`, `--exchange`, `--no-copy`, and `--no-target-directory`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, and `O_DIRECTORY`/`O_NOFOLLOW`. Other Linux architectures or systems without those filesystem primitives, macOS, and Windows remain unverified.
 
 This is a local stdio server. It runs with the invoking user's filesystem permissions, and clients may request any `project_root` that user can access. It does not provide HTTP authentication, sandboxing, tenant isolation, or a remote-service security boundary. Remote, untrusted, and multi-tenant operation is unsupported.
 
-Symbol-index persistence remains disabled by default. `AST_SYMBOL_INDEX_PERSISTENCE=canary` additionally requires an explicit absolute `AST_SYMBOL_INDEX_CACHE_ROOT`; the reserved `enabled` mode fails closed to memory-only with `enabled_not_released`.
+In the local `0.9.0` release candidate, an absent `AST_SYMBOL_INDEX_PERSISTENCE` or explicit `enabled` selects the private SQLite symbol-index cache. `disabled` is the immediate memory-only rollback. `canary` requires an explicit absolute normalized `AST_SYMBOL_INDEX_CACHE_ROOT`. Invalid policy or storage fails closed to compiler-authoritative memory reads with bounded path-free status.
+
+The default cache root is selected from `AST_SYMBOL_INDEX_CACHE_ROOT`, then `XDG_CACHE_HOME`, then `HOME`. Inspect or clear only derived cache artifacts through the bounded CLI:
+
+```bash
+ast-tool cache inspect
+ast-tool cache clear --yes
+```
+
+Clear requires exact confirmation, refuses unsafe or active SQLite artifacts, and preserves unknown regular files. No automatic cache GC is enabled.
 
 See [Support policy](docs/support.md) for the complete platform, runtime, persistence, and operational contract. Report security issues through [SECURITY.md](SECURITY.md).
 

package/SECURITY.md

@@ -11,7 +11,7 @@ Security fixes are provided for the exact version currently identified by the np
 | Earlier npm versions                        | No        |
 | Unpublished release candidates              | No        |
 
-This project supports trusted single-user local stdio use; the supported operating-system and architecture boundary remains Linux x64 only. The package engine floor is Node.js `>=22.5.0`, and the v0.8.0 release matrix covers Linux x64 under exact Node.js 22.5.0 and the current Node.js 24 line, including managed setup-file publication. That mutation requires GNU coreutils 9.7 `mv --update=none-fail --exchange --no-copy --no-target-directory`, GNU coreutils `ln -L -T`, and procfs descriptor-relative paths at `/proc/self/fd` with `O_DIRECTORY`/`O_NOFOLLOW`. Other Linux architectures and systems without those primitives are unverified, as are macOS and Windows. Remote, untrusted, and multi-tenant use is outside the supported security boundary.
+This project supports trusted single-user local stdio use; the supported operating-system and architecture boundary remains Linux x64 only. The local `0.9.0` release candidate requires Node.js `>=22.13.0`, with evidence targeted at exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.8.1 retains its immutable Node.js 22.5.0/24 release matrix. Managed setup mutation requires GNU coreutils 9.7 `mv --update=none-fail --exchange --no-copy --no-target-directory`, GNU coreutils `ln -L -T`, and procfs descriptor-relative paths at `/proc/self/fd` with `O_DIRECTORY`/`O_NOFOLLOW`. The candidate's default SQLite cache also relies on Linux ownership, mode, no-follow, link-count and inode-identity checks; it does not defend against a malicious same-UID process. Other Linux architectures and systems without those primitives are unverified, as are macOS and Windows. Remote, untrusted, and multi-tenant use is outside the supported security boundary.
 
 ## Reporting a vulnerability
 

package/dist/cli.js

@@ -6,6 +6,7 @@ import { BatchExecutionError, parseBatchDocument, runBatchDocument } from "./bat
 import { MAX_BATCH_INPUT_BYTES, isPrepareBatchTool } from "./batch/schema.js";
 import { CliOutputError, serializeCliSuccess } from "./cli-output.js";
 import { applyPersistedOperation, persistOperationPlan } from "./services/operation-plan-file.js";
+import { clearSymbolIndexCache, inspectSymbolIndexCache, SymbolIndexCacheError, } from "./services/symbol-index-cache.js";
 import { AgentSetupError, detectInstalledAgents, resolveServerEntryPath, runAgentSetup, } from "./services/agent-setup.js";
 import { installBundledSkill, resolveBundledSkillAssets, } from "./services/skill-installer.js";
 import { parseAgentsArgument, promptForAgentSelection, resolveAgentSelection, } from "./services/setup-wizard.js";
@@ -31,6 +32,8 @@ function usage() {
         "  ast-tool run <pipeline.json|-> [--output-format json|toon]",
         "  ast-tool validate <pipeline.json|->",
         "  ast-tool apply <plan.astplan> --plan-hash <sha256>",
+        "  ast-tool cache inspect",
+        "  ast-tool cache clear --yes",
         "  ast-tool install-skill [claude|hermes|all] [--scope user|project] [--project-root <path>] [--force]",
         "  ast-tool setup [--agents claude,hermes|all --yes] [--force-skill]",
     ].join("\n");
@@ -227,6 +230,24 @@ export async function runCli(args) {
             throw new CliError(error instanceof Error ? error.message : String(error), "EXECUTION_ERROR", 1, command, undefined, { cause: error });
         }
     }
+    if (command === "cache") {
+        const [subcommand, ...cacheArgs] = commandArgs;
+        const cacheCommand = subcommand ? `cache ${subcommand}` : "cache";
+        const inspectRequested = subcommand === "inspect" && cacheArgs.length === 0;
+        const clearRequested = subcommand === "clear" && cacheArgs.length === 1 && cacheArgs[0] === "--yes";
+        if (!inspectRequested && !clearRequested) {
+            throw new CliError(usage(), "USAGE", 2, cacheCommand);
+        }
+        try {
+            return inspectRequested ? await inspectSymbolIndexCache() : await clearSymbolIndexCache();
+        }
+        catch (error) {
+            if (error instanceof SymbolIndexCacheError) {
+                throw new CliError(error.message, error.code, 1, cacheCommand, undefined, { cause: error }, error.details);
+            }
+            throw new CliError("Cache command failed without exposing host details.", "CACHE_ERROR", 1, cacheCommand, undefined, { cause: error });
+        }
+    }
     if (command === "apply") {
         const { planFile, planHash } = parseApplyArgs(commandArgs);
         try {

package/dist/services/opencode-config.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { link, mkdir, mkdtemp, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { link, mkdir, mkdtemp, open, readFile, rename, rm, stat, writeFile, } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { applyEdits, modify, parse } from "jsonc-parser";
@@ -120,8 +120,21 @@ export async function applyOpenCodeConfigPlan(plan) {
     const directory = path.dirname(plan.filePath);
     await mkdir(directory, { recursive: true });
     const temporary = path.join(directory, `.${path.basename(plan.filePath)}.${randomUUID()}.tmp`);
-    await writeFile(temporary, plan.content, { encoding: "utf8", flag: "wx", mode: plan.mode });
     try {
+        let handle;
+        try {
+            handle = await open(temporary, "wx", plan.mode);
+            await handle.writeFile(plan.content, { encoding: "utf8" });
+            await handle.chmod(plan.mode);
+            await handle.sync();
+            const staged = await handle.stat();
+            if ((staged.mode & 0o777) !== plan.mode) {
+                throw new Error("OpenCode configuration mode could not be preserved.");
+            }
+        }
+        finally {
+            await handle?.close();
+        }
         if (!plan.beforeExists) {
             await link(temporary, plan.filePath);
             await rm(temporary);

package/dist/services/project.js

@@ -32,8 +32,14 @@ function getProjectRuntimePolicy() {
     return projectRuntimePolicy;
 }
 function closePersistentSymbolIndex(session) {
-    session.persistentSymbolIndex?.close();
+    const persistentSymbolIndex = session.persistentSymbolIndex;
     session.persistentSymbolIndex = undefined;
+    try {
+        persistentSymbolIndex?.close();
+    }
+    catch {
+        // Detachment is authoritative; a stale SQLite store must not survive cleanup failure.
+    }
 }
 function symbolIndexFailureOperation(reason) {
     if (reason === "corrupt_storage")
@@ -118,8 +124,12 @@ async function ensureSessionSymbolIndex(session, requestContext) {
             symbolIndexObservability: createInitialSymbolIndexRuntimeObservability(policy),
         };
     }
-    if (policy.backend === "memory")
+    if (policy.backend === "memory") {
+        if (policy.mode === "enabled" || policy.mode === "canary") {
+            fallbackToMemory(session, policy.reason);
+        }
         return;
+    }
     if (session.persistentSymbolIndex)
         return;
     const cachePath = symbolIndexCachePath(policy, session.context.status.project);