@cmodjs/core 0.1.14 → 0.2.1

package/src/runtime/options.ts

@@ -0,0 +1,102 @@
+import type { PluginOptions } from 'claude-code'
+import { fitsOption, isUnset, type Option, type Options } from '../options.js'
+import { configFolders } from '../records.js'
+import { listed, messageOf } from '../utils/text.js'
+import type { Claude } from './claude.js'
+
+export class MissingOptions extends Error {
+  readonly keys: readonly string[]
+  readonly titles: readonly string[]
+
+  constructor(keys: readonly string[], titles: readonly string[]) {
+    super(`it needs ${listed(titles)}`)
+    this.keys = keys
+    this.titles = titles
+  }
+}
+
+export type ModOptions = {
+  readonly values: Readonly<Record<string, unknown>>
+  readonly missing: readonly string[]
+  load(root: string): Promise<void>
+}
+
+export function createOptions({ name, declared, fromClaude, claude, changed }: { readonly name: string; readonly declared: Options; readonly fromClaude: PluginOptions; readonly claude: Claude; readonly changed: () => void }): ModOptions {
+  let values: Readonly<Record<string, unknown>> = merged(declared, fromClaude, {}, new Set())
+  let locked: Set<string> | undefined
+  let loadedRoot: string | undefined
+
+  const readLocked = async () => {
+    if (Object.keys(declared).length === 0) return new Set<string>()
+    const rows = await claude.config.list().catch((error: unknown) => {
+      claude.ui.log(`${name} could not read /config, so a project's options.json may override a value your organization set: ${messageOf(error)}`, { to: 'debug' })
+      return []
+    })
+    return new Set(rows.filter((row) => row.isLocked && row.key.startsWith(`${name}.`)).map((row) => row.key.slice(name.length + 1)))
+  }
+
+  const readProject = async (root: string): Promise<Record<string, unknown>> => {
+    const env = { HOME: await claude.env.home(), CLAUDE_CONFIG_DIR: await claude.env.configHome() }
+    const project = configFolders(env, name, root).find(({ tier }) => tier === 'project')
+    if (project === undefined) return {}
+    const path = `${project.folder}/options.json`
+    if (!(await claude.fs.exists(path))) return {}
+    const ignore = (reason: string) => claude.ui.log(`${path} ${reason}`)
+    let file: unknown
+    try {
+      file = JSON.parse(await claude.fs.read(path))
+    } catch (error) {
+      ignore(`is not JSON (${messageOf(error)}). Fix the file; ${name} uses its other options until then.`)
+      return {}
+    }
+    if (typeof file !== 'object' || file === null || Array.isArray(file)) {
+      ignore('is not a JSON object. Write one, such as { "branch": "main" }.')
+      return {}
+    }
+    const kept: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(file)) {
+      const option = declared[key]
+      if (option === undefined) ignore(`sets ${key}, which ${name} does not declare. ${Object.keys(declared).length === 0 ? 'Remove it.' : `Remove it, or use one of: ${Object.keys(declared).join(', ')}.`}`)
+      else if (option.kind === 'secret') ignore(`sets ${key}, a secret, and a project file is committed for everyone to read. Remove it, and set it in /config.`)
+      else {
+        const misfit = fitsOption(option, value)
+        if (misfit === undefined) kept[key] = value
+        else ignore(`sets ${key} to ${JSON.stringify(value)}, and ${option.title} ${misfit}.`)
+      }
+    }
+    return kept
+  }
+
+  return {
+    get values() {
+      return values
+    },
+    get missing() {
+      return Object.entries(declared)
+        .filter(([key, option]) => option.default === undefined && isUnset(values[key]))
+        .map(([key]) => key)
+    },
+    async load(root) {
+      if (Object.keys(declared).length === 0) return
+      locked ??= await readLocked()
+      const project = await readProject(root)
+      const isFirst = loadedRoot === undefined
+      loadedRoot = root
+      const next = merged(declared, fromClaude, project, locked)
+      if (!isFirst && JSON.stringify(next) === JSON.stringify(values)) return
+      values = next
+      if (!isFirst) changed()
+    },
+  }
+}
+
+function merged(declared: Options, fromClaude: PluginOptions, project: Readonly<Record<string, unknown>>, locked: ReadonlySet<string>): Readonly<Record<string, unknown>> {
+  return Object.freeze(Object.fromEntries(Object.entries(declared).map(([key, option]) => [key, valueOf(key, option, fromClaude[key], project, locked)])))
+}
+
+function valueOf(key: string, option: Option, own: unknown, project: Readonly<Record<string, unknown>>, locked: ReadonlySet<string>): unknown {
+  if (locked.has(key)) return own
+  if (Object.hasOwn(project, key)) return project[key]
+  if (!isUnset(own) && fitsOption(option, own) === undefined) return Array.isArray(own) ? Object.freeze([...own]) : own
+  return option.default ?? (option.kind === 'list' ? Object.freeze([]) : option.kind === 'number' ? undefined : '')
+}

package/src/runtime/state.ts

@@ -1,5 +1,4 @@
 import type { ClassicHookInputs } from 'claude-code'
-import { configFolder, configFolders } from '../records.js'
 import { messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
 
@@ -21,6 +20,7 @@ export type StateOptions = {
 export type ModState<State extends object> = {
   readonly state: State
   readonly root: string
+  changed(): void
   load(): Promise<void>
   moveTo(root: string): Promise<void>
   switchSession(session: string, source: ClassicHookInputs['SessionStart']['source']): Promise<void>
@@ -28,8 +28,6 @@ export type ModState<State extends object> = {
 
 const lifetimes: readonly Lifetime[] = ['memory', 'session', 'project', 'global']
 
-const savedLifetimes: readonly SavedLifetime[] = ['session', 'project', 'global']
-
 const keptPerValue = 20
 
 const listeners = new WeakMap<object, Set<() => void>>()
@@ -47,7 +45,6 @@ export function createState<State extends object>({ name, initial, session, root
   }
   const declared = declaredGroups(name, initial)
   const current = copied(declared)
-  let defaults = declared
   let projectRoot = root
   let sessionId = session
   let turn: Promise<unknown> = Promise.resolve()
@@ -72,66 +69,14 @@ export function createState<State extends object>({ name, initial, session, root
     for (const oldest of owners.slice(0, -keptPerValue)) await claude.store.delete(oldest)
   }
 
-  const fileValues = (path: string, tier: 'system' | 'project', text: string, systemPath: string) => {
-    const values: [SavedLifetime, string, unknown][] = []
-    const ignore = (reason: string) => claude.ui.log(`${path} ${reason}`)
-    let file: unknown
-    try {
-      file = JSON.parse(text)
-    } catch (error) {
-      ignore(`is not JSON (${messageOf(error)}). Fix the file, then run /reload-plugins.`)
-      return values
-    }
-    if (!isPlainObject(file)) {
-      ignore('is not a JSON object. Write one, such as { "global": { "key": "value" } }.')
-      return values
-    }
-    for (const [group, entries] of Object.entries(file)) {
-      if (!isLifetime(group)) {
-        ignore(`sets ${group}, which ${name} does not declare. Remove it, or use one of: ${savedLifetimes.join(', ')}.`)
-        continue
-      }
-      if (group === 'memory') {
-        ignore('sets memory, and memory values are never saved, so a file cannot set them. Remove it.')
-        continue
-      }
-      if (!isPlainObject(entries)) {
-        ignore(`sets ${group} to ${typeOf(entries)}. Write an object of values, such as { "${group}": { "key": "value" } }.`)
-        continue
-      }
-      for (const [key, value] of Object.entries(entries)) {
-        const choices = Object.keys(declared[group])
-        const wanted = typeOf(declared[group][key])
-        if (!Object.hasOwn(declared[group], key)) ignore(`sets ${group}.${key}, which ${name} does not declare. ${choices.length === 0 ? 'Remove it.' : `Remove it, or use one of: ${choices.join(', ')}.`}`)
-        else if (tier === 'project' && group === 'global') ignore(`sets ${group}.${key}, and one repository cannot change a value for every project. Move it to ${systemPath}.`)
-        else if (typeOf(value) !== wanted) ignore(`sets ${group}.${key} to ${typeOf(value)}, and ${name} keeps ${wanted} there. Write ${wanted}, or remove it.`)
-        else values.push([group, key, frozen(name, `${group}.${key}`, value)])
-      }
-    }
-    return values
-  }
-
-  const readDefaults = async (nextRoot: string): Promise<Groups> => {
-    const env = { HOME: await claude.env.home(), CLAUDE_CONFIG_DIR: await claude.env.configHome() }
-    const systemPath = `${configFolder(env, name)}/state.json`
-    const next = copied(declared)
-    for (const { tier, folder } of configFolders(env, name, nextRoot)) {
-      const path = `${folder}/state.json`
-      if (!(await claude.fs.exists(path))) continue
-      for (const [lifetime, key, value] of fileValues(path, tier, await claude.fs.read(path), systemPath)) next[lifetime][key] = value
-    }
-    return next
-  }
-
-  const loadGroups = async (only: readonly Lifetime[], next: { readonly root: string; readonly session: string; readonly defaults: Groups }) => {
+  const loadGroups = async (only: readonly Lifetime[], next: { readonly root: string; readonly session: string }) => {
     const loaded: [Lifetime, string, unknown][] = []
     for (const lifetime of only) {
       for (const key of Object.keys(declared[lifetime])) loaded.push([lifetime, key, lifetime === 'memory' ? undefined : await read(lifetime, key, lifetime === 'project' ? next.root : next.session)])
     }
     projectRoot = next.root
     sessionId = next.session
-    defaults = next.defaults
-    for (const [lifetime, key, saved] of loaded) current[lifetime][key] = saved === undefined ? defaults[lifetime][key] : frozen(name, `${lifetime}.${key}`, saved)
+    for (const [lifetime, key, saved] of loaded) current[lifetime][key] = saved === undefined ? declared[lifetime][key] : frozen(name, `${lifetime}.${key}`, saved)
     changed()
   }
 
@@ -167,14 +112,14 @@ export function createState<State extends object>({ name, initial, session, root
     get root() {
       return projectRoot
     },
-    load: () => inTurn(async () => loadGroups(lifetimes, { root: projectRoot, session: sessionId, defaults: await readDefaults(projectRoot) })),
-    moveTo: (nextRoot) =>
-      inTurn(async () => (nextRoot === projectRoot ? undefined : loadGroups(['project'], { root: nextRoot, session: sessionId, defaults: await readDefaults(nextRoot) }))),
+    changed,
+    load: () => inTurn(() => loadGroups(lifetimes, { root: projectRoot, session: sessionId })),
+    moveTo: (nextRoot) => inTurn(async () => (nextRoot === projectRoot ? undefined : loadGroups(['project'], { root: nextRoot, session: sessionId }))),
     switchSession: (nextSession, source) =>
       inTurn(async () => {
         if (nextSession === sessionId) return
         if (source === 'fork') await copySession(nextSession)
-        return loadGroups(['memory', 'session'], { root: projectRoot, session: nextSession, defaults })
+        return loadGroups(['memory', 'session'], { root: projectRoot, session: nextSession })
       }),
   }
 }
@@ -197,14 +142,6 @@ function isLifetime(group: string): group is Lifetime {
   return (lifetimes as readonly string[]).includes(group)
 }
 
-function typeOf(value: unknown): string {
-  if (value === null) return 'null'
-  if (Array.isArray(value)) return 'an array'
-  if (typeof value === 'object') return 'an object'
-  if (value === undefined) return 'nothing'
-  return `a ${typeof value}`
-}
-
 function frozen(name: string, path: string, value: unknown): unknown {
   const isArray = Array.isArray(value)
   if (!isArray && !isPlainObject(value)) return value

package/src/testing/fake-claude.ts

@@ -12,6 +12,7 @@ export type Fakes = {
   fs: { read?: Claude['fs']['read']; write?: Claude['fs']['write']; list?: Claude['fs']['list']; exists?: Claude['fs']['exists']; stat?: Claude['fs']['stat'] }
   http: { fetch?: Claude['http']['fetch'] }
   settings: { read?: Claude['settings']['read'] }
+  config: { list?: Claude['config']['list']; set?: Claude['config']['set'] }
   ui: { ask?: Claude['ui']['ask']; open?: Claude['ui']['open']; scroll?: Claude['ui']['scroll'] }
   session: { messages?: Claude['session']['messages']; append?: Claude['session']['append'] }
   prompt: { submit?: Claude['prompt']['submit'] }
@@ -48,7 +49,7 @@ export type FakeClaude = {
 
 export function fakeClaude(plugin: { readonly name: string; readonly root: string }): FakeClaude {
   const calls: TestCall[] = []
-  const fakes: Fakes = { process: {}, fs: {}, http: {}, settings: {}, ui: {}, session: {}, prompt: {}, model: {}, agent: {}, clock: {}, cmod: {}, tool: {} }
+  const fakes: Fakes = { process: {}, fs: {}, http: {}, settings: {}, config: {}, ui: {}, session: {}, prompt: {}, model: {}, agent: {}, clock: {}, cmod: {}, tool: {} }
   const shown: Shown = { toasts: [], notes: [], prompts: [], logs: [], debug: [], statuses: [], openPanes: new Set(), commands: [], tools: [], schedules: [] }
   const unplacedPanes = new Set<string>()
   let focusedPane: string | undefined
@@ -148,6 +149,10 @@ export function fakeClaude(plugin: { readonly name: string; readonly root: strin
     },
     http: { fetch: rejected('http.fetch', () => fakes.http.fetch) },
     settings: { read: rejected('settings.read', () => fakes.settings.read) },
+    config: {
+      list: rejected('config.list', () => fakes.config.list ?? (async () => [])),
+      set: rejected('config.set', () => fakes.config.set ?? (async ({ value }) => ({ value }))) as Claude['config']['set'],
+    },
     agent: {
       list: rejected('agent.list', () => fakes.agent.list),
       spawn: rejected('agent.spawn', () => fakes.agent.spawn),

package/src/testing/fake-files.ts

@@ -19,6 +19,9 @@ export function fakeFiles(files: Readonly<Record<string, string>>, links: Readon
     return below(path).length > 0 ? 'dir' : undefined
   }
   const sizeOf = (path: string) => new TextEncoder().encode(contents.get(path) ?? '').length
+  const modified = new Map<string, number>()
+  let writes = 0
+  const mtimeOf = (path: string) => modified.get(path) ?? 0
 
   return {
     read: async (path) => {
@@ -27,7 +30,10 @@ export function fakeFiles(files: Readonly<Record<string, string>>, links: Readon
       return text
     },
     write: async (path, text) => {
-      contents.set(realPathOf(path), text)
+      const realPath = realPathOf(path)
+      contents.set(realPath, text)
+      writes += 1
+      modified.set(realPath, writes)
     },
     list: async (path) => {
       if (path === undefined) throw new Error('fs.list() lists the working folder, which the fake files do not know. Name the folder, such as fs.list(mod.cwd).')
@@ -37,7 +43,7 @@ export function fakeFiles(files: Readonly<Record<string, string>>, links: Readon
       return [...names].map((name) => {
         const entry = resolve(folder, name)
         if (Object.hasOwn(links, entry)) return { name, kind: 'other', size: 0, mtimeMs: 0, isLink: true }
-        return { name, kind: contents.has(entry) ? 'file' : 'dir', size: sizeOf(entry), mtimeMs: 0, isLink: false }
+        return { name, kind: contents.has(entry) ? 'file' : 'dir', size: sizeOf(entry), mtimeMs: mtimeOf(entry), isLink: false }
       })
     },
     exists: async (path) => kindOf(realPathOf(path)) !== undefined,
@@ -47,7 +53,7 @@ export function fakeFiles(files: Readonly<Record<string, string>>, links: Readon
       const isLink = Object.hasOwn(links, resolve('/', path))
       if (kind === undefined && isLink) return { kind: 'other', size: 0, mtimeMs: 0, isLink }
       if (kind === undefined) throw new Error(`ENOENT: no such file or directory, stat '${path}'`)
-      return { kind, size: sizeOf(realPath), mtimeMs: 0, isLink, ...(options?.resolve === true ? { realPath } : {}) }
+      return { kind, size: sizeOf(realPath), mtimeMs: mtimeOf(realPath), isLink, ...(options?.resolve === true ? { realPath } : {}) }
     },
   }
 }

package/src/testing.ts

@@ -7,6 +7,7 @@ import type {
   EventResult,
   Frozen,
   PaneOpenArgs,
+  PluginOptions,
   PressedLink,
   RenderChildren,
   RenderComponent,
@@ -18,26 +19,32 @@ import type {
 } from 'claude-code'
 import type { Reply } from './jobs/slash-command.js'
 import type { ModDefinition, ModEvent } from './mod.js'
-import { storeFolder } from './records.js'
+import type { Options, OptionValues } from './options.js'
+import { readSteps, storeFolder, type Steps } from './records.js'
 import type { Claude } from './runtime/claude.js'
 import { answerCall, notInstalled } from './runtime/dependencies.js'
 import type { RoutedEvent } from './runtime/hooks.js'
 import { toolInputOf } from './runtime/tool-calls.js'
 import { createLifecycle } from './runtime/lifecycle.js'
+import { MissingOptions } from './runtime/options.js'
 import { fakeClaude, type Fakes, type Shown, type TestCall } from './testing/fake-claude.js'
 import { elements, findElement, rowsOf } from './testing/fake-elements.js'
 import { fakeFiles } from './testing/fake-files.js'
+import { listed } from './utils/text.js'
 import type { Slot, SlotProps } from './ui/slots.js'
 
 export type { Fakes, Shown, TestCall } from './testing/fake-claude.js'
 
-export type TestOptions<State extends object> = {
+export type TestOptions<State extends object, Declared extends Options = Options> = {
   readonly state?: { readonly [Lifetime in keyof State]?: Partial<State[Lifetime]> }
+  readonly options?: Partial<OptionValues<Declared>>
+  readonly permissions?: readonly string[]
   readonly scope?: 'user' | 'project'
   readonly projectRoot?: string
   readonly cwd?: string
   readonly dependencies?: { readonly [Name in keyof CmodDependencies]?: CmodDependencies[Name] }
   readonly files?: Readonly<Record<string, string>>
+  readonly links?: Readonly<Record<string, string>>
 }
 
 type FilledField = 'session_id' | 'transcript_path' | 'cwd' | 'hook_event_name' | 'tool_use_id'
@@ -71,7 +78,7 @@ const presentation: CommandPresentation = { isFullscreen: false, columns: defaul
 
 const toolUseEvents: readonly string[] = ['PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'PermissionDenied'] satisfies readonly ModEvent[]
 
-export function testMod<State extends object>(definition: ModDefinition<State>, options: TestOptions<State> = {}): TestedMod<State> {
+export function testMod<State extends object, Declared extends Options = Options>(definition: ModDefinition<State, string, Declared>, options: TestOptions<State, Declared> = {}): TestedMod<State> {
   installJsx()
   const name = definition.name
   const isProjectPlugin = options.scope === 'project'
@@ -93,25 +100,34 @@ export function testMod<State extends object>(definition: ModDefinition<State>,
     if (fake.fakes.agent.list !== undefined || firedAgents.size === 0) return listAgents()
     return [...firedAgents].map(([id, type]) => ({ id, type, description: '', status: 'running' as const }))
   }
-  Object.assign(fake.fakes.fs, fakeFiles(options.files ?? {}))
+  Object.assign(fake.fakes.fs, fakeFiles(options.files ?? {}, options.links))
   const starting = options.state as Record<string, object> | undefined
   const declared = Object.entries(definition.state ?? {}) as [string, object][]
   const state = Object.fromEntries(declared.map(([lifetime, values]) => [lifetime, { ...values, ...starting?.[lifetime] }])) as State
-  const lifecycle = createLifecycle<State>({ ...definition, state })
+  const lifecycle = createLifecycle<State, Declared>({ ...definition, state }, () => true, (options.options ?? {}) as PluginOptions, false)
   let started: Promise<void> | undefined
 
   const start = async () => {
-    started ??= lifecycle.start(fake.claude, async (claude) => ({
-      name,
-      root,
-      version: '0.0.0',
-      store: storeFolder({ HOME: await claude.env.home(), XDG_DATA_HOME: await claude.env.dataHome() }),
-      isInstalled: true,
-      shouldRecord: false,
-      keys: {},
-    }))
+    started ??= lifecycle.start(fake.claude, async (claude) => {
+      const steps = await modSteps()
+      return {
+        name,
+        root,
+        version: '0.0.0',
+        store: storeFolder({ HOME: await claude.env.home(), XDG_DATA_HOME: await claude.env.dataHome() }),
+        isInstalled: true,
+        shouldRecord: false,
+        steps,
+        granted: options.permissions ?? steps.permissions ?? [],
+      }
+    })
     await started
-    if (lifecycle.phase !== 'active') throw lifecycle.failure ?? new Error(`${name} did not start: the lifecycle is ${lifecycle.phase}.`)
+    const { failure } = lifecycle
+    if (failure instanceof MissingOptions) {
+      const given = failure.keys.map((key) => `${key}: …`).join(', ')
+      throw new Error(`${name} needs ${listed(failure.titles)}, which a person sets in /config. Give ${failure.keys.length === 1 ? 'it' : 'them'} to the tested mod: testMod(mod, { options: { ${given} } }).`)
+    }
+    if (lifecycle.phase !== 'active') throw failure ?? new Error(`${name} did not start: the lifecycle is ${lifecycle.phase}.`)
   }
 
   const route = async <N extends RoutedEvent>(event: N, input: unknown, below: unknown): Promise<EventResult<N>> => {
@@ -282,6 +298,15 @@ function replyOf({ text, context }: CommandRunResult): Reply {
   return { ...(text === undefined ? {} : { text }), ...(context === undefined ? {} : { context: context.join('\n') }) }
 }
 
+async function modSteps(): Promise<Steps> {
+  const manifest = '../../../package.json'
+  const loaded: unknown = await import(manifest, { with: { type: 'json' } }).then(
+    (module: { default: unknown }) => module.default,
+    () => undefined,
+  )
+  return readSteps(loaded) ?? {}
+}
+
 function installJsx(): void {
   const scope = globalThis as unknown as Record<string, unknown>
   scope['h'] ??= (tag: unknown, props: Record<string, unknown> | null, ...children: unknown[]) => {

package/src/utils/metadata.ts

@@ -0,0 +1,242 @@
+export type MetadataFormat = { readonly kind: 'frontmatter' } | { readonly kind: 'comment'; readonly prefix: string } | { readonly kind: 'sidecar' }
+
+export type ReadMetadata = {
+  readonly metadata: Readonly<Record<string, string>>
+  readonly name?: string
+}
+
+export class MetadataError extends Error {
+  readonly line: number
+
+  constructor(line: number, message: string) {
+    super(`line ${line}: ${message}`)
+    this.line = line
+  }
+}
+
+const markdown: readonly string[] = ['md', 'markdown', 'mdx']
+const hashComments: readonly string[] = ['sh', 'bash', 'zsh', 'fish', 'py', 'rb', 'pl', 'r', 'yaml', 'yml', 'toml', 'ps1', 'nu', 'tcl', 'mk', 'conf', 'cfg', 'env']
+const slashComments: readonly string[] = ['ts', 'tsx', 'mts', 'cts', 'js', 'jsx', 'mjs', 'cjs', 'go', 'rs', 'swift', 'kt', 'kts', 'java', 'c', 'h', 'cc', 'cpp', 'hpp', 'cs', 'scala', 'dart', 'zig', 'jsonc', 'json5']
+const dashComments: readonly string[] = ['lua', 'sql', 'hs', 'elm']
+const hashCommentNames: readonly string[] = ['Makefile', 'Dockerfile', 'Brewfile', 'Gemfile', 'Rakefile', 'Justfile', 'justfile']
+
+export const sidecarSuffix = '.meta'
+
+export function formatOf(path: string, firstLine: string | undefined): MetadataFormat {
+  const name = path.slice(path.lastIndexOf('/') + 1)
+  const dot = name.lastIndexOf('.')
+  const extension = dot <= 0 ? '' : name.slice(dot + 1).toLowerCase()
+  if (markdown.includes(extension)) return { kind: 'frontmatter' }
+  if (hashComments.includes(extension) || hashCommentNames.includes(name)) return { kind: 'comment', prefix: '#' }
+  if (slashComments.includes(extension)) return { kind: 'comment', prefix: '//' }
+  if (dashComments.includes(extension)) return { kind: 'comment', prefix: '--' }
+  if (extension === '' && firstLine?.startsWith('#!') === true) return { kind: 'comment', prefix: '#' }
+  return { kind: 'sidecar' }
+}
+
+type Region = { readonly start: number; readonly end: number; readonly lines: readonly string[] }
+
+type Entry = { readonly key: string; readonly value: string }
+
+type Block = { readonly start: number; readonly end: number; readonly entries: readonly Entry[] }
+
+export function readMetadata(text: string, format: MetadataFormat): ReadMetadata {
+  const lines = text.split('\n')
+  if (format.kind === 'comment') {
+    const region = commentRegion(lines, format.prefix)
+    return { metadata: region === undefined ? {} : asRecord(mapEntries(region.lines, region.start + 2, 0)) }
+  }
+  const region = format.kind === 'frontmatter' ? frontmatterRegion(lines) : { start: -1, end: lines.length, lines }
+  if (region === undefined) return { metadata: {} }
+  const block = metadataBlock(region)
+  const name = format.kind === 'frontmatter' ? topLevelScalar(region, 'name') : undefined
+  return { metadata: block === undefined ? {} : asRecord(block.entries), ...(name === undefined ? {} : { name }) }
+}
+
+export function writeMetadata(text: string, format: MetadataFormat, metadata: Readonly<Record<string, string>>): string {
+  const lines = text.split('\n')
+  const entries = Object.entries(metadata)
+  if (format.kind === 'comment') {
+    const { prefix } = format
+    const block = entries.length === 0 ? [] : [`${prefix} /// metadata`, ...entries.map(([key, value]) => `${prefix} ${scalar(key)}: ${scalar(value)}`), `${prefix} ///`]
+    const region = commentRegion(lines, prefix)
+    if (region !== undefined) return [...lines.slice(0, region.start), ...block, ...lines.slice(region.end + 1)].join('\n')
+    if (block.length === 0) return text
+    const at = lines[0]?.startsWith('#!') === true ? 1 : 0
+    return [...lines.slice(0, at), ...block, ...lines.slice(at)].join('\n')
+  }
+  const map = entries.length === 0 ? [] : ['metadata:', ...entries.map(([key, value]) => `  ${scalar(key)}: ${scalar(value)}`)]
+  if (format.kind === 'sidecar') {
+    const block = metadataBlock({ start: -1, end: lines.length, lines })
+    const rest = block === undefined ? lines : [...lines.slice(0, block.start), ...lines.slice(block.end)]
+    const kept = rest.join('\n').trim()
+    return [...(kept === '' ? [] : [kept]), ...map].join('\n') + (map.length === 0 && kept === '' ? '' : '\n')
+  }
+  const region = frontmatterRegion(lines)
+  if (region === undefined) return map.length === 0 ? text : ['---', ...map, '---', ...lines].join('\n')
+  const block = metadataBlock(region)
+  const inner = block === undefined ? [...region.lines, ...map] : [...lines.slice(region.start + 1, block.start), ...map, ...lines.slice(block.end, region.end)]
+  if (inner.every((line) => line.trim() === '')) return lines.slice(region.end + 1).join('\n')
+  return [...lines.slice(0, region.start + 1), ...inner, ...lines.slice(region.end)].join('\n')
+}
+
+function frontmatterRegion(lines: readonly string[]): Region | undefined {
+  if (lines[0]?.replace(/^\uFEFF/, '').trimEnd() !== '---') return undefined
+  const end = lines.findIndex((line, index) => index > 0 && line.trimEnd() === '---')
+  if (end === -1) throw new MetadataError(1, 'the frontmatter starts with --- and never ends. Close it with a --- line.')
+  return { start: 0, end, lines: lines.slice(1, end) }
+}
+
+function commentRegion(lines: readonly string[], prefix: string): Region | undefined {
+  const start = lines.findIndex((line) => line.trimEnd() === `${prefix} /// metadata`)
+  if (start === -1) return undefined
+  const content: string[] = []
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const line = (lines[index] ?? '').trimEnd()
+    if (line === `${prefix} ///`) return { start, end: index, lines: content }
+    if (line !== prefix && !line.startsWith(`${prefix} `)) break
+    content.push(line.slice(prefix.length + 1))
+  }
+  throw new MetadataError(start + 1, `the metadata block never ends. Close it with a "${prefix} ///" line.`)
+}
+
+function metadataBlock(region: Region): Block | undefined {
+  const at = region.lines.findIndex((line) => /^metadata\s*:/.test(line))
+  if (at === -1) return undefined
+  const lineNumber = region.start + 2 + at
+  const rest = withoutComment((region.lines[at] ?? '').replace(/^metadata\s*:/, '')).trim()
+  const start = region.start + 1 + at
+  if (rest.startsWith('{')) return { start, end: start + 1, entries: flowEntries(rest, lineNumber) }
+  if (rest !== '') throw new MetadataError(lineNumber, 'metadata holds a single value. Write a map of names to text, such as metadata: { mymod.key: value }.')
+  let index = at + 1
+  while (index < region.lines.length && (/^\s/.test(region.lines[index] ?? '') || (region.lines[index] ?? '').trim() === '')) index += 1
+  while (index > at + 1 && (region.lines[index - 1] ?? '').trim() === '') index -= 1
+  const children = region.lines.slice(at + 1, index)
+  return { start, end: region.start + 1 + index, entries: mapEntries(children, lineNumber + 1, indentOf(children)) }
+}
+
+function indentOf(lines: readonly string[]): number {
+  const first = lines.find((line) => line.trim() !== '' && !line.trim().startsWith('#'))
+  return first === undefined ? 0 : (/^\s*/.exec(first)?.[0].length ?? 0)
+}
+
+function mapEntries(lines: readonly string[], firstLine: number, indent: number): Entry[] {
+  const entries: Entry[] = []
+  lines.forEach((raw, index) => {
+    const lineNumber = firstLine + index
+    const line = withoutComment(raw)
+    if (line.trim() === '') return
+    const depth = /^\s*/.exec(line)?.[0].length ?? 0
+    if (depth !== indent) throw new MetadataError(lineNumber, 'a metadata value holds a list or a map. Each value is one line of text, and a list is one space-separated text.')
+    const body = line.trim()
+    if (body.startsWith('- ')) throw new MetadataError(lineNumber, 'metadata holds a list. Write a map of names to text, and a list as one space-separated text.')
+    entries.push(entryOf(body, lineNumber))
+  })
+  return entries
+}
+
+function flowEntries(text: string, lineNumber: number): Entry[] {
+  if (!text.endsWith('}')) throw new MetadataError(lineNumber, 'the metadata map starts with { and does not end on the same line. Close it with }, or write one entry per line.')
+  const body = text.slice(1, -1).trim()
+  if (body === '') return []
+  return splitOutsideQuotes(body, ',', lineNumber)
+    .map((part) => part.trim())
+    .filter((part) => part !== '')
+    .map((part) => entryOf(part, lineNumber))
+}
+
+function entryOf(text: string, lineNumber: number): Entry {
+  const [keyText, ...rest] = splitOutsideQuotes(text, ':', lineNumber, true)
+  if (keyText === undefined || rest.length === 0) throw new MetadataError(lineNumber, `"${text}" has no ":". Write each entry as name: value.`)
+  const valueText = rest.join(':').trim()
+  if (valueText.startsWith('{') || valueText.startsWith('[') || valueText === '|' || valueText === '>') throw new MetadataError(lineNumber, `${keyText.trim()} holds a list or a map. Each value is one line of text, and a list is one space-separated text.`)
+  return { key: unquoted(keyText.trim(), lineNumber), value: unquoted(valueText, lineNumber) }
+}
+
+function splitOutsideQuotes(text: string, separator: string, lineNumber: number, needsSpace = false): string[] {
+  const parts: string[] = []
+  let quote: string | undefined
+  let current = ''
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index] as string
+    if (quote !== undefined) {
+      current += char
+      if (char === '\\' && quote === '"') {
+        current += text[index + 1] ?? ''
+        index += 1
+      } else if (char === quote) quote = undefined
+      continue
+    }
+    const before = current.trimEnd().at(-1)
+    if ((char === '"' || char === "'") && (before === undefined || before === ':')) quote = char
+    const next = text[index + 1]
+    if (char === separator && (!needsSpace || next === undefined || next === ' ' || next === '\t')) {
+      parts.push(current)
+      current = ''
+      if (needsSpace) {
+        parts.push(text.slice(index + 1))
+        return parts
+      }
+      continue
+    }
+    current += char
+  }
+  if (quote !== undefined) throw new MetadataError(lineNumber, `a ${quote === '"' ? 'double' : 'single'} quote never closes.`)
+  parts.push(current)
+  return parts
+}
+
+function withoutComment(line: string): string {
+  let quote: string | undefined
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line[index]
+    if (quote !== undefined) {
+      if (char === '\\' && quote === '"') index += 1
+      else if (char === quote) quote = undefined
+      continue
+    }
+    if (char === '"' || char === "'") quote = char
+    if (char === '#' && (index === 0 || /\s/.test(line[index - 1] ?? ''))) return line.slice(0, index)
+  }
+  return line
+}
+
+function unquoted(text: string, lineNumber: number): string {
+  if (text.startsWith('"')) {
+    if (!text.endsWith('"') || text.length < 2) throw new MetadataError(lineNumber, `${text} opens a double quote that never closes.`)
+    try {
+      return JSON.parse(text) as string
+    } catch {
+      throw new MetadataError(lineNumber, `${text} is not a double-quoted text. Escape a " inside it as \\".`)
+    }
+  }
+  if (text.startsWith("'")) {
+    if (!text.endsWith("'") || text.length < 2) throw new MetadataError(lineNumber, `${text} opens a single quote that never closes.`)
+    return text.slice(1, -1).replaceAll("''", "'")
+  }
+  return text
+}
+
+function topLevelScalar(region: Region, key: string): string | undefined {
+  const at = region.lines.findIndex((line) => line.startsWith(`${key}:`))
+  if (at === -1) return undefined
+  const text = withoutComment((region.lines[at] ?? '').slice(key.length + 1)).trim()
+  if (text === '') return undefined
+  try {
+    return unquoted(text, region.start + 2 + at)
+  } catch {
+    return undefined
+  }
+}
+
+function asRecord(entries: readonly Entry[]): Readonly<Record<string, string>> {
+  return Object.freeze(Object.fromEntries(entries.map(({ key, value }) => [key, value])))
+}
+
+const plain = /^[A-Za-z0-9_./+~$%^()=\\][^#]*$/
+const special = /^(true|false|yes|no|on|off|null|~|[-+]?(\d[\d_]*)?\.?\d+([eE][-+]?\d+)?|0x[0-9a-fA-F]+|\.inf|\.nan)$/i
+
+function scalar(text: string): string {
+  const isPlain = plain.test(text) && text === text.trim() && !text.includes(': ') && !text.endsWith(':') && !text.includes(' #') && !special.test(text) && !/["',{}[\]]/.test(text)
+  return isPlain ? text : JSON.stringify(text)
+}