@cmodjs/core 0.1.2 → 0.1.4

package/docs/mod.md

@@ -0,0 +1,217 @@
+# Define a mod
+
+`defineMod` describes a mod: its name, its state, the methods it offers other mods, and the `setup` function that attaches everything to Claude Code. `connect` hands the definition to Claude Code.
+
+## defineMod
+
+```ts
+defineMod<State, Name>(definition: ModDefinition<State, Name>): ModDefinition<State, Name>
+```
+
+```ts
+type ModDefinition<State, Name> = {
+  readonly name: Name
+  readonly state?: State
+  readonly api?: { … }
+  setup(mod: Mod<State>): void | Promise<void>
+}
+```
+
+- `name` is the mod's name. Use the `name` in `.claude-plugin/plugin.json`. Claude Mod Manager (CMod) keys the saved state and the `state.json` files by this name, and the data folder and the Skill overrides by the plugin's name, so the two must match. `defineMod` throws `defineMod: the mod needs a name, such as the name in .claude-plugin/plugin.json.` for a blank name.
+- `state` holds the starting values, grouped by how long they last. [state.md](state.md) explains the groups.
+- `api` holds the methods other mods call. [dependencies.md](dependencies.md) explains it.
+- `setup` runs once when the mod starts. It adds hooks, panes, slot renders, and jobs. It may be `async`.
+
+```tsx
+import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+
+export const greeter = defineMod({
+  name: 'greeter',
+  state: { session: { isGreeted: false } },
+
+  setup(mod) {
+    mod.on('UserPromptSubmit', () => {
+      if (mod.state.session.isGreeted) return
+      mod.state.session.isGreeted = true
+      mod.ui.toast(`Hello from ${mod.name}`)
+    })
+  },
+})
+```
+
+## When setup runs
+
+Claude Code loads the mod at the start of each session. CMod then checks that the mod is set up. A mod with an install step that has not run waits for the person's consent and the install first ([install-steps.md](install-steps.md)). Then CMod loads the saved state, runs `setup`, and marks as open each of the mod's panes that Claude Code already shows.
+
+The first time a version starts, CMod shows the toast `<name> is ready` and logs `<name> added <what setup added>`, such as `the my-mod pane, a render of AbovePrompt and a hook on UserPromptSubmit`.
+
+When a step fails, the mod does not start. Its progress line above the prompt names the failure and the fix:
+
+- `<mod>: state.<group> is not a lifetime. …` or `<mod>: state.<group> is not an object of values. …` when the declared state is not valid ([state.md](state.md)).
+- `its state did not load: <error>` when reading the saved values or a `state.json` fails.
+- `its setup function threw: <error>` when `setup` throws or rejects.
+- `its open panes did not load: <error>` when Claude Code cannot list the open panes.
+
+Each of these says `Fix it, then run /reload-plugins.`
+
+## Connect the mod to Claude Code
+
+`hooks/hooks.json` names `hooks/register.ts` as the plugin's hooks module. `register.ts` calls `connect` and does nothing else:
+
+```ts
+import type { Register } from 'claude-code'
+import { connect } from '../node_modules/@cmodjs/core/connect.js'
+import { greeter } from '../src/mod.js'
+
+export const register: Register = (on) => {
+  connect(on, greeter)
+}
+```
+
+```ts
+connect<State>(on: On, definition: ModDefinition<State>): void
+```
+
+`connect` registers one handler per Claude Code event the mod can use, and routes each event to the mod. Keep `register.ts` this small. Claude Code checks a hooks module before it loads it, and refuses some shapes, such as a `$` passed to a function in another module.
+
+## What `mod` can call
+
+`setup` gets `mod`, of type `Mod<State>`. Every hook, render, and job gets the same `mod`.
+
+```ts
+type Mod<State> = {
+  readonly name: string
+  readonly state: Readonly<State>
+  readonly dataFolder: string
+  readonly projectRoot: string
+  readonly cwd: string
+  on(event, hook): void
+  use(part): Handle
+  readonly ui: { pane, render, toast, progress, ask }
+  readonly process: { run, spawn }
+  readonly fs: { read, write, list }
+  readonly http: { fetch }
+  readonly settings: { read }
+  readonly dependencies: CmodDependencies
+}
+```
+
+| Member | What it is | Docs |
+| --- | --- | --- |
+| `name` | The mod's name from `defineMod`. | |
+| `state` | The mod's values. Assign to a key to change it. | [state.md](state.md) |
+| `dataFolder` | The mod's own folder in the CMod store: `$XDG_DATA_HOME/cmod/data/<plugin name>`, or `~/.local/share/cmod/data/<plugin name>` when `XDG_DATA_HOME` is not set. The install step gets the same folder as `CMOD_DATA`. CMod deletes it when the mod is removed. | [install-steps.md](install-steps.md) |
+| `projectRoot` | The project the session works in. It follows `/cd`. | |
+| `cwd` | The session's working folder. It follows a `cd` in a Bash or PowerShell call, and `/cd`. | |
+| `on` | Adds a hook on a Claude Code event. | [hooks.md](hooks.md) |
+| `use` | Adds a job, such as a slash command or a tool, and returns its handle. | [jobs.md](jobs.md) |
+| `ui` | Panes, slot renders, toasts, progress lines, and questions. | [ui.md](ui.md) |
+| `process` | Runs a program. | below |
+| `fs` | Reads and writes files. | below |
+| `http` | Fetches a URL. | below |
+| `settings` | Reads Claude Code's settings. | below |
+| `dependencies` | Calls the methods of other mods. | [dependencies.md](dependencies.md) |
+
+### mod.process
+
+```ts
+mod.process.run(argv: readonly string[], init?: ProcessRunInit): Promise<ProcessRunResult>
+mod.process.spawn(argv: readonly string[], init?: { cwd?, env?, input? }): HookStream<ProcessSpawnChunk, ProcessSpawnResult>
+```
+
+Both run a program without a shell. `argv[0]` is the program and the rest are its arguments.
+
+- `init.cwd` is the program's folder, absolute or relative to the session's working folder. Without it the program runs in the session's working folder.
+- `init.env` sets variables over Claude Code's own environment.
+- `run` takes `stdin`, and `spawn` takes `input`: text written to standard input, which then closes.
+- `run` takes `timeoutMs`: Claude Code kills the program after it, 30 seconds by default and 10 minutes at most. `longestMs`, exported from `mod.js`, is those 10 minutes in milliseconds, `600000`.
+- `run` resolves `{ exitCode, stdout, stderr, isStdoutTruncated, isStderrTruncated }` once the program exits, whatever its exit code. It keeps the first 4 MiB of each stream. A program ended by a signal has `exitCode` 1.
+- `run` rejects when the program cannot start, and when it is still running at `timeoutMs`. It reads the whole output, so a background process the program leaves writing holds the call until the timeout.
+- `spawn` streams `{ stream: 'stdout' | 'stderr', text }` pieces as the program writes them. Its `result` resolves `{ code, signal }` once the stream is read to its end. Its first pull rejects when the program cannot start.
+- The `for await` loop over a `spawn` is the program's life. Leaving the loop, or calling `return()` on the stream, kills the program, and so does unloading the mod. Returning from the hook does not.
+
+Inside a job, CMod adds the job's deadline to each call ([jobs.md](jobs.md)).
+
+```ts
+import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+
+export const branchNote = defineMod({
+  name: 'branch-note',
+  setup(mod) {
+    mod.on('SessionStart', async () => {
+      const { exitCode, stdout } = await mod.process.run(['git', 'branch', '--show-current'], { cwd: mod.projectRoot })
+      if (exitCode !== 0) return
+      return { hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: `The git branch is ${stdout.trim()}.` } }
+    })
+  },
+})
+```
+
+### mod.fs
+
+```ts
+mod.fs.read(path: string): Promise<string>
+mod.fs.write(path: string, text: string): Promise<void>
+mod.fs.list(path?: string): Promise<FsEntry[]>
+```
+
+- A relative path is under the session's working folder. An absolute path is used as given. Text is UTF-8.
+- `read` rejects a missing file and a file over 4 MiB.
+- `write` writes the whole file and creates its folders.
+- `list` lists a folder, the working folder without a path. Each entry is `{ name, kind, size, mtimeMs, isLink }`, and `kind` is `'file'`, `'dir'`, or `'other'`. A symbolic link is `'other'` with `isLink` true.
+
+A file the mod ships is under the plugin's folder. `mod` has no member that names that folder, so a job of your own reads it from `claude.plugin.root` ([jobs.md](jobs.md#the-claude-members)). A file the mod keeps for itself belongs in `mod.dataFolder`.
+
+### mod.http
+
+```ts
+mod.http.fetch(url: string, init?: HttpInit): Promise<HttpResponse>
+```
+
+- `init` takes `method` (`GET` by default), `headers`, `body` as text, and `socketPath`, the absolute path of a Unix socket the request goes over.
+- The response is `{ status, ok, headers, text }`. `ok` is true for a 2xx status. Header names are lower case.
+
+### mod.settings
+
+```ts
+mod.settings.read(args?: { source?: 'user' | 'project' | 'local' | 'flag' | 'policy' }): Promise<Settings>
+```
+
+Without a `source` it answers the settings Claude Code runs under, every source merged. With a `source` it answers that one source: `user` is `~/.claude/settings.json`, `project` is `.claude/settings.json`, and `local` is `.claude/settings.local.json`. The answer is keyed as a `settings.json` is, such as `permissions`, `env`, and `enabledPlugins`.
+
+```ts
+import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+
+export const pluginCount = defineMod({
+  name: 'plugin-count',
+  setup(mod) {
+    mod.on('SessionStart', async () => {
+      const enabled = (await mod.settings.read({ source: 'user' }))['enabledPlugins'] as Record<string, unknown> | undefined
+      mod.ui.toast(`${Object.keys(enabled ?? {}).length} plugins are enabled`)
+    })
+  },
+})
+```
+
+## messageOf
+
+```ts
+messageOf(error: unknown): string
+```
+
+Returns an `Error`'s `message`, or the value as text. Use it in a `catch`, where the error is `unknown`.
+
+```ts
+import { defineMod, messageOf } from '../node_modules/@cmodjs/core/mod.js'
+
+export const notes = defineMod({
+  name: 'notes',
+  setup(mod) {
+    mod.on('Stop', async () => {
+      await mod.fs.write(`${mod.dataFolder}/last-stop.txt`, new Date().toISOString()).catch((error: unknown) => {
+        mod.ui.toast(`notes could not save: ${messageOf(error)}`)
+      })
+    })
+  },
+})
+```

package/docs/state.md

@@ -0,0 +1,140 @@
+# State
+
+`mod.state` holds the mod's values. Claude Mod Manager (CMod) saves them, redraws the mod's panes and slot renders when one changes, and lets a person change the starting values without touching the mod's code.
+
+## Declare the state
+
+`defineMod`'s `state` groups the starting values by how long they last:
+
+| Group | How long a value lasts | Saved |
+| --- | --- | --- |
+| `memory` | Until `/clear`, `--resume`, `/branch`, or a reload of Claude Code or its plugins. A compaction keeps it. | No |
+| `session` | This conversation. It comes back on `--resume`, starts over on `/clear`, and `/branch` copies it. | Yes |
+| `project` | This project, in every conversation. | Yes |
+| `global` | Every project. | Yes |
+
+CMod keeps each `session` value for the 20 sessions that wrote it last, and each `project` value for the 20 projects that wrote it last. A session or project past those 20 starts that value over from its starting value.
+
+Put values the mod works out again on every prompt, such as a git status, in `memory`.
+
+Declare the state in its own file with its type, as `cmod new` does:
+
+```ts
+export type TasksState = {
+  memory: { changedFiles: readonly string[] }
+  session: { prompts: number }
+  project: { isFrozen: boolean }
+  global: { defaultCommitPolicy: 'ask' | 'never' }
+}
+
+export const initialState: TasksState = {
+  memory: { changedFiles: [] },
+  session: { prompts: 0 },
+  project: { isFrozen: false },
+  global: { defaultCommitPolicy: 'ask' },
+}
+```
+
+Then pass it to `defineMod`:
+
+```ts
+import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+import { initialState } from './state.js'
+
+export const tasks = defineMod({
+  name: 'tasks',
+  state: initialState,
+  setup(mod) {
+    mod.on('UserPromptSubmit', () => {
+      mod.state.session.prompts += 1
+    })
+  },
+})
+```
+
+A group other than `memory`, `session`, `project`, and `global` throws `<mod>: state.<group> is not a lifetime.` when the mod starts. A group that is not an object of values throws too.
+
+## Change a value
+
+Assign to a key. CMod saves the new value and redraws the mod.
+
+- A key the state does not declare throws `<mod>: mod.state.<group>.<key> is not declared. Add it to state.<group> in defineMod with its starting value.`
+- An object or an array in the state is frozen. Changing it in place throws `<mod>: mod.state.<path> cannot change in place.` Assign a new value instead:
+
+```ts
+import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+
+export const reads = defineMod({
+  name: 'reads',
+  state: { memory: { readFiles: [] as readonly string[] } },
+  setup(mod) {
+    mod.on('PostToolUse', (input) => {
+      mod.state.memory.readFiles = [...mod.state.memory.readFiles, ...input.files.read]
+    })
+  },
+})
+```
+
+- Keep only JSON data in a saved group. A value CMod cannot save logs `<mod> could not keep state.<group>.<key>: <error>. Keep only JSON data in mod.state.`
+- CMod saves values one at a time in the order they were assigned.
+
+## Where the values come from
+
+When the mod starts, each value is, in order of precedence:
+
+1. The value the mod saved for this session, this project, or globally.
+2. The value in the project's `state.json`.
+3. The value in the person's own `state.json`.
+4. The starting value in `defineMod`.
+
+After a `/cd` to another project, CMod loads that project's `project` values and reads its `state.json` again.
+
+## Let a person change the starting values
+
+Each mod has two config folders, outside its code:
+
+```text
+~/.claude/cmods/<mod>/              the person's own, in every project
+<project>/.claude/cmods/<mod>/      the team's, committed with the repository
+```
+
+`CLAUDE_CONFIG_DIR` moves `~/.claude`. Removing the mod keeps both folders.
+
+A `state.json` in either folder lists only the values to change:
+
+```json
+{ "global": { "defaultCommitPolicy": "never" }, "session": { "prompts": 10 } }
+```
+
+- A `session` value is what each new conversation starts with. A `project` value is what each project starts with.
+- A file in the project folder wins over the same value in the person's folder.
+- A project `state.json` cannot set `global` values, because one repository cannot change a value for every project.
+- A file cannot set `memory` values.
+
+CMod ignores each entry it cannot use and logs one line naming the file, the entry, and the fix:
+
+- a file that is not JSON, or not a JSON object
+- a group the mod does not declare
+- a key the mod does not declare
+- a value whose type differs from the starting value's
+- a `global` value in a project file
+- a `memory` value
+
+## Let a person replace a Skill's text
+
+A person replaces the text of a Skill the mod ships by putting a file at the same path in a config folder:
+
+```text
+~/.claude/cmods/<mod>/skills/<skill>/SKILL.md
+<project>/.claude/cmods/<mod>/skills/<skill>/SKILL.md
+```
+
+- Claude reads that file in place of the mod's from the next time the Skill loads, and updates of the mod keep it.
+- The project file wins over the person's file.
+- CMod drops the file's frontmatter, so the mod's own name and description stay.
+- Only a Skill the mod ships in `skills/<skill>/` is replaced, and only when it loads as `<mod>:<skill>`.
+- Deleting the file brings the mod's text back.
+
+## Test state
+
+`testMod(mod, { state: { session: { prompts: 3 } } })` starts the tested mod with those values over the declared ones. `tested.state` reads the values after a test step. [testing.md](testing.md) covers both.

package/docs/testing.md

@@ -0,0 +1,247 @@
+# Testing
+
+`testMod` runs a mod against a fake Claude Code in `bun test`, so a test drives the mod the way a person and Claude do and reads what they would see. It needs no running Claude Code.
+
+```ts
+testMod<State>(definition: ModDefinition<State>, options?: TestOptions<State>): TestedMod<State>
+```
+
+```ts
+import { expect, test } from 'bun:test'
+import { testMod } from '../node_modules/@cmodjs/core/testing.js'
+import { todo } from '../src/mod.js'
+
+test('/todo adds the item to the project list', async () => {
+  const tested = testMod(todo)
+
+  expect(await tested.type('/todo buy milk')).toEqual({ text: 'Added: buy milk', context: 'The to-do list is now: buy milk' })
+  expect(tested.state.project.items).toEqual(['buy milk'])
+})
+```
+
+Assert what a person or Claude sees: `tested.lines(...)`, `tested.shown`, `tested.state`, and what `tested.fire(...)`, `tested.type(...)`, and `tested.callTool(...)` return.
+
+## TestOptions
+
+```ts
+type TestOptions<State> = {
+  readonly state?: { [Lifetime in keyof State]?: Partial<State[Lifetime]> }
+  readonly scope?: 'user' | 'project'
+  readonly projectRoot?: string
+  readonly cwd?: string
+  readonly dependencies?: { [Name in keyof CmodDependencies]?: CmodDependencies[Name] }
+  readonly files?: Readonly<Record<string, string>>
+}
+```
+
+| Option | What it sets | Default |
+| --- | --- | --- |
+| `state` | Values over the declared starting state | The declared state |
+| `scope` | `'project'` makes the mod a project plugin, in `<projectRoot>/.claude/skills/<name>` | `'user'` |
+| `projectRoot` | `mod.projectRoot` | `/test/plugins/<name>`, or `/test/project` for a project plugin |
+| `cwd` | `mod.cwd` | `projectRoot` |
+| `dependencies` | The methods other mods answer with | none: every call fails with `<name> is not installed. Run cmod install <name>.` |
+| `files` | The fake file system, absolute path to text | no files |
+
+A project plugin finds its repository through a `.git` entry at `projectRoot`, so a test of one puts it in `files`, such as `files: { '/test/project/.git': '' }`. Without it the project plugin has no repository, and its rules match calls in every folder, as a user mod's do.
+
+The fake session's id is `test-session`, its model is `test-model`, and its home is `/test/home`. So `mod.dataFolder` is `/test/home/.local/share/cmod/data/<name>`. The mod is installed and draws on a terminal 80 columns wide.
+
+## TestedMod
+
+```ts
+type TestedMod<State> = {
+  start(): Promise<void>
+  fire(event, input, below?): Promise<EventResult>
+  settle(): Promise<void>
+  lines(paneId: string): Promise<string[]>
+  lines(slot, props, requestId?): Promise<string[]>
+  type(line: string): Promise<Reply>
+  callTool(name: string, input: Record<string, unknown>): Promise<EventResult<'tool.call'>>
+  press(paneId: string, key: string): Promise<void>
+  moveTo(projectRoot: string, cwd?: string): Promise<void>
+  readonly state: Readonly<State>
+  readonly calls: readonly TestCall[]
+  readonly fakes: Fakes
+  readonly shown: Shown
+}
+```
+
+### start
+
+Starts the mod: loads its state, runs `setup`, and adds its parts. `fire`, `lines`, `type`, `callTool`, `press`, and `moveTo` start the mod first, so a test calls `start` only before it reads `state` or `shown` with nothing else to run. It rejects with the reason when the mod does not start.
+
+### fire
+
+```ts
+fire<E extends ModEvent>(event: E, input: TestInput<E>, below?): Promise<EventResult<`classic.${E}`>>
+fire<N extends RoutedEvent>(event: N, input: Args<N>, below?): Promise<EventResult<N>>
+```
+
+- `fire('UserPromptSubmit', { prompt: 'hello' })` runs the mod's hooks on a `ModEvent`. `TestInput<E>` is the event's input without the fields `fire` fills: `session_id`, `transcript_path`, `cwd`, `hook_event_name`, and a new `tool_use_id` for each tool event.
+- For a tool event, `files` is worked out from the call and the test's `files`, as in Claude Code.
+- `below` is what the hooks beneath the mod answered. Pass it to test how the mod's answer combines with another, such as a `deny` beneath. When nothing in the mod answers, `fire` returns `below` as it is.
+- Left out, `below` is `{}`, except on `prompt.submit`, where it is what Claude Code answers: the prompt that entered, `{ text, context, origin }`, with the `context` the mod's hooks added.
+- It returns the combined answer in Claude Code's own field names: `additionalContext` is a list, a `PreToolUse` decision is `allow: true`, or the key `ask` or `deny` with the reason as its value, and `decision: 'block'` is `block`.
+- `fire('tool.check', { tool: 'Edit', input: { … }, tool_use_id: 'toolu_1' }, { decision: 'allow' })` asks the mod's permission rules about any call. A name with a dot fires that Claude Code hook-module event as it is.
+
+```ts
+import { expect, test } from 'bun:test'
+import { testMod } from '../node_modules/@cmodjs/core/testing.js'
+import { guard } from '../src/mod.js'
+
+test('a force push is denied with the reason', async () => {
+  const tested = testMod(guard)
+
+  const answer = await tested.fire('tool.check', { tool: 'Bash', input: { command: 'git push --force' }, tool_use_id: 'toolu_1' }, { decision: 'allow' })
+
+  expect(answer).toEqual({ decision: 'deny', reason: 'Force pushes rewrite shared history.' })
+})
+```
+
+### Test a prompt with when
+
+A `prompt` with `when` runs on the hook-module event `prompt.submit`, not on `UserPromptSubmit`, so `fire('UserPromptSubmit', …)` never reaches it. `fire('prompt.submit', …)` returns the prompt that entered, with the text the prompt added in its `context`:
+
+- The `prompt.submit` input is `{ text, wait, origin }`. A prompt the person typed has `wait: false` and `origin: { kind: 'composer' }`.
+- `context` is a list of strings, each `# <name>\n<text>`. The answer has no `context` when no prompt added anything.
+
+```ts
+import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+import { prompt } from '../node_modules/@cmodjs/core/jobs/prompt.js'
+
+export const release = defineMod({
+  name: 'release',
+  setup(mod) {
+    mod.use(prompt({ name: 'release-steps', prompt: 'Run bun run release, then push the tag.', when: /\brelease\b/i }))
+  },
+})
+```
+
+```ts
+import { expect, test } from 'bun:test'
+import { testMod } from '../node_modules/@cmodjs/core/testing.js'
+import { release } from '../src/mod.js'
+
+test('a prompt about a release gets the release steps, and another prompt gets nothing', async () => {
+  const tested = testMod(release)
+  const typed = { wait: false, origin: { kind: 'composer' } } as const
+
+  const aboutRelease = await tested.fire('prompt.submit', { text: 'Cut a release', ...typed })
+  const aboutBug = await tested.fire('prompt.submit', { text: 'Fix the bug', ...typed })
+
+  expect(aboutRelease).toEqual({ text: 'Cut a release', context: ['# release-steps\nRun bun run release, then push the tag.'], origin: typed.origin })
+  expect(aboutBug).toEqual({ text: 'Fix the bug', origin: typed.origin })
+})
+```
+
+### settle
+
+Waits until the work a hook started without awaiting it has run, such as a `void` call in a `Stop` hook. It returns while a fake the test holds open has not answered.
+
+### lines
+
+- `lines(paneId)` draws an open pane and returns its rows of text. It rejects a pane that is not open: open it first with `tested.type('/<command>')` or `pane.open()` in the mod. The render gets the props `title`, `isFocused: false`, `bodyColumns`, `placement: 'dock'`, `scroll: { offset: 0, bodyRows: 24 }`, and `view: {}`, the main conversation's view.
+- `lines(slot, props, requestId?)` draws a slot render with `props` and returns its rows. `Default` draws a plain listing of the props it gets, so a test sees what the render changed. Draw `slots.AssistantMessage` with a reply's `text` to test a markdown slot render. Draws that pass one `requestId` grow one streamed reply.
+
+```ts
+import { expect, test } from 'bun:test'
+import type { RenderPropsOf } from 'claude-code'
+import { testMod } from '../node_modules/@cmodjs/core/testing.js'
+import { slots } from '../node_modules/@cmodjs/core/ui/slots.js'
+import { hints } from '../src/mod.js'
+
+const band: RenderPropsOf['AbovePrompt'] = { hasSurvey: false, isWorking: false, maxRows: 12, bodyColumns: 75, scroll: { offset: 0, bodyRows: 12 }, view: {} }
+
+test('the band shows the prompt count on its last line', async () => {
+  const tested = testMod(hints)
+  await tested.fire('UserPromptSubmit', { prompt: 'hello' })
+
+  expect((await tested.lines(slots.AbovePrompt, band)).at(-1)).toBe('Prompts: 1')
+})
+```
+
+### type
+
+`type('/<command> <arguments>')` runs a slash command as the person types it and returns its reply, `{ text?, context? }`. It rejects a line that does not start with `/`, and a command the mod does not add.
+
+### callTool
+
+`callTool(name, input)` runs the mod's permission rules on a call of its own tool, then the tool. `name` is the name given to `tool`, without `mcp__<plugin>__`. It returns `{ result }`, or `{ deny }` when a rule or the input check denies the call. It rejects a call a rule would ask the person about, and a tool the mod does not add.
+
+### press
+
+`press(paneId, key)` presses the `Button` of an open pane whose `key` or `label` is `key`, and awaits its `onPress`.
+
+### moveTo
+
+`moveTo(projectRoot, cwd?)` moves the session. A new `projectRoot` runs a `/cd` there, so the mod loads that project's state. A `cwd` then runs a Bash `cd` there. The mod's `CwdChanged` hooks run for each move.
+
+### state
+
+The mod's current values. Reading it before the mod starts throws.
+
+### calls
+
+Every call the mod made to the fake Claude Code, in order, as `{ call, args }`, such as `{ call: 'process.run', args: [['git', 'status'], { cwd: '/work' }] }` and `{ call: 'cmod.call', args: [{ to, method, input }] }`.
+
+### fakes
+
+```ts
+type Fakes = {
+  process: { run?, spawn? }
+  fs: { read?, write?, list?, exists?, stat? }
+  http: { fetch? }
+  settings: { read? }
+  ui: { ask?, open? }
+  agent: { list? }
+  clock: { after?, every? }
+  cmod: { call? }
+}
+```
+
+Set a fake to answer a call:
+
+- A call with no fake throws `<call>(<args>) has no fake answer. Set fakes.<call> on the tested mod.` So set `fakes.process.run` before a test runs a program, and `fakes.ui.ask` before the mod asks a question.
+- A `program` job is the exception: it catches the `process.spawn` error and retries after 1, 2, 4, 8 and 16 seconds on real timers, so its `ready()` waits past `bun test`'s 5-second timeout. Set `fakes.process.spawn` before a test starts a `program` job.
+- `files` already fills the `fs` fakes: a write is read back, and `list` lists the given files. The fake file system resolves a relative path against `/`, not against `mod.cwd`, so a mod under test reads `${mod.projectRoot}/<file>` rather than a relative path. `fs.list()` with no path rejects.
+- `ui.open` places every pane by default. A fake that answers `{ isPlaced: false }` holds a pane back.
+- `clock.after(ms, fn)` and `clock.every(ms, fn)` each return `{ cancel() }`, and so must a fake of either. `clock.after` runs a real timer by default. `clock.every` never fires unless a fake keeps `fn` for the test to call.
+
+```ts
+import { expect, test } from 'bun:test'
+import { testMod } from '../node_modules/@cmodjs/core/testing.js'
+import { committer } from '../src/mod.js'
+
+test('a Commit answer commits', async () => {
+  const tested = testMod(committer)
+  tested.fakes.ui.ask = async () => 'Commit'
+  tested.fakes.process.run = async () => ({ exitCode: 0, stdout: '', stderr: '', isStdoutTruncated: false, isStderrTruncated: false })
+
+  await tested.fire('Stop', { stop_hook_active: false })
+
+  expect(tested.calls.filter(({ call }) => call === 'process.run').map(({ args }) => args[0])).toEqual([['git', 'commit', '-am', 'wip']])
+})
+```
+
+### shown
+
+```ts
+type Shown = {
+  readonly toasts: string[]
+  readonly logs: string[]
+  readonly debug: string[]
+  readonly statuses: (string | undefined)[]
+  readonly openPanes: Set<string>
+  readonly commands: string[]
+  readonly tools: string[]
+}
+```
+
+What the person would see: the toasts, the log lines, the debug log lines, each status line text, the open panes, and the slash commands and tools the mod added.
+
+`testing.js` exports the types `TestOptions`, `TestInput`, `TestedMod`, `Fakes`, `Shown`, and `TestCall`, so a test helper can take them.
+
+## Run the tests
+
+Run `bun test` in the mod's folder. `cmod check` runs the test files the same way, all but those that import `claude-code/testing`. A test file that imports `claude-code/testing` is for Claude Code's own test kit, and `cmod check` runs those with `claude plugin test` instead. `testMod` tests import neither.