@tritard/waterbrother 0.9.8 → 0.10.0

package/README.md

@@ -1,8 +1,8 @@
-# waterbrother
+#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
+##Web docs interface
 
 This repo includes a static docs web interface:
 
@@ -17,18 +17,18 @@ This repo includes a static docs web interface:
 
 It is Vercel-ready via `vercel.json` (clean URLs, no build step required).
 
-## Implemented features
+##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`
+ - `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
+ - 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
@@ -41,33 +41,33 @@ It is Vercel-ready via `vercel.json` (clean URLs, no build step required).
 - 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`
+ - 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
+ - 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`)
+ - 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
+ - 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`
@@ -76,39 +76,39 @@ It is Vercel-ready via `vercel.json` (clean URLs, no build step required).
 - 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
+ - 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
+ - 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
+ - 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
+ - `/` 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
+ - 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`
+ - `-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
+##Quick start
 
 User install:
 
@@ -157,10 +157,10 @@ 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
+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:
@@ -180,13 +180,13 @@ Web research examples:
 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
+#interactive
 /read https://console.x.ai/
 /search latest xAI vision docs
 /open 1
 ```
 
-## Release flow
+##Release flow
 
 Partners should ship updates by pushing a version tag, not by running `npm publish` locally.
 
@@ -218,7 +218,7 @@ This lets partners such as Umair and Austin ship releases without using the publ
 Long-running session controls:
 
 ```bash
-# inside interactive mode
+#inside interactive mode
 /compact
 /compact 32
 /cost
@@ -236,7 +236,7 @@ Long-running session controls:
 /memory add Always run tests before final answer.
 /memory reload
 
-# config tuning
+#config tuning
 waterbrother config set autoCompactThreshold 0.9
 waterbrother config set traceMode verbose
 waterbrother config set receiptMode verbose
@@ -267,11 +267,11 @@ waterbrother config set-json mcpServers '{"filesystem":{"command":"npx","args":[
 waterbrother mcp list
 ```
 
-## Task console
+##Task console
 
 Waterbrother treats serious work as **tasks**, not chat turns.
 
-### Commands
+###Commands
 
 | Command | Description |
 |---------|-------------|
@@ -290,7 +290,7 @@ Waterbrother treats serious work as **tasks**, not chat turns.
 | `/close` | Close the active task |
 | `/panel` | Show/toggle operator panel |
 
-### Typical flow
+###Typical flow
 
 ```
 /feature auth-rework
@@ -308,3 +308,4 @@ Supported in this release:
 - automatic tool discovery at startup
 - tool routing through normal approval + trace flow
 - interactive inspection with `/mcp`
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tritard/waterbrother",
-  "version": "0.9.8",
+  "version": "0.10.0",
   "description": "Waterbrother: Grok-powered coding CLI with local tools, sessions, operator modes, and approval controls",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -5987,6 +5987,26 @@ async function promptLoop(agent, session, context) {
             onAssistant() {
               markProgress();
               turnSummary.events.push({ at: Date.now(), name: "responded" });
+            },
+            onVerifyStart(count) {
+              markProgress();
+              printRailTransition("verifying");
+              spinner.setLabel(`running ${count} verifier${count > 1 ? "s" : ""}...`);
+            },
+            onVerifyResult(result) {
+              markProgress();
+              const icon = result.ok ? green("✓") : red("✗");
+              const count = result.issueCount !== null ? ` (${result.issueCount} issues)` : "";
+              console.log(`${dim("  ▸")} ${icon} ${result.name}${count}`);
+            },
+            onAutofixStart() {
+              markProgress();
+              printRailTransition("fixing");
+              spinner.setLabel("autofixing...");
+            },
+            onAutofixEnd() {
+              markProgress();
+              spinner.setLabel("re-verifying...");
             }
           }
         });
@@ -5996,7 +6016,7 @@ async function promptLoop(agent, session, context) {
         spinner.stop();
 
         // Verifying phase (impact + sentinel happened inside runBuildWorkflow)
-        if (buildResult.receipt?.mutated) {
+        if (buildResult.receipt?.mutated && !buildResult.verifierResults) {
           printRailTransition("verifying");
         }
         if (buildResult.review) {
@@ -6028,6 +6048,11 @@ async function promptLoop(agent, session, context) {
           }
         }
 
+        // Verifiers
+        if (buildResult.verifierSummary) {
+          lines.push(`${dim("verifiers:")} ${buildResult.verifierSummary}`);
+        }
+
         // Impact
         if (buildResult.impactSummary) {
           const is = buildResult.impactSummary;
@@ -6217,25 +6242,15 @@ async function promptLoop(agent, session, context) {
         continue;
       }
 
-      // Extract flags — parse --metric value (everything until next -- flag or end)
+      // Extract flags
+      const metricMatch = rawArgs.match(/--metric\s+"([^"]+)"|--metric\s+(\S+)/);
       const attemptsMatch = rawArgs.match(/--attempts\s+(\d+)/);
       const timeMatch = rawArgs.match(/--time\s+(\d+)/);
-      // Remove --attempts and --time first so --metric can grab the rest
-      let cleaned = rawArgs.replace(/--attempts\s+\d+/g, "").replace(/--time\s+\d+/g, "");
-      let metricCmd = "";
-      const metricIdx = cleaned.indexOf("--metric");
-      if (metricIdx !== -1) {
-        const afterMetric = cleaned.slice(metricIdx + 8).trim();
-        // If quoted, take the quoted content; otherwise take everything until end
-        if (afterMetric.startsWith('"')) {
-          const endQuote = afterMetric.indexOf('"', 1);
-          metricCmd = endQuote > 0 ? afterMetric.slice(1, endQuote) : afterMetric.slice(1);
-        } else {
-          metricCmd = afterMetric;
-        }
-        cleaned = cleaned.slice(0, metricIdx).trim();
-      }
-      const goalArg = cleaned.trim();
+      const goalArg = rawArgs
+        .replace(/--metric\s+"[^"]+"|--metric\s+\S+/g, "")
+        .replace(/--attempts\s+\d+/g, "")
+        .replace(/--time\s+\d+/g, "")
+        .trim();
 
       if (!goalArg) {
         console.log("experiment needs a goal");
@@ -6244,8 +6259,8 @@ async function promptLoop(agent, session, context) {
 
       const charter = parseCharterFromGoal(goalArg);
 
-      if (metricCmd) {
-        charter.metric.command = metricCmd.trim();
+      if (metricMatch) {
+        charter.metric.command = (metricMatch[1] || metricMatch[2]).trim();
       }
       if (attemptsMatch) {
         charter.budget.maxAttempts = parseInt(attemptsMatch[1], 10);

package/src/config.js

@@ -198,6 +198,7 @@ export function resolveRuntimeConfig(config, overrides = {}) {
           : true,
     decisionModel: overrides.decisionModel || config.decisionModel || "",
     plannerModel: overrides.plannerModel || config.plannerModel || "",
+    verifiers: Array.isArray(overrides.verifiers) ? overrides.verifiers : Array.isArray(config.verifiers) ? config.verifiers : [],
     taskDefaults: normalizeTaskDefaults(
       overrides.taskDefaults !== undefined ? overrides.taskDefaults : config.taskDefaults
     ),

package/src/verifier.js

@@ -0,0 +1,166 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const MAX_OUTPUT_CHARS = 3000;
+const MAX_AUTOFIX_ATTEMPTS = 2;
+
+/**
+ * Verifier config shape:
+ * {
+ *   verifiers: [
+ *     { command: "npx eslint . --format json", name: "eslint", autofix: true },
+ *     { command: "npx tsc --noEmit", name: "typescript", autofix: false },
+ *     { command: "npm audit --json", name: "security", autofix: false }
+ *   ]
+ * }
+ */
+
+async function runCommand(command, cwd) {
+  const isWin = process.platform === "win32";
+  const opts = { cwd, env: process.env, maxBuffer: 8 * 1024 * 1024, timeout: 120000 };
+  try {
+    let stdout, stderr;
+    if (isWin) {
+      const result = await execFileAsync("powershell.exe", ["-NoProfile", "-Command", command], opts);
+      stdout = String(result.stdout || "");
+      stderr = String(result.stderr || "");
+    } else {
+      const result = await execFileAsync("/bin/sh", ["-c", command], opts);
+      stdout = String(result.stdout || "");
+      stderr = String(result.stderr || "");
+    }
+    return { ok: true, stdout, stderr, exitCode: 0 };
+  } catch (error) {
+    return {
+      ok: false,
+      stdout: String(error.stdout || ""),
+      stderr: String(error.stderr || error.message || ""),
+      exitCode: error.code || 1
+    };
+  }
+}
+
+function parseIssueCount(output) {
+  // Try common patterns: "X errors", "X warnings", "X problems", "X issues"
+  const match = output.match(/(\d+)\s+(error|warning|problem|issue|vulnerabilit)/i);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+export async function runVerifiers({ verifiers, cwd }) {
+  if (!Array.isArray(verifiers) || verifiers.length === 0) return [];
+
+  const results = [];
+  for (const v of verifiers) {
+    const name = v.name || v.command.split(/\s+/)[0];
+    const result = await runCommand(v.command, cwd);
+    const combined = `${result.stdout}\n${result.stderr}`.trim();
+    const issueCount = parseIssueCount(combined);
+
+    results.push({
+      name,
+      command: v.command,
+      ok: result.ok,
+      exitCode: result.exitCode,
+      output: combined.slice(0, MAX_OUTPUT_CHARS),
+      issueCount,
+      autofix: v.autofix === true
+    });
+  }
+
+  return results;
+}
+
+export function formatVerifierResults(results) {
+  if (!results || results.length === 0) return "";
+  const lines = [];
+  for (const r of results) {
+    const icon = r.ok ? "✓" : "✗";
+    const count = r.issueCount !== null ? ` (${r.issueCount} issues)` : "";
+    lines.push(`${icon} ${r.name}${count}`);
+  }
+  return lines.join("  ");
+}
+
+export function formatVerifierResultsForModel(results) {
+  if (!results || results.length === 0) return "";
+  const lines = ["Verifier results (fix any issues before continuing):"];
+  for (const r of results) {
+    if (r.ok) {
+      lines.push(`✓ ${r.name}: clean`);
+    } else {
+      lines.push(`✗ ${r.name}: ${r.output.slice(0, 1000)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export function hasFailures(results) {
+  return results.some((r) => !r.ok);
+}
+
+export function getAutofixableFailures(results) {
+  return results.filter((r) => !r.ok && r.autofix);
+}
+
+export function buildAutofixPrompt(failures) {
+  const lines = ["Fix the following issues. Only fix what the tools reported — do not make other changes."];
+  for (const f of failures) {
+    lines.push(`\n--- ${f.name} (${f.command}) ---`);
+    lines.push(f.output.slice(0, 1500));
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Run verifiers, optionally autofix, return final results.
+ *
+ * handlers: {
+ *   onVerifyStart(verifierCount) — verification starting
+ *   onVerifyResult(result) — single verifier finished
+ *   onAutofixStart(failures) — about to autofix
+ *   onAutofixEnd() — autofix complete
+ *   executeAutofix(prompt) — run the model to fix issues
+ * }
+ */
+export async function runVerificationPass({ verifiers, cwd, handlers = {} }) {
+  if (!Array.isArray(verifiers) || verifiers.length === 0) {
+    return { results: [], fixed: false, attempts: 0 };
+  }
+
+  if (handlers.onVerifyStart) handlers.onVerifyStart(verifiers.length);
+
+  let results = await runVerifiers({ verifiers, cwd });
+  let attempts = 0;
+
+  // Autofix loop
+  while (hasFailures(results) && attempts < MAX_AUTOFIX_ATTEMPTS) {
+    const fixable = getAutofixableFailures(results);
+    if (fixable.length === 0) break;
+
+    attempts++;
+    if (handlers.onAutofixStart) handlers.onAutofixStart(fixable);
+
+    const prompt = buildAutofixPrompt(fixable);
+    if (handlers.executeAutofix) {
+      try {
+        await handlers.executeAutofix(prompt);
+      } catch {
+        break;
+      }
+    } else {
+      break;
+    }
+
+    if (handlers.onAutofixEnd) handlers.onAutofixEnd();
+
+    // Re-run verifiers to check if fixes worked
+    results = await runVerifiers({ verifiers, cwd });
+  }
+
+  for (const r of results) {
+    if (handlers.onVerifyResult) handlers.onVerifyResult(r);
+  }
+
+  return { results, fixed: attempts > 0, attempts };
+}

package/src/workflow.js

@@ -15,6 +15,7 @@ import {
   shouldRunFrontendReview
 } from "./frontend.js";
 import { runPlannerPass, formatPlanForExecutor, formatPlanForDisplay } from "./planner.js";
+import { runVerificationPass, formatVerifierResults, hasFailures } from "./verifier.js";
 
 export async function runBuildWorkflow({
   agent,
@@ -99,6 +100,47 @@ export async function runBuildWorkflow({
     return { response, receipt: null, impact: null, review: null };
   }
 
+  // Verification pass: run configured linters/analyzers, autofix if possible
+  const verifiers = context.runtime?.verifiers;
+  let verifierResults = null;
+  if (receipt.mutated && Array.isArray(verifiers) && verifiers.length > 0) {
+    try {
+      const vResult = await runVerificationPass({
+        verifiers,
+        cwd: context.cwd,
+        handlers: {
+          onVerifyStart(count) {
+            if (handlers.onStateChange) handlers.onStateChange("verifying");
+            if (handlers.onVerifyStart) handlers.onVerifyStart(count);
+          },
+          onVerifyResult(result) {
+            if (handlers.onVerifyResult) handlers.onVerifyResult(result);
+          },
+          onAutofixStart(failures) {
+            if (handlers.onStateChange) handlers.onStateChange("fixing");
+            if (handlers.onAutofixStart) handlers.onAutofixStart(failures);
+          },
+          onAutofixEnd() {
+            if (handlers.onAutofixEnd) handlers.onAutofixEnd();
+          },
+          async executeAutofix(prompt) {
+            response = await agent.runBuildTurn(prompt, handlers);
+            const fixReceipt = await agent.toolRuntime.completeTurn({ signal: handlers.signal });
+            if (fixReceipt) {
+              // Merge fix receipt into main receipt
+              receipt.changedFiles = [...new Set([...(receipt.changedFiles || []), ...(fixReceipt.changedFiles || [])])];
+              if (fixReceipt.diff) receipt.diff = (receipt.diff || "") + "\n" + fixReceipt.diff;
+              if (fixReceipt.diffStat) receipt.diffStat = fixReceipt.diffStat;
+            }
+          }
+        }
+      });
+      verifierResults = vResult.results;
+    } catch {
+      // Verification failure is non-fatal
+    }
+  }
+
   async function analyze(activeReceipt, activeResponse) {
     let impact = null;
     if (activeReceipt.mutated && context.runtime.impact?.enabled !== false) {
@@ -276,7 +318,9 @@ export async function runBuildWorkflow({
     review,
     designReview,
     screenshotReview,
-    impactSummary: impact ? summarizeImpactMap(impact) : null
+    impactSummary: impact ? summarizeImpactMap(impact) : null,
+    verifierResults,
+    verifierSummary: verifierResults ? formatVerifierResults(verifierResults) : null
   };
 }