@henols/vice-mcp 0.1.9 → 0.1.11

package/stock-memory.ts

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+// stock-memory.ts
+//
+// THE memory half of Family A on the stock backend (D-03/DIRECT-01/
+// DIRECT-09): vice_memory_read, vice_memory_write, and vice_memory_banks,
+// as StockSessionHandler-shaped exports, plus the per-session bank catalog
+// all three share.
+//
+// WHY THIS FILE EXISTS: this is the first half of phase success criterion
+// 1 -- reads must be side-effect-free by default and must not force a
+// pause/resume round trip. On stock there is no round trip at all: the
+// command halts the machine (D-05) and the answer reports `runState`
+// (D-06) via stock-handler.ts's stockAnswer(). A named `bank` argument
+// (the fork's own "e.g. 'ram' to read RAM under ROM" convention) must
+// resolve to a wire bank id through the emulator's own BANKS_AVAILABLE
+// enumeration -- RESEARCH.md's "reading them beats hardcoding a guess" --
+// never a hardcoded table, since bank ids are build- and machine-specific.
+//
+// WHAT NOT TO DO:
+//   - Never build a MEM_GET/MEM_SET body by hand -- stock-protocol.ts's
+//     memGetBody()/memSetBody() are the only encoders used here.
+//   - Never re-derive address parsing locally (D-04) -- stock-address.ts's
+//     parseAddress()/parseByteCount() are the only seam.
+//   - Never construct an ok-answer outside stockAnswer() (D-06) -- that is
+//     exactly how an answer ships without `runState`.
+//   - Never send an EXIT to "restore" the machine after a read (D-05) -- a
+//     read leaves the machine halted, and the answer says so via runState.
+import { CommandType, memGetBody, memSetBody } from "./stock-protocol.ts";
+import { parseAddress, parseByteCount } from "./stock-address.ts";
+import { convertWireError, isErrorText, stockAnswer, type StockSessionHandler, type StockToolResult } from "./stock-handler.ts";
+import type { StockConnectSession } from "./stock-connect.ts";
+
+/** True iff `value` is a well-formed, generic JSON object -- not null, not
+ * an array. Matches vice.ts's own isPlainObject() predicate exactly -- the
+ * same narrowing discipline this module tree uses everywhere a parsed JSON
+ * value's fields are touched (03-PATTERNS.md). */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// ---------------------------------------------------------------------------
+// The bank catalog (Task 2) -- a per-session, lazily-fetched map between a
+// bank's wire id and its name, backed by ONE module-level cache keyed on
+// the session object (see freshCatalogCache() below for the single
+// definition of that cache's storage). A stockReconnect() builds a fresh
+// session and therefore naturally gets a fresh catalog, with no manual
+// invalidation. Never a module-level singleton, and never a persisted
+// record: this is in-memory, per-connection state, unlike
+// stock-connect.ts's resolveCapabilities() (settle-once, cache-on-disk).
+// ---------------------------------------------------------------------------
+
+export interface BankCatalog {
+  byName: Map<string, number>;
+  byId: Map<number, string>;
+}
+
+/** The one place this file's per-session cache storage is defined -- an
+ * object-keyed cache that never prevents a dropped session from being
+ * garbage-collected. Both the module-level holder below and
+ * resetBankCatalogsForTest() call this rather than repeating the
+ * constructor inline. */
+function freshCatalogCache(): WeakMap<object, BankCatalog> { return new WeakMap(); }
+
+let bankCatalogs = freshCatalogCache();
+
+/** Test-only: replaces the module-level cache with a fresh one, matching
+ * clearHeldStockSession()'s / resetRunStateTrackersForTest()'s role in this
+ * module tree's beforeEach() convention. */
+export function resetBankCatalogsForTest(): void {
+  bankCatalogs = freshCatalogCache();
+}
+
+/**
+ * Resolves (and caches, per session) the emulator's own bank enumeration.
+ * On a cache miss, sends BANKS_AVAILABLE (0x82) with no body -- the opcode
+ * takes an empty body, and client.send() already defaults to
+ * Buffer.alloc(0), so there is no dedicated wire-body encoder to invent for
+ * this command. Bank names are matched case-insensitively on lookup (the
+ * lowercased name is the map key; the wire's own spelling is kept in
+ * `byId` for reporting), because the fork's own tool description uses
+ * lowercase 'ram'.
+ */
+export async function bankCatalogFor(session: StockConnectSession): Promise<BankCatalog> {
+  const existing = bankCatalogs.get(session);
+  if (existing) {
+    return existing;
+  }
+
+  const response = await session.client.send(CommandType.BanksAvailable);
+  if (response.type !== "banks_available") {
+    throw new Error(`bankCatalogFor: expected a "banks_available" reply, got "${response.type}"`);
+  }
+
+  const byName = new Map<string, number>();
+  const byId = new Map<number, string>();
+  for (const bank of response.banks) {
+    byName.set(bank.name.toLowerCase(), bank.id);
+    byId.set(bank.id, bank.name);
+  }
+
+  const catalog: BankCatalog = { byName, byId };
+  bankCatalogs.set(session, catalog);
+  return catalog;
+}
+
+/** Shared bank-argument resolution for both memory handlers below: omitted
+ * `bank` resolves to wire id 0x0000, a non-string `bank` refuses, and an
+ * unknown name refuses listing the names the catalog actually returned --
+ * never a hardcoded table. Factored once so handleMemoryRead/Write do not
+ * each re-derive the same three branches. */
+async function resolveBank(
+  toolName: string,
+  bankArg: unknown,
+  session: StockConnectSession,
+): Promise<{ ok: true; id: number; name?: string } | { ok: false; result: StockToolResult }> {
+  if (bankArg === undefined) {
+    return { ok: true, id: 0x0000 };
+  }
+  if (typeof bankArg !== "string") {
+    return { ok: false, result: isErrorText(`${toolName}: bank must be a string, got ${typeof bankArg}`) };
+  }
+
+  let catalog: BankCatalog;
+  try {
+    catalog = await bankCatalogFor(session);
+  } catch (err) {
+    return { ok: false, result: convertWireError(toolName, err) };
+  }
+
+  const resolved = catalog.byName.get(bankArg.toLowerCase());
+  if (resolved === undefined) {
+    const names = [...catalog.byId.values()].join(", ") || "(none reported)";
+    return { ok: false, result: isErrorText(`${toolName}: unknown bank "${bankArg}" -- available banks: ${names}`) };
+  }
+  return { ok: true, id: resolved, name: bankArg };
+}
+
+// ---------------------------------------------------------------------------
+// vice_memory_banks (Task 2)
+// ---------------------------------------------------------------------------
+
+export const handleMemoryBanks: StockSessionHandler = async (args, session, _deps) => {
+  if (!isPlainObject(args)) {
+    return isErrorText("vice_memory_banks: arguments must be an object");
+  }
+  const unexpected = Object.keys(args);
+  if (unexpected.length > 0) {
+    return isErrorText(`vice_memory_banks: unexpected argument(s): ${unexpected.join(", ")} -- this tool takes no arguments`);
+  }
+
+  let catalog: BankCatalog;
+  try {
+    catalog = await bankCatalogFor(session);
+  } catch (err) {
+    return convertWireError("vice_memory_banks", err);
+  }
+
+  const banks = [...catalog.byId.entries()].map(([id, name]) => ({ id, name }));
+  return stockAnswer(session.client, { banks, count: banks.length });
+};
+
+// ---------------------------------------------------------------------------
+// vice_memory_read (Task 1)
+// ---------------------------------------------------------------------------
+
+export const handleMemoryRead: StockSessionHandler = async (args, session, _deps) => {
+  if (!isPlainObject(args)) {
+    return isErrorText("vice_memory_read: arguments must be an object");
+  }
+
+  let address: number;
+  try {
+    address = parseAddress(args.address, { what: "address" });
+  } catch (err) {
+    return isErrorText(`vice_memory_read: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  let size: number;
+  try {
+    size = parseByteCount(args.size, { max: 0xffff, what: "size" });
+  } catch (err) {
+    return isErrorText(`vice_memory_read: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  const end = address + size - 1;
+  if (end > 0xffff) {
+    return isErrorText(
+      `vice_memory_read: address 0x${address.toString(16)} + size ${size} exceeds the 16-bit address space (end would be 0x${end.toString(16)})`,
+    );
+  }
+
+  let encoding: "hex" | "array" = "hex";
+  if (args.encoding !== undefined) {
+    if (args.encoding !== "hex" && args.encoding !== "array") {
+      return isErrorText(`vice_memory_read: encoding must be "hex" or "array", got ${JSON.stringify(args.encoding)}`);
+    }
+    encoding = args.encoding;
+  }
+
+  let sideEffects = false;
+  if (args.sideEffects !== undefined) {
+    if (typeof args.sideEffects !== "boolean") {
+      return isErrorText(`vice_memory_read: sideEffects must be a boolean, got ${typeof args.sideEffects}`);
+    }
+    sideEffects = args.sideEffects;
+  }
+
+  const bankResolution = await resolveBank("vice_memory_read", args.bank, session);
+  if (!bankResolution.ok) {
+    return bankResolution.result;
+  }
+
+  // Memspace is fixed to 0x00 (main) in Phase 3 -- drive memspace is Phase
+  // 6's GAIN-03; there is deliberately no argument for it here.
+  const body = memGetBody({ sidefx: sideEffects, start: address, end, memspace: 0x00, bank: bankResolution.id });
+
+  let response;
+  try {
+    response = await session.client.send(CommandType.MemoryGet, body);
+  } catch (err) {
+    return convertWireError("vice_memory_read", err);
+  }
+
+  if (response.type !== "memory_get") {
+    return isErrorText(
+      `vice_memory_read: the binary monitor replied with an unexpected response type ("${response.type}"), expected "memory_get"`,
+    );
+  }
+
+  if (response.bytes.length !== size) {
+    return isErrorText(`vice_memory_read: expected ${size} byte(s), got ${response.bytes.length} -- a short read is a wrong answer, not a partial success`);
+  }
+
+  const payload: Record<string, unknown> = {
+    address,
+    size,
+    encoding,
+    sideEffects,
+    bank: bankResolution.name !== undefined ? { id: bankResolution.id, name: bankResolution.name } : bankResolution.id,
+    memspace: "main",
+  };
+  if (encoding === "hex") {
+    payload.hex = Buffer.from(response.bytes).toString("hex");
+  } else {
+    payload.bytes = Array.from(response.bytes);
+  }
+
+  return stockAnswer(session.client, payload);
+};
+
+// ---------------------------------------------------------------------------
+// vice_memory_write (Task 1)
+// ---------------------------------------------------------------------------
+
+export const handleMemoryWrite: StockSessionHandler = async (args, session, _deps) => {
+  if (!isPlainObject(args)) {
+    return isErrorText("vice_memory_write: arguments must be an object");
+  }
+
+  let address: number;
+  try {
+    address = parseAddress(args.address, { what: "address" });
+  } catch (err) {
+    return isErrorText(`vice_memory_write: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  if (!Array.isArray(args.data)) {
+    return isErrorText(`vice_memory_write: data must be an array of integers 0..255, got ${typeof args.data}`);
+  }
+  if (args.data.length === 0) {
+    return isErrorText("vice_memory_write: data must not be empty");
+  }
+  const data: number[] = [];
+  for (let index = 0; index < args.data.length; index += 1) {
+    const value: unknown = args.data[index];
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 0xff) {
+      return isErrorText(`vice_memory_write: data[${index}] must be an integer 0..255, got ${JSON.stringify(value)}`);
+    }
+    data.push(value);
+  }
+
+  const end = address + data.length - 1;
+  if (end > 0xffff) {
+    return isErrorText(
+      `vice_memory_write: address 0x${address.toString(16)} + data.length ${data.length} exceeds the 16-bit address space (end would be 0x${end.toString(16)})`,
+    );
+  }
+
+  const bankResolution = await resolveBank("vice_memory_write", args.bank, session);
+  if (!bankResolution.ok) {
+    return bankResolution.result;
+  }
+
+  // memSetBody() forces sidefx to 0x00 on the wire -- a write is not a read
+  // and takes no sideEffects argument.
+  const body = memSetBody({ start: address, end, memspace: 0x00, bank: bankResolution.id, data: Buffer.from(data) });
+
+  let response;
+  try {
+    response = await session.client.send(CommandType.MemorySet, body);
+  } catch (err) {
+    return convertWireError("vice_memory_write", err);
+  }
+
+  // MEM_SET's acknowledgement carries no useful body -- stock-protocol.ts
+  // has no named parsed shape for it (matching several other ack-only
+  // commands in that file's switch), so the "unknown" fallback IS the
+  // expected reply shape here, not an error. Anything else would mean a
+  // future parser change gave MEM_SET a real shape without this handler
+  // noticing.
+  if (response.type !== "unknown") {
+    return isErrorText(
+      `vice_memory_write: the binary monitor replied with an unexpected response type ("${response.type}"), expected an acknowledgement`,
+    );
+  }
+
+  return stockAnswer(session.client, {
+    address,
+    bytesWritten: data.length,
+    bank: bankResolution.name !== undefined ? { id: bankResolution.id, name: bankResolution.name } : bankResolution.id,
+    memspace: "main",
+  });
+};

package/stock-paths.ts

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// stock-paths.ts
+//
+// D-17's ONE declared table and the ONE translation wrapper: this file is the
+// single place a stock handler turns a container-side path into the
+// host-side path stock VICE's binary monitor itself opens. Four tools --
+// `vice_autostart` (AUTOSTART's filename), `vice_disk_attach` (AUTOSTART's
+// filename, the D-14 approximation), `vice_snapshot_save` (DUMP's filename,
+// client-constructed from `name`), `vice_snapshot_load` (UNDUMP's filename,
+// also client-constructed) -- carry a filename VICE opens ON THE HOST, so
+// those four, and only those four, translate through here.
+//
+// WHY THIS FILE EXISTS: this is the MIRROR IMAGE of Phase 4's DERIV-07
+// hazard -- there, translating a client-side-derived path is the bug; here,
+// NOT translating an emulator-side path is the bug. D-17 puts both
+// directions in one legible place so a future implementer working either
+// side finds this comment.
+//
+// WHAT NOT TO DO:
+//   - Never call rewriteArguments() from a stock handler. It lives INSIDE
+//     forwardToVice() (vice-proxy.ts, around line 2773) -- the one function
+//     Phase 2's D-09 says the stock path must never touch -- and its own
+//     comment inverts on stock: what is correct for the fork's derived tools
+//     is exactly wrong here.
+//   - Never build a host path with a local heuristic (a hand-rolled prefix
+//     swap, a hardcoded mount guess, anything not routed through
+//     hostpath.ts's own hostPathCandidates()/tryHostPaths()). hostpath.ts is
+//     the one seam that owns bind-mount discovery.
+//   - Never add a CLIENT-SIDE derivation to STOCK_EMULATOR_SIDE_PATH_TOOLS.
+//     Phase 5's screenshots are decoded client-side (the INDEXED8 framebuffer
+//     arrives over the wire and is encoded to PNG in this process) and must
+//     NEVER be translated -- adding a client-side-derived tool to this table
+//     would be the exact mirror-image bug this file's header exists to name.
+//     A future Phase 5 implementer who is tempted to route a screenshot path
+//     through withEmulatorSidePath() should stop and re-read this paragraph.
+import { dirname, join } from "node:path";
+
+import { ViceError, type ViceErrorOptions } from "./vice.ts";
+import { repoRoot } from "./repo-root.ts";
+import { isInsideContainer } from "./container-guard.mts";
+import { tryHostPaths } from "./hostpath.ts";
+import { ErrorCode, StockProtocolError } from "./stock-protocol.ts";
+
+/** The one error type this module ever throws -- never a bare Error,
+ * matching vice.ts's established ViceError hierarchy (stock-address.ts's
+ * StockAddressError is the sibling precedent). */
+export class StockPathError extends ViceError {
+  constructor(message: string, options: ViceErrorOptions = {}) {
+    super(message, options);
+    this.name = "StockPathError";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// D-17's declared table -- the complete Phase 3 set. Exactly four entries;
+// a test asserts the size and membership so a future addition (or removal)
+// is a deliberate, reviewed edit to this literal, not a silent drift.
+// ---------------------------------------------------------------------------
+
+export const STOCK_EMULATOR_SIDE_PATH_TOOLS: ReadonlySet<string> = new Set([
+  "vice_autostart", // AUTOSTART (0xdd) request body's filename field
+  "vice_disk_attach", // AUTOSTART (0xdd) again -- the D-14 approximation
+  "vice_snapshot_save", // DUMP (0x41) request body's filename field
+  "vice_snapshot_load", // UNDUMP (0x42) request body's filename field
+]);
+
+// ---------------------------------------------------------------------------
+// withEmulatorSidePath() -- the one translation wrapper.
+// ---------------------------------------------------------------------------
+
+/**
+ * Translates `containerPath` to a host path and calls `send(hostPath)`,
+ * returning both the callee's result and the path actually put on the wire.
+ *
+ * Refuses any `toolName` not in STOCK_EMULATOR_SIDE_PATH_TOOLS -- a handler
+ * cannot opt itself into translation without being declared in the table
+ * above, so the declared set and the actual behaviour can never drift apart.
+ *
+ * On a bare host (`isInsideContainer()` false), `containerPath` already IS
+ * the host path -- calling hostPathCandidates()'s mountinfo guesser there
+ * would fabricate a wrong path (with only a stderr warning to show for it),
+ * so this branch calls `send(containerPath)` directly and reports
+ * `sentPath: containerPath` unchanged.
+ *
+ * Inside a container, translates via `tryHostPaths()` with
+ * `workspaceRoot: repoRoot()` and a `fatal` predicate that returns `false`
+ * ONLY for a StockProtocolError whose errorCode is ErrorCode.CmdFailure
+ * (0x8f) -- "the monitor could not open that file", the one genuine
+ * wrong-path signal that licenses retrying the next candidate host path.
+ * Every other rejection (a framing error, a connection failure, a timeout)
+ * returns `true` (fatal), stopping probing immediately rather than retrying
+ * five more candidates against a connection that is not coming back.
+ */
+export async function withEmulatorSidePath<T>(
+  toolName: string,
+  containerPath: string,
+  send: (path: string) => Promise<T>,
+): Promise<{ result: T; sentPath: string }> {
+  if (!STOCK_EMULATOR_SIDE_PATH_TOOLS.has(toolName)) {
+    throw new StockPathError(
+      `withEmulatorSidePath: ${toolName} is not declared in STOCK_EMULATOR_SIDE_PATH_TOOLS -- only vice_autostart, ` +
+        `vice_disk_attach, vice_snapshot_save and vice_snapshot_load carry an emulator-side path argument (D-17).`,
+    );
+  }
+
+  if (!isInsideContainerFn()) {
+    // On a bare host, containerPath already IS the host path -- see this
+    // function's own header comment above for why the mountinfo guesser
+    // must not run here.
+    const result = await send(containerPath);
+    return { result, sentPath: containerPath };
+  }
+
+  const fatal = (err: unknown): boolean => {
+    if (err instanceof StockProtocolError && err.errorCode === ErrorCode.CmdFailure) {
+      return false; // the one genuine wrong-path signal -- keep probing
+    }
+    return true; // anything else stops probing immediately
+  };
+
+  const { result, hostPath } = await tryHostPaths(containerPath, send, { workspaceRoot: repoRoot(), fatal });
+  return { result, sentPath: hostPath };
+}
+
+// ---------------------------------------------------------------------------
+// Test-only injection point for isInsideContainer(), following
+// stock-address.ts's setSymbolResolver() / stock-runstate.ts's
+// resetRunStateTrackersForTest() precedent: a module-level setter rather than
+// widening withEmulatorSidePath()'s own public signature (which the plan
+// fixes at exactly three parameters). Production code never calls this;
+// the default below is the real isInsideContainer() from container-guard.mts.
+// ---------------------------------------------------------------------------
+
+let isInsideContainerFn: () => boolean = () => isInsideContainer();
+
+/** Test-only: overrides the isInsideContainer() check withEmulatorSidePath()
+ * consults, without touching container-guard.mts's own memoised verdict or
+ * widening withEmulatorSidePath()'s public signature. Pass `null` to restore
+ * the real check. */
+export function setIsInsideContainerForTest(fn: (() => boolean) | null): void {
+  isInsideContainerFn = fn ?? (() => isInsideContainer());
+}
+
+// ---------------------------------------------------------------------------
+// Snapshot name sanitisation and path construction -- T-3-05's mitigation.
+// ---------------------------------------------------------------------------
+
+const SNAPSHOT_NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
+/**
+ * Refuses anything not matching /^[A-Za-z0-9_-]{1,64}$/ -- the name is used
+ * to build a filename, so path separators, `..` and absolute paths are
+ * rejected outright rather than sanitised. Matches the fork's own documented
+ * constraint ("alphanumeric, underscore, hyphen only"). This is the T-3-05
+ * control: a snapshot `name` is never treated as a path fragment.
+ */
+export function sanitizeSnapshotName(name: unknown): string {
+  if (typeof name !== "string" || !SNAPSHOT_NAME_RE.test(name)) {
+    throw new StockPathError(
+      `sanitizeSnapshotName: name must be 1-64 characters of alphanumeric, underscore or hyphen only ` +
+        `(matching ${SNAPSHOT_NAME_RE}) -- it is used to build a filename, so path separators, ".." and absolute ` +
+        `paths are rejected outright. Got ${JSON.stringify(name)}.`,
+    );
+  }
+  return name;
+}
+
+/**
+ * The container path a snapshot named `name` lives at:
+ * `<repoRoot>/.vice-snapshots/<name>.vsf`. The directory is inside the
+ * workspace rather than under `~/.config/vice/` (the fork's own location)
+ * because only a workspace path is inside hostpath.ts's bind-mount mapping
+ * -- anything outside it cannot be translated for the host at all -- and
+ * keeping it inside the workspace makes workspace escape structurally
+ * impossible rather than merely checked (T-3-05).
+ */
+export function snapshotPathFor(name: string): string {
+  return join(repoRoot(), ".vice-snapshots", `${sanitizeSnapshotName(name)}.vsf`);
+}
+
+/** The sidecar metadata path for the same snapshot: same directory, `.json`
+ * extension, same sanitisation. */
+export function snapshotMetaPathFor(name: string): string {
+  return join(repoRoot(), ".vice-snapshots", `${sanitizeSnapshotName(name)}.json`);
+}
+
+// Re-exported so a caller building a directory before translating (Task 3's
+// handleSnapshotSave, matching vice-sync.ts's screenshot()'s own
+// mkdirSync(dirname(containerPath), { recursive: true })-before-translate
+// ordering) never needs a second import specifier for dirname().
+export { dirname };

package/stock-petscii.ts

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// stock-petscii.ts
+//
+// THE one ASCII<->PETSCII conversion in this tree. No such table exists
+// anywhere else in this codebase or its skills -- the custom fork did this
+// conversion server-side in C (docs/03-RESEARCH.md's own grep confirmed
+// zero hits). stock-input.ts's handleKeyboardType() is the only production
+// call site; nothing else may hand-roll a second version.
+//
+// WHY THIS FILE EXISTS: KEYBOARD_FEED (0x72) only accepts PETSCII bytes on
+// the wire, but the `vice_keyboard_type` tool's `text` argument is an
+// ordinary ASCII/JS string. Something has to sit between the two, and it
+// has to get the case-swap and control-code boundaries exactly right --
+// PETSCII's unshifted/shifted case-swap region is a frequent source of
+// off-by-one and reversed-case bugs when hand-transcribed (03-RESEARCH.md
+// Pitfall 3), because the letter ranges "look like" a uniform 0x20 XOR but
+// the boundary and control regions do not follow that rule. The mapping
+// below matches VICE's own charset_p_topetscii() case-swap behaviour.
+//
+// WHAT NOT TO DO:
+//   - Never write a second inline ASCII->PETSCII conversion at a call site.
+//     Five inconsistent hand-rolled versions scattered across handlers is
+//     exactly the failure mode this module exists to prevent -- import
+//     asciiToPetscii() instead.
+//   - Never pass an unmapped byte through silently. A raw PETSCII control
+//     code such as 0x93 (clear screen) landing in an LLM-supplied string
+//     would silently corrupt the debugged program's display the moment it
+//     reaches the keyboard buffer. Every byte this table does not
+//     explicitly map is refused, naming the offending index and hex code --
+//     never truncated, never passed through, never silently dropped.
+//   - Never assume the letter ranges are a uniform 0x20 XOR. The boundary
+//     bytes (0x40/0x41, 0x5a/0x5b, 0x60/0x61, 0x7a/0x7b) and the control-code
+//     regions do not follow that rule uniformly; each range below is
+//     checked explicitly, not derived from a single arithmetic shortcut.
+import { ViceError } from "./vice.ts";
+
+/** PETSCII's Return code. Both ASCII LF (`\n`) and CR (`\r`) map here -- this
+ * is what the fork's own "Use \n for Return" tool description promises. */
+export const PETSCII_RETURN = 0x0d;
+
+export interface StockPetsciiErrorOptions {
+  index?: number;
+}
+
+/**
+ * Raised by asciiToPetscii() for any input that cannot be safely converted:
+ * a non-string, an empty string, a converted length over 255 bytes, a code
+ * unit above 0xff, or a byte this table does not map. Always thrown before
+ * any bytes are written to the caller-visible Buffer.
+ */
+export class StockPetsciiError extends ViceError {
+  index?: number;
+
+  constructor(message: string, { index }: StockPetsciiErrorOptions = {}) {
+    super(message);
+    this.name = "StockPetsciiError";
+    this.index = index;
+  }
+}
+
+export interface AsciiToPetsciiOptions {
+  /** Default true: uppercase ASCII (`A`-`Z`) displays as uppercase on the
+   * C64 -- the fork's own petscii_upper default-true semantic. Setting this
+   * false is a deliberate pass-through of the raw ASCII byte for both case
+   * ranges, mirroring the fork's "raw PETSCII (uppercase ASCII maps to
+   * graphics)" documented behaviour. The case-swap this option performs
+   * when true is exactly what makes uppercase ASCII display as uppercase in
+   * both the unshifted and mixed-case C64 charsets. */
+  upper?: boolean;
+}
+
+/**
+ * Converts one input byte (already narrowed to 0x00-0xff by the caller) to
+ * its PETSCII equivalent, or throws a StockPetsciiError naming `index` if
+ * the byte has no mapping. Matches VICE's own charset_p_topetscii() case-
+ * swap rule, byte range by byte range -- never a single 0x20 XOR shortcut.
+ */
+function convertByte(byte: number, index: number, upper: boolean): number {
+  if (byte === 0x0a || byte === 0x0d) {
+    return PETSCII_RETURN;
+  }
+  if (byte >= 0x20 && byte <= 0x40) {
+    return byte;
+  }
+  if (byte >= 0x41 && byte <= 0x5a) {
+    return upper ? (byte | 0x80) : byte;
+  }
+  if (byte >= 0x5b && byte <= 0x60) {
+    return byte;
+  }
+  if (byte >= 0x61 && byte <= 0x7a) {
+    return upper ? byte - 0x20 : byte;
+  }
+  if (byte >= 0x7b && byte <= 0x7e) {
+    return byte;
+  }
+  throw new StockPetsciiError(
+    `asciiToPetscii: character at index ${index} (0x${byte.toString(16).padStart(2, "0")}) has no PETSCII mapping -- ` +
+      `PETSCII control codes (e.g. 0x93 clear-screen) and other unmapped bytes must be sent explicitly via ` +
+      `vice_keyboard_petscii, never through vice_keyboard_type`,
+    { index },
+  );
+}
+
+/**
+ * Converts an ASCII/Latin-1 JS string to PETSCII bytes for KEYBOARD_FEED
+ * (0x72). Refuses (never silently truncates or passes through):
+ *   - a non-string input
+ *   - an empty string
+ *   - a converted length over 255 bytes (KEYBOARD_FEED's textLen field is a
+ *     uint8) -- since this mapping is 1:1, the converted length always
+ *     equals `text.length`, so this is checked up front
+ *   - any code unit above 0xff (a non-Latin-1 character) -- never a lossy
+ *     `charCodeAt() & 0xff`
+ *   - any byte convertByte() does not map (PETSCII control codes, the
+ *     0x00-0x1f/0x7f gaps, and every byte >= 0x80 not otherwise handled)
+ */
+export function asciiToPetscii(text: string, { upper = true }: AsciiToPetsciiOptions = {}): Buffer {
+  if (typeof text !== "string") {
+    throw new StockPetsciiError(`asciiToPetscii: text must be a string, got ${typeof text}`);
+  }
+  if (text.length === 0) {
+    throw new StockPetsciiError("asciiToPetscii: text must not be empty");
+  }
+  if (text.length > 255) {
+    throw new StockPetsciiError(
+      `asciiToPetscii: converted text exceeds 255 bytes (${text.length}) -- KEYBOARD_FEED's textLen field is a uint8`,
+    );
+  }
+  const out = Buffer.alloc(text.length);
+  for (let index = 0; index < text.length; index++) {
+    const codeUnit = text.charCodeAt(index);
+    if (codeUnit > 0xff) {
+      throw new StockPetsciiError(
+        `asciiToPetscii: character at index ${index} (code point 0x${codeUnit.toString(16)}) is not a Latin-1 byte -- ` +
+          `PETSCII conversion only accepts code points 0x00-0xff`,
+        { index },
+      );
+    }
+    out[index] = convertByte(codeUnit, index, upper);
+  }
+  return out;
+}