mini-coder 0.0.4 → 0.0.6

package/README.md

@@ -53,7 +53,10 @@ I can also connect to **MCP servers** (like Exa for web search), giving you supe
 - **Multi-provider** — set `OPENCODE_API_KEY` for Zen, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, or just run Ollama locally. I auto-discover whatever's available.
 - **Session memory** — conversations are saved in a local SQLite database. Resume where you left off with `-c` or pick a specific session with `-r <id>`.
 - **Shell integration** — prefix with `!` to run shell commands inline. Use `@` to reference files in your prompt (with Tab completion).
-- **Slash commands** — `/model` to switch models, `/plan` for read-only thinking mode, `/ralph` for autonomous looping (agent re-runs your goal with fresh context each iteration until it signals done), `/review` for a code review, `/undo` to roll back a turn, `/new` for a clean session, `/mcp` to manage MCP servers.
+- **Slash commands** — `/model` to switch models, `/plan` for read-only thinking mode, `/ralph` for autonomous looping, `/review` for a code review, `/undo` to roll back a turn, `/new` for a clean session, `/mcp` to manage MCP servers. See all with `/help`.
+- **Custom commands** — drop a `.md` file in `.agents/commands/` and it becomes a `/command`. Supports argument placeholders (`$ARGUMENTS`, `$1`…`$9`) and shell interpolation (`` !`cmd` ``). Global commands live in `~/.agents/commands/`. Custom commands take precedence over built-ins. → [docs/custom-commands.md](docs/custom-commands.md)
+- **Custom agents** — drop a `.md` file in `.agents/agents/` (or `~/.agents/agents/` globally) and reference it with `@agent-name` in your prompt. The agent runs in its own context window with a custom system prompt and optional model override. → [docs/custom-agents.md](docs/custom-agents.md)
+- **Skills** — place a `SKILL.md` in `.agents/skills/<name>/` and inject it into any prompt with `@skill-name`. Skills are *never* auto-loaded — always explicit. → [docs/skills.md](docs/skills.md)
 - **Post-tool hooks** — drop an executable at `.agents/hooks/post-<tool>` and I'll run it after every matching tool call.
 - **Beautiful, minimal output** — diffs for edits, formatted trees for file searches, a live status bar with model, git branch, and token counts.
 - **16 ANSI colors only** — my output inherits *your* terminal theme. Dark mode, light mode, Solarized, Gruvbox — I fit right in.
@@ -64,17 +67,35 @@ I can also connect to **MCP servers** (like Exa for web search), giving you supe
 
 - **I eat my own dog food.** I was built *by* a mini-coder agent. It's agents all the way down. 🐢
 - **I'm tiny but mighty.** The whole runtime is [Bun.js](https://bun.com) — fast startup, native TypeScript, and a built-in SQLite driver.
-- **I respect existing conventions.** Hook scripts live in `.agents/hooks/`, context in `AGENTS.md` or `CLAUDE.md` — I follow the ecosystem instead of inventing new standards.
+- **I respect existing conventions.** Hook scripts live in `.agents/hooks/`, context in `AGENTS.md` or `CLAUDE.md`, commands in `.agents/commands/`, agents in `.agents/agents/`, skills in `.agents/skills/` — I follow the ecosystem instead of inventing new standards.
 - **I spin while I think.** ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ (It's the little things.)
 - **I can clone myself.** The `subagent` tool lets me spin up parallel instances of myself to tackle independent subtasks simultaneously. Divide and conquer! (Up to 3 levels deep.)
 
 ---
 
+## 📁 The `.agents` folder
+
+mini-coder follows the [`.agents` convention](https://github.com/agentsmd/agents) used across the AI coding tool ecosystem. Drop files in `.agents/` to extend behaviour for the current repo, or `~/.agents/` to apply them globally.
+
+| Path | What it does |
+|---|---|
+| `.agents/commands/*.md` | Custom slash commands (`/name`) |
+| `.agents/agents/*.md` | Custom agents (`@name`) |
+| `.agents/skills/<name>/SKILL.md` | Reusable skill instructions (`@name`) |
+| `.agents/hooks/post-<tool>` | Scripts run after a tool call |
+| `AGENTS.md` | Project context injected into every system prompt |
+
+Local always overrides global. The same `~/.agents/` folder is shared with Claude Code, Opencode, and other compatible tools — skills and agents you write once work everywhere.
+
+---
+
+
 ## 🚀 Getting Started
 
 ```bash
-# Install globally
-bun run build && bun add -g mini-coder@file:$(pwd)
+# Install from npm
+bun add -g mini-coder
+# or: npm install -g mini-coder
 
 # Set your provider key (pick one — or run Ollama locally)
 export OPENCODE_API_KEY=your-zen-key    # recommended
@@ -137,4 +158,12 @@ I believe the best tools disappear into your workflow. I don't want to be the st
 
 ---
 
+## 💬 What People Are Saying
+
+> "sean this is fucking sick"
+> — [vpr99](https://github.com/vpr99) (eric)
+
+---
+
+
 *Built with ❤️ and a healthy obsession with terminal aesthetics.*

package/better-errors.md

@@ -0,0 +1,96 @@
+# 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).