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

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

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { atomicReplacePrivateText, ensureContainedPrivateDirectory, openRegularFileNoFollow, readRegularTextNoFollow } from '../../project/private-state.mjs'
 import { ObsidianContractRefusal, assertObsidianContract } from '../../projection/obsidian/contracts.mjs'
 import { canonicalJson, closedObject } from './documents.mjs'
@@ -60,6 +61,41 @@ export function executableIdentity(entryPath) {
   return { path: resolved, digest: `sha256:${createHash('sha256').update(fs.readFileSync(resolved)).digest('hex')}` }
 }
 
+// The package this module ships in.
+const PACKAGE_ROOT = fileURLToPath(new URL('../../../', import.meta.url))
+const byName = (left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0)
+const releases = new Map()
+
+// The release that runs, beyond its entry module: the version of the package
+// and a digest of the runtime it ships, by relative path and content. That is
+// what the service loads: every module under `src/`, the `contracts/` it
+// reads, and the plugin under `plugins/` it publishes into every vault it
+// maintains; outside those it reads nothing else of the package but the
+// version in `package.json`. A release that changes any of it, and not only
+// the entry, differs. A package without `plugins/` reads as one with an empty
+// one. Computed once per process and package root, so a service keeps the
+// identity of the code it loaded.
+export function releaseIdentity({ root = PACKAGE_ROOT } = {}) {
+  if (!releases.has(root)) {
+    const hash = createHash('sha256')
+    const walk = (relative, { optional = false } = {}) => {
+      let entries
+      try { entries = fs.readdirSync(path.join(root, relative), { withFileTypes: true }) } catch (error) { if (optional && error.code === 'ENOENT') return; throw error }
+      for (const entry of entries.sort(byName)) {
+        const child = `${relative}/${entry.name}`
+        if (entry.isDirectory()) walk(child)
+        else if (entry.isFile()) hash.update(`${child}\0${createHash('sha256').update(fs.readFileSync(path.join(root, child))).digest('hex')}\n`)
+      }
+    }
+    for (const part of ['src', 'contracts']) walk(part)
+    walk('plugins', { optional: true })
+    let version = null
+    try { const read = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version; version = typeof read === 'string' ? read : null } catch { version = null }
+    releases.set(root, Object.freeze({ version, digest: `sha256:${hash.digest('hex')}` }))
+  }
+  return releases.get(root)
+}
+
 // ---------------------------------------------------------------------------
 // The adapter record
 // ---------------------------------------------------------------------------

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

@@ -1,31 +1,50 @@
 import { createHash, timingSafeEqual } from 'node:crypto'
 import http from 'node:http'
+import { isContractIdentifier } from '../../projection/obsidian/contracts.mjs'
+import { PLUGIN_MAX_REQUEST_BYTES, pluginCommandOf, validatePluginRequest } from '../../projection/obsidian/plugin-bridge/channel.mjs'
 import { requestHeader, sameOrigin } from '../../server/security.mjs'
 import { isPlainObject } from './documents.mjs'
 import { HEALTH_SCHEMA, LOOPBACK_HOSTS, authorityOf } from './service-client.mjs'
 
-// The listener of the maintenance service: four fixed operations and nothing
-// else. There is no file serving, no command, no evaluation and no route that
-// takes a path, a name or code from a request.
+// The listener of the maintenance service: four fixed operations, the five
+// fixed commands of Atelier's plugin, and nothing else. There is no file
+// serving, no command, no evaluation and no route that takes a path, a name or
+// code from a request.
 //
 //   GET  /health   who answers here; open, and says nothing else
 //   GET  /status   service and per-view freshness summary; bearer required
 //   POST /tick     run one tick now; bearer required
 //   POST /stop     finish the tick in flight and exit; bearer required
 //
+//   POST /plugin/challenge | /plugin/hello | /plugin/lease | /plugin/release |
+//        /plugin/status
+//                  Atelier's plugin inside one vault, authenticated by a
+//                  handshake over that vault's key (plugin-bridge/channel.mjs)
+//
 // Every request, before its operation is even looked up:
 //
 //   - `Host` is exactly the literal loopback authority this listener is bound
 //     to, so a name that resolves to loopback (DNS rebinding) is refused;
 //   - a `Sec-Fetch-Site` other than `none` or `same-origin`, or an `Origin`
 //     that is not this listener itself, is refused: no web page drives this;
-//   - the path is one of the four, exactly, with no query; the method is the
+//   - the path is one of the nine, exactly, with no query; the method is the
 //     one that path has.
 //
-// Everything but health needs the per-runtime random bearer that exists only
-// in the owner-only record. A POST body is JSON of at most 1 KiB naming the
-// runtime it is meant for, so a request aimed at an earlier runtime on the
-// same port does nothing.
+// Everything but health and the plugin's commands needs the per-runtime
+// random bearer that exists only in the owner-only record. A POST body is JSON
+// of at most 1 KiB naming the runtime it is meant for, so a request aimed at an
+// earlier runtime on the same port does nothing (409). A tick may also name one
+// view (`scopeId`, a contract identifier), which is then prepared and published
+// once more on that tick; any other member is refused (400,
+// `request-member-unknown`).
+//
+// A plugin command carries no bearer: the plugin never sends its vault's key.
+// Its body, JSON of at most 1 KiB with exactly the fields of its command, is
+// judged by the plugin channel (plugin-channel.mjs): a challenge the service
+// answers only for a key it holds, a hello that proves the same key, and
+// session commands under the key the handshake derived. What it grants is
+// these commands for that one vault. The runtime bearer is not accepted there,
+// and nothing a plugin holds reaches status, tick or stop.
 
 export const MAX_REQUEST_BYTES = 1024
 export const SERVICE_OPERATIONS = Object.freeze({ '/health': 'GET', '/status': 'GET', '/tick': 'POST', '/stop': 'POST' })
@@ -35,6 +54,7 @@ const digestOf = (value) => createHash('sha256').update(String(value)).digest()
 // The decisions the request oracles are sensitive to; tests substitute broken ones to prove the oracles can fail.
 export const SERVER_PRIMITIVES = Object.freeze({
   bearerMatches: (presented, expected) => typeof presented === 'string' && presented !== '' && timingSafeEqual(digestOf(presented), digestOf(expected)),
+  maxPluginRequestBytes: PLUGIN_MAX_REQUEST_BYTES,
   hostMatches: (header, authority) => header === authority,
   originAllowed(headers, authority) {
     const site = requestHeader(headers, 'sec-fetch-site').toLowerCase()
@@ -73,7 +93,9 @@ function readBoundedJson(request, limit) {
 }
 
 // identity: { serviceName, workspaceId, runtimeId, pid, host, port, executableDigest, startedAt }
-// operations: { healthStatus(), status(), tick(), stop() }
+// operations: { healthStatus(), status(), tick(), stop() }, and, where the
+// service holds the plugin channel, { plugin(command, { body, authority }) ->
+// { statusCode, body } }
 export function createServiceServerForOracleTests({ identity, bearer, operations }, primitives = SERVER_PRIMITIVES) {
   if (!LOOPBACK_HOSTS.includes(identity?.host)) throw new TypeError('the service listens on a literal loopback address only')
   if (typeof bearer !== 'string' || bearer.length < 32) throw new TypeError('the service needs its random bearer')
@@ -83,6 +105,19 @@ export function createServiceServerForOracleTests({ identity, bearer, operations
     const authority = authorityOf(identity.host, identity.port)
     if (!rules.hostMatches(requestHeader(request.headers, 'host'), authority)) return send(response, 403, { error: 'host-not-this-loopback-listener' })
     if (!rules.originAllowed(request.headers, authority)) return send(response, 403, { error: 'cross-site-request' })
+    const presented = /^Bearer ([A-Za-z0-9_-]+)$/.exec(requestHeader(request.headers, 'authorization'))?.[1] ?? null
+    const command = typeof operations.plugin === 'function' ? pluginCommandOf(request.url) : null
+    if (command !== null) {
+      if (request.method !== 'POST') return send(response, 405, { error: 'method-not-allowed' })
+      // No credential travels in a header here: a request that sends one was not made by the plugin.
+      if (requestHeader(request.headers, 'authorization') !== '') return send(response, 400, { error: 'plugin-command-takes-no-bearer' })
+      const payload = await readBoundedJson(request, rules.maxPluginRequestBytes)
+      if (!payload.ok) return send(response, payload.statusCode, { error: payload.code })
+      const checked = validatePluginRequest(command, payload.body)
+      if (!checked.ok) return send(response, checked.code === 'protocol-unsupported' ? 409 : 400, { error: checked.code })
+      const answer = await operations.plugin(command, { body: checked.body, authority })
+      return send(response, answer.statusCode, answer.body)
+    }
     const method = Object.hasOwn(SERVICE_OPERATIONS, request.url) ? SERVICE_OPERATIONS[request.url] : null
     if (method === null) return send(response, 404, { error: 'unknown-operation' })
     if (request.method !== method) return send(response, 405, { error: 'method-not-allowed' })
@@ -90,13 +125,16 @@ export function createServiceServerForOracleTests({ identity, bearer, operations
       const { serviceName, workspaceId, runtimeId, pid, host, port, executableDigest, startedAt } = identity
       return send(response, 200, { schema: HEALTH_SCHEMA, serviceName, workspaceId, runtimeId, pid, host, port, executableDigest, startedAt, status: operations.healthStatus() })
     }
-    const presented = /^Bearer ([A-Za-z0-9_-]+)$/.exec(requestHeader(request.headers, 'authorization'))?.[1] ?? null
     if (!rules.bearerMatches(presented, bearer)) return send(response, 401, { error: 'bearer-required' })
     if (request.url === '/status') return send(response, 200, await operations.status())
     const payload = await readBoundedJson(request, rules.maxRequestBytes)
     if (!payload.ok) return send(response, payload.statusCode, { error: payload.code })
-    if (Object.keys(payload.body).length !== 1 || payload.body.runtimeId !== identity.runtimeId) return send(response, 409, { error: 'request-names-another-runtime' })
-    if (request.url === '/tick') return send(response, 200, await operations.tick())
+    const { runtimeId, scopeId, ...unknown } = payload.body
+    if (runtimeId !== identity.runtimeId) return send(response, 409, { error: 'request-names-another-runtime' })
+    // A member the operation does not take: a view on a stop, or anything else.
+    if (Object.keys(unknown).length > 0 || (scopeId !== undefined && request.url !== '/tick')) return send(response, 400, { error: 'request-member-unknown' })
+    if (scopeId !== undefined && !isContractIdentifier(scopeId)) return send(response, 400, { error: 'request-invalid' })
+    if (request.url === '/tick') return send(response, 200, await operations.tick(scopeId === undefined ? {} : { scopeId }))
     // The answer leaves first; the service then finishes its tick and exits.
     response.once('finish', () => { void operations.stop() })
     return send(response, 202, { stopping: true, runtimeId: identity.runtimeId, pid: identity.pid })

package/src/runtime/obsidian/service.mjs

@@ -2,18 +2,24 @@ import { randomBytes as cryptoRandomBytes } from 'node:crypto'
 import fs from 'node:fs'
 import { AtelierDiagnosticError } from '../../project/config.mjs'
 import { ObsidianContractRefusal } from '../../projection/obsidian/contracts.mjs'
+import { prepareView as productionPrepareView } from '../../projection/obsidian/materialize/index.mjs'
+import { preparePluginFiles } from '../../projection/obsidian/plugin-bridge/bundle.mjs'
+import { publishView as productionPublishView } from '../../projection/obsidian/publication/publisher.mjs'
 import { isoTime } from './documents.mjs'
 import { createMaintenanceEngine } from './engine.mjs'
 import { ObsidianMaintenanceRefusal, refuse } from './errors.mjs'
 import { assertOutsideRepositories, protectedRoots, readLocalPointer, resolveDataRoot, workspaceStateRoot } from './machine-settings.mjs'
+import { createPluginChannel, createPluginSessions, ensurePluginBearer, pluginPresence } from './plugin-channel.mjs'
+import { confirmPluginEntry, confirmPluginSeen, currentPluginChoice, decidePluginChoice, vaultFilePresent, viewVaultRoot } from './plugin-choice.mjs'
+import { createPluginDriftObserver } from './plugin-drift.mjs'
 import { isProcessAlive } from './private-lock.mjs'
 import { probeHealth } from './service-client.mjs'
 import {
-  SERVICE_ERROR_SCHEMA, executableIdentity, readLastServiceError, readServiceRecord, readServiceSettings, removeServiceRecord, serviceNameFor, servicePaths,
+  SERVICE_ERROR_SCHEMA, executableIdentity, readLastServiceError, readServiceRecord, readServiceSettings, releaseIdentity, removeServiceRecord, serviceNameFor, servicePaths,
   writeLastServiceError, writeServiceRecord,
 } from './service-record.mjs'
 import { createServiceServer } from './service-server.mjs'
-import { createMaintenanceStateStore } from './state-store.mjs'
+import { OPEN_EDIT_STATES, createMaintenanceStateStore } from './state-store.mjs'
 import { DEFAULT_MAX_BACKOFF_MS, DEFAULT_TICK_INTERVAL_MS, createTickLoop } from './tick-loop.mjs'
 import { createFsWatcherFactory } from './watchers.mjs'
 
@@ -33,6 +39,13 @@ import { createFsWatcherFactory } from './watchers.mjs'
 // publication that was cut short is settled by the publisher's own restart
 // recovery on a later tick, never by deleting what it left behind.
 //
+// It also holds the plugin channel (plugin-channel.mjs). Every view it
+// prepares carries Atelier's plugin, whose data file names this listener and
+// the view's bearer, unless the person turned the plugin off in that vault
+// (plugin-choice.mjs): then the entry is left alone and only the plugin files
+// that are still there are kept current. A plugin that holds a view open is
+// reported by status and tells the adapter factory the app version it runs in.
+//
 // `adapterFactory` has no default here either: whoever starts the service
 // decides whether it may reach a running app.
 
@@ -98,6 +111,8 @@ export async function runMaintenanceService(options = {}) {
   const identity = { serviceName: serviceNameFor(workspaceId), workspaceId, runtimeId, pid, host, port, executableDigest: executable.digest, startedAt }
   const bearer = randomBytes(32).toString('base64url')
   const stateStore = createMaintenanceStateStore({ workspaceRoot, workspaceId })
+  // Session identities live in memory only and are always random, whatever `randomBytes` the service was given.
+  const pluginSessions = createPluginSessions()
 
   let stopping = false
   let consecutiveFailures = 0
@@ -105,7 +120,49 @@ export async function runMaintenanceService(options = {}) {
   let settleDone
   const done = new Promise((resolve) => { settleDone = resolve })
 
-  const engine = createEngine({ watcherFactory: createFsWatcherFactory(), ...engineOptions, loadProject, dataRoot, adapterFactory, clock, env, platform, lockOwner: { host, port, runtimeId } })
+  // Every prepared view carries the plugin with this listener's address and the view's bearer, as the person's choice
+  // for that vault allows: the choice is read, and recorded when the vault shows it changed, from the community plugin
+  // list as it is now, and those very bytes travel with the view. A bearer or a choice that cannot be kept leaves that
+  // view without the plugin for this tick; the view itself is prepared as ever.
+  const pluginFor = (scopeId) => {
+    try {
+      const vaultRoot = viewVaultRoot(workspaceRoot, scopeId)
+      const { choice, community } = decidePluginChoice({ workspaceRoot, workspaceId, scopeId, vaultRoot, clock })
+      const off = choice.state === 'off'
+      const bearer = ensurePluginBearer({ workspaceRoot, workspaceId, scopeId, randomBytes, clock })
+      if (pluginChannel.bearers().get(scopeId) !== bearer) pluginChannel.bearersChanged()
+      const plugin = preparePluginFiles({ channel: { host, port }, scopeId, bearer, onlyIfPresent: off })
+      // Turned off: the files still there are kept current; a folder the person removed is not made again.
+      const files = off ? plugin.files.filter((file) => vaultFilePresent(vaultRoot, file.path)) : plugin.files
+      const kept = new Set(files.map((file) => file.path))
+      const unreadable = community.file.state === 'unreadable'
+      return {
+        files, ownership: { ...plugin.ownership, files: plugin.ownership.files.filter((entry) => kept.has(entry.path)) },
+        community: off || unreadable ? { entry: 'withheld', reason: off ? 'turned-off-in-this-vault' : 'list-unreadable' } : { entry: 'owned', existing: community.file.bytes },
+      }
+    } catch (error) {
+      log({ at: isoTime(clock), event: 'plugin-not-prepared', code: errorCode(error), name: errorName(error) })
+      return null
+    }
+  }
+  const prepareWithPlugin = (input) => (engineOptions.seams?.prepareView ?? productionPrepareView)({ ...input, plugin: pluginFor(input.scope.scopeId) })
+  // An entry offered to a vault and now in place is confirmed: from then on, a list without it is the person's decision.
+  const publishAndConfirm = async (input) => {
+    const result = await (engineOptions.seams?.publishView ?? productionPublishView)(input)
+    try { confirmPluginEntry({ workspaceRoot, workspaceId, scopeId: input.recoveryStore.scopeId, result, clock }) } catch (error) {
+      log({ at: isoTime(clock), event: 'plugin-entry-not-confirmed', code: errorCode(error), name: errorName(error) })
+    }
+    return result
+  }
+  // The app version a live plugin reports counts as checked for the view it holds open, while one launch of the plugin
+  // alone holds it: with two apps holding the vault, which one the command-line tool reaches is unknown.
+  const pluginReportOf = (scopeId) => { const report = pluginSessions.report(scopeId); return report?.instances === 1 ? report : null }
+  // The engine also asks the factory itself (`forget`, on a tick somebody asked for): the wrapper keeps its methods.
+  const pluginAwareAdapterFactory = Object.assign((input) => adapterFactory({ ...input, pluginReport: typeof input?.scope?.scopeId === 'string' ? pluginReportOf(input.scope.scopeId) : null }), adapterFactory)
+  const engine = createEngine({
+    watcherFactory: createFsWatcherFactory(), ...engineOptions, seams: { ...(engineOptions.seams ?? {}), prepareView: prepareWithPlugin, publishView: publishAndConfirm },
+    loadProject, dataRoot, adapterFactory: pluginAwareAdapterFactory, clock, env, platform, lockOwner: { host, port, runtimeId },
+  })
 
   const recordIsOurs = () => {
     try { const record = readServiceRecord({ workspaceRoot, workspaceId }); return record !== null && record.runtimeId === runtimeId && record.pid === pid } catch { return false }
@@ -128,11 +185,21 @@ export async function runMaintenanceService(options = {}) {
     writeLastServiceError({ workspaceRoot, workspaceId, document: { schema: SERVICE_ERROR_SCHEMA, workspaceId, runtimeId, code: errorCode(outcome.error), name: errorName(outcome.error), at, consecutiveFailures, totalFailures: (previous?.totalFailures ?? 0) + 1, resolvedAt: null } })
   }
 
+  // A plugin file a view's committed generation pins that is not on disk as pinned has the view prepared again, so the
+  // publisher writes it again; a drift is asked about once, not at every tick.
+  const pluginDrift = createPluginDriftObserver({ workspaceRoot, workspaceId })
+  const askForDriftedViews = () => {
+    try { for (const scopeId of pluginDrift.observe([...pluginChannel.bearers().keys()])) engine.requestPreparation(scopeId) } catch (error) {
+      log({ at: isoTime(clock), event: 'plugin-drift-not-read', code: errorCode(error), name: errorName(error) })
+    }
+  }
+
   const loop = createTickLoop({
     intervalMs, maxBackoffMs, onOutcome: recordOutcome,
     async tick() {
       // The service runs only while its record names it: a replaced or removed record ends it, cleanly.
       if (!recordIsOurs()) { void shutdown('record-no-longer-names-this-runtime'); return { state: 'stopping', reason: 'record-no-longer-names-this-runtime' } }
+      askForDriftedViews()
       return engine.tick()
     },
   })
@@ -150,6 +217,26 @@ export async function runMaintenanceService(options = {}) {
   }
 
   const healthStatus = () => (stopping ? 'stopped' : consecutiveFailures > 0 ? 'degraded' : 'healthy')
+
+  // One view as the plugin is told about it: its freshness entry with held notes counted, and its open pending edits.
+  function pluginStatusOf(scopeId) {
+    let entry = null
+    try { entry = stateStore.readFreshness()?.scopes.find((item) => item.scopeId === scopeId) ?? null } catch (error) { if (!isTyped(error)) throw error; return { view: null, pendingEdits: null } }
+    let open = null
+    try { open = stateStore.readPendingEdits().edits.filter((edit) => edit.scopeId === scopeId && OPEN_EDIT_STATES.includes(edit.state)).length } catch (error) { if (!isTyped(error)) throw error }
+    const view = entry === null ? null : {
+      state: entry.state, reason: entry.reason, verified: entry.verified, generationId: entry.generationId, preparedGenerationId: entry.preparedGenerationId,
+      heldNoteCount: entry.heldNotes.length, retainedEdits: entry.retainedEdits, checkedAt: entry.checkedAt,
+    }
+    return { view, pendingEdits: open === null ? null : { open } }
+  }
+  // A plugin that holds a view open shows that its app has the view's entry: an entry only offered so far is confirmed.
+  const pluginSeen = (scopeId) => {
+    try { confirmPluginSeen({ workspaceRoot, workspaceId, scopeId, clock }) } catch (error) {
+      log({ at: isoTime(clock), event: 'plugin-entry-not-confirmed', code: errorCode(error), name: errorName(error) })
+    }
+  }
+  const pluginChannel = createPluginChannel({ workspaceRoot, workspaceId, runtimeId, sessions: pluginSessions, statusOf: pluginStatusOf, serviceStatus: healthStatus, onSessionOpened: pluginSeen })
   const server = createServiceServer({
     identity, bearer,
     operations: {
@@ -158,14 +245,21 @@ export async function runMaintenanceService(options = {}) {
         let lastError = null
         try { lastError = readLastServiceError({ workspaceRoot, workspaceId }) } catch (error) { if (!isTyped(error)) throw error; lastError = { unreadable: error.code } }
         if (lastError?.schema) { const { schema: _schema, workspaceId: _workspace, ...shown } = lastError; lastError = shown }
-        return { schema: SERVICE_STATUS_SCHEMA, service: { ...identity, status: healthStatus() }, loop: loop.state(), lastTick, lastError, freshness: freshnessSummary(), ...(typeof appStatus === 'function' ? { app: appStatus() } : {}) }
+        return {
+          schema: SERVICE_STATUS_SCHEMA, service: { ...identity, status: healthStatus() }, loop: loop.state(), lastTick, lastError, freshness: freshnessSummary(),
+          plugins: pluginPresence({ sessions: pluginSessions, scopeIds: [...pluginChannel.bearers().keys()], entryOf: (scopeId) => currentPluginChoice({ workspaceRoot, workspaceId, scopeId }).state }),
+          ...(typeof appStatus === 'function' ? { app: appStatus() } : {}),
+        }
       },
-      async tick() {
+      // A tick asked for one view (`open` asks for its own) prepares and publishes that view once more.
+      async tick({ scopeId } = {}) {
+        if (scopeId !== undefined) engine.requestPreparation?.(scopeId)
         const outcome = await loop.tickNow()
         if (outcome.stopped) return { ok: false, stopped: true }
         return outcome.ok ? { ok: true, ...summary(outcome.report) } : { ok: false, error: { code: errorCode(outcome.error), name: errorName(outcome.error) } }
       },
       stop: () => shutdown('stop-requested'),
+      plugin: (command, request) => pluginChannel.handle(command, request),
     },
   })
 
@@ -202,7 +296,7 @@ export async function runMaintenanceService(options = {}) {
       workspaceRoot, workspaceId,
       record: {
         schema: 'atelier-obsidian-service-state/v1', contractVersion: '1.0.0', workspaceId, serviceName: identity.serviceName, host, port, runtimeId, pid,
-        executable: { path: executable.path, digest: executable.digest, ext: { runner: process.execPath } }, stateLocation: servicePaths(workspaceRoot).stateLocation,
+        executable: { path: executable.path, digest: executable.digest, ext: { runner: process.execPath, release: releaseIdentity() } }, stateLocation: servicePaths(workspaceRoot).stateLocation,
         health: { status: 'healthy', checkedAt: startedAt }, consent: settings.consent, ext: { bearer },
       },
     })

package/src/runtime/obsidian/state-store.mjs

@@ -47,6 +47,9 @@ const isDigest = (value) => typeof value === 'string' && DIGEST.test(value)
 const isTimestamp = (value) => typeof value === 'string' && TIMESTAMP.test(value)
 const isRelative = (value) => typeof value === 'string' && value !== '' && !value.startsWith('/') && !value.includes('\\') && !value.split('/').some((part) => part === '' || part === '.' || part === '..')
 const isCount = (value) => Number.isInteger(value) && value >= 0
+const isShortCode = (value) => typeof value === 'string' && /^[a-z][a-z0-9-]{0,63}$/.test(value)
+// What a scope entry may say about notes of the view: a code, the rule, and which note or file; never a value.
+export const MAX_FRESHNESS_DIAGNOSTICS = 100
 
 function check(condition, code, message) {
   if (!condition) refuse(code, message)
@@ -67,7 +70,7 @@ export function validateFreshness(document, workspaceId) {
   check(Array.isArray(document.scopes), code, 'scopes must be a list')
   const seen = new Set()
   for (const scope of document.scopes) {
-    closedObject(scope, { required: ['scopeId', 'state', 'reason', 'generationId', 'preparedGenerationId', 'verified', 'heldNotes', 'changeClasses', 'retainedEdits', 'checkedAt'] }, code, 'a scope freshness entry')
+    closedObject(scope, { required: ['scopeId', 'state', 'reason', 'generationId', 'preparedGenerationId', 'verified', 'heldNotes', 'changeClasses', 'retainedEdits', 'checkedAt'], optional: ['diagnostics'] }, code, 'a scope freshness entry')
     check(isIdentifier(scope.scopeId) && !seen.has(scope.scopeId), code, 'a scope identity is malformed or repeated')
     seen.add(scope.scopeId)
     check(FRESHNESS_STATES.includes(scope.state), code, 'a scope carries an unknown freshness state')
@@ -79,6 +82,15 @@ export function validateFreshness(document, workspaceId) {
     check(scope.state !== 'current' || (scope.verified && scope.generationId !== null && scope.generationId === scope.preparedGenerationId && scope.heldNotes.length === 0), code, 'a scope claims current without an exact verified generation')
     check(Array.isArray(scope.changeClasses) && scope.changeClasses.every((item) => CHANGE_CLASSES.includes(item)), code, 'changeClasses names an unknown class')
     check(isCount(scope.retainedEdits) && isTimestamp(scope.checkedAt), code, 'a scope entry is malformed')
+    if (scope.diagnostics !== undefined) {
+      check(Array.isArray(scope.diagnostics) && scope.diagnostics.length <= MAX_FRESHNESS_DIAGNOSTICS, code, 'diagnostics must be a short list')
+      for (const item of scope.diagnostics) {
+        closedObject(item, { required: ['code'], optional: ['rule', 'repoId', 'nodeId', 'assetPath', 'notePath', 'filePath'] }, code, 'a diagnostic')
+        check(isShortCode(item.code) && (item.rule === undefined || isShortCode(item.rule)), code, 'a diagnostic names a malformed code or rule')
+        check(['repoId', 'nodeId', 'assetPath'].every((key) => item[key] === undefined || (typeof item[key] === 'string' && item[key] !== '')), code, 'a diagnostic names a malformed identity')
+        check(['notePath', 'filePath'].every((key) => item[key] === undefined || isRelative(item[key])), code, 'a diagnostic names a path that is not vault-relative')
+      }
+    }
   }
   return document
 }

package/src/server/local-sidecar.mjs

@@ -5,6 +5,7 @@ import fs from 'node:fs'
 import http from 'node:http'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { AtelierDiagnosticError } from '../project/config.mjs'
 import {
   atomicReplacePrivateText,
   ensureContainedPrivateDirectory,
@@ -196,6 +197,25 @@ function capabilityContract() {
   }
 }
 
+// A listen failure a person can fix by choosing another port becomes a typed
+// diagnostic the CLI prints with that remedy. Any other failure is returned
+// unchanged, so the CLI's own rule for unknown errors still decides what shows.
+function listenFailure(error, port) {
+  if (error?.code === 'EADDRINUSE') {
+    return new AtelierDiagnosticError('port-in-use', `port ${port} is already in use`, {
+      hint: 'Pass --port=<free port> to choose another.',
+      cause: error,
+    })
+  }
+  if (error?.code === 'EACCES') {
+    return new AtelierDiagnosticError('port-permission-denied', `permission to listen on port ${port} was denied`, {
+      hint: 'Pass --port=<free port from 1024 to 65535> to choose another; lower ports need elevated privileges.',
+      cause: error,
+    })
+  }
+  return error
+}
+
 function doctorEnvelope() {
   return {
     ok: true,
@@ -662,14 +682,13 @@ export function createAtelierSidecarServer({
       if (!isLoopbackHost(host)) {
         return Promise.reject(new Error(`non-loopback listen host refused: ${host}`))
       }
-      // A busy port is an ordinary condition, not a crash: surface it as a
-      // rejection the CLI can print, instead of an unhandled 'error' event.
+      // A busy or refused port is an ordinary condition, not a crash: surface
+      // it as a typed rejection the CLI prints with its remedy, instead of an
+      // unhandled 'error' event or a redacted internal error.
       return new Promise((resolve, reject) => {
         const onError = (error) => {
           server.removeListener('listening', onListening)
-          reject(error.code === 'EADDRINUSE'
-            ? new Error(`port ${listenPort} is already in use — pass --port=<free port> to choose another`)
-            : error)
+          reject(listenFailure(error, listenPort))
         }
         const onListening = () => {
           server.removeListener('error', onError)

package/src/server/server.mjs

@@ -1,4 +1,4 @@
-import { resolveProjectConfig } from '../project/config.mjs'
+import { AtelierDiagnosticError, resolveProjectConfig } from '../project/config.mjs'
 import { createAtelierSidecarServer } from './local-sidecar.mjs'
 
 function parseServerArgs(argv = []) {
@@ -11,6 +11,22 @@ function parseServerArgs(argv = []) {
   return args
 }
 
+// argv > PORT env > default. Supervisors that assign a free port (preview
+// panes, dev harnesses) pass it via PORT, and an Atelier that ignores that
+// fights whatever already holds the canonical port instead of coexisting.
+// A value listen would refuse is refused here, naming where it came from;
+// Node's own range error names neither the flag nor the variable.
+function resolvePort(args, env = process.env) {
+  const [source, raw] = args.port ? ['--port', args.port] : env.PORT ? ['PORT', env.PORT] : [null, '8137']
+  const port = Number(raw)
+  if (Number.isInteger(port) && port >= 0 && port <= 65535) return port
+  throw new AtelierDiagnosticError('port-invalid', `${source} must be a whole number from 0 to 65535, got ${JSON.stringify(raw)}`, {
+    hint: source === 'PORT'
+      ? 'Set PORT to a free port or unset it, or pass --port=<free port> to override it.'
+      : 'Pass a free port, for example --port=8138.',
+  })
+}
+
 export async function runServerCommand(argv = process.argv.slice(2)) {
   const args = parseServerArgs(argv)
   const project = resolveProjectConfig({ argv: args.projectArgs })
@@ -18,10 +34,7 @@ export async function runServerCommand(argv = process.argv.slice(2)) {
     workspaceRoot: project.outputRoot,
     stateDir: project.outputRoot,
     reviewProject: argv.includes('--review') ? project : null,
-    // argv > PORT env > default. Supervisors that assign a free port (preview
-    // panes, dev harnesses) pass it via PORT, and an Atelier that ignores that
-    // fights whatever already holds the canonical port instead of coexisting.
-    port: args.smoke ? 0 : Number(args.port || process.env.PORT || 8137),
+    port: args.smoke ? 0 : resolvePort(args),
   })
 
   if (args.smoke) {

package/src/upgrade/upgrade.mjs

@@ -128,7 +128,7 @@ export function buildAtelierLock({ project, templateId = 'existing-workspace', a
     },
     runtime: {
       node: {
-        range: packageJson.engines?.node || '>=22.18.0 <23',
+        range: packageJson.engines?.node || '>=22.18.0 <23 || >=24.13.1 <25',
       },
       telemetry: 'none',
       egress: 'local-only',

package/templates/external-project-workspace/pack-lifecycle.json

@@ -6,7 +6,7 @@
       "version": "v1",
       "digest": "sha256:0eff795765e0bbd4c2510acda2e492201c23bc870df6c354eef623484643ab11",
       "compatibleRootVersions": [
-        "0.2.0-alpha.10"
+        "0.2.0-alpha.12"
       ],
       "status": "active"
     }