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

package/src/c64.ts

@@ -0,0 +1,281 @@
+const ADDRESS_PATTERN = /^\$([0-9a-fA-F]{4})$/;
+
+/** Returns the value when it is a C64 address (0-$ffff). Throws RangeError otherwise. */
+function checkAddress(value: number): number {
+  if (!Number.isInteger(value) || value < 0 || value > 0xffff) {
+    throw new RangeError(`C64 address out of range: ${value}`);
+  }
+  return value;
+}
+
+export function parseC64Address(value: string): number {
+  const match = ADDRESS_PATTERN.exec(value);
+  if (match === null) {
+    throw new TypeError(`Invalid C64 address: ${value}`);
+  }
+  return checkAddress(Number.parseInt(match[1]!, 16));
+}
+
+export function formatC64Address(value: number): string {
+  return `$${checkAddress(value).toString(16).padStart(4, "0")}`;
+}
+
+/** A byte as $xx. Throws RangeError outside 0-255. */
+export function formatC64Byte(value: number): string {
+  if (!Number.isInteger(value) || value < 0 || value > 0xff) throw new RangeError(`C64 byte out of range: ${value}`);
+  return `$${value.toString(16).padStart(2, "0")}`;
+}
+
+/**
+ * The memory a PRG loads into: the 2-byte load address, then the body.
+ * Throws RangeError for a file shorter than 3 bytes or one that runs past $ffff.
+ */
+export function prgRange(prg: Uint8Array): { start: number; end: number; body: Uint8Array } {
+  if (prg.length < 3) throw new RangeError("A PRG has a 2-byte load address and at least one byte.");
+  const start = prg[0]! | (prg[1]! << 8);
+  if (start + prg.length - 2 > 0x10000) throw new RangeError("The PRG runs past $ffff.");
+  return { start, end: start + prg.length - 3, body: prg.subarray(2) };
+}
+
+/** How 6502 code refers to an address. */
+export const REFERENCE_KINDS = ["call", "jump", "read", "write", "reference"] as const;
+export type ReferenceKind = (typeof REFERENCE_KINDS)[number];
+
+/** A symbol or label name: assembler label syntax, at most 64 characters; a leading dot marks a local label. */
+export const SYMBOL_NAME = /^\.?[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+
+/** The VIC-II's 16 KiB bank base, from CIA 2 port A bits 0-1 (inverted); undriven lines read high. */
+export function vicBankBase(cia2PortA: number, cia2DdrA = 0xff): number {
+  const lines = (cia2PortA | ~cia2DdrA) & 0x03;
+  return (3 - lines) * 0x4000;
+}
+
+/** The offsets inside the VIC-II bank that $d018 selects. */
+export function d018Offsets(d018: number): { screen: number; characters: number; bitmap: number } {
+  return { screen: ((d018 >> 4) & 0x0f) * 0x400, characters: ((d018 >> 1) & 0x07) * 0x800, bitmap: (d018 & 0x08) !== 0 ? 0x2000 : 0 };
+}
+
+/**
+ * Converts text to the PETSCII bytes the C64 keyboard types after a reset
+ * (upper case/graphics mode). Letters of either case type the unshifted key,
+ * which shows as an upper-case letter. "\n" and "\r\n" type RETURN.
+ * Throws RangeError naming the first character that has no key.
+ */
+export function textToPetscii(text: string): Uint8Array {
+  const bytes: number[] = [];
+  const normalized = text.replace(/\r\n/g, "\n");
+  for (const character of normalized) {
+    const code = character.codePointAt(0)!;
+    if (character === "\n" || character === "\r") bytes.push(0x0d);
+    else if (code >= 0x61 && code <= 0x7a) bytes.push(code - 0x20);
+    else if (code >= 0x20 && code <= 0x5b) bytes.push(code);
+    else if (character === "]") bytes.push(0x5d);
+    else if (character === "£") bytes.push(0x5c);
+    else if (character === "↑" || character === "^") bytes.push(0x5e);
+    else if (character === "←") bytes.push(0x5f);
+    else throw new RangeError(`There is no C64 key for ${JSON.stringify(character)}`);
+  }
+  return Uint8Array.from(bytes);
+}
+
+/**
+ * Shows a CBM file or disk name (PETSCII bytes) as text, the way a directory
+ * listing shows it in upper case/graphics mode. Bytes $20-$5f are their
+ * characters ($5c is £, $5e is ↑, $5f is ←); every other byte is written as
+ * {$xx}, so the text converts back to the same bytes.
+ */
+export function petsciiNameToText(bytes: Uint8Array): string {
+  let text = "";
+  for (const byte of bytes) {
+    if (byte === 0x5c) text += "£";
+    else if (byte === 0x5e) text += "↑";
+    else if (byte === 0x5f) text += "←";
+    else if (byte >= 0x20 && byte <= 0x5d) text += String.fromCharCode(byte);
+    else text += `{$${byte.toString(16).padStart(2, "0")}}`;
+  }
+  return text;
+}
+
+/**
+ * The reverse of petsciiNameToText. Letters of either case are the unshifted
+ * letters ($41-$5a). Throws RangeError for text that is no name.
+ */
+export function textToPetsciiName(text: string): Uint8Array {
+  const bytes: number[] = [];
+  const escape = /^\{\$([0-9a-fA-F]{2})\}/;
+  for (let index = 0; index < text.length; ) {
+    const escaped = escape.exec(text.slice(index));
+    if (escaped !== null) {
+      bytes.push(Number.parseInt(escaped[1]!, 16));
+      index += escaped[0].length;
+      continue;
+    }
+    const character = text[index]!;
+    const code = character.charCodeAt(0);
+    if (code >= 0x61 && code <= 0x7a) bytes.push(code - 0x20);
+    else if (character === "£") bytes.push(0x5c);
+    else if (character === "↑") bytes.push(0x5e);
+    else if (character === "←") bytes.push(0x5f);
+    else if (code >= 0x20 && code <= 0x5d) bytes.push(code);
+    else throw new RangeError(`${JSON.stringify(character)} is not a name character. Write other bytes as {$xx}.`);
+    index++;
+  }
+  return Uint8Array.from(bytes);
+}
+
+// C64 BASIC V2 program text, as LOAD puts it in memory.
+
+/** BASIC refuses higher line numbers when a line is entered. */
+const MAX_LINE_NUMBER = 63999;
+
+const TOKEN = { data: 0x83, rem: 0x8f, sys: 0x9e, usr: 0xb7, plus: 0xaa, minus: 0xab, times: 0xac, divide: 0xad } as const;
+const QUOTE = 0x22;
+const COLON = 0x3a;
+
+export interface TokenizedLine {
+  number: number;
+  /** The line's bytes after the line number, without the terminating zero. */
+  tokens: Uint8Array;
+}
+
+/** A machine-code handoff in BASIC program text: SYS with a constant address, or a SYS or USR whose target needs run-time values. */
+export type BasicHandoff = { kind: "sys"; line: number; address: number } | { kind: "sys" | "usr"; line: number; computed: true };
+
+export type TokenizedProgram = { loadAddress: number; basicEnd: number; lines: TokenizedLine[] } | { reason: string };
+
+/**
+ * Splits a PRG into BASIC lines the way BASIC relinks a loaded program: each
+ * line ends at a zero byte, and a link whose high byte is zero ends the
+ * program. The stored links are not trusted.
+ */
+export function parseTokenized(program: Uint8Array): TokenizedProgram {
+  if (program.length < 4) return { reason: "The file is too short for a BASIC program." };
+  const loadAddress = program[0]! | (program[1]! << 8);
+  const lines: TokenizedLine[] = [];
+  let at = 2;
+  // File offset k (from 2 on) loads at loadAddress + k - 2.
+  for (;;) {
+    // A file that ends right after a line leaves the end marker to the zeros after it in memory;
+    // basicEnd is the address after that marker, as when the file holds it.
+    if (at === program.length && lines.length > 0) return { loadAddress, basicEnd: loadAddress + at, lines };
+    if (at + 1 >= program.length) return { reason: "The BASIC program has no end marker." };
+    if (program[at + 1] === 0) {
+      // An end marker before any line, with more bytes after it, is how machine code at a non-BASIC address often starts.
+      if (lines.length === 0 && at + 2 < program.length) return { reason: "The file holds no BASIC line before other bytes, so it is no BASIC program." };
+      return { loadAddress, basicEnd: loadAddress + at, lines };
+    }
+    if (at + 4 > program.length) return { reason: "The last BASIC line is cut off." };
+    const number = program[at + 2]! | (program[at + 3]! << 8);
+    if (number > MAX_LINE_NUMBER) return { reason: `Line number ${number} is above ${MAX_LINE_NUMBER}, so the bytes are no BASIC program.` };
+    const end = program.indexOf(0, at + 4);
+    if (end < 0) return { reason: `BASIC line ${number} has no end.` };
+    lines.push({ number, tokens: program.subarray(at + 4, end) });
+    at = end + 1;
+  }
+}
+
+/**
+ * Evaluates a SYS argument that holds only numbers, + - * / and brackets.
+ * Returns undefined for anything that needs run-time values.
+ */
+export function constantExpression(bytes: Uint8Array): number | undefined {
+  const tokens = [...bytes].filter((byte) => byte !== 0x20);
+  let at = 0;
+  const peek = () => tokens[at];
+  const isDigit = () => peek() !== undefined && peek()! >= 0x30 && peek()! <= 0x39;
+  // A number as BASIC reads it: digits and a point, then an optional E with an
+  // optional sign (token or character) and exponent digits, so 2E3 is 2000.
+  const number = (): number | undefined => {
+    let text = "";
+    while (isDigit() || peek() === 0x2e) text += String.fromCharCode(tokens[at++]!);
+    if (text === "" || text === ".") return undefined;
+    if (peek() === 0x45) {
+      at++;
+      let exponent = "";
+      if (peek() === TOKEN.minus || peek() === 0x2d) {
+        exponent = "-";
+        at++;
+      } else if (peek() === TOKEN.plus || peek() === 0x2b) at++;
+      let digits = "";
+      while (isDigit()) digits += String.fromCharCode(tokens[at++]!);
+      text += `e${exponent}${digits === "" ? "0" : digits}`;
+    }
+    return Number(text);
+  };
+  const primary = (): number | undefined => {
+    if (peek() === TOKEN.minus || peek() === TOKEN.plus) {
+      const negative = tokens[at++] === TOKEN.minus;
+      const value = primary();
+      return value === undefined ? undefined : negative ? -value : value;
+    }
+    if (peek() === 0x28) {
+      at++;
+      const value = sum();
+      if (value === undefined || tokens[at++] !== 0x29) return undefined;
+      return value;
+    }
+    return number();
+  };
+  const product = (): number | undefined => {
+    let value = primary();
+    while (value !== undefined && (peek() === TOKEN.times || peek() === TOKEN.divide)) {
+      const operator = tokens[at++];
+      const right = primary();
+      if (right === undefined) return undefined;
+      value = operator === TOKEN.times ? value * right : value / right;
+    }
+    return value;
+  };
+  const sum = (): number | undefined => {
+    let value = product();
+    while (value !== undefined && (peek() === TOKEN.plus || peek() === TOKEN.minus)) {
+      const operator = tokens[at++];
+      const right = product();
+      if (right === undefined) return undefined;
+      value = operator === TOKEN.plus ? value + right : value - right;
+    }
+    return value;
+  };
+  const value = sum();
+  if (value === undefined || !Number.isFinite(value)) return undefined;
+  // BASIC's evaluator ends the expression at the first byte that is no operator,
+  // so "SYS2073 TCS-CRUNCH!" jumps to 2073. An operator
+  // this evaluator does not handle (^, AND, OR, a comparison) needs run-time values.
+  if (at < tokens.length && BASIC_OPERATORS.has(tokens[at]!)) return undefined;
+  return value;
+}
+
+/** BASIC V2 operator tokens: + - * / ^ AND OR > = <. */
+const BASIC_OPERATORS = new Set([0xaa, 0xab, 0xac, 0xad, 0xae, 0xaf, 0xb0, 0xb1, 0xb2, 0xb3]);
+
+/** SYS and USR in program text: not in strings, REM or DATA. */
+export function findHandoffs(lines: TokenizedLine[]): BasicHandoff[] {
+  const handoffs: BasicHandoff[] = [];
+  for (const { number, tokens } of lines) {
+    let quoted = false;
+    let inData = false;
+    for (let at = 0; at < tokens.length; at++) {
+      const byte = tokens[at]!;
+      if (byte === QUOTE) quoted = !quoted;
+      if (quoted) continue;
+      if (inData) {
+        if (byte === COLON) inData = false;
+        continue;
+      }
+      if (byte === TOKEN.rem) break;
+      if (byte === TOKEN.data) inData = true;
+      else if (byte === TOKEN.usr) handoffs.push({ kind: "usr", line: number, computed: true });
+      else if (byte === TOKEN.sys) {
+        // The argument ends at the statement end or at a comma (extra SYS parameters).
+        let end = at + 1;
+        while (end < tokens.length && tokens[end] !== COLON && tokens[end] !== 0x2c) end++;
+        const value = constantExpression(tokens.subarray(at + 1, end));
+        if (value === undefined) handoffs.push({ kind: "sys", line: number, computed: true });
+        // BASIC drops the fraction; outside 0-65535 SYS stops with ILLEGAL QUANTITY and jumps nowhere.
+        else if (Math.trunc(value) >= 0 && Math.trunc(value) <= 0xffff) handoffs.push({ kind: "sys", line: number, address: Math.trunc(value) });
+        at = end - 1;
+      }
+    }
+  }
+  return handoffs;
+}

package/src/cli/ap-sdk.ts

@@ -0,0 +1,44 @@
+// Runs the AP SDK CLI of this package's own dependency as a bounded native
+// run: its own process group, a time limit, and the whole group stopped when
+// the limit ends or the CLI stops.
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { runToolOrFail, type ToolContext } from "../native/run.ts";
+import { WireFailure } from "../protocol/messages.ts";
+
+/** How long one AP SDK install, update or uninstall may take. */
+export const AP_SDK_TIMEOUT_MS = 120_000;
+
+const PLUGIN = fileURLToPath(new URL("../../distribution/plugin.ts", import.meta.url));
+
+export interface ApSdkRun {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Runs `ap-sdk <command> <plugin or id> <flags>`. Returns its exit status and
+ * what it printed. Throws WireFailure(operation-failed) with the name AP SDK
+ * when it does not start, stops on a signal, does not finish within the time
+ * limit, or the run is cancelled.
+ */
+export async function runApSdk(
+  command: "install" | "uninstall",
+  flags: readonly string[],
+  context: ToolContext,
+  options: { cli?: string; timeoutMs?: number; env?: NodeJS.ProcessEnv } = {},
+): Promise<ApSdkRun> {
+  const cli = options.cli ?? join(dirname(fileURLToPath(import.meta.resolve("@jalco/ap-sdk"))), "cli.js");
+  // execArgv keeps the TypeScript loader (tsx) for the plugin module under node_modules.
+  const argv = [process.execPath, ...process.execArgv, cli, command, command === "uninstall" ? "c64-re-tools" : PLUGIN, ...flags];
+  const run = await runToolOrFail("AP SDK", "The AP SDK run", { argv, cwd: process.cwd(), timeoutMs: options.timeoutMs ?? AP_SDK_TIMEOUT_MS }, {
+    ...context,
+    env: options.env ?? context.env,
+  });
+  // runToolOrFail refuses a run that did not start or that a signal stopped, so an exit status is here.
+  if (run.code === null) throw new WireFailure("operation-failed", "AP SDK ended without an exit status.");
+  return { code: run.code, stdout: run.stdout, stderr: run.stderr };
+}

package/src/cli/cleanup.ts

@@ -0,0 +1,194 @@
+// Tidying that AP SDK leaves to its caller:
+// - A project install must not change the home directory. AP SDK writes the
+//   Windsurf MCP declaration to ~/.codeium/windsurf/mcp_config.json even in
+//   project scope, and records it in the project manifest, so a project
+//   uninstall would also remove a declaration that a global install made.
+// - AP SDK's uninstall deletes the installed files but leaves their
+//   directories, and leaves each MCP configuration file with an empty server
+//   list. Only empty directories and files with nothing else in them go.
+
+import { existsSync, readFileSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+const PLUGIN_ID = "c64-re-tools";
+
+export type Scope = "project" | "global";
+
+export interface InstallItem {
+  harness: string;
+  kind: string;
+  name: string;
+  files: string[];
+  detail?: { mergeKey?: string; names?: string[] };
+}
+
+interface Manifest {
+  version: number;
+  plugins: Record<string, { items: InstallItem[] } & Record<string, unknown>>;
+}
+
+/** The directory that the manifest and relative item paths belong to. */
+function scopeRoot(scope: Scope, cwd = process.cwd()): string {
+  return scope === "global" ? homedir() : cwd;
+}
+
+function manifestPath(scope: Scope, cwd = process.cwd()): string {
+  return join(scopeRoot(scope, cwd), ".ap-sdk", "install-manifest.json");
+}
+
+function readManifest(path: string): Manifest | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as Manifest;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The recorded items of this plugin, for the given harnesses (all when undefined). */
+export function installedItems(scope: Scope, targets: readonly string[] | undefined, cwd = process.cwd()): InstallItem[] {
+  const items = readManifest(manifestPath(scope, cwd))?.plugins[PLUGIN_ID]?.items ?? [];
+  return targets === undefined ? items : items.filter((item) => targets.includes(item.harness));
+}
+
+/** The harnesses of a --target value; undefined means all of them. */
+export function parseTargets(value: string | undefined): string[] | undefined {
+  return value === undefined ? undefined : value.split(",").map((target) => target.trim()).filter((target) => target !== "");
+}
+
+const WINDSURF_MCP = () => join(homedir(), ".codeium", "windsurf", "mcp_config.json");
+const WINDSURF_KEY = "mcpServers";
+
+function readJson(path: string): Record<string, unknown> | undefined {
+  try {
+    const value = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** What the Windsurf configuration held before an install, to put it back after a project install. */
+export interface WindsurfBefore {
+  /** The file's bytes, or undefined when the file did not exist. */
+  bytes: Buffer | undefined;
+  hadServer: boolean;
+}
+
+export function windsurfBefore(): WindsurfBefore {
+  const path = WINDSURF_MCP();
+  const servers = readJson(path)?.[WINDSURF_KEY] as Record<string, unknown> | undefined;
+  let bytes: Buffer | undefined;
+  try {
+    bytes = readFileSync(path);
+  } catch {
+    bytes = undefined;
+  }
+  return { bytes, hadServer: servers !== undefined && PLUGIN_ID in servers };
+}
+
+/**
+ * After a project install for Windsurf: puts the home configuration back as
+ * it was, and removes the Windsurf MCP item from the project manifest.
+ * Returns a note for the user, or undefined when Windsurf was not a target.
+ */
+export function undoWindsurfProjectMcp(before: WindsurfBefore, cwd = process.cwd()): string | undefined {
+  const manifestFile = manifestPath("project", cwd);
+  const manifest = readManifest(manifestFile);
+  const entry = manifest?.plugins[PLUGIN_ID];
+  const item = entry?.items.find((candidate) => candidate.harness === "windsurf" && candidate.kind === "mcp" && candidate.files.length > 0);
+  if (manifest === undefined || entry === undefined || item === undefined) return undefined;
+
+  const path = WINDSURF_MCP();
+  if (before.bytes !== undefined) {
+    // The file existed: its bytes go back unchanged.
+    if (!existsSync(path) || !readFileSync(path).equals(before.bytes)) writeFileSync(path, before.bytes);
+  } else {
+    // The install made the file: it goes when it holds only this declaration.
+    const root = readJson(path);
+    const servers = root?.[WINDSURF_KEY] as Record<string, unknown> | undefined;
+    if (root !== undefined && servers !== undefined) {
+      delete servers[PLUGIN_ID];
+      if (isEmptyConfig(root, WINDSURF_KEY)) {
+        unlinkSync(path);
+        removeEmptyDirectories(dirname(path), homedir());
+      } else {
+        writeFileSync(path, `${JSON.stringify(root, null, 2)}\n`);
+      }
+    }
+  }
+  entry.items = entry.items.filter((candidate) => candidate !== item);
+  writeFileSync(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`);
+  return before.hadServer
+    ? "Windsurf reads MCP servers only from your home directory. Its c64-re-tools declaration from a global install stays as it is."
+    : "Windsurf reads MCP servers only from your home directory, so this project install did not declare the MCP for Windsurf. To declare it, run: c64-re-tools install --global --target windsurf";
+}
+
+/** A configuration that holds nothing but an empty server list (and perhaps a $schema). */
+function isEmptyConfig(root: Record<string, unknown>, mergeKey: string): boolean {
+  const bucket = root[mergeKey];
+  if (typeof bucket !== "object" || bucket === null || Object.keys(bucket).length > 0) return false;
+  return Object.keys(root).every((key) => key === mergeKey || key === "$schema");
+}
+
+/** True when `path` is `root` itself or inside it. */
+function isWithin(root: string, path: string): boolean {
+  const rel = relative(root, path);
+  return !isAbsolute(rel) && rel.split(sep)[0] !== "..";
+}
+
+/** Removes `directory` and its parents while they are empty, up to `stop` (never `stop` itself or anything outside it). */
+export function removeEmptyDirectories(directory: string, stop: string): void {
+  let current = resolve(directory);
+  const limit = resolve(stop);
+  while (current !== limit) {
+    if (relative(limit, current) === "" || !isWithin(limit, current)) return;
+    try {
+      rmdirSync(current);
+    } catch {
+      return; // not empty, or gone
+    }
+    current = dirname(current);
+  }
+}
+
+/**
+ * After an uninstall: deletes MCP configuration files that hold nothing but
+ * an empty server list, then the directories that the items left empty.
+ */
+export function tidyAfterUninstall(items: readonly InstallItem[], scope: Scope, cwd = process.cwd()): void {
+  const root = scopeRoot(scope, cwd);
+  const absolute = (file: string) => (isAbsolute(file) ? file : resolve(root, file));
+  for (const item of items) {
+    if (item.kind !== "mcp" || item.detail?.mergeKey === undefined) continue;
+    for (const file of item.files.map(absolute)) {
+      const config = existsSync(file) ? readJson(file) : undefined;
+      if (config !== undefined && isEmptyConfig(config, item.detail.mergeKey)) unlinkSync(file);
+    }
+  }
+  const directories = new Set<string>([dirname(manifestPath(scope, cwd))]);
+  for (const item of items) for (const file of item.files) directories.add(dirname(absolute(file)));
+  // Deepest first, so a parent is tried after its children.
+  for (const directory of [...directories].sort((a, b) => b.length - a.length)) {
+    // Each file's own home: the scope root, or the home directory for a file outside it.
+    const stop = isWithin(root, directory) ? root : homedir();
+    removeEmptyDirectories(directory, stop);
+  }
+}
+
+const ANSI = new RegExp(String.fromCharCode(27) + "\\[[0-9;]*m", "g");
+
+/** AP SDK's report without its Windsurf MCP line and that line's detail, for when the CLI undid that item. */
+export function withoutWindsurfMcp(output: string): string {
+  const lines = output.split("\n");
+  const kept: string[] = [];
+  for (let index = 0; index < lines.length; index++) {
+    if (/^\s*\S+\s+windsurf\s+mcp\s/.test(lines[index]!.replace(ANSI, ""))) {
+      if (lines[index + 1]?.replace(ANSI, "").trim().startsWith("\u21b3")) index++;
+      continue;
+    }
+    kept.push(lines[index]!);
+  }
+  return kept.join("\n");
+}

package/src/cli/main.ts

@@ -0,0 +1,122 @@
+#!/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 "../../distribution/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.
+  for (const line of toolLines("Tools here:", await localToolStatus(localToolContext()))) console.log(line);
+  for (const line of await hostStatusLines()) console.log(line);
+  return 0;
+}
+
+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,34 @@
+// 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 type { ToolStatus } from "../protocol/tools.ts";
+
+/** One line per tool under `heading`: its version, or why it does not run. */
+export function toolLines(heading: string, tools: readonly ToolStatus[]): string[] {
+  return [
+    heading,
+    ...tools.map((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}`,
+    ),
+  ];
+}
+
+/**
+ * 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.
+ */
+export async function hostStatusLines(options: ToolCallOptions = {}): Promise<string[]> {
+  let tools: ToolStatus[];
+  try {
+    tools = await hostTools(options);
+  } catch (error) {
+    return [`Host Runtime: not reachable. ${(error as Error).message}`];
+  }
+  return ["Host Runtime: reachable", ...toolLines("Tools on the host:", tools)];
+}