miii-cli 0.2.4 → 0.2.6

package/README.md

@@ -1,42 +1,53 @@
 # miii
 
-> A local AI coding assistant that actually works. No cloud. No Python. No API keys required.
+> Claude Code-level terminal AI — runs on your machine, zero cloud required.
 
 ```
-╭──────────────────────────────────────────────────────────────╮
-│  miii — Claude Code-level workflows, fully offline           │
-╰──────────────────────────────────────────────────────────────╯
+╭──────────────────────────────────────────────────────────────────────╮
+│  miii  v0.2.5                                                        │
+│  model: qwen2.5-coder:7b                                             │
+├──────────────────────────────────────────────────────────────────────┤
+│  ✦ cross-referencing vibes…                              12s         │
+│  ⚙ running patch_file…                                               │
+│  ⚙ running run_tests…                                                │
+├──────────────────────────────────────────────────────────────────────┤
+│  ❯ █                                                                 │
+│  @ file  / command  enter send  ctrl+c exit                          │
+╰──────────────────────────────────────────────────────────────────────╯
 ```
 
 [![npm version](https://img.shields.io/npm/v/miii-cli)](https://www.npmjs.com/package/miii-cli)
+[![npm downloads](https://img.shields.io/npm/dm/miii-cli)](https://www.npmjs.com/package/miii-cli)
 [![license](https://img.shields.io/npm/l/miii-cli)](LICENSE)
 [![node](https://img.shields.io/node/v/miii-cli)](https://nodejs.org)
 
-![miii demo](mii-cli.gif)
-
 ---
 
-## Why miii exists
+## What is this
 
-Every local AI coding tool is either too clunky to set up, requires cloud APIs, or has terminal output that's genuinely painful to read. miii is what happens when you build a local coding assistant that takes UX seriously — real Ink-based terminal UI, automatic git context, multi-file refactors with task queues, and a context compactor that keeps local models on-track.
+A local AI coding assistant with the workflow depth of Claude Code — file editing, multi-file refactors, test running, git integration, web search — except it runs entirely on your machine using Ollama, or any OpenAI-compatible API.
 
-Your code never leaves your machine.
+No Python. No cloud. No API key required to start. 176K bundle.
 
 ---
 
-## What makes it different
+## Why it beats the alternatives
 
 | Feature | miii | aider | shell_gpt | open-interpreter |
-|---|---|---|---|---|
-| Ink terminal UI | ✅ | ❌ | ❌ | ❌ |
+|---|:---:|:---:|:---:|:---:|
+| Ink terminal UI (not raw text) | ✅ | ❌ | ❌ | ❌ |
 | Zero Python | ✅ | ❌ | ❌ | ❌ |
-| Auto git context | ✅ | ✅ | ❌ | ❌ |
-| Context compaction | ✅ | ✅ | ❌ | ❌ |
+| Auto git context injection | ✅ | ✅ | ❌ | ❌ |
 | Multi-file refactor queue | ✅ | partial | ❌ | ❌ |
-| `.miiiignore` | ✅ | ✅ | ❌ | ❌ |
-| Session persistence | ✅ | ❌ | ❌ | ❌ |
+| Context compaction (keeps local models on-track) | ✅ | ✅ | ❌ | ❌ |
+| Auto-runs tests after file edits | ✅ | ❌ | ❌ | ❌ |
+| Web search + extract (Tavily) | ✅ | ❌ | ❌ | partial |
+| npm skill plugin system | ✅ | ❌ | ❌ | ❌ |
 | Planning mode | ✅ | ❌ | ❌ | ❌ |
-| Bundle size | 176K | ~50MB | ~40MB | ~100MB |
+| Named sessions + persistence | ✅ | ❌ | ❌ | ❌ |
+| `.miiiignore` | ✅ | ✅ | ❌ | ❌ |
+| Live model switching mid-session | ✅ | ❌ | ❌ | ❌ |
+| Bundle size | **176K** | ~50MB | ~40MB | ~100MB |
 
 ---
 
@@ -46,24 +57,21 @@ Your code never leaves your machine.
 npm install -g miii-cli
 ```
 
-**Requirements:** Node.js 18+ and [Ollama](https://ollama.com) (or any OpenAI-compatible API)
+**Requires:** Node.js 18+  and [Ollama](https://ollama.com)
+
+Or any OpenAI-compatible API — see [configuration](#configuration).
 
 ---
 
 ## Quick start
 
 ```bash
-# Start Ollama
 ollama serve
-
-# Pull a model
 ollama pull qwen2.5-coder:7b
-
-# Launch miii
 miii
 ```
 
-A model picker opens on launch. Select a model and start coding.
+Model picker opens on launch. Select a model. Start coding.
 
 ```bash
 miii                          # default session
@@ -72,11 +80,17 @@ miii --session myproject      # named session
 miii -s work -m codellama     # short flags
 ```
 
+miii checks for updates on startup and lets you know when a new version is available:
+
+```
+├── miii v0.2.5 → v0.2.6 available  run: npm install -g miii-cli ───┤
+```
+
 ---
 
 ## Auto git context
 
-miii automatically detects changed files via `git status` and injects their contents into the model's context — no `@file` needed for files you're actively working on.
+miii watches `git status` and silently injects your changed files into context — before you even type `@file`.
 
 ```
 ❯ fix the type error in the auth middleware
@@ -84,201 +98,228 @@ miii automatically detects changed files via `git status` and injects their cont
 [auto-loaded 3 changed file(s)]
 ```
 
-Only fires for code-related messages. Pure questions ("what is a closure?") skip the git scan entirely. Deduped — same files don't re-inject unless they change.
+Smart enough to skip it for non-code questions. Deduped — same files don't re-inject unless they change on disk. Disable per-project:
 
-Disable per-project:
 ```json
 { "gitContext": false }
 ```
 
 ---
 
-## File context with `@`
+## Multi-file refactor
 
-Type `@` to fuzzy-search and inject any project file:
+One goal, executed across the whole codebase:
 
 ```
-❯ review the auth logic in @src/auth/middleware.ts
-❯ what does @src/utils/parser.ts return when input is empty?
+/refactor extract all database queries into a repository layer
+/refactor rename UserService to AccountService everywhere
+/refactor add input validation to all API route handlers
 ```
 
-Automatically excluded: `node_modules`, `dist`, `.git`, lock files, binaries, images.
+How it works: model plans which files change → reads all in parallel → per-file LLM call with isolated context → writes queued changes → runs tests. Each file gets its own fresh context so local models never lose the thread.
 
 ---
 
-## `.miiiignore`
+## Auto-test after edits
 
-Create `.miiiignore` in your project root to exclude files from `@` picker and auto-context:
+Every time the model edits a file, miii runs your test suite automatically and feeds results back into the conversation — without you asking.
 
 ```
-# .miiiignore
-secrets/
-*.generated.ts
-fixtures/
-*.sql
+⚙ running run_tests…
+● src/auth/middleware.test.ts — 2 tests failed
 ```
 
-Supports exact names, relative paths, and `*.ext` glob patterns.
+Model sees the failures and fixes them on the next hop. Supports jest, vitest, mocha — auto-detected from `package.json`.
 
 ---
 
-## Git integration
+## Web search
 
-Full git workflow from the terminal:
+Add a Tavily key and the model can search the web and scrape pages as tools, mid-conversation:
 
+```bash
+/tavily-key tvly-your-key-here
 ```
-/git status          show working tree
-/git diff            unstaged changes
-/git diff --staged   staged changes
-/git log             recent commits
-/git review          AI reviews current changes for bugs + improvements
-/git branch          list branches
-/git commit <msg>    stage all and commit
+
+Get a free key at [tavily.com](https://tavily.com) — 1000 free searches/month.
+
+```
+❯ what's the latest breaking change in React 19?
+❯ find the docs for the Hono.js routing API and implement it here
+❯ search for the error: "Cannot read properties of undefined (reading 'map')"
 ```
 
-The model also has access to git tools directly — it can check status, read diffs, and commit as part of autonomous workflows.
+Tools available to the model: `web_search` (semantic search, configurable depth) and `web_extract` (scrape and summarize any URL). API key stored at `~/.config/miii/tavily.key` with mode 600.
 
 ---
 
-## Multi-file refactor
+## npm skill ecosystem
 
-Describe a goal, miii plans and executes across multiple files with isolated context per file:
+Write your own:
 
-```
-/refactor extract all database queries into a repository layer
-/refactor rename UserService to AccountService everywhere
-/refactor add input validation to all API route handlers
+```typescript
+// miii-skill-mytool/index.js
+export default {
+  name: 'mytool',
+  ns: 'custom',
+  description: 'does something useful',
+  execute: async (args, ctx) => {
+    ctx.setSystemPrompt(ctx.getSystemPrompt() + '\nExtra context here.')
+    return 'skill activated'
+  }
+}
 ```
 
-Uses a priority task queue (P0=blocking, P1=reads parallel, P2=writes sequential, P3=verify). Each file gets its own fresh context — the local model never loses the thread on large codebases.
+Markdown skills still work too — drop a `.md` file in `~/.config/miii/skills/` and it becomes a `/command` instantly.
 
 ---
 
 ## Planning mode
 
-Structured step-by-step planning before writing any code:
+Think before you code:
 
 ```
 /plan add OAuth2 to this Express app
 /plan refactor the frontend to use React Query
 ```
 
-In planning mode:
+Switches the model into a structured planning mode — no code, just questions, breakdowns, and concrete steps. Then:
+
 ```
-/plan:next        suggest next concrete steps
-/plan:breakdown   break topic into subtasks
+/plan:next        next concrete steps
+/plan:breakdown   break into subtasks
 /plan:review      critique the plan so far
-/plan:done        exit planning mode
+/plan:done        exit, go build
 ```
 
 ---
 
-## Built-in commands
+## File context with `@`
 
-Type `/` to open the command palette with fuzzy search.
+Type `@` anywhere to fuzzy-search and inject any project file into context:
 
-| Command | Description |
-|---|---|
-| `/model <name>` | Switch model mid-session — no restart needed |
-| `/models` | Open model picker, pull new Ollama models |
-| `/session <name>` | Switch to or create a named session |
-| `/sessions` | List all sessions with message counts |
-| `/new` | Start a fresh auto-named session |
-| `/clear` | Clear current session history |
-| `/plan [topic]` | Enter planning mode |
-| `/refactor <goal>` | Multi-file AI refactor |
-| `/git <subcommand>` | Git commands (see above) |
-| `/list` | Show all loaded skills |
-| `/exit` | Exit miii |
+```
+❯ review the auth logic in @src/auth/middleware.ts
+❯ what does @src/utils/parser.ts return when input is empty?
+```
+
+Files auto-excluded: `node_modules`, `dist`, `.git`, lock files, binaries, images.
 
 ---
 
-## Built-in tools
+## `.miiiignore`
 
-The model calls these autonomously — reads, writes, edits, runs, tests, and commits on its own.
+Exclude files from `@` fuzzy picker and git auto-context:
 
-| Tool | Description |
-|---|---|
-| `read_file` | Read any file |
-| `list_files` | List directory contents |
-| `create_file` | Create a new file (fails if exists) |
-| `edit_file` | Create or fully rewrite a file |
-| `patch_file` | Targeted string replacement — throws if match is ambiguous |
-| `delete_file` | Delete a file |
-| `move_file` | Move or rename a file or directory |
-| `create_folder` | Create directory with parents |
-| `run_command` | Run shell command in cwd (30s timeout) |
-| `run_tests` | Run test suite, auto-detects jest/vitest/mocha from package.json |
-| `git_status` | Working tree status |
-| `git_diff` | Unstaged or staged diff (truncated at 8K) |
-| `git_log` | Recent commit history |
-| `git_commit` | Stage files and commit |
+```
+# .miiiignore
+secrets/
+*.generated.ts
+fixtures/
+*.sql
+```
 
-Tool calls chain up to 6 hops — model reads, edits, runs tests, and verifies autonomously.
+Supports exact names, relative paths, and `*.ext` glob patterns.
 
 ---
 
-## Context compaction
+## Git integration
+
+```
+/git status          working tree
+/git diff            unstaged changes
+/git diff --staged   staged diff
+/git log             recent commits  (n optional: /git log 20)
+/git review          AI reviews current changes for bugs + improvements
+/git branch          list branches
+/git commit <msg>    stage all and commit
+```
 
-Local models lose the thread after ~15-20 messages. miii auto-compacts context at threshold: keeps system prompt + original goal + tool result summary + last 6 exchanges. The session history is preserved on disk — only the LLM context window gets trimmed.
+The model also has `git_status`, `git_diff`, `git_log`, `git_commit` as autonomous tools — it checks status and commits without being asked.
 
 ---
 
-## Thinking indicator
+## All built-in tools
 
-```
-✦ staring into the abyss (it blinked)…   [0:12]
+The model calls these autonomously as needed:
 
-⚙ running patch_file…
-⚙ running run_tests…
-```
+| Tool | What it does |
+|---|---|
+| `read_file` | Read any file in cwd |
+| `list_files` | List directory, respects `.miiiignore` |
+| `create_file` | Create new file — throws if already exists |
+| `edit_file` | Create or fully rewrite a file |
+| `patch_file` | Targeted string replace — throws on ambiguous match |
+| `delete_file` | Delete a file |
+| `move_file` | Move or rename |
+| `create_folder` | mkdir -p |
+| `run_command` | Shell command, cwd, 30s timeout |
+| `run_tests` | Run test suite (jest/vitest/mocha auto-detected) |
+| `git_status` | Working tree status |
+| `git_diff` | Diff, staged or unstaged, 8K truncated |
+| `git_log` | Commit history |
+| `git_commit` | Stage + commit |
+| `web_search` | Tavily semantic search (requires API key) |
+| `web_extract` | Scrape + summarize URLs (requires API key) |
 
-Phrase rotates every 5 seconds. Tool name updates live as each call fires. Elapsed time shown throughout.
+Chains up to 6 tool hops per response — read, edit, test, verify, commit in one shot.
 
 ---
 
 ## Sessions
 
-Every conversation persists automatically.
+Every conversation persists automatically to disk.
 
 ```bash
-miii                          # resumes "default" session
+miii                          # resumes last session
 miii --session feature-auth   # resumes or creates "feature-auth"
 ```
 
-Sessions stored at `~/.config/miii/sessions/`. History capped at 100 messages in memory, full history on disk.
+```
+/session <name>     switch to a session (creates if new)
+/sessions           list all sessions with message counts
+/new                fresh auto-named session
+/clear              clear current session
+```
+
+Sessions at `~/.config/miii/sessions/`. History capped at 100 messages in-context, full history on disk. Debounced writes — no I/O on every message.
 
 ---
 
-## Skills
+## Context compaction
 
-Custom `/` commands via Markdown in `~/.config/miii/skills/`:
+Local models lose coherence around 15–20 messages. miii auto-compacts when context gets long: keeps system prompt + original goal + tool result summary + last 6 exchanges. You keep going without restarting. Session history always preserved on disk — only the LLM window gets trimmed.
 
-```markdown
----
-name: review
-description: review current changes for bugs and improvements
 ---
 
-Review the code I'm about to share. Look for bugs, edge cases, and improvements.
-Be direct and specific. No markdown.
-```
+## All commands
 
-```
-/review
-```
+Type `/` to open the command palette with fuzzy search.
 
-TypeScript skills with `execute` functions available for programmatic behavior.
+| Command | Description |
+|---|---|
+| `/model <name>` | Switch model mid-session — no restart |
+| `/models` | Model picker, pull new Ollama models |
+| `/session <name>` | Switch or create session |
+| `/sessions` | List all sessions |
+| `/new` | Fresh auto-named session |
+| `/clear` | Clear current history |
+| `/plan [topic]` | Planning mode |
+| `/refactor <goal>` | Multi-file refactor |
+| `/git <sub>` | Git commands |
+| `/skills <sub>` | Install / uninstall / list npm skills |
+| `/tavily-key <key>` | Set web search API key |
+| `/version` | Show current version |
+| `/list` | List all loaded skills |
+| `/exit` | Exit |
 
 ---
 
 ## Configuration
 
-Config loaded from (in order):
-1. `.miii.json` in current directory
-2. `~/.config/miii/config.json`
+Loaded in order from `.miii.json` (project) → `~/.config/miii/config.json` (global).
 
-**Ollama:**
+**Ollama (default):**
 ```json
 {
   "model": "qwen2.5-coder:7b",
@@ -287,7 +328,7 @@ Config loaded from (in order):
 }
 ```
 
-**OpenAI-compatible (LM Studio, vLLM, Groq, Together, etc.):**
+**Any OpenAI-compatible API** (LM Studio, vLLM, Groq, Together, OpenRouter…):
 ```json
 {
   "model": "gpt-4o",
@@ -305,32 +346,34 @@ Config loaded from (in order):
   "baseUrl": "http://localhost:11434",
   "apiKey": "",
   "gitContext": true,
+  "tavilyApiKey": "tvly-...",
   "systemPrompt": "optional override"
 }
 ```
 
 ---
 
-## Keybindings
+## Security
 
-| Key | Action |
+| Threat | Defense |
 |---|---|
-| `enter` | Send message |
-| `↑ / ↓` | Navigate command palette or file picker |
-| `esc` | Close overlay / abort request |
-| `ctrl+c` | Abort current request or exit |
+| Path traversal (OWASP A01) | All file ops restricted to cwd via `guardPath()` |
+| `@file` injection | Refs validated against cwd before reading |
+| Session name injection | Names sanitized to alphanumeric + hyphens |
+| Shell injection (OWASP A03) | `run_command` enforces 30s hard timeout |
+| Config injection (OWASP A08) | Config key whitelist; session data validated as array |
+| API key exposure | Tavily key stored at `~/.config/miii/tavily.key` mode 600 |
 
 ---
 
-## Security
+## Keybindings
 
-| Issue | Fix |
+| Key | Action |
 |---|---|
-| Path traversal (OWASP A01) | All file operations restricted to cwd via `guardPath()` |
-| Path traversal (OWASP A01) | `@file` refs validated against cwd before reading |
-| Path traversal (OWASP A01) | Session names sanitized to alphanumeric + hyphens |
-| Injection (OWASP A03) | `run_command` enforces 30s execution timeout |
-| Insecure deserialization (OWASP A08) | Config whitelists allowed keys; session data validated as array |
+| `enter` | Send |
+| `↑ / ↓` | Navigate command palette or file picker |
+| `esc` | Close overlay / abort in-flight request |
+| `ctrl+c` | Abort current request or exit |
 
 ---
 
@@ -342,20 +385,18 @@ cd miii-cli
 npm install
 npm run build
 npm link
+npm test          # 8 integration tests
 ```
 
 ---
 
-## What's in 0.2.x
-
-- **Auto git context** — changed files injected automatically, code-gated heuristic
-- **`.miiiignore`** — per-project file exclusions
-- **Multi-file refactor** — macro/micro task queue, isolated context per file
-- **Planning mode** — structured `/plan` workflow
-- **Git integration** — full git toolkit in commands and model tools
-- **`run_tests` tool** — model runs and retries tests autonomously
-- **`/model` live switch** — change models mid-session
-- **Context compaction** — auto-trim at 18 messages, keep goal + summary + recent
-- **Ambiguous patch detection** — `patch_file` throws on multiple matches instead of silently corrupting
-- **176K bundle** — removed dead workers, sourcemaps, unused deps (was 468K)
-- **Debounced session saves** — writes at most once per 2s, no I/O on every keypress
+## What's new in 0.2.5
+
+- **Web search** — `web_search` + `web_extract` tools powered by Tavily
+- **npm skill ecosystem** — install/uninstall `miii-skill-*` packages, write your own
+- **Auto-test after edits** — model runs test suite after every file change, feeds failures back
+- **Live model switching** — `/model <name>` mid-session, no restart
+- **Update check** — startup banner when a new version is available
+- **Hook architecture** — `useSession`, `useModelPicker`, `useRunLoop` for clean internals
+- **Ambiguous patch detection** — `patch_file` throws on multiple matches
+- **176K bundle** — vs ~50MB for the Python alternatives

package/dist/__tests__/integration.test.js

@@ -0,0 +1,50 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { writeFileSync, unlinkSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { looksCodeRelated } from '../tui/git-context.js';
+import { tools } from '../tools/index.js';
+// patch_file uses guardPath which restricts to CWD — use a local scratch file
+const SCRATCH = join(process.cwd(), '.miii-test-scratch.txt');
+// ─── looksCodeRelated ─────────────────────────────────────────────────────────
+describe('looksCodeRelated', () => {
+    it('true: file extension in message', () => {
+        expect(looksCodeRelated('fix the bug in auth.ts')).toBe(true);
+    });
+    it('true: code keyword present', () => {
+        expect(looksCodeRelated('refactor the user login function')).toBe(true);
+    });
+    it('true: backtick token', () => {
+        expect(looksCodeRelated('what does `useEffect` do')).toBe(true);
+    });
+    it('false: too short', () => {
+        expect(looksCodeRelated('hi')).toBe(false);
+    });
+    it('false: plain prose, no code signal', () => {
+        expect(looksCodeRelated('what is the weather like in london today')).toBe(false);
+    });
+});
+// ─── patch_file ───────────────────────────────────────────────────────────────
+describe('patch_file', () => {
+    const patchTool = tools.find(t => t.name === 'patch_file');
+    afterEach(() => {
+        try {
+            unlinkSync(SCRATCH);
+        }
+        catch { }
+    });
+    it('applies a unique patch correctly', async () => {
+        writeFileSync(SCRATCH, 'hello world\ngoodbye world\n');
+        await patchTool.execute({ path: SCRATCH, old: 'hello world', new: 'hello earth' });
+        expect(readFileSync(SCRATCH, 'utf-8')).toBe('hello earth\ngoodbye world\n');
+    });
+    it('throws when old text not found', async () => {
+        writeFileSync(SCRATCH, 'hello world\n');
+        await expect(patchTool.execute({ path: SCRATCH, old: 'no such text', new: 'x' }))
+            .rejects.toThrow('old text not found');
+    });
+    it('throws on ambiguous match (2+ occurrences)', async () => {
+        writeFileSync(SCRATCH, 'hello world\nhello world\n');
+        await expect(patchTool.execute({ path: SCRATCH, old: 'hello world', new: 'hi' }))
+            .rejects.toThrow('ambiguous');
+    });
+});

package/dist/config.js

@@ -6,7 +6,7 @@ const defaults = {
     provider: 'ollama',
     baseUrl: 'http://localhost:11434',
 };
-const ALLOWED_KEYS = new Set(['model', 'provider', 'baseUrl', 'systemPrompt', 'apiKey']);
+const ALLOWED_KEYS = new Set(['model', 'provider', 'baseUrl', 'systemPrompt', 'apiKey', 'gitContext', 'tavilyApiKey']);
 export function loadConfig() {
     const candidates = [
         join(process.cwd(), '.miii.json'),