veto-leash 2.0.4 → 2.1.1

package/README.md

@@ -1,213 +1,314 @@
 <p align="center">
   <h1 align="center">veto-leash</h1>
-  <p align="center"><strong>sudo for AI agents</strong></p>
+  <p align="center"><strong>Permission layer for AI coding agents</strong></p>
   <p align="center">
-    <a href="https://www.npmjs.com/package/veto-leash"><img src="https://img.shields.io/npm/v/veto-leash?style=flat-square&color=black" alt="npm version"></a>
-    <a href="https://github.com/VulnZap/veto-leash/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/veto-leash?style=flat-square&color=black" alt="License"></a>
-    <a href="https://www.npmjs.com/package/veto-leash"><img src="https://img.shields.io/npm/dm/veto-leash?style=flat-square&color=black" alt="Downloads"></a>
+    <a href="https://www.npmjs.com/package/veto-leash"><img src="https://img.shields.io/npm/v/veto-leash?style=flat-square&color=f5a524" alt="npm version"></a>
+    <a href="https://github.com/VulnZap/veto-leash/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/veto-leash?style=flat-square&color=000" alt="License"></a>
+    <a href="https://www.npmjs.com/package/veto-leash"><img src="https://img.shields.io/npm/dm/veto-leash?style=flat-square&color=000" alt="Downloads"></a>
   </p>
 </p>
 
-Your AI agent has root access to your codebase. You have... vibes.
+<br>
 
-```bash
-# One file. That's it.
-echo "no lodash
-no any types" > .leash
+## Overview
 
-leash   # Interactive dashboard
-```
+AI coding agents have unrestricted access to your codebase. veto-leash adds a permission layer with natural language policies enforced through AST-level validation.
 
-Now every action is validated with **AST-level precision**. Zero false positives. Zero config.
+```bash
+npm install -g veto-leash
+leash
+```
 
-## What's New in 2.0
+Create policies in plain English. Block dangerous operations. Zero false positives.
 
-- **Native Go TUI** - Beautiful interactive dashboard built with Bubble Tea
-- **4.5MB binary** - Instant startup, no Node.js required at runtime
-- **Cross-platform** - Native binaries for macOS, Linux, Windows (arm64 + amd64)
-- **Hybrid engine** - Go for speed, TypeScript for LLM compilation + AST validation
+<br>
 
 ## The Problem
 
-AI coding agents can `npm install lodash` when you want native methods. They'll sprinkle `any` types everywhere. They'll `git push --force` to main.
+Modern AI coding assistants can execute arbitrary commands and modify any file. While powerful, this creates risk:
+
+- Installing unwanted dependencies (lodash when you prefer native)
+- Using loose types (any instead of proper TypeScript)
+- Executing dangerous commands (force push to main)
+- Modifying protected files (.env, credentials)
 
-Regex-based blockers create false positives. A comment saying `// TODO: remove lodash` shouldn't trigger a block.
+Traditional regex-based blocking creates false positives. Comments mentioning "lodash" shouldn't trigger blocks.
+
+<br>
 
 ## The Solution
 
-veto-leash uses **AST parsing** for surgical precision:
+veto-leash uses Abstract Syntax Tree parsing for surgical precision:
+
+| Code                     | Regex Blocker | veto-leash            |
+| ------------------------ | ------------- | --------------------- |
+| `// import lodash`       | BLOCKED       | ALLOWED (comment)     |
+| `"use any type"`         | BLOCKED       | ALLOWED (string)      |
+| `const anyValue = 5`     | BLOCKED       | ALLOWED (variable)    |
+| `import _ from 'lodash'` | BLOCKED       | BLOCKED (actual code) |
 
-| Code                     | Regex Result | AST Result                 |
-| ------------------------ | ------------ | -------------------------- |
-| `// import lodash`       | BLOCKED      | ALLOWED (comment)          |
-| `"use any type"`         | BLOCKED      | ALLOWED (string)           |
-| `const anyValue = 5`     | BLOCKED      | ALLOWED (variable name)    |
-| `import _ from 'lodash'` | BLOCKED      | BLOCKED (correct)          |
+The difference is precision. AST parsing understands code structure, eliminating false positives entirely.
 
-**This precision is our moat.** No other tool achieves zero false positives.
+<br>
 
 ## Quick Start
 
+### Installation
+
 ```bash
-# Install globally
 npm install -g veto-leash
+```
+
+### Create Policies
 
-# Create policies
-echo "no lodash
+One policy per line in `.leash`:
+
+```
+no lodash
 no any types
-prefer pnpm" > .leash
+prefer pnpm over npm
+protect .env files
+```
 
-# Launch the dashboard
+### Launch Dashboard
+
+```bash
 leash
 ```
 
-The interactive TUI lets you:
-- Add and manage policies
-- Install hooks for detected agents
-- Monitor enforcement in real-time
-- View audit logs
+Interactive TUI for policy management, agent configuration, and monitoring.
 
-Or use CLI commands directly:
+### CLI Usage
 
 ```bash
 leash init              # Auto-detect agents, install hooks
-leash add "no axios"    # Add a policy
+leash add "no axios"    # Add policy
 leash sync              # Apply to all agents
+leash status            # Show configuration
 ```
 
-## Simple `.leash` Format
+<br>
 
-```
-# .leash - One rule per line
-no lodash
-no any types - enforces strict TypeScript
-no console.log
-prefer pnpm over npm
-protect .env files
-```
+## Features
+
+### Native Performance
 
-Lines starting with `#` are comments. Optional reasons after `-`.
+- **6.8MB binary** - Go-based TUI, instant startup
+- **Cross-platform** - macOS, Linux, Windows (ARM64 + AMD64)
+- **Auto-update** - Built-in version checking and updates
 
-## Built-in Rules
+### Smart Validation
 
-These work **instantly** with zero LLM calls:
+- **50+ built-in patterns** - Common policies work instantly
+- **AST parsing** - Tree-sitter for zero false positives
+- **LLM compilation** - Custom policies use Gemini API
+- **243 test suite** - Comprehensive validation coverage
 
-| Rule                  | What It Catches                            |
+### Agent Integration
+
+Native support for major AI coding tools:
+
+| Agent           | Integration Method          | Status |
+| --------------- | --------------------------- | ------ |
+| **Claude Code** | PreToolUse hooks            | Full   |
+| **OpenCode**    | AGENTS.md injection         | Full   |
+| **Cursor**      | rules/ directory            | Full   |
+| **Windsurf**    | Cascade rules               | Full   |
+| **Aider**       | .aider.conf.yml             | Full   |
+
+<br>
+
+## Built-in Policies
+
+Instant validation without LLM calls:
+
+| Policy                | Blocks                                     |
 | --------------------- | ------------------------------------------ |
 | `no lodash`           | ES imports, require(), dynamic import()    |
 | `no any types`        | Type annotations, generics, as expressions |
 | `no console.log`      | console.log(), console['log']()            |
 | `no eval`             | eval(), new Function()                     |
 | `no class components` | React.Component, PureComponent             |
-| `no innerhtml`        | innerHTML, dangerouslySetInnerHTML         |
+| `no innerHTML`        | innerHTML, dangerouslySetInnerHTML         |
 | `no debugger`         | debugger statements                        |
 | `no var`              | var declarations                           |
-| `prefer pnpm`         | npm/yarn commands blocked                  |
-| `protect .env`        | Environment file modifications blocked     |
+| `prefer pnpm`         | npm/yarn package manager commands          |
+| `protect .env`        | Modifications to environment files         |
 
-50+ built-in patterns cover most common policies.
+Over 50 patterns available. See source for complete list.
 
-## Native Agent Support
+<br>
 
-| Agent           | How It Works                         | Status     |
-| --------------- | ------------------------------------ | ---------- |
-| **Claude Code** | PreToolUse hooks with AST validation | Full       |
-| **OpenCode**    | AGENTS.md injection                  | Full       |
-| **Cursor**      | rules/ directory integration         | Full       |
-| **Windsurf**    | Cascade rules integration            | Full       |
-| **Aider**       | .aider.conf.yml configuration        | Full       |
-
-## Commands
+## Architecture
 
 ```
-leash                     Interactive dashboard
-leash init                Auto-detect agents, install hooks
-leash add "<policy>"      Add a policy
-leash list                Show current policies
-leash explain "<policy>"  Preview what a policy catches
-leash sync [agent]        Apply policies to agents
-leash install <agent>     Install hooks for specific agent
-leash uninstall <agent>   Remove agent hooks
-leash status              Show detected agents
-leash audit [--tail]      View enforcement log
+┌──────────────────────────────────────────────┐
+│           leash (Native Binary)              │
+├──────────────────────────────────────────────┤
+│  Interactive TUI    │  CLI Commands          │
+│  • Policy editor    │  • add, list, sync     │
+│  • Agent manager    │  • install, status     │
+│  • Live updates     │  • Pattern matching    │
+├─────────────────────┴──────────────────────┤
+│         TypeScript Engine (as needed)        │
+│  • LLM policy compilation (Gemini API)       │
+│  • AST validation (Tree-sitter)              │
+│  • Audit logging and reporting               │
+└──────────────────────────────────────────────┘
 ```
 
-**Agent shortcuts:** `cc` (Claude Code), `oc` (OpenCode), `cursor`, `windsurf`, `aider`
+Built-in policies execute in Go (instant). Custom policies compile via TypeScript engine with LLM.
 
-## Architecture
+<br>
+
+## How It Works
+
+**Step 1: Policy Compilation**
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│                    leash (Go, 4.5MB)                    │
-├─────────────────────────────────────────────────────────┤
-│  TUI Dashboard          │  Fast Commands               │
-│  - Policy management    │  - list, status, sync        │
-│  - Agent installation   │  - install, uninstall        │
-│  - Real-time monitoring │  - Pattern matching          │
-├─────────────────────────┴───────────────────────────────┤
-│              TypeScript Engine (when needed)            │
-│  - LLM policy compilation (custom rules)                │
-│  - AST validation (Tree-sitter)                         │
-│  - 243 tests                                            │
-└─────────────────────────────────────────────────────────┘
+Input: "no lodash"
+  ↓
+Check built-in patterns → Match found
+  ↓
+Generate:
+  - Regex pre-filter: /lodash/
+  - AST query: (import_statement source: "lodash")
+  - Suggested alternative: "Use native ES6+"
 ```
 
-**Key insight**: 95%+ of policies use built-in rules (pure Go, instant). LLM compilation only runs for custom rules.
+**Step 2: Runtime Enforcement**
 
-## How It Works
+```
+Agent attempts: import _ from 'lodash'
+  ↓
+Regex pre-filter → Contains "lodash"
+  ↓
+Parse file with Tree-sitter (5ms)
+  ↓
+Query AST → Import statement found
+  ↓
+BLOCK with context and suggestion
+```
+
+<br>
+
+## Configuration
+
+### .leash Format
 
 ```
-User: "no lodash"
-         ↓
-┌─────────────────────────────────────────┐
-│  1. Check builtins (instant, no LLM)    │
-│     → Found: "no lodash" builtin        │
-└─────────────────────────────────────────┘
-         ↓
-┌─────────────────────────────────────────┐
-│  2. Runtime: Write/Edit intercepted     │
-│     → Regex pre-filter: "lodash"?       │
-│     → AST parse (5ms, cached)           │
-│     → BLOCKED with line/column          │
-└─────────────────────────────────────────┘
+# Lines starting with # are comments
+no lodash
+no any types - enforces strict TypeScript
+protect .env
+prefer pnpm over npm
 ```
 
-## Environment Variables
+Policies support optional reasoning after `-`.
+
+### Environment Variables
 
-| Variable         | Description                                 |
-| ---------------- | ------------------------------------------- |
-| `GEMINI_API_KEY` | Only needed for custom rules (not builtins) |
+| Variable         | Purpose                         | Required |
+| ---------------- | ------------------------------- | -------- |
+| `GEMINI_API_KEY` | LLM compilation for custom rules | Optional |
 
-Get a free API key: https://aistudio.google.com/apikey
+Free API key: https://aistudio.google.com/apikey
 
-## Philosophy
+Built-in policies work without API key.
 
-1. **Surgeon-level precision** - AST parsing = zero false positives
-2. **Invisible until needed** - Auto-detection, background enforcement
-3. **Native performance** - Go binary, instant startup
-4. **Natural language** - `no lodash` not `{ "rule": "no-import", "pattern": "^lodash" }`
+<br>
 
-## Test Suite
+## CLI Reference
 
 ```
-243 tests passing
-├── 77 AST validation tests
-├── 93 content matching tests
-├── 41 command interception tests
-├── 17 pattern matcher tests
-├── 16 builtin rules tests
-├── 12 parser tests
-└── 9 session tests
+USAGE
+  leash                     Interactive dashboard
+  leash init                Setup wizard
+  leash add "policy"        Add enforcement rule
+  leash list                Show active policies
+  leash sync [agent]        Apply to agents
+  leash install <agent>     Install agent hooks
+  leash uninstall <agent>   Remove hooks
+  leash status              Show configuration
+  leash explain "policy"    Preview rule behavior
+  leash audit [--tail]      View enforcement log
+  leash update              Update to latest version
+
+AGENTS
+  cc, claude-code    Claude Code
+  oc, opencode       OpenCode
+  cursor             Cursor
+  windsurf           Windsurf
+  aider              Aider
 ```
 
+<br>
+
+## Development
+
+### Build from Source
+
+```bash
+git clone https://github.com/VulnZap/veto-leash
+cd veto-leash
+pnpm install
+pnpm build
+cd go && make build-all
+```
+
+### Run Tests
+
+```bash
+pnpm test              # TypeScript test suite
+pnpm typecheck         # Type validation
+go test ./...          # Go tests
+```
+
+### Test Suite
+
+- 243 tests passing
+- 77 AST validation tests
+- 93 content matching tests
+- 41 command interception tests
+- 17 pattern matcher tests
+- 16 builtin rule tests
+- 12 parser tests
+- 9 session tests
+
+<br>
+
+## Design Principles
+
+1. **Precision over approximation** - AST parsing eliminates false positives
+2. **Speed over flexibility** - Native binary, instant feedback
+3. **Clarity over cleverness** - Natural language policies
+4. **Safety over convenience** - Explicit validation required
+
+<br>
+
+## Comparison
+
+| Feature          | veto-leash   | git hooks | IDE linters |
+| ---------------- | ------------ | --------- | ----------- |
+| AST validation   | Yes          | No        | Limited     |
+| Natural language | Yes          | No        | No          |
+| Agent-aware      | Yes          | No        | No          |
+| False positives  | Zero         | High      | Medium      |
+| Runtime          | 5ms          | N/A       | Seconds     |
+| Setup            | One command  | Manual    | Per-project |
+
+<br>
+
 ## License
 
 Apache-2.0
 
+See [LICENSE](LICENSE) for details.
+
+<br>
+
 ---
 
 <p align="center">
   Built by <a href="https://plaw.io">Plaw, Inc.</a> for the <a href="https://veto.run">Veto</a> product line.
-  <br><br>
-  <strong>Ship faster. Sleep better.</strong>
 </p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veto-leash",
-  "version": "2.0.4",
+  "version": "2.1.1",
   "description": "Semantic permissions for AI coding agents — sudo for AI agents",
   "main": "./dist/cli.js",
   "bin": {