pi-harness-runtime 1.1.404 → 1.1.406

package/packages/tooling-preference/src/proposal.ts

@@ -0,0 +1,173 @@
+/**
+ * The tooling proposal: request IDs, buttons and the wording.
+ *
+ * The proposal is a decision of its own. It never travels through the
+ * task-approval path, because a "No" there pauses the work and a "Yes"
+ * there resumes it - neither belongs to a tooling preference.
+ */
+
+import { createHash } from "node:crypto";
+import type { ToolingContext } from "./detect.js";
+
+/**
+ * The callback action of the proposal.
+ *
+ * The callback data is parsed by splitting on "_", so an action must be a
+ * single token: an action that carries an underscore would be read as the
+ * action up to that underscore, and the rest as the target.
+ */
+export const TOOLING_ACTION = "biome";
+
+/** The answer of the user. */
+export type ToolingChoice = "yes" | "no";
+
+/** The saved preference of a user in a workspace. */
+export type ToolingPreference = "prefer_biome" | "use_project_tools";
+
+export interface ToolingButton {
+	/** The label of the button. */
+	text: string;
+	/** The callback action - always `TOOLING_ACTION`. */
+	action: string;
+	/** The choice and the request ID, e.g. `yes-biome-<hash>`. */
+	targetId: string;
+}
+
+export interface ToolingTarget {
+	choice: ToolingChoice;
+	requestId: string;
+}
+
+function shortHash(value: string, length = 16): string {
+	return createHash("sha256").update(value).digest("hex").slice(0, length);
+}
+
+/**
+ * The canonical request ID of one proposal.
+ *
+ * The request ID is the correlation key: both channels send the same ID,
+ * and the first answer wins. It only holds hex characters and dashes so it
+ * survives the "_" split of the callback data.
+ */
+export function buildToolingRequestId(userKey: string, workspaceRoot: string): string {
+	return `biome-${shortHash(`${userKey} ${workspaceRoot}`)}`;
+}
+
+/**
+ * The key of the user the proposal is sent to.
+ *
+ * The identity is hashed: the store holds the key of a user, never the id
+ * of the user.
+ */
+export function buildToolingUserKey(identity: string): string {
+	const trimmed = identity.trim();
+	if (!trimmed) return "default";
+	return `u-${shortHash(`user:${trimmed}`)}`;
+}
+
+/**
+ * The two buttons of the proposal.
+ */
+export function buildToolingButtons(requestId: string): ToolingButton[] {
+	return [
+		{
+			text: "Yes - use Biome.js",
+			action: TOOLING_ACTION,
+			targetId: `yes-${requestId}`,
+		},
+		{
+			text: "No - keep the current tools",
+			action: TOOLING_ACTION,
+			targetId: `no-${requestId}`,
+		},
+	];
+}
+
+/**
+ * Read the choice and the request ID out of a callback target.
+ *
+ * A target that does not belong to the proposal returns `null` - a click on
+ * a foreign button must never resolve a preference.
+ */
+export function parseToolingTarget(targetId: string | undefined): ToolingTarget | null {
+	if (!targetId) return null;
+	const match = /^(yes|no)-(.+)$/.exec(targetId);
+	if (!match) return null;
+	return { choice: match[1] as ToolingChoice, requestId: match[2] };
+}
+
+/**
+ * The wording of the proposal.
+ */
+export function buildToolingProposalMessage(context: ToolingContext): string {
+	const frameworks: string[] = [];
+	if (context.isNextJs) frameworks.push("Next.js");
+	if (context.isReact && !context.isNextJs) frameworks.push("React");
+
+	const tools: string[] = [];
+	if (context.usesEslint) tools.push("ESLint");
+	if (context.usesPrettier) tools.push("Prettier");
+
+	const lines: string[] = [];
+	lines.push(
+		frameworks.length > 0
+			? `This workspace looks like a ${frameworks.join(" + ")} project that still uses ${tools.join(" and ")}.`
+			: `This workspace looks like a JavaScript/TypeScript project that still uses ${tools.join(" and ")}.`,
+	);
+	lines.push("");
+	lines.push("Biome.js can replace both: one tool for linting, formatting and import order.");
+	lines.push("");
+	lines.push(`Detected: ${tools.join(", ")}${context.packageManager ? ` - ${context.packageManager}` : ""}`);
+	lines.push("");
+	lines.push(
+		"Yes adds Biome and migrates the lint/format setup here. No keeps the current tools. Nothing changes until you answer.",
+	);
+	return lines.join("\n");
+}
+
+/**
+ * The instruction the agent receives after a "Yes".
+ *
+ * The agent does the repository work: the harness only records the
+ * decision and starts the implementation.
+ */
+export function buildToolingImplementationPrompt(
+	context: ToolingContext,
+	workspaceRoot: string,
+): string {
+	const frameworks: string[] = [];
+	if (context.isNextJs) frameworks.push("Next.js");
+	if (context.isReact && !context.isNextJs) frameworks.push("React");
+
+	const manager = context.packageManager;
+	let install = "install it as a dev dependency with the package manager of the workspace";
+	if (manager === "npm") {
+		install = "install it with npm install --save-dev";
+	} else if (manager) {
+		install = `install it with ${manager} add --save-dev`;
+	}
+
+	const lines: string[] = [];
+	lines.push(
+		`The user chose to use Biome.js in this workspace (${workspaceRoot}). Implement it now.`,
+	);
+	lines.push("");
+	lines.push("1. Add Biome to the dev dependencies: " + install + " @biomejs/biome.");
+	lines.push("2. Add a biome.json that fits the project:");
+	if (frameworks.length > 0) {
+		lines.push(`   - enable the ${frameworks.join(" and ")} rules,`);
+	}
+	lines.push("   - enable the formatter, the linter and the import organizer,");
+	lines.push("   - keep the settings that match the existing code style (indentation, quotes, semicolons).");
+	lines.push(
+		"3. Replace the lint and format scripts in package.json with the Biome equivalents (biome check, biome format, biome ci).",
+	);
+	lines.push(
+		"4. Migrate the ESLint and Prettier configuration that Biome replaces and remove the files Biome fully replaces.",
+	);
+	lines.push("5. Keep the type check and the tests as they are - Biome does not replace them.");
+	lines.push("6. Run the Biome check, fix what it reports in the files you touched, and report the result.");
+	lines.push("");
+	lines.push("Do not touch files outside this workspace and do not change the public behaviour of the code.");
+	return lines.join("\n");
+}

package/packages/tooling-preference/src/registry.ts

@@ -0,0 +1,79 @@
+/**
+ * The pending proposals of this session.
+ *
+ * The first answer wins: a second click on the other button changes
+ * nothing. The registry is in memory only - a proposal that was never
+ * answered simply disappears with the session.
+ */
+
+import type { ToolingChoice, ToolingPreference } from "./proposal.js";
+
+export interface ToolingRequest {
+	/** The canonical request ID of the proposal. */
+	requestId: string;
+	/** The workspace the proposal belongs to. */
+	workspaceRoot: string;
+	/** The user the proposal was sent to. */
+	userKey: string;
+	/** The tooling facts of the workspace. */
+	frameworks: string[];
+}
+
+export interface ToolingResolution {
+	choice: ToolingChoice;
+	preference: ToolingPreference;
+	channel?: string;
+}
+
+export class ToolingRequestRegistry {
+	private readonly pending = new Map<string, ToolingRequest>();
+	private readonly resolved = new Map<string, ToolingResolution>();
+
+	/**
+	 * Register a proposal. A request ID that is already known is refused.
+	 */
+	register(request: ToolingRequest): boolean {
+		if (this.pending.has(request.requestId) || this.resolved.has(request.requestId)) {
+			return false;
+		}
+		this.pending.set(request.requestId, request);
+		return true;
+	}
+
+	/**
+	 * Is the request still waiting for an answer?
+	 */
+	has(requestId: string): boolean {
+		return this.pending.has(requestId);
+	}
+
+	/**
+	 * Claim a request for an answer.
+	 *
+	 * The claim removes the request, so a second click finds nothing and the
+	 * first answer stays the one that counts.
+	 */
+	claim(
+		requestId: string,
+		choice: ToolingChoice,
+		channel?: string,
+	): { request: ToolingRequest; resolution: ToolingResolution } | null {
+		const request = this.pending.get(requestId);
+		if (!request) return null;
+		this.pending.delete(requestId);
+		const resolution: ToolingResolution = {
+			choice,
+			preference: choice === "yes" ? "prefer_biome" : "use_project_tools",
+			...(channel ? { channel } : {}),
+		};
+		this.resolved.set(requestId, resolution);
+		return { request, resolution };
+	}
+
+	/**
+	 * The answer of a request that was already resolved.
+	 */
+	resolutionOf(requestId: string): ToolingResolution | undefined {
+		return this.resolved.get(requestId);
+	}
+}

package/packages/tooling-preference/src/store.ts

@@ -0,0 +1,162 @@
+/**
+ * The saved tooling preference of a user in a workspace.
+ *
+ * The store is a plain JSON file under the harness runtime directory: it
+ * works in every runtime (a SQLite file would not - `node:sqlite` is
+ * missing in some of them) and it stays readable for the user.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { ToolingPreference } from "./proposal.js";
+
+export interface ToolingPreferenceRecord {
+	/** The saved decision, when the user answered. */
+	decision?: ToolingPreference;
+	/** When the proposal was sent. */
+	askedAt?: string;
+	/** When the user answered. */
+	decidedAt?: string;
+	/** The request ID of the proposal that was sent. */
+	requestId?: string;
+	/** The workspace the record belongs to. */
+	workspaceRoot?: string;
+	/** The channel the answer came from. */
+	channel?: string;
+}
+
+type StoreFile = Record<string, ToolingPreferenceRecord>;
+
+function shortHash(value: string, length = 16): string {
+	return createHash("sha256").update(value).digest("hex").slice(0, length);
+}
+
+/**
+ * The key of one record: the user and the workspace.
+ */
+export function toolingPreferenceKey(userKey: string, workspaceRoot: string): string {
+	return `${userKey}::${shortHash(workspaceRoot)}`;
+}
+
+/**
+ * The runtime directory of the harness.
+ */
+export function harnessRuntimeDir(): string {
+	const configured = process.env.PI_HARNESS_HOME?.trim();
+	if (configured) return configured;
+	return join(homedir(), ".pi-harness-runtime");
+}
+
+export class ToolingPreferenceStore {
+	constructor(private readonly filePath: string) {}
+
+	/**
+	 * The default store: `~/.pi-harness-runtime/tooling-preference.json`.
+	 */
+	static defaultFilePath(): string {
+		return join(harnessRuntimeDir(), "tooling-preference.json");
+	}
+
+	/**
+	 * The record of one user in one workspace.
+	 */
+	read(userKey: string, workspaceRoot: string): ToolingPreferenceRecord | undefined {
+		const data = this.load();
+		return data[toolingPreferenceKey(userKey, workspaceRoot)];
+	}
+
+	/**
+	 * Remember that the proposal was sent.
+	 */
+	markAsked(
+		userKey: string,
+		workspaceRoot: string,
+		requestId: string,
+		now: Date = new Date(),
+	): void {
+		const key = toolingPreferenceKey(userKey, workspaceRoot);
+		const data = this.load();
+		const existing = data[key] ?? {};
+		data[key] = {
+			...existing,
+			askedAt: now.toISOString(),
+			requestId,
+			workspaceRoot,
+		};
+		this.save(data);
+	}
+
+	/**
+	 * Save the answer of the user.
+	 */
+	recordDecision(
+		userKey: string,
+		workspaceRoot: string,
+		decision: ToolingPreference,
+		requestId: string,
+		channel?: string,
+		now: Date = new Date(),
+	): void {
+		const key = toolingPreferenceKey(userKey, workspaceRoot);
+		const data = this.load();
+		const existing = data[key] ?? {};
+		data[key] = {
+			...existing,
+			decision,
+			decidedAt: now.toISOString(),
+			askedAt: existing.askedAt ?? now.toISOString(),
+			requestId,
+			workspaceRoot,
+			...(channel ? { channel } : {}),
+		};
+		this.save(data);
+	}
+
+	private load(): StoreFile {
+		if (!existsSync(this.filePath)) return {};
+		try {
+			const parsed = JSON.parse(readFileSync(this.filePath, "utf8")) as unknown;
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+			return parsed as StoreFile;
+		} catch {
+			// A broken store must not stop the harness: the proposal is
+			// simply asked again.
+			return {};
+		}
+	}
+
+	private save(data: StoreFile): void {
+		try {
+			mkdirSync(dirname(this.filePath), { recursive: true });
+			const temporary = `${this.filePath}.tmp`;
+			writeFileSync(temporary, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+			// The rename keeps a half written file from being read.
+			renameSync(temporary, this.filePath);
+		} catch {
+			// A store that cannot be written is a lost preference, not a
+			// broken harness.
+		}
+	}
+}
+
+/**
+ * May the proposal be sent again?
+ *
+ * A workspace that was asked and never answered is asked again after the
+ * cooldown - the user may have missed it. A workspace with a decision is
+ * never asked again.
+ */
+export function shouldAskAgain(
+	record: ToolingPreferenceRecord | undefined,
+	cooldownMs: number,
+	now: Date = new Date(),
+): boolean {
+	if (!record) return true;
+	if (record.decision) return false;
+	if (!record.askedAt) return true;
+	const askedAt = Date.parse(record.askedAt);
+	if (Number.isNaN(askedAt)) return true;
+	return now.getTime() - askedAt >= cooldownMs;
+}

package/packages/tooling-preference/tests/detect.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it } from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	detectToolingContext,
+	evaluateBiomeProposalEligibility,
+} from "../src/detect.ts";
+
+function workspace(files: Record<string, string>): string {
+	const root = mkdtempSync(join(tmpdir(), "tooling-preference-"));
+	for (const [name, content] of Object.entries(files)) {
+		const path = join(root, name);
+		mkdirSync(join(path, ".."), { recursive: true });
+		writeFileSync(path, content, "utf8");
+	}
+	return root;
+}
+
+function cleanup(root: string): void {
+	rmSync(root, { recursive: true, force: true });
+}
+
+describe("detectToolingContext", () => {
+	it("detects a Next.js + React + TypeScript workspace with ESLint and Prettier", () => {
+		const root = workspace({
+			"package.json": JSON.stringify({
+				name: "web",
+				dependencies: { next: "15.0.0", react: "19.0.0" },
+				devDependencies: { eslint: "^9.0.0", prettier: "^3.0.0", typescript: "^5.7.0" },
+			}),
+			"tsconfig.json": "{}",
+			".eslintrc.json": "{}",
+			".prettierrc": "{}",
+			"src/app/page.tsx": "export const x = 1;",
+		});
+		try {
+			const context = detectToolingContext(root);
+			expect(context.hasPackageJson).toBe(true);
+			expect(context.isJavaScriptTypeScript).toBe(true);
+			expect(context.isNextJs).toBe(true);
+			expect(context.isReact).toBe(true);
+			expect(context.usesBiome).toBe(false);
+			expect(context.usesEslint).toBe(true);
+			expect(context.usesPrettier).toBe(true);
+			expect(context.frameworks).toContain("next");
+		} finally {
+			cleanup(root);
+		}
+	});
+
+	it("reports a workspace that already uses Biome", () => {
+		const root = workspace({
+			"package.json": JSON.stringify({ name: "web", devDependencies: { eslint: "^9.0.0" } }),
+			"biome.json": "{}",
+			"tsconfig.json": "{}",
+		});
+		try {
+			const context = detectToolingContext(root);
+			expect(context.usesBiome).toBe(true);
+		} finally {
+			cleanup(root);
+		}
+	});
+
+	it("detects Biome through the dependency alone", () => {
+		const root = workspace({
+			"package.json": JSON.stringify({
+				name: "web",
+				devDependencies: { "@biomejs/biome": "^2.4.7" },
+			}),
+			"tsconfig.json": "{}",
+		});
+		try {
+			expect(detectToolingContext(root).usesBiome).toBe(true);
+		} finally {
+			cleanup(root);
+		}
+	});
+
+	it("detects the package manager through the lockfile", () => {
+		const root = workspace({
+			"package.json": JSON.stringify({ name: "web" }),
+			"pnpm-lock.yaml": "",
+		});
+		try {
+			expect(detectToolingContext(root).packageManager).toBe("pnpm");
+		} finally {
+			cleanup(root);
+		}
+	});
+
+	it("prefers the declared package manager", () => {
+		const root = workspace({
+			"package.json": JSON.stringify({ name: "web", packageManager: "bun@1.3.0" }),
+			"package-lock.json": "{}",
+		});
+		try {
+			expect(detectToolingContext(root).packageManager).toBe("bun");
+		} finally {
+			cleanup(root);
+		}
+	});
+
+	it("finds a source file without a tsconfig", () => {
+		const root = workspace({
+			"package.json": JSON.stringify({ name: "web" }),
+			"src/index.ts": "export const x = 1;",
+		});
+		try {
+			expect(detectToolingContext(root).isJavaScriptTypeScript).toBe(true);
+		} finally {
+			cleanup(root);
+		}
+	});
+
+	it("does not walk into a dependency directory for sources", () => {
+		const root = workspace({
+			"package.json": JSON.stringify({ name: "web" }),
+			"node_modules/some-package/index.js": "module.exports = 1;",
+		});
+		try {
+			expect(detectToolingContext(root).isJavaScriptTypeScript).toBe(false);
+		} finally {
+			cleanup(root);
+		}
+	});
+});
+
+describe("evaluateBiomeProposalEligibility", () => {
+	it("offers the proposal for a JS/TS workspace with ESLint or Prettier", () => {
+		const root = workspace({
+			"package.json": JSON.stringify({ name: "web", devDependencies: { eslint: "^9.0.0" } }),
+			"tsconfig.json": "{}",
+		});
+		try {
+			const decision = evaluateBiomeProposalEligibility(detectToolingContext(root));
+			expect(decision.eligible).toBe(true);
+		} finally {
+			cleanup(root);
+		}
+	});
+
+	it("never asks a workspace that already uses Biome", () => {
+		const root = workspace({
+			"package.json": JSON.stringify({
+				name: "web",
+				devDependencies: { eslint: "^9.0.0", "@biomejs/biome": "^2.4.7" },
+			}),
+			"tsconfig.json": "{}",
+		});
+		try {
+			const decision = evaluateBiomeProposalEligibility(detectToolingContext(root));
+			expect(decision.eligible).toBe(false);
+			expect(decision.reason).toContain("Biome");
+		} finally {
+			cleanup(root);
+		}
+	});
+
+	it("never asks a workspace without ESLint and Prettier", () => {
+		const root = workspace({
+			"package.json": JSON.stringify({ name: "web" }),
+			"tsconfig.json": "{}",
+		});
+		try {
+			const decision = evaluateBiomeProposalEligibility(detectToolingContext(root));
+			expect(decision.eligible).toBe(false);
+			expect(decision.reason).toContain("neither ESLint nor Prettier");
+		} finally {
+			cleanup(root);
+		}
+	});
+
+	it("never asks a workspace that is not JavaScript/TypeScript", () => {
+		const root = workspace({
+			"package.json": JSON.stringify({ name: "docs" }),
+			"README.md": "# docs",
+		});
+		try {
+			const decision = evaluateBiomeProposalEligibility(detectToolingContext(root));
+			expect(decision.eligible).toBe(false);
+			expect(decision.reason).toContain("not a JavaScript/TypeScript project");
+		} finally {
+			cleanup(root);
+		}
+	});
+});

package/packages/tooling-preference/tests/proposal.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "bun:test";
+import {
+	buildToolingButtons,
+	buildToolingImplementationPrompt,
+	buildToolingProposalMessage,
+	buildToolingRequestId,
+	parseToolingTarget,
+	TOOLING_ACTION,
+} from "../src/proposal.ts";
+import type { ToolingContext } from "../src/detect.ts";
+
+const context: ToolingContext = {
+	root: "/work/web",
+	hasPackageJson: true,
+	isJavaScriptTypeScript: true,
+	isNextJs: true,
+	isReact: true,
+	usesBiome: false,
+	usesEslint: true,
+	usesPrettier: true,
+	packageManager: "pnpm",
+	frameworks: ["next"],
+};
+
+describe("buildToolingRequestId", () => {
+	it("is stable for the same user and workspace", () => {
+		const first = buildToolingRequestId("user-1", "/work/web");
+		const second = buildToolingRequestId("user-1", "/work/web");
+		expect(first).toBe(second);
+	});
+
+	it("differs per user and per workspace", () => {
+		expect(buildToolingRequestId("user-1", "/work/web")).not.toBe(
+			buildToolingRequestId("user-2", "/work/web"),
+		);
+		expect(buildToolingRequestId("user-1", "/work/web")).not.toBe(
+			buildToolingRequestId("user-1", "/work/other"),
+		);
+	});
+
+	it("holds no underscore, so the callback parser keeps it intact", () => {
+		const requestId = buildToolingRequestId("user-1", "/work/web");
+		expect(requestId).not.toContain("_");
+		expect(requestId.startsWith("biome-")).toBe(true);
+	});
+});
+
+describe("buildToolingButtons", () => {
+	it("sends one action with a choice per button", () => {
+		const requestId = buildToolingRequestId("user-1", "/work/web");
+		const buttons = buildToolingButtons(requestId);
+		expect(buttons).toHaveLength(2);
+		for (const button of buttons) {
+			expect(button.action).toBe(TOOLING_ACTION);
+			expect(button.targetId).toContain(requestId);
+		}
+		expect(buttons[0].targetId.startsWith("yes-")).toBe(true);
+		expect(buttons[1].targetId.startsWith("no-")).toBe(true);
+	});
+
+	it("keeps the action a single token", () => {
+		expect(TOOLING_ACTION).not.toContain("_");
+	});
+});
+
+describe("parseToolingTarget", () => {
+	it("reads the choice and the request ID back", () => {
+		const requestId = buildToolingRequestId("user-1", "/work/web");
+		const [yes, no] = buildToolingButtons(requestId);
+		expect(parseToolingTarget(yes.targetId)).toEqual({ choice: "yes", requestId });
+		expect(parseToolingTarget(no.targetId)).toEqual({ choice: "no", requestId });
+	});
+
+	it("refuses a target that is not part of the proposal", () => {
+		expect(parseToolingTarget("q-123")).toBeNull();
+		expect(parseToolingTarget("maybe-biome-abc")).toBeNull();
+		expect(parseToolingTarget("")).toBeNull();
+		expect(parseToolingTarget(undefined)).toBeNull();
+	});
+
+	it("survives the callback data round trip", () => {
+		const requestId = buildToolingRequestId("user-1", "/work/web");
+		const [yes] = buildToolingButtons(requestId);
+		const data = `${yes.action}_${yes.targetId}`;
+		const [action, targetId] = data.split("_");
+		expect(action).toBe(TOOLING_ACTION);
+		expect(parseToolingTarget(targetId)?.requestId).toBe(requestId);
+	});
+});
+
+describe("the wording", () => {
+	it("names the detected tools and the frameworks", () => {
+		const message = buildToolingProposalMessage(context);
+		expect(message).toContain("Next.js");
+		expect(message).toContain("ESLint");
+		expect(message).toContain("Prettier");
+		expect(message).toContain("Biome");
+	});
+
+	it("asks the agent to implement Biome after a yes", () => {
+		const prompt = buildToolingImplementationPrompt(context, "/work/web");
+		expect(prompt).toContain("/work/web");
+		expect(prompt).toContain("@biomejs/biome");
+		expect(prompt).toContain("pnpm add --save-dev");
+		expect(prompt).toContain("Next.js");
+	});
+});