@henols/vice-mcp 0.2.0 → 0.2.2

package/vice-proxy.ts

@@ -185,6 +185,130 @@ import * as stockDispatch from "./stock-dispatch.ts";
 // below, strictly after the DENY_LIST check -- see the comment at that call
 // site for why the ordering is load-bearing.
 import { capabilityRefusalMessage } from "./capability-registry.ts";
+// Plan 29-01: the curated anno_* tool surface's DEFINITIONS, imported
+// STATICALLY -- registration below happens synchronously at module scope, so
+// a dynamic import cannot serve it. This costs nothing at module load: no
+// store file is opened here. The owned SQLite annotation store stays behind
+// anno-tools.ts's own runAnnoTool(), which opens it, answers exactly one call
+// against it and closes it again (D-06), reached only when a tool is called.
+import { ANNO_TOOL_DEFINITIONS, runAnnoTool } from "./anno-tools.ts";
+
+// ------------------------------------------------------------ anno subcommand
+//
+// D-06 / RESEARCH.md Open Question #1 (plan 10-04): `vice-mcp anno <verb>` is
+// the ONLY surface that resolves identically across the Claude Code plugin
+// route and both npm-installer routes -- `installer/bin/cli.mjs`'s
+// `viceServerEntry()` always launches this server via `npx` in BOTH
+// npm-installer modes (`--vendor` only pre-resolves the package; it never
+// places `src/mcp/vice/*.ts` as plain files inside a consuming project),
+// so any design resolving a filesystem path to the seam would silently fail
+// to resolve for npm-installed users. This bin is the one surface proven to
+// work in all three routes.
+//
+// This branch runs as the first executable statement of the module body,
+// deliberately ABOVE `ACTIVE_BACKEND`'s backend probe (which shells out to a
+// binary's `--help`), above the manifest read, and above
+// `new MCPServer(...)`/`server.startStdio()` far below -- a CLI invocation
+// must never open a socket, never probe a binary, and never write a byte of
+// JSON-RPC to stdout. WHAT NOT TO DO: never let this branch fall through
+// into the server path, and never print anything on stdout on the server
+// path that a CLI caller could confuse for `anno` output.
+//
+// Ending the process here is deliberate and is NOT a violation of this
+// file's standing "never end the process from a teardown handler" rule (see
+// that handler's own comment further down): that rule protects the
+// long-lived server's lease-release path, and this branch ends the process
+// before any lease, socket or handler exists. A dynamic import is used
+// (not a static one) so the CLI module is not part of the server's startup
+// cost on the normal, non-`anno` path.
+//
+// IN-01 (10-REVIEW.md; 11.1-CONTEXT.md AUDIT-01, D-11.1-04): `console.log`/
+// `console.error` writes to `process.stdout`/`process.stderr` are
+// ASYNCHRONOUS on POSIX once the fd is a pipe (Node opens pipe/socket fds
+// non-blocking, unlike a TTY or a regular file), so a bare `process.exit()`
+// immediately after can discard whatever write has not yet drained --
+// measured at a 128 KiB truncation point on this host's Node for a single
+// write exceeding the OS pipe's capacity. The trigger this was FOUND
+// through -- a CLI verb that echoed a spawned child's whole stderr -- was
+// withdrawn with the analyser it spawned (plan 29-07, D-14), but the hazard
+// is a property of the exit path rather than of that verb: any verb that
+// prints a diagnostic larger than the pipe's capacity hits it, and the one
+// case where the user most needs the diagnostic is exactly the case a piped
+// invocation could silently lose it in. `drainStdio()` below explicitly
+// awaits both streams' own pending writes (a `write("", cb)`-style
+// zero-length write's callback fires only once every prior queued write has
+// actually flushed) before the terminating `process.exit(code)`.
+//
+// T-11.1-EXITHANG: the drain is BOUNDED to `ANNO_CLI_DRAIN_TIMEOUT_MS`. An
+// exit that hangs forever waiting on a pipe nobody reads is worse than a
+// truncated diagnostic -- this project's standing rule is that a teardown
+// path never becomes a hang (see the "never end the process from a teardown
+// handler" comment above; a BOUNDED drain here does not violate that rule
+// for the same reason the original unbounded `process.exit()` did not: this
+// still runs before any lease, socket or handler exists, and now also can
+// never block indefinitely).
+const ANNO_CLI_DRAIN_TIMEOUT_MS = 300;
+
+/** Resolves once `stream`'s own pending writes have flushed, or after
+ * `timeoutMs`, whichever comes first. A zero-length `write("", cb)`'s
+ * callback fires strictly after every write queued ahead of it on the same
+ * stream has completed -- so this is a genuine drain barrier, not a fixed
+ * sleep. Guarded so a stream that is not writable (already closed/ended,
+ * e.g. under `> /dev/null` teardown races) resolves immediately rather than
+ * calling `write()` on it. */
+function drainStdio(stream: NodeJS.WriteStream): Promise<void> {
+  return new Promise((resolve) => {
+    if (!stream.writable) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(resolve, ANNO_CLI_DRAIN_TIMEOUT_MS);
+    stream.write("", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+if (process.argv[2] === "anno") {
+  // A broken pipe (the reader closing early, e.g. `| head`) makes
+  // `stream.write()` fail with EPIPE. Awaiting `drainStdio()` below gives
+  // that failure the chance to actually surface as Node's stream 'error'
+  // event -- which throws UNCAUGHT and crashes the process if nothing is
+  // listening, converting what used to be a silent (bare `process.exit()`
+  // outran the async error) success into a stack-trace crash. This
+  // mirrors the SAME EPIPE class this file already guards against for the
+  // server path further down (see that handler's own
+  // modelcontextprotocol/typescript-sdk#1564 citation) -- registered here
+  // too because this branch exits long before reaching that one.
+  process.stdout.on("error", () => {});
+  process.stderr.on("error", () => {});
+
+  // Test-only escape hatch, never documented to end users and inert unless
+  // this exact env var is set: writes a deterministic filler payload
+  // through this SAME drained-exit path, so vice-proxy.test.ts can measure
+  // an exact byte count well above any OS pipe capacity without needing any
+  // real project file at all. That independence is the point: measured at
+  // the time, neither `--help`'s ~5.6 KB USAGE text nor a synthesized or
+  // garbage project file fed to a verb's error path scaled anywhere near
+  // 128 KiB on this host, so no real invocation could reach the truncation
+  // point on demand (see 11.1-05-SUMMARY.md for those measurements). The
+  // hatch outlives the routes it was measured against, because it depends on
+  // none of them. Never reachable
+  // from a real `anno <verb>` invocation: the check is against a specific,
+  // unambiguous env var name no real caller would ever set.
+  const testFillBytes = process.env.VICE_TEST_ANNO_CLI_STDOUT_FILL_BYTES;
+  if (testFillBytes) {
+    process.stdout.write("x".repeat(Number(testFillBytes)));
+    await Promise.all([drainStdio(process.stdout), drainStdio(process.stderr)]);
+    process.exit(0);
+  }
+
+  const { runAnnoCli } = await import("./anno-cli.ts");
+  const code = await runAnnoCli(process.argv.slice(3));
+  await Promise.all([drainStdio(process.stdout), drainStdio(process.stderr)]);
+  process.exit(code);
+}
 
 const HERE_DIR = dirname(fileURLToPath(import.meta.url));
 
@@ -193,6 +317,23 @@ const HERE_DIR = dirname(fileURLToPath(import.meta.url));
 // selection, the tools construction loop's dispatch choice, and the final
 // ready log line) reads THIS constant, never the raw environment variable
 // and never a second detection call.
+//
+// `ACTIVE_BACKEND.binPath` is what `vice_ping`'s `resolvedBinaryPath` field
+// reports (see stock-dispatch.ts's `handlePing()`). It is resolved exactly
+// ONCE here, at MCP-server process startup, by a bare `x64sc` `$PATH` probe
+// run in THIS process's own environment -- it is NOT re-probed per request
+// and has no connection to the broker, a separate, already-running process
+// that leases whichever instance it chose to whatever request comes in. On a
+// host where bare `x64sc` resolves to one build, `resolvedBinaryPath` reports
+// that build's path on every ping, even when the broker actually launched
+// (or later recycled to) a different one. The authoritative per-instance
+// answer lives in the broker's own launch record (`epoch.json`'s `vice_bin`
+// field, written by `broker-epoch.mts`) -- Phase 8.2 plan 04's own
+// walkthrough had to route around this field entirely and prove backend
+// identity from that launch record plus a live `ps -o args=` read instead
+// (2026-08-19 finding, closed as a documentation fix by Phase 15 plan 15-09
+// rather than a per-request requery, which would be a behavioural change out
+// of a disposition phase's remit).
 const ACTIVE_BACKEND = backendDetect.resolvedBackend();
 
 // -------------------------------------------------------------- JSON-RPC
@@ -3016,6 +3157,7 @@ async function forwardToVice(name: string, args: Record<string, unknown>): Promi
 // and asserts that slice contains no promise-awaiting construct and calls
 // the control session's release function exactly once. Do not move either
 // marker away from the code each one bounds.
+//
 let teardownRan = false;
 
 function releaseLeaseNow(trigger: string): void {
@@ -3220,6 +3362,32 @@ tools[RESULT_CONTINUE_TOOL.name] = buildViceTool(RESULT_CONTINUE_TOOL, (args) =>
 // entry in `tools/list`.
 tools[RECYCLE_TOOL.name] = buildBackendAwareTool(stockDispatch.resolveAdvertisedToolDefinition(RECYCLE_TOOL, ACTIVE_BACKEND.backend, manifestTools), (args) => handleRecycle(args));
 tools[DIAGNOSE_TOOL.name] = buildBackendAwareTool(stockDispatch.resolveAdvertisedToolDefinition(DIAGNOSE_TOOL, ACTIVE_BACKEND.backend, manifestTools), (args) => handleDiagnose(args));
+// Backend-INDEPENDENT by construction (plan 29-01): the anno_* family never
+// touches VICE at all -- it reaches a PROXY-LOCAL SQLite annotation store
+// this repo owns, opened and closed inside the runner itself, so there is no
+// fork/stock distinction to make and buildBackendAwareTool() would be flatly
+// wrong here (there is nothing for it to dispatch to on either backend). The
+// family is in NEITHER tools-manifest.json NOR tools-manifest.stock.json:
+// both are regenerated by refresh-manifest.ts from a live HOST VICE server's
+// own tools/list, and a local store file is never that host -- a hand-added
+// entry in either manifest would be silently wiped on the next refresh.
+// Registered here via buildViceTool() directly (the SAME exception
+// RESULT_CONTINUE_TOOL above is), so no anno_* runner can ever reach
+// forwardToVice(), call(), or ensureViceSession() -- CLAUDE.md's "derived
+// tools must be intercepted before forwardToVice()" constraint is satisfied
+// by construction for this family, not by an interception, because the
+// runner is never wired to forwardToVice() in the first place.
+// Deliberately NOT named `def` (the manifest loop's own loop variable,
+// above): `stock-dispatch.test.ts`'s `proxyToolRegistrations()` regex-scans
+// this file's own `tools[...] = ...;` lines and keys each one by its raw
+// captured text, so an identically-named loop variable here would make this
+// registration textually indistinguishable from the manifest loop's -- a
+// distinct name (`annoDef`) keeps the anno_* family's own exemption from
+// `buildBackendAwareTool()` from ever being confused with, or accidentally
+// widened to cover, the manifest loop's registration.
+for (const annoDef of ANNO_TOOL_DEFINITIONS) {
+  tools[annoDef.name] = buildViceTool(annoDef, (args) => runAnnoTool(annoDef.name, args));
+}
 
 const server = new MCPServer({ name: "vice", version: PROXY_VERSION, tools });
 await server.startStdio();