pi-checkup 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xinghe-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,344 @@
-# Temporary Holding Version
+# pi-checkup
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**`pi list` tells you what you installed. `pi-checkup` tells you what actually works.**
+
+A health-check extension for [Pi](https://pi.dev). It inspects the *running* session — not just your `settings.json` — and reports the failures that produce no error message anywhere: tools silently shadowed by another package, binaries that resolve to a completely different program, packages that are installed but registered nothing, endpoints that stopped answering.
+
+## Install
+
+```bash
+pi install npm:pi-checkup
+```
+
+Start a new session afterwards (or run `/reload` in a running one): a package
+installed mid-session is not loaded until Pi re-reads its package list.
+
+Then, in a session:
+
+```text
+/checkup            run every check
+/checkup verbose    same, plus what to do about each finding
+/checkup json       machine-readable report
+/checkup fix        apply the available repairs (asks first)
+```
+
+## The problem
+
+A Pi install accumulates packages. Each one registers tools, commands, hooks, and sometimes shell binaries. When one of them stops working, nothing tells you:
+
+- Two packages claimed the same tool name, and the second one silently won. The first is now unreachable.
+- A package is in `settings.json`, its directory exists, but its manifest points at a file that isn't there. It loaded nothing and logged nothing.
+- `ast-grep` ships a binary named `sg`. So does the shadow-utils package. Typing `sg` starts the wrong one.
+- A blocked `postinstall` left `node_modules/.bin/playwright` as a dangling symlink.
+- Your provider endpoint moved. The only symptom is a request that hangs, then fails.
+
+`pi list` prints paths. `pi --verbose` prints warnings you have to read line by line. Neither answers *"is my setup actually coherent right now?"*
+
+## The standalone CLI
+
+The in-session command is useless in the one case you need it most: Pi is installed but will not boot. The same checks also ship as a CLI that needs no session, no Pi, and no `node_modules` — which is also what you want in CI, or on a machine you are about to hand over.
+
+One difference to know before you read the first CLI report: the registry section — collisions, silent packages, attribution — is read from the live process, so the CLI marks it skipped. Everything else runs without a session: packages, binaries, network, config, runtime. On a machine where Pi has never been started, most rows have nothing to inspect and say so rather than passing.
+
+```bash
+npx pi-checkup              # full report
+npx pi-checkup --verbose    # same report, plus the hint under every finding
+npx pi-checkup --offline    # skip every network probe
+npx pi-checkup --json       # for scripts
+npx pi-checkup --fix        # list the available repairs
+npx pi-checkup --fix -y     # apply them (nothing is written without -y)
+npx pi-checkup --version    # print the version
+npx pi-checkup --help       # every flag and exit code
+```
+
+Requires Node 20 or newer (`engines` in `package.json`); no dependencies, no `node_modules`.
+
+It exits `1` when any check fails, so it works as a pre-flight step in CI or a shell profile. After a repair it re-runs the checks and exits on the new result, so `npx pi-checkup --fix -y && start-pi` does what it looks like it does. `--json` cannot be combined with `--fix`: the JSON is a single snapshot, and a repair changes what the snapshot describes.
+
+The registry section reports skipped — auditing loaded tools genuinely requires a live process — and the CLI says so instead of implying a clean bill of health.
+
+Exit codes: `0` nothing failed, `1` at least one check failed, `2` bad usage or a crashed run. The `--json` payload is the same report the text renderer prints, minus the repair metadata.
+
+| Variable | Effect |
+|---|---|
+| `PI_CODING_AGENT_DIR` | Check a different Pi install than `~/.pi/agent`. The CLI needs no session, so this is how you check a container, a second profile, or a Pi that will not boot at all |
+| `PI_CHECKUP_IGNORE` | Suppress rows you have decided to live with — see below |
+| `PI_CHECKUP_PROBE_URL` | Test real proxy *forwarding* with `curl`, instead of only proving the port is open. Only meaningful when a proxy variable below is set — without one there is nothing to forward through |
+| `https_proxy`, `HTTPS_PROXY`, `http_proxy`, `HTTP_PROXY`, `all_proxy`, `ALL_PROXY` | The first one set is used by the provider probe (through `curl`, because Node's `fetch` ignores these) and reported redacted under Runtime. The probe runs with `--noproxy ''`, so a `NO_PROXY` entry cannot route it around the proxy it is meant to test — and Pi's own `fetch` ignores `NO_PROXY` too |
+
+```text
+$ npx pi-checkup
+Registry
+  · live registry      no Pi session — registry checks need a running process
+Packages
+  ✓ package dirs       14 present
+  ✓ manifests          14 readable
+  ✓ entry files        13 manifest(s) resolve
+Binaries
+  ✓ dangling links     19 links all resolve
+  · shadowed names     no package command resolved on PATH
+  ! unreachable bins   6 package command(s) not on PATH: pi-web-access-mcp,
+                       pi-subagents, pi-mcp-adapter, pi-lens, pi-lens-mcp,
+                       pi-lens-analyze
+Network
+  ✓ providers          2 endpoint(s) reachable
+  ✓ dns                1 provider host(s) resolve normally
+Config
+  ✓ settings.json      valid JSON
+  ✓ models.json        valid JSON
+  · project settings   none
+  ✓ backups            2 file(s) backed up; edited since the newest backup:
+                       settings.json
+  ✓ duplicate packages none
+  · env references     no $VAR reference in models.json credentials
+Runtime
+  ✓ node               v22.23.3
+  ✓ pi launcher        /root/.pi/agent/bin/pi
+  ✓ disk               6% used on /, 950.7 GB free
+  ✓ proxy              http://127.0.0.1:10808 accepting connections
+
+19 checks: 14 ok, 1 warning, 0 failed, 4 skipped
+Run `npx pi-checkup --verbose` to show what to do about each finding.
+
+! 1 warning, 4 skipped  ·  run /checkup inside Pi for registry checks
+```
+
+Both captures below and above come from a real machine, taken with pi-checkup 0.1.0; free space, Node versions and which packages are installed are properties of that machine, not of the tool, and the row counts grow when checks are added.
+
+## Real output
+
+This is an actual run on a working install, copied out of the TUI at 80 columns — not a mock-up. The two `Network` rows describe the moment it ran; everything else is a property of the install. 20 of 24 checks pass, three are skipped because there is genuinely nothing to look at, and the one warning is the expected state on this machine — the package commands are installed but their directory is not on `PATH`, which the hint explains and `PI_CHECKUP_IGNORE=unreachable` silences.
+
+```text
+Registry
+  ✓ tools              49 registered (39 extension, 10 builtin) across 12
+                       sources
+  ✓ commands           95 registered across 21 sources, 0 MCP server(s)
+  ✓ attribution        49 tool(s) from 12 source(s): pi-lens (13), builtin (10),
+                       pi-web-access (5), pi-subagents (5), ... 8 more
+  ✓ tool collisions    none
+  ✓ command collisions none
+  ✓ silent packages    none
+Packages
+  ✓ package dirs       14 present
+  ✓ manifests          14 readable
+  ✓ entry files        13 manifest(s) resolve
+Binaries
+  ✓ dangling links     19 links all resolve
+  · shadowed names     no package command resolved on PATH
+  ! unreachable bins   6 package command(s) not on PATH: pi-web-access-mcp,
+                       pi-subagents, pi-mcp-adapter, pi-lens, pi-lens-mcp,
+                       pi-lens-analyze
+Network
+  ✓ providers          2 endpoint(s) reachable
+  ✓ dns                1 provider host(s) resolve normally
+Config
+  ✓ settings.json      valid JSON (values read from the running session)
+  ✓ models.json        valid JSON
+  · project settings   none
+  ✓ backups            2 file(s) backed up; edited since the newest backup:
+                       settings.json
+  ✓ duplicate packages none
+  · env references     no $VAR reference in models.json credentials
+Runtime
+  ✓ node               v22.23.3
+  ✓ pi launcher        /root/.pi/agent/bin/pi
+  ✓ disk               6% used on /, 950.7 GB free
+  ✓ proxy              http://127.0.0.1:10808 accepting connections
+
+24 checks: 20 ok, 1 warning, 0 failed, 3 skipped
+Run `/checkup verbose` to show what to do about each finding.
+```
+
+The `attribution` row is the part no other tool gives you: which package owns which tools, counted from the live registry rather than from your config. Both blocks above share the same 23-column detail column, because `duplicate packages` and `command collisions` are both 18 characters wide and the renderer sizes the column to the longest title in the report it is printing, up to a 22-character cap after which the detail moves to its own line.
+
+## What it checks
+
+| Group | Finding | Why it matters |
+|---|---|---|
+| **Registry** | Live registry | No Pi session — the registry checks need a running process, so the whole section collapses to this one skipped row |
+| | Tool and command collisions | One extension silently stops being reachable; the later registration wins with no error |
+| | Silent packages | Declared an extension but registered no tool or command — either by design or a load failure |
+| | Loaded tools and commands | How many registered, split by extension and builtin, and how many distinct sources they came from |
+| | Attribution | Which package owns each of your tools, by name |
+| **Packages** | Package list | Whether `settings.json` could be read at all — a hand-edited file that does not parse is reported as unreadable, not as "no packages" |
+| | Missing directories | In `settings.json` but gone from `node_modules`. A version pin (`npm:name@1.2.3`) is resolved to the directory it installs into, not taken as part of the name |
+| | Version pins | `settings.json` pins an exact version and a different one is installed — the code that runs is not the code that was asked for. Ranges and tags are not compared, because the installer is free to satisfy them |
+| | Corrupt manifests | A `package.json` that parses as nothing — reported as a failure, because the package cannot load |
+| | Missing manifests | The package directory exists but holds no `package.json` — an interrupted install, or a leftover folder. Its own row, because telling someone to check ownership of a directory that has no manifest sends them to fix the wrong thing |
+| | Unreadable manifests | A `package.json` this process could not read (permissions, or larger than the 4 MB limit). Reported as a warning: unproven, not broken |
+| | Missing entry files | The manifest points at a build output that was never shipped |
+| | Not a package | A `packages` entry that points at a file instead of a directory. Reported without a repair: there is nothing to delete |
+| | Unverifiable sources | `git:` and `https:` packages, which Pi resolves internally and no static check can follow |
+| | Malformed entries | A `packages` entry that is not a source string — `null`, a number, an object without `source` |
+| | Unreadable directories | A package directory that exists but cannot be listed, which is a permission problem rather than a missing install |
+| | Manifest shape | A `pi.extensions` entry that is not a string. The string entries are still checked; only the malformed ones are left out |
+| **Binaries** | Bin directory | Whether `.bin` could be listed at all — a missing `.bin` is a `skip` that still says how many commands it should have held, an unreadable one is a warning |
+| | Dangling links | A symlink whose target is gone — a blocked `postinstall`, or an optional native dependency skipped for this platform. Only links are counted, so a Windows `.bin` of plain shim files reports `skip` instead of a green tick over nothing |
+| | Unreadable links | A link that exists but cannot be followed (permissions, a loop) — reported, not called broken |
+| | Install leftovers | `.<name>-<random>` staging links in `.bin`: an install is running right now, or was interrupted. Its own finding, not a broken package |
+| | Missing shims | The package declares a `bin` but npm never linked it into `.bin` — usually an install run with `--ignore-scripts` |
+| | Shadowed names | A package's command name resolves to an unrelated program earlier on `PATH`. Skipped when no declared command resolved at all: there is nothing to compare, and a green tick there would sit next to a row saying the commands are missing |
+| | Unreachable bins | A package ships a CLI you cannot invoke by name |
+| **Network** | Endpoint reachability | Probes `<baseUrl>/models` for every provider. `401`/`403` counts as alive — this never validates your key and never spends tokens. An endpoint that answers with something other than life — a refused connection, a rejected certificate, an HTTP error — is a failure, and fails the run; only a probe that was cut off locally by its own timeout stays a warning, because the deadline is this process's, not the endpoint's |
+| | Cleartext auth | A provider on `http://` to another machine with a credential configured — an `apiKey`, a password embedded in the `baseUrl`, a credential-named header value, or a query string, which cannot be inspected for secrets. The `apiKey` and `baseUrl` credentials are withheld from the probe; a query string is never sent, so that endpoint is reported unprobed. Loopback hosts are exempt |
+| | baseUrl shape | A `baseUrl` that is not a string or an object. A string that is not a URL — including the `localhost:11434/v1` paste with no scheme — is reported as an unhealthy provider, and also named in this row, because the endpoint is what would have to be probed |
+| | DNS | Provider hosts that do not resolve, or resolve only to loopback |
+| **Config** | Invalid JSON | With a backup on disk, `/checkup fix` can restore it |
+| | Duplicate package entries | The package loads twice and the second registration can shadow the first |
+| | Unset env references | `$NAME` / `${NAME}` in the `models.json` fields Pi actually interpolates (`apiKey`, header values) with nothing in the environment |
+| | Backups | Whether a broken config could be recovered at all |
+| **Runtime** | Agent directory | Whether the directory being inspected exists and can be listed — without it most other rows skip, which would otherwise read as a clean install |
+| | Node version, launcher, disk, proxy | The host conditions Pi itself needs |
+
+The groups above are the ones that appear in a report, in that order. Independent of them: a check that throws, or runs past 30 seconds, is reported as a failure naming the module, and every other section still prints.
+
+## `/checkup fix`
+
+Only reversible repairs are automated, and inside a session it normally offers only the first:
+
+1. **Restore a config file** that is no longer valid JSON, from its newest sibling backup. The broken copy is kept.
+
+2. **Collapse duplicate `packages` entries** in `settings.json`. Only byte-identical repeats are dropped: `"npm:a"` next to `{"source": "npm:a", "enabled": false}` carries different intent and is left alone.
+3. **Prune `packages` entries whose directory is gone** — the ones a reinstall did not bring back. Sources resolved by Pi itself (`git:`, `https:`) are never touched, and a prune that would leave the list empty is refused and never even offered: that pattern means the agent directory is wrong, not that every package vanished.
+
+Repairs 2 and 3 rewrite `settings.json`, so they need a settings file checkup actually read. Inside a session Pi hands checkup the settings from the *running process*, not the file on disk, and checkup will not rewrite a file it never read — so `/checkup fix` in-session offers repair 1, plus the other two only when Pi returned no settings and checkup read the file itself. If `getSettings()` threw, the fallback is still unverified and neither rewrite is offered. Stop Pi and run the CLI to be sure:
+
+```bash
+npx pi-checkup --fix --yes
+```
+
+Every write is preceded by a timestamped backup, and neither path writes on its own: `/checkup fix` asks in the TUI, and the CLI refuses to write unless you pass `--yes`. Anything that would delete a package, disable an extension, or edit your shell environment is reported with a suggestion and left alone — a diagnostic tool should not be able to break your setup in the process of describing it.
+
+A repair that rewrites `settings.json` re-serialises it with two-space indentation, so expect a larger diff than the change itself. Nothing is repaired unless a check found something wrong, so a healthy install writes nothing at all.
+
+## Ignoring a finding you have decided to live with
+
+Some warnings are correct and permanent: a launcher you deliberately keep off `PATH`, an event-only package that registers no tool. A health check you have learned to ignore is worse than no health check, so rows can be suppressed by name.
+
+```bash
+PI_CHECKUP_IGNORE=unreachable,Config:env npx pi-checkup
+```
+
+Each entry matches a row's `id`, its `Group:id` form, or its title. A suppressed row is downgraded to `skip`, keeps its original detail, and says what it replaced:
+
+```text
+  · unreachable bins   ignored via PI_CHECKUP_IGNORE (would be warn): 6 package
+                       command(s) not on PATH: pi-web-access-mcp, pi-subagents,
+                       pi-mcp-adapter, pi-lens, pi-lens-mcp, pi-lens-analyze
+```
+
+Suppression is never silent, and it drops the row's repair offer so a hidden finding cannot be fixed behind your back. It applies to failures too: a suppressed `fail` no longer affects the exit code, which is the point of the variable — use it for a state you have decided to accept, not to turn a red build green. Export it from your shell profile if you want it to apply inside Pi too.
+
+## JSON output
+
+`/checkup json` prints the report as one object, delivered as a TUI notification — good for pasting into a bug report. For a pipe, use `npx pi-checkup --json`, which writes the same object to stdout, stamped with the version and platform that produced it. The excerpt below is from `/checkup json` inside a session — 24 entries, because the registry section has something to read there; in the CLI that section collapses to a single skipped row. Two of the entries, and the summary, are shown here:
+
+```json
+{
+  "summary": {
+    "total": 24,
+    "ok": 20,
+    "warn": 1,
+    "fail": 0,
+    "skip": 3
+  },
+  "version": "0.1.0",
+  "node": "22.23.3",
+  "platform": "linux",
+  "checks": [
+    {
+      "group": "Binaries",
+      "id": "unreachable",
+      "title": "unreachable bins",
+      "status": "warn",
+      "detail": "6 package command(s) not on PATH: pi-web-access-mcp, pi-subagents, pi-mcp-adapter, pi-lens, pi-lens-mcp, pi-lens-analyze",
+      "hint": "Pi installs package commands into /root/.pi/agent/npm/node_modules/.bin without adding it to PATH. Extensions that call them by full path still work; to use them by name, add that directory to PATH or run them with npx. If this is the state you want, silence the row with PI_CHECKUP_IGNORE=unreachable."
+    },
+    {
+      "group": "Config",
+      "id": "env",
+      "title": "env references",
+      "status": "skip",
+      "detail": "no $VAR reference in models.json credentials"
+    }
+  ]
+}
+```
+
+The `checks` array always has one entry per row of the text report, in the same order. The excerpt above omits the other 22 entries; real output is printed by `JSON.stringify(payload, null, 2)`.
+
+Exit-worthy statuses are `fail`; `warn` means something needs attention without by itself failing the run — a package command that is not on `PATH`, or an `apiKey` that no HTTP request can carry. Repair metadata is stripped from the JSON payload.
+
+## Design principles
+
+- **No traffic to anyone but your own provider.** The only outbound requests are `<baseUrl>/models` for providers already in `models.json`, plus a DNS lookup of those same hosts. The proxy check is a plain TCP connect to the proxy's own address — set `PI_CHECKUP_PROBE_URL` if you want a real end-to-end forwarding test.
+- **No secrets printed, no keys validated.** A provider probe sends the `apiKey` — or the `baseUrl` credentials, moved into an `Authorization` header — that your config defines, and ignores the response body. Custom `headers` are not replayed. A key on a plain-`http://` endpoint that is not on your own machine is never sent, and neither is a query string there — `?key=…` gateways are a real shape, and a query cannot be inspected for secrets. A proxy URL is reduced to scheme, host and port, and a value that is nothing but a credential prints `(configured)`; a `git:` source carrying a token is scrubbed the same way: corporate proxies and private repos both keep credentials in the URL, and both are the kind of string that ends up in a CI log. A `baseUrl` with credentials in it is moved into a header before the probe, so no error message can quote it back; over plain `http://` to another machine it is dropped instead, and the row says so. A header value that cannot be sent at all — a newline, a character above Latin-1 — is never sent through either path and is never quoted back: the row says the request could not be built and points at `models.json`.
+- **Non-blocking.** Every check runs concurrently, and every outbound call has its own timeout — 6s for a curl probe, 8s for a fetch probe, 4s for DNS, 3s for a TCP connect — under a 30s per-module backstop. A hung endpoint costs one timeout, or two when a configured proxy fails and the direct path is tried as well, and never the whole command.
+- **A crashing check is a finding, not a crash.** If a check module throws, the report says which one, marks it failed, and still shows everything else.
+- **A check with nothing to inspect says so.** `skip` means nothing was inspected — an absent optional config file, an empty `.bin`, a provider list with no host to resolve, or a row you suppressed with `PI_CHECKUP_IGNORE` (whose detail says what it replaced). Zero packages present reports `skip`, never a green tick over nothing, and the verdict counts them: `✓ 3 ok, 2 skipped` rather than a bare "all clear".
+- **Cross-platform.** Node built-ins only. `PATH` is resolved in-process against `PATHEXT` on Windows and the executable bit on POSIX, so a minimal container without `which` still works; `/dev/null` vs `NUL` for curl output, symlinked package stores, and path separators are handled. A check that finds nothing to inspect is marked skipped rather than failed — but a check module that throws or runs past its 30s backstop is a failure, because something was supposed to be inspected and was not.
+- **Zero dependencies.** Nothing to audit, nothing to break on a Pi upgrade.
+
+## Known limitations
+
+Being explicit about what this cannot see:
+
+- **Extension load errors are not exposed to extensions.** Pi's own `LoadExtensionsResult.errors` is not reachable from the extension API, so "which extension threw during load" is inferred statically (declared but unregistered), not read directly.
+- **`git:` and URL package sources are not inspected.** Pi resolves them internally; static probing cannot follow them, so they are reported as `unverifiable` rather than guessed at.
+- **Only the personal agent directory is audited.** A project's `.pi/settings.json` is checked for parseability, but the packages it declares are not resolved: where a project installs them is Pi's decision, and guessing the path produced "missing" claims that were not true.
+- **The registry section needs a running session.** Tools and commands are read from the live process; the CLI reports that section as skipped rather than guessing from disk.
+- **Tool collisions are reported, not resolved.** Pi's registry keeps the last registration; checkup tells you it happened.
+- **The proxy check proves the port is open, not that forwarding works.** A TCP connect tells you the process is running; it says nothing about whether it can reach a given target. Set `PI_CHECKUP_PROBE_URL` for the full test, which uses `curl`.
+- **A proxied provider probe needs `curl`.** Node's `fetch` ignores `https_proxy`, so when a proxy is configured the probe shells out to `curl`, which honours it. Without `curl` on `PATH` that row reports `skip` with the reason instead of inventing a reachability failure.
+- **Static checks describe the current session.** Install a package and the registry section is stale until `/reload`.
+- **A DNS lookup that hangs can outlive the report.** `resolveHost` races the lookup against a 4s deadline so the report is never held hostage, but Node's pending `getaddrinfo` request can keep the process alive for a while after the verdict is printed. The report is complete and correct; the exit is merely later than it looks.
+- **A run that overlaps an install describes a moving target.** Half-extracted packages and npm's staging links in `.bin` are visible for a second or two; checkup reports them as install leftovers and suggests re-running once the install finishes, but it cannot wait for it.
+
+## Development
+
+```bash
+git clone https://github.com/xinghe-labs/pi-checkup
+cd pi-checkup
+npm run lint         # node --check over every source file
+node --test          # the whole suite; no Pi session needed
+```
+
+To try a local checkout without installing:
+
+```bash
+pi -e ./src/index.js
+```
+
+Layout:
+
+```text
+bin/
+  checkup.js         standalone CLI entry
+src/
+  index.js           in-session command registration, fix flow
+  context.js         where a check gets its inputs (session vs disk)
+  render.js          one formatter for text and JSON
+  repair.js          the only module that writes to user files
+  util.js            cross-platform helpers, no dependencies
+  checks/
+    index.js         the check registry, shared by command and CLI
+    registry.js      what is loaded, who owns it, what collided
+    packages.js      installed vs present vs loadable
+    binaries.js      PATH reachability and shadowing
+    network.js       provider endpoints and DNS
+    config.js        JSON validity, backups, duplicates, env refs
+    runtime.js       node, launcher, disk, proxy
+test/
+  *.test.js          node --test, no Pi session needed
+scripts/
+  lint.js            node --check over every source file (`npm run lint`)
+```
+
+Adding a check: export `group` and `run(ctx)`, return an array of `{ group, id, title, status, detail, hint? }`, and add the module to the `CHECKS` array in `src/checks/index.js`.
+
+`ctx` carries everything a check may read — `agentDir`, `settingsFile`, `projectSettingsFile`, `modelsFile`, `binDir`, `settings`, `settingsLoaded`, `settingsSource`, `env`, `offline`, `hasRuntime`, `agentDirExplicit`, `pi`, `cwd` — so no check reads the process environment or a path on its own. Tests point `agentDir` at a temp directory; see `test/checks.test.js`.
+
+## License
+
+MIT

package/bin/checkup.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+// Standalone CLI — for the case the in-session command cannot cover: Pi is
+// installed but will not start, so there is no session to run /checkup in.
+//
+// The registry checks need a live process and report skipped here. Everything
+// else (packages, binaries, config, runtime, and network unless --offline) runs
+// exactly as it does inside Pi.
+import { runChecks } from "../src/checks/index.js";
+import { buildContext } from "../src/context.js";
+import { renderReport, renderVerdict, toJson } from "../src/render.js";
+import { applyRepairs } from "../src/repair.js";
+import { packageVersion, scrubCredentials } from "../src/util.js";
+
+const VERSION = packageVersion();
+
+const HELP = `pi-checkup ${VERSION} — health checks for a Pi installation
+
+Usage
+  pi-checkup [options]
+
+Options
+  -v, --verbose    show how to fix each finding
+      --json       print the report as JSON
+      --offline    skip every network probe
+      --fix        list the available repairs, and apply them with --yes
+  -y, --yes        apply the repairs instead of only listing them
+  -h, --help       show this help
+      --version    print the version
+
+Exit codes
+  0  no failed checks (including after a successful repair)
+  1  at least one check failed
+  2  usage error, or the run itself crashed
+
+--json and --fix cannot be combined: --json is a single machine-readable
+snapshot, and a repair changes what the snapshot describes.
+
+The registry section needs a running Pi session; use /checkup inside Pi to
+audit loaded tools and commands.
+
+Environment
+  PI_CODING_AGENT_DIR    agent directory to inspect (default: ~/.pi/agent)
+  PI_CHECKUP_IGNORE      comma-separated rows to downgrade to skipped, by id,
+                         Group:id, or title (e.g. "unreachable,Config:env")
+  PI_CHECKUP_PROBE_URL   opt in to a real forwarding test through the proxy
+  https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY, all_proxy, ALL_PROXY
+                         the first one set is tested for reachability; never
+                         printed with credentials`;
+
+function parseArgs(argv) {
+	const opts = { verbose: false, json: false, offline: false, fix: false, yes: false, help: false, version: false };
+	for (const arg of argv) {
+		switch (arg) {
+			case "-v":
+			case "--verbose":
+				opts.verbose = true;
+				break;
+			case "--json":
+				opts.json = true;
+				break;
+			case "--offline":
+				opts.offline = true;
+				break;
+			case "--fix":
+				opts.fix = true;
+				break;
+			case "--yes":
+			case "-y":
+				opts.yes = true;
+				break;
+			case "-h":
+			case "--help":
+				opts.help = true;
+				break;
+			case "--version":
+				opts.version = true;
+				break;
+			default:
+				throw new Error(`unknown option: ${arg}`);
+		}
+	}
+	// Silently ignoring one of these two would run no repairs and say nothing.
+	if (opts.json && opts.fix) throw new Error("--json cannot be combined with --fix");
+	return opts;
+}
+
+async function main() {
+	let opts;
+	try {
+		opts = parseArgs(process.argv.slice(2));
+	} catch (e) {
+		process.stderr.write(`${e.message}\n\n${HELP}\n`);
+		return 2;
+	}
+
+	if (opts.help) {
+		process.stdout.write(`${HELP}\n`);
+		return 0;
+	}
+	if (opts.version) {
+		process.stdout.write(`${VERSION}\n`);
+		return 0;
+	}
+
+	// `--yes` on its own reads as "apply the repairs" and does nothing. Say so
+	// rather than returning a normal report that silently ignored a flag.
+	if (opts.yes && !opts.fix) process.stderr.write("pi-checkup: --yes only means something with --fix\n");
+
+	// Whether the agent directory was named explicitly matters to the Runtime
+	// group: a path the user typed and got wrong is a fault in this run, while an
+	// absent default location only means Pi has not been started on this machine.
+	const ctx = buildContext({
+		cwd: process.cwd(),
+		offline: opts.offline,
+		agentDirExplicit: Boolean(process.env.PI_CODING_AGENT_DIR),
+	});
+	const results = await runChecks(ctx);
+
+	if (opts.json) {
+		// Stamped: a JSON report pasted into an issue has to say what produced it,
+		// and a version or a platform is the first thing anyone asks for.
+		const payload = toJson(results, { version: VERSION, node: process.versions.node, platform: process.platform });
+		// Set before the write, like the text path: a consumer that closes the pipe
+		// mid-payload must still see the code the report implies.
+		process.exitCode = results.some((r) => r.status === "fail") ? 1 : 0;
+		process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+		return process.exitCode;
+	}
+
+	const report = renderReport(results, {
+		verbose: opts.verbose,
+		// `pi-checkup` alone only resolves after a global install the README does
+		// not require, so the hint names the form that always works.
+		hintCommand: "npx pi-checkup --verbose",
+		// Piped output has no columns; the renderer's default keeps logs stable.
+		width: process.stdout.isTTY ? process.stdout.columns || 80 : 80,
+	});
+	// Set before the first byte of the report, so a consumer that closes the pipe
+	// mid-report (`pi-checkup | head -3`) still exits with the code the report
+	// implies instead of a misleading 0.
+	process.exitCode = results.some((r) => r.status === "fail") ? 1 : 0;
+	process.stdout.write(`${report}\n`);
+	const fixable = results.filter((r) => r.fix && r.fixTarget);
+	let finalResults = results;
+	if (opts.fix) {
+		if (!fixable.length) {
+			process.stdout.write("\nNothing to repair automatically.\n");
+		} else if (!opts.yes) {
+			process.stdout.write(`\n${fixable.length} repair(s) available — each rewrites a config file after backing it up:\n`);
+			for (const f of fixable) process.stdout.write(`  • ${f.title}: ${f.detail}\n`);
+			process.stdout.write("\nRe-run with --fix --yes to apply them. Every file is backed up first.\n");
+		} else {
+			const applied = await applyRepairs(fixable, { agentDir: ctx.agentDir });
+			process.stdout.write("\nRepairs\n");
+			for (const a of applied) process.stdout.write(`  ${a.ok ? "✓" : "✗"} ${a.message}\n`);
+			// Only when something was actually written: a refused repair, or one
+			// that found nothing to do by the time it ran, changed nothing, so
+			// telling the user to restart Pi is noise.
+			const wrote = applied.some((a) => a.changed);
+			if (wrote) process.stdout.write("\nRestart Pi so it picks up the changes.\n");
+			// Re-check: the exit code has to describe the tree as it is now, not as
+			// it was before the repair. Exiting 1 right after fixing the only
+			// failure breaks every `&&` chain that calls this.
+			//
+			// The context has to be rebuilt, not reused: it holds the settings it
+			// parsed on construction, so re-running the checks against the old one
+			// reports the entries the repair just removed. That is how a successful
+			// prune still exited 1.
+			if (wrote) {
+				finalResults = await runChecks(
+					buildContext({
+						cwd: process.cwd(),
+						offline: opts.offline,
+						agentDirExplicit: Boolean(process.env.PI_CODING_AGENT_DIR),
+					}),
+				);
+			}
+		}
+	} else if (fixable.length) {
+		process.stdout.write(`\n${fixable.length} finding(s) can be repaired with --fix.\n`);
+	}
+
+	// Discoverability: the CLI cannot audit the registry, and saying so is more
+	// useful than letting the skipped section look like a clean bill of health.
+	// Labelled, because an unlabelled verdict printed under a pre-repair report
+	// reads as a contradiction: "1 failed" then "✓ 23 ok".
+	const after = finalResults === results ? "" : "  ·  re-checked after repair";
+	process.stdout.write(`\n${renderVerdict(finalResults)}${after}  ·  run /checkup inside Pi for registry checks\n`);
+	return finalResults.some((r) => r.status === "fail") ? 1 : 0;
+}
+
+// `npx pi-checkup | head -3` closes stdout while the report is still being
+// written. Node surfaces that as an unhandled EPIPE rejection, so a truncated
+// pipe printed "pi-checkup crashed" with a stack for something that is not a
+// failure of the check at all. A consumer that stopped reading is a normal exit.
+// Anything else is a real write failure, and it goes through the same scrubbing
+// as a caught exception: an uncaught throw from an event listener printed a raw
+// stack, which is the one place a config value can slip out unredacted.
+let reported = false;
+const writeFailure = (e) => {
+	// A write error on stderr is itself reported to stderr, so without this guard
+	// a broken stderr re-enters the handler instead of exiting.
+	if (reported) return;
+	reported = true;
+	process.stderr.write(`pi-checkup crashed: ${scrubCredentials(String(e?.stack ?? e))}\n`);
+	process.exitCode = 2;
+};
+process.stdout.on("error", (e) => {
+	// A consumer that stopped reading is a normal exit, but not a successful one:
+	// `pi-checkup | head -1` over failed checks must still exit 1.
+	if (e?.code === "EPIPE") process.exit(process.exitCode ?? 0);
+	writeFailure(e);
+});
+process.stderr.on("error", (e) => {
+	if (e?.code !== "EPIPE") writeFailure(e);
+});
+
+// `process.exit()` can truncate a pipe that has not drained, and a --json report
+// on a slow consumer is exactly the payload large enough to hit that. Setting
+// exitCode lets Node flush and exit on its own.
+main().then(
+	(code) => {
+		// A write failure already set 2, and "2 = the run itself crashed" is the
+		// one thing that must not be overwritten by a normal return.
+		if (!reported) process.exitCode = code;
+	},
+	(e) => {
+		// Scrubbed: an uncaught error can quote the URL or the config value it
+		// choked on, and a crash report is exactly where nobody looks twice.
+		process.stderr.write(`pi-checkup crashed: ${scrubCredentials(String(e?.stack ?? e))}\n`);
+		process.exitCode = 2;
+	},
+);

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "pi-checkup",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Health checks for your Pi setup: tool/command conflicts, broken packages, shadowed binaries, dead endpoints.",
+  "type": "module",
+  "license": "MIT",
+  "author": "xinghe-labs",
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-coding-agent",
+    "pi",
+    "extension",
+    "healthcheck",
+    "diagnostics",
+    "doctor",
+    "troubleshooting"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.js"
+    ]
+  },
+  "bin": {
+    "pi-checkup": "bin/checkup.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "lint": "node scripts/lint.js",
+    "checkup": "node ./bin/checkup.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xinghe-labs/pi-checkup.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xinghe-labs/pi-checkup/issues"
+  },
+  "homepage": "https://github.com/xinghe-labs/pi-checkup#readme"
+}