@henols/c64-re-tools 2.1.1 → 2.1.3

package/src/media.ts

@@ -0,0 +1,57 @@
+// Media file signatures and sizes. The host checks a file with them before
+// VICE gets it: VICE takes a file that is not of its type in another way, and
+// a CRT or T64 that it cannot read loads as a PRG with a successful autostart.
+
+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   "],
+  t64: ["C64"],
+  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. */
+export function hasSignature(type: string, bytes: Uint8Array): boolean {
+  const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const signatures = SIGNATURES[type];
+  return signatures === undefined || signatures.some((signature) => buffer.toString("latin1", 0, signature.length) === signature);
+}
+
+/** The file sizes that VICE reads for each disk image type without a signature. */
+const SIZES: Readonly<Record<string, readonly number[]>> = {
+  d64: [174848, 175531, 196608, 197376, 205312, 206114],
+  d71: [349696, 351062],
+  d81: [819200, 822400],
+};
+
+/** 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(", ")}`);
+  if (type === "x64" && (!bytes.subarray(0, 4).equals(X64_MAGIC) || !SIZES.d64!.includes(bytes.length - 64))) refuse("it has no x64 header before a d64 image");
+}

package/src/opcodes.ts

@@ -4,7 +4,7 @@
 // spelling, ACME writes only one of them: the generator finds those with a
 // probe and writes the others as bytes.
 
-import { formatC64Byte, formatC64Address } from "./c64.ts";
+import { formatC64Byte, formatC64Address, SYMBOL_NAME } from "./c64.ts";
 
 export type Mode = "imp" | "imm" | "zp" | "zpx" | "zpy" | "abs" | "abx" | "aby" | "ind" | "izx" | "izy" | "rel";
 
@@ -45,6 +45,17 @@ export const MODE_LENGTH: Record<Mode, 1 | 2 | 3> = { imp: 1, imm: 2, zp: 2, zpx
 /** Every mnemonic in the table: a symbol with one of these names would read as an instruction. */
 export const MNEMONICS: ReadonlySet<string> = new Set(OPCODES.map((opcode) => opcode.mnemonic));
 
+/**
+ * Why ACME cannot take a name as a label, or undefined when it can. A label
+ * has label syntax (SYMBOL_NAME) and is no mnemonic in upper or lower case.
+ * The one rule for a symbol of the knowledge and a label of c64-source.
+ */
+export function labelProblem(name: string): string | undefined {
+  if (!SYMBOL_NAME.test(name)) return "A symbol name is a letter or underscore, then letters, digits or underscores (at most 64), with an optional leading dot.";
+  if (MNEMONICS.has(name.toLowerCase())) return `${name} is the name of a 6502 instruction, which ACME cannot read as a label. Give another name.`;
+  return undefined;
+}
+
 const ZERO_PAGE_OF: Partial<Record<Mode, Mode>> = { abs: "zp", abx: "zpx", aby: "zpy" };
 
 /** True when the mnemonic also has the zero-page form of an absolute mode: ACME would pick it for a small operand. */
@@ -65,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]!;
@@ -78,26 +117,50 @@ export function useKind(opcode: number): UseKind {
 }
 
 
-/** 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);
+/**
+ * The ACME text of an instruction with its operand as an expression: the
+ * mnemonic, the size suffix (+1 or +2, or none) and the operand in the syntax
+ * of its addressing mode, for example "lda #<table", "sta screen,x" or
+ * "lda (pointer),y". ACME reads an operand in brackets as indirect, so a
+ * non-immediate expression that starts with a bracket gets 0+ in front.
+ * The one place that writes an instruction: the generated source, the
+ * listing of the knowledge and the disassembly of the emulator use it.
+ */
+export function instructionWith(opcode: number, expression: string, suffix = ""): string {
+  const { mnemonic, mode } = OPCODES[opcode]!;
+  const value = mode !== "imm" && expression.startsWith("(") ? `0+${expression}` : expression;
   const operand: Record<Mode, string> = {
     imp: "",
-    imm: `#${formatC64Byte(low)}`,
-    zp: formatC64Byte(low),
-    zpx: `${formatC64Byte(low)},x`,
-    zpy: `${formatC64Byte(low)},y`,
-    abs: formatC64Address(word),
-    abx: `${formatC64Address(word)},x`,
-    aby: `${formatC64Address(word)},y`,
-    ind: `(${formatC64Address(word)})`,
-    izx: `(${formatC64Byte(low)},x)`,
-    izy: `(${formatC64Byte(low)}),y`,
-    rel: formatC64Address((pc + 2 + (low < 0x80 ? low : low - 0x100)) & 0xffff),
+    imm: `#${value}`,
+    zp: value,
+    zpx: `${value},x`,
+    zpy: `${value},y`,
+    abs: value,
+    abx: `${value},x`,
+    aby: `${value},y`,
+    ind: `(${value})`,
+    izx: `(${value},x)`,
+    izy: `(${value}),y`,
+    rel: value,
   };
-  return operand[mode] === "" ? mnemonic : `${mnemonic} ${operand[mode]}`;
+  return operand[mode] === "" ? `${mnemonic}${suffix}` : `${mnemonic}${suffix} ${operand[mode]}`;
+}
+
+/** The value of the operand of the instruction in `bytes` at `pc` as a number: a byte, a word, or the target of a branch. Empty for no operand. */
+export function operandNumber(bytes: readonly number[], pc: number): string {
+  const { mode } = OPCODES[bytes[0]!]!;
+  const low = bytes[1] ?? 0;
+  if (mode === "imp") return "";
+  if (mode === "rel") return formatC64Address((pc + 2 + (low < 0x80 ? low : low - 0x100)) & 0xffff);
+  return MODE_LENGTH[mode] === 3 ? formatC64Address(low | ((bytes[2] ?? 0) << 8)) : formatC64Byte(low);
+}
+
+/** 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]!]!;
+  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

@@ -5,7 +5,7 @@
 // the agent saves for itself and ignores itself in git.
 
 import { Refusal } from "./errors.ts";
-import { existsSync, mkdirSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { accessSync, constants, existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
@@ -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. */
@@ -117,7 +122,8 @@ export function namedProject(folder: string, cwd: string = process.cwd()): strin
   if (stat === undefined) throw new Refusal("not-found", `There is no folder ${folder}.`);
   if (!stat.isDirectory()) throw new Refusal("invalid-input", `${folder} is not a folder.`);
   if (path === homedir()) throw new Refusal("invalid-input", "The home folder is not a project folder.");
-  const outer = foldersUpFrom(path).slice(1).find(isProject);
+  // A project inside another project is a project of its own, as the lookup from a working directory in it finds.
+  const outer = isProject(path) ? undefined : foldersUpFrom(path).slice(1).find(isProject);
   if (outer !== undefined) {
     throw new Refusal("invalid-input", `${folder} is inside the project ${relative(cwd, outer) || outer}. Give that project folder.`);
   }
@@ -180,6 +186,115 @@ export function resolveProjectPath(path: string, root = projectRoot()): string {
   throw new Refusal("invalid-input", `${path} leads out of the project folder: give a path that stays inside it.`);
 }
 
+/** The folder of the committed knowledge text in PROJECT_DIRECTORY. The knowledge (src/knowledge/database.ts) has the same name. */
+export const KNOWLEDGE_TEXT_DIRECTORY = "knowledge";
+
+/** The index of the knowledge in LOCAL_DIRECTORY, and the files that SQLite keeps beside it. The knowledge has the same name. */
+const KNOWLEDGE_INDEX = /^knowledge\.db(?:-wal|-shm|-journal)?$/;
+
+/**
+ * The part of the knowledge that a path relative to the project folder is in:
+ * the text in .c64-re-tools/knowledge/ or the index in .c64-re-tools/local/.
+ * Undefined for every other path. Letter case does not count: some file
+ * systems do not tell the cases apart.
+ */
+export function knowledgePart(fromRoot: string): string | undefined {
+  const parts = fromRoot.split(/[\\/]+/).filter((part) => part !== "" && part !== ".").map((part) => part.toLowerCase());
+  if (parts[0] !== PROJECT_DIRECTORY) return undefined;
+  if (parts[1] === KNOWLEDGE_TEXT_DIRECTORY) return `${PROJECT_DIRECTORY}/${KNOWLEDGE_TEXT_DIRECTORY}/`;
+  if (parts[1] === LOCAL_DIRECTORY && parts.length === 3 && KNOWLEDGE_INDEX.test(parts[2]!)) return `${PROJECT_DIRECTORY}/${LOCAL_DIRECTORY}/${parts[2]}`;
+  return undefined;
+}
+
+/** What a command writes at an output path: one file, or files in a folder. */
+export type OutputKind = "file" | "folder";
+
+/** Why a file cannot be written, by the error code of the file system; the codes that are a fault of the path. */
+const WRITE_PROBLEMS: Record<string, string> = {
+  EISDIR: "is a folder. Give the path of a file",
+  EEXIST: "has a file where a folder must be. Give a path whose folders are folders",
+  ENOTDIR: "has a file where a folder must be. Give a path whose folders are folders",
+  ENOENT: "is in a folder that does not exist",
+  EACCES: "cannot be written: there is no permission. Give a path that you can write",
+  EPERM: "cannot be written: there is no permission. Give a path that you can write",
+  EROFS: "is on a file system that is read-only. Give another path",
+  ENAMETOOLONG: "is too long. Give a shorter path",
+};
+
+/**
+ * The message for a write that the file system refused because of the path
+ * (a folder, a file in place of a folder, no permission): the path and what
+ * to do. Undefined for another error, which is no fault of the path.
+ */
+export function writeProblem(error: unknown, path: string, what?: string): string | undefined {
+  const problem = WRITE_PROBLEMS[(error as NodeJS.ErrnoException | undefined)?.code ?? ""];
+  return problem === undefined ? undefined : `${what === undefined ? "" : `${what}: `}${path} ${problem}.`;
+}
+
+/**
+ * Checks a path that a command writes, before the command does any work. The
+ * path must stay inside the project, also through symbolic links, and must
+ * not be in the knowledge (only the c64-knowledge skill writes it). A file
+ * must not be a folder or a symbolic link; a folder must be a folder. The
+ * nearest folder that exists must be a folder that can be written. Returns
+ * the absolute path. Throws a Refusal (invalid-input) whose message starts
+ * with `what` (for example --out). writeProjectFile does the same check for
+ * each file that it writes.
+ */
+export function checkOutputPath(path: string, kind: OutputKind, options: { root?: string; what?: string } = {}): string {
+  const root = options.root ?? projectRoot();
+  const what = options.what;
+  const outside = () => new Refusal("invalid-input", `${what ?? path}: give a path relative to the project folder that stays inside it, not ${path}.`);
+  const problem = (error: unknown) => {
+    const message = writeProblem(error, path, what);
+    return message === undefined ? error : new Refusal("invalid-input", message);
+  };
+  const inKnowledge = (fromRoot: string) => {
+    const part = knowledgePart(fromRoot);
+    if (part !== undefined) {
+      throw new Refusal("invalid-input", `${what === undefined ? "" : `${what}: `}${path} is in ${part}, the knowledge of the project. Only the c64-knowledge skill writes it: a write there destroys the knowledge. Give a path outside ${PROJECT_DIRECTORY}/${KNOWLEDGE_TEXT_DIRECTORY}/, for example ${PROJECT_DIRECTORY}/${LOCAL_DIRECTORY}/<file>.`);
+    }
+  };
+  let target: string;
+  try {
+    target = resolveProjectPath(path, root);
+  } catch {
+    throw outside();
+  }
+  inKnowledge(relative(root, target));
+  // The nearest entry that exists: the path itself, or a folder above it.
+  let existing = target;
+  for (;;) {
+    let found;
+    try {
+      found = lstatSync(existing, { throwIfNoEntry: false });
+    } catch (error) {
+      throw problem(error);
+    }
+    if (found !== undefined) break;
+    existing = dirname(existing);
+  }
+  const realRoot = realpathSync(root);
+  if (existing === target && kind === "file" && lstatSync(target).isSymbolicLink()) throw outside();
+  const real = realpathSync(existing);
+  if (!isInside(realRoot, real)) throw outside();
+  inKnowledge(relative(realRoot, join(real, relative(existing, target))));
+  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" });
+  }
+  try {
+    accessSync(real, constants.W_OK);
+  } catch (error) {
+    throw problem(error);
+  }
+  return target;
+}
+
 /** A project path in one spelling: relative to the project folder, with / and without ./, .. or a double /. Refuses a path as resolveProjectPath does. */
 export function projectRelative(path: string, root = projectRoot()): string {
   return relative(root, resolveProjectPath(path, root)).split(sep).join("/");

package/src/protocol/vice.ts

@@ -385,6 +385,8 @@ export interface MachineStatus {
   stopReason?: PointStopReason;
   /** The id of the breakpoint or watchpoint that stopped the machine. */
   pointId?: number;
+  /** With pc: the CPU whose address pc is, drive8 when a point in the drive stopped the machine. */
+  space?: "c64" | "drive8";
 }
 
 /** What stopped the machine outside a request that stops it. */
@@ -1092,7 +1094,8 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         (value.pc === undefined || isInteger(value.pc, 0, 0xffff)) &&
         typeof value.cartridge === "boolean" &&
         (value.stopReason === undefined || isOneOf(POINT_STOP_REASONS, value.stopReason)) &&
-        (value.pointId === undefined || isInteger(value.pointId, 1, Number.MAX_SAFE_INTEGER));
+        (value.pointId === undefined || isInteger(value.pointId, 1, Number.MAX_SAFE_INTEGER)) &&
+        (value.space === undefined || isOneOf(SPACES, value.space));
       if (!ok) throw new ProtocolError("status result is malformed");
       break;
     }

package/src/script.ts

@@ -13,7 +13,7 @@ import { parseArgs } from "node:util";
 
 import { c64AddressOf, formatC64Address, SPACE_PATTERN, SYMBOL_NAME, type AddressRange } from "./c64.ts";
 import { isRefusal, Refusal, type ErrorCode } from "./errors.ts";
-import { projectRoot, resolveProjectPath, useProject } from "./project.ts";
+import { checkOutputPath, projectRoot, resolveProjectPath, useProject, type OutputKind } from "./project.ts";
 import { shownMessage } from "./protocol/messages.ts";
 import { elapsedMs, startTrace, trace, type TraceFields } from "./trace.ts";
 
@@ -59,6 +59,12 @@ export interface OptionSpec {
   max?: number;
   /** The value when the option is not given. */
   default?: number | string;
+  /**
+   * path only: the command writes there, a file or files in a folder. The
+   * path is checked before the command runs (checkOutputPath). Every option
+   * --out and --out-<name> has it.
+   */
+  output?: OutputKind;
 }
 
 /** The options that have one meaning in every script. A command can change the help, the value and whether it is required, never the kind. */
@@ -157,7 +163,7 @@ export class Call {
 
   /** The knowledge space of the command: --space, else c64. */
   get space(): string {
-    return "space" in this.#options ? this.string("space")! : "c64";
+    return ("space" in this.#options ? this.string("space") : undefined) ?? "c64";
   }
 
   /** Subject `index` as text. */
@@ -339,6 +345,8 @@ function commandOptions(command: CommandSpec): Record<string, OptionSpec> {
     const shared = (OPTIONS as Record<string, OptionSpec>)[name];
     if (shared !== undefined && shared.kind !== spec.kind) throw fault(`--${name} of ${command.name} is a ${spec.kind}, but OPTIONS has it as a ${shared.kind}`);
     if (name === "help" || name === "project") throw fault(`--${name} of ${command.name}: the contract owns this option`);
+    if (spec.kind === "path" && (name === "out" || name.startsWith("out-")) && spec.output === undefined) throw fault(`--${name} of ${command.name} has no output kind (file or folder)`);
+    if (spec.output !== undefined && spec.kind !== "path") throw fault(`--${name} of ${command.name} has an output kind, but it is a ${spec.kind}, not a path`);
   }
   return options;
 }
@@ -391,9 +399,109 @@ function checkPath(text: string, what: string): void {
   }
 }
 
+/**
+ * Refuses a range in two parts: two subjects '$1bc2' '$1bd0' where the command
+ * takes one <range>, or --start and --end where it takes a range option. The
+ * message gives the range as one token.
+ */
+function refuseSplitRange(command: CommandSpec, options: Readonly<Record<string, OptionSpec>>, argv: readonly string[], subjects?: readonly string[]): void {
+  if (subjects === undefined) {
+    const end = argv.indexOf("--");
+    const words = end < 0 ? argv : argv.slice(0, end);
+    const valueOf = (name: string) => {
+      const index = words.findIndex((word) => word === `--${name}` || word.startsWith(`--${name}=`));
+      if (index < 0) return undefined;
+      const word = words[index]!;
+      return word.includes("=") ? word.slice(word.indexOf("=") + 1) : (words[index + 1] ?? "");
+    };
+    const [start, last] = [valueOf("start"), valueOf("end")];
+    const range = Object.entries(options).find(([, spec]) => spec.kind === "range")?.[0];
+    if ((start === undefined && last === undefined) || range === undefined || "start" in options || "end" in options) return;
+    throw new UsageError(`${command.name} takes no --start or --end. Give the range as one option: --${range} '${start || "<start>"}-${last || "<end>"}'`);
+  }
+  const specs = command.subjects ?? [];
+  for (let index = 0; index + 1 < subjects.length; index++) {
+    const spec = specs[Math.min(index, specs.length - 1)];
+    const [first, second] = [subjects[index]!, subjects[index + 1]!];
+    if (spec === undefined || !spec.name.includes("range") || rangeParts(first) !== undefined || !isAddressText(first) || c64AddressOf(second) === undefined) continue;
+    throw new UsageError(`${spec.name} is one token <start>-<end>: give '${first}-${second}', not '${first}' '${second}'`);
+  }
+}
+
+/** 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,
+ * a file where a folder must be, or a folder that cannot be written.
+ */
+function checkOutput(text: string, what: string, kind: OutputKind): void {
+  checkPath(text, what);
+  checkOutputPath(text, kind, { root: projectRoot(), what });
+}
+
 /** Parses the command line of one command. Refuses a wrong count of subjects, an unknown option, a missing required option or a value of the wrong form. */
 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({
@@ -402,11 +510,13 @@ 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;
+  refuseSplitRange(command, options, argv, subjects);
   const specs = command.subjects ?? [];
   const last = specs.at(-1);
   const least = specs.filter((subject) => !subject.optional).length;
@@ -428,7 +538,10 @@ export function parseCall(script: ScriptSpec, command: CommandSpec, argv: readon
       if (spec.kind === "range" && rangeParts(text) === undefined) throw new UsageError(`--${name} must be <start>-<end>, each ${ADDRESS_FORM}, for example '$c000-$cfff', not ${JSON.stringify(text)}`);
       if (spec.kind === "space" && !SPACE_PATTERN.test(text)) throw new UsageError(`--${name} must be c64, drive8, or bank0 to bank255, not ${JSON.stringify(text)}`);
       if (spec.kind === "choice" && !(spec.choices ?? []).includes(text)) throw new UsageError(`--${name} must be one of ${(spec.choices ?? []).join(", ")}, not ${JSON.stringify(text)}`);
-      if (spec.kind === "path") checkPath(text, `--${name}`);
+      if (spec.kind === "path") {
+        if (spec.output === undefined) checkPath(text, `--${name}`);
+        else checkOutput(text, `--${name}`, spec.output);
+      }
     }
   }
   const call = new Call(script.name, command.name, subjects, options, values, script.names);