acrylblends 1.0.6 → 1.0.8

package/dist/index.js

@@ -4,8 +4,10 @@ import { basename, dirname, join, posix, relative, resolve, sep } from "node:pat
 import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
+import { createServer } from "node:net";
+import { homedir } from "node:os";
 //#region src/templates.ts
 /** The templates, all Cordis apps: a web app with a page and a client component (nodejs), a notes app and a chat app on the db port (notes, chat), a blank app on the router, a todo list on the router and state, and the blank app with the offline agent. */
 const TEMPLATES = [
@@ -1262,6 +1264,272 @@ async function kvImport(options, io) {
 	}
 }
 //#endregion
+//#region src/preflight.ts
+/** The Node the framework needs (the bin refuses an older one before loading anything). */
+const NODE_MINIMUM = [22, 19];
+/** The range an app's port is chosen in (plugins/instance: PORT_BASE and PORT_SPAN). */
+const APP_PORTS = [3100, 3999];
+const AGENTS = [
+	"claude",
+	"codex",
+	"pi"
+];
+const AGENT_INSTALL = "install one coding agent: npm i -g @openai/codex then codex login, or Claude Code (https://claude.com/claude-code), or npm i -g @earendil-works/pi-coding-agent with DEEPSEEK_API_KEY set";
+/** Off by default on Windows; a full workshop ran without it, so it is a NOTE: what to do if a path is ever too long. */
+const LONG_PATHS_NOTE = "off; if an install fails with ENAMETOOLONG or \"path too long\", in PowerShell as administrator: New-ItemProperty -Path HKLM:\\SYSTEM\\CurrentControlSet\\Control\\FileSystem -Name LongPathsEnabled -Value 1 -PropertyType DWORD -Force";
+const firstLine = (text) => text.trim().split(/\r?\n/)[0]?.trim() ?? "";
+function checkNode(version) {
+	const [major = 0, minor = 0] = version.split(".").map(Number);
+	const [needMajor, needMinor] = NODE_MINIMUM;
+	return major > needMajor || major === needMajor && minor >= needMinor ? {
+		name: "node",
+		status: "PASS",
+		detail: version
+	} : {
+		name: "node",
+		status: "FIX",
+		detail: `${version} is too old: install Node ${needMajor}.${needMinor} or newer (the LTS) from https://nodejs.org`
+	};
+}
+async function checkNpm(probes) {
+	const npm = packageManagerInvocation("npm", ["--version"], probes.platform, probes.env);
+	const result = await probes.run(npm.file, npm.args);
+	return result.code === 0 ? {
+		name: "npm",
+		status: "PASS",
+		detail: firstLine(result.stdout)
+	} : {
+		name: "npm",
+		status: "FIX",
+		detail: "npm did not run: it comes with Node, reinstall Node from https://nodejs.org"
+	};
+}
+async function checkGit(probes) {
+	const result = await probes.run("git", ["--version"]);
+	return result.code === 0 ? {
+		name: "git",
+		status: "PASS",
+		detail: firstLine(result.stdout).replace(/^git version /, "")
+	} : {
+		name: "git",
+		status: "FIX",
+		detail: "install git from https://git-scm.com"
+	};
+}
+/** Whether pi can reach DeepSeek: the key in the environment, or the one pi stored when its owner logged in (the panel's rule). */
+function piHasKey(probes) {
+	if (probes.env.DEEPSEEK_API_KEY) return true;
+	const stored = probes.readFile(join(probes.env.PI_CODING_AGENT_DIR ?? join(probes.home, ".pi", "agent"), "auth.json"));
+	if (stored === void 0) return false;
+	try {
+		const key = JSON.parse(stored).deepseek?.key;
+		return typeof key === "string" && key !== "";
+	} catch {
+		return false;
+	}
+}
+/**
+* The coding agents the agent panel would offer: on the PATH, and pi only with a DeepSeek key. On Windows the panel also reads an npm shim to find
+* its script (plugins/agent-panel/launch.ts); that is plugin code an app carries, not something the command imports, so the PATH is checked here.
+*/
+const HINT = {
+	claude: "be logged in: run claude once",
+	codex: "be logged in: codex login",
+	pi: "DeepSeek key found"
+};
+function checkAgent(probes) {
+	const installed = AGENTS.filter((agent) => probes.onPath(agent));
+	const usable = installed.filter((agent) => agent !== "pi" || piHasKey(probes));
+	if (usable.length > 0) return {
+		name: "agent",
+		status: "PASS",
+		detail: usable.map((agent) => `${agent} (${HINT[agent]})`).join(", ")
+	};
+	if (installed.includes("pi")) return {
+		name: "agent",
+		status: "FIX",
+		detail: "pi has no DeepSeek key: set DEEPSEEK_API_KEY, or log in to pi once, or install another agent"
+	};
+	return {
+		name: "agent",
+		status: "FIX",
+		detail: AGENT_INSTALL
+	};
+}
+async function checkPort(probes) {
+	const [from, to] = APP_PORTS;
+	const found = await probes.freePort(from, to);
+	return typeof found === "number" ? {
+		name: "port",
+		status: "PASS",
+		detail: `127.0.0.1:${found} is free (apps use ${from}-${to})`
+	} : {
+		name: "port",
+		status: "FIX",
+		detail: `nothing can listen on 127.0.0.1 in ${from}-${to} (${found}): allow Node in the firewall or security software, or free a port`
+	};
+}
+/** Only block 5 needs gh, so it is a NOTE, never a FIX. */
+async function checkGh(probes) {
+	if (!probes.onPath("gh")) return {
+		name: "gh",
+		status: "NOTE",
+		detail: "not installed; block 5 publishes with it: https://cli.github.com, then gh auth login"
+	};
+	return (await probes.run("gh", ["auth", "status"])).code === 0 ? {
+		name: "gh",
+		status: "PASS",
+		detail: "logged in"
+	} : {
+		name: "gh",
+		status: "NOTE",
+		detail: "not logged in; block 5 needs it: gh auth login"
+	};
+}
+async function checkPowerShell(probes) {
+	const pwsh = probes.onPath("pwsh");
+	const result = await probes.run("powershell.exe", [
+		"-NoProfile",
+		"-Command",
+		"$PSVersionTable.PSVersion.ToString()"
+	]);
+	const version = result.code === 0 ? firstLine(result.stdout) : void 0;
+	if (pwsh) return {
+		name: "powershell",
+		status: "PASS",
+		detail: `pwsh 7 found${version ? `, Windows PowerShell ${version}` : ""}`
+	};
+	if (version !== void 0) return {
+		name: "powershell",
+		status: "PASS",
+		detail: `Windows PowerShell ${version}: use the guide's PowerShell lines where they differ (&& and NODE_ENV=... need PowerShell 7)`
+	};
+	return {
+		name: "powershell",
+		status: "NOTE",
+		detail: "powershell.exe did not run; use cmd.exe lines or install PowerShell 7 (winget install Microsoft.PowerShell)"
+	};
+}
+async function checkLongPaths(probes) {
+	const result = await probes.run("reg", [
+		"query",
+		"HKLM\\SYSTEM\\CurrentControlSet\\Control\\FileSystem",
+		"/v",
+		"LongPathsEnabled"
+	]);
+	const value = /LongPathsEnabled\s+REG_DWORD\s+0x([0-9a-f]+)/i.exec(result.stdout)?.[1];
+	return value !== void 0 && Number.parseInt(value, 16) === 1 ? {
+		name: "long paths",
+		status: "PASS",
+		detail: "enabled"
+	} : {
+		name: "long paths",
+		status: "NOTE",
+		detail: LONG_PATHS_NOTE
+	};
+}
+/** Git Bash rewrites a slash-led argument into a Windows path (`/board` becomes `C:/Program Files/Git/board`); the door undoes it from 1.0.7. */
+function checkGitBash(probes) {
+	if (!probes.env.MSYSTEM) return void 0;
+	return {
+		name: "git bash",
+		status: "NOTE",
+		detail: "this shell rewrites /paths: the door handles it from acrylblends 1.0.7; on an older app run .acryl/bin/acryl from PowerShell, or npx acrylblends@latest upgrade"
+	};
+}
+async function preflight(probes) {
+	const checks = [
+		checkNode(probes.nodeVersion),
+		await checkNpm(probes),
+		await checkGit(probes),
+		checkAgent(probes),
+		await checkPort(probes),
+		await checkGh(probes)
+	];
+	if (probes.platform === "win32") {
+		checks.push(await checkPowerShell(probes), await checkLongPaths(probes));
+		const gitBash = checkGitBash(probes);
+		if (gitBash) checks.push(gitBash);
+	}
+	return checks;
+}
+function formatChecks(checks) {
+	const width = Math.max(...checks.map((check) => check.name.length));
+	const lines = checks.map((check) => `${check.status.padEnd(4)}  ${check.name.padEnd(width)}  ${check.detail}`);
+	const fixes = checks.filter((check) => check.status === "FIX").length;
+	lines.push(fixes === 0 ? "Ready for the workshop." : `${fixes} to fix before the workshop: run each FIX line, then npx acrylblends@latest preflight again.`);
+	return `${lines.join("\n")}\n`;
+}
+/** The real machine. A program that cannot start resolves with code null; nothing here throws. */
+function machineProbes() {
+	return {
+		platform: process.platform,
+		nodeVersion: process.versions.node,
+		env: process.env,
+		home: homedir(),
+		run: (file, args) => new Promise((done) => {
+			let stdout = "";
+			const child = spawn(file, args, {
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				],
+				windowsHide: true
+			});
+			const timer = setTimeout(() => child.kill(), 15e3);
+			child.stdout.on("data", (chunk) => {
+				stdout += chunk.toString();
+			});
+			child.on("error", () => {
+				clearTimeout(timer);
+				done({
+					code: null,
+					stdout
+				});
+			});
+			child.on("close", (code) => {
+				clearTimeout(timer);
+				done({
+					code,
+					stdout
+				});
+			});
+		}),
+		onPath: (program) => spawnSync(process.platform === "win32" ? "where" : "which", [program], { windowsHide: true }).status === 0,
+		readFile: (path) => {
+			try {
+				return readFileSync(path, "utf8");
+			} catch {
+				return;
+			}
+		},
+		freePort: async (from, to) => {
+			let last = "no port tried";
+			for (let port = from; port <= to; port++) {
+				const result = await new Promise((done) => {
+					const server = createServer();
+					server.once("error", (error) => done(error.code ?? error.message));
+					server.listen({
+						port,
+						host: "127.0.0.1",
+						exclusive: true
+					}, () => server.close(() => done(true)));
+				});
+				if (result === true) return port;
+				last = result;
+				if (last !== "EADDRINUSE") return last;
+			}
+			return last;
+		}
+	};
+}
+async function runPreflight(io, probes = machineProbes()) {
+	const checks = await preflight(probes);
+	io.stdout.write(formatChecks(checks));
+	return checks.some((check) => check.status === "FIX") ? 1 : 0;
+}
+//#endregion
 //#region src/diff.ts
 function ops(a, b) {
 	if (a.length * b.length > 6e6) return void 0;
@@ -1563,6 +1831,8 @@ Usage:
                                       Bring the library plugins an app carries (the router, the server, the door, ...) up to this
                                       version: untouched files are replaced, an edited file stops it (diff shown) unless --force
   acrylblends plugins                    List the plugin library
+  acrylblends preflight                  Check this machine for the workshop: Node, npm, git, a coding agent, a free port
+                                      (and on Windows PowerShell and long paths); one line per check, PASS or the fix
   acrylblends build-client [root] [out]  Compile the client modules once for production (src/client to dist/client)
   acrylblends kv import <kv.json> <db>   Move a JSON-file kv store into the kv table of a SQLite database [--overwrite] [--table t] [--migrations dir]
   acrylblends check-deps [dir]           Fail when app code imports a database driver or opener outside the file named in
@@ -1603,6 +1873,7 @@ async function runCli(argv, io = processIo()) {
 		if (command === "kv") return await kvImport(parseKv(args), io);
 		if (command === "check-deps") return checkDeps(parseCheckDeps(args), io);
 		if (command === "plugins") return listPlugins(io);
+		if (command === "preflight") return await runPreflight(io);
 		throw new UsageError(`unknown command "${command}"`);
 	} catch (error) {
 		if (error instanceof UsageError) {