electrobun 2.0.1-beta.24 → 2.0.1-beta.28

package/README.md

@@ -1,9 +1,15 @@
 # Electrobun npm bootstrap
 
-The `electrobun` npm package is a small Hutch 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`) 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:
 
@@ -17,19 +23,26 @@ 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/releases/electrobun` 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: an exact
+`// @hutch` pragma or `electrobun.version` in `hutch.config.ts` always wins.
+Without an explicit Electrobun pin, 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, but
+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 npm or another project package manager into offline mode.
+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,60 +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;
-
-// Hutch owns a separate release-channel contract: its stable executable is
-// still published under Hutch's "production" channel.
-function normalizeHutchChannel(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 = normalizeHutchChannel(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;
-	}
-
-	const pathApi = platform === "win32" ? path.win32 : path.posix;
-	// 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 ||
-		pathApi.join(userHome, ".hutch");
-	const command = channel === "canary" ? "hutch-canary" : "hutch";
-	return pathApi.join(
-		hutchHome,
-		"bin",
-		`${command}${platform === "win32" ? ".exe" : ""}`,
-	);
-}
+const {
+	resolveHutchBinary,
+	runHutch,
+} = require("./resolve-hutch.cjs");
 
 function hutchArguments(args) {
 	const forwarded = Array.from(args);
@@ -70,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) {
@@ -240,9 +46,4 @@ if (require.main === module) {
 		});
 }
 
-module.exports = {
-	hutchArguments,
-	hutchBinaryPath,
-	hutchChannel,
-	main,
-};
+module.exports = { hutchArguments, main };