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

package/src/runtime/obsidian/plugin-drift.mjs

@@ -0,0 +1,124 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { readRegularTextNoFollow } from '../../project/private-state.mjs'
+import { OBSIDIAN_EXT_KEY } from '../../projection/obsidian/contracts.mjs'
+import { sha256Digest } from '../../projection/obsidian/materialize/byte-lens.mjs'
+import { readFileBytes, readFileDigest } from '../../projection/obsidian/recovery/store.mjs'
+import { viewVaultRoot } from './plugin-choice.mjs'
+
+// Whether the plugin files a view's committed generation pins are on disk as
+// pinned. A person may remove one, change one, or repair a path Atelier had to
+// leave (a folder where a file goes, say). The publisher then publishes the
+// same generation again (publisher.mjs), but only when the view is prepared
+// again, which nothing else asks for while its sources are unchanged.
+//
+// `observe(scopeIds)` looks at each view once per tick and returns the views
+// to prepare again: those whose files differ from their pins and look
+// different from the last look. A drift Atelier leaves for the person (a link
+// where a file goes) is asked about once, not at every tick; a change to it is
+// asked about again. Where the plugin is turned off in the vault, a pinned
+// file that is gone is no drift: the publisher never makes one again.
+// `settle(scopeIds)` looks again after each tick, and takes as seen what a
+// publication of that tick could not change, so a drift publishing cannot
+// repair is not published a second time at the next look (at a service's
+// start, say).
+
+const segment = (identifier) => identifier.replaceAll(':', '_')
+const TURNED_OFF = 'turned-off-in-this-vault'
+
+// The plugin record of the view's committed manifest, read as the store reads
+// it: the pointer names the manifest and its digest. Null when there is none.
+function pinnedPlugin(workspaceRoot, workspaceId, scopeId) {
+  const manifests = path.join(workspaceRoot, 'state', 'manifests', segment(scopeId))
+  try {
+    const pointer = JSON.parse(readRegularTextNoFollow(path.join(manifests, 'current.json')))
+    if (pointer?.workspaceId !== workspaceId || pointer?.scopeId !== scopeId || typeof pointer.manifestFile !== 'string' || pointer.manifestFile.includes('/')) return null
+    const bytes = readFileBytes(path.join(manifests, pointer.manifestFile))
+    if (sha256Digest(bytes) !== pointer.manifestDigest) return null
+    const owned = JSON.parse(bytes.toString('utf8'))?.ext?.[OBSIDIAN_EXT_KEY]?.settings?.pluginOwned
+    if (!Array.isArray(owned?.files)) return null
+    return { manifest: pointer.manifestDigest, files: owned.files.filter((file) => typeof file?.path === 'string' && typeof file?.digest === 'string'), off: owned.withheldBecause === TURNED_OFF }
+  } catch {
+    return null
+  }
+}
+
+// What one pinned path holds: its digest, 'absent', or 'unreadable' (a link, a
+// folder where a file goes, a path nobody may read).
+function onDisk(vaultRoot, relativePath) {
+  let current = vaultRoot
+  for (const part of relativePath.split('/').slice(0, -1)) {
+    current = path.join(current, part)
+    let stat
+    try { stat = fs.lstatSync(current, { throwIfNoEntry: false }) } catch { return 'unreadable' }
+    if (!stat) return 'absent'
+    if (stat.isSymbolicLink() || !stat.isDirectory()) return 'unreadable'
+  }
+  try { return readFileDigest(path.join(vaultRoot, relativePath)) ?? 'absent' } catch { return 'unreadable' }
+}
+
+// A look, as it is compared: the vault root, and each pinned file with its pin and what the disk holds.
+const signatureOf = (record) => JSON.stringify([record.root, record.files.map((file) => file.digest), record.files.map((file) => file.state)])
+// Never what a look finds on disk: a path recorded so is asked about at the next look whatever it holds then.
+const NOT_SEEN = 'not-seen'
+
+export function createPluginDriftObserver({ workspaceRoot, workspaceId }) {
+  // Per view: the last look ({ root, files: [{ path, digest, state }], manifest }).
+  const looked = new Map()
+  // The views the last observe asked to be prepared again: the tick that follows publishes them.
+  let asked = new Set()
+  // What the pinned plugin files of a view look like on disk now; null when its committed generation pins none.
+  const look = (scopeId) => {
+    const pinned = pinnedPlugin(workspaceRoot, workspaceId, scopeId)
+    if (pinned === null || pinned.files.length === 0) return null
+    // The view's vault wherever it is; one that cannot be found is refused by the engine, not observed here.
+    let vaultRoot
+    try { vaultRoot = viewVaultRoot(workspaceRoot, scopeId, workspaceId) } catch (error) { if (typeof error?.code !== 'string') throw error; return null }
+    let root = 'absent'
+    try { const stat = fs.lstatSync(vaultRoot); root = stat.isSymbolicLink() ? 'link' : (stat.mode & 0o777).toString(8) } catch { root = 'absent' }
+    const files = pinned.files.map((file) => ({ path: file.path, digest: file.digest, state: onDisk(vaultRoot, file.path) }))
+    const drifted = (file) => file.state !== file.digest && !(pinned.off && file.state === 'absent')
+    return { root, files, manifest: pinned.manifest, drifted, differs: files.some(drifted) }
+  }
+  return {
+    observe(scopeIds) {
+      const drifted = []
+      for (const scopeId of scopeIds) {
+        const seen = look(scopeId)
+        if (seen === null) { looked.delete(scopeId); continue }
+        const last = looked.get(scopeId)
+        if (seen.differs && (last === undefined || signatureOf(last) !== signatureOf(seen))) drifted.push(scopeId)
+        looked.set(scopeId, { root: seen.root, files: seen.files, manifest: seen.manifest })
+      }
+      asked = new Set(drifted)
+      return drifted
+    },
+    // After a tick. A view this tick published (one the last observe asked for, one whose committed generation
+    // changed since the last look, or one never looked at before) had its plugin files written or left for the person
+    // by its publisher. Of what the disk shows now, only what that publication could not change is taken as seen,
+    // without asking: a file as it pins it, or one that holds what it held before the tick under the same pin and the
+    // same vault root. So a drift publishing cannot repair (the data file of a vault root that is a link, say) is not
+    // asked about again once it was asked about under its pin. Anything else is not taken as seen, and the next look
+    // asks about it: a file another writer removed or changed after the publication, while the tick went on, or
+    // brought back to what it held under a pin the tick replaced; a file the publication left for the person, which
+    // the person may have repaired before the tick ended; and any file, when the vault root changed during the tick.
+    // Asking about a file that is still left writes no vault file: the publisher does not publish a committed
+    // generation again for it (pluginFilesDrifted). Any other view keeps its last look.
+    settle(scopeIds) {
+      for (const scopeId of scopeIds) {
+        const seen = look(scopeId)
+        if (seen === null) { looked.delete(scopeId); continue }
+        const last = looked.get(scopeId)
+        if (!asked.has(scopeId) && last !== undefined && last.manifest === seen.manifest) continue
+        // Keyed by path and pin: what a file held under a pin this tick replaced says nothing about the new one.
+        const key = (file) => `${file.path}\u0000${file.digest}`
+        const before = new Map((last?.files ?? []).map((file) => [key(file), file.state]))
+        // And only under the same vault root: a root made private during the tick changes what the publisher leaves.
+        const sameRoot = last !== undefined && last.root === seen.root
+        const files = seen.files.map((file) => (!seen.drifted(file) || (sameRoot && before.get(key(file)) === file.state) ? file : { ...file, state: NOT_SEEN }))
+        looked.set(scopeId, { root: seen.root, files, manifest: seen.manifest })
+      }
+      asked = new Set()
+    },
+  }
+}

package/src/runtime/obsidian/plugin-presence.mjs

@@ -0,0 +1,61 @@
+import { isPlainObject } from './documents.mjs'
+
+// What `status` and `open` say about Atelier's plugin, read from the status
+// document of the running service (`plugins`, see plugin-channel.mjs). The
+// plugin is present for a view while it holds a live lease on it.
+
+export const PLUGIN_PRESENCE_REASONS = Object.freeze(['live-lease', 'no-live-lease', 'turned-off-in-this-vault', 'service-not-running', 'service-reports-no-plugin-channel'])
+
+// The two ways back, for a view whose vault turned the plugin off.
+export const turnPluginOnNext = (scopeId) => `turn Atelier on in Obsidian (Settings, Community plugins), or run \`atelier obsidian plugin on --scope ${scopeId}\`, which restores it at the view's next publication`
+
+// A view kept `current` while a plugin file its committed generation pins waits for an app that qualifies: the notes
+// are verified, the plugin file (often `data.json`) is not written yet (engine.mjs). Its freshness reason says so.
+export const PLUGIN_FILES_WAIT_FOR_APP = 'verified-by-read-back-plugin-waits-for-app'
+export const PLUGIN_FILES_WAIT_NEXT = 'the view\'s notes are current, but a file of Atelier\'s plugin in this vault is not written yet, since Obsidian could not be coordinated with (it runs without its command line answering, say): it is written once Obsidian answers its command line or is quit, and it is retried automatically'
+
+// The presence, with the plugin files that wait for the app when the view's freshness says so (`files`, and the next
+// step unless the presence has its own).
+export function withPluginFilesPending(presence, freshness) {
+  if (freshness?.state !== 'current' || freshness.reason !== PLUGIN_FILES_WAIT_FOR_APP) return presence
+  return { ...presence, files: 'waits-for-app', next: presence.next ?? PLUGIN_FILES_WAIT_NEXT }
+}
+
+export function pluginPresenceOf(statusDocument, scopeId) {
+  if (!isPlainObject(statusDocument)) return { present: false, reason: 'service-not-running' }
+  const scopes = isPlainObject(statusDocument.plugins) && Array.isArray(statusDocument.plugins.scopes) ? statusDocument.plugins.scopes : null
+  if (scopes === null) return { present: false, reason: 'service-reports-no-plugin-channel' }
+  const entry = scopes.find((item) => isPlainObject(item) && item.scopeId === scopeId)
+  if (entry?.present === true && typeof entry.appVersion === 'string') {
+    return { present: true, reason: 'live-lease', appVersion: entry.appVersion, pluginVersion: typeof entry.pluginVersion === 'string' ? entry.pluginVersion : null, sessions: Number.isInteger(entry.sessions) ? entry.sessions : 1 }
+  }
+  if (entry?.entry === 'off') return { present: false, reason: 'turned-off-in-this-vault', next: turnPluginOnNext(scopeId) }
+  return { present: false, reason: 'no-live-lease' }
+}
+
+// An app probe that takes the version from the plugin when one holds the view
+// and the command-line tool gives none: that plugin runs inside the app, so its
+// version is the app's. A version the tool did give decides, since the tool may
+// reach another app that holds the same vault. Whether the app is installed and
+// has its command-line capability is still the probe's answer; that capability
+// opens and coordinates the vault in this phase. So is whether the app runs: a
+// lease outlives a crashed app by up to its lease time.
+// The presence is asked at most once per `maxAgeMs`: open's wait loop asks the
+// app far more often, and each answer about the plugin costs a round trip to
+// the service.
+export function withPluginReportedVersion(appProbe, readPresence, { maxAgeMs = 1000, now = () => Date.now() } = {}) {
+  let last = null
+  const presenceNow = () => {
+    if (last === null || now() - last.at >= maxAgeMs) last = { at: now(), presence: Promise.resolve().then(readPresence).catch(() => null) }
+    return last.presence
+  }
+  return {
+    async inspect() {
+      const [observation, presence] = await Promise.all([appProbe.inspect(), presenceNow()])
+      // A command line that answered it is turned off stays that answer: a plugin's version never hides it.
+      if (presence?.present !== true || observation?.installed !== true || observation?.cli !== true || observation.running === false || typeof observation.version === 'string' || observation.cliOff === true) return observation
+      return { ...observation, running: true, version: presence.appVersion, noVaultOpen: false, versionSource: 'plugin' }
+    },
+    vaultState: (input) => appProbe.vaultState(input),
+  }
+}

package/src/runtime/obsidian/process-identity.mjs

@@ -1,5 +1,6 @@
 import { execFileSync } from 'node:child_process'
 import fs from 'node:fs'
+import path from 'node:path'
 import { executableIdentity } from './service-record.mjs'
 
 // Whether a live PID provably runs the executable a service record names,
@@ -32,27 +33,36 @@ export function readProcessCommandLine(pid, { platform = process.platform, readF
   return null
 }
 
-// Pure. The command line must name the recorded entry module, and a runtime
-// identifier it carries must be the recorded one.
-export function commandLineNamesRecord(commandLine, record) {
-  const entry = record?.executable?.path
-  if (typeof entry !== 'string' || entry === '' || typeof record.runtimeId !== 'string') return false
+// Pure. The command line must name the recorded entry module, by one of
+// `entries` (its recorded path, and the path it was started by when that is
+// another name for it), and a runtime identifier it carries must be the
+// recorded one.
+export function commandLineNamesRecord(commandLine, record, entries = [record?.executable?.path]) {
+  const names = entries.filter((entry) => typeof entry === 'string' && entry !== '')
+  if (names.length === 0 || typeof record?.runtimeId !== 'string') return false
   if (Array.isArray(commandLine)) {
-    if (!commandLine.slice(1).includes(entry)) return false
+    if (!commandLine.slice(1).some((word) => names.includes(word))) return false
     const named = commandLine.filter((word) => word.startsWith(RUNTIME_ARGUMENT)).map((word) => word.slice(RUNTIME_ARGUMENT.length))
     return named.every((runtimeId) => runtimeId === record.runtimeId)
   }
   if (typeof commandLine !== 'string') return false
-  if (!` ${commandLine} `.includes(` ${entry} `)) return false
+  if (!names.some((entry) => ` ${commandLine} `.includes(` ${entry} `))) return false
   const named = [...commandLine.matchAll(/(?:^|\s)--runtime-id=(\S+)/g)].map((match) => match[1])
   return named.every((runtimeId) => runtimeId === record.runtimeId)
 }
 
 // The recorded executable is still the bytes that were recorded, and the live
-// process was started on it.
-export function processRunsRecordedExecutable(record, { commandLineOf = readProcessCommandLine, identityOf = executableIdentity } = {}) {
+// process was started on it: by its recorded path, or by the path the record
+// says it was started by (a login item names the installed entry by its path),
+// when that still leads to the recorded one.
+export function processRunsRecordedExecutable(record, { commandLineOf = readProcessCommandLine, identityOf = executableIdentity, realpathOf = fs.realpathSync } = {}) {
   try {
     if (identityOf(record.executable.path).digest !== record.executable.digest) return false
   } catch { return false }
-  return commandLineNamesRecord(commandLineOf(record.pid), record)
+  const entries = [record.executable.path]
+  const invokedAs = record.executable.ext?.invokedAs
+  if (typeof invokedAs === 'string' && path.isAbsolute(invokedAs)) {
+    try { if (realpathOf(invokedAs) === record.executable.path) entries.push(invokedAs) } catch { /* not another name for it */ }
+  }
+  return commandLineNamesRecord(commandLineOf(record.pid), record, entries)
 }

package/src/runtime/obsidian/project-views.mjs

@@ -0,0 +1,282 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { validateProjectConfigDoc } from '../../project/config.mjs'
+import { MAX_EXPANSION_DEPTH, OBSIDIAN_EXT_KEY, ObsidianContractRefusal } from '../../projection/obsidian/contracts.mjs'
+import { readObsidianEnablement } from './enablement.mjs'
+import { ObsidianMaintenanceRefusal, refuse } from './errors.mjs'
+
+// The views a project declares, written into its `atelier.project.json` for a
+// person, so nobody edits JSON by hand: `view add`, and the view a project
+// that never used Obsidian gets on its first open.
+//
+// The project file is committed source. Atelier changes it only when asked,
+// shows the exact change as a diff, and never commits. It rewrites a file only
+// when the file is in the form Atelier writes JSON in (two-space indentation,
+// with LF or CRLF line ends, with or without a final one), so the change is
+// the Obsidian member and nothing else; and only over the bytes it read. The
+// workspace pointer is only ever written into an ignored `.atelier-local/`, so
+// a project where that folder is not ignored gets the ignore line in the same
+// change.
+
+export const EXT_SETTINGS_SCHEMA = 'atelier-obsidian-ext-settings/v1'
+// Every note this machine may show, in one view that is the default. Its name reads well in a command
+// (`--scope everything`) and in a vault's name (`harbor-notes (everything)`).
+export const DEFAULT_VIEW = Object.freeze({ scopeId: 'everything', mode: 'full', selector: Object.freeze({ all: true }) })
+const LOCAL_STATE_LINE = '.atelier-local/'
+const SCOPE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const MAX_EXPANSION_NODES = 100000
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+const linesOf = (text) => { const lines = text.split(/\r?\n/); if (lines.at(-1) === '') lines.pop(); return lines }
+// A hunk's range: the first line and the count, or the line before an empty range.
+const range = (start, count) => (count === 0 ? `${start},0` : `${start + 1},${count}`)
+
+// The lines that differ between two texts, as one unified hunk with up to three lines of context on each side. Enough
+// for a change that inserts or replaces one run of lines, which is every change made here.
+export function unifiedDiff(before, after, { label }) {
+  if (before === after) return ''
+  const [left, right] = [linesOf(before), linesOf(after)]
+  let prefix = 0
+  while (prefix < left.length && prefix < right.length && left[prefix] === right[prefix]) prefix += 1
+  let suffix = 0
+  while (suffix < left.length - prefix && suffix < right.length - prefix && left[left.length - 1 - suffix] === right[right.length - 1 - suffix]) suffix += 1
+  const context = 3
+  const start = Math.max(0, prefix - context)
+  const leftEnd = Math.min(left.length, left.length - suffix + context)
+  const rightEnd = Math.min(right.length, right.length - suffix + context)
+  const lines = [
+    `--- ${label}`, `+++ ${label}`, `@@ -${range(start, leftEnd - start)} +${range(start, rightEnd - start)} @@`,
+    ...left.slice(start, prefix).map((line) => ` ${line}`),
+    ...left.slice(prefix, left.length - suffix).map((line) => `-${line}`),
+    ...right.slice(prefix, right.length - suffix).map((line) => `+${line}`),
+    ...right.slice(right.length - suffix, rightEnd).map((line) => ` ${line}`),
+  ]
+  return `${lines.join('\n')}\n`
+}
+
+const jsonText = (document, { eol, final }) => {
+  const text = JSON.stringify(document, null, 2)
+  return `${eol === '\n' ? text : text.replaceAll('\n', '\r\n')}${final ? eol : ''}`
+}
+
+// The form `text` is `document` written in, or null when it is in none Atelier writes.
+function formOf(text, document) {
+  for (const eol of ['\n', '\r\n']) for (const final of [true, false]) if (text === jsonText(document, { eol, final })) return { eol, final }
+  return null
+}
+
+// A file Atelier may replace: a regular file, not a link to one elsewhere. `bytes` is null when there is none.
+function readRegularFile(file, { code, what }) {
+  const stat = fs.lstatSync(file, { throwIfNoEntry: false })
+  if (stat === undefined) return { bytes: null, mode: null }
+  if (!stat.isFile()) refuse('project-file-not-regular', `${what} is not a regular file, so Atelier does not rewrite it; make the change by hand`, { file: path.basename(file) })
+  try { return { bytes: fs.readFileSync(file), mode: stat.mode & 0o777 } } catch (error) { return refuse(code, `${what} cannot be read`, { cause: error.code ?? 'unreadable' }) }
+}
+
+// The text of a file's bytes, only when they are UTF-8 that decodes and encodes back to exactly them: a file in another
+// encoding is never rewritten, since a byte that is not UTF-8 would be replaced without the diff showing it.
+function textOf(bytes, refusal) {
+  const text = bytes.toString('utf8')
+  if (!Buffer.from(text, 'utf8').equals(bytes)) refusal()
+  return text
+}
+
+// The settings as enablement will read them, or a typed refusal naming what is wrong.
+function checkedSettings(document, settings) {
+  try {
+    readObsidianEnablement({ config: { ...document, ext: { ...(isPlainObject(document.ext) ? document.ext : {}), [OBSIDIAN_EXT_KEY]: settings } } })
+  } catch (error) {
+    if (error instanceof ObsidianMaintenanceRefusal || error instanceof ObsidianContractRefusal) refuse('invalid-view', 'the views would not satisfy the Obsidian settings contract; nothing was written', { errors: error.detail?.errors ?? [] })
+    throw error
+  }
+  return settings
+}
+
+// The project file with `settings` as its Obsidian member: { file, bytes, after, mode, diff }, `bytes` being the ones
+// it was made from. `document` is the file as read. Refuses a file that is not in a form Atelier writes, since
+// rewriting it would change more than the member, and names the member to add by hand.
+function planMember({ file, bytes, before, mode, document, settings }) {
+  const form = isPlainObject(document) && (document.ext === undefined || isPlainObject(document.ext)) ? formOf(before, document) : null
+  if (form === null) {
+    refuse('project-config-format-unknown', `${path.basename(file)} is not in the form Atelier writes (two-space JSON), so rewriting it would change more than the Obsidian member; nothing was written. Add the member by hand, under "ext"`, { member: { [OBSIDIAN_EXT_KEY]: settings } })
+  }
+  const next = { ...document, ext: { ...(document.ext ?? {}), [OBSIDIAN_EXT_KEY]: settings } }
+  const errors = validateProjectConfigDoc(next)
+  if (errors.length > 0) refuse('invalid-view', 'the project configuration would not be valid; nothing was written', { errors })
+  const after = jsonText(next, form)
+  return { file, what: path.basename(file), bytes, after, mode, diff: unifiedDiff(before, after, { label: path.basename(file) }) }
+}
+
+// The ignore line a project needs before the workspace pointer can be written:
+// { needed, file, bytes, after, mode, diff }.
+function planIgnore(project) {
+  if (project?.localState?.ignored === true) return { needed: false }
+  const file = path.join(project.configDir, '.gitignore')
+  const { bytes, mode } = readRegularFile(file, { code: 'gitignore-unreadable', what: 'the project\'s .gitignore' })
+  const before = bytes === null ? '' : textOf(bytes, () => refuse('gitignore-not-utf8', `the project's .gitignore is not UTF-8, so Atelier does not rewrite it; add the line ${LOCAL_STATE_LINE} to it by hand; nothing was written`, { line: LOCAL_STATE_LINE }))
+  const eol = before.includes('\r\n') ? '\r\n' : '\n'
+  const after = `${before}${before === '' || before.endsWith('\n') ? '' : eol}${LOCAL_STATE_LINE}${eol}`
+  return { needed: true, file, what: 'the project\'s .gitignore', bytes, after, mode, diff: unifiedDiff(before, after, { label: '.gitignore' }) }
+}
+
+// The project file as it is now: its bytes and their text, its mode, and its document (null when it is not JSON).
+function readProjectFile(project) {
+  const file = project?.configPath
+  if (typeof file !== 'string') refuse('project-config-unreadable', 'this project has no configuration file to write the view into')
+  const { bytes, mode } = readRegularFile(file, { code: 'project-config-unreadable', what: path.basename(file) })
+  if (bytes === null) refuse('project-config-unreadable', `${path.basename(file)} is not there`)
+  // Not UTF-8: in no form Atelier writes. The member is named for the person when the rest of the file can be read.
+  let before
+  try { before = textOf(bytes, () => { throw new SyntaxError('not UTF-8') }) } catch {
+    return { file, bytes, before: null, mode, document: null }
+  }
+  let document = null
+  try { document = JSON.parse(before) } catch { document = null }
+  return { file, bytes, before, mode, document }
+}
+
+// A folder as the repository-relative prefix of the notes a view selects, `./` and a trailing `/` dropped; null for
+// the whole repository.
+function folderPrefix(text) {
+  const cleaned = String(text).replace(/^(?:\.\/)+/, '').replace(/\/+$/, '')
+  if (cleaned === '' || cleaned === '.') return null
+  if (cleaned.startsWith('/') || cleaned.startsWith('~') || /^[A-Za-z]:/.test(cleaned) || cleaned.includes('\\') || cleaned.includes('\u0000') || cleaned.split('/').includes('..')) {
+    refuse('invalid-view', 'a folder is written relative to its repository\'s root, with "/", and without ".." (docs/notes, say)', { folder: String(text).slice(0, 200) })
+  }
+  return cleaned
+}
+
+// `DEPTH:MAX`: follow outgoing links up to DEPTH steps from the selected notes, adding at most MAX notes in all.
+function expansionOf(text) {
+  const match = /^([0-9]{1,2}):([0-9]{1,6})$/.exec(String(text))
+  const depth = match ? Number(match[1]) : NaN
+  const maxNodes = match ? Number(match[2]) : NaN
+  if (!(depth >= 1 && depth <= MAX_EXPANSION_DEPTH && maxNodes >= 1 && maxNodes <= MAX_EXPANSION_NODES)) {
+    refuse('invalid-view', `--expand is DEPTH:MAX, a depth from 1 to ${MAX_EXPANSION_DEPTH} and at most ${MAX_EXPANSION_NODES} notes in all (2:200, say)`)
+  }
+  return { depth, maxNodes, direction: 'outgoing', order: 'canonical-id' }
+}
+
+// The view `view add` asks for: every note (`all`, a full view), or a scoped view of the notes under folders of one
+// repository or with a tag, optionally expanded along outgoing links. `repositories` are the names of the project's
+// managed repositories; `repo` may be left out when there is one. (The contract's `type` selector matches a note's
+// file type, not its `kg.type`, so it is not offered here.)
+export function viewFromRequest({ scopeId, all = false, folders = [], repo, tag, expand, repositories = [] }) {
+  if (typeof scopeId !== 'string' || !SCOPE_ID.test(scopeId)) refuse('usage', 'a view is named by an identifier: a letter or digit, then letters, digits, ".", "_", ":" or "-", 128 at most')
+  const kinds = [all === true, folders.length > 0, tag !== undefined].filter(Boolean).length
+  if (kinds !== 1) refuse('usage', 'a view selects its notes with exactly one of --all, --folder PATH (as often as needed) or --tag T')
+  if (repo !== undefined && folders.length === 0) refuse('usage', '--repo names the repository of --folder')
+  if (all === true && expand !== undefined) refuse('usage', 'a view of every note has nothing to expand')
+  const expansion = expand === undefined ? undefined : expansionOf(expand)
+  let selector
+  if (all === true) selector = { all: true }
+  else if (tag !== undefined) selector = { tag }
+  else {
+    if (repo === undefined && repositories.length !== 1) refuse('view-repository-ambiguous', 'this project enrols more than one repository; name the one the folders are in with --repo', { repositories })
+    const repoId = repo ?? repositories[0]
+    if (!repositories.includes(repoId)) refuse('unknown-repo', 'the project enrols no repository of that name', { repositories })
+    const prefixes = [...new Set(folders.map(folderPrefix))]
+    const members = prefixes.includes(null) ? [{ repo: repoId }] : prefixes.map((pathPrefix) => ({ repo: repoId, pathPrefix }))
+    selector = members.length === 1 ? members[0] : { union: members }
+  }
+  return { scopeId, mode: all === true ? 'full' : 'scoped', selector, ...(expansion === undefined ? {} : { expansion }) }
+}
+
+// One more view: the project's Obsidian member with `scope` added (the member made, enabled, when there is none), and
+// the default when asked or when it is the first view. Refuses a view whose name is taken. Writes nothing:
+// { settings, member, ignore, diff }, for writeViewPlan.
+export function planViewAdd(project, { scope, makeDefault = false }) {
+  const source = readProjectFile(project)
+  const document = isPlainObject(source.document) ? source.document : project.config
+  const present = isPlainObject(document?.ext) ? document.ext[OBSIDIAN_EXT_KEY] : undefined
+  const scopes = Array.isArray(present?.scopes) ? present.scopes : []
+  if (scopes.some((item) => item?.scopeId === scope.scopeId)) refuse('view-exists', 'the project declares a view of this name already', { scopeId: scope.scopeId })
+  // A member of its own keeps its keys in their order; a new one is written as the documentation shows it.
+  const next = present === undefined
+    ? { schema: EXT_SETTINGS_SCHEMA, enabled: true, defaultScopeId: scope.scopeId, scopes: [scope] }
+    : { ...present, scopes: [...scopes, scope], ...(makeDefault || scopes.length === 0 ? { defaultScopeId: scope.scopeId } : {}) }
+  const settings = checkedSettings(document ?? {}, next)
+  const member = planMember({ ...source, settings })
+  const ignore = planIgnore(project)
+  return { settings, member, ignore, diff: `${member.diff}${ignore.needed ? ignore.diff : ''}` }
+}
+
+// A planned file still holds exactly the bytes its plan was made from (a file that was not there is still not there).
+function assertUnchanged({ file, what, bytes: planned }) {
+  const { bytes } = readRegularFile(file, { code: 'project-file-unreadable', what })
+  if (planned === null ? bytes !== null : bytes === null || !bytes.equals(planned)) {
+    refuse('project-config-changed', `${path.basename(file)} changed while the change was prepared; nothing was written`, { file: path.basename(file) })
+  }
+}
+
+// The temporary file a planned file's new text is written to, beside it: `.<name>.<pid>.<ms>.atelier.tmp`.
+const temporaryOf = (file) => path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}.atelier.tmp`)
+const isAlive = (pid) => { try { process.kill(pid, 0); return true } catch (error) { return error.code === 'EPERM' } }
+// Temporary files an earlier run left beside a planned file when it stopped between writing and renaming (a crash):
+// removed, unless the run that made them still runs, so none is left to be committed.
+function removeLeftovers(file) {
+  const pattern = new RegExp(`^\\.${path.basename(file).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.([0-9]+)\\.[0-9]+\\.atelier\\.tmp$`)
+  let names = []
+  try { names = fs.readdirSync(path.dirname(file)) } catch { return }
+  for (const name of names) {
+    const match = pattern.exec(name)
+    if (match !== null && (Number(match[1]) === process.pid || !isAlive(Number(match[1])))) fs.rmSync(path.join(path.dirname(file), name), { force: true })
+  }
+}
+
+// A planned file's new text in its temporary file, keeping its mode, and on the disk before any file is replaced.
+function writeTemporary({ file, after, mode }) {
+  const temporary = temporaryOf(file)
+  const descriptor = fs.openSync(temporary, 'wx', mode ?? 0o666)
+  try {
+    fs.writeFileSync(descriptor, after)
+    if (mode !== null) fs.fchmodSync(descriptor, mode)
+    fs.fsyncSync(descriptor)
+  } catch (error) {
+    fs.closeSync(descriptor)
+    fs.rmSync(temporary, { force: true })
+    throw error
+  } finally {
+    try { fs.closeSync(descriptor) } catch { /* closed above */ }
+  }
+  return temporary
+}
+
+// The folder of a replaced file, on the disk, so the renames survive a crash. A system that cannot sync a folder
+// (Windows) keeps the renames all the same.
+function syncFolder(folder) {
+  let descriptor
+  try { descriptor = fs.openSync(folder, 'r'); fs.fsyncSync(descriptor) } catch { /* not supported here */ } finally { if (descriptor !== undefined) fs.closeSync(descriptor) }
+}
+
+// Writes a plan of planViewAdd when every file it changes still holds the bytes it was made from: every new text is
+// written and synced to its temporary file first, then the files are replaced, the ignore line first, so a project
+// file that names a view never waits on it. A failure before the first replacement changes nothing
+// (`project-files-not-written`); one after it says which files changed (`project-files-partly-written`). No temporary
+// file is left. Commits nothing. Answers the files written. `rename` is injectable for tests.
+export function writeViewPlan(plan, { rename = fs.renameSync } = {}) {
+  const targets = [...(plan.ignore.needed ? [plan.ignore] : []), plan.member]
+  for (const target of targets) removeLeftovers(target.file)
+  for (const target of targets) assertUnchanged(target)
+  const prepared = []
+  const discard = () => { for (const { temporary } of prepared) fs.rmSync(temporary, { force: true }) }
+  try {
+    for (const target of targets) prepared.push({ target, temporary: writeTemporary(target) })
+  } catch (error) {
+    discard()
+    refuse('project-files-not-written', 'the change could not be written; nothing was changed', { cause: error.code ?? String(error.message) })
+  }
+  const written = []
+  for (const { target, temporary } of prepared) {
+    try { rename(temporary, target.file) } catch (error) {
+      discard()
+      const names = (list) => list.map((file) => path.basename(file))
+      const rest = targets.map((item) => item.file).filter((file) => !written.includes(file))
+      if (written.length === 0) refuse('project-files-not-written', 'the change could not be written; nothing was changed', { cause: error.code ?? String(error.message) })
+      refuse('project-files-partly-written', `${names(written).join(', ')} changed, and ${names(rest).join(', ')} could not be; finish the change by hand, or undo it`, { written: names(written), notWritten: names(rest), cause: error.code ?? String(error.message) })
+    }
+    written.push(target.file)
+  }
+  for (const folder of new Set(written.map((file) => path.dirname(file)))) syncFolder(folder)
+  return { written }
+}

package/src/runtime/obsidian/questions.mjs

@@ -0,0 +1,48 @@
+import readline from 'node:readline'
+
+// Questions for a person at a terminal, one line each, over the streams the
+// caller gives, so a test types the answers. A question never waits forever:
+// no line within the timeout (10 minutes), or the end of the input, is no
+// answer, so an agent that was handed a terminal still never hangs. Whether a
+// person is there at all is decided before anything is asked
+// (src/commands/obsidian.mjs `isInteractive`).
+
+export const ANSWER_TIMEOUT_MS = 10 * 60 * 1000
+const MAX_ANSWER_LENGTH = 4096
+const clean = (line) => line.slice(0, MAX_ANSWER_LENGTH).trim()
+
+// `ask(question)` writes the question and answers the next line typed, trimmed, or null when none came. A line typed
+// before its question is kept for it. `close()` stops reading.
+export function createQuestioner({ input, output, timeoutMs = ANSWER_TIMEOUT_MS }) {
+  const typed = []
+  const waiting = []
+  let ended = false
+  const lines = readline.createInterface({ input, terminal: false, crlfDelay: Infinity })
+  lines.on('line', (line) => { const next = waiting.shift(); if (next === undefined) typed.push(line); else next(line) })
+  lines.on('close', () => { ended = true; for (const next of waiting.splice(0)) next(null) })
+  return {
+    ask(question) {
+      output.write(question)
+      if (typed.length > 0) return Promise.resolve(clean(typed.shift()))
+      if (ended) return Promise.resolve(null)
+      return new Promise((resolve) => {
+        const answer = (line) => { clearTimeout(timer); resolve(line === null ? null : clean(line)) }
+        const timer = setTimeout(() => { waiting.splice(waiting.indexOf(answer), 1); output.write('\n'); resolve(null) }, timeoutMs)
+        waiting.push(answer)
+      })
+    },
+    close() { lines.close() },
+  }
+}
+
+// A go-ahead: Enter, y or yes is yes; n or no is no; anything else is asked again, three times in all. null: no answer.
+export async function askGoAhead(questioner, question) {
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const answer = await questioner.ask(question)
+    if (answer === null) return null
+    const word = answer.toLowerCase()
+    if (word === '' || word === 'y' || word === 'yes') return true
+    if (word === 'n' || word === 'no') return false
+  }
+  return null
+}

package/src/runtime/obsidian/release-watch.mjs

@@ -0,0 +1,56 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { packageRootOfEntry, readReleaseIdentity, walkRelease } from './service-record.mjs'
+
+// Whether the package a service runs from changed on disk since it started.
+//
+// A service started by a login item runs until the person logs out. When the
+// package it was started from is upgraded meanwhile (`npm i -D
+// @mnstry/atelier@<new>` in the project), it would go on running the release
+// it loaded, and load any module it had not needed yet from the new one. So,
+// under `--startup`, the service asks after every tick whether its package
+// changed, finishes that tick and exits with a code its service manager
+// restarts (service.mjs, service-main.mjs): the next process runs the new
+// release.
+//
+// The package is read through the path the service was started by, not its
+// real path: a linked install (`file:`, `npm link`) that is pointed elsewhere
+// is then seen. What is compared is the release identity (readReleaseIdentity
+// in service-record.mjs, the one a service records at its start): the package
+// version and a digest of every file under `src/`, `contracts/` and
+// `plugins/`, by relative path and content. It is cheap to ask: the files'
+// status (inode, size, change and modification time) is compared first, and
+// the digest is computed only when that differs. A package that cannot be read right now (an install in
+// progress) is not a change yet; it is asked again after the next tick.
+
+export { packageRootOfEntry, readReleaseIdentity }
+
+// The status of every file the identity covers and of package.json, as one comparable text. A package replaced by an
+// install has new inodes and change times even where the archive kept the modification times.
+export function releaseStatSignature({ root }) {
+  const lines = []
+  const stat = (relative, absolute) => { const found = fs.lstatSync(absolute); lines.push(`${relative}\0${found.dev}\0${found.ino}\0${found.size}\0${found.mtimeMs}\0${found.ctimeMs}`) }
+  walkRelease(root, stat)
+  stat('package.json', path.join(root, 'package.json'))
+  return lines.join('\n')
+}
+
+// { root, started, changed() }. `started` is the identity the service runs, read when the watch is made; `changed()`
+// answers true once the package on disk is another release, and false while it is the same or cannot be read.
+export function createReleaseWatch({ root, identityOf = readReleaseIdentity, signatureOf = releaseStatSignature } = {}) {
+  if (typeof root !== 'string' || !path.isAbsolute(root)) throw new TypeError('a release watch needs the absolute root of a package')
+  let signature = signatureOf({ root })
+  const started = identityOf({ root })
+  return {
+    root, started,
+    changed() {
+      let now
+      try { now = signatureOf({ root }) } catch { return false }
+      if (now === signature) return false
+      let identity
+      try { identity = identityOf({ root }) } catch { return false }
+      if (identity.version === started.version && identity.digest === started.digest) { signature = now; return false }
+      return true
+    },
+  }
+}