npm - @lovenyberg/ove - Versions diffs - 0.3.0 → 0.4.0 - Mend

@lovenyberg/ove 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

package/.claude/skills/create-issue/SKILL.md +24 -0
package/.claude/skills/review-pr/SKILL.md +37 -0
package/.claude/skills/ship/SKILL.md +22 -0
package/.env.example +5 -0
package/CLAUDE.md +20 -0
package/README.md +93 -17
package/docs/examples.md +11 -52
package/docs/index.html +40 -2
package/docs/plans/2026-02-23-conversation-repo-memory.md +272 -0
package/package.json +1 -1
package/public/favicon.ico +0 -0
package/public/index.html +424 -36
package/public/logo.png +0 -0
package/public/status.html +519 -0
package/public/trace.html +973 -0
package/src/adapters/cli.ts +16 -1
package/src/adapters/debounce.test.ts +57 -0
package/src/adapters/debounce.ts +36 -4
package/src/adapters/discord.ts +17 -2
package/src/adapters/github.ts +26 -1
package/src/adapters/http.test.ts +7 -1
package/src/adapters/http.ts +220 -48
package/src/adapters/slack.ts +17 -2
package/src/adapters/telegram.ts +21 -9
package/src/adapters/types.ts +11 -0
package/src/adapters/whatsapp.ts +40 -2
package/src/flows.test.ts +126 -0
package/src/handlers.ts +76 -17
package/src/index.ts +35 -2
package/src/queue.ts +22 -0
package/src/router.ts +8 -2
package/src/runners/claude.ts +24 -5
package/src/runners/codex.ts +20 -1
package/src/trace.ts +71 -0
package/src/worker.ts +68 -6

package/.claude/skills/create-issue/SKILL.md ADDED Viewed

@@ -0,0 +1,24 @@
+---
+name: create-issue
+description: Create a well-structured GitHub issue with labels and acceptance criteria
+disable-model-invocation: true
+argument-hint: "[repo] [title]"
+allowed-tools: Bash(gh *)
+---
+Create a GitHub issue on the specified repo.
+Usage: `/create-issue owner/repo Title of the issue`
+If only a title is given without a repo, use the current repository.
+## Steps
+1. Parse $ARGUMENTS into repo and title
+2. Ask clarifying questions if the request is vague
+3. Draft the issue body with:
+   - **Description**: What and why
+   - **Acceptance criteria**: Checkboxes for done conditions
+   - **Technical notes**: Relevant files, patterns, constraints
+4. Create with: `gh issue create --repo <repo> --title "<title>" --body "<body>"`
+5. Return the issue URL

package/.claude/skills/review-pr/SKILL.md ADDED Viewed

@@ -0,0 +1,37 @@
+---
+name: review-pr
+description: Review a pull request with critical analysis and refactoring suggestions
+disable-model-invocation: true
+argument-hint: "[PR number or URL]"
+allowed-tools: Bash(gh *), Read, Grep, Glob
+---
+Review the pull request specified by $ARGUMENTS.
+## Steps
+1. Fetch PR details: `gh pr view $ARGUMENTS --json title,body,additions,deletions,changedFiles,baseRefName,headRefName`
+2. Fetch the diff: `gh pr diff $ARGUMENTS`
+3. Read changed files in full for context
+4. Analyze the changes for:
+   - Correctness: bugs, edge cases, off-by-one errors
+   - Security: injection, auth issues, secrets in code
+   - Performance: N+1 queries, unnecessary allocations, missing indexes
+   - Style: matches project conventions (see CLAUDE.md)
+   - Tests: adequate coverage for new/changed behavior
+## Output format
+Provide a structured review:
+### Summary
+One paragraph on what the PR does.
+### Issues
+List any problems found, with file:line references.
+### Suggestions
+Optional improvements that aren't blocking.
+### Verdict
+APPROVE, REQUEST_CHANGES, or COMMENT with reasoning.

package/.claude/skills/ship/SKILL.md ADDED Viewed

@@ -0,0 +1,22 @@
+---
+name: ship
+description: Create branch, commit changes, push, and open a PR
+disable-model-invocation: true
+argument-hint: "[description of changes]"
+allowed-tools: Bash(git *), Bash(gh *)
+---
+Ship the current changes as a pull request.
+## Steps
+1. Run `git status` and `git diff --stat` to understand what changed
+2. Create a descriptive branch name from the changes (e.g. `fix/sse-timeout`, `feat/sidebar-history`)
+3. Stage relevant files (avoid secrets, lock files, local config)
+4. Commit with a conventional commit message (feat/fix/refactor/docs/chore)
+5. Push the branch with `git push -u origin <branch>`
+6. Create a PR with `gh pr create` including:
+   - Short title (under 70 chars)
+   - Summary section with bullet points
+   - Test plan section
+7. Return the PR URL

package/.env.example CHANGED Viewed

@@ -4,6 +4,8 @@ SLACK_APP_TOKEN=xapp-...
 # WhatsApp
 WHATSAPP_ENABLED=false
+# WHATSAPP_PHONE=46701234567
+# WHATSAPP_ALLOWED_CHATS=46701234567,120363xxx@g.us
 # Telegram
 # TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
@@ -23,6 +25,9 @@ WHATSAPP_ENABLED=false
 # CLI mode (auto-enabled when no other adapters configured)
 # CLI_MODE=true
+# Task tracing (stores per-task event timeline in SQLite)
+# OVE_TRACE=true
 # Repos directory
 REPOS_DIR=./repos

package/CLAUDE.md CHANGED Viewed

@@ -27,3 +27,23 @@ Your grumpy but meticulous dev companion — routes chat messages to AI coding a
 - Use bun:sqlite directly, no ORMs
 - Use bun:test for testing
 - Structured JSON logging via src/logger.ts
+## Skills
+Ove spawns Claude Code CLI (`claude -p`) in isolated worktrees. The spawned instances automatically pick up:
+- **Project skills** from `.claude/skills/` in the target repo's worktree
+- **Personal skills** from `~/.claude/skills/` on the host machine
+- **Plugin skills** from installed plugins (configured via `~/.claude/settings.json` `enabledPlugins`)
+Skills follow the [Agent Skills](https://agentskills.io) open standard. See [Claude Code skills docs](https://code.claude.com/docs/en/skills) for full reference.
+### Setting up skills for Ove
+Skills are configured **manually** in the Claude Code installation that Ove runs on:
+1. **Personal skills** — place in `~/.claude/skills/<name>/SKILL.md` on the host running Ove
+2. **Per-repo skills** — commit `.claude/skills/<name>/SKILL.md` to each repo Ove manages
+3. **Plugins** — install via `claude plugins add` and enable in `~/.claude/settings.json`
+The Ove project itself ships skills in `.claude/skills/` (review-pr, create-issue, ship) that are available when working on the Ove codebase.

package/README.md CHANGED Viewed

@@ -41,7 +41,7 @@ Talk to Ove the way you'd talk to a teammate. These all work:
 "refactor the user service, it's getting messy"
 ```
-Ove figures out the intent, picks the right repo, and gets to work. For common tasks, there are also shorthand commands:
+Ove figures out the intent, picks the right repo, and gets to work. See [more examples](docs/examples.md). For common tasks, there are also shorthand commands:
 ```
 review PR #N on <repo>      Code review with inline comments
@@ -130,8 +130,9 @@ sudo systemctl enable --now ove
 ### HTTP API + Web UI
 1. Set `HTTP_API_PORT=3000` and `HTTP_API_KEY=<your-secret>` in `.env`
-2. Open `http://localhost:3000` for the Web UI
-3. Or call the API directly: `curl -X POST http://localhost:3000/api/message -H "X-API-Key: <key>" -H "Content-Type: application/json" -d '{"text": "validate my-app"}'`
+2. Open `http://localhost:3000` for the chat UI
+3. Open `http://localhost:3000/trace` for the trace viewer (see [Web Pages](#web-pages) below)
+4. Or call the API directly: `curl -X POST http://localhost:3000/api/message -H "X-API-Key: <key>" -H "Content-Type: application/json" -d '{"text": "validate my-app"}'`
 ### GitHub (issue/PR comments)
@@ -142,8 +143,9 @@ sudo systemctl enable --now ove
 ### WhatsApp
-1. Set `WHATSAPP_ENABLED=true` in `.env`
-2. Scan the QR code printed in the terminal on first start
+1. Set `WHATSAPP_ENABLED=true` and `WHATSAPP_PHONE=<your-number>` in `.env`
+2. Start Ove and enter the pairing code on your phone (WhatsApp → Linked Devices → Link a Device)
+3. Set `WHATSAPP_ALLOWED_CHATS=<phone1>,<phone2>` to limit which chats Ove listens to. Without this, Ove responds to **all** your outgoing messages in every chat. Use phone numbers (e.g. `46701234567`) for individual chats or full JIDs (e.g. `120363xxx@g.us`) for groups.
 ## Config
@@ -195,25 +197,99 @@ Per-repo `runner` overrides the global default. Supported runners: `"claude"` (d
 Static cron jobs go in `config.json`. Users can also create schedules via chat — these are stored in SQLite and managed with `list schedules` / `remove schedule #N`.
+## Web Pages
+The HTTP adapter serves two pages (no auth required to load — API key is entered in-browser and stored in `localStorage`):
+| Route | Page | Description |
+|-------|------|-------------|
+| `/` | Chat UI | Send messages to Ove, see streaming status updates and results |
+| `/trace` | Trace Viewer | Browse tasks and inspect per-task trace timelines |
+| `/status` | Status | Adapter health, connection state, queue stats, WhatsApp pairing code |
+### Trace Viewer (`/trace`)
+A debugging dashboard for inspecting what happened during task execution.
+- **Left panel** — Task list with status badges, repo name, prompt preview, and relative timestamps. Filterable by repo, user, and status.
+- **Right panel** — When a task is selected, shows:
+  - **Context card** — Full prompt, user, repo, status, created/done timestamps, and total duration.
+  - **Trace timeline** — Chronological events with color-coded kinds: lifecycle (green), tool (blue), status (gray), output (white), error (red). Each event with detail data can be expanded individually.
+- **Toolbar** — "show all details" expands every trace event at once, "copy json" copies the full task + trace data as JSON for troubleshooting.
+- **Auto-refresh** — Toggle to poll every 3 seconds, useful for watching running tasks.
+### Tracing
+Tracing records per-task event timelines in SQLite. Enable it with:
+```bash
+OVE_TRACE=true
+```
+Trace events are also accessible via chat (`trace <task-id>`) and the API:
+```bash
+# List recent tasks
+curl http://localhost:3000/api/tasks?key=<key>&limit=20&status=completed
+# Get trace for a specific task
+curl http://localhost:3000/api/trace/<task-id>?key=<key>
+```
+## Skills
+Ove spawns Claude Code CLI (`claude -p`) in isolated worktrees. The spawned instances automatically pick up [skills](https://code.claude.com/docs/en/skills) — reusable instruction sets that follow the [Agent Skills](https://agentskills.io) open standard.
+Skills are configured **manually** on the host machine running Ove:
+| Level | Path | Scope |
+|-------|------|-------|
+| Personal | `~/.claude/skills/<name>/SKILL.md` | All repos on this machine |
+| Per-repo | `.claude/skills/<name>/SKILL.md` (committed to repo) | That repo only |
+| Plugins | Installed via `claude plugins add` | Where enabled |
+When Ove runs a task in a worktree, Claude Code picks up personal skills from `~/.claude/skills/`, project skills from the repo's `.claude/skills/`, and any enabled plugins. This means you can give the Claude instances domain-specific knowledge, coding conventions, deployment workflows, or review checklists — just by dropping a `SKILL.md` in the right place.
+Example: adding a review skill to a repo so Ove knows your team's review standards:
+```
+my-repo/.claude/skills/review/SKILL.md
+```
+```yaml
+---
+name: review
+description: Review code using our team standards
+---
+When reviewing code, check for:
+1. Error handling covers all failure modes
+2. Tests cover the happy path and at least one edge case
+3. No secrets or credentials in code
+```
+See the [Claude Code skills docs](https://code.claude.com/docs/en/skills) for the full reference on frontmatter options, argument passing, subagent execution, and more.
 ## Testing
 ```bash
-bun test    # 150 tests
+bun test    # 224 tests
 ```
-## How It Works
+## Security
+Ove executes arbitrary code on your machine via Claude Code CLI. Treat it accordingly.
+**Never expose Ove to the public internet.** The HTTP API and Web UI are designed for local or private network use only. There is no rate limiting, no session management, and the API key is a single shared secret. Putting this behind a public URL is asking for trouble.
-1. Message arrives via any transport (Slack, WhatsApp, Telegram, Discord, CLI, HTTP API, or GitHub comment)
-2. Chat adapters use `handleMessage`, event adapters use `handleEvent`
-3. Router parses intent and extracts repo/args
-4. Task gets queued in SQLite (one per repo at a time, different repos run in parallel)
-5. Worker loop picks up tasks concurrently (up to 5 parallel tasks across different repos)
-6. Each task gets an isolated git worktree
-7. Runs the configured agent runner (`claude -p` or `codex exec`) with streaming JSON output
-8. Status updates stream back (chat: edits a message, HTTP: SSE, GitHub: single comment)
-9. Result sent back, worktree cleaned up
+- **Run on localhost or a private network.** If you need remote access, put it behind a VPN or SSH tunnel — not a reverse proxy with a public domain.
+- **Keep your API key secret.** It grants full access to submit tasks, read chat history, and view adapter status (including WhatsApp pairing codes). Rotate it if compromised.
+- **Ove runs code as your user.** Whatever permissions your shell user has, Ove's spawned agents have too — SSH keys, git credentials, cloud CLI sessions, everything. Run it under a dedicated user with minimal permissions where possible.
+- **Audit your config.** The `users` map controls who can submit tasks. Don't add wildcard entries. Lock repos to specific users.
+- **WhatsApp pairing codes are sensitive.** They appear on the `/status` page (behind API key auth) and in server logs. Anyone with the code can link a device to your WhatsApp account.
+- **Docker helps.** Running in Docker limits blast radius. The container only mounts what you give it.
-See [example conversations](docs/examples.md) for all flows.
+This is a power tool for developers, not a hosted service. You are responsible for securing your deployment.
 ## License

package/docs/examples.md CHANGED Viewed

@@ -9,10 +9,7 @@ You don't need commands. Just describe what you need, like you'd tell a colleagu
 **Slack DM:**
 ```
 alice: the login page is broken, users get a 500 after submitting the form
-ove:   Task queued (aaa11111). Working on it...
-       > Grep: "login" in src/
-       > Read: src/routes/auth.ts
-       > Read: src/middleware/session.ts
+ove:   Working on it...
 ove:   Found the issue — the session middleware wasn't awaiting the
        database call on line 34 of src/middleware/session.ts. Created
        PR #47 with the fix and added a test:
@@ -22,11 +19,7 @@ ove:   Found the issue — the session middleware wasn't awaiting the
 **Telegram:**
 ```
 alice: can you add input validation to the user registration endpoint in my-app?
-ove:   Task queued (bbb22222). Working on it...
-       > Read: src/routes/users.ts
-       > Edit: src/routes/users.ts
-       > Write: src/routes/users.test.ts
-       > Bash: bun test
+ove:   Working on it...
 ove:   Done. Added zod validation for email, password length, and
        username format. All 48 tests pass. PR #48:
        https://github.com/org/my-app/pull/48
@@ -37,10 +30,6 @@ ove:   Done. Added zod validation for email, password length, and
 alice: how does the caching layer work in my-app? I need to understand
        it before I make changes
 ove:   Looking into it...
-       > Glob: **/*cache*
-       > Read: src/cache/redis.ts
-       > Read: src/cache/keys.ts
-       > Read: src/middleware/cache.ts
 ove:   The caching layer has 3 parts:
        1. src/cache/redis.ts — Redis client wrapper with connection pooling
        2. src/cache/keys.ts — key generation with TTL per resource type
@@ -55,10 +44,7 @@ ove:   The caching layer has 3 parts:
 **Slack DM:**
 ```
 alice: review PR #42 on my-app
-ove:   Task queued (abc12345). Working on it...
-       > Bash: gh pr diff 42
-       > Read: src/auth.ts
-       > Read: src/middleware.ts
+ove:   Working on it...
 ove:   PR #42 review done. Left 3 inline comments:
        - src/auth.ts:15 — potential SQL injection in query param
        - src/middleware.ts:42 — missing error handler for async route
@@ -76,14 +62,7 @@ Ove replies with a comment containing the review summary.
 **Telegram:**
 ```
 alice: fix issue #15 on my-app
-ove:   Task queued (bbb22222). Working on it...
-       > Bash: gh issue view 15
-       > Grep: "handleAuth"
-       > Read: src/auth.ts
-       > Edit: src/auth.ts
-       > Bash: bun test
-       > Bash: git add -A && git commit -m "Fix auth token expiry check"
-       > Bash: gh pr create --title "Fix #15: auth token expiry"
+ove:   Working on it...
 ove:   Fixed! Created PR #43:
        https://github.com/org/my-app/pull/43
        Changed src/auth.ts to properly check token expiry timestamps.
@@ -94,10 +73,7 @@ ove:   Fixed! Created PR #43:
 **Discord:**
 ```
 alice: validate my-app
-ove:   Task queued (ccc33333). Working on it...
-       > Bash: bun test
-       > Read: package.json
-       > Bash: bunx eslint src/
+ove:   Working on it...
 ove:   All 42 tests pass. ESLint found 3 warnings:
        • src/utils.ts:12 — unused variable 'tmp'
        • src/api.ts:45 — prefer const
@@ -108,11 +84,7 @@ ove:   All 42 tests pass. ESLint found 3 warnings:
 ```
 alice: simplify src/router.ts in my-app
-ove:   Task queued (ddd44444). Working on it...
-       > Read: src/router.ts
-       > Edit: src/router.ts
-       > Bash: bun test
-       > Bash: gh pr create --title "Simplify src/router.ts"
+ove:   Working on it...
 ove:   Created PR #44. Reduced cyclomatic complexity from 18 to 9.
        Extracted 3 helper functions, removed duplicated regex logic.
 ```
@@ -142,12 +114,7 @@ ove:   Let's think about this. Key questions:
 ```
 alice: create project my-api with template express
-ove:   Task queued (eee55555). Working on it...
-       > Bash: mkdir -p my-api && cd my-api && npm init -y
-       > Write: src/index.ts
-       > Bash: npm install express
-       > Bash: git init && git add -A && git commit -m "Initial commit"
-       > Bash: gh repo create my-api --public --push
+ove:   Working on it...
 ove:   Project "my-api" created and pushed to GitHub:
        https://github.com/org/my-api
        Structure: Express + TypeScript, src/index.ts entry point
@@ -182,9 +149,6 @@ Anything you type works. Ove parses intent from natural language.
 ```
 alice: what does the auth middleware do in my-app
-ove:   Task queued (fff66666). Working on it...
-       > Glob: **/*middleware*
-       > Read: src/middleware/auth.ts
 ove:   The auth middleware in my-app:
        1. Extracts JWT from Authorization header
        2. Verifies signature against JWKS endpoint
@@ -195,10 +159,7 @@ ove:   The auth middleware in my-app:
 ```
 alice: the CI is red on main, can you check what's going on?
-ove:   Task queued (ggg77777). Working on it...
-       > Bash: gh run list --limit 5
-       > Bash: gh run view 12345 --log-failed
-       > Read: src/api.test.ts
+ove:   Looking into it...
 ove:   The test "should return 404 for unknown routes" is failing
        because the new /health endpoint was added without updating
        the route count assertion. Line 89 in src/api.test.ts expects
@@ -217,12 +178,10 @@ curl -X POST http://localhost:3000/api/message \
 **Stream results via SSE:**
 ```bash
-curl -N http://localhost:3000/api/tasks/abc12345/stream \
-  -H "X-API-Key: your-secret"
+curl -N "http://localhost:3000/api/message/<eventId>/stream?key=your-secret"
-data: {"type":"status","message":"Running tests..."}
-data: {"type":"status","message":"All 42 tests pass."}
-data: {"type":"done","result":"Validation complete. No issues."}
+data: {"status":"pending","statusText":"Running tests..."}
+data: {"status":"completed","result":"Validation complete. No issues."}
 ```
 **Web UI:** Open `http://localhost:3000` in a browser for a chat-style interface.

package/docs/index.html CHANGED Viewed

@@ -807,6 +807,43 @@ sudo systemctl enable --now ove</pre>
     </ol>
   </section>
+  <section class="section" id="skills">
+    <h2>Skills</h2>
+    <p class="section-note">Teach Ove's Claude instances your conventions. Manually.</p>
+    <p>Ove spawns <a href="https://code.claude.com/docs/en/skills">Claude Code CLI</a> in isolated worktrees. The spawned instances automatically pick up <strong>skills</strong> &mdash; reusable instruction sets that follow the <a href="https://agentskills.io">Agent Skills</a> open standard.</p>
+    <p>Skills are configured <strong>manually</strong> on the host machine running Ove:</p>
+    <dl class="cmd-grid">
+      <dt>~/.claude/skills/</dt>
+      <dd>Personal skills &mdash; available across all repos on this machine</dd>
+      <dt>.claude/skills/</dt>
+      <dd>Per-repo skills &mdash; committed to each repo Ove manages</dd>
+      <dt>Plugins</dt>
+      <dd>Installed via <code>claude plugins add</code> &mdash; available where enabled</dd>
+    </dl>
+    <p>When Ove runs a task, Claude Code picks up all three levels. Drop a <code>SKILL.md</code> with domain knowledge, coding conventions, review checklists, or deployment workflows &mdash; and every task on that repo benefits.</p>
+<pre data-label="example: .claude/skills/review/SKILL.md">---
+name: review
+description: Review code using our team standards
+---
+When reviewing code, check for:
+1. Error handling covers all failure modes
+2. Tests cover the happy path and at least one edge case
+3. No secrets or credentials in code</pre>
+    <p>See the <a href="https://code.claude.com/docs/en/skills">Claude Code skills docs</a> for frontmatter options, argument passing, subagent execution, and more.</p>
+    <div class="ove-says">
+      "Skills are just instructions in a file. Not magic. But they work."
+      <span class="attr">&mdash; Ove</span>
+    </div>
+  </section>
   <section class="section" id="transports">
     <h2>Transport Setup</h2>
     <p class="section-note">Enable what you need. Ove doesn't judge. Much.</p>
@@ -855,8 +892,9 @@ sudo systemctl enable --now ove</pre>
     <h3>WhatsApp</h3>
     <ol class="steps">
-      <li>Set <code>WHATSAPP_ENABLED=true</code> in <code>.env</code></li>
-      <li>Scan the QR code printed in the terminal on first start</li>
+      <li>Set <code>WHATSAPP_ENABLED=true</code> and <code>WHATSAPP_PHONE=&lt;your-number&gt;</code> in <code>.env</code></li>
+      <li>Start Ove and enter the pairing code on your phone (WhatsApp &rarr; Linked Devices &rarr; Link a Device)</li>
+      <li>Set <code>WHATSAPP_ALLOWED_CHATS=&lt;phone1&gt;,&lt;phone2&gt;</code> to limit which chats Ove listens to. Without this, Ove responds to <strong>all</strong> your outgoing messages in every chat. Use phone numbers (e.g. <code>46701234567</code>) for individual chats or full JIDs (e.g. <code>120363xxx@g.us</code>) for groups.</li>
     </ol>
   </section>