@lincyaw/workspace 1.0.0-rc.0 → 1.0.0-rc.2

package/src/node/site.ts

@@ -1,26 +1,31 @@
 import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
 import { basename, dirname, join, relative, resolve, sep } from 'node:path'
-import { compileTranslations, DECK_ENTRY, directoryAsset, fileHash, frontmatterLine, inside, lineOf, loadPlugins, portable, publishesDirectory, readFrontmatter, viewFor } from '@lincyaw/compiler'
+import { compileTranslations, directoryAsset, fileHash, lineContaining, loadPlugins, nodeVitePlugins, portable, publishesDirectory, viewFor } from '@lincyaw/compiler'
 import type { Compilation } from '@lincyaw/compiler'
-import type { Finding, IRDocument, RenderContext, Renderer, SiteDocument, SiteSpec, SourcePos } from '@lincyaw/kernel'
-import type { WorkspaceDocument } from '../domain/api.ts'
+import { DOCUMENT_ENTRY, isRecord, NON_FILE_URL, WEB_RENDERER_PACKAGE } from '@lincyaw/kernel'
+import type { DocumentSummary, Finding, IRDocument, RenderContext, Renderer, SiteDocument, SiteSpec, SourcePos } from '@lincyaw/kernel'
+import { isInside } from '@lincyaw/kernel/node'
 import type { WorkspaceConfig } from './config.ts'
 
-const WEB_PACKAGE = '@lincyaw/web'
-
 export async function webRenderer(root: string, bundled?: string): Promise<Renderer> {
-  const { plugins, problems } = await loadPlugins(root, [WEB_PACKAGE], { workspaceRoot: root, listed: [], bundled })
+  const { plugins, problems } = await loadPlugins(root, [WEB_RENDERER_PACKAGE], { workspaceRoot: root, listed: [], bundled })
   const renderer = plugins[0]?.plugin?.renderer
-  if (!renderer?.buildSite || !renderer.devSite) throw new Error(`the web renderer (${WEB_PACKAGE}) is not installed: ${problems.map(p => p.message).join('; ') || 'it has no workspace site'}`)
+  if (!renderer?.buildSite || !renderer.devSite) throw new Error(`the web renderer (${WEB_RENDERER_PACKAGE}) is not installed: ${problems.map(p => p.message).join('; ') || 'it has no workspace site'}`)
   return renderer
 }
 
-export function siteIR(compilation: Compilation, doc: IRDocument = compilation.doc): IRDocument {
+/** The document as the workspace site has it, every form's blocks in it: its plugins named by their directories. */
+export function siteDocumentIR(compilation: Compilation, doc: IRDocument = compilation.doc): IRDocument {
   const dirs = doc.config.plugins.flatMap((name) => {
     const loaded = compilation.plugins.find(plugin => plugin.name === name)
     return loaded ? [loaded.dir] : []
   })
-  return viewFor({ ...doc, config: { ...doc.config, plugins: dirs } }, 'web')
+  return { ...doc, config: { ...doc.config, plugins: dirs } }
+}
+
+/** The document's web form on the workspace site. */
+export function siteIR(compilation: Compilation, doc: IRDocument = compilation.doc): IRDocument {
+  return viewFor(siteDocumentIR(compilation, doc), 'web')
 }
 
 export async function siteTranslations(compilation: Compilation): Promise<{ translations: NonNullable<SiteDocument['translations']>, findings: Finding[] }> {
@@ -29,16 +34,23 @@ export async function siteTranslations(compilation: Compilation): Promise<{ tran
   return { translations: translations.map(({ lang, doc }) => ({ lang, doc: siteIR(compilation, doc) })), findings }
 }
 
-export function siteDocument(document: WorkspaceDocument, doc?: IRDocument, translations?: SiteDocument['translations']): SiteDocument {
-  return { dir: document.dir, title: document.title, ...document.lang ? { lang: document.lang } : {}, ...document.tags ? { tags: document.tags } : {}, ...doc ? { doc } : {}, ...translations?.length ? { translations } : {} }
+export function siteDocument(document: DocumentSummary, doc?: IRDocument, translations?: SiteDocument['translations'], compilation?: Compilation): SiteDocument {
+  return { dir: document.dir, title: document.title, description: document.description, ...document.lang ? { lang: document.lang } : {}, ...document.tags ? { tags: document.tags } : {}, ...doc ? { doc } : {}, ...translations?.length ? { translations } : {}, ...compilation ? { nodeVitePlugins: nodeVitePlugins(compilation) } : {} }
+}
+
+export function refreshDocumentVitePlugins(site: SiteSpec, dir: string, compilation: Compilation): void {
+  let document = site.documents.find(document => document.dir === dir)
+  if (!document) {
+    document = { dir, title: compilation.doc.meta.title, lang: compilation.doc.meta.lang }
+    site.documents.push(document)
+  }
+  document.nodeVitePlugins = nodeVitePlugins(compilation)
 }
 
 export function siteSpec(config: WorkspaceConfig, documents: SiteDocument[]): SiteSpec {
   return { title: config.title, documents, ...typeof config.site.home === 'string' ? { home: config.site.home } : {}, config: config.site }
 }
 
-const REMOTE = /^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i
-
 export interface SiteContextOptions {
   root: string
   outDir: string
@@ -60,7 +72,6 @@ export function siteContext(options: SiteContextOptions): RenderContext {
     pluginDirs: {},
     renderers: ['web'],
     base: options.base ?? '/',
-    vitePlugins: [],
     extensionFor: () => undefined,
     portable: (value, from) => portable(value, from, root),
     localAsset: (source, url) => publishedAsset(options, source, url, ctx.report),
@@ -72,15 +83,15 @@ export function siteContext(options: SiteContextOptions): RenderContext {
 }
 
 function deckOf(file: string, root: string): string | undefined {
-  for (let dir = dirname(file); inside(dir, root); dir = dirname(dir)) {
-    if (existsSync(join(dir, DECK_ENTRY))) return dir
+  for (let dir = dirname(file); isInside(dir, root); dir = dirname(dir)) {
+    if (existsSync(join(dir, DOCUMENT_ENTRY))) return dir
     if (dir === root) return undefined
   }
   return undefined
 }
 
 function publishedAsset(options: SiteContextOptions, source: SourcePos, url: string, report: (finding: Finding) => void): { file: string, name: string } | undefined {
-  if (REMOTE.test(url)) return undefined
+  if (NON_FILE_URL.test(url)) return undefined
   const path = url.replace(/[?#].*$/s, '')
   if (!path || path.startsWith('/')) return undefined
   let name = path
@@ -88,7 +99,7 @@ function publishedAsset(options: SiteContextOptions, source: SourcePos, url: str
     name = decodeURIComponent(path)
   } catch {
   }
-  const warn = (message: string) => report({ checkId: 'presmium.links', severity: 'warning', message, source: { file: source.file, line: lineOf(source, url) } })
+  const warn = (message: string) => report({ checkId: 'presmium.links', severity: 'warning', message, source: { file: source.file, line: lineContaining(source, url) } })
   const target = resolve(dirname(source.file), name)
   const stat = statSync(target, { throwIfNoEntry: false })
   if (!stat) {
@@ -97,25 +108,25 @@ function publishedAsset(options: SiteContextOptions, source: SourcePos, url: str
   }
   const root = realpathSync(options.root)
   const real = realpathSync(target)
-  if (!inside(real, root)) {
+  if (!isInside(real, root)) {
     if (stat.isFile()) warn(`${url} is not published: the file lies outside the workspace`)
     return undefined
   }
   if (stat.isFile()) return { file: target, name: `${fileHash(target).slice(0, 8)}-${basename(target)}` }
   const deck = deckOf(source.file, options.root)
   if (!deck || !publishesDirectory(target, deck)) return undefined
-  const lang = readFrontmatter(readFileSync(join(deck, DECK_ENTRY), 'utf8')).lang
+  const document: unknown = JSON.parse(readFileSync(join(deck, DOCUMENT_ENTRY), 'utf8'))
+  const lang = isRecord(document) && isRecord(document.metadata) ? document.metadata.lang : undefined
   return directoryAsset(target, deck, join(options.workDir, 'files'), typeof lang === 'string' ? lang : undefined, message => warn(`${url} is not published: ${message}`))
 }
 
-export function untranslated(compilation: Compilation, root: string): Finding[] {
+export function untranslatedFindings(compilation: Compilation, root: string): Finding[] {
   const { translations } = compilation.doc.config
   if (!translations) return []
-  const text = readFileSync(compilation.entry, 'utf8')
   return Object.entries(translations).map(([lang, entry]) => ({
     checkId: 'presmium.translations',
     severity: 'warning' as const,
     message: `translation "${lang}" (${entry}) is not in the workspace site of presmium serve, which shows the originals; presmium build at the workspace root publishes it (or presmium build ${relative(root, compilation.deckDir).split(sep).join('/') || '.'} for this document alone)`,
-    source: { file: compilation.entry, line: frontmatterLine(text, entry) },
+    source: { file: compilation.entry, line: 1 },
   }))
 }

package/src/node/source-editor.ts

@@ -0,0 +1,332 @@
+import { createHash } from 'node:crypto'
+import { lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
+import { join } from 'node:path'
+import { WORKSPACE_CONFIG } from '@lincyaw/compiler'
+import { DOCUMENT_ENTRY, validateDocument } from '@lincyaw/kernel'
+import type { ConflictAnswer, DocumentFileChange, FilesAnswer, Member, Revision, SavedAnswer, SourceAnswer, SourceFile, SourceTransactionAnswer, SourceTransactionChange } from '@lincyaw/kernel'
+import { isWithin } from '../domain/paths.ts'
+import { listDocumentEntries, readDocumentSummary } from './config.ts'
+import type { DocumentEntry, WorkspaceConfig } from './config.ts'
+import { RequestError } from './errors.ts'
+import { lockedError } from './locks.ts'
+import type { DocumentLocks } from './locks.ts'
+import { documentDirOf, FilesError, writeChanges } from './writer.ts'
+import type { DocumentWriter } from './writer.ts'
+
+export const MAX_SOURCE = 2 << 20
+export const MAX_SOURCE_CHANGES = 16
+const MAX_FILES = 2000
+const HIDDEN_FROM_EDITOR = new Set(['node_modules', 'dist', '.git', '.presmium'])
+const BINARY = /\.(?:png|jpe?g|gif|webp|avif|ico|bmp|pdf|wasm|zip|gz|tgz|bz2|xz|7z|woff2?|ttf|otf|eot|mp3|mp4|m4a|wav|ogg|oga|webm|mov|avi|mkv|bin|so|dylib|dll|exe|pyc|xlsx?|docx?|pptx?|parquet|npy|npz|pkl|db|sqlite)$/i
+
+export function validateDocumentSource(path: string, content: string, before?: Uint8Array): void {
+  if (path !== DOCUMENT_ENTRY && !path.endsWith(`/${DOCUMENT_ENTRY}`)) return
+  let value: unknown
+  try { value = JSON.parse(content.replace(/^\uFEFF/, '')) }
+  catch { throw new RequestError(422, 'document-invalid', { issues: [{ path: '', code: 'json-syntax', message: 'The document is not valid JSON.', severity: 'error' }] }) }
+  const checked = validateDocument(value)
+  if (!checked.document || checked.issues.some(issue => issue.severity === 'error')) throw new RequestError(422, 'document-invalid', { issues: checked.issues })
+  if (before) {
+    let previous: unknown
+    try { previous = JSON.parse(Buffer.from(before).toString('utf8').replace(/^\uFEFF/, '')) } catch {}
+    if (previous && typeof previous === 'object' && 'id' in previous && typeof previous.id === 'string' && previous.id !== checked.document.id) throw new RequestError(422, 'document-identity-changed')
+  }
+}
+
+export function versionOf(bytes: Uint8Array | string): string {
+  return createHash('sha256').update(bytes).digest('hex').slice(0, 20)
+}
+
+export interface SourceEditorOptions {
+  config: WorkspaceConfig
+  writer: DocumentWriter
+  locks?: DocumentLocks
+}
+
+interface Scope {
+  document: string
+  home: boolean
+}
+
+export interface SourceTransactionHistory {
+  run<T>(work: () => Promise<T>): Promise<T>
+  commit(paths: string[], lang: string | undefined): Promise<Revision | undefined>
+}
+interface TransactionFile { path: string, content: string | Uint8Array, base: string | null }
+
+/** The source files the browser's editor lists, opens, creates and saves, as far as the member and the page's document may. */
+export class SourceEditor {
+  readonly #config: WorkspaceConfig
+  readonly #writer: DocumentWriter
+  readonly #locks?: DocumentLocks
+
+  constructor(options: SourceEditorOptions) {
+    this.#config = options.config
+    this.#writer = options.writer
+    this.#locks = options.locks
+  }
+
+  scope(document: string): Scope {
+    return { document, home: document === '' && !this.#config.singleDeck }
+  }
+
+  roots(scope: Scope): string[] {
+    if (!scope.home) return [scope.document]
+    return ['']
+  }
+
+  canEdit(scope: Scope, path: string, member: Member): boolean {
+    return this.#canEdit(scope, path, member)
+  }
+
+  #canEdit(scope: Scope, path: string, member: Member, documents?: readonly DocumentEntry[]): boolean {
+    if (path === WORKSPACE_CONFIG) return (scope.home || (this.#config.singleDeck && scope.document === '')) && member.roles.includes('owner')
+    if (scope.home && member.roles.includes('owner')) return true
+    const dir = documentDirOf(this.#config, path)
+    if (dir === undefined) return scope.home && member.roles.includes('owner')
+    return scope.home ? (documents ?? listDocumentEntries(this.#config)).some(doc => doc.dir === dir) : dir === scope.document
+  }
+
+  files(scope: Scope, member: Member): FilesAnswer {
+    const files: SourceFile[] = []
+    const documents = scope.home ? listDocumentEntries(this.#config) : undefined
+    let truncated = false
+    const walk = (dir: string, owner: string | undefined) => {
+      let names: string[]
+      try {
+        names = readdirSync(join(this.#config.root, dir)).sort()
+      } catch {
+        return
+      }
+      for (const name of names) {
+        if (HIDDEN_FROM_EDITOR.has(name) || name.startsWith('.')) continue
+        const path = dir ? `${dir}/${name}` : name
+        const found = lstatSync(join(this.#config.root, path), { throwIfNoEntry: false })
+        if (!found || found.isSymbolicLink()) continue
+        if (found.isDirectory() && (scope.home || documentDirOf(this.#config, `${path}/x`) === owner)) {
+          walk(path, owner)
+        } else if (found.isFile() && this.#canEdit(scope, path, member, documents)) {
+          if (files.length >= MAX_FILES) {
+            truncated = true
+            return
+          }
+          files.push({ path, ...BINARY.test(name) ? { binary: true as const } : {} })
+        }
+      }
+    }
+    walk(scope.home ? '' : scope.document, scope.home ? undefined : scope.document)
+    return { document: scope.document, home: scope.home, ...documents ? { documents: documents.map(doc => doc.dir) } : {}, files, ...truncated ? { truncated: true as const } : {} }
+  }
+
+  #documentHolding(path: string, documents: readonly DocumentEntry[]): DocumentEntry | undefined {
+    let found: DocumentEntry | undefined
+    for (const doc of documents) if (isWithin(path, doc.dir) && (!found || doc.dir.length > found.dir.length)) found = doc
+    return found
+  }
+
+  /** Checks path and document policy without requiring a file to exist. */
+  assertEditable(scope: Scope, path: string, member: Member): void {
+    this.#assertEditable(scope, path, member)
+  }
+
+  #assertEditable(scope: Scope, path: string, member: Member, documents?: readonly DocumentEntry[]): void {
+    if (typeof path !== 'string' || !path || path.startsWith('/') || path.includes('\\') || path.includes('\0') || path.split('/').some(part => part === '' || part === '.' || part === '..' || HIDDEN_FROM_EDITOR.has(part))) throw new RequestError(400, 'workspace-path-invalid', { path: String(path).slice(0, 500) })
+    if (!this.#canEdit(scope, path, member, documents)) throw new RequestError(403, 'workspace-file-forbidden', { path })
+  }
+
+  /** A regular file under the same path and document policy as source editing. */
+  readableFile(scope: Scope, path: string, member: Member): string {
+    return this.#readableFile(scope, path, member)
+  }
+
+  #readableFile(scope: Scope, path: string, member: Member, documents?: readonly DocumentEntry[]): string {
+    this.#assertEditable(scope, path, member, documents)
+    const file = join(this.#config.root, path)
+    let real: string
+    try {
+      real = realpathSync(file)
+    } catch {
+      throw new RequestError(404, 'workspace-file-missing', { path })
+    }
+    if (real !== file || !lstatSync(file).isFile()) throw new RequestError(403, 'workspace-file-irregular', { path })
+    return file
+  }
+
+  #readBytes(scope: Scope, path: string, member: Member, documents?: readonly DocumentEntry[]): Buffer {
+    const file = this.#readableFile(scope, path, member, documents)
+    const bytes = readFileSync(file)
+    if (bytes.byteLength > MAX_SOURCE) throw new RequestError(413, `${path} is larger than the editor opens (${MAX_SOURCE} bytes)`)
+    return bytes
+  }
+
+  read(scope: Scope, path: string, member: Member): SourceAnswer {
+    const bytes = this.#readBytes(scope, path, member)
+    if (BINARY.test(path) || bytes.includes(0)) throw new RequestError(415, `${path} is not a text file`)
+    let content: string
+    try {
+      content = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes)
+    } catch {
+      throw new RequestError(415, `${path} is not UTF-8 text`)
+    }
+    return { path, content, version: versionOf(bytes) }
+  }
+
+  async create(scope: Scope, path: string, member: Member): Promise<SourceAnswer> {
+    const documents = listDocumentEntries(this.#config)
+    this.#assertEditable(scope, path, member, documents)
+    if (path === DOCUMENT_ENTRY || path.endsWith(`/${DOCUMENT_ENTRY}`)) throw new RequestError(422, 'create-a-document-with-valid-content')
+    if (BINARY.test(path)) throw new RequestError(415, `${path} is not a text file`)
+    const document = this.#documentHolding(path, documents)?.dir
+    const scopeDir = document ?? ''
+    const release = this.#locks ? this.#locks.claim(scopeDir, 'editor:create') : () => {}
+    if (!release) throw lockedError(scopeDir, this.#locks!.holder(scopeDir)!)
+    try {
+      await this.#writer.create(path, Buffer.alloc(0), document === undefined)
+      return { path, content: '', version: versionOf('') }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'EEXIST') throw new RequestError(409, `${path} already exists`, { exists: true })
+      if (error instanceof FilesError) throw new RequestError(403, error.message)
+      throw error
+    } finally {
+      release()
+    }
+  }
+
+  /** Saves related sources as one authoring change; any failed write or commit restores all preimages. */
+  async transaction(scope: Scope, changes: SourceTransactionChange[], member: Member, history?: SourceTransactionHistory): Promise<SourceTransactionAnswer> {
+    return this.#transaction(scope, changes, member, history)
+  }
+
+  /** Checks the same scope, size, CAS and candidate rules without writing or committing. */
+  async planTransaction(scope: Scope, changes: SourceTransactionChange[], member: Member): Promise<SourceTransactionAnswer> {
+    return this.#transaction(scope, changes, member, undefined, undefined, true)
+  }
+
+  /** A validated authoring document and one new original attachment share CAS, rollback and history. */
+  async transactionWithBinary(scope: Scope, document: SourceTransactionChange, attachment: { path: string, content: Uint8Array }, member: Member, history?: SourceTransactionHistory): Promise<SourceTransactionAnswer> {
+    if (document.path !== DOCUMENT_ENTRY && !document.path.endsWith(`/${DOCUMENT_ENTRY}`) || document.base === null) throw new RequestError(400, 'document-transaction-required')
+    if (!attachment.content.byteLength || attachment.content.byteLength > 16 << 20) throw new RequestError(413, 'production.asset-size')
+    return this.#transaction(scope, [document, { ...attachment, content: new Uint8Array(attachment.content), base: null }], member, history, attachment.path)
+  }
+
+  async #transaction(scope: Scope, changes: TransactionFile[], member: Member, history?: SourceTransactionHistory, binaryPath?: string, dryRun = false): Promise<SourceTransactionAnswer> {
+    if (changes.length === 0 || changes.length > MAX_SOURCE_CHANGES) throw new RequestError(400, `a source transaction takes 1 to ${MAX_SOURCE_CHANGES} files`)
+    const paths = new Set<string>()
+    const known = listDocumentEntries(this.#config)
+    let bytes = 0
+    const documents = changes.map(change => {
+      this.#assertEditable(scope, change.path, member, known)
+      if (paths.has(change.path)) throw new RequestError(400, `a source path occurs twice: ${change.path}`)
+      paths.add(change.path)
+      if (change.path !== binaryPath) {
+        if (typeof change.content !== 'string' || BINARY.test(change.path) || change.content.includes('\0')) throw new RequestError(415, `${change.path} is not a text file`)
+        bytes += Buffer.byteLength(change.content, 'utf8')
+      }
+      return this.#documentHolding(change.path, known)
+    })
+    if (bytes > MAX_SOURCE) throw new RequestError(413, `the transaction is larger than the editor saves (${MAX_SOURCE} bytes)`)
+    for (const path of paths) if ([...paths].some(other => path !== other && path.startsWith(`${other}/`))) throw new RequestError(400, `a source file cannot also be a parent directory: ${path}`)
+    const document = documents[0]
+    if (!document || documents.some(found => found?.dir !== document.dir)) throw new RequestError(400, 'a source transaction must stay in one document')
+    const scopeDir = document.dir
+    const release = this.#locks ? this.#locks.claim(scopeDir, 'editor:transaction') : () => {}
+    if (!release) throw lockedError(scopeDir, this.#locks!.holder(scopeDir)!)
+    const work = async (): Promise<SourceTransactionAnswer> => {
+      // Read every preimage before creating directories or writing any file.
+      const snapshots = changes.map(change => {
+        const written = typeof change.content === 'string' ? Buffer.from(change.content, 'utf8') : Buffer.from(change.content)
+        if (change.base !== null) {
+          const before = this.#readBytes(scope, change.path, member, known)
+          const version = versionOf(before)
+          if (version !== change.base) throw new RequestError(409, `${change.path} changed since it was opened`, { conflict: { path: change.path, version, content: before.toString('utf8') } })
+          if (BINARY.test(change.path) || before.includes(0)) throw new RequestError(415, `${change.path} is not a text file`)
+          try { new TextDecoder('utf-8', { fatal: true }).decode(before) } catch { throw new RequestError(415, `${change.path} is not UTF-8 text`) }
+          const executable = (lstatSync(join(this.#config.root, change.path)).mode & 0o111) !== 0
+          return { path: change.path, before, written, executable }
+        }
+        const file = join(this.#config.root, change.path)
+        let parent = this.#config.root
+        for (const part of change.path.split('/').slice(0, -1)) {
+          parent = join(parent, part)
+          const found = lstatSync(parent, { throwIfNoEntry: false })
+          if (found && (!found.isDirectory() || realpathSync(parent) !== parent)) throw new RequestError(403, `${change.path} has no regular workspace parent`)
+          if (!found) break
+        }
+        if (lstatSync(file, { throwIfNoEntry: false })) throw new RequestError(409, `${change.path} already exists`, { exists: true })
+        return { path: change.path, before: undefined, written, executable: false }
+      })
+      for (const snapshot of snapshots) if (snapshot.path !== binaryPath) validateDocumentSource(snapshot.path, snapshot.written.toString('utf8'), snapshot.before)
+      if (dryRun) return { versions: snapshots.map(snapshot => ({ path: snapshot.path, version: versionOf(snapshot.written) })) }
+      const created: string[] = []
+      const edited = snapshots.filter(snapshot => snapshot.before && !snapshot.written.equals(snapshot.before))
+      const touched = snapshots.filter(snapshot => !snapshot.before || !snapshot.written.equals(snapshot.before)).map(snapshot => snapshot.path)
+      const lang = history && touched.length ? readDocumentSummary(this.#config, document).lang : undefined
+      const write = (next: DocumentFileChange[]) => this.#writer.write(next)
+      try {
+        // Exclusive creation prevents replacing a file created outside serve after validation.
+        for (const snapshot of snapshots) if (!snapshot.before) {
+          await this.#writer.create(snapshot.path, snapshot.written)
+          created.push(snapshot.path)
+        }
+        if (edited.length) await write(edited.map(snapshot => ({ path: snapshot.path, content: snapshot.written, ...snapshot.executable ? { executable: true } : {} })))
+        const revision = history && touched.length ? await history.commit(touched, lang) : undefined
+        return { versions: snapshots.map(snapshot => ({ path: snapshot.path, version: versionOf(snapshot.written) })), ...revision ? { revision } : {} }
+      } catch (error) {
+        try {
+          await write([
+            ...snapshots.flatMap(snapshot => snapshot.before ? [{ path: snapshot.path, content: snapshot.before, ...snapshot.executable ? { executable: true } : {} }] : []),
+            ...created.map(path => ({ path, remove: true as const })),
+          ])
+        } catch (rollback) {
+          throw new Error(`source transaction failed (${error instanceof Error ? error.message : String(error)}); restoring sources also failed (${rollback instanceof Error ? rollback.message : String(rollback)})`)
+        }
+        throw error
+      }
+    }
+    try {
+      return await (history ? history.run(work) : work())
+    } finally {
+      release()
+    }
+  }
+
+  /**
+   * Writes the text over the version the editor opened. `commit` makes a change a revision while the document's lock
+   * is still held; when it fails, the file is put back as it was and the save fails.
+   */
+  async save(scope: Scope, path: string, content: string, base: string, member: Member, commit?: (path: string, lang: string | undefined) => Promise<Revision | undefined>): Promise<SavedAnswer> {
+    const documents = listDocumentEntries(this.#config)
+    const document = this.#documentHolding(path, documents)
+    const outside = document === undefined
+    const scopeDir = document?.dir ?? ''
+    const release = this.#locks ? this.#locks.claim(scopeDir, 'editor:save') : () => {}
+    if (!release) throw lockedError(scopeDir, this.#locks!.holder(scopeDir)!)
+    try {
+      const bytes = this.#readBytes(scope, path, member, documents)
+      const now = versionOf(bytes)
+      if (now !== base) {
+        const conflict: Omit<ConflictAnswer, 'error'> = { conflict: { version: now, content: bytes.toString('utf8') } }
+        throw new RequestError(409, `${path} changed since it was opened`, conflict)
+      }
+      const written = Buffer.from(content, 'utf8')
+      validateDocumentSource(path, content, bytes)
+      if (written.byteLength > MAX_SOURCE) throw new RequestError(413, `the text is larger than the editor saves (${MAX_SOURCE} bytes)`)
+      const change: DocumentFileChange = { path, content: written, ...(lstatSync(join(this.#config.root, path)).mode & 0o111) !== 0 ? { executable: true } : {} }
+      const lang = commit && !written.equals(bytes) && document ? readDocumentSummary(this.#config, document).lang : undefined
+      const write = async (next: DocumentFileChange) => (outside ? writeChanges(this.#config, [next], true) : await this.#writer.write([next]))
+      await write(change)
+      let revision: Revision | undefined
+      if (commit && !written.equals(bytes)) {
+        try {
+          revision = await commit(path, lang)
+        } catch (error) {
+          await write({ ...change, content: bytes })
+          throw error
+        }
+      }
+      return { version: versionOf(written), ...revision ? { revision } : {} }
+    } finally {
+      release()
+    }
+  }
+}

package/src/node/speech-settings.ts

@@ -0,0 +1,21 @@
+import { isRecord, jsonResponse, problemResponse } from '@lincyaw/kernel'
+import type { Route, SpeechSettingsChange } from '@lincyaw/kernel'
+import { OperatorSpeechSettings, SpeechSettingsError } from '@lincyaw/kernel/node'
+
+/** Global operator route: works before opening a document and never returns credential values. */
+export function speechSettingsRoute(directory: string, fallback: (name: string) => string | undefined): Route {
+  const settings = new OperatorSpeechSettings(directory, fallback)
+  return { role: 'owner', maxBody: 16384, handle: async request => {
+    try {
+      if (request.method === 'GET') return jsonResponse(settings.read(), 200, { 'cache-control': 'no-store' })
+      if (request.method !== 'POST') return problemResponse(405, 'GET or POST')
+      const body: unknown = await request.json().catch(() => undefined)
+      if (!isRecord(body) || typeof body.revision !== 'string' || !['save', 'clear'].includes(String(body.action)) || Object.keys(body).some(key => !['action', 'revision', 'apiKey', 'appId'].includes(key))
+        || body.action === 'save' && (body.apiKey !== undefined && typeof body.apiKey !== 'string' || body.appId !== undefined && typeof body.appId !== 'string')) return problemResponse(400, 'speech-settings-invalid')
+      return jsonResponse(await settings.change(body as unknown as SpeechSettingsChange), 200, { 'cache-control': 'no-store' })
+    } catch (error) {
+      const code = error instanceof SpeechSettingsError ? error.code : 'speech-settings-unavailable'
+      return problemResponse(code === 'speech-settings-invalid' ? 400 : code === 'speech-settings-conflict' || code === 'speech-settings-busy' ? 409 : 503, code)
+    }
+  } }
+}

package/src/node/templates.ts

@@ -0,0 +1,27 @@
+import { existsSync, lstatSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { WorkspaceConfig } from './config.ts'
+
+const BUILTIN_TEMPLATES = fileURLToPath(new URL('../../templates/document', import.meta.url))
+
+export const DEFAULT_TEMPLATE = 'default'
+
+function templatesDir(config: WorkspaceConfig): string {
+  return config.templates ?? BUILTIN_TEMPLATES
+}
+
+export function listTemplates(config: WorkspaceConfig): string[] {
+  const dir = templatesDir(config)
+  try {
+    return readdirSync(dir).filter(name => statSync(join(dir, name)).isDirectory()).sort()
+  } catch {
+    return []
+  }
+}
+
+export function findTemplate(config: WorkspaceConfig, name: string): string | undefined {
+  if (!name || name.includes('/') || name.includes('\\') || name.startsWith('.')) return undefined
+  const dir = join(templatesDir(config), name)
+  return existsSync(dir) && lstatSync(dir, { throwIfNoEntry: false })?.isDirectory() ? dir : undefined
+}