@stacknyu/pi-check 0.0.0-stage → 1.1.0

package/lib/util.mjs

@@ -0,0 +1,395 @@
+// Shared helpers: paths, git, hashing, globs, processes.
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, statSync, writeFileSync, renameSync, appendFileSync } from "node:fs";
+import { cpus, homedir } from "node:os";
+import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+export const STATE_DIR = ".pi-check";
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+export const HOME_DIR = join(process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent"), "pi-check");
+export const SHIM_DIR = join(HOME_DIR, "shims");
+
+export const CPUS = Math.max(1, cpus()?.length || 2);
+
+// ---------- small io ----------
+
+export function readText(p) {
+	try {
+		return readFileSync(p, "utf8");
+	} catch {
+		return "";
+	}
+}
+
+export function loadJson(p, fallback = undefined) {
+	try {
+		return JSON.parse(readFileSync(p, "utf8"));
+	} catch {
+		return fallback;
+	}
+}
+
+export function writeJson(p, data) {
+	mkdirSync(dirname(p), { recursive: true });
+	const tmp = `${p}.${process.pid}.tmp`;
+	writeFileSync(tmp, JSON.stringify(data, null, 2));
+	renameSync(tmp, p);
+}
+
+export function ensureDir(p) {
+	mkdirSync(p, { recursive: true });
+	return p;
+}
+
+/** JSON with comments and trailing commas (tsconfig, etc). */
+export function parseJsonc(text) {
+	let out = "";
+	let i = 0;
+	let inStr = false;
+	while (i < text.length) {
+		const c = text[i];
+		const n = text[i + 1];
+		if (inStr) {
+			out += c;
+			if (c === "\\") {
+				out += n ?? "";
+				i += 2;
+				continue;
+			}
+			if (c === '"') inStr = false;
+			i++;
+			continue;
+		}
+		if (c === '"') {
+			inStr = true;
+			out += c;
+			i++;
+			continue;
+		}
+		if (c === "/" && n === "/") {
+			while (i < text.length && text[i] !== "\n") i++;
+			continue;
+		}
+		if (c === "/" && n === "*") {
+			i += 2;
+			while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++;
+			i += 2;
+			continue;
+		}
+		out += c;
+		i++;
+	}
+	out = out.replace(/,(\s*[}\]])/g, "$1");
+	try {
+		return JSON.parse(out);
+	} catch {
+		return undefined;
+	}
+}
+
+export function loadJsonc(p) {
+	const t = readText(p);
+	return t ? parseJsonc(t) : undefined;
+}
+
+// ---------- paths ----------
+
+export const toPosix = (p) => (sep === "/" ? p : p.split(sep).join("/"));
+export const rel = (from, to) => toPosix(relative(from, to)) || ".";
+
+export function isUnder(relPath, dir) {
+	if (!dir || dir === ".") return true;
+	return relPath === dir || relPath.startsWith(dir + "/");
+}
+
+export function parentDirs(relPath) {
+	// "a/b/c.ts" -> ["a/b", "a", "."]
+	const out = [];
+	let d = relPath.includes("/") ? relPath.slice(0, relPath.lastIndexOf("/")) : ".";
+	while (true) {
+		out.push(d);
+		if (d === ".") break;
+		d = d.includes("/") ? d.slice(0, d.lastIndexOf("/")) : ".";
+	}
+	return out;
+}
+
+export const dirOf = (relPath) => (relPath.includes("/") ? relPath.slice(0, relPath.lastIndexOf("/")) : ".");
+export const baseOf = (relPath) => relPath.slice(relPath.lastIndexOf("/") + 1);
+export const joinRel = (a, b) => (a === "." || !a ? b : b === "." ? a : `${a}/${b}`);
+
+export function normRel(p) {
+	const parts = [];
+	for (const seg of toPosix(p).split("/")) {
+		if (!seg || seg === ".") continue;
+		if (seg === "..") parts.pop();
+		else parts.push(seg);
+	}
+	return parts.join("/") || ".";
+}
+
+// ---------- git ----------
+
+export function git(cwd, args, opts = {}) {
+	const r = spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: 256 * 1024 * 1024, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" }, ...opts });
+	return { ok: r.status === 0, out: (r.stdout ?? "").toString(), err: (r.stderr ?? "").toString() };
+}
+
+/** The checkout this path is in, and the repo's main checkout (shared by all worktrees). */
+export function repoRoots(cwd) {
+	const top = git(cwd, ["rev-parse", "--show-toplevel"]);
+	if (!top.ok) return undefined;
+	const root = top.out.trim();
+	const common = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+	let main = root;
+	if (common.ok) {
+		const c = common.out.trim();
+		if (c.endsWith("/.git") || c.endsWith(`${sep}.git`)) main = dirname(c);
+	}
+	return { root, main };
+}
+
+// ---------- hashing ----------
+
+export const sha = (s, algo = "sha256") => createHash(algo).update(s).digest("hex");
+
+/** Content hashes with an (mtime, size, inode) memo, so unchanged files are never re-read. */
+export class FileHasher {
+	constructor() {
+		this.memo = new Map();
+		this.reads = 0;
+	}
+	hash(abs) {
+		let st;
+		try {
+			st = statSync(abs);
+		} catch {
+			this.memo.delete(abs);
+			return "-";
+		}
+		if (!st.isFile()) return "d";
+		const m = this.memo.get(abs);
+		if (m && m.mtimeMs === st.mtimeMs && m.size === st.size && m.ino === st.ino) return m.hash;
+		let hash;
+		try {
+			hash = createHash("sha1").update(readFileSync(abs)).digest("hex");
+			this.reads++;
+		} catch {
+			hash = "-";
+		}
+		this.memo.set(abs, { mtimeMs: st.mtimeMs, size: st.size, ino: st.ino, hash });
+		if (this.memo.size > 400000) this.memo.clear();
+		return hash;
+	}
+	/** Read a text file through the same memo (used for import scanning). */
+	text(abs) {
+		return readText(abs);
+	}
+}
+
+// ---------- globs ----------
+
+const globCache = new Map();
+export function globToRegex(glob) {
+	let g = globCache.get(glob);
+	if (g) return g;
+	let re = "";
+	let i = 0;
+	while (i < glob.length) {
+		const c = glob[i];
+		if (c === "*") {
+			if (glob[i + 1] === "*") {
+				const slash = glob[i + 2] === "/";
+				re += slash ? "(?:.*/)?" : ".*";
+				i += slash ? 3 : 2;
+				continue;
+			}
+			re += "[^/]*";
+		} else if (c === "?") re += "[^/]";
+		else if (c === "{") {
+			const end = glob.indexOf("}", i);
+			if (end > i) {
+				re += `(?:${glob
+					.slice(i + 1, end)
+					.split(",")
+					.map((s) => s.replace(/[.+^$()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*"))
+					.join("|")})`;
+				i = end + 1;
+				continue;
+			}
+			re += "\\{";
+		} else if (".+^$()|[]\\".includes(c)) re += `\\${c}`;
+		else re += c;
+		i++;
+	}
+	g = new RegExp(`^${re}$`);
+	globCache.set(glob, g);
+	return g;
+}
+
+export const matchGlob = (glob, relPath) => globToRegex(glob).test(relPath);
+export const matchAny = (globs, relPath) => (globs ?? []).some((g) => matchGlob(g, relPath));
+
+// ---------- processes ----------
+
+export function which(cmd, { skipDir, pathEnv = process.env.PATH ?? "" } = {}) {
+	if (isAbsolute(cmd)) return existsSync(cmd) ? cmd : undefined;
+	for (const d of pathEnv.split(delimiter)) {
+		if (!d || (skipDir && resolve(d) === resolve(skipDir))) continue;
+		const p = join(d, cmd);
+		try {
+			accessSync(p, constants.X_OK);
+			if (statSync(p).isFile()) return p;
+		} catch {}
+	}
+	return undefined;
+}
+
+/** First executable named `name` in node_modules/.bin from dir up to stopAt (inclusive), then alt roots. */
+export function findBin(name, absDir, stopAt, alsoTry = []) {
+	const tryDirs = [];
+	let d = absDir;
+	while (true) {
+		tryDirs.push(d);
+		if (d === stopAt || dirname(d) === d) break;
+		d = dirname(d);
+	}
+	for (const extra of alsoTry) if (extra) tryDirs.push(extra);
+	for (const dir of tryDirs) {
+		const p = join(dir, "node_modules", ".bin", name);
+		if (existsSync(p)) return p;
+	}
+	return undefined;
+}
+
+export const NICE = which("nice");
+
+/**
+ * Run a process in its own process group. Resolves { code, stdout, stderr, killed, ms }.
+ * `signal` (AbortSignal) kills the whole group.
+ */
+export function runProc({ cmd, args = [], cwd, env, signal, timeoutMs, nice = 10, onData, maxBytes = 8 * 1024 * 1024 }) {
+	return new Promise((resolveP) => {
+		const started = Date.now();
+		const argv = nice && NICE ? [NICE, "-n", String(nice), cmd, ...args] : [cmd, ...args];
+		let child;
+		try {
+			child = spawn(argv[0], argv.slice(1), { cwd, env, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+		} catch (e) {
+			resolveP({ code: 127, stdout: "", stderr: String(e?.message ?? e), killed: false, ms: 0 });
+			return;
+		}
+		let stdout = "";
+		let stderr = "";
+		let killed = false, killTimer;
+		const cap = (buf, add) => {
+			buf += add;
+			return buf.length > maxBytes ? buf.slice(buf.length - maxBytes) : buf;
+		};
+		child.stdout.on("data", (d) => {
+			const s = d.toString();
+			stdout = cap(stdout, s);
+			onData?.(s, "stdout");
+		});
+		child.stderr.on("data", (d) => {
+			const s = d.toString();
+			stderr = cap(stderr, s);
+			onData?.(s, "stderr");
+		});
+		const kill = () => {
+			if (killed) return;
+			killed = true;
+			try {
+				process.kill(-child.pid, "SIGTERM");
+			} catch {}
+			killTimer = setTimeout(() => {
+				try {
+					process.kill(-child.pid, "SIGKILL");
+				} catch {}
+			}, 3000).unref();
+		};
+		const onAbort = () => kill();
+		signal?.addEventListener("abort", onAbort);
+		if (signal?.aborted) kill();
+		const timer = timeoutMs ? setTimeout(kill, timeoutMs) : undefined;
+		child.on("error", (e) => {
+			stderr += String(e?.message ?? e);
+		});
+		child.on("close", (code) => {
+			if (timer) clearTimeout(timer);
+			clearTimeout(killTimer);
+			signal?.removeEventListener("abort", onAbort);
+			resolveP({ code: code ?? (killed ? 143 : 1), stdout, stderr, killed, ms: Date.now() - started });
+		});
+	});
+}
+
+/** Environment for checks: no npm/pnpm script variables leaking from whoever started the broker. */
+const POLLUTED = /^(npm_.*|PNPM_.*|pnpm_.*|INIT_CWD|NODE_ENV|NODE_OPTIONS|NEXT_.*|PORT|HOSTNAME|PI_WEB_.*|PI_CHECK_SHIM_DIR|VITEST.*|JEST_WORKER_ID)$/;
+export function cleanEnv(extra = {}) {
+	const env = {};
+	for (const [k, v] of Object.entries(process.env)) if (!POLLUTED.test(k)) env[k] = v;
+	return { ...env, ...extra };
+}
+
+/** PATH as the user's login shell sets it (Homebrew, Go, pyenv…), merged into this process once. */
+export function adoptLoginPath() {
+	const sh = process.env.SHELL || "/bin/sh";
+	try {
+		const r = spawnSync(sh, ["-lc", 'printf "%s" "$PATH"'], { encoding: "utf8", timeout: 8000 });
+		const login = (r.stdout ?? "").trim();
+		if (!login) return;
+		const cur = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+		const add = login.split(delimiter).filter((d) => d && !cur.includes(d));
+		if (add.length) process.env.PATH = [...cur, ...add].join(delimiter);
+	} catch {}
+}
+
+export function parseDuration(v, fallbackMs) {
+	if (v == null || v === "") return fallbackMs;
+	if (typeof v === "number") return v * 1000;
+	const m = String(v).match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/);
+	if (!m) return fallbackMs;
+	const n = Number(m[1]);
+	return n * ({ ms: 1, s: 1000, m: 60000, h: 3600000 }[m[2] ?? "s"] ?? 1000);
+}
+
+export function fmtMs(ms) {
+	if (ms < 1000) return `${Math.round(ms)}ms`;
+	const s = ms / 1000;
+	if (s < 90) return `${s.toFixed(s < 10 ? 1 : 0)}s`;
+	const m = Math.floor(s / 60);
+	return `${m}m${String(Math.round(s % 60)).padStart(2, "0")}s`;
+}
+
+export function tailLines(text, n) {
+	const lines = String(text ?? "").replace(/\s+$/, "").split("\n");
+	return lines.length <= n ? lines.join("\n") : `… (${lines.length - n} earlier lines)\n${lines.slice(-n).join("\n")}`;
+}
+
+export function headLines(text, n) {
+	const lines = String(text ?? "").replace(/\s+$/, "").split("\n");
+	return lines.length <= n ? lines.join("\n") : `${lines.slice(0, n).join("\n")}\n… (${lines.length - n} more lines)`;
+}
+
+export const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+
+export function logTo(file) {
+	return (...parts) => {
+		const line = `${new Date().toISOString()} ${parts.map((p) => (typeof p === "string" ? p : JSON.stringify(p))).join(" ")}\n`;
+		try {
+			appendFileSync(file, line);
+		} catch {}
+	};
+}
+
+export function pidAlive(pid) {
+	if (!pid) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e) {
+		return e?.code === "EPERM";
+	}
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@stacknyu/pi-check",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.0",
+  "description": "One shared, cached, speculative check runner per repo for every Pi session and worktree: Go, TypeScript/JavaScript and Python tests, type checks and linters run once per file content, pre-run while you edit, and throttled so parallel agents stop fighting for the CPU.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacknyu/stack-pi-plugins.git",
+    "directory": "packages/pi-check"
+  },
+  "homepage": "https://github.com/stacknyu/stack-pi-plugins/tree/main/packages/pi-check#readme",
+  "bugs": {
+    "url": "https://github.com/stacknyu/stack-pi-plugins/issues"
+  },
+  "files": [
+    "extension.ts",
+    "cli.mjs",
+    "lib",
+    "skills",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "pi-package"
+  ],
+  "bin": {
+    "pi-check": "./cli.mjs"
+  },
+  "pi": {
+    "extensions": [
+      "./extension.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*",
+    "typebox": "*"
+  }
 }

package/skills/pi-check/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: pi-check
+description: How the shared check broker (pi-check) works — the check tool, reading its report, pre-existing failures, configuring pi-check.json, and fixing slow or wrong checks. Use when running tests/typecheck/lint, when a check result is confusing, or when the user asks about pi-check, /check, check speed or CPU load.
+---
+
+# pi-check
+
+One broker per repo runs every test, type check and lint for all sessions and worktrees. Results are keyed by file content, so identical work runs once and is shared.
+
+## Running checks
+
+- Use the `check` tool, not `go test` / `pytest` / `vitest` / `tsc` / `eslint` / `ruff` in bash.
+  - Default scope: what your changes affect, compared with the base branch.
+  - `scope: "all"`: everything.
+  - `files: [...]`: only checks that depend on those files.
+  - `kinds: ["test"]` / `projects: ["apps/x"]` narrow it further.
+- Run it after a meaningful batch of edits. The broker already runs affected checks in the background while you edit, so results are often instant.
+- Raw commands in bash still work: they are routed through the broker. Commands that change files (`--fix`, `-u`, `install`) run normally.
+
+## Reading the report
+
+```
+pi-check · w2 · scope: changed vs main · 41 units: 8 ran, 28 cached, 5 shared · 3m12s
+✗ go apps/api · test: 36/37 pass — 2 pre-existing failures (also fail on base)
+   ✗ example.com/api/billing TestInvoiceTotals
+     invoice_test.go:42: got 10, want 12
+RESULT: FAIL — 1 new failure
+```
+
+- **cached / shared**: the result came from an identical earlier run, here or in another checkout. It is as valid as a fresh run.
+- **new failure**: not failing on the base branch. Yours to fix.
+- **pre-existing**: also fails on the base branch. Don't fix it unless that is your task. It doesn't fail the check.
+- **"files changed during the run"**: the result may not match the current files. Run `check` again.
+- **could not run** (tool missing, timeout): an environment problem, not a code verdict. Mention it, don't loop on it.
+
+## For the user
+
+- `/check`: what runs, what waits, time saved.
+- `/check baseline`: records pre-existing failures from the main checkout.
+- `/check known`: lists them.
+- `/check run all`: runs everything.
+- `/check init`: writes `pi-check.json` to commit and tune.
+- In `pi-check.json`:
+  - `projects.<dir>.<kind>`: `false` to disable, or `{ timeout, env, args, inputs, exclude, parallel }`.
+  - `maxJobs`: maximum concurrent jobs (0 = CPU budget).
+  - `cpuBudget`: total cooperative allocation (0 = available cores), independent of agent count.
+  - `threads`: per-job ceiling (0 = divide spare allocation at dispatch).
+  - `fastLane`: reserves one total job slot/CPU for short work when capacity permits. Three slots allow two heavy jobs plus one fast job; two slots allow one of each. It never preempts running requested work.
+  - `projects.<dir>.<kind>.lane` / `custom[].lane`: `fast` or `heavy`; put slow integration suites/large typechecks in heavy. Native lint/vet/typechecks/TS tests and recognizable raw type/lint/Node-test commands default fast; builds/Go tests/unknown commands default heavy.
+  - `warmBase`: full-suite cache warming, off by default; normal speculation is affected-only.
+  - `speculate`: ahead-of-time runs.
+  - `intercept`: `route` | `block` | `off`.
+  - `ignore`: globs that are never inputs.
+  - `custom`: extra checks.
+- After editing `pi-check.json`: `/check reload`. It waits for requested work to finish; active checks are not restarted. Source-code updates need a fresh broker process after a natural idle exit; config reload alone cannot hot-swap JavaScript.
+- Broker errors are not permission to launch competing direct checks. Inspect status first. An upgrade must wait for active checks to finish.
+- Whole-command jobs hold their own allocation; nested shims execute inside it. Prefer native units for fine-grained cache sharing.
+- Progress includes the latest Go test event and elapsed time. Reused unit-runtime is not elapsed time saved.
+
+## When something is off
+
+- **A change didn't rerun a test that reads a file at run time:** add that file's glob to the project's `inputs`.
+- **A unit keeps rerunning by itself:** its tests write files into the repo. Git-ignore them, or add them to `ignore`.
+- **Go tests time out:** set `projects.<module dir>.test.timeout` (e.g. `"30m"`). Timeouts are never cached.
+- **The machine is still busy:** lower `maxJobs`, set `speculate: false`, or raise `nice`.
+- **Wrong "pre-existing" list:**
+  - `/check known clear`, then `/check baseline`.
+  - "Pre-existing" means failing on the base branch tip, in the main checkout (or an identical worktree).
+- **The broker misbehaves:** `/check log`, then `/check restart`. The cache is in `.pi-check/cache/`. `pi-check forget` clears it.