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

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

@@ -0,0 +1,138 @@
+import { refuse } from './errors.mjs'
+
+// Whether the installed Obsidian may be published through and opened.
+//
+// Nothing here looks at this machine. What is installed is learned through an
+// injected `appProbe`:
+//
+//   appProbe.inspect()                 -> { installed, cli, running, version, noVaultOpen? }
+//   appProbe.vaultState({ vaultRoot }) -> { answered, indexReady }
+//
+// `installed` and `cli` are booleans, `running` is true, false or null (not
+// known) and `version` is the app's own version text or null. `noVaultOpen`
+// is true when the command-line tool answered that no vault is open. The
+// production probe is a separate module that only the real command-line
+// entries load; every test passes its own.
+
+// The publication protocol sets the view's undocumented `lastSavedData` field.
+// 1.13.7 is the only app version that protocol was proven on, so it is the
+// floor. Raising the ceiling needs the protocol cases re-run on that release.
+export const MINIMUM_APP_VERSION = '1.13.7'
+
+export const APP_OUTCOMES = Object.freeze(['qualified', 'app-missing', 'app-cli-unavailable', 'app-version-unsupported'])
+
+const VERSION = /^v?(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})(?:-([0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*))?(?:\+[0-9A-Za-z.-]+)?(?=$|[\s(])/
+
+// { major, minor, patch, prerelease: string[] } or null. Only a version at the
+// very start of the text counts; anything else is not a version.
+export function parseAppVersion(text) {
+  if (typeof text !== 'string' || text.length > 200) return null
+  const match = VERSION.exec(text.trim())
+  if (!match) return null
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]), prerelease: match[4] === undefined ? [] : match[4].split('.') }
+}
+
+function comparePrerelease(left, right) {
+  // No prerelease ranks above any prerelease of the same version.
+  if (left.length === 0 || right.length === 0) return left.length === right.length ? 0 : left.length === 0 ? 1 : -1
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    if (left[index] === undefined) return -1
+    if (right[index] === undefined) return 1
+    const [a, b] = [left[index], right[index]]
+    const [aNumeric, bNumeric] = [/^\d+$/.test(a), /^\d+$/.test(b)]
+    if (aNumeric && bNumeric) { if (Number(a) !== Number(b)) return Number(a) < Number(b) ? -1 : 1 } else if (aNumeric !== bNumeric) return aNumeric ? -1 : 1
+    else if (a !== b) return a < b ? -1 : 1
+  }
+  return 0
+}
+
+// Pure. -1, 0 or 1; null when either side is not a version.
+export function compareAppVersions(left, right) {
+  const [a, b] = [parseAppVersion(left), parseAppVersion(right)]
+  if (a === null || b === null) return null
+  for (const part of ['major', 'minor', 'patch']) if (a[part] !== b[part]) return a[part] < b[part] ? -1 : 1
+  return comparePrerelease(a.prerelease, b.prerelease)
+}
+
+// Pure. A version that cannot be read does not meet the floor.
+export function meetsMinimumAppVersion(version, floor = MINIMUM_APP_VERSION) {
+  const order = compareAppVersions(version, floor)
+  return order !== null && order >= 0
+}
+
+// While the app runs with no vault open, its command-line tool answers every
+// command, `version` too, with this line (observed on 1.13.7, on either output
+// stream and with either exit status). It is not a version.
+const NO_VAULT_OPEN = /^vault not found\.?$/i
+
+// Pure. What one `version` call of the command-line tool answered:
+// { version, noVaultOpen }. `exited` is false for a call that failed or exited
+// non-zero; its output is then read for the no-vault answer, never for a version.
+export function readVersionAnswer({ stdout = '', stderr = '', exited = true } = {}) {
+  const lines = [stdout, stderr].flatMap((text) => (typeof text === 'string' ? text.split('\n') : [])).map((line) => line.trim())
+  if (lines.some((line) => NO_VAULT_OPEN.test(line))) return { version: null, noVaultOpen: true }
+  const text = typeof stdout === 'string' ? stdout.trim() : ''
+  return { version: exited && text !== '' ? text : null, noVaultOpen: false }
+}
+
+// Pure. `requireVersion: false` lets an installed app that is positively not
+// running pass without a version: nothing is published through an app that
+// does not run, and the version is asked for again once it does. An app whose
+// command-line tool says no vault is open runs, whatever the process table
+// said, and answers nothing else: `no-vault-open`, which does not qualify.
+export function qualifyApp(observation, { requireVersion = true, floor = MINIMUM_APP_VERSION } = {}) {
+  const seen = observation !== null && typeof observation === 'object' ? observation : {}
+  const base = { floor, version: typeof seen.version === 'string' ? seen.version.slice(0, 80) : null, running: seen.running === true ? true : seen.running === false ? false : null }
+  if (seen.installed !== true) return { ...base, outcome: 'app-missing', reason: 'no-app-found' }
+  if (seen.cli !== true) return { ...base, outcome: 'app-cli-unavailable', reason: 'cli-capability-absent' }
+  if (seen.noVaultOpen === true) return { ...base, outcome: 'app-version-unsupported', reason: 'no-vault-open' }
+  if (base.version === null) {
+    if (!requireVersion && base.running === false) return { ...base, outcome: 'qualified', reason: 'app-not-running-version-not-needed', versionChecked: false }
+    return { ...base, outcome: 'app-version-unsupported', reason: 'version-unknown' }
+  }
+  if (parseAppVersion(base.version) === null) return { ...base, outcome: 'app-version-unsupported', reason: 'version-unreadable' }
+  if (!meetsMinimumAppVersion(base.version, floor)) return { ...base, outcome: 'app-version-unsupported', reason: 'below-minimum-version' }
+  return { ...base, outcome: 'qualified', reason: 'meets-minimum-version', versionChecked: true }
+}
+
+export async function inspectApp(appProbe) {
+  if (typeof appProbe?.inspect !== 'function') throw new TypeError('an appProbe with inspect() is required')
+  try { return await appProbe.inspect() } catch { return { installed: false, cli: false, running: null, version: null } }
+}
+
+// The adapter factory of a service that reaches a real app. The editor adapter
+// is constructed only after the app qualified; otherwise the factory refuses,
+// typed, and the engine records that reason and publishes nothing. The answer
+// is remembered briefly so a tick over many views asks once, unless it let an
+// adapter through without a checked version. `createAdapter` receives the
+// qualification with its input: an app that was not running qualified without
+// a version, and an adapter built on that answer must not coordinate with an
+// app started since (see createEditorAdapter).
+export function createQualifiedAdapterFactory({ appProbe, createAdapter, floor = MINIMUM_APP_VERSION, maxAgeMs = 10_000, now = () => Date.now() } = {}) {
+  if (typeof appProbe?.inspectSync !== 'function') throw new TypeError('the qualified adapter factory needs an appProbe with inspectSync()')
+  if (typeof createAdapter !== 'function') throw new TypeError('the qualified adapter factory needs createAdapter')
+  let last = null
+  // An answer that lets an adapter through without a checked version (no app
+  // was running, or none was found) is never reused: an app started since is
+  // asked for its version by the next call, not refused on the old answer. An
+  // answer that checked a version, or that refuses, is reused for `maxAgeMs`.
+  const reusable = (result) => result.versionChecked === true || (result.outcome !== 'qualified' && result.outcome !== 'app-missing')
+  const qualification = () => {
+    if (last === null || !reusable(last.result) || now() - last.at > maxAgeMs) {
+      let observation
+      try { observation = appProbe.inspectSync() } catch { observation = null }
+      last = { at: now(), result: qualifyApp(observation, { requireVersion: false, floor }) }
+    }
+    return last.result
+  }
+  const factory = (input) => {
+    const result = qualification()
+    // No app at all is not an unqualified app: the publisher's own path needs none, and its adapter finds no process.
+    if (result.outcome !== 'qualified' && result.outcome !== 'app-missing') refuse(result.outcome, 'the installed Obsidian does not qualify; nothing is published through it', { reason: result.reason, floor: result.floor, version: result.version })
+    return createAdapter({ ...input, qualification: result })
+  }
+  factory.qualification = qualification
+  // What was last learned, without asking again: for a status answer.
+  factory.lastQualification = () => last?.result ?? null
+  return factory
+}

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

@@ -0,0 +1,107 @@
+import { execFile, spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { defaultCliPath, defaultObsidianProcessProbe } from '../../projection/obsidian/publication/transport.mjs'
+import { readVersionAnswer } from './app-capability.mjs'
+
+// The production seams of `obsidian open` and of the service's adapter
+// factory: the only code that asks the installed Obsidian anything or asks the
+// operating system to open it.
+//
+// This module is imported by exactly two places, both real command-line
+// entries and both behind an explicit `--adapter=obsidian-cli`: the service
+// entry (service-main.mjs) and the command entry (src/commands/obsidian.mjs,
+// `production: true`). No test imports it in-process, and importing it leaves
+// a trace below that the test suite asserts is absent. One test imports it in
+// a child process, with a stand-in for the command-line tool, to read the
+// version answers it parses.
+//
+// Status: written against the documented command-line interface and NOT yet
+// exercised against a running app. The acceptance work qualifies it on an
+// isolated host before any of it is relied on; until then every answer it
+// cannot establish is the failing one.
+globalThis[Symbol.for('mnstry.atelier.obsidian.production-seams-loaded')] = true
+
+const CLI_TIMEOUT_MS = 5000
+
+function installedAppPath(platform) {
+  if (platform === 'darwin') return '/Applications/Obsidian.app'
+  return null
+}
+
+function cliExists(cliPath) {
+  if (!path.isAbsolute(cliPath)) return null // found through PATH or not at all: only running it tells
+  try { return fs.statSync(cliPath).isFile() } catch { return false }
+}
+
+const NOT_ASKED = Object.freeze({ version: null, noVaultOpen: false })
+
+const observationOf = ({ platform, cliPath, processes, answer }) => {
+  const appPath = installedAppPath(platform)
+  const present = cliExists(cliPath)
+  const answered = answer.version !== null || answer.noVaultOpen
+  return {
+    installed: appPath === null ? (present !== false && (answered || present === true)) : fs.existsSync(appPath),
+    cli: present === true || answered,
+    running: processes === 'running' ? true : processes === 'absent' ? false : null,
+    version: answer.version,
+    ...(answer.noVaultOpen ? { noVaultOpen: true } : {}),
+  }
+}
+
+export function createProductionAppProbe({ platform = process.platform, env = process.env, cliPath = defaultCliPath(platform) } = {}) {
+  const options = { env, timeout: CLI_TIMEOUT_MS, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 1024 * 1024 }
+  return {
+    // For the service's adapter factory, which is synchronous. The version is asked for only while an app runs.
+    // Both output streams are read, whatever the exit status: the answer with no vault open is not a version.
+    inspectSync() {
+      const processes = defaultObsidianProcessProbe({ platform })
+      if (processes === 'absent') return observationOf({ platform, cliPath, processes, answer: NOT_ASKED })
+      let answer = NOT_ASKED
+      try {
+        const reply = spawnSync(cliPath, ['version'], { ...options, stdio: ['ignore', 'pipe', 'pipe'] })
+        answer = readVersionAnswer({ stdout: reply.stdout, stderr: reply.stderr, exited: reply.error === undefined && reply.status === 0 })
+      } catch { answer = NOT_ASKED }
+      return observationOf({ platform, cliPath, processes, answer })
+    },
+    inspect() {
+      const processes = defaultObsidianProcessProbe({ platform })
+      if (processes === 'absent') return Promise.resolve(observationOf({ platform, cliPath, processes, answer: NOT_ASKED }))
+      return new Promise((resolve) => {
+        execFile(cliPath, ['version'], options, (error, stdout, stderr) => resolve(observationOf({ platform, cliPath, processes, answer: readVersionAnswer({ stdout, stderr, exited: !error }) })))
+      })
+    },
+    // Whether the app answers for exactly this vault and has finished reading it.
+    vaultState({ vaultRoot }) {
+      const code = '(()=>JSON.stringify({basePath:app.vault.adapter.basePath,ready:app.metadataCache.initialized===true}))()'
+      return new Promise((resolve) => {
+        execFile(cliPath, ['eval', `code=${code}`], options, (error, stdout) => {
+          if (error) return resolve({ answered: false, indexReady: false })
+          try {
+            const text = String(stdout)
+            const value = JSON.parse(JSON.parse(text.slice(text.indexOf('=> ') + 3)))
+            return resolve({ answered: value.basePath === vaultRoot, indexReady: value.basePath === vaultRoot && value.ready === true })
+          } catch { return resolve({ answered: false, indexReady: false }) }
+        })
+      })
+    },
+  }
+}
+
+// Asks the operating system to open the vault in Obsidian. No shell.
+export function createProductionLauncher({ platform = process.platform, env = process.env } = {}) {
+  const command = platform === 'darwin' ? '/usr/bin/open' : platform === 'linux' ? 'xdg-open' : null
+  return {
+    open({ vaultRoot }) {
+      if (command === null) return Promise.resolve({ launched: false, reason: 'launcher-platform-unqualified' })
+      const uri = `obsidian://open?path=${encodeURIComponent(vaultRoot)}`
+      return new Promise((resolve) => {
+        execFile(command, [uri], { env, timeout: 15_000 }, (error) => resolve(error ? { launched: false, reason: 'os-open-failed' } : { launched: true, reason: 'os-open-accepted' }))
+      })
+    },
+  }
+}
+
+export function createProductionAppSeams(options = {}) {
+  return { appProbe: createProductionAppProbe(options), launcher: createProductionLauncher(options) }
+}

package/src/runtime/obsidian/contributions/proposal-adapter.mjs

@@ -0,0 +1,4 @@
+import { createProposalAdapterContribution } from '../../../projection/obsidian/proposals/contribution.mjs'
+
+// The proposal adapter: what the engine hands structural edits to on a tick, and `atelier obsidian proposals`.
+export default createProposalAdapterContribution()

package/src/runtime/obsidian/contributions/selection-ui.mjs

@@ -0,0 +1,4 @@
+import { createSelectionContribution } from '../../../projection/obsidian/selection-ui/contribution.mjs'
+
+// The selection, conflict and apply-policy operations: `atelier obsidian selection`, `conflicts` and `apply-policy`.
+export default createSelectionContribution()

package/src/runtime/obsidian/contributions/source-apply.mjs

@@ -0,0 +1,4 @@
+import { createSourceApplyContribution } from '../../../projection/obsidian/edits/contribution.mjs'
+
+// The source apply operation: what the engine dispatches to in automatic mode, and `atelier obsidian apply`.
+export default createSourceApplyContribution()

package/src/runtime/obsidian/contributions.mjs

@@ -0,0 +1,27 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { refuse } from './errors.mjs'
+
+// Where later work plugs in without touching a shared file: every module in
+// `contributions/` beside this file is a contribution. Its default export is
+// `{ id, register({ extensions, operations }) }`. The command and the service
+// entry both load the directory, so an apply operation registered there is
+// the one the service dispatches to and the one `status` reports.
+//
+// Only regular `.mjs` files directly in that directory are loaded, in name
+// order. The directory ships with the package; nothing outside it is read.
+
+export const CONTRIBUTIONS_DIRECTORY = path.join(path.dirname(fileURLToPath(import.meta.url)), 'contributions')
+
+export async function loadContributions({ directory = CONTRIBUTIONS_DIRECTORY } = {}) {
+  let entries
+  try { entries = fs.readdirSync(directory, { withFileTypes: true }) } catch (error) { if (error.code === 'ENOENT') return []; throw error }
+  const contributions = []
+  for (const entry of entries.filter((item) => item.isFile() && item.name.endsWith('.mjs')).sort((left, right) => (left.name < right.name ? -1 : 1))) {
+    const loaded = await import(pathToFileURL(path.join(directory, entry.name)).href)
+    if (loaded.default === null || typeof loaded.default !== 'object' || typeof loaded.default.register !== 'function') refuse('invalid-extension', 'a contribution module must export { id, register } by default', { file: entry.name })
+    contributions.push(loaded.default)
+  }
+  return contributions
+}

package/src/runtime/obsidian/documents.mjs

@@ -0,0 +1,37 @@
+import { refuse } from './errors.mjs'
+
+// Helpers shared by this module's private documents. Each document is
+// versioned by its `schema` string, closed (an unknown key refuses) and
+// written in one canonical form, so equal state is equal bytes.
+
+export const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys)
+  if (!isPlainObject(value)) return value
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortKeys(value[key])]))
+}
+
+// Keys sorted at every depth, two-space indentation, one final newline.
+export function canonicalJson(value) {
+  return `${JSON.stringify(sortKeys(value), null, 2)}\n`
+}
+
+export function closedObject(value, { required = [], optional = [] }, code, label) {
+  if (!isPlainObject(value)) refuse(code, `${label} must be an object`)
+  const allowed = new Set([...required, ...optional])
+  const unknown = Object.keys(value).filter((key) => !allowed.has(key))
+  if (unknown.length > 0) refuse(code, `${label} carries an unknown key`, { keys: unknown.sort() })
+  const missing = required.filter((key) => !Object.hasOwn(value, key))
+  if (missing.length > 0) refuse(code, `${label} lacks a required key`, { keys: missing })
+  return value
+}
+
+export const compareText = (left, right) => (left < right ? -1 : left > right ? 1 : 0)
+
+export function isoTime(clock) {
+  const value = clock()
+  const date = value instanceof Date ? value : new Date(value)
+  if (Number.isNaN(date.getTime())) refuse('missing-clock', 'the injected clock did not return a time')
+  return date.toISOString()
+}

package/src/runtime/obsidian/enablement.mjs

@@ -0,0 +1,53 @@
+import { projectExtMember } from '../../project/config.mjs'
+import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal, assertObsidianContract } from '../../projection/obsidian/contracts.mjs'
+import { refuse } from './errors.mjs'
+
+// Typed enablement. The project v1 schema is unchanged: a project without the
+// ext member is valid and means "not configured", which is disabled. A member
+// that is present must satisfy the closed ext-settings contract exactly. An
+// unknown key or value refuses here; it is never ignored and never read as
+// permission, so a newer or mistyped setting cannot switch anything on.
+
+export const ENABLEMENT_STATES = Object.freeze(['disabled', 'enabled'])
+export const DISABLED_REASONS = Object.freeze(['not-configured', 'disabled-in-settings'])
+
+const SCOPE_SCHEMA = 'atelier-obsidian-scope/v1'
+
+function scopeDocument({ scopeId, mode, selector, expansion, ext }) {
+  return {
+    schema: SCOPE_SCHEMA,
+    scopeId,
+    mode,
+    selector,
+    ...(expansion === undefined ? {} : { expansion }),
+    ...(ext === undefined ? {} : { ext }),
+  }
+}
+
+function assertOrRefuse(shape, document, code, message) {
+  try {
+    return assertObsidianContract(shape, document)
+  } catch (error) {
+    if (error instanceof ObsidianContractRefusal) refuse(code, message, { errors: error.detail?.errors ?? [] })
+    throw error
+  }
+}
+
+// Returns a frozen { state, reason, settings, scopes, defaultScopeId }.
+// `scopes` are complete scope contract documents, in declared order, and are
+// listed even when the integration is disabled so a caller can name them.
+export function readObsidianEnablement(project) {
+  const member = projectExtMember(project, OBSIDIAN_EXT_KEY)
+  if (!member.present) {
+    return Object.freeze({ state: 'disabled', reason: 'not-configured', settings: null, scopes: Object.freeze([]), defaultScopeId: null })
+  }
+  const settings = assertOrRefuse('ext-settings', member.value, 'invalid-ext-settings', 'the project Obsidian settings do not satisfy their contract; nothing is enabled')
+  const scopes = settings.scopes.map((scope) => assertOrRefuse('scope', scopeDocument(scope), 'invalid-ext-settings', 'a declared scope does not satisfy the scope contract; nothing is enabled'))
+  return Object.freeze({
+    state: settings.enabled === true ? 'enabled' : 'disabled',
+    reason: settings.enabled === true ? 'enabled' : 'disabled-in-settings',
+    settings,
+    scopes: Object.freeze(scopes),
+    defaultScopeId: settings.defaultScopeId ?? null,
+  })
+}