command-center/agent/managed-skills/plugin-git-install-committed-artifact/SKILL.md

name, description

name	description
plugin-git-install-committed-artifact	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:

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):

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.