@deckbuilderkit/platform 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@deckbuilderkit/platform",
-  "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/platform"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}

package/src/browser.ts

@@ -0,0 +1,55 @@
+import { existsSync } from 'node:fs';
+import { win32 } from 'node:path';
+
+export interface FindBrowserOptions {
+  platform?: NodeJS.Platform;
+  env?: Record<string, string | undefined>;
+  exists?: (path: string) => boolean;
+  which?: (cmd: string) => string | null;
+}
+
+const WINDOWS_BROWSERS = ['Microsoft\\Edge\\Application\\msedge.exe', 'Google\\Chrome\\Application\\chrome.exe'];
+const WINDOWS_ROOTS = ['ProgramFiles(x86)', 'ProgramFiles', 'LOCALAPPDATA'];
+const LINUX_BROWSERS = ['microsoft-edge', 'google-chrome', 'chromium', 'chromium-browser'];
+const MAC_BROWSERS = [
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+];
+
+/** The Chromium browser that can open an app window (`--app=<url>`): Edge first, then Chrome. Null when none is installed. */
+export function findAppBrowser(opts: FindBrowserOptions = {}): string | null {
+  const platform = opts.platform ?? process.platform;
+  const exists = opts.exists ?? existsSync;
+  if (platform === 'win32') {
+    const env = opts.env ?? process.env;
+    for (const browser of WINDOWS_BROWSERS) {
+      for (const root of WINDOWS_ROOTS) {
+        const dir = env[root];
+        if (!dir) continue;
+        const path = win32.join(dir, browser);
+        if (exists(path)) return path;
+      }
+    }
+    return null;
+  }
+  if (platform === 'darwin') return MAC_BROWSERS.find(exists) ?? null;
+  const which = opts.which ?? ((cmd: string) => Bun.which(cmd));
+  for (const cmd of LINUX_BROWSERS) {
+    const path = which(cmd);
+    if (path) return path;
+  }
+  return null;
+}
+
+/** Command line for an app window. Its own `profileDir` gives the app a browser process apart from the user's browser. */
+export function appBrowserArgv(browser: string, url: string, profileDir: string, size: { width: number; height: number }): string[] {
+  return [
+    browser,
+    `--app=${url}`,
+    `--user-data-dir=${profileDir}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+    `--window-size=${size.width},${size.height}`,
+  ];
+}

package/src/dialogs.ts

@@ -0,0 +1,296 @@
+import { PlatformError } from './errors.ts';
+import { asciiJson, spawnPowerShell } from './win/powershell.ts';
+
+export interface DialogFilter {
+  name: string;
+  /** Globs such as `*.md`. */
+  patterns: string[];
+}
+
+export interface FolderDialogOptions {
+  title?: string;
+  /** Folder the dialog starts in. */
+  start?: string;
+}
+
+export interface FileDialogOptions extends FolderDialogOptions {
+  filters?: DialogFilter[];
+}
+
+export interface SaveDialogOptions {
+  title?: string;
+  suggestedName?: string;
+  filters?: DialogFilter[];
+}
+
+export type DialogKind = 'folder' | 'file' | 'save';
+
+interface DialogProcess {
+  stdin: { write(data: string): unknown; end(): unknown };
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+  exited: Promise<number>;
+}
+
+export interface DialogDeps {
+  spawn: (script: string, opts: { sta: true; stdin: 'pipe'; stdout: 'pipe' }) => DialogProcess;
+}
+
+const defaultDeps: DialogDeps = { spawn: spawnPowerShell };
+
+/** Opens the native folder picker; resolves the chosen absolute path, or null when cancelled. */
+export const pickFolder = (opts: FolderDialogOptions = {}, deps = defaultDeps) => openDialog('folder', opts, deps);
+
+/** Opens the native "Open file" dialog; resolves the chosen absolute path, or null when cancelled. */
+export const pickFile = (opts: FileDialogOptions = {}, deps = defaultDeps) => openDialog('file', opts, deps);
+
+/** Opens the native "Save as" dialog (asks before overwriting); resolves the absolute path, or null when cancelled. */
+export const saveFileAs = (opts: SaveDialogOptions = {}, deps = defaultDeps) => openDialog('save', opts, deps);
+
+interface Request {
+  title: string;
+  start: string;
+  name: string;
+  filters: DialogFilter[];
+}
+
+const str = (v: unknown, max = 1000) => (typeof v === 'string' ? v.slice(0, max) : '');
+
+function request(opts: FileDialogOptions & SaveDialogOptions): Request {
+  const filters = (Array.isArray(opts.filters) ? opts.filters : [])
+    .slice(0, 20)
+    .map((f) => ({
+      name: str(f?.name, 100),
+      patterns: (Array.isArray(f?.patterns) ? f.patterns : []).map((p) => str(p, 100).replace(/[;|]/g, '')).filter(Boolean).slice(0, 20),
+    }))
+    .filter((f) => f.patterns.length);
+  return { title: str(opts.title, 200), start: str(opts.start), name: str(opts.suggestedName, 260), filters };
+}
+
+let busy = false;
+
+async function openDialog(kind: DialogKind, opts: FileDialogOptions & SaveDialogOptions, deps: DialogDeps): Promise<string | null> {
+  if (busy) throw new PlatformError('dialogBusy', 'A dialog is already open.');
+  busy = true;
+  try {
+    const req = request(opts);
+    if (deps !== defaultDeps || process.platform === 'win32') return await windowsDialog(kind, req, deps);
+    if (process.platform === 'darwin') return await macDialog(kind, req);
+    return await zenityDialog(kind, req);
+  } finally {
+    busy = false;
+  }
+}
+
+// --- Windows ---------------------------------------------------------------------------------
+
+// The COM IFileOpenDialog / IFileSaveDialog (the Vista+ dialogs). Only IFileDialog's own methods
+// are called, so both coclasses are used through that one interface. Writes the result as ASCII
+// JSON itself: Windows PowerShell's ConvertTo-Json leaves non-ASCII to the console code page.
+const DIALOG_CS = `
+using System;
+using System.Runtime.InteropServices;
+using System.Text;
+
+namespace DeckBuilder {
+  public static class FileDialog {
+    public const uint FOS_OVERWRITEPROMPT = 0x2;
+    public const uint FOS_PICKFOLDERS = 0x20;
+    public const uint FOS_FORCEFILESYSTEM = 0x40;
+    public const uint FOS_PATHMUSTEXIST = 0x800;
+    public const uint FOS_FILEMUSTEXIST = 0x1000;
+    const uint SIGDN_FILESYSPATH = 0x80058000;
+    const int ERROR_CANCELLED = unchecked((int)0x800704C7);
+
+    [ComImport, Guid("DC1C5A9C-E88A-4dde-A5A1-60F82A20AEF7")] class FileOpenDialogCo {}
+    [ComImport, Guid("C0B4E2F3-BA21-4773-8DBA-335EC946EB8B")] class FileSaveDialogCo {}
+
+    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+    struct FilterSpec {
+      [MarshalAs(UnmanagedType.LPWStr)] public string Name;
+      [MarshalAs(UnmanagedType.LPWStr)] public string Spec;
+    }
+
+    [ComImport, Guid("43826D1E-E718-42EE-BC55-A1E261C37BFE"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    interface IShellItem {
+      void BindToHandler(IntPtr pbc, ref Guid bhid, ref Guid riid, out IntPtr ppv);
+      void GetParent(out IShellItem ppsi);
+      void GetDisplayName(uint sigdnName, [MarshalAs(UnmanagedType.LPWStr)] out string ppszName);
+      void GetAttributes(uint sfgaoMask, out uint psfgaoAttribs);
+      void Compare(IShellItem psi, uint hint, out int piOrder);
+    }
+
+    [ComImport, Guid("42f85136-db7e-439c-85f1-e4075d135fc8"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    interface IFileDialog {
+      [PreserveSig] int Show(IntPtr parent);
+      void SetFileTypes(uint cFileTypes, [MarshalAs(UnmanagedType.LPArray)] FilterSpec[] rgFilterSpec);
+      void SetFileTypeIndex(uint iFileType);
+      void GetFileTypeIndex(out uint piFileType);
+      void Advise(IntPtr pfde, out uint pdwCookie);
+      void Unadvise(uint dwCookie);
+      void SetOptions(uint fos);
+      void GetOptions(out uint pfos);
+      void SetDefaultFolder(IShellItem psi);
+      void SetFolder(IShellItem psi);
+      void GetFolder(out IShellItem ppsi);
+      void GetCurrentSelection(out IShellItem ppsi);
+      void SetFileName([MarshalAs(UnmanagedType.LPWStr)] string pszName);
+      void GetFileName([MarshalAs(UnmanagedType.LPWStr)] out string pszName);
+      void SetTitle([MarshalAs(UnmanagedType.LPWStr)] string pszTitle);
+      void SetOkButtonLabel([MarshalAs(UnmanagedType.LPWStr)] string pszText);
+      void SetFileNameLabel([MarshalAs(UnmanagedType.LPWStr)] string pszLabel);
+      void GetResult(out IShellItem ppsi);
+      void AddPlace(IShellItem psi, int fdap);
+      void SetDefaultExtension([MarshalAs(UnmanagedType.LPWStr)] string pszDefaultExtension);
+      void Close(int hr);
+      void SetClientGuid(ref Guid guid);
+      void ClearClientData();
+      void SetFilter(IntPtr pFilter);
+    }
+
+    [DllImport("shell32.dll", CharSet = CharSet.Unicode, PreserveSig = false)]
+    static extern void SHCreateItemFromParsingName(string pszPath, IntPtr pbc, [MarshalAs(UnmanagedType.LPStruct)] Guid riid, out IShellItem ppv);
+
+    [DllImport("user32.dll")]
+    static extern IntPtr GetForegroundWindow();
+
+    public static string Run(bool save, uint options, string title, string start, string name, string[] filterNames, string[] filterSpecs) {
+      IFileDialog dialog = save ? (IFileDialog)new FileSaveDialogCo() : (IFileDialog)new FileOpenDialogCo();
+      try {
+        uint current;
+        dialog.GetOptions(out current);
+        dialog.SetOptions(current | options | FOS_FORCEFILESYSTEM);
+        if (!String.IsNullOrEmpty(title)) dialog.SetTitle(title);
+        if (!String.IsNullOrEmpty(name)) dialog.SetFileName(name);
+        if (!String.IsNullOrEmpty(start)) {
+          try {
+            IShellItem folder;
+            SHCreateItemFromParsingName(start, IntPtr.Zero, typeof(IShellItem).GUID, out folder);
+            dialog.SetFolder(folder);
+          } catch (Exception) {
+            // a start folder that doesn't exist: the dialog opens where it would anyway
+          }
+        }
+        if (filterNames.Length > 0) {
+          FilterSpec[] specs = new FilterSpec[filterNames.Length];
+          for (int i = 0; i < specs.Length; i++) { specs[i].Name = filterNames[i]; specs[i].Spec = filterSpecs[i]; }
+          dialog.SetFileTypes((uint)specs.Length, specs);
+        }
+        int hr = dialog.Show(GetForegroundWindow());
+        if (hr == ERROR_CANCELLED) return Json(null);
+        Marshal.ThrowExceptionForHR(hr);
+        IShellItem result;
+        dialog.GetResult(out result);
+        string path;
+        result.GetDisplayName(SIGDN_FILESYSPATH, out path);
+        return Json(path);
+      } finally {
+        Marshal.ReleaseComObject(dialog);
+      }
+    }
+
+    static string Json(string path) {
+      if (path == null) return "{\\"path\\":null}";
+      StringBuilder sb = new StringBuilder("{\\"path\\":\\"");
+      foreach (char c in path) {
+        if (c == '"' || c == '\\\\') sb.Append('\\\\').Append(c);
+        else if (c < 0x20 || c > 0x7e) sb.Append("\\\\u").Append(((int)c).ToString("x4"));
+        else sb.Append(c);
+      }
+      return sb.Append("\\"}").ToString();
+    }
+  }
+}
+`;
+
+const FLAGS: Record<DialogKind, string> = {
+  folder: '[DeckBuilder.FileDialog]::FOS_PICKFOLDERS -bor [DeckBuilder.FileDialog]::FOS_PATHMUSTEXIST',
+  file: '[DeckBuilder.FileDialog]::FOS_FILEMUSTEXIST -bor [DeckBuilder.FileDialog]::FOS_PATHMUSTEXIST',
+  save: '[DeckBuilder.FileDialog]::FOS_OVERWRITEPROMPT -bor [DeckBuilder.FileDialog]::FOS_PATHMUSTEXIST',
+};
+
+/**
+ * The PowerShell script for one dialog kind. It holds no caller data: the options arrive as JSON
+ * on stdin, so a title can't inject script.
+ */
+export function dialogScript(kind: DialogKind): string {
+  return `
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+$o = [Console]::In.ReadToEnd() | ConvertFrom-Json
+Add-Type -TypeDefinition @'
+${DIALOG_CS}
+'@
+$names = @(); $specs = @()
+foreach ($f in @($o.filters)) { if ($f) { $names += [string]$f.name; $specs += (@($f.patterns) -join ';') } }
+$json = [DeckBuilder.FileDialog]::Run($${kind === 'save'}, (${FLAGS[kind]}), [string]$o.title, [string]$o.start, [string]$o.name, [string[]]$names, [string[]]$specs)
+[Console]::Out.Write($json)
+`;
+}
+
+async function windowsDialog(kind: DialogKind, req: Request, deps: DialogDeps): Promise<string | null> {
+  const proc = deps.spawn(dialogScript(kind), { sta: true, stdin: 'pipe', stdout: 'pipe' });
+  proc.stdin.write(asciiJson(req));
+  proc.stdin.end();
+  const [stdout, stderr, code] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
+  if (code !== 0) throw new PlatformError('dialogFailed', 'The dialog could not be opened.', stderr.trim());
+  try {
+    const { path } = JSON.parse(stdout) as { path: unknown };
+    if (path === null || typeof path === 'string') return path || null;
+  } catch {
+    // reported below
+  }
+  throw new PlatformError('dialogFailed', 'The dialog could not be opened.', stdout.trim());
+}
+
+// --- Linux and macOS (best-effort, untested) -------------------------------------------------
+
+async function runDialog(argv: string[]): Promise<string | null> {
+  let proc: Bun.Subprocess<'ignore', 'pipe', 'pipe'>;
+  try {
+    proc = Bun.spawn(argv, { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' });
+  } catch (err) {
+    throw new PlatformError('dialogFailed', 'The dialog could not be opened.', (err as Error).message);
+  }
+  const [stdout, stderr, code] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
+  if (code === 1) return null;
+  if (code !== 0) throw new PlatformError('dialogFailed', 'The dialog could not be opened.', stderr.trim());
+  return stdout.replace(/\r?\n$/, '') || null;
+}
+
+function zenityDialog(kind: DialogKind, req: Request): Promise<string | null> {
+  const argv = ['zenity', '--file-selection'];
+  if (req.title) argv.push(`--title=${req.title}`);
+  if (kind === 'folder') argv.push('--directory');
+  if (kind === 'save') argv.push('--save', '--confirm-overwrite');
+  const start = kind === 'save' ? req.name : req.start && req.start.replace(/\/?$/, '/');
+  if (start) argv.push(`--filename=${start}`);
+  for (const f of req.filters) argv.push(`--file-filter=${f.name || f.patterns.join(' ')} | ${f.patterns.join(' ')}`);
+  return runDialog(argv);
+}
+
+// The AppleScript text is fixed per option set; the values arrive as `argv` of its run handler.
+function macDialog(kind: DialogKind, req: Request): Promise<string | null> {
+  const args: string[] = [];
+  const clauses: string[] = [];
+  const arg = (value: string) => {
+    args.push(value);
+    return `(item ${args.length} of argv)`;
+  };
+  if (req.title) clauses.push(`with prompt ${arg(req.title)}`);
+  if (kind === 'save' && req.name) clauses.push(`default name ${arg(req.name)}`);
+  if (kind !== 'save' && req.start) clauses.push(`default location (POSIX file ${arg(req.start)})`);
+  const command = { folder: 'choose folder', file: 'choose file', save: 'choose file name' }[kind];
+  const lines = ['on run argv', `POSIX path of (${command} ${clauses.join(' ')})`, 'end run'];
+  return runDialog(['osascript', ...lines.flatMap((line) => ['-e', line]), '--', ...args]);
+}
+
+// `bun packages/platform/src/dialogs.ts --selftest`: opens the folder picker, then "Save as";
+// prints each result (null = cancelled).
+if (import.meta.main && process.argv.includes('--selftest')) {
+  console.log('pickFolder:', await pickFolder({ title: 'DeckBuilder self-test: pick a folder "ção"' }));
+  console.log(
+    'saveFileAs:',
+    await saveFileAs({ title: 'DeckBuilder self-test: save as', suggestedName: 'notes.md', filters: [{ name: 'Markdown', patterns: ['*.md'] }] }),
+  );
+}

package/src/editors.ts

@@ -0,0 +1,107 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { isAbsolute, win32 } from 'node:path';
+import { PlatformError } from './errors.ts';
+import { launch } from './launch.ts';
+
+export type EditorId = 'vscode' | 'intellij';
+
+export const EDITOR_NAMES: Record<EditorId, string> = { vscode: 'VS Code', intellij: 'IntelliJ IDEA' };
+
+export interface EditorDeps {
+  platform: NodeJS.Platform;
+  env: Record<string, string | undefined>;
+  which(cmd: string): string | null;
+  exists(path: string): boolean;
+  readText(path: string): Promise<string | null>;
+  listDir(path: string): Promise<string[]>;
+}
+
+const defaultDeps: EditorDeps = {
+  platform: process.platform,
+  env: process.env,
+  which: (cmd) => Bun.which(cmd),
+  exists: (path) => existsSync(path),
+  readText: (path) => readFile(path, 'utf8').catch(() => null),
+  listDir: (path) => readdir(path).catch(() => []),
+};
+
+const versionOf = (name: string) => (name.match(/(\d+(?:\.\d+)*)$/)?.[1] ?? '').split('.').filter(Boolean).map(Number);
+
+function compareVersions(a: string, b: string): number {
+  const [x, y] = [versionOf(a), versionOf(b)];
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const d = (x[i] ?? 0) - (y[i] ?? 0);
+    if (d) return d;
+  }
+  return a.localeCompare(b);
+}
+
+async function findOnWindows(id: EditorId, deps: EditorDeps): Promise<string | null> {
+  const { env, exists } = deps;
+  const local = env.LOCALAPPDATA;
+  const programs = env.ProgramFiles;
+  if (id === 'vscode') {
+    const code = deps.which('code');
+    if (code && /\x5cbin\x5ccode\.cmd$/i.test(code)) {
+      const exe = win32.join(win32.dirname(code), '..', 'Code.exe');
+      if (exists(exe)) return exe;
+    }
+    const candidates = [
+      local && win32.join(local, 'Programs', 'Microsoft VS Code', 'Code.exe'),
+      programs && win32.join(programs, 'Microsoft VS Code', 'Code.exe'),
+    ];
+    return candidates.find((c): c is string => !!c && exists(c)) ?? null;
+  }
+  const script = deps.which('idea') ?? (local ? win32.join(local, 'JetBrains', 'Toolbox', 'scripts', 'idea.cmd') : null);
+  const text = script ? await deps.readText(script) : null;
+  const fromScript = text?.match(/"([^"]+\x5cidea64\.exe)"/i)?.[1];
+  if (fromScript && exists(fromScript)) return fromScript;
+  for (const base of [local && win32.join(local, 'Programs'), programs && win32.join(programs, 'JetBrains')]) {
+    if (!base) continue;
+    const folders = (await deps.listDir(base)).filter((name) => name.startsWith('IntelliJ IDEA')).sort(compareVersions);
+    const newest = folders.at(-1);
+    if (!newest) continue;
+    const exe = win32.join(base, newest, 'bin', 'idea64.exe');
+    if (exists(exe)) return exe;
+  }
+  return null;
+}
+
+/** The program that opens `id`, or null when it isn't installed (best-effort off Windows). */
+export async function findEditor(id: EditorId, deps: EditorDeps = defaultDeps): Promise<string | null> {
+  if (deps.platform === 'win32') return findOnWindows(id, deps);
+  return deps.which(id === 'vscode' ? 'code' : 'idea');
+}
+
+export interface OpenInEditorOptions {
+  /** The project folder (absolute). */
+  folder: string;
+  /** A file inside it (absolute). */
+  file?: string;
+  line?: number;
+}
+
+/** The argv that opens the project (and a file) in the editor; no shell is involved. */
+export function editorArgv(id: EditorId, exe: string, opts: OpenInEditorOptions): string[] {
+  const { folder, file, line } = opts;
+  if (id === 'vscode') return file ? [exe, folder, '-g', `${file}:${line ?? 1}`] : [exe, folder];
+  return file ? [exe, '--line', String(line ?? 1), file] : [exe, folder];
+}
+
+/**
+ * Opens a project in an editor, detached. Rejects with PlatformError 'editorNotExe' unless `exe`
+ * is an existing absolute path (on Windows a `.exe`): `code.cmd` and `idea.cmd` would go through
+ * cmd.exe, which interprets `&`, `%` and `^` in a project path.
+ */
+export async function openInEditor(
+  id: EditorId,
+  exe: string,
+  opts: OpenInEditorOptions,
+  deps: Pick<EditorDeps, 'platform' | 'exists'> = defaultDeps,
+): Promise<void> {
+  const win = deps.platform === 'win32';
+  const valid = win ? win32.isAbsolute(exe) && /\.exe$/i.test(exe) : isAbsolute(exe);
+  if (!valid || !deps.exists(exe)) throw new PlatformError('editorNotExe', 'The editor program must be an existing .exe file.', exe);
+  launch(editorArgv(id, exe, opts));
+}

package/src/errors.ts

@@ -0,0 +1,15 @@
+/**
+ * An expected platform failure. platform has no server-core dep, so server code maps it with
+ * `fromPlatform` (server-mods) to an AppError: `code` picks the UI text (`error.<code>`),
+ * `detail` carries raw tool output.
+ */
+export class PlatformError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly detail?: string,
+  ) {
+    super(message);
+    this.name = 'PlatformError';
+  }
+}

package/src/exe.ts

@@ -0,0 +1,42 @@
+import { rm } from 'node:fs/promises';
+import { basename, dirname, extname, join } from 'node:path';
+
+/** True inside a `bun build --compile` exe, false when running from source with bun. */
+export function isCompiledExe(execPath = process.execPath): boolean {
+  return !/^(bun|node)(\.exe)?$/i.test(basename(execPath));
+}
+
+/**
+ * Files next to the exe during a self-update: `fresh` is the downloaded release, `old` the
+ * running exe moved aside (Windows allows renaming a running exe, not replacing it).
+ */
+export function updatePaths(execPath: string): { fresh: string; old: string } {
+  const ext = extname(execPath);
+  const stem = join(dirname(execPath), basename(execPath, ext));
+  return { fresh: `${stem}.new${ext}`, old: `${stem}.old${ext}` };
+}
+
+/**
+ * Run by the new exe (`--after-update`) before anything else: deleting the old exe fails while
+ * the old process still runs, so success means it has exited. Gives up after `timeoutMs` (false),
+ * leaving the file for the next update to remove.
+ */
+export async function removeOldExe(
+  execPath: string,
+  opts: { remove?: (path: string) => Promise<void>; timeoutMs?: number; pollMs?: number; sleep?: (ms: number) => Promise<void> } = {},
+): Promise<boolean> {
+  const remove = opts.remove ?? ((path: string) => rm(path, { force: true }));
+  const sleep = opts.sleep ?? ((ms: number) => Bun.sleep(ms));
+  const pollMs = opts.pollMs ?? 250;
+  const tries = Math.max(1, Math.ceil((opts.timeoutMs ?? 30_000) / pollMs));
+  const { old } = updatePaths(execPath);
+  for (let i = 0; i < tries; i++) {
+    try {
+      await remove(old);
+      return true;
+    } catch {
+      await sleep(pollMs);
+    }
+  }
+  return false;
+}

package/src/files.ts

@@ -0,0 +1,49 @@
+import { dirname, extname } from 'node:path';
+import { PlatformError } from './errors.ts';
+import { launch } from './launch.ts';
+
+// Extensions whose default app shows the file. An allowlist: a denylist misses every script type
+// another tool registers (`.py` → py.exe). `.svg`/`.html` open in a browser and run script; macro
+// formats (`.docm`, `.xlsm`, `.pptm`) are left out too.
+const OPENABLE = new Set(
+  [
+    '.txt .md .markdown .log .csv .tsv .json .xml .yaml .yml .toml .ini .sql',
+    '.pdf .docx .xlsx .pptx .odt .ods .odp',
+    '.png .jpg .jpeg .gif .webp .bmp .ico .avif .tif .tiff',
+    '.mp3 .wav .ogg .flac .m4a .mp4 .webm .mov .mkv .avi',
+    '.zip',
+  ].join(' ').split(' '),
+);
+
+/** True when `path` is a document, image, media file or zip that `openWithDefault` may open. */
+export function isOpenable(path: string): boolean {
+  return OPENABLE.has(extname(path).toLowerCase());
+}
+
+/**
+ * The command that opens `path` with its default app. On Windows the path is quoted and passed
+ * verbatim: explorer.exe splits an unquoted command line at commas, so `run.cmd,a.txt` ran `run.cmd`.
+ */
+export function openArgv(path: string, platform: NodeJS.Platform = process.platform): { argv: string[]; verbatim: boolean } {
+  // Windows paths can't contain `"`, so quoting is safe.
+  if (platform === 'win32') return { argv: ['explorer.exe', `"${path}"`], verbatim: true };
+  return { argv: [platform === 'darwin' ? 'open' : 'xdg-open', path], verbatim: false };
+}
+
+/** Shows the absolute `path` selected in the OS file manager (Linux: opens its folder). */
+export async function revealInFolder(path: string): Promise<void> {
+  // explorer.exe parses its own command line; Windows paths can't contain `"`, so quoting is safe.
+  if (process.platform === 'win32') launch(['explorer.exe', `/select,"${path}"`], true);
+  else if (process.platform === 'darwin') launch(['open', '-R', path]);
+  else launch(['xdg-open', dirname(path)]);
+}
+
+/**
+ * Opens the absolute `path` with the OS default app. Rejects with PlatformError 'openRefused'
+ * unless `isOpenable(path)`: the app shows files, it never runs them.
+ */
+export async function openWithDefault(path: string): Promise<void> {
+  if (!isOpenable(path)) throw new PlatformError('openRefused', 'This file type is not opened from the app.', path);
+  const { argv, verbatim } = openArgv(path);
+  launch(argv, verbatim);
+}

package/src/home.ts

@@ -0,0 +1,7 @@
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+/** App data folder `~/.<id>`: outside the install folder, so data survives reinstalls and updates. */
+export function appHome(id: string): string {
+  return join(homedir(), `.${id}`);
+}