veto-leash 0.1.3 → 1.0.0

package/README.md

@@ -3,7 +3,6 @@
   <p align="center"><strong>sudo for AI 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/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/VulnZap/veto-leash/ci.yml?style=flat-square&color=black&label=tests" alt="CI"></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>
   </p>
@@ -12,247 +11,163 @@
 Your AI agent has root access to your codebase. You have... vibes.
 
 ```bash
-leash cc "don't delete test files"
+# One file. That's it.
+echo "no lodash
+no any types" > .leash
+
+leash init  # Auto-detects agents, installs hooks
 ```
 
-Now every destructive action requires explicit policy. No regex. No config files. Just English.
+Now every action is validated with **AST-level precision**. Zero false positives. Zero config.
+
+## What's New in 1.0
+
+- **🎯 AST Validation** - Tree-sitter parsing means `// import lodash` in comments is ignored
+- **📄 Simple `.leash` format** - One rule per line, no YAML boilerplate
+- **🔍 Auto-detection** - `leash init` finds and configures all your AI agents
+- **⚡ Instant** - 95%+ policies use built-in rules (no LLM call needed)
 
 ## The Problem
 
-AI coding agents can delete your test files, wipe your .env, run arbitrary migrations. Current permission systems require you to write regex patterns and understand glob syntax. You want to say "protect my tests" and be done.
+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.
+
+Regex-based blockers create false positives. A comment saying `// TODO: remove lodash` shouldn't trigger a block.
 
 ## The Solution
 
-veto-leash compiles natural language restrictions into precise policies **once**, then enforces them at runtime with zero LLM latency.
+veto-leash uses **AST parsing** for surgical precision:
 
-```
-"don't delete test files"
-        │
-        ▼
-┌─────────────────────────────────────┐
-│  Semantic Compilation (100ms)       │
-│  • Understands "test files" = test  │
-│    source code, not test-results.xml│
-│  • Gemini 2.0 Flash + JSON Schema   │
-│  • Cached for instant reuse         │
-└─────────────────────────────────────┘
-        │
-        ▼
-┌─────────────────────────────────────┐
-│  Policy                             │
-│  action: delete                     │
-│  include: *.test.*, *.spec.*,       │
-│           __tests__/**, test/**     │
-│  exclude: test-results.*, coverage/ │
-└─────────────────────────────────────┘
-        │
-        ▼
-    Enforcement (0ms per check)
-```
+| 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)       |
+
+**This precision is our moat.** No other tool achieves zero false positives.
 
 ## Quick Start
 
 ```bash
-# Install
+# Install globally
 npm install -g veto-leash
 
-# Get free Gemini API key (optional - builtins work without it)
-# https://aistudio.google.com/apikey
-export GEMINI_API_KEY="your-key"
+# Create a simple .leash file
+echo "no lodash
+no any types
+no console.log" > .leash
 
-# Use it
-leash cc "don't delete test files"
+# One command setup
+leash init
 ```
 
-That's it. Your Claude Code session now blocks test file deletions.
-
-## How It Works
-
-### Three Enforcement Modes
-
-| Mode | Use Case | How |
-|------|----------|-----|
-| **Wrapper** | Any agent | PATH hijacking, TCP daemon |
-| **Native** | Claude Code, Windsurf, OpenCode | Hooks directly into agent |
-| **Watchdog** | Background protection | File system monitoring, auto-restore |
-
-### Native Integrations
+That's it. `leash init` will:
 
-```bash
-# Claude Code - PreToolUse hooks
-leash add "don't delete test files"
-leash install cc
-
-# Windsurf - Cascade hooks  
-leash add "protect .env"
-leash install windsurf
-
-# OpenCode - permission.bash rules
-leash add "no migrations"
-leash install oc
-```
+1. Detect installed agents (Claude Code, Cursor, OpenCode, Windsurf)
+2. Install native hooks for each
+3. Your policies are now enforced
 
-### Wrapper Mode (Works with anything)
+## Simple `.leash` Format
 
-```bash
-# Works with ANY CLI agent
-leash cc "don't delete test files"
-leash opencode "protect .env"
-leash cursor "no database migrations"
-leash aider "read-only src/core"
-leash my-custom-agent "protect config"
 ```
-
-### Watchdog Mode (Catches everything)
-
-```bash
-# Background file protection - catches programmatic changes too
-leash watch "protect test files"
+# .leash - One rule per line
+no lodash
+no any types - enforces strict TypeScript
+no console.log
+prefer pnpm over npm
 ```
 
-## Supported Agents
-
-| Agent | Native | Wrapper | Notes |
-|-------|--------|---------|-------|
-| Claude Code | PreToolUse hooks | PATH shims | Best support |
-| Windsurf | Cascade hooks | PATH shims | Full support |
-| OpenCode | permission.bash | PATH shims | Full support |
-| Cursor | .cursorrules | PATH shims | Guidance only |
-| Aider | .aider.conf.yml | PATH shims | Read-only files |
-| Codex CLI | - | Watchdog | OS sandbox |
-| GitHub Copilot | - | Wrapper | No hooks |
-| Any CLI tool | - | PATH shims | Universal |
+Lines starting with `#` are comments. Optional reasons after `-`.
 
-## Project Configuration
+## Built-in AST Rules
 
-Create a `.leash` file for team-wide policies:
+These work **instantly** with zero LLM calls:
 
-```yaml
-# .leash
-version: 1
+| Rule                  | What It Catches                            |
+| --------------------- | ------------------------------------------ |
+| `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 debugger`         | debugger statements                        |
+| `no var`              | var declarations                           |
 
-policies:
-  - "don't delete test files"
-  - "protect .env"
-  - "no database migrations"
+## Native Agent Support
 
-settings:
-  fail_closed: true
-  audit_log: true
-```
-
-Then sync to your agents:
-
-```bash
-leash sync cc
-leash sync windsurf
-```
+| Agent           | How It Works                         | Status       |
+| --------------- | ------------------------------------ | ------------ |
+| **Claude Code** | PreToolUse hooks with AST validation | ✅ Full      |
+| **Cursor**      | hooks.json + beforeShellExecution    | ✅ Full      |
+| **OpenCode**    | permission.bash deny rules           | ✅ Full      |
+| **Windsurf**    | Cascade pre_write_code hooks         | ✅ Full      |
+| **Aider**       | .aider.conf.yml read-only            | ✅ Partial   |
+| **Any CLI**     | Wrapper mode (PATH hijacking)        | ✅ Universal |
 
 ## Commands
 
 ```
-leash <agent> "<restriction>"     Wrap agent with policy
-leash watch "<restriction>"       Background file protection
-leash explain "<restriction>"     Preview policy without installing
-leash add "<restriction>"         Save policy for native install
-leash init                        Create .leash config file
-leash sync [agent]                Apply .leash policies
-leash install <agent>             Install native hooks
-leash uninstall <agent>           Remove native hooks
-leash list                        Show saved policies
-leash audit [--tail] [--clear]    View audit log
-leash login                       Leash Cloud (coming soon)
+leash init                        Auto-detect agents, install hooks
+leash sync [agent]                Apply .leash policies to agents
+leash add "<rule>"                Add a policy
+leash install <agent>             Install hooks for specific agent
+leash explain "<rule>"            Preview what a rule catches
+leash watch "<rule>"              Background file protection
+leash audit [--tail]              View enforcement log
 leash status                      Show active sessions
-leash clear                       Clear compilation cache
 ```
 
-## Built-in Patterns
-
-These work instantly without an API key:
-
-| Phrase | What It Protects |
-|--------|------------------|
-| `test files` | `*.test.*`, `*.spec.*`, `__tests__/**` |
-| `.env` | `.env`, `.env.*`, excluding `.env.example` |
-| `migrations` | `**/migrations/**`, `prisma/migrations/**` |
-| `config` | `*.config.*`, `tsconfig*`, `.eslintrc*` |
-| `lock files` | `package-lock.json`, `yarn.lock`, etc. |
-
-## Examples
-
-```bash
-# Preview what a policy protects
-leash explain "don't delete test files"
-
-# Wrapper mode - intercepts shell commands
-leash cc "don't delete test files"
-
-# Native mode - integrates with agent's permission system
-leash add "don't delete test files"
-leash add "protect .env"
-leash install cc
-
-# Watchdog mode - file system monitoring
-leash watch "protect test files"
+## How It Works
 
-# Team config
-leash init              # Creates .leash
-leash sync windsurf     # Applies to agent
+```
+User: "no lodash"
+         ↓
+┌─────────────────────────────────────────┐
+│  1. Check builtins (instant, no LLM)    │
+│     → Found: "no lodash" builtin        │
+└─────────────────────────────────────────┘
+         ↓
+┌─────────────────────────────────────────┐
+│  2. Runtime: Write/Edit intercepted     │
+│     → Regex pre-filter: contains        │
+│       "lodash"? Yes → continue          │
+│     → AST parse (5ms, cached)           │
+│     → Query: import_statement with      │
+│       source matching "lodash"          │
+│     → BLOCKED with line/column          │
+└─────────────────────────────────────────┘
 ```
 
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `GEMINI_API_KEY` | Required for custom restrictions (not builtins) |
-| `LEASH_CLOUD_URL` | Leash Cloud API endpoint (coming soon) |
-| `LEASH_API_KEY` | Leash Cloud API key (coming soon) |
+**Key insight**: Regex pre-filter skips 95%+ of files instantly. AST parsing only runs when needed.
 
-## Leash Cloud (Coming Soon)
+## Environment Variables
 
-- Team-wide policy sync
-- Centralized audit logs
-- LLM credits for compilation
-- Policy analytics
+| Variable         | Description                                 |
+| ---------------- | ------------------------------------------- |
+| `GEMINI_API_KEY` | Only needed for custom rules (not builtins) |
 
-Join the waitlist: https://leash.cloud
+Get a free API key: https://aistudio.google.com/apikey
 
 ## Philosophy
 
-1. **Semantic over syntactic** - "test files" means test source code, not files with "test" in the name
-2. **Compile once, enforce always** - LLM runs once at startup, enforcement is instant
-3. **Fail closed** - If the daemon is unreachable, commands are blocked
-4. **Defense in depth** - Native hooks + wrapper mode + watchdog = comprehensive protection
-5. **No config tax** - Natural language in, protection out
-
-## How veto-leash Protects Files
-
-When you run `leash cc "don't delete test files"`:
-
-1. **Compile**: Natural language → glob patterns (via Gemini 2.0 Flash)
-2. **Start daemon**: TCP server on localhost (random port)
-3. **Create shims**: Shell wrappers for `rm`, `git rm`, etc.
-4. **Launch agent**: With modified PATH
-5. **Intercept**: Every shell command checks daemon first
-6. **Block or allow**: Based on policy
+1. **Surgeon-level precision** - AST parsing = zero false positives
+2. **Invisible until needed** - Auto-detection, background enforcement
+3. **Steroid, not weight** - Makes AI agents _better_, not slower
+4. **Natural language policies** - `no lodash` not `{ "rule": "no-import", "pattern": "^lodash" }`
 
-The agent never knows veto-leash is there - it just sees commands failing with clear error messages.
+## Test Suite
 
-## Security Model
-
-- Localhost only (`127.0.0.1`)
-- Random port each session
-- Temp directory cleaned on exit
-- No eval - patterns validated with micromatch
-- Fail closed by default
-- API key from environment only
-
-## Platform Support
-
-- macOS
-- Linux
-- Windows (PowerShell shims)
-- WSL
+```
+229 tests passing
+├── 41 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
+```
 
 ## License
 

package/dist/ast/builtins.d.ts

@@ -0,0 +1,28 @@
+import type { ASTRule } from '../types.js';
+/**
+ * Pre-compiled AST queries for common restrictions.
+ * These replace regex-based content rules with precise structural queries.
+ *
+ * Key advantages over regex:
+ * - Zero false positives (AST ignores comments and strings)
+ * - Catches all variants (destructuring, bracket notation, dynamic imports)
+ * - Can express structural constraints regex cannot
+ *
+ * Query syntax: tree-sitter S-expressions
+ * - (node_type) matches any node of that type
+ * - (node_type field: (child)) matches with specific field
+ * - @name captures the node
+ * - (#eq? @name "value") exact string match on node text
+ * - (#match? @name "regex") regex match on node text
+ */
+export declare const AST_BUILTINS: Record<string, ASTRule[]>;
+/**
+ * Get all AST rules for a restriction
+ * Normalizes common variations (e.g., "no any" vs "no any types")
+ */
+export declare function getASTRules(restriction: string): ASTRule[] | null;
+/**
+ * List all available AST builtin keys
+ */
+export declare function listASTBuiltins(): string[];
+//# sourceMappingURL=builtins.d.ts.map

package/dist/ast/builtins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/ast/builtins.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAyUlD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,IAAI,CA0BjE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAE1C"}