@mnstry/atelier 0.2.0-alpha.11 → 0.2.0-alpha.13

package/src/runtime/obsidian/app-production-seams.mjs

@@ -1,25 +1,39 @@
-import { execFile, spawnSync } from 'node:child_process'
+import { execFile, execFileSync, spawnSync } from 'node:child_process'
 import fs from 'node:fs'
+import { performance } from 'node:perf_hooks'
 import path from 'node:path'
-import { defaultCliPath, defaultObsidianProcessProbe } from '../../projection/obsidian/publication/transport.mjs'
-import { readVersionAnswer } from './app-capability.mjs'
+import { NEUTRAL_DIRECTORY, defaultCliPath, defaultObsidianProcessProbe, routedCall } from '../../projection/obsidian/publication/transport.mjs'
+import { obsidianSandboxedBuild, obsidianUserDataDir, readObsidianSettings } from '../../projection/obsidian/publication/vault-list.mjs'
+import { realPathAsStored } from '../../project/private-state.mjs'
+import { appAnswered, readEvalAnswer, readVersionAnswer } from './app-capability.mjs'
+import { backupObsidianSettings, registerVaultInObsidianSettings } from './app-registration.mjs'
+import { createAppQuitter } from './app-restart.mjs'
+import { launchPlan, runLaunchPlan, urlProcessed } from './launch-plan.mjs'
 
 // The production seams of `obsidian open` and of the service's adapter
-// factory: the only code that asks the installed Obsidian anything or asks the
-// operating system to open it.
+// factory: the only code that asks the installed Obsidian anything, asks the
+// operating system to open it, or quits it (for a restart a person asked for).
 //
 // This module is imported by exactly two places, both real command-line
 // entries and both behind an explicit `--adapter=obsidian-cli`: the service
 // entry (service-main.mjs) and the command entry (src/commands/obsidian.mjs,
-// `production: true`). No test imports it in-process, and importing it leaves
-// a trace below that the test suite asserts is absent. One test imports it in
-// a child process, with a stand-in for the command-line tool, to read the
-// version answers it parses.
+// `production: true`). No test of the default suite imports it in-process, and
+// importing it leaves a trace below that the test suite asserts is absent.
+// Tests import it in child processes only, with a private HOME: with a
+// stand-in for the command-line tool, to read the answers it parses, and with
+// a stand-in execFile, to check the launcher's executors; the opt-in real-app
+// suite imports it to reach an isolated app through that app's private HOME.
 //
-// Status: written against the documented command-line interface and NOT yet
-// exercised against a running app. The acceptance work qualifies it on an
-// isolated host before any of it is relied on; until then every answer it
-// cannot establish is the failing one.
+// Status: exercised against an isolated Obsidian 1.13.7 (installer 1.12.7) on
+// macOS by the opt-in real-app suite in test/obsidian-first-open-real-app.test.mjs;
+// every answer it cannot establish is the failing one.
+//
+// Where each call runs matters: the app answers a command in the window of the
+// vault its list routes the call to, opening that vault when it is closed (see
+// vault-list.mjs). A call about one vault goes where its route says, in its
+// folder or naming its id, and is not made without a route that reaches only
+// that vault; every other call runs in a directory that is no vault, so the
+// directory this process was started in never picks, or opens, a vault.
 globalThis[Symbol.for('mnstry.atelier.obsidian.production-seams-loaded')] = true
 
 const CLI_TIMEOUT_MS = 5000
@@ -34,74 +48,179 @@ function cliExists(cliPath) {
   try { return fs.statSync(cliPath).isFile() } catch { return false }
 }
 
-const NOT_ASKED = Object.freeze({ version: null, noVaultOpen: false })
+const NOT_ASKED = Object.freeze({ version: null, noVaultOpen: false, cliOff: false })
 
 const observationOf = ({ platform, cliPath, processes, answer }) => {
   const appPath = installedAppPath(platform)
   const present = cliExists(cliPath)
-  const answered = answer.version !== null || answer.noVaultOpen
+  const answered = answer.version !== null || answer.noVaultOpen || answer.cliOff === true
   return {
     installed: appPath === null ? (present !== false && (answered || present === true)) : fs.existsSync(appPath),
     cli: present === true || answered,
     running: processes === 'running' ? true : processes === 'absent' ? false : null,
     version: answer.version,
     ...(answer.noVaultOpen ? { noVaultOpen: true } : {}),
+    ...(answer.cliOff === true ? { cliOff: true } : {}),
   }
 }
 
-export function createProductionAppProbe({ platform = process.platform, env = process.env, cliPath = defaultCliPath(platform) } = {}) {
-  const options = { env, timeout: CLI_TIMEOUT_MS, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 1024 * 1024 }
+// `processProbe` reads the process table ('running', 'absent' or 'unknown');
+// `workingDirectory` is where calls that are about no vault run.
+export function createProductionAppProbe({ platform = process.platform, env = process.env, cliPath = defaultCliPath(platform), processProbe = () => defaultObsidianProcessProbe({ platform }), workingDirectory = NEUTRAL_DIRECTORY } = {}) {
+  const options = { env, cwd: workingDirectory, timeout: CLI_TIMEOUT_MS, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 1024 * 1024 }
+  const processes = () => { try { return processProbe() } catch { return 'unknown' } }
   return {
     // For the service's adapter factory, which is synchronous. The version is asked for only while an app runs.
     // Both output streams are read, whatever the exit status: the answer with no vault open is not a version.
     inspectSync() {
-      const processes = defaultObsidianProcessProbe({ platform })
-      if (processes === 'absent') return observationOf({ platform, cliPath, processes, answer: NOT_ASKED })
+      const seen = processes()
+      if (seen === 'absent') return observationOf({ platform, cliPath, processes: seen, answer: NOT_ASKED })
       let answer = NOT_ASKED
       try {
         const reply = spawnSync(cliPath, ['version'], { ...options, stdio: ['ignore', 'pipe', 'pipe'] })
         answer = readVersionAnswer({ stdout: reply.stdout, stderr: reply.stderr, exited: reply.error === undefined && reply.status === 0 })
       } catch { answer = NOT_ASKED }
-      return observationOf({ platform, cliPath, processes, answer })
+      return observationOf({ platform, cliPath, processes: seen, answer })
     },
     inspect() {
-      const processes = defaultObsidianProcessProbe({ platform })
-      if (processes === 'absent') return Promise.resolve(observationOf({ platform, cliPath, processes, answer: NOT_ASKED }))
+      const seen = processes()
+      if (seen === 'absent') return Promise.resolve(observationOf({ platform, cliPath, processes: seen, answer: NOT_ASKED }))
       return new Promise((resolve) => {
-        execFile(cliPath, ['version'], options, (error, stdout, stderr) => resolve(observationOf({ platform, cliPath, processes, answer: readVersionAnswer({ stdout, stderr, exited: !error }) })))
+        execFile(cliPath, ['version'], options, (error, stdout, stderr) => resolve(observationOf({ platform, cliPath, processes: seen, answer: readVersionAnswer({ stdout, stderr, exited: !error }) })))
       })
     },
-    // Whether the app answers for exactly this vault and has finished reading it.
-    vaultState({ vaultRoot }) {
-      const code = '(()=>JSON.stringify({basePath:app.vault.adapter.basePath,ready:app.metadataCache.initialized===true}))()'
+    // Whether the app answers for exactly this vault and has finished reading it. Asked where `route` (a
+    // `vaultRoute` of the app's list) says: from inside the vault's folder, or naming its id, so the app answers in
+    // that vault's window whichever window has focus, and opens it when it is known and closed. Without a route that
+    // reaches only this vault nothing is asked. Both sides are compared by real path, in the stored spelling.
+    vaultState({ vaultRoot, route }) {
+      let target
+      try { target = realPathAsStored(vaultRoot) } catch { return Promise.resolve({ answered: false, indexReady: false }) }
+      if (route?.how !== 'folder' && route?.how !== 'id') return Promise.resolve({ answered: false, indexReady: false })
+      const where = routedCall(route, workingDirectory)
       return new Promise((resolve) => {
-        execFile(cliPath, ['eval', `code=${code}`], options, (error, stdout) => {
-          if (error) return resolve({ answered: false, indexReady: false })
-          try {
-            const text = String(stdout)
-            const value = JSON.parse(JSON.parse(text.slice(text.indexOf('=> ') + 3)))
-            return resolve({ answered: value.basePath === vaultRoot, indexReady: value.basePath === vaultRoot && value.ready === true })
-          } catch { return resolve({ answered: false, indexReady: false }) }
+        execFile(cliPath, [...where.args, 'eval', `code=${VAULT_STATE_CODE}`], { ...options, cwd: where.cwd }, (error, stdout, stderr) => {
+          const answer = readEvalAnswer({ stdout, stderr, failed: Boolean(error) })
+          const value = answer.answered ? answer.value : null
+          const answered = value !== null && typeof value === 'object' && value.basePath === target
+          resolve({ answered, indexReady: answered && value.ready === true })
         })
       })
     },
   }
 }
 
-// Asks the operating system to open the vault in Obsidian. No shell.
-export function createProductionLauncher({ platform = process.platform, env = process.env } = {}) {
-  const command = platform === 'darwin' ? '/usr/bin/open' : platform === 'linux' ? 'xdg-open' : null
+// The fixed scripts the app runs for `open`. The only variable input is a JSON
+// payload that travels base64-encoded, so a path never becomes code. The app's
+// folder is taken as the file system stores it, as the target is and as the
+// bridge takes it, so a vault the app lists under another letter case answers.
+const VAULT_STATE_CODE = "(()=>{let p=app.vault.adapter.basePath;try{const f=require('fs');p=process.platform!=='win32'&&f.realpathSync.native?f.realpathSync.native(p):f.realpathSync(p)}catch(e){}return JSON.stringify({basePath:p,ready:app.metadataCache.initialized===true})})()"
+const VAULT_LIST_CODE = "(()=>JSON.stringify({vaults:require('electron').ipcRenderer.sendSync('vault-list')}))()"
+// `vault-open` with `false` adds an existing folder to the app's vault list (the app writes its own file) and opens
+// it in a window; it answers true, or a message. With `true` it would create a new folder, which is never wanted.
+const VAULT_REGISTER_SCRIPT = "return JSON.stringify({result:require('electron').ipcRenderer.sendSync('vault-open',P.path,false)})"
+function vaultRegisterCode(vaultRoot) {
+  if (typeof vaultRoot !== 'string' || !path.isAbsolute(vaultRoot) || vaultRoot.includes('\u0000')) throw new TypeError('vaultRoot must be an absolute path')
+  const data = Buffer.from(JSON.stringify({ path: vaultRoot }), 'utf8').toString('base64')
+  return `(()=>{const P=JSON.parse(new TextDecoder().decode(Uint8Array.from(atob('${data}'),c=>c.charCodeAt(0))));${VAULT_REGISTER_SCRIPT}})()`
+}
+
+// The vault list of the app, and adding this view's vault to it:
+//
+//   listThroughApp()                  -> { answered: true, vaults } | { answered: false, reason }
+//   registerThroughApp({ vaultRoot }) -> { answered: true, result } | { answered: false, reason }
+//   readSettings()                    -> readObsidianSettings answer (never writes)
+//   registerInSettings({ vaultRoot, keepBackups }) -> registerVaultInObsidianSettings answer
+//   backupSettings()                  -> backupObsidianSettings answer (a copy beside the file; the file is not written)
+//
+// Through the app only while it runs and answers; in its settings file only
+// while no Obsidian runs, which registerVaultInObsidianSettings checks itself.
+// A Flatpak or snap build found for this account (`sandbox`) never reads that
+// file: it is then neither read nor written (`obsidian-sandboxed`), and a vault
+// is added through the app only. Adding a vault opens a window, so a call may
+// take longer than a version answer.
+export function createProductionAppRegistry({
+  platform = process.platform, env = process.env, cliPath = defaultCliPath(platform), processProbe = () => defaultObsidianProcessProbe({ platform }), workingDirectory = NEUTRAL_DIRECTORY,
+  userDataDir = obsidianUserDataDir({ platform, env }), sandbox = obsidianSandboxedBuild({ platform, env }), timeoutMs = CLI_TIMEOUT_MS * 3,
+} = {}) {
+  const sandboxed = { ok: false, code: 'obsidian-sandboxed', message: `this Obsidian is a ${sandbox} build, which reads its vault list inside its sandbox, where Atelier does not write` }
+  const evaluate = (code) => new Promise((resolve) => {
+    execFile(cliPath, ['eval', `code=${code}`], { env, cwd: workingDirectory, timeout: timeoutMs, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => resolve(readEvalAnswer({ stdout, stderr, failed: Boolean(error) })))
+  })
   return {
-    open({ vaultRoot }) {
-      if (command === null) return Promise.resolve({ launched: false, reason: 'launcher-platform-unqualified' })
-      const uri = `obsidian://open?path=${encodeURIComponent(vaultRoot)}`
-      return new Promise((resolve) => {
-        execFile(command, [uri], { env, timeout: 15_000 }, (error) => resolve(error ? { launched: false, reason: 'os-open-failed' } : { launched: true, reason: 'os-open-accepted' }))
+    async listThroughApp() {
+      const answer = await evaluate(VAULT_LIST_CODE)
+      if (!answer.answered) return answer
+      const vaults = answer.value?.vaults
+      return vaults !== null && typeof vaults === 'object' && !Array.isArray(vaults) ? { answered: true, vaults } : { answered: false, reason: 'no-value' }
+    },
+    async registerThroughApp({ vaultRoot }) {
+      const answer = await evaluate(vaultRegisterCode(vaultRoot))
+      return answer.answered ? { answered: true, result: answer.value?.result ?? null } : answer
+    },
+    readSettings: () => (sandbox === null ? readObsidianSettings({ userDataDir }) : sandboxed),
+    // A copy of the settings file as it is, before a restart sends the app any signal (backupObsidianSettings).
+    backupSettings: () => (sandbox !== null ? sandboxed : userDataDir === null
+      ? { ok: false, code: 'obsidian-settings-location-unknown', message: 'where Obsidian keeps its settings on this system is not known' }
+      : backupObsidianSettings({ userDataDir })),
+    registerInSettings: ({ vaultRoot, keepBackups = [] }) => (sandbox !== null ? sandboxed : userDataDir === null
+      ? { ok: false, code: 'obsidian-settings-location-unknown', message: 'where Obsidian keeps its settings on this system is not known' }
+      : registerVaultInObsidianSettings({ userDataDir, vaultRoot, processProbe, keepBackups })),
+  }
+}
+
+// Shows the vault in Obsidian by the steps of launchPlan, carried out by
+// runLaunchPlan: a quit app is started plainly (so it reopens every vault its
+// list flags open) and handed the vault's URL through its command-line tool once
+// the app itself answers the tool; a running app is handed the URL through its
+// tool, which takes a URL even with its command line turned off, and through the
+// operating system when the tool did not take it. A URL is never handed to the
+// operating system for an app this launch started. No shell. `execFile` is
+// node's, and a stand-in in the test of these executors, which runs in a child
+// process (the default suite never imports this module in-process).
+export function createProductionLauncher({
+  platform = process.platform, env = process.env, cliPath = defaultCliPath(platform), workingDirectory = NEUTRAL_DIRECTORY, waitMs, pollMs, sleep, execFile: runFile = execFile,
+} = {}) {
+  const osCommand = platform === 'darwin' ? '/usr/bin/open' : platform === 'linux' ? 'xdg-open' : null
+  const run = (file, args, timeout = 15_000) => new Promise((resolve) => {
+    runFile(file, args, { env, cwd: workingDirectory, timeout, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => resolve({ failed: Boolean(error), stdout: String(stdout ?? ''), stderr: String(stderr ?? '') }))
+  })
+  return {
+    // Starts a quit app with no URL, so it reopens the vaults its list flags open: for giving back an app `open`
+    // quit to restart it, when the vault could not be added after all. macOS only, as the restart is.
+    startPlain: async () => platform === 'darwin' && !(await run(osCommand, ['-b', 'md.obsidian'])).failed,
+    // `startedByThisOpen`: this `open` started the app with an earlier launch; the link goes through its tool only.
+    open({ vaultId = null, vaultPath = null, appRunning, startedByThisOpen = false }) {
+      const plan = launchPlan({ platform, appRunning, vaultId, vaultPath })
+      return runLaunchPlan(plan, {
+        startedEarlier: startedByThisOpen === true,
+        start: async () => !(await run(osCommand, ['-b', 'md.obsidian'])).failed,
+        answered: async () => { const reply = await run(cliPath, ['version'], CLI_TIMEOUT_MS); return appAnswered({ stdout: reply.stdout, stderr: reply.stderr, exited: !reply.failed }) },
+        handLink: async (uri) => urlProcessed((await run(cliPath, [uri], CLI_TIMEOUT_MS)).stdout),
+        osOpen: async (uri) => !(await run(osCommand, [uri])).failed,
+        ...(waitMs === undefined ? {} : { waitMs }), ...(pollMs === undefined ? {} : { pollMs }), ...(sleep === undefined ? {} : { sleep }),
       })
     },
   }
 }
 
+// Quits the running app for a restart a person asked for (app-restart.mjs): SIGTERM to its main process only, proven
+// from this machine's process table (`ps`, never a pattern search) as this account's, then waits until the process
+// probe says no Obsidian runs. The table is `pid ppid uid executable`; one process is described again by its parent,
+// user, start time and executable immediately before the signal.
+export function createProductionAppQuitter({ platform = process.platform, processProbe = () => defaultObsidianProcessProbe({ platform }), waitMs } = {}) {
+  const ps = (args) => execFileSync('/bin/ps', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 16 * 1024 * 1024, timeout: 5000, killSignal: 'SIGKILL' })
+  return createAppQuitter({
+    platform, uid: typeof process.getuid === 'function' ? process.getuid() : null, processProbe,
+    readTable: () => ps(['-ww', '-A', '-o', 'pid=,ppid=,uid=,comm=']),
+    readProcess: (pid) => ps(['-ww', '-o', 'ppid=,uid=,lstart=,comm=', '-p', String(pid)]),
+    signal: (pid) => process.kill(pid, 'SIGTERM'),
+    // The wait and the linger are measured on a monotonic clock: a step of the wall clock changes neither.
+    now: () => performance.now(),
+    ...(waitMs === undefined ? {} : { waitMs }),
+  })
+}
+
 export function createProductionAppSeams(options = {}) {
-  return { appProbe: createProductionAppProbe(options), launcher: createProductionLauncher(options) }
+  return { appProbe: createProductionAppProbe(options), launcher: createProductionLauncher(options), registry: createProductionAppRegistry(options), quitter: createProductionAppQuitter(options) }
 }

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

@@ -0,0 +1,313 @@
+import { randomBytes as cryptoRandomBytes } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { MAX_OBSIDIAN_SETTINGS_BYTES, OBSIDIAN_SETTINGS_FILE, enclosingVaults, findVaultEntry, readObsidianSettings } from '../../projection/obsidian/publication/vault-list.mjs'
+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 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
+// (see vault-list.mjs). The app reads it when it starts and rewrites all of it
+// whenever its list changes, so while it runs the file is the app's: a vault
+// is then added through the app itself (`open` does that through its command
+// line), never here. Here, the file is written only while the injected process
+// probe says, positively, that no Obsidian runs, read immediately before and
+// again immediately before the rename, and:
+//
+//   - never for a Flatpak or snap build, which reads its list inside its
+//     sandbox and never this file (`sandbox`, see obsidianSandboxedBuild);
+//   - 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 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);
+//   - every other key and every other vault entry is kept as the app wrote
+//     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
+//     replaced; the replacement is a temporary file in the same directory,
+//     fsynced, renamed over it, and the directory is fsynced. Of these
+//     backups, the first (the list as it was before Atelier wrote it) and the
+//     latest are kept, and any between them removed;
+//   - a file that changed since it was read is not replaced.
+//
+// Every refusal writes nothing, leaves nothing behind and is typed: a file
+// created on the way is removed again whichever step after its creation fails.
+
+const refused = (code, message) => ({ ok: false, code, message })
+const currentUid = () => (typeof process.getuid === 'function' ? process.getuid() : null)
+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, `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 || keep.includes(name)) continue
+    const file = path.join(directory, name)
+    try { if (fs.lstatSync(file).isFile()) fs.unlinkSync(file) } catch { /* it stays */ }
+  }
+}
+
+// Creates `file`, which must not exist (an exclusive create fails on anything
+// there, a link included), with these bytes, fsynced. The file exists exactly
+// when the create returned; any failure after it removes the file again.
+function writeNewFile(file, bytes, mode) {
+  const descriptor = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), mode)
+  try {
+    try {
+      fs.writeFileSync(descriptor, bytes)
+      fs.fchmodSync(descriptor, mode)
+      fs.fsyncSync(descriptor)
+    } finally {
+      fs.closeSync(descriptor)
+    }
+  } catch (error) {
+    try { fs.unlinkSync(file) } catch { /* already gone */ }
+    throw error
+  }
+}
+
+function readBytesNoFollow(file) {
+  const descriptor = openRegularFileNoFollow(file)
+  try { return fs.readFileSync(descriptor) } finally { try { fs.closeSync(descriptor) } catch { /* read already, or failed */ } }
+}
+
+// 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`).
+// `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)
+  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 (!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 = 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()
+  // 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)
+  const backupPath = path.join(directory, `${OBSIDIAN_SETTINGS_FILE}.atelier-backup-${compactUtc(at)}`)
+  const temporary = path.join(directory, `.${OBSIDIAN_SETTINGS_FILE}.atelier-${randomBytes(6).toString('hex')}.tmp`)
+  const created = []
+  const removeCreated = () => { for (const file of created.splice(0)) try { fs.unlinkSync(file) } catch { /* already gone */ } }
+  try {
+    writeNewFile(temporary, bytes, settings.mode)
+    created.push(temporary)
+    writeNewFile(backupPath, settings.bytes, settings.mode)
+    created.push(backupPath)
+  } catch (error) {
+    removeCreated()
+    return refused(error.code === 'EEXIST' ? 'obsidian-settings-changed' : 'obsidian-settings-unwritable', 'the Obsidian settings directory cannot be written')
+  }
+  // Immediately before the rename: still no app, and still the bytes that were read.
+  if (!absent()) { removeCreated(); return refused('app-may-be-running', 'an Obsidian process appeared, and its vault list belongs to it') }
+  let current
+  try { current = readBytesNoFollow(settings.file) } catch { current = null }
+  if (current === null || !current.equals(settings.bytes)) { removeCreated(); return refused('obsidian-settings-changed', 'the Obsidian settings file changed while the vault was being added') }
+  try {
+    fs.renameSync(temporary, settings.file)
+  } catch {
+    removeCreated()
+    return refused('obsidian-settings-unwritable', 'the Obsidian settings file cannot be replaced')
+  }
+  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), (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: 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
+// without asking it anything: whether an Obsidian process runs (`processes`, a
+// process probe's 'running', 'absent' or 'unknown'), and which vaults its list
+// shows open (`settings`, a `readObsidianSettings` answer or null). The app
+// writes that list whenever a vault window opens or closes. The engine tries a
+// view that did not settle again as soon as this changes; the app itself is
+// asked only when a view is published.
+export function appStateSignature({ processes = null, settings = null } = {}) {
+  const open = settings?.ok === true
+    ? Object.values(settings.vaults).filter((entry) => entry !== null && typeof entry === 'object' && entry.open === true && typeof entry.path === 'string').map((entry) => entry.path).sort()
+    : null
+  return JSON.stringify([typeof processes === 'string' ? processes : null, open])
+}