From 92441aefd600b49bd3526402cb0b17cc8479df0f Mon Sep 17 00:00:00 2001 From: Sam Rolfe Date: Wed, 5 Aug 2026 10:23:33 +1000 Subject: [PATCH] nixos-workflow: correct pi install context (Nix pi-coding-agent 0.82.1, no npx), add per-machine repo model + vscode-languageserver-protocol vendoring pitfall runbook --- skills/nixos-workflow/SKILL.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/skills/nixos-workflow/SKILL.md b/skills/nixos-workflow/SKILL.md index d2601b1..240bf13 100644 --- a/skills/nixos-workflow/SKILL.md +++ b/skills/nixos-workflow/SKILL.md @@ -11,6 +11,9 @@ You are an expert at managing Pi Agent assets on a NixOS system using a Gitea-ce ## ⛔ CRITICAL PROHIBITIONS - **NEVER** suggest or perform edits to `home.nix` to add individual extensions or skills. - **NEVER** use `pi install` or `npm install -g` (Nix store is read-only). +## 🗄 PER-MACHINE REPOS +Each machine has its OWN `~/.agents` git repo — its own clone of the shared Gitea `pi-config` repo (Gitea itself runs as Docker on `.35`, web `.35:3001`, SSH `.35:2222`). **A push from `.27` does NOT auto-update `.13`/`.51`** — update each machine's clone individually (`git -C ~/.agents pull`). `/config-add` discovery reads the local `~/.agents/extensions|skills` dirs, so a machine must pull before a new asset can be activated there. (.51 had no repo until 2026-08-05 — cloned then.) + ## 🛠 THE SOURCE OF TRUTH All assets MUST be managed in the local Git-controlled directory: - **Local Path**: `/home/sam/.agents` @@ -56,20 +59,27 @@ External npm extension (Langfuse LLM observability for pi) vendored + activated: The extension's own config lives at `~/.pi/agent/pi-langfuse/config.json` (`publicKey`/`secretKey`/`host` → `http://192.168.20.13:3001`). Commands: `/langfuse-setup`, `/langfuse-status`. Full documentation: `/home/sam/obsidian/300 areas/350 AI/Pi Agent Extensions & Skills.md` (section "pi-langfuse — LLM Observability for Pi"). +## ⚠️ VENDORING PITFALL — vscode-languageserver-protocol subpath +`pi-lsp-extension` (and possibly other extensions) imports `vscode-languageserver-protocol/node.js`. npm resolves `^3.17.5` to 3.18.x whose `exports` map exposes `./node` but **not** `./node.js` — the import throws at load and the ENTIRE extension silently fails (no `/lsp` commands appear, while other extensions still load — confusing). Fix: change the import to `vscode-languageserver-protocol/node` (no `.js`); re-apply whenever re-vendoring from npm (our fix = commit `57c5cd2`). + +**Load-verify any vendored extension** by bundling it the way pi's loader does: +```bash +npx esbuild src/index.ts --bundle --platform=node --format=esm \ + --external:@earendil-works/* --external:vscode-languageserver-protocol \ + --external:web-tree-sitter --external:tree-sitter-wasms --outfile=/tmp/x.mjs +# then import /tmp/x.mjs with a stub ExtensionAPI (registerTool/registerCommand/on/events) +``` + ## ❄ NIXOS INTEGRATION The ONLY time you reference Nix is for the **Global Settings**. Confirm the user's `home.nix` contains a `settings.json` that points to the Gitea source: `"source": "git:https://gitea.lab.audasmedia.com.au/sam/pi-config"` ## 🖥 PI INSTALLATION CONTEXT -On this system, `pi` is a shell script wrapper defined in `home.nix`: -``` -${pkgs.nodejs_24}/bin/npx @mariozechner/pi-coding-agent "$@" -``` -- **`pi update --self` will always fail** — npx manages freshness automatically; `pi update --extensions` works fine. -- **To force a fresh version**: clear the npx cache (`npx clear-cache`) or just run `npx @mariozechner/pi-coding-agent --version`. -- **Global npm install does NOT apply here** — NixOS manages the wrapper, not `npm install -g`. -- **Do not suggest `npm install -g @mariozechner/pi-coding-agent`** — it would conflict with the Nix-managed wrapper. -- **The binary runs from**: `/home/sam/.npm/_npx//node_modules/.bin/pi` (npx cache, not a managed install). +On all three machines (`.27`/`.13`/`.51`) `pi` is **Nix-managed** — the nixpkgs package **`pi-coding-agent`** (v0.82.1) in `home.packages`. There is NO npx wrapper and NO npm-global install anymore (both removed 2026-08-05). +- **`pi update --self` / `pi update --extensions`**: not applicable — the binary is Nix. Updating pi = bump the nixpkgs flake input (`nix flake update nixpkgs`) + `sudo nixos-rebuild switch --flake .#`. +- **Never `npm install -g @earendil-works/pi-coding-agent`** — npm-global/bin precedes `/etc/profiles/per-user/sam/bin` in PATH, so it shadows the Nix pi (caused a real bug once). +- **After a Nix pi switch: fully CLOSE running pi sessions.** A `/reload` in a session started from the old binary fails — the loader re-resolves every extension import against the old runtime dir, which no longer exists. Fresh sessions only. +- **Vendored extensions** (`pi-tool-display` global, `pi-lsp-extension` per-project) live in `~/.agents`; see the Obsidian doc `350 AI → Pi Agent Extensions & Skills.md`. ## ⌨ KEYBOARD TROUBLESHOOTING (Corne/QMK)