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

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/messages.ts

@@ -7,7 +7,7 @@ import type { ViceOperation, ViceOperations } from "./vice.ts";
 /** Private Host Runtime protocol identifier. */
 export const HOST_PROTOCOL_ID = "c64-re-tools-host" as const;
 /** Bumped on any incompatible change; a mismatch fails the handshake. */
-export const HOST_PROTOCOL_VERSION = 2;
+export const HOST_PROTOCOL_VERSION = 3;
 /** After ready, the client pings this often, on every connection. */
 export const HEARTBEAT_INTERVAL_MS = 10_000;
 /** Either side closes a connection that has sent nothing for this long. */
@@ -54,13 +54,8 @@ export interface Hello {
   role: Role;
   /** vice-session only; fixed for the session. */
   videoStandard?: VideoStandard;
-  /** The shared secret (C64RT_HOST_TOKEN) for a host that listens beyond loopback. */
-  token?: string;
 }
 
-/** Longest accepted shared token. */
-const MAX_TOKEN_LENGTH = 256;
-
 export interface Ready {
   type: "ready";
 }
@@ -111,6 +106,22 @@ 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).
+ */
+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.";
+
+/** The message with STOP_AND_ASK at its end, once. */
+export function withStopAndAsk(message: string): string {
+  return message.endsWith(STOP_AND_ASK) ? message : `${message} ${STOP_AND_ASK}`;
+}
+
+/** The message that the agent sees for a refusal: an installation-incomplete one ends with STOP_AND_ASK. */
+export function shownMessage(error: { code: string; message: string }): string {
+  return error.code === "installation-incomplete" ? withStopAndAsk(error.message) : error.message;
+}
+
 export class WireFailure extends Error implements WireError {
   override name = "WireFailure";
   readonly code: ErrorCode;
@@ -166,12 +177,8 @@ export function parseClientMessage(value: unknown): ReceivedClientMessage {
     if (value.videoStandard !== undefined && !isOneOf(VIDEO_STANDARDS, value.videoStandard)) {
       throw new ProtocolError("hello has an unknown video standard");
     }
-    if (value.token !== undefined && (typeof value.token !== "string" || value.token.length > MAX_TOKEN_LENGTH)) {
-      throw new ProtocolError("hello has a malformed token");
-    }
     const hello: Hello = { type: "hello", protocol: value.protocol, version: value.version, role: value.role };
     if (value.videoStandard !== undefined) hello.videoStandard = value.videoStandard;
-    if (value.token !== undefined) hello.token = value.token;
     return hello;
   }
   if (value.type === "request") {

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 }>;
@@ -41,7 +41,8 @@ export interface DiskSector {
 
 export type C1541Result =
   | { action: "directory"; diskName: string; diskId: string; dosType: string; freeBlocks: number; entries: DiskFile[] }
-  | { action: "bam"; tracks: Array<{ track: number; freeSectors: number[]; usedSectors: number[] }> }
+  /** unreferenced: the used sectors that no file, the header, the directory or the BAM holds. */
+  | { action: "bam"; tracks: Array<{ track: number; freeSectors: number[]; usedSectors: number[] }>; unreferenced: DiskSector[] }
   | { action: "entry"; found: false }
   | { action: "entry"; found: true; entry: DiskFile & { startTrack: number; startSector: number } }
   | { action: "chain"; found: false }
@@ -61,7 +62,7 @@ export type PetcatResult =
   | {
       decoded: true;
       loadAddress: number;
-      /** The address after the BASIC end marker; any bytes from here on are no BASIC. */
+      /** The first address that holds no BASIC: after a 00 00 end marker, or at a link whose high byte only is zero. */
       basicEnd: number;
       listing: string;
       lines: Array<{ number: number; text: string }>;
@@ -79,10 +80,22 @@ export interface ToolStatus {
   runs: boolean;
   /** What is wrong and what to do, when it is missing or does not run. */
   problem?: string;
+  /** Known flaws of this version, each with the version that fixes it (D56). The tool still runs. */
+  flaws?: string[];
+}
+
+/** The Host Runtime itself: its package version and the system it runs on. */
+export interface HostInfo {
+  version: string;
+  /** Node's name of the operating system: linux, darwin or win32. */
+  platform: string;
+  /** The release of the operating system. */
+  release: string;
+  arch: string;
 }
 
 export interface ToolOperations {
-  "host.status": { params: Record<string, never>; result: { tools: ToolStatus[] } };
+  "host.status": { params: Record<string, never>; result: { host: HostInfo; tools: ToolStatus[] } };
   "c1541.inspect": { params: C1541Params; result: C1541Result };
   "petcat.decode": { params: PetcatParams; result: PetcatResult };
 }
@@ -96,20 +109,6 @@ export function isRelativePath(value: unknown): value is string {
   return typeof value === "string" && value.length <= 1024 && RELATIVE_PATH.test(value) && !value.includes("//") && !value.endsWith("/");
 }
 
-/** Validates a transferred source tree against its attachments. Throws WireFailure(invalid-input). */
-export function validateSourceTree(value: unknown, attachments: readonly Uint8Array[]): SourceTree {
-  if (!Array.isArray(value) || value.length > MAX_TREE_FILES) invalid(`files must list at most ${MAX_TREE_FILES} files`);
-  if (value.length !== attachments.length) invalid("each listed file needs exactly one attachment");
-  const seen = new Set<string>();
-  return value.map((entry, index) => {
-    if (!isObject(entry) || !isRelativePath(entry.path)) invalid("each file needs a relative path inside the source root");
-    if (seen.has(entry.path)) invalid(`the file ${entry.path} is listed twice`);
-    seen.add(entry.path);
-    if (entry.size !== attachments[index]!.length) invalid(`the size of ${entry.path} does not match its bytes`);
-    return { path: entry.path, size: entry.size as number };
-  });
-}
-
 /** Refuses anything but exactly one attachment with at least one byte, named by what it must hold. */
 function oneFile(attachments: readonly Uint8Array[], what: string): void {
   if (attachments.length !== 1 || attachments[0]!.length === 0) invalid(`${what} must be the one attachment, and it must not be empty`);
@@ -173,8 +172,11 @@ export function validateToolResult<O extends ToolOperation>(op: O, value: unknow
         typeof tool.name === "string" &&
         typeof tool.found === "boolean" &&
         typeof tool.runs === "boolean" &&
-        [tool.path, tool.version, tool.problem].every((field) => field === undefined || typeof field === "string");
-      if (!Array.isArray(tools) || !tools.every(isStatus) || attachments.length !== 0) throw new ProtocolError("host.status result is malformed");
+        [tool.path, tool.version, tool.problem].every((field) => field === undefined || typeof field === "string") &&
+        (tool.flaws === undefined || (Array.isArray(tool.flaws) && tool.flaws.every((flaw: unknown) => typeof flaw === "string")));
+      const host = value.host;
+      const isHost = isObject(host) && [host.version, host.platform, host.release, host.arch].every((field) => typeof field === "string");
+      if (!isHost || !Array.isArray(tools) || !tools.every(isStatus) || attachments.length !== 0) throw new ProtocolError("host.status result is malformed");
       return value as unknown as ToolOperations[O]["result"];
     }
   }
@@ -211,7 +213,9 @@ function isC1541Result(value: Fields, attachments: readonly Uint8Array[]): boole
     case "bam":
       return (
         Array.isArray(value.tracks) &&
-        value.tracks.every((track) => isObject(track) && isInteger(track.track, 1, 255) && isSectorList(track.freeSectors) && isSectorList(track.usedSectors))
+        value.tracks.every((track) => isObject(track) && isInteger(track.track, 1, 255) && isSectorList(track.freeSectors) && isSectorList(track.usedSectors)) &&
+        Array.isArray(value.unreferenced) &&
+        value.unreferenced.every(isTrackSector)
       );
     case "entry":
       return (
@@ -233,7 +237,8 @@ function isPetcatResult(value: Fields): boolean {
     isObject(handoff) &&
     isInteger(handoff.line, 0, 0xffff) &&
     ((handoff.kind === "sys" && isInteger(handoff.address, 0, 0xffff) && handoff.computed === undefined) ||
-      ((handoff.kind === "sys" || handoff.kind === "usr") && handoff.computed === true && handoff.address === undefined));
+      (handoff.kind === "sys" && handoff.computed === true && handoff.address === undefined && typeof handoff.expression === "string") ||
+      (handoff.kind === "usr" && handoff.computed === true && handoff.address === undefined));
   return (
     value.decoded === true &&
     isInteger(value.loadAddress, 0, 0xffff) &&