@henols/vice-mcp 0.2.2 → 0.2.4

package/capability-registry.ts

@@ -1,390 +0,0 @@
-// capability-registry.ts
-//
-// WHY THIS FILE EXISTS (BACK-05): today, a tool name the ACTIVE backend does
-// not advertise falls straight through vice-proxy.ts's CallToolRequestSchema
-// override to its generic `Unknown tool: ${name}` fallback -- the exact same
-// message a genuine typo gets. That is indistinguishable and unhelpful: a
-// caller cannot tell "you misspelled this" from "this tool exists, but only
-// on the other backend, for this specific reason." This module is the ONE
-// authoritative place holding that per-backend capability data -- names,
-// reason categories, reason text, and which backend actually provides each
-// one -- so a future call site (the runtime refusal wired in plan 08-02, the
-// generated support table in plan 08-03, the skill-text lint in plan 08-04)
-// reads exactly one source rather than re-deriving or hand-copying it.
-//
-// WHAT NOT TO DO: do not hand-maintain a second copy of this data anywhere
-// else in the repo (D-E; see CLAUDE.md's "re-deriving a cross-cutting seam
-// locally" anti-pattern). If a consumer needs this data in a different
-// shape, import CAPABILITY_REGISTRY and reshape it there -- never re-type
-// the 26 entries or their reasons from memory.
-//
-// SECURITY POSTURE: this module is a READ-ONLY MESSAGE-TEXT LOOKUP and is
-// NEVER an authorization boundary. DENY_LIST (vice.ts) remains the only
-// refusal in this tree that is a security control; that check runs first, at
-// every call site, and this module never overrides or duplicates it. Every
-// string held here is already public: it names only information already
-// published in docs/stock-vice-parity.md and this public repository -- no
-// credential, no secret, no host, no port, no path, and no tool name that is
-// not already present in one of the two shipped manifests
-// (tools-manifest.json, tools-manifest.stock.json).
-//
-// This is the exact shape vice.ts's DENY_LIST / denyListRefusalMessage()
-// already established: one exported readonly array, one exported
-// message-rendering function, keyed by hazard/reason shape rather than one
-// wording reused for every entry -- because telling a caller the wrong
-// reason shape for what is otherwise the same permanent refusal invites a
-// pointless retry (that function's own doc comment makes the identical
-// point).
-//
-// EXCLUDED, DELIBERATELY (see docs/stock-vice-parity.md and
-// 08-RESEARCH.md's "Capability Delta Registry"):
-//   - "vice_diagnose" and "vice_recycle" are NOT capability gaps: they are
-//     synthetic, proxy-local tools registered on BOTH backends by
-//     vice-proxy.ts's buildBackendAwareTool()/resolveAdvertisedToolDefinition()
-//     synthetic-registration call sites, never listed in either raw manifest
-//     JSON file. A naive set-difference over the two manifests misclassifies
-//     them as a divergence; they are not one, and including them here would
-//     be a factual error, not merely an omission.
-//   - "initialize", "notifications_initialized", "tools_call", "tools_list"
-//     are already refused by vice.ts's DENY_LIST, which runs strictly BEFORE
-//     any capability-registry lookup and owns a different hazard shape
-//     entirely (confused-deputy bypass, not a missing capability). They must
-//     keep being owned there, not duplicated here.
-//
-// This module imports nothing at runtime -- the only import is a type-only
-// import of ViceBackend, which is erased by Node's type-stripping -- so it
-// has no transport, no filesystem, and no process dependency of its own.
-import type { ViceBackend } from "./backend-detect.mts";
-
-/**
- * Three reason categories, matching the distinctions the project's own docs
- * already draw (docs/stock-vice-parity.md SS A/B):
- *   - "hardware": no 1:1 opcode can ever exist because of a hardware or
- *     firmware property (a write-only register, per-read recomputation, no
- *     monitor command for a physical line). Permanent; nothing to build.
- *   - "descoped": theoretically buildable client-side (an opcode or
- *     equivalent already exists) but cut from v0.2.0 scope because no
- *     shipped skill calls it.
- *   - "stock-only-gain": the reverse direction -- stock has a native opcode
- *     the fork's custom HTTP API never exposed an equivalent RPC for.
- */
-export type CapabilityCategory = "hardware" | "descoped" | "stock-only-gain";
-
-/**
- * One row of capability data. `providedBy` names the backend that DOES have
- * the capability (never the backend refusing it). `reason` is one sentence
- * of user-facing prose ending in a full stop -- no planning identifier
- * (BACK-05, SKILL-01, DERIV-*, SHOT-*, GAIN-*, "Phase N") belongs in this
- * field; those are internal routing annotations, not something a caller
- * calling a tool by name should ever see. `alternative`, when present, names
- * a concrete route that exists on the OTHER backend today -- omit it rather
- * than inventing one where none exists.
- */
-export interface CapabilityEntry {
-  name: string;
-  category: CapabilityCategory;
-  providedBy: ViceBackend;
-  reason: string;
-  alternative?: string;
-}
-
-const KEYBOARD_ALTERNATIVE =
-  "vice_keyboard_type / vice_keyboard_petscii inject text through the KERNAL keyboard buffer, " +
-  "and vice_joystick_set covers most in-game input -- but a program polling $DC00/$DC01 directly " +
-  "will not see buffer injection.";
-
-/**
- * The 26-entry capability delta: every tool one backend advertises that the
- * other genuinely does not, after excluding registration artifacts
- * (vice_diagnose/vice_recycle) and DENY_LIST's own four meta-tools -- see
- * the header comment above and 08-RESEARCH.md's "Capability Delta Registry"
- * for the full accounting this array is derived from.
- */
-export const CAPABILITY_REGISTRY: readonly CapabilityEntry[] = [
-  // --- hardware (6), providedBy: fork -------------------------------------
-  {
-    name: "vice_sid_get_state",
-    category: "hardware",
-    providedBy: "fork",
-    reason:
-      "SID's $D400-$D418 registers are write-only in hardware, and the binary monitor exposes " +
-      "no SID read command.",
-  },
-  {
-    name: "vice_keyboard_matrix",
-    category: "hardware",
-    providedBy: "fork",
-    reason:
-      "The binary monitor's KEYBOARD_FEED (0x72) only injects PETSCII buffer text; the emulator " +
-      "recomputes CIA port B from its own keyboard array on every read, so there is no wire " +
-      "command that can drive the raw matrix.",
-    alternative: KEYBOARD_ALTERNATIVE,
-  },
-  {
-    name: "vice_keyboard_restore",
-    category: "hardware",
-    providedBy: "fork",
-    reason:
-      "RESTORE pulses the NMI line directly; it is not part of the keyboard matrix, and " +
-      "KEYBOARD_FEED has no way to produce it.",
-    alternative: KEYBOARD_ALTERNATIVE,
-  },
-  {
-    name: "vice_keyboard_chord",
-    category: "hardware",
-    providedBy: "fork",
-    reason:
-      "KEYBOARD_FEED injects a whole string at a time; it has no primitive for holding multiple " +
-      "keys down together for a span of frames.",
-    alternative: KEYBOARD_ALTERNATIVE,
-  },
-  {
-    name: "vice_keyboard_key_press",
-    category: "hardware",
-    providedBy: "fork",
-    reason:
-      "KEYBOARD_FEED has no hold/release primitive -- it injects a complete string, not an " +
-      "individual key-down event.",
-    alternative: KEYBOARD_ALTERNATIVE,
-  },
-  {
-    name: "vice_keyboard_key_release",
-    category: "hardware",
-    providedBy: "fork",
-    reason:
-      "KEYBOARD_FEED has no hold/release primitive -- it injects a complete string, not an " +
-      "individual key-up event.",
-    alternative: KEYBOARD_ALTERNATIVE,
-  },
-
-  // --- descoped (18), providedBy: fork -------------------------------------
-  {
-    name: "vice_disk_detach",
-    category: "descoped",
-    providedBy: "fork",
-    reason:
-      "No detach opcode exists on the stock binary monitor; attaching a different disk image " +
-      "covers the same workflow.",
-  },
-  {
-    name: "vice_disk_read_sector",
-    category: "descoped",
-    providedBy: "fork",
-    reason:
-      "Reading a sector would require parsing the .d64 file client-side rather than calling a " +
-      "live-drive opcode, and no shipped skill calls it.",
-  },
-  {
-    name: "vice_display_screenshot",
-    category: "descoped",
-    providedBy: "fork",
-    reason:
-      "The client-side PNG encoder for the INDEXED8 framebuffer DISPLAY_GET returns was descoped " +
-      "because no shipped skill calls it.",
-  },
-  {
-    name: "vice_display_get_dimensions",
-    category: "descoped",
-    providedBy: "fork",
-    reason: "Descoped alongside vice_display_screenshot -- no shipped skill calls it.",
-  },
-  {
-    name: "vice_backtrace",
-    category: "descoped",
-    providedBy: "fork",
-    reason: "No shipped skill calls it.",
-  },
-  {
-    name: "vice_checkpoint_group_add",
-    category: "descoped",
-    providedBy: "fork",
-    reason: "No shipped skill calls any checkpoint-group tool.",
-  },
-  {
-    name: "vice_checkpoint_group_create",
-    category: "descoped",
-    providedBy: "fork",
-    reason: "No shipped skill calls any checkpoint-group tool.",
-  },
-  {
-    name: "vice_checkpoint_group_list",
-    category: "descoped",
-    providedBy: "fork",
-    reason: "No shipped skill calls any checkpoint-group tool.",
-  },
-  {
-    name: "vice_checkpoint_group_toggle",
-    category: "descoped",
-    providedBy: "fork",
-    reason: "No shipped skill calls any checkpoint-group tool.",
-  },
-  {
-    name: "vice_checkpoint_set_ignore_count",
-    category: "descoped",
-    providedBy: "fork",
-    reason:
-      "No native wire ignore-count exists; the only implementation would require resuming the " +
-      "machine on every ignored hit, which the no-unrequested-resume policy forbids. " +
-      "CHECKPOINT_INFO's reply still reports an existing ignore count read-only.",
-  },
-  {
-    name: "vice_cia_set_state",
-    category: "descoped",
-    providedBy: "fork",
-    reason:
-      "The write half of a tool whose read half already ships on stock; no shipped skill calls " +
-      "the write half.",
-  },
-  {
-    name: "vice_vicii_set_state",
-    category: "descoped",
-    providedBy: "fork",
-    reason:
-      "The write half of a tool whose read half already ships on stock; no shipped skill calls " +
-      "the write half.",
-  },
-  {
-    name: "vice_sprite_set",
-    category: "descoped",
-    providedBy: "fork",
-    reason:
-      "The write half of a tool whose read half already ships on stock; no shipped skill calls " +
-      "the write half.",
-  },
-  {
-    name: "vice_memory_fill",
-    category: "descoped",
-    providedBy: "fork",
-    reason: "No shipped skill calls it.",
-  },
-  {
-    name: "vice_sid_set_state",
-    category: "descoped",
-    providedBy: "fork",
-    reason:
-      "SID writes work fine over MEM_SET at $D400-$D418 -- this is not a hardware loss, only " +
-      "reads are write-only in hardware. It is simply not implemented because no shipped skill " +
-      "calls it.",
-  },
-  {
-    name: "vice_machine_config_get",
-    category: "descoped",
-    providedBy: "fork",
-    reason:
-      "Full resource get/set access was descoped; the fork's tool is a hand-curated whitelist " +
-      "subset that never shipped on stock.",
-  },
-  {
-    name: "vice_machine_config_set",
-    category: "descoped",
-    providedBy: "fork",
-    reason:
-      "Full resource get/set access was descoped; the fork's tool is a hand-curated whitelist " +
-      "subset that never shipped on stock. Its advertised WarpMode resource is fork-only: stock " +
-      "has no runtime warp resource at all, and warp on stock is a launch-time flag, not a " +
-      "resource that can be toggled while running.",
-  },
-  {
-    name: "vice_joystick_tap",
-    category: "descoped",
-    providedBy: "fork",
-    reason:
-      "Requires running the machine for a measured hold-then-release interval, which depends on " +
-      "timing infrastructure; not yet built, and no shipped skill calls it.",
-  },
-
-  // --- stock-only-gain (2), providedBy: stock ------------------------------
-  {
-    name: "vice_execution_until_return",
-    category: "stock-only-gain",
-    providedBy: "stock",
-    reason: "The fork's custom HTTP API has no equivalent RPC; this is the native EXECUTE_UNTIL_RETURN opcode.",
-  },
-  {
-    name: "vice_registers_available",
-    category: "stock-only-gain",
-    providedBy: "stock",
-    reason: "The fork has no equivalent enumeration call; this is the native REGISTERS_AVAILABLE opcode.",
-  },
-];
-
-/**
- * Plain name-keyed lookup over CAPABILITY_REGISTRY. `name` is untrusted
- * `request.params.name` from the wire: it is used ONLY as an equality
- * comparison value below. Never interpolate it into a path, a command, or
- * anything executed.
- */
-export function capabilityEntryFor(name: string): CapabilityEntry | undefined {
-  return CAPABILITY_REGISTRY.find((entry) => entry.name === name);
-}
-
-/**
- * Renders the BACK-05 refusal for `name` on `activeBackend`, or `undefined`
- * when there is nothing to refuse -- mirroring denyListRefusalMessage()'s
- * keyed-by-hazard-shape contract (vice.ts).
- *
- * Returns `undefined` when:
- *   - no registry entry exists for `name` (a genuinely unknown tool name --
- *     a typo -- must still fall through to the generic "Unknown tool"
- *     message at the call site, not this function's wording); or
- *   - `entry.providedBy === activeBackend` (defensive: the active backend
- *     already advertises this tool, so a miss here is a genuine
- *     unknown-tool case, not a capability gap, and must not be
- *     misclassified as one).
- *
- * Otherwise renders one of three wordings, selected by `entry.category`:
- *   - "hardware": names the tool, states it is unrecoverable on
- *     `activeBackend`, gives `entry.reason`, then names `entry.providedBy`
- *     with the actionable `Set VICE_BACKEND=...`, then `entry.alternative`
- *     when present. No "wait for a later phase" framing -- none is coming
- *     for a hardware loss, but a stock route may still exist and must be
- *     named here, since this is where the caller actually reads it.
- *   - "descoped": names the tool, states it is not implemented on
- *     `activeBackend`, gives `entry.reason`, then `entry.providedBy` and
- *     `Set VICE_BACKEND=...`, then `entry.alternative` when present. The
- *     literal token "unrecoverable" must NEVER appear in this wording: a
- *     reader told "not supported" for both a hardware loss and a merely
- *     unbuilt tool cannot tell which one is worth filing an issue about.
- *   - "stock-only-gain": names the tool, states it is not implemented on the
- *     fork backend specifically, gives `entry.reason`, then
- *     `Set VICE_BACKEND=stock`.
- */
-export function capabilityRefusalMessage(
-  name: string,
-  activeBackend: ViceBackend,
-): string | undefined {
-  const entry = capabilityEntryFor(name);
-  if (!entry) return undefined;
-  if (entry.providedBy === activeBackend) return undefined;
-
-  // `alternative` is rendered in EVERY branch that has one. It used to be
-  // read only inside the "descoped" branch, which made the field dead at
-  // runtime: all five entries that carry an alternative are category
-  // "hardware", and no "descoped" entry has one. The generated support
-  // table, the skill playbooks and README all printed the stock route while
-  // the runtime refusal -- the one surface BACK-05 exists for -- dropped it.
-  // Do not re-scope this back into a single branch.
-  const alt = entry.alternative ? ` ${entry.alternative}` : "";
-
-  if (entry.category === "hardware") {
-    return (
-      `${entry.name} is unrecoverable on the ${activeBackend} backend: ${entry.reason} ` +
-      `Use the ${entry.providedBy} backend instead (Set VICE_BACKEND=${entry.providedBy}).${alt}`
-    );
-  }
-
-  if (entry.category === "descoped") {
-    return (
-      `${entry.name} is not implemented on the ${activeBackend} backend: ${entry.reason} ` +
-      `Use the ${entry.providedBy} backend instead (Set VICE_BACKEND=${entry.providedBy}).${alt}`
-    );
-  }
-
-  // category === "stock-only-gain": only reachable with activeBackend ===
-  // "fork" and entry.providedBy === "stock", since the same-backend guard
-  // above already excluded the activeBackend === "stock" case.
-  return (
-    `${entry.name} is not implemented on the fork backend: ${entry.reason} ` +
-    `Use the stock backend instead (Set VICE_BACKEND=stock).${alt}`
-  );
-}

package/refresh-manifest.ts

@@ -1,124 +0,0 @@
-#!/usr/bin/env node
-// The ONLY writer of tools-manifest.json (see vice-proxy.mjs's tools/list
-// handler doc comment -- that handler is a pure, offline READ of the file
-// this CLI produces). An operator runs this by hand against a running host
-// to refresh the snapshot; vice-proxy.mjs never imports this file, so this
-// file's stdout is a normal CLI stream, not the MCP channel.
-//
-// Sibling import: the transport module lives in this skill's own scripts/
-// directory (plan 01.1-04 relocated it from the now-retired `vice-session`
-// skill).
-import { serverInfo, activeInstance, type ServerInfoPayload, type ToolInfo } from "./vice.ts";
-import { writeFileSync, chmodSync, renameSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { basename, dirname, join, resolve } from "node:path";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-const DEFAULT_MANIFEST_PATH = join(HERE, "tools-manifest.json");
-
-// The hand-authored stock surface's own filename (stock-dispatch.ts's
-// tools-manifest.stock.json, plan 02-09) -- named here ONLY so
-// writeManifestAtomic() below can refuse to ever target it, never as
-// something this file writes.
-const STOCK_MANIFEST_BASENAME = "tools-manifest.stock.json";
-
-function manifestPath(): string {
-  return process.env.VICE_TOOLS_MANIFEST
-    ? resolve(process.env.VICE_TOOLS_MANIFEST)
-    : DEFAULT_MANIFEST_PATH;
-}
-
-export interface ToolsManifest {
-  generated_at: string;
-  endpoint: string;
-  tools: ToolInfo[];
-}
-
-/** Write `manifest` to `path` via the tmp sibling -> restrict-mode -> content
- * -> rename sequence (01.6.1-06 Decision 1), copied verbatim in shape from
- * vice-broker.mts's writeBrokerRecord(). The tmp file is created EMPTY and
- * mode-tightened to 0o600 BEFORE any content reaches it, then renamed into
- * place -- so a crash or a full disk mid-write can only ever leave a stray
- * tmp sibling behind, never a partial or empty file at the real path. This
- * is what makes this module's own long-standing promise ("a partial or
- * empty manifest is never written over a good one on failure") true against
- * a crash, not only against a rejected handshake -- the rejected-handshake
- * half of that guarantee already held (the early return below, unchanged
- * from the original), but a crash between "open the file" and "write the
- * content" could previously still truncate a good manifest to nothing.
- *
- * T-02-31 (02-09): this function regenerates the manifest from a LIVE fork
- * host's tools/list, so its output path must NEVER be
- * tools-manifest.stock.json -- that file is the hand-authored, separately
- * committed stock surface (D-07/D-09), and this refresh path overwriting it
- * with the fork's full tool list would silently destroy the trimming that
- * surface exists to enforce. This assertion makes that impossible by
- * accident; a future `--stock` flag pointing this generator at the stock
- * file has to edit this line deliberately, not merely change a default. */
-function writeManifestAtomic(path: string, manifest: ToolsManifest): void {
-  if (basename(path) === STOCK_MANIFEST_BASENAME) {
-    throw new Error(
-      `refresh-manifest: refusing to write ${STOCK_MANIFEST_BASENAME} -- this generator regenerates the fork's ` +
-        `manifest from a live host and must never overwrite the hand-authored stock surface (D-07/D-09)`
-    );
-  }
-  const tmpPath = `${path}.tmp-${process.pid}-${Date.now()}`;
-  writeFileSync(tmpPath, "");
-  chmodSync(tmpPath, 0o600);
-  writeFileSync(tmpPath, JSON.stringify(manifest, null, 2) + "\n");
-  renameSync(tmpPath, path);
-}
-
-/** Parses no arguments (there are none), performs the host handshake, and
- * writes the manifest -- or leaves the existing one untouched and sets a
- * non-zero exit code if the handshake fails. Exported (01.6.1-06 Decision 2)
- * so this can be driven directly in a test without spawning a process; the
- * bottom-of-module entry-point guard below is what makes that safe -- import
- * alone must never perform a handshake or write anything. */
-export async function main(): Promise<void> {
-  const path = manifestPath();
-
-  // serverInfo() performs the host handshake (initialize + tools/list) and
-  // already strips DENY_LIST names before returning (vice.ts's own
-  // documented choke point) -- vice-proxy.mjs's tools/list handler applies
-  // the SAME filter again at read time, so a snapshot generated by any other
-  // means is still safe, but this refresh path inherits the omission for
-  // free.
-  let info: ServerInfoPayload;
-  try {
-    info = (await serverInfo()) as ServerInfoPayload;
-  } catch (e) {
-    const message = e instanceof Error ? e.message : String(e);
-    console.error(
-      `refresh-manifest: could not reach the host VICE MCP server (${message}) -- ` +
-        `manifest at ${path} left UNCHANGED. A partial or empty manifest is never written over a good one on ` +
-        `failure -- whether the failure is a rejected handshake (this path) or a crash mid-write, the latter now ` +
-        `also covered by the tmp-sibling -> restrict-mode -> content -> rename sequence below.`
-    );
-    process.exitCode = 1;
-    return;
-  }
-
-  const tools = Array.isArray(info?.tools) ? info.tools : [];
-  const manifest: ToolsManifest = {
-    generated_at: new Date().toISOString(),
-    endpoint: activeInstance().url,
-    tools,
-  };
-
-  writeManifestAtomic(path, manifest);
-  console.log(`refresh-manifest: wrote ${tools.length} tool${tools.length === 1 ? "" : "s"} to ${path}`);
-}
-
-// -------------------------------------------------------------------- CLI
-// Guarded exactly like vice-broker.mts's own entry point: importing this
-// module (e.g. from a test) must never itself perform a handshake or write
-// anything. process.exitCode, never process.exit(), so any pending I/O
-// flushes first.
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  main().catch((e: unknown) => {
-    const detail = e instanceof Error && e.stack ? e.stack : String(e);
-    console.error(`refresh-manifest: unexpected error -- ${detail}`);
-    process.exitCode = 1;
-  });
-}