pi-harness-runtime 1.1.406 → 1.1.407

package/packages/tooling-preference/src/quality-check.ts

@@ -0,0 +1,279 @@
+/**
+ * The post-change quality check of a JavaScript/TypeScript workspace.
+ *
+ * The check honors the saved preference: "prefer_biome" runs Biome on the
+ * changed files, "use_project_tools" runs the project's own lint script.
+ * The check never writes: it reports what it found and the agent fixes it.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ToolingContext } from "./detect.js";
+import type { ToolingPreference } from "./proposal.js";
+
+/** The tool that checks the changed files. */
+export type QualityCheckTool = "biome" | "project" | "none";
+
+export interface QualityCheckPlan {
+	/** The tool that would run. */
+	tool: QualityCheckTool;
+	/** The binary to run - never a shell string. */
+	command: string | null;
+	/** The arguments of the command. */
+	args: string[];
+	/** The files the check looks at. */
+	files: string[];
+	/** Why this plan - a human wording. */
+	reason: string;
+}
+
+export interface QualityCheckResult {
+	/** Did the check run? */
+	ran: boolean;
+	/** Did the check pass? Meaningless when the check did not run. */
+	passed: boolean;
+	/** The tool that ran. */
+	tool: QualityCheckTool;
+	/** How many files the check looked at. */
+	fileCount: number;
+	/** The exit code of the check. */
+	exitCode: number | null;
+	/** Did the check hit the timeout? */
+	timedOut: boolean;
+	/** The output of the check, truncated. */
+	output: string;
+	/** Why the result is what it is - a human wording. */
+	reason: string;
+}
+
+/** A command to run: the binary and its arguments, never a shell string. */
+interface CommandSpec {
+	command: string;
+	args: string[];
+}
+
+/** How the tool is started with the package manager of the workspace. */
+function packageRunner(packageManager: string | null, binary: string): CommandSpec {
+	switch (packageManager) {
+		case "bun":
+			return { command: "bunx", args: [binary] };
+		case "pnpm":
+			return { command: "pnpm", args: ["exec", binary] };
+		case "yarn":
+			return { command: "yarn", args: [binary] };
+		case "npm":
+			return { command: "npx", args: ["--no-install", binary] };
+		default:
+			return { command: binary, args: [] };
+	}
+}
+
+/** How a package script is started with the package manager of the workspace. */
+function scriptRunner(packageManager: string | null, script: string): CommandSpec {
+	switch (packageManager) {
+		case "bun":
+			return { command: "bun", args: ["run", script] };
+		case "pnpm":
+			return { command: "pnpm", args: ["run", script] };
+		case "yarn":
+			return { command: "yarn", args: [script] };
+		default:
+			return { command: "npm", args: ["run", script] };
+	}
+}
+
+/** The scripts of the workspace, if it has a package.json. */
+export function readWorkspaceScripts(root: string): Record<string, string> {
+	try {
+		const path = join(root, "package.json");
+		if (!existsSync(path)) return {};
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as {
+			scripts?: Record<string, string>;
+		};
+		const scripts = parsed?.scripts;
+		if (!scripts || typeof scripts !== "object") return {};
+		return scripts;
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Choose the check that runs after a change.
+ *
+ * The preference decides the tool: Biome when the user asked for it, the
+ * project's own script otherwise. A workspace without a saved decision is
+ * never checked - the user has not chosen a tool yet.
+ */
+export function selectQualityCheck(options: {
+	context: ToolingContext;
+	preference: ToolingPreference | undefined;
+	files: string[];
+	scripts?: Record<string, string>;
+}): QualityCheckPlan {
+	const { context, preference, files } = options;
+	const scripts = options.scripts ?? readWorkspaceScripts(context.root);
+
+	const none = (reason: string): QualityCheckPlan => ({
+		tool: "none",
+		command: null,
+		args: [],
+		files: [],
+		reason,
+	});
+
+	if (files.length === 0) {
+		return none("no JavaScript/TypeScript file changed");
+	}
+	if (!preference) {
+		return none("the user has not chosen a tool yet");
+	}
+
+	const projectScript = (): { script: string; spec: CommandSpec } | null => {
+		for (const name of ["lint", "typecheck"]) {
+			if (typeof scripts[name] === "string") {
+				return { script: name, spec: scriptRunner(context.packageManager, name) };
+			}
+		}
+		return null;
+	};
+
+	if (preference === "prefer_biome") {
+		if (!context.usesBiome) {
+			// The user asked for Biome, but the workspace does not have it
+			// (yet). The project's own tool is the honest fallback.
+			const fallback = projectScript();
+			if (!fallback) {
+				return none("Biome is not installed and the project has no lint script");
+			}
+			return {
+				tool: "project",
+				command: fallback.spec.command,
+				args: fallback.spec.args,
+				files,
+				reason: `Biome is not installed yet - the project script "${fallback.script}" runs instead`,
+			};
+		}
+		const runner = packageRunner(context.packageManager, "biome");
+		return {
+			tool: "biome",
+			command: runner.command,
+			args: [...runner.args, "check", ...files],
+			files,
+			reason: "the preference asks for Biome",
+		};
+	}
+
+	const script = projectScript();
+	if (!script) {
+		return none("the project has neither a lint nor a typecheck script");
+	}
+	return {
+		tool: "project",
+		command: script.spec.command,
+		args: script.spec.args,
+		files,
+		reason: `the project script "${script.script}" runs`,
+	};
+}
+
+/**
+ * Run the check.
+ *
+ * The command is started without a shell, with a timeout, and it never
+ * writes: a check that wants to fix files is not a check.
+ */
+export function runQualityCheck(
+	plan: QualityCheckPlan,
+	options: { cwd: string; timeoutMs?: number; maxOutputChars?: number },
+): QualityCheckResult {
+	const maxOutputChars = options.maxOutputChars ?? 2000;
+	const base = {
+		tool: plan.tool,
+		fileCount: plan.files.length,
+	};
+
+	if (!plan.command) {
+		return {
+			...base,
+			ran: false,
+			passed: false,
+			exitCode: null,
+			timedOut: false,
+			output: "",
+			reason: plan.reason,
+		};
+	}
+
+	try {
+		const result = spawnSync(plan.command, plan.args, {
+			cwd: options.cwd,
+			encoding: "utf8",
+			timeout: options.timeoutMs ?? 60_000,
+			maxBuffer: 8 * 1024 * 1024,
+			shell: false,
+			env: { ...process.env, CI: process.env.CI ?? "1" },
+		});
+		const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+		const error = result.error;
+		const timedOut = Boolean(error && /ETIMEDOUT/i.test(String(error.message)));
+		const exitCode = result.status ?? null;
+
+		if (error && !timedOut) {
+			// The binary does not exist: the check never started.
+			return {
+				...base,
+				ran: false,
+				passed: false,
+				exitCode: null,
+				timedOut: false,
+				output: output.slice(0, maxOutputChars),
+				reason: `the check could not start: ${String(error.message).slice(0, 200)}`,
+			};
+		}
+
+		let reason = "the check reported problems";
+		if (timedOut) {
+			reason = "the check hit the timeout";
+		} else if (exitCode === 0) {
+			reason = "the check passed";
+		}
+		return {
+			...base,
+			ran: true,
+			passed: !timedOut && exitCode === 0,
+			exitCode,
+			timedOut,
+			output: output.slice(0, maxOutputChars),
+			reason,
+		};
+	} catch (error) {
+		return {
+			...base,
+			ran: false,
+			passed: false,
+			exitCode: null,
+			timedOut: false,
+			output: "",
+			reason: `the check could not start: ${String(error).slice(0, 200)}`,
+		};
+	}
+}
+
+/**
+ * The status line of the check.
+ *
+ * The line stays plain ASCII: it is read by the pi host and by terminals
+ * without a font of their own.
+ */
+export function formatQualityCheckStatus(result: QualityCheckResult): string {
+	if (!result.ran) {
+		return `[TOOL] no check: ${result.reason}`;
+	}
+	const tool = result.tool === "biome" ? "biome" : "project lint";
+	if (result.timedOut) {
+		return `[TOOL] ${tool}: ${result.fileCount} file(s), timeout`;
+	}
+	return `[TOOL] ${tool}: ${result.fileCount} file(s), ${result.passed ? "ok" : "failed"}`;
+}

package/packages/tooling-preference/tests/changed-files.test.ts

@@ -0,0 +1,124 @@
+/**
+ * The changed JavaScript/TypeScript files of a workspace.
+ *
+ * The detection reads the worktree of the session: a file that changed is
+ * a file the check may read. A workspace without git yields nothing - the
+ * harness never guesses which files belong to the session.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	detectChangedJsTsFiles,
+	isIgnoredPath,
+	isJsTsFile,
+	parseGitStatus,
+} from "../src/changed-files.js";
+
+let root = "";
+
+function git(...args: string[]): void {
+	execFileSync("git", args, { cwd: root, stdio: "ignore" });
+}
+
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "tooling-changed-"));
+	git("init", "-q");
+	git("config", "user.email", "test@example.com");
+	git("config", "user.name", "Test");
+});
+
+afterEach(() => {
+	rmSync(root, { recursive: true, force: true });
+});
+
+describe("the changed file detection", () => {
+	it("finds the JavaScript and TypeScript files of the worktree", () => {
+		mkdirSync(join(root, "src"), { recursive: true });
+		writeFileSync(join(root, "src", "app.ts"), "export const a = 1;\n");
+		writeFileSync(join(root, "src", "app.tsx"), "export const B = 1;\n");
+		writeFileSync(join(root, "src", "notes.md"), "# notes\n");
+		writeFileSync(join(root, "src", "styles.css"), "body {}\n");
+
+		const result = detectChangedJsTsFiles(root);
+
+		expect(result.detected).toBe(true);
+		expect(result.files).toEqual(["src/app.ts", "src/app.tsx"]);
+	});
+
+	it("finds the files that were changed after the commit", () => {
+		writeFileSync(join(root, "a.ts"), "export const a = 1;\n");
+		git("add", ".");
+		git("commit", "-q", "-m", "first");
+		writeFileSync(join(root, "a.ts"), "export const a = 2;\n");
+
+		const result = detectChangedJsTsFiles(root);
+
+		expect(result.files).toEqual(["a.ts"]);
+	});
+
+	it("finds a file that was renamed", () => {
+		writeFileSync(join(root, "old.ts"), "export const a = 1;\n");
+		git("add", ".");
+		git("commit", "-q", "-m", "first");
+		git("mv", "old.ts", "new.ts");
+
+		const result = detectChangedJsTsFiles(root);
+
+		expect(result.files).toEqual(["new.ts"]);
+	});
+
+	it("ignores the files of a build directory", () => {
+		mkdirSync(join(root, "dist"), { recursive: true });
+		writeFileSync(join(root, "dist", "bundle.js"), "// built\n");
+
+		const result = detectChangedJsTsFiles(root);
+
+		expect(result.files).toEqual([]);
+	});
+
+	it("yields nothing in a workspace that is not a repository", () => {
+		const plain = mkdtempSync(join(tmpdir(), "tooling-plain-"));
+		try {
+			writeFileSync(join(plain, "app.ts"), "export const a = 1;\n");
+
+			const result = detectChangedJsTsFiles(plain);
+
+			expect(result.detected).toBe(false);
+			expect(result.files).toEqual([]);
+		} finally {
+			rmSync(plain, { recursive: true, force: true });
+		}
+	});
+});
+
+describe("the git status parser", () => {
+	it("reads the path of every record", () => {
+		const output = " M src/app.ts\0?? src/new.ts\0";
+		expect(parseGitStatus(output)).toEqual(["src/app.ts", "src/new.ts"]);
+	});
+
+	it("skips the original path of a rename", () => {
+		const output = "R  src/new.ts\0src/old.ts\0";
+		expect(parseGitStatus(output)).toEqual(["src/new.ts"]);
+	});
+});
+
+describe("the file filters", () => {
+	it("knows the JavaScript and TypeScript extensions", () => {
+		expect(isJsTsFile("src/app.ts")).toBe(true);
+		expect(isJsTsFile("src/app.tsx")).toBe(true);
+		expect(isJsTsFile("src/app.mjs")).toBe(true);
+		expect(isJsTsFile("src/app.json")).toBe(false);
+		expect(isJsTsFile("README.md")).toBe(false);
+	});
+
+	it("knows the directories that hold no source", () => {
+		expect(isIgnoredPath("node_modules/pkg/index.js")).toBe(true);
+		expect(isIgnoredPath("dist/bundle.js")).toBe(true);
+		expect(isIgnoredPath("src/app.ts")).toBe(false);
+	});
+});

package/packages/tooling-preference/tests/quality-check.test.ts

@@ -0,0 +1,272 @@
+/**
+ * The post-change quality check.
+ *
+ * The saved preference decides the tool: Biome when the user asked for it,
+ * the project's own script otherwise. The check never writes and never runs
+ * without a decision of the user.
+ */
+
+import { describe, it, expect, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	formatQualityCheckStatus,
+	runQualityCheck,
+	selectQualityCheck,
+} from "../src/quality-check.js";
+import type { ToolingContext } from "../src/detect.js";
+
+const cleanups: string[] = [];
+
+function workspace(pkg: unknown, files: Record<string, string> = {}): string {
+	const root = mkdtempSync(join(tmpdir(), "tooling-check-"));
+	cleanups.push(root);
+	writeFileSync(join(root, "package.json"), JSON.stringify(pkg), "utf8");
+	for (const [name, content] of Object.entries(files)) {
+		writeFileSync(join(root, name), content, "utf8");
+	}
+	return root;
+}
+
+function context(root: string, overrides: Partial<ToolingContext> = {}): ToolingContext {
+	return {
+		root,
+		hasPackageJson: true,
+		isJavaScriptTypeScript: true,
+		isNextJs: false,
+		isReact: false,
+		usesBiome: false,
+		usesEslint: true,
+		usesPrettier: false,
+		packageManager: "npm",
+		frameworks: [],
+		...overrides,
+	};
+}
+
+afterEach(() => {
+	while (cleanups.length > 0) {
+		const root = cleanups.pop();
+		if (root) rmSync(root, { recursive: true, force: true });
+	}
+});
+
+describe("the check selection", () => {
+	it("runs Biome on the changed files when the preference asks for it", () => {
+		const root = workspace({ name: "web" });
+		const plan = selectQualityCheck({
+			context: context(root, { usesBiome: true, packageManager: "bun" }),
+			preference: "prefer_biome",
+			files: ["src/app.ts"],
+		});
+
+		expect(plan.tool).toBe("biome");
+		expect(plan.command).toBe("bunx");
+		expect(plan.args).toEqual(["biome", "check", "src/app.ts"]);
+		expect(plan.files).toEqual(["src/app.ts"]);
+	});
+
+	it("never asks Biome to fix the files", () => {
+		const root = workspace({ name: "web" });
+		const plan = selectQualityCheck({
+			context: context(root, { usesBiome: true }),
+			preference: "prefer_biome",
+			files: ["src/app.ts"],
+		});
+
+		expect(plan.args.join(" ")).not.toContain("--write");
+		expect(plan.args.join(" ")).not.toContain("--fix");
+	});
+
+	it("runs the project script when the preference keeps the project tools", () => {
+		const root = workspace({ name: "web", scripts: { lint: "eslint ." } });
+		const plan = selectQualityCheck({
+			context: context(root),
+			preference: "use_project_tools",
+			files: ["src/app.ts"],
+		});
+
+		expect(plan.tool).toBe("project");
+		expect(plan.command).toBe("npm");
+		expect(plan.args).toEqual(["run", "lint"]);
+	});
+
+	it("falls back to the project script when Biome is not installed yet", () => {
+		const root = workspace({ name: "web", scripts: { lint: "eslint ." } });
+		const plan = selectQualityCheck({
+			context: context(root, { usesBiome: false }),
+			preference: "prefer_biome",
+			files: ["src/app.ts"],
+		});
+
+		expect(plan.tool).toBe("project");
+		expect(plan.reason).toContain("Biome is not installed");
+	});
+
+	it("checks nothing without a decision of the user", () => {
+		const root = workspace({ name: "web", scripts: { lint: "eslint ." } });
+		const plan = selectQualityCheck({
+			context: context(root),
+			preference: undefined,
+			files: ["src/app.ts"],
+		});
+
+		expect(plan.tool).toBe("none");
+		expect(plan.command).toBeNull();
+		expect(plan.reason).toContain("not chosen");
+	});
+
+	it("checks nothing when no file changed", () => {
+		const root = workspace({ name: "web", scripts: { lint: "eslint ." } });
+		const plan = selectQualityCheck({
+			context: context(root),
+			preference: "use_project_tools",
+			files: [],
+		});
+
+		expect(plan.tool).toBe("none");
+		expect(plan.reason).toContain("no JavaScript/TypeScript file changed");
+	});
+
+	it("checks nothing when the project has no script to run", () => {
+		const root = workspace({ name: "web" });
+		const plan = selectQualityCheck({
+			context: context(root),
+			preference: "use_project_tools",
+			files: ["src/app.ts"],
+		});
+
+		expect(plan.tool).toBe("none");
+		expect(plan.reason).toContain("neither a lint nor a typecheck");
+	});
+
+	it("uses the typecheck script when there is no lint script", () => {
+		const root = workspace({ name: "web", scripts: { typecheck: "tsc --noEmit" } });
+		const plan = selectQualityCheck({
+			context: context(root),
+			preference: "use_project_tools",
+			files: ["src/app.ts"],
+		});
+
+		expect(plan.command).toBe("npm");
+		expect(plan.args).toEqual(["run", "typecheck"]);
+	});
+});
+
+describe("the check itself", () => {
+	it("reports a passing check", () => {
+		const root = workspace({ name: "web" });
+		const plan = selectQualityCheck({
+			context: context(root),
+			preference: "use_project_tools",
+			files: ["src/app.ts"],
+		});
+		const pass = {
+			tool: plan.tool,
+			command: "node",
+			args: ["-e", "process.exit(0)"],
+			files: ["src/app.ts"],
+			reason: "test",
+		};
+
+		const result = runQualityCheck(pass, { cwd: root, timeoutMs: 10_000 });
+
+		expect(result.ran).toBe(true);
+		expect(result.passed).toBe(true);
+		expect(result.reason).toContain("passed");
+	});
+
+	it("reports a failing check", () => {
+		const root = workspace({ name: "web" });
+		const fail = {
+			tool: "project" as const,
+			command: "node",
+			args: ["-e", "process.stderr.write('problem'); process.exit(2)"],
+			files: ["src/app.ts"],
+			reason: "test",
+		};
+
+		const result = runQualityCheck(fail, { cwd: root, timeoutMs: 10_000 });
+
+		expect(result.ran).toBe(true);
+		expect(result.passed).toBe(false);
+		expect(result.exitCode).toBe(2);
+		expect(result.output).toContain("problem");
+	});
+
+	it("reports a check that cannot start", () => {
+		const result = runQualityCheck(
+			{
+				tool: "project",
+				command: "definitely-not-a-command",
+				args: [],
+				files: ["src/app.ts"],
+				reason: "test",
+			},
+			{ cwd: process.cwd(), timeoutMs: 10_000 },
+		);
+
+		expect(result.ran).toBe(false);
+		expect(result.reason).toContain("could not start");
+	});
+
+	it("runs nothing when the plan has no command", () => {
+		const result = runQualityCheck(
+			{ tool: "none", command: null, args: [], files: [], reason: "nothing to do" },
+			{ cwd: process.cwd(), timeoutMs: 10_000 },
+		);
+
+		expect(result.ran).toBe(false);
+		expect(result.passed).toBe(false);
+	});
+});
+
+describe("the status line", () => {
+	it("names the tool and the outcome", () => {
+		const line = formatQualityCheckStatus({
+			ran: true,
+			passed: true,
+			tool: "biome",
+			fileCount: 3,
+			exitCode: 0,
+			timedOut: false,
+			output: "",
+			reason: "the check passed",
+		});
+
+		expect(line).toBe("[TOOL] biome: 3 file(s), ok");
+		expect(/[^\x20-\x7e]/.test(line)).toBe(false);
+	});
+
+	it("names the reason when no check ran", () => {
+		const line = formatQualityCheckStatus({
+			ran: false,
+			passed: false,
+			tool: "none",
+			fileCount: 0,
+			exitCode: null,
+			timedOut: false,
+			output: "",
+			reason: "no JavaScript/TypeScript file changed",
+		});
+
+		expect(line).toContain("no check");
+		expect(line).toContain("no JavaScript/TypeScript file changed");
+	});
+
+	it("names a timeout", () => {
+		const line = formatQualityCheckStatus({
+			ran: true,
+			passed: false,
+			tool: "project",
+			fileCount: 2,
+			exitCode: null,
+			timedOut: true,
+			output: "",
+			reason: "the check hit the timeout",
+		});
+
+		expect(line).toContain("timeout");
+	});
+});

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/trajectory",
-  "version": "1.1.406",
+  "version": "1.1.407",
   "description": "Trajectory capture for the write-review loop — persists cycle records for learning",
   "type": "module",
   "main": "./dist/src/index.js",

package/packages/tui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/tui",
-  "version": "1.1.406",
+  "version": "1.1.407",
   "description": "pi-harness-runtime — tui",
   "type": "module",
   "main": "./dist/index.js",

package/packages/types/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/types",
-  "version": "1.1.406",
+  "version": "1.1.407",
   "description": "Shared TypeScript types for pi-harness-runtime packages",
   "type": "module",
   "main": "./dist/index.js",