@mnstry/atelier 0.2.0-alpha.12 → 0.2.0-alpha.14

package/src/runtime/obsidian/app-registration.mjs

@@ -5,7 +5,7 @@ import { MAX_OBSIDIAN_SETTINGS_BYTES, OBSIDIAN_SETTINGS_FILE, enclosingVaults, f
 import { openRegularFileNoFollow, realPathAsStored, syncPrivateDirectory } from '../../project/private-state.mjs'
 
 // Adding a view's vault to Obsidian's own vault list while Obsidian is not
-// running, so that `obsidian://open?path=` finds it when the app starts.
+// running, so that the app opens it when it starts.
 //
 // Outside Atelier's own storage, it is the only file of another application
 // Atelier writes. The list is `obsidian.json` in the app's user-data directory
@@ -18,10 +18,11 @@ import { openRegularFileNoFollow, realPathAsStored, syncPrivateDirectory } from
 //
 //   - never for a Flatpak or snap build, which reads its list inside its
 //     sandbox and never this file (`sandbox`, see obsidianSandboxedBuild);
-//   - only an existing file, in an existing user-data directory, both this
+//   - an existing file only in an existing user-data directory, both this
 //     user's own, a real directory and a regular file (no link, and no second
-//     name: a hard link would keep the old list), holding a JSON object: a file
-//     Obsidian has not written is never created;
+//     name: a hard link would keep the old list), holding a JSON object;
+//   - a file that does not exist (Obsidian never started on this account) is
+//     created, and only then: see createObsidianSettings below;
 //   - never for a vault inside a folder the list has as a vault already: the
 //     app would show its notes in that vault too, and a call run in its folder
 //     would reach that vault (see vault-list.mjs);
@@ -29,6 +30,12 @@ import { openRegularFileNoFollow, realPathAsStored, syncPrivateDirectory } from
 //     it, as values: the app itself rewrites the file with JSON.stringify;
 //   - the new entry is { path: the vault root's real path, ts: now, open:
 //     true } under a fresh 16-hex id that no entry has;
+//   - the command-line switch: whenever the list is written, `cli` is set to
+//     true when it is not (the default of a new installation is off, and
+//     `open` needs the command line while the app holds the vault). A vault the
+//     list has already, with `cli` not true, is written for the switch alone.
+//     Only here, so only while no Obsidian runs: a running app keeps its
+//     switch in memory and would write it back;
 //   - the new file is no larger than a settings file this module reads;
 //   - the bytes as they were are kept beside it in
 //     `obsidian.json.atelier-backup-<UTC time>`, fsynced, before the file is
@@ -46,13 +53,14 @@ const currentUid = () => (typeof process.getuid === 'function' ? process.getuid(
 const compactUtc = (ms) => new Date(ms).toISOString().replace(/[-:.]/g, '')
 const BACKUP = new RegExp(`^${OBSIDIAN_SETTINGS_FILE.replaceAll('.', '\\.')}\\.atelier-backup-\\d{8}T\\d{9}Z$`)
 
-// Keeps the first backup, the list as it was before Atelier ever wrote it, and `latest`; removes the ones between.
-// Their names sort as their times. A backup that cannot be removed stays.
-function pruneBackups(directory, latest) {
+// Keeps the first backup, the list as it was before Atelier ever wrote it, `latest`, and the names in `keep` (a copy
+// the same run took before it quit the app); removes the others between. Their names sort as their times. A backup
+// that cannot be removed stays.
+function pruneBackups(directory, latest, keep = []) {
   let names
   try { names = fs.readdirSync(directory).filter((name) => BACKUP.test(name)).sort() } catch { return }
   for (const name of names.slice(1)) {
-    if (name === latest) continue
+    if (name === latest || keep.includes(name)) continue
     const file = path.join(directory, name)
     try { if (fs.lstatSync(file).isFile()) fs.unlinkSync(file) } catch { /* it stays */ }
   }
@@ -82,35 +90,113 @@ function readBytesNoFollow(file) {
   try { return fs.readFileSync(descriptor) } finally { try { fs.closeSync(descriptor) } catch { /* read already, or failed */ } }
 }
 
-// { ok: true, registered: 'already' | 'written', entry: { id, path, open }, confirmed, vaults, backupPath?, reason? }
-// or a typed refusal { ok: false, code, message }. `confirmed` is false when an
-// app appeared right after the rename (`app-started-during-registration`): it
-// may have read the list before it, so whoever asked verifies through the
-// app; and when the written file could not be read back to find the entry
-// (`registration-not-read-back`). `vaults` is the list as it was found or
-// written. `processProbe()` answers 'absent', 'running' or 'unknown'; only
-// 'absent' allows a write. `sandbox` names a Flatpak or snap build found for
+// Creates the settings file of an Obsidian that never started on this account:
+// the file does not exist, and the process table says, positively, that no
+// Obsidian runs, read before and again immediately before the file appears.
+// The app reads the file when it starts (a missing or unreadable one reads as
+// no settings) and opens every vault flagged open, so a plain start opens this
+// one, with its command line on. Only:
+//
+//   - in the user-data directory as it is when that is this user's own real
+//     directory, or, when it does not exist, in one created here with mode
+//     0700 inside an existing real parent directory (a missing parent is
+//     `obsidian-settings-missing`: nothing is created above the directory);
+//   - with exactly { "vaults": { "<16 hex>": { path, ts, open: true } },
+//     "cli": true }, mode 0600;
+//   - by an exclusive create: the complete bytes are written, fsynced, to a
+//     temporary file in the directory, which is then linked to the file's name
+//     (a link fails on any name there, a file the app wrote meanwhile
+//     included, which is kept: `obsidian-settings-changed`), and the
+//     temporary name removed. A reader never sees a part of the file.
+//
+// There is nothing to back up. A refusal removes what it created, the
+// directory included.
+function createObsidianSettings({ userDataDir, vaultRoot, absent, now, randomBytes, uid }) {
+  const owned = (stat) => uid === null || stat.uid === uid
+  let directory = null
+  try { directory = fs.lstatSync(userDataDir) } catch (error) { if (error.code !== 'ENOENT') return refused('obsidian-settings-unreadable', 'the Obsidian settings directory cannot be read') }
+  let folder
+  try { folder = realPathAsStored(vaultRoot) } catch { return refused('vault-root-missing', 'the view\'s vault folder does not exist') }
+  if (!fs.statSync(folder).isDirectory()) return refused('vault-root-missing', 'the view\'s vault folder is not a directory')
+  let madeDirectory = false
+  if (directory === null) {
+    const parent = path.dirname(userDataDir)
+    let above
+    try { above = fs.lstatSync(parent) } catch { above = null }
+    if (above === null || above.isSymbolicLink() || !above.isDirectory() || !owned(above)) return refused('obsidian-settings-missing', 'Obsidian has no settings directory on this account, and the folder it would be in is missing, a link or not this user\'s own')
+    try { fs.mkdirSync(userDataDir, { mode: 0o700 }) } catch (error) {
+      return refused(error.code === 'EEXIST' ? 'obsidian-settings-changed' : 'obsidian-settings-unwritable', 'the Obsidian settings directory cannot be created')
+    }
+    madeDirectory = true
+    directory = fs.lstatSync(userDataDir)
+  }
+  const removeDirectory = () => { if (madeDirectory) try { fs.rmdirSync(userDataDir) } catch { /* something else is in it now: it stays */ } }
+  if (directory.isSymbolicLink() || !directory.isDirectory()) return refused('obsidian-settings-unsafe', 'the Obsidian settings directory is a link or not a directory')
+  if (!owned(directory)) return refused('obsidian-settings-not-owned', 'the Obsidian settings directory belongs to another user')
+  const id = randomBytes(8).toString('hex')
+  const at = now()
+  const document = { vaults: { [id]: { path: folder, ts: at, open: true } }, cli: true }
+  const bytes = Buffer.from(JSON.stringify(document), 'utf8')
+  if (bytes.length > MAX_OBSIDIAN_SETTINGS_BYTES) { removeDirectory(); return refused('obsidian-settings-too-large', 'with this vault the Obsidian settings file would be larger than a settings file can be') }
+  const file = path.join(userDataDir, OBSIDIAN_SETTINGS_FILE)
+  const temporary = path.join(userDataDir, `.${OBSIDIAN_SETTINGS_FILE}.atelier-${randomBytes(6).toString('hex')}.tmp`)
+  const undo = () => { try { fs.unlinkSync(temporary) } catch { /* already gone */ } removeDirectory() }
+  try { writeNewFile(temporary, bytes, 0o600) } catch { undo(); return refused('obsidian-settings-unwritable', 'the Obsidian settings directory cannot be written') }
+  // Immediately before the file appears: still no app.
+  if (!absent()) { undo(); return refused('app-may-be-running', 'an Obsidian process appeared, and its settings belong to it') }
+  try { fs.linkSync(temporary, file) } catch (error) {
+    undo()
+    return refused(error.code === 'EEXIST' ? 'obsidian-settings-changed' : 'obsidian-settings-unwritable', error.code === 'EEXIST' ? 'an Obsidian settings file appeared while it was being created, and it was kept as it is' : 'the Obsidian settings file cannot be created')
+  }
+  try { fs.unlinkSync(temporary) } catch { /* the file is complete; a second name is refused by the next write */ }
+  try { syncPrivateDirectory(userDataDir); if (madeDirectory) syncPrivateDirectory(path.dirname(userDataDir)) } catch { /* the file exists; a directory that cannot be fsynced is not undone */ }
+  const stillAbsent = absent()
+  const written = readObsidianSettings({ userDataDir, uid })
+  const entry = written.ok ? findVaultEntry(written.vaults, vaultRoot) : null
+  const reason = !stillAbsent ? 'app-started-during-registration' : entry === null ? 'registration-not-read-back' : null
+  return {
+    ok: true, registered: 'created', entry: entry ?? { id, path: folder, open: true }, confirmed: reason === null, vaults: written.ok ? written.vaults : document.vaults,
+    file, created: { directory: madeDirectory }, cliTurnedOn: true, ...(reason === null ? {} : { reason }),
+  }
+}
+
+// { ok: true, registered: 'already' | 'written' | 'created', entry: { id, path, open }, confirmed, vaults, file, cliTurnedOn,
+// backupPath?, created?, reason? } or a typed refusal { ok: false, code, message }. `registered` is 'already' when the
+// list had the vault (then the file was written only to turn the command line on, `cliTurnedOn`), 'written' when this
+// vault was added to an existing file, 'created' when the file was created (createObsidianSettings). `confirmed` is
+// false when an app appeared right after the rename (`app-started-during-registration`): it may have read the list
+// before it, so whoever asked verifies through the app; and when the written file could not be read back to find the
+// entry (`registration-not-read-back`). `vaults` is the list as it was found or written. `processProbe()` answers
+// 'absent', 'running' or 'unknown'; only 'absent' allows a write. `sandbox` names a Flatpak or snap build found for
 // this account, which refuses (`obsidian-sandboxed`).
-export function registerVaultInObsidianSettings({ userDataDir, vaultRoot, processProbe, sandbox = null, now = () => Date.now(), randomBytes = cryptoRandomBytes, uid = currentUid() } = {}) {
+// `keepBackups`: backup names (in the file's directory) this write must not prune: the copy `open` kept before it
+// quit the app for this write.
+export function registerVaultInObsidianSettings({ userDataDir, vaultRoot, processProbe, sandbox = null, now = () => Date.now(), randomBytes = cryptoRandomBytes, uid = currentUid(), keepBackups = [] } = {}) {
   if (typeof processProbe !== 'function') throw new TypeError('registering a vault needs a process probe')
   if (typeof vaultRoot !== 'string' || !path.isAbsolute(vaultRoot) || vaultRoot.includes('\u0000')) throw new TypeError('vaultRoot must be an absolute path')
   if (sandbox !== null) return refused('obsidian-sandboxed', `this Obsidian is a ${sandbox} build, which reads its vault list inside its sandbox, where Atelier does not write`)
   const absent = () => { try { return processProbe() === 'absent' } catch { return false } }
   if (!absent()) return refused('app-may-be-running', 'an Obsidian process may be running, and its vault list belongs to it')
   const settings = readObsidianSettings({ userDataDir, uid })
+  // No file: Obsidian never started on this account. A missing directory is refused as missing when it has no parent.
+  if (!settings.ok && settings.code === 'obsidian-settings-missing' && typeof userDataDir === 'string' && path.isAbsolute(userDataDir)) return createObsidianSettings({ userDataDir, vaultRoot, absent, now, randomBytes, uid })
   if (!settings.ok) return settings
   const known = findVaultEntry(settings.vaults, vaultRoot)
-  if (known) return { ok: true, registered: 'already', entry: known, confirmed: true, vaults: settings.vaults }
+  const switchOn = settings.document.cli !== true
+  if (known && !switchOn) return { ok: true, registered: 'already', entry: known, confirmed: true, vaults: settings.vaults, file: settings.file, cliTurnedOn: false }
   if (settings.links > 1) return refused('obsidian-settings-unsafe', 'the Obsidian settings file has a second name (a hard link), which a replacement would leave with the old list')
-  if (enclosingVaults({ vaults: settings.vaults, vaultRoot }).length > 0) return refused('vault-inside-another-vault', 'Obsidian lists a vault at a folder that contains this vault\'s folder')
+  if (!known && enclosingVaults({ vaults: settings.vaults, vaultRoot }).length > 0) return refused('vault-inside-another-vault', 'Obsidian lists a vault at a folder that contains this vault\'s folder')
 
-  let folder
-  try { folder = realPathAsStored(vaultRoot) } catch { return refused('vault-root-missing', 'the view\'s vault folder does not exist') }
-  if (!fs.statSync(folder).isDirectory()) return refused('vault-root-missing', 'the view\'s vault folder is not a directory')
-  let id
-  do { id = randomBytes(8).toString('hex') } while (Object.hasOwn(settings.vaults, id))
+  let folder = null
+  let id = null
+  if (!known) {
+    try { folder = realPathAsStored(vaultRoot) } catch { return refused('vault-root-missing', 'the view\'s vault folder does not exist') }
+    if (!fs.statSync(folder).isDirectory()) return refused('vault-root-missing', 'the view\'s vault folder is not a directory')
+    do { id = randomBytes(8).toString('hex') } while (Object.hasOwn(settings.vaults, id))
+  }
   const at = now()
-  const document = { ...settings.document, vaults: { ...settings.vaults, [id]: { path: folder, ts: at, open: true } } }
+  // The switch keeps its place when the file has one; otherwise it is added last, as the app would.
+  const document = { ...settings.document, ...(known ? {} : { vaults: { ...settings.vaults, [id]: { path: folder, ts: at, open: true } } }), ...(switchOn ? { cli: true } : {}) }
   const bytes = Buffer.from(JSON.stringify(document), 'utf8')
   if (bytes.length > MAX_OBSIDIAN_SETTINGS_BYTES) return refused('obsidian-settings-too-large', 'with this vault the Obsidian settings file would be larger than a settings file can be')
   const directory = path.dirname(settings.file)
@@ -140,15 +226,76 @@ export function registerVaultInObsidianSettings({ userDataDir, vaultRoot, proces
   }
   created.splice(0)
   try { syncPrivateDirectory(directory) } catch { /* the rename is done; a directory that cannot be fsynced is not undone */ }
-  pruneBackups(directory, path.basename(backupPath))
+  pruneBackups(directory, path.basename(backupPath), (Array.isArray(keepBackups) ? keepBackups : []).filter((name) => typeof name === 'string').map((name) => path.basename(name)))
   const stillAbsent = absent()
   const written = readObsidianSettings({ userDataDir, uid })
   const entry = written.ok ? findVaultEntry(written.vaults, vaultRoot) : null
   const reason = !stillAbsent ? 'app-started-during-registration' : entry === null ? 'registration-not-read-back' : null
   return {
-    ok: true, registered: 'written', entry: entry ?? { id, path: folder, open: true }, backupPath, confirmed: reason === null, vaults: written.ok ? written.vaults : document.vaults,
-    ...(reason === null ? {} : { reason }),
+    ok: true, registered: known ? 'already' : 'written', entry: entry ?? known ?? { id, path: folder, open: true }, backupPath, confirmed: reason === null, vaults: written.ok ? written.vaults : document.vaults,
+    file: settings.file, cliTurnedOn: switchOn, ...(reason === null ? {} : { reason }),
+  }
+}
+
+// Read-only, for `open` before it quits a running app to restart it: whether registerVaultInObsidianSettings would
+// write this vault into the settings file `settings` (a readObsidianSettings answer, read while the app runs), as far
+// as a read can tell. { ok: true, create } or { ok: false, code } with the refusal the write would give: an
+// unreadable, linked, foreign, sandboxed or too large file, a vault inside another listed vault, a vault folder that
+// is missing. A file that does not exist (an app that has shown only its starter window writes none) is the create
+// case, `create: true`, checked as createObsidianSettings checks before it writes: the vault folder is a directory,
+// and the user-data directory is this user's own real directory, or is absent inside this user's own real parent.
+// What only the moment of the write can tell (an app that appears, a file that changes) is still checked then.
+export function settingsWriteOutlook({ settings, vaultRoot, now = () => Date.now(), uid = currentUid() } = {}) {
+  const no = (code) => ({ ok: false, code })
+  if (typeof vaultRoot !== 'string' || !path.isAbsolute(vaultRoot)) return no('vault-root-missing')
+  if (settings?.ok !== true && settings?.code === 'obsidian-settings-missing') {
+    const userDataDir = settings.userDataDir
+    if (typeof userDataDir !== 'string' || !path.isAbsolute(userDataDir)) return no('obsidian-settings-location-unknown')
+    try { if (!fs.statSync(realPathAsStored(vaultRoot)).isDirectory()) return no('vault-root-missing') } catch { return no('vault-root-missing') }
+    const owned = (stat) => uid === null || stat.uid === uid
+    let directory = null
+    try { directory = fs.lstatSync(userDataDir) } catch (error) { if (error.code !== 'ENOENT') return no('obsidian-settings-unreadable') }
+    if (directory !== null) {
+      if (directory.isSymbolicLink() || !directory.isDirectory()) return no('obsidian-settings-unsafe')
+      return owned(directory) ? { ok: true, create: true } : no('obsidian-settings-not-owned')
+    }
+    let above = null
+    try { above = fs.lstatSync(path.dirname(userDataDir)) } catch { above = null }
+    return above !== null && !above.isSymbolicLink() && above.isDirectory() && owned(above) ? { ok: true, create: true } : no('obsidian-settings-missing')
+  }
+  if (settings?.ok !== true) return no(typeof settings?.code === 'string' ? settings.code : 'obsidian-settings-unreadable')
+  if (typeof settings.links === 'number' && settings.links > 1) return no('obsidian-settings-unsafe')
+  const size = Buffer.isBuffer(settings.bytes) ? settings.bytes.length : 0
+  const known = findVaultEntry(settings.vaults, vaultRoot)
+  if (known) return size + 16 > MAX_OBSIDIAN_SETTINGS_BYTES ? no('obsidian-settings-too-large') : { ok: true, create: false }
+  if (enclosingVaults({ vaults: settings.vaults, vaultRoot }).length > 0) return no('vault-inside-another-vault')
+  let folder
+  try { folder = realPathAsStored(vaultRoot); if (!fs.statSync(folder).isDirectory()) return no('vault-root-missing') } catch { return no('vault-root-missing') }
+  const entry = Buffer.byteLength(JSON.stringify({ '0123456789abcdef': { path: folder, ts: now(), open: true } }), 'utf8')
+  return size + entry + 16 > MAX_OBSIDIAN_SETTINGS_BYTES ? no('obsidian-settings-too-large') : { ok: true, create: false }
+}
+
+// Keeps a copy of the settings file as it is, beside it, under the backup name the write uses
+// (`obsidian.json.atelier-backup-<UTC time>`), fsynced, with the file's mode. Read-only for the file itself. `open`
+// takes it right before the first signal to a running app, so a list the app was writing when it ended can be
+// restored. { ok: true, backupPath } or a typed refusal (readObsidianSettings's, or `obsidian-settings-unwritable`).
+// The write that follows in the same run keeps it (`keepBackups`); a later write prunes it as any other backup.
+export function backupObsidianSettings({ userDataDir, now = () => Date.now(), uid = currentUid() } = {}) {
+  const settings = readObsidianSettings({ userDataDir, uid })
+  if (!settings.ok) return settings
+  const directory = path.dirname(settings.file)
+  for (let offset = 0; offset < 3; offset += 1) {
+    const backupPath = path.join(directory, `${OBSIDIAN_SETTINGS_FILE}.atelier-backup-${compactUtc(now() + offset)}`)
+    try {
+      writeNewFile(backupPath, settings.bytes, settings.mode)
+    } catch (error) {
+      if (error.code === 'EEXIST') continue
+      return refused('obsidian-settings-unwritable', 'a copy of the Obsidian settings file cannot be kept beside it')
+    }
+    try { syncPrivateDirectory(directory) } catch { /* the copy is written */ }
+    return { ok: true, backupPath }
   }
+  return refused('obsidian-settings-unwritable', 'a copy of the Obsidian settings file cannot be kept beside it')
 }
 
 // What the app looks like, as one comparable text, from what can be seen

package/src/runtime/obsidian/app-restart.mjs

@@ -0,0 +1,154 @@
+import path from 'node:path'
+import { performance } from 'node:perf_hooks'
+
+// Quitting a running Obsidian so that `open` can add a vault and turn its
+// command line on, only when a person asked for it (`--restart-obsidian`).
+//
+// `open` restarts the app in two states only, where it runs but cannot be
+// reached: its command line is turned off, or no vault is open (and the app
+// does not list the view's vault). The settings file then belongs to the
+// running app, which would write its own list back over any change, and the
+// app cannot be asked to add a vault. Before anything is sent, `open` checks,
+// read-only, that the write the restart is for can succeed (opening.mjs); right
+// before the first signal, once the main process is proven, `beforeSignal` keeps
+// a copy of the settings file, and a copy that cannot be kept sends nothing.
+//
+// SIGTERM, which Electron handles as a quit, is sent to one process: the app's
+// main process, proven from the process table, and never to anything else. The
+// main process is proven when, in a table of this machine's processes as
+// `pid ppid uid comm` (`comm` is the process's argv[0] as macOS reports it, not
+// a verified image: a process of this user can name itself anything, which is
+// why two candidates prove nothing):
+//
+//   - every process of the app (the names the process probe counts: `Obsidian`
+//     and the bundle's `Obsidian Helper…`) runs as this user;
+//   - exactly one of them names the app bundle's main executable by an absolute
+//     path (`…/Contents/MacOS/Obsidian`); a process shown by its short name
+//     only is not proven;
+//   - every other one is a child of that process (its helpers).
+//
+// Anything else (two instances, another user's app, a helper of another
+// parent, a table that cannot be read) is `app-main-process-unproven`, and no
+// signal is sent. Immediately before the signal the one process is read again
+// (`ppid uid start-time comm`) and must be of this user, under the parent the
+// table showed, with the same name, and read the same twice.
+//
+// What SIGTERM does (1.13.7, checked on an isolated instance): the app handles
+// the first one as a quit. It closes every window, keeping the vaults that were
+// open flagged open in its list, and its helper processes end; on macOS the main
+// process can then stay, with no window, as a macOS app does. Electron handles
+// only the first SIGTERM as a quit: a second one ends the process at once,
+// without its quit handlers. It is sent only after that same process has shown
+// no window and no helper (it is alone in the table, and reads the same) at
+// every reading for at least `lingerMs`, measured on a monotonic clock; a
+// reading that cannot be parsed does not count as alone. That is a margin, not
+// a proof that nothing is left to save. There is never a third signal, and
+// never another kind; an app that is still not gone is reported
+// (`app-did-not-quit`) and left to the person. `signals` counts the signals
+// that were delivered.
+//
+// Qualified on macOS only: on Linux a quit app is started again with a link,
+// which drops the other vaults' reopen flags (launch-plan.mjs), so the promise
+// that they reopen would not hold there.
+//
+// Nothing here reads the process table or sends a signal itself: every seam is
+// injected, with no default. Only the production seams module of the command
+// entry and the opt-in real-app suite, for its isolated app, construct one.
+
+export const RESTART_PLATFORMS = Object.freeze(['darwin'])
+const APP_PROCESS = /^obsidian(?: helper\b.*)?$/i
+const MAIN_EXECUTABLE = /^\/.+\.app\/Contents\/MacOS\/Obsidian$/i
+// `pid ppid uid comm`. macOS prints the uid of `nobody` as -2: a uid is signed.
+export const PROCESS_ROW = /^\s*(\d+)\s+(\d+)\s+(-?\d+)\s+(.+?)\s*$/
+// `ppid uid start-time comm`, one process read again.
+const DESCRIBED = /^\s*(\d+)\s+(-?\d+)\s+(.+?)\s*$/
+
+const unproven = (detail) => ({ state: 'unproven', reason: 'app-main-process-unproven', detail })
+const rowsOf = (table) => table.split('\n').filter((line) => line.trim() !== '').map((line) => PROCESS_ROW.exec(line))
+
+// Pure. The app's main process in a process table (`ps -A -o pid=,ppid=,uid=,comm=`), for the account `uid`:
+// { state: 'proven', pid, ppid, executable } | { state: 'absent' } | { state: 'unproven', reason, detail }.
+export function provenMainProcess({ table, uid } = {}) {
+  if (typeof table !== 'string' || table.trim() === '') return unproven('the process table could not be read')
+  if (!Number.isSafeInteger(uid) || uid < 0) return unproven('the account is not known')
+  const matches = rowsOf(table)
+  if (matches.some((match) => match === null)) return unproven('the process table has a line that is not a process')
+  const rows = matches.map((match) => ({ pid: Number(match[1]), ppid: Number(match[2]), uid: Number(match[3]), executable: match[4] }))
+  const app = rows.filter((row) => APP_PROCESS.test(path.posix.basename(row.executable)))
+  if (app.length === 0) return { state: 'absent' }
+  if (app.some((row) => row.uid !== uid)) return unproven('an Obsidian process runs as another user')
+  const main = app.filter((row) => /^obsidian$/i.test(path.posix.basename(row.executable)))
+  if (main.length !== 1) return unproven(main.length === 0 ? 'no Obsidian main process is in the process table' : 'more than one Obsidian main process runs')
+  const [one] = main
+  if (!MAIN_EXECUTABLE.test(one.executable)) return unproven('the main process does not name the app bundle\'s executable')
+  if (app.some((row) => row !== one && row.ppid !== one.pid)) return unproven('an Obsidian helper process is not a child of the main process')
+  return { state: 'proven', pid: one.pid, ppid: one.ppid, executable: one.executable }
+}
+
+// `readTable()`      -> the process table as provenMainProcess reads it (throws or answers '' when it cannot)
+// `readProcess(pid)` -> that process read again as `ppid uid start-time comm`, or null
+// `signal(pid)`      -> sends SIGTERM to exactly that pid; throws when it was not delivered
+// `processProbe()`   -> 'running' | 'absent' | 'unknown', the probe the settings write uses
+//
+// quit({ beforeSignal }) answers { quit: true, pid, signalled, signals, settingsCopy? } once the probe says `absent`,
+// or { quit: false, reason, signalled, signals, pid?, detail?, settingsCopy? }: `restart-platform-unqualified`,
+// `app-main-process-unproven` and the refusal of `beforeSignal` before any signal, `app-did-not-quit` after one, when
+// the probe did not say `absent` within `waitMs`. `beforeSignal()`, when given, runs once the main process is proven
+// and read again, immediately before the first signal: { ok: true, backupPath? } lets it be sent, anything else
+// ({ ok: false, code }) sends nothing. `now` is a monotonic clock in milliseconds.
+export function createAppQuitter({ platform, uid, readTable, readProcess, signal, processProbe, sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms) }), now = () => performance.now(), waitMs = 30_000, pollMs = 250, lingerMs = 5000 } = {}) {
+  for (const [name, seam] of Object.entries({ readTable, readProcess, signal, processProbe })) if (typeof seam !== 'function') throw new TypeError(`quitting Obsidian needs an injected ${name}`)
+  const probe = () => { try { return processProbe() } catch { return 'unknown' } }
+  const describe = (pid) => { try { const line = readProcess(pid); return typeof line === 'string' && line.trim() !== '' ? line.trim() : null } catch { return null } }
+  const table = () => { try { const text = readTable(); return typeof text === 'string' ? text : '' } catch { return '' } }
+  // The process read again is the one the table proved: this user's, under the parent the table showed, same name.
+  const isFound = (line, found) => {
+    const match = line === null ? null : DESCRIBED.exec(line)
+    return match !== null && Number(match[1]) === found.ppid && Number(match[2]) === uid && match[3].endsWith(found.executable)
+  }
+  // The proven main process alone in the table, still the process `seen` described: its windows closed, it did not quit.
+  const lingersAlone = (found, seen) => {
+    const matches = rowsOf(table())
+    if (matches.length === 0 || matches.some((match) => match === null)) return false
+    const rows = matches.filter((match) => APP_PROCESS.test(path.posix.basename(match[4])))
+    return rows.length === 1 && Number(rows[0][1]) === found.pid && describe(found.pid) === seen
+  }
+  return {
+    async quit({ beforeSignal = null } = {}) {
+      if (!RESTART_PLATFORMS.includes(platform)) return { quit: false, reason: 'restart-platform-unqualified', signalled: false, signals: 0 }
+      const found = provenMainProcess({ table: table(), uid })
+      if (found.state === 'absent') return probe() === 'absent' ? { quit: true, pid: null, signalled: false, signals: 0 } : { quit: false, reason: 'app-main-process-unproven', detail: 'the process table shows no Obsidian, and the process probe does not say it is gone', signalled: false, signals: 0 }
+      if (found.state !== 'proven') return { quit: false, reason: found.reason, detail: found.detail, signalled: false, signals: 0 }
+      const seen = describe(found.pid)
+      if (!isFound(seen, found)) return { quit: false, reason: 'app-main-process-unproven', detail: 'the main process read again is not the one the table showed', signalled: false, signals: 0 }
+      // Immediately before the signal: still the same process.
+      if (describe(found.pid) !== seen) return { quit: false, reason: 'app-main-process-unproven', detail: 'the main process changed while it was being proven', signalled: false, signals: 0 }
+      let copy = {}
+      if (typeof beforeSignal === 'function') {
+        let kept
+        try { kept = await beforeSignal() } catch { kept = null }
+        if (kept?.ok !== true) return { quit: false, reason: typeof kept?.code === 'string' ? kept.code : 'obsidian-settings-unwritable', signalled: false, signals: 0 }
+        if (typeof kept.backupPath === 'string') copy = { settingsCopy: kept.backupPath }
+      }
+      try { signal(found.pid) } catch { return { quit: false, reason: 'app-main-process-unproven', detail: 'the main process could not be signalled', signalled: false, signals: 0, ...copy } }
+      let signals = 1
+      let second = false
+      let aloneSince = null
+      const deadline = now() + waitMs
+      for (;;) {
+        if (probe() === 'absent') return { quit: true, pid: found.pid, signalled: true, signals, ...copy }
+        if (now() >= deadline) return { quit: false, reason: 'app-did-not-quit', pid: found.pid, signalled: true, signals, ...copy }
+        if (!second) {
+          if (!lingersAlone(found, seen)) aloneSince = null
+          else if (aloneSince === null) aloneSince = now()
+          else if (now() - aloneSince >= lingerMs) {
+            // Once, whether or not it is delivered.
+            second = true
+            try { signal(found.pid); signals = 2 } catch { /* not delivered: not counted */ }
+          }
+        }
+        await sleep(pollMs)
+      }
+    },
+  }
+}