@tritard/waterbrother 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phillip Holland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,279 @@
+# waterbrother
+
+A local coding CLI that connects to Grok (`api.x.ai`) with codex/claude-style interactive workflows, local tool calls, session persistence, and approval controls.
+
+## Web docs interface
+
+This repo includes a static docs web interface:
+
+- `/` landing page
+- `/onboarding` onboarding + API key guide
+- `/install` install instructions
+- `/usage` usage guide
+- `/commands` command reference
+- `/prod-readiness` production-readiness checklist and release blockers
+- `/changelog` release notes
+- `/faq` FAQ
+
+It is Vercel-ready via `vercel.json` (clean URLs, no build step required).
+
+## Implemented features
+
+- Interactive and one-shot chat modes
+- Codex-style non-interactive commands:
+  - `waterbrother exec <prompt>`
+  - `waterbrother review <prompt>`
+  - `waterbrother resume [session-id] [prompt]`
+  - `waterbrother resume --last`
+- First-run onboarding wizard in terminal
+  - asks for API key
+  - offers opening `https://console.x.ai/`
+  - prompts for default model and agent profile
+- Grok API integration (`/chat/completions`)
+- Vision command for local images: `waterbrother vision <image-path> <prompt>`
+- Authenticated GitHub repo reading for GitHub URLs, including private repos when `gh` is logged in
+- Built-in webpage reading and web search tools for pasted URLs and open-web research prompts
+- MCP stdio server support via config-driven `mcpServers`
+- Interactive URL drop support: paste a public `https://...` URL directly and Waterbrother will read and summarize it
+- Multiline paste stays buffered until explicit Enter, with a prompt-row placeholder like `[Pasted Content 14083 chars]`
+- Agent profiles: `coder`, `designer`, `reviewer`, `planner`
+- Model discovery command (`waterbrother models list`)
+- Local model catalog (`waterbrother models catalog`)
+- Onboarding guide command (`waterbrother onboarding`)
+- Local self-update command (`waterbrother update`)
+  - git-clone installs pull latest source, install deps, and run checks
+  - npm installs upgrade with `npm install -g @tritard/waterbrother@latest`
+- Environment diagnostics (`waterbrother doctor`)
+- Tool calling for file, shell, search, and git tasks
+- Diff preview in approval prompts: see exactly what will change before approving file writes and replacements
+- Fuzzy whitespace-tolerant matching in `replace_in_file` to reduce failed edits
+- Shell working directory tracking (`cd` commands update the shell cwd for subsequent calls)
+- Approval policy for mutating/shell tools: `auto`, `on-request`, `never`
+  - supports path-aware allow/ask/deny rules via config
+  - supports command-aware shell allow/ask/deny rules via config
+  - includes `apply_patch`, `make_directory`, and `restore_checkpoint` in approval-protected actions
+  - `restore_checkpoint` is treated as high-risk and always requires explicit approval
+  - On-request prompt supports keyboard-first actions:
+  - `↑/↓` changes the highlighted approval row
+  - `Enter` or `y` approve once
+  - `p` saves a session approval rule for the current shell-command prefix or tool
+  - `Esc` denies and optionally provides alternate guidance
+  - the chooser renders in a bordered block with the default action highlighted
+  - the footer shows a short rules indicator when session approval rules are active
+- AI-powered commit command: `waterbrother commit [--push]`
+- Split config layers:
+  - user config (`~/.waterbrother/config.json`)
+  - project overrides (`.waterbrother/config.json`)
+- Session persistence (`~/.waterbrother/sessions/*.json`)
+- Two-tier project memory:
+  - global instructions (`~/.waterbrother/WATERBROTHER.md`)
+  - project instructions (`WATERBROTHER.md`) — both merged into system prompt
+- Accurate token tracking using API usage data when available (falls back to estimation)
+- Manual compaction command (`/compact`) for long-running sessions
+- Session forking with `/fork`
+- Session cost tracking with `/cost`
+- Working tree inspection with `/diff`
+- Git-backed local checkpoints with restore support (`/checkpoints`, `/rewind [id]`)
+- Deterministic patch application tool (`apply_patch`) with preflight validation
+- Turn contracts (new)
+  - agent must declare intended scope before edits or risky shell calls
+  - contract includes summary, allowed paths, expected commands, and verification commands
+  - runtime blocks out-of-scope mutations automatically
+- Turn receipts (new)
+  - every tool-heavy or mutating turn writes a local receipt under `.waterbrother/receipts/`
+  - receipt captures contract, files touched, checkpoint, verification results, and command/tool provenance
+  - inspect with `/receipts`, `/receipt last`, `/receipt <id>`
+  - summary printing is configurable with `receiptMode` / `--receipts auto|off|verbose`
+  - default `auto` suppresses noisy receipt lines for minimal read-only turns
+- Automatic post-edit verification
+  - verification commands from the turn contract run automatically after edits
+  - optional default verification commands available through config
+- Auto-compaction near context limits (`autoCompactThreshold`, default `0.9`)
+- Interactive slash controls with command palette
+  - `/` opens command menu
+  - `↑/↓` changes selection
+  - `Enter` accepts selected command
+- Read-only file tools can inspect common home folders such as ~/Desktop, ~/Downloads, and ~/Documents without falling back to shell; /desktop, /downloads, and /documents are treated as aliases for those locations on macOS
+- Turn presentation improvements
+  - streaming assistant output for faster perceived response
+  - explicit run-state tracking (`planning`, `reading`, `editing`, `running`, `reviewing`, `done`, `error`) persisted in session metadata
+  - heartbeat/stuck detection with interrupt hint during long-running steps
+  - spinner/progress animation while model or tools are running
+  - live visible trace lines during turns for phases like thinking and tool use, with verbose-only run-state heartbeat details
+  - per-turn summary with duration, tool outcomes, and token usage when available
+  - compact trace grouping so tool retries do not spam the status line
+  - formatted code-fence rendering with line numbers
+- Headless pipe mode for one-shot automation:
+  - `-p` reads prompt from stdin or `--prompt`
+  - `--output-format text|json|stream-json`
+- Production-readiness tracking page for the active P0/P1/P2 release matrix
+
+## Quick start
+
+User install (after the npm package is published):
+
+```bash
+npm install -g @tritard/waterbrother
+waterbrother
+```
+
+Source install for contributors:
+
+```bash
+git clone https://github.com/PhillipHolland/waterbrother.git
+cd waterbrother
+npm install
+npm link
+```
+
+Start interactive mode (first run launches onboarding wizard):
+
+```bash
+waterbrother --approval on-request
+```
+
+One-shot prompt:
+
+```bash
+waterbrother "inspect this project and explain the structure"
+```
+
+Non-interactive command forms:
+
+```bash
+waterbrother exec "summarize the repository architecture"
+waterbrother review "review changed files for bugs and missing tests"
+waterbrother resume --last "continue and finish the previous task"
+```
+
+Vision/web design prompt with local image:
+
+```bash
+waterbrother vision ./mockup.png "Suggest concrete CSS and layout improvements"
+```
+
+Git workflow:
+
+```bash
+waterbrother commit               # stage, diff, generate commit message, confirm
+waterbrother commit --push        # same as above, then push
+waterbrother pr                   # commit, push, generate PR title+body, create via gh
+waterbrother pr --branch=my-feat  # create branch first if on main, then PR
+```
+
+Utility commands:
+
+```bash
+waterbrother doctor
+waterbrother models list
+waterbrother models catalog
+waterbrother mcp list
+waterbrother onboarding
+waterbrother update
+```
+
+Web research examples:
+
+```bash
+waterbrother "Read https://console.x.ai and summarize how to create an API key"
+waterbrother "Search the web for the latest xAI API docs about vision support and cite the sources"
+
+# interactive
+/read https://console.x.ai/
+/search latest xAI vision docs
+/open 1
+```
+
+Long-running session controls:
+
+```bash
+# inside interactive mode
+/compact
+/compact 32
+/cost
+/fork
+/diff
+/run inspect the project and summarize the architecture
+/receipt-mode
+/receipt-mode off
+/contract
+/receipts
+/receipt last
+/checkpoints
+/rewind
+/memory init
+/memory add Always run tests before final answer.
+/memory reload
+
+# config tuning
+waterbrother config set autoCompactThreshold 0.9
+waterbrother config set traceMode verbose
+waterbrother config set receiptMode verbose
+waterbrother config set model grok-4.20-beta-0309-reasoning --scope project
+waterbrother config set-json approvalPolicy '{"autoApprovePaths":["src/**"],"askPaths":["package.json"],"denyShellPatterns":["git\\s+reset\\s+--hard"]}' --scope project
+waterbrother config set-json verification '{"commands":["npm run lint","npm test"],"timeoutMs":180000}' --scope project
+waterbrother config set-json mcpServers '{"filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","."]}}' --scope project
+```
+
+Pipe mode examples:
+
+```bash
+printf 'summarize this repo' | waterbrother -p
+printf 'read https://example.com and summarize it' | waterbrother -p --output-format json
+printf 'inspect package.json' | waterbrother -p --output-format stream-json
+```
+
+Config scope notes:
+
+- `waterbrother config set ...` defaults to user scope (`~/.waterbrother/config.json`)
+- add `--scope project` to save repo-local overrides in `.waterbrother/config.json`
+- `waterbrother config get ...` and `waterbrother config list` default to merged runtime values
+
+MCP setup example:
+
+```bash
+waterbrother config set-json mcpServers '{"filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","."]}}' --scope project
+waterbrother mcp list
+```
+
+## Task console
+
+Waterbrother treats serious work as **tasks**, not chat turns.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `/feature <name>` | Start a new task (creates branch, sets up tracking) |
+| `/tasks` | List recent tasks |
+| `/task` | Show active task details |
+| `/decide [goal]` | Run decision pass — get structured implementation options |
+| `/choose <option>` | Choose a decision option and lock contract |
+| `/redecide` | Clear decision and re-plan |
+| `/surgeon <paths...>` | Set contract scope directly, skip `/decide` |
+| `/build <prompt>` | Execute within task contract |
+| `/review` | Show structured review panel |
+| `/challenge` | Adversarial re-review of last changes |
+| `/accept` | Accept reviewed changes |
+| `/tighten <paths...>` | Narrow contract scope |
+| `/close` | Close the active task |
+| `/panel` | Show/toggle operator panel |
+
+### Typical flow
+
+```
+/feature auth-rework
+/decide add Google login without breaking auth API
+/choose minimal
+/build implement the adapter layer
+/review
+/accept
+/close
+```
+
+Supported in this release:
+
+- stdio MCP servers
+- automatic tool discovery at startup
+- tool routing through normal approval + trace flow
+- interactive inspection with `/mcp`

package/bin/waterbrother.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.js";
+
+runCli(process.argv.slice(2)).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@tritard/waterbrother",
+  "version": "0.5.0",
+  "description": "Waterbrother: Grok-powered coding CLI with local tools, sessions, operator modes, and approval controls",
+  "type": "module",
+  "bin": {
+    "waterbrother": "bin/waterbrother.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "scripts": {
+    "start": "node bin/waterbrother.js",
+    "dev": "node --watch bin/waterbrother.js",
+    "check": "node -e \"import('./src/cli.js')\"",
+    "smoke": "node scripts/smoke.js",
+    "soak:long-session": "node scripts/long-session-soak.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PhillipHolland/waterbrother.git"
+  },
+  "homepage": "https://github.com/PhillipHolland/waterbrother#readme",
+  "bugs": {
+    "url": "https://github.com/PhillipHolland/waterbrother/issues"
+  },
+  "keywords": [
+    "cli",
+    "grok",
+    "coding-agent",
+    "terminal",
+    "ai",
+    "mcp"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}