pi-checkup 0.1.2 → 0.1.3

package/README.md

@@ -1,7 +1,15 @@
 # pi-checkup
 
+[![npm version](https://img.shields.io/npm/v/pi-checkup.svg)](https://www.npmjs.com/package/pi-checkup)
+[![CI](https://github.com/xinghe-labs/pi-checkup/actions/workflows/ci.yml/badge.svg)](https://github.com/xinghe-labs/pi-checkup/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/pi-checkup.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/pi-checkup.svg)](https://nodejs.org)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](./package.json)
+
 **`pi list` tells you what you installed. `pi-checkup` tells you what actually works.**
 
+![pi-checkup report](./docs/demo.svg)
+
 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
@@ -305,6 +313,17 @@ npm run lint         # node --check over every source file
 node --test          # the whole suite; no Pi session needed
 ```
 
+Coverage, as of 0.1.2 (`node --test --experimental-test-coverage`):
+
+```text
+all files          95.76 % lines   86.66 % branches   95.96 % funcs
+```
+
+The one file well below that is `src/index.js` at 25.69 % — the in-session command handler.
+Covering it needs a live Pi process, and the parts that matter (the confirmation prompt, the repair
+call, the re-check) were driven end to end over the RPC extension-UI protocol by hand rather than
+in the suite. A green number there would be worth less than saying so.
+
 To try a local checkout without installing:
 
 ```bash

package/docs/demo.svg

@@ -0,0 +1,44 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="690" height="726" viewBox="0 0 690 726" role="img" aria-label="pi-checkup report">
+  <title>pi-checkup report</title>
+  <rect width="690" height="726" rx="10" fill="#10141a"/>
+  <rect width="690" height="38" rx="10" fill="#1b222c"/>
+  <rect y="28" width="690" height="10" fill="#1b222c"/>
+  <circle cx="22" cy="19" r="6" fill="#e06c75"/>
+  <circle cx="42" cy="19" r="6" fill="#e0b25c"/>
+  <circle cx="62" cy="19" r="6" fill="#4ec9a0"/>
+  <text x="345.0" y="24" fill="#5c6b7f" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="11.5" text-anchor="middle">npx pi-checkup</text>
+  <g font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13.5" xml:space="preserve">
+    <text x="22" y="58" fill="#7aa2f7" font-weight="600">Registry</text>
+    <text x="22" y="77" fill="#5c6b7f" font-weight="400">  · live registry      no Pi session — registry checks need a running process</text>
+    <text x="22" y="96" fill="#7aa2f7" font-weight="600">Packages</text>
+    <text x="22" y="115" fill="#4ec9a0" font-weight="400">  ✓ package dirs       15 present</text>
+    <text x="22" y="134" fill="#4ec9a0" font-weight="400">  ✓ manifests          15 readable</text>
+    <text x="22" y="153" fill="#4ec9a0" font-weight="400">  ✓ entry files        14 manifest(s) resolve</text>
+    <text x="22" y="172" fill="#7aa2f7" font-weight="600">Binaries</text>
+    <text x="22" y="191" fill="#4ec9a0" font-weight="400">  ✓ dangling links     19 links all resolve</text>
+    <text x="22" y="210" fill="#5c6b7f" font-weight="400">  · shadowed names     no package command resolved on PATH</text>
+    <text x="22" y="229" fill="#5c6b7f" font-weight="400">  · unreachable bins   6 package command(s) live in</text>
+    <text x="22" y="248" fill="#c8d3e0" font-weight="400">                       /root/.pi/agent/npm/node_modules/.bin, which is not on</text>
+    <text x="22" y="267" fill="#c8d3e0" font-weight="400">                       PATH: pi-web-access-mcp, pi-subagents, pi-mcp-adapter,</text>
+    <text x="22" y="286" fill="#c8d3e0" font-weight="400">                       pi-lens, pi-lens-mcp, pi-lens-analyze</text>
+    <text x="22" y="305" fill="#7aa2f7" font-weight="600">Network</text>
+    <text x="22" y="324" fill="#4ec9a0" font-weight="400">  ✓ providers          2 endpoint(s) reachable</text>
+    <text x="22" y="343" fill="#4ec9a0" font-weight="400">  ✓ dns                1 provider host(s) resolve normally</text>
+    <text x="22" y="362" fill="#7aa2f7" font-weight="600">Config</text>
+    <text x="22" y="381" fill="#4ec9a0" font-weight="400">  ✓ settings.json      valid JSON</text>
+    <text x="22" y="400" fill="#4ec9a0" font-weight="400">  ✓ models.json        valid JSON</text>
+    <text x="22" y="419" fill="#5c6b7f" font-weight="400">  · project settings   none</text>
+    <text x="22" y="438" fill="#4ec9a0" font-weight="400">  ✓ backups            2 file(s) backed up; edited since the newest backup:</text>
+    <text x="22" y="457" fill="#c8d3e0" font-weight="400">                       settings.json, models.json</text>
+    <text x="22" y="476" fill="#4ec9a0" font-weight="400">  ✓ duplicate packages none</text>
+    <text x="22" y="495" fill="#5c6b7f" font-weight="400">  · env references     no $VAR reference in models.json credentials</text>
+    <text x="22" y="514" fill="#7aa2f7" font-weight="600">Runtime</text>
+    <text x="22" y="533" fill="#4ec9a0" font-weight="400">  ✓ node               v22.23.3</text>
+    <text x="22" y="552" fill="#4ec9a0" font-weight="400">  ✓ pi launcher        /root/.pi/agent/bin/pi</text>
+    <text x="22" y="571" fill="#4ec9a0" font-weight="400">  ✓ disk               6% used on /, 950.3 GB free</text>
+    <text x="22" y="590" fill="#4ec9a0" font-weight="400">  ✓ proxy              http://127.0.0.1:10808 accepting connections</text>
+    <text x="22" y="628" fill="#7aa2f7" font-weight="600">19 checks: 14 ok, 0 warnings, 0 failed, 5 skipped</text>
+    <text x="22" y="647" fill="#7aa2f7" font-weight="600">Run `npx pi-checkup --verbose` to show what to do about each finding.</text>
+    <text x="22" y="685" fill="#4ec9a0" font-weight="400">✓ 14 ok, 5 skipped  ·  run /checkup inside Pi for registry checks</text>
+  </g>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-checkup",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Health checks for your Pi setup: tool/command conflicts, broken packages, shadowed binaries, dead endpoints.",
   "type": "module",
   "license": "MIT",
@@ -21,7 +21,8 @@
   "pi": {
     "extensions": [
       "./src/index.js"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/xinghe-labs/pi-checkup/main/docs/demo.svg"
   },
   "bin": {
     "pi-checkup": "bin/checkup.js"
@@ -30,6 +31,7 @@
     "src/",
     "bin/",
     "scripts/",
+    "docs/",
     "README.md",
     "LICENSE"
   ],

package/src/checks/network.js

@@ -34,7 +34,7 @@ function hasCredentialHeader(headers) {
 	);
 }
 
-export async function run({ offline = false, agentDir: root, modelsFile, env = process.env, hasRuntime = false }) {
+export async function run({ offline = false, modelsFile, env = process.env, hasRuntime = false }) {
 	const results = [];
 	const models = readJson(modelsFile);
 	if (!models.ok) {
@@ -91,6 +91,11 @@ export async function run({ offline = false, agentDir: root, modelsFile, env = p
 	// hole one level up.
 	const shape = [];
 	const queryWithheld = [];
+	// Providers that declare a credential but no `baseUrl` are not endpoints to
+	// probe — Pi may have a built-in default for them — but they were dropped in
+	// silence, so a user with five providers and one baseUrl read "1 endpoint(s)
+	// reachable" and had no way to tell the other four were never looked at.
+	const noBaseUrl = [];
 	const proxy = proxyFromEnv(env);
 	for (const [name, provider] of Object.entries(providers)) {
 		if (!provider || typeof provider !== "object" || Array.isArray(provider)) {
@@ -98,11 +103,24 @@ export async function run({ offline = false, agentDir: root, modelsFile, env = p
 			continue;
 		}
 		const baseUrl = provider.baseUrl ?? provider.base_url;
-		if (baseUrl === undefined || baseUrl === null || baseUrl === "") continue;
+		if (baseUrl === undefined || baseUrl === null || baseUrl === "") {
+			noBaseUrl.push(name);
+			continue;
+		}
 		if (typeof baseUrl !== "string") {
 			shape.push(`${name} (${Array.isArray(baseUrl) ? "array" : typeof baseUrl}) — baseUrl is not a string`);
 			continue;
 		}
+		// Pi interpolates `apiKey` and header values, not `baseUrl`. A `${HOST}` here
+		// is a literal string, and `new URL` accepts it — so the probe would ask DNS
+		// for a host literally named `${HOST}`, report "does not resolve", and leave
+		// the reader to work out that the interpolation they expected never happens.
+		// Only the part before the query is examined: `?$filter=x` is OData, not an
+		// environment reference, and flagging it was noise.
+		if (/\$\{[A-Za-z_][A-Za-z0-9_]*\}|\$[A-Za-z_][A-Za-z0-9_]*/.test(baseUrl.split("?")[0])) {
+			shape.push(`${name}: baseUrl contains an environment reference, but Pi interpolates only apiKey and header values — this is the literal string`);
+			continue;
+		}
 		let url;
 		try {
 			url = new URL(baseUrl);
@@ -208,6 +226,12 @@ export async function run({ offline = false, agentDir: root, modelsFile, env = p
 
 	// Built once so offline mode can emit it too: whether a baseUrl is even a
 	// string is a property of the config, not of the probe.
+	// Named, not silently dropped: a provider with a credential but no `baseUrl`
+	// is not an endpoint to probe, and Pi may have a built-in default for it — but
+	// saying only "1 endpoint(s) reachable" left the reader unable to tell whether
+	// the other four providers were fine or were never looked at.
+	const noBaseUrlNote = noBaseUrl.length ? `; ${noBaseUrl.length} provider(s) declare no baseUrl and were not probed: ${truncateList(noBaseUrl, 4)}` : "";
+
 	const shapeRow = shapeNotes.length
 		? {
 				group,
@@ -215,7 +239,8 @@ export async function run({ offline = false, agentDir: root, modelsFile, env = p
 				title: "baseUrl shape",
 				status: "warn",
 				detail: `${shapeNotes.join("; ")} — not probed`,
-				hint: "baseUrl has to be an absolute http(s) URL as a quoted string, like \"https://api.example.com/v1\".",
+				hint: "baseUrl has to be an absolute http(s) URL as a quoted string, like \"https://api.example.com/v1\"."
+					+ " An environment reference there is not expanded: Pi interpolates only apiKey and header values.",
 			}
 		: null;
 
@@ -228,7 +253,7 @@ export async function run({ offline = false, agentDir: root, modelsFile, env = p
 				status: "skip",
 				detail: shapeNotes.length
 					? `offline mode — ${planned.length} endpoint(s) not probed; ${shapeNotes.join("; ")}`
-					: `offline mode — ${planned.length} configured endpoint(s) not probed`,
+					: `offline mode — ${planned.length} configured endpoint(s) not probed${noBaseUrlNote}`,
 				hint: "Re-run without --offline to test reachability.",
 			},
 			// Emitted as a skip rather than omitted: a row that vanishes in offline
@@ -293,7 +318,9 @@ export async function run({ offline = false, agentDir: root, modelsFile, env = p
 			status: "skip",
 			detail: shapeNotes.length
 				? `no provider with a usable baseUrl — ${shapeNotes.join("; ")}`
-				: "no provider with a baseUrl in models.json",
+				: noBaseUrl.length
+					? `no provider with a baseUrl in models.json (${truncateList(noBaseUrl, 4)} declare${noBaseUrl.length === 1 ? "s" : ""} none)`
+					: "no provider with a baseUrl in models.json",
 		});
 	} else if (!unhealthy.length && unprobed.length) {
 		// Nothing was sent, so there is nothing to call healthy — but when some
@@ -306,13 +333,13 @@ export async function run({ offline = false, agentDir: root, modelsFile, env = p
 			status: "skip",
 			detail: `${answered ? `${answered} endpoint(s) reachable; ` : ""}${unprobed.map((o) => o.detail).join("; ")}`,
 		});
-	} else if (!unhealthy.length) {
+		} else if (!unhealthy.length) {
 		results.push({
 			group,
 			id: "providers",
 			title: "providers",
-		status: "ok",
-			detail: `${probed} endpoint(s) reachable`,
+			status: "ok",
+			detail: `${probed} endpoint(s) reachable${noBaseUrlNote}`,
 		});
 	} else {
 		results.push({
@@ -320,7 +347,7 @@ export async function run({ offline = false, agentDir: root, modelsFile, env = p
 			id: "providers",
 			title: "providers",
 			status: unhealthy.some((o) => o.status === "fail") ? "fail" : "warn",
-			detail: `${unhealthy.length} of ${probed} unhealthy: ${truncateList(unhealthy.map((o) => o.name), 6)}`,
+			detail: `${unhealthy.length} of ${probed} unhealthy: ${truncateList(unhealthy.map((o) => o.name), 6)}${noBaseUrlNote}`,
 			// An outcome that knows why it failed brings its own advice; the generic
 			// sentence is only for the ones that do not (a refused connection, a
 			// timeout) and for the ones that sit next to them.

package/src/repair.js

@@ -170,11 +170,35 @@ function unreadable(target, parsed) {
 	return { ok: false, message: `${name} could not be read: ${parsed.error}` };
 }
 
+/**
+ * Identity of a file at one moment: size plus mtime, or null when it is gone.
+ *
+ * Two `--fix` processes that read the same file and then both write it leave
+ * whichever finished last as the content, computed from the older of the two
+ * reads. There is no lock, and a lock file brings its own problems (stale locks,
+ * a crash leaving one behind). This is the cheaper guard: capture the identity
+ * before reading, re-check it immediately before the write, and refuse when the
+ * file moved underneath.
+ */
+function fileStamp(target) {
+	try {
+		const st = fs.statSync(target);
+		return `${st.size}:${st.mtimeMs}`;
+	} catch {
+		return null;
+	}
+}
+
+function changedSince(target, stamp) {
+	return fileStamp(target) !== stamp;
+}
+
 export function applyRestoreConfig(target) {
 	// Re-read before overwriting. The decision to restore was made when the check
 	// ran, and in-session the confirmation prompt can sit open indefinitely: if the
 	// user repaired the file by hand in that window, writing the older backup over
 	// it would undo the fix.
+	const before = fileStamp(target);
 	const current = readJson(target);
 	if (current.ok) return { ok: false, message: `${path.basename(target)} is valid JSON again — nothing to restore` };
 	const candidates = backupsNewestFirst(target);
@@ -199,6 +223,9 @@ export function applyRestoreConfig(target) {
 		return { ok: false, message: `nothing to restore from: ${rejected.join("; ")}` };
 	}
 	const skipped = candidates.indexOf(backup);
+	if (changedSince(target, before)) {
+		return { ok: false, message: `${path.basename(target)} changed while checkup was running — not restoring over it. Re-run to see the current state.` };
+	}
 	const aside = copyBackup(target, "broken");
 	// The backup is valid JSON (checked above), so restoring its bytes verbatim
 	// keeps any formatting the user had. If the write itself fails after the
@@ -233,6 +260,7 @@ export function applyRestoreConfig(target) {
  * recoverable, but a repair that needs its backup is not a repair.
  */
 export function applyDedupePackages(target, options = {}) {
+	const before = fileStamp(target);
 	const settings = readJson(target);
 	if (!settings.ok) return unreadable(target, settings);
 	if (!Array.isArray(settings.data?.packages)) return { ok: false, message: "no packages array to dedupe" };
@@ -249,6 +277,9 @@ export function applyDedupePackages(target, options = {}) {
 	// between — a second read would prove nothing. Backing up before the plan was
 	// known left a stray `.checkup-bak-*` beside a healthy config on runs that
 	// repaired nothing.
+	if (changedSince(target, before)) {
+		return { ok: false, message: `${path.basename(target)} changed while checkup was running — not writing over it. Re-run to see the current state.` };
+	}
 	const backup = backupFor(target, options.backups);
 	settings.data.packages = plan.kept;
 	writeAtomic(target, `${JSON.stringify(settings.data, null, 2)}\n`);
@@ -298,6 +329,7 @@ export function applyPruneMissingPackages(target, root, options = {}) {
 	// Not defaulted: a wrong root makes every entry look missing, and this repair
 	// deletes what it cannot resolve.
 	if (!root) throw new Error("applyPruneMissingPackages needs the agent directory to resolve packages against");
+	const before = fileStamp(target);
 	const settings = readJson(target);
 	if (!settings.ok) return unreadable(target, settings);
 	if (!Array.isArray(settings.data?.packages)) return { ok: false, message: "no packages array to prune" };
@@ -324,6 +356,9 @@ export function applyPruneMissingPackages(target, root, options = {}) {
 
 	// Same reasoning as dedupe: the read above is post-prompt, and the rest of
 	// this function is synchronous.
+	if (changedSince(target, before)) {
+		return { ok: false, message: `${path.basename(target)} changed while checkup was running — not writing over it. Re-run to see the current state.` };
+	}
 	const backup = backupFor(target, options.backups);
 	settings.data.packages = plan.kept;
 	writeAtomic(target, `${JSON.stringify(settings.data, null, 2)}\n`);