electrobun 2.0.1-beta.6 → 2.0.1

package/README.md

@@ -1,10 +1,15 @@
 # Electrobun npm bootstrap
 
-The `electrobun` npm package is a small compatibility entry point for npm,
-pnpm, Yarn, and Bun users. It contains no Electrobun runtime or SDK. The
-`electrobun` command installs Hutch into `~/.hutch` (override with
-`HUTCH_HOME`; `DASH_HOME` is honored as a deprecated fallback) when necessary
-and delegates all commands to `hutch electrobun`.
+The dependency-free `electrobun` npm package is a small Hutch entry point for
+npm, pnpm, Yarn, and Bun users. It contains no Electrobun runtime, SDK, or
+platform-specific npm dependency. On first use, the `electrobun` command reads
+the `hutch-artifacts.json` index for its exact version, downloads the host's
+matching Hutch archive from the indexed immutable Electrobun GitHub Release
+URL, checks its byte length and SHA-256 digest against that index entry, caches
+the extracted launcher and engine safely, and delegates all commands to `hutch
+electrobun`. `electrobun init` additionally ensures a compatible global
+Hutch launcher is present for the generated project's `hutch run ...` tasks;
+init itself still runs through the exact private cache.
 
 Create a project from the current stable template catalog:
 
@@ -18,17 +23,27 @@ Use the beta catalog only when you ask for it:
 npx electrobun init --beta
 ```
 
-The npm bootstrap ships under the same release version as Electrobun, but it
-does not contain or select the runtime by itself. An application's exact
-Electrobun version is selected in `hutch.config.ts`; Hutch downloads the
-matching runtime and SDK into the shared `~/.hutch` store and projects the SDKs
-into the project's `.hutch/devkit` sysroot. Installing a beta bootstrap still
-uses stable templates unless `init` receives `--beta`.
+The npm bootstrap supplies the exact Hutch and Electrobun defaults paired with
+its own release version. Those defaults are not overrides: published templates
+include an exact `electrobun.version`, and an exact `// @hutch` pragma or
+product pin in `hutch.config.ts` always wins. In an unpinned hand-written
+project, the installed package version selects the toolchain for npm-launched
+commands, so the single `electrobun` dependency and its immutable GitHub Release
+assets ride the project lockfile together. Hutch
+downloads the matching runtime and SDK into the shared
+`~/.hutch/releases/electrobun` store and projects the SDKs into the project's
+`.hutch/devkit` sysroot. Hutch's paired Cottontail is the build-time runtime;
+the Cottontail bundled into an app is separately pinned by that resolved
+Electrobun devkit. Installing a beta bootstrap still uses stable templates
+unless `init` receives `--beta`.
 
 `DASH_RELEASE_OFFLINE=1` prevents this bootstrap from downloading a missing
-Hutch installation. An already installed Hutch is still invoked, and the flag
-continues to prevent network access for Dash-managed releases and artifacts.
-It does not put npm or another project package manager into offline mode.
+Hutch archive. A previously verified cached copy can still run, but
+`electrobun init` requires network access for the current template catalog and
+selected template. Builds can run without network access only when every exact
+release and managed toolchain they require is already installed. The flag does
+not put Hutch's built-in dependency resolver or an external project package
+manager into offline mode.
 
 You can install Hutch directly from <https://hutch.blackboard.sh> and run the
 same commands without npm:

package/bin/electrobun.cjs

@@ -1,58 +1,14 @@
 #!/usr/bin/env node
 "use strict";
 
-const { spawnSync } = require("node:child_process");
-const { existsSync, mkdtempSync, rmSync, writeFileSync } = require("node:fs");
-const { get } = require("node:https");
-const { homedir, tmpdir } = require("node:os");
-const path = require("node:path");
+// The electrobun front door: resolves the vendored (or installed) Hutch and
+// forwards every argument to `hutch electrobun`, supplying this release's
+// paired toolchain versions as defaults for unpinned projects.
 
-const installerBaseUrl = "https://hutch.blackboard.sh/hutch";
-const maxInstallerBytes = 1024 * 1024;
-const maxInstallerRedirects = 5;
-
-function normalizeChannel(value) {
-	if (value === "stable") return "production";
-	if (value === "production" || value === "canary") return value;
-	return null;
-}
-
-function hutchChannel(environment) {
-	for (const key of ["ELECTROBUN_HUTCH_CHANNEL", "HUTCH_ACTIVE_CHANNEL"]) {
-		const selected = normalizeChannel(environment[key]);
-		if (selected) return selected;
-	}
-	return "production";
-}
-
-function environmentFlagEnabled(environment, name) {
-	const value = environment[name];
-	return (
-		value === "1" ||
-		(typeof value === "string" &&
-			["true", "yes"].includes(value.toLowerCase()))
-	);
-}
-
-function hutchBinaryPath(channel, environment, platform, userHome) {
-	if (environment.ELECTROBUN_HUTCH_BINARY) {
-		return environment.ELECTROBUN_HUTCH_BINARY;
-	}
-
-	// HUTCH_HOME is Hutch's own home; DASH_HOME stays honored as a deprecated
-	// fallback for Dash Desktop and older setups.
-	const hutchHome =
-		environment.HUTCH_HOME ||
-		environment.DASH_HOME ||
-		path.join(userHome, ".hutch");
-	const command = channel === "canary" ? "hutch-canary" : "hutch";
-	const pathApi = platform === "win32" ? path.win32 : path.posix;
-	return pathApi.join(
-		hutchHome,
-		"bin",
-		`${command}${platform === "win32" ? ".exe" : ""}`,
-	);
-}
+const {
+	resolveHutchBinary,
+	runHutch,
+} = require("./resolve-hutch.cjs");
 
 function hutchArguments(args) {
 	const forwarded = Array.from(args);
@@ -68,163 +24,15 @@ function hutchArguments(args) {
 		: [...forwarded, "--channel=stable"];
 }
 
-function download(url, redirects = 0) {
-	if (redirects > maxInstallerRedirects) {
-		return Promise.reject(new Error("too many installer redirects"));
-	}
-
-	let target;
-	try {
-		target = new URL(url);
-	} catch {
-		return Promise.reject(new Error("invalid Hutch installer URL"));
-	}
-	if (target.protocol !== "https:") {
-		return Promise.reject(
-			new Error("the Hutch installer must be downloaded over HTTPS"),
-		);
-	}
-
-	return new Promise((resolve, reject) => {
-		const request = get(target, (response) => {
-			if (
-				response.statusCode >= 300 &&
-				response.statusCode < 400 &&
-				response.headers.location
-			) {
-				response.resume();
-				let redirected;
-				try {
-					redirected = new URL(response.headers.location, target);
-				} catch {
-					reject(new Error("invalid Hutch installer redirect URL"));
-					return;
-				}
-				resolve(download(redirected.href, redirects + 1));
-				return;
-			}
-
-			if (response.statusCode !== 200) {
-				response.resume();
-				reject(
-					new Error(
-						`installer download returned HTTP ${response.statusCode ?? "unknown"}`,
-					),
-				);
-				return;
-			}
-
-			const chunks = [];
-			let size = 0;
-			response.on("data", (chunk) => {
-				size += chunk.length;
-				if (size > maxInstallerBytes) {
-					request.destroy(
-						new Error("installer download exceeded the 1 MiB limit"),
-					);
-					return;
-				}
-				chunks.push(chunk);
-			});
-			response.on("end", () => resolve(Buffer.concat(chunks)));
-			response.on("error", reject);
-		});
-		request.on("error", reject);
-	});
-}
-
-function checkedSpawn(command, args, options) {
-	const result = spawnSync(command, args, options);
-	if (result.error) throw result.error;
-	if (result.status !== 0) {
-		throw new Error(
-			`${command} exited with status ${result.status ?? "unknown"}`,
-		);
-	}
-}
-
-async function installHutch({ channel, environment, platform }) {
-	const temporary = mkdtempSync(path.join(tmpdir(), "electrobun-hutch-"));
-	try {
-		if (platform === "win32") {
-			const installer = path.join(temporary, "install.ps1");
-			writeFileSync(
-				installer,
-				await download(`${installerBaseUrl}/install.ps1`),
-			);
-			checkedSpawn(
-				"powershell.exe",
-				[
-					"-NoProfile",
-					"-NonInteractive",
-					"-ExecutionPolicy",
-					"Bypass",
-					"-File",
-					installer,
-					"-Channel",
-					channel,
-				],
-				{ env: environment, stdio: "inherit" },
-			);
-		} else {
-			const installer = path.join(temporary, "install.sh");
-			writeFileSync(
-				installer,
-				await download(`${installerBaseUrl}/install.sh`),
-				{ mode: 0o700 },
-			);
-			checkedSpawn("sh", [installer, "--channel", channel], {
-				env: environment,
-				stdio: "inherit",
-			});
-		}
-	} finally {
-		rmSync(temporary, { force: true, recursive: true });
-	}
-}
-
-function runHutch({ binary, args, environment }) {
-	const result = spawnSync(binary, ["electrobun", ...args], {
-		env: environment,
-		stdio: "inherit",
-	});
-	if (result.error) throw result.error;
-	if (result.status !== null) return result.status;
-	if (result.signal === "SIGINT") return 130;
-	if (result.signal === "SIGTERM") return 143;
-	return 1;
-}
-
 async function main(options = {}) {
 	const args = hutchArguments(options.args ?? process.argv.slice(2));
 	const environment = options.environment ?? process.env;
-	const platform = options.platform ?? process.platform;
-	const userHome = options.userHome ?? homedir();
-	const fileExists = options.existsSync ?? existsSync;
-	const install = options.installHutch ?? installHutch;
 	const run = options.runHutch ?? runHutch;
-	const channel = hutchChannel(environment);
-	const binary = hutchBinaryPath(channel, environment, platform, userHome);
-
-	if (!fileExists(binary)) {
-		if (environment.ELECTROBUN_HUTCH_BINARY) {
-			throw new Error(`ELECTROBUN_HUTCH_BINARY does not exist: ${binary}`);
-		}
-		if (environmentFlagEnabled(environment, "DASH_RELEASE_OFFLINE")) {
-			throw new Error(
-				`Hutch is not installed at ${binary}; DASH_RELEASE_OFFLINE prevents downloading it`,
-			);
-		}
-		console.error(
-			`Electrobun requires Hutch; installing the latest ${channel} release...`,
-		);
-		await install({ channel, environment, platform });
-	}
-
-	if (!fileExists(binary)) {
-		throw new Error(`Hutch was not installed at ${binary}`);
-	}
-	return run({ binary, args, environment });
+	const binary = await resolveHutchBinary({
+		...options,
+		ensureGlobalHutch: args[0] === "init",
+	});
+	return run({ binary, args: ["electrobun", ...args], environment });
 }
 
 if (require.main === module) {
@@ -238,9 +46,4 @@ if (require.main === module) {
 		});
 }
 
-module.exports = {
-	hutchArguments,
-	hutchBinaryPath,
-	hutchChannel,
-	main,
-};
+module.exports = { hutchArguments, main };