mini-coder 0.0.7 → 0.0.9

package/hanging-bug.md

@@ -0,0 +1,78 @@
+# Hanging Bug Investigation
+
+## Symptoms
+
+After a shell tool call completes successfully, **SOMETIMES** the app hangs indefinitely instead of
+returning to the prompt. Two observed states:
+
+```
+  $ $ rm src/session/db.ts && bun run test
+⠇ shell
+```
+
+Stayed spinning with shell label for well over the timeout time. I had to kill the app.
+
+Another example with a different shell command:
+```
+  $ $ git diff
+    ✔ 0
+    │ diff --git a/src/cli/tool-render.ts b/src/cli/tool-render.ts
+    │ index f8d33af..e224932 100644
+    │ --- a/src/cli/tool-render.ts
+    │ +++ b/src/cli/tool-render.ts
+    │ @@ -148,21 +148,25 @@ export function renderToolResultInline(
+    │   }
+    │
+    │   if (toolName === "glob") {
+    │ -         const r = result as { files: string[]; truncated: boolean };
+    │ -         const n = r.files.length;
+    │ -         writeln(
+    │ -                 `${indent}${G.info} ${c.dim(n === 0 ? "no matches" : `${n} file${n === 1 ? "" : "s"}${r.truncated ? " (capped)" : ""}`)}`,
+    │ -         );
+    │ -         return;
+    │ +         const r = result as { files?: string[]; truncated?: boolean };
+    │ +         if (Array.isArray(r.files)) {
+    │ +                 const n = r.files.length;
+    │ +                 writeln(
+    │ +                         `${indent}${G.info} ${c.dim(n === 0 ? "no matches" : `${n} file${n === 1 ? "" : "s"}${r.truncated ? " (capped)" : ""}`)}`,
+    │ +                 );
+    │ … +150 lines
+⠦ thinking
+```
+User also had to kill the app.
+
+Only seen with Gemini/Google models.
+Only happens after shell tool calls.
+Other tools calls worked just fine during the same session with the same model and mini-coder version.
+There are no shell tool related hooks configured anywhere.
+
+The expectation was the turn to continue as normal since the tool calls succeded.
+
+Find the root cause, show proof.
+
+## Findings:
+
+Here is the concrete proof I just ran, no edits:
+- I executed renderTurn with an event stream that does:
+  1) tool-call-start(shell)
+  2) tool-result(shell success)
+  3) then never yields again
+- Result: the promise did not resolve within 700ms (timed_out_700ms).
+Then I ran the same sequence but added turn-complete:
+- Result: it resolved immediately (resolved).
+So this is now proven in your codepath:
+- renderTurn waits forever when the upstream async stream goes silent after a shell tool result.
+- This exactly matches the visible hang states.
+
+### Root Cause 1: Hangs spinning on `"shell"`
+**Proof in code:** `src/tools/shell.ts`
+*   When a command times out, `proc.kill("SIGTERM")` only kills the parent process (e.g., `bash`). Any child processes (e.g., `bun`) become orphaned but stay alive, holding the write end of the `stdout`/`stderr` pipes open. 
+*   Because the pipe never closes, `await reader.read()` inside `collectStream()` hangs indefinitely. 
+*   Because `collectStream()` never resolves, the tool execution never finishes, `tool-result` is never yielded, and the stream goes completely silent while the spinner stays stuck on "shell".
+
+### Root Cause 2: Hangs spinning on `"thinking"`
+**Proof in code:** `src/llm-api/turn.ts`
+*   After `git diff` completes, the tool resolves and `renderTurn` switches the spinner to `"thinking"`.
+*   The AI SDK automatically makes a new HTTP request to the Gemini API containing the tool result to generate the next step.
+*   Gemini's API occasionally hangs indefinitely or silently drops connections when receiving certain payloads (like large tool outputs or ANSI color codes, which `git diff` outputs).
+*   Because there is no timeout configured on the `streamText` call in `runTurn` (unless the user manually aborts), the underlying fetch request waits forever. The `result.fullStream` never yields the next chunk, but also never closes or errors.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mini-coder",
-	"version": "0.0.7",
+	"version": "0.0.9",
 	"description": "A small, fast CLI coding agent",
 	"module": "src/index.ts",
 	"type": "module",

package/plan-code-health.md

@@ -0,0 +1,169 @@
+# Code Health Remediation Plan
+
+## Goal
+Address maintainability and reliability issues identified in `code-health.md` with low-risk, incremental refactors that keep behavior stable.
+
+## Constraints
+- Keep `mini-coder-idea.md` and `README.md` unchanged.
+- Prefer small PR-sized changes with passing tests after each step.
+- Preserve current CLI behavior while improving structure.
+
+## Workstreams
+
+### 1) Decompose `src/agent/agent.ts` (High)
+**Outcome:** `runAgent` remains orchestration entrypoint; responsibilities split into focused modules.
+
+**Steps:**
+1. Add `src/agent/reporter.ts` interface (narrow surface for output/status/tool events).
+2. Extract session lifecycle + turn loop into `src/agent/session-runner.ts`.
+3. Extract subagent execution into `src/agent/subagent-runner.ts`.
+4. Extract snapshot/undo helpers into `src/agent/undo-snapshot.ts`.
+5. Extract user input processing into `src/agent/input-loop.ts`.
+6. Keep `agent.ts` as composition/wiring file only.
+
+**Checks:**
+- Add/adjust unit tests around orchestration boundaries.
+- Ensure no behavior regressions in interrupts, resume, and tool-call flows.
+
+---
+
+### 2) Decompose `src/cli/output.ts` (High)
+**Outcome:** Rendering responsibilities isolated and testable.
+
+**Target modules:**
+- `src/cli/spinner.ts`
+- `src/cli/tool-render.ts`
+- `src/cli/stream-render.ts`
+- `src/cli/status-bar.ts`
+- `src/cli/error-render.ts`
+- `src/cli/output.ts` as facade
+
+**Steps:**
+1. Extract pure formatting helpers first (no IO).
+2. Extract spinner lifecycle module.
+3. Extract stream queue/tick/flush behavior.
+4. Keep compatibility exports in `output.ts` to avoid broad callsite churn.
+
+**Checks:**
+- Add focused tests for formatting + stream behavior.
+- Verify terminal rendering remains stable manually.
+
+---
+
+### 3) Introduce `TerminalIO` abstraction (Medium)
+**Outcome:** Centralized process/TTY interactions and signal lifecycle.
+
+**Steps:**
+1. Create `src/cli/terminal-io.ts` with methods for stdout/stderr writes, raw mode, signal subscriptions.
+2. Replace direct `process.*` use in output/input stack with injected `TerminalIO`.
+3. Centralize signal registration/unregistration in one lifecycle owner.
+
+**Checks:**
+- Add unit tests for signal registration cleanup semantics.
+- Confirm no stuck raw-mode edge cases.
+
+---
+
+### 4) Split DB layer by domain (Medium)
+**Outcome:** Reduced blast radius and clearer data ownership.
+
+**Target modules:**
+- `src/session/db/connection.ts`
+- `src/session/db/session-repo.ts`
+- `src/session/db/message-repo.ts`
+- `src/session/db/settings-repo.ts`
+- `src/session/db/mcp-repo.ts`
+- `src/session/db/snapshot-repo.ts`
+- `src/session/db/index.ts` (facade exports)
+
+**Steps:**
+1. Move code without behavior changes.
+2. Keep SQL and schema unchanged initially.
+3. Replace direct `JSON.parse` in message loading with guarded parser:
+   - skip malformed rows
+   - emit diagnostic via logger/reporter
+
+**Checks:**
+- Add tests for malformed payload handling.
+- Validate existing DB tests still pass.
+
+---
+
+### 5) Shared markdown config loader (Medium)
+**Outcome:** Remove duplication across agents/skills/custom-commands.
+
+**Steps:**
+1. Create `src/cli/load-markdown-configs.ts` with parameterized layout strategy.
+2. Migrate:
+   - `src/cli/agents.ts`
+   - `src/cli/skills.ts`
+   - `src/cli/custom-commands.ts`
+3. Keep precedence rules identical (built-in/user/project).
+4. Preserve existing frontmatter semantics.
+
+**Checks:**
+- Reuse/expand existing loader tests to cover parity.
+
+---
+
+### 6) Runtime/UI decoupling via reporter boundary (Medium)
+**Outcome:** Core runtime no longer depends directly on terminal rendering.
+
+**Steps:**
+1. Define domain events or reporter interface in `src/agent/reporter.ts`.
+2. Implement CLI reporter adapter in `src/cli/output-reporter.ts`.
+3. Replace direct output calls in agent runtime with reporter calls.
+
+**Checks:**
+- Add tests using test reporter to assert emitted events.
+
+---
+
+### 7) Error observability and silent catches (Medium)
+**Outcome:** Non-fatal failures become diagnosable without crashing.
+
+**Steps:**
+1. Find empty/broad catches in agent/output/loaders.
+2. Add debug-level diagnostics with contextual metadata.
+3. Keep user-facing behavior unchanged unless critical.
+
+**Checks:**
+- Validate noisy paths are still quiet at normal verbosity.
+
+---
+
+### 8) Startup FS sync usage (Low/Deferred)
+**Outcome:** Optional responsiveness improvement if startup cost grows.
+
+**Steps:**
+1. Measure startup and config-loading time first.
+2. If needed, move high-volume file scanning to async or cache results with invalidation.
+
+---
+
+### 9) Test hygiene cleanup (Low)
+**Outcome:** Cleaner CI output.
+
+**Steps:**
+1. Remove `console.log` skip notices in `src/tools/shell.test.ts`.
+2. Use test-framework-native skip annotations/helpers.
+
+---
+
+## Execution Order (recommended)
+1. Reporter interface (foundation for later decoupling).
+2. `agent.ts` decomposition.
+3. `output.ts` decomposition.
+4. Shared config loader extraction.
+5. DB module split + safe JSON parsing.
+6. TerminalIO + centralized signals.
+7. Silent catch diagnostics.
+8. Test hygiene and any deferred FS optimization.
+
+## Definition of Done
+- `bun run typecheck && bun run format && bun run lint && bun test` passes.
+- No behavior regressions in interactive CLI flows.
+- `agent.ts` and `output.ts` materially reduced in size/responsibility.
+- Config loader duplication removed.
+- Message loading resilient to malformed JSON rows.
+- New abstractions documented in code comments where non-obvious.

package/better-errors.md

@@ -1,96 +0,0 @@
-# Better Errors — Implementation Plan
-
-## Overview
-
-Add structured error logging to file and friendly error parsing for display. Three concerns: (1) log full error details to `~/.config/mini-coder/errors.log`, (2) map known AI SDK errors to terse user-facing messages, (3) wire both into existing error surfaces.
-
----
-
-## Files to Create
-
-| File | Purpose |
-|---|---|
-| `src/cli/error-log.ts` | `initErrorLog()`, `logError()` |
-| `src/cli/error-parse.ts` | `parseAppError()` |
-
-## Files to Modify
-
-| File | Change |
-|---|---|
-| `src/index.ts` | Call `initErrorLog()` at startup; use `logError` + `parseAppError` in top-level catch and `main().catch()` |
-| `src/cli/output.ts` | Update `renderError(err: unknown)` to call log + parse; update `turn-error` branch in `renderTurn()` |
-| `src/agent/agent.ts` | Pass `unknown` to `renderError()` — no logic change needed if signature widens correctly |
-
----
-
-## Implementation Steps
-
-1. **Create `src/cli/error-log.ts`**
-   - Module-level `let writer: ReturnType<ReturnType<typeof Bun.file>['writer']> | null = null`
-   - `initErrorLog()`: if `writer` is not null, return early (idempotency). Otherwise resolve path `~/.config/mini-coder/errors.log`, open with `Bun.file(path).writer()` (truncates on open), assign to `writer`. Register `process.on('uncaughtException', (err) => { logError(err, 'uncaught'); process.exit(1) })`.
-   - `logError(err: unknown, context?: string)`: if `writer` is null, return. Build log entry string (see Log Format), call `writer.write(entry)`. Keep sync-ish by not awaiting — `write()` on a Bun file writer is buffered; call `writer.flush()` after each write so data lands before a crash.
-   - Extract error fields via type-narrowing helpers (not exported): `isObject(err)`, read `.name`, `.message`, `.stack`, `.statusCode`, `.url`, `.isRetryable` defensively.
-
-2. **Create `src/cli/error-parse.ts`**
-   - Import AI SDK error classes: `APICallError`, `RetryError`, `NoContentGeneratedError`, `LoadAPIKeyError`, `NoSuchModelError` from `ai`.
-   - Export `parseAppError(err: unknown): { headline: string; hint?: string }`.
-   - Implement as a chain of `instanceof` checks (see Error Parse Table). For `RetryError`, recurse on `.lastError` and prepend `"Retries exhausted: "` to `headline`.
-   - Fallback: extract first non-empty line of `(err as any)?.message ?? String(err)`, no hint.
-   - Network check: before the fallback, check if `(err as any)?.code === 'ECONNREFUSED'` or message includes `'ECONNREFUSED'`.
-
-3. **Update `src/cli/output.ts`**
-   - Change `renderError` signature from `(msg: string)` to `(err: unknown)`. Inside: call `logError(err, 'render')`, call `parseAppError(err)`, print `✖ red(headline)`, if `hint` print a dim indented hint line (e.g. `  dim(hint)`).
-   - In `renderTurn()` `turn-error` branch (non-abort path): replace raw `event.error.message` display with `logError(event.error, 'turn')` then `parseAppError(event.error)` → print `✖ red(headline)`, optional dim hint. Keep the abort quiet-note branch unchanged.
-   - All callers of `renderError` that currently pass a string (e.g. in `agent.ts`) — check each call site; if passing a plain string, wrap in `new Error(string)` or let `parseAppError` fallback handle a string gracefully (add string branch at top of `parseAppError`: `if (typeof err === 'string') return { headline: err }`).
-
-4. **Update `src/index.ts`**
-   - After `registerTerminalCleanup()` (or equivalent startup call), add `initErrorLog()`.
-   - Top-level `catch` around `runAgent()`: replace any raw print with `logError(err, 'agent')` + `parseAppError(err)` → print `✖ red(headline)` + dim hint, then `process.exit(1)`.
-   - `main().catch()`: same pattern — `logError(err, 'main')` + parse + print + `process.exit(1)`. Remove bare `console.error(err)`.
-
-5. **Tests (`src/cli/error-parse.test.ts`)**
-   - Test `parseAppError` for each mapped error type.
-   - Construct real instances where possible (e.g. `new APICallError({ ... })`); check `headline` and `hint` values.
-   - Test `RetryError` unwrapping.
-   - Test fallback for plain `Error` and plain string.
-   - No mocks, no file I/O, no server calls.
-
----
-
-## Error Parse Table
-
-| Condition | `headline` | `hint` |
-|---|---|---|
-| `APICallError` with `statusCode === 429` | `"Rate limit hit"` | `"Wait a moment and retry, or switch model with /model"` |
-| `APICallError` with `statusCode === 401 \|\| 403` | `"Auth failed"` | `"Check the relevant provider API key env var"` |
-| `APICallError` other | `"API error \${statusCode}"` | `url` if present |
-| `RetryError` | `"Retries exhausted: \${inner.headline}"` | inner `hint` |
-| `NoContentGeneratedError` | `"Model returned empty response"` | `"Try rephrasing or switching model with /model"` |
-| `LoadAPIKeyError` | `"API key not found"` | `"Set the relevant provider env var"` |
-| `NoSuchModelError` | `"Model not found"` | `"Use /model to pick a valid model"` |
-| `code === 'ECONNREFUSED'` or message contains `'ECONNREFUSED'` | `"Connection failed"` | `"Check network or local server"` |
-| `string` input | string value | — |
-| fallback | first line of `err.message` | — |
-
-> `AbortError` is never passed to `parseAppError` — abort is handled at the call sites before reaching these functions.
-
----
-
-## Log Format
-
-```
-[2026-02-25T22:38:53.123Z] context=turn
-  name: APICallError
-  message: 429 Too Many Requests
-  statusCode: 429
-  url: https://api.anthropic.com/v1/messages
-  isRetryable: true
-  stack: APICallError: 429 Too Many Requests
-    at ...
----
-```
-
-- Each entry ends with `---\n`.
-- Extra fields (`statusCode`, `url`, `isRetryable`) are only emitted if present on the error object.
-- Stack is indented two spaces per line.
-- File is truncated on each app start (writer opened without append flag).