@lumpcode/cli 0.0.0

package/DOCS/advanced-config.md

@@ -0,0 +1,261 @@
+# Advanced Lumpcode CLI configuration
+
+This page is the deep-dive companion to [lump-config.md](./lump-config.md): where that page lists every config field at table depth, this one covers the parts that need more — **hook lifecycle**, **dynamic prompt lists**, **workspace overrides**, and **custom agent command modules**. Operations (daemon, cron, isolated repo copies, workspace presets) live in [concepts.md](./concepts.md); type shapes live in [types.md](./types.md).
+
+Every `*Fn` field below is a [function reference](./lump-config.md#field-forms-conventions) — either:
+
+- an **inline function** — only in `config.js`, or
+- a **string path** to a `.js` module whose **default export** is the function — works in both `config.json` and `config.js`.
+
+Relative paths resolve from the lump folder.
+
+---
+
+## Hook lifecycle
+
+For one tick of `lumpcode run <lumpName>`:
+
+```pseudocode
+pre-flight ─ pull projectBaseBranch into the resolved workspace
+             (mode = shared → copy under ~/.lumpcode/project-copies/<projectName>/)
+             (mode = dedicated → the checkout itself, with destructive reset)
+discover contexts ─ contextListJson | getContextListFn | contextMatchFn
+                  └─ contextOptionsFn        (only with contextListJson)
+batch contexts    → branchFn                 (one branch name for the batch)
+auto-setupWorkspace                          (fetch + reset + pull baseBranch, fresh lump branch)
+for each context in batch:
+  setupFn                                    (seeds contextRunState)
+  for each prompt item:
+    if item is a function:                   (dynamic steps — see below)
+      sub-items = item({ context, contextRunState, … })
+      recurse on sub-items
+    else:                                    (classic case)
+      promptFn                               (or promptTemplate substitution)
+      command  →  CommandFn → executable + args
+      postCommandExecFn      
+  teardownFn                                 (receives accumulated contextRunState)
+  git add + git commit                       (LUMP: <lumpName> - <ctx>)
+git push                                     (once per batch)
+auto-teardownWorkspace                       (git switch projectBaseBranch — always)
+```
+
+The pre-flight, per-lump fetch/branch, and per-lump teardown are all generated by the CLI — they are not configurable in lump config. The baseline lifecycle ties to **`projectBaseBranch`** from [local-config.md](./local-config.md); lump-level `baseBranch` only overrides the per-lump fetch, not the teardown switch-back.
+
+`setupFn` / `teardownFn` from the lump config are **composed** with every loaded command module's `setup` / `teardown` — see [Custom agent commands](#custom-agent-commands).
+
+### `contextRunState`
+
+A mutable bag scoped to **one context execution**. Not shared across contexts, batches, or runs. The same object reference is passed into every hook below — any of them can read **or** mutate it. The "typical use" column is convention, not enforcement.
+
+
+| Stage                          | Typical use                                                                        |
+| ------------------------------ | ---------------------------------------------------------------------------------- |
+| `setupFn`                      | Seed the bag — its returned `{ contextRunState: { … } }` becomes the initial value |
+| `promptFn`                     | Read (e.g. interpolate previous results into prompt text)                          |
+| `commandFn`                    | Read (e.g. switch `executable` / `args` based on a flag)                           |
+| `postCommandExecFn`            | Mutate (parse stdout, set flags for later steps)                                   |
+| Dynamic `steps` function | Read (gate the next prompt)                                                        |
+| `teardownFn`                   | Read the accumulated `contextRunState`                                             |
+
+
+Type: [types.md](./types.md#contextrunstate).
+
+---
+
+## Hook reference
+
+Detailed shapes live in [types.md](./types.md); runnable code lives in [examples.md](./examples.md). This table summarises **purpose, gotchas, and where to look**.
+
+### Discovery
+
+
+| Hook | Purpose | Gotcha | Example |
+|------|---------|--------|---------|
+| [`getContextListFn`](./types.md#getcontextlistfn) | Return a fully custom `Context[]` (e.g. ticket queue, external API) | `variables` map values **must be strings** — they feed prompt substitution and git paths | [Example 2](./examples.md#2-feature-ticket-queue--strict-dependency-order) |
+| [`contextMatchFn`](./types.md#contextmatchfn) | Per-file matcher: Lumpcode walks every `CodeBasePath` and calls you once per file/dir with `codeBasePath`, the full `codeBasePaths` list, and `lumpVariables` | Multiple files returning the same `contextName` **merge** into one context (variables and options merge; later files override); use `codeBasePaths` for cross-file skip or merge logic | [Examples 3 & 4](./examples.md#3-test-coverage-sweep--add-a-test-next-to-every-untested-module) |
+| [`contextOptionsFn`](./types.md#contextoptionsfn) | Attach `priority` / `dependsOnContexts` to `contextListJson`-derived contexts | **Only** runs with `contextListJson`; ignored for `getContextListFn` / `contextMatchFn` (those attach `options` on their returned data) | — |
+
+### Per-context lifecycle
+
+
+| Hook | Purpose | Gotcha |
+|------|---------|--------|
+| [`branchFn`](./types.md#branchfn) | Override the default `lump/<lumpName>/<contextNames…>` branch name | Returns **one** branch name for the whole batch (all contexts in `numberOfContextsPerBranch`) |
+| [`setupFn`](./types.md#setupfn) | Seed `contextRunState` before the prompt loop for one context | Runs once per context index, **not** once per prompt item |
+| [`teardownFn`](./types.md#teardownfn) | Cleanup, metrics, post-processing after all prompt items for one context | Receives the accumulated `contextRunState` |
+
+
+### Per-step
+
+
+| Hook | Purpose | Gotcha |
+|------|---------|--------|
+| [`promptFn`](./types.md#promptfn) | Build prompt text with custom logic (inject `contextRunState`, branch on `stepIndex`, …) | Mutually exclusive with `promptTemplate` on the same item; per-item, not per-context |
+| [`postCommandExecFn`](./types.md#postcommandexecfn) | Parse the agent's stdout and stash flags on `contextRunState` (gate the next prompt, enforce JSON contracts) | `commandResult` is **raw stdout** (string) |
+
+
+---
+
+## `promptFn`
+
+Use `promptFn` when `promptTemplate` is not enough — it gives you fine-grained control over how each prompt is built (inject `contextRunState` from a previous step, switch on `stepIndex`, run any custom logic). Inline in `config.js`, or as a [function reference](./lump-config.md#field-forms-conventions) string path from either format.
+
+```js
+export default {
+  baseBranch: 'main',
+  contextListJson: { FILE: 'src/{NAME}.ts' },
+  command: 'claude',
+  steps: [
+    {
+      promptFn: ({ context, contextRunState }) => {
+        const focus = contextRunState.perfIssues ? 'performance' : 'general code quality';
+        return `Review @${context.variables.FILE}, focusing on ${focus}.`;
+      },
+    },
+  ],
+};
+```
+
+`promptFn` and `promptTemplate` are **mutually exclusive** on the same prompt item.
+
+---
+
+## Dynamic `steps`
+
+In `config.js`, an element of `steps` may be a **function** that receives the same inputs as a `promptFn` and returns **another** `steps` array (possibly empty) to expand inline.
+
+This enables branching workflows:
+
+```js
+export default {
+  baseBranch: 'main',
+  contextListJson: { FILE: 'src/{NAME}.ts' },
+  command: 'claude',
+  steps: [
+    {
+      promptTemplate: 'Does @{FILE} need a README section? Reply YES or NO only.',
+      postCommandExecFn: ({ commandResult, contextRunState }) => {
+        contextRunState.needsDocs = commandResult.trim().toUpperCase().includes('YES');
+      },
+    },
+    ({ contextRunState }) =>
+      contextRunState.needsDocs
+        ? [{ promptTemplate: 'Add minimal module docs for @{FILE}.' }]
+        : [],
+  ],
+};
+```
+
+Full runnable variant: [Example 6](./examples.md#6-conditional-follow-up--only-do-step-b-if-step-a-says-so).
+
+### `stepIndex` paths
+
+For static items, `stepIndex` is a number (`0`, `1`, …). Inside arrays returned by a function item, nested items receive `stepIndex` as `number[]` — e.g. `[1, 0]` for the first nested prompt under function item `1`. Deeper nesting grows the array.
+
+### `registerCommands`
+
+If the **only** reference to a custom `command` name appears inside a dynamic function return, register it up front:
+
+```json
+"registerCommands": ["my-agent"]
+```
+
+Otherwise lazy loading may throw when the nested array resolves.
+
+---
+
+## Custom agent commands
+
+Place modules at:
+
+1. `.lumpcode/commands/<name>.js` — **project-local**
+2. `~/.lumpcode/commands/<name>.js` — **global user override**
+3. `~/.lumpcode/commands/presets/<name>.js` — **shipped preset** (installed automatically on first run)
+
+Reference them from `command` fields by **string name** (`"my-agent"`, `"cursor"`, `"copilot"`), same as built-in names. **First existing file wins** in the order above.
+
+### Shipped presets
+
+Lumpcode ships ready-made modules for common CLI agents. Set `"command": "cursor"` or `"command": "copilot"` in lump config — no custom module required. You still need the agent binary on `PATH` (`cursor-agent`, `copilot`).
+
+| Preset name | Agent binary | Default model (`stepVariables.model`) |
+| ----------- | ------------ | --------------------------------------------- |
+| `cursor` | `cursor-agent` | `composer-2.5` |
+| `copilot` | `copilot` | `auto` |
+
+On first `run`, `start`, or `lump-plan`, missing preset files are copied into `~/.lumpcode/commands/presets/` without overwriting files already there. To restore shipped defaults after editing presets, use `lumpcode reset-presets` (when available) or replace the files manually.
+
+Override a preset by placing `~/.lumpcode/commands/<name>.js` (global) or `.lumpcode/commands/<name>.js` (project-local).
+
+Each module exports:
+
+
+| Export     | Required | Description                                                      |
+| ---------- | -------- | ---------------------------------------------------------------- |
+| `command`  | **Yes**  | Same contract as `commandFn` in [types.md](./types.md#commandfn) |
+| `setup`    | No       | Composed with the lump's `setupFn` (see below)                   |
+| `teardown` | No       | Composed with the lump's `teardownFn` (see below)                |
+
+
+For editor hints, install [`@lumpcode/cli-types`](https://www.npmjs.com/package/@lumpcode/cli-types) and use `defineCommand`, `defineCommandSetup`, `defineCommandTeardown` (or `defineCommandModule` for the whole file):
+
+```js
+import { defineCommand, defineCommandSetup } from '@lumpcode/cli-types';
+
+export const command = defineCommand(({ prompt, stepVariables }) => ({
+  executable: 'my-agent',
+  args: ['--message', prompt],
+}));
+
+export const setup = defineCommandSetup(async () => ({}));
+```
+
+### `workspacePath` vs `projectRoot` in `command`
+
+Lump configs do **not** define `projectRoot`; the CLI resolves it as the directory that contains `.lumpcode/`. Both fields below are runtime parameters on your `CommandFn`:
+
+- **`projectRoot`** — **project workspace**: the source checkout where `.lumpcode/` lives (always your repo in `shared` mode; same as the execution workspace in `dedicated` mode).
+- **`workspacePath`** — **branch workspace**: where the agent process runs for this lump (the engine sets `cwd: workspacePath` for you). With `workspaceStrategy: "checkout"`, this equals the execution workspace (project copy in `shared`, checkout in `dedicated`). With `"worktree"`, it is a linked worktree under `.lumpcode/worktrees/<branch>/` inside the execution workspace. See [concepts.md § Three workspaces](./concepts.md#three-workspaces) and [local-config.md](./local-config.md).
+
+The CLI also resolves an **execution workspace** (git repo root after pre-flight)—not passed to `CommandFn`. In `shared` mode that is `~/.lumpcode/project-copies/<projectName>/`; in `dedicated` mode it matches `projectRoot`.
+
+### How `setup` / `teardown` compose
+
+Lumpcode wraps the lump-level `setupFn` and `teardownFn` to also run every loaded command module's `setup` / `teardown`, in this order:
+
+
+| Stage    | Order                                                                                |
+| -------- | ------------------------------------------------------------------------------------ |
+| Setup    | lump `setupFn` first → then each command module's `setup` (registration order)       |
+| Teardown | each command module's `teardown` first (registration order) → then lump `teardownFn` |
+
+
+State merge in `contextRunState`:
+
+- The lump's `setupFn` returns `{ contextRunState }` — its keys go directly into the bag.
+- Each command module's `setup` return goes under a **namespaced key**: `contextRunState["<commandName>Setup"]`. Namespacing prevents two modules from clobbering each other.
+
+---
+
+## Workspace handling
+
+Per-lump git setup is generated by the CLI from the execution workspace (resolved at pre-flight), `local.json` `workspaceStrategy`, and the lump's `baseBranch`. There are **no** `workspaceSetup`, `setupWorkspaceFn`, or `teardownWorkspaceFn` knobs in lump config.
+
+| `workspaceStrategy` | Behavior |
+| ------------------- | -------- |
+| `checkout` (default) | Main worktree: fetch/reset/pull `baseBranch`, `git switch -c` lump branch; teardown switches back to `projectBaseBranch`. |
+| `worktree` | Main worktree stays on `projectBaseBranch`; agent runs in `.lumpcode/worktrees/<branch>/`; teardown removes the worktree. |
+
+Pick `mode` (`shared` / `dedicated`) and `workspaceStrategy` in [local-config.md](./local-config.md). Worktrees are always created under the execution workspace (project copy in `shared`, checkout in `dedicated`).
+
+---
+
+## Related documentation
+
+- [lump-config.md](./lump-config.md) — Field reference
+- [local-config.md](./local-config.md) — Per-machine `local.json` (`mode`, `projectBaseBranch`, `workspaceStrategy`)
+- [concepts.md](./concepts.md) — Daemon, pre-flight, status lifecycle
+- [types.md](./types.md) — Hook signatures
+- [examples.md](./examples.md) — Runnable lump configs
+- [commands.md](./commands.md) — `run`, `start`, `daemon-status`, `clean`
+