@deckbuilderkit/server-mods 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@deckbuilderkit/server-mods",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adrianogpena/deckbuilder.git",
+    "directory": "packages/server-mods"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./archive-worker": "./src/archive-worker.ts"
+  },
+  "dependencies": {
+    "7z-wasm": "^1.2.0",
+    "@deckbuilderkit/platform": "0.1.1",
+    "@deckbuilderkit/server-core": "0.1.1"
+  }
+}

package/src/archive-worker.ts

@@ -0,0 +1,13 @@
+import { run, type SevenZipJob } from './archive.ts';
+
+declare const self: Worker;
+
+// One 7z run per worker: the caller posts a job, gets the result and terminates the worker.
+self.onmessage = async (e: MessageEvent<SevenZipJob>) => {
+  try {
+    const { args, mounts, cwd } = e.data;
+    self.postMessage(await run(args, mounts, cwd));
+  } catch (err) {
+    self.postMessage({ error: (err as Error).message ?? String(err) });
+  }
+};

package/src/archive.ts

@@ -0,0 +1,205 @@
+/// <reference path="./wasm.d.ts" />
+import { mkdtemp, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import SevenZip from '7z-wasm';
+import wasmFile from '7z-wasm/7zz.wasm' with { type: 'file' };
+import { invalid } from '@deckbuilderkit/server-core';
+
+export interface ArchiveEntry {
+  /** `/`-separated path inside the archive. */
+  path: string;
+  dir: boolean;
+  /** Bytes; 0 for folders. */
+  size: number;
+  /** Epoch ms, or 0 when the archive has none. */
+  mtime: number;
+  encrypted: boolean;
+}
+
+export interface ArchiveListing {
+  entries: ArchiveEntry[];
+  /** More entries than `MAX_ENTRIES`: the rest are left out. */
+  truncated: boolean;
+}
+
+const MAX_ENTRIES = 20_000;
+// A .tar.gz lists as one .tar; one this small is unpacked in memory to list the files inside.
+const MAX_NESTED_TAR_BYTES = 256_000_000;
+
+let wasm: Promise<ArrayBuffer> | undefined;
+
+export interface SevenZipJob {
+  args: string[];
+  /** Emscripten mount point -> host folder, mounted through NODEFS. */
+  mounts: Record<string, string>;
+  cwd?: string;
+}
+
+export interface SevenZipResult {
+  out: string[];
+  err: string[];
+  code: number;
+}
+
+export async function run(args: string[], mounts: Record<string, string>, cwd?: string): Promise<SevenZipResult> {
+  wasm ??= Bun.file(wasmFile).arrayBuffer();
+  const out: string[] = [];
+  const err: string[] = [];
+  const m = await SevenZip({ wasmBinary: await wasm, print: (s) => out.push(s), printErr: (s) => err.push(s) });
+  for (const [point, root] of Object.entries(mounts)) {
+    m.FS.mkdir(point);
+    m.FS.mount(m.NODEFS, { root }, point);
+  }
+  if (cwd) m.FS.chdir(cwd);
+  let code = 0;
+  try {
+    m.callMain(args);
+  } catch (e) {
+    code = (e as { status?: number }).status ?? 1;
+  }
+  return { out, err, code };
+}
+
+/** Parses `7z l -slt -ba`: blocks of `Key = value` lines; the first key's line may carry progress text before it. */
+export function parseListing(lines: string[]): ArchiveEntry[] {
+  const entries: ArchiveEntry[] = [];
+  let cur: Record<string, string> = {};
+  const flush = () => {
+    if (cur.Path !== undefined) {
+      const mtime = Date.parse(`${(cur.Modified ?? '').slice(0, 19).replace(' ', 'T')}Z`);
+      entries.push({
+        path: cur.Path.replaceAll('\\', '/'),
+        dir: cur.Folder === '+' || (cur.Attributes ?? '').startsWith('D') || /^d/.test(cur.Attributes ?? ''),
+        size: Number(cur.Size) || 0,
+        mtime: Number.isNaN(mtime) ? 0 : mtime,
+        encrypted: cur.Encrypted === '+',
+      });
+    }
+    cur = {};
+  };
+  for (const raw of lines) {
+    const line = raw.includes('Path = ') ? raw.slice(raw.indexOf('Path = ')) : raw;
+    if (line.trim() === '') {
+      flush();
+      continue;
+    }
+    const i = line.indexOf(' = ');
+    if (i > 0) {
+      const key = line.slice(0, i);
+      if (key === 'Path' && cur.Path !== undefined) flush();
+      cur[key] = line.slice(i + 3);
+    }
+  }
+  flush();
+  return entries;
+}
+
+async function list(abs: string, extra: string[] = []): Promise<ArchiveEntry[]> {
+  const { out, err, code } = await run(['l', '-slt', '-ba', '-bd', ...extra, `/host/${basename(abs)}`], { '/host': dirname(abs) });
+  const entries = parseListing(out);
+  if (entries.length === 0 && (code !== 0 || err.length > 0)) {
+    throw invalid('badArchive', err.find((l) => l.trim()) ?? 'This file is not a supported archive.');
+  }
+  return entries;
+}
+
+/** Lists an archive (7z, rar, zip, tar, gz, xz, bz2, iso, cab, ...), looking inside a lone .tar as well. */
+export async function listArchive(abs: string): Promise<ArchiveListing> {
+  let entries = await list(abs);
+  const only = entries.length === 1 ? entries[0]! : undefined;
+  if (only && !only.dir && /\.tar$/i.test(only.path) && only.size <= MAX_NESTED_TAR_BYTES) {
+    const dir = await mkdtemp(join(tmpdir(), 'deckbuilder-arc-'));
+    try {
+      const { code } = await run(['e', '-y', '-bd', `-o/out`, `/host/${basename(abs)}`], { '/host': dirname(abs), '/out': dir });
+      if (code === 0 && (await stat(join(dir, basename(only.path))).catch(() => null))) entries = await list(join(dir, basename(only.path)));
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }
+  return { entries: entries.slice(0, MAX_ENTRIES), truncated: entries.length > MAX_ENTRIES };
+}
+
+/**
+ * `callMain` is synchronous and blocks its thread for the whole run, so extract and compress run
+ * 7z in a Worker; the server keeps answering meanwhile.
+ */
+function runInWorker(job: SevenZipJob): Promise<SevenZipResult> {
+  // In the exe this resolves next to the bundled entry, where `deckbuilder build` must put the worker entrypoint.
+  const worker = new Worker(new URL('./archive-worker.ts', import.meta.url).href);
+  return new Promise<SevenZipResult>((resolve, reject) => {
+    worker.addEventListener('message', (e: MessageEvent<SevenZipResult | { error: string }>) => {
+      if ('error' in e.data) reject(new Error(e.data.error));
+      else resolve(e.data);
+    });
+    worker.addEventListener('error', (e) => reject(new Error(e.message)));
+    worker.postMessage(job);
+  }).finally(() => worker.terminate());
+}
+
+// 7z asks for a password on stdin when it needs one; a dummy one makes it fail instead.
+const NO_PASSWORD = '-pdeckbuilder-no-password';
+const encrypted = () => invalid('archiveEncrypted', 'The archive is encrypted; password-protected archives are not supported.');
+const wrongPassword = (lines: string[]) => lines.some((l) => /wrong password|encrypted|can ?not open encrypted/i.test(l));
+
+const unsafe = () => invalid('archiveUnsafe', 'The archive has entries that lead outside the target folder.');
+/** An entry name that climbs out (`..`) or is absolute; 7z would quietly strip that, so it is refused instead. */
+const unsafePath = (path: string) => /^([\\/]|[a-zA-Z]:)/.test(path) || path.split(/[\\/]/).includes('..');
+
+/** 7z's exit status isn't passed back by `callMain`, so errors are read from its output too. */
+function check(r: SevenZipResult): void {
+  const lines = [...r.err, ...r.out];
+  if (r.code === 0 && !lines.some((l) => /ERROR|Errors:/.test(l))) return;
+  if (wrongPassword(lines)) throw encrypted();
+  if (lines.some((l) => /dangerous (link )?path/i.test(l))) throw unsafe();
+  throw invalid('badArchive', lines.find((l) => /ERROR/.test(l))?.trim() ?? r.err.find((l) => l.trim()) ?? 'The archive could not be extracted.');
+}
+
+/** Lists `abs` for extraction: encrypted entries or entry names leading out are refused. */
+async function checkedList(abs: string): Promise<ArchiveEntry[]> {
+  const entries = await list(abs, [NO_PASSWORD]).catch((err) => {
+    throw wrongPassword([(err as Error).message ?? '']) ? encrypted() : err;
+  });
+  if (entries.some((e) => e.encrypted)) throw encrypted();
+  if (entries.some((e) => unsafePath(e.path))) throw unsafe();
+  return entries;
+}
+
+const extract = (archive: string, to: string, mode: 'x' | 'e' = 'x') =>
+  runInWorker({ args: [mode, '-y', '-bd', NO_PASSWORD, '-o/out', `/host/${basename(archive)}`], mounts: { '/host': dirname(archive), '/out': to } }).then(check);
+
+/**
+ * Extracts `abs` into the existing empty folder `to` (7z `x`, folders kept). A lone .tar inside a
+ * .gz/.xz/.bz2 is unpacked too, like `listArchive` lists it. Encrypted archives and entries that
+ * lead out of `to` (`..`, absolute names, links out) are refused.
+ */
+export async function extractArchive(abs: string, to: string): Promise<void> {
+  const entries = await checkedList(abs);
+  const only = entries.length === 1 ? entries[0]! : undefined;
+  if (only && !only.dir && /\.tar$/i.test(only.path)) {
+    const dir = await mkdtemp(join(tmpdir(), 'deckbuilder-arc-'));
+    try {
+      await extract(abs, dir, 'e');
+      const tar = join(dir, basename(only.path));
+      await checkedList(tar);
+      await extract(tar, to);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+    return;
+  }
+  await extract(abs, to);
+}
+
+/**
+ * Writes the archive `file` (zip or 7z) of the entries `names` of the folder `dir`, stored by name.
+ * Links are stored as links (`-snl`), never followed.
+ */
+export async function compressArchive(dir: string, names: string[], file: string, format: 'zip' | '7z'): Promise<void> {
+  const r = await runInWorker({
+    args: ['a', `-t${format}`, '-snl', '-bd', '-y', `/out/${basename(file)}`, '--', ...names],
+    mounts: { '/host': dir, '/out': dirname(file) },
+    cwd: '/host',
+  });
+  if (r.code !== 0) throw invalid('compressFailed', r.err.find((l) => l.trim()) ?? 'The archive could not be written.');
+}

package/src/backup.ts

@@ -0,0 +1,139 @@
+import { pickFile, saveFileAs, writeJsonAtomic } from '@deckbuilderkit/platform';
+import { type BackupInspect, invalid, isRecord, type Routes } from '@deckbuilderkit/server-core';
+import { fromPlatform } from './platform-errors.ts';
+import type { ImportResult, RecordStore, Rec } from './records.ts';
+import type { SettingsStore } from './settings.ts';
+
+export interface BackupRoutesOptions {
+  app: { id: string; version: string };
+  settings: SettingsStore<any>;
+  /** Record stores a backup may hold, by the name used in the file. */
+  stores: Record<string, RecordStore<any>>;
+  /** Settings keys left out of exports and imports (machine-specific ones). */
+  excludeSettings?: string[];
+  save?: typeof saveFileAs;
+  pick?: typeof pickFile;
+}
+
+/** What an export writes. Secret fields are left out. */
+export interface BackupFile {
+  format: 'deckbuilder-backup';
+  version: 1;
+  app: string;
+  appVersion: string;
+  exportedAt: string;
+  settings?: Record<string, unknown>;
+  records?: Record<string, Rec<object>[]>;
+}
+
+const MAX_FILE_BYTES = 20_000_000;
+const MAX_INSPECTED = 5;
+const INSPECTED_TTL_MS = 600_000;
+const JSON_FILTER = [{ name: 'JSON', patterns: ['*.json'] }];
+
+const badRequest = () => invalid('badRequest', 'Invalid request.');
+const badBackup = () => invalid('badBackup', 'This file is not a valid backup.');
+const isStringArray = (v: unknown): v is string[] => Array.isArray(v) && v.every((s) => typeof s === 'string');
+
+const localDate = (d = new Date()) =>
+  `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+
+/**
+ * `GET /api/backup/parts`, `POST /api/backup/export`, `POST /api/backup/inspect` and
+ * `POST /api/backup/import`. Both files come from server-side dialogs; inspect keeps the parsed
+ * file under a one-shot token that import takes, so the client never sends a path.
+ */
+export function backupRoutes(opts: BackupRoutesOptions): Routes {
+  const { app, settings, stores, excludeSettings = [], save = saveFileAs, pick = pickFile } = opts;
+  const inspected = new Map<string, { file: BackupFile; at: number }>();
+
+  const withoutExcluded = (values: Record<string, unknown>) => {
+    const copy = { ...values };
+    for (const key of excludeSettings) delete copy[key];
+    return copy;
+  };
+
+  const parts = (body: unknown) => {
+    if (!isRecord(body) || typeof body.settings !== 'boolean' || !isStringArray(body.stores)) throw badRequest();
+    return { settings: body.settings, stores: body.stores };
+  };
+
+  async function read(path: string): Promise<BackupFile> {
+    const handle = Bun.file(path);
+    if (handle.size > MAX_FILE_BYTES) throw invalid('backupTooLarge', 'The backup file is too large.');
+    let file: unknown;
+    try {
+      file = JSON.parse(await handle.text());
+    } catch {
+      throw badBackup();
+    }
+    if (!isRecord(file) || file.format !== 'deckbuilder-backup' || file.version !== 1 || typeof file.app !== 'string') throw badBackup();
+    if (file.app !== app.id) throw invalid('backupOtherApp', 'This backup belongs to another app ({app}).', { app: file.app.slice(0, 100) });
+    if (file.settings !== undefined && !isRecord(file.settings)) throw badBackup();
+    if (file.records !== undefined && !(isRecord(file.records) && Object.values(file.records).every(Array.isArray))) throw badBackup();
+    return file as unknown as BackupFile;
+  }
+
+  return {
+    'GET /api/backup/parts': () => ({ stores: Object.keys(stores) }),
+
+    'POST /api/backup/export': async ({ json }) => {
+      const chosen = parts(await json());
+      if (chosen.stores.some((name) => !Object.hasOwn(stores, name))) throw badRequest();
+      if (!chosen.settings && chosen.stores.length === 0) throw invalid('backupEmpty', 'Choose something to export.');
+      const path = await save({ suggestedName: `${app.id}-backup-${localDate()}.json`, filters: JSON_FILTER }).catch(fromPlatform);
+      if (path === null) return { path: null };
+      const file: BackupFile = { format: 'deckbuilder-backup', version: 1, app: app.id, appVersion: app.version, exportedAt: new Date().toISOString() };
+      if (chosen.settings) file.settings = withoutExcluded(await settings.load());
+      const counts: Record<string, number> = {};
+      if (chosen.stores.length) {
+        file.records = {};
+        for (const name of new Set(chosen.stores)) {
+          file.records[name] = await stores[name]!.exportItems();
+          counts[name] = file.records[name].length;
+        }
+      }
+      await writeJsonAtomic(path, file);
+      return { path, counts };
+    },
+
+    'POST /api/backup/inspect': async (): Promise<BackupInspect> => {
+      const path = await pick({ filters: JSON_FILTER }).catch(fromPlatform);
+      if (path === null) return { token: null };
+      const file = await read(path);
+      const now = Date.now();
+      for (const [key, entry] of inspected) if (now - entry.at >= INSPECTED_TTL_MS) inspected.delete(key);
+      const token = crypto.randomUUID();
+      inspected.set(token, { file, at: now });
+      while (inspected.size > MAX_INSPECTED) inspected.delete(inspected.keys().next().value as string);
+      return {
+        token,
+        appVersion: typeof file.appVersion === 'string' ? file.appVersion : '',
+        exportedAt: typeof file.exportedAt === 'string' ? file.exportedAt : '',
+        settings: file.settings !== undefined,
+        stores: Object.entries(file.records ?? {}).map(([name, items]) => ({ name, count: items.length, known: Object.hasOwn(stores, name) })),
+      };
+    },
+
+    'POST /api/backup/import': async ({ json }) => {
+      const body = await json();
+      const chosen = parts(body);
+      const mode = (body as Record<string, unknown>).mode;
+      const token = (body as Record<string, unknown>).token;
+      if (mode !== 'merge' && mode !== 'replace') throw badRequest();
+      const entry = typeof token === 'string' ? inspected.get(token) : undefined;
+      if (entry) inspected.delete(token as string);
+      if (!entry || Date.now() - entry.at >= INSPECTED_TTL_MS) throw invalid('backupExpired', 'The backup file was read too long ago. Choose it again.');
+      const { file } = entry;
+      const applied = chosen.settings && file.settings !== undefined;
+      if (applied) await settings.save(withoutExcluded(file.settings!));
+      const results: Record<string, ImportResult> = {};
+      for (const name of new Set(chosen.stores)) {
+        if (Object.hasOwn(stores, name) && file.records && Object.hasOwn(file.records, name)) {
+          results[name] = await stores[name]!.importItems(file.records[name]!, mode);
+        }
+      }
+      return { settings: applied, stores: results };
+    },
+  };
+}

package/src/bytes.ts

@@ -0,0 +1,2 @@
+/** True when the first 8 KiB holds a NUL byte, which text files don't. */
+export const isBinary = (bytes: Uint8Array) => bytes.subarray(0, 8192).includes(0);

package/src/dialogs.ts

@@ -0,0 +1,68 @@
+import { type DialogFilter, pickFile, pickFolder, saveFileAs } from '@deckbuilderkit/platform';
+import type { Routes } from '@deckbuilderkit/server-core';
+import { fromPlatform } from './platform-errors.ts';
+
+const str = (v: unknown) => (typeof v === 'string' ? v : undefined);
+
+/** The well-typed filters of a body; malformed ones are dropped. */
+function filters(v: unknown): DialogFilter[] | undefined {
+  if (!Array.isArray(v)) return undefined;
+  return v
+    .filter((f): f is { name: unknown; patterns: unknown[] } => typeof f === 'object' && f !== null && Array.isArray(f.patterns))
+    .map((f) => ({ name: str(f.name) ?? '', patterns: f.patterns.filter((p): p is string => typeof p === 'string') }));
+}
+
+const body = async (json: () => Promise<unknown>) => (await json()) as Record<string, unknown>;
+
+/** Paths a server dialog returned that a later route may accept once. */
+export interface PickedPaths {
+  add(path: string): void;
+  /** True once for a path added less than `ttlMs` ago (exact match); removes it. */
+  take(path: string): boolean;
+}
+
+/** A one-shot set of dialog results; adding beyond `max` drops the oldest entry. */
+export function pickedPaths(opts: { max?: number; ttlMs?: number; now?: () => number } = {}): PickedPaths {
+  const { max = 20, ttlMs = 600_000, now = Date.now } = opts;
+  const added = new Map<string, number>();
+  return {
+    add(path) {
+      added.delete(path);
+      added.set(path, now());
+      while (added.size > max) added.delete(added.keys().next().value as string);
+    },
+    take(path) {
+      const at = added.get(path);
+      if (at === undefined) return false;
+      added.delete(path);
+      return now() - at < ttlMs;
+    },
+  };
+}
+
+/**
+ * `POST /api/dialog/folder|file|save` with the dialog options → `{ path: string | null }` (null =
+ * cancelled). The path is absolute: a route that takes it back from the client must check it with
+ * `picked.take` (folder and file results are added to `picked`; save targets need their own route).
+ */
+export function dialogRoutes(opts: { picked?: PickedPaths } = {}): Routes {
+  const result = (path: Promise<string | null>, pick = true) =>
+    path.then((p) => {
+      if (pick && p !== null) opts.picked?.add(p);
+      return { path: p };
+    }, fromPlatform);
+  return {
+    'POST /api/dialog/folder': async ({ json }) => {
+      const b = await body(json);
+      return result(pickFolder({ title: str(b.title) }));
+    },
+    'POST /api/dialog/file': async ({ json }) => {
+      const b = await body(json);
+      return result(pickFile({ title: str(b.title), filters: filters(b.filters) }));
+    },
+    'POST /api/dialog/save': async ({ json }) => {
+      const b = await body(json);
+      return result(saveFileAs({ title: str(b.title), suggestedName: str(b.suggestedName), filters: filters(b.filters) }), false);
+    },
+  };
+}

package/src/editors.ts

@@ -0,0 +1,109 @@
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import {
+  EDITOR_NAMES,
+  type EditorId,
+  findEditor,
+  openInEditor,
+  pickFile,
+  readJsonFile,
+  writeJsonAtomic,
+} from '@deckbuilderkit/platform';
+import { type EditorInfo, invalid, isRecord, type Routes } from '@deckbuilderkit/server-core';
+import { fromPlatform } from './platform-errors.ts';
+import type { RootedFs } from './rooted-fs.ts';
+
+export type { EditorInfo };
+
+export interface EditorRoutesOptions {
+  /** Folder of editors.json (the overrides), usually `appHome(APP.id)`. */
+  dir: string;
+  fs: RootedFs;
+  pick?: typeof pickFile;
+  find?: typeof findEditor;
+  open?: typeof openInEditor;
+}
+
+type Overrides = Partial<Record<EditorId, string>>;
+
+const badRequest = () => invalid('badRequest', 'Invalid request.');
+const badEditor = () => invalid('badEditor', 'Unknown editor.');
+const isEditor = (v: unknown): v is EditorId => typeof v === 'string' && Object.hasOwn(EDITOR_NAMES, v);
+const editorOf = (v: unknown): EditorId => {
+  if (!isEditor(v)) throw badEditor();
+  return v;
+};
+
+/**
+ * `GET /api/editors`, `POST /api/editors/pick`, `DELETE /api/editors/override?editor=` and
+ * `POST /api/editors/open`. The program to run comes from detection or from a server-side file
+ * dialog saved in `<dir>/editors.json`, never from the client; `.cmd` scripts are refused because
+ * they would go through cmd.exe.
+ */
+export function editorRoutes(opts: EditorRoutesOptions): Routes {
+  const { dir, fs, pick = pickFile, find = findEditor, open = openInEditor } = opts;
+  const file = join(dir, 'editors.json');
+
+  const readOverrides = async (): Promise<Overrides> => {
+    const stored = (await readJsonFile(file, isRecord)) as Record<string, unknown> | undefined;
+    const overrides: Overrides = {};
+    for (const id of Object.keys(EDITOR_NAMES) as EditorId[]) {
+      const value = stored?.[id];
+      if (typeof value === 'string' && value !== '') overrides[id] = value;
+    }
+    return overrides;
+  };
+
+  const list = async (): Promise<EditorInfo[]> => {
+    const overrides = await readOverrides();
+    return Promise.all(
+      (Object.keys(EDITOR_NAMES) as EditorId[]).map(async (id) => {
+        const custom = overrides[id] !== undefined;
+        return { id, name: EDITOR_NAMES[id], path: overrides[id] ?? (await find(id)), custom };
+      }),
+    );
+  };
+
+  return {
+    'GET /api/editors': () => list(),
+
+    'POST /api/editors/pick': async ({ json }) => {
+      const editor = editorOf(((await json()) as Record<string, unknown>).editor);
+      const picked = await pick({
+        title: `Choose the ${EDITOR_NAMES[editor]} program`,
+        filters: [{ name: 'Programs', patterns: ['*.exe'] }],
+      }).catch(fromPlatform);
+      if (picked === null) return list();
+      if (process.platform === 'win32' && !/\.exe$/i.test(picked)) throw invalid('editorNotExe', 'The editor program must be an existing .exe file.');
+      await writeJsonAtomic(file, { ...(await readOverrides()), [editor]: picked });
+      return list();
+    },
+
+    'DELETE /api/editors/override': async ({ query }) => {
+      const editor = editorOf(query.get('editor'));
+      const { [editor]: _removed, ...rest } = await readOverrides();
+      await writeJsonAtomic(file, rest);
+      return list();
+    },
+
+    'POST /api/editors/open': async ({ json }) => {
+      const b = (await json()) as Record<string, unknown>;
+      const editor = editorOf(b.editor);
+      if (typeof b.root !== 'string' || (b.path !== undefined && typeof b.path !== 'string')) throw badRequest();
+      const line = b.line;
+      if (line !== undefined && (typeof line !== 'number' || !Number.isInteger(line) || line < 1)) throw badRequest();
+
+      const folder = (await fs.resolve(b.root, '', { mustExist: true })).real;
+      let target: string | undefined;
+      if (typeof b.path === 'string' && b.path !== '') {
+        const real = (await fs.resolve(b.root, b.path, { mustExist: true })).real;
+        if (!(await stat(real)).isDirectory()) target = real;
+      }
+
+      const exe = (await readOverrides())[editor] ?? (await find(editor));
+      if (!exe) throw invalid('editorNotFound', 'The editor was not found. Choose its program in Settings.');
+      await open(editor, exe, { folder, file: target, line: target ? line : undefined }).catch(fromPlatform);
+      return { ok: true };
+    },
+  };
+}

package/src/encoding.ts

@@ -0,0 +1,87 @@
+import { invalid } from '@deckbuilderkit/server-core';
+
+/** The text encodings the file routes read and write; a file keeps its own on save. */
+export type TextEncodingId = 'utf8' | 'utf8bom' | 'utf16le' | 'utf16be' | 'windows1252';
+
+export const TEXT_ENCODINGS: readonly TextEncodingId[] = ['utf8', 'utf8bom', 'utf16le', 'utf16be', 'windows1252'];
+
+const BOMS: Array<[TextEncodingId, number[]]> = [
+  ['utf8bom', [0xef, 0xbb, 0xbf]],
+  ['utf16le', [0xff, 0xfe]],
+  ['utf16be', [0xfe, 0xff]],
+];
+
+const bomOf = (enc: TextEncodingId) => BOMS.find(([id]) => id === enc)?.[1] ?? [];
+
+/** The encoding its byte order mark names, or undefined without one. */
+export function encodingByBom(bytes: Uint8Array): TextEncodingId | undefined {
+  return BOMS.find(([, bom]) => bom.every((b, i) => bytes[i] === b))?.[0];
+}
+
+/**
+ * The encoding of a text file's first bytes: its BOM, else UTF-8 when the bytes are valid UTF-8,
+ * else Windows-1252 (what Notepad calls ANSI on Western systems). The bytes of a `truncated` read
+ * may end inside a character.
+ */
+export function detectEncoding(bytes: Uint8Array, truncated = false): TextEncodingId {
+  const byBom = encodingByBom(bytes);
+  if (byBom) return byBom;
+  try {
+    new TextDecoder('utf-8', { fatal: true }).decode(bytes, { stream: truncated });
+    return 'utf8';
+  } catch {
+    return 'windows1252';
+  }
+}
+
+const LABELS: Record<TextEncodingId, string> = {
+  utf8: 'utf-8',
+  utf8bom: 'utf-8',
+  utf16le: 'utf-16le',
+  utf16be: 'utf-16be',
+  windows1252: 'windows-1252',
+};
+
+/** `bytes` as text in `enc`, without its BOM. */
+export function decodeText(bytes: Uint8Array, enc: TextEncodingId): string {
+  return new TextDecoder(LABELS[enc] as ConstructorParameters<typeof TextDecoder>[0]).decode(bytes.subarray(bomOf(enc).length));
+}
+
+let cp1252: Map<number, number> | undefined;
+
+/** Code point → byte, built from the decoder so it round-trips exactly. */
+function cp1252Bytes(): Map<number, number> {
+  if (!cp1252) {
+    const all = new TextDecoder('windows-1252').decode(Uint8Array.from({ length: 256 }, (_, i) => i));
+    cp1252 = new Map([...all].map((ch, i) => [ch.codePointAt(0)!, i]));
+  }
+  return cp1252;
+}
+
+/** `text` as bytes in `enc`, with the BOM the encoding has. A character Windows-1252 can't hold is refused, never replaced. */
+export function encodeText(text: string, enc: TextEncodingId): Uint8Array {
+  const bom = bomOf(enc);
+  if (enc === 'utf8' || enc === 'utf8bom') {
+    const body = new TextEncoder().encode(text);
+    const out = new Uint8Array(bom.length + body.length);
+    out.set(bom);
+    out.set(body, bom.length);
+    return out;
+  }
+  if (enc === 'windows1252') {
+    const map = cp1252Bytes();
+    const out = new Uint8Array(text.length);
+    let n = 0;
+    for (const ch of text) {
+      const b = map.get(ch.codePointAt(0)!);
+      if (b === undefined) throw invalid('unencodable', `"${ch}" can't be saved in Windows-1252. Remove it or change the encoding.`);
+      out[n++] = b;
+    }
+    return out.subarray(0, n);
+  }
+  const out = new Uint8Array(bom.length + text.length * 2);
+  out.set(bom);
+  const view = new DataView(out.buffer);
+  for (let i = 0; i < text.length; i++) view.setUint16(bom.length + i * 2, text.charCodeAt(i), enc === 'utf16le');
+  return out;
+}