@rpgm-tools/neo-angband-core 0.10.0

package/src/host/io.ts

@@ -0,0 +1,239 @@
+/**
+ * The host layer: z-file.c's file access and init.c's directory set, as an
+ * interface core can be handed instead of a platform it has to guess at.
+ *
+ * WHY THIS EXISTS
+ *
+ * Upstream is not a browser program that happens to run on desktops; it is a
+ * desktop program with several front ends (main-sdl2.c, main-gcu.c, main-win.c)
+ * over ONE host layer (z-file.c) and ONE directory set (init.c's ANGBAND_DIR_*).
+ * The port had the first half of that - a platform-agnostic core with the front
+ * end in packages/web - but no second half: every feature that needed a file
+ * asked the browser, got "no", and was then quietly reshaped to fit the answer.
+ *
+ * That reshaping is the bug. Measured on 2026-07-28, 18 of the 35 remaining
+ * text-census absences exist only because there is no host filesystem, no argv
+ * and no process to receive a signal - not because the C was hard to read. And
+ * the damage is not limited to absences: a platform limit that goes unmodelled
+ * turns into an invented stand-in (the "use the CLI" spoiler line, the PNG
+ * screen dump), which is worse, because a stand-in FILLS the slot and neither
+ * census can see it.
+ *
+ * So the host is a first-class, injectable seam with three adapters:
+ *
+ *   - desktop (Electron main process, real node:fs)  - full capability
+ *   - cli     (node:fs directly)                     - full capability
+ *   - web     (localStorage, one key per file)       - reduced, and SAYS so
+ *
+ * THE RULE THIS ENCODES: the reference C defines the semantics. A front end
+ * either expresses them or is recorded as reduced, via `capabilities`. What a
+ * front end cannot do must never edit what the game IS.
+ */
+
+/** file_mode (z-file.h L113-118). */
+export enum FileMode {
+  WRITE = 0,
+  READ = 1,
+  APPEND = 2,
+}
+
+/**
+ * file_type (z-file.h L123-129). Upstream passes this so systems without file
+ * extensions can tag the file; it reaches the platform through file_open_hook.
+ * Kept because the HTML tag distinguishes the screen dump and disconnect.html
+ * from the text dumps, and a host may want to act on that.
+ */
+export enum FileType {
+  TEXT = 1,
+  SAVE = 2,
+  RAW = 3,
+  HTML = 4,
+}
+
+/**
+ * init.c's ANGBAND_DIR_* (init.h L229-241), minus the read-only gamedata roots
+ * the port ships as bundled JSON rather than a tree on disk. These five are the
+ * ones the game WRITES to, which is exactly the set a browser cannot provide.
+ */
+export enum HostDir {
+  /** ANGBAND_DIR_USER: dumps, pref files, lore.txt, spoilers, the dev logs. */
+  USER = "user",
+  /** ANGBAND_DIR_SAVE: one savefile per character. */
+  SAVE = "save",
+  /** ANGBAND_DIR_PANIC: the signal handler's separate savefile. */
+  PANIC = "panic",
+  /** ANGBAND_DIR_SCORES: the shared score list. */
+  SCORES = "scores",
+  /** ANGBAND_DIR_ARCHIVE: retired characters' savefiles. */
+  ARCHIVE = "archive",
+}
+
+/**
+ * What a host can actually do. A screen reads this to decide which of
+ * upstream's paths it can take; it must NEVER be used to decide what the game
+ * means. Every field is a statement about the platform, not about the port.
+ */
+export interface HostCapabilities {
+  /**
+   * Files persist somewhere the user can see and other programs can reach. On
+   * the web adapter this is false: localStorage is private to the origin and
+   * evictable, so a mod manager cannot deploy into it and a "clear browsing
+   * data" destroys it.
+   */
+  readonly realFiles: boolean;
+  /** A process command line exists (main.c's switches: -f, -u, -w, -p, ...). */
+  readonly argv: boolean;
+  /** The host can be told the process is dying, so a panic save can be written. */
+  readonly signals: boolean;
+  /**
+   * More than one terminal window can exist. Upstream's ANGBAND_TERM_MAX is 8
+   * (ui-term.h:244); a single canvas is 1, which is why the port's subwindow
+   * setup, its window: pref directive and its option_dump are all hollow.
+   */
+  readonly termCount: number;
+  /** Directories can be listed and watched, so an on-disk mod tree can be found. */
+  readonly directories: boolean;
+}
+
+/**
+ * The write outcomes upstream's callers distinguish. file_open failing and
+ * file_close failing are reported with DIFFERENT messages at the same call site
+ * (wiz-spoil.c: "Cannot create spoiler file." vs "Cannot close spoiler file."),
+ * so a host must be able to tell them apart rather than returning one boolean.
+ */
+export type WriteOutcome = "ok" | "create-failed" | "close-failed";
+
+/**
+ * z-file.c's file access, per directory. Paths are LEAF names within a HostDir,
+ * not host paths: core never composes a path (that is path_build's job, and it
+ * is host-specific), and a leaf-only API cannot traverse out of its directory.
+ */
+export interface HostIo {
+  /** What this host can do. Checked, never assumed. */
+  readonly capabilities: HostCapabilities;
+
+  /**
+   * path_build(dir, name) purely for DISPLAY - the text upstream prints in
+   * prompts and messages ("Cannot open '%s'."). Never used to open anything.
+   */
+  displayPath(dir: HostDir, name: string): string;
+
+  /** file_exists (z-file.h L135). */
+  exists(dir: HostDir, name: string): boolean;
+
+  /** file_open(MODE_READ) + a file_getl loop: the whole text, or null if absent. */
+  read(dir: HostDir, name: string): string | null;
+
+  /**
+   * file_open(mode, ftype) + file_put + file_close, as one call. The two
+   * failure modes stay distinct; see WriteOutcome.
+   */
+  write(
+    dir: HostDir,
+    name: string,
+    text: string,
+    mode?: FileMode,
+    ftype?: FileType,
+  ): WriteOutcome;
+
+  /** file_delete (z-file.h L145). */
+  remove(dir: HostDir, name: string): boolean;
+
+  /** file_move (z-file.h L169). */
+  move(dir: HostDir, from: string, to: string): boolean;
+
+  /**
+   * file_newer (z-file.h L174). This is the gate on upstream's panic-save
+   * prompt (ui-game.c:709-720), so a host without timestamps must say so rather
+   * than guess: null means "cannot tell", which is not the same as false.
+   */
+  newer(dir: HostDir, first: string, second: string): boolean | null;
+
+  /** The directory listing. Upstream reaches this through its platform layer. */
+  list(dir: HostDir): string[];
+
+  /**
+   * main.c's argv, minus the program name. Empty when capabilities.argv is
+   * false - which is why ui-player.c:1250's "You are not allowed to change your
+   * name!" (reachable only via -f / arg_force_name) has no way to fire on the
+   * web adapter.
+   */
+  argv(): readonly string[];
+}
+
+/**
+ * A host that has no directories at all: every read misses and every write
+ * fails. This is what core falls back to when nothing was injected, so a
+ * missing host is a reported failure rather than a thrown exception - the same
+ * discipline z-file.c uses, where file_open just returns NULL.
+ *
+ * Deliberately NOT a silent success. A write that claims to have worked while
+ * storing nothing is the failure mode already recorded against persistSave.
+ */
+export const NULL_HOST: HostIo = {
+  capabilities: {
+    realFiles: false,
+    argv: false,
+    signals: false,
+    termCount: 1,
+    directories: false,
+  },
+  displayPath: (dir, name) => `${dir}/${name}`,
+  exists: () => false,
+  read: () => null,
+  write: () => "create-failed",
+  remove: () => false,
+  move: () => false,
+  newer: () => null,
+  list: () => [],
+  argv: () => [],
+};
+
+let current: HostIo = NULL_HOST;
+
+/** Install the host for this process. The front end calls this at startup. */
+export function setHost(host: HostIo): void {
+  current = host;
+}
+
+/** The installed host, or NULL_HOST if the front end never set one. */
+export function host(): HostIo {
+  return current;
+}
+
+/**
+ * text_lines_to_file (z-textblock.c L703-737): write <name>.new, rotate it into
+ * place over any existing file, and keep <name>.old only for the length of the
+ * rename. Returns an `errr` exactly as the C does - 0 on success, -1 when the
+ * staged file could not be opened - because callers read it that way:
+ *
+ *     if (text_lines_to_file(path, writer)) msg("Failed to create file %s.new", path);
+ *
+ * Lives here rather than in a front end because the staging sequence is host
+ * behaviour that every adapter owes, and it was previously duplicated in the
+ * web layer alone.
+ */
+export function textLinesToFile(
+  io: HostIo,
+  dir: HostDir,
+  name: string,
+  text: string,
+): number {
+  const newName = `${name}.new`;
+  const oldName = `${name}.old`;
+
+  /* Write new file (L714-724). */
+  if (io.write(dir, newName, text) !== "ok") return -1;
+
+  /* Move files around (L726-734). */
+  if (!io.exists(dir, name)) {
+    io.move(dir, newName, name);
+  } else if (io.move(dir, name, oldName)) {
+    io.move(dir, newName, name);
+    io.remove(dir, oldName);
+  } else {
+    io.remove(dir, newName);
+  }
+
+  return 0;
+}

package/src/host/memory.ts

@@ -0,0 +1,134 @@
+/**
+ * An in-memory HostIo: the reference implementation of the host contract, and
+ * the one the tests drive.
+ *
+ * It exists so the file-shaped code paths can be exercised WITHOUT a platform.
+ * Before the host seam, the only way to test a dump was to reach into the web
+ * layer's localStorage shim, so core code that wrote files could not be tested
+ * from core at all - and the failure paths (a write that fails, a file that is
+ * older than another) had no way to be provoked deliberately.
+ *
+ * Capabilities default to full, because this host really can do everything the
+ * contract asks; `failWrites` and `truncateWrites` let a test provoke
+ * upstream's two distinct write failures on demand.
+ */
+
+import type { HostCapabilities, HostIo, WriteOutcome } from "./io.js";
+import { FileMode, HostDir } from "./io.js";
+
+/** Knobs a test uses to provoke the failure paths. */
+export interface MemoryHostOpts {
+  /** Override any capability; the rest stay at full. */
+  capabilities?: Partial<HostCapabilities>;
+  /** argv, minus the program name. */
+  argv?: readonly string[];
+  /** Names whose write fails at open - upstream's "can't open" message. */
+  failWrites?: readonly string[];
+  /**
+   * Names whose write appears to succeed but stores nothing - upstream's
+   * "can't close" message, and the real localStorage failure mode where a
+   * quota-evicted setItem does not throw.
+   */
+  truncateWrites?: readonly string[];
+}
+
+const FULL: HostCapabilities = {
+  realFiles: true,
+  argv: true,
+  signals: true,
+  /** ANGBAND_TERM_MAX (ui-term.h:244). */
+  termCount: 8,
+  directories: true,
+};
+
+/** A HostIo backed by a Map per directory, with an inspectable file table. */
+export class MemoryHost implements HostIo {
+  readonly capabilities: HostCapabilities;
+  private readonly files = new Map<string, string>();
+  /** Monotonic write counter, standing in for an mtime so `newer` is decidable. */
+  private readonly stamps = new Map<string, number>();
+  private clock = 0;
+  private readonly cmdline: readonly string[];
+  private readonly failSet: ReadonlySet<string>;
+  private readonly truncSet: ReadonlySet<string>;
+
+  constructor(opts: MemoryHostOpts = {}) {
+    this.capabilities = { ...FULL, ...opts.capabilities };
+    this.cmdline = opts.argv ?? [];
+    this.failSet = new Set(opts.failWrites ?? []);
+    this.truncSet = new Set(opts.truncateWrites ?? []);
+  }
+
+  private key(dir: HostDir, name: string): string {
+    return `${dir}/${name}`;
+  }
+
+  displayPath(dir: HostDir, name: string): string {
+    return `${dir}/${name}`;
+  }
+
+  exists(dir: HostDir, name: string): boolean {
+    return this.files.has(this.key(dir, name));
+  }
+
+  read(dir: HostDir, name: string): string | null {
+    return this.files.get(this.key(dir, name)) ?? null;
+  }
+
+  write(
+    dir: HostDir,
+    name: string,
+    text: string,
+    mode: FileMode = FileMode.WRITE,
+  ): WriteOutcome {
+    if (this.failSet.has(name)) return "create-failed";
+    const k = this.key(dir, name);
+    /* MODE_APPEND keeps the current contents; MODE_WRITE overwrites them. */
+    const body = mode === FileMode.APPEND ? (this.files.get(k) ?? "") + text : text;
+    if (this.truncSet.has(name)) return "close-failed";
+    this.files.set(k, body);
+    this.stamps.set(k, ++this.clock);
+    return "ok";
+  }
+
+  remove(dir: HostDir, name: string): boolean {
+    const k = this.key(dir, name);
+    this.stamps.delete(k);
+    return this.files.delete(k);
+  }
+
+  move(dir: HostDir, from: string, to: string): boolean {
+    const text = this.read(dir, from);
+    if (text === null) return false;
+    if (this.write(dir, to, text) !== "ok") return false;
+    return this.remove(dir, from);
+  }
+
+  newer(dir: HostDir, first: string, second: string): boolean | null {
+    const a = this.stamps.get(this.key(dir, first));
+    const b = this.stamps.get(this.key(dir, second));
+    /* file_newer's own answer when either side is missing: it stats both and
+     * returns false unless the first exists and is strictly newer. */
+    if (a === undefined) return false;
+    if (b === undefined) return true;
+    return a > b;
+  }
+
+  list(dir: HostDir): string[] {
+    const prefix = `${dir}/`;
+    const out: string[] = [];
+    for (const k of this.files.keys()) {
+      if (k.startsWith(prefix)) out.push(k.slice(prefix.length));
+    }
+    return out.sort((x, y) => x.localeCompare(y));
+  }
+
+  argv(): readonly string[] {
+    return this.cmdline;
+  }
+
+  /** Test helper: every file, as dir/name -> text. */
+  snapshot(): Record<string, string> {
+    return Object.fromEntries(this.files);
+  }
+}

package/src/host/raw.ts

@@ -0,0 +1,190 @@
+/**
+ * The real-filesystem HostIo, split so there is exactly ONE copy of the
+ * semantics.
+ *
+ * WHY THIS EXISTS
+ *
+ * Two front ends have a real filesystem under them - the CLI (node:fs directly)
+ * and the Electron desktop build (node:fs in the main process, reached from the
+ * renderer over IPC). They are the same z-file.c, so they must not be two
+ * hand-written adapters that agree today and drift tomorrow. `file_newer`'s
+ * three-way rule is the clearest example: it is the gate on ui-game.c's
+ * panic-save prompt, and "second is missing" returning TRUE rather than false
+ * (z-file.c:952-967) is the kind of detail one of two copies would get wrong.
+ *
+ * So the split is:
+ *
+ *   RawFs      - the syscall surface. One method per operation, no rules.
+ *                Each host implements this: node:fs directly, or an IPC hop.
+ *   RawFsHost  - z-file.c's rules over any RawFs. Written once, tested once.
+ *
+ * The traversal guard deliberately lives in the RawFs implementations rather
+ * than here, because on the Electron split it is a SECURITY boundary and has to
+ * be enforced in the trusted process. Enforcing it here as well would read as if
+ * the renderer's copy were the one that mattered.
+ */
+
+import type { HostCapabilities, HostIo, WriteOutcome } from "./io.js";
+import { FileMode, FileType, HostDir } from "./io.js";
+
+/**
+ * The raw operations a real filesystem provides, addressed the way HostIo is:
+ * by (directory, leaf name), never by a composed path. An implementation owns
+ * path composition, because that is path_build's job and it is host-specific.
+ *
+ * Every method reports failure by return value; none throws. That mirrors
+ * z-file.c, where file_open returns NULL rather than dying.
+ */
+export interface RawFs {
+  /**
+   * path_build(dir, name) for DISPLAY only - the text upstream prints in
+   * "Cannot open '%s'." A name that escapes its directory still has to render
+   * as something, so this never returns null.
+   */
+  displayPath(dir: HostDir, name: string): string;
+
+  /** stat(p).isFile(). False for a directory, which is what file_exists means. */
+  isFile(dir: HostDir, name: string): boolean;
+
+  /** The whole file as text, or null if it cannot be read. */
+  readText(dir: HostDir, name: string): string | null;
+
+  /**
+   * open + write + close, reporting WHICH phase failed. The two are separate
+   * because upstream prints different messages for them at one call site
+   * (wiz-spoil.c's "Cannot create spoiler file." / "Cannot close spoiler file.").
+   */
+  writeText(
+    dir: HostDir,
+    name: string,
+    text: string,
+    append: boolean,
+    ftype: FileType,
+  ): WriteOutcome;
+
+  /** unlink. */
+  unlink(dir: HostDir, name: string): boolean;
+
+  /** rename within one directory. */
+  rename(dir: HostDir, from: string, to: string): boolean;
+
+  /** Modification time in milliseconds, or null when the file is not there. */
+  mtime(dir: HostDir, name: string): number | null;
+
+  /** The files (not subdirectories) in a directory. */
+  listFiles(dir: HostDir): string[];
+}
+
+/** Every writable HostDir, for hosts that need to create the tree up front. */
+export const ALL_HOST_DIRS: readonly HostDir[] = [
+  HostDir.USER,
+  HostDir.SAVE,
+  HostDir.PANIC,
+  HostDir.SCORES,
+  HostDir.ARCHIVE,
+];
+
+export interface RawFsHostOpts {
+  /** argv minus the program name. */
+  argv?: readonly string[];
+  /**
+   * Terminals this front end can show. Upstream's ANGBAND_TERM_MAX is 8
+   * (ui-term.h:244); a single-canvas front end is 1.
+   */
+  termCount?: number;
+  /**
+   * Whether this front end is actually told the process is dying, so a panic
+   * save can be written. True for a process that installs handlers itself (the
+   * CLI). A sandboxed renderer only has this if its host process forwards the
+   * event, so it must declare what it really has rather than inherit a yes -
+   * capabilities describe the platform, and a false yes here silently removes
+   * ui-game.c's panic save instead of removing any code.
+   */
+  signals?: boolean;
+}
+
+/**
+ * z-file.c's rules over any RawFs. This is the full-capability host: real
+ * files, a command line, and a process that can be signalled.
+ */
+export class RawFsHost implements HostIo {
+  readonly capabilities: HostCapabilities;
+  private readonly raw: RawFs;
+  private readonly cmdline: readonly string[];
+
+  constructor(raw: RawFs, opts: RawFsHostOpts = {}) {
+    this.raw = raw;
+    this.cmdline = opts.argv ?? [];
+    this.capabilities = {
+      realFiles: true,
+      argv: true,
+      signals: opts.signals ?? true,
+      termCount: opts.termCount ?? 1,
+      directories: true,
+    };
+  }
+
+  displayPath(dir: HostDir, name: string): string {
+    return this.raw.displayPath(dir, name);
+  }
+
+  /** file_exists (z-file.h:135) - exists AND is a file. */
+  exists(dir: HostDir, name: string): boolean {
+    return this.raw.isFile(dir, name);
+  }
+
+  read(dir: HostDir, name: string): string | null {
+    return this.raw.readText(dir, name);
+  }
+
+  write(
+    dir: HostDir,
+    name: string,
+    text: string,
+    mode: FileMode = FileMode.WRITE,
+    ftype: FileType = FileType.TEXT,
+  ): WriteOutcome {
+    /* MODE_APPEND must not truncate: prefs_save appends its dump after
+     * remove_old_dump has stripped the previous one. MODE_READ reaching a write
+     * is a caller bug, and truncating on it would destroy the file, so it is
+     * treated as the open failure it would be in C. */
+    if (mode === FileMode.READ) return "create-failed";
+    return this.raw.writeText(dir, name, text, mode === FileMode.APPEND, ftype);
+  }
+
+  remove(dir: HostDir, name: string): boolean {
+    return this.raw.unlink(dir, name);
+  }
+
+  move(dir: HostDir, from: string, to: string): boolean {
+    return this.raw.rename(dir, from, to);
+  }
+
+  /**
+   * file_newer (z-file.c:952-967), all three branches:
+   *
+   *   if (stat(first,  ...) != 0) return false;   // first missing -> not newer
+   *   if (stat(second, ...) != 0) return true;    // second missing -> newer
+   *   return stat1.st_mtime > stat2.st_mtime;
+   *
+   * Never null here: a real filesystem always knows. The null in HostIo exists
+   * for BrowserHost, which stores no mtime and must say "cannot tell" rather
+   * than guess false - that guess would silently delete ui-game.c:709-720's
+   * panic-save prompt.
+   */
+  newer(dir: HostDir, first: string, second: string): boolean {
+    const a = this.raw.mtime(dir, first);
+    if (a === null) return false;
+    const b = this.raw.mtime(dir, second);
+    if (b === null) return true;
+    return a > b;
+  }
+
+  list(dir: HostDir): string[] {
+    return this.raw.listFiles(dir);
+  }
+
+  argv(): readonly string[] {
+    return this.cmdline;
+  }
+}