Merge pull request #2 from magaransoft/refactor-tool-harness-unification

refactor: tool-harness + sbt/dotnet/formatter wrappers (v1.2.0)

Author: Blanquitoh

.github/workflows/ci.yml

@@ -36,6 +36,24 @@ jobs:
       - name: run hook tests
         run: bash hooks/tests/run.sh
 
+  harness-tests:
+    name: harness + proxy smoke (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: run harness + proxy smoke tests
+        run: node --test bin/tool-harness.test.js bin/tool-server-proxy.test.js
+
   fixture-probe:
     name: fixture probe (${{ matrix.os }})
     runs-on: ${{ matrix.os }}
@@ -60,6 +78,10 @@ jobs:
         run: |
           npm i -g pyright typescript-language-server typescript
 
+      - name: install formatter tools (opt-in wrappers)
+        run: |
+          npm i -g prettier eslint
+
       - name: install jq (linux)
         if: matrix.os == 'ubuntu-latest'
         run: sudo apt-get update && sudo apt-get install -y jq
@@ -72,5 +94,97 @@ jobs:
         if: matrix.os == 'macos-latest'
         run: brew install jdtls
 
-      - name: probe fixtures
-        run: bash scripts/verify.sh
+      - name: install wrapper symlinks into ~/.claude
+        run: |
+          mkdir -p ~/.claude
+          ./scripts/install.sh
+
+      - name: probe fixtures + diff baselines (shape-gate)
+        # Body-sha check gated behind VERIFY_STRICT_SHA — CI runners install
+        # the latest pyright/ts-ls/csharp-ls/jdtls, which can emit
+        # version-specific serialization differences even when semantics
+        # are identical. Shape (top_level + total_nodes counts) still
+        # hard-fails on structural regressions; sha drift warns.
+        run: bash scripts/verify.sh --diff-baselines
+
+  opt-in-probe:
+    name: opt-in wrapper smoke (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: setup python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: install jq (linux)
+        if: matrix.os == 'ubuntu-latest'
+        run: sudo apt-get update && sudo apt-get install -y jq
+
+      - name: install jq (macos)
+        if: matrix.os == 'macos-latest'
+        run: brew install jq
+
+      - name: install prettier + eslint
+        run: npm i -g prettier eslint
+
+      - name: install dotnet (macos)
+        if: matrix.os == 'macos-latest'
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '9.0.x'
+
+      - name: install dotnet (linux)
+        if: matrix.os == 'ubuntu-latest'
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '9.0.x'
+
+      - name: install sbt (macos)
+        if: matrix.os == 'macos-latest'
+        run: brew install sbt
+
+      - name: install sbt (linux)
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          sudo mkdir -p /etc/apt/keyrings
+          curl -sL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x2EE0EA64E40A89B84B2DF73499E82A75642AC823" \
+            | sudo gpg --dearmor -o /etc/apt/keyrings/sbt.gpg
+          echo "deb [signed-by=/etc/apt/keyrings/sbt.gpg] https://repo.scala-sbt.org/scalasbt/debian all main" \
+            | sudo tee /etc/apt/sources.list.d/sbt.list
+          sudo apt-get update
+          sudo apt-get install -y sbt
+
+      - name: install wrapper symlinks into ~/.claude
+        run: |
+          mkdir -p ~/.claude
+          ./scripts/install.sh
+
+      - name: smoke prettier-direct
+        run: |
+          bin/prettier-direct call format-file \
+            "{\"filepath\":\"$PWD/fixtures/node-formatter/hello.ts\"}" \
+            "$PWD/fixtures/node-formatter"
+
+      - name: smoke eslint-direct
+        run: |
+          bin/eslint-direct call version '{}' "$PWD/fixtures/node-formatter"
+
+      - name: smoke dotnet-direct
+        run: |
+          bin/dotnet-direct call version '{}' "$PWD/fixtures/dotnet-csproj"
+
+      - name: smoke sbt-direct (non-fatal — sbt cold JVM may be slow on CI)
+        continue-on-error: true
+        run: |
+          bin/sbt-direct call version '{}' "$PWD/fixtures/scala-sbt"

CHANGELOG.md

@@ -4,6 +4,59 @@ All notable changes to this project will be documented here.
 
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
 
+## [1.2.0] — 2026-04-22
+
+### Added
+- `bin/adapters/sbt-thin-client.js` — persistent-JVM sbt adapter. Activated via `SBT_DIRECT_MODE=thin-client` or `--mode thin-client`. Coordinator spawns `sbt` in server mode once per workspace and proxies each `/call` through `sbt --client "<task>"`; warm calls land in 200-500ms vs 20-40s one-shot cold. Adoption: attaches to an externally-running `sbt shell` if `target/active.json` + live socket detected. Requires `install.sh` allowlist for ipcsocket paths (pre-merged into `sandbox.filesystem.allowWrite`).
+- `hooks/prewarm-direct-wrappers.py` — SessionStart hook. Iterates `~/.cache/*-direct/*/` slots, probes each with `GET /health`, fires `<wrapper>-direct start <workspace>` in the background for any dead slot. First `call` in a new session is warm.
+- `install.sh` — wires the prewarm hook into `~/.claude/settings.json`'s `hooks.SessionStart` (idempotent, `unique_by(.command)`). `uninstall.sh` removes it symmetrically.
+- `scripts/verify.sh VERIFY_STRICT_SHA=1` — env-gated strict mode for CI. Default (unset/0) treats sha256-body mismatch as a warning so downstream users on different pyright/tsserver/csharp-ls versions don't fail the gate; structural-shape match (top_level + total_nodes) remains hard either way. CI workflow exports `VERIFY_STRICT_SHA=1`.
+- `bin/tool-harness.js` — shared coordinator primitives: `resolveWorkspace`, `stateDir`, `freePort`, `serveHttp`, `invalidationLoop`, `callLog`, plus `framing` readers/writers (contentLength, jsonLine, tsserverMixed) and a `jsonRpcClient` correlation helper
+- `bin/tool-server-proxy.js` — external-child coordinator; adapters declare `children[]`, `init`, `onChildMessage`, `call`, `triggers`
+- `bin/node-formatter-daemon.js` — in-process Node-library coordinator (sibling of tool-server-proxy); adapters declare `preload(workspace)` + `call(req, {pkg, state})`
+- `bin/adapters/lsp-stdio.js` — LSP adapter (py/ts/cs/java); extracted from monolithic `lsp-stdio-proxy.js`
+- `bin/adapters/vue-hybrid.js` — Vue LS v3 + tsserver hybrid adapter; extracted from `vue-direct-coordinator.js`
+- `bin/adapters/sbt-oneshot.js` + `bin/sbt-direct` + `bin/sbt-direct-coordinator.js` + `fixtures/scala-sbt/` — per-call sbt coordinator (`task`, `reload`, `version`)
+- `bin/adapters/dotnet-cli.js` + `bin/dotnet-direct` + `bin/dotnet-direct-coordinator.js` + `fixtures/dotnet-csproj/` — per-call dotnet coordinator (11 methods: build/test/restore/publish/run/pack/…); MSBuild build-server handles warm persistence transparently
+- `bin/adapters/prettier.js` + `bin/prettier-direct` + `bin/prettier-direct-daemon.js` + `fixtures/node-formatter/` — in-process prettier daemon (`format`, `check`, `format-file`, `resolve-config`, `version`)
+- `bin/adapters/eslint.js` + `bin/eslint-direct` + `bin/eslint-direct-daemon.js` — in-process eslint daemon (`lint-text`, `lint-files`, `fix-text`, `format-results`, `version`)
+- `bin/adapters/scalafmt-cli.js` + `bin/scalafmt-direct` + `bin/scalafmt-direct-coordinator.js` — per-call scalafmt coordinator (`format-stdin`, `format-files`, `check-files`, `version`)
+- `scripts/capture-baseline.sh` + `fixtures/baselines/*.json` — per-wrapper JSON baselines (cold/warm timings + response sha256 + shape summary) for 5 LSP wrappers
+- `scripts/verify.sh --json` and `scripts/verify.sh --diff-baselines` modes
+- `docs/per-language/sbt.md`, `docs/per-language/dotnet.md`, `docs/per-language/node-formatters.md`, `docs/per-language/scalafmt.md`
+- `MIGRATION.md` — describes the refactor, back-compat guarantees, rollback tags
+- `CONTRIBUTING.md` — new "Architecture overview" + rewritten "Hybrid servers" + "Non-LSP tools" sections covering the adapter contract for both module families
+
+### Changed
+- `bin/lsp-stdio-proxy.js` body replaced with composition of `tool-harness` + `tool-server-proxy` + `adapters/lsp-stdio`. Steady-state response shape + state-dir layout byte-identical; CLI unchanged. External Node importers keep working — the file name and argv contract are preserved.
+- `bin/vue-direct-coordinator.js` body similarly replaced, now composing `tool-harness` + `tool-server-proxy` + `adapters/vue-hybrid`. Vue LS v3 + tsserver bridging preserved verbatim (configurePlugin → warmup → init order, tsserver/request↔response tuple unwrap + double-wrap).
+- `bin/py-direct`, `bin/ts-direct`, `bin/cs-direct`, `bin/java-direct` now pass `--tool-name <wrapper>` so the harness's `stateDir` resolves to the wrapper's existing slot instead of drifting to `~/.cache/lsp-stdio-proxy-direct/…`.
+- `scripts/install.sh` symlinks the new shared modules + adapters dir + 5 opt-in wrappers + their coordinators. Merges new permission entries + sandbox-write allowlist entries for the new cache dirs.
+- `README.md` lists the new opt-in wrappers; architecture section restructured (layout vs behavior) to describe the three-module split.
+
+### Fixed
+- Prettier/eslint adapter preload now consults `npm root -g` so globally-installed packages are picked up when the workspace has no local install.
+- Stale-config bugs on existing LSP wrappers: touching `tsconfig.json`/`pyrightconfig.json`/`*.csproj`/`pom.xml`/`package.json` triggers `workspace/didChangeConfiguration` + `workspace/didChangeWatchedFiles` without a stop/start cycle. Hard-trigger files (`.env`, `.jvmopts`, `global.json`, `pnpm-lock.yaml`, `.python-version`, `.java-version`, `dotnet-tools.json`) force coordinator restart on next call.
+
+### Added (observability)
+- `<stateDir>/calls.log` — per-call JSON lines: `{ts, method, ms, adopted, invalidation_fired, outcome}`. Disable via `TOOL_DIRECT_CALLLOG=0`.
+- `<stateDir>/triggers.json` — mtime baseline for invalidation.
+
+### Verified
+- `scripts/verify.sh --diff-baselines` clean on py/ts/cs/java/vue (response-body sha + shape match pre-refactor baselines; timings within machine noise).
+- Invalidation smoke on all 5 LSP wrappers: soft trigger preserves PID, hard trigger restarts coordinator.
+- `dotnet-direct call version {}` returns `{exit: 0, stdout: "10.0.103\n"}`.
+- `prettier-direct call format-file {...}` returns `{formatted, changed}`; `eslint-direct call version {}` returns `{version: "10.2.1"}`.
+- `sbt-direct call version {}` reads a real Play 3 / Scala 3 project's `build.sbt` → `{exit: 0, stdout: "sbt version in this project: 1.11.6\nsbt runner version: 1.10.11"}`.
+- `sbt-direct call task {"task":"scalafmtCheckAll"}` against the same project runs the sbt-scalafmt plugin end-to-end, correctly surfaces per-file formatting diagnostics. Under Claude Bash sandbox, `install.sh` pre-allows `/private/var/folders/**/.sbt/**` + `~/.sbt/**` + `~/.ivy2/**` + `~/.coursier/**` so sbt's BootServerSocket + dependency caches write without `dangerouslyDisableSandbox`.
+- `scalafmt-direct call check-files {...}` against a version-matched fixture → `{exit: 0, stdout: "All files are formatted with scalafmt :)"}`.
+- `scalafmt-direct call format-stdin {source: "object A{def   x=1}", filepath: "A.scala"}` → `{exit: 0, stdout: "object A { def x = 1 }\n"}`.
+- `dotnet-direct call version {}` → `{exit: 0, stdout: "10.0.103\n"}`.
+- `prettier-direct call format-file {filepath}` → `{formatted, changed}`.
+- `eslint-direct call version {}` → `{version: "10.2.1"}`.
+- `hooks/tests/run.sh` → 97/97 pass.
+- 19/19 harness + proxy smoke tests (`node --test bin/*.test.js`).
+
 ## [1.1.0] — 2026-04-21
 
 ### Added
@@ -38,5 +91,6 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 - `fixtures/` — minimal sample projects for CI + local verification
 - GitHub Actions CI on macOS + Ubuntu
 
+[1.2.0]: https://github.com/CHANGE-ME/claude-lsp-direct/releases/tag/v1.2.0
 [1.1.0]: https://github.com/CHANGE-ME/claude-lsp-direct/releases/tag/v1.1.0
 [1.0.0]: https://github.com/CHANGE-ME/claude-lsp-direct/releases/tag/v1.0.0

CONTRIBUTING.md

@@ -1,5 +1,21 @@
 # Contributing
 
+## Architecture overview
+
+The coordinator is split into three modules sharing one harness:
+
+- `bin/tool-harness.js` — six primitives: `resolveWorkspace`,
+  `stateDir`, `serveHttp`, `invalidationLoop`, `callLog`, plus
+  framing readers/writers (contentLength, jsonLine, tsserverMixed).
+- `bin/tool-server-proxy.js` — coordinator for tools with an external
+  child process (LSPs, build tools). Adapters declare `children[]`
+  + `init` + `onChildMessage` + `call` + `triggers`.
+- `bin/node-formatter-daemon.js` — coordinator for in-process Node
+  libraries (prettier, eslint). Adapters declare `preload(workspace)`
+  → pkg + `call(req, {pkg, state})`.
+
+See `docs/architecture.md` for the full adapter contract.
+
 ## Adding a new language
 
 Minimal steps for a standard stdio LSP (server speaks LSP over `--stdio`, no hybrid coordination):
@@ -53,11 +69,46 @@ Add the new language to the primary-path table.
 
 ## Hybrid servers (require paired processes)
 
-If the target LSP requires a paired companion process (like Vue LS v3 + tsserver + `@vue/typescript-plugin`), the generic `lsp-stdio-proxy.js` isn't enough. Write a dedicated coordinator modeled on `bin/vue-direct-coordinator.js`:
-- Spawn both children
-- Bridge any custom cross-server notifications
-- Expose the same HTTP surface (`POST /lsp`, `GET /health`)
-- Wire the bash wrapper to point at your new coordinator instead of `lsp-stdio-proxy.js`
+If the target LSP requires a paired companion process (like Vue LS v3 + tsserver + `@vue/typescript-plugin`), the generic `lsp-stdio-proxy.js` isn't enough. Write a dedicated adapter in `bin/adapters/<name>.js` declaring two child specs:
+
+```js
+spawn(workspace) {
+  return [
+    { id: 'main', frame: 'contentLength', cmd: 'main-ls', args: ['--stdio'] },
+    { id: 'helper', frame: 'tsserverMixed', cmd: 'node', args: [...] },
+  ];
+}
+```
+
+Adapter `onChildMessage(childId, msg, ctx)` handles cross-child routing;
+`ctx.state` stores bridge tables. See `bin/adapters/vue-hybrid.js` for
+the Vue LS v3 + tsserver bridging pattern.
+
+Compose into `bin/<name>-direct-coordinator.js` (3-line shim):
+
+```js
+const { createProxy } = require('./tool-server-proxy.js');
+const { createAdapter } = require('./adapters/<name>.js');
+createProxy({ adapter: createAdapter(), workspace, port, toolName });
+```
+
+## Non-LSP tools (build tools, formatters)
+
+The same harness accepts non-LSP tools. Two patterns:
+
+### External-subprocess adapter (JVM CLIs, compilers)
+Use `tool-server-proxy.js`. Adapter spawns a keepalive child (e.g.
+`node -e 'setInterval(...)'`) so the harness's child-exit +
+health-probe wiring works; each `call` runs the target CLI via
+`child_process.spawn` and returns the `{exit, signal, stdout,
+stderr}` quad. See `bin/adapters/sbt-oneshot.js`, `dotnet-cli.js`,
+`scalafmt-cli.js`.
+
+### In-process Node library adapter (prettier, eslint)
+Use `node-formatter-daemon.js`. Adapter implements `preload(workspace)`
+→ pkg + `call(req, {pkg, state})`. Prefer workspace-local resolution
+via `require.resolve(pkg, {paths: [workspace]})`, fall back to global.
+See `bin/adapters/prettier.js`, `bin/adapters/eslint.js`.
 
 ## Invariants