@henols/c64-re-tools 2.0.0-rc.8 → 2.0.0

package/src/mcp/tools/video.ts

@@ -3,10 +3,10 @@
 
 import { z } from "zod";
 
-import { formatC64Address } from "../../c64.ts";
+import { formatC64Address, formatSprite, formatVicii } from "../../c64.ts";
 import { WireFailure } from "../../protocol/messages.ts";
 import { CIA_SELECTIONS, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_OBSERVE_BYTES, MAX_OBSERVE_RANGES, SPACES, VICII_MODES, type ObserveParams } from "../../protocol/vice.ts";
-import { OutInput, writeOut, WrittenOutput } from "../output.ts";
+import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
 import { AddressInput, AddressOutput, Byte, defineTool, HexData, MemoryViewInput, requireFields, SpaceInput, ToolOutput, TransientName } from "../server.ts";
 
 const Color = z.number().int().min(0).max(15);
@@ -31,8 +31,7 @@ export const c64Vicii = defineTool({
   }),
   readOnly: true,
   async run(_input, session) {
-    const state = await session.vicii();
-    return { ...state, screenAddress: formatC64Address(state.screenAddress), graphicsAddress: formatC64Address(state.graphicsAddress) };
+    return formatVicii(await session.vicii());
   },
 });
 
@@ -62,7 +61,7 @@ export const c64Sprite = defineTool({
   readOnly: true,
   async run(input, session) {
     const result = await session.sprites(input.sprites ?? []);
-    return { sprites: result.sprites.map((sprite) => ({ ...sprite, dataAddress: formatC64Address(sprite.dataAddress) })) };
+    return { sprites: result.sprites.map(formatSprite) };
   },
 });
 
@@ -150,6 +149,7 @@ export const c64Screen = defineTool({
       mask: z.array(Rectangle).max(MAX_MASK_RECTANGLES).optional().describe("compare only: rectangles to ignore, in frame pixels"),
       includeDiff: z.boolean().optional().describe("compare only: also return a difference image"),
       out: OutInput.optional(),
+      project: ProjectInput.optional().describe("capture and compare with out only: the project folder, relative to the folder where the agent started. Give it when that folder is not in a project and has projects below it"),
     })
     .strict(),
   outputSchema: z.object({
@@ -169,21 +169,21 @@ export const c64Screen = defineTool({
   async run(input, session) {
     const { action, ...fields } = input;
     if (action === "capture") {
-      requireFields(action, fields, ["baseline", "out"]);
+      requireFields(action, fields, fields.out === undefined ? ["baseline"] : ["baseline", "out", "project"]);
       const shot = await session.screenCapture(fields.baseline);
       const result = { width: shot.width, height: shot.height, ...(shot.baseline === undefined ? {} : { baseline: shot.baseline }) };
-      if (fields.out !== undefined) return { ...result, ...writeOut(fields.out, Buffer.from(shot.png, "base64")) };
+      if (fields.out !== undefined) return { ...result, ...writeOut(fields.out, Buffer.from(shot.png, "base64"), fields.project) };
       return new ToolOutput(result, [{ type: "image", data: shot.png, mimeType: "image/png" }]);
     }
     if (action === "compare") {
-      requireFields(action, fields, ["baseline", "maxMismatchRatio", "mask", "includeDiff", "out"], ["baseline"]);
+      requireFields(action, fields, ["baseline", "maxMismatchRatio", "mask", "includeDiff", ...(fields.out === undefined ? [] : ["out", "project"])], ["baseline"]);
       const { diffPng, ...result } = await session.screenCompare({
         baseline: fields.baseline!,
         maxMismatchRatio: fields.maxMismatchRatio ?? 0,
         mask: fields.mask ?? [],
         includeDiff: (fields.includeDiff ?? false) || fields.out !== undefined,
       });
-      if (fields.out !== undefined && diffPng !== undefined) return { ...result, ...writeOut(fields.out, Buffer.from(diffPng, "base64")) };
+      if (fields.out !== undefined && diffPng !== undefined) return { ...result, ...writeOut(fields.out, Buffer.from(diffPng, "base64"), fields.project) };
       return diffPng === undefined ? result : new ToolOutput(result, [{ type: "image", data: diffPng, mimeType: "image/png" }]);
     }
     if (action === "list") {

package/src/native/discover.ts

@@ -7,7 +7,7 @@ import { isAbsolute, join, posix, win32 } from "node:path";
 
 import { WireFailure } from "../protocol/messages.ts";
 
-/** Where the user finds the install steps of the native tools for each system (D38). */
+/** Where the user finds the install steps of the native tools for each system. */
 export const INSTALL_STEPS = "Steps for each system: https://github.com/henols/c64-re-tools/blob/main/docs/install-tools.md";
 
 export interface ToolSpec {
@@ -84,7 +84,7 @@ export function viceVersionOf(text: string): ViceVersion | undefined {
 }
 
 /**
- * Known flaws of VICE versions that c64-re-tools still runs on (D56). A flaw
+ * Known flaws of VICE versions that c64-re-tools still runs on. A flaw
  * is not worked around: it is named with the VICE version that fixes it.
  * `upTo` is the last flawed major.minor; `fixedRevision` the first SVN
  * revision with the fix, for builds from VICE's source tree.

package/src/native/ghidra/analyze.ts

@@ -25,7 +25,7 @@ export async function analyze(
   const base = start;
 
   // Ghidra disassembles and defines data only in the loaded bytes; labels may name any address.
-  const { entryPoints, dataRanges } = seedsInside(params, start, end);
+  const { entryPoints, codeStarts, dataRanges } = seedsInside(params, start, end);
   if (entryPoints.length === 0) {
     throw new WireFailure("invalid-input", "Give at least one entry point inside the program, for example the SYS address of its BASIC loader.");
   }
@@ -33,7 +33,7 @@ export async function analyze(
   const workspace = Workspace.create(context.supervisor);
   try {
     workspace.materialize("input", [{ path: "image.bin", size: body.length }], [body]);
-    writeFileSync(workspace.path("seeds.json"), JSON.stringify({ start, end, entryPoints, dataRanges, labels: params.labels }));
+    writeFileSync(workspace.path("seeds.json"), JSON.stringify({ start, end, entryPoints, codeStarts, dataRanges, labels: params.labels }));
     writeFileSync(
       workspace.path("request.json"),
       JSON.stringify({

package/src/native/ghidra/index.ts

@@ -129,7 +129,7 @@ export interface HeadlessOptions {
 /** What Ghidra's launcher (launch.sh, launch.bat) prints when it finds no Java that it can use. */
 export const NO_USABLE_JDK = /The 'java' command could not be found in your PATH or with JAVA_HOME|Unable to prompt user for JDK path, no TTY detected|Failed to find a supported JDK/;
 
-/** A Ghidra without a usable JDK is an incomplete installation that names the Java version it needs (D38). */
+/** A Ghidra without a usable JDK is an incomplete installation that names the Java version it needs. */
 export function noJdk(ghidra: GhidraInstallation): WireFailure {
   const java = ghidra.javaMin === undefined ? "a JDK" : `JDK ${ghidra.javaMin} or later`;
   return new WireFailure(

package/src/native/ghidra/language/c64rt_6510.slaspec

@@ -263,13 +263,16 @@ REL: target      is rel [ target = inst_next + rel; ] { export *:2 target; }
 }
 
 # BRK skips its padding byte: the return address is two bytes on.
+# The vector at $FFFE is in ROM unless the program banks the KERNAL out, and
+# the analysis cannot know the banking. Thus BRK ends the flow, and Ghidra
+# does not follow the RAM bytes at $FFFE of a flat image.
 :BRK is op=0x00 {
 	*:2 (SP - 1) = inst_next + 1;
 	SP = SP - 2;
 	pushP(1);
 	I = 1;
 	local vector:2 = 0xfffe;
-	goto [*:2 vector];
+	return [*:2 vector];
 }
 
 :CLC is op=0x18 { C = 0; }

package/src/native/ghidra/scripts/C64Export.java

@@ -3,7 +3,7 @@
 // Writes the structural result for the loaded image: functions with the
 // source of their names, code and defined-data regions, memory references
 // from instructions, every instruction with its bytes, mnemonic, operand
-// text and flow targets (D44), and the requested decompilations within their bounds.
+// text and flow targets, and the requested decompilations within their bounds.
 //@category c64-re-tools
 
 import java.io.FileReader;

package/src/native/ghidra/scripts/C64Prepare.java

@@ -3,7 +3,8 @@
 // Fills the rest of the 64 KiB address space with uninitialized memory, so
 // references to I/O and other RAM resolve, then applies the knowledge seeds:
 // labels (user-defined names), data ranges (defined bytes that analysis does
-// not disassemble) and entry points (disassembled functions).
+// not disassemble), entry points (disassembled functions) and code starts
+// (disassembled code without a function: a branch target is no routine).
 //@category c64-re-tools
 
 import java.io.FileReader;
@@ -56,5 +57,10 @@ public class C64Prepare extends GhidraScript {
 				createFunction(entry, null);
 			}
 		}
+		if (seeds.has("codeStarts")) {
+			for (JsonElement element : seeds.getAsJsonArray("codeStarts")) {
+				disassemble(toAddr(element.getAsLong()));
+			}
+		}
 	}
 }

package/src/native/types.ts

@@ -39,13 +39,15 @@ export interface AcmeResult {
 export const IMAGE_KINDS = ["prg", "flat64k"] as const;
 export type ImageKind = (typeof IMAGE_KINDS)[number];
 
-export const GHIDRA_LIMITS = { entryPoints: 1024, dataRanges: 1024, labels: 4096, decompile: 32, decompiledChars: 16_000, decompiledTotalChars: 128_000 } as const;
+export const GHIDRA_LIMITS = { entryPoints: 1024, codeStarts: 8192, dataRanges: 1024, labels: 4096, decompile: 32, decompiledChars: 16_000, decompiledTotalChars: 128_000 } as const;
 
 /** The Ghidra analysis. Its image is given next to these fields: a PRG, or 64 KiB from $0000. */
 export interface GhidraParams {
   imageKind: ImageKind;
   /** Seeds from current knowledge. */
   entryPoints: number[];
+  /** Executed instruction starts that Ghidra disassembles without making a function: a branch target is no routine. */
+  codeStarts?: number[];
   dataRanges: Array<{ start: number; end: number }>;
   labels: Array<{ address: number; name: string }>;
   /** Routine entries to decompile for immediate reasoning; the text is never stored. */
@@ -71,7 +73,7 @@ export interface GhidraResult {
   decompilations: Array<{ entry: number; text: string; truncated: boolean }>;
   /** Requested routines without decompiled code, with the decompiler's reason. */
   notDecompiled?: Array<{ entry: number; reason: string }>;
-  /** Every instruction in the coverage, as Ghidra decoded it (D44). */
+  /** Every instruction in the coverage, as Ghidra decoded it. */
   instructions: GhidraInstruction[];
   /** Which categories are complete inside the coverage; private to the importer. */
   completeness: { functions: boolean; regions: boolean; references: boolean };
@@ -80,9 +82,10 @@ export interface GhidraResult {
 }
 
 /** Refuses a DXA or Ghidra request with more seeds or decompilations than the request bounds allow, by name. */
-export function checkRequestBounds(params: DxaParams & { decompile?: number[] }): void {
+export function checkRequestBounds(params: DxaParams & { decompile?: number[]; codeStarts?: number[] }): void {
   const bounds = [
     ["entry points", params.entryPoints.length, GHIDRA_LIMITS.entryPoints],
+    ["code starts", params.codeStarts?.length ?? 0, GHIDRA_LIMITS.codeStarts],
     ["data ranges", params.dataRanges.length, GHIDRA_LIMITS.dataRanges],
     ["labels", params.labels.length, GHIDRA_LIMITS.labels],
     ["routines to decompile", params.decompile?.length ?? 0, GHIDRA_LIMITS.decompile],
@@ -93,7 +96,7 @@ export function checkRequestBounds(params: DxaParams & { decompile?: number[] })
 }
 
 /** The DXA analysis: the same image and seeds as Ghidra, without decompilation. */
-export type DxaParams = Omit<GhidraParams, "decompile">;
+export type DxaParams = Omit<GhidraParams, "decompile" | "codeStarts">;
 
 export interface DxaResult {
   coverage: Array<{ start: number; end: number }>;
@@ -247,11 +250,14 @@ export function imageRange(kind: ImageKind, image: Uint8Array): { start: number;
  * it, and the data ranges cut to it. A data range that holds an entry point
  * is left out, so that the entry point is disassembled.
  */
-export function seedsInside(params: Pick<DxaParams, "entryPoints" | "dataRanges">, start: number, end: number): Pick<DxaParams, "entryPoints" | "dataRanges"> {
-  const entryPoints = params.entryPoints.filter((address) => address >= start && address <= end);
+export function seedsInside(params: Pick<GhidraParams, "entryPoints" | "dataRanges" | "codeStarts">, start: number, end: number): { entryPoints: number[]; codeStarts: number[]; dataRanges: GhidraParams["dataRanges"] } {
+  const inside = (address: number) => address >= start && address <= end;
+  const entryPoints = params.entryPoints.filter(inside);
+  const codeStarts = (params.codeStarts ?? []).filter(inside);
+  const code = [...entryPoints, ...codeStarts];
   const dataRanges = params.dataRanges
     .filter((range) => range.end >= start && range.start <= end)
     .map((range) => ({ start: Math.max(range.start, start), end: Math.min(range.end, end) }))
-    .filter((range) => !entryPoints.some((entry) => entry >= range.start && entry <= range.end));
-  return { entryPoints, dataRanges };
+    .filter((range) => !code.some((entry) => entry >= range.start && entry <= range.end));
+  return { entryPoints, codeStarts, dataRanges };
 }

package/{skills/c64-source/scripts → src}/opcodes.ts

@@ -1,4 +1,4 @@
-// The ACME spelling of each 6510 opcode (D48): the mnemonic and the addressing
+// The ACME spelling of each 6510 opcode: the mnemonic and the addressing
 // mode, undocumented opcodes included. Ghidra gives the instruction
 // boundaries; this table gives the text. Where several opcodes share one
 // spelling, ACME writes only one of them: the generator finds those with a
@@ -56,6 +56,78 @@ export function takesAddress(mode: Mode): boolean {
   return mode !== "imp" && mode !== "imm";
 }
 
-export function isZeroPageMode(mode: Mode): boolean {
-  return mode === "zp" || mode === "zpx" || mode === "zpy" || mode === "izx" || mode === "izy";
+/** How an instruction uses the address of its operand, in the order a summary lists them. */
+export const USE_KINDS = ["read", "written", "modified", "called", "jumped to", "jumped through", "branched to", "pointer", "address", "table", "macro argument"] as const;
+export type UseKind = (typeof USE_KINDS)[number];
+
+const WRITES = new Set(["sta", "stx", "sty", "sax", "sha", "shx", "shy", "tas"]);
+const MODIFIES = new Set(["inc", "dec", "asl", "lsr", "rol", "ror", "slo", "rla", "sre", "rra", "dcp", "isc"]);
+
+/** The use of the operand address of an instruction that takes an address. Through (zp),y and (zp,x) the address is a pointer. */
+export function useKind(opcode: number): UseKind {
+  const { mnemonic, mode } = OPCODES[opcode]!;
+  if (mode === "izx" || mode === "izy") return "pointer";
+  if (mode === "rel") return "branched to";
+  if (mnemonic === "jsr") return "called";
+  if (mnemonic === "jmp") return mode === "ind" ? "jumped through" : "jumped to";
+  if (WRITES.has(mnemonic)) return "written";
+  if (MODIFIES.has(mnemonic)) return "modified";
+  return "read";
+}
+
+const hex2 = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
+const hex4 = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
+
+/** The text of the instruction in `bytes` at `pc`, for example "sta $d011" or "bne $c002". */
+export function instructionText(bytes: readonly number[], pc: number): string {
+  const { mnemonic, mode } = OPCODES[bytes[0]!]!;
+  const low = bytes[1] ?? 0;
+  const word = low | ((bytes[2] ?? 0) << 8);
+  const operand: Record<Mode, string> = {
+    imp: "",
+    imm: `#${hex2(low)}`,
+    zp: hex2(low),
+    zpx: `${hex2(low)},x`,
+    zpy: `${hex2(low)},y`,
+    abs: hex4(word),
+    abx: `${hex4(word)},x`,
+    aby: `${hex4(word)},y`,
+    ind: `(${hex4(word)})`,
+    izx: `(${hex2(low)},x)`,
+    izy: `(${hex2(low)}),y`,
+    rel: hex4((pc + 2 + (low < 0x80 ? low : low - 0x100)) & 0xffff),
+  };
+  return operand[mode] === "" ? mnemonic : `${mnemonic} ${operand[mode]}`;
+}
+
+/**
+ * The address that a read or write of the instruction in `bytes` uses, with X
+ * and Y as they were before it; `byteAt` reads a zero-page pointer. Undefined
+ * for a mode that uses no memory operand.
+ */
+export function operandAddress(bytes: readonly number[], x: number, y: number, byteAt: (address: number) => number): number | undefined {
+  const { mode } = OPCODES[bytes[0]!]!;
+  const low = bytes[1] ?? 0;
+  const word = low | ((bytes[2] ?? 0) << 8);
+  const pointer = (at: number) => byteAt(at & 0xff) | (byteAt((at + 1) & 0xff) << 8);
+  switch (mode) {
+    case "zp":
+      return low;
+    case "zpx":
+      return (low + x) & 0xff;
+    case "zpy":
+      return (low + y) & 0xff;
+    case "abs":
+      return word;
+    case "abx":
+      return (word + x) & 0xffff;
+    case "aby":
+      return (word + y) & 0xffff;
+    case "izx":
+      return pointer(low + x);
+    case "izy":
+      return (pointer(low) + y) & 0xffff;
+    default:
+      return undefined;
+  }
 }

package/src/platform.ts

@@ -1,5 +1,5 @@
 // C64 platform reference data and decoders: the c64-memory-map script, and the
-// platform names that c64-source uses (D52).
+// platform names that c64-source uses.
 // Names follow "Mapping the Commodore 64". Only platform facts live here:
 // an address without one belongs to the application.
 
@@ -323,10 +323,33 @@ const AREAS: Array<{ start: number; end: number; area: string; kind: Lookup["kin
 
 const hex = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
 
+export interface Area {
+  name: string;
+  start: number;
+  end: number;
+  kind: Lookup["kind"];
+  /** What a memory area holds. A chip register block has none: its name says it. */
+  meaning?: string;
+}
+
+/** The memory area or the I/O register block of an address. */
+export function areaOf(address: number): Area {
+  const block = IO.find((candidate) => address >= candidate.start && address <= candidate.end);
+  if (block !== undefined) return { name: block.area, start: block.start, end: block.end, kind: "platform" };
+  const area = AREAS.find((candidate) => address >= candidate.start && address <= candidate.end)!;
+  return { name: area.area, start: area.start, end: area.end, kind: area.kind, meaning: area.meaning };
+}
+
+/** The area of an address, and the register that an I/O mirror repeats: c64-source groups and describes its constants with them. */
+export function describeAddress(address: number): { area: Area; mirrorOf?: number } {
+  const { mirrorOf } = lookup(address);
+  return { area: areaOf(address), ...(mirrorOf === undefined ? {} : { mirrorOf }) };
+}
+
 /** The platform meaning of one address, or its application area. */
 export function lookup(address: number): Lookup {
-  for (const block of IO) {
-    if (address < block.start || address > block.end) continue;
+  const block = IO.find((candidate) => address >= candidate.start && address <= candidate.end);
+  if (block !== undefined) {
     const base = block.start + ((address - block.start) % block.period);
     const register = block.registers.find((entry) => entry.start === base);
     const mirror = base !== address ? { mirrorOf: base } : {};
@@ -334,15 +357,15 @@ export function lookup(address: number): Lookup {
     return { address, kind: "platform", area: block.area, name: register.name, meaning: register.meaning, ...mirror };
   }
   const entry = [...SYSTEM, ...ROM].find((candidate) => address >= candidate.start && address <= candidate.end);
-  const area = AREAS.find((candidate) => address >= candidate.start && address <= candidate.end)!;
+  const area = areaOf(address);
   if (entry !== undefined) {
-    return { address, kind: "platform", area: area.area, name: entry.name, meaning: entry.meaning, ...(entry.start !== address ? { entryStart: entry.start } : {}) };
+    return { address, kind: "platform", area: area.name, name: entry.name, meaning: entry.meaning, ...(entry.start !== address ? { entryStart: entry.start } : {}) };
   }
-  return { address, kind: area.kind, area: area.area, meaning: area.meaning };
+  return { address, kind: area.kind, area: area.name, meaning: area.meaning! };
 }
 
 /**
- * The platform name of each named address (D52): system variables, ROM
+ * The platform name of each named address: system variables, ROM
  * entries and I/O registers, not mirrors, in address order. Only names that
  * an assembler can use as a symbol, and each name once, at its lowest address.
  * `end` is the last address of the entry: a vector has two bytes.
@@ -357,6 +380,46 @@ export function platformNames(): Array<{ address: number; end: number; name: str
     .filter((entry) => !seen.has(entry.name) && seen.add(entry.name) !== undefined);
 }
 
+/** Which ROMs a program uses: a ROM it does not use gives no names, and without both the system area gives none. */
+export interface RomUse {
+  basic: boolean;
+  kernal: boolean;
+}
+
+/**
+ * The platform names of a program that uses only some ROMs: the BASIC
+ * ROM entries need the BASIC ROM, the KERNAL ROM entries the KERNAL, and the
+ * system variables of $0002-$03FF (the workspace of both) one of them. The
+ * processor port and the I/O registers always stay.
+ */
+export function platformNamesFor(use: RomUse): ReturnType<typeof platformNames> {
+  return platformNames().filter((entry) => {
+    if (entry.address >= 0xa000 && entry.address <= 0xbfff) return use.basic;
+    if (entry.address >= 0xe000) return use.kernal;
+    if (entry.address >= 0x0002 && entry.address <= 0x03ff) return use.basic || use.kernal;
+    return true;
+  });
+}
+
+/**
+ * The ROMs that a coverage map shows in use: code of the ROM executed. A read
+ * of ROM bytes is data, for example a table or random numbers, and does not use
+ * the routines of the ROM or their workspace (Bruce Lee reads 1,571 bytes of the
+ * BASIC ROM and executes none).
+ */
+export function romUseOf(coverage: Uint8Array, romExecute: number): RomUse {
+  const used = (start: number, end: number) => {
+    for (let address = start; address <= end; address++) if ((coverage[address]! & romExecute) !== 0) return true;
+    return false;
+  };
+  return { basic: used(0xa000, 0xbfff), kernal: used(0xe000, 0xffff) };
+}
+
+/** The ROMs that a value of $01 switches in: HIRAM for the KERNAL, LORAM and HIRAM for BASIC. */
+export function romUseOfPort(port: number): RomUse {
+  return { basic: (port & 0x03) === 0x03, kernal: (port & 0x02) !== 0 };
+}
+
 export type Decoded = Record<string, unknown>;
 
 const bits = (value: number) => [0, 1, 2, 3, 4, 5, 6, 7].filter((bit) => (value & (1 << bit)) !== 0);

package/src/project.ts

@@ -1,8 +1,180 @@
-import { realpathSync } from "node:fs";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+// The project: the nearest folder at or above the working directory that
+// holds .c64-re-tools/, below the home folder, the way git finds .git. A skill
+// script names it with --project <folder> and an MCP tool with `project`. Every
+// project path is relative to that folder. .c64-re-tools/local/ holds what
+// the agent saves for itself and ignores itself in git.
 
+import { existsSync, mkdirSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+/** The folder that marks a project and holds its knowledge. */
+export const PROJECT_DIRECTORY = ".c64-re-tools";
+
+/** The folder for machine-local scratch: saved results, batches and step files. */
+export const LOCAL_DIRECTORY = "local";
+
+/** The .gitignore of LOCAL_DIRECTORY: git ignores everything in it, the .gitignore too. */
+const LOCAL_GITIGNORE = "# Machine-local scratch of c64-re-tools (saved results, batches, step files). Never committed.\n*\n";
+
+/** How deep a working directory without a project is searched for projects below it. */
+const SEARCH_DEPTH = 3;
+
+/** At most this many projects are named in a refusal. */
+const LISTED_PROJECTS = 20;
+
+/** A refusal of the project rules, with a stable code, shown to the LLM unchanged. */
+export class ProjectError extends Error {
+  override name = "ProjectError";
+  readonly code: "invalid-input" | "not-found";
+
+  constructor(code: "invalid-input" | "not-found", message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** How a refusal tells the caller to name a project: "--project <folder>" for a script, "project" for an MCP tool. */
+export interface ProjectRemedy {
+  remedy?: string;
+}
+
+const SCRIPT_REMEDY = "Give --project <folder>";
+
+/** The folder that --project chose for this process, or undefined. */
+let chosen: string | undefined;
+
+/** The project that the project lookup found from a working directory, kept for the next call from the same directory. */
+let found: { cwd: string; root: string } | undefined;
+
+function isProject(folder: string): boolean {
+  return statSync(join(folder, PROJECT_DIRECTORY), { throwIfNoEntry: false })?.isDirectory() === true;
+}
+
+/** `start` and each folder above it, nearest first, below the home folder when `start` is under it. */
+function foldersUpFrom(start: string): string[] {
+  const home = homedir();
+  const underHome = start !== home && isInside(home, start);
+  if (start === home) return [];
+  const folders: string[] = [];
+  for (let folder = start; ; folder = dirname(folder)) {
+    if (underHome && folder === home) break;
+    folders.push(folder);
+    if (dirname(folder) === folder) break;
+  }
+  return folders;
+}
+
+/** The projects below `start` to SEARCH_DEPTH, relative to it and sorted. Dot folders and node_modules are skipped. */
+function projectsBelow(start: string): string[] {
+  const found: string[] = [];
+  const visit = (folder: string, depth: number) => {
+    let entries;
+    try {
+      entries = readdirSync(folder, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const path = join(folder, entry.name);
+      if (isProject(path)) found.push(relative(start, path));
+      else if (depth < SEARCH_DEPTH) visit(path, depth + 1);
+    }
+  };
+  visit(start, 1);
+  return found.sort();
+}
+
+function listed(projects: readonly string[]): string {
+  const shown = projects.slice(0, LISTED_PROJECTS).join(", ");
+  return projects.length > LISTED_PROJECTS ? `${shown} and ${projects.length - LISTED_PROJECTS} more` : shown;
+}
+
+/**
+ * The project of the working directory `cwd` by the project rules: the nearest
+ * folder at or above it with .c64-re-tools/, below the home folder. Without
+ * one, `cwd` itself, unless projects are below it or it is the home folder:
+ * then a ProjectError names them and the remedy, so no write lands outside a
+ * project.
+ */
+export function findProject(cwd: string = process.cwd(), options: ProjectRemedy = {}): string {
+  const start = resolve(cwd);
+  const remedy = options.remedy ?? SCRIPT_REMEDY;
+  for (const folder of foldersUpFrom(start)) {
+    if (isProject(folder)) return folder;
+  }
+  if (start === homedir()) {
+    throw new ProjectError("invalid-input", `The home folder is not a project folder. Start in a project folder, or ${remedy.charAt(0).toLowerCase()}${remedy.slice(1)}.`);
+  }
+  const below = projectsBelow(start);
+  if (below.length > 0) {
+    throw new ProjectError("invalid-input", `${start} is not a project folder. These folders below it are projects: ${listed(below)}. ${remedy} with one of them.`);
+  }
+  return start;
+}
+
+/**
+ * The project folder that `folder` names, relative to `cwd` or absolute. It
+ * must be a folder. It is the project as given, also without .c64-re-tools/
+ * (the first write makes it), but not a folder inside another project or the
+ * home folder.
+ */
+export function namedProject(folder: string, cwd: string = process.cwd()): string {
+  if (folder.length === 0) throw new ProjectError("invalid-input", "The project folder must not be empty.");
+  const path = resolve(cwd, folder);
+  const stat = statSync(path, { throwIfNoEntry: false });
+  if (stat === undefined) throw new ProjectError("not-found", `There is no folder ${folder}.`);
+  if (!stat.isDirectory()) throw new ProjectError("invalid-input", `${folder} is not a folder.`);
+  if (path === homedir()) throw new ProjectError("invalid-input", "The home folder is not a project folder.");
+  const outer = foldersUpFrom(path).slice(1).find(isProject);
+  if (outer !== undefined) {
+    throw new ProjectError("invalid-input", `${folder} is inside the project ${relative(cwd, outer) || "."}. Give that project folder.`);
+  }
+  return path;
+}
+
+/**
+ * Makes .c64-re-tools/local/ with its .gitignore when the project has
+ * .c64-re-tools/ and local/ has no .gitignore yet. A folder that is not
+ * yet a project gets nothing. A failure (for example a read-only project) is
+ * left to the write into local/ that needs the folder.
+ */
+export function ensureLocal(root: string): void {
+  const local = join(root, PROJECT_DIRECTORY, LOCAL_DIRECTORY);
+  const gitignore = join(local, ".gitignore");
+  if (existsSync(gitignore) || !isProject(root)) return;
+  try {
+    mkdirSync(local, { recursive: true });
+    writeFileSync(gitignore, LOCAL_GITIGNORE, { flag: "wx" });
+  } catch {
+    // Another process made it, or the project is read-only.
+  }
+}
+
+/** The project of an MCP call or another caller without process state: `folder` when given, else the project lookup from `cwd`. */
+export function resolveProject(folder: string | undefined, cwd: string = process.cwd(), options: ProjectRemedy = {}): string {
+  const root = folder === undefined ? findProject(cwd, options) : namedProject(folder, cwd);
+  ensureLocal(root);
+  return root;
+}
+
+/** Sets the project of this process from --project. Throws ProjectError for a folder that the rules refuse. */
+export function useProject(folder: string): void {
+  chosen = namedProject(folder);
+}
+
+/** The project folder of this process: the --project choice, else the project lookup from the working directory. */
 export function projectRoot(): string {
-  return process.cwd();
+  let root = chosen;
+  if (root === undefined) {
+    const cwd = process.cwd();
+    if (found?.cwd !== cwd) found = { cwd, root: findProject(cwd) };
+    root = found.root;
+  }
+  // Each call: the first write of a process can make .c64-re-tools/ after the lookup.
+  ensureLocal(root);
+  return root;
 }
 
 export function resolveProjectPath(path: string, root = projectRoot()): string {
@@ -18,6 +190,11 @@ export function resolveProjectPath(path: string, root = projectRoot()): string {
   throw new TypeError("Project path escapes the project root");
 }
 
+/** A project path in one spelling: relative to the project folder, with / and without ./, .. or a double /. Throws TypeError as resolveProjectPath does. */
+export function projectRelative(path: string, root = projectRoot()): string {
+  return relative(root, resolveProjectPath(path, root)).split(sep).join("/");
+}
+
 /** True when `candidate` is `root` or below it. Both are absolute paths. */
 export function isInside(root: string, candidate: string): boolean {
   const fromRoot = relative(root, candidate);

package/src/protocol/messages.ts

@@ -108,7 +108,7 @@ export class ProtocolError extends Error {
 /** Thrown by parameter/result validators; carries the wire code to answer with. */
 /**
  * The instruction at the end of a refusal that only the user can fix: a
- * missing or broken tool, or a Host Runtime that does not run (D37).
+ * missing or broken tool, or a Host Runtime that does not run.
  */
 export const STOP_AND_ASK = "Stop the task. Give this message to the user and wait for the user. Do not make a replacement for the tool or the host runtime.";