# Install
npm install buggy

# Initialize in your project
cd /path/to/your/project
npx buggy init

# Edit .debugger.yaml to match your project setup, then:
npx buggy analyze src/payments.ts
npx buggy investigate processPayment --file src/payments.ts

git add .kiro/
git commit -m "Add Buggy hooks and steering files for automatic bug detection"

npm install buggy

npm install -g buggy
buggy --help

language: typescript
parser:
  command: tree-sitter-typescript
lsp:
  command: typescript-language-server
sandbox:
  runtime: node
  memory_limit_mb: 512
  timeout_seconds: 60

# Buggy
.debugger/

import { ProofDebugger } from 'buggy';

const debugger_ = new ProofDebugger({
  projectRoot: '/path/to/your/project',
  language: 'typescript', // optional override
  sandbox: { memory_limit_mb: 1024 }, // optional override
});

await debugger_.initialize();

// Investigate a specific function
const report = await debugger_.investigate({
  functionId: 'processPayment',
  filePath: 'src/payments.ts',
  specification: {
    preconditions: ['amount > 0'],
    postconditions: ['result.status === "success" || result.status === "failed"'],
    parameters: [{ name: 'amount', type: 'number' }],
    return_type: 'PaymentResult',
  },
});

// Access results
console.log(report.status);
// → 'confirmed_and_repaired' | 'confirmed_no_repair' | 'unconfirmed' | 'halted'

console.log(report.proof);           // The proof-of-failure certificate
console.log(report.approved_patches); // Patches that passed overfitting check

// Run a single parse
const parseResult = await debugger_.parse('src/payments.ts');
console.log(parseResult.cst);    // Full concrete syntax tree
console.log(parseResult.errors); // Syntax errors with locations

// Query the semantic graph
const { callees, edges } = await debugger_.queryCallees('processPayment');

// Query a specific node
const node = debugger_.queryNode('node_42');

// Get file subgraph
const { nodes, edges: fileEdges } = debugger_.queryFileGraph('src/payments.ts');

// Check investigation status
const status = debugger_.getStatus(report.id);

// Halt a running investigation
debugger_.halt(report.id);

// Shutdown (closes DB, LSP connections)
await debugger_.shutdown();

interface ProofDebuggerOptions {
  projectRoot: string;        // Required: path to your project
  language?: string;          // Override auto-detected language
  configPath?: string;        // Custom .debugger.yaml path
  dbPath?: string;            // Custom database path
  sandbox?: {
    memory_limit_mb?: number;
    timeout_seconds?: number;
    egress_policy?: 'deny' | 'allow_host_only';
  };
  probe?: {
    search_budget?: number;
    max_refinement_iterations?: number;
  };
}

buggy init
buggy init --json  # Machine-readable output

buggy analyze src/payments.ts
buggy analyze src/payments.ts --verbose   # Show CST depth-2 summary
buggy analyze src/payments.ts --json      # Full JSON output

buggy investigate processPayment --file src/payments.ts
buggy investigate processPayment -f src/payments.ts --verbose
buggy investigate processPayment -f src/payments.ts --json

buggy status inv_1234567890_abc1234
buggy status inv_1234567890_abc1234 --json

buggy halt inv_1234567890_abc1234

# Required
version: "1.0"
language: typescript    # Primary project language

# Parser configuration
parser:
  command: tree-sitter-typescript  # Tree-sitter grammar to use
  grammar_path: ./custom.wasm     # Optional: path to custom grammar

# Language Server Protocol
lsp:
  command: typescript-language-server
  initialization_options:          # Optional: passed to LSP on init
    preferences:
      includeInlayParameterNameHints: "all"

# Sandbox execution environment
sandbox:
  runtime: node                    # Execution runtime (node, python, deno, bun)
  memory_limit_mb: 512             # 64-8192 MB
  timeout_seconds: 60              # 1-300 seconds
  egress_policy: deny              # deny | allow_host_only

# Oracle violation detectors
oracles:
  timeout_threshold_seconds: 10    # 1-300 seconds
  crash_detection: true
  overflow_detection: true
  determinism_check_count: 5       # 1-100 runs

# PROBE loop configuration
probe:
  search_budget: 100               # Max property candidates
  max_refinement_iterations: 10    # Max iterations per property

# Optional: custom plug-ins
plugs:
  parsing: ./plugs/parser
  oracles:
    - ./plugs/memory-oracle
  repair: ./plugs/repair-strategy
  sandbox_executor: ./plugs/sandbox

┌──────────────────────────────────────────────────────────────┐
│                     Agent Orchestrator                        │
│  (Coordinates sequential pipeline + sandbox concurrency)     │
└─────────┬──────────┬──────────────┬──────────────┬───────────┘
          │          │              │              │
    ┌─────▼─────┐ ┌─▼──────────┐ ┌▼──────────┐ ┌─▼───────────┐
    │  Parser   │ │ Bug-Proving │ │  Repair   │ │ Classifier  │
    │  Agent    │ │   Agent     │ │  Agent    │ │   Agent     │
    └───────────┘ └─────────────┘ └───────────┘ └─────────────┘
          │              │              │              │
          └──────────────┴──────────────┴──────────────┘
                              │
                    ┌─────────▼─────────┐
                    │   Sandbox Agent   │
                    │  (up to 4 conc.)  │
                    └───────────────────┘

import type { ParsingPlug } from 'buggy';

export const myParser: ParsingPlug = {
  name: 'my-custom-parser',
  parse(source: string, filePath: string) {
    // Your custom parsing logic
    return { cst, errors, duration_ms, file_path: filePath };
  },
};

import type { OraclePlug } from 'buggy';

export const memoryOracle: OraclePlug = {
  name: 'memory-leak-detector',
  detect(executionResult) {
    // Analyze execution for memory leaks
    return violations;
  },
};

import type { RepairPlug } from 'buggy';

export const mlRepair: RepairPlug = {
  name: 'ml-based-repair',
  generatePatches(proof, target) {
    // ML-based patch generation
    return patches;
  },
};

plugs:
  parsing: ./plugs/my-custom-parser
  oracles:
    - ./plugs/memory-leak-detector
  repair: ./plugs/ml-based-repair

# Build
npm run build

# Run tests
npm test

# Run specific test suites
npm run test:unit
npm run test:properties
npm run test:integration

# Run the CLI locally
node dist/cli.js --help