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

package/src/mcp/output.ts

@@ -1,14 +1,21 @@
 // Tool results written to a project file instead of the context (D39). The
-// MCP server runs on the agent's machine with the project as its working
-// directory, so it writes the file itself; the host never sees the path.
+// MCP server runs on the agent's machine, so it writes the file itself; the
+// host never sees the path. The project is the folder that `project` names,
+// or the one that the D67 rules find from the folder the agent started in (D68).
 
 import { createHash } from "node:crypto";
 
 import { z } from "zod";
 
-import { writeProjectFile } from "../host-client/transfer.ts";
+import { projectFolder, writeProjectFile } from "../host-client/transfer.ts";
 
-export const OutInput = z.string().min(1).describe("write the result to this file, relative to the project directory, in place of returning it. An existing file is overwritten");
+export const OutInput = z.string().min(1).describe("write the result to this file, relative to the project folder, in place of returning it. An existing file is overwritten");
+
+/** The project of a tool with a path (D67, D68). */
+export const ProjectInput = z
+  .string()
+  .min(1)
+  .describe("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. The paths of this call are relative to the project folder");
 
 /** What a result says in place of the bytes it wrote. */
 export interface Written {
@@ -24,9 +31,9 @@ export const WrittenOutput = {
   sha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
 };
 
-/** Writes `data` to the project file `path` and gives what the result shows in its place. */
-export function writeOut(path: string, data: Uint8Array | string, root?: string): Written {
+/** Writes `data` to the file `path` of the project that `project` names (or the D67 lookup finds), and gives what the result shows in its place. */
+export function writeOut(path: string, data: Uint8Array | string, project: string | undefined): Written {
   const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : data;
-  writeProjectFile(path, bytes, { what: "out", ...(root === undefined ? {} : { root }) });
+  writeProjectFile(path, bytes, { what: "out", root: projectFolder(project) });
   return { out: path, bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") };
 }

package/src/mcp/tools/debug.ts

@@ -7,7 +7,7 @@ import { COVERAGE, executedRamCode, EXECUTE, formatC64Address, READ, WRITE, type
 import { WireFailure } from "../../protocol/messages.ts";
 import { CHECKPOINT_ACTIONS, MAX_BACKTRACE, MAX_HISTORY, MAX_MEMMAP_RANGES, MAX_MEMORY_READ, MAX_PROFILE, MAX_WATCH_SIZE, SPACES, TIMING_ACTIONS, WATCH_ACCESS, type Breakpoint, type Watchpoint } from "../../protocol/vice.ts";
 import { readCoverage } from "../../host-client/coverage.ts";
-import { OutInput, writeOut, WrittenOutput } from "../output.ts";
+import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
 import { AddressInput, AddressOutput, Byte, ConditionInput, ConditionOutput, defineTool, HexData, requireFields, showCondition, SpaceInput, toCondition, type ViceSessionApi } from "../server.ts";
 import { spaced } from "./memory.ts";
 
@@ -135,7 +135,7 @@ export const c64CpuHistory = defineTool({
     "In space c64, it also gives the raster line and cycle when the instruction started. " +
     "With out, it writes the entries as text lines to that project file, and the result gives the file in place of the entries. " +
     "This does not change the run state of the machine.",
-  inputSchema: z.object({ limit: z.number().int().min(1).max(MAX_HISTORY).default(50), space: SpaceInput, out: OutInput.optional() }).strict(),
+  inputSchema: z.object({ limit: z.number().int().min(1).max(MAX_HISTORY).default(50), space: SpaceInput, out: OutInput.optional(), project: ProjectInput.optional() }).strict(),
   outputSchema: z.object({
     entries: z.array(
       z.object({
@@ -155,7 +155,8 @@ export const c64CpuHistory = defineTool({
   }),
   readOnly: false,
   async run(input, session) {
-    const { out, ...request } = input;
+    const { out, project, ...request } = input;
+    if (out === undefined && project !== undefined) throw new WireFailure("invalid-input", "project is used only with out.");
     const { entries } = await session.cpuHistory(request);
     if (out === undefined) return { entries: entries.map((entry) => ({ ...entry, address: formatC64Address(entry.address) })) };
     const byte = (value: number) => value.toString(16).padStart(2, "0");
@@ -163,7 +164,7 @@ export const c64CpuHistory = defineTool({
       const raster = entry.rasterLine === undefined ? "" : `  line ${entry.rasterLine} cycle ${entry.rasterCycle ?? 0}`;
       return `${formatC64Address(entry.address)}  ${spaced(entry.bytes).padEnd(9)} ${entry.text.padEnd(16)} a=${byte(entry.a)} x=${byte(entry.x)} y=${byte(entry.y)} sp=${byte(entry.sp)}${raster}`;
     });
-    return { count: entries.length, ...writeOut(out, `${lines.join("\n")}\n`) };
+    return { count: entries.length, ...writeOut(out, `${lines.join("\n")}\n`, project) };
   },
 });
 
@@ -261,6 +262,7 @@ export const c64Memmap = defineTool({
       end: AddressInput.optional().describe("read and summary. Default $ffff"),
       maxRanges: z.number().int().min(1).max(MAX_MEMMAP_RANGES).optional().describe("read without out only. Default 256"),
       out: OutInput.optional().describe("read only: write a coverage map to this project file, one byte for each address. An existing file is overwritten"),
+      project: ProjectInput.optional().describe("read 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({
@@ -307,8 +309,8 @@ export const c64Memmap = defineTool({
       };
     }
     if (fields.out !== undefined) {
-      requireFields("read", fields, ["start", "end", "out"]);
-      return writeOut(fields.out, await readCoverage(session, start, end));
+      requireFields("read", fields, ["start", "end", "out", "project"]);
+      return writeOut(fields.out, await readCoverage(session, start, end), fields.project);
     }
     requireFields("read", fields, ["start", "end", "maxRanges"]);
     const result = await session.memmap({ action: "read", start, end, maxRanges: fields.maxRanges ?? 256 });

package/src/mcp/tools/media.ts

@@ -1,16 +1,16 @@
 // Media tools: c64_autostart, c64_program_load, c64_disk_attach and
-// c64_snapshot. Paths are project-relative; the host-client reads the file and
-// the Host Runtime receives only its bytes.
+// c64_snapshot. Paths are relative to the project folder (D68); the host-client
+// reads the file and the Host Runtime receives only its bytes.
 
 import { z } from "zod";
 
 import { formatC64Address } from "../../c64.ts";
-import { readProjectFile } from "../../host-client/transfer.ts";
+import { projectFolder, readProjectFile } from "../../host-client/transfer.ts";
 import { AUTOSTART_TYPES, DISK_TYPES, MAX_SNAPSHOTS, RUN_STATES } from "../../protocol/vice.ts";
-import { OutInput, writeOut, WrittenOutput } from "../output.ts";
+import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
 import { AddressInput, AddressOutput, defineTool, requireFields, TransientName } from "../server.ts";
 
-const ProjectPath = z.string().min(1).describe("path relative to the project directory, for example build/game.prg");
+const ProjectPath = z.string().min(1).describe("path relative to the project folder, for example build/game.prg");
 
 const list = (types: readonly string[]) => types.map((type) => `.${type}`).join(", ");
 
@@ -27,6 +27,7 @@ export const c64Autostart = defineTool({
   inputSchema: z
     .object({
       path: ProjectPath,
+      project: ProjectInput.optional(),
       index: z.number().int().min(0).max(0xfffe).optional().describe("directory entry of a disk image, 0 is the first entry. Without it, the first file loads as with LOAD\"*\""),
       run: z.boolean().default(true).describe("true runs the program after it loads"),
     })
@@ -39,7 +40,7 @@ export const c64Autostart = defineTool({
   readOnly: false,
   async run(input, session) {
     // VICE numbers the directory entries from 1, and its 0 loads "*".
-    return session.autostart({ path: input.path, index: input.index === undefined ? 0 : input.index + 1, run: input.run });
+    return session.autostart({ path: input.path, index: input.index === undefined ? 0 : input.index + 1, run: input.run, root: projectFolder(input.project) });
   },
 });
 
@@ -53,13 +54,15 @@ export const c64ProgramLoad = defineTool({
   inputSchema: z
     .object({
       path: ProjectPath,
+      project: ProjectInput.optional(),
       address: AddressInput.optional().describe("load here instead of at the file's own load address"),
     })
     .strict(),
   outputSchema: z.object({ state: z.enum(RUN_STATES), loadAddress: AddressOutput, size: z.number().int().min(1).max(0x10000) }),
   readOnly: false,
   async run(input, session) {
-    const result = await session.programLoad(input.address === undefined ? { path: input.path } : { path: input.path, address: input.address });
+    const root = projectFolder(input.project);
+    const result = await session.programLoad(input.address === undefined ? { path: input.path, root } : { path: input.path, address: input.address, root });
     return { state: result.state, loadAddress: formatC64Address(result.loadAddress), size: result.size };
   },
 });
@@ -71,11 +74,11 @@ export const c64DiskAttach = defineTool({
     `Put a disk image from the project into drive 8 (${list(DISK_TYPES)}). ` +
     "Nothing loads or runs. To load from the disk, type LOAD on the C64 or use c64_autostart. " +
     "This does not change the run state of the machine.",
-  inputSchema: z.object({ path: ProjectPath }).strict(),
+  inputSchema: z.object({ path: ProjectPath, project: ProjectInput.optional() }).strict(),
   outputSchema: z.object({ attached: z.boolean() }),
   readOnly: false,
   async run(input, session) {
-    return session.diskAttach(input);
+    return session.diskAttach({ path: input.path, root: projectFolder(input.project) });
   },
 });
 
@@ -94,6 +97,7 @@ export const c64Snapshot = defineTool({
       name: TransientName.optional().describe("save and discard, and restore without file: 1 to 64 letters, digits, dots, underscores or hyphens"),
       out: OutInput.optional().describe("save only: also write the snapshot to this project file, for example snapshots/room0.vsf. An existing file is overwritten"),
       file: ProjectPath.optional().describe("restore only: a .vsf file in the project, in place of name"),
+      project: ProjectInput.optional().describe("save with out, and restore with file: 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({
@@ -113,13 +117,13 @@ export const c64Snapshot = defineTool({
       return session.snapshot({ action });
     }
     if (action === "restore" && fields.file !== undefined) {
-      requireFields(action, fields, ["file"], ["file"]);
-      return session.snapshotRestore(readProjectFile(fields.file).bytes);
+      requireFields(action, fields, ["file", "project"], ["file"]);
+      return session.snapshotRestore(readProjectFile(fields.file, { root: projectFolder(fields.project) }).bytes);
     }
     if (action === "save") {
-      requireFields(action, fields, ["name", "out"], ["name"]);
+      requireFields(action, fields, fields.out === undefined ? ["name"] : ["name", "out", "project"], ["name"]);
       const saved = await session.snapshot({ action, name: fields.name! });
-      return fields.out === undefined ? saved : { ...saved, ...writeOut(fields.out, await session.snapshotExport(fields.name!)) };
+      return fields.out === undefined ? saved : { ...saved, ...writeOut(fields.out, await session.snapshotExport(fields.name!), fields.project) };
     }
     requireFields(action, fields, ["name"], ["name"]);
     return session.snapshot({ action, name: fields.name! });

package/src/mcp/tools/memory.ts

@@ -6,7 +6,7 @@ import { z } from "zod";
 import { formatC64Address } from "../../c64.ts";
 import { WireFailure } from "../../protocol/messages.ts";
 import { MAX_COMPARE_DIFFERENCES, MAX_COMPARE_SIZE, MAX_DISASSEMBLE, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_SEARCH_PATTERN, MAX_SEARCH_RESULTS, type RegisterValues } 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, HexDataInput, MemoryViewInput, requireFields, SpaceInput } from "../server.ts";
 
 /** With out, a read or a disassembly can be larger than one answer of the session: it is read in parts (D39). */
@@ -28,12 +28,14 @@ export const c64MemoryRead = defineTool({
       space: SpaceInput,
       view: MemoryViewInput,
       out: OutInput.optional(),
+      project: ProjectInput.optional(),
     })
     .strict(),
   outputSchema: z.object({ address: AddressOutput, size: z.number().int().min(1).max(MAX_MEMORY_READ_OUT), data: HexData.optional(), ...WrittenOutput }),
   readOnly: false,
   async run(input, session) {
-    const { out, ...read } = input;
+    const { out, project, ...read } = input;
+    if (out === undefined && project !== undefined) throw new WireFailure("invalid-input", "project is used only with out.");
     if (out === undefined) {
       if (read.size > MAX_MEMORY_READ) throw new WireFailure("invalid-input", `size can be at most ${MAX_MEMORY_READ} without out.`);
       const result = await session.memoryRead(read);
@@ -45,7 +47,7 @@ export const c64MemoryRead = defineTool({
       const part = await session.memoryRead({ ...read, address: at, size: Math.min(MAX_MEMORY_READ, read.address + read.size - at) });
       parts.push(Buffer.from(part.data, "hex"));
     }
-    return { address: formatC64Address(read.address), size: read.size, ...writeOut(out, Buffer.concat(parts)) };
+    return { address: formatC64Address(read.address), size: read.size, ...writeOut(out, Buffer.concat(parts), project) };
   },
 });
 
@@ -210,12 +212,14 @@ export const c64Disassemble = defineTool({
       space: SpaceInput,
       view: MemoryViewInput,
       out: OutInput.optional(),
+      project: ProjectInput.optional(),
     })
     .strict(),
   outputSchema: z.object({ instructions: z.array(z.object({ address: AddressOutput, bytes: HexData, text: z.string() })).optional(), count: z.number().int().min(0).optional(), ...WrittenOutput }),
   readOnly: false,
   async run(input, session) {
-    const { out, ...request } = input;
+    const { out, project, ...request } = input;
+    if (out === undefined && project !== undefined) throw new WireFailure("invalid-input", "project is used only with out.");
     if (out === undefined) {
       if (request.count > MAX_DISASSEMBLE) throw new WireFailure("invalid-input", `count can be at most ${MAX_DISASSEMBLE} without out.`);
       const result = await session.disassemble(request);
@@ -238,7 +242,7 @@ export const c64Disassemble = defineTool({
         address = instruction.address + instruction.bytes.length / 2;
       }
     }
-    return { count: lines.length, ...writeOut(out, `${lines.join("\n")}\n`) };
+    return { count: lines.length, ...writeOut(out, `${lines.join("\n")}\n`, project) };
   },
 });
 

package/src/mcp/tools/video.ts

@@ -6,7 +6,7 @@ import { z } from "zod";
 import { formatC64Address } 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);
@@ -150,6 +150,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 +170,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/platform.ts

@@ -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,11 +357,11 @@ 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! };
 }
 
 /**

package/src/project.ts

@@ -1,8 +1,171 @@
-import { realpathSync } from "node:fs";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+// The project (D67): 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 (D68). .c64-re-tools/local/ holds what
+// the agent saves for itself and ignores itself in git (D70).
 
+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 (D70). */
+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;
+
+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 D67 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 (D70). 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 D67 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 D67 lookup from the working directory. */
 export function projectRoot(): string {
-  return process.cwd();
+  const root = chosen ?? findProject();
+  ensureLocal(root);
+  return root;
 }
 
 export function resolveProjectPath(path: string, root = projectRoot()): string {

package/src/protocol/tools.ts

@@ -5,7 +5,7 @@ import { type Fields, invalid, isInteger, isObject, isOneOf, onlyFields, Protoco
 
 // ---------------------------------------------------------------------------
 // Native-tool operations. Short-lived requests on "tool" connections; they
-// never touch an emulator or knowledge.db.
+// never touch an emulator or the knowledge.
 
 /** A transferred source tree: relative POSIX paths, one attachment per file in this order. */
 export type SourceTree = Array<{ path: string; size: number }>;

package/src/script.ts

@@ -1,7 +1,8 @@
 // The one error envelope for the skill scripts and the CLI: a script prints one JSON line,
 // a refusal prints {"error":{code,message}} with exit status 1, and a usage error prints the
-// usage text as an invalid-input error with exit status 2.
+// usage text as an invalid-input error with exit status 2. Every script takes --project <folder> (D67).
 
+import { ProjectError, useProject } from "./project.ts";
 import { shownMessage, WireFailure } from "./protocol/messages.ts";
 import { elapsedMs, startTrace, trace, type TraceFields } from "./trace.ts";
 
@@ -17,27 +18,65 @@ function isParseArgsError(error: unknown): error is Error {
   return error instanceof Error && typeof code === "string" && code.startsWith("ERR_PARSE_ARGS_");
 }
 
+/** The line that every usage text ends with. */
+export const PROJECT_USAGE = "Every script takes --project <folder>: the project folder, relative to the working directory. Without it, the script uses the nearest folder at or above the working directory that holds .c64-re-tools/.";
+
+/**
+ * Takes --project <folder> and --project=<folder> out of a command line, up to "--".
+ * Returns the folder and the other arguments. Throws UsageError for a --project without a folder or a second --project.
+ */
+export function takeProject(argv: readonly string[]): { project?: string; argv: string[] } {
+  const rest: string[] = [];
+  let project: string | undefined;
+  for (let index = 0; index < argv.length; index++) {
+    const argument = argv[index]!;
+    if (argument === "--") {
+      rest.push(...argv.slice(index));
+      break;
+    }
+    let value: string | undefined;
+    if (argument === "--project") {
+      value = argv[index + 1];
+      if (value === undefined || value.startsWith("-")) throw new UsageError("--project needs a folder");
+      index++;
+    } else if (argument.startsWith("--project=")) {
+      value = argument.slice("--project=".length);
+      if (value === "") throw new UsageError("--project needs a folder");
+    } else {
+      rest.push(argument);
+      continue;
+    }
+    if (project !== undefined) throw new UsageError("give --project only once");
+    project = value;
+  }
+  return project === undefined ? { argv: rest } : { project, argv: rest };
+}
+
 function printLine(value: unknown): void {
   process.stdout.write(`${JSON.stringify(value)}\n`);
 }
 
 /**
- * Runs a script body. Prints its result as one JSON line when it returns a value (undefined prints nothing).
- * A refusal (WireFailure always, plus `refusals`) prints {"error":{code,message}} with exit status 1.
+ * Runs a script body with the command line of the process, without --project: that sets the project first (D67).
+ * Prints its result as one JSON line when it returns a value (undefined prints nothing).
+ * A refusal (WireFailure and ProjectError always, plus `refusals`) prints {"error":{code,message}} with exit status 1.
  * A UsageError or a node:util parseArgs error (code ERR_PARSE_ARGS_*) prints {"error":{"code":"invalid-input",
  * "message": message === "" ? usage : message + "\n\n" + usage}} with exit status 2. Anything else is rethrown.
  * The body may set process.exitCode itself for an extra exit status; a value it returns is printed as usual.
  */
-export async function runScript(body: () => unknown, options: { usage: string; refusals?: readonly RefusalClass[] }): Promise<void> {
+export async function runScript(body: (argv: string[]) => unknown, options: { usage: string; refusals?: readonly RefusalClass[] }): Promise<void> {
+  const usage = `${options.usage}\n\n${PROJECT_USAGE}`;
   // The trace of the script, when C64RT_TRACE is set; its start event carries the script and its arguments.
   startTrace("script", { warn: (line) => process.stderr.write(`${line}\n`) });
   const started = performance.now();
   const end = (fields: TraceFields) => trace().event("script.end", { ms: elapsedMs(started), status: process.exitCode ?? 0, ...fields });
   let result: unknown;
   try {
-    result = await body();
+    const { project, argv } = takeProject(process.argv.slice(2));
+    if (project !== undefined) useProject(project);
+    result = await body(argv);
   } catch (error) {
-    if ([WireFailure, ...(options.refusals ?? [])].some((refusal) => error instanceof refusal)) {
+    if ([WireFailure, ProjectError, ...(options.refusals ?? [])].some((refusal) => error instanceof refusal)) {
       const { code } = error as Error & { code: string };
       const message = shownMessage(error as Error & { code: string });
       printLine({ error: { code, message } });
@@ -47,7 +86,7 @@ export async function runScript(body: () => unknown, options: { usage: string; r
     }
     if (error instanceof UsageError || isParseArgsError(error)) {
       const { message } = error;
-      printLine({ error: { code: "invalid-input", message: message === "" ? options.usage : `${message}\n\n${options.usage}` } });
+      printLine({ error: { code: "invalid-input", message: message === "" ? usage : `${message}\n\n${usage}` } });
       process.exitCode = 2;
       end({ error: { code: "invalid-input", message } });
       return;