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

package/plugins/obsidian/main.js

@@ -0,0 +1,444 @@
+'use strict'
+
+// Atelier's own plugin. Atelier ships it into every vault it manages, under
+// .obsidian/plugins/atelier-projection/, beside a data file that names the
+// maintenance service of the workspace and this vault's key (its bearer). The
+// person never installs it; Obsidian asks once per vault whether to trust the
+// vault's plugins, and until then (or in restricted mode, or on an app older
+// than 1.13.7) everything works without it.
+//
+// Phase 1: presence and status, read-only. While the vault is open the plugin
+// tells the service so (a lease renewed every two seconds, released when the
+// plugin unloads), reports the app version it runs in, and shows the view's
+// freshness in the status bar and in "Atelier: show status".
+//
+// The key never leaves this machine's files. The plugin first asks whatever
+// listens at the service's address to prove that it holds the key, and sends
+// nothing that names this vault until it did; then it proves the same, and
+// every later request and answer is sealed with a key for that session only.
+//
+// What it never does: write a file (a note, a setting, its own data file),
+// run code it is sent, or reach anything but that one service, on a literal
+// loopback address, with no name to resolve.
+
+const obsidian = require('obsidian')
+
+// Held equal to src/projection/obsidian/plugin-bridge/channel.mjs by the test suite.
+const CHANNEL = Object.freeze({
+  pluginId: 'atelier-projection',
+  protocol: 'atelier-obsidian-plugin-channel/v2',
+  dataSchema: 'atelier-obsidian-plugin-data/v1',
+  statusSchema: 'atelier-obsidian-plugin-status/v1',
+  routes: Object.freeze({ challenge: '/plugin/challenge', hello: '/plugin/hello', lease: '/plugin/lease', release: '/plugin/release', status: '/plugin/status' }),
+  renewEveryMs: 2000,
+  requestTimeoutMs: 1500,
+  maxResponseBytes: 64 * 1024,
+  minimumAppVersion: '1.13.7',
+})
+
+const BEARER = /^[A-Za-z0-9_-]{43}$/
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const NONCE = /^[0-9a-f]{64}$/
+const MAC = /^[0-9a-f]{64}$/
+const HANDSHAKE_ID = /^ph-[0-9a-f]{32}$/
+const SESSION_ID = /^ps-[0-9a-f]{32}$/
+const VERSION = /^v?(\d{1,9})\.(\d{1,9})\.(\d{1,9})(?:-([0-9A-Za-z.]+))?/
+
+// -1, 0 or 1; null when either side is not a version. A prerelease ranks below its release.
+function compareVersions(left, right) {
+  const [a, b] = [VERSION.exec(String(left || '')), VERSION.exec(String(right || ''))]
+  if (!a || !b) return null
+  for (let index = 1; index <= 3; index += 1) if (Number(a[index]) !== Number(b[index])) return Number(a[index]) < Number(b[index]) ? -1 : 1
+  if (Boolean(a[4]) === Boolean(b[4])) return a[4] === b[4] || !a[4] ? 0 : a[4] < b[4] ? -1 : 1
+  return a[4] ? -1 : 1
+}
+
+function meetsFloor(version) {
+  const order = compareVersions(version, CHANNEL.minimumAppVersion)
+  return order !== null && order >= 0
+}
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+// The handshake and session computations of plugin-bridge/channel.mjs; the
+// test suite holds the two to each other. Every input but the vault path is a
+// shape without a line break, and the vault path is the only input of its
+// computation, so joining them by lines is unambiguous.
+function transcript(label, fields) {
+  return [CHANNEL.protocol, label].concat(fields.map(String)).join('\n')
+}
+function hmac(crypto, key, label, fields) {
+  return crypto.createHmac('sha256', key).update(transcript(label, fields), 'utf8').digest()
+}
+function hmacHex(crypto, key, label, fields) {
+  return hmac(crypto, key, label, fields).toString('hex')
+}
+// Two MACs in hex, compared in time that does not depend on where they differ.
+function sameMac(presented, expected) {
+  if (typeof presented !== 'string' || !MAC.test(presented) || presented.length !== expected.length) return false
+  let difference = 0
+  for (let index = 0; index < expected.length; index += 1) difference |= presented.charCodeAt(index) ^ expected.charCodeAt(index)
+  return difference === 0
+}
+// The exact address the service is reached at, as both proofs bind it.
+const authorityOf = (channel) => (channel.host === '::1' ? `[::1]:${channel.port}` : `127.0.0.1:${channel.port}`)
+
+// The channel this vault's data file names, or null when it names none that can be used.
+function channelOf(data) {
+  if (!isPlainObject(data) || data.schema !== CHANNEL.dataSchema || !isPlainObject(data.channel)) return null
+  const { host, port } = data.channel
+  if (host !== '127.0.0.1' && host !== '::1') return null
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) return null
+  if (typeof data.scopeId !== 'string' || !IDENTIFIER.test(data.scopeId) || typeof data.bearer !== 'string' || !BEARER.test(data.bearer)) return null
+  return Object.freeze({ host, port, scopeId: data.scopeId, bearer: data.bearer })
+}
+
+// What the status bar says. `held` carries the number of held edits.
+const LABELS = Object.freeze({
+  connecting: 'Atelier: connecting',
+  current: 'Atelier: current',
+  updating: 'Atelier: updating',
+  stale: 'Atelier: stale',
+  unreachable: 'Atelier: service unreachable',
+  'not-set-up': 'Atelier: not set up',
+  unsupported: 'Atelier: needs a newer Obsidian',
+})
+
+function labelOf(view) {
+  return view.state === 'held' ? `Atelier: held (${view.held})` : LABELS[view.state]
+}
+
+const plural = (count, one, many) => (count === 1 ? one : many)
+
+// The two ways a round can fail to reach the view. Between them the status bar moves only once two rounds agree.
+const ROUND_FAILURES = new Set(['not-set-up', 'unreachable'])
+
+// Notices on a transition into a state that needs a person, and back out of one.
+const ATTENTION = Object.freeze({
+  held: (view) => `Atelier kept ${plural(view.held, 'an edit', `${view.held} edits`)} you made. This view is not updated over ${plural(view.held, 'it', 'them')} until ${plural(view.held, 'it is', 'they are')} applied or withdrawn.`,
+  stale: () => 'Atelier: this view is not current. "Atelier: show status" says why.',
+  unreachable: () => 'Atelier: the maintenance service does not answer. The vault stays as it is.',
+  unsupported: () => `Atelier's plugin needs Obsidian ${CHANNEL.minimumAppVersion} or later. The vault keeps working without it.`,
+})
+
+// The view as the service reports it. Anything but current, updating or held is stale.
+function viewOfStatus(body) {
+  const view = isPlainObject(body) && body.schema === CHANNEL.statusSchema && isPlainObject(body.view) ? body.view : null
+  const common = { reason: view && typeof view.reason === 'string' ? view.reason : 'no-freshness-recorded', report: isPlainObject(body) ? body : null }
+  if (view === null) return { state: 'stale', ...common }
+  if (view.state === 'current') return { state: 'current', ...common }
+  if (view.state === 'updating') return { state: 'updating', ...common }
+  if (view.state === 'held-for-your-edit') return { state: 'held', held: Number.isInteger(view.heldNoteCount) ? view.heldNoteCount : 0, ...common }
+  return { state: 'stale', ...common }
+}
+
+const readable = (code) => (typeof code === 'string' && code !== '' ? code.replace(/[-_]+/g, ' ') : 'none')
+const byteLength = (text) => new TextEncoder().encode(text).length
+
+// One request to the service. Resolves, never rejects:
+//   { kind: 'response', statusCode, body }   body is a JSON object or null
+//   { kind: 'unreachable', code }            nothing usable came back
+function post(http, channel, route, body) {
+  return new Promise((resolve) => {
+    let settled = false
+    const settle = (value) => { if (!settled) { settled = true; resolve(value) } }
+    const text = JSON.stringify(body)
+    const authority = authorityOf(channel)
+    let request
+    try {
+      // A literal loopback address, whatever the data file said: nothing is resolved by name.
+      request = http.request({ host: channel.host === '::1' ? '::1' : '127.0.0.1', family: channel.host === '::1' ? 6 : 4, port: channel.port, method: 'POST', path: route, agent: false, timeout: CHANNEL.requestTimeoutMs,
+        headers: { Host: authority, 'Content-Type': 'application/json', 'Content-Length': byteLength(text), Connection: 'close' } }, (response) => {
+        let size = 0
+        let received = ''
+        response.setEncoding('utf8')
+        response.on('data', (chunk) => {
+          size += chunk.length
+          if (size > CHANNEL.maxResponseBytes) { settle({ kind: 'unreachable', code: 'answer-too-large' }); request.destroy() } else received += chunk
+        })
+        response.on('end', () => {
+          let parsed = null
+          try { parsed = JSON.parse(received) } catch { parsed = null }
+          settle({ kind: 'response', statusCode: response.statusCode, body: isPlainObject(parsed) ? parsed : null })
+        })
+        response.on('error', () => settle({ kind: 'unreachable', code: 'answer-failed' }))
+      })
+    } catch {
+      settle({ kind: 'unreachable', code: 'request-failed' })
+      return
+    }
+    request.on('timeout', () => { settle({ kind: 'unreachable', code: 'timeout' }); request.destroy() })
+    request.on('error', (error) => settle({ kind: 'unreachable', code: error && error.code === 'ECONNREFUSED' ? 'refused' : 'request-failed' }))
+    request.end(text)
+  })
+}
+
+class AtelierStatusModal extends obsidian.Modal {
+  constructor(app, rows) {
+    super(app)
+    this.rows = rows
+  }
+
+  onOpen() {
+    this.setTitle('Atelier status')
+    const list = this.contentEl.createEl('dl', { cls: 'atelier-projection-status' })
+    for (const [label, value] of this.rows) {
+      list.createEl('dt', { text: label })
+      list.createEl('dd', { text: value })
+    }
+  }
+
+  onClose() {
+    this.contentEl.empty()
+  }
+}
+
+class AtelierProjectionPlugin extends obsidian.Plugin {
+  async onload() {
+    this.channel = null
+    this.session = null
+    this.cycling = null
+    this.unloaded = false
+    this.view = { state: 'connecting', reason: 'not-yet-asked', report: null }
+    this.shownState = null
+    // A round's failure that differs from the failure shown, not yet seen twice in a row.
+    this.pendingFailure = null
+    this.appVersion = typeof obsidian.apiVersion === 'string' ? obsidian.apiVersion : null
+    this.statusBarEl = this.addStatusBarItem()
+    this.statusBarEl.addClass('atelier-projection-status-bar')
+    this.registerDomEvent(this.statusBarEl, 'click', () => this.showStatus())
+    this.addCommand({ id: 'show-status', name: 'Show status', callback: () => this.showStatus() })
+    this.setView(this.view)
+
+    if (!meetsFloor(this.appVersion)) {
+      // Older than the floor, or a version that cannot be read: visible, and the channel stays closed.
+      this.setView({ state: 'unsupported', reason: 'app-below-minimum-version', report: null })
+      return
+    }
+    try {
+      this.http = require('http')
+      this.fs = require('fs')
+      this.crypto = require('crypto')
+    } catch {
+      this.http = null
+    }
+    if (!this.http || typeof this.http.request !== 'function' || !this.fs || typeof this.fs.realpathSync !== 'function' || !this.crypto || typeof this.crypto.createHmac !== 'function' || typeof this.crypto.randomBytes !== 'function') {
+      this.setView({ state: 'not-set-up', reason: 'node-modules-unavailable', report: null })
+      return
+    }
+    // This launch of the plugin: the service tells two apps holding the same vault apart by it.
+    this.instanceId = `pi-${this.crypto.randomBytes(16).toString('hex')}`
+    await this.readChannel()
+    this.registerInterval(globalThis.setInterval(() => { void this.cycle() }, CHANNEL.renewEveryMs))
+    // Not awaited: the app finishes loading while the first round trip is under way.
+    void this.cycle()
+  }
+
+  onunload() {
+    // The lease lapses by itself; releasing it says at once that the vault closed. A round still under way stops at its
+    // next step, and a session it opens after this is released at once.
+    this.unloaded = true
+    const session = this.session
+    this.session = null
+    if (this.channel && session) void this.release(this.channel, session)
+  }
+
+  // Obsidian calls this when data.json changed on disk: Atelier republished the channel.
+  async onExternalSettingsChange() {
+    await this.readChannel()
+    // A round under way still speaks for the old channel; the next one uses the new.
+    if (this.cycling) await this.cycling
+    await this.cycle()
+  }
+
+  async readChannel() {
+    let data = null
+    try { data = await this.loadData() } catch { data = null }
+    const next = channelOf(data)
+    const same = next && this.channel && next.host === this.channel.host && next.port === this.channel.port && next.scopeId === this.channel.scopeId && next.bearer === this.channel.bearer
+    if (!same) this.session = null
+    this.channel = next
+    if (next === null) this.setView({ state: 'not-set-up', reason: data === null ? 'no-channel-data' : 'channel-data-unusable', report: null })
+  }
+
+  // One round: shake hands (once per session), renew the lease, read the status.
+  cycle() {
+    if (this.cycling) return this.cycling
+    this.cycling = this.runCycle().finally(() => { this.cycling = null })
+    return this.cycling
+  }
+
+  // Whether a round that started for `channel` may still act.
+  current(channel) {
+    return !this.unloaded && channel === this.channel
+  }
+
+  async runCycle() {
+    const channel = this.channel
+    if (channel === null || this.unloaded) return
+    if (this.session === null) {
+      if (!(await this.handshake(channel))) return
+    } else {
+      const lease = await this.request(channel, 'lease')
+      if (!this.current(channel)) return
+      if (lease.kind !== 'sealed') {
+        // Whatever answered did not seal its answer with the session's key: the session ends here, and the next request
+        // starts a handshake, which only the service can answer. An unproven listener gets no second request of it.
+        this.session = null
+        if (!(lease.kind === 'refused' && (lease.error === 'session-unknown' || lease.statusCode === 401))) {
+          this.showRound(this.unreachable(lease))
+          return
+        }
+        // The service started again since, the vault's key changed, or the session is not accepted: shake hands at once.
+        if (!(await this.handshake(channel))) return
+      }
+    }
+    const status = await this.request(channel, 'status')
+    if (!this.current(channel)) return
+    if (status.kind !== 'sealed') this.session = null
+    this.showRound(status.kind === 'sealed' ? viewOfStatus(status.document) : this.unreachable(status))
+  }
+
+  // The handshake. Nothing that names this vault is sent before the listener proved it holds the vault's key.
+  async handshake(channel) {
+    let vaultPath = null
+    // As the file system stores the path, as the service proves it: the app may have the vault in another letter case.
+    // On Windows Node's own resolution, as the service's (the native one also expands short names).
+    const native = globalThis.process?.platform !== 'win32' && typeof this.fs.realpathSync.native === 'function'
+    try { vaultPath = native ? this.fs.realpathSync.native(this.app.vault.adapter.getBasePath()) : this.fs.realpathSync(this.app.vault.adapter.getBasePath()) } catch { vaultPath = null }
+    if (typeof vaultPath !== 'string') {
+      this.showRound({ state: 'not-set-up', reason: 'vault-path-unknown', report: null })
+      return false
+    }
+    const crypto = this.crypto
+    const clientNonce = crypto.randomBytes(32).toString('hex')
+    const issuedAt = Date.now()
+    const challenge = await post(this.http, channel, CHANNEL.routes.challenge, { protocol: CHANNEL.protocol, keyHint: hmacHex(crypto, channel.bearer, 'key-hint', [clientNonce, issuedAt]), clientNonce, issuedAt })
+    if (!this.current(channel)) return false
+    const offer = challenge.kind === 'response' && challenge.statusCode === 200 ? challenge.body : null
+    if (offer === null) {
+      // A 401 is a key the service does not know, unless the service says the challenge itself came too late or was
+      // answered already: the key is not in question then, and the next round's fresh challenge tries again.
+      const refusal = challenge.kind === 'response' && challenge.body ? challenge.body.error : null
+      const keyUnknown = challenge.kind === 'response' && challenge.statusCode === 401 && refusal !== 'challenge-stale' && refusal !== 'challenge-replayed'
+      this.showRound(keyUnknown ? { state: 'not-set-up', reason: 'key-not-known-to-the-service', report: null } : this.unreachable(challenge))
+      return false
+    }
+    const bound = [channel.scopeId, authorityOf(channel), clientNonce, offer.serverNonce, offer.handshakeId]
+    if (offer.protocol !== CHANNEL.protocol || typeof offer.handshakeId !== 'string' || !HANDSHAKE_ID.test(offer.handshakeId) || typeof offer.serverNonce !== 'string' || !NONCE.test(offer.serverNonce)
+      || !sameMac(offer.serverProof, hmacHex(crypto, channel.bearer, 'server-proof', bound))) {
+      // Whatever answers there does not hold this vault's key: it is told nothing more.
+      this.showRound({ state: 'unreachable', reason: 'listener-not-proven', report: null })
+      return false
+    }
+    const key = hmac(crypto, channel.bearer, 'session-key', bound)
+    const vaultProof = hmacHex(crypto, key, 'vault', [vaultPath])
+    const pluginVersion = String(this.manifest.version)
+    const clientProof = hmacHex(crypto, channel.bearer, 'client-proof', bound.concat([pluginVersion, this.appVersion, this.instanceId, vaultProof]))
+    const answer = await post(this.http, channel, CHANNEL.routes.hello, { handshakeId: offer.handshakeId, pluginVersion, appVersion: this.appVersion, instanceId: this.instanceId, vaultProof, clientProof })
+    const sealed = this.opened(answer, 'hello', { key, id: null }, 0)
+    if (sealed.kind === 'sealed') {
+      const session = { id: sealed.sessionId, key, counter: 0 }
+      if (!this.current(channel)) {
+        // Unloaded, or a new channel, while the hello was under way: the session it opened is let go at once.
+        void this.release(channel, session)
+        return false
+      }
+      this.session = session
+      return true
+    }
+    if (!this.current(channel)) return false
+    // A copy of a vault carries its data file, but the service maintains the original only.
+    if (sealed.kind === 'refused' && sealed.statusCode === 409 && sealed.error === 'wrong-vault') this.showRound({ state: 'not-set-up', reason: 'not-the-vault-atelier-maintains', report: null })
+    else this.showRound(this.unreachable(sealed))
+    return false
+  }
+
+  // One command of the session: a counter that only goes up, and a MAC over it under the session's key.
+  request(channel, command) {
+    const session = this.session
+    session.counter += 1
+    const counter = session.counter
+    return post(this.http, channel, CHANNEL.routes[command], { sessionId: session.id, counter, mac: hmacHex(this.crypto, session.key, 'request', [command, session.id, counter]) })
+      .then((answer) => this.opened(answer, command, session, counter))
+  }
+
+  release(channel, session) {
+    session.counter += 1
+    return post(this.http, channel, CHANNEL.routes.release, { sessionId: session.id, counter: session.counter, mac: hmacHex(this.crypto, session.key, 'request', ['release', session.id, session.counter]) })
+  }
+
+  // An answer counts only when it is sealed with the session's key over this very request:
+  //   { kind: 'sealed', document, sessionId }   the service's own answer
+  //   { kind: 'refused', statusCode, error }    an error; nobody vouches for it, so it only ever makes the plugin ask again
+  //   { kind: 'unreachable', code }             nothing usable came back
+  opened(answer, command, session, counter) {
+    if (answer.kind !== 'response') return answer
+    const body = answer.body
+    if (answer.statusCode !== 200) return { kind: 'refused', statusCode: answer.statusCode, error: body && typeof body.error === 'string' ? body.error : null }
+    let document = null
+    try { document = body && typeof body.payload === 'string' ? JSON.parse(body.payload) : null } catch { document = null }
+    // A hello's answer names the session it opened; the MAC over it is what vouches for that name.
+    const sessionId = command === 'hello' ? (isPlainObject(document) && typeof document.sessionId === 'string' && SESSION_ID.test(document.sessionId) ? document.sessionId : null) : session.id
+    if (!isPlainObject(document) || sessionId === null || !sameMac(body.mac, hmacHex(this.crypto, session.key, 'response', [command, sessionId, counter, body.payload]))) return { kind: 'unreachable', code: 'answer-not-authenticated' }
+    return { kind: 'sealed', document, sessionId }
+  }
+
+  unreachable(answer) {
+    const reason = answer.kind === 'unreachable' ? answer.code : typeof answer.error === 'string' ? answer.error : answer.body && typeof answer.body.error === 'string' ? answer.body.error : `answered-${answer.statusCode}`
+    return { state: 'unreachable', reason, report: null }
+  }
+
+  // What a round found. A failure other than the one shown ('not set up' where 'service unreachable' is shown, or the other
+  // way round) is shown only when the next round finds it too, so answers that alternate between them do not make the
+  // status bar flip. Anything else is shown at once.
+  showRound(view) {
+    if (ROUND_FAILURES.has(view.state) && ROUND_FAILURES.has(this.shownState) && view.state !== this.shownState && this.pendingFailure !== view.state) {
+      this.pendingFailure = view.state
+      return
+    }
+    this.setView(view)
+  }
+
+  setView(view) {
+    // Nothing is shown once the plugin unloaded.
+    if (this.unloaded) return
+    this.pendingFailure = null
+    const previous = this.shownState
+    this.view = view
+    this.statusBarEl.setText(labelOf(view))
+    this.statusBarEl.setAttr('aria-label', `${labelOf(view)} (${readable(view.reason)})`)
+    this.shownState = view.state
+    if (previous === view.state || previous === null) return
+    if (Object.prototype.hasOwnProperty.call(ATTENTION, view.state)) new obsidian.Notice(ATTENTION[view.state](view))
+    else if (view.state === 'current' && Object.prototype.hasOwnProperty.call(ATTENTION, previous)) new obsidian.Notice('Atelier: this view is current again.')
+  }
+
+  statusRows() {
+    const report = this.view.report || {}
+    const view = isPlainObject(report.view) ? report.view : {}
+    const count = (value) => (Number.isInteger(value) ? String(value) : 'unknown')
+    const channel = this.channel
+    return [
+      ['View', channel ? channel.scopeId : 'not set up'],
+      ['State', labelOf(this.view).replace(/^Atelier: /, '')],
+      ['Reason', readable(this.view.reason)],
+      ['Generation', typeof view.generationId === 'string' ? view.generationId : 'none yet'],
+      ['Prepared generation', typeof view.preparedGenerationId === 'string' ? view.preparedGenerationId : 'none yet'],
+      ['Checked at', typeof view.checkedAt === 'string' ? view.checkedAt : 'not yet'],
+      ['Held edits', count(view.heldNoteCount)],
+      ['Retained edits', count(view.retainedEdits)],
+      ['Pending edits', count(isPlainObject(report.pendingEdits) ? report.pendingEdits.open : null)],
+      ['Service', channel ? `${channel.host === '::1' ? '[::1]' : '127.0.0.1'}:${channel.port}, ${isPlainObject(report.service) && typeof report.service.status === 'string' ? report.service.status : 'no answer'}` : 'not set up'],
+      ['Plugin', String(this.manifest.version)],
+      ['Obsidian', this.appVersion || 'unknown'],
+    ]
+  }
+
+  showStatus() {
+    new AtelierStatusModal(this.app, this.statusRows()).open()
+  }
+}
+
+AtelierProjectionPlugin.channel = CHANNEL
+module.exports = AtelierProjectionPlugin

package/plugins/obsidian/manifest.json

@@ -0,0 +1,9 @@
+{
+  "id": "atelier-projection",
+  "name": "Atelier",
+  "version": "1.1.1",
+  "minAppVersion": "1.13.7",
+  "description": "Shows whether this Atelier view is current and tells Atelier's maintenance service that the vault is open. Shipped by Atelier into the vaults it manages.",
+  "author": "MNSTRY",
+  "isDesktopOnly": true
+}

package/plugins/obsidian/styles.css

@@ -0,0 +1,22 @@
+/* Atelier's plugin: the status bar item and the status modal. */
+
+.atelier-projection-status-bar {
+  cursor: pointer;
+}
+
+.atelier-projection-status {
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  gap: var(--size-4-1) var(--size-4-4);
+  margin: 0;
+}
+
+.atelier-projection-status dt {
+  color: var(--text-muted);
+}
+
+.atelier-projection-status dd {
+  margin: 0;
+  font-variant-numeric: tabular-nums;
+  overflow-wrap: anywhere;
+}

package/src/commands/obsidian.mjs

@@ -11,12 +11,14 @@ import { isoTime } from '../runtime/obsidian/documents.mjs'
 import { readObsidianEnablement } from '../runtime/obsidian/enablement.mjs'
 import { ObsidianMaintenanceRefusal, refuse } from '../runtime/obsidian/errors.mjs'
 import { BUILT_IN_OPERATIONS, UNAVAILABLE_APPLY_OPERATION, createObsidianRegistry } from '../runtime/obsidian/extension-points.mjs'
-import { LIFECYCLE_PRIMITIVES, readServiceStatusDocument, serviceStatus, startService, stopService } from '../runtime/obsidian/lifecycle.mjs'
+import { LIFECYCLE_PRIMITIVES, readServiceStatusDocument, requestServiceTick, serviceStatus, startService, stopService } from '../runtime/obsidian/lifecycle.mjs'
 import {
   authorizeAutomaticApply, defaultMachineSettings, ensureWorkspaceIdentity, installApplyPolicy, protectedRoots, readInstalledApplyPolicy, readMachineSettings,
   revokeApplyPolicy, writeMachineSettings,
 } from '../runtime/obsidian/machine-settings.mjs'
-import { APPLY_UNAVAILABLE, OPENING_OUTCOMES, OPENING_PRIMITIVES, nextStep, openScopeForOracleTests, resolveScope, scopeReport } from '../runtime/obsidian/opening.mjs'
+import { APPLY_UNAVAILABLE, OPENING_OUTCOMES, OPENING_PRIMITIVES, REASON_NEXT, nextStep, openScopeForOracleTests, resolveScope, scopeReport } from '../runtime/obsidian/opening.mjs'
+import { currentPluginChoice, writePluginChoice } from '../runtime/obsidian/plugin-choice.mjs'
+import { pluginPresenceOf, turnPluginOnNext, withPluginReportedVersion } from '../runtime/obsidian/plugin-presence.mjs'
 import { serviceNameFor, servicePaths } from '../runtime/obsidian/service-record.mjs'
 import { resolveServiceWorkspace } from '../runtime/obsidian/service.mjs'
 import { buildStartupAdapter } from '../runtime/obsidian/startup-adapters.mjs'
@@ -33,7 +35,7 @@ import { buildStartupAdapter } from '../runtime/obsidian/startup-adapters.mjs'
 // that did not start, a stop that was refused).
 //
 // Reaching the installed app or the operating system goes through seams
-// (`appProbe`, `launcher`, `service`). A caller passes them. The production
+// (`appProbe`, `launcher`, `registry`, `service`). A caller passes them. The production
 // seams are constructed only when this module runs as the real command-line
 // entry (`production: true`) AND `--adapter=obsidian-cli` was given, the same
 // explicit rule the service entry has; there is no default.
@@ -58,7 +60,12 @@ export const USAGE = `Usage: atelier obsidian <operation> [--project atelier.pro
   service unit --print --adapter=${PRODUCTION_ADAPTER}
                                        Print an operating-system startup unit. Writes and installs nothing.
   open [--scope ID] [--consent-actor ID] [--allow-stale] --adapter=${PRODUCTION_ADAPTER}
-                                       Start or reconnect maintenance, verify the view, open it in Obsidian.
+                                       Start or reconnect maintenance, verify the view, add it to Obsidian and open it.
+  plugin show [--scope ID]             Whether Atelier's plugin is on in a view's vault, and whether it holds it open.
+  plugin on [--scope ID] [--adapter=${PRODUCTION_ADAPTER}]
+                                       Offer Atelier's plugin again in a vault where it was turned off; a running
+                                       service publishes the view at once (with --adapter, one of an earlier release
+                                       is replaced first).
 
 Contributed operations, registered by the modules shipped under src/runtime/obsidian/contributions/:
   apply list | show EDIT | run EDIT [--actor ID] | recover
@@ -147,11 +154,20 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
       return { entryPath: SERVICE_ENTRY_PATH, entryArgs: [`--adapter=${PRODUCTION_ADAPTER}`] }
     }
     const appSeams = async () => {
-      if (seams !== null) return { appProbe: seams.appProbe, launcher: seams.launcher }
+      if (seams !== null) return { appProbe: seams.appProbe, launcher: seams.launcher, registry: seams.registry }
       if (flags.adapter !== PRODUCTION_ADAPTER) refuse('app-adapter-not-selected', 'no editor adapter was selected; reaching the installed app is never a default')
       const { createProductionAppSeams } = await import('../runtime/obsidian/app-production-seams.mjs')
       return createProductionAppSeams({ env, platform })
     }
+    // Atelier's plugin as the running service sees it, for one view. A vault that turned it off says so from its own list
+    // and the private record too, whether or not the service runs.
+    const pluginView = (running, workspace, scopeId) => {
+      const presence = pluginPresenceOf(running, scopeId)
+      if (presence.present || workspace === null || currentPluginChoice({ ...workspace, scopeId }).state !== 'off') return presence
+      return { present: false, reason: 'turned-off-in-this-vault', next: turnPluginOnNext(scopeId) }
+    }
+    const pluginOf = async (scopeId) => pluginPresenceOf((await readServiceStatusDocument(lifecycle, lifecycleRules)).document, scopeId)
+    const pluginLine = (plugin) => (plugin.present ? `; plugin present (Obsidian ${plugin.appVersion})` : plugin.reason === 'turned-off-in-this-vault' ? '; plugin turned off in this vault' : `; plugin not present (${plugin.reason})`)
 
     const configured = () => {
       const project = loadProject()
@@ -193,7 +209,8 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
           ? enablement.scopes.map(({ scopeId }) => ({ scopeId, outcome: enablement.state === 'disabled' ? 'disabled' : 'not-prepared', reason: enablement.state === 'disabled' ? enablement.reason : 'workspace-not-prepared' }))
           : enablement.scopes.map(({ scopeId }) => {
             const { vaultRoot: _vault, summary: _summary, ...report } = scopeReport({ workspace, scopeId, repositoryRoots: protectedRoots(project), serviceState: service.state, applyAvailable }, openingRules)
-            return enablement.state === 'disabled' ? { ...report, outcome: 'disabled', reason: enablement.reason, next: OPENING_OUTCOMES.disabled.next } : report
+            const plugin = pluginView(running, workspace, scopeId)
+            return enablement.state === 'disabled' ? { ...report, outcome: 'disabled', reason: enablement.reason, next: OPENING_OUTCOMES.disabled.next, plugin } : { ...report, plugin }
           })
         const document = {
           enablement: { state: enablement.state, reason: enablement.reason, defaultScopeId: enablement.defaultScopeId }, workspace: { workspaceId, prepared: workspace !== null },
@@ -208,7 +225,11 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
             `service: ${service.state} (${service.reason ?? 'no reason'})${app ? `; app ${app.outcome} (${app.reason})` : ''}`,
             ...(app?.next ? [`Next for the app: ${app.next}`] : []),
             `apply: ${applyShown.state}`,
-            ...scopes.map((scope) => `view ${scope.scopeId}: ${scope.outcome} (${scope.reason})${scope.pendingEdits?.open ? `; ${scope.pendingEdits.open} pending edit(s), apply ${scope.pendingEdits.apply}` : ''}`),
+            ...scopes.flatMap((scope) => [
+              `view ${scope.scopeId}: ${scope.outcome} (${scope.reason})${scope.pendingEdits?.open ? `; ${scope.pendingEdits.open} pending edit(s), apply ${scope.pendingEdits.apply}` : ''}${scope.plugin ? pluginLine(scope.plugin) : ''}`,
+              ...(scope.plugin?.next ? [`  Next for the plugin: ${scope.plugin.next}`] : []),
+              ...(scope.diagnostics ?? []).map((item) => `  ${item.notePath ?? item.filePath ?? item.assetPath ?? item.nodeId ?? ''}: ${item.code}${item.rule ? ` (${item.rule})` : ''}`),
+            ]),
           ],
         }
       },
@@ -326,12 +347,70 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
 
       async open() {
         const seam = await serviceSeam()
+        const app = await appSeams()
+        const { appProbe } = app
+        // The view whose plugin may report the app version; an unknown one is refused by open itself.
+        const requested = () => { try { return resolveScope(readObsidianEnablement(loadProject()), flags.scope) } catch { return null } }
         const result = await openScopeForOracleTests({
-          ...lifecycle, ...(await appSeams()), service: seam, scopeId: flags.scope, consent, allowStale: flags['allow-stale'] === true, extensions: registry.extensions,
+          ...lifecycle, ...app,
+          appProbe: typeof appProbe?.inspect === 'function' && typeof appProbe?.vaultState === 'function' ? withPluginReportedVersion(appProbe, async () => { const scopeId = requested(); return scopeId === null ? null : pluginOf(scopeId) }) : appProbe,
+          service: seam, scopeId: flags.scope, consent, allowStale: flags['allow-stale'] === true, extensions: registry.extensions,
           ...(flags['wait-ms'] === undefined ? {} : { tickTimeoutMs: Number(flags['wait-ms']) || undefined }), ...(options.open ?? {}),
         }, openingRules, lifecycleRules)
-        const { ok: _ok, ...document } = result
-        return { exit: result.ok ? EXIT.ok : EXIT.notSuccess, document, human: [`${result.outcome}: ${result.summary}${result.reason ? ` (${result.reason})` : ''}`, `Next: ${result.next}`, ...(result.pendingEdits?.open ? [`${result.pendingEdits.open} pending edit(s); apply ${result.pendingEdits.apply}`] : [])] }
+        const { ok: _ok, ...opened } = result
+        const plugin = typeof result.scopeId === 'string' ? await pluginOf(result.scopeId) : null
+        const document = plugin === null ? opened : { ...opened, plugin }
+        return {
+          exit: result.ok ? EXIT.ok : EXIT.notSuccess, document,
+          human: [`${result.outcome}: ${result.summary}${result.reason ? ` (${result.reason})` : ''}${plugin ? pluginLine(plugin) : ''}`, `Next: ${result.next}`, ...(result.service?.restarted ? [`service: restarted (${result.service.restarted})`] : []), ...(result.duplicates ? [`open in Obsidian as: ${result.duplicates.map((entry) => entry.path).join(', ')}`] : []), ...(result.pendingEdits?.open ? [`${result.pendingEdits.open} pending edit(s); apply ${result.pendingEdits.apply}`] : [])],
+        }
+      },
+
+      // Atelier's plugin in the vault of a view: the person's choice (as recorded, or as the vault shows it before the next
+      // publication records it), and whether a plugin holds the vault open. `on` records a request and asks a running
+      // maintenance service for a tick that names the view, whose publication brings the entry and the plugin files back;
+      // with no service running, the view's next publication does.
+      async plugin() {
+        if (sub !== undefined && sub !== 'show' && sub !== 'on') refuse('usage', 'plugin show [--scope ID] | plugin on [--scope ID]')
+        if (sub === 'on') {
+          const { enablement, workspace } = writable()
+          const scopeId = resolveScope(enablement, flags.scope)
+          const choice = writePluginChoice({ ...workspace, scopeId, state: 'requested', reason: 'requested-by-command', clock })
+          // The request is recorded either way; a service that cannot be asked leaves it to the view's next publication.
+          // With the installed entry to start (`--adapter`), a service of an earlier release still running after an upgrade
+          // is replaced before its tick, under the consent already recorded, as `open` does; without it, it is reported.
+          const replaceable = seams !== null || flags.adapter === PRODUCTION_ADAPTER
+          let asked
+          try { asked = await requestServiceTick({ ...lifecycle, scopeId, ...(replaceable ? { service: await serviceSeam() } : {}) }, lifecycleRules) } catch (error) { if (!isTyped(error)) throw error; asked = { requested: false, reason: error.code } }
+          const view = asked.tick?.scopes?.find((scope) => scope.scopeId === scopeId) ?? null
+          const takesEffect = view?.state === 'current' ? 'published' : asked.pending === true || view?.state === 'updating' ? 'publishing' : 'next-publication'
+          const service = {
+            asked: asked.requested === true, reason: asked.reason ?? asked.state ?? null, ...(asked.restarted ? { restarted: asked.restarted } : {}),
+            ...(view === null ? {} : { view: { state: view.state, reason: view.reason } }),
+          }
+          const human = takesEffect === 'published'
+            ? `view ${scopeId}: Atelier's plugin is requested and back: the maintenance service published the view again with its entry and its files; Obsidian runs it from the next time it opens the vault`
+            : takesEffect === 'publishing'
+              ? `view ${scopeId}: Atelier's plugin is requested; the maintenance service is publishing the view again, which brings its entry and its files back`
+              : `view ${scopeId}: Atelier's plugin is requested; its entry and its files come back with the view's next publication (the next change at its sources, or when the maintenance service next starts)${service.asked ? ` (the service's tick: ${view ? `${view.state}, ${view.reason}` : service.reason})` : ''}`
+          // A service this command could not ask: one of an earlier release it may replace (with `--adapter`), and one of a
+          // later release it never replaces, which gets open's next step.
+          const next = service.reason === 'service-outdated'
+            ? `the running maintenance service is of an earlier release; run \`atelier obsidian plugin on --scope ${scopeId} --adapter=${PRODUCTION_ADAPTER}\` to replace it`
+            : service.reason === 'service-other-release' ? REASON_NEXT['service-other-release'] : null
+          return { exit: EXIT.ok, document: { scopeId, choice, takesEffect, service, ...(next === null ? {} : { next }) }, human: [human, ...(service.restarted ? [`service: restarted (${service.restarted})`] : []), ...(next === null ? [] : [`  Next: ${next}`])] }
+        }
+        const { enablement, workspace } = readable()
+        const scopeIds = flags.scope === undefined ? enablement.scopes.map((scope) => scope.scopeId) : [resolveScope(enablement, flags.scope)]
+        const service = enablement.reason === 'not-configured' ? { state: 'stopped' } : await serviceStatus(lifecycle, lifecycleRules)
+        const running = service.state === 'healthy' ? (await readServiceStatusDocument(lifecycle, lifecycleRules)).document : null
+        const plugins = scopeIds.map((scopeId) => ({
+          scopeId, choice: workspace === null ? { state: 'undecided', reason: null, since: null } : currentPluginChoice({ ...workspace, scopeId }), presence: pluginView(running, workspace, scopeId),
+        }))
+        return {
+          exit: EXIT.ok, document: { plugins },
+          human: plugins.flatMap(({ scopeId, choice, presence }) => [`view ${scopeId}: plugin ${choice.state}${choice.pending ? ' (as the vault shows it; recorded at the view\'s next publication)' : ''}${pluginLine(presence)}`, ...(presence.next ? [`  Next: ${presence.next}`] : [])]),
+        }
       },
 
       // The placeholder that answers when no contribution registered an apply operation; the shipped source-apply contribution replaces it.