pi-harness-runtime 1.1.387 → 1.1.388

package/packages/contracts/src/workspace-env-format.ts

@@ -0,0 +1,165 @@
+/**
+ * Workspace environment formatting helpers.
+ *
+ * Split out of workspace-env.ts so the wording can be unit tested without the
+ * node:sqlite dependency (bun 1.3.x has no node:sqlite module).
+ *
+ * Wording rules:
+ * - The mode is only reported when it is EXPLICIT (NODE_ENV). An unknown mode
+ *   is always shown with its reason, never as a bare word next to a dev
+ *   server state that could be read as proof of the mode.
+ * - A dev/build script is a CAPABILITY, not a state. The status line says
+ *   "not running (script available)" so it cannot be mistaken for a running
+ *   server or for evidence about the workspace mode.
+ */
+
+/**
+ * Workspace mode with explicit states
+ */
+export type WorkspaceMode = "development" | "production" | "test" | "unknown";
+
+/**
+ * Evidence source for mode detection
+ */
+export interface EnvEvidence {
+	source: "process.env" | ".env file" | "package.json" | "command" | "detection";
+	key: string;
+	value: string;
+	timestamp: number;
+}
+
+/**
+ * Workspace environment result
+ */
+export interface WorkspaceEnvResult {
+	workspacePath: string;
+	mode: WorkspaceMode;
+	evidence: EnvEvidence[];
+	hasDevScript: boolean;
+	hasBuildScript: boolean;
+	packageManager: string | null;
+	devServerRunning: boolean;
+	buildServerRunning: boolean;
+	ramTotalGb: number | null;
+	ramAvailableGb: number | null;
+	ramEffectiveLimitGb: number | null;
+	lowRamWarning: boolean;
+	buildAllowed: boolean;
+	detectedAt: number;
+}
+
+/**
+ * Human readable mode label.
+ *
+ * "unknown" always carries the reason: the mode can only be proven by an
+ * explicit NODE_ENV (process env or .env file). When a NODE_ENV IS present
+ * but names a mode this detector does not know ("staging"), the label says
+ * exactly that instead of claiming there is no NODE_ENV at all.
+ */
+export function describeWorkspaceMode(env: WorkspaceEnvResult): string {
+	if (env.mode !== "unknown") {
+		return env.mode.toUpperCase();
+	}
+	const nodeEnv = env.evidence.find(
+		(e) => e.key === "NODE_ENV" && (e.source === "process.env" || e.source === ".env file"),
+	);
+	if (nodeEnv) {
+		return `UNKNOWN (NODE_ENV=${nodeEnv.value} is not a known mode)`;
+	}
+	return "UNKNOWN (no explicit NODE_ENV)";
+}
+
+/**
+ * Describe a dev/build server as a state.
+ *
+ * "not running (script available)" means the script EXISTS, i.e. a server
+ * could be started. It is not evidence that a server is running and not
+ * evidence about the workspace mode.
+ */
+export function describeServerState(running: boolean, hasScript: boolean): string {
+	if (running) return "running";
+	if (hasScript) return "not running (script available)";
+	return "no script";
+}
+
+/**
+ * One line status for the footer / status bar.
+ */
+export function formatEnvStatusLine(env: WorkspaceEnvResult): string {
+	const mode = describeWorkspaceMode(env);
+	const devStatus = describeServerState(env.devServerRunning, env.hasDevScript);
+	const buildStatus = describeServerState(env.buildServerRunning, env.hasBuildScript);
+
+	let status = `Workspace: ${mode} | dev server: ${devStatus} | build: ${buildStatus}`;
+	const ramStr = formatRam(env);
+	if (ramStr) {
+		status += ` | RAM: ${ramStr}`;
+	}
+
+	return status;
+}
+
+/**
+ * RAM segment of the status line.
+ *
+ * Both values are optional - an unreadable /proc must never produce a
+ * "7.7/null" line.
+ */
+function formatRam(env: WorkspaceEnvResult): string {
+	const total = env.ramTotalGb;
+	const available = env.ramAvailableGb;
+	if (total === null && available === null) return "";
+	if (total === null) return `${available}GB available`;
+	if (available === null) return `${total}GB total`;
+	return `${available}/${total}`;
+}
+
+/**
+ * RAM segment for the agent block.
+ */
+function formatRamForAgent(env: WorkspaceEnvResult): string {
+	const total = env.ramTotalGb;
+	const available = env.ramAvailableGb;
+	if (total !== null && available !== null) return `${available}/${total}GB available`;
+	if (total !== null) return `${total}GB total`;
+	return `${available}GB available`;
+}
+
+/**
+ * Multi line description for the agent context.
+ */
+export function formatEnvForAgentResult(env: WorkspaceEnvResult): string {
+	let message = `[Workspace Environment]\n`;
+	message += `Mode: ${describeWorkspaceMode(env)}\n`;
+
+	if (env.evidence.length > 0) {
+		const sources = env.evidence.map((e) => `${e.source}:${e.value}`).join(", ");
+		message += `Evidence: ${sources}\n`;
+	}
+
+	message += `Dev script: ${env.hasDevScript ? "yes" : "no"}\n`;
+	message += `Build script: ${env.hasBuildScript ? "yes" : "no"}\n`;
+
+	if (env.devServerRunning) {
+		message += `Dev server: running\n`;
+	}
+	if (env.buildServerRunning) {
+		message += `Build server: running\n`;
+	}
+
+	if (env.ramTotalGb !== null || env.ramAvailableGb !== null) {
+		message += `RAM: ${formatRamForAgent(env)}\n`;
+		if (env.lowRamWarning) {
+			message += `WARNING: Low RAM - avoid parallel build + dev\n`;
+		}
+	}
+
+	message += `\n`;
+	message += `Build allowed: ${env.buildAllowed ? "yes" : "no - requires explicit request"}\n`;
+
+	if (env.mode === "unknown") {
+		message += `\nNOTE: Environment unknown - a dev/build script only means a server CAN be started, it does not establish the workspace mode. Explicitly ask the user before build.\n`;
+	}
+
+	return message;
+}

package/packages/contracts/src/workspace-env.ts

@@ -14,6 +14,13 @@ import { DatabaseSync } from "node:sqlite";
 import { existsSync, readFileSync, mkdirSync } from "fs";
 import { join } from "path";
 import { platform, totalmem, freemem } from "os";
+import {
+	describeServerState,
+	describeWorkspaceMode,
+	formatEnvForAgentResult,
+	formatEnvStatusLine as formatStatusLine,
+} from "./workspace-env-format.js";
+import type { EnvEvidence, WorkspaceEnvResult, WorkspaceMode } from "./workspace-env-format.js";
 
 const STORE_DIR = join(process.env.HOME || "/home/frappe", ".pi-harness-runtime");
 
@@ -63,39 +70,16 @@ function initDatabase(): DatabaseSync {
 }
 
 /**
- * Workspace mode with explicit states
+ * The mode/evidence types and every human readable rendering of the workspace
+ * environment live in workspace-env-format.ts. They are re-exported here so
+ * the existing import paths keep working.
  */
-export type WorkspaceMode = "development" | "production" | "test" | "unknown";
-
-/**
- * Evidence source for mode detection
- */
-export interface EnvEvidence {
-	source: "process.env" | ".env file" | "package.json" | "command" | "detection";
-	key: string;
-	value: string;
-	timestamp: number;
-}
-
-/**
- * Workspace environment result
- */
-export interface WorkspaceEnvResult {
-	workspacePath: string;
-	mode: WorkspaceMode;
-	evidence: EnvEvidence[];
-	hasDevScript: boolean;
-	hasBuildScript: boolean;
-	packageManager: string | null;
-	devServerRunning: boolean;
-	buildServerRunning: boolean;
-	ramTotalGb: number | null;
-	ramAvailableGb: number | null;
-	ramEffectiveLimitGb: number | null;
-	lowRamWarning: boolean;
-	buildAllowed: boolean;
-	detectedAt: number;
-}
+export {
+	describeServerState,
+	describeWorkspaceMode,
+	formatEnvForAgentResult,
+};
+export type { EnvEvidence, WorkspaceEnvResult, WorkspaceMode };
 
 /**
  * Parse dotenv file without loading secrets
@@ -191,31 +175,22 @@ function determineMode(
 	// Explicit process.env takes highest priority (for build processes)
 	if (processEnv) {
 		const env = processEnv.toLowerCase();
+		// The evidence is recorded for EVERY value, including one that names
+		// no known mode ("staging"): the label then says which NODE_ENV could
+		// not be interpreted instead of claiming there is none.
+		evidence.push({
+			source: "process.env",
+			key: "NODE_ENV",
+			value: env,
+			timestamp: Date.now(),
+		});
 		if (env === "production") {
-			evidence.push({
-				source: "process.env",
-				key: "NODE_ENV",
-				value: env,
-				timestamp: Date.now(),
-			});
 			return "production";
 		}
 		if (env === "development" || env === "dev") {
-			evidence.push({
-				source: "process.env",
-				key: "NODE_ENV",
-				value: env,
-				timestamp: Date.now(),
-			});
 			return "development";
 		}
 		if (env === "test") {
-			evidence.push({
-				source: "process.env",
-				key: "NODE_ENV",
-				value: env,
-				timestamp: Date.now(),
-			});
 			return "test";
 		}
 	}
@@ -474,59 +449,12 @@ export function revalidateWorkspaceEnv(workspacePath: string): WorkspaceEnvResul
  * Format workspace env as agent-readable message
  */
 export function formatEnvForAgent(workspacePath: string): string {
-	const env = getWorkspaceEnv(workspacePath);
-
-	let message = `[Workspace Environment]\n`;
-	message += `Mode: ${env.mode.toUpperCase()}\n`;
-
-	if (env.evidence.length > 0) {
-		const sources = env.evidence.map((e) => `${e.source}:${e.value}`).join(", ");
-		message += `Evidence: ${sources}\n`;
-	}
-
-	message += `Dev script: ${env.hasDevScript ? "yes" : "no"}\n`;
-	message += `Build script: ${env.hasBuildScript ? "yes" : "no"}\n`;
-
-	if (env.devServerRunning) {
-		message += `Dev server: running\n`;
-	}
-	if (env.buildServerRunning) {
-		message += `Build server: running\n`;
-	}
-
-	if (env.ramTotalGb !== null) {
-		const ramStr = env.ramAvailableGb !== null
-			? `${env.ramAvailableGb}/${env.ramTotalGb}GB available`
-			: `${env.ramTotalGb}GB total`;
-		message += `RAM: ${ramStr}\n`;
-		if (env.lowRamWarning) {
-			message += `WARNING: Low RAM - avoid parallel build + dev\n`;
-		}
-	}
-
-	message += `\n`;
-	message += `Build allowed: ${env.buildAllowed ? "yes" : "no - requires explicit request"}\n`;
-
-	if (env.mode === "unknown") {
-		message += `\nNOTE: Environment unknown. Explicitly ask user before build.\n`;
-	}
-
-	return message;
+	return formatEnvForAgentResult(getWorkspaceEnv(workspacePath));
 }
 
 /**
  * Format workspace env as compact status line for UI
  */
 export function formatEnvStatusLine(env: WorkspaceEnvResult): string {
-	const mode = env.mode.toUpperCase();
-	const devStatus = env.devServerRunning ? "running" : (env.hasDevScript ? "available" : "none");
-	const buildStatus = env.buildServerRunning ? "running" : (env.hasBuildScript ? "explicit request" : "none");
-	const ramStr = env.ramAvailableGb !== null ? `${env.ramAvailableGb}/${env.ramTotalGb}` : "";
-
-	let status = `Workspace: ${mode} | dev server: ${devStatus} | build: ${buildStatus}`;
-	if (ramStr) {
-		status += ` | RAM: ${ramStr}`;
-	}
-
-	return status;
+	return formatStatusLine(env);
 }

package/packages/contracts/test/workspace-env.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	describeServerState,
+	describeWorkspaceMode,
+	formatEnvForAgentResult,
+	formatEnvStatusLine,
+} from "../src/workspace-env-format.ts";
+import type { EnvEvidence, WorkspaceEnvResult } from "../src/workspace-env-format.ts";
+
+function makeEnv(overrides: Partial<WorkspaceEnvResult> = {}): WorkspaceEnvResult {
+	return {
+		workspacePath: "/home/frappe/pi-harness-runtime",
+		mode: "unknown",
+		evidence: [],
+		hasDevScript: false,
+		hasBuildScript: false,
+		packageManager: "bun",
+		devServerRunning: false,
+		buildServerRunning: false,
+		ramTotalGb: 15,
+		ramAvailableGb: 7.7,
+		ramEffectiveLimitGb: null,
+		lowRamWarning: true,
+		buildAllowed: false,
+		detectedAt: 0,
+		...overrides,
+	};
+}
+
+describe("workspace mode wording", () => {
+	test("an unknown mode carries its reason", () => {
+		expect(describeWorkspaceMode(makeEnv())).toBe("UNKNOWN (no explicit NODE_ENV)");
+	});
+
+	test("an unrecognized NODE_ENV names the value that could not be read", () => {
+		const evidence: EnvEvidence[] = [
+			{ source: "process.env", key: "NODE_ENV", value: "staging", timestamp: 0 },
+		];
+
+		expect(describeWorkspaceMode(makeEnv({ evidence }))).toBe(
+			"UNKNOWN (NODE_ENV=staging is not a known mode)",
+		);
+	});
+
+	test("a known mode is reported plainly", () => {
+		expect(describeWorkspaceMode(makeEnv({ mode: "development" }))).toBe("DEVELOPMENT");
+		expect(describeWorkspaceMode(makeEnv({ mode: "production" }))).toBe("PRODUCTION");
+		expect(describeWorkspaceMode(makeEnv({ mode: "test" }))).toBe("TEST");
+	});
+
+	test("a dev script is a capability, not a state", () => {
+		expect(describeServerState(false, true)).toBe("not running (script available)");
+		expect(describeServerState(true, true)).toBe("running");
+		expect(describeServerState(false, false)).toBe("no script");
+	});
+});
+
+describe("formatEnvStatusLine", () => {
+	test("does not show a bare UNKNOWN next to an available dev script", () => {
+		const line = formatEnvStatusLine(makeEnv({ hasDevScript: true, hasBuildScript: true }));
+
+		expect(line).toContain("Workspace: UNKNOWN (no explicit NODE_ENV)");
+		expect(line).not.toContain("Workspace: UNKNOWN |");
+		expect(line).toContain("dev server: not running (script available)");
+		expect(line).toContain("build: not running (script available)");
+		expect(line).toContain("RAM: 7.7/15");
+	});
+
+	test("a running dev server is reported as running", () => {
+		const line = formatEnvStatusLine(makeEnv({ mode: "development", hasDevScript: true, devServerRunning: true }));
+
+		expect(line).toContain("Workspace: DEVELOPMENT");
+		expect(line).toContain("dev server: running");
+	});
+
+	test("a missing RAM reading omits the RAM segment", () => {
+		const line = formatEnvStatusLine(makeEnv({ ramTotalGb: null, ramAvailableGb: null }));
+
+		expect(line).not.toContain("RAM:");
+	});
+
+	test("a partial RAM reading never renders a null value", () => {
+		const available = formatEnvStatusLine(makeEnv({ ramTotalGb: null, ramAvailableGb: 7.7 }));
+		const total = formatEnvStatusLine(makeEnv({ ramTotalGb: 15, ramAvailableGb: null }));
+
+		expect(available).toContain("RAM: 7.7GB available");
+		expect(available).not.toContain("null");
+		expect(total).toContain("RAM: 15GB total");
+		expect(total).not.toContain("null");
+	});
+});
+
+describe("export surface of workspace-env.ts", () => {
+	// The module itself needs node:sqlite, which bun 1.3.x does not provide.
+	// Assert the re-export surface on the source text instead.
+	const source = readFileSync(
+		join(import.meta.dir, "..", "src", "workspace-env.ts"),
+		"utf8",
+	);
+
+	test("keeps re-exporting the formatting helpers", () => {
+		for (const name of [
+			"describeServerState",
+			"describeWorkspaceMode",
+			"formatEnvForAgentResult",
+		]) {
+			expect(source).toContain(name);
+		}
+	});
+
+	test("keeps exporting the detector functions", () => {
+		for (const name of [
+			"detectWorkspaceEnv",
+			"loadWorkspaceEnv",
+			"getWorkspaceEnv",
+			"revalidateWorkspaceEnv",
+			"formatEnvForAgent",
+			"formatEnvStatusLine",
+		]) {
+			expect(source).toContain(`export function ${name}`);
+		}
+	});
+});
+
+describe("formatEnvForAgentResult", () => {
+	test("explains that a dev script does not establish the mode", () => {
+		const text = formatEnvForAgentResult(makeEnv({ hasDevScript: true }));
+
+		expect(text).toContain("Mode: UNKNOWN (no explicit NODE_ENV)");
+		expect(text).toContain("Dev script: yes");
+		expect(text).toContain("Build allowed: no - requires explicit request");
+		expect(text).toContain("a dev/build script only means a server CAN be started");
+	});
+
+	test("a known mode drops the unknown-mode note", () => {
+		const text = formatEnvForAgentResult(makeEnv({ mode: "production", buildAllowed: true }));
+
+		expect(text).toContain("Mode: PRODUCTION");
+		expect(text).toContain("Build allowed: yes");
+		expect(text).not.toContain("Environment unknown");
+	});
+});

package/packages/cookie-sanitizer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/cookie-sanitizer",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "pi-harness-runtime — cookie sanitizer (provider-quota cookie file normaliser)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/cost-optimizer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/cost-optimizer",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Cost Optimizer for pi-harness-runtime — budget tracking, forecasting, and model selection optimization",
   "type": "module",
   "main": "./dist/index.js",

package/packages/dependency-analyzer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/dependency-analyzer",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/django-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/django-plugin",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Django framework analysis — models, management commands, settings",
   "type": "module",
   "main": "./dist/index.js",

package/packages/doc-generator/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/doc-generator",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Auto-Doc Generator — generate documentation from source code (RFC-0014)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/durable-review/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/durable-review",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "SQLite-backed durable reviewer using @earendil-works/pi-durable",
   "type": "module",
   "main": "src/index.ts",

package/packages/e2e-tester/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/e2e-tester",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "WebMCP-powered E2E testing for pi-harness - natural language test scenarios",
   "type": "module",
   "main": "./dist/index.js",

package/packages/evaluation-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/evaluation-engine",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Evaluation engine for pi-harness runtime (RFC-0057)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/evaluation-runner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/evaluation-runner",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "type": "module",
   "description": "Framework-agnostic evaluation framework for AI outputs (RFC-0020)",
   "main": "dist/index.js",

package/packages/event-bus/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/event-bus",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/event-sink/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/event-sink",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "type": "module",
   "description": "Atomic event sourcing with SQLite transactions for pi-harness",
   "main": "./dist/index.js",

package/packages/event-store/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/event-store",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/experience-replay/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/experience-replay",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Experience replay for debugging and reproducibility (RFC-0059)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/feedback-collector/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/feedback-collector",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "type": "module",
   "description": "Collect and aggregate human/automated feedback (RFC-0021)",
   "main": "dist/index.js",

package/packages/file-copy-helper/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/file-copy-helper",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Injects cp/sudo cp rule when user asks to mimic/copy files",
   "type": "module",
   "main": "dist/index.js",

package/packages/framework-detector/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/framework-detector",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Framework detection system for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/framework-plugin-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/framework-plugin-sdk",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Framework plugin SDK for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/frappe-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/frappe-plugin",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Frappe/ERPNext framework analysis — DocTypes, hooks, bench sites, site config",
   "type": "module",
   "main": "./dist/index.js",

package/packages/generic-web-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/generic-web-plugin",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Generic web framework analysis — REST/GraphQL endpoints, OpenAPI, auth",
   "type": "module",
   "main": "./dist/index.js",

package/packages/health-monitor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/health-monitor",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "type": "module",
   "description": "Health monitoring and auto-healing",
   "main": "dist/index.js",

package/packages/intent-analyzer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/intent-analyzer",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/jev-judge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/jev-judge",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Jev Judge - Structured decision model for agent routing, E2E testing, and automated decisions",
   "type": "module",
   "main": "./dist/index.js",