ast-mcp-server 0.9.2 → 0.11.0

package/CHANGELOG.md

@@ -6,6 +6,39 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.11.0] — local release candidate, pending release (2026-08-23)
+
+### Added
+
+- Managed setup and `install-skill` now install manifested multi-file skill bundles atomically, verify every bundled digest, and admit exact npm-proven predecessor bytes without treating version text as ownership.
+- `ast-tool upgrade --check` inspects supported direct npm and Volta installations without mutation; `ast-tool upgrade` performs the safe direct update with isolated package-manager state and then reconciles managed assets.
+- CLI batch and doctor project selection now discovers the nearest `tsconfig.json` or `jsconfig.json` up to the Git or filesystem boundary, while rejecting same-level ambiguity and symlinked config identities.
+- `ast-tool doctor` reports bounded, privacy-safe compiler, session, index, and queue state with executable continuations; unavailable registered-session evidence is reported as `not_run` instead of being fabricated.
+
+### Fixed
+
+- Project watchers now ignore events owned by exact symbol-index cache artifacts while preserving legitimate source invalidations, including POSIX filenames containing a literal backslash.
+
+### Release status
+
+- This local candidate is pending its exact-tree release matrix, 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.10.0] — published to `latest` and `next`, registry verified (2026-08-22)
+
+### Added
+
+- Added deterministic atomic `ast_explore` clusters, categorized omission metadata, opt-in compiler-authoritative call spines, and registered-handler parity across MCP and the batch CLI.
+- Added read-only `ast_find_test_candidates` across MCP and `ast-tool run`, with incoming compiler authority, fail-closed incomplete evidence, whole-candidate pagination, and lossless final JSON/TOON parity.
+
+### Fixed
+
+- Oversized `ast_explore` call-spine aggregates are omitted atomically instead of failing valid requests.
+- SQLite capability fallback now preserves fresh compiler-backed reads while retaining failed memory-backed index observability. Stable capability and invalid-root fallbacks retry only after restart or policy change; transient storage failures continue to recover automatically.
+
+### Release status
+
+- npm published these immutable bytes under `next` with provenance and the expected Git commit. Public-registry consumer and release-preflight verification passed, `latest` and `next` both resolve to `0.10.0`, and the annotated `v0.10.0` tag plus GitHub Release resolve to the same release commit.
+
 ## [0.9.2] — local release candidate, pending release (2026-08-16)
 
 ### Fixed

package/README.md

@@ -25,16 +25,17 @@ Coding agents often fall back to two generic operations: read files as plain tex
 
 This MCP server gives the agent structural code tools in addition to generic file reads and writes. Under the hood, `ts-morph` uses the TypeScript compiler project model, so the server can reason about declarations and references as code rather than undifferentiated text.
 
-| Need                           | Structural operation      | Returned scope                                             |
-| ------------------------------ | ------------------------- | ---------------------------------------------------------- |
-| Read a bounded file            | `ast_get_file`            | Exact selected source lines, hashes, and bounded freshness |
-| Explore bounded context        | `ast_explore`             | Ranked selectors plus optional source and references       |
-| Understand a file              | `ast_get_outline`         | Signatures without implementation bodies                   |
-| Inspect one declaration        | `ast_get_symbol_source`   | Exact source for one function, method, class, or type      |
-| Find usages across the project | `ast_find_references`     | Compiler-resolved reference locations                      |
-| Understand symbol impact       | `ast_get_impact`          | Bounded direct/transitive compiler-backed relationships    |
-| Rename a symbol everywhere     | `ast_rename_symbol`       | A reviewed project-wide rename plan                        |
-| Change one implementation      | `ast_replace_symbol_body` | A body-only plan that preserves the declaration            |
+| Need                           | Structural operation       | Returned scope                                              |
+| ------------------------------ | -------------------------- | ----------------------------------------------------------- |
+| Read a bounded file            | `ast_get_file`             | Exact selected source lines, hashes, and bounded freshness  |
+| Explore bounded context        | `ast_explore`              | Ranked selectors plus optional source and references        |
+| Understand a file              | `ast_get_outline`          | Signatures without implementation bodies                    |
+| Inspect one declaration        | `ast_get_symbol_source`    | Exact source for one function, method, class, or type       |
+| Find usages across the project | `ast_find_references`      | Compiler-resolved reference locations                       |
+| Understand symbol impact       | `ast_get_impact`           | Bounded direct/transitive compiler-backed relationships     |
+| Select affected tests          | `ast_find_test_candidates` | Whole candidate proofs from incoming compiler relationships |
+| Rename a symbol everywhere     | `ast_rename_symbol`        | A reviewed project-wide rename plan                         |
+| Change one implementation      | `ast_replace_symbol_body`  | A body-only plan that preserves the declaration             |
 
 Reads can start with a bounded file slice, a compact outline, or exact source only for the declaration that needs inspection. Mutations are prepared in memory first, compared against baseline diagnostics, and returned as immutable, hash-bound plans. Nothing is written until the caller reviews and explicitly applies the plan.
 
@@ -46,6 +47,7 @@ Reads can start with a bounded file slice, a compact outline, or exact source on
 - Use `ast_get_outline` for a compact body-free view of a known file without source lines.
 - Use `ast_get_symbol_source` when one declaration or implementation is the required evidence.
 - Use `ast_get_impact` when the exact symbol is known and bounded direct/transitive compiler relationships are needed; it is read-only evidence, not a mutation plan.
+- Use `ast_find_test_candidates` when an exact symbol should map to conservative test candidates. It forces incoming compiler traversal, returns complete relationship paths, and never executes tests.
 
 `snapshot_state: "fresh"` means that the returned file bytes match the synchronized compiler snapshot. The separate `freshness` object describes the project/session state and preserves causes such as source changes or watcher failure. Neither field means that the project has zero TypeScript diagnostics; use `ast_get_diagnostics` for compiler errors and warnings.
 
@@ -62,7 +64,7 @@ The server exposes evidence labels instead of collapsing every result into an un
 
 Freshness is orthogonal to TypeScript diagnostics. `fresh` means the evidence matches the synchronized snapshot; `pending`, `rebuilding`, `stale`, or `degraded` means the response must not be presented as current compiler evidence. Read tools expose the state, causes (`source_change`, `config_change`, `index_failure`, `watcher_failure`, or `compiler_rebuild`), and bounded `checked_at` timestamp. `ast_get_impact` refuses non-fresh compiler relationships. `ast_explore` returns the state together with `completeness`, `unresolved`, `budget`, and `truncation` metadata rather than silently dropping evidence.
 
-All reads are budgeted. Callers control pagination and, where applicable, `max_bytes`, `reference_limit`, `max_depth`, `max_nodes`, and `max_edges`; responses report the effective limits and whether a record, byte, depth, edge, invocation, or serialization limit truncated the result. A truncated or unresolved result is incomplete evidence, not an empty negative result. The internal test-candidate resolver follows the same rule: it accepts only fresh, exact compiler-backed impact, emits direct/transitive evidence and bounded relationship IDs, and never executes tests or guesses from filenames alone.
+All reads are budgeted. Callers control pagination and, where applicable, `max_bytes`, `reference_limit`, `max_depth`, `max_nodes`, and `max_edges`; responses report the effective limits and whether a record, byte, depth, edge, invocation, or serialization limit truncated the result. A truncated or unresolved result is incomplete evidence, not an empty negative result. `ast_find_test_candidates` follows the same rule: it accepts only fresh, exact compiler-backed impact, emits direct/transitive evidence and bounded relationship IDs, and never executes tests or guesses from filenames alone. Only a complete authoritative traversal may return `candidates: []` with `proven_empty: true`.
 
 ## Why this helps
 
@@ -82,11 +84,11 @@ The included batch benchmark records a 50% reduction in model round-trips and a
 
 ## Supported environment and trust boundary
 
-The local `0.9.2` 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.
+The local `0.11.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.10.0 retains its immutable historical Node.js 22.13.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.
 
-In the local `0.9.2` 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.
+In published v0.10.0 and the local `0.11.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:
 
@@ -129,6 +131,29 @@ The package exposes two executables when installed:
 - `ast-mcp-server`: MCP stdio server.
 - `ast-tool`: batch, skill-installation, and agent-setup CLI.
 
+### Diagnose the active installation
+
+```bash
+ast-tool doctor [--project <config-or-dir>]
+```
+
+Doctor reuses CLI project discovery and existing runtime authorities without changing project,
+agent, package, or skill state. It prints bounded JSON; exit `0` is healthy, `1` degraded, and `2`
+failed. A healthy compiler remains usable when only the derived SQLite index is degraded.
+Standalone diagnosis marks registered-session-only index and queue evidence as `not_run` rather
+than fabricating healthy state.
+
+### Upgrade an installed package
+
+Inspect the active global installation without writing, or update it immediately:
+
+```bash
+ast-tool upgrade --check
+ast-tool upgrade
+```
+
+Upgrade supports only a direct package proven to belong to the active npm global prefix or to Volta. It rejects linked/source and ambiguous installations, never uses `sudo`, guesses from `PATH`, or accepts `--yes`. npm runs its proven `npm-cli.js` through the active Node with lifecycle scripts disabled and a disposable cache/config copy; cleanup is verified and blocks success if absence cannot be proven. Volta uses its native integration. The updated CLI then reconciles managed setup through that Node. Customized skill bytes remain untouched and produce `ast-tool setup --agents all --yes --force-skill`. Restart MCP clients after any package update; an already-running server does not change in place.
+
 ## Guided agent setup
 
 The installed package opens the interactive wizard with:
@@ -298,6 +323,7 @@ Project-scoped tools accept `project_root`, either the project directory or an e
 | `ast_search_symbols`        | Paginated structural symbol discovery                                | No            |
 | `ast_find_references`       | Compiler-resolved references with bounded context                    | No            |
 | `ast_get_impact`            | Bounded incoming/outgoing compiler-backed impact evidence            | No            |
+| `ast_find_test_candidates`  | Paginated affected tests with atomic compiler relationship proofs    | No            |
 | `ast_get_diagnostics`       | Project- or file-scoped TypeScript diagnostics                       | No            |
 | `ast_rename_symbol`         | Prepare a project-wide rename                                        | No            |
 | `ast_replace_symbol_body`   | Prepare a body-only replacement while preserving the signature       | No            |
@@ -307,7 +333,9 @@ Project-scoped tools accept `project_root`, either the project directory or an e
 
 Read results use project-relative paths, deterministic ordering, structured MCP output, and pagination where result sets can grow with the project.
 
-`ast_explore` supports query, exact file, and exact symbol routes. Its default `summary` profile returns bounded reusable selectors; `context` adds selected source and `full` adds compiler references. Every response reports freshness, completeness, truncation, unresolved selectors, record limits, and a serialized byte budget. Use the primitive tools when a single exact operation is clearer or when preparing a mutation.
+`ast_explore` supports query, exact file, and exact symbol routes. Its default `summary` profile returns bounded reusable selectors; `context` adds selected source and `full` adds compiler references. Whole symbol clusters are admitted under the caller's `max_bytes` ceiling, so source, reference records, and call paths are never sliced. `omissions` classifies withheld components as `budget`, `incomplete`, or `untrusted`, and any requested omission keeps completeness false.
+
+Exact `file_path` plus `symbol_path` requests may opt into bounded static `call_spines`. Only fresh, exact, compiler-resolved invocation sites qualify; generic references, dynamic dispatch, and runtime behavior are not inferred. Absence of `call_spines` performs no call traversal. Every response still reports freshness, completeness, truncation, unresolved selectors, record limits, and canonical serialized-byte accounting. Use the primitive tools when a single exact operation is clearer or when preparing a mutation. See [ADR 0013](docs/adr/0013-ast-explore-presentation.md).
 
 Symbol search is relevance-ranked and defaults to at most 20 `summary` records containing `file`, a directly reusable `selector`, `kind`, and body-free `signature`. Request `detail: "selectors"` for routing coordinates only, or `detail: "full", limit: 100` for the v0.4.0 fields/page. References default to `detail: "locations"`; request `detail: "context"` only when the bounded source line is needed.
 
@@ -357,6 +385,10 @@ Example search-to-source pipeline:
 
 A `$ref` is an RFC 6901 JSON Pointer rooted at prior step results. References cannot point forward. If `emit` is omitted, only the final step result is returned; intermediate results remain inside the process.
 
+For CLI batches only, omit `project_root` or provide a directory to select the nearest `tsconfig.json` or `jsconfig.json` from the invocation directory upward. An explicit config file always wins. Discovery stops at a `.git` or filesystem boundary and rejects same-level ambiguity or symlinked identities; MCP tool calls still require an explicit `project_root`.
+
+`ast_find_test_candidates` and `ast_explore` are admitted as read steps. The batch runner injects the pipeline `project_root`, rejects a conflicting step root, and invokes the same registered MCP implementation. Candidate relationship proofs and exploration clusters remain whole; final JSON and TOON differ only in serialization, not logical evidence.
+
 ### Bounded foreach
 
 ```json

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 local `0.9.2` 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.
+This project supports trusted single-user local stdio use; the supported operating-system and architecture boundary remains Linux x64 only. The local `0.11.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.10.0 retains its immutable Node.js 22.13.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/batch/schema.js

@@ -14,6 +14,8 @@ export const READ_BATCH_TOOLS = [
     "ast_get_symbol_source",
     "ast_search_symbols",
     "ast_find_references",
+    "ast_find_test_candidates",
+    "ast_explore",
     "ast_get_diagnostics",
 ];
 export const PREPARE_BATCH_TOOLS = [

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
+import path from "node:path";
 import process from "node:process";
 import { ZodError } from "zod";
 import { BatchExecutionError, parseBatchDocument, runBatchDocument } from "./batch/runner.js";
@@ -10,6 +11,12 @@ import { clearSymbolIndexCache, inspectSymbolIndexCache, SymbolIndexCacheError,
 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";
+import { runUpgradeLease, UpgradeCommandError } from "./services/upgrade-command.js";
+import { reconcileUpgrade } from "./services/upgrade-reconcile.js";
+import { createUpgradeRuntime, UpgradeCleanupError } from "./services/upgrade-runtime.js";
+import { UpgradeError } from "./services/upgrade.js";
+import { CliProjectDiscoveryError, resolveCliBatchProject, } from "./services/cli-project-discovery.js";
+import { runDoctor } from "./services/doctor.js";
 class CliError extends Error {
     code;
     exitCode;
@@ -34,8 +41,10 @@ function usage() {
         "  ast-tool apply <plan.astplan> --plan-hash <sha256>",
         "  ast-tool cache inspect",
         "  ast-tool cache clear --yes",
+        "  ast-tool doctor [--project <config-or-dir>]",
         "  ast-tool install-skill [claude|hermes|all] [--scope user|project] [--project-root <path>] [--force]",
         "  ast-tool setup [--agents claude,hermes|all --yes] [--force-skill]",
+        "  ast-tool upgrade [--check]",
     ].join("\n");
 }
 async function readStdinBounded() {
@@ -71,6 +80,13 @@ function parseApplyArgs(args) {
     }
     return { planFile: args[0], planHash: args[2] };
 }
+function parseDoctorArgs(args) {
+    if (args.length === 0)
+        return {};
+    if (args.length === 2 && args[0] === "--project" && args[1] && !args[1].startsWith("--"))
+        return { project: args[1] };
+    throw new CliError(usage(), "USAGE", 2, "doctor");
+}
 function parseRunArgs(args) {
     let source;
     let outputFormat = "json";
@@ -184,18 +200,37 @@ function parseSetupArgs(args) {
 }
 async function parseDocumentForCommand(source, command) {
     try {
-        return parseBatchDocument(await readBatchInput(source));
+        const input = await readBatchInput(source);
+        return parseBatchDocument(await resolveCliBatchProject(input, process.cwd()));
     }
     catch (error) {
         if (error instanceof CliError) {
             throw new CliError(error.message, error.code, 2, command, error.stepId, { cause: error });
         }
+        if (error instanceof CliProjectDiscoveryError) {
+            const relativeSource = source === "-" ? source : path.relative(process.cwd(), path.resolve(source));
+            const shellSource = `'${relativeSource.replaceAll("'", `'\\''`)}'`;
+            throw new CliError(error.message, error.code, 2, command, undefined, undefined, {
+                continuation: `${error.continuation} Then run: ast-tool ${command} ${shellSource}`,
+            });
+        }
         const message = error instanceof ZodError ? error.issues.map((issue) => issue.message).join("; ") : error;
         throw new CliError(message instanceof Error ? message.message : String(message), "INVALID_BATCH", 2, command, undefined, { cause: error });
     }
 }
 export async function runCli(args) {
     const [command, ...commandArgs] = args;
+    if (command === "doctor") {
+        const executable = process.argv[1];
+        if (!executable)
+            throw new CliError(usage(), "USAGE", 2, command);
+        return runDoctor({
+            ...parseDoctorArgs(commandArgs),
+            cwd: process.cwd(),
+            executable,
+            environment: process.env,
+        });
+    }
     if (command === "run" || command === "validate") {
         const runArgs = command === "run"
             ? parseRunArgs(commandArgs)
@@ -320,6 +355,33 @@ export async function runCli(args) {
             throw new CliError(error instanceof Error ? error.message : String(error), "SKILL_INSTALL_ERROR", 1, command, undefined, { cause: error });
         }
     }
+    if (command === "upgrade") {
+        try {
+            const executable = process.argv[1];
+            if (!executable)
+                throw new Error("missing executable");
+            const lease = await createUpgradeRuntime(executable);
+            return await runUpgradeLease(commandArgs, lease, reconcileUpgrade);
+        }
+        catch (error) {
+            if (error instanceof UpgradeCommandError) {
+                throw new CliError(error.message, "USAGE", 2, command, undefined, { cause: error });
+            }
+            if (error instanceof UpgradeError) {
+                throw new CliError(error.message, error.code, 1, command, undefined, { cause: error }, {
+                    continuation: error.continuation,
+                });
+            }
+            if (error instanceof UpgradeCleanupError) {
+                throw new CliError(error.message, error.code, 1, command, undefined, undefined, {
+                    cleanup: "required",
+                    ...(error.primaryCode ? { primary_code: error.primaryCode } : {}),
+                    continuation: "ast-tool upgrade --check",
+                });
+            }
+            throw new CliError("Upgrade failed without exposing host details.", "UPGRADE_ERROR", 1, command, undefined, { cause: error });
+        }
+    }
     throw new CliError(usage(), "USAGE", 2, command ?? null);
 }
 function failure(error, command = null) {
@@ -363,6 +425,10 @@ async function main() {
         const result = await runCli(args);
         const outputFormat = args[0] === "run" ? parseRunArgs(args.slice(1)).outputFormat : "json";
         process.stdout.write(`${serializeCliSuccess(result, outputFormat)}\n`);
+        if (args[0] === "doctor") {
+            const status = result.status;
+            process.exitCode = status === "healthy" ? 0 : status === "degraded" ? 1 : 2;
+        }
     }
     catch (error) {
         const failed = failure(error, args[0] ?? null);

package/dist/server.js

@@ -3,6 +3,7 @@ import { McpServer, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { PublicOperationalError } from "./services/public-errors.js";
 import { registerApplyOperation } from "./tools/apply_operation.js";
 import { registerFindReferences } from "./tools/find_references.js";
+import { registerFindTestCandidates } from "./tools/find_test_candidates.js";
 import { registerGetDiagnostics } from "./tools/get_diagnostics.js";
 import { registerGetFile } from "./tools/get_file.js";
 import { registerGetImpact } from "./tools/get_impact.js";
@@ -47,6 +48,7 @@ export function createServer(options = {}) {
     registerSearchSymbols(server);
     registerFindReferences(server);
     registerGetImpact(server);
+    registerFindTestCandidates(server);
     registerGetDiagnostics(server);
     registerGetFile(server);
     registerRenameSymbol(server);

package/dist/services/agent-setup.js

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { randomUUID } from "node:crypto";
-import { planBundledSkillInstallation, SkillConflictError, } from "./skill-installer.js";
+import { applySkillInstallationPlan, planBundledSkillInstallation, SkillConflictError, } from "./skill-installer.js";
 import { planManagedGuidance, } from "./managed-guidance.js";
 import { applyManagedFilePlan, createManagedFileApplyContext, ManagedFileApplyError, ManagedFileRollbackError, revalidateManagedFilePlan, verifyManagedFilePostimage, } from "./managed-file.js";
 import { AGENT_IDS, classifyAgentVersion, getAgentTarget, MCP_SERVER_NAME, } from "./agent-targets.js";
@@ -29,14 +29,18 @@ export async function applyManagedAssetPlans(skillPlan, guidancePlan, context =
     const rollbackFailed = [];
     const authenticated = [];
     let activePlan;
+    let skillBundleApplying = true;
     try {
         for (const file of [...skillPlan.files, ...guidancePlan.files]) {
             await revalidateManagedFilePlan(file);
         }
-        const plans = [
-            ...skillPlan.files.map((file) => ({ file, asset: "skill" })),
-            ...guidancePlan.files.map((file) => ({ file, asset: "guidance" })),
-        ];
+        await applySkillInstallationPlan(skillPlan, (file) => {
+            authenticated.push(file);
+            if (file.status !== "unchanged")
+                physicalWrites.push({ path: file.path, asset: "skill", status: file.status });
+        }, context, hooks);
+        skillBundleApplying = false;
+        const plans = guidancePlan.files.map((file) => ({ file, asset: "guidance" }));
         for (const { file, asset } of plans) {
             activePlan = { file, asset };
             for (const current of authenticated) {
@@ -55,6 +59,8 @@ export async function applyManagedAssetPlans(skillPlan, guidancePlan, context =
         return physicalWrites;
     }
     catch (error) {
+        if (skillBundleApplying)
+            physicalWrites.length = 0;
         if (activePlan !== undefined && activePlan.file.status !== "unchanged") {
             const write = {
                 path: activePlan.file.path,

package/dist/services/agent-targets.js

@@ -5,6 +5,7 @@ const EXPECTED_TOOLS = [
     "ast_get_symbol_source",
     "ast_search_symbols",
     "ast_find_references",
+    "ast_find_test_candidates",
     "ast_get_diagnostics",
     "ast_rename_symbol",
     "ast_replace_symbol_body",

package/dist/services/call-spines.js

@@ -0,0 +1,101 @@
+const endpointKey = (endpoint) => [endpoint.file, endpoint.symbol_path, endpoint.selector].join("\u0000");
+const sequenceKey = (values) => JSON.stringify(values);
+const exactCall = (edge) => edge.kind === "call" &&
+    edge.provenance === "compiler" &&
+    edge.confidence === "exact" &&
+    edge.resolution === "resolved" &&
+    edge.freshness.state === "fresh" &&
+    edge.compiler_authoritative;
+function assertLimit(value, minimum, name) {
+    if (!Number.isSafeInteger(value) || value < minimum)
+        throw new Error(`Call spine ${name} is invalid.`);
+    return value;
+}
+export function planCallSpines(root, edges, options) {
+    const maxDepth = assertLimit(options.max_depth, 0, "max_depth");
+    const maxNodes = assertLimit(options.max_nodes, 1, "max_nodes");
+    const maxEdges = assertLimit(options.max_edges, 1, "max_edges");
+    const accepted = edges.filter(exactCall);
+    const freshness = options.freshness?.state ?? edges[0]?.freshness.state;
+    const authorityState = freshness !== "fresh" || accepted.length !== edges.length
+        ? "untrusted"
+        : options.discovery_complete === false
+            ? "incomplete"
+            : "authoritative";
+    const reasons = new Set();
+    const rootKey = endpointKey(root);
+    const initial = { endpoint: root, endpoints: [root], relationshipIds: [], depth: 0 };
+    const records = new Map([[rootKey, initial]]);
+    const observedEdges = new Set();
+    let layer = [initial];
+    while (layer.length > 0) {
+        const candidates = new Map();
+        for (const current of layer.sort((left, right) => endpointKey(left.endpoint).localeCompare(endpointKey(right.endpoint)))) {
+            const incident = accepted
+                .filter((edge) => options.direction === "outgoing"
+                ? endpointKey(edge.source) === endpointKey(current.endpoint)
+                : endpointKey(edge.target) === endpointKey(current.endpoint))
+                .sort((left, right) => left.relationship_id.localeCompare(right.relationship_id));
+            for (const edge of incident) {
+                if (!observedEdges.has(edge.relationship_id) && observedEdges.size >= maxEdges) {
+                    reasons.add("edge_limit");
+                    continue;
+                }
+                observedEdges.add(edge.relationship_id);
+                const next = options.direction === "outgoing" ? edge.target : edge.source;
+                const key = endpointKey(next);
+                if (current.endpoints.some((endpoint) => endpointKey(endpoint) === key) || records.has(key))
+                    continue;
+                if (current.depth >= maxDepth) {
+                    reasons.add("depth_limit");
+                    continue;
+                }
+                const outgoing = options.direction === "outgoing";
+                const candidate = {
+                    endpoint: next,
+                    endpoints: outgoing ? [...current.endpoints, next] : [next, ...current.endpoints],
+                    relationshipIds: outgoing
+                        ? [...current.relationshipIds, edge.relationship_id]
+                        : [edge.relationship_id, ...current.relationshipIds],
+                    depth: current.depth + 1,
+                };
+                const previous = candidates.get(key);
+                if (!previous ||
+                    sequenceKey(candidate.relationshipIds) < sequenceKey(previous.relationshipIds))
+                    candidates.set(key, candidate);
+            }
+        }
+        const ordered = [...candidates.values()].sort((left, right) => endpointKey(left.endpoint).localeCompare(endpointKey(right.endpoint)));
+        const available = maxNodes - records.size;
+        if (ordered.length > available)
+            reasons.add("node_limit");
+        layer = ordered.slice(0, Math.max(0, available));
+        for (const record of layer)
+            records.set(endpointKey(record.endpoint), record);
+    }
+    const paths = [...records.values()]
+        .filter((record) => record.depth > 0)
+        .sort((left, right) => left.depth - right.depth ||
+        endpointKey(left.endpoint).localeCompare(endpointKey(right.endpoint)))
+        .map((record) => ({
+        endpoint: record.endpoint,
+        endpoints: record.endpoints,
+        relationship_ids: record.relationshipIds,
+    }));
+    const incomplete = authorityState !== "authoritative" || reasons.size > 0;
+    return {
+        root,
+        direction: options.direction,
+        paths,
+        visited: {
+            nodes: records.size,
+            edges: observedEdges.size,
+            max_depth: Math.max(0, ...paths.map((path) => path.relationship_ids.length)),
+        },
+        budget: { max_depth: maxDepth, max_nodes: maxNodes, max_edges: maxEdges },
+        incomplete,
+        truncation_reasons: ["depth_limit", "node_limit", "edge_limit"].filter((reason) => reasons.has(reason)),
+        authority_state: authorityState,
+        empty_proven: paths.length === 0 && !incomplete,
+    };
+}

package/dist/services/cli-project-discovery.js

@@ -0,0 +1,97 @@
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+const EXPLICIT = "Set project_root to a direct config file.";
+export class CliProjectDiscoveryError extends Error {
+    code;
+    continuation;
+    constructor(code, message, continuation) {
+        super(message);
+        this.code = code;
+        this.continuation = continuation;
+        this.name = "CliProjectDiscoveryError";
+    }
+}
+function fail(code, message, continuation) {
+    throw new CliProjectDiscoveryError(code, message, continuation);
+}
+function same(left, right) {
+    return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+async function directPath(value) {
+    let info;
+    try {
+        info = await lstat(value);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            fail("PROJECT_CONFIG_UNSAFE", "The requested CLI project location could not be inspected safely.", EXPLICIT);
+        fail("PROJECT_CONFIG_NOT_FOUND", "The requested CLI project location does not exist.", "Set project_root to an existing config file.");
+    }
+    if (info.isSymbolicLink())
+        fail("PROJECT_CONFIG_UNSAFE", "Symlinked CLI project locations are unsupported.", EXPLICIT);
+    const canonical = await realpath(value).catch(() => fail("PROJECT_CONFIG_UNSAFE", "CLI project identity could not be proven.", EXPLICIT));
+    if (!same(value, canonical))
+        fail("PROJECT_CONFIG_UNSAFE", "Symlinked CLI project ancestors are unsupported.", EXPLICIT);
+    return { path: canonical, file: info.isFile() };
+}
+async function configAt(directory, name) {
+    const candidate = path.join(directory, name);
+    try {
+        const direct = await directPath(candidate);
+        return direct.file ? direct.path : undefined;
+    }
+    catch (error) {
+        if (error instanceof CliProjectDiscoveryError && error.code === "PROJECT_CONFIG_NOT_FOUND")
+            return;
+        throw error;
+    }
+}
+async function hasGitBoundary(directory) {
+    return lstat(path.join(directory, ".git")).then(() => true, (error) => {
+        if (error.code === "ENOENT")
+            return false;
+        fail("PROJECT_CONFIG_UNSAFE", "The repository boundary could not be inspected safely.", EXPLICIT);
+    });
+}
+function relativeConfig(from, config) {
+    const relative = path.relative(from, config).split(path.sep).join("/");
+    return relative.startsWith(".") ? relative : `./${relative}`;
+}
+async function discover(start, relativeTo) {
+    const visited = new Set();
+    let directory = start;
+    while (!visited.has(directory)) {
+        visited.add(directory);
+        const [tsconfig, jsconfig] = await Promise.all([
+            configAt(directory, "tsconfig.json"),
+            configAt(directory, "jsconfig.json"),
+        ]);
+        if (tsconfig && jsconfig)
+            fail("PROJECT_CONFIG_AMBIGUOUS", "Both supported project configs exist at the nearest CLI project level.", `Set project_root to "${relativeConfig(relativeTo, tsconfig)}" or "${relativeConfig(relativeTo, jsconfig)}".`);
+        if (tsconfig || jsconfig)
+            return tsconfig ?? jsconfig;
+        if (await hasGitBoundary(directory))
+            break;
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    fail("PROJECT_CONFIG_NOT_FOUND", "No supported project config was found within the CLI discovery boundary.", "Set project_root to a config file.");
+}
+export async function resolveCliBatchProject(input, cwd) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return input;
+    const document = input;
+    const requested = document.project_root;
+    if (requested !== undefined && typeof requested !== "string")
+        return input;
+    const absolute = path.resolve(cwd, requested ?? cwd);
+    const direct = await directPath(absolute);
+    const projectRoot = direct.file
+        ? absolute.endsWith(".json")
+            ? direct.path
+            : fail("PROJECT_CONFIG_NOT_FOUND", "The explicit CLI project file is not a JSON config.", "Set project_root to a config file.")
+        : await discover(direct.path, cwd);
+    return { ...document, project_root: projectRoot };
+}