gentle-pi 4.0.0 → 4.2.0

package/scripts/install-gentle-ai.mjs

@@ -8,6 +8,52 @@ import { fileURLToPath } from "node:url";
 import { INSTALLER_VERSION, installGentleAi } from "./gentle-ai-installer.mjs";
 import { installTuiModeSetting, isPiManagedInstall } from "./install-tui-mode-setting.mjs";
 
+const FAILURE_CAUSE_DEPTH = 6;
+const FAILURE_OUTPUT_TAIL = 4000;
+
+function failureOutputs(error) {
+	return ["stderr", "stdout"].map((stream) => [stream, typeof error?.[stream] === "string" ? error[stream].trimEnd() : ""]).filter(([, text]) => text.trim().length > 0);
+}
+
+function failureHeadline(error, outputs) {
+	const message = error instanceof Error ? error.message : String(error);
+	// A child-process error repeats its stderr after the first message line; it is printed below, bounded.
+	const text = outputs.length > 0 ? message.split(/\r?\n/)[0] : message;
+	const status = [
+		...(typeof error?.code === "string" || typeof error?.code === "number" ? [`code ${error.code}`] : []),
+		...(typeof error?.signal === "string" ? [`signal ${error.signal}`] : []),
+	];
+	return `${text}${status.length > 0 ? ` (${status.join(", ")})` : ""}`;
+}
+
+/**
+ * A failed installation for the postinstall's stderr: the error's message, then its
+ * `cause` chain (at most 6 deep) with each code and the last 4000 characters of any
+ * stdout/stderr a failed command left on it. When a cause carried output, the last
+ * line repeats the deepest one's last output line in `Error:` form, the line the
+ * installer wizard's one-line failure detail selects after pnpm's own summary.
+ */
+function describeGentleAiInstallFailure(error) {
+	const lines = [];
+	let rootCause = null;
+	let cause = error;
+	for (let depth = 0; cause !== undefined && cause !== null && depth <= FAILURE_CAUSE_DEPTH; depth += 1) {
+		const outputs = failureOutputs(cause);
+		const name = cause instanceof Error && typeof cause.name === "string" && cause.name !== "" ? cause.name : "Error";
+		lines.push(depth === 0 ? failureHeadline(cause, outputs) : `  caused by ${name}: ${failureHeadline(cause, outputs)}`);
+		for (const [stream, text] of outputs) {
+			const tail = text.length > FAILURE_OUTPUT_TAIL ? text.slice(-FAILURE_OUTPUT_TAIL) : text;
+			lines.push(`    ${stream}${tail === text ? "" : ` (last ${FAILURE_OUTPUT_TAIL} characters)`}:`, ...tail.split(/\r?\n/).map((line) => `    | ${line}`));
+		}
+		// stderr first: a deeper cause's output replaces a shallower one's.
+		if (outputs.length > 0) rootCause = outputs[0][1].split(/\r?\n/).findLast((line) => line.trim().length > 0).trim();
+		cause = cause instanceof Error ? cause.cause : undefined;
+	}
+	if (cause !== undefined && cause !== null) lines.push("  ... further causes omitted");
+	if (rootCause !== null) lines.push(`  root cause Error: ${rootCause}`);
+	return lines.join("\n");
+}
+
 if (process.env.GENTLE_PI_SKIP_GENTLE_AI_INSTALL === "1") {
 	console.warn("GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1: skipped package-local Gentle AI installation; native review operations will fail with package-local-binary-missing until gentle-pi is reinstalled.");
 } else {
@@ -15,7 +61,8 @@ if (process.env.GENTLE_PI_SKIP_GENTLE_AI_INSTALL === "1") {
 		const result = await installGentleAi();
 		console.log(`Gentle AI v${INSTALLER_VERSION} ${result.installed ? "installed" : "integrity-verified"} at ${result.binaryPath}`);
 	} catch (error) {
-		console.error(`gentle-pi could not install its package-local Gentle AI v${INSTALLER_VERSION} binary: ${error instanceof Error ? error.message : String(error)}`);
+		// The whole cause chain: the failing command's own output is the diagnosis.
+		console.error(`gentle-pi could not install its package-local Gentle AI v${INSTALLER_VERSION} binary: ${describeGentleAiInstallFailure(error)}`);
 		process.exitCode = 1;
 	}
 }

package/scripts/install-tui-mode-setting.mjs

@@ -65,6 +65,15 @@ function sameFile(left, right) {
 	return left && right && left.dev === right.dev && left.ino === right.ino;
 }
 
+// A path's lstat against the fstat of the handle just opened on it. On recent
+// Windows, lstat by path reports dev 0 (no volume serial) while fstat reports
+// the volume's (#1258, #2109): there the file index alone identifies it, and a
+// known dev must still match. POSIX keeps the full device and inode check.
+export function sameOpenedFile(pathStat, handleStat, platform = process.platform) {
+	if (platform !== "win32" || !pathStat || !handleStat || (pathStat.dev !== 0 && handleStat.dev !== 0)) return Boolean(sameFile(pathStat, handleStat));
+	return pathStat.ino === handleStat.ino;
+}
+
 function assertDirectories(paths) {
 	for (const path of paths) {
 		const stat = inspect(path);
@@ -80,7 +89,7 @@ function readSettings(path) {
 	if (!before.isFile() || before.isSymbolicLink()) throw new Error("settings.json must be a regular, non-symlink file");
 	const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
 	try {
-		if (!sameFile(before, fstatSync(fd))) throw new Error("settings.json changed while opening");
+		if (!sameOpenedFile(before, fstatSync(fd))) throw new Error("settings.json changed while opening");
 		const text = readFileSync(fd, "utf8");
 		const value = JSON.parse(text.replace(/^\uFEFF/, ""));
 		if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("settings.json must contain a JSON object");

package/scripts/install-wizard-preview.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// Development preview for the browser installation wizard.
+//
+// Starts the REAL local host (createInstallerServer) with the real assets, but
+// with fake inventories and a fake runner: it never runs host probes, package
+// managers, downloads or installs. Use it to develop and visually check the UI:
+//
+//   node scripts/install-wizard-preview.mjs --scenario=terminal --step-ms=600
+//
+// Then open the printed one-time session URL. Not part of the installer entry.
+
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { PI_INSTALL_VERSION, planPreflight, requirements } from "./installer-preflight.mjs";
+import { createInstallerServer } from "./installer-server.mjs";
+
+const BIN = "/home/you/.local/share/pnpm/bin";
+const baseInventory = Object.freeze({
+	platform: "linux",
+	arch: "x64",
+	node: { available: true, version: "24.21.0", usable: true, persistent: true, npm: true },
+	pnpm: { available: true, version: "11.1.1", usable: true, compatible: true, persistent: true },
+	pi: { available: false },
+	shell: { available: false },
+	gentleAi: { available: false },
+	go: { available: false },
+	globalBin: { available: true, path: BIN, writable: true, onPath: true },
+	setup: false,
+});
+// A machine that only has the bootstrap's temporary Node and pnpm, with no pnpm bin on PATH.
+const freshInventory = Object.freeze({
+	...baseInventory,
+	node: { available: true, version: "24.21.0", usable: true, persistent: false, npm: false },
+	pnpm: { available: true, version: "11.1.1", usable: true, compatible: true, persistent: false },
+	globalBin: { ...baseInventory.globalBin, onPath: false },
+});
+// An earlier run installed the pinned stack, but its setup and `pnpm setup` did not finish.
+const recoveryInventory = Object.freeze({
+	...baseInventory,
+	pi: { available: true, version: PI_INSTALL_VERSION, usable: true },
+	shell: { available: true, version: requirements.shell, usable: true, global: true },
+	gentleAi: { available: true, version: requirements.gentleAi, usable: true, compatible: true },
+	globalBin: { ...baseInventory.globalBin, onPath: false },
+	setup: { available: true, recoverable: true },
+});
+const checks = ["check-npm", "check-global-bin", "check-existing-stack"];
+const install = ["install-global", "verify-global-list", "verify-shell-bin", "verify-gentle-ai", "shell-setup"];
+const persistence = ["persist-node", "persist-package-managers", "verify-persistent-runtime", "check-npm", "configure-npm-prefix"];
+
+// Each scenario mirrors the runner's fixed step order for its plan.
+const scenarios = Object.freeze({
+	ready: { inventories: [baseInventory], steps: [...checks, ...install], result: { outcome: "ready" } },
+	terminal: {
+		inventories: [freshInventory],
+		steps: ["check-global-bin", "check-existing-stack", ...persistence, ...install, "persist-path"],
+		result: { outcome: "terminal-action-required", action: "open-new-terminal", npmPrefix: "configured" },
+	},
+	blocked: {
+		inventories: [baseInventory],
+		steps: ["check-npm", "check-global-bin"],
+		result: { outcome: "blocked", reason: "existing-stack" },
+	},
+	failed: {
+		inventories: [freshInventory],
+		steps: ["check-global-bin", "check-existing-stack", ...persistence],
+		result: { outcome: "failed", failedStep: "install-global" },
+	},
+	// The first plan goes stale before install (the PATH was fixed meanwhile): the host
+	// answers 409 plan-changed and the wizard must show the new plan and ask again.
+	"plan-changed": { inventories: [freshInventory, baseInventory], steps: [...checks, ...install], result: { outcome: "ready" } },
+	recovery: {
+		inventories: [recoveryInventory],
+		steps: ["check-npm", "check-global-bin", "check-recoverable-stack", ...install.slice(1), "persist-path"],
+		result: { outcome: "terminal-action-required", action: "open-new-terminal" },
+	},
+	preflight: {
+		inventories: [{ ...baseInventory, node: { available: true, version: "18.20.0", usable: true, persistent: true, npm: true },
+			gentleAi: { available: true, version: "1.0.0", usable: true, compatible: false } }],
+		steps: [],
+		result: { outcome: "blocked", reason: "preflight-blocked" },
+	},
+});
+export const scenarioNames = Object.freeze(Object.keys(scenarios));
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Fake collectPlan/runInstall for a scenario; nothing touches the machine. */
+export function previewScenario(name, { stepMs = 600 } = {}) {
+	const scenario = scenarios[name];
+	if (!scenario) throw new Error(`Unknown scenario "${name}". Use one of: ${scenarioNames.join(", ")}`);
+	let collected = 0;
+	return {
+		collectPlan: async () => {
+			const inventory = structuredClone(scenario.inventories[Math.min(collected, scenario.inventories.length - 1)]);
+			collected += 1;
+			await sleep(Math.min(stepMs, 400));
+			return { inventory, plan: planPreflight(inventory) };
+		},
+		runInstall: async (_request, log) => {
+			const completed = [];
+			for (const step of scenario.steps) {
+				await sleep(stepMs);
+				completed.push(step);
+				log({ step, status: "done" });
+			}
+			await sleep(stepMs);
+			const { result } = scenario;
+			if (result.outcome === "blocked") log({ step: "gate", status: "blocked", reason: result.reason });
+			if (result.outcome === "failed") log({ step: result.failedStep, status: "failed" });
+			return { ...result, completed };
+		},
+	};
+}
+
+/** Starts the real host on 127.0.0.1 with a fake scenario. Returns { host, url }. */
+export async function startPreview({ scenario = "ready", stepMs = 600, log = console.log } = {}) {
+	const fake = previewScenario(scenario, { stepMs });
+	const host = createInstallerServer({
+		assetsDir: fileURLToPath(new URL("../assets/install-wizard/", import.meta.url)),
+		collectPlan: fake.collectPlan,
+		runInstall: fake.runInstall,
+	});
+	const { url } = await host.listen();
+	log(`Gentle Shell wizard preview (scenario: ${scenario}). Fake plan and fake installer: nothing is installed.`);
+	log(`Open this one-time link (expires in 2 minutes):\n  ${url}`);
+	return { host, url };
+}
+
+function option(args, name, fallback) {
+	const found = args.find((arg) => arg.startsWith(`--${name}=`));
+	return found === undefined ? fallback : found.slice(name.length + 3);
+}
+
+async function main(args) {
+	if (args.includes("--help")) {
+		console.log(`Usage: node scripts/install-wizard-preview.mjs [--scenario=${scenarioNames.join("|")}] [--step-ms=600]`);
+		return;
+	}
+	const scenario = option(args, "scenario", "ready");
+	const stepMs = Number(option(args, "step-ms", "600"));
+	if (!scenarioNames.includes(scenario) || !Number.isFinite(stepMs) || stepMs < 0) {
+		console.error(`Use --scenario=${scenarioNames.join("|")} and a non-negative --step-ms.`);
+		process.exitCode = 2;
+		return;
+	}
+	const { host } = await startPreview({ scenario, stepMs });
+	process.once("SIGINT", () => host.close("signal"));
+	process.once("SIGTERM", () => host.close("signal"));
+	const { reason, outcome } = await host.closed;
+	console.log(`Preview closed (${reason}); last outcome: ${outcome?.outcome ?? "none"}.`);
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	await main(process.argv.slice(2));
+}