@henols/c64-re-tools 1.1.0 → 2.0.0-rc.11

package/src/cli/main.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env tsx
+// The human CLI: installs the skills and the VICE MCP
+// declaration into agent harnesses through AP SDK, and reports status. It is
+// thin: AP SDK does the harness-specific work.
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+
+import { PACKAGE } from "../package.ts";
+import { localToolContext } from "../native/local.ts";
+import { localToolStatus } from "../native/status.ts";
+import { WireFailure } from "../protocol/messages.ts";
+import { startTrace } from "../trace.ts";
+import { runApSdk } from "./ap-sdk.ts";
+import { installedItems, parseTargets, tidyAfterUninstall, undoWindsurfProjectMcp, windsurfBefore, withoutWindsurfMcp, type Scope } from "./cleanup.ts";
+import { hostStatusLines, toolLines } from "./status.ts";
+
+const HELP = `c64-re-tools: Commodore 64 reverse engineering and development
+
+Usage:
+  c64-re-tools install   [--target <harnesses>] [--global]   install the skills and the VICE MCP
+  c64-re-tools update    [--target <harnesses>] [--global]   install this version over an earlier one
+  c64-re-tools uninstall [--target <harnesses>] [--global]   remove them
+  c64-re-tools status                                        version, package, tools and the Host Runtime
+  c64-re-tools --help
+
+Harnesses: claude, codex, pi, opencode, gemini, copilot, cursor, windsurf
+(comma-separated; default: all). Without --global the files go into the
+current project; with --global into your home directory.
+
+Run it in the project: npx -y ${PACKAGE.name}@${PACKAGE.tag} install. The VICE
+MCP declaration starts the latest c64-re-tools-mcp through npx. The Host
+Runtime runs on the machine with VICE: start it there with
+npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-host.
+It runs VICE and the tools that come with it (c1541, petcat). The skill
+scripts run ACME, DXA and Ghidra themselves, on the machine of the agent.`;
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** Runs the AP SDK CLI. Writes its error output to stderr and returns its exit status and its report. */
+async function apSdk(command: "install" | "uninstall", flags: readonly string[]): Promise<{ code: number; output: string }> {
+  // The report is printed after the CLI's own tidying, so the colours stay when this is a terminal.
+  const run = await runApSdk(command, flags, localToolContext(), process.stdout.isTTY ? { env: { ...process.env, FORCE_COLOR: "1" } } : {});
+  process.stderr.write(run.stderr);
+  return { code: run.code, output: run.stdout };
+}
+
+async function status(): Promise<number> {
+  console.log(`c64-re-tools ${PACKAGE.version}`);
+  console.log(`Package: ${join(here, "..", "..")}`);
+  console.log(`Node: ${process.version} (${process.execPath})`);
+  // The skill scripts run these tools here, on this machine.
+  const local = await localToolStatus(localToolContext());
+  for (const line of toolLines("Tools here:", local)) console.log(line);
+  const host = await hostStatusLines();
+  for (const line of host.lines) console.log(line);
+  // A script or a CI check can tell a ready setup from a broken one.
+  return host.ready && local.every((tool) => tool.runs) ? 0 : 1;
+}
+
+async function main(argv: string[]): Promise<number> {
+  startTrace("cli", { warn: (line) => console.error(line) });
+  const { values, positionals } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: true,
+    options: { target: { type: "string", short: "t" }, global: { type: "boolean", short: "g" }, help: { type: "boolean", short: "h" } },
+  });
+  const [command, ...rest] = positionals;
+  if (values.help || command === undefined) {
+    console.log(HELP);
+    return 0;
+  }
+  if (rest.length > 0) {
+    console.error(`Too many arguments.\n\n${HELP}`);
+    return 2;
+  }
+  const flags = [...(values.target === undefined ? [] : ["--target", values.target]), ...(values.global ? ["--global"] : [])];
+  const scope: Scope = values.global ? "global" : "project";
+  const targets = parseTargets(values.target);
+  switch (command) {
+    case "install":
+    case "update": {
+      const before = windsurfBefore();
+      const { code, output } = await apSdk("install", flags);
+      // A project install leaves the home directory as it was.
+      const note = scope === "project" && (targets === undefined || targets.includes("windsurf")) ? undoWindsurfProjectMcp(before) : undefined;
+      process.stdout.write(note === undefined ? output : withoutWindsurfMcp(output));
+      if (note !== undefined) console.log(`  ${note}\n`);
+      return code;
+    }
+    case "uninstall": {
+      const items = installedItems(scope, targets);
+      const { code, output } = await apSdk("uninstall", flags);
+      process.stdout.write(output);
+      if (code === 0) tidyAfterUninstall(items, scope);
+      return code;
+    }
+    case "status":
+      if (flags.length > 0) {
+        console.error(`status takes no --target or --global.\n\n${HELP}`);
+        return 2;
+      }
+      return status();
+    default:
+      console.error(`Unknown command ${command}.\n\n${HELP}`);
+      return 2;
+  }
+}
+
+try {
+  process.exitCode = await main(process.argv.slice(2));
+} catch (error) {
+  if ((error as NodeJS.ErrnoException).code?.startsWith("ERR_PARSE_ARGS")) {
+    console.error(`${(error as Error).message}\n\n${HELP}`);
+    process.exitCode = 2;
+  } else if (error instanceof WireFailure) {
+    // A refusal by name, for example AP SDK that did not finish in time.
+    console.error(error.message);
+    process.exitCode = 1;
+  } else {
+    throw error;
+  }
+}

package/src/cli/status.ts

@@ -0,0 +1,61 @@
+// The status report of the CLI: the tools on this machine and the Host
+// Runtime with its tools.
+
+import { hostTools, type ToolCallOptions } from "../host-client/tools.ts";
+import { viceVersionOf } from "../native/discover.ts";
+import { PACKAGE } from "../package.ts";
+import { STOP_AND_ASK } from "../protocol/messages.ts";
+import type { HostInfo, ToolStatus } from "../protocol/tools.ts";
+
+/** One line per tool under `heading`: its version, or why it does not run; then each known flaw of it. */
+export function toolLines(heading: string, tools: readonly ToolStatus[]): string[] {
+  return [
+    heading,
+    ...tools.flatMap((tool) => [
+      tool.runs
+        ? `  ${tool.name}: ${tool.version} (${tool.path})`
+        : tool.found
+          ? `  ${tool.name}: found at ${tool.path} but it does not run. ${tool.problem}`
+          : `  ${tool.name}: missing. ${tool.problem}`,
+      ...(tool.flaws ?? []).map((flaw) => `    Known flaw: ${flaw}`),
+    ]),
+  ];
+}
+
+/**
+ * Whether the Host Runtime answers, and the tools it has. VICE and its tools
+ * live on the host; it finds and runs each one. One request shows both that
+ * the host answers and what it has. `ready` is true when the host answers and
+ * every tool on it runs.
+ */
+export async function hostStatusLines(options: ToolCallOptions = {}): Promise<{ lines: string[]; ready: boolean }> {
+  let host: HostInfo;
+  let tools: ToolStatus[];
+  try {
+    ({ host, tools } = await hostTools(options));
+  } catch (error) {
+    // status is read by a person: the instruction for an agent (D37) stays out.
+    return { lines: [`Host Runtime: not reachable. ${(error as Error).message.replace(` ${STOP_AND_ASK}`, "")}`], ready: false };
+  }
+  const mixed = mixedViceBuilds(tools);
+  return {
+    lines: [
+      `Host Runtime: reachable, c64-re-tools ${host.version} on ${host.platform} ${host.release} (${host.arch})`,
+      ...(host.version === PACKAGE.version ? [] : [`  Warning: the Host Runtime is c64-re-tools ${host.version} and this is ${PACKAGE.version}. Start the host again so that both are the same version.`]),
+      ...toolLines("Tools on the host:", tools),
+      ...(mixed === undefined ? [] : [`  Warning: ${mixed}`]),
+    ],
+    ready: tools.every((tool) => tool.runs),
+  };
+}
+
+/** A warning when x64sc, c1541 and petcat that run come from different VICE versions or builds. */
+export function mixedViceBuilds(tools: readonly ToolStatus[]): string | undefined {
+  const running = tools.filter((tool) => tool.runs && tool.version !== undefined);
+  const builds = running.map((tool) => {
+    const version = viceVersionOf(tool.version!);
+    return version === undefined ? tool.version! : `VICE ${version.major}.${version.minor}${version.revision === undefined ? "" : ` SVN r${version.revision}`}`;
+  });
+  if (new Set(builds).size <= 1) return undefined;
+  return `the VICE tools come from different VICE builds: ${running.map((tool) => `${tool.version} (${tool.path})`).join(", ")}. Put x64sc, c1541 and petcat of one VICE first on PATH, or set C64RT_VICE, C64RT_C1541 and C64RT_PETCAT.`;
+}

package/src/host/main.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env tsx
+
+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 { ListenError, parsePort, startHostServer, stopSignal } from "./server.ts";
+import { viceFlaws, type ViceVersion } from "../native/discover.ts";
+import { createToolDispatcher } from "./tools/index.ts";
+import { checkViceStarts, findVice } from "./vice/process.ts";
+import { viceSessionFactory } from "./vice/session.ts";
+import { PACKAGE } from "../package.ts";
+
+const HELP = `c64-re-tools-host
+
+Usage:
+  npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-host [--port <port>] [--log-console] [--log-dir <directory>]
+  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 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).
+  --log-console            Also print each request with its result, and each run
+                           of c1541 or petcat, to the console.
+  --log-dir <directory>    Write the same events as JSON lines to a file in this
+                           directory, with a copy of each VICE log.
+  --help                   Show this help.
+
+The host always logs its start and stop, connections, failures, and each call
+from a skill script (c1541, petcat) with its outcome. --log-console adds the
+calls of the MCP server and the tool runs. C64RT_TRACE does not apply to the host.`;
+
+function log(line: string): void {
+  process.stderr.write(`c64-re-tools-host: ${line}\n`);
+  trace().log(line);
+}
+
+async function main(): Promise<number> {
+  let values: { help?: boolean; port?: string; "log-console"?: boolean; "log-dir"?: string };
+  try {
+    ({ values } = parseArgs({
+      options: { help: { type: "boolean" }, port: { type: "string" }, "log-console": { type: "boolean" }, "log-dir": { type: "string" } },
+      strict: true,
+    }));
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n\n${HELP}\n`);
+    return 2;
+  }
+  if (values.help) {
+    process.stdout.write(`${HELP}\n`);
+    return 0;
+  }
+  const logDir = values["log-dir"];
+  if (logDir === "") {
+    process.stderr.write("--log-dir needs a directory.\n");
+    return 2;
+  }
+  startTrace("host", {
+    target: {
+      ...(logDir === undefined ? {} : { dir: { path: logDir, given: `--log-dir ${logDir}` } }),
+      ...(values["log-console"] ? { echo: (line: string) => process.stderr.write(`c64-re-tools-host: ${line}\n`) } : {}),
+    },
+    warn: log,
+  });
+
+  const port = values.port === undefined ? DEFAULT_HOST_PORT : parsePort(values.port);
+  if (port === undefined) {
+    process.stderr.write(`--port must be a number from 0 to 65535, written with digits only. You gave "${values.port}".\n`);
+    return 2;
+  }
+
+  // Without an emulator the runtime is useless: refuse to start, by name and with the remedy.
+  try {
+    findVice(process.env);
+  } catch (error) {
+    process.stderr.write(`${(error as Error).message}\n`);
+    return 1;
+  }
+
+  // Every emulator and tool is started through this one supervisor; however
+  // this process ends, the exit guard takes their process groups down with it,
+  // and the watchdog does the same if this process is killed.
+  const supervisor = new ProcessSupervisor();
+  supervisor.startWatchdog("host");
+
+  // Finding x64sc is not enough: VICE without its ROM files exits at once.
+  let vice: ViceVersion;
+  try {
+    vice = await checkViceStarts({ supervisor });
+  } catch (error) {
+    process.stderr.write(`${(error as Error).message}\n`);
+    await supervisor.stopAll();
+    return 1;
+  }
+  log(`VICE ${vice.major}.${vice.minor}${vice.revision === undefined ? "" : ` r${vice.revision}`} starts`);
+  const flaws = viceFlaws(vice);
+  // A known VICE flaw is named, not worked around (D56).
+  for (const flaw of flaws) log(`Known VICE flaw: ${flaw}`);
+
+  let server;
+  try {
+    server = await startHostServer({
+      host: "0.0.0.0",
+      port,
+      log,
+      createViceSession: viceSessionFactory({ supervisor, log, flaws }),
+      tools: createToolDispatcher({ supervisor, log, vice }),
+    });
+  } catch (error) {
+    if (error instanceof ListenError && error.code === "EADDRINUSE") {
+      process.stderr.write(`Port ${error.port} on ${error.address} is in use. Is another c64-re-tools-host running?\n`);
+      return 1;
+    }
+    throw error;
+  }
+  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();
+  await supervisor.stopAll();
+  return 0;
+}
+
+process.exitCode = await main();