---
name: plugin-git-install-committed-artifact
description: "Use when shipping an omp/pi plugin for omp plugin install git: — the installer clone fails validation (missing build artifact) or silently reuses a stale bun git-mirror cache; recipes for committing dist + drift pins + cache purge."
---

# Plugin install from git: committed artifact + fresh mirror

`omp plugin install git:<url>` (and `pi install git:`) **clone the repo and validate the manifest's declared extension entry WITHOUT running a build step**. Two failure classes seen live (dank/dankvoice, 2026-10-19):

## 1. Declared entry missing from the clone

Symptom: `Plugin <name> extension validation failed: ./dist/index.js: declared extension entry not found on disk`.

Cause: build output (`dist/`) is gitignored; the manifest points at it; the clone has only `src/`.

Fix — ship the artifact:
- Remove `dist/` from `.gitignore`, `bun run build`, commit `dist/`.
- Prove build determinism first: build twice, `cmp` the outputs (bun esm builds are byte-reproducible without sourcemaps).
- Pin the contract in a small bats suite so it can't rot:
  1. the manifest's declared entry is tracked in git (`git ls-files -- "${entry#./}"` non-empty — this is the installer's exact contract, not a config assertion);
  2. committed bytes equal a fresh build (`bun run build` then `git diff --name-only -- dist` is empty → red on drift).

## 2. Stale bun git-mirror cache

Symptom: fix pushed, retry **still** fails identically, and the retry is suspiciously fast (seconds).

Cause: bun keeps bare mirrors in `~/.bun/install/cache/<hash>.git` and may reuse them at an old commit — even after the fix is pushed and the default branch is correct.

Diagnose + fix:
```bash
find ~/.bun/install/cache -maxdepth 2 -iname "*<repo>*"
git --git-dir ~/.bun/install/cache/<hash>.git log --oneline -3 --all   # stale HEAD?
rm -rf ~/.bun/install/cache/<hash>.git                                  # it is a cache; safe
```
Prove the fetch path independently first (also validates credentials for private Gitea repos):
```bash
GIT_TERMINAL_PROMPT=0 git clone -q <url> /tmp/x && git -C /tmp/x log --oneline -1 && ls /tmp/x/dist
```

## Order of investigation (don't skip)
1. Gitea default branch correct? (`GET /api/v1/repos/<o>/<r>` with token — private repos 404/None unauthenticated.)
2. Plain unattended clone contains the entry? If yes, the installer's view is cached → purge mirror.
3. Only then suspect the installer itself (validation code lives in the minified bundle; `grep -oE '.{600}<error string>' "$bunfile"` on `readlink -f $(which omp)` shows the exact check).

## After install — proof without a TUI
- `omp plugin doctor` → per-plugin ✔ line.
- Audible/behavioral chain when TUI input is unusable (update-banner modal freezes pty submits): run `omp --mode=rpc --no-session` with the feature env armed (dankvoice: `DANKVOICE_AUTO=1`, gate is print/json-only) and watch for objective side effects, e.g. PipeWire: `pw-dump | grep -q "say-<ms>.wav"` proves synth+playback end-to-end.