electrobun 1.18.4-beta.5 → 2.0.1-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Blackboard Technologies inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,178 +1,37 @@
-<p align="center">
-  <a href="https://electrobun.dev"><img src="https://github.com/blackboardsh/electrobun/assets/75102186/8799b522-0507-45e9-86e3-c3cfded1aa7c" alt="Logo" height=170></a>
-</p>
+# Electrobun npm bootstrap
 
-<h1 align="center">Electrobun</h1>
+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 `~/.dash` when necessary and delegates
+all commands to `hutch electrobun`.
 
-<div align="center">
-  Get started with a template <br />
-  <code><strong>npx electrobun init</strong></code>   
-</div>
+Create a project from the current stable template catalog:
 
-
-
-## What is Electrobun?
-
-Electrobun aims to be a complete **solution-in-a-box** for building, updating, and shipping ultra fast, tiny, and cross-platform desktop applications written in Typescript.
-Under the hood it uses <a href="https://bun.sh">bun</a> to execute the main process and to bundle webview typescript, and has native bindings written in Objc, C++, and several core parts written in <a href="https://ziglang.org/">zig</a>.
-
-Visit <a href="https://docs.electrobunny.ai/electrobun/">https://docs.electrobunny.ai/electrobun/</a> to see api documentation, guides, and more.
-
-You use it via npm.
-
-Don't miss our:
-- self-extracting bundles that use ZSTD compression for more compact distributables as small as 16MB
-- zig optimized BSDIFF implementation that lets you ship tiny app updates as small as 4KB
-- `bundleCEF` flag to bundle and pin Chromium for those that want that tradeoff of consistency over file size
-- `bundleWGPU` that lets you use Bun Typescript -> WGPU to control a native GPU surface without a webview
-- Our Three.js and Babylon.js adapters that work right in Bun
-- Our `<electrobun-webview>` and `<electrobun-wpgu>` html elements that let you composit proper OOPIFs and native GPU surfaces into your UIs
-- so much more.
-
-**Project Goals**
-
-- Write typescript for the main process and webviews without having to think about it.
-- Isolation between main and webview processes with fast, typed, easy to implement RPC between them.
-- Small self-extracting app bundles ~14MB (when using system webview, most of this is the bun runtime)
-- Even smaller app updates as small as 4KB (using bsdiff it only downloads tiny patches between versions)
-- Provide everything you need in one tightly integrated workflow to start writing code in 5 minutes and distribute in 10.
-
-## Apps Built with Electrobun
-- [24agents](https://github.com/jhsu/24agents) - Hyperprompter
-- [act-track-ai](https://github.com/IrdanGu/act-track-ai) - personal desktop productivity tracker
-- [Agents Council](https://github.com/MrLesk/agents-council) - agent-to-agent MCP communication tool for feedback requests
-- [ai-wrapped](https://github.com/gulivan/ai-wrapped) - Wrapped-style desktop dashboard for your AI coding agent activity
-- [Audio TTS](https://github.com/blackboardsh/audio-tts) - desktop text-to-speech app using Qwen3-TTS for voice design, cloning, and generation
-- [aueio-player-desktop](https://github.com/tuomashatakka/aueio-player-desktop) - beautiful, minimal cross-platform audio player
-- [bestdiff](https://github.com/tesmond/bestdiff) - a git diff checker with curved connectors
-- [BuddyWriter](https://github.com/OxFrancesco/BuddyWriter) - BuddyWriter desktop and mobile apps
-- [burns](https://github.com/l3wi/burns) - a Smithers manager
-- [cbx-tool](https://github.com/jebin2/cbx-tool) - desktop app for reading and editing comic book archives (.cbz/.cbr)
-- [Co(lab)](https://blackboard.sh/colab/) - a hybrid web browser + code editor for deep work
-- [codlogs](https://github.com/tobitege/codlogs) - search and export local Codex sessions via CLI or desktop app
-- [Codex Agents Composer](https://github.com/MrLesk/codex-agents-composer) - desktop app for managing your Codex agents and their skills
-- [codex-devtools](https://github.com/gulivan/codex-devtools) - desktop inspector for Codex session data; browse conversations, search messages, and analyze agent activity
-- [Deskdown](https://github.com/guarana-studio/deskdown) - transform any web address into a desktop app in under 20 seconds
-- [Dictate](https://github.com/siddhantparadox/dictate) - Windows dictation app with local and BYOK cloud transcription
-- [dev-3.0](https://github.com/h0x91b/dev-3.0) - helps you not get lost while managing multiple AI agents across projects
-- [DOOM](https://github.com/blackboardsh/electrobun-doom) - DOOM implemented in 2 ways: bun -> (c doom -> bundled wgpu) and (full ts port bun -> bundled wgpu)
-- [dotlock](https://github.com/tsconfigdotjson/dotlock) - macOS desktop app for managing `.env` files across your projects
-- [electrobun-pdf](https://github.com/GijungKim/electrobun-pdf) - local-first PDF & DOCX editor for opening, annotating, and exporting documents without leaving your machine
-- [electrobun-rms](https://github.com/khanhthanhdev/electrobun-rms) - fast Electrobun desktop app template with React, Tailwind CSS, and Vite
-- [golb](https://github.com/chrisdadev13/golb) - desktop AI coding workspace built with React, Vite, and Tailwind
-- [GOG Achievements GUI](https://github.com/timendum/gog-achievements-gui) - desktop app for managing GOG achievements
-- [groov](https://github.com/laurenzcodes/groov) - desktop audio deck monitor
-- [Guerilla Glass](https://github.com/okikeSolutions/guerillaglass) - open-source cross-platform creator studio for fast Record -> Edit -> Deliver workflows
-- [Invoke](https://getinvoke.com) - macOS UI automation & shortcut platform
-- [Marginalia](https://github.com/lars-hoeijmans/Marginalia) - a simple note taking app
-- [MarkBun](https://github.com/xiaochong/markbun) - fast, beautiful, Typora-like markdown desktop editor
-- [md-browse](https://github.com/needle-tools/md-browse) - a markdown-first browser that converts web pages to clean markdown
-- [moop](https://github.com/zrubinrattet/moop/) - desktop app for batch image optimization for the web
-- [Patchline](https://github.com/adwaithks/Patchline) - lightweight desktop Git client for reading patches and line diffs, then staging and committing changes
-- [peekachu](https://github.com/needle-tools/peekachu) - password manager for AIs; store secrets in your OS keychain and scrub output so AI assistants never see actual values
-- [PiBun](https://github.com/khairold/pibun) - desktop GUI for the Pi coding agent with chat, terminal, git integration, and plugin system
-- [PLEXI](https://github.com/ianjamesburke/PLEXI) - a multi-dimensional terminal multiplexer for the agentic era
-- [Prometheus](https://github.com/opensourcectl/prometheus) - desktop utility toolbox for file cleanup, document manipulation, and image processing
-- [Quiver](https://ataraxy-labs.github.io/quiver/) - desktop app for GitHub PR reviews, merge conflict resolution, and AI commit messages
-- [remotecode.io](https://github.com/samuelfaj/remotecode.io) - continue local AI coding sessions (Claude Code or Codex) from your mobile device
-- [sirene](https://github.com/KevinBonnoron/sirene) - self-hosted multi-backend text-to-speech platform with voice cloning
-- [StoryForge](https://github.com/vrrdnt/StoryForge) - desktop app for Vintage Story players to switch between game versions, modpacks, servers, and accounts
-- [Tensamin Client](https://github.com/Tensamin/Client) - web, desktop, and mobile app for accessing Tensamin
-- [tokenpass-desktop](https://github.com/b-open-io/tokenpass-desktop) - desktop app that runs the Sigma Identity stack locally for Bitcoin-backed authentication
-- [typsmthng-desktop](https://github.com/aaditagrawal/typsmthng-desktop) - experimental desktop typing application
-- [VibesOS](https://github.com/popmechanic/VibesOS) - A GUI for Claude Code that makes it easy to vibe code simple, un-hackable apps
-- [VoiceVault](https://github.com/PJH720/VoiceVault) - AI-powered voice recorder with transcription, summarization, and RAG search
-- [warren](https://github.com/Loa212/warren) - open-source, peer-to-peer terminal mesh for accessing your machines from any device without SSH keys or config files
-- [whatsapp-reminder](https://github.com/FatahChan/whatsapp-reminder) - managed scheduled WhatsApp messages
-
-### Video Demos
-
-[![Audio TTS Demo](https://img.youtube.com/vi/Z4dNK1d6l6E/maxresdefault.jpg)](https://www.youtube.com/watch?v=Z4dNK1d6l6E)
-
-[![Co(lab) Demo](https://img.youtube.com/vi/WWTCqGmE86w/maxresdefault.jpg)](https://www.youtube.com/watch?v=WWTCqGmE86w)
-
-[![DOOM Demo](https://github.com/user-attachments/assets/6cc5f04a-6d97-4010-b65f-3f282d32590c)](https://x.com/YoavCodes/status/2028499038148903239?s=20)
-
-## Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=blackboardsh/electrobun&type=date&legend=top-left&cache=3)](https://www.star-history.com/#blackboardsh/electrobun&type=date&legend=top-left)
-
-## Contributing
-Electrobun is one piece of a vision I'm building. I'm optimizing for focus and execution. Issues and PRs can be used to share ideas, but there should be no expectation that I will review, respond to, or merge them.
-
-Ways to get involved:
-
-- Read the [Contribution guidelines](./CONTRIBUTING.md)
-- Follow us on X for updates <a href="https://twitter.com/BlackboardTech">@BlackboardTech</a> and <a href="https://twitter.com/YoavCodes">@YoavCodes</a> or on bluesky <a href="https://bsky.app/profile/yoav.codes">@yoav.codes</a>
-- Join the conversation on <a href="https://discord.gg/ueKE4tjaCE">Discord</a>
-- Create and participate in Github issues and discussions
-- Let me know what you're building with Electrobun
-
-## Development Setup
-Building apps with Electrobun is as easy as updating your package.json dependencies with `npm add electrobun` or try one of our templates via `npx electrobun init`.
-
-**This section is for building Electrobun from source locally in order to contribute fixes to it.**
-
-### Prerequisites
-
-**macOS:**
-- Xcode command line tools
-- cmake (install via homebrew: `brew install cmake`)
-
-**Windows:**
-- Visual Studio Build Tools or Visual Studio with C++ development tools
-- cmake
-
-**Linux:**
-- build-essential package
-- cmake
-- webkit2gtk and GTK development packages
-
-On Ubuntu/Debian based distros: `sudo apt install build-essential cmake pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev`
-
-### First-time Setup
-
-```bash
-git clone --recurse-submodules https://github.com/blackboardsh/electrobun.git
-cd electrobun/package
-bun install
-bun dev:clean
+```sh
+npx electrobun init
 ```
 
-### Development Workflow
-
-```bash
-# All commands are run from the /package directory
-cd electrobun/package
-
-# After making changes to source code
-bun dev
-
-# If you only changed kitchen sink code (not electrobun source)
-bun dev:rerun
+Use the beta catalog only when you ask for it:
 
-# If you need a completely fresh start
-bun dev:clean
+```sh
+npx electrobun init --beta
 ```
 
-### Additional Commands
+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 `~/.dash` store and projects the SDKs
+into the project's `.hutch/devkit` sysroot. Installing a beta bootstrap still
+uses stable templates unless `init` receives `--beta`.
 
-All commands are run from the `/package` directory:
+`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.
 
-- `bun dev:canary` - Build and run kitchen sink in canary mode
-- `bun build:dev` - Build electrobun in development mode
-- `bun build:release` - Build electrobun in release mode
+You can install Hutch directly from <https://hutch.blackboard.sh> and run the
+same commands without npm:
 
-### Debugging
-
-**macOS:** Use `lldb <path-to-bundle>/Contents/MacOS/launcher` and then `run` to debug release builds
-
-## Platform Support
-
-| OS | Status |
-|---|---|
-| macOS 14+ | Official |
-| Windows 11+ | Official |
-| Ubuntu 22.04+ | Official |
-| Other Linux distros (gtk3, webkit2gtk-4.1) | Community |
-| Raspberry Pi | Unofficial fork: [kortexa-ai/electrobun (linux-wpe)](https://github.com/kortexa-ai/electrobun/tree/kortexa/linux-wpe) — follow the author [@francip](https://x.com/francip/status/2050149256053539059?s=20) |
+```sh
+hutch electrobun init
+```

package/bin/electrobun.cjs

@@ -1,169 +1,241 @@
 #!/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");
+
+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";
+}
 
-const { execSync, spawn } = require('child_process');
-const { existsSync, mkdirSync, unlinkSync, chmodSync, copyFileSync, createWriteStream } = require('fs');
-const { join, dirname } = require('path');
-const https = require('https');
-const ProxyAgent = require('proxy-agent').ProxyAgent;
-
-// Create an HTTPS agent that respects environment proxy settings
-const agent = new ProxyAgent();
-
-// Detect platform and architecture
-function getPlatform() {
-  switch (process.platform) {
-    case 'win32': return 'win';
-    case 'darwin': return 'darwin';
-    case 'linux': return 'linux';
-    default: throw new Error(`Unsupported platform: ${process.platform}`);
-  }
+function environmentFlagEnabled(environment, name) {
+	const value = environment[name];
+	return (
+		value === "1" ||
+		(typeof value === "string" &&
+			["true", "yes"].includes(value.toLowerCase()))
+	);
 }
 
-function getArch() {
-  switch (process.arch) {
-    case 'arm64': return 'arm64';
-    case 'x64': return 'x64';
-    default: throw new Error(`Unsupported architecture: ${process.arch}`);
-  }
+function hutchBinaryPath(channel, environment, platform, userHome) {
+	if (environment.ELECTROBUN_HUTCH_BINARY) {
+		return environment.ELECTROBUN_HUTCH_BINARY;
+	}
+
+	const dashHome = environment.DASH_HOME || path.join(userHome, ".dash");
+	const command = channel === "canary" ? "hutch-canary" : "hutch";
+	const pathApi = platform === "win32" ? path.win32 : path.posix;
+	return pathApi.join(
+		dashHome,
+		"bin",
+		`${command}${platform === "win32" ? ".exe" : ""}`,
+	);
 }
 
-const platform = getPlatform();
-// Always use x64 for Windows since we only build x64 Windows binaries
-const arch = platform === 'win' ? 'x64' : getArch();
-const binExt = platform === 'win' ? '.exe' : '';
+function hutchArguments(args) {
+	const forwarded = Array.from(args);
+	if (forwarded[0] !== "init") return forwarded;
+
+	const explicitTemplateChannel = forwarded.some(
+		(argument) =>
+			argument === "--beta" ||
+			argument.startsWith("--channel="),
+	);
+	return explicitTemplateChannel
+		? forwarded
+		: [...forwarded, "--channel=stable"];
+}
 
-function getTarCommand() {
-  if (platform !== 'win') {
-    return 'tar';
-  }
+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"}`,
+		);
+	}
+}
 
-  // Git Bash tar can treat C:\... as a remote path. Force the built-in Windows tar.
-  const systemTar = join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'tar.exe');
-  return existsSync(systemTar) ? `"${systemTar}"` : 'tar';
+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 });
+	}
 }
 
-// Paths
-const electrobunDir = join(__dirname, '..');
-const cacheDir = join(electrobunDir, '.cache');
-const cliBinary = join(cacheDir, `electrobun${binExt}`);
-
-async function downloadFile(url, filePath) {
-  return new Promise((resolve, reject) => {
-    mkdirSync(dirname(filePath), { recursive: true });
-    const file = createWriteStream(filePath);
-
-    https.get(url, {agent}, (response) => {
-      if (response.statusCode === 302 || response.statusCode === 301) {
-        // Follow redirect
-        return downloadFile(response.headers.location, filePath).then(resolve).catch(reject);
-      }
-
-      if (response.statusCode !== 200) {
-        reject(new Error(`Download failed: ${response.statusCode}`));
-        return;
-      }
-
-      response.pipe(file);
-
-      file.on('finish', () => {
-        file.close();
-        resolve();
-      });
-
-      file.on('error', reject);
-    }).on('error', reject);
-  });
+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 ensureCliBinary() {
-  // Check if CLI binary exists in bin location (where npm expects it)
-  const binLocation = join(electrobunDir, 'bin', 'electrobun' + binExt);
-  if (existsSync(binLocation)) {
-    return binLocation;
-  }
-
-  // Check if core dependencies already exist in cache
-  if (existsSync(cliBinary)) {
-    // Copy to bin location if it exists in cache but not in bin
-    mkdirSync(dirname(binLocation), { recursive: true });
-    copyFileSync(cliBinary, binLocation);
-    if (platform !== 'win') {
-      chmodSync(binLocation, '755');
-    }
-    return binLocation;
-  }
-
-  console.log('Downloading electrobun CLI for your platform...');
-
-  // Get the package version to download the matching release
-  const packageJson = require(join(electrobunDir, 'package.json'));
-  const version = packageJson.version;
-  const tag = `v${version}`;
-
-  const tarballUrl = `https://github.com/blackboardsh/electrobun/releases/download/${tag}/electrobun-cli-${platform}-${arch}.tar.gz`;
-  const tarballPath = join(cacheDir, `electrobun-${platform}-${arch}.tar.gz`);
-
-  try {
-    // Download tarball
-    await downloadFile(tarballUrl, tarballPath);
-
-    // Extract using system tar (available on macOS, Linux, and Windows 10+)
-    execSync(`${getTarCommand()} -xzf "${tarballPath}"`, { cwd: cacheDir, stdio: 'pipe' });
-
-    // Clean up tarball
-    unlinkSync(tarballPath);
-
-    // Check if CLI binary was extracted
-    if (!existsSync(cliBinary)) {
-      throw new Error(`CLI binary not found at ${cliBinary} after extraction`);
-    }
-
-    // Make executable on Unix systems
-    if (platform !== 'win') {
-      chmodSync(cliBinary, '755');
-    }
-
-    // Copy CLI to bin location so npm scripts can find it
-    mkdirSync(dirname(binLocation), { recursive: true });
-    copyFileSync(cliBinary, binLocation);
-
-    // Make the bin location executable too
-    if (platform !== 'win') {
-      chmodSync(binLocation, '755');
-    }
-
-    console.log('electrobun CLI downloaded successfully!');
-    return binLocation;
-
-  } catch (error) {
-    throw new Error(`Failed to download electrobun CLI: ${error.message}`);
-  }
+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 });
 }
 
-async function main() {
-  try {
-    const args = process.argv.slice(2);
-    const cliPath = await ensureCliBinary();
-
-    // Replace this process with the actual CLI
-    const child = spawn(cliPath, args, {
-      stdio: 'inherit',
-      cwd: process.cwd()
-    });
-
-    child.on('exit', (code) => {
-      process.exit(code || 0);
-    });
-
-    child.on('error', (error) => {
-      console.error('Failed to start electrobun CLI:', error.message);
-      process.exit(1);
-    });
-
-  } catch (error) {
-    console.error('Error:', error.message);
-    process.exit(1);
-  }
+if (require.main === module) {
+	main()
+		.then((status) => {
+			process.exitCode = status;
+		})
+		.catch((error) => {
+			console.error(`electrobun: ${error.message}`);
+			process.exitCode = 1;
+		});
 }
 
-main();
+module.exports = {
+	hutchArguments,
+	hutchBinaryPath,
+	hutchChannel,
+	main,
+};