> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibelearn.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Development

> Build from source and contribute to VibeLearn

## Prerequisites

* **Bun** — worker runtime and build tool
* **Node.js** 18+ — for npm tooling
* **Git**

## Build from Source

```bash theme={null}
git clone https://github.com/anergcorp/vibelearn.git
cd vibelearn
npm install
npm run build-and-sync
```

`build-and-sync` runs `scripts/build-hooks.js` (via Bun) which:

1. Compiles TypeScript hooks → ESM scripts → bundles with esbuild
2. Bundles `worker-service.cjs` (\~1.7MB)
3. Bundles `vl-cli.cjs` (\~10KB)
4. Syncs built artifacts to `~/.claude/plugins/marketplaces/vibelearn/`
5. Restarts the worker

## Build Artifacts

| Output                              | Source                           | Purpose             |
| ----------------------------------- | -------------------------------- | ------------------- |
| `plugin/scripts/*-hook.js`          | `src/hooks/*.ts`                 | Hook scripts        |
| `plugin/scripts/worker-service.cjs` | `src/services/worker-service.ts` | Worker bundle       |
| `plugin/scripts/vl-cli.cjs`         | `src/cli/vl/index.ts`            | `vl` CLI bundle     |
| `plugin/scripts/worker-wrapper.cjs` | pre-built                        | Bun process manager |

## Development Workflow

```bash theme={null}
# Make changes to src/

# Rebuild hooks only (fast)
bun scripts/build-hooks.js

# Full build + restart worker
npm run build-and-sync

# Watch worker logs
tail -f ~/.vibelearn/logs/vibelearn-$(date +%Y-%m-%d).log
```

## Adding a New Analysis Step

1. Create `src/services/analysis/MyAnalyzer.ts`
2. Add a new route in `src/services/worker/http/routes/VibeLearnRoutes.ts`
3. Call it from `src/hooks/summarize.ts` (the Stop hook dispatcher)
4. Add any new columns to `src/services/sqlite/migrations.ts` (increment migration ID)

## Adding a New vl CLI Command

Edit `src/cli/vl/index.ts`. The CLI uses `bun:sqlite` directly — no HTTP to worker.

```typescript theme={null}
async function cmdMyCommand() {
  const db = new Database(`${homedir()}/.vibelearn/vibelearn.db`);
  const rows = db.query('SELECT * FROM vl_concepts LIMIT 10').all();
  // ...
}
```

## Database Migrations

Add migrations to the array in `src/services/sqlite/migrations.ts`:

```typescript theme={null}
{ id: 9, sql: `ALTER TABLE vl_concepts ADD COLUMN my_new_column TEXT` }
```

Migrations run automatically on worker startup. Never modify existing migration IDs.

## Code Style

* TypeScript strict mode
* ESM modules throughout (`import`/`export`, no `require`)
* Hooks: always exit 0 (never block the IDE)
* Worker errors: log at ERROR level, continue execution
* Analysis steps: independent — step failure must not block subsequent steps

## Testing

VibeLearn uses real-world testing: install the plugin, run coding sessions, check `vl quiz`. The analysis pipeline is LLM-dependent and not meaningfully unit-testable.

For worker endpoint testing:

```bash theme={null}
# Test session init
curl -X POST http://127.0.0.1:37778/api/sessions/init \
  -H "Content-Type: application/json" \
  -d '{"contentSessionId":"test-123","project":"test","prompt":"test"}'

# Test health
curl http://127.0.0.1:37778/api/health | jq .
```

## Publishing

```bash theme={null}
npm run build-and-sync
# Artifacts in plugin/ are ready to publish to the marketplace
```

Plugin identity: `vibelearn@anergcorp`