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

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
+    },
+  }
+}

package/src/runtime/obsidian/service-main.mjs

@@ -3,20 +3,29 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { firstString, parseArgs, resolveProjectConfig } from '../../project/config.mjs'
-import { runMaintenanceService } from './service.mjs'
+import { workspaceStateRoot } from './machine-settings.mjs'
+import { RELEASE_CHANGED, resolveServiceWorkspace, runMaintenanceService } from './service.mjs'
 
 // The process of the maintenance service. `start` runs it as a child; a unit
 // installed at the operating-system level runs it with `--startup`.
 //
 //   --project=<absolute atelier.project.json>   required
 //   --data-root=<absolute directory>            optional; otherwise the pointer, the overlay or the platform default
+//   --workspace-id=<identifier>                 named by a login item: under `--startup`, where a refusal is recorded
+//                                               when the project no longer leads to a workspace
 //   --runtime-id=<identifier>                   given by `start`, so it can recognise the child it created
 //   --interval-ms=<milliseconds>                optional
-//   --startup                                   run by an operating-system unit; needs a consent that covers startup
+//   --startup                                   run by a login item; needs a consent that covers startup
 //   --adapter=obsidian-cli                      the editor adapter; there is no default
 //
 // Without `--adapter` the process refuses before it listens or ticks: reaching
 // a running app is a decision of whoever starts the service, never a default.
+//
+// Exit codes: 0 after a clean stop, and under `--startup` after a refusal too;
+// 2 (EXIT_REFUSED) after a refusal otherwise; 75 (EXIT_RELEASE_CHANGED) under
+// `--startup` once the package changed on disk; 1 after an error without a
+// code. A refusal is any error that carries a string code, Node's system
+// errors (EACCES, EADDRNOTAVAIL, EPERM) included.
 
 // Reaching a real app happens here and nowhere else in the service: the
 // production probe and the CLI transport are imported only once `--adapter`
@@ -33,52 +42,121 @@ import { runMaintenanceService } from './service.mjs'
 // only read here.
 const ADAPTERS = Object.freeze({
   'obsidian-cli': async () => {
-    const [{ createObsidianCliAdapter, defaultObsidianProcessProbe }, { createProductionAppProbe }, { createQualifiedAdapterFactory }, { obsidianUserDataDir, readObsidianSettings }, { appStateSignature }] = await Promise.all([
+    const [{ createObsidianCliAdapter, defaultObsidianProcessProbe }, { createProductionAppProbe }, { createQualifiedAdapterFactory }, { obsidianSandboxedBuild, obsidianUserDataDir, readObsidianSettings }, { appStateSignature }, { readAppVaultListForAllocation }, { createProductionUnheldEvidence }] = await Promise.all([
       import('../../projection/obsidian/publication/transport.mjs'), import('./app-production-seams.mjs'), import('./app-capability.mjs'),
-      import('../../projection/obsidian/publication/vault-list.mjs'), import('./app-registration.mjs'),
+      import('../../projection/obsidian/publication/vault-list.mjs'), import('./app-registration.mjs'), import('./vault-location.mjs'), import('./unheld-evidence.mjs'),
     ])
     const adapterFactory = createQualifiedAdapterFactory({ appProbe: createProductionAppProbe(), createAdapter: ({ qualification }) => createObsidianCliAdapter({ qualification }) })
     const userDataDir = obsidianUserDataDir()
     const observeApp = () => appStateSignature({ processes: defaultObsidianProcessProbe(), settings: userDataDir === null ? null : readObsidianSettings({ userDataDir }) })
+    // The app's own vault list, read from its file and never written, so a new vault's folder is never allocated inside
+    // a vault it lists nor under a name one of its vaults has; a list that cannot be read allocates nothing.
+    const readAppVaultList = () => readAppVaultListForAllocation({
+      read: () => (userDataDir === null ? { ok: false, code: 'obsidian-settings-location-unknown' } : readObsidianSettings({ userDataDir })),
+      sandboxed: obsidianSandboxedBuild() !== null,
+    })
     return {
-      adapterFactory, engineOptions: { observeApp },
+      // The same file tells the publisher whether a view's first publication may go into a vault no Obsidian lists yet.
+      adapterFactory, engineOptions: { observeApp, readAppVaultList, readUnheldEvidence: createProductionUnheldEvidence() },
       appStatus: () => { const known = adapterFactory.lastQualification(); return known === null ? null : { outcome: known.outcome, reason: known.reason, version: known.version, floor: known.floor } },
     }
   },
 })
 
+// What the tests read: which reader each adapter hands its engine. Calling one builds the production seams, and
+// reaches no app and no file until the engine uses them.
+export { ADAPTERS as SERVICE_ADAPTERS }
+
+import { createReleaseWatch, packageRootOfEntry } from './release-watch.mjs'
 import { SERVICE_ENTRY_PATH } from './service-entry-path.mjs'
+import { LAST_STARTUP_SCHEMA, openServiceLog, writeLastStartup } from './service-record.mjs'
 
 export { SERVICE_ENTRY_PATH }
 export const EXIT_REFUSED = 2
+// A service a login item started exits with this code when the package it runs from changed on disk: its service
+// manager restarts it (a non-zero exit), on the release now installed. EX_TEMPFAIL.
+export const EXIT_RELEASE_CHANGED = 75
 
-const log = (entry) => { try { process.stdout.write(`${JSON.stringify(entry)}\n`) } catch { /* a closed log never ends the service */ } }
+const printed = (entry) => { try { process.stdout.write(`${JSON.stringify(entry)}\n`) } catch { /* a closed log never ends the service */ } }
+
+// The workspace of a service a login item started, when it can be found: where it keeps its log and records how its
+// start ended. When the project no longer leads to one (it moved, its pointer is gone), the workspace the unit names by
+// its data root and identity, if that exists; it is never created here. Null otherwise; a refusal is then printed
+// only, into the unit's own output file.
+function startupWorkspace({ loadProject, dataRoot, workspaceId, env = process.env, platform = process.platform }) {
+  try {
+    const workspace = resolveServiceWorkspace({ project: loadProject(), dataRoot, env, platform })
+    if (workspace?.workspaceRoot) return workspace
+  } catch { /* the workspace the unit names, below */ }
+  if (typeof dataRoot !== 'string' || !path.isAbsolute(dataRoot) || typeof workspaceId !== 'string') return null
+  try {
+    const root = workspaceStateRoot(path.resolve(dataRoot), workspaceId)
+    return fs.lstatSync(root).isDirectory() ? { workspaceId, workspaceRoot: fs.realpathSync(root) } : null
+  } catch { return null }
+}
+
+// The service's own log, bounded as under `start`, which hands a child that same file. Under a login item the output
+// goes to the unit's file instead, which nothing bounds; it keeps only what happens before this log is open.
+function workspaceLog(workspaceRoot) {
+  let descriptor
+  try { descriptor = openServiceLog(workspaceRoot).descriptor } catch { return printed }
+  return (entry) => { try { fs.writeSync(descriptor, `${JSON.stringify(entry)}\n`) } catch { /* a closed log never ends the service */ } }
+}
+
+function recordStartup(workspace, { at, outcome, code }) {
+  if (workspace === null) return
+  try { writeLastStartup({ ...workspace, document: { schema: LAST_STARTUP_SCHEMA, workspaceId: workspace.workspaceId, at, outcome, code } }) } catch { /* reported by the log only */ }
+}
 
 // The common body of a service process: run, end cleanly on a signal, exit 0
 // after a clean stop and EXIT_REFUSED when the service refused to run.
+//
+// Started by a login item (`startup`), it logs into its workspace's bounded
+// service log, records how the start ended (`last-startup.json`), exits 0 on
+// a refusal as well, so the service manager does not start it again every
+// minute over something that does not change by itself, and exits
+// EXIT_RELEASE_CHANGED after the tick that found another release on disk.
+// Anything else that ends it (an error nobody typed, a signal) is a crash,
+// and the manager restarts it after its throttle.
 export async function runServiceProcess(options) {
+  const startup = options.startup === true
+  const workspace = startup ? startupWorkspace(options) : null
+  const log = workspace === null ? printed : workspaceLog(workspace.workspaceRoot)
   try {
-    const service = await runMaintenanceService({ log, ...options })
+    const service = await runMaintenanceService({ log, invokedAs: process.argv[1], ...options })
+    if (startup) recordStartup(workspace, { at: new Date().toISOString(), outcome: 'started', code: null })
     for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => { void service.shutdown(`signal-${signal}`) })
-    await service.done
+    const { reason } = await service.done
     // Everything durable is on disk by now; nothing left over may keep a stopped service's PID alive.
-    process.exit(0)
+    process.exit(reason === RELEASE_CHANGED ? EXIT_RELEASE_CHANGED : 0)
   } catch (error) {
-    log({ at: new Date().toISOString(), event: 'refused', code: error?.code ?? 'untyped-error', message: String(error?.message ?? error) })
-    process.exitCode = typeof error?.code === 'string' ? EXIT_REFUSED : 1
+    const at = new Date().toISOString()
+    const code = typeof error?.code === 'string' ? error.code : null
+    log({ at, event: 'refused', code: code ?? 'untyped-error', message: String(error?.message ?? error) })
+    if (startup && code !== null) { recordStartup(workspace, { at, outcome: 'refused', code }); process.exitCode = 0; return }
+    process.exitCode = code !== null ? EXIT_REFUSED : 1
   }
 }
 
+// The release a service a login item started runs, read through the path it was started by (`argv[1]`), so an
+// upgrade, or a linked install pointed elsewhere, is seen. Null when that package cannot be read.
+function watchRelease(invokedAs) {
+  const root = packageRootOfEntry(invokedAs) ?? packageRootOfEntry(SERVICE_ENTRY_PATH)
+  if (root === null) return null
+  try { return createReleaseWatch({ root }) } catch { return null }
+}
+
 export function serviceOptionsFromArgv(argv, { env = process.env } = {}) {
   const args = parseArgs(argv)
   const configPath = firstString(args.project)
   if (!configPath || !path.isAbsolute(configPath)) throw Object.assign(new Error('--project must be the absolute path of a project configuration'), { code: 'service-arguments-invalid' })
   const dataRoot = firstString(args['data-root']) ?? undefined
+  const workspaceId = firstString(args['workspace-id']) ?? undefined
   const intervalMs = args['interval-ms'] === undefined ? undefined : Number(args['interval-ms'])
   if (intervalMs !== undefined && (!Number.isInteger(intervalMs) || intervalMs < 1)) throw Object.assign(new Error('--interval-ms must be a positive integer'), { code: 'service-arguments-invalid' })
   return {
     loadProject: () => resolveProjectConfig({ argv: [`--project=${configPath}`], cwd: path.dirname(configPath), env, writeLocalState: false }),
-    ...(dataRoot === undefined ? {} : { dataRoot }), ...(intervalMs === undefined ? {} : { intervalMs }),
+    ...(dataRoot === undefined ? {} : { dataRoot }), ...(workspaceId === undefined ? {} : { workspaceId }), ...(intervalMs === undefined ? {} : { intervalMs }),
     ...(firstString(args['runtime-id']) ? { runtimeId: firstString(args['runtime-id']) } : {}),
     startup: args.startup === true, adapter: firstString(args.adapter),
   }
@@ -87,13 +165,18 @@ export function serviceOptionsFromArgv(argv, { env = process.env } = {}) {
 const invokedDirectly = (() => { try { return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)) } catch { return false } })()
 
 if (invokedDirectly) {
+  const argv = process.argv.slice(2)
+  // As early as this entry can: its static imports have already loaded most of the modules, so a release that changes
+  // between this process's start and this reading is not noticed until the next change (docs/obsidian.md says so).
+  const releaseWatch = argv.includes('--startup') ? watchRelease(process.argv[1]) : null
   let options = null
   try {
-    options = serviceOptionsFromArgv(process.argv.slice(2))
+    options = serviceOptionsFromArgv(argv)
     if (!options.adapter || !Object.hasOwn(ADAPTERS, options.adapter)) throw Object.assign(new Error('no editor adapter was selected; pass --adapter explicitly'), { code: 'service-adapter-not-selected' })
   } catch (error) {
-    log({ at: new Date().toISOString(), event: 'refused', code: error.code ?? 'untyped-error', message: error.message })
-    process.exitCode = EXIT_REFUSED
+    printed({ at: new Date().toISOString(), event: 'refused', code: error.code ?? 'untyped-error', message: error.message })
+    // Under a login item arguments that do not work never will: it ends cleanly, and is not started again every minute.
+    process.exitCode = argv.includes('--startup') ? 0 : EXIT_REFUSED
     options = null
   }
   if (options) {
@@ -101,6 +184,6 @@ if (invokedDirectly) {
     const [{ loadContributions }, { createObsidianRegistry }] = await Promise.all([import('./contributions.mjs'), import('./extension-points.mjs')])
     const registry = createObsidianRegistry({ contributions: await loadContributions() })
     const { engineOptions, ...seams } = await ADAPTERS[adapter]()
-    await runServiceProcess({ ...rest, entryPath: SERVICE_ENTRY_PATH, ...seams, engineOptions: { ...engineOptions, extensions: registry.extensions } })
+    await runServiceProcess({ ...rest, entryPath: SERVICE_ENTRY_PATH, ...seams, engineOptions: { ...engineOptions, extensions: registry.extensions }, releaseWatch })
   }
 }