aihype 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7cc192201918569a5ff5128801c64cee31c2efc7117ce270e26d0b92026d01a1
+  data.tar.gz: 43f1de094be13bc2b3cc10bf455f8584caec0031537418030d0dc5b4a89bdcd2
+SHA512:
+  metadata.gz: dd9ba38ee3b7c017336d59914d9819e9c4821d535af474de86a5198011272397b23922bd74757c9f7a9176c7a10daceac4afe7fe8d1cc4e25ca223acd30ed8e5
+  data.tar.gz: cd8c74bf746ba393ebdc4ab9c9ca4aea7f7929b1d182163f33ec9af092432129fa5ac1735bbd6d7bce1fcc8b289a63ef17b1ba39948d49a92b1218d65e495487

data/README.md

@@ -0,0 +1,452 @@
+# AIHype
+
+Like `yes | ai` - auto-approve AI agent prompts with blacklist protection.
+
+## TL;DR
+
+```bash
+# Demo: Bash blocks on read, aihype auto-answers, proceeds
+aihype bash -c 'read -p "Deploy? (y/n) " x && echo "→ $x"'
+# Without aihype: hangs forever waiting for input
+# With aihype: auto-answers "yes", continues execution
+```
+
+## What It Does
+
+AIHype wraps command-line tools that ask for approval, spawning them via PTY and automatically responding to prompts like "Do you want to proceed? (y/n)" with "yes". Dangerous prompts matching blacklist rules get "no" instead, with AI-powered evaluation.
+
+Perfect for:
+- Automating interactive CLIs without modification
+- CI/CD pipelines with confirmation prompts
+- Controlling AI assistants (Claude, Gemini, etc.)
+- Protecting against dangerous operations
+
+---
+
+## Integration Tests (Real-World Verification)
+
+**IMPORTANT**: We provide real integration tests that verify aihype works with actual Claude CLI, not mocks.
+
+### Running Integration Tests
+
+```bash
+# Set your API key
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Run all integration tests (2-3 minutes, costs apply)
+./samples/00-verify-all.sh
+
+# Or run individual tests:
+./samples/01-api-key-approval.sh      # Basic Claude integration
+./samples/02-deployment-confirmation.sh # Multi-step workflow
+./samples/03-blacklist-denial.sh       # Security (CRITICAL)
+./samples/04-multi-prompt-sequence.sh  # Long output streaming
+```
+
+### What These Tests Verify
+
+✅ **Real Claude CLI integration** - Actual Claude process via API (tests 1, 2, 4)
+✅ **PTY process spawning and control** - Full process lifecycle management
+✅ **Output streaming** - Multi-paragraph responses flow correctly through PTY
+✅ **Interactive prompt handling** - Mock-claude tests y/n prompts (test 3)
+✅ **Blacklist security** - Dangerous prompts are denied, safe ones approved (CRITICAL)
+✅ **Claude --print mode** - Non-interactive automation mode (real-world CI/CD usage)
+
+**These tests are your "gut check"** - if they pass, aihype works in the real world.
+
+### Test Requirements
+
+- **ANTHROPIC_API_KEY**: Must be set (tests hit real API)
+- **claude CLI**: Must be installed (`npm install -g @anthropic-ai/claude-code`)
+- **Reasonable timeouts**: 30-60s per test (API latency)
+- **Conservative rate limits**: 5s delay between tests
+- **Real costs**: API calls cost money (minimal, but real)
+
+### Understanding Test Output
+
+Each test shows:
+- ✓ Prerequisites verified
+- Expected behavior description
+- Actual command output with [AIHype] logging
+- Success/failure with detailed diagnosis
+
+**If a test fails**, it tells you exactly what went wrong:
+- Process spawning issues?
+- Output streaming problems?
+- Blacklist not working?
+- API call failed?
+
+---
+
+## How It Works
+
+**Process Control via PTY:**
+```
+aihype <command> [args]
+  ↓
+Spawns command as child process via PTY
+  ↓
+Reads child's output, detects prompts
+  ↓
+Evaluates against blacklist via AI
+  ↓
+Writes "yes" or "no" to child's stdin
+  ↓
+Child continues with response
+```
+
+**NOT a pipe filter** - aihype actually controls the child process.
+
+## Installation
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+```bash
+# Initialize configuration
+./bin/aihype init
+
+# Run any interactive tool through aihype
+./bin/aihype your-tool --with-args
+
+# Set your Anthropic API key for AI-powered blacklist matching
+export ANTHROPIC_API_KEY=your_key_here
+```
+
+## Real Examples
+
+### Control Mock Claude
+
+```bash
+# Create a test config
+cat > test.yml <<'EOF'
+sequence:
+  - type: output
+    text: "Starting deployment..."
+  - type: prompt
+    text: "Do you want to proceed? (y/n)"
+    expect: ["y", "yes", "n", "no"]
+    if_yes: "Proceeding..."
+    if_no: "Cancelled."
+  - type: output
+    text: "Done!"
+EOF
+
+# Run with aihype
+./bin/aihype ./bin/mock-claude test.yml
+```
+
+Output:
+```
+Starting deployment...
+Do you want to proceed? (y/n)
+yes                           ← Auto-answered!
+Proceeding...
+Done!
+```
+
+### Security: Blacklist Protection
+
+```bash
+# Test with dangerous prompts
+./bin/aihype ./bin/mock-claude test/fixtures/dangerous_prompts.yml
+```
+
+Output:
+```
+Do you want to enable automatic backups? (y/n)
+yes                           ← APPROVED ✅
+
+Should I charge your credit card $500? (yes/no)
+no                            ← DENIED ⛔
+[AIHype] WARNING: DENIED: Should I charge your credit card $500?
+(matched rule: Never use the credit card)
+
+Payment cancelled.
+```
+
+### Control Real Claude
+
+```bash
+# AIHype controls Claude and auto-answers its prompts
+export ANTHROPIC_API_KEY=your_key
+./bin/aihype claude -p prompt.md
+```
+
+## Configuration
+
+### Blacklist Rules
+
+Edit `memory/aihype.md` to customize your blacklist rules:
+
+```markdown
+---
+version: 1.0.0
+created: 2025-10-02T00:00:00Z
+updated: 2025-10-02T00:00:00Z
+---
+
+# AIHype Blacklist Rules
+
+## Default Safety Rules
+- Never execute rm -rf / or similar destructive filesystem operations
+- Never modify critical system files (/etc/passwd, /boot/, /etc/shadow)
+- Never disable security features or firewalls
+
+## User Rules
+- Never use the credit card
+- Never delete production databases
+- Never install code sponsored by shopify
+```
+
+### Environment Variables
+
+```bash
+# API Configuration
+export ANTHROPIC_API_KEY=your_key_here          # Required for AI matching
+export AIHYPE_MODEL=claude-3-5-sonnet-20241022  # Override model selection
+export AIHYPE_MODEL_PREFERENCE=cheap            # fast, cheap, balanced, powerful
+export AIHYPE_API_TIMEOUT=5                     # API timeout in seconds
+
+# Rate Limiting
+export AIHYPE_RATE_LIMIT_RPM=50                 # Requests per minute (default: 50)
+export AIHYPE_RATE_LIMIT_WINDOW=60              # Window size in seconds (default: 60)
+
+# Paths
+export AIHYPE_CONFIG=memory/aihype.md           # Config file path
+export AIHYPE_LOG=memory/aihype.log             # Log file path
+
+# Logging
+export AIHYPE_VERBOSE=1                         # Enable verbose logging
+```
+
+## Commands
+
+### Spawn and Control a Command (default)
+
+```bash
+# AIHype spawns the command and controls it via PTY
+./bin/aihype <command> [args...]
+
+# Examples:
+./bin/aihype mock-claude config.yml
+./bin/aihype claude -p prompt.md
+./bin/aihype deployment-script.sh --production
+```
+
+### Initialize Config
+
+```bash
+# Create default memory/aihype.md configuration
+./bin/aihype init
+```
+
+### Validate Config
+
+```bash
+# Validate memory/aihype.md configuration
+./bin/aihype validate
+```
+
+Output:
+```
+Configuration is valid
+  Version: 1.0.0
+  Default rules: 3
+  User rules: 2
+  Total enabled rules: 5
+```
+
+### Options
+
+```bash
+./bin/aihype --help              # Show help
+./bin/aihype --version           # Show version
+./bin/aihype --config PATH cmd   # Custom config path
+./bin/aihype --log PATH cmd      # Custom log path
+./bin/aihype --verbose cmd       # Enable verbose logging
+```
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────┐
+│ aihype <command> [args]                      │
+└────────────────┬─────────────────────────────┘
+                 │
+                 ▼
+┌────────────────────────────────────────────────┐
+│ PTY.spawn(command, args)                       │
+│   - Spawns child process                       │
+│   - Creates pseudo-terminal                    │
+│   - Controls child's stdin/stdout              │
+└──────────┬─────────────────────┬───────────────┘
+           │                     │
+           │ stdout              │ stdin
+           ▼                     ▲
+┌──────────────────┐    ┌────────────────────┐
+│ Read child       │    │ Write responses    │
+│ output           │    │ to child           │
+│ (detect prompts) │    │ ("yes" or "no")    │
+└────┬─────────────┘    └─────────▲──────────┘
+     │                            │
+     │                            │
+     ▼                            │
+┌─────────────────────────────────┴──────────┐
+│ Prompt detected?                           │
+│  → Yes: Evaluate against blacklist         │
+│     → Match: respond "no" (DENIED)         │
+│     → No match: respond "yes" (APPROVED)   │
+│  → No: Pass through to stdout              │
+└────────────────────────────────────────────┘
+```
+
+## Real-World Use Cases
+
+### 1. Control AI assistants
+
+```bash
+# AIHype controls Claude and auto-approves safe operations
+./bin/aihype claude -p "deploy to staging"
+```
+
+### 2. Automate deployment scripts
+
+```bash
+# Your deploy script asks for confirmations, aihype answers them
+./bin/aihype ./deploy.sh --prod
+```
+
+### 3. CI/CD pipelines
+
+```bash
+# In your CI config:
+- run: aihype ./deployment-tool.sh
+```
+
+### 4. Protect against dangerous operations
+
+```bash
+# AIHype denies prompts about:
+# - Deleting production data
+# - Using credit cards
+# - Disabling security
+# - Any custom blacklist rules
+./bin/aihype dangerous-script.sh
+```
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rake test
+
+# Run specific test
+ruby -Ilib -Itest test/unit/test_core.rb
+
+# Run integration tests (requires ANTHROPIC_API_KEY)
+ANTHROPIC_API_KEY=your_key ./samples/00-verify-all.sh
+```
+
+## Testing
+
+### Unit Tests (Fast, No API)
+
+```bash
+# Run all unit tests (minitest)
+bundle exec rake test
+
+# Tests mock-claude interactions
+# No API key needed, runs offline
+```
+
+### Integration Tests (Slow, Real API)
+
+```bash
+# Run full integration suite with real Claude
+export ANTHROPIC_API_KEY=your_key
+./samples/00-verify-all.sh
+
+# Takes 3-5 minutes, hits real API
+# This is your "does it actually work?" test
+```
+
+Test coverage:
+- ✅ PTY process spawning and control
+- ✅ Prompt detection and pattern matching
+- ✅ Blacklist rule evaluation with real AI
+- ✅ Response writing to child process stdin
+- ✅ Integration tests with mock-claude
+- ✅ Real-world tests with actual Claude CLI
+- ✅ Security denials
+
+## Key Features
+
+✅ **Process control via PTY** - actually spawns and controls child processes
+✅ **Auto-answers approval prompts** with "yes"
+✅ **AI-powered blacklist protection** denies dangerous actions
+✅ **Real stdin/stdout control** - not a pipe filter
+✅ **Works with ANY interactive tool** - Claude, deploy scripts, installers, etc.
+✅ **Configurable rules** via markdown file
+✅ **Rate limiting** for API calls
+✅ **Dynamic model selection** from Anthropic API
+✅ **Graceful fallback** when API unavailable
+✅ **Real-world verification** via integration tests
+
+## Mock Claude for Testing
+
+AIHype includes `mock-claude`, a configurable test CLI that simulates interactive tools:
+
+```bash
+# Create a test scenario
+cat > scenario.yml <<'EOF'
+sequence:
+  - type: output
+    text: "Starting process..."
+  - type: prompt
+    text: "Continue? (y/n)"
+    expect: ["y", "n"]
+    if_yes: "Continuing..."
+    if_no: "Stopped."
+  - type: output
+    text: "Done!"
+EOF
+
+# Test with aihype
+./bin/aihype ./bin/mock-claude scenario.yml
+```
+
+See `test/fixtures/*.yml` for more examples.
+
+## Limitations
+
+**Claude AI Output Behavior**: Claude AI (via `claude -p`) outputs text and exits - it does not generate blocking interactive prompts that wait for user input. AIHype works perfectly with Claude for process control and output streaming, but there are no prompts to auto-answer in non-interactive mode.
+
+**Interactive Prompts**: To demonstrate auto-prompt-answering, use tools that actually generate blocking prompts:
+- `bash -c 'read -p "Continue? " x'` - Blocks on read
+- `rm -i file` - Interactive confirmation
+- `mock-claude` - Simulated interactive tool for testing
+
+**Real-World Value**: AIHype's primary use cases are:
+1. Wrapping deployment scripts with confirmation prompts
+2. Automating interactive CLI tools (`rm -i`, `apt-get`, etc.)
+3. Process control and logging for AI agents
+4. Blacklist security for any command-line tool
+
+## Technical Documentation
+
+- [PTY and Terminal Automation Analysis](docs/pty-terminal-automation.md) - Deep dive on why PTY approach is correct for Ink-based CLIs
+
+## License
+
+See LICENSE file for details.
+
+## Author
+
+See gemspec for author information.

data/bin/aihype

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Add lib directory to load path
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'aihype/cli'
+
+# Run the CLI
+AIHype::CLI.new(ARGV).run

data/bin/mock-claude

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Mock Claude CLI for testing aihype
+# Takes a config file that defines interaction sequences
+
+require 'yaml'
+require 'json'
+
+def main
+  config_file = ARGV[0]
+
+  unless config_file
+    $stderr.puts "Usage: mock-claude <config.yml>"
+    exit 1
+  end
+
+  unless File.exist?(config_file)
+    $stderr.puts "Error: Config file not found: #{config_file}"
+    exit 1
+  end
+
+  config = YAML.load_file(config_file)
+
+  # Run the interaction sequence
+  config['sequence'].each do |step|
+    case step['type']
+    when 'output'
+      puts step['text']
+      $stdout.flush
+
+    when 'prompt'
+      puts step['text']
+      $stdout.flush
+
+      # Wait for input
+      response = $stdin.gets
+
+      if response.nil?
+        $stderr.puts "ERROR: Expected input but got EOF"
+        exit 1
+      end
+
+      response = response.strip.downcase
+
+      # Check if response matches expected
+      if step['expect']
+        expected = step['expect'].map(&:downcase)
+        unless expected.include?(response)
+          $stderr.puts "WARNING: Got '#{response}', expected one of: #{expected.join(', ')}"
+        end
+      end
+
+      # Handle conditional flow
+      if step['if_yes'] && ['y', 'yes'].include?(response)
+        puts step['if_yes']
+        $stdout.flush
+      elsif step['if_no'] && ['n', 'no'].include?(response)
+        puts step['if_no']
+        $stdout.flush
+      end
+
+    when 'error'
+      $stderr.puts step['text']
+
+    when 'sleep'
+      sleep step['duration'] || 0.1
+
+    else
+      $stderr.puts "Unknown step type: #{step['type']}"
+    end
+  end
+
+  exit 0
+end
+
+main

data/lib/aihype/ai_matcher.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require_relative 'env'
+require_relative 'model_selector'
+require_relative 'rate_limiter'
+
+module AIHype
+  class AIMatcher
+    attr_reader :api_key, :timeout, :model
+
+    CLAUDE_API_URL = 'https://api.anthropic.com/v1/messages'
+
+    # Class-level rate limiter shared across all instances
+    def self.rate_limiter
+      @rate_limiter ||= RateLimiter.new(
+        requests_per_minute: Env.rate_limit_rpm,
+        window_size: Env.rate_limit_window
+      )
+    end
+
+    def initialize(api_key: nil, timeout: nil, model: nil)
+      @api_key = api_key || Env.anthropic_api_key
+      @timeout = timeout || Env.api_timeout
+      @model = model || select_model
+    end
+
+    def evaluate(prompt_text, blacklist_rules)
+      return fallback_result('No API key provided') if @api_key.nil? || @api_key.empty?
+
+      request_payload = build_request(prompt_text, blacklist_rules)
+      response = http_post(request_payload)
+      parse_response(response)
+    rescue Faraday::TimeoutError
+      fallback_result('AI timeout')
+    rescue Faraday::UnauthorizedError
+      fallback_result('Authentication failed')
+    rescue Faraday::ConnectionFailed, Faraday::Error
+      fallback_result('Network error')
+    rescue JSON::ParserError, StandardError => e
+      fallback_result("Invalid response: #{e.message}")
+    end
+
+    def http_post(payload)
+      # Apply rate limiting before making request
+      self.class.rate_limiter.throttle
+
+      conn = Faraday.new(url: CLAUDE_API_URL) do |f|
+        f.request :json
+        f.response :json
+        f.adapter Faraday.default_adapter
+        f.options.timeout = @timeout
+        f.options.open_timeout = @timeout
+      end
+
+      response = conn.post do |req|
+        req.headers['anthropic-version'] = '2023-06-01'
+        req.headers['x-api-key'] = @api_key
+        req.headers['content-type'] = 'application/json'
+        req.body = payload
+      end
+
+      extract_claude_response(response.body)
+    end
+
+    private
+
+    def build_request(prompt_text, blacklist_rules)
+      rules_text = blacklist_rules.each_with_index.map { |rule, i| "#{i + 1}. #{rule}" }.join("\n")
+
+      system_prompt = 'You are a blacklist rule evaluator. Given an approval prompt and a list of blacklist rules in plain English, determine if the prompt violates any rule. Respond ONLY with JSON: {"matched": true/false, "rule_id": "<rule_content>" or null, "confidence": 0.0-1.0, "reasoning": "brief explanation"}'
+
+      user_content = <<~CONTENT
+        Prompt: "#{prompt_text}"
+
+        Blacklist Rules:
+        #{rules_text}
+
+        Does the prompt violate any rule?
+      CONTENT
+
+      {
+        model: @model,
+        max_tokens: 100,
+        temperature: 0.0,
+        system: system_prompt,
+        messages: [
+          { role: 'user', content: user_content }
+        ]
+      }
+    end
+
+    def select_model
+      # Check for explicit model override
+      explicit_model = Env.model
+      return explicit_model if explicit_model && !explicit_model.empty?
+
+      # Use model selector to pick best model
+      preference = Env.model_preference
+      selector = ModelSelector.new(api_key: @api_key, preference: preference)
+      selector.select_model
+    end
+
+    def extract_claude_response(body)
+      # Check for API errors
+      if body.is_a?(Hash) && body['type'] == 'error'
+        error_msg = body.dig('error', 'message') || 'Unknown API error'
+        raise StandardError, "API error: #{error_msg}"
+      end
+
+      # If already in the right format
+      return body if body.is_a?(Hash) && body['matched']
+
+      # Extract from Claude's response format
+      content_text = body.dig('content', 0, 'text')
+      return body unless content_text
+
+      JSON.parse(content_text)
+    end
+
+    def parse_response(response)
+      raise StandardError, 'Invalid response format' unless response.is_a?(Hash)
+
+      {
+        matched: response['matched'] || false,
+        rule_id: response['rule_id'],
+        confidence: response['confidence'] || 0.0,
+        reasoning: response['reasoning'],
+        error: nil
+      }
+    end
+
+    def fallback_result(error_message)
+      {
+        matched: false,
+        rule_id: nil,
+        confidence: 0.0,
+        reasoning: nil,
+        error: error_message
+      }
+    end
+  end
+end