@henols/vice-mcp 1.0.0 → 1.1.0

package/version.ts

@@ -1,248 +1,49 @@
-// The ONE authoritative implementation of this project's version-resolution
-// algorithm (D-5). Before this file existed the repo carried FOUR
-// hand-maintained version strings and none of them were true:
-// `src/mcp/vice/package.json` and `installer/package.json` were stale
-// placeholders CI never touched between releases, `.claude-plugin/plugin.json`
-// was bumped by NO automation at all, and `vice-proxy.ts`'s own
-// `PROXY_VERSION` literal -- advertised to every MCP client over
-// `initialize` -- sat twelve patches behind npm's actual `latest`. This file
-// exists so there is exactly one place that (a) parses the repo-root
-// `VERSION` template, (b) resolves it against a published version per D-2's
-// four rules, and (c) answers "what version am I, right now, at runtime"
-// (D-4) -- every other consumer (the CLI in `scripts/version.mjs`,
-// `vice-proxy.ts`'s `PROXY_VERSION`, CI's `release-on-merge` job) calls INTO
-// this module rather than re-deriving any part of the algorithm locally.
+// Answers one question: what version is this server, right now, at runtime.
 //
-// Do NOT reimplement the resolution rules (`pinned` / `no-published` /
-// `prefix-differs` / `prefix-matches`) anywhere else in this repo -- not in
-// `scripts/version.mjs`, not in CI YAML, not in `installer/bin/cli.mjs`.
-// `version.test.ts`'s "single-implementation guard" test greps
-// `scripts/version.mjs` for the rule literals to catch exactly that
-// regression.
+// WHY THIS FILE EXISTS: `vice-proxy.ts` advertises a version to every MCP
+// client over `initialize`. That string used to be a hand-maintained
+// `PROXY_VERSION` literal and it sat twelve patches behind npm's actual
+// `latest`, because nothing bumped it. One function now derives it from the
+// package.json that ships beside the code, so it cannot drift again.
 //
-// Do NOT import `repo-root.ts` from this file. That module's `repoRoot()`
-// carries a documented side effect (`ensureResourcesInstalled()`, fired at
-// module-load time) this seam must never trigger just by being imported --
-// `scripts/version.mjs` and any future test that imports this module for
-// its pure functions alone would otherwise deploy host launcher resources as
-// a side effect of asking what version something is. Per this repo's own
-// convention (see `hostpath.ts`/`containerpath.ts`), the workspace root
-// arrives here as an explicit argument (`readTemplate(repoRootDir)`) or a
-// caller-supplied lazy thunk (`runtimeVersion({ repoRoot })`), never as an
-// import this module resolves itself.
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-
-/** The single self-evident placeholder every derived, publishable version
- * string (the two npm package.json `.version` fields, the installer's
- * `@henols/vice-mcp` dependency pin, and the three plugin-manifest version
- * fields) carries in the working tree (R-2). Valid semver -- `npm pack`
- * accepts it -- but unmistakably not a release. Overwritten at publish time
- * by `npm version` (npm packages) or `scripts/version.mjs stamp` (plugin
- * manifests); never hand-edited. */
+// This file once also carried a bespoke version-RESOLUTION algorithm (a
+// `VERSION` template parsed against the published version under four named
+// rules) used only by the auto-patch-on-merge release job. That job and its
+// template are gone: the git tag is the version now, and the publish workflow
+// reads it straight from the ref. Do not reintroduce a second version
+// algorithm here -- if you need to know what a release will be called, look
+// at the tag.
+//
+// Do NOT import `repo-root.ts` from this file, and do not reintroduce a
+// `repoRoot` option. That module's `repoRoot()` fires
+// `ensureResourcesInstalled()` at module-load time, and asking what version
+// something is must never deploy host launcher resources as a side effect.
+// The option existed to locate a `VERSION` template that no longer exists.
+import { readFileSync } from "node:fs";
+
+/** The placeholder both publishable `package.json` `.version` fields carry in
+ * the working tree. Valid semver -- `npm pack` accepts it -- but unmistakably
+ * not a release. `npm version` overwrites it at publish time from the git tag;
+ * never hand-edited. */
 export const DEV_PLACEHOLDER = "0.0.0-dev";
 
-export type ResolveRule = "pinned" | "no-published" | "prefix-differs" | "prefix-matches";
-
-export interface ResolveResult {
-  version: string;
-  rule: ResolveRule;
-  template: string;
-  published: string | null;
-}
-
-// Leading zeros are rejected (bare "0" is the only zero-value exception) --
-// SemVer 2.0.0 SS2 forbids leading-zero numeric identifiers, and this
-// component is echoed VERBATIM into the resolved string for literal (non-`-`)
-// slots, so "1.00.0" must be rejected here rather than surfacing later as an
-// npm-publish-time failure (MED-2).
-const TEMPLATE_COMPONENT = /^(0|[1-9]\d*|-)$/;
-
-/**
- * Parse a version TEMPLATE (not a resolved version) into its three
- * dot-separated components. Each component must be either a non-negative
- * integer literal or the literal string `-` (an auto-managed slot, D-2).
- * Throws on anything else: wrong component count, a non-numeric/non-`-`
- * component, a blank/whitespace-only string, OR a literal component
- * appearing after a `-` component (MED-1) -- D-2's "literal prefix" wording,
- * and every row of CONTEXT.md's worked-example table, only ever describe
- * dashes trailing literals, never leading or interleaved. A shape like
- * "-.2.3" or "0.-.2" has no defined resolution semantics and must be
- * rejected at the one seam that owns validating the hand-edited VERSION
- * file, not silently resolved into something CONTEXT.md never specified.
- */
-export function parseTemplate(raw: string): string[] {
-  const trimmed = raw.trim();
-  if (trimmed === "") {
-    throw new Error(`version.ts: malformed template ${JSON.stringify(raw)} -- empty`);
-  }
-  const parts = trimmed.split(".");
-  if (parts.length !== 3) {
-    throw new Error(
-      `version.ts: malformed template ${JSON.stringify(raw)} -- expected exactly 3 dot-separated components, got ${parts.length}`
-    );
-  }
-  let sawDash = false;
-  for (const part of parts) {
-    if (part === "-") {
-      sawDash = true;
-      continue;
-    }
-    if (sawDash) {
-      throw new Error(
-        `version.ts: malformed template ${JSON.stringify(raw)} -- literal component ${JSON.stringify(part)} cannot follow a "-" component; dashes only trail literals (D-2)`
-      );
-    }
-    if (!TEMPLATE_COMPONENT.test(part)) {
-      throw new Error(
-        `version.ts: malformed template ${JSON.stringify(raw)} -- component ${JSON.stringify(part)} is neither an integer (no leading zeros) nor "-"`
-      );
-    }
-  }
-  return parts;
-}
-
-/**
- * Parse a PUBLISHED version string into a 3-tuple of numbers, stripping any
- * `-prerelease` / `+build` suffix first. Returns null (never throws) when
- * the input is null, not parseable, or does not have exactly 3 numeric
- * dot-separated components -- callers treat null exactly like "nothing is
- * published" (D-2 rule 4).
- */
-function parsePublished(published: string | null): number[] | null {
-  if (published == null) return null;
-  const core = published.split(/[-+]/, 1)[0];
-  const parts = core.split(".");
-  if (parts.length !== 3) return null;
-  // Strict plain-decimal-digit validation (MED-4) -- deliberately NOT
-  // `Number(p)` + `Number.isInteger`, which also accepts hex-like literals
-  // ("0x2" -> 2), exponential notation ("5e2" -> 500), and whitespace-padded
-  // numbers. Those would silently coerce malformed `--published` input or an
-  // unexpected `npm view` response into a number that doesn't reflect the
-  // original text; this must instead fall back to null (== "no-published",
-  // D-2 rule 4) exactly like any other unparseable input, matching the
-  // strict digit validation `parseTemplate`'s `TEMPLATE_COMPONENT` already
-  // uses for the same kind of input.
-  if (!parts.every((p) => /^\d+$/.test(p))) return null;
-  return parts.map((p) => Number(p));
-}
-
-/**
- * The D-2 resolution algorithm, in full. `template` must already be
- * well-formed (call `parseTemplate` first, or pass through unchanged --
- * this function calls it internally so a malformed template always throws
- * here too). `published` is the raw published-version string (or null);
- * this function does its own stripping/parsing via `parsePublished`.
- */
-export function resolveVersion(template: string, published: string | null): ResolveResult {
-  const components = parseTemplate(template);
-
-  if (!components.includes("-")) {
-    return { version: components.join("."), rule: "pinned", template, published };
-  }
-
-  const pub = parsePublished(published);
-
-  if (pub === null) {
-    const resolved = components.map((c) => (c === "-" ? "0" : c));
-    return { version: resolved.join("."), rule: "no-published", template, published };
-  }
-
-  const prefixMatches = components.every((c, i) => c === "-" || Number(c) === pub[i]);
-
-  if (!prefixMatches) {
-    const resolved = components.map((c) => (c === "-" ? "0" : c));
-    return { version: resolved.join("."), rule: "prefix-differs", template, published };
-  }
-
-  let firstDashSeen = false;
-  const resolved = components.map((c, i) => {
-    if (c !== "-") return c;
-    if (!firstDashSeen) {
-      firstDashSeen = true;
-      // Guard (LOW-1): `pub[i] + 1` on a published component at
-      // Number.MAX_SAFE_INTEGER would silently lose precision to float
-      // rounding and could fail to actually increment, violating this
-      // seam's "always publishes something new" invariant. Purely
-      // theoretical for real-world semver (patch counts in the billions are
-      // not realistic) but the arithmetic is load-bearing enough to fail
-      // loud rather than silently miscompute.
-      if (pub[i] >= Number.MAX_SAFE_INTEGER) {
-        throw new Error(
-          `version.ts: published component ${pub[i]} at index ${i} is at or beyond Number.MAX_SAFE_INTEGER -- refusing to increment (would lose precision)`
-        );
-      }
-      return String(pub[i] + 1);
-    }
-    return "0";
-  });
-  return { version: resolved.join("."), rule: "prefix-matches", template, published };
-}
-
-/**
- * Compare two plain, fully-resolved (no `-`, no prerelease) semver-shaped
- * version strings as a numeric 3-tuple. Returns -1/0/1. Throws if either
- * side does not parse as 3 numeric components -- this is for comparing
- * RESOLVED versions, not templates.
- */
-export function compareVersions(a: string, b: string): -1 | 0 | 1 {
-  const pa = parsePublished(a);
-  const pb = parsePublished(b);
-  if (pa === null) throw new Error(`version.ts: compareVersions() cannot parse ${JSON.stringify(a)}`);
-  if (pb === null) throw new Error(`version.ts: compareVersions() cannot parse ${JSON.stringify(b)}`);
-  for (let i = 0; i < 3; i++) {
-    if (pa[i] < pb[i]) return -1;
-    if (pa[i] > pb[i]) return 1;
-  }
-  return 0;
-}
-
-/**
- * Read `<repoRootDir>/VERSION`, trimmed. Returns the empty string for an
- * existing-but-blank (or whitespace-only) file, and null ONLY when the file
- * is absent (never throws on either outcome) -- do not treat `=== null` as
- * the sole "no template" signal; an empty string is also "no usable
- * template", and every current caller checks for it via truthiness (LOW-3).
- * Does NOT validate the template shape -- `resolveVersion`/`parseTemplate`
- * do that; this function's only job is the filesystem read.
- */
-export function readTemplate(repoRootDir: string): string | null {
-  const path = join(repoRootDir, "VERSION");
-  if (!existsSync(path)) return null;
-  try {
-    return readFileSync(path, "utf8").trim();
-  } catch {
-    return null;
-  }
-}
-
 export interface RuntimeVersionOptions {
+  /** Path to the `package.json` shipped beside the running code. */
   pkgJsonPath?: string;
-  /** LAZY -- see this file's header and the precedence note below. Only
-   * called when `pkgJsonPath`'s own version is absent or is
-   * DEV_PLACEHOLDER, so a published tarball (which has a real version and
-   * no repo-root VERSION file) never calls this and never risks the
-   * stderr note `repoRoot()` implementations may emit. */
-  repoRoot?: () => string | undefined;
 }
 
 /**
- * D-4's runtime precedence, synchronous and never throwing:
+ * Runtime precedence, synchronous and never throwing:
  *
  *   1. `pkgJsonPath`'s own `.version`, when present and not DEV_PLACEHOLDER
- *      -- the published-tarball path: `npm version` already stamped it.
- *   2. Otherwise call `opts.repoRoot?.()` and, if it yields a directory,
- *      read that directory's `VERSION` template. A pinned template (no `-`)
- *      returns verbatim; a template containing `-` resolves every `-` to 0
- *      and appends a `-dev` prerelease tag, so a dev checkout never claims
- *      to be a release build.
- *   3. Otherwise DEV_PLACEHOLDER.
+ *      -- the published-tarball path: `npm version` stamped it from the git
+ *      tag at publish time.
+ *   2. Otherwise DEV_PLACEHOLDER, which is what a git checkout reports.
  *
- * The whole body is wrapped in try/catch: any unexpected failure (a
- * malformed package.json, a repoRoot() thunk that throws, a malformed
- * VERSION template) degrades to DEV_PLACEHOLDER rather than crashing the
- * caller -- this is the one runtime-facing entry point in this file, and a
- * standalone MCP server must never fail to start over a version string.
+ * The body is wrapped in try/catch: a missing or malformed package.json
+ * degrades to DEV_PLACEHOLDER rather than crashing the caller. This is the
+ * one runtime-facing entry point in this file, and a standalone MCP server
+ * must never fail to start over a version string.
  */
 export function runtimeVersion(opts: RuntimeVersionOptions = {}): string {
   try {
@@ -257,19 +58,6 @@ export function runtimeVersion(opts: RuntimeVersionOptions = {}): string {
         // No readable/parseable package.json at pkgJsonPath -- fall through.
       }
     }
-
-    const root = opts.repoRoot?.();
-    if (root) {
-      const template = readTemplate(root);
-      if (template) {
-        const components = parseTemplate(template);
-        if (!components.includes("-")) {
-          return components.join(".");
-        }
-        const resolved = components.map((c) => (c === "-" ? "0" : c));
-        return `${resolved.join(".")}-dev`;
-      }
-    }
   } catch {
     // Degrade to the placeholder below -- see this function's own doc
     // comment for why nothing here may throw.

package/vice-proxy.ts

@@ -302,21 +302,23 @@ const HERE_DIR = dirname(fileURLToPath(import.meta.url));
 //
 // `RESOLVED_BINARY.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
+// ONCE here, at MCP-server process startup -- Phase 60 (LOC-01/LOC-02) routes
+// that resolution through the tool-location seam (a `.c64-re-tools/tools.json`
+// entry for `x64sc`, then a bare `x64sc` `$PATH` probe, in THIS process's own
+// environment) rather than a `$PATH` probe alone -- 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 the seam 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 RESOLVED_BINARY = backendDetect.resolvedBackend();
+const RESOLVED_BINARY = backendDetect.resolvedBackend({ toolsDir: toolsDir({ from: HERE_DIR }), projectRoot: repoRoot({ from: HERE_DIR }) });
 
 // -------------------------------------------------------------- JSON-RPC
 //
@@ -395,16 +397,14 @@ process.stdout.on("error", (err) => {
 // repo-root `VERSION` template -- rendered as `<resolved>-dev` -- only in a
 // git checkout, degrading to `0.0.0-dev` if neither is available. Reused,
 // unchanged, as MCPServer's own `version` field below.
-const PROXY_VERSION = runtimeVersion({
-  pkgJsonPath: join(HERE_DIR, "package.json"),
-  repoRoot: () => repoRoot(),
-});
+const PROXY_VERSION = runtimeVersion({ pkgJsonPath: join(HERE_DIR, "package.json") });
 
 // --------------------------------------------------------------- tools/list
 //
 // A pure, offline read of the committed schema snapshot (decision D-C).
-// `refresh-manifest.mjs` is the ONLY writer of that file -- this handler
-// never fetches, never awaits a network call, and never throws. Any problem
+// Nothing regenerates that file from a live host -- it is committed and
+// changed by hand. This handler never fetches, never awaits a network
+// call, and never throws. Any problem
 // with the snapshot (absent, unparseable, wrong shape) degrades to a
 // well-formed empty `tools` array plus one stderr line naming the path and
 // the reason, never a fetch and never a hang.
@@ -503,8 +503,8 @@ const RESULT_CONTINUE_TOOL: ToolDefinition = {
 
 // The recycle tool (plan 01.3-01, task 1): the only new HOST-SIDE ACTION
 // this phase adds. Served entirely proxy-local -- like RESULT_CONTINUE_TOOL
-// above, it is never in tools-manifest.json (RESEARCH Key Finding 3), so a
-// manifest regenerate can never drop it. Deliberately split from
+// above, it is never in tools-manifest.stock.json (RESEARCH Key Finding 3),
+// so a manifest edit can never drop it. Deliberately split from
 // vice_diagnose (D-03): this tool NEVER gates on a verdict, so there is no
 // "confirm"/"mode" argument and no shared state between the two tools to
 // keep in sync -- the separation itself is the safety.
@@ -1584,11 +1584,11 @@ tools[DIAGNOSE_TOOL.name] = buildViceTool(stockDispatch.resolveAdvertisedToolDef
 // 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. 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.
+// fork/stock distinction to make. The family is deliberately absent from
+// tools-manifest.stock.json, which records what a live HOST VICE server
+// answers and never a proxy-local store file. Registering the family here,
+// rather than listing it there, keeps that manifest an honest record of the
+// emulator surface.
 // Registered here via buildViceTool() directly (the SAME pattern
 // RESULT_CONTINUE_TOOL above uses), so no anno_* runner ever reaches
 // stockDispatch: there is no generic-dispatch surface left anywhere in this