@cmodjs/core 0.1.13 → 0.2.0

package/src/runtime/metadata.ts

@@ -0,0 +1,153 @@
+import type { FileMatch, Metadata } from '../mod.js'
+import { formatOf, MetadataError, readMetadata, sidecarSuffix, writeMetadata, type MetadataFormat } from '../utils/metadata.js'
+import { messageOf } from '../utils/text.js'
+import { picomatch, resolve } from '../vendor.js'
+import type { Claude } from './claude.js'
+
+export type Places = {
+  readonly home: string | undefined
+  readonly configRoot: string | undefined
+  readonly projectRoot: () => string
+}
+
+export type ModFiles = {
+  find(glob: string | readonly string[]): Promise<readonly FileMatch[]>
+  read(path: string): Promise<Metadata>
+  update(path: string, change: (metadata: Record<string, string>) => void): Promise<void>
+}
+
+type Read = { readonly metadata: Metadata; readonly name?: string; readonly error?: string }
+
+type Located = { readonly realPath: string; readonly format: MetadataFormat; readonly holder: string; readonly signature: string }
+
+const skippedFolders: readonly string[] = ['.git', 'node_modules']
+
+const ownKey = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/
+
+export function resolvedPath(path: string, places: Places): string {
+  const configured = /^~\/\.claude(?=\/|$)/.exec(path)
+  if (configured !== null && places.configRoot !== undefined) return resolve(`${places.configRoot}${path.slice(configured[0].length)}`)
+  if (path === '~' || path.startsWith('~/')) {
+    if (places.home === undefined) throw new Error(`${path} starts with ~, and HOME is not set. Start Claude Code with HOME set.`)
+    return resolve(`${places.home}${path.slice(1)}`)
+  }
+  return path.startsWith('/') ? resolve(path) : resolve(places.projectRoot(), path)
+}
+
+export function createModFiles({ name, claude, places, checkWrite }: { readonly name: string; readonly claude: Claude; readonly places: Places; readonly checkWrite: (path: string) => Promise<void> }): ModFiles {
+  const prefix = `${name}.`
+  const cache = new Map<string, { readonly signature: string; readonly read: Read }>()
+  const logged = new Set<string>()
+
+  const own = (all: Metadata): Metadata => Object.freeze(Object.fromEntries(Object.entries(all).flatMap(([key, value]) => (key.startsWith(prefix) ? [[key.slice(prefix.length), value]] : []))))
+
+  const locate = async (path: string): Promise<Located> => {
+    const stat = await claude.fs.stat(path, { resolve: true })
+    if (stat.kind !== 'file') throw new Error(`${path} is not a file, so it holds no metadata.`)
+    const realPath = stat.realPath ?? path
+    const extensionless = !realPath.slice(realPath.lastIndexOf('/') + 1).includes('.')
+    const firstLine = extensionless ? (await claude.fs.read(realPath)).split('\n', 1)[0] : undefined
+    const format = formatOf(realPath, firstLine)
+    const holder = format.kind === 'sidecar' ? `${realPath}${sidecarSuffix}` : realPath
+    const sidecar = format.kind === 'sidecar' ? await claude.fs.stat(holder).catch(() => undefined) : undefined
+    return { realPath, format, holder, signature: `${stat.mtimeMs}:${stat.size}:${sidecar?.kind === 'file' ? `${sidecar.mtimeMs}:${sidecar.size}` : ''}` }
+  }
+
+  const textOf = async (holder: string): Promise<string> => ((await claude.fs.stat(holder).catch(() => undefined))?.kind === 'file' ? claude.fs.read(holder) : '')
+
+  const readEntry = async (path: string): Promise<Read> => {
+    const located = await locate(path)
+    const cached = cache.get(path)
+    if (cached?.signature === located.signature) return cached.read
+    let read: Read
+    try {
+      const { metadata, name: declared } = readMetadata(await textOf(located.holder), located.format)
+      read = { metadata, ...(declared === undefined ? {} : { name: declared }) }
+    } catch (error) {
+      if (!(error instanceof MetadataError)) throw error
+      const failure = `${located.holder} ${error.message}`
+      read = { metadata: {}, error: failure }
+      if (!logged.has(failure)) claude.ui.log(`${name}: ${failure}`)
+      logged.add(failure)
+    }
+    cache.set(path, { signature: located.signature, read })
+    return read
+  }
+
+  const matchesOf = async (pattern: string): Promise<string[]> => {
+    const absolute = resolvedPath(pattern, places)
+    const scanned = picomatch.scan(absolute)
+    if (!scanned.isGlob) return (await claude.fs.stat(absolute).catch(() => undefined))?.kind === 'file' ? [absolute] : []
+    const isMatch = picomatch(absolute, { dot: true })
+    const entersSkipped = skippedFolders.filter((folder) => scanned.glob.split('/').includes(folder))
+    const maxDepth = scanned.glob.includes('**') ? Number.POSITIVE_INFINITY : scanned.glob.split('/').length
+    const found: string[] = []
+    const visited = new Set<string>()
+    const walk = async (folder: string, depth: number): Promise<void> => {
+      const real = (await claude.fs.stat(folder, { resolve: true }).catch(() => undefined))?.realPath ?? folder
+      if (visited.has(real)) return
+      visited.add(real)
+      const entries = await claude.fs.list(folder).catch(() => [])
+      await Promise.all(
+        entries.map(async (entry) => {
+          const path = `${folder}/${entry.name}`
+          const kind = entry.isLink === true ? (await claude.fs.stat(path).catch(() => undefined))?.kind : entry.kind
+          if (kind === 'file' && isMatch(path)) found.push(path)
+          if (kind !== 'dir' || depth + 1 >= maxDepth) return
+          if (skippedFolders.includes(entry.name) && !entersSkipped.includes(entry.name)) return
+          await walk(path, depth + 1)
+        }),
+      )
+    }
+    const base = scanned.base === '' ? '/' : scanned.base
+    if ((await claude.fs.stat(base).catch(() => undefined))?.kind === 'dir') await walk(base, 0)
+    return found
+  }
+
+  return {
+    async find(glob) {
+      const patterns = typeof glob === 'string' ? [glob] : glob
+      const paths = [...new Set((await Promise.all(patterns.map(matchesOf))).flat())].sort()
+      const kept = paths.filter((path) => !(path.endsWith(sidecarSuffix) && paths.includes(path.slice(0, -sidecarSuffix.length))))
+      return Promise.all(
+        kept.map(async (path): Promise<FileMatch> => {
+          const read = await readEntry(path)
+          return { path, ...(read.name === undefined ? {} : { name: read.name }), metadata: own(read.metadata), ...(read.error === undefined ? {} : { error: read.error }) }
+        }),
+      )
+    },
+    async read(path) {
+      const read = await readEntry(resolvedPath(path, places))
+      if (read.error !== undefined) throw new Error(`${name}: ${read.error}`)
+      return own(read.metadata)
+    },
+    async update(path, change) {
+      const given = resolvedPath(path, places)
+      await checkWrite(given)
+      const located = await locate(given)
+      const text = await textOf(located.holder)
+      let all: Metadata
+      try {
+        all = readMetadata(text, located.format).metadata
+      } catch (error) {
+        throw new Error(`${name}: ${located.holder} ${messageOf(error)}`, { cause: error })
+      }
+      const edited: Record<string, string> = { ...own(all) }
+      change(edited)
+      for (const [key, value] of Object.entries(edited)) {
+        if (!ownKey.test(key)) throw new Error(`${name}: the metadata key "${key}" is not a name. Use letters, digits, "_", ".", and "-".`)
+        if (typeof value !== 'string') throw new Error(`${name}: the metadata key "${key}" holds ${JSON.stringify(value)}. Each value is text, and a list is one space-separated text.`)
+        if (value.includes('\n')) throw new Error(`${name}: the metadata key "${key}" holds a line break. Each value is one line of text.`)
+      }
+      const next: Record<string, string> = {}
+      for (const [key, value] of Object.entries(all)) {
+        if (!key.startsWith(prefix)) next[key] = value
+        else if (Object.hasOwn(edited, key.slice(prefix.length))) next[key] = edited[key.slice(prefix.length)] as string
+      }
+      for (const [key, value] of Object.entries(edited)) next[`${prefix}${key}`] = value
+      if (JSON.stringify(next) === JSON.stringify(all)) return
+      await claude.fs.write(located.holder, writeMetadata(text, located.format, next))
+      cache.delete(given)
+    },
+  }
+}

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[]) => {