@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/plans/0206-decompose-show-agent-detail.md

@@ -1,211 +0,0 @@
----
-issue: 206
-issue_title: "Decompose showAgentDetail (cognitive 33)"
----
-
-# Decompose `showAgentDetail`
-
-## Problem Statement
-
-`showAgentDetail` in `ui/agent-config-editor.ts` has cognitive complexity 33 (CRITICAL per fallow health).
-It interleaves menu-option computation, user-choice dispatch, and three inline action handlers (edit, delete, reset) in a single 67-line function.
-`ejectAgent` in the same file has cognitive complexity 20 from its 14-branch frontmatter builder.
-Phase 12, Step 2 targets cognitive complexity < 10 per function.
-
-## Goals
-
-- Extract menu-option computation and inline action handlers into separate functions, each with cognitive complexity < 10.
-- Extract frontmatter building from `ejectAgent` into a pure function.
-- Preserve all existing behavior — no user-visible or API changes.
-- Add unit tests for the two new exported pure functions.
-
-## Non-Goals
-
-- Decomposing `renderWidgetLines` (#205), `update` (#207), or shared test fixtures (#208) — sibling Phase 12 steps.
-- Changing the menu structure, option labels, or action semantics.
-- Decomposing `disableAgent` or `enableAgent` — their cognitive complexity is already manageable (< 15).
-
-## Background
-
-`agent-config-editor.ts` was extracted from `agent-menu.ts` in Phase 8 (#136).
-The file exposes a single factory `createAgentConfigEditor` that returns `{ showAgentDetail }`.
-Internally the factory closes over `fileOps`, `registry`, `personalAgentsDir`, and `projectAgentsDir`.
-
-Three action handlers already exist as closure-level functions: `ejectAgent`, `disableAgent`, `enableAgent`.
-The remaining three actions — Edit, Delete, and Reset to default — are inlined in `showAgentDetail`'s if/else dispatch chain.
-
-The existing test suite (`test/ui/agent-config-editor.test.ts`, 18 tests) covers all menu-option combinations and action branches through the public `showAgentDetail` entry point.
-
-### Complexity sources
-
-`showAgentDetail` (cognitive 33):
-
-1. Menu-option building — 4-branch if/else chain with 3 boolean conditions (`disabled`, `isDefault`, `file`).
-2. Action dispatch — 6-branch if/else chain based on `choice`.
-3. Inline Edit handler — 3 nested `if` guards (`file`, `content`, `edited !== content`).
-4. Inline Delete handler — nested `if (file)` + `if (confirmed)`.
-5. Inline Reset handler — nested `if (file)` + `if (confirmed)`.
-
-`ejectAgent` (cognitive 20):
-
-1. Location selection + overwrite check — 2 early returns with nested ifs.
-2. Frontmatter field building — 14 conditional `if`/`else if` branches.
-
-## Design Overview
-
-### Extracted from `showAgentDetail`
-
-#### `buildMenuOptions` (exported, pure)
-
-```typescript
-export function buildMenuOptions(
-  cfg: { isDefault?: boolean; enabled?: boolean },
-  file: string | undefined,
-): string[]
-```
-
-Accepts the minimal config shape and file path.
-Returns the menu option array.
-Pure computation — no IO, no side effects.
-Exported for direct unit testing.
-
-#### `handleEdit` (closure-internal)
-
-Handles the Edit action: reads the file, opens the editor, writes if changed.
-Signature: `(ui: MenuUI, name: string, file: string) => Promise<void>`.
-Called only when `file` is defined (guaranteed by menu-option construction).
-
-#### `handleDelete` (closure-internal)
-
-Handles the Delete action: confirms with user, removes file, reloads registry.
-Signature: `(ui: MenuUI, name: string, file: string) => Promise<void>`.
-
-#### `handleReset` (closure-internal)
-
-Handles the Reset to default action: confirms, removes override file, reloads registry.
-Signature: `(ui: MenuUI, name: string, file: string) => Promise<void>`.
-
-### Extracted from `ejectAgent`
-
-#### `buildEjectContent` (exported, pure)
-
-```typescript
-export function buildEjectContent(cfg: AgentConfig): string
-```
-
-Builds the full `.md` file content (frontmatter + system prompt) for an ejected agent.
-Pure function — no IO.
-Exported for direct unit testing.
-
-### After refactoring
-
-`showAgentDetail` becomes a thin orchestrator (~15 lines):
-
-```typescript
-async function showAgentDetail(ui: MenuUI, name: string) {
-  if (registry.resolveType(name) == null) {
-    ui.notify(`Agent config not found for "${name}".`, "warning");
-    return;
-  }
-  const cfg = registry.resolveAgentConfig(name);
-  const file = fileOps.findAgentFile(name, agentDirs());
-
-  const choice = await ui.select(name, buildMenuOptions(cfg, file));
-  if (!choice || choice === "Back") return;
-
-  if (choice === "Edit" && file) await handleEdit(ui, name, file);
-  else if (choice === "Delete" && file) await handleDelete(ui, name, file);
-  else if (choice === "Reset to default" && file) await handleReset(ui, name, file);
-  else if (choice.startsWith("Eject")) await ejectAgent(ui, name, cfg);
-  else if (choice === "Disable") await disableAgent(ui, name);
-  else if (choice === "Enable") await enableAgent(ui, name);
-}
-```
-
-Cognitive complexity: ~5 (one null-check early return + flat dispatch chain with no nesting).
-
-`ejectAgent` becomes:
-
-```typescript
-async function ejectAgent(ui: MenuUI, name: string, cfg: AgentConfig) {
-  const location = await ui.select("Choose location", [...]);
-  if (!location) return;
-  const targetDir = location.startsWith("Project") ? projectAgentsDir : personalAgentsDir;
-  const targetPath = join(targetDir, `${name}.md`);
-  if (fileOps.exists(targetPath)) {
-    const overwrite = await ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
-    if (!overwrite) return;
-  }
-  fileOps.write(targetPath, buildEjectContent(cfg));
-  registry.reload();
-  ui.notify(`Ejected ${name} to ${targetPath}`, "info");
-}
-```
-
-Cognitive complexity: ~6 (two early returns, one ternary, one nested if).
-
-## Module-Level Changes
-
-### Changed: `src/ui/agent-config-editor.ts`
-
-- Add exported `buildMenuOptions(cfg, file)` — pure function extracted from `showAgentDetail`.
-- Add exported `buildEjectContent(cfg)` — pure function extracted from `ejectAgent`.
-- Add closure-internal `handleEdit(ui, name, file)` — extracted from `showAgentDetail` inline logic.
-- Add closure-internal `handleDelete(ui, name, file)` — extracted from `showAgentDetail` inline logic.
-- Add closure-internal `handleReset(ui, name, file)` — extracted from `showAgentDetail` inline logic.
-- Simplify `showAgentDetail` to orchestrate: resolve → build menu → select → dispatch.
-- Simplify `ejectAgent` to delegate frontmatter building to `buildEjectContent`.
-
-No exports are removed or renamed.
-The public API (`createAgentConfigEditor` returning `{ showAgentDetail }`) is unchanged.
-
-### Changed: `test/ui/agent-config-editor.test.ts`
-
-- Add `describe("buildMenuOptions")` with tests for each menu-option combination (5 cases from existing tests, restructured as direct function calls).
-- Add `describe("buildEjectContent")` with tests for minimal config and config with all optional fields.
-- Existing `showAgentDetail` tests remain unchanged as integration coverage.
-
-### Changed: `docs/architecture/architecture.md`
-
-- Update the complexity hotspots table: `showAgentDetail` drops from 25/33 to ~5/5; `ejectAgent` drops from 21/20 to ~6/6.
-
-## Test Impact Analysis
-
-1. **New tests enabled:** Direct unit tests for `buildMenuOptions` (pure function with 5 state combinations) and `buildEjectContent` (pure function with many optional fields).
-   These were previously impossible to test in isolation because the logic was embedded in async UI flows.
-2. **Existing tests that stay:** All 18 `showAgentDetail` tests remain as integration coverage — they exercise the full resolve → menu → dispatch → action pipeline.
-3. **No tests become redundant:** The existing menu-option-structure tests (5 tests) overlap with `buildMenuOptions` unit tests, but they remain valuable as integration tests verifying the full flow produces the correct menu.
-
-## TDD Order
-
-1. **Red → Green:** Add `buildMenuOptions` unit tests (5 cases: default no-file, default with-file, custom with-file, disabled-default with-file, disabled-custom with-file).
-   Export `buildMenuOptions` as a pure function.
-   Extract the menu-option computation from `showAgentDetail` into it.
-   Verify all existing tests pass.
-   Commit: `refactor: extract buildMenuOptions from showAgentDetail`
-
-2. **Red → Green:** Extract `handleEdit`, `handleDelete`, `handleReset` as closure-internal functions.
-   Simplify `showAgentDetail` dispatch to a flat if/else chain calling named handlers.
-   Verify all existing tests pass.
-   Commit: `refactor: extract inline handlers from showAgentDetail`
-
-3. **Red → Green:** Add `buildEjectContent` unit tests (minimal config, config with all optional fields, config with array extensions/skills).
-   Export `buildEjectContent` as a pure function.
-   Extract the frontmatter-building logic from `ejectAgent` into it.
-   Verify all existing tests pass.
-   Commit: `refactor: extract buildEjectContent from ejectAgent`
-
-4. **Docs:** Update the complexity hotspots table in `docs/architecture/architecture.md`.
-   Commit: `docs: update complexity table after showAgentDetail decomposition`
-
-## Risks and Mitigations
-
-| Risk                                                                           | Mitigation                                                                                                     |
-| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
-| `buildMenuOptions` return order must match existing select mock expectations   | Unit tests verify exact array equality; integration tests remain as safety net.                                |
-| `buildEjectContent` frontmatter field ordering is load-bearing for eject tests | Unit tests verify the full content string; existing eject integration test uses `stringContaining` (flexible). |
-| Closure-internal handlers share mutable `fileOps`/`registry` references        | No change from current behavior — they already close over these references.                                    |
-
-## Open Questions
-
-None — the decomposition is mechanical extraction of existing code into named functions.

package/docs/plans/0207-decompose-agent-widget-update.md

@@ -1,242 +0,0 @@
----
-issue: 207
-issue_title: "Decompose update in agent-widget.ts (cognitive 31)"
----
-
-# Decompose `update` in `agent-widget.ts`
-
-## Problem Statement
-
-`update` in `ui/agent-widget.ts` has cognitive complexity 31 (CRITICAL per fallow health).
-It mixes agent state categorization, widget teardown, status bar management, and widget registration dispatch in a single 70-line method.
-Phase 12, Step 3 targets cognitive complexity < 10 per function.
-
-## Goals
-
-- Extract `assembleWidgetState` as an exported pure function (agent list → lightweight counts/flags) that is directly unit-testable.
-- Extract `clearWidget` as a private method encapsulating the "nothing to show" teardown path.
-- Extract `updateStatusBar` as a private method encapsulating status text computation and conditional update.
-- Simplify `update` to a thin orchestrator: guard → assemble → if idle clear → else update status + register.
-- Target: cognitive complexity < 10 for every function in the file.
-
-## Non-Goals
-
-- Decomposing `renderWidgetLines` (#205, done), `showAgentDetail` (#206, done), or shared test fixtures (#208) — sibling Phase 12 steps.
-- Extracting a separate timer-manager class — the timer lifecycle (`ensureTimer` + `clearWidget`) is two lines of `setInterval`/`clearInterval`.
-- Changing the widget's visual output, status bar format, registration timing, or timer interval.
-- Narrowing the `AgentManager` dependency to an interface — tracked separately.
-- Adding end-to-end tests for `AgentWidget` — the widget depends on the Pi TUI context.
-- Changing `dispose` behavior — it remains a shutdown-only teardown path.
-
-## Background
-
-`agent-widget.ts` was substantially decomposed in #148 (Phase 9, Step P), which extracted pure rendering into `widget-renderer.ts`.
-The widget shrank from 374 to ~198 lines.
-`update` remained as a 70-line orchestrator with five interwoven concerns:
-
-1. **Guard** — early return when `uiCtx` is not yet set.
-2. **Agent state categorization** — counting running/queued/finished agents from `listAgents()`.
-3. **Clear path** — unregistering widget, clearing status, stopping timer, cleaning stale `finishedTurnAge` entries.
-4. **Status bar update** — computing status text from running/queued counts, conditionally calling `setStatus`.
-5. **Widget lifecycle** — incrementing `widgetFrame`, registering the widget factory on first use, calling `requestRender()` on subsequent ticks.
-
-Concerns 3–4 consume counts from concern 2 but each has a distinct responsibility.
-
-`categorizeAgents` in `widget-renderer.ts` performs a similar filter but returns full `WidgetAgent[]` arrays for rendering.
-`assembleWidgetState` returns lightweight counts for lifecycle decisions — different outputs for different consumers, not duplication.
-
-No existing tests cover `AgentWidget` methods — `test/widget-renderer.test.ts` covers the rendering layer.
-
-### Complexity sources in `update` (cognitive 31)
-
-1. Agent counting loop with 3-branch if/else (`status` checks + `shouldShowFinished`) — contributes ~6.
-2. Conditional widget clear path: nested checks for `widgetRegistered`, `lastStatusText`, `widgetInterval`, plus a `for`-loop with nested `if` for stale-entry cleanup — contributes ~12.
-3. Status text computation with conditional `if (hasActive)` and nested `if`/push branches — contributes ~5.
-4. Conditional status update (`newStatusText !== this.lastStatusText`) — contributes ~2.
-5. Widget registration dispatch (`if (!widgetRegistered) ... else ...`) — contributes ~4.
-
-### `dispose` is not a duplication target
-
-`dispose` (10 lines, cognitive ~2) and `update`'s idle path share *some* statements — `clearInterval`, `setWidget(undefined)`, `setStatus(undefined)`, flag resets — but differ in two ways:
-
-- **Guards:** `update`'s idle path guards each call (`if (widgetRegistered)`, `if (lastStatusText !== undefined)`) to avoid redundant SDK calls during repeated timer ticks.
-  `dispose` unconditionally calls `setWidget`/`setStatus` (when `uiCtx` exists) as a correctness guarantee during shutdown.
-- **Stale-entry cleanup:** `update`'s idle path cleans `finishedTurnAge` entries for agents no longer in `listAgents()`.
-  `dispose` skips this — the Map is about to be garbage collected.
-
-Per the code-design skill ("duplication is far cheaper than the wrong abstraction" — verify structural context before extracting), these are different lifecycle semantics.
-`dispose` stays as-is; `clearWidget` is extracted only from `update`'s idle path.
-
-## Design Overview
-
-### `assembleWidgetState` (exported, pure)
-
-```typescript
-/** Minimal agent shape needed for widget lifecycle decisions. */
-interface AgentSummary {
-  readonly id: string;
-  readonly status: string;
-  readonly completedAt?: number;
-}
-
-export interface WidgetState {
-  readonly runningCount: number;
-  readonly queuedCount: number;
-  readonly hasFinished: boolean;
-  readonly hasActive: boolean;
-}
-
-export function assembleWidgetState(
-  agents: readonly AgentSummary[],
-  shouldShowFinished: (agentId: string, status: string) => boolean,
-): WidgetState
-```
-
-The input uses a local `AgentSummary` interface (3 fields) rather than `WidgetAgent` (10+ fields).
-This follows ISP — `assembleWidgetState` only reads `id`, `status`, and `completedAt`.
-Tests can pass plain objects without constructing full agent fixtures.
-`AgentRecord` satisfies `AgentSummary` structurally, so no adapter is needed at the call site.
-
-`hasActive` is derived from the counts (`runningCount > 0 || queuedCount > 0`) but included for call-site readability.
-Only `assembleWidgetState` constructs `WidgetState`, so consistency is guaranteed.
-
-### `clearWidget` (private method)
-
-Encapsulates `update`'s "nothing to show" teardown path:
-
-- Unregister widget via `setWidget("agents", undefined)` if `widgetRegistered`.
-- Clear status via `setStatus("subagents", undefined)` if `lastStatusText` is set.
-- Stop timer via `clearInterval` if `widgetInterval` is running.
-- Reset lifecycle flags (`widgetRegistered`, `tui`, `lastStatusText`, `widgetInterval`).
-- Clean stale `finishedTurnAge` entries (agents no longer in `allAgents`).
-
-Accepts `allAgents` as a parameter for the stale-entry cleanup.
-
-```typescript
-private clearWidget(allAgents: readonly AgentSummary[]): void
-```
-
-`dispose` does **not** delegate to `clearWidget` — see "dispose is not a duplication target" above.
-
-### `updateStatusBar` (private method)
-
-Encapsulates the status text concern:
-
-- Compute status text from `runningCount` / `queuedCount` (undefined when `!hasActive`).
-- Call `setStatus("subagents", text)` only when text differs from `lastStatusText`.
-- Cache the new value in `lastStatusText`.
-
-```typescript
-private updateStatusBar(state: WidgetState): void
-```
-
-### After refactoring
-
-```typescript
-update() {
-  if (!this.uiCtx) return;
-
-  const allAgents = this.manager.listAgents();
-  const state = assembleWidgetState(allAgents, (id, status) => this.shouldShowFinished(id, status));
-
-  if (!state.hasActive && !state.hasFinished) {
-    this.clearWidget(allAgents);
-    return;
-  }
-
-  this.updateStatusBar(state);
-  this.widgetFrame++;
-
-  if (!this.widgetRegistered) {
-    this.uiCtx.setWidget("agents", (tui, theme) => {
-      this.tui = tui;
-      return {
-        render: () => this.renderWidget(tui, theme),
-        invalidate: () => {
-          this.widgetRegistered = false;
-          this.tui = undefined;
-        },
-      };
-    }, { placement: "aboveEditor" });
-    this.widgetRegistered = true;
-  } else {
-    this.tui?.requestRender();
-  }
-}
-```
-
-Cognitive complexity: ~4 (one guard early return + one if/else branch + flat registration dispatch).
-
-### Complexity budget
-
-| Function              | Estimated cognitive complexity                  |
-| --------------------- | ----------------------------------------------- |
-| `assembleWidgetState` | ~3 (flat loop with 3 branches)                  |
-| `clearWidget`         | ~6 (4 guards + loop with if)                    |
-| `updateStatusBar`     | ~4 (hasActive check + diff check)               |
-| `update` (after)      | ~4 (guard + idle check + registration dispatch) |
-| `dispose` (unchanged) | ~2                                              |
-
-All under 10.
-
-## Module-Level Changes
-
-### Changed: `src/ui/agent-widget.ts`
-
-- Add local `AgentSummary` interface (3 fields: `id`, `status`, `completedAt?`).
-- Add exported `WidgetState` interface.
-- Add exported `assembleWidgetState(agents, shouldShowFinished)` pure function.
-- Add private `clearWidget(allAgents)` method — extracted from `update`'s idle path.
-- Add private `updateStatusBar(state)` method — extracted from `update`'s status bar logic.
-- Simplify `update` to orchestrate: guard → assemble → if idle clear → else update status + register.
-- `dispose` is unchanged.
-
-No exports are removed or renamed.
-The public API (`AgentWidget` class with `setUICtx`, `onTurnStart`, `ensureTimer`, `markFinished`, `update`, `dispose`) is unchanged.
-`UICtx` type stays exported.
-
-### Unchanged: `test/widget-renderer.test.ts`
-
-No changes — this file covers `widget-renderer.ts` functions, not `agent-widget.ts`.
-
-### Changed: `docs/architecture/architecture.md`
-
-- Update the complexity hotspots table: remove `update` row (no longer ≥ 21 cyclomatic).
-- Also remove the `renderWidgetLines` row if #205 is already implemented (it is — closed).
-
-## Test Impact Analysis
-
-1. **New tests enabled:** Direct unit tests for `assembleWidgetState` — a pure function accepting plain objects.
-   Tests cover: empty list, running-only, queued-only, finished-only, mixed states, `shouldShowFinished` filtering, agents without `completedAt` excluded from finished.
-   The narrow `AgentSummary` input type means test fixtures are 3-field objects — no need for full agent records.
-2. **No existing tests become redundant** — there are currently no tests for `AgentWidget`.
-3. **No existing tests must change** — `test/widget-renderer.test.ts` (23 tests) exercises the renderer layer and is unaffected.
-
-## TDD Order
-
-1. **Red → Green:** Write unit tests for `assembleWidgetState` covering all agent status combinations.
-   Add the `AgentSummary` interface, `WidgetState` interface, and `assembleWidgetState` function as exported module-level items.
-   Implement to make tests pass.
-   Commit: `feat: extract assembleWidgetState from agent-widget update`
-
-2. **Refactor:** Wire `update` to use `assembleWidgetState`.
-   Extract `clearWidget(allAgents)` method from the idle path.
-   Extract `updateStatusBar(state)` method from the status bar logic.
-   All existing tests pass (no behavior change, no export changes, `dispose` unchanged).
-   Commit: `refactor: decompose update into clearWidget and updateStatusBar`
-
-3. **Docs:** Update the complexity hotspots table in `docs/architecture/architecture.md`.
-   Remove both `renderWidgetLines` (done in #205) and `update` rows.
-   Commit: `docs: update complexity hotspots after widget decomposition`
-
-## Risks and Mitigations
-
-| Risk                                                                                                            | Mitigation                                                                                                                                                                             |
-| --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `assembleWidgetState` has overlapping categorization with `categorizeAgents` in `widget-renderer.ts`            | Different outputs for different consumers: counts+flags for lifecycle vs. full arrays for rendering. Not duplication.                                                                  |
-| No existing tests for `AgentWidget` — refactoring risks are higher for `clearWidget`/`updateStatusBar`          | The pure function `assembleWidgetState` is tested directly. The method extractions are mechanical code moves with no semantic change — the type checker verifies structural integrity. |
-| `clearWidget` guards redundant SDK calls (`if (widgetRegistered)`) — caller might expect unconditional teardown | Only `update`'s idle path calls `clearWidget`. `dispose` stays as-is with its own unconditional teardown semantics.                                                                    |
-
-## Open Questions
-
-None — the decomposition is a mechanical extraction of existing code into named functions and methods, following the pattern established by Phase 12 Steps 1 and 2.