@lincyaw/workspace 0.0.0-stage → 1.0.0-rc.0

package/src/node/revisions.ts

@@ -0,0 +1,346 @@
+import { lstatSync, mkdtempSync, readdirSync, readFileSync, rmdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, relative, sep } from 'node:path'
+import type { DocumentFileChange, Member, RevertResult, Revision, RevisionService } from '@lincyaw/kernel'
+import type { HistoryRevision, UncommittedFile } from '../domain/api.ts'
+import { leavesRoot } from '../domain/paths.ts'
+import { commitMessage, memberAddress, originOf } from '../domain/revisions.ts'
+import type { CommitOrigin } from '../domain/revisions.ts'
+import type { WorkspaceConfig } from './config.ts'
+import { makeDocumentDir, RequestError } from './documents.ts'
+import { documentDirOf, generatedPath, writeChanges } from './files.ts'
+import type { DocumentWriter } from './files.ts'
+import type { Git } from './git.ts'
+
+const FIELD = '\x00'
+const RECORD = '\x1e'
+const FORMAT = '--format=%x1e%H%x00%an <%ae>%x00%aI%x00%B%x00'
+
+interface LogEntry {
+  id: string
+  author: string
+  date: string
+  message: string
+  files: string[]
+}
+
+function parseLog(output: string): LogEntry[] {
+  return output.split(RECORD).filter(Boolean).map((record) => {
+    const [id = '', author = '', date = '', message = '', rest = ''] = record.split(FIELD)
+    return { id, author, date, message: message.trim(), files: rest.split('\n').map(line => line.trim()).filter(Boolean) }
+  })
+}
+
+function revertedOf(message: string): string | undefined {
+  return originOf(message)?.revert ?? /This reverts commit ([0-9a-f]{7,64})/.exec(message)?.[1]
+}
+
+function redoes(entries: LogEntry[]): (entry: LogEntry) => boolean {
+  const find = (id: string) => entries.find(entry => entry.id === id || (id.length >= 7 && entry.id.startsWith(id)))
+  const known = new Map<string, boolean>()
+  const redo = (entry: LogEntry): boolean => {
+    let found = known.get(entry.id)
+    if (found !== undefined) return found
+    known.set(entry.id, false)
+    const reverted = revertedOf(entry.message)
+    const target = reverted === undefined ? undefined : find(reverted)
+    found = target !== undefined && revertedOf(target.message) !== undefined && !redo(target)
+    known.set(entry.id, found)
+    return found
+  }
+  return redo
+}
+
+function revision(entry: LogEntry, revertedBy?: string, redo = false): HistoryRevision | undefined {
+  const origin = originOf(entry.message)
+  if (!origin) return undefined
+  const { revert, coAuthor: _coAuthor, operation, ...plain } = origin
+  return {
+    id: entry.id,
+    message: entry.message,
+    author: entry.author,
+    date: entry.date,
+    origin: plain,
+    files: entry.files,
+    ...revertedBy ? { revertedBy } : {},
+    ...operation ? { operation } : {},
+    ...revert ? { reverts: revert } : {},
+    ...revert && redo ? { redo: true as const } : {},
+  }
+}
+
+interface TreeFile {
+  path: string
+  mode: string
+  oid: string
+}
+
+export interface RevisionFiles {
+  config: WorkspaceConfig
+  writer: DocumentWriter
+}
+
+export class Revisions implements RevisionService {
+  readonly #git: Git
+  readonly #files: RevisionFiles
+
+  constructor(git: Git, files: RevisionFiles) {
+    this.#git = git
+    this.#files = files
+  }
+
+  commit(change: { files: string[], message: string, origin: CommitOrigin, trailers?: [string, string][] }): Promise<Revision | undefined> {
+    const [summary = '', ...body] = change.message.trim().split('\n')
+    return this.#git.exclusive(() => this.commitNow(change.files, summary, body.join('\n'), change.origin, undefined, change.trailers))
+  }
+
+  async commitNow(paths: string[], summary: string, body: string, origin: CommitOrigin, revert?: string, more: [string, string][] = []): Promise<Revision | undefined> {
+    const unique = [...new Set(paths.map(path => path.replace(/^\.?\/+|\/+$/g, '')).filter(path => path && !leavesRoot(path)))]
+    if (unique.length === 0) return undefined
+    for (const path of unique) await this.#git.attempt(['add', '-A', '--', path], { GIT_LITERAL_PATHSPECS: '1' })
+    const staged = (await this.#git.raw(['diff', '--cached', '--name-only', '--', ...unique], { GIT_LITERAL_PATHSPECS: '1' })).trim()
+    if (!staged) return undefined
+    const message = withTrailers(commitMessage(summary, body, origin, revert), more)
+    await this.#git.raw([...await this.#identity(), 'commit', '-q', '--no-verify', '-m', message, ...this.#author(origin.member), '--', ...unique], { GIT_LITERAL_PATHSPECS: '1' })
+    return this.#revision('HEAD')
+  }
+
+  async status(paths: string[] = ['']): Promise<{ branch?: string, uncommitted: number }> {
+    const branch = await this.#git.attempt(['symbolic-ref', '--quiet', '--short', 'HEAD'])
+    return { ...branch.ok ? { branch: branch.output.trim() } : {}, uncommitted: (await this.#statusOf(paths)).length }
+  }
+
+  async uncommittedFiles(paths: string[]): Promise<UncommittedFile[]> {
+    const specs = paths.map(path => path || '.')
+    const status = await this.#statusOf(paths)
+    const counts = new Map<string, [number, number]>()
+    const numstat = await this.#git.attempt(['diff', '--numstat', '-z', '--no-renames', 'HEAD', '--', ...specs], { GIT_LITERAL_PATHSPECS: '1' })
+    if (numstat.ok) {
+      for (const entry of numstat.output.split('\0').filter(Boolean)) {
+        const [added = '-', removed = '-', path = ''] = entry.split('\t')
+        if (added !== '-') counts.set(this.#fromTop(path), [Number(added), Number(removed)])
+      }
+    }
+    return status.map(({ code, path }): UncommittedFile => {
+      const kind = code.includes('D') ? 'deleted' : code === '??' || code[0] === 'A' ? 'added' : 'modified'
+      const counted = counts.get(path) ?? (kind === 'added' ? lineCount(join(this.#files.config.root, path)) : undefined)
+      return { path, kind, ...counted ? { added: counted[0], removed: counted[1] } : {} }
+    }).sort((a, b) => a.path.localeCompare(b.path))
+  }
+
+  discard(paths: string[]): Promise<void> {
+    return this.#git.exclusive(async () => {
+      const files: TreeFile[] = []
+      for (const path of paths) {
+        const listed = await this.#git.attempt(['ls-tree', '-z', 'HEAD', '--', path], { GIT_LITERAL_PATHSPECS: '1' })
+        const [meta = '', named] = (listed.ok ? listed.output.split('\0')[0] ?? '' : '').split('\t')
+        const [mode = '', , oid = ''] = meta.split(' ')
+        files.push(named && mode ? { path, mode, oid } : { path, mode: '000000', oid: '' })
+      }
+      await this.#write(files)
+    })
+  }
+
+  async history(filter: { document?: string, task?: string, limit?: number } = {}): Promise<HistoryRevision[]> {
+    const log = await this.#git.attempt(['log', FORMAT, '--name-only', '--no-renames', ...filter.document ? ['--', filter.document] : []], { GIT_LITERAL_PATHSPECS: '1' })
+    if (!log.ok) return []
+    const entries = parseLog(log.output)
+    const revertedBy = new Map<string, string>()
+    for (const entry of entries) {
+      const reverted = revertedOf(entry.message)
+      if (reverted && !revertedBy.has(reverted)) revertedBy.set(reverted, entry.id)
+    }
+    const redo = redoes(entries)
+    const revisions = entries.flatMap((entry) => {
+      const found = revision(entry, revertedBy.get(entry.id), redo(entry))
+      return found && (!filter.task || found.origin.task === filter.task) ? [found] : []
+    })
+    return filter.limit ? revisions.slice(0, filter.limit) : revisions
+  }
+
+  revert(id: string, member: Member): Promise<RevertResult> {
+    return this.#git.exclusive(async () => {
+      const verified = await this.#git.attempt(['rev-parse', '--verify', '--quiet', `${id}^{commit}`])
+      if (!verified.ok) throw new Error(`no commit ${id}`)
+      const target = (await this.#log(verified.output.trim()))!
+      const parent = await this.#git.attempt(['rev-parse', '--verify', '--quiet', `${target.id}^1`])
+      if (!parent.ok) throw new Error(`commit ${target.id} has no parent to go back to`)
+      const merged = await this.#git.run(['merge-tree', '--write-tree', '--no-messages', '--name-only', `--merge-base=${target.id}`, 'HEAD', parent.output.trim()])
+      const lines = merged.stdout.toString('utf8').split('\n').map(line => line.trim()).filter(Boolean)
+      if (merged.code === 1) return { ok: false, conflicts: [...new Set(lines.slice(1).map(this.#fromTop))] }
+      if (merged.code !== 0 || !lines[0]) throw new Error(`git merge-tree failed: ${merged.stderr.trim()}`)
+      const changes = await this.#changes('HEAD', lines[0])
+      if (changes.length === 0) throw new Error(`commit ${target.id} is undone already`)
+      const outside = changes.filter(change => documentDirOf(this.#files.config, change.path) === undefined).map(change => change.path)
+      if (outside.length > 0 && !member.roles.includes('owner')) throw new RequestError(403, `only an owner reverts a change of ${outside.join(', ')}, outside the documents`)
+      const blocked = await this.#uncommitted(changes.map(change => change.path))
+      if (blocked.length > 0) return { ok: false, conflicts: blocked }
+      await this.#write(changes)
+      const subject = target.message.split('\n')[0] ?? target.id
+      const undone = originOf(target.message)
+      const origin: CommitOrigin = { kind: undone?.kind ?? 'editor', member, ...undone?.operation ? { operation: undone.operation } : {} }
+      const done = await this.commitNow(changes.map(change => change.path), `Revert "${subject}"`, `This reverts commit ${target.id}.`, origin, target.id)
+      if (!done) throw new Error(`the revert of ${target.id} committed nothing`)
+      return { ok: true, revision: done }
+    })
+  }
+
+  async messageOf(id: string): Promise<string | undefined> {
+    const shown = await this.#git.attempt(['show', '-s', '--format=%B', `${id}^{commit}`])
+    return shown.ok ? shown.output : undefined
+  }
+
+  async filesOf(id: string): Promise<string[]> {
+    const shown = await this.#git.attempt(['show', '--no-renames', '--name-only', '-z', '--format=', `${id}^{commit}`])
+    return shown.ok ? shown.output.split('\0').filter(Boolean).map(this.#fromTop) : []
+  }
+
+  async documentsOf(id: string): Promise<string[]> {
+    const verified = await this.#git.attempt(['rev-parse', '--verify', '--quiet', `${id}^{commit}`])
+    if (!verified.ok) return []
+    const files = (await this.#git.raw(['show', '--no-renames', '--name-only', '-z', '--format=', verified.output.trim()])).split('\0').filter(Boolean).map(this.#fromTop)
+    return [...new Set(files.flatMap(file => documentDirOf(this.#files.config, file) ?? []))]
+  }
+
+  async #statusOf(paths: string[]): Promise<{ code: string, path: string }[]> {
+    const status = await this.#git.attempt(['status', '--porcelain=v1', '-z', '--no-renames', '--untracked-files=all', '--', ...paths.map(path => path || '.')], { GIT_LITERAL_PATHSPECS: '1' })
+    if (!status.ok) return []
+    return status.output.split('\0').filter(Boolean)
+      .map(entry => ({ code: entry.slice(0, 2), path: this.#fromTop(entry.slice(3)) }))
+      .filter(({ path }) => !generatedPath(path))
+  }
+
+  #fromTop = (path: string): string => relative(this.#files.config.root, join(this.#git.top, path)).split(sep).join('/')
+
+  async #changes(from: string, to: string): Promise<TreeFile[]> {
+    const fields = (await this.#git.raw(['diff-tree', '-r', '-z', '--no-renames', from, to])).split('\0').filter(Boolean)
+    const out: TreeFile[] = []
+    for (let i = 0; i + 1 < fields.length; i += 2) {
+      const [, mode = '', , oid = ''] = fields[i]!.slice(1).split(' ')
+      const path = this.#fromTop(fields[i + 1]!)
+      if (leavesRoot(path)) throw new Error(`the revert changes ${fields[i + 1]}, outside the workspace`)
+      out.push({ path, mode, oid })
+    }
+    return out
+  }
+
+  async #uncommitted(paths: string[]): Promise<string[]> {
+    const work = mkdtempSync(join(tmpdir(), 'presmium-revert-'))
+    const env = { GIT_INDEX_FILE: join(work, 'index'), GIT_LITERAL_PATHSPECS: '1' }
+    try {
+      await this.#git.raw(['read-tree', 'HEAD'], env)
+      const blocked = new Set<string>()
+      for (const path of paths) {
+        const tracked = (await this.#git.attempt(['ls-files', '--', path], env)).output.trim() !== ''
+        let present = true
+        try {
+          lstatSync(join(this.#files.config.root, path))
+        } catch {
+          present = false
+        }
+        if (!tracked && !present) continue
+        if (!(await this.#git.attempt(['add', '-A', '--', path], env)).ok) blocked.add(path)
+      }
+      const differ = (await this.#git.raw(['diff-index', '--cached', '--name-only', '-z', 'HEAD', '--', ...paths], env)).split('\0').filter(Boolean).map(this.#fromTop)
+      for (const path of differ) blocked.add(path)
+      return [...blocked].sort()
+    } finally {
+      rmSync(work, { recursive: true, force: true })
+    }
+  }
+
+  async #write(files: TreeFile[]): Promise<void> {
+    const { config, writer } = this.#files
+    const changes: { change: DocumentFileChange, dir?: string }[] = []
+    for (const file of files) {
+      if (file.mode === '160000') throw new Error(`${file.path} is a submodule: not reverted`)
+      const dir = documentDirOf(config, file.path)
+      if (/^0+$/.test(file.mode)) {
+        changes.push({ change: { path: file.path, remove: true }, dir })
+        continue
+      }
+      const blob = (await this.#git.run(['cat-file', 'blob', file.oid])).stdout
+      const change: DocumentFileChange = file.mode === '120000' ? { path: file.path, link: blob.toString('utf8') } : { path: file.path, content: blob, ...file.mode === '100755' ? { executable: true } : {} }
+      changes.push({ change, dir })
+    }
+    const inDocuments = changes.filter(({ dir }) => dir !== undefined)
+    for (const dir of new Set(inDocuments.filter(({ change }) => !('remove' in change)).map(({ dir }) => dir!))) {
+      if (!exists(join(config.root, dir))) makeDocumentDir(config.root, dir)
+    }
+    if (inDocuments.length > 0) await writer.write(inDocuments.map(({ change }) => change))
+    const outside = changes.filter(({ dir }) => dir === undefined).map(({ change }) => change)
+    for (const { path } of outside) {
+      const open = writableByOthers(config.root, path)
+      if (open) throw new Error(`the revert would write ${path}, in ${open}, which more than serve may write`)
+    }
+    if (outside.length > 0) writeChanges(config, outside, true)
+    for (const dir of new Set(inDocuments.map(({ dir }) => dir!))) {
+      if (!dir) continue
+      try {
+        if (readdirSync(join(config.root, dir)).length === 0) rmdirSync(join(config.root, dir))
+      } catch {
+      }
+    }
+  }
+
+  async #log(id: string): Promise<LogEntry | undefined> {
+    return parseLog(await this.#git.raw(['show', '--no-renames', '--name-only', FORMAT, id]))[0]
+  }
+
+  async #revision(id: string): Promise<Revision | undefined> {
+    const entry = await this.#log(id)
+    return entry && revision(entry)
+  }
+
+  #author(member: Member | undefined): string[] {
+    return member ? [`--author=${memberAddress(member)}`] : []
+  }
+
+  async #identity(): Promise<string[]> {
+    const email = await this.#git.attempt(['config', 'user.email'])
+    return email.ok && email.output.trim() ? [] : ['-c', 'user.name=Presmium', '-c', 'user.email=presmium@presmium.invalid']
+  }
+}
+
+function withTrailers(message: string, more: [string, string][]): string {
+  if (more.length === 0) return message
+  const lines = message.trimEnd().split('\n')
+  const at = lines.at(-1)?.startsWith('Co-authored-by: ') ? lines.length - 1 : lines.length
+  lines.splice(at, 0, ...more.map(([key, value]) => `${key}: ${value.replace(/\s+/g, ' ').trim()}`))
+  return `${lines.join('\n')}\n`
+}
+
+function writableByOthers(root: string, path: string): string | undefined {
+  const parts = path.split('/').slice(0, -1)
+  for (let i = 0; i <= parts.length; i++) {
+    const dir = parts.slice(0, i).join('/')
+    let mode: number
+    try {
+      ({ mode } = lstatSync(join(root, dir)))
+    } catch {
+      return undefined
+    }
+    if ((mode & 0o002) !== 0) return dir || '.'
+  }
+  return undefined
+}
+
+function lineCount(path: string): [number, number] | undefined {
+  try {
+    const bytes = readFileSync(path)
+    if (bytes.includes(0)) return undefined
+    const text = bytes.toString('utf8')
+    return [text === '' ? 0 : text.split('\n').length - (text.endsWith('\n') ? 1 : 0), 0]
+  } catch {
+    return undefined
+  }
+}
+
+function exists(path: string): boolean {
+  try {
+    lstatSync(path)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/node/routes.ts

@@ -0,0 +1,239 @@
+import { timingSafeEqual } from 'node:crypto'
+import { createRequire } from 'node:module'
+import { eventStream, errorMessage, isRecord, json, problem } from '@lincyaw/kernel'
+import type { Member, PresmiumNodePlugin, RequestContext, Route, ServerContribution } from '@lincyaw/kernel'
+import { bearer } from '@lincyaw/server'
+import type { ChangesAnswer, CommitAnswer, DocumentOperation, DocumentsAnswer, RevertAnswer, RevisionsAnswer, SavedAnswer } from '../domain/api.ts'
+import { WORKSPACE_ID } from '../domain/api.ts'
+import { trailers } from '../domain/revisions.ts'
+import { lockedError, RequestError } from './documents.ts'
+import type { Documents, DocumentsChange } from './documents.ts'
+import { documentDirOf } from './files.ts'
+import type { DocumentLocks } from './locks.ts'
+import type { Revisions } from './revisions.ts'
+import { reviewRoutes } from './review/routes.ts'
+import type { Reviews } from './review/reviews.ts'
+import type { WorkspaceService } from './service.ts'
+import { MAX_SOURCE, SourceFiles } from './source.ts'
+
+const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
+
+export interface WorkspaceRoutes {
+  documents: Documents
+  revisions?: Revisions
+  locks?: DocumentLocks
+  documentsChanged?(change: DocumentsChange): Promise<void> | void
+  document?: string
+  service?: WorkspaceService
+  token?: string
+  reviews?: Reviews
+}
+
+function authorized(request: Request, token: string): boolean {
+  const given = Buffer.from(bearer(request.headers.get('authorization')) ?? '')
+  const own = Buffer.from(token)
+  return given.length === own.length && timingSafeEqual(given, own)
+}
+
+function rendererIds(body: unknown): string[] | undefined {
+  if (!isRecord(body) || !Array.isArray(body.to)) return undefined
+  const ids = body.to.filter((id): id is string => typeof id === 'string' && /^[\w.-]+$/.test(id))
+  return ids.length > 0 ? ids : undefined
+}
+
+const NO_GIT = 'the workspace is not a git repository: run git init in it to use the document operations and the history'
+
+function operationOf(body: unknown): DocumentOperation | undefined {
+  if (!isRecord(body) || typeof body.dir !== 'string') return undefined
+  const text = (value: unknown) => (typeof value === 'string' ? value.trim() : undefined)
+  const dir = body.dir.trim().replace(/^\/+|\/+$/g, '')
+  switch (body.op) {
+    case 'create': return { op: 'create', dir, ...text(body.title) ? { title: text(body.title) } : {}, ...text(body.template) ? { template: text(body.template) } : {} }
+    case 'rename':
+    case 'copy': return typeof body.to === 'string' ? { op: body.op, dir, to: body.to.trim().replace(/^\/+|\/+$/g, '') } : undefined
+    case 'delete': return { op: 'delete', dir }
+    default: return undefined
+  }
+}
+
+async function answer(work: () => Promise<Response>): Promise<Response> {
+  try {
+    return await work()
+  } catch (error) {
+    if (error instanceof RequestError) return json({ error: error.message, ...error.detail }, error.status)
+    return problem(500, errorMessage(error))
+  }
+}
+
+function difference(before: string[], after: string[]): DocumentsChange {
+  return { removed: before.filter(dir => !after.includes(dir)), added: after.filter(dir => !before.includes(dir)) }
+}
+
+function chosenPaths(body: unknown, uncommitted: string[]): string[] {
+  const asked = isRecord(body) && Array.isArray(body.paths) ? body.paths.filter((path): path is string => typeof path === 'string') : undefined
+  return asked ? uncommitted.filter(path => asked.includes(path)) : uncommitted
+}
+
+export function workspaceContribution(options: WorkspaceRoutes): ServerContribution {
+  const { documents, revisions, locks } = options
+  const listed = () => documents.list().map(doc => doc.dir)
+  const source = new SourceFiles({ config: documents.config, writer: documents.writer, ...locks ? { locks } : {} })
+  const scopeOf = (ctx: RequestContext) => source.scope(options.document ?? ctx.document)
+  const uncommitted = async (ctx: RequestContext) => (revisions ? await revisions.uncommittedFiles(source.roots(scopeOf(ctx))) : [])
+  const onChanges = async (request: Request, ctx: RequestContext, holder: string, work: (paths: string[], member: Member, body: Record<string, unknown>) => Promise<Response>) => {
+    if (request.method !== 'POST') return problem(405, 'POST')
+    if (!revisions) return problem(409, NO_GIT)
+    const body: unknown = await request.json().catch(() => ({}))
+    const paths = chosenPaths(body, (await uncommitted(ctx)).map(file => file.path))
+    if (paths.length === 0) return problem(409, 'no changes to take: every file is as committed')
+    const claimed = locks?.claimAll(paths.flatMap(path => documentDirOf(documents.config, path) ?? []), holder)
+    if (claimed && 'holder' in claimed) throw lockedError(claimed.document, claimed.holder)
+    try {
+      return await work(paths, ctx.member, isRecord(body) ? body : {})
+    } finally {
+      claimed?.release()
+    }
+  }
+  const routes: Record<string, Route> = {
+    documents: {
+      role: 'reader',
+      handle: (request, ctx) => answer(async () => {
+        if (request.method === 'GET') {
+          const status = revisions ? await revisions.status(source.roots(scopeOf(ctx))) : {}
+          return json({ title: documents.config.title, documents: documents.list(), templates: documents.templates(), git: Boolean(revisions), ...status, single: documents.config.single || options.document !== undefined } satisfies DocumentsAnswer)
+        }
+        if (request.method !== 'POST') return problem(405, 'GET or POST')
+        if (options.document !== undefined) return problem(409, 'presmium dev serves one deck: the document operations are the workspace service\'s (presmium serve)')
+        if (!ctx.member.roles.some(role => role === 'editor' || role === 'owner')) return problem(403, 'document operations need the role editor')
+        if (!revisions) return problem(409, NO_GIT)
+        const operation = operationOf(await request.json().catch(() => undefined))
+        if (!operation) return problem(400, '{ op: create | rename | copy | delete, dir, to?, title?, template? }')
+        return json(await documents.apply(operation, ctx.member))
+      }),
+    },
+    revisions: {
+      role: 'editor',
+      handle: (request, ctx) => answer(async () => {
+        if (request.method !== 'GET') return problem(405, 'GET')
+        if (!revisions) return json({ revisions: [] } satisfies RevisionsAnswer)
+        const params = new URL(request.url).searchParams
+        const limit = Number(params.get('limit'))
+        const document = params.get('document') ?? ((options.document ?? ctx.document) || (documents.config.single ? '.' : undefined))
+        return json({ revisions: await revisions.history({ ...document ? { document } : {}, ...params.get('task') ? { task: params.get('task')! } : {}, ...Number.isInteger(limit) && limit > 0 ? { limit } : {} }) } satisfies RevisionsAnswer)
+      }),
+    },
+    'revisions/revert': {
+      role: 'editor',
+      handle: (request, ctx) => answer(async () => {
+        if (request.method !== 'POST') return problem(405, 'POST')
+        if (!revisions) return problem(409, NO_GIT)
+        const body: unknown = await request.json().catch(() => undefined)
+        if (!isRecord(body) || typeof body.id !== 'string' || !/^[0-9a-f]{4,64}$/i.test(body.id)) return problem(400, '{ id: <commit> }')
+        const claimed = locks?.claimAll(await revisions.documentsOf(body.id), 'revision:revert')
+        if (claimed && 'holder' in claimed) throw lockedError(claimed.document, claimed.holder)
+        try {
+          const before = listed()
+          const result = await revisions.revert(body.id, ctx.member)
+          if (result.ok) {
+            await options.documentsChanged?.(difference(before, listed()))
+            const undone = trailers(result.revision.message)['Presmium-Revert']?.[0] ?? body.id
+            void options.reviews?.reverted(undone, result.revision.id).catch(() => undefined)
+          }
+          return json(result satisfies RevertAnswer, result.ok ? 200 : 409)
+        } finally {
+          claimed?.release()
+        }
+      }),
+    },
+    'files': {
+      role: 'editor',
+      handle: (request, ctx) => answer(async () => {
+        if (request.method !== 'GET') return problem(405, 'GET')
+        return json(source.files(scopeOf(ctx), ctx.member))
+      }),
+    },
+    'source': {
+      role: 'editor',
+      maxBody: MAX_SOURCE * 3,
+      handle: (request, ctx) => answer(async () => {
+        const scope = scopeOf(ctx)
+        if (request.method === 'GET') return json(source.read(scope, new URL(request.url).searchParams.get('path') ?? '', ctx.member))
+        if (request.method !== 'POST') return problem(405, 'GET or POST')
+        const body: unknown = await request.json().catch(() => undefined)
+        if (!isRecord(body) || typeof body.path !== 'string' || typeof body.content !== 'string' || typeof body.base !== 'string') return problem(400, '{ path, content, base: <the version opened> }')
+        return json({ version: await source.save(scope, body.path, body.content, body.base, ctx.member) } satisfies SavedAnswer)
+      }),
+    },
+    'changes': {
+      role: 'editor',
+      handle: (request, ctx) => answer(async () => {
+        if (request.method !== 'GET') return problem(405, 'GET')
+        return json({ files: await uncommitted(ctx) } satisfies ChangesAnswer)
+      }),
+    },
+    'changes/commit': {
+      role: 'editor',
+      handle: (request, ctx) => answer(() => onChanges(request, ctx, 'editor:commit', async (paths, member, body) => {
+        const message = typeof body.message === 'string' ? body.message.trim().slice(0, 4000) : ''
+        if (!message) return problem(400, '{ message: what the change is, paths? }')
+        const revision = await revisions!.commit({ files: paths, message, origin: { kind: 'editor', member } })
+        return json({ ...revision ? { revision } : {}, paths } satisfies CommitAnswer)
+      })),
+    },
+    ...options.service ? serviceRoutes(options.service) : {},
+    ...options.reviews ? reviewRoutes(options.reviews, answer) : {},
+    'changes/discard': {
+      role: 'editor',
+      handle: (request, ctx) => answer(() => onChanges(request, ctx, 'editor:discard', async (paths) => {
+        const before = listed()
+        await revisions!.discard(paths)
+        await options.documentsChanged?.(difference(before, listed()))
+        return json({ paths } satisfies CommitAnswer)
+      })),
+    },
+  }
+  const { token } = options
+  if (token) {
+    for (const [key, route] of Object.entries(routes)) {
+      routes[key] = { ...route, handle: (request, ctx) => (authorized(request, token) ? route.handle(request, ctx) : Promise.resolve(problem(401, 'the workspace service\'s routes need its token: Authorization: Bearer <PRESMIUM_SERVICE_TOKEN>'))) }
+    }
+  }
+  return { routes, ...options.service ? { proxies: options.service.proxies } : {} }
+}
+
+function serviceRoutes(service: WorkspaceService): Record<string, Route> {
+  return {
+    'ir': {
+      role: 'editor',
+      handle: (request, ctx) => answer(async () => (request.method === 'GET' ? json(await service.ir(ctx.document)) : problem(405, 'GET'))),
+    },
+    'ir/events': {
+      role: 'editor',
+      handle: async (request, ctx) => (request.method === 'GET' ? eventStream(service.events(ctx.document, request.signal), request.signal) : problem(405, 'GET')),
+    },
+    'preview': {
+      role: 'editor',
+      handle: (request, ctx) => answer(async () => (request.method === 'GET' ? json(await service.preview(ctx.document)) : problem(405, 'GET'))),
+    },
+    'build': {
+      role: 'editor',
+      handle: (request, ctx) => answer(async () => {
+        if (request.method !== 'POST') return problem(405, 'POST')
+        return json(await service.build(ctx.document, rendererIds(await request.json().catch(() => undefined))))
+      }),
+    },
+    'check': {
+      role: 'editor',
+      handle: (request, ctx) => answer(async () => (request.method === 'POST' ? json(await service.check(ctx.document)) : problem(405, 'POST'))),
+    },
+  }
+}
+
+export function workspacePlugin(options: WorkspaceRoutes): PresmiumNodePlugin {
+  return {
+    id: WORKSPACE_ID,
+    version,
+    kernel: '^1.0.0',
+    server: () => workspaceContribution(options),
+  }
+}