@henols/c64-re-tools 2.0.0-rc.2 → 2.0.0-rc.3

package/README.md

@@ -17,73 +17,27 @@ run ACME, DXA and Ghidra themselves, and keep project knowledge local in
 The design is in [`docs/redesign/`](docs/redesign/README.md), and
 [`docs/plan.md`](docs/plan.md) tracks the implementation.
 
-## Install and start
+## Install
 
-Requirements:
+You need Node.js 24 or newer, and VICE 3.9 or later (`x64sc`, `c1541`, `petcat`) with its ROM files. ACME, DXA and Ghidra are needed only for the skills that use them.
 
-- Node.js 24 or newer with npx.
-- On the machine with VICE: VICE 3.9 or later (`x64sc`, `c1541`, `petcat`) with its ROM files.
-- Where the agent runs: ACME, DXA and Ghidra, for the skills that use them.
-
-Everything runs through npx. Nothing is installed globally.
-
-### Release or prerelease
-
-| Channel | Version |
-| --- | --- |
-| `latest` | The current release. |
-| `next` | The current prerelease, for example `2.0.0-rc.1`. |
-
-Until 2.0.0 is released, `latest` is the old 1.1.0. Use `next` until then. In the commands below, replace `<channel>` with `latest` or `next`. Use the same channel on both machines.
-
-### On one machine
-
-Start the Host Runtime in its own terminal. Ctrl+C stops it and every emulator:
+Start the Host Runtime and leave it running:
 
 ```
-npx -y --package=@henols/c64-re-tools@<channel> c64-re-tools-host
+npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host
 ```
 
-Install into the project, check it, and start the agent:
+Install into your project and start the agent:
 
 ```
 cd my-c64-project
-npx -y @henols/c64-re-tools@<channel> install --target claude
-npx -y @henols/c64-re-tools@<channel> status
+npx -y @henols/c64-re-tools@latest install --target claude
 claude
 ```
 
-### In a dev container
-
-On the host, start the Host Runtime on the container bridge with a shared secret:
+`npx -y @henols/c64-re-tools@latest status` shows what works.
 
-```
-export C64RT_HOST_TOKEN=$(openssl rand -hex 16)
-npx -y --package=@henols/c64-re-tools@<channel> c64-re-tools-host --listen 172.17.0.1
-```
-
-In the container, set the same `C64RT_HOST_TOKEN`, then:
-
-```
-npx -y @henols/c64-re-tools@<channel> install --target claude
-npx -y @henols/c64-re-tools@<channel> status
-claude
-```
-
-The container reaches the host as `host.docker.internal`. `status` must show the Host Runtime as reachable.
-
-### Update and remove
-
-```
-npx -y @henols/c64-re-tools@<channel> update      # the newest skills into the project
-npx -y @henols/c64-re-tools@<channel> uninstall
-```
-
-Restart the Host Runtime after a new release. `--global` installs into your home directory.
-
-### Debugging
-
-See [docs/debugging.md](docs/debugging.md) for the trace and the field test.
+Until 2.0.0 is released, `@latest` is the old 1.1.0. Use the prerelease instead. For the prerelease, a dev container and debugging, see [docs/debug-install.md](docs/debug-install.md).
 
 ### Settings
 
@@ -94,9 +48,8 @@ See [docs/debugging.md](docs/debugging.md) for the trace and the field test.
 | `C64RT_ACME`, `C64RT_DXA` | skills, CLI | Full path of the tool when it is not on `PATH`. |
 | `C64RT_GHIDRA` | skills, CLI | The Ghidra installation directory, when `analyzeHeadless` is not on `PATH`. |
 | `C64RT_HOST` | MCP, skills, CLI | `host:port` of the Host Runtime when it is not on 127.0.0.1, `host.docker.internal` or `host.containers.internal` at 6464. |
-| `C64RT_HOST_TOKEN` | host, MCP, skills, CLI | The shared secret for a Host Runtime that listens beyond loopback. |
 | `C64RT_VIDEO` | MCP | `pal` (default) or `ntsc`, fixed for the life of the MCP process. |
-| `C64RT_TRACE` | host, MCP, skills, CLI | A directory for a trace of what the programs do, for a person who debugs a run. See [docs/debugging.md](docs/debugging.md). Nothing of the trace reaches the agent. |
+| `C64RT_TRACE` | host, MCP, skills, CLI | A directory for a trace of what the programs do, for a person who debugs a run. See [docs/debug-install.md](docs/debug-install.md). Nothing of the trace reaches the agent. |
 
 Ghidra runs with its own settings directory for each request. The toolkit
 brings its own NMOS 6510 language (all 256 opcodes); your Ghidra installation
@@ -104,6 +57,8 @@ and settings stay unchanged.
 
 ## Use it with an agent
 
+## Use it with an agent
+
 1. Install for your harness: `--target claude`, `codex`, `pi`, `opencode`, `gemini`, `copilot`, `cursor` or `windsurf`. Without `--target`, `install` installs for all of them.
 2. Start the Host Runtime and leave it running.
 3. Start the harness in the project, for example `claude` or `codex`, or open the project in Cursor or Windsurf. The harness starts the MCP server and finds the skills by itself.
@@ -190,14 +145,7 @@ C64RT_LIVE_VICE=/usr/bin/x64sc C64RT_GHIDRA=/opt/ghidra pnpm test
 
 ACME, DXA, c1541 and petcat tests run when the tools are on `PATH`.
 
-To release, push a tag on a commit of `main`. The tag gives the version:
-
-```
-git tag v2.0.0-rc.2 && git push origin v2.0.0-rc.2   # a prerelease, to npm next
-git tag v2.0.0      && git push origin v2.0.0        # a release, to npm latest
-```
-
-CI checks and tests the tagged commit, publishes it to npm and makes a GitHub Release. The repository keeps the version `0.0.0-development`.
+To release, push a tag. See [docs/releasing.md](docs/releasing.md).
 
 ## Layout
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "2.0.0-rc.2",
+  "version": "2.0.0-rc.3",
   "description": "Agent-friendly Commodore 64 engineering toolkit for reverse engineering, debugging, development and testing.",
   "license": "MIT",
   "author": "Henrik Olsson",

package/src/host/main.ts

@@ -5,7 +5,7 @@ import { parseArgs } from "node:util";
 import { DEFAULT_HOST_PORT } from "../protocol/messages.ts";
 import { ProcessSupervisor } from "../native/processes.ts";
 import { startTrace, trace } from "../trace.ts";
-import { isLoopback, ListenError, parsePort, startHostServer, stopSignal } from "./server.ts";
+import { ListenError, parsePort, startHostServer, stopSignal } from "./server.ts";
 import { createToolDispatcher } from "./tools/index.ts";
 import { checkViceStarts, findVice } from "./vice/process.ts";
 import { viceSessionFactory } from "./vice/session.ts";
@@ -13,22 +13,19 @@ import { viceSessionFactory } from "./vice/session.ts";
 const HELP = `c64-re-tools-host
 
 Usage:
-  npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host [--port <port>] [--listen <address> ...]
+  npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host [--port <port>]
   c64-re-tools-host --help
 
 Runs the c64-re-tools Host Runtime in the foreground. It first starts VICE
 once (x64sc on PATH, or C64RT_VICE) and does not start if VICE cannot run.
-It listens on 127.0.0.1:${DEFAULT_HOST_PORT}, starts one VICE emulator for each
+It listens on port ${DEFAULT_HOST_PORT} on every address, so a dev container
+reaches it as host.docker.internal. It starts one VICE emulator for each
 connected c64-re-tools-mcp process, and runs the tools that come with VICE
 (c1541, petcat) for skill scripts. Stop it with Ctrl+C; that stops every
 emulator and tool it started.
 
 Options:
   --port <port>       Listen on this port instead (0 picks a free port).
-  --listen <address>  Also listen on this address, on the same port, for
-                      example the container bridge (172.17.0.1). An address
-                      that is not loopback needs C64RT_HOST_TOKEN: set it to
-                      the same secret for this program and for the clients.
   --help              Show this help.`;
 
 function log(line: string): void {
@@ -37,9 +34,9 @@ function log(line: string): void {
 }
 
 async function main(): Promise<number> {
-  let values: { help?: boolean; port?: string; listen?: string[] };
+  let values: { help?: boolean; port?: string };
   try {
-    ({ values } = parseArgs({ options: { help: { type: "boolean" }, port: { type: "string" }, listen: { type: "string", multiple: true } }, strict: true }));
+    ({ values } = parseArgs({ options: { help: { type: "boolean" }, port: { type: "string" } }, strict: true }));
   } catch (error) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n\n${HELP}\n`);
     return 2;
@@ -56,13 +53,6 @@ async function main(): Promise<number> {
     return 2;
   }
 
-  const extraHosts = values.listen ?? [];
-  const token = process.env.C64RT_HOST_TOKEN;
-  if (extraHosts.some((address) => !isLoopback(address)) && (token === undefined || token.length < 16)) {
-    process.stderr.write("--listen with an address that is not loopback needs C64RT_HOST_TOKEN with at least 16 characters, so that only your clients can connect.\n");
-    return 2;
-  }
-
   // Without an emulator the runtime is useless: refuse to start, by name and with the remedy.
   try {
     findVice(process.env);
@@ -90,9 +80,8 @@ async function main(): Promise<number> {
   let server;
   try {
     server = await startHostServer({
+      host: "0.0.0.0",
       port,
-      extraHosts,
-      ...(token === undefined || token === "" ? {} : { token }),
       log,
       createViceSession: viceSessionFactory({ supervisor, log }),
       tools: createToolDispatcher({ supervisor, log }),
@@ -102,15 +91,11 @@ async function main(): Promise<number> {
       process.stderr.write(`Port ${error.port} on ${error.address} is in use. Is another c64-re-tools-host running?\n`);
       return 1;
     }
-    if (error instanceof ListenError && error.code === "EADDRNOTAVAIL") {
-      process.stderr.write(`The address ${error.address} in --listen does not belong to this machine.\n`);
-      return 1;
-    }
     throw error;
   }
-  const addresses = [server.host, ...extraHosts].map((address) => `${address}:${server.port}`);
-  process.stdout.write(`c64-re-tools-host listening on ${addresses.join(", ")}\n`);
-  trace().event("host.listening", { addresses });
+  const address = `${server.host}:${server.port}`;
+  process.stdout.write(`c64-re-tools-host listening on ${address}\n`);
+  trace().event("host.listening", { addresses: [address] });
 
   trace().event("host.stop", { signal: await stopSignal(log) });
   await server.close();

package/src/host/server.ts

@@ -1,4 +1,3 @@
-import { createHash, timingSafeEqual } from "node:crypto";
 import { createServer, type Server, type Socket } from "node:net";
 
 import { encodeFrame, MessageReader } from "../protocol/framing.ts";
@@ -37,16 +36,8 @@ export interface HostServerOptions {
   createViceSession: ViceSessionFactory;
   /** Native-tool requests on "tool" connections; without it they are refused. */
   tools?: ToolDispatcher;
-  /** Defaults to 127.0.0.1. More addresses listen on the same port, for example a container bridge. */
+  /** Defaults to 127.0.0.1; 0.0.0.0 listens on every address, so a container reaches it too. */
   host?: string;
-  /** Extra addresses to listen on, on the same port as `host`. */
-  extraHosts?: string[];
-  /**
-   * The shared secret. A connection that arrives on an address that is
-   * not loopback must send it in its hello; without a token such a
-   * connection is refused.
-   */
-  token?: string;
   /** 0 picks a free port. */
   port: number;
   /** How long a new connection may stay silent before it must send hello. */
@@ -67,10 +58,6 @@ const DEFAULT_HANDSHAKE_TIMEOUT_MS = 10_000;
 /** How long a refused client may keep its side of the connection open after the host has ended its side. */
 const REFUSED_CLOSE_MS = 1_000;
 
-function digest(text: string): Buffer {
-  return createHash("sha256").update(text, "utf8").digest();
-}
-
 /** A caught value for the log, with its stack when it has one. */
 function describe(error: unknown): string {
   return error instanceof Error ? (error.stack ?? error.message) : String(error);
@@ -95,18 +82,6 @@ class Connection {
   #isTool = false;
   readonly #reader = new MessageReader();
 
-  /** A connection on a loopback address needs no token; any other needs the host's token. */
-  #checkToken(token: string | undefined): WireError | undefined {
-    if (isLoopback(this.#socket.localAddress ?? "")) return undefined;
-    const expected = this.#options.token;
-    // Equal-length digests: the comparison takes the same time for any token, also one with multibyte characters.
-    const matches = expected !== undefined && token !== undefined && timingSafeEqual(digest(token), digest(expected));
-    if (matches) return undefined;
-    return {
-      code: "installation-incomplete",
-      message: "The c64-re-tools host runtime refused this client: a connection from outside the host needs C64RT_HOST_TOKEN with the same value on both sides.",
-    };
-  }
   readonly #socket: Socket;
   readonly #options: HostServerOptions;
   readonly #log: (line: string) => void;
@@ -191,7 +166,7 @@ class Connection {
     if (this.#state === "handshake") {
       if (message.type !== "hello") throw new ProtocolError("first message is not hello");
       clearTimeout(this.#handshakeTimer);
-      const mismatch = checkHello(message) ?? this.#checkToken(message.token);
+      const mismatch = checkHello(message);
       if (mismatch !== undefined) {
         this.#log(`refusing a client: ${mismatch.message}`);
         trace().event("connection.refused", { connection: this.#id, role: message.role, ...mismatch });
@@ -308,12 +283,6 @@ class Connection {
   }
 }
 
-/** True for 127.0.0.0/8 and ::1, also in their IPv4-mapped IPv6 form. */
-export function isLoopback(address: string): boolean {
-  const plain = address.startsWith("::ffff:") ? address.slice(7) : address;
-  return plain === "::1" || /^127\.\d+\.\d+\.\d+$/.test(plain);
-}
-
 /** A port as the user gives it: decimal digits only, 0 to 65535. Anything else gives undefined. */
 export function parsePort(text: string): number | undefined {
   if (!/^\d{1,5}$/.test(text)) return undefined;
@@ -386,8 +355,6 @@ export async function startHostServer(options: HostServerOptions): Promise<HostS
   let port: number;
   try {
     port = await listen(host, options.port);
-    // The extra addresses share the port, so one endpoint setting reaches every address.
-    for (const extra of options.extraHosts ?? []) await listen(extra, port);
   } catch (error) {
     await Promise.all(servers.map((server) => new Promise<void>((resolve) => server.close(() => resolve()))));
     throw error;

package/src/host-client/connect.ts

@@ -150,9 +150,6 @@ export class HostConnection {
     const connection = new HostConnection(socket);
     const hello: Hello = { type: "hello", protocol: HOST_PROTOCOL_ID, version: HOST_PROTOCOL_VERSION, role: options.role };
     if (options.videoStandard !== undefined) hello.videoStandard = options.videoStandard;
-    // A host that listens beyond loopback checks this shared secret.
-    const token = (options.env ?? process.env).C64RT_HOST_TOKEN;
-    if (token !== undefined && token !== "") hello.token = token;
 
     const stop = () => void connection.close();
     signal?.addEventListener("abort", stop, { once: true });

package/src/mcp/main.ts

@@ -28,10 +28,7 @@ the agent, through npx with the latest version.
 Environment:
   C64RT_VIDEO  pal (default) or ntsc; fixed for the life of the process.
   C64RT_HOST   host:port of the Host Runtime when it is not on 127.0.0.1:6464,
-               host.docker.internal:6464 or host.containers.internal:6464.
-  C64RT_HOST_TOKEN
-               the shared secret of a Host Runtime that listens on an address
-               that is not loopback. Use the same value as the Host Runtime.`;
+               host.docker.internal:6464 or host.containers.internal:6464.`;
 
 function log(line: string): void {
   process.stderr.write(`c64-re-tools-mcp: ${line}\n`);

package/src/protocol/messages.ts

@@ -54,13 +54,8 @@ export interface Hello {
   role: Role;
   /** vice-session only; fixed for the session. */
   videoStandard?: VideoStandard;
-  /** The shared secret (C64RT_HOST_TOKEN) for a host that listens beyond loopback. */
-  token?: string;
 }
 
-/** Longest accepted shared token. */
-const MAX_TOKEN_LENGTH = 256;
-
 export interface Ready {
   type: "ready";
 }
@@ -166,12 +161,8 @@ export function parseClientMessage(value: unknown): ReceivedClientMessage {
     if (value.videoStandard !== undefined && !isOneOf(VIDEO_STANDARDS, value.videoStandard)) {
       throw new ProtocolError("hello has an unknown video standard");
     }
-    if (value.token !== undefined && (typeof value.token !== "string" || value.token.length > MAX_TOKEN_LENGTH)) {
-      throw new ProtocolError("hello has a malformed token");
-    }
     const hello: Hello = { type: "hello", protocol: value.protocol, version: value.version, role: value.role };
     if (value.videoStandard !== undefined) hello.videoStandard = value.videoStandard;
-    if (value.token !== undefined) hello.token = value.token;
     return hello;
   }
   if (value.type === "request") {