@henols/c64-re-tools 2.1.2 → 2.1.3

package/src/knowledge/write.ts

@@ -62,7 +62,7 @@ import {
   type SuppressionRow,
   type SymbolRow,
 } from "./read.ts";
-import { CODE_REGION_TYPES, COMMENT_PLACEMENTS, EVIDENCE_KINDS, MAX_ELEMENT, MODULE_FILE, DEFAULT_SPACE, GENERATED_FILES, isGeneratedFile, MACRO_NAME, MACRO_PARAM, SWITCH_NAME, NO_ELEMENT_TYPES, OPERAND_SELECTS, POINTER_KIND, REFERENCE_KINDS, REGION_TYPES, SYMBOL_KINDS, type CommentPlacement, type EvidenceKind, type OperandSelect, type Origin, type ReferenceKind, type RegionType, type Space, type SymbolKind } from "./schema.ts";
+import { CODE_REGION_TYPES, COMMENT_PLACEMENTS, EVIDENCE_KINDS, MAX_ELEMENT, MODULE_FILE, DEFAULT_SPACE, GENERATED_FILES, isGeneratedFile, isSemantic, MACRO_NAME, MACRO_PARAM, SWITCH_NAME, NO_ELEMENT_TYPES, OPERAND_SELECTS, POINTER_KIND, REFERENCE_KINDS, REGION_TYPES, SYMBOL_KINDS, type CommentPlacement, type EvidenceKind, type OperandSelect, type Origin, type ReferenceKind, type RegionType, type Space, type SymbolKind } from "./schema.ts";
 import { newRevisionId, rowId, sqlName } from "./text.ts";
 
 /** What a change rests on: a coverage run, a test or another project file with its SHA-256, or a note. */
@@ -353,6 +353,27 @@ const result = <T, P>(written: { revision: string | null; current: Step<T, P> })
 // Each write has a check, which refuses bad input before anything opens, and a
 // step, which runs inside a change. A single write and a batch share both.
 
+/**
+ * True when a write of `origin` over a current row with the same content
+ * records a decision, so it replaces the row: over a row of an analyzer (the
+ * next run of the analyzer can retire its own rows, never a decision), and the
+ * user over the LLM. The LLM over the user changes nothing.
+ */
+function confirms(existing: Origin, origin: Origin): boolean {
+  return existing !== origin && (!isSemantic(existing) || origin === "user");
+}
+
+/**
+ * The bytes of the program of a space in the knowledge, by address: undefined
+ * outside it. A module and a comment are checked against them.
+ */
+function programBytes(db: DatabaseSync, space: Space): (address: number) => number | undefined {
+  const rows = db.prepare("SELECT address, bytes FROM current_memory WHERE space = ?").all(space) as Array<{ address: number; bytes: string }>;
+  const memory = new Map<number, number>();
+  for (const row of rows) Buffer.from(row.bytes, "hex").forEach((byte, offset) => memory.set(row.address + offset, byte));
+  return (address) => memory.get(address);
+}
+
 /** Every request names its space; without one it is the C64. */
 type InSpace = { space?: Space };
 type SymbolRequest = InSpace & { address: number; name: string; kind?: SymbolKind };
@@ -381,7 +402,7 @@ function renameStep(db: DatabaseSync, change: Change, origin: Origin, request: S
   const space = spaceOf(request);
   const existing = symbolAt(db, request.address, space);
   const kind = request.kind ?? existing?.kind ?? "label";
-  if (existing !== undefined && existing.name === request.name && existing.kind === kind) return { current: existing };
+  if (existing !== undefined && existing.name === request.name && existing.kind === kind && !confirms(existing.origin, origin)) return { current: existing };
   const owner = symbolNamed(db, request.name, space);
   if (owner !== undefined && owner.address !== request.address) {
     throw new Refusal("conflict", `The name ${request.name} already belongs to ${formatC64Address(owner.address)}. Rename or remove that symbol first.`);
@@ -459,7 +480,7 @@ function classifyStep(db: DatabaseSync, change: Change, origin: Origin, request:
   const overlapping = regionsOverlapping(db, request.start, request.end, space);
   const [only] = overlapping;
   const same = overlapping.length === 1 && only!.start === request.start && only!.end === request.end && only!.type === request.type && only!.element === request.element;
-  if (same) return { current: overlapping };
+  if (same && !confirms(only!.origin, origin)) return { current: overlapping };
   clearRange(db, change, request.start, request.end, space);
   change.insertRegion({ space, start: request.start, end: request.end, type: request.type, ...(request.element === undefined ? {} : { element: request.element }), origin });
   liftRegionSuppressions(db, change, request.start, request.end, space);
@@ -490,14 +511,17 @@ function checkComment(request: CommentRequest): string {
   return text;
 }
 
-function commentStep(db: DatabaseSync, change: Change, origin: Origin, request: CommentRequest): Step<CommentRow> {
+function commentStep(db: DatabaseSync, change: Change, origin: Origin, request: CommentRequest): Step<CommentRow, CommentRow> {
   const space = spaceOf(request);
   const text = request.text.trim();
   const existing = commentsAt(db, request.address, space).find((comment) => comment.placement === request.placement);
-  if (existing?.text === text) return { current: existing };
+  if (existing?.text === text && !confirms(existing.origin, origin)) return { current: existing };
+  // A comment belongs to an instruction: the listing and the source show it at the start of the instruction only.
+  checkInstructionStart(db, space, programBytes(db, space), request.address, "comment");
   if (existing !== undefined) change.close("comments", "space = ? AND address = ? AND placement = ?", space, request.address, request.placement);
   change.insertComment({ space, address: request.address, placement: request.placement, text, origin });
-  return { current: commentsAt(db, request.address, space).find((comment) => comment.placement === request.placement)! };
+  const current = commentsAt(db, request.address, space).find((comment) => comment.placement === request.placement)!;
+  return existing !== undefined && existing.origin !== origin ? { current, previous: existing } : { current };
 }
 
 function checkPlacement(request: PlacementRequest): void {
@@ -523,14 +547,16 @@ function checkReference(request: ReferenceRequest): void {
   if (request.kind === POINTER_KIND) throw new Refusal("invalid-input", "Only an operand expression writes a pointer reference: use operand and unoperand.");
 }
 
-function referenceStep(db: DatabaseSync, change: Change, origin: Origin, request: ReferenceRequest): Step<ReferenceRow> {
+function referenceStep(db: DatabaseSync, change: Change, origin: Origin, request: ReferenceRequest): Step<ReferenceRow, ReferenceRow> {
   const space = spaceOf(request);
   const find = () => referencesFrom(db, request.from, space).find((reference) => reference.to === request.to && reference.kind === request.kind);
   const existing = find();
-  if (existing !== undefined) return { current: existing };
+  if (existing !== undefined && !confirms(existing.origin, origin)) return { current: existing };
+  // A confirmation of a reference of an analyzer makes it a reference of the writer: the next run of the analyzer keeps it.
+  if (existing !== undefined) change.close('"references"', "space = ? AND from_address = ? AND to_address = ? AND kind = ?", space, request.from, request.to, request.kind);
   change.insertReference({ space, from: request.from, to: request.to, kind: request.kind, origin });
   change.close("suppressions", "space = ? AND entity = 'reference' AND start_address = ? AND to_address = ? AND kind = ?", space, request.from, request.to, request.kind);
-  return { current: find()! };
+  return existing !== undefined ? { current: find()!, previous: existing } : { current: find()! };
 }
 
 function unreferenceStep(db: DatabaseSync, change: Change, origin: Origin, request: ReferenceRequest): Step<null> {
@@ -581,26 +607,32 @@ const shown = (value: number, size: number) => (value < 0 ? String(value) : `$${
 /**
  * Refuses an address that is not the start of an instruction. The code
  * regions of the knowledge give the instructions: they are decoded from the
- * start of the region, as the listing and the source decode them.
+ * start of the region, as the listing and the source decode them. An operand
+ * expression needs an instruction, so it is refused also outside the code
+ * regions and where the program has no byte. A module and a comment are
+ * refused only at an operand byte of a known instruction: they can start data.
  */
-function checkInstructionStart(db: DatabaseSync, space: Space, image: OperandImage, address: number): void {
+function checkInstructionStart(db: DatabaseSync, space: Space, byteAt: (address: number) => number | undefined, address: number, write: "operand" | "module" | "comment"): void {
   const where = formatC64Address(address);
   const code = regionsOverlapping(db, address, address, space).find((region) => CODE_REGION_TYPES.includes(region.type));
   if (code === undefined) {
+    if (write !== "operand") return;
     throw new Refusal("invalid-input", `${where} is in no code region, so the knowledge does not know an instruction that starts there. Classify the code that holds the instruction first (classify <range> code), then write the operand.`);
   }
   let start = code.start;
   let next = code.start;
   while (next < address) {
-    const opcode = image.byteAt(next);
+    const opcode = byteAt(next);
     if (opcode === undefined) {
+      if (write !== "operand") return;
       throw new Refusal("invalid-input", `The code region ${formatC64Address(code.start)}-${formatC64Address(code.end)} has no program byte at ${formatC64Address(next)}, so its instructions up to ${where} are not known. Correct the region (classify), then write the operand.`);
     }
     start = next;
     next += instructionLength(opcode);
   }
   if (next !== address) {
-    throw new Refusal("invalid-input", `${where} is not the start of an instruction. It is an operand byte of the instruction at ${formatC64Address(start)}, decoded from the start of the code region at ${formatC64Address(code.start)}. Give ${formatC64Address(start)}.`);
+    const what = write === "operand" ? "" : ` A ${write} is at the start of an instruction, as the listing and the source show it.`;
+    throw new Refusal("invalid-input", `${where} is not the start of an instruction. It is an operand byte of the instruction at ${formatC64Address(start)}, decoded from the start of the code region at ${formatC64Address(code.start)}.${what} Give ${formatC64Address(start)}.`);
   }
 }
 
@@ -613,7 +645,7 @@ function checkOperandValue(db: DatabaseSync, space: Space, image: OperandImage,
   const where = formatC64Address(request.address);
   const opcode = image.byteAt(request.address);
   if (opcode === undefined) throw new Refusal("invalid-input", `${where} is outside the image.`);
-  checkInstructionStart(db, space, image, request.address);
+  checkInstructionStart(db, space, (at) => image.byteAt(at), request.address, "operand");
   const length = instructionLength(opcode);
   if (length === 1) throw new Refusal("invalid-input", `The instruction at ${where} (opcode ${shown(opcode, 0x100)}) has no operand.`);
   if ((opcode & 0x1f) === 0x10) throw new Refusal("invalid-input", `The instruction at ${where} is a branch: its operand is a distance, not a value.`);
@@ -646,10 +678,10 @@ function operandStep(db: DatabaseSync, change: Change, context: ChangeContext &
   if (request.expression !== undefined) wanted.expression = request.expression.trim();
   const targets = new Set(checkOperandValue(db, space, context.image, request, operandText(wanted)));
   const existing = operandAt(db, request.address, space);
-  if (existing !== undefined && existing.select === wanted.select && existing.symbol === wanted.symbol && existing.offset === wanted.offset && existing.expression === wanted.expression) {
+  const origin = context.origin as OperandRow["origin"];
+  if (existing !== undefined && existing.select === wanted.select && existing.symbol === wanted.symbol && existing.offset === wanted.offset && existing.expression === wanted.expression && !confirms(existing.origin, origin)) {
     return { current: existing };
   }
-  const origin = context.origin as OperandRow["origin"];
   if (existing !== undefined) change.close("operands", "space = ? AND address = ?", space, request.address);
   change.insertOperand({ space, address: request.address, ...wanted, origin });
   const pointers = referencesFrom(db, request.address, space).filter((reference) => reference.kind === POINTER_KIND);
@@ -683,19 +715,22 @@ function checkModule(request: ModuleRequest): void {
   if (request.title !== undefined && (request.title.trim().length === 0 || request.title.length > MAX_COMMENT)) throw new Refusal("invalid-input", `A module title has 1 to ${MAX_COMMENT} characters.`);
 }
 
-function moduleStep(db: DatabaseSync, change: Change, origin: Origin, request: ModuleRequest): Step<ModuleRow> {
+function moduleStep(db: DatabaseSync, change: Change, origin: Origin, request: ModuleRequest): Step<ModuleRow, ModuleRow> {
   const space = spaceOf(request);
   const existing = moduleAt(db, request.start, space);
   // A module write without a title keeps the title it has.
   const title = request.title === undefined ? existing?.title : request.title.trim();
-  if (existing !== undefined && existing.file === request.file && existing.title === title) return { current: existing };
+  if (existing !== undefined && existing.file === request.file && existing.title === title && !confirms(existing.origin, origin)) return { current: existing };
+  // A file of the source starts at an instruction: a start inside one splits it into bytes.
+  checkInstructionStart(db, space, programBytes(db, space), request.start, "module");
   const owner = moduleWithFile(db, request.file, space);
   if (owner !== undefined && owner.start !== request.start) {
     throw new Refusal("conflict", `The file ${request.file} already belongs to the module at ${formatC64Address(owner.start)}. Give this module another file, or remove that module first.`);
   }
   if (existing !== undefined) change.close("modules", "space = ? AND start_address = ?", space, request.start);
   change.insertModule({ space, start: request.start, file: request.file, ...(title === undefined ? {} : { title }), origin: origin as ModuleRow["origin"] });
-  return { current: moduleAt(db, request.start, space)! };
+  const current = moduleAt(db, request.start, space)!;
+  return existing !== undefined && existing.origin !== origin ? { current, previous: existing } : { current };
 }
 
 function unmoduleStep(db: DatabaseSync, change: Change, _origin: Origin, request: InSpace & { start: number }): Step<null> {
@@ -760,9 +795,10 @@ function patchStep(db: DatabaseSync, change: Change, context: ChangeContext & {
   const symbol = symbolNamed(db, request.switch, space);
   if (symbol !== undefined) throw new Refusal("conflict", `The switch name ${request.switch} is the name of the symbol at ${formatC64Address(symbol.address)}. Give the switch another name.`);
   if (space === DEFAULT_SPACE && context.image.platform.has(request.switch)) throw new Refusal("conflict", `The switch name ${request.switch} is a C64 platform name. Give the switch another name.`);
-  const other = patchesOverlapping(db, request.start, request.end, space).find((row) => row.start !== request.start);
+  // A write at the start of a patch of the same switch changes that patch; every other patch that it overlaps is a conflict.
+  const other = patchesOverlapping(db, request.start, request.end, space).find((row) => row.start !== request.start || row.switch !== request.switch);
   if (other !== undefined) {
-    throw new Refusal("conflict", `The patch ${range} overlaps the patch of ${other.switch} at ${formatC64Address(other.start)}-${formatC64Address(other.end)}. Change or remove that patch first (unpatch).`);
+    throw new Refusal("conflict", `The patch ${range} of ${request.switch} overlaps the patch of ${other.switch} at ${formatC64Address(other.start)}-${formatC64Address(other.end)}. A patch cannot overlap another patch, and only a patch of the same switch at the same start replaces it. Change or remove that patch first (unpatch).`);
   }
   const [use] = macroUsesOverlapping(db, request.start, request.end, space);
   if (use !== undefined) {
@@ -772,8 +808,8 @@ function patchStep(db: DatabaseSync, change: Change, context: ChangeContext & {
   const code = request.code.trimEnd();
   // A patch write without a comment keeps the comment it has, as a module keeps its title.
   const comment = request.comment === undefined ? existing?.comment : request.comment.trim();
-  if (existing !== undefined && existing.end === request.end && existing.switch === request.switch && existing.code === code && existing.comment === comment) return { current: existing };
   const origin = context.origin as PatchRow["origin"];
+  if (existing !== undefined && existing.end === request.end && existing.switch === request.switch && existing.code === code && existing.comment === comment && !confirms(existing.origin, origin)) return { current: existing };
   if (existing !== undefined) change.close("patches", "space = ? AND start_address = ?", space, request.start);
   change.insertPatch({ space, start: request.start, end: request.end, switch: request.switch, code, ...(comment === undefined ? {} : { comment }), origin });
   const current = patchesOverlapping(db, request.start, request.start, space).find((row) => row.start === request.start)!;
@@ -815,7 +851,7 @@ function macroStep(db: DatabaseSync, change: Change, origin: Origin, request: Ma
   const params = request.params ?? [];
   const body = request.body.trimEnd();
   const comment = request.comment === undefined ? existing?.comment : request.comment.trim();
-  if (existing !== undefined && listText(existing.params) === listText(params) && existing.body === body && existing.comment === comment) return { current: existing };
+  if (existing !== undefined && listText(existing.params) === listText(params) && existing.body === body && existing.comment === comment && !confirms(existing.origin, origin)) return { current: existing };
   if (existing !== undefined && existing.params.length !== params.length) {
     const uses = listMacroUses(db, undefined, request.name, undefined, space);
     if (uses.length > 0) {
@@ -901,8 +937,8 @@ function useStep(db: DatabaseSync, change: Change, context: ChangeContext & { im
     throw new Refusal("conflict", `The macro use ${range} overlaps the use of ${other.macro} at ${formatC64Address(other.start)}-${formatC64Address(other.end)}. Remove that use first (unuse).`);
   }
   const existing = macroUsesOverlapping(db, request.start, request.start, space).find((row) => row.start === request.start);
-  if (existing !== undefined && existing.end === request.end && existing.macro === request.macro && listText(existing.args) === listText(args)) return { current: existing };
   const origin = context.origin as MacroUseRow["origin"];
+  if (existing !== undefined && existing.end === request.end && existing.macro === request.macro && listText(existing.args) === listText(args) && !confirms(existing.origin, origin)) return { current: existing };
   if (existing !== undefined) change.close("macro_uses", "space = ? AND start_address = ?", space, request.start);
   change.insertMacroUse({ space, start: request.start, end: request.end, macro: request.macro, args, origin });
   const current = macroUsesOverlapping(db, request.start, request.start, space).find((row) => row.start === request.start)!;
@@ -940,7 +976,7 @@ export function unclassifyRegion(db: DatabaseSync, context: WriteContext, reques
   return result(write(db, context, "unclassify-region", (change) => unclassifyStep(db, change, context.origin, request)));
 }
 
-export function setComment(db: DatabaseSync, context: WriteContext, request: CommentRequest): WriteResult<CommentRow> {
+export function setComment(db: DatabaseSync, context: WriteContext, request: CommentRequest): WriteResult<CommentRow, CommentRow> {
   checkComment(request);
   return result(write(db, context, "set-comment", (change) => commentStep(db, change, context.origin, request)));
 }
@@ -950,7 +986,7 @@ export function removeComment(db: DatabaseSync, context: WriteContext, request:
   return result(write(db, context, "remove-comment", (change) => uncommentStep(db, change, context.origin, request)));
 }
 
-export function addReference(db: DatabaseSync, context: WriteContext, request: ReferenceRequest): WriteResult<ReferenceRow> {
+export function addReference(db: DatabaseSync, context: WriteContext, request: ReferenceRequest): WriteResult<ReferenceRow, ReferenceRow> {
   checkReference(request);
   return result(write(db, context, "add-reference", (change) => referenceStep(db, change, context.origin, request)));
 }
@@ -961,7 +997,7 @@ export function removeReference(db: DatabaseSync, context: WriteContext, request
 }
 
 /** Starts a file of the generated source at an address; one module per address and per file. */
-export function setModule(db: DatabaseSync, context: WriteContext, request: ModuleRequest): WriteResult<ModuleRow> {
+export function setModule(db: DatabaseSync, context: WriteContext, request: ModuleRequest): WriteResult<ModuleRow, ModuleRow> {
   checkModule(request);
   return result(write(db, context, "set-module", (change) => moduleStep(db, change, context.origin, request)));
 }
@@ -1053,7 +1089,7 @@ export const MAX_BATCH = 10_000;
 /** The result of each write of a batch, in order. */
 export type BatchStep = Step<
   SymbolRow | RegionRow[] | CommentRow | ReferenceRow | ModuleRow | OperandRow | PatchRow | MacroRow | MacroUseRow | null,
-  SymbolRow | RegionRow[] | OperandRow | PatchRow | MacroRow | MacroUseRow
+  SymbolRow | RegionRow[] | CommentRow | ReferenceRow | ModuleRow | OperandRow | PatchRow | MacroRow | MacroUseRow
 >;
 
 /**

package/src/mcp/output.ts

@@ -7,7 +7,7 @@ import { z } from "zod";
 
 import { projectFolder, writeReported, type Written } from "../host-client/transfer.ts";
 
-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");
+export const OutInput = z.string().min(1).describe("write the data to this file, relative to the project folder. An existing file is overwritten. The tool description tells what the result then gives");
 
 /** The project of a tool with a path. */
 export const ProjectInput = z

package/src/mcp/server.ts

@@ -10,6 +10,7 @@ import { z } from "zod";
 import { formatC64Address } from "../c64.ts";
 import { Byte, TOOL_INPUTS } from "./inputs.ts";
 import { LostBeforeAnswer, type ViceSessionClient } from "../host-client/vice-session.ts";
+import { checkOut } from "../host-client/transfer.ts";
 import { isRefusal } from "../errors.ts";
 import { shownMessage, WireFailure, type WireError } from "../protocol/messages.ts";
 import { COMPARISONS, CONDITION_REGISTERS, MEMORY_VIEWS, SPACES, type Condition } from "../protocol/vice.ts";
@@ -179,7 +180,10 @@ function errorResult(error: WireError): CallToolResult {
  * An unknown field of the tool input also gets the fields that the tool takes.
  */
 function describeIssues(error: z.ZodError, input?: z.ZodObject): string {
+  // An unknown field also breaks the rules that look at the whole object: name only the field.
+  const unknown = error.issues.some((issue) => issue.code === "unrecognized_keys");
   return error.issues
+    .filter((issue) => !unknown || issue.code !== "custom")
     .map((issue) => {
       const where = issue.path.length === 0 ? "input" : issue.path.join(".");
       const names = input === undefined ? [] : Object.keys(input.shape);
@@ -229,6 +233,9 @@ async function runCall(
   const parsed = tool.inputSchema.safeParse(args ?? {});
   if (!parsed.success) return errorResult({ code: "invalid-input", message: describeIssues(parsed.error, tool.inputSchema) });
   try {
+    // An out path is checked before the tool runs: a refused path must not lose the work or leave its side effects.
+    const fields = parsed.data as { out?: unknown; project?: unknown };
+    if (typeof fields.out === "string") checkOut(fields.out, typeof fields.project === "string" ? fields.project : undefined);
     let output: unknown;
     try {
       output = await tool.run(parsed.data, await session());

package/src/mcp/tools/debug.ts

@@ -186,7 +186,8 @@ export const c64Trace = defineTool({
     "Each hit gives the instruction (pc, bytes, text) and the registers a, x, y and sp before it. " +
     "point in a hit is the number of its point in points, 0 for the first. " +
     "It also gives the frame from 0, and the raster line and cycle where the instruction started. " +
-    "A read or write hit also gives the address that the instruction used, and the byte there after the access. " +
+    "A read or write hit also gives the address that the instruction used, and value, the byte that it read or wrote. " +
+    "At $D000-$DFFF only a load or a store gives value: a read after the access can give another byte. " +
     `The trace ends after frames frames (1 to ${MAX_TRACE_FRAMES}), at maxHits hits (at most ${MAX_TRACE_HITS}), or at a breakpoint, a watchpoint or a JAM. ` +
     `The result lists the first ${TRACE_LISTED} hits. With out, it writes all hits as JSON lines to that project file. ` +
     "Each hit stops the machine for a short time. Thus a point with many hits in each frame makes the trace slow. Use a small range and a maxHits. " +

package/src/mcp/tools/media.ts

@@ -44,6 +44,10 @@ export const c64Autostart = defineTool({
   }),
   readOnly: false,
   async run(input, session) {
+    const type = extname(input.path).slice(1).toLowerCase();
+    if (input.index !== undefined && !(DISK_TYPES as readonly string[]).includes(type)) {
+      throw new WireFailure("invalid-input", `index selects an entry of a disk image (${list(DISK_TYPES)}). A .${type} file has no directory: leave out index.`);
+    }
     // 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, root: projectFolder(input.project) });
   },
@@ -131,7 +135,7 @@ export const c64Snapshot = defineTool({
     }
     if (action === "restore" && fields.file !== undefined) {
       requireFields(action, fields, ["file", "project"], ["file"]);
-      return session.snapshotRestore(readProjectFile(fields.file, { root: projectFolder(fields.project) }).bytes);
+      return session.snapshotRestore(readProjectFile(fields.file, { root: projectFolder(fields.project), what: "file" }).bytes);
     }
     if (action === "save") {
       requireOut(fields);

package/src/media.ts

@@ -4,6 +4,9 @@
 
 import { Refusal } from "./errors.ts";
 
+/** The signature at the start of every VICE snapshot file (.vsf). */
+export const VSF_SIGNATURE = "VICE Snapshot File\x1a";
+
 /** The signature at the start of each media type that has one. */
 const SIGNATURES: Readonly<Record<string, readonly string[]>> = {
   crt: ["C64 CARTRIDGE   "],
@@ -11,6 +14,7 @@ const SIGNATURES: Readonly<Record<string, readonly string[]>> = {
   tap: ["C64-TAPE-RAW"],
   g64: ["GCR-1541"],
   p00: ["C64File"],
+  vsf: [VSF_SIGNATURE],
 };
 
 /** True when `bytes` start with a signature of `type`, or `type` has none. */
@@ -30,11 +34,22 @@ const SIZES: Readonly<Record<string, readonly number[]>> = {
 /** The x64 header: 64 bytes that start with these four, then a d64 image. */
 const X64_MAGIC = Buffer.from([0x43, 0x15, 0x41, 0x64]);
 
+/** The refusal of a file that is no VICE snapshot file (.vsf): its signature is missing. `path` names the file. */
+export function checkSnapshotFile(path: string, bytes: Uint8Array): void {
+  if (!hasSignature("vsf", bytes)) throw new Refusal("invalid-input", `${path} is not a VICE snapshot file (.vsf): it does not start with "VICE Snapshot File". Give a file that c64_snapshot save or a save step of a run wrote.`);
+}
+
 /** Refuses a file whose bytes are not of `type` (its extension), with media-error. */
 export function checkMedia(type: string, bytes: Buffer): void {
   const refuse = (why: string) => {
     throw new Refusal("media-error", `The file is not a valid .${type} file: ${why}. Give a file of that type.`);
   };
+  if (type === "crt" && hasSignature(type, bytes)) {
+    // The header gives its own length; a CHIP packet with the ROM data follows it.
+    const header = bytes.length >= 0x40 ? bytes.readUInt32BE(0x10) : 0;
+    if (bytes.length < 0x40) refuse("the header is shorter than 64 bytes");
+    if (bytes.toString("latin1", header, header + 4) !== "CHIP") refuse("it has no CHIP packet with ROM data after the header");
+  }
   if (!hasSignature(type, bytes)) refuse(`it does not start with ${SIGNATURES[type]!.map((signature) => `"${signature.trimEnd()}"`).join(" or ")}`);
   const sizes = SIZES[type];
   if (sizes !== undefined && !sizes.includes(bytes.length)) refuse(`it has ${bytes.length} bytes, and a .${type} image has ${sizes.join(", ")}`);

package/src/opcodes.ts

@@ -76,6 +76,34 @@ 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 byte that an instruction wrote to or read from its operand address:
+ * a store gives its register, a load the register after it. For another
+ * access the byte at the address now (`memoryNow`) is the byte, when the
+ * caller can read it back. Undefined when it is not known.
+ */
+export function accessedValue(opcode: number, before: { a: number; x: number; y: number }, after: { a: number; x: number; y: number }, memoryNow: number | undefined): number | undefined {
+  switch (OPCODES[opcode]!.mnemonic) {
+    case "sta":
+      return before.a;
+    case "stx":
+      return before.x;
+    case "sty":
+      return before.y;
+    case "sax":
+      return before.a & before.x;
+    case "lda":
+    case "lax":
+      return after.a;
+    case "ldx":
+      return after.x;
+    case "ldy":
+      return after.y;
+    default:
+      return memoryNow;
+  }
+}
+
 /** 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]!;
@@ -130,7 +158,9 @@ export function operandNumber(bytes: readonly number[], pc: number): string {
 /** The text of the instruction in `bytes` at `pc` as the monitor shows it, for example "STA $d011" or "BNE $c002". */
 export function instructionText(bytes: readonly number[], pc: number): string {
   const { mnemonic } = OPCODES[bytes[0]!]!;
-  return `${mnemonic.toUpperCase()}${instructionWith(bytes[0]!, operandNumber(bytes, pc)).slice(mnemonic.length)}`;
+  const operand = instructionWith(bytes[0]!, operandNumber(bytes, pc)).slice(mnemonic.length);
+  // The monitor writes the index register in capitals: LDA ($c1),Y.
+  return `${mnemonic.toUpperCase()}${operand.replace(/,([xy])\b/g, (_, index: string) => `,${index.toUpperCase()}`)}`;
 }
 
 /**

package/src/platform.ts

@@ -3,7 +3,7 @@
 // Names follow "Mapping the Commodore 64". Only platform facts live here:
 // an address without one belongs to the application.
 
-import { d018Offsets, formatC64Address, vicBankBase } from "./c64.ts";
+import { COVERAGE, d018Offsets, formatC64Address, vicBankBase } from "./c64.ts";
 import { Refusal } from "./errors.ts";
 
 export interface Entry {
@@ -420,6 +420,19 @@ export function romUseOfPort(port: number): RomUse {
   return { basic: (port & 0x03) === 0x03, kernal: (port & 0x02) !== 0 };
 }
 
+/**
+ * The ROMs that a program uses, and what tells it: the coverage when the
+ * knowledge has it, else $01 of the entry state, else both ROMs. c64-source and
+ * c64-static-analysis give the platform names of platformNamesFor of it, so
+ * they use the same names.
+ */
+export function romUseOfProgram(coverage: Uint8Array | undefined, state: Record<string, unknown> | undefined): RomUse & { from: "coverage" | "entry state" | "none" } {
+  if (coverage !== undefined) return { ...romUseOf(coverage, COVERAGE.romExecute), from: "coverage" };
+  const port = (state?.cpuPort as Record<string, unknown> | undefined)?.$01;
+  if (typeof port === "number") return { ...romUseOfPort(port), from: "entry state" };
+  return { basic: true, kernal: true, from: "none" };
+}
+
 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

@@ -37,8 +37,13 @@ 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;
 
+/** True when `folder` holds .c64-re-tools/. A folder that cannot be read (no permission) is not a project. */
 function isProject(folder: string): boolean {
-  return statSync(join(folder, PROJECT_DIRECTORY), { throwIfNoEntry: false })?.isDirectory() === true;
+  try {
+    return statSync(join(folder, PROJECT_DIRECTORY), { throwIfNoEntry: false })?.isDirectory() === true;
+  } catch {
+    return false;
+  }
 }
 
 /** `start` and each folder above it, nearest first, below the home folder when `start` is under it. */
@@ -277,6 +282,8 @@ export function checkOutputPath(path: string, kind: OutputKind, options: { root?
   const stat = statSync(real);
   if (existing === target && kind === "file") {
     if (stat.isDirectory()) throw problem({ code: "EISDIR" });
+  } else if (existing === target && !stat.isDirectory()) {
+    throw new Refusal("invalid-input", `${what === undefined ? "" : `${what}: `}${path} is a file, but ${what ?? "the path"} needs a folder. Give the path of a folder, or a new path for the folder.`);
   } else if (!stat.isDirectory()) {
     throw problem({ code: "ENOTDIR" });
   }

package/src/script.ts

@@ -428,6 +428,65 @@ function refuseSplitRange(command: CommandSpec, options: Readonly<Record<string,
   }
 }
 
+/** The options of a command for a message: --a, --b and --c, or a word that it has none. */
+function optionList(options: Readonly<Record<string, OptionSpec>>): string {
+  const names = Object.keys(options).map((name) => `--${name}`);
+  if (names.length === 0) return "It takes no options";
+  return `Its options are ${names.length === 1 ? names[0] : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`}`;
+}
+
+/** True for a word that the command line reads as an option: - and one or more characters. A lone - is a subject (standard input). */
+const isOptionWord = (word: string) => word.length > 1 && word.startsWith("-");
+
+/**
+ * Refuses the words of a command line that parseArgs refuses, with a message
+ * that names the option and tells what to give: an option that the command
+ * does not have, a flag with a value, an option without its value, a value
+ * that starts with -, and a range option in two parts.
+ */
+function refuseOptionWords(command: CommandSpec, options: Readonly<Record<string, OptionSpec>>, argv: readonly string[]): void {
+  const end = argv.indexOf("--");
+  const words = end < 0 ? argv : argv.slice(0, end);
+  for (let index = 0; index < words.length; index++) {
+    const word = words[index]!;
+    if (!isOptionWord(word)) continue;
+    if (!word.startsWith("--")) {
+      throw new UsageError(`${word} is not an option of ${command.name}: an option starts with --. ${optionList(options)}. Give a subject that starts with - after --, for example -- ${word}`);
+    }
+    const equals = word.indexOf("=");
+    const name = equals < 0 ? word.slice(2) : word.slice(2, equals);
+    const spec = options[name];
+    if (spec === undefined) throw new UsageError(`${command.name} has no option --${name}. ${optionList(options)}`);
+    if (spec.kind === "flag") {
+      if (equals >= 0) throw new UsageError(`--${name} is a flag: give --${name} without a value`);
+      continue;
+    }
+    let value: string;
+    let valueIndex = index;
+    if (equals >= 0) {
+      value = word.slice(equals + 1);
+    } else {
+      valueIndex = index + 1;
+      const next = words[valueIndex];
+      if (next === undefined) throw new UsageError(`--${name} needs a value: give --${name} ${spec.value ?? "<value>"}`);
+      if (isOptionWord(next)) {
+        if ((spec.kind === "count" || spec.kind === "number") && /^-\d/.test(next)) {
+          const range = spec.kind === "count" ? `a whole number from ${spec.min ?? 0} to ${spec.max ?? Number.MAX_SAFE_INTEGER}` : `a number from ${spec.min ?? 0} to ${spec.max ?? 0xffff}`;
+          throw new UsageError(`--${name} must be ${range}, not ${JSON.stringify(next)}`);
+        }
+        throw new UsageError(`--${name} needs a value: give --${name} ${spec.value ?? "<value>"}, not ${next}. Give a value that starts with - as --${name}=${next}`);
+      }
+      value = next;
+      index++;
+    }
+    // A range option in two parts: --range '$1bc2' '$1c00'.
+    const second = words[valueIndex + 1];
+    if (spec.kind === "range" && rangeParts(value) === undefined && isAddressText(value) && second !== undefined && c64AddressOf(second) !== undefined) {
+      throw new UsageError(`--${name} is one token <start>-<end>: give --${name} '${value}-${second}', not '${value}' '${second}'`);
+    }
+  }
+}
+
 /**
  * Refuses an output path before the command does any work: a path that
  * leaves the project, a path in the knowledge, a folder where a file must be,
@@ -442,6 +501,7 @@ function checkOutput(text: string, what: string, kind: OutputKind): void {
 export function parseCall(script: ScriptSpec, command: CommandSpec, argv: readonly string[]): Call {
   const options = commandOptions(command);
   refuseSplitRange(command, options, argv);
+  refuseOptionWords(command, options, argv);
   let parsed: ReturnType<typeof parseArgs>;
   try {
     parsed = parseArgs({
@@ -450,8 +510,9 @@ export function parseCall(script: ScriptSpec, command: CommandSpec, argv: readon
       allowPositionals: true,
       options: Object.fromEntries(Object.entries(options).map(([name, spec]) => [name, { type: spec.kind === "flag" ? "boolean" : "string", ...(spec.multiple ? { multiple: true } : {}) }])),
     });
-  } catch (error) {
-    throw new UsageError((error as Error).message);
+  } catch {
+    // refuseOptionWords gives a message of its own for each word that parseArgs refuses; this is the last guard.
+    throw new UsageError(`the command line of ${command.name} is not correct. Give each option as --name <value>, each flag as --name, and a subject that starts with - after --`);
   }
   const values = parsed.values as Record<string, string | boolean | string[] | undefined>;
   const subjects = parsed.positionals;