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

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

@@ -13,6 +13,17 @@ import { refuse } from './errors.mjs'
 // is true when the command-line tool answered that no vault is open. The
 // production probe is a separate module that only the real command-line
 // entries load; every test passes its own.
+//
+// A version can also come from Atelier's plugin: a plugin that holds a live
+// lease runs inside the app and reports `apiVersion`, the version of exactly
+// that app. It stands in only where the command-line tool gives no version:
+// the tool reaches the app a publication coordinates with, which may be
+// another app holding the same vault, so its own answer decides wherever it
+// gives one. Such an observation carries `versionSource: 'plugin'` and
+// qualifies with reason `plugin-reported`; whether the app is installed where
+// Atelier looks, with its command-line tool, is still the probe's answer, and
+// so is whether it runs: a lease outlives a crashed app by up to its lease
+// time, so while the process table shows no app, a report stands for none.
 
 // The publication protocol sets the view's undocumented `lastSavedData` field.
 // 1.13.7 is the only app version that protocol was proven on, so it is the
@@ -64,6 +75,13 @@ export function meetsMinimumAppVersion(version, floor = MINIMUM_APP_VERSION) {
 // command, `version` too, with this line (observed on 1.13.7, on either output
 // stream and with either exit status). It is not a version.
 const NO_VAULT_OPEN = /^vault not found\.?$/i
+// While a vault window is still loading, right after the app started or opened
+// a vault, the tool answers a command with this line instead (observed on
+// 1.13.7). The app is not up yet: this is not a version either.
+const COMMAND_NOT_READY = /^error: command "[^"]*" not found\b/i
+// With its command line turned off (the default of a new installation: Settings > General > Advanced), the app
+// answers every command but a URL with this line (1.13.7). It runs and is reachable only by URL: not a version.
+const CLI_TURNED_OFF = /^command line interface is not enabled\b/i
 
 // Pure. What one `version` call of the command-line tool answered:
 // { version, noVaultOpen }. `exited` is false for a call that failed or exited
@@ -71,10 +89,47 @@ const NO_VAULT_OPEN = /^vault not found\.?$/i
 export function readVersionAnswer({ stdout = '', stderr = '', exited = true } = {}) {
   const lines = [stdout, stderr].flatMap((text) => (typeof text === 'string' ? text.split('\n') : [])).map((line) => line.trim())
   if (lines.some((line) => NO_VAULT_OPEN.test(line))) return { version: null, noVaultOpen: true }
+  if (lines.some((line) => CLI_TURNED_OFF.test(line))) return { version: null, noVaultOpen: false, cliOff: true }
+  if (lines.some((line) => COMMAND_NOT_READY.test(line))) return { version: null, noVaultOpen: false }
   const text = typeof stdout === 'string' ? stdout.trim() : ''
   return { version: exited && text !== '' ? text : null, noVaultOpen: false }
 }
 
+// Pure. Whether a reply of the command-line tool came from the app itself: a
+// version, or one of the lines the app answers with (no vault open, a command
+// not ready yet, the command line turned off). The tool's own message while it
+// cannot reach the app ("The CLI is unable to find Obsidian …") is not one, and
+// nor is silence: the app is not up.
+export function appAnswered({ stdout = '', stderr = '', exited = true } = {}) {
+  const lines = [stdout, stderr].flatMap((text) => (typeof text === 'string' ? text.split('\n') : [])).map((line) => line.trim())
+  if (lines.some((line) => NO_VAULT_OPEN.test(line) || CLI_TURNED_OFF.test(line) || COMMAND_NOT_READY.test(line))) return true
+  const text = typeof stdout === 'string' ? stdout.trim() : ''
+  return exited && parseAppVersion(text) !== null
+}
+
+// Pure. What one `eval` call of the command-line tool answered:
+// { answered: true, value } with the value the script returned, parsed as
+// JSON, or { answered: false, reason }. The tool prints a returned string as
+// it is after `=> `; a string that is itself JSON text is parsed once more.
+// `reason` is `no-vault-open` for the answer the app gives with no vault open,
+// `cli-failed` for a call that failed, and `no-value` otherwise.
+export function readEvalAnswer({ stdout = '', stderr = '', failed = false } = {}) {
+  const lines = [stdout, stderr].flatMap((text) => (typeof text === 'string' ? text.split('\n') : [])).map((line) => line.trim())
+  if (lines.some((line) => NO_VAULT_OPEN.test(line))) return { answered: false, reason: 'no-vault-open' }
+  if (lines.some((line) => CLI_TURNED_OFF.test(line))) return { answered: false, reason: 'cli-turned-off' }
+  if (failed) return { answered: false, reason: 'cli-failed' }
+  const text = typeof stdout === 'string' ? stdout : ''
+  const start = text.indexOf('=> ')
+  if (start < 0) return { answered: false, reason: 'no-value' }
+  try {
+    let value = JSON.parse(text.slice(start + 3))
+    if (typeof value === 'string') { try { value = JSON.parse(value) } catch { /* a plain string */ } }
+    return { answered: true, value }
+  } catch {
+    return { answered: false, reason: 'no-value' }
+  }
+}
+
 // Pure. `requireVersion: false` lets an installed app that is positively not
 // running pass without a version: nothing is published through an app that
 // does not run, and the version is asked for again once it does. An app whose
@@ -83,7 +138,18 @@ export function readVersionAnswer({ stdout = '', stderr = '', exited = true } =
 export function qualifyApp(observation, { requireVersion = true, floor = MINIMUM_APP_VERSION } = {}) {
   const seen = observation !== null && typeof observation === 'object' ? observation : {}
   const base = { floor, version: typeof seen.version === 'string' ? seen.version.slice(0, 80) : null, running: seen.running === true ? true : seen.running === false ? false : null }
+  if (seen.versionSource === 'plugin') {
+    // The plugin runs inside the app it reports: that app runs and has a vault open.
+    const reported = { ...base, running: true, versionSource: 'plugin' }
+    if (seen.installed !== true) return { ...reported, outcome: 'app-missing', reason: 'no-app-found' }
+    if (seen.cli !== true) return { ...reported, outcome: 'app-cli-unavailable', reason: 'cli-capability-absent' }
+    if (reported.version === null) return { ...reported, outcome: 'app-version-unsupported', reason: 'version-unknown' }
+    if (parseAppVersion(reported.version) === null) return { ...reported, outcome: 'app-version-unsupported', reason: 'version-unreadable' }
+    if (!meetsMinimumAppVersion(reported.version, floor)) return { ...reported, outcome: 'app-version-unsupported', reason: 'below-minimum-version' }
+    return { ...reported, outcome: 'qualified', reason: 'plugin-reported', versionChecked: true }
+  }
   if (seen.installed !== true) return { ...base, outcome: 'app-missing', reason: 'no-app-found' }
+  if (seen.cliOff === true) return { ...base, running: true, outcome: 'app-cli-unavailable', reason: 'cli-turned-off' }
   if (seen.cli !== true) return { ...base, outcome: 'app-cli-unavailable', reason: 'cli-capability-absent' }
   if (seen.noVaultOpen === true) return { ...base, outcome: 'app-version-unsupported', reason: 'no-vault-open' }
   if (base.version === null) {
@@ -103,27 +169,62 @@ export async function inspectApp(appProbe) {
 // The adapter factory of a service that reaches a real app. The editor adapter
 // is constructed only after the app qualified; otherwise the factory refuses,
 // typed, and the engine records that reason and publishes nothing. The answer
-// is remembered briefly so a tick over many views asks once.
+// is remembered briefly so a tick over many views asks once, unless it let an
+// adapter through without a checked version. `createAdapter` receives the
+// qualification with its input: an app that was not running qualified without
+// a version, and an adapter built on that answer must not coordinate with an
+// app started since (see createEditorAdapter).
+//
+// The app is asked only when an adapter is wanted, that is when a view is
+// about to be published. An appProbe with `inspect()` is asked without
+// blocking, and the factory and `qualification()` then answer promises; one
+// with only `inspectSync()` is asked synchronously.
+//
+// When the service passes `pluginReport` (one launch of the plugin holds a
+// live lease on the view), the probe is asked as without one, through the same
+// remembered answer, and that answer decides wherever the tool gave a version,
+// found no app or no tool, or the process table showed no app running. Only
+// where the tool gave no version while an app may run does the plugin's
+// version stand in; such an answer is never reused for another view or a later
+// call. The adapter still coordinates through its own channel, which must
+// answer for the vault before anything is published.
 export function createQualifiedAdapterFactory({ appProbe, createAdapter, floor = MINIMUM_APP_VERSION, maxAgeMs = 10_000, now = () => Date.now() } = {}) {
-  if (typeof appProbe?.inspectSync !== 'function') throw new TypeError('the qualified adapter factory needs an appProbe with inspectSync()')
+  const waits = typeof appProbe?.inspect === 'function'
+  if (!waits && typeof appProbe?.inspectSync !== 'function') throw new TypeError('the qualified adapter factory needs an appProbe with inspect() or inspectSync()')
   if (typeof createAdapter !== 'function') throw new TypeError('the qualified adapter factory needs createAdapter')
   let last = null
-  const qualification = () => {
-    if (last === null || now() - last.at > maxAgeMs) {
-      let observation
-      try { observation = appProbe.inspectSync() } catch { observation = null }
-      last = { at: now(), result: qualifyApp(observation, { requireVersion: false, floor }) }
-    }
-    return last.result
+  // An answer that lets an adapter through without a checked version (no app
+  // was running, or none was found) is never reused: an app started since is
+  // asked for its version by the next call, not refused on the old answer. An
+  // answer that checked a version, or that refuses, is reused for `maxAgeMs`.
+  const reusable = (result) => result.versionChecked === true || (result.outcome !== 'qualified' && result.outcome !== 'app-missing')
+  const current = () => last !== null && reusable(last.result) && now() - last.at <= maxAgeMs
+  const learn = (observation) => { last = { at: now(), result: qualifyApp(observation, { requireVersion: false, floor }) }; return last.result }
+  const qualification = waits
+    ? async () => { if (current()) return last.result; let observation; try { observation = await appProbe.inspect() } catch { observation = null } return learn(observation) }
+    : () => { if (current()) return last.result; let observation; try { observation = appProbe.inspectSync() } catch { observation = null } return learn(observation) }
+  const withPlugin = (probed, report) => {
+    if (report === null) return probed
+    // No app in the process table: a live lease is the echo of an app that is gone (it lapses within the lease time) or
+    // of a process holding the key, and vouches for no version. The probe's own answer stands, so an adapter built on it
+    // never coordinates with an app started since, whose version nobody checked.
+    if (probed.version !== null || probed.running === false || probed.outcome === 'app-missing' || probed.outcome === 'app-cli-unavailable') return probed
+    return qualifyApp({ installed: true, cli: true, version: typeof report?.appVersion === 'string' ? report.appVersion : null, versionSource: 'plugin' }, { requireVersion: true, floor })
   }
-  const factory = (input) => {
-    const result = qualification()
+  let shown = null
+  const build = (input, probed) => {
+    const result = withPlugin(probed, input?.pluginReport ?? null)
+    shown = result
     // No app at all is not an unqualified app: the publisher's own path needs none, and its adapter finds no process.
     if (result.outcome !== 'qualified' && result.outcome !== 'app-missing') refuse(result.outcome, 'the installed Obsidian does not qualify; nothing is published through it', { reason: result.reason, floor: result.floor, version: result.version })
-    return createAdapter(input)
+    return createAdapter({ ...input, qualification: result })
   }
+  const factory = waits ? async (input) => build(input, await qualification()) : (input) => build(input, qualification())
   factory.qualification = qualification
-  // What was last learned, without asking again: for a status answer.
-  factory.lastQualification = () => last?.result ?? null
+  // What was last learned, from the probe or from a plugin, without asking again: for a status answer.
+  factory.lastQualification = () => shown ?? last?.result ?? null
+  // Drops what was learned, so the next adapter asks the app again: a tick somebody asked for does not reuse an
+  // answer from before the app changed.
+  factory.forget = () => { last = null; shown = null }
   return factory
 }

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

@@ -1,8 +1,12 @@
 import { execFile, spawnSync } from 'node:child_process'
 import fs from 'node:fs'
 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 { registerVaultInObsidianSettings } from './app-registration.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
@@ -11,13 +15,22 @@ import { readVersionAnswer } from './app-capability.mjs'
 // 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, and importing it leaves a trace
-// below that the test suite asserts is absent.
+// `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. One
+// test imports it in a child process, with a stand-in for the command-line
+// tool, to read the version answers it parses; 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
@@ -32,74 +45,150 @@ 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 }) -> registerVaultInObsidianSettings answer
+//
+// 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),
+    registerInSettings: ({ vaultRoot }) => (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 })),
+  }
+}
+
+// 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.
+export function createProductionLauncher({
+  platform = process.platform, env = process.env, cliPath = defaultCliPath(platform), workingDirectory = NEUTRAL_DIRECTORY, waitMs, pollMs, sleep,
+} = {}) {
+  const osCommand = platform === 'darwin' ? '/usr/bin/open' : platform === 'linux' ? 'xdg-open' : null
+  const run = (file, args, timeout = 15_000) => new Promise((resolve) => {
+    execFile(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 {
+    open({ vaultId = null, vaultPath = null, appRunning }) {
+      const plan = launchPlan({ platform, appRunning, vaultId, vaultPath })
+      return runLaunchPlan(plan, {
+        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 }),
       })
     },
   }
 }
 
 export function createProductionAppSeams(options = {}) {
-  return { appProbe: createProductionAppProbe(options), launcher: createProductionLauncher(options) }
+  return { appProbe: createProductionAppProbe(options), launcher: createProductionLauncher(options), registry: createProductionAppRegistry(options) }
 }

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

@@ -0,0 +1,166 @@
+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 `obsidian://open?path=` finds it when the app 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);
+//   - only an existing file, 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;
+//   - 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 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, and `latest`; removes the ones between.
+// Their names sort as their times. A backup that cannot be removed stays.
+function pruneBackups(directory, latest) {
+  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
+    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 */ } }
+}
+
+// { 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
+// this account, which refuses (`obsidian-sandboxed`).
+export function registerVaultInObsidianSettings({ userDataDir, vaultRoot, processProbe, sandbox = null, now = () => Date.now(), randomBytes = cryptoRandomBytes, uid = currentUid() } = {}) {
+  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 })
+  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 }
+  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')
+
+  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))
+  const at = now()
+  const document = { ...settings.document, vaults: { ...settings.vaults, [id]: { path: folder, ts: at, open: 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))
+  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 }),
+  }
+}
+
+// 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])
+}