Switch Extension Source

Toggle a monorepo extension between npm (published) and local (working tree) source.

Why this exists

GUI equivalent: Settings → Packages exposes a per-row Reset to published version action (change: reset-override-to-npm) that resets a local/git-installed row back to its canonical npm:<name> — install-first / remove-second, confirm-gated. It is the one-click UI analog of switch <pkg> npm here; keep the two semantically aligned (both drop the local packages[] registration only, never the working-tree files).

On a dev machine you want extensions to load your live working tree so edits take effect. Distribution users consume the published npm package. Both can be wired at once across two config layers, and whichever pi resolves last wins — non-deterministic ("I edited it but nothing changed"). This skill enforces exactly one source per package.

  GLOBAL ~/.pi/agent/settings.json   "packages": [...]
    npm   -> "npm:<npmName>"
    local -> "<repoRoot>/packages/<dir>"      (dir path; pi resolves package.json "pi")

  PROJECT <repo>/.pi/settings.json   "packages":[{ source, extensions:["+packages/<dir>/<entry>"] }]
    local overlay -> only with --overlay; loads ONLY inside this repo; needs pi.extensions

local (default) = global dir path → loads in every session everywhere. local --overlay = project overlay → loads only when running pi inside this repo.

Commands

npx tsx ./scripts/switch-source.ts status               # where each installed pkg loads from
npx tsx ./scripts/switch-source.ts local <pkg>          # -> local working tree (global path)
npx tsx ./scripts/switch-source.ts local <pkg> --overlay# -> local, this-repo-only (extensions only)
npx tsx ./scripts/switch-source.ts npm   <pkg>          # -> published npm build

<pkg> = monorepo dir name (kb-extension) OR npm name (@blackbelt-technology/pi-dashboard-kb-extension).

Each switch removes all other representations of that package, timestamped-backs-up every file it edits (*.bak-switch-*), and re-validates JSON before writing.