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

package/src/node/config.ts

@@ -0,0 +1,126 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { DECK_ENTRY, readFrontmatter, WORKSPACE_CONFIG } from '@lincyaw/compiler'
+import type { OperatorSettings } from '@lincyaw/compiler'
+import { errorMessage, isRecord } from '@lincyaw/kernel'
+import type { ApprovalKind } from '@lincyaw/kernel'
+import type { ApprovalPolicy } from '@lincyaw/server'
+import { parse as parseYaml } from 'yaml'
+import type { WorkspaceDocument } from '../domain/api.ts'
+import { matchesPattern, patternSegments } from '../domain/paths.ts'
+
+export const DEFAULT_DOCUMENTS = [`*/${DECK_ENTRY}`]
+
+const SKIPPED = new Set(['node_modules', '.git', '.presmium', 'dist'])
+
+const KINDS: ApprovalKind[] = ['operate', 'spend', 'write', 'agent']
+const POLICIES = new Set<ApprovalPolicy>(['off', 'ask', 'allow'])
+
+export interface WorkspaceConfig {
+  root: string
+  title: string
+  documents: string[]
+  single: boolean
+  site: Record<string, unknown>
+  approvals: Partial<Record<ApprovalKind, ApprovalPolicy>>
+  templates?: string
+  settings: OperatorSettings
+}
+
+function strings(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string' && v.trim() !== '').map(v => v.trim()) : typeof value === 'string' && value.trim() ? [value.trim()] : []
+}
+
+export function readWorkspace(root: string): WorkspaceConfig {
+  const dir = realpathSync(resolve(root))
+  const file = join(dir, WORKSPACE_CONFIG)
+  let data: Record<string, unknown> = {}
+  if (existsSync(file)) {
+    try {
+      const parsed: unknown = parseYaml(readFileSync(file, 'utf8'))
+      data = isRecord(parsed) ? parsed : {}
+    } catch (error) {
+      throw new Error(`${file}: ${errorMessage(error)}`)
+    }
+  }
+  const declared = strings(data.documents)
+  const single = declared.length === 0 && existsSync(join(dir, DECK_ENTRY))
+  const approvals = isRecord(data.approvals) ? data.approvals : {}
+  const settings = isRecord(data.settings) ? data.settings : {}
+  return {
+    root: dir,
+    title: typeof data.title === 'string' && data.title.trim() ? data.title.trim() : dir.split('/').at(-1) ?? 'Presmium',
+    documents: single ? [DECK_ENTRY] : declared.length > 0 ? declared : DEFAULT_DOCUMENTS,
+    single,
+    site: isRecord(data.site) ? data.site : {},
+    approvals: Object.fromEntries(KINDS.flatMap(kind => (POLICIES.has(approvals[kind] as ApprovalPolicy) ? [[kind, approvals[kind] as ApprovalPolicy]] : []))),
+    ...typeof data.templates === 'string' && data.templates.trim() ? { templates: resolve(dir, data.templates.trim()) } : {},
+    settings: Object.fromEntries(Object.entries(settings).map(([id, value]) => [id, isRecord(value) ? value : {}])),
+  }
+}
+
+export function isWorkspaceRoot(dir: string): boolean {
+  if (!existsSync(join(dir, WORKSPACE_CONFIG))) return false
+  try {
+    return !readWorkspace(dir).single
+  } catch {
+    return true
+  }
+}
+
+function entries(config: WorkspaceConfig): string[] {
+  const found: string[] = []
+  for (const pattern of config.documents) {
+    const parts = patternSegments(pattern)
+    const walk = (dir: string, rel: string, i: number): string[] => {
+      const part = parts[i]!
+      const last = i === parts.length - 1
+      const names = typeof part === 'string'
+        ? [part]
+        : (() => {
+            try {
+              return readdirSync(dir).filter(name => !SKIPPED.has(name) && !name.startsWith('.') && part.test(name)).sort()
+            } catch {
+              return []
+            }
+          })()
+      return names.flatMap((name) => {
+        const path = join(dir, name)
+        const next = rel ? `${rel}/${name}` : name
+        if (last) return existsSync(path) && statSync(path).isFile() ? [next] : []
+        return existsSync(path) && statSync(path).isDirectory() ? walk(path, next, i + 1) : []
+      })
+    }
+    for (const entry of walk(config.root, '', 0)) if (!found.includes(entry)) found.push(entry)
+  }
+  return found
+}
+
+export interface FoundDocument extends WorkspaceDocument {
+  entry: string
+}
+
+function documentOf(config: WorkspaceConfig, entry: string): FoundDocument {
+  const dir = entry.split('/').slice(0, -1).join('/')
+  let headmatter: Record<string, unknown> = {}
+  try {
+    headmatter = readFrontmatter(readFileSync(join(config.root, entry), 'utf8'))
+  } catch {
+  }
+  const tags = strings(headmatter.tags)
+  return {
+    dir,
+    entry,
+    title: typeof headmatter.title === 'string' && headmatter.title.trim() ? headmatter.title.trim() : dir || config.title,
+    ...typeof headmatter.lang === 'string' && headmatter.lang.trim() ? { lang: headmatter.lang.trim() } : {},
+    ...tags.length > 0 ? { tags } : {},
+  }
+}
+
+export function listDocuments(config: WorkspaceConfig): FoundDocument[] {
+  return entries(config).map(entry => documentOf(config, entry))
+}
+
+export function namedByPatterns(config: WorkspaceConfig, dir: string): boolean {
+  return config.documents.some(pattern => matchesPattern(pattern, dir ? `${dir}/${DECK_ENTRY}` : DECK_ENTRY))
+}

package/src/node/documents.ts

@@ -0,0 +1,185 @@
+import { existsSync, mkdirSync, readdirSync, renameSync, rmdirSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { Member } from '@lincyaw/kernel'
+import type { DocumentOperation, LockedAnswer, OperationAnswer, WorkspaceDocument } from '../domain/api.ts'
+import { invalidDocumentDir, within } from '../domain/paths.ts'
+import type { CommitOrigin, RevisionOperation } from '../domain/revisions.ts'
+import { listDocuments, namedByPatterns } from './config.ts'
+import type { WorkspaceConfig } from './config.ts'
+import { templatesDir } from './files.ts'
+import type { DocumentWriter } from './files.ts'
+import type { Git } from './git.ts'
+import { lockedMessage } from './locks.ts'
+import type { DocumentLocks } from './locks.ts'
+import type { Revisions } from './revisions.ts'
+
+export { BUILTIN_TEMPLATES } from './files.ts'
+export const DEFAULT_TEMPLATE = 'default'
+
+export class RequestError extends Error {
+  readonly status: number
+  readonly detail?: Record<string, unknown>
+  constructor(status: number, message: string, detail?: Record<string, unknown>) {
+    super(message)
+    this.status = status
+    this.detail = detail
+  }
+}
+
+export function lockedError(document: string, holder: string): RequestError {
+  return new RequestError(409, lockedMessage(document, holder), { locked: { document, holder } } satisfies Omit<LockedAnswer, 'error'>)
+}
+
+export function makeDocumentDir(root: string, dir: string): void {
+  const path = join(root, dir)
+  mkdirSync(dirname(path), { recursive: true })
+  mkdirSync(path)
+}
+
+export interface DocumentsChange {
+  removed: string[]
+  added: string[]
+}
+
+export interface DocumentsOptions {
+  config: WorkspaceConfig
+  git: Git
+  revisions: Revisions
+  writer: DocumentWriter
+  changed?: (change: DocumentsChange) => void | Promise<void>
+  locks?: DocumentLocks
+}
+
+function touched(operation: DocumentOperation): string[] {
+  return operation.op === 'create' || operation.op === 'delete' ? [operation.dir] : [operation.dir, operation.to]
+}
+
+export class Documents {
+  readonly config: WorkspaceConfig
+  readonly #git: Git
+  readonly #revisions: Revisions
+  readonly #writer: DocumentWriter
+  readonly #changed: (change: DocumentsChange) => void | Promise<void>
+  readonly #locks?: DocumentLocks
+
+  constructor(options: DocumentsOptions) {
+    this.config = options.config
+    this.#git = options.git
+    this.#revisions = options.revisions
+    this.#writer = options.writer
+    this.#changed = options.changed ?? (() => {})
+    this.#locks = options.locks
+  }
+
+  get writer(): DocumentWriter {
+    return this.#writer
+  }
+
+  get locks(): DocumentLocks | undefined {
+    return this.#locks
+  }
+
+  list(): WorkspaceDocument[] {
+    return listDocuments(this.config).map(({ entry: _entry, ...document }) => document)
+  }
+
+  get templatesDir(): string {
+    return templatesDir(this.config)
+  }
+
+  templates(): string[] {
+    try {
+      return readdirSync(this.templatesDir).filter(name => statSync(join(this.templatesDir, name)).isDirectory()).sort()
+    } catch {
+      return []
+    }
+  }
+
+  async apply(operation: DocumentOperation, member: Member): Promise<OperationAnswer> {
+    if (this.config.single) throw new RequestError(409, 'this workspace is a single deck: it has no document operations')
+    const claimed = this.#locks?.claimAll(touched(operation), `document:${operation.op}`)
+    if (claimed && 'holder' in claimed) throw lockedError(claimed.document, claimed.holder)
+    try {
+      const answer = await this.#git.exclusive(() => this.#apply(operation, member))
+      const added = operation.op === 'delete' ? [] : [answer.dir!]
+      const removed = operation.op === 'rename' || operation.op === 'delete' ? [operation.dir] : []
+      await this.#changed({ removed, added })
+      return answer
+    } finally {
+      claimed?.release()
+    }
+  }
+
+  async #fill(dir: string, fill: () => Promise<void>): Promise<void> {
+    makeDocumentDir(this.config.root, dir)
+    try {
+      await fill()
+    } catch (error) {
+      await this.#remove(dir).catch(() => undefined)
+      throw error
+    }
+  }
+
+  async #remove(dir: string): Promise<void> {
+    for (let attempt = 0; ; attempt++) {
+      await this.#writer.empty(dir)
+      try {
+        rmdirSync(join(this.config.root, dir))
+        return
+      } catch (error) {
+        if (attempt > 0 || (error as NodeJS.ErrnoException).code !== 'ENOTEMPTY') throw new RequestError(409, `${dir} could not be removed: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
+  }
+
+  async #apply(operation: DocumentOperation, member: Member): Promise<OperationAnswer> {
+    const origin = (done: RevisionOperation): CommitOrigin => ({ kind: 'document', member, operation: done })
+    const known = listDocuments(this.config).map(doc => doc.dir)
+    const existing = (dir: string) => {
+      if (!known.includes(dir)) throw new RequestError(404, `no document ${JSON.stringify(dir)}`)
+      return dir
+    }
+    const fresh = (dir: string) => {
+      const invalid = invalidDocumentDir(dir)
+      if (invalid) throw new RequestError(400, invalid)
+      if (!namedByPatterns(this.config, dir)) throw new RequestError(400, `"${dir}" is not where the workspace configuration's documents are (${this.config.documents.join(', ')})`)
+      const holder = known.find(doc => doc !== '' && (within(dir, doc) || within(doc, dir)))
+      if (holder !== undefined) throw new RequestError(409, `${dir} would hold or be inside the document ${holder}`)
+      if (existsSync(join(this.config.root, dir))) throw new RequestError(409, `${dir} exists already`)
+      return dir
+    }
+    switch (operation.op) {
+      case 'create': {
+        const dir = fresh(operation.dir)
+        const name = operation.template ?? (this.templates().includes(DEFAULT_TEMPLATE) ? DEFAULT_TEMPLATE : this.templates()[0])
+        if (!name || !this.templates().includes(name)) throw new RequestError(400, `no document template ${JSON.stringify(name ?? '')}`)
+        const title = operation.title?.trim() || dir.split('/').at(-1)!
+        await this.#fill(dir, () => this.#writer.template(dir, name, title))
+        const revision = await this.#revisions.commitNow([dir], `Create document ${dir}`, `Title: ${title}\nTemplate: ${name}`, origin({ op: 'create', dir }))
+        return { revision, dir }
+      }
+      case 'rename': {
+        const from = existing(operation.dir)
+        const to = fresh(operation.to)
+        mkdirSync(dirname(join(this.config.root, to)), { recursive: true })
+        renameSync(join(this.config.root, from), join(this.config.root, to))
+        const rewritten = (await this.#writer.relink(from, to)).filter(path => !within(path, to))
+        const revision = await this.#revisions.commitNow([from, to, ...rewritten], `Rename document ${from} to ${to}`, rewritten.length ? `Links rewritten in: ${rewritten.join(', ')}` : '', origin({ op: 'rename', dir: from, to }))
+        return { revision, dir: to }
+      }
+      case 'copy': {
+        const from = existing(operation.dir)
+        const to = fresh(operation.to)
+        await this.#fill(to, () => this.#writer.copy(from, to))
+        const revision = await this.#revisions.commitNow([to], `Copy document ${from} to ${to}`, '', origin({ op: 'copy', dir: from, to }))
+        return { revision, dir: to }
+      }
+      case 'delete': {
+        const dir = existing(operation.dir)
+        await this.#remove(dir)
+        const revision = await this.#revisions.commitNow([dir], `Delete document ${dir}`, '', origin({ op: 'delete', dir }))
+        return { revision }
+      }
+    }
+  }
+}

package/src/node/files.ts

@@ -0,0 +1,252 @@
+import { randomBytes } from 'node:crypto'
+import { closeSync, constants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, renameSync, rmdirSync, rmSync, symlinkSync, writeFileSync, writeSync } from 'node:fs'
+import type { Stats } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { DocumentFileChange, DocumentFiles } from '@lincyaw/kernel'
+import { rewriteLinks, within } from '../domain/paths.ts'
+import { listDocuments, namedByPatterns } from './config.ts'
+import type { WorkspaceConfig } from './config.ts'
+
+export const BUILTIN_TEMPLATES = fileURLToPath(new URL('../../templates/document', import.meta.url))
+
+const NOT_SOURCE = new Set(['node_modules', 'dist', '.git'])
+
+export class FilesError extends Error {}
+
+export interface DocumentWriter extends DocumentFiles {
+  template(dir: string, template: string, title: string): Promise<void>
+  copy(from: string, to: string): Promise<void>
+  relink(from: string, to: string): Promise<string[]>
+  empty(dir: string): Promise<void>
+}
+
+function partsOf(path: unknown): string[] {
+  if (typeof path !== 'string' || !path || path.includes('\0') || path.startsWith('/')) throw new FilesError(`not a path in the workspace: ${JSON.stringify(path)}`)
+  const parts = path.split('/')
+  if (parts.some(part => part === '' || part === '.' || part === '..')) throw new FilesError(`not a plain path: ${path}`)
+  if (parts.some(part => part.toLowerCase() === '.git')) throw new FilesError(`a path in a git directory: ${path}`)
+  return parts
+}
+
+function stat(path: string): Stats | undefined {
+  try {
+    return lstatSync(path)
+  } catch {
+    return undefined
+  }
+}
+
+function realDirectory(root: string, dir: string): boolean {
+  let current = root
+  for (const part of dir ? dir.split('/') : []) {
+    current = join(current, part)
+    if (!stat(current)?.isDirectory()) return false
+  }
+  return stat(current)?.isDirectory() ?? false
+}
+
+export function documentDirOf(config: WorkspaceConfig, path: string): string | undefined {
+  const parts = path.split('/')
+  for (let i = parts.length - 1; i >= 0; i--) {
+    const dir = parts.slice(0, i).join('/')
+    if (namedByPatterns(config, dir)) return dir
+  }
+  return undefined
+}
+
+function documentDir(config: WorkspaceConfig, dir: string): string {
+  if (dir !== '') partsOf(dir)
+  if (!namedByPatterns(config, dir)) throw new FilesError(`${dir || '.'} is not a document directory of this workspace`)
+  if (!realDirectory(config.root, dir)) throw new FilesError(`the document directory ${dir || '.'} is not there`)
+  return dir
+}
+
+function madeParent(root: string, base: string, parts: string[]): string {
+  let current = join(root, base)
+  const start = base ? base.split('/').length : 0
+  for (const part of parts.slice(start, -1)) {
+    current = join(current, part)
+    const found = stat(current)
+    if (found?.isDirectory()) continue
+    if (found) rmSync(current, { force: true })
+    mkdirSync(current)
+  }
+  return current
+}
+
+function existingParent(root: string, base: string, parts: string[]): string | undefined {
+  let current = join(root, base)
+  const start = base ? base.split('/').length : 0
+  for (const part of parts.slice(start, -1)) {
+    current = join(current, part)
+    if (!stat(current)?.isDirectory()) return undefined
+  }
+  return current
+}
+
+function replace(parent: string, target: string, make: (temporary: string) => void): void {
+  const temporary = join(parent, `.presmium-write-${randomBytes(6).toString('hex')}`)
+  make(temporary)
+  try {
+    const found = stat(target)
+    if (found?.isDirectory()) rmSync(target, { recursive: true, force: true })
+    renameSync(temporary, target)
+  } catch (error) {
+    rmSync(temporary, { force: true })
+    throw error
+  }
+}
+
+function prune(root: string, base: string, from: string): void {
+  const top = join(root, base)
+  for (let dir = from; dir !== top && dir.startsWith(`${top}/`); dir = join(dir, '..')) {
+    try {
+      if (readdirSync(dir).length > 0) return
+      rmdirSync(dir)
+    } catch {
+      return
+    }
+  }
+}
+
+function apply(root: string, base: string, change: DocumentFileChange): void {
+  const parts = partsOf(change.path)
+  const name = parts.at(-1)!
+  if ('remove' in change) {
+    const parent = existingParent(root, base, parts)
+    if (!parent || !stat(join(parent, name))) return
+    rmSync(join(parent, name), { recursive: true, force: true })
+    prune(root, base, parent)
+    return
+  }
+  const parent = madeParent(root, base, parts)
+  const target = join(parent, name)
+  if ('link' in change) {
+    if (typeof change.link !== 'string' || !change.link || change.link.includes('\0')) throw new FilesError(`not a link target: ${change.path}`)
+    replace(parent, target, temporary => symlinkSync(change.link, temporary))
+    return
+  }
+  if (change.at !== undefined) {
+    writeAt(parent, target, change.content, change.at)
+    return
+  }
+  replace(parent, target, temporary => writeFileSync(temporary, change.content, { flag: 'wx', mode: change.executable ? 0o777 : 0o666 }))
+}
+
+function writeAt(parent: string, target: string, content: Uint8Array, at: number): void {
+  if (!Number.isSafeInteger(at) || at < 0) throw new FilesError(`not a position in a file: ${at}`)
+  if (!stat(target)?.isFile()) replace(parent, target, temporary => writeFileSync(temporary, '', { flag: 'wx', mode: 0o666 }))
+  const fd = openSync(target, constants.O_WRONLY | constants.O_NOFOLLOW)
+  try {
+    const size = fstatSync(fd).size
+    if (at > size) throw new FilesError(`position ${at} is past the end of the file (${size} bytes)`)
+    writeSync(fd, content, 0, content.byteLength, at)
+  } finally {
+    closeSync(fd)
+  }
+}
+
+export function writeChanges(config: WorkspaceConfig, changes: DocumentFileChange[], outside = false): void {
+  const targets = changes.map((change) => {
+    const parts = partsOf(change.path)
+    const dir = documentDirOf(config, parts.join('/'))
+    if (dir === undefined && !outside) throw new FilesError(`${change.path} is in no document directory`)
+    if (dir !== undefined) documentDir(config, dir)
+    return { change, base: dir ?? '' }
+  })
+  for (const { change, base } of targets) if ('remove' in change) apply(config.root, base, change)
+  for (const { change, base } of targets) if (!('remove' in change)) apply(config.root, base, change)
+}
+
+const DECK_CONTENT = new Set(['freeze', 'drawings', 'assets', 'speech', 'speech.lock.json', 'anchors.lock.json'])
+
+export function generatedPath(path: string): boolean {
+  const parts = path.split('/')
+  const at = parts.indexOf('.presmium')
+  return at >= 0 && !DECK_CONTENT.has(parts[at + 1] ?? '')
+}
+
+function sourceEntries(dir: string): { path: string, link?: string, executable?: boolean }[] {
+  const out: { path: string, link?: string, executable?: boolean }[] = []
+  const walk = (current: string, rel: string) => {
+    for (const name of readdirSync(current).sort()) {
+      if (NOT_SOURCE.has(name)) continue
+      if (rel === '.presmium' && !DECK_CONTENT.has(name)) continue
+      const path = join(current, name)
+      const entry = rel ? `${rel}/${name}` : name
+      const found = stat(path)
+      if (!found) continue
+      if (found.isSymbolicLink()) out.push({ path: entry, link: readlinkSync(path) })
+      else if (found.isDirectory()) walk(path, entry)
+      else if (found.isFile()) out.push({ path: entry, executable: (found.mode & 0o111) !== 0 })
+    }
+  }
+  if (stat(dir)?.isDirectory()) walk(dir, '')
+  return out
+}
+
+export function templatesDir(config: WorkspaceConfig): string {
+  return config.templates ?? BUILTIN_TEMPLATES
+}
+
+export function templateOf(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) && stat(dir)?.isDirectory() ? dir : undefined
+}
+
+export function fromTemplate(config: WorkspaceConfig, dir: string, template: string, title: string): void {
+  documentDir(config, dir)
+  const source = templateOf(config, template)
+  if (!source) throw new FilesError(`no document template ${JSON.stringify(template)}`)
+  const quoted = JSON.stringify(title).slice(1, -1)
+  writeChanges(config, sourceEntries(source).filter(entry => entry.link === undefined).map(({ path, executable }) => {
+    const content = readFileSync(join(source, path))
+    return { path: `${dir}/${path}`, content: path.endsWith('.md') ? Buffer.from(content.toString('utf8').replaceAll('{{title}}', () => quoted)) : content, ...executable ? { executable } : {} }
+  }))
+}
+
+export function copyDocument(config: WorkspaceConfig, from: string, to: string): void {
+  documentDir(config, from)
+  documentDir(config, to)
+  writeChanges(config, sourceEntries(join(config.root, from)).map(({ path, link, executable }): DocumentFileChange => {
+    if (link !== undefined) return { path: `${to}/${path}`, link }
+    const content = readFileSync(join(config.root, from, path))
+    if (path.endsWith('.md')) return { path: `${to}/${path}`, content: Buffer.from(rewriteLinks(content.toString('utf8'), `${to}/${path}`, `${from}/${path}`, from, to)) }
+    return { path: `${to}/${path}`, content, ...executable ? { executable } : {} }
+  }))
+}
+
+export function relinkDocuments(config: WorkspaceConfig, from: string, to: string): string[] {
+  const changes: DocumentFileChange[] = []
+  for (const doc of listDocuments(config)) {
+    if (!realDirectory(config.root, doc.dir)) continue
+    for (const entry of sourceEntries(join(config.root, doc.dir))) {
+      if (entry.link !== undefined || !entry.path.endsWith('.md')) continue
+      const path = doc.dir ? `${doc.dir}/${entry.path}` : entry.path
+      const was = within(path, to) ? `${from}${path.slice(to.length)}` : path
+      const text = readFileSync(join(config.root, path), 'utf8')
+      const next = rewriteLinks(text, path, was, from, to)
+      if (next !== text) changes.push({ path, content: Buffer.from(next) })
+    }
+  }
+  writeChanges(config, changes)
+  return changes.map(change => change.path)
+}
+
+export function emptyDocument(config: WorkspaceConfig, dir: string): void {
+  documentDir(config, dir)
+  const path = join(config.root, dir)
+  for (const name of readdirSync(path)) rmSync(join(path, name), { recursive: true, force: true })
+}
+
+export function localWriter(config: WorkspaceConfig): DocumentWriter {
+  return {
+    write: async changes => writeChanges(config, changes),
+    template: async (dir, template, title) => fromTemplate(config, dir, template, title),
+    copy: async (from, to) => copyDocument(config, from, to),
+    relink: async (from, to) => relinkDocuments(config, from, to),
+    empty: async dir => emptyDocument(config, dir),
+  }
+}

package/src/node/git.ts

@@ -0,0 +1,68 @@
+import { execFile, execFileSync } from 'node:child_process'
+import { realpathSync } from 'node:fs'
+import { gitConfigArgs, gitEnvironment } from '@lincyaw/kernel'
+
+export interface GitResult {
+  code: number
+  stdout: Buffer
+  stderr: string
+}
+
+export class Git {
+  readonly root: string
+  readonly top: string
+  #queue: Promise<unknown> = Promise.resolve()
+
+  constructor(root: string) {
+    this.root = root
+    this.top = realpathSync(execFileSync('git', [...gitConfigArgs(), 'rev-parse', '--show-toplevel'], { cwd: root, encoding: 'utf8', env: gitEnvironment(process.env) }).trim())
+  }
+
+  static isRepository(root: string): boolean {
+    try {
+      return execFileSync('git', [...gitConfigArgs(), 'rev-parse', '--is-inside-work-tree'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: gitEnvironment(process.env) }).trim() === 'true'
+    } catch {
+      return false
+    }
+  }
+
+  static ignores(dir: string, path: string): boolean {
+    try {
+      execFileSync('git', [...gitConfigArgs(), 'check-ignore', '-q', '--', path], { cwd: dir, stdio: 'ignore', env: gitEnvironment(process.env) })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  run(command: string[], env: Record<string, string> = {}): Promise<GitResult> {
+    return new Promise((done) => {
+      execFile('git', [...gitConfigArgs(), ...command], {
+        cwd: this.root,
+        encoding: 'buffer',
+        maxBuffer: 1 << 30,
+        env: { ...gitEnvironment(process.env), ...env },
+      }, (error, stdout, stderr) => {
+        const code = !error ? 0 : typeof error.code === 'number' ? error.code : 1
+        done({ code, stdout, stderr: stderr.toString('utf8') })
+      })
+    })
+  }
+
+  async raw(command: string[], env?: Record<string, string>): Promise<string> {
+    const result = await this.run(command, env)
+    if (result.code !== 0) throw new Error(result.stderr.trim() || `git ${command[0]} exited with ${result.code}`)
+    return result.stdout.toString('utf8')
+  }
+
+  async attempt(command: string[], env?: Record<string, string>): Promise<{ ok: boolean, output: string }> {
+    const result = await this.run(command, env)
+    return { ok: result.code === 0, output: result.code === 0 ? result.stdout.toString('utf8') : `${result.stderr}${result.stdout.toString('utf8')}` }
+  }
+
+  exclusive<T>(work: () => Promise<T>): Promise<T> {
+    const next = this.#queue.then(work, work)
+    this.#queue = next.catch(() => undefined)
+    return next
+  }
+}

package/src/node/locks.ts

@@ -0,0 +1,41 @@
+import type { DocumentLockService } from '@lincyaw/kernel'
+import { lockKind } from '../domain/api.ts'
+
+export class DocumentLocks implements DocumentLockService {
+  readonly #held = new Map<string, string>()
+
+  claim(document: string, holder: string): (() => void) | undefined {
+    if (this.#held.has(document)) return undefined
+    this.#held.set(document, holder)
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      this.#held.delete(document)
+    }
+  }
+
+  holder(document: string): string | undefined {
+    return this.#held.get(document)
+  }
+
+  claimAll(documents: string[], holder: string): { release(): void } | { document: string, holder: string } {
+    const releases: (() => void)[] = []
+    for (const document of new Set(documents)) {
+      const release = this.claim(document, holder)
+      if (release) {
+        releases.push(release)
+        continue
+      }
+      for (const taken of releases) taken()
+      return { document, holder: this.holder(document)! }
+    }
+    return { release: () => releases.forEach(release => release()) }
+  }
+}
+
+export function lockedMessage(document: string, holder: string): string {
+  const kind = lockKind(holder)
+  const what = kind === 'agent' ? 'an agent\'s change task runs or waits for its review' : kind === 'revert' ? 'a change is being undone' : 'a document operation is under way'
+  return `${document || 'the document'} cannot change now: ${what} (${holder}); try again once it is done`
+}