pi-harness-runtime 1.1.404 → 1.1.406

package/packages/tooling-preference/dist/registry.js

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ */
+export class ToolingRequestRegistry {
+    pending = new Map();
+    resolved = new Map();
+    /**
+     * Register a proposal. A request ID that is already known is refused.
+     */
+    register(request) {
+        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) {
+        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, choice, channel) {
+        const request = this.pending.get(requestId);
+        if (!request)
+            return null;
+        this.pending.delete(requestId);
+        const resolution = {
+            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) {
+        return this.resolved.get(requestId);
+    }
+}
+//# sourceMappingURL=registry.js.map

package/packages/tooling-preference/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAqBH,MAAM,OAAO,sBAAsB;IACjB,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC5C,QAAQ,GAAG,IAAI,GAAG,EAA6B,CAAC;IAEjE;;OAEG;IACH,QAAQ,CAAC,OAAuB;QAC/B,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YACjF,OAAO,KAAK,CAAC;QACd,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC7C,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,SAAiB;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACpC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CACJ,SAAiB,EACjB,MAAqB,EACrB,OAAgB;QAEhB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAC1B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC/B,MAAM,UAAU,GAAsB;YACrC,MAAM;YACN,UAAU,EAAE,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,mBAAmB;YACnE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC/B,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;QACzC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,SAAiB;QAC7B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACrC,CAAC;CACD"}

package/packages/tooling-preference/dist/store.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 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;
+}
+/**
+ * The key of one record: the user and the workspace.
+ */
+export declare function toolingPreferenceKey(userKey: string, workspaceRoot: string): string;
+/**
+ * The runtime directory of the harness.
+ */
+export declare function harnessRuntimeDir(): string;
+export declare class ToolingPreferenceStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    /**
+     * The default store: `~/.pi-harness-runtime/tooling-preference.json`.
+     */
+    static defaultFilePath(): string;
+    /**
+     * The record of one user in one workspace.
+     */
+    read(userKey: string, workspaceRoot: string): ToolingPreferenceRecord | undefined;
+    /**
+     * Remember that the proposal was sent.
+     */
+    markAsked(userKey: string, workspaceRoot: string, requestId: string, now?: Date): void;
+    /**
+     * Save the answer of the user.
+     */
+    recordDecision(userKey: string, workspaceRoot: string, decision: ToolingPreference, requestId: string, channel?: string, now?: Date): void;
+    private load;
+    private save;
+}
+/**
+ * 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 declare function shouldAskAgain(record: ToolingPreferenceRecord | undefined, cooldownMs: number, now?: Date): boolean;
+//# sourceMappingURL=store.d.ts.map

package/packages/tooling-preference/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,MAAM,WAAW,uBAAuB;IACvC,kDAAkD;IAClD,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAQD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAI1C;AAED,qBAAa,sBAAsB;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAArC,YAA6B,QAAQ,EAAE,MAAM,EAAI;IAEjD;;OAEG;IACH,MAAM,CAAC,eAAe,IAAI,MAAM,CAE/B;IAED;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAGhF;IAED;;OAEG;IACH,SAAS,CACR,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,IAAiB,GACpB,IAAI,CAWN;IAED;;OAEG;IACH,cAAc,CACb,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,EAChB,GAAG,GAAE,IAAiB,GACpB,IAAI,CAcN;IAED,OAAO,CAAC,IAAI;IAaZ,OAAO,CAAC,IAAI;CAYZ;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,uBAAuB,GAAG,SAAS,EAC3C,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,IAAiB,GACpB,OAAO,CAOT"}

package/packages/tooling-preference/dist/store.js

@@ -0,0 +1,129 @@
+/**
+ * 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";
+function shortHash(value, length = 16) {
+    return createHash("sha256").update(value).digest("hex").slice(0, length);
+}
+/**
+ * The key of one record: the user and the workspace.
+ */
+export function toolingPreferenceKey(userKey, workspaceRoot) {
+    return `${userKey}::${shortHash(workspaceRoot)}`;
+}
+/**
+ * The runtime directory of the harness.
+ */
+export function harnessRuntimeDir() {
+    const configured = process.env.PI_HARNESS_HOME?.trim();
+    if (configured)
+        return configured;
+    return join(homedir(), ".pi-harness-runtime");
+}
+export class ToolingPreferenceStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    /**
+     * The default store: `~/.pi-harness-runtime/tooling-preference.json`.
+     */
+    static defaultFilePath() {
+        return join(harnessRuntimeDir(), "tooling-preference.json");
+    }
+    /**
+     * The record of one user in one workspace.
+     */
+    read(userKey, workspaceRoot) {
+        const data = this.load();
+        return data[toolingPreferenceKey(userKey, workspaceRoot)];
+    }
+    /**
+     * Remember that the proposal was sent.
+     */
+    markAsked(userKey, workspaceRoot, requestId, now = new Date()) {
+        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, workspaceRoot, decision, requestId, channel, now = new Date()) {
+        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);
+    }
+    load() {
+        if (!existsSync(this.filePath))
+            return {};
+        try {
+            const parsed = JSON.parse(readFileSync(this.filePath, "utf8"));
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return {};
+            return parsed;
+        }
+        catch {
+            // A broken store must not stop the harness: the proposal is
+            // simply asked again.
+            return {};
+        }
+    }
+    save(data) {
+        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, cooldownMs, now = new Date()) {
+    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;
+}
+//# sourceMappingURL=store.js.map

package/packages/tooling-preference/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/packages/tooling-preference/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@pi-harness/tooling-preference",
+  "version": "1.1.406",
+  "description": "pi-harness-runtime — JS/TS tooling preference (Biome vs ESLint/Prettier) proposal",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test"
+  }
+}

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

@@ -0,0 +1,251 @@
+/**
+ * Tooling detection for a workspace.
+ *
+ * The proposal ("use Biome.js instead of ESLint + Prettier") is only made
+ * for a JavaScript/TypeScript workspace that still uses ESLint or Prettier
+ * and does not use Biome yet. The detection reads the workspace itself -
+ * it never guesses from the harness.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export interface ToolingContext {
+	/** Absolute workspace root. */
+	root: string;
+	/** The workspace has a package.json. */
+	hasPackageJson: boolean;
+	/** The workspace is a JavaScript/TypeScript project. */
+	isJavaScriptTypeScript: boolean;
+	/** Next.js is in use. */
+	isNextJs: boolean;
+	/** React is in use. */
+	isReact: boolean;
+	/** Biome is configured or installed. */
+	usesBiome: boolean;
+	/** ESLint is configured or installed. */
+	usesEslint: boolean;
+	/** Prettier is configured or installed. */
+	usesPrettier: boolean;
+	/** The package manager the workspace uses, if it can be told. */
+	packageManager: string | null;
+	/** The frameworks that were detected. */
+	frameworks: string[];
+}
+
+const ESLINT_CONFIGS = [
+	".eslintrc",
+	".eslintrc.js",
+	".eslintrc.cjs",
+	".eslintrc.mjs",
+	".eslintrc.json",
+	".eslintrc.yaml",
+	".eslintrc.yml",
+	"eslint.config.js",
+	"eslint.config.mjs",
+	"eslint.config.cjs",
+	"eslint.config.ts",
+];
+
+const PRETTIER_CONFIGS = [
+	".prettierrc",
+	".prettierrc.json",
+	".prettierrc.yaml",
+	".prettierrc.yml",
+	".prettierrc.js",
+	".prettierrc.cjs",
+	".prettierrc.mjs",
+	"prettier.config.js",
+	"prettier.config.cjs",
+	"prettier.config.mjs",
+	"prettier.config.ts",
+];
+
+const BIOME_CONFIGS = ["biome.json", "biome.jsonc", "biome.json5"];
+
+const NEXT_CONFIGS = [
+	"next.config.js",
+	"next.config.mjs",
+	"next.config.cjs",
+	"next.config.ts",
+];
+
+const SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+
+const IGNORED_DIRECTORIES = new Set([
+	"node_modules",
+	"dist",
+	"build",
+	"out",
+	"coverage",
+	"vendor",
+	".git",
+	".next",
+	".turbo",
+	".cache",
+]);
+
+interface PackageJson {
+	name?: string;
+	dependencies?: Record<string, string>;
+	devDependencies?: Record<string, string>;
+	peerDependencies?: Record<string, string>;
+	packageManager?: string;
+}
+
+function readPackageJson(root: string): PackageJson | null {
+	const path = join(root, "package.json");
+	if (!existsSync(path)) return null;
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+		if (!parsed || typeof parsed !== "object") return null;
+		return parsed as PackageJson;
+	} catch {
+		return null;
+	}
+}
+
+function allDependencies(pkg: PackageJson | null): Record<string, string> {
+	if (!pkg) return {};
+	return {
+		...(pkg.dependencies ?? {}),
+		...(pkg.devDependencies ?? {}),
+		...(pkg.peerDependencies ?? {}),
+	};
+}
+
+function anyExists(root: string, names: string[]): boolean {
+	return names.some((name) => existsSync(join(root, name)));
+}
+
+/**
+ * Is there a JavaScript/TypeScript source file in the workspace?
+ *
+ * The scan is shallow on purpose: it only answers "does this workspace hold
+ * JS/TS code at all", so it stops at the first source file and never walks
+ * a build or dependency directory.
+ */
+function hasSourceFile(root: string, maxDepth = 2): boolean {
+	const queue: Array<{ dir: string; depth: number }> = [{ dir: root, depth: 0 }];
+	while (queue.length > 0) {
+		const current = queue.shift();
+		if (!current) break;
+		let entries: string[];
+		try {
+			entries = readdirSync(current.dir);
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (entry.startsWith(".")) continue;
+			const full = join(current.dir, entry);
+			let isDirectory = false;
+			try {
+				isDirectory = statSync(full).isDirectory();
+			} catch {
+				continue;
+			}
+			if (isDirectory) {
+				if (current.depth < maxDepth && !IGNORED_DIRECTORIES.has(entry)) {
+					queue.push({ dir: full, depth: current.depth + 1 });
+				}
+				continue;
+			}
+			if (SOURCE_EXTENSIONS.some((extension) => entry.endsWith(extension))) {
+				return true;
+			}
+		}
+	}
+	return false;
+}
+
+/**
+ * Which package manager does the workspace use?
+ *
+ * The `packageManager` field wins; a lockfile decides otherwise.
+ */
+export function detectPackageManager(root: string, pkg: PackageJson | null): string | null {
+	const declared = pkg?.packageManager?.split("@")[0]?.trim();
+	if (declared) return declared;
+	if (existsSync(join(root, "pnpm-lock.yaml"))) return "pnpm";
+	if (existsSync(join(root, "yarn.lock"))) return "yarn";
+	if (existsSync(join(root, "bun.lock")) || existsSync(join(root, "bun.lockb"))) return "bun";
+	if (existsSync(join(root, "package-lock.json"))) return "npm";
+	return null;
+}
+
+/**
+ * Read the tooling facts of a workspace.
+ */
+export function detectToolingContext(root: string): ToolingContext {
+	const pkg = readPackageJson(root);
+	const deps = allDependencies(pkg);
+	const hasPackageJson = pkg !== null;
+	const hasTsConfig = existsSync(join(root, "tsconfig.json"));
+	const isNextJs = Boolean(deps.next) || anyExists(root, NEXT_CONFIGS);
+	const isReact = Boolean(deps.react || deps["react-dom"]) || isNextJs;
+	const isTypeScript =
+		hasTsConfig || Boolean(deps.typescript) || hasSourceFile(root);
+
+	return {
+		root,
+		hasPackageJson,
+		isJavaScriptTypeScript: hasPackageJson && isTypeScript,
+		isNextJs,
+		isReact,
+		usesBiome: anyExists(root, BIOME_CONFIGS) || Boolean(deps["@biomejs/biome"]),
+		usesEslint: anyExists(root, ESLINT_CONFIGS) || Boolean(deps.eslint),
+		usesPrettier: anyExists(root, PRETTIER_CONFIGS) || Boolean(deps.prettier),
+		packageManager: detectPackageManager(root, pkg),
+		frameworks: [
+			...(isNextJs ? ["next"] : []),
+			...(isReact && !isNextJs ? ["react"] : []),
+		],
+	};
+}
+
+export interface ProposalEligibility {
+	/** May the proposal be sent? */
+	eligible: boolean;
+	/** Why the proposal is (not) sent - a human wording. */
+	reason: string;
+}
+
+/**
+ * May the Biome proposal be sent for this workspace?
+ *
+ * A workspace that already uses Biome is never asked about Biome, and a
+ * workspace without ESLint and Prettier has nothing to replace.
+ */
+export function evaluateBiomeProposalEligibility(
+	context: ToolingContext,
+): ProposalEligibility {
+	if (!context.hasPackageJson) {
+		return {
+			eligible: false,
+			reason: "the workspace has no package.json",
+		};
+	}
+	if (!context.isJavaScriptTypeScript) {
+		return {
+			eligible: false,
+			reason: "the workspace is not a JavaScript/TypeScript project",
+		};
+	}
+	if (context.usesBiome) {
+		return {
+			eligible: false,
+			reason: "Biome is already configured in this workspace",
+		};
+	}
+	if (!context.usesEslint && !context.usesPrettier) {
+		return {
+			eligible: false,
+			reason: "the workspace uses neither ESLint nor Prettier",
+		};
+	}
+	return {
+		eligible: true,
+		reason: "the workspace uses ESLint and/or Prettier and no Biome",
+	};
+}

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

@@ -0,0 +1,44 @@
+/**
+ * The JS/TS tooling preference of a workspace.
+ *
+ * The harness offers the user to replace ESLint and Prettier with Biome.js
+ * in a JavaScript/TypeScript workspace. The offer is a decision of its own:
+ * it never pauses the work and never travels through the task-approval
+ * path.
+ */
+
+export {
+	detectPackageManager,
+	detectToolingContext,
+	evaluateBiomeProposalEligibility,
+	type ProposalEligibility,
+	type ToolingContext,
+} from "./detect.js";
+
+export {
+	buildToolingButtons,
+	buildToolingImplementationPrompt,
+	buildToolingProposalMessage,
+	buildToolingRequestId,
+	buildToolingUserKey,
+	parseToolingTarget,
+	TOOLING_ACTION,
+	type ToolingButton,
+	type ToolingChoice,
+	type ToolingPreference,
+	type ToolingTarget,
+} from "./proposal.js";
+
+export {
+	harnessRuntimeDir,
+	shouldAskAgain,
+	ToolingPreferenceStore,
+	toolingPreferenceKey,
+	type ToolingPreferenceRecord,
+} from "./store.js";
+
+export {
+	ToolingRequestRegistry,
+	type ToolingRequest,
+	type ToolingResolution,
+} from "./registry.js";