david/pi-extensions-and-skills

Watch

Fork 0

Add npm run local:install script to update and install all skills and extensions #41

New issue

Closed

opened 2026-08-18 12:54:27 +00:00 by david · 2 comments

david commented

2026-08-18 12:54:27 +00:00

Owner

Summary
Add an explicit npm script, npm run local:install, that updates and installs all skills and extensions in this package in one command, from any git checkout of this repo (dev machine or fresh clone elsewhere). It must fail fast on any problem and tell the user exactly what is missing and how to fix it.

Background

Root package.json has a pi manifest declaring 3 extensions (extensions/rg/index.ts, extensions/postgres/index.ts, extensions/pr-comments/src/index.ts) + ./skills (12 markdown-only skills), and no scripts section.
README documents two manual flows: other machines -> pi install https://git.excelera.net/david/pi-extensions-and-skills@main (pi clones, runs npm install, registers); dev machine -> manual npm install + pi install /abs/path (pi does not run npm install for local paths), update = git pull + /reload.
extensions/forgejo now has a working entry point (extensions/forgejo/src/index.ts: forgejo_detect + issue/PR/milestone tool suites), importing only @earendil-works/pi-coding-agent (root peerDep) and typebox (root dep) — no new runtime deps.
README is stale: says 11 skills (there are 12) and lists forgejo as not in the package / WIP.

Requirements

Add "local:install" to scripts in root package.json — no npm lifecycle semantics (never auto-runs on npm install; runs only via npm run local:install).
Works from any git checkout of this repo; behaves sensibly elsewhere (fail fast).
Steps in order: (a) preflight checks -> (b) git pull (only on clean main) -> (c) npm install -> (d) global pi registration with URL-entry dedupe -> (e) /reload reminder.
Manifest: add extensions/forgejo/src/index.ts -> 4 extensions; skills stay ./skills (12 skills).
README: 12 skills, 4 extensions incl. forgejo, new flow (git clone <url> && cd pi-extensions-and-skills && npm run local:install), fix stale sections.

Fail-fast behavior — abort (non-zero exit) on any of these, each with an actionable remediation message (what is missing + how to fix it):

pi CLI not found -> how to install pi
Inside pi's managed clone (~/.pi/agent/git/..., .pi/git/...) -> run from your own checkout
Not a git checkout of this repo -> clone it first
Not on main -> git checkout main
Dirty working tree -> git commit / git stash
git pull fails (offline/auth) -> check network/credentials
npm install fails -> npm error output
rg binary missing (rg ext) -> e.g. sudo apt install ripgrep
DATABASE_URL missing from env or .env (postgres ext)
FORGEJO_TOKEN missing (forgejo ext) -> generate in Forgejo -> Settings -> Applications
fj CLI missing/not authenticated (pr-comments ext) -> fj auth login

Registration & dedupe

Global settings (~/.pi/agent/settings.json).
Before pi install <abs path>, remove any existing entry whose source references this repo's URL (match plain URL and git:/ssh:// forms) -> single clean identity, no duplicate skills/extensions.

Validation / acceptance criteria

Dev machine (clean main): npm run local:install exits 0; pi list shows local-path entry with no URL duplicate; after /reload, /skills lists all 12; spot-check one tool per extension (grep/rg, postgres, pr-comments, forgejo_detect).
Fresh machine: git clone <url> <tmp> && cd <tmp> && npm run local:install succeeds; same verification.
Negative tests: dirty tree -> commit/stash message; feature branch -> checkout-main message; unset FORGEJO_TOKEN -> token message; missing rg -> ripgrep message.

Out of scope

grillme (separate npm package: pi install npm:@majorgilles/pi-grill-me)
Per-extension devDeps, build steps, tests
Any npm lifecycle/postinstall hooks

Rollout (per AGENTS.md) — label feature; branch feature/issue-<N>/<slug>; commits issue-<N>: <summary>; PR issue-<N>: <title> with Closes #<N>; squash-merge; delete branch.

**Summary** Add an explicit npm script, `npm run local:install`, that updates and installs all skills and extensions in this package in one command, from any git checkout of this repo (dev machine or fresh clone elsewhere). It must fail fast on any problem and tell the user exactly what is missing and how to fix it. **Background** - Root `package.json` has a `pi` manifest declaring 3 extensions (`extensions/rg/index.ts`, `extensions/postgres/index.ts`, `extensions/pr-comments/src/index.ts`) + `./skills` (12 markdown-only skills), and **no `scripts` section**. - README documents two manual flows: other machines -> `pi install https://git.excelera.net/david/pi-extensions-and-skills@main` (pi clones, runs npm install, registers); dev machine -> manual `npm install` + `pi install /abs/path` (pi does **not** run npm install for local paths), update = `git pull` + `/reload`. - `extensions/forgejo` now has a working entry point (`extensions/forgejo/src/index.ts`: forgejo_detect + issue/PR/milestone tool suites), importing only `@earendil-works/pi-coding-agent` (root peerDep) and `typebox` (root dep) — **no new runtime deps**. - README is stale: says 11 skills (there are 12) and lists forgejo as not in the package / WIP. **Requirements** 1. Add `"local:install"` to `scripts` in root `package.json` — **no npm lifecycle semantics** (never auto-runs on `npm install`; runs only via `npm run local:install`). 2. Works from any git checkout of this repo; behaves sensibly elsewhere (fail fast). 3. Steps in order: (a) preflight checks -> (b) `git pull` (only on clean `main`) -> (c) `npm install` -> (d) global pi registration with URL-entry dedupe -> (e) `/reload` reminder. 4. Manifest: add `extensions/forgejo/src/index.ts` -> **4 extensions**; skills stay `./skills` (**12 skills**). 5. README: 12 skills, 4 extensions incl. forgejo, new flow (`git clone <url> && cd pi-extensions-and-skills && npm run local:install`), fix stale sections. **Fail-fast behavior — abort (non-zero exit) on any of these, each with an actionable remediation message** (what is missing + how to fix it): - `pi` CLI not found -> how to install pi - Inside pi's managed clone (`~/.pi/agent/git/...`, `.pi/git/...`) -> run from your own checkout - Not a git checkout of this repo -> clone it first - Not on `main` -> `git checkout main` - Dirty working tree -> `git commit` / `git stash` - `git pull` fails (offline/auth) -> check network/credentials - `npm install` fails -> npm error output - `rg` binary missing (rg ext) -> e.g. `sudo apt install ripgrep` - `DATABASE_URL` missing from env or `.env` (postgres ext) - `FORGEJO_TOKEN` missing (forgejo ext) -> generate in Forgejo -> Settings -> Applications - `fj` CLI missing/not authenticated (pr-comments ext) -> `fj auth login` **Registration & dedupe** - Global settings (`~/.pi/agent/settings.json`). - Before `pi install <abs path>`, remove any existing entry whose source references this repo's URL (match plain URL **and** `git:`/`ssh://` forms) -> single clean identity, no duplicate skills/extensions. **Validation / acceptance criteria** - Dev machine (clean `main`): `npm run local:install` exits 0; `pi list` shows local-path entry with no URL duplicate; after `/reload`, `/skills` lists all 12; spot-check one tool per extension (grep/rg, postgres, pr-comments, forgejo_detect). - Fresh machine: `git clone <url> <tmp> && cd <tmp> && npm run local:install` succeeds; same verification. - Negative tests: dirty tree -> commit/stash message; feature branch -> checkout-main message; unset `FORGEJO_TOKEN` -> token message; missing `rg` -> ripgrep message. **Out of scope** - `grillme` (separate npm package: `pi install npm:@majorgilles/pi-grill-me`) - Per-extension devDeps, build steps, tests - Any npm lifecycle/postinstall hooks **Rollout (per AGENTS.md)** — label `feature`; branch `feature/issue-<N>/<slug>`; commits `issue-<N>: <summary>`; PR `issue-<N>: <title>` with `Closes #<N>`; squash-merge; delete branch.

david added the

feature

label

2026-08-18 12:54:27 +00:00

david referenced this issue

2026-08-18 12:56:42 +00:00

Commit uncommitted docs — implementation plan for local:install #42

david referenced this issue

2026-08-18 12:56:53 +00:00

issue-42: Commit uncommitted docs — implementation plan for local:install #43

david referenced this issue

2026-08-18 13:17:58 +00:00

41: Add npm run local:install script to update and install all skills and extensions #44

david closed this issue

2026-08-18 13:18:01 +00:00

david commented

2026-08-18 13:18:02 +00:00

Author

Owner

pi-loop opened and merged a pull request for this issue: #44

pi-loop opened and merged a pull request for this issue: https://git.excelera.net/david/pi-extensions-and-skills/pulls/44

david referenced this issue

2026-08-27 23:59:07 +00:00

Validate install:local from a scratch clone (fresh machine) #89

david referenced this issue

2026-08-27 23:59:07 +00:00

Implement pi registration with URL dedupe and reload reminder in scripts/local-install.mjs #90

david referenced this issue

2026-08-27 23:59:07 +00:00

Validate install:local end-to-end on the dev machine #92

david referenced this issue

2026-08-27 23:59:07 +00:00

Add unit tests for scripts/local-install.mjs (node --test) #93

david referenced this issue

2026-08-27 23:59:07 +00:00

Rewrite README.md: 12 skills, 4 extensions (incl. forgejo), install:local flow #94

david referenced this issue

2026-08-27 23:59:07 +00:00

Update package.json: add install:local script and register forgejo extension #95

david commented

2026-08-28 02:20:45 +00:00

Author

Owner

Validation results — issue #92: install:local end-to-end on the dev machine (2026-08-28)

Environment: Nobara Linux 43 (x86_64), pi 0.84.3, node v22.22.0, npm 10.9.4; dev checkout at origin/main e0d1db2 (clean main, clean tree). All runs on the dev machine against the shared ~/.pi/agent/settings.json.

All acceptance criteria pass:

✅ npm run install:local exits 0 on clean main — preflight passed, git pull --ff-only → "Already up to date.", npm install → 157 packages / 0 vulnerabilities, pi install /home/david/Projects/pi-extensions-and-skills → "Installed", reminder printed.
✅ pi list shows the package as a local-path entry (../../Projects/pi-extensions-and-skills); no URL entry for this repo remains (none pre-existed — the dev machine already used a local-path registration; settings byte-identical before/after).
✅ /reload + /skills = 12 — headless equivalent: fresh pi --print session booted exit 0 and listed all 12 skills of this package (bruno-cli, commit-changes, commit-docs, create-issues, explain, forgejo-cli, furnish-repo, github-cli, init-project, meilisearch, review, tdd-implementation). The session also listed pi-planning-with-files, a separate npm package on this machine.
✅ Spot-checks:
- rg → grep: 6 matches for install:local in README.md (first at line 70) — independently confirmed with rg -c.
- forgejo → forgejo_detect: host git.excelera.net, owner david, repo pi-extensions-and-skills, token configured.
- pr-comments → detect_branch "Current branch: main"; find_pr → clean domain error "No open PR found for branch: main" (expected — no open PR against main).
- postgres → db_list_tables: ⚠️ environment-limited — no DATABASE_URL in env or <cwd>/.env; the extension registers zero tools when unconfigured (by design; confirmed DB_TOOLS=none from a live session's tool list), so the live-DB check cannot run on this machine. The extension loads without crashing (pi boots exit 0). Same limitation as #89.
- grillme (bonus): all six grill_* tools registered.
✅ Negative tests, all exact:
- on a feature branch → exit 1, [install:local] Aborted: not on main (current: feature/issue-92/…). Switch first: \git checkout main``
- dirty tree → exit 1, [install:local] Aborted: working tree is dirty. Commit or stash your changes first: \git commit` / `git stash``
- FORGEJO_TOKEN unset → [install:local] Warning: FORGEJO_TOKEN is not set. … on stderr, install continues to completion, exit 0
- rg missing (PATH stripped) → exit 1, [install:local] Aborted: rg binary not found. Install ripgrep, e.g. \sudo apt install ripgrep` (needed by the rg extension).`

Observations:

Branch-check message wording differs slightly from plan §3 ("Switch first" vs "switch to main first") — behavior matches the spec; only phrasing differs.
Dedupe removal path not exercised live (no URL-form entry pre-existed on this machine) — covered by unit tests (43/43 passing, including dedupe cases) and observed in #89's scratch-clone validation.
Postgres spot-check remains environment-limited here (no DATABASE_URL), same as #89.

Full results table recorded in docs/IMPLEMENTATION_PLAN.md §5.1 in this issue's change. No state left behind: temporary dirty-tree file removed, stripped-PATH dir removed, settings byte-identical to pre-validation state; dev machine verified healthy (headless pi boots exit 0).

## Validation results — issue #92: install:local end-to-end on the dev machine (2026-08-28) Environment: Nobara Linux 43 (x86_64), pi 0.84.3, node v22.22.0, npm 10.9.4; dev checkout at origin/main `e0d1db2` (clean `main`, clean tree). All runs on the dev machine against the shared `~/.pi/agent/settings.json`. **All acceptance criteria pass:** - ✅ `npm run install:local` exits 0 on clean `main` — preflight passed, `git pull --ff-only` → "Already up to date.", `npm install` → 157 packages / 0 vulnerabilities, `pi install /home/david/Projects/pi-extensions-and-skills` → "Installed", reminder printed. - ✅ `pi list` shows the package as a local-path entry (`../../Projects/pi-extensions-and-skills`); no URL entry for this repo remains (none pre-existed — the dev machine already used a local-path registration; settings byte-identical before/after). - ✅ `/reload` + `/skills` = 12 — headless equivalent: fresh `pi --print` session booted exit 0 and listed all 12 skills of this package (bruno-cli, commit-changes, commit-docs, create-issues, explain, forgejo-cli, furnish-repo, github-cli, init-project, meilisearch, review, tdd-implementation). The session also listed `pi-planning-with-files`, a separate npm package on this machine. - ✅ Spot-checks: - rg → grep: 6 matches for `install:local` in README.md (first at line 70) — independently confirmed with `rg -c`. - forgejo → `forgejo_detect`: host `git.excelera.net`, owner `david`, repo `pi-extensions-and-skills`, token configured. - pr-comments → `detect_branch` "Current branch: main"; `find_pr` → clean domain error "No open PR found for branch: main" (expected — no open PR against `main`). - postgres → `db_list_tables`: ⚠️ environment-limited — no `DATABASE_URL` in env or `<cwd>/.env`; the extension registers zero tools when unconfigured (by design; confirmed `DB_TOOLS=none` from a live session's tool list), so the live-DB check cannot run on this machine. The extension loads without crashing (pi boots exit 0). Same limitation as #89. - grillme (bonus): all six `grill_*` tools registered. - ✅ Negative tests, all exact: - on a feature branch → exit 1, `[install:local] Aborted: not on main (current: feature/issue-92/…). Switch first: \`git checkout main\`` - dirty tree → exit 1, `[install:local] Aborted: working tree is dirty. Commit or stash your changes first: \`git commit\` / \`git stash\`` - `FORGEJO_TOKEN` unset → `[install:local] Warning: FORGEJO_TOKEN is not set. …` on stderr, install continues to completion, exit 0 - `rg` missing (PATH stripped) → exit 1, `[install:local] Aborted: rg binary not found. Install ripgrep, e.g. \`sudo apt install ripgrep\` (needed by the rg extension).` Observations: 1. Branch-check message wording differs slightly from plan §3 ("Switch first" vs "switch to main first") — behavior matches the spec; only phrasing differs. 2. Dedupe removal path not exercised live (no URL-form entry pre-existed on this machine) — covered by unit tests (43/43 passing, including dedupe cases) and observed in #89's scratch-clone validation. 3. Postgres spot-check remains environment-limited here (no `DATABASE_URL`), same as #89. Full results table recorded in `docs/IMPLEMENTATION_PLAN.md` §5.1 in this issue's change. No state left behind: temporary dirty-tree file removed, stripped-PATH dir removed, settings byte-identical to pre-validation state; dev machine verified healthy (headless pi boots exit 0).