executor 2.0.0-beta.36 → 2.0.0-beta.38

package/README.md

@@ -1,7 +1,6 @@
 # Executor 2 beta
 
-Install with npm, `npm i -g executor@beta --include=optional`, on Node 14.18
-or newer. Without Node, run `curl -fsSL https://executor.sh/docs/install.sh | sh`
+Install with npm, `npm i -g executor@beta`, on Node 14.18 or newer. Without Node, run `curl -fsSL https://executor.sh/docs/install.sh | sh`
 on macOS or Linux, or `irm https://executor.sh/docs/install.ps1 | iex` in
 PowerShell on Windows. Each release also attaches its archives and `SHA256SUMS`.
 Run `executor` to start the background Executor, or join the one already
@@ -23,10 +22,13 @@ Executor is one executable, built with Bun, with the files it runs or reads
 beside it: the dashboard, the app framework and compiler references, workerd,
 Git, the native credential-store binding and the Motel collector. It needs no
 source checkout, Node, Bun or 1Password on the user machine. The `executor` npm
-package is a launcher that starts the executable from the platform package npm
-installs as an optional dependency, for macOS (Apple Silicon and Intel), Linux
-(arm64 and x64, glibc) and Windows (x64). The same archive is the release
-download the install scripts and Homebrew use.
+package is a launcher. The first time a version starts, it downloads that
+release's archive for the platform, for macOS (Apple Silicon and Intel), Linux
+(arm64 and x64, glibc) or Windows (x64), from the public GitHub release, checks it
+against the SHA-256 the package records, and keeps it in
+`~/.executor/v2/launcher/<version>` with the version before it. The same archive
+is the release download the install scripts and Homebrew use.
+`EXECUTOR_DOWNLOAD_URL` names a mirror of the releases for all of them.
 
 Beta uses `~/.executor/v2/cli` for its data. This path stays the same at the
 stable release. It is separate from Executor 1 data. One server runs per data
@@ -79,20 +81,25 @@ Native artifacts are under `.local/releases/<version>-<platform>-<arch>/`.
 `release:cli` bundles the runtime twice. `package/` holds the JavaScript runtime
 the desktop app runs with its own Node. `standalone/` holds the release install:
 the `executor` executable (`bun build --compile`) and the files beside it, which
-`executor-<version>-<platform>-<arch>.tgz` packs as the platform's npm package
-and release archive. The executable takes `runtime/cli.mjs` in its install
-directory as every module's location, so resources, `require` and
-`import.meta.resolve` find the same files beside it as from the npm package,
-through any launcher symlink. Packages that must stay on disk load from
+`executor-<version>-<platform>-<arch>.tgz` packs as the platform's release
+archive. The executable takes `runtime/cli.mjs` in its install directory as
+every module's location, so resources, `require` and `import.meta.resolve` find
+the same files beside it wherever the archive is unpacked, through any launcher
+symlink. Packages that must stay on disk load from
 `runtime/node_modules`; Git is in `runtime/git`.
-The npm launcher is under `.local/releases/<version>/wrapper/` and uses exact
-native version aliases. These build commands do not publish anything.
-The app compiler and framework are prepared for workerd at build time. No
-runtime download is needed. Each compressed native archive must fit within
-178 MiB before publication (`npmArchiveBudgetBytes` in `config.ts`). npm
-documents no limit; the budget stays below the largest archive it has accepted
-from Executor. Most of each archive is the executable, workerd and the bundled
-Git, which keeps only what the runtime runs (`keptGit` in `runtime-bundle.ts`).
+The npm launcher is under `.local/releases/<version>/wrapper/`. Its
+package.json records the SHA-256 of each platform archive found under
+`.local/releases/<version>-<platform>-<arch>/`, or under the directory
+`release:wrapper` is given; publishing requires all five. The runtimes are never
+published to npm. Through 2.0.0-beta.36 each was published as a version of the
+`executor` package, such as `2.0.0-beta.36-win32-x64`, which semver ranks above
+the launcher, so a range update such as `bun update -g` replaced the launcher
+with a runtime. Those versions are deprecated so package managers skip them.
+These build commands do not publish anything.
+The app compiler and framework are prepared for workerd at build time, so the
+executable downloads nothing more. Most of each archive is the executable,
+workerd and the bundled Git, which keeps only what the runtime runs (`keptGit`
+in `runtime-bundle.ts`).
 External source maps stay in the separate CI artifact for release diagnostics.
 
 Stock Bun lets any local process run its own code inside a compiled executable,

package/bin.mjs

@@ -1,39 +1,216 @@
 #!/usr/bin/env node
-// The `executor` npm package's command. It starts the Executor executable from the platform
-// package npm installed as an optional dependency, passes signals on, and exits as it exits. The
-// executable carries its own runtime, so this file uses only what every Node since 14 has.
-import { spawn } from "child_process";
+// The `executor` npm package's command. The package holds no runtime: on first use of a version it
+// downloads that release's archive for this platform from the public GitHub release, checks it
+// against the SHA-256 this package's package.json records, and unpacks it into
+// ~/.executor/v2/launcher/<version>. It then starts the Executor executable there, passes signals
+// on, and exits as it exits.
+//
+// npm, Bun, pnpm and Yarn resolve `executor` alone, so an update can only ever land on another
+// launcher; the running executable lives outside node_modules, so an update never has to replace a
+// file in use. The executable carries its own runtime, so this file uses only what every Node since
+// 14 has.
+import { spawn, spawnSync } from "child_process";
+import { createHash, randomBytes } from "crypto";
+import {
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  utimesSync,
+} from "fs";
+import { request as httpRequest } from "http";
+import { request as httpsRequest } from "https";
 import { createRequire } from "module";
-import { dirname, join } from "path";
+import { homedir } from "os";
+import { join } from "path";
 import { fileURLToPath } from "url";
 
 const require = createRequire(import.meta.url);
 const manifest = require("./package.json");
-const name = "executor-" + process.platform + "-" + process.arch;
-const channel = manifest.version.indexOf("-beta.") === -1 ? "" : "@beta";
-const reinstall = "npm i -g executor" + channel + " --include=optional";
+const version = manifest.version;
+const target = process.platform + "-" + process.arch;
+const digest = (manifest.runtimes || {})[target];
+const channel = version.indexOf("-beta.") === -1 ? "" : "@beta";
+const executableName = process.platform === "win32" ? "executor.exe" : "executor";
+const archive = "executor-" + version + "-" + target + ".tgz";
+// The same mirror setting the install scripts and `executor upgrade` read.
+const downloads = (
+  process.env.EXECUTOR_DOWNLOAD_URL ||
+  "https://github.com/UsefulSoftwareCo/executor/releases/download"
+).replace(/\/+$/, "");
+const url = downloads + "/executor@" + version + "/" + archive;
+const root = join(homedir(), ".executor", "v2", "launcher");
+const installed = join(root, version);
+const executable = join(installed, executableName);
 
 const fail = (lines) => {
   for (const line of lines) console.error(line);
   process.exit(1);
 };
 
-if (!Object.prototype.hasOwnProperty.call(manifest.optionalDependencies || {}, name))
+if (typeof digest !== "string")
   fail(["Executor does not support " + process.platform + "/" + process.arch + "."]);
 
-let root;
-try {
-  root = dirname(require.resolve(name + "/package.json"));
-} catch {
-  // npm skips optional dependencies with --omit=optional, or when a lockfile made on another
-  // platform did not list this one.
-  fail([
-    "Executor's native runtime is missing: " + name + " is not installed.",
-    "Reinstall with optional dependencies: " + reinstall,
-  ]);
-}
+/** GET `address`, following redirects; resolves to the response of the final location. */
+const get = (address, redirects) =>
+  new Promise((resolve, reject) => {
+    const request = (address.startsWith("http:") ? httpRequest : httpsRequest)(
+      address,
+      { headers: { "user-agent": "executor-launcher/" + version } },
+      (response) => {
+        const status = response.statusCode || 0;
+        if (status >= 300 && status < 400 && response.headers.location) {
+          response.resume();
+          if (redirects >= 10) return reject(new Error("too many redirects"));
+          return resolve(get(new URL(response.headers.location, address).href, redirects + 1));
+        }
+        if (status !== 200) {
+          response.resume();
+          return reject(new Error("HTTP " + status));
+        }
+        resolve(response);
+      },
+    );
+    // A connection that stops sending for a minute is not coming back.
+    request.setTimeout(60000, () => request.destroy(new Error("the connection stalled")));
+    request.on("error", reject);
+    request.end();
+  });
+
+/** Download the archive to `file`, hashing it as it arrives; resolves to its SHA-256. */
+const download = async (file) => {
+  const response = await get(url, 0);
+  const total = Number(response.headers["content-length"]) || 0;
+  const hash = createHash("sha256");
+  const out = createWriteStream(file);
+  const tty = process.stderr.isTTY;
+  let received = 0;
+  let shown = -1;
+  const label = "Downloading Executor " + version + " for " + target;
+  if (!tty) console.error(label + " (first run of this version)");
+  await new Promise((resolve, reject) => {
+    response.on("data", (chunk) => {
+      hash.update(chunk);
+      received += chunk.length;
+      const step = total ? Math.floor((received * 100) / total) : Math.floor(received / 1048576);
+      if (tty && step !== shown) {
+        shown = step;
+        const amount = (received / 1048576).toFixed(1) + " MB";
+        process.stderr.write(
+          "\r\x1b[2K" + label + (total ? " " + step + "%" : "") + " (" + amount + ")",
+        );
+      }
+    });
+    response.on("error", reject);
+    out.on("error", reject);
+    out.on("finish", resolve);
+    response.pipe(out);
+  });
+  if (tty) process.stderr.write("\r\x1b[2K");
+  return hash.digest("hex");
+};
+
+/**
+ * Keep this version and the most recently installed other one, which a background Executor started
+ * before an update may still run from, as the install scripts keep `previous`. Downloads that
+ * stopped part way are removed after a day. Anything in use, which Windows refuses to delete, stays
+ * for a later download to remove.
+ */
+const prune = () => {
+  const day = 24 * 60 * 60 * 1000;
+  const entries = readdirSync(root)
+    .filter((name) => name !== version)
+    .map((name) => ({ name, time: statSync(join(root, name)).mtimeMs }));
+  const versions = entries.filter((entry) => !entry.name.startsWith("."));
+  versions.sort((left, right) => right.time - left.time);
+  const stale = versions
+    .slice(1)
+    .concat(entries.filter((entry) => entry.name.startsWith(".") && Date.now() - entry.time > day));
+  for (const entry of stale) {
+    try {
+      rmSync(join(root, entry.name), { recursive: true, force: true });
+    } catch {
+      // In use; a later download removes it.
+    }
+  }
+};
+
+const install = async () => {
+  mkdirSync(root, { recursive: true });
+  const staging = join(root, ".download-" + process.pid + "-" + randomBytes(4).toString("hex"));
+  mkdirSync(staging);
+  // `fail` exits at once, without running `finally`.
+  const cleanup = () => rmSync(staging, { recursive: true, force: true });
+  process.on("exit", cleanup);
+  try {
+    let actual;
+    try {
+      actual = await download(join(staging, archive));
+    } catch (error) {
+      fail([
+        "Executor could not download its runtime from " + url + ": " + error.message + ".",
+        "Check your connection and try again. EXECUTOR_DOWNLOAD_URL names a mirror of the releases.",
+      ]);
+    }
+    if (actual !== digest)
+      fail([
+        archive +
+          " does not match the SHA-256 this package records (expected " +
+          digest +
+          ", got " +
+          actual +
+          ").",
+        "Nothing was installed. Check EXECUTOR_DOWNLOAD_URL, or reinstall with: npm i -g executor" +
+          channel,
+      ]);
+    // The system's tar, as the install scripts use: Windows' own bsdtar, since Git's GNU tar on
+    // PATH reads a drive letter as a remote host. The archive path is relative for the same reason.
+    const tar =
+      process.platform === "win32"
+        ? join(process.env.SystemRoot || "C:\\Windows", "System32", "tar.exe")
+        : "tar";
+    // Nothing reaches stdout, which an MCP client starting `executor mcp` reads as the protocol.
+    const unpacked = spawnSync(tar, ["-xzf", archive], {
+      cwd: staging,
+      stdio: ["ignore", "ignore", "inherit"],
+    });
+    if (unpacked.status !== 0)
+      fail([
+        "Executor could not unpack " +
+          archive +
+          " with " +
+          tar +
+          (unpacked.error ? ": " + unpacked.error.message : "."),
+      ]);
+    try {
+      renameSync(join(staging, "package"), installed);
+    } catch (error) {
+      // Another `executor` command installed this version first.
+      if (!existsSync(executable))
+        fail([
+          "Executor could not install its runtime in " + installed + ": " + error.message,
+          "Remove " + installed + " and try again.",
+        ]);
+    }
+    // The version's time orders it for pruning; the archive's own times are from 1985.
+    const now = new Date();
+    utimesSync(installed, now, now);
+  } finally {
+    process.removeListener("exit", cleanup);
+    cleanup();
+  }
+  try {
+    prune();
+  } catch {
+    // Pruning never stops Executor from starting.
+  }
+};
+
+if (!existsSync(executable)) await install();
 
-const executable = join(root, process.platform === "win32" ? "executor.exe" : "executor");
 const child = spawn(executable, process.argv.slice(2), {
   stdio: "inherit",
   env: Object.assign({}, process.env, {
@@ -57,7 +234,7 @@ for (const signal of signals) process.on(signal, forward);
 child.on("error", (error) =>
   fail([
     "Executor could not start " + executable + ": " + error.message,
-    "Reinstall with: " + reinstall,
+    "Remove " + installed + " to download it again.",
   ]),
 );
 child.on("exit", (code, signal) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "executor",
-  "version": "2.0.0-beta.36",
+  "version": "2.0.0-beta.38",
   "private": false,
   "description": "Run Executor locally and connect your agents to your apps.",
   "homepage": "https://executor.sh",
@@ -27,11 +27,11 @@
     "access": "public",
     "tag": "beta"
   },
-  "optionalDependencies": {
-    "executor-darwin-arm64": "npm:executor@2.0.0-beta.36-darwin-arm64",
-    "executor-darwin-x64": "npm:executor@2.0.0-beta.36-darwin-x64",
-    "executor-linux-x64": "npm:executor@2.0.0-beta.36-linux-x64",
-    "executor-linux-arm64": "npm:executor@2.0.0-beta.36-linux-arm64",
-    "executor-win32-x64": "npm:executor@2.0.0-beta.36-win32-x64"
+  "runtimes": {
+    "darwin-arm64": "eb01447cfdb59c03aec9e16e5989d717ddc33bded40c2b864e2aa1b0482b73e0",
+    "darwin-x64": "126fb19eb8a421507a199ded24bec5fc79ee345d76f17b8fb571f5639bd31ba4",
+    "linux-x64": "01f232a7cd13aa5116092fc8767741c12d566502fdfc53ab851ab9b3ead8e413",
+    "linux-arm64": "172784c097fccf30d4d3f238b72ba048bc724c0d5d263feac189cbb67d73b3f9",
+    "win32-x64": "2e9726e74d6b2414a29971bd7603056675542a9cc2edeba35eef388b5a954936"
   }
 }