# Vibe-Audit

**Autonomous DOM Lifecycle Auditor** -- built on the principles of the [Kaggle 5-Day Gen AI Intensive Course](https://www.kaggle.com/learn-guide/5-day-genai).

[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.12-6B46C1?style=flat-square)](https://github.com/modelcontextprotocol/typescript-sdk)
[![Gemini](https://img.shields.io/badge/Gemini-2.5%20Flash-4285F4?style=flat-square&logo=google&logoColor=white)](https://deepmind.google/technologies/gemini/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)

A multi-agent system that scans a JavaScript or TypeScript source file for unbalanced `addEventListener` calls, flags memory-leak vectors, and produces a validated patch via a Gemini LLM. Every output passes through a deterministic security handrail before it is surfaced.

---

## Problem

DOM event listeners registered without a matching cleanup call are one of the most common memory leak vectors in long-running single-page applications. Each time a component mounts without calling `removeEventListener` on unmount, the listener and its closure are retained in memory indefinitely. Standard linters catch the most obvious cases but miss the framework-specific teardown patterns -- React's `useEffect` cleanup return, Vue's `onUnmounted` hook, and the `AbortController` signal pattern -- that account for the majority of leaks in modern codebases.

Vibe-Audit addresses this gap with a dedicated MCP tool that performs a structural scan of any source file and, when a leak is detected, delegates to an LLM-powered patching agent to generate a corrected version. Every generated patch is screened by a deterministic validation layer before it is returned.

---

## Table of Contents

1. [Architecture Overview](#architecture-overview)
2. [Execution Flow](#execution-flow)
3. [Course Concept Mapping](#course-concept-mapping)
4. [Security Layers](#security-layers)
5. [Installation and Local Execution](#installation-and-local-execution)
6. [Project Structure](#project-structure)
7. [Sample Pipeline Output](#sample-pipeline-output)
8. [Demonstration Video](#demonstration-video)
9. [Roadmap](#roadmap)

---

## Architecture Overview

The system runs as two separate processes. The orchestrator process hosts the agent logic. The MCP server process hosts the diagnostic tool. They communicate over stdio using the JSON-RPC transport defined by the Model Context Protocol.

```mermaid
graph TB
    subgraph orchestrator["Orchestrator Process (src/orchestrator.ts)"]
        A["Auditor Agent\nrunAuditorAgent()"]
        R["Router\nrouterDecision()"]
        P["Patching Agent\nrunPatchingAgent()"]
        V["Validation Handrail\nrunValidationHandrail()"]

        A --> R
        R -- "requiresPatch = true" --> P
        R -- "requiresPatch = false" --> done1["Return PipelineContext"]
        P --> V
        V -- "passed = true" --> done2["Return PipelineContext"]
        V -- "passed = false" --> done3["Return PipelineContext (flagged)"]
    end

    subgraph mcp["MCP Server Process (src/index.ts)"]
        T["Tool: analyze_dom_lifecycles\n1. Sanitize filePath\n2. Read file\n3. Pattern scan\n4. Return CRITICAL or OK"]
    end

    subgraph gemini["External"]
        G["Gemini 2.5 Flash API"]
    end

    A -- "stdio JSON-RPC" --> T
    T -- "diagnostic string" --> A
    P -- "HTTPS" --> G
    G -- "raw patch text" --> P
```

---

## Execution Flow

```mermaid
sequenceDiagram
    participant CLI
    participant Orchestrator
    participant MCPServer as MCP Server
    participant Gemini

    CLI->>Orchestrator: executeAuditPipeline(filePath, source)
    Orchestrator->>MCPServer: tools/call analyze_dom_lifecycles
    MCPServer-->>Orchestrator: "CRITICAL: Memory leak vector detected..."
    Orchestrator->>Orchestrator: routerDecision() -- requiresPatch = true
    Orchestrator->>Gemini: generateContent(structuredPrompt + source)
    Gemini-->>Orchestrator: patched source text
    Orchestrator->>Orchestrator: runValidationHandrail()
    alt validation passes
        Orchestrator-->>CLI: PipelineContext (validationResult.passed = true)
    else validation fails
        Orchestrator-->>CLI: PipelineContext (validationResult.passed = false, flaggedPatterns)
    end
```

---

## Course Concept Mapping

| Rubric Criterion | Course Day | Implementation | File |
|---|---|---|---|
| Agent / Multi-agent system (ADK) | Day 5 | `PerformanceOrchestrator` is the ADK router. `runAuditorAgent` and `runPatchingAgent` are specialist agents with single responsibilities. State passes through an immutable `PipelineContext` object -- the ADK context-enrichment pattern. | `src/orchestrator.ts` |
| MCP Server | Day 5 | `McpServer` with `StdioServerTransport`. Tool `analyze_dom_lifecycles` is registered with a Zod-validated `filePath` input. The orchestrator uses an adapter function so the mock and the live `Client` session share the same interface. | `src/index.ts` |
| Structured prompting | Day 2 | `buildPatchPrompt()` produces a multi-section system prompt with explicit role, mandatory rules, absolute prohibitions, and an output contract. The prompt is separated from the invocation call so it can be versioned and tested independently. | `src/orchestrator.ts` |
| Security features | Day 4 | Three independent layers: (1) API key pre-flight in constructor, (2) directory-traversal guard in MCP server via `path.resolve` and prefix check, (3) six-category regex scan of every LLM output before it is returned. | `src/index.ts`, `src/orchestrator.ts` |
| Deployability | Day 5 | ESM project with `type: module`, strict `tsconfig.json`, single `npm run build` step. Launchable by any MCP host (Claude Desktop, Continue, ADK runtime) via a one-entry JSON config block. | `package.json`, `tsconfig.json` |
| Evaluation / Critic agent | Day 5 | `runValidationHandrail()` is a pure synchronous function with no LLM dependency. It checks the generated patch against a defined safety rubric and returns a structured `ValidationResult` with a per-flag audit trail. | `src/orchestrator.ts` |

---

## Security Layers

### Layer 1 -- API Key Pre-flight

Checked in the constructor before any object is instantiated. If `GEMINI_API_KEY` is absent or empty, the process throws immediately.

```typescript
const apiKey = process.env.GEMINI_API_KEY;
if (!apiKey || apiKey.trim() === "") {
  throw new Error(
    "[FATAL] GEMINI_API_KEY environment variable is not set."
  );
}
```

### Layer 2 -- Path Traversal Guard

Runs inside the MCP server before any file I/O. The resolved path must remain within `PROJECT_ROOT`. A trailing separator is appended before the prefix check to prevent sibling-directory collisions.

```typescript
const resolved = path.resolve(PROJECT_ROOT, rawPath);
const rootWithSep = PROJECT_ROOT + path.sep;
if (!resolved.startsWith(rootWithSep) && resolved !== PROJECT_ROOT) {
  throw new Error("Path traversal attempt detected.");
}
```

### Layer 3 -- Output Validation Handrail

Scans every LLM-generated patch with six regex categories. Any match fails the pipeline and returns a flagged `ValidationResult` without discarding the pipeline context.

| Category | Detects |
|---|---|
| `shell-exec` | `child_process`, `.exec()`, `.spawn()` |
| `eval-variant` | `eval()`, `new Function()`, `setTimeout("string")` |
| `filesystem-nuke` | `rm -rf`, `fs.unlinkSync`, `fs.rmdirSync` |
| `network-exfil` | `curl`, `wget`, external `fetch()` calls |
| `proto-pollution` | `__proto__`, `constructor.prototype` mutations |
| `env-exfiltration` | `process.env.*` variable piped into a network call |

Required logic anchors (patterns that must survive the patch, e.g. `addEventListener`) are checked separately. A missing anchor is treated as a validation failure.

---

## Installation and Local Execution

### Prerequisites

- Node.js 18 or later
- npm 9 or later
- A Gemini API key from [Google AI Studio](https://aistudio.google.com/apikey)

---

### Step 1 -- Clone

```bash
git clone https://github.com/your-username/vibe-audit.git
cd vibe-audit
```

### Step 2 -- Install dependencies

```bash
npm install
```

Installs:
- `@modelcontextprotocol/sdk` -- MCP server runtime
- `@google/generative-ai` -- Gemini API client
- `typescript`, `@types/node` -- TypeScript toolchain

### Step 3 -- Set the API key

```bash
# Linux / macOS
export GEMINI_API_KEY="your-key-here"

# Windows PowerShell
$env:GEMINI_API_KEY = "your-key-here"
```

For `.env` file support, install `dotenv` and add `import 'dotenv/config'` at the top of `src/orchestrator.ts`.

### Step 4 -- Build

```bash
npm run build
```

Compiles `src/` to `dist/`. The build has zero warnings under strict TypeScript settings.

### Step 5 -- Run the MCP server standalone

```bash
npm start
```

The server writes its startup message to stderr and then waits for JSON-RPC messages on stdin.

### Step 6 -- Run the orchestrator pipeline

```bash
# Against a leaky fixture
GEMINI_API_KEY="your-key" npx ts-node src/orchestrator.ts leaky.js

# Against a clean fixture
GEMINI_API_KEY="your-key" npx ts-node src/orchestrator.ts clean.js
```

### Step 7 -- Integrate with Claude Desktop

Add the following to your Claude Desktop config file:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "vibe-audit": {
      "command": "node",
      "args": ["/absolute/path/to/vibe-audit/dist/index.js"]
    }
  }
}
```

Restart Claude Desktop. The `analyze_dom_lifecycles` tool will appear in the tool list.

---

## Project Structure

```
vibe-audit/
├── src/
│   ├── index.ts          # MCP server -- analyze_dom_lifecycles tool
│   └── orchestrator.ts   # Multi-agent ADK pipeline
├── dist/                 # Compiled output (generated by tsc)
│   ├── index.js
│   └── orchestrator.js
├── leaky.js              # Test fixture: addEventListener with no cleanup
├── clean.js              # Test fixture: addEventListener with removeEventListener
├── package.json
├── tsconfig.json
└── README.md
```

---

## Sample Pipeline Output

Run against `leaky.js`:

```
[Orchestrator] Initialized. Environment pre-flight: PASSED

[Auditor Agent] Invoking MCP tool: analyze_dom_lifecycles
[Auditor Agent] Diagnostic: CRITICAL: Memory leak vector detected -- addEventListener
                is used but no cleanup was found.

[Router] Requires patch: YES -- handing off to Patching Agent

[Patching Agent] Constructing structured repair prompt
[Patching Agent] Prompt built. Invoking Gemini LLM
[Patching Agent] LLM response received.

[Validation] Running safety scan on LLM-generated patch
[Validation] VALIDATION PASSED: Patch is clean. No dangerous patterns.
             All core logic anchors preserved.
```

---

## Demonstration Video

A walkthrough video showing Vibe-Audit deployed end-to-end using the Antigravity IDE is in production. The video will cover:

- Starting the MCP server and orchestrator from a cold clone using Antigravity agentic scaffolding
- Live pipeline execution with Auditor, Patcher, and Validator log output
- Claude Desktop MCP tool integration auditing a real React component

Link will be added here when published.

---

## Roadmap

- [ ] Replace mock MCP adapter with a live `@modelcontextprotocol/sdk` `Client` session
- [ ] Add `dotenv` support
- [ ] Expand diagnostic patterns: Vue 3 `onUnmounted`, Svelte `onDestroy`, RxJS `unsubscribe`
- [ ] GitHub Actions CI with fixture-based tests
- [ ] Docker image for isolated server deployment
- [ ] Web UI for pipeline run history and diff view

---

## License

MIT 2026 -- built during the [Kaggle 5-Day Gen AI Intensive](https://www.kaggle.com/learn-guide/5-day-genai).


## TANUSH Bhootra ✨