npm package: @openverb/pulse
Description: AI-friendly project log that auto-updates with builds, tests, and errors
Author: OpenVerb
Latest version: 0.3.6

# @openverb/pulse

AI-friendly project log that automatically updates with builds, tests, and errors.

## Features

- 📝 **Auto-logging**: Wrap any command to automatically log results
- 🚀 **Runtime Error Capture**: Automatically capture errors from dev servers
- 🧠 **Project Brain**: Machine-readable `openverb-pulse.json` for AI tools
- 🔍 **Codebase Analysis**: Automatically analyzes your project to extract:
  - Real tech stack from `package.json`
  - Features from route structure
  - Project purpose from main entry point
  - Intent and vision from codebase
- ✅ **Task Extraction**: High-severity errors automatically become actionable tasks
- 🌐 **Browser viewable**: HTML files work in editors and browsers
- 🤖 **AI-ready**: Structured JSON embedded for easy parsing
- 🔗 **OpenVerb integration**: Optional link to sync with OpenVerb cloud

## Installation

```bash
npm install -D @openverb/pulse
```

## Quick Start

### 1. Initialize

```bash
npx ov-pulse init --name "My Project"
```

This creates `.ov-pulse.json` and `.ai/openverb-pulse.html`

### 2. Wrap Commands

```bash
# Instead of: npm run build
npx ov-pulse exec -- npm run build

# Instead of: pnpm test
npx ov-pulse exec -- pnpm test
```

### 3. Capture Runtime Errors

```bash
# Start dev server with error capture
npx ov-pulse dev -- next dev
# or
npx ov-pulse dev -- vite
```

Automatically captures React errors, route failures, console errors, and more.

### 4. View Log

```bash
# View permanent project brain
npx ov-pulse view

# View current session errors
npx ov-pulse view --session
```

Opens `.ai/openverb-pulse.html` in your browser.

## Usage

### Dev Server Proxy (Runtime Error Capture)

Capture runtime errors from your dev server:

```bash
npx ov-pulse dev -- next dev
npx ov-pulse dev -- vite
npx ov-pulse dev -- npm run dev
```

**What gets captured:**
- React hydration errors
- Route/page errors
- Console errors and warnings
- Network/API errors
- Compilation errors
- Unhandled exceptions

Errors are automatically recorded to `openverb-pulse.json` and session errors.

**Note:** Only actual errors (4xx/5xx status codes) are captured. Successful requests (200) are ignored.

### Exec Command

Execute any command and automatically log the result:

```bash
ov-pulse exec -- <your-command>
```

Examples:
```bash
ov-pulse exec -- next build
ov-pulse exec -- pnpm test
ov-pulse exec -- vercel --prod
```

### Snapshot Command

Create a snapshot of current project state:

```bash
npx ov-pulse snapshot
```

Captures:
- Git branch and commit
- Project structure (entrypoints, routes)
- Build/runtime status
- Updates `openverb-pulse.json`

### Dev Command

Start dev server with runtime error capture:

```bash
npx ov-pulse dev -- <command>
```

See [Dev Server Proxy](#dev-server-proxy-runtime-error-capture) above for details.

### Enrich Command (Coming Soon)

Enrich `openverb-pulse.json` with AI analysis:

```bash
npx ov-pulse enrich
```

This will use a local LLM to add:
- Diagnosis hypotheses
- Proposed fixes
- Impact severity
- Task grouping

### View Command

Open the pulse log in your browser:

```bash
ov-pulse view
ov-pulse view --session  # View session errors
```

### Generate Command

Regenerate the HTML and JSON files:

```bash
ov-pulse generate
```

## Output Files

### openverb-pulse.json

Machine-readable project brain in JSON format:

```json
{
  "schema_version": "1.0.0",
  "project": { ... },
  "snapshot": { ... },
  "events": [ ... ],
  "open_tasks": [ ... ],
  "notes": [ ... ]
}
```

This file can be consumed by AI tools (ChatGPT, Claude, Cursor, etc.) to understand your project without manual explanation.

**Location:** `.ai/openverb-pulse.json`

### openverb-pulse.html

Human-readable project brain with visual timeline.

**Location:** `.ai/openverb-pulse.html`

### session-errors.json & session-errors.html

Ephemeral errors from current development session.

**Location:** `.ai/session-errors.json` and `.ai/session-errors.html`

## Integration with package.json

Add scripts to your `package.json`:

```json
{
  "scripts": {
    "dev": "ov-pulse dev -- next dev",
    "build": "ov-pulse exec -- next build",
    "test": "ov-pulse exec -- pnpm vitest",
    "deploy": "ov-pulse exec -- vercel --prod",
    "pulse:view": "ov-pulse view",
    "pulse:snapshot": "ov-pulse snapshot"
  }
}
```

## Configuration

Edit `.ov-pulse.json`:

```json
{
  "projectName": "My Project",
  "projectId": "optional-project-id",
  "visualMode": "none",
  "sync": {
    "enabled": false,
    "endpoint": null,
    "apiKeyEnv": null
  },
  "outputFile": ".ai/openverb-pulse.html"
}
```

## How It Works

1. **Command Execution**: `ov-pulse exec` runs your command and captures output
2. **Runtime Capture**: `ov-pulse dev` proxies your dev server and captures runtime errors
3. **Event Logging**: Results are saved to `.ai/openverb-pulse.json` and session errors
4. **HTML Generation**: `.ai/openverb-pulse.html` is generated with:
   - Human-readable event list
   - Embedded JSON for AI/tool parsing
   - "Continue in OpenVerb" link

## AI Integration

### For ChatGPT/Claude (browser)

1. Run `ov-pulse view` to open the log
2. Copy relevant event snippets or the entire `openverb-pulse.json`
3. Paste into chat

### For Cursor/VS Code AI

The AI can read `.ai/openverb-pulse.json` or `.ai/openverb-pulse.html` directly as files in your repo.

### For AI with Browsing

Use the "Continue in OpenVerb" link to view logs on the web, then share the URL.

## File Structure

```
.ai/
  ├── openverb-pulse.json     # Machine-readable project brain (unified format)
  ├── openverb-pulse.html     # Browser-viewable log
  ├── session-errors.json     # Ephemeral errors
  └── session-errors.html     # Session errors viewer
.ov-pulse.json                 # Configuration
```

## License

MIT