synabun 2.0.0 → 2.0.5

package/neural-interface/lib/file-explorer-system.js

@@ -0,0 +1,355 @@
+// ── The File Explorer's system programs ──
+// The three things the explorer asks the operating system for: move something
+// to the Trash, show something in the file manager, and (for "Add project")
+// the folder picker. Every path is handed over as an argument of its own
+// (execFile, never a shell), so nothing in a file name is ever read as a command.
+//
+// Trash, per system:
+//   macOS    /usr/bin/trash (macOS 14 and later), else a move into ~/.Trash
+//   Windows  the Recycle Bin, through lib/file-explorer-trash.ps1, and only
+//            where the bin is sure to keep the item (recycleVerdict)
+//   Linux    `gio trash`, else the FreeDesktop Trash of the home folder
+// A path that has no Trash (another volume, a system without one) throws
+// TrashUnavailable and nothing is removed: the caller asks before deleting for good.
+
+import { execFile } from 'node:child_process';
+import {
+  closeSync, existsSync, lstatSync, mkdirSync, openSync, renameSync, rmdirSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { lstat, readdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { splitName } from '../public/shared/explorer/fx-names.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const TRASH_SCRIPT = join(HERE, 'file-explorer-trash.ps1');
+export const MAC_TRASH = '/usr/bin/trash';
+const SYSTEM_TIMEOUT_MS = 20000;
+
+/** There is no Trash for that path on this system. Nothing was removed. */
+export class TrashUnavailable extends Error {
+  constructor(message = 'No Trash is available for that path.') {
+    super(message);
+    this.name = 'TrashUnavailable';
+    this.code = 'no-trash';
+  }
+}
+
+/** Run a program with its arguments, without a shell. Rejects with the error (its `code` is the errno or exit code). */
+export function runProgram(file, args, { timeoutMs = SYSTEM_TIMEOUT_MS, env = process.env } = {}) {
+  return new Promise((done, failed) => {
+    try {
+      execFile(file, args, { timeout: timeoutMs, windowsHide: true, shell: false, env, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
+        if (error) { error.stderr = String(stderr || ''); failed(error); } else done({ stdout: String(stdout || ''), stderr: String(stderr || '') });
+      });
+    } catch (error) { failed(error); }
+  });
+}
+
+const two = (n) => String(n).padStart(2, '0');
+
+/**
+ * Move `path` into the folder `dir` without ever replacing something that is there. The name is reserved first by
+ * making an empty placeholder exclusively (a file, or a folder for a folder): `rename` then replaces only what
+ * was just made here. A second entry of one name gets the time appended, as the Finder does.
+ * @returns {string} where it is now
+ */
+export function moveIntoFolder(path, dir, { now = new Date() } = {}) {
+  const st = lstatSync(path);
+  const isDir = st.isDirectory();
+  const name = basename(path);
+  const { stem, ext } = isDir ? { stem: name, ext: '' } : splitName(name);
+  const stamp = `${two(now.getHours())}.${two(now.getMinutes())}.${two(now.getSeconds())}`;
+  for (let n = 0; n < 500; n++) {
+    const candidate = n === 0 ? name : `${stem} ${stamp}${n > 1 ? ` ${n}` : ''}${ext}`;
+    const dest = join(dir, candidate);
+    try {
+      if (isDir) mkdirSync(dest);
+      else closeSync(openSync(dest, 'wx'));
+    } catch (error) {
+      if (error?.code === 'EEXIST') continue;
+      throw error;
+    }
+    try {
+      renameSync(path, dest);
+      return dest;
+    } catch (error) {
+      try { if (isDir) rmdirSync(dest); else unlinkSync(dest); } catch { /* the placeholder stays: an empty entry in the Trash */ }
+      throw error;
+    }
+  }
+  throw new Error('No free name in the Trash.');
+}
+
+/**
+ * Give `path` the name `dest` only when nothing is there: a file or a folder that is under that name, or turns up
+ * under it while a request waits, is never replaced. The name is reserved first by an empty placeholder made
+ * exclusively (a file, or a folder for a folder), and `rename` then replaces only what was just made here. Throws
+ * EEXIST when the name is taken; a rename that fails leaves nothing under the name.
+ *
+ * The window that is left, and why it is accepted. Between the two calls (making the placeholder, renaming onto
+ * it) another writer can put something of its own in the placeholder's place, and the rename replaces it. That
+ * takes another program writing to the very same name in the instant between two system calls that follow one
+ * another; for a folder the system closes most of it (a rename onto a folder that got content fails by itself).
+ * The one way to close it for a file is to give the file its new name as a hard link, which replaces nothing; it
+ * was tried and taken out again, because macOS does not report the later deletion of a file that ever had a
+ * second hard link (APFS, macOS 26.6: not to a recursive watch, not to a watch on its folder). A file placed
+ * that way and deleted by something else kept its row in the tree: the explorer no longer followed the disk for
+ * every file it had renamed, moved or taken in. A window that needs a second writer on the same name in the same
+ * instant is the smaller cost. (tests/file-explorer-safety.test.mjs asks the real disk.)
+ * @param {string} path @param {string} dest
+ * @param {{ isDir?: boolean, platform?: string, rename?: typeof renameSync }} [o]
+ */
+export function renameExclusive(path, dest, { isDir = false, platform = process.platform, rename = renameSync } = {}) {
+  if (isDir && platform === 'win32') {
+    // Windows renames a folder over nothing at all, and not onto a placeholder either: the name is looked at,
+    // and the system's own refusal is what holds.
+    let there = true;
+    try { lstatSync(dest); } catch { there = false; }
+    if (there) throw Object.assign(new Error(`EEXIST: file already exists, rename '${path}' -> '${dest}'`), { code: 'EEXIST' });
+    rename(path, dest);
+    return;
+  }
+  if (isDir) mkdirSync(dest);
+  else closeSync(openSync(dest, 'wx'));
+  try {
+    rename(path, dest);
+  } catch (error) {
+    try { if (isDir) rmdirSync(dest); else unlinkSync(dest); } catch { /* the placeholder stays: an empty entry */ }
+    throw error;
+  }
+}
+
+// ── The Recycle Bin (Windows) ──
+// The Shell deletes for good, without a word, what its bin cannot keep: an item on a network or a removable
+// drive, on a drive whose bin is switched off, or larger than the bin. So the bin is asked about first
+// (file-explorer-trash.ps1 -Probe gives the facts) and the item is handed to the Shell only when the rule
+// below says it will be kept. The rule is here, not in the script, so that it is tested without Windows.
+
+const MB = 1024 * 1024;
+/** The Win32 drive type of a local disk (Win32_Volume.DriveType): the only kind whose bin keeps what it is given. */
+export const FIXED_DRIVE = 3;
+/** A bin that was never set up has the system's own limit: taken at its smallest. */
+export const DEFAULT_BIN_SHARE = 0.05;
+export const BIN_PROBE_TTL_MS = 5000;
+export const MEASURE_MAX_ENTRIES = 200000;
+
+/**
+ * Whether an item is sure to be kept by the Recycle Bin. Each of the two switches is `true` (off), `false` (on:
+ * also what the probe says of a setting that is not there, which is Windows' default) or anything else, which is
+ * "it could not be read": then nothing is known, and the answer is no.
+ * @param {{ driveType?: number | string, volumeBytes?: number | null, maxCapacityMB?: number | null, nukeOnDelete?: boolean | null, policyOff?: boolean | null, error?: string } | null} facts
+ *   what the probe said of the bin that serves the item's folder
+ * @param {number | null} sizeBytes how large the item is (`Infinity`: past the limit it was measured to; null: not known)
+ * @returns {{ ok: true } | { ok: false, reason: 'unknown' | 'drive' | 'off' | 'too-large' }} `unknown`: the bin could
+ *   not be asked, one of its switches could not be read, or the item was not measured; `drive`: not a local disk;
+ *   `off`: the bin is switched off, for the drive or by policy; `too-large`: the item is larger than the bin
+ */
+export function recycleVerdict(facts, sizeBytes) {
+  const no = (reason) => ({ ok: false, reason });
+  if (!facts || typeof facts !== 'object' || facts.error) return no('unknown');
+  if (facts.policyOff === true) return no('off');
+  if (facts.policyOff !== false) return no('unknown');
+  if (Number(facts.driveType) !== FIXED_DRIVE) return no('drive');
+  if (facts.nukeOnDelete === true) return no('off');
+  if (facts.nukeOnDelete !== false) return no('unknown');
+  const own = facts.maxCapacityMB;
+  const capacity = typeof own === 'number' && Number.isFinite(own) && own >= 0 ? own * MB
+    : typeof facts.volumeBytes === 'number' && Number.isFinite(facts.volumeBytes) && facts.volumeBytes > 0 ? facts.volumeBytes * DEFAULT_BIN_SHARE
+      : null;
+  if (capacity === null) return no('unknown');
+  if (typeof sizeBytes !== 'number' || Number.isNaN(sizeBytes) || sizeBytes < 0) return no('unknown');
+  return sizeBytes > capacity ? no('too-large') : { ok: true };
+}
+
+/**
+ * How large an entry is: a file's size, or everything below a folder (a link counts as the link it is).
+ * @param {string} path
+ * @param {{ stopAt?: number, maxEntries?: number }} [o] past `stopAt` bytes the answer is `Infinity` and the rest
+ *   is not walked; a folder of more than `maxEntries` entries is not measured
+ * @returns {Promise<number | null>} null when it cannot be said
+ */
+export async function entryBytes(path, { stopAt = Infinity, maxEntries = MEASURE_MAX_ENTRIES } = {}) {
+  let total = 0; let seen = 0;
+  const queue = [path];
+  try {
+    while (queue.length) {
+      const at = queue.pop();
+      if (++seen > maxEntries) return null;
+      const st = await lstat(at);
+      total += st.size;
+      if (total > stopAt) return Infinity;
+      if (st.isDirectory()) for (const name of await readdir(at)) queue.push(join(at, name));
+    }
+  } catch { return null; }
+  return total;
+}
+
+const BIN_REASONS = {
+  unknown: 'The Recycle Bin of that drive could not be asked about.',
+  drive: 'That drive has no Recycle Bin (a network or a removable drive).',
+  off: 'The Recycle Bin is switched off for that drive.',
+  'too-large': 'That is larger than the Recycle Bin of its drive.',
+};
+
+/** The FreeDesktop Trash of the home folder: `files/` holds the entry, `info/<name>.trashinfo` where it came from. */
+export function trashFreeDesktop(path, { trashDir, now = new Date() } = {}) {
+  const files = join(trashDir, 'files');
+  const info = join(trashDir, 'info');
+  mkdirSync(files, { recursive: true, mode: 0o700 });
+  mkdirSync(info, { recursive: true, mode: 0o700 });
+  const name = basename(path);
+  const isDir = lstatSync(path).isDirectory();
+  const { stem, ext } = isDir ? { stem: name, ext: '' } : splitName(name);
+  const when = `${now.getFullYear()}-${two(now.getMonth() + 1)}-${two(now.getDate())}T${two(now.getHours())}:${two(now.getMinutes())}:${two(now.getSeconds())}`;
+  const record = `[Trash Info]\nPath=${pathToFileURL(path).pathname}\nDeletionDate=${when}\n`;
+  for (let n = 1; n < 1000; n++) {
+    const candidate = n === 1 ? name : `${stem}.${n}${ext}`;
+    const infoFile = join(info, `${candidate}.trashinfo`);
+    if (existsSync(join(files, candidate))) continue;
+    // The record is written first, exclusively: that is what reserves the name (the Trash specification).
+    try { writeFileSync(infoFile, record, { flag: 'wx', mode: 0o600 }); }
+    catch (error) { if (error?.code === 'EEXIST') continue; throw error; }
+    try {
+      renameSync(path, join(files, candidate));
+      return join(files, candidate);
+    } catch (error) {
+      try { unlinkSync(infoFile); } catch { /* nothing to undo */ }
+      throw error;
+    }
+  }
+  throw new Error('No free name in the Trash.');
+}
+
+/**
+ * @param {object} [o]
+ * @param {string} [o.platform]
+ * @param {(file: string, args: string[]) => Promise<any>} [o.run] runs a program (tests hand in a recorder)
+ * @param {object} [o.env] @param {string} [o.home]
+ * @param {(path: string) => boolean} [o.exists]
+ * @param {typeof entryBytes} [o.measure] @param {() => number} [o.now] Windows: how an item is measured, and the clock
+ * @returns {{ kind: string, available: () => boolean, trash: (path: string) => Promise<void> }} `path` is a
+ *   canonical absolute path that exists; `trash` rejects with TrashUnavailable when it has nowhere to go
+ */
+export function createTrash({
+  platform = process.platform, run = runProgram, env = process.env, home = homedir(), exists = existsSync,
+  measure = entryBytes, now = () => Date.now(),
+} = {}) {
+  // A cross-device move, or a Trash that cannot be written, is "no Trash here", not a failure of the delete.
+  const noTrashHere = (error) => ['EXDEV', 'EACCES', 'EPERM', 'ENOENT', 'EROFS'].includes(error?.code);
+
+  if (platform === 'darwin') {
+    const fallback = (path) => {
+      try { moveIntoFolder(path, join(home, '.Trash')); }
+      catch (error) { if (noTrashHere(error)) throw new TrashUnavailable(); throw error; }
+    };
+    return {
+      kind: 'macos',
+      available: () => true,
+      async trash(path) {
+        if (exists(MAC_TRASH)) {
+          try { await run(MAC_TRASH, [path]); return; }
+          catch { if (!exists(path)) return; /* it went all the same */ }
+        }
+        fallback(path);
+      },
+    };
+  }
+
+  if (platform === 'win32') {
+    const script = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', TRASH_SCRIPT];
+    const asked = new Map();   // folder → { at, facts }: the rows of one delete are mostly of one folder
+    // What is known of the bin that serves a folder, or null when it could not be asked.
+    async function binOf(folder) {
+      const known = asked.get(folder);
+      if (known && now() - known.at < BIN_PROBE_TTL_MS) return known.facts;
+      let facts = null;
+      try { facts = JSON.parse(String((await run('powershell.exe', [...script, '-Probe', folder]))?.stdout || '').trim()); } catch { facts = null; }
+      asked.set(folder, { at: now(), facts });
+      if (asked.size > 64) asked.delete(asked.keys().next().value);
+      return facts;
+    }
+    return {
+      kind: 'windows',
+      available: () => true,
+      async trash(path) {
+        // Asked first, and nothing is handed to the Shell unless the bin is sure to keep it: what it cannot keep
+        // it deletes for good without a word. Refused here, the item stays and the caller asks its own question.
+        const facts = await binOf(dirname(path));
+        const limit = typeof facts?.maxCapacityMB === 'number' ? facts.maxCapacityMB * MB : typeof facts?.volumeBytes === 'number' ? facts.volumeBytes * DEFAULT_BIN_SHARE : 0;
+        const verdict = recycleVerdict(facts, recycleVerdict(facts, 0).ok ? await measure(path, { stopAt: limit }) : null);
+        if (!verdict.ok) throw new TrashUnavailable(BIN_REASONS[verdict.reason]);
+        try {
+          await run('powershell.exe', [...script, path]);
+        } catch (error) {
+          if (!exists(path)) return;
+          // The script could not be run at all (no PowerShell), or the Shell refused the item.
+          throw new TrashUnavailable(String(error?.stderr || error?.message || '').trim() || undefined);
+        }
+      },
+    };
+  }
+
+  const trashDir = join(env.XDG_DATA_HOME || join(home, '.local', 'share'), 'Trash');
+  return {
+    kind: 'freedesktop',
+    available: () => true,
+    async trash(path) {
+      try { await run('gio', ['trash', '--', path]); return; }
+      catch { if (!exists(path)) return; /* no gio, or it refused: the home Trash is tried by hand */ }
+      try { trashFreeDesktop(path, { trashDir }); }
+      catch (error) { if (noTrashHere(error)) throw new TrashUnavailable(); throw error; }
+    },
+  };
+}
+
+/**
+ * The program that shows `path` selected in the system's file manager, as `{ file, args }` lists (the first that
+ * runs is used), or an empty list when this system has none.
+ */
+export function revealCommands(platform, path, { env = process.env } = {}) {
+  if (platform === 'darwin') return [{ file: 'open', args: ['-R', path] }];
+  // explorer.exe takes "/select," and the path as one argument, and answers 1 even when it worked.
+  if (platform === 'win32') return [{ file: 'explorer.exe', args: [`/select,${path}`], anyExit: true }];
+  if (!env.DISPLAY && !env.WAYLAND_DISPLAY) return [];
+  // dbus-send splits the items of an array at commas: one in the path is written as its escape, which a file
+  // manager reads back as the comma.
+  const url = pathToFileURL(path).href.replace(/,/g, '%2C');
+  return [
+    { file: 'dbus-send', args: ['--session', '--dest=org.freedesktop.FileManager1', '--type=method_call', '/org/freedesktop/FileManager1',
+      'org.freedesktop.FileManager1.ShowItems', `array:string:${url}`, 'string:'] },
+    { file: 'xdg-open', args: [dirname(path)] },
+  ];
+}
+
+/** @returns {{ available: () => boolean, reveal: (path: string) => Promise<boolean> }} */
+export function createRevealer({ platform = process.platform, run = runProgram, env = process.env } = {}) {
+  return {
+    available: () => revealCommands(platform, '/', { env }).length > 0,
+    async reveal(path) {
+      for (const command of revealCommands(platform, path, { env })) {
+        try { await run(command.file, command.args); return true; }
+        catch (error) { if (command.anyExit && error?.code !== 'ENOENT') return true; }
+      }
+      return false;
+    },
+  };
+}
+
+/**
+ * The system's folder picker as a program and its arguments. The prompt is an argument: it is never part of a
+ * script or a command line that is parsed again.
+ * @param {string} platform @param {string} prompt
+ * @param {{ scriptPath?: string }} [o] Windows: lib/folder-picker.ps1
+ */
+export function folderPickerCommand(platform, prompt, { scriptPath = join(HERE, 'folder-picker.ps1') } = {}) {
+  const title = String(prompt || 'Select a folder').replace(/[\r\n]+/g, ' ').slice(0, 200);
+  if (platform === 'win32') {
+    return { file: 'powershell.exe', args: ['-NoProfile', '-STA', '-WindowStyle', 'Hidden', '-ExecutionPolicy', 'Bypass', '-File', scriptPath, '-Title', title] };
+  }
+  if (platform === 'darwin') {
+    return { file: 'osascript', args: ['-e', 'on run argv', '-e', 'POSIX path of (choose folder with prompt (item 1 of argv))', '-e', 'end run', title] };
+  }
+  return { file: 'zenity', args: ['--file-selection', '--directory', `--title=${title}`] };
+}

package/neural-interface/lib/file-explorer-trash.ps1

@@ -0,0 +1,85 @@
+# The Recycle Bin, for lib/file-explorer-system.js. Two uses, and a path is always the script's argument (it is
+# never part of a command line that is parsed again):
+#
+#   file-explorer-trash.ps1 -Probe <folder>   says what is known of the bin that serves that folder, as one line
+#                                             of JSON, and removes nothing
+#   file-explorer-trash.ps1 <path>            moves that file or folder to the Recycle Bin
+#
+# Nothing is decided here. The Shell deletes for good, without a word, what its bin cannot keep (a network or a
+# removable drive, a bin that is switched off, an item larger than the bin), so the server asks first and applies
+# its rule, recycleVerdict() in lib/file-explorer-system.js, which is tested without Windows. It runs the second
+# form only for an item that rule says the bin will keep. Nobody has run this script on Windows yet.
+param([Parameter(Mandatory = $true, Position = 0)][string]$LiteralPath, [switch]$Probe)
+$ErrorActionPreference = 'Stop'
+
+if ($Probe) {
+  # The facts. A setting that is not there and a setting that could not be read are told apart: the first is
+  # Windows' default (the bin is on, with the system's own limit), the second is nothing known, and the rule
+  # takes "not known" for "not sure" and hands the bin nothing.
+  #   driveType      Win32_Volume.DriveType of the volume the folder is on (3 is a local disk); 0 when no volume
+  #                  is found for it (a network drive, a drive made by subst)
+  #   volumeBytes    how large that volume is
+  #   maxCapacityMB  the bin's own limit on that volume; $null when it was never set up
+  #   nukeOnDelete   "Don't move files to the Recycle Bin" is chosen for that volume: $true, $false (also when
+  #                  the setting is not there), or $null when it could not be read
+  #   policyOff      the same, by policy: $true, $false (also when there is no such policy), or $null when a
+  #                  policy key could not be read
+  $facts = @{ driveType = 0; volumeBytes = $null; maxCapacityMB = $null; nukeOnDelete = $null; policyOff = $null }
+
+  # The values of one registry key: a table (empty when the key is not there), or $null when it could not be read.
+  function Read-Key([string]$Key) {
+    try {
+      $values = @{}
+      $item = Get-ItemProperty -LiteralPath $Key -ErrorAction Stop
+      if ($null -ne $item) { foreach ($property in $item.PSObject.Properties) { $values[$property.Name] = $property.Value } }
+      return $values
+    } catch [System.Management.Automation.ItemNotFoundException] {
+      return @{}
+    } catch {
+      return $null
+    }
+  }
+
+  try {
+    $folder = [System.IO.Path]::GetFullPath($LiteralPath).TrimEnd('\') + '\'
+    # The volume whose mount point is the longest beginning of the folder: a volume mounted in a folder is found too.
+    $volume = Get-CimInstance -ClassName Win32_Volume |
+      Where-Object { $_.Name -and $folder.StartsWith($_.Name, [System.StringComparison]::OrdinalIgnoreCase) } |
+      Sort-Object -Property { $_.Name.Length } -Descending |
+      Select-Object -First 1
+    if ($volume) {
+      $facts.driveType = [int]$volume.DriveType
+      if ($volume.Capacity) { $facts.volumeBytes = [double]$volume.Capacity }
+      $id = [regex]::Match([string]$volume.DeviceID, '\{[0-9A-Fa-f-]{36}\}').Value
+      if ($id) {
+        $bin = Read-Key "HKCU:\Software\Microsoft\Windows\CurrentVersion\Explorer\BitBucket\Volume\$id"
+        if ($null -ne $bin) {
+          if ($bin.ContainsKey('MaxCapacity') -and $null -ne $bin['MaxCapacity']) { $facts.maxCapacityMB = [double]$bin['MaxCapacity'] }
+          $facts.nukeOnDelete = ($bin.ContainsKey('NukeOnDelete') -and $bin['NukeOnDelete'] -eq 1)
+        }
+      }
+    }
+    $off = $false
+    $read = $true
+    foreach ($hive in 'HKCU:', 'HKLM:') {
+      $policy = Read-Key "$hive\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer"
+      if ($null -eq $policy) { $read = $false }
+      elseif ($policy.ContainsKey('NoRecycleFiles') -and $policy['NoRecycleFiles'] -eq 1) { $off = $true }
+    }
+    # Switched off by one hive is off, whatever the other says; otherwise both must have been read to say "on".
+    if ($off) { $facts.policyOff = $true } elseif ($read) { $facts.policyOff = $false }
+  } catch {
+    $facts.error = [string]$_.Exception.Message
+  }
+  [Console]::Out.WriteLine(($facts | ConvertTo-Json -Compress))
+  exit 0
+}
+
+Add-Type -AssemblyName Microsoft.VisualBasic
+if (Test-Path -LiteralPath $LiteralPath -PathType Container) {
+  [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteDirectory($LiteralPath, 'OnlyErrorDialogs', 'SendToRecycleBin')
+} elseif (Test-Path -LiteralPath $LiteralPath) {
+  [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($LiteralPath, 'OnlyErrorDialogs', 'SendToRecycleBin')
+} else {
+  exit 3
+}