jev-agent-tools 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -9,10 +9,93 @@ modules are not a stable library API.
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-03
+
+### Added
+
+- `jev-agent-tools-mcp`: a dependency-free MCP stdio server exposing the same six
+  tools to any MCP client. It reuses the existing tool factories, session limits,
+  HTTP client and saved configuration; the binary ships as compiled JavaScript built
+  by `npm run build`.
+- MCP setup guide (`docs/mcp.md`) and a project instruction template for MCP agents
+  (`docs/agent-instructions.md`, for `CLAUDE.md`, `AGENTS.md` or Kiro steering).
+- `JEV_TOOLS_BASH` and `JEV_TOOLS_ROOT` settings (Windows bash path; MCP root).
+- MCP Registry publication: `server.json` (`io.github.NomenAK/jev-agent-tools`) and
+  `mcpName` in `package.json`. After the npm publish, the release workflow waits for the
+  approved version and its `mcpName` on npm, then publishes with a pinned, checksum-verified
+  `mcp-publisher` over GitHub OIDC; an existing registry version is skipped only
+  when its server definition matches the approved tarball's metadata.
+- `scripts/check-mcp-package.ts`: CI and release gate that installs the packed
+  tarball, checks modern discovery and all advertised legacy handshakes, and
+  exercises `jev_ask` against a local synthetic HTTP endpoint.
+- Native Windows and macOS CI for MCP, managed process termination, private
+  configuration, platform paths and the installed package; Linux retains the
+  complete offline suite.
+
+### Changed
+
+- The npm package now includes `SECURITY.md` and `docs/adr/`, which shipped
+  documentation already linked to.
+
+### Fixed
+
+- MCP command cancellation and timeout now finish process-group escalation even
+  when the parent shell exits first. Closing stdin, SIGTERM and SIGINT drain
+  outstanding tool calls before the server exits; cancelled calls stay silent.
+- Windows command cleanup maps MSYS descendants before forced termination, so
+  Git Bash fork/exec no longer hides ordinary descendants from `taskkill /T`.
+- Package checks use local archive paths on Windows and macOS; private-storage
+  test fixtures use canonical macOS temporary paths without relaxing symlink checks.
+- Modern MCP discovery now includes server identity in result metadata, and
+  tool lists declare immediately stale, private caching as required by the
+  2026-07-28 protocol.
+- MCP Registry reruns skip only an identical server definition. Divergent,
+  malformed or inconclusive responses fail; registry metadata is checked
+  against `server.json` inside the approved tarball before lookup.
+
+- In omp, first-launch Jev setup no longer waits for credential entry inside the
+  bounded `session_start` handler. The offer and input dialogs stay open while
+  users find their endpoint and key, rather than closing after the host's
+  30-second event deadline.
+- `JEV_TOOLS_MAX_USD` could be overshot by up to seven requests: concurrent batches
+  were all admitted before any cost was reported. Under a USD limit, requests are
+  now admitted one at a time, so only the final admitted request can exceed it.
+- Windows: `jev_ask` commands ran `env CI=1 bash`, which fails without `env` and
+  resolves to the WSL launcher. Git for Windows bash is now used.
+- Windows: imported providers were never found for `jev_check_diff` risk callers
+  because a repository path was resolved with platform path semantics.
+- Windows: node:test `file:///C:/...` failure locations (including `%20`) were not
+  mapped back to repository files.
+- Windows: an 8.3 short working directory (for example `C:\Users\NAME~1`) did not
+  relate to the Git root, which emptied import closures and file references.
+- Line endings are pinned to LF via `.gitattributes`, so lint and the rule/guideline
+  parity check pass on Windows checkouts with `core.autocrlf=true`.
+- Windows: saving or loading `/jev-setup` configuration always failed, because the
+  privacy check read POSIX mode bits, which Windows reports as `0o666` for every file.
+  Windows now checks the folder and file access lists (allow entries limited to the
+  current user, SYSTEM and Administrators) and restricts a new folder when saving.
+- Tests: `secret-input` passed a `C:\` path to `import()`; the risk-caller latency
+  test compared one run with a fixed 250 ms and now checks 250- to 1000-line scaling.
+
+## [0.1.4] - 2026-10-02
+
+### Added
+
+- Interactive configuration for pi and omp: first-launch offer, `/jev-setup`, masked
+  key entry, `--jev-skip-setup`, `--jev-url` and `--jev-model`. Configuration applies
+  immediately; optional saving uses a private file outside the repository and stores the
+  key in plaintext. No dialog appears in print, JSON, RPC or sub-agent sessions.
+
+### Changed
+
+- Release publication uses trusted publishing (OIDC) without a temporary npm token.
+- Document the npm release's verified pi 1.0.0 integration, simulated-service smoke
+  scope and non-blocking `@sinclair/typebox` packaging warning.
+
 ## [0.1.3] - 2026-10-02
 
-Initial npm release candidate, under the name `jev-agent-tools`. Versions 0.1.0,
-0.1.1 and 0.1.2 were tagged but never published; their outcomes are recorded below.
+First npm release, published as `jev-agent-tools`. Versions 0.1.0, 0.1.1 and 0.1.2
+were tagged but never published; their outcomes are recorded below.
 
 ### Added
 
@@ -59,7 +142,9 @@ Tagged but never published to npm: the unscoped package name was rejected.
 
 Tagged but never published to npm: the publish workflow failed before upload.
 
-[Unreleased]: https://github.com/NomenAK/jev-tools/compare/v0.1.3...HEAD
+[Unreleased]: https://github.com/NomenAK/jev-tools/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/NomenAK/jev-tools/compare/v0.1.4...v0.2.0
+[0.1.4]: https://github.com/NomenAK/jev-tools/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/NomenAK/jev-tools/compare/v0.1.0...v0.1.3
 [0.1.2]: https://github.com/NomenAK/jev-tools/tree/v0.1.2
 [0.1.1]: https://github.com/NomenAK/jev-tools/tree/v0.1.1

package/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+Issues and external pull requests are welcome. Use English for issues, pull requests, documentation, comments, and test descriptions; keep non-English fixtures when they test language or encoding behavior. For vulnerabilities, follow [SECURITY.md](SECURITY.md).
+
+## Issues or pull requests?
+
+Open an issue for a reproducible product bug or a feature request. Include the package and host versions, expected and actual behavior, and a minimal sanitized reproduction. Small, focused fixes or documentation corrections can go straight to a pull request. Discuss new tools, contract changes, and research-dependent features in an issue before implementing them.
+
+An issue may describe an unmet need without claiming that a method already works. Features such as co-change suggestions are not accepted for implementation without a new, validated method. Propose the method, its evaluation protocol, and reproducible evidence in an issue first; an unvalidated heuristic or a renamed version of it is not enough.
+
+## Local checks
+
+Use Node.js 24 or newer and npm. From a checkout, with development dependencies enabled:
+
+```sh
+npm ci --include=optional
+npm run typecheck
+npm run build
+npm run check:imports
+npm run lint
+npm test
+```
+
+`npm run build` compiles only the MCP server into `dist/` (git-ignored); `npm pack` runs it automatically. To try the server against a checkout, see [From a clone](docs/mcp.md#from-a-clone). CI packs the package and runs `node scripts/check-mcp-package.ts <tarball>`: it installs the tarball into an empty directory, checks modern discovery and all advertised legacy handshakes, lists the six tools with their schemas and caching fields, and runs `jev_ask` through a local synthetic HTTP endpoint. This verifies installed integration, not live model accuracy. Linux runs the full offline suite; native Windows and macOS jobs run targeted MCP, process, configuration and packaging checks.
+
+## Releases
+
+Maintainers release by pushing a `vX.Y.Z` tag on reviewed `main`. Before tagging, set the same version in `package.json`, in both `version` fields of `server.json`, and in a `CHANGELOG.md` section; `test/server-json.test.ts` fails if they drift. [`publish.yml`](.github/workflows/publish.yml) then packs once, checks the packed MCP server, publishes the approved tarball to npm with trusted publishing, publishes `server.json` to the MCP Registry with GitHub OIDC, and creates a draft GitHub Release. Each publication step skips a version that already exists with the same content and fails on anything inconclusive.
+
+Keep optional native dependencies enabled for development. These checks make no Jev API calls and need no Jev key. Dependency installation may use the network. Some runner-identity tests skip when additional runners are unavailable locally; CI provisions those runners in [.github/workflows/ci.yml](.github/workflows/ci.yml).
+
+Maintainers run a private regression probe on reviewed release candidates before release and on the published package before announcing it. Contributors do not need access to that probe or its credentials.
+
+## Pull request expectations
+
+Keep changes focused. Explain the user-visible behavior, link the relevant issue when there is one, and report the checks you actually ran, including skips or limitations. Add or update deterministic tests for changed behavior and regressions, and update affected documentation. Public CI must pass without service credentials.
+
+Do not make accuracy, recall, speed, or other measurement claims without describing the method, baseline, data, and limitations sufficiently to reproduce and review them. Do not include credentials, raw service responses, private data, or personal configuration in issues, patches, or logs. Use synthetic or sanitized examples.
+
+Check the name and email attached to your commits before submitting; GitHub's noreply email is an option if you do not want to publish a personal email address.

package/README.md

@@ -1,31 +1,82 @@
 # jev-agent-tools
 
-Six evidence-oriented tools for pi and omp, compatible with the Jev API format. Use them to navigate unfamiliar code, ask typed questions about repository evidence, review completed changes and select existing tests. They complement reading, searching and execution; they do not replace them.
+Six evidence-oriented tools for pi, omp and any MCP client, compatible with the Jev API format. Use them to navigate unfamiliar code, ask typed questions about repository evidence, review completed changes and select existing tests. They complement reading, searching and execution; they do not replace them.
+
+[![jev-agent-tools launch video: six tools, one habit, show the evidence. Click to play (74 s).](docs/media/jev-agent-tools-launch.jpg)](docs/media/jev-agent-tools-launch.mp4)
+
+[Watch the launch video](docs/media/jev-agent-tools-launch.mp4) (74 s, MP4).
 
 ## Install
 
-Install through your host's package manager. The npm package is `jev-agent-tools`. It ships TypeScript sources; no separate compilation is required.
+Install through your host's package manager, or register the MCP server with an MCP client. The npm package is `jev-agent-tools`. pi and omp load its TypeScript sources directly; the MCP server ships prebuilt.
 
 ### pi
 
 ```sh
-pi install npm:jev-agent-tools@0.1.3
+pi install npm:jev-agent-tools@0.2.0
 # Project-local installation:
-pi install -l npm:jev-agent-tools@0.1.3
+pi install -l npm:jev-agent-tools@0.2.0
 ```
 
 ### omp
 
 ```sh
-omp plugin install jev-agent-tools@0.1.3
+omp plugin install jev-agent-tools@0.2.0
 ```
 
+### Any MCP client
+
+Since version 0.2.0, the package also ships `jev-agent-tools-mcp`, a stdio MCP server that exposes the same six tools to any MCP client: Claude Code, Claude Desktop, Kiro, Cursor, VS Code, Codex CLI and others. A typical `mcpServers` entry:
+
+```json
+{
+  "mcpServers": {
+    "jev": {
+      "command": "npx",
+      "args": ["-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "/path/to/repository"],
+      "env": {
+        "JEV_TOOLS_URL": "${JEV_TOOLS_URL}",
+        "JEV_TOOLS_API_KEY": "${JEV_TOOLS_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+On Windows most clients start commands without a shell, so use `"command": "cmd"` with `"/c", "npx"` at the start of `args`. The [MCP setup guide](docs/mcp.md) has per-client files, CLI commands, variable interpolation, verification and troubleshooting. Releases are also listed in the official MCP Registry as `io.github.NomenAK/jev-agent-tools`. Add the [agent instructions](docs/agent-instructions.md) to `CLAUDE.md`, `AGENTS.md` or a Kiro steering file so the agent uses and reads the tools correctly.
+
+The server reads the same environment variables as pi and omp and the configuration saved by `/jev-setup`. One server process is one session. The automatic run-end documentation check does not exist in MCP; call `jev_check_diff` with `check: "docs"` instead. `jev_ask` is marked as not read-only while commands are enabled; set `JEV_TOOLS_ALLOW_COMMAND=0` to remove `command` from its schema.
+
 ### Requirements and compatibility
 
-Requires Node.js 24 or later. Supported host baselines are pi 0.87.1 and omp 18.4.10. These are support baselines, not claims that every later version has been individually validated. omp uses its Bun runtime; Node.js is also required for Node-based project checks. Git and, for optional command evidence, Bash must be available. Optional native parsers and file-search acceleration may be unavailable on some platforms; affected tools report their limitations.
+Requires Node.js 24 or later. Supported host baselines are pi 0.87.1 and omp 18.4.10. These are support baselines, not claims that every later version has been individually validated. omp uses its Bun runtime; Node.js is also required for Node-based project checks. Git and, for optional command evidence, Bash must be available. On Windows, command evidence uses Git for Windows bash (found next to `git` on `PATH` or under Program Files); the WSL `bash.exe` launchers are never used. Set `JEV_TOOLS_BASH` to the full path of another bash. Optional native parsers and file-search acceleration may be unavailable on some platforms; affected tools report their limitations.
+
+The published `jev-agent-tools@0.1.3` package was also checked with **pi 1.0.0** on Linux under Node.js 24.15.0: npm installation, TypeScript checking against the host types, all six tools in the actual CLI, and reading-guide injection passed. The CLI smoke used a simulated conversation provider and Jev endpoint; it verifies host integration, not live model accuracy or every tool scenario.
+
+**pi 1.0.0 packaging warning:** the package declares `@sinclair/typebox` in `dependencies`, while pi expects host-provided extension modules in `peerDependencies` with a `"*"` range. pi warns that separately installed copies can create duplicate runtime modules. The warning did not prevent the smoke from completing; it remains a packaging issue, not a claim of warning-free compatibility.
 
 ## Configure
 
+### Interactive setup
+
+In the main interactive terminal of pi or omp, a first launch without configuration offers **Configure now / Later**. Run `/jev-setup` at any time to change the endpoint, model or key. The key is typed in a masked field and is never passed as a command-line argument. Choose **This session only** (nothing is written) or **Save for future sessions**. Cancelling at any step changes nothing.
+
+| Flag | Effect |
+|---|---|
+| `--jev-skip-setup` | Suppress the first-launch offer for this run; `/jev-setup` still works. |
+| `--jev-url <url>` | Endpoint for this run. |
+| `--jev-model <name>` | Jev model for this run, not the conversation model. |
+
+No dialog appears in print, JSON or RPC modes, or in sub-agents; configure those with the environment variables below. Changes apply immediately, without restarting the host.
+
+Interactive setup waits for submission or cancellation, without a credential-entry timeout. The first-launch offer does not keep the host's startup event handler open while you find the endpoint or key.
+
+**Precedence per field:** environment variable, then launch flag, then this session's setup, then saved configuration, then the default model `openjev`. A field set by the environment or a flag is shown as controlled and is never saved.
+
+**Saved configuration** lives outside the repository at `$XDG_CONFIG_HOME/jev-agent-tools/config.json` (default `~/.config/jev-agent-tools/config.json`), in a private directory (`0700`) with a private file (`0600`). On Windows, where mode bits do not exist, privacy is the folder's access list: saving restricts it to you, SYSTEM and Administrators, and loading refuses any other account with access. **The key is stored in plaintext, not encrypted.** Storage that is a symlink, accessible to other users, not owned by you or malformed is refused rather than overwritten. The MCP server also reads this file, after environment variables.
+
+### Environment variables
+
 Set these before starting the host, using your own endpoint and credentials:
 
 ```sh
@@ -35,7 +86,7 @@ export JEV_TOOLS_API_KEY="${YOUR_JEV_API_KEY}"
 export JEV_TOOLS_MODEL="openjev"
 ```
 
-`YOUR_*` placeholders are inputs you supply, not additional product settings. Configuration is read when the extension loads; restart the host after changing it.
+`YOUR_*` placeholders are inputs you supply, not additional product settings. Environment variables are read when the extension loads and take precedence over everything else.
 
 | Variable | Meaning |
 |---|---|
@@ -46,6 +97,8 @@ export JEV_TOOLS_MODEL="openjev"
 | `JEV_TOOLS_MAX_USD` | Session-wide finite non-negative cost limit, including fractions; absent or empty means unlimited. Invalid values refuse requests. |
 | `JEV_TOOLS_ALLOW_COMMAND` | `0` disables `command` in `jev_ask`; otherwise commands run with ordinary shell permissions, without an additional sandbox. |
 | `JEV_TOOLS_AUTO_DOCS` | `0` disables the automatic run-end documentation check. |
+| `JEV_TOOLS_BASH` | Optional full path of the bash used for `jev_ask` commands on Windows. |
+| `JEV_TOOLS_ROOT` | MCP server only: repository directory when `--root` is not given. |
 
 Without the endpoint or key, tools remain registered and explain the missing configuration; the automatic documentation check is disabled. There is no fallback to a chat model. Per-tool `max_calls` is separate from session limits. A model name echoed by the response does not establish which model was actually served.
 
@@ -86,15 +139,17 @@ The extension supplies the shared reading guide in both hosts. omp discovers ena
 
 > Before concluding that a failure is a code bug, an incorrect test or an environment problem, or that a plan matches documentation, pass the relevant files to [jev_ask](docs/tools/jev_ask.md) and weigh its answer against your own reading. Include both the failing test and the code it exercises; identify any conclusion that remains unconfirmed.
 
+MCP clients receive the guide as server `instructions`, which some clients ignore. Add the [agent instructions](docs/agent-instructions.md) to the project's `CLAUDE.md`, `AGENTS.md` or Kiro steering file.
+
 ## Data and command safety
 
 Repository evidence, notes and optional command output are sent to your configured endpoint. Review its data-handling policy before using confidential repositories. See [security guidance](SECURITY.md).
 
-File collection is confined to the repository: absolute paths, parent traversal, escaping symlinks, Git metadata and internal URLs are not file inputs. Build output, binaries, lockfiles and oversized files are skipped or refused with visible limits; evidence is not silently truncated into a verdict. This confinement does **not** sandbox a command. `jev_ask` commands can read, write or access the network with the host's shell permissions. omp uses execution approval for commands; pi does not supply an additional per-tool command approval. Set `JEV_TOOLS_ALLOW_COMMAND=0` to disable them.
+File collection is confined to the repository: absolute paths, parent traversal, escaping symlinks, Git metadata and internal URLs are not file inputs. Build output, binaries, lockfiles and oversized files are skipped or refused with visible limits; evidence is not silently truncated into a verdict. This confinement does **not** sandbox a command. `jev_ask` commands can read, write or access the network with the host's shell permissions. omp uses execution approval for commands; pi does not supply an additional per-tool command approval; MCP clients apply their own tool approval, and the server marks `jev_ask` as not read-only. Set `JEV_TOOLS_ALLOW_COMMAND=0` to disable them.
 
 ## Automatic documentation check
 
-On a dirty tree, the extension can check existing Markdown documentation once at run end against changes from `HEAD`, including untracked files. A flagged existing sentence can request one additional turn to update it or explain why it remains correct. Merely unsure sections do not trigger another turn. Missing configuration, disabled automation, invalid/exhausted session budgets or a clean tree skip the check. Errors and timeout do not block the host. This is not a check for every missing documentation obligation.
+On a dirty tree, the extension can check existing Markdown documentation once at run end against changes from `HEAD`, including untracked files. A flagged existing sentence can request one additional turn to update it or explain why it remains correct. Merely unsure sections do not trigger another turn. Missing configuration, disabled automation, invalid/exhausted session budgets or a clean tree skip the check. Errors and timeout do not block the host. This is not a check for every missing documentation obligation. The MCP server has no run-end hook; there, call `jev_check_diff` with `check: "docs"` before finishing.
 
 ## Known limits
 

package/SECURITY.md

@@ -0,0 +1,27 @@
+# Security policy
+
+## Supported versions
+
+Security fixes target the latest patch release in the 0.1.x series. Older 0.1.x patches should be upgraded; 0.0.x and unreleased snapshots are not supported releases.
+
+## Report privately
+
+Use GitHub's [Report a vulnerability](https://github.com/NomenAK/jev-tools/security/advisories/new) form. Do not disclose vulnerabilities in public issues or pull requests. If the form is unavailable, open an issue asking to restore private reporting, without vulnerability details. There is no email reporting channel.
+
+Include the affected version, impact, and a minimal reproduction using synthetic data. Never include live credentials, private repository contents, or personal configuration. If a credential may have been exposed, revoke or rotate it independently of this report.
+
+This is a solo-maintained project. Reports are reviewed on a best-effort basis; there is no guaranteed acknowledgement or fix deadline. Follow-up and disclosure coordination take place in the private report. Please coordinate public disclosure there.
+
+## Scope and trust boundaries
+
+Report repository-confinement escapes in file evidence collection, including reads outside the selected repository; unintended secret exposure caused by jev-tools; and unintended command execution or bypasses of disabled command execution.
+
+File evidence collection is confined to the repository, but optional commands are not sandboxed: they run with the host's permissions and may read or modify files or access the network. `JEV_TOOLS_ALLOW_COMMAND=0` disables this command path. Selected repository evidence and requested command output are sent to the configured API endpoint; automatic secret redaction is not promised. Review the data and endpoint before use.
+
+Saved interactive configuration stores the API key in plaintext in a private user-level file (`~/.config/jev-agent-tools/config.json` by default). Privacy uses each operating system's own model: owner-only mode bits on POSIX; on Windows, an access list whose allow entries are only the current user, SYSTEM and Administrators, read by SID through the system Windows PowerShell. Protect the account and back-ups accordingly, or use environment variables from a secret manager instead.
+
+The MCP server (`jev-agent-tools-mcp`) has the same boundaries. It talks to its client only over stdio and opens no network listener. MCP client configuration files that contain a literal API key are as sensitive as the saved configuration; prefer the client's environment-variable interpolation and do not commit such files. Tool approval is the MCP client's responsibility; the server marks `jev_ask` as not read-only while commands are enabled.
+
+Command cancellation and timeout, and MCP connection shutdown, complete bounded termination of the managed process group on POSIX or await the system process-tree termination operation on Windows. This is cleanup, not containment: deliberately detached descendants or processes that escape that tree are not tracked, and previously completed side effects are not undone.
+
+Expected execution of an explicitly supplied command, intentional submission of evidence, inaccurate judgments, and ordinary bugs or feature requests are not by themselves security vulnerabilities. Report ordinary product problems through issues; report host or API-service vulnerabilities to their respective maintainers. If unsure about a jev-tools security impact, use the private form.

package/dist/adapters/analysis-context.js

@@ -0,0 +1,75 @@
+import { createHash } from "node:crypto";
+import { tokenize, } from "../core/lexical.js";
+import { loadSyntaxRootParser } from "./syntax.js";
+/** Owns one invocation's source versions; never retains repository data across calls. */
+export async function createAnalysisContext(counter, sourceParser) {
+    const fingerprints = new Map();
+    const fingerprint = (text) => {
+        let value = fingerprints.get(text);
+        if (value === undefined) {
+            value = createHash("sha256").update(text).digest("hex");
+            fingerprints.set(text, value);
+        }
+        return value;
+    };
+    const lexical = new Map();
+    const tokenizeSource = (path, text, python = false) => {
+        const version = fingerprint(text);
+        let versions = lexical.get(path);
+        if (!versions) {
+            versions = new Map();
+            lexical.set(path, versions);
+        }
+        const key = `${version}:${python}`;
+        let tokens = versions.get(key);
+        if (!tokens) {
+            counter?.tokenized(path, version);
+            tokens = tokenize(text, python);
+            versions.set(key, tokens);
+        }
+        return tokens;
+    };
+    const source = sourceParser ?? (await loadSyntaxRootParser());
+    if (!source)
+        return {
+            parser: undefined,
+            fingerprint,
+            counter,
+            tokenize: tokenizeSource,
+        };
+    const roots = new Map();
+    const parser = {
+        supports: source.supports,
+        parseRaw(path, text) {
+            const version = fingerprint(text);
+            let versions = roots.get(path);
+            if (!versions) {
+                versions = new Map();
+                roots.set(path, versions);
+            }
+            let parsed = versions.get(version);
+            if (!parsed) {
+                counter?.parsed(path, version);
+                parsed = source.parseRaw(path, text);
+                versions.set(version, parsed);
+            }
+            return parsed;
+        },
+        parse(path, text) {
+            const parsed = this.parseRaw(path, text);
+            if (!parsed.ok)
+                return parsed;
+            return parsed.root.find({ rule: { kind: "ERROR" } })
+                ? { ok: false, error: "Source syntax incomplete" }
+                : parsed;
+        },
+        declarations: source.declarations,
+    };
+    return {
+        parser,
+        fingerprint,
+        counter,
+        tokenize: tokenizeSource,
+        resolved: (path, text) => counter?.resolved(path, fingerprint(text)),
+    };
+}

package/dist/adapters/ask-files.js

@@ -0,0 +1,189 @@
+import { readdir, stat } from "node:fs/promises";
+import { dirname, isAbsolute, matchesGlob, relative, resolve } from "node:path";
+import { CONCURRENCY, MAX_FILES, TIMEOUT_MS } from "../constants.js";
+import { checkFileAdmission, collectFiles, resolveInsideRepo, } from "./files.js";
+const excludedDirectories = new Set(["node_modules", ".git", "dist", "build"]);
+const lockfile = /(?:^|\/)(?:package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|Cargo\.lock|Gemfile\.lock|poetry\.lock|uv\.lock|composer\.lock|Pipfile\.lock|go\.sum)$/;
+export async function collectAskFiles(cwd, paths, signal, exec) {
+    if (!paths.length)
+        return {
+            ok: false,
+            error: "Provide at least one path, directory or glob.",
+        };
+    for (const path of paths) {
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path))
+            return {
+                ok: false,
+                error: `Internal URLs are not files; use read for ${path}.`,
+            };
+        if (isAbsolute(path) || path.split(/[\\/]/).includes(".."))
+            return {
+                ok: false,
+                error: `Path must remain inside the repository: ${path}.`,
+            };
+    }
+    const skipped = new Set();
+    const candidates = new Set();
+    try {
+        let inventory;
+        if (exec) {
+            const result = await exec("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z"], { cwd, timeout: TIMEOUT_MS, signal });
+            if (result.code === 0)
+                inventory = new Set(result.stdout.split("\0").filter(Boolean));
+        }
+        const add = async (path) => {
+            const admission = await checkFileAdmission(cwd, path, exec, signal, inventory);
+            if (!admission.ok) {
+                skipped.add(`${path} (${admission.error})`);
+                return;
+            }
+            if (path.split("/").some((part) => excludedDirectories.has(part)))
+                skipped.add(`${path} (build output or dependencies)`);
+            else if (lockfile.test(path))
+                skipped.add(`${path} (lockfile)`);
+            else
+                candidates.add(path);
+        };
+        const walk = async (directory, pattern) => {
+            signal?.throwIfAborted();
+            const safe = await resolveInsideRepo(cwd, directory);
+            if (!safe.ok) {
+                skipped.add(`${directory} (${safe.error})`);
+                return;
+            }
+            const entries = await readdir(safe.abs, { withFileTypes: true });
+            await Promise.all(entries.map(async (entry) => {
+                const path = relative(cwd, resolve(cwd, directory, entry.name)).replaceAll("\\", "/");
+                if (entry.isSymbolicLink()) {
+                    skipped.add(`${path} (symbolic link)`);
+                    return;
+                }
+                if (entry.isDirectory()) {
+                    if (excludedDirectories.has(entry.name)) {
+                        skipped.add(`${path}/ (build output or dependencies)`);
+                        return;
+                    }
+                    await walk(path, pattern);
+                    return;
+                }
+                if (entry.isFile() &&
+                    (!pattern ||
+                        matchesGlob(path
+                            .split("/")
+                            .map((part) => part.startsWith(".") ? `__dot__${part.slice(1)}` : part)
+                            .join("/"), pattern
+                            .split("/")
+                            .map((part) => part.startsWith(".") ? `__dot__${part.slice(1)}` : part)
+                            .join("/"))))
+                    await add(path);
+            }));
+        };
+        for (const input of paths) {
+            signal?.throwIfAborted();
+            const safe = await resolveInsideRepo(cwd, input);
+            const info = safe.ok
+                ? await stat(safe.abs).catch(() => undefined)
+                : undefined;
+            if (info && safe.ok) {
+                if (info.isFile()) {
+                    const admission = await checkFileAdmission(cwd, safe.rel, exec, signal, inventory);
+                    if (!admission.ok)
+                        return admission;
+                }
+                if (input.split("/").some((part) => excludedDirectories.has(part))) {
+                    skipped.add(`${input} (build output or dependencies)`);
+                    continue;
+                }
+                if (info.isDirectory())
+                    await walk(safe.rel || ".");
+                else if (info.isFile()) {
+                    const admission = await checkFileAdmission(cwd, safe.rel, exec, signal, inventory);
+                    if (!admission.ok)
+                        return admission;
+                    await add(safe.rel);
+                }
+                else
+                    skipped.add(`${input} (not a regular file)`);
+            }
+            else {
+                const parts = input.split("/");
+                const wildcard = parts.findIndex((part) => /[?*[\]{}]/.test(part));
+                if (wildcard < 0) {
+                    if (!safe.ok && !safe.error.includes("ENOENT"))
+                        return safe;
+                    skipped.add(`${input} (missing)`);
+                    continue;
+                }
+                const prefix = parts.slice(0, wildcard).join("/") || ".";
+                const prefixLocation = await resolveInsideRepo(cwd, prefix);
+                if (!prefixLocation.ok)
+                    return prefixLocation;
+                const pattern = input.replace(/^\.\//, "");
+                if (inventory) {
+                    for (const path of inventory) {
+                        const dotPath = path
+                            .split("/")
+                            .map((part) => part.startsWith(".") ? `__dot__${part.slice(1)}` : part)
+                            .join("/");
+                        const dotPattern = pattern
+                            .split("/")
+                            .map((part) => part.startsWith(".") ? `__dot__${part.slice(1)}` : part)
+                            .join("/");
+                        if (matchesGlob(dotPath, dotPattern))
+                            await add(path);
+                    }
+                }
+                else
+                    await walk(prefix, pattern);
+            }
+        }
+        const files = [];
+        const sorted = [...candidates].sort();
+        const contributions = new Map();
+        for (const path of sorted) {
+            const directory = dirname(path);
+            contributions.set(directory, (contributions.get(directory) ?? 0) + 1);
+        }
+        let accepted = 0;
+        for (let i = 0; i < sorted.length; i += CONCURRENCY) {
+            const rows = await Promise.all(sorted.slice(i, i + CONCURRENCY).map(async (path) => {
+                const result = await collectFiles(cwd, [path], signal, {
+                    exec,
+                    inventory,
+                });
+                if (!result.ok) {
+                    skipped.add(`${path} (${result.error})`);
+                    return;
+                }
+                const identity = result.identities[0];
+                if (!identity)
+                    return;
+                if (identity.content.includes("\0") ||
+                    identity.readSha256 !== identity.insertedSha256) {
+                    skipped.add(`${path} (binary or invalid UTF-8)`);
+                    return;
+                }
+                return { path, content: identity.content, identity };
+            }));
+            for (const file of rows)
+                if (file) {
+                    accepted++;
+                    if (files.length < MAX_FILES)
+                        files.push(file);
+                }
+            if (accepted > MAX_FILES) {
+                const largest = [...contributions]
+                    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+                    .slice(0, 5);
+                return {
+                    ok: false,
+                    error: `At least ${accepted} files exceeds MAX_FILES=${MAX_FILES}; narrow paths. Largest expanded directories: ${largest.map(([path, count]) => `${path}: ${count}`).join(", ")}.`,
+                };
+            }
+        }
+        return { ok: true, files, skipped: [...skipped].sort() };
+    }
+    catch (error) {
+        return { ok: false, error: `Cannot expand paths: ${String(error)}` };
+    }
+}