@haakco/hostingctl 0.0.0-stage → 1.0.310

package/bin/hostingctl.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * The published `hostingctl` command.
+ *
+ * npm is the delivery truck, not the product: the package carries one self-contained executable per
+ * platform, published as its own package, and this launcher runs the one that matches the machine it was
+ * installed on. The JavaScript bundle in `dist/` is the fallback for a platform with no published
+ * binary, so an install always produces a working command.
+ *
+ * The launcher adds no output of its own and interprets no flags of its own: the command it runs
+ * answers, and its exit status is the command's own 0, 1 or 2.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { constants as osConstants } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { targets } from "./platforms.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const argv = process.argv.slice(2);
+
+/**
+ * This launcher's own path, which is the installation the command belongs to.
+ *
+ * A native-backed install runs the platform package's executable, so the path that executable sees is the
+ * **platform package's** — and detection would then read the copy as `@haakco/hostingctl-linux-x64` and
+ * update *that*, leaving the parent the client installed untouched. Handing the launcher's own path down as
+ * `HOSTINGCTL_ENTRY` keeps the identity of the package the client actually installed, for both the native
+ * and the bundle path. A platform package run on its own has no launcher, so it keeps its own identity.
+ */
+const launcher = fileURLToPath(import.meta.url);
+
+/** The platform package for this machine, or undefined when this platform has no published binary. */
+function targetFor(platform, arch) {
+  return targets.find((one) => one.platform === platform && one.arch === arch);
+}
+
+/**
+ * The executable inside this machine's platform package, when that package is installed.
+ *
+ * The package is resolved through the launcher's own installation rather than a path guess, so a global
+ * install, a local install and an `npx` cache all find the same package. A package that is not installed,
+ * or one without the executable in it, is not a binary: the caller falls back to the JavaScript bundle.
+ */
+function binaryFor(target) {
+  if (target === undefined) return undefined;
+
+  let manifest;
+  try {
+    manifest = require.resolve(`${target.package}/package.json`);
+  } catch {
+    return undefined;
+  }
+
+  const binary = join(dirname(manifest), target.executable);
+  return existsSync(binary) ? binary : undefined;
+}
+
+/**
+ * The command's own exit status.
+ *
+ * A command killed by a signal has no status of its own, and the shell's own convention for that is 128
+ * plus the signal's number, so a Ctrl+C still reads as an interruption rather than as success.
+ */
+function exitCodeOf(result) {
+  if (result.status !== null) return result.status;
+  if (result.signal !== null && result.signal !== undefined) {
+    return 128 + (osConstants.signals[result.signal] ?? 0);
+  }
+
+  return 2;
+}
+
+/**
+ * Run the resolved command and hand back its result.
+ *
+ * The child's output is inherited, which is what makes the bytes on the terminal and the exit status the
+ * command's own. `--version` is the one case that is captured, because the launch path is reported
+ * underneath it; the child's own text is still written out unchanged.
+ */
+function run(command, args, capture) {
+  const result = spawnSync(command, args, {
+    stdio: capture ? ["inherit", "pipe", "inherit"] : "inherit",
+    encoding: "utf8",
+    env: { ...process.env, HOSTINGCTL_ENTRY: launcher },
+  });
+
+  if (capture && typeof result.stdout === "string" && result.stdout !== "") {
+    process.stdout.write(result.stdout);
+  }
+
+  return result;
+}
+
+const target = targetFor(process.platform, process.arch);
+const forced = process.env.HOSTINGCTL_FORCE_JS === "1";
+const bundle = join(here, "..", "dist", "main.js");
+
+// The version is the one answer the launcher adds, because only the launcher knows which of the two
+// paths answered it. `--json` is left alone: a machine-readable answer stays machine-readable.
+const reportsPath = argv.includes("--version") && !argv.includes("--json");
+
+let result;
+let path;
+
+if (!forced) {
+  const binary = binaryFor(target);
+  if (binary !== undefined) {
+    result = run(binary, argv, reportsPath);
+    path = `native binary (${target.id})`;
+    if (result.error !== undefined) {
+      process.stderr.write(
+        `hostingctl: the published binary could not be run (${result.error.message}); using the JavaScript bundle.\n`,
+      );
+      result = undefined;
+    }
+  }
+}
+
+if (result === undefined) {
+  if (!existsSync(bundle)) {
+    process.stderr.write(
+      "hostingctl: this installation carries neither a native binary nor the JavaScript bundle.\n",
+    );
+    process.exitCode = 2;
+  } else {
+    result = run(process.execPath, [bundle, ...argv], reportsPath);
+    path =
+      forced === true
+        ? "JavaScript bundle (HOSTINGCTL_FORCE_JS=1)"
+        : `JavaScript bundle (no published binary for ${process.platform}-${process.arch})`;
+  }
+}
+
+if (reportsPath === true && result !== undefined) {
+  process.stdout.write(`Launch path: ${path}\n`);
+}
+
+process.exitCode = result === undefined ? 2 : exitCodeOf(result);

package/bin/platforms.js

@@ -0,0 +1,70 @@
+/**
+ * The published platform packages, and the machine each one answers for.
+ *
+ * This table is the one owner of the five platform names. The launcher resolves the package for the
+ * machine it runs on, `scripts/ci/build-cli-binaries.sh` compiles and stages them, and its `check` mode
+ * refuses a manifest or an optional dependency that names a package this table does not. A rename
+ * therefore happens here and nowhere else.
+ *
+ * `id` is the target's name in this repository and in a release. `platform` and `arch` are Node's own
+ * values for the machine the package answers for, and are what npm's `os` and `cpu` fields need.
+ * `bunTarget` is the compile target Bun names it by.
+ */
+export const targets = [
+  {
+    id: "darwin-arm64",
+    package: "@haakco/hostingctl-darwin-arm64",
+    platform: "darwin",
+    arch: "arm64",
+    bunTarget: "bun-darwin-arm64",
+    executable: "hostingctl",
+  },
+  {
+    id: "darwin-x64",
+    package: "@haakco/hostingctl-darwin-x64",
+    platform: "darwin",
+    arch: "x64",
+    bunTarget: "bun-darwin-x64",
+    executable: "hostingctl",
+  },
+  {
+    id: "linux-arm64",
+    package: "@haakco/hostingctl-linux-arm64",
+    platform: "linux",
+    arch: "arm64",
+    bunTarget: "bun-linux-arm64",
+    executable: "hostingctl",
+  },
+  {
+    id: "linux-x64",
+    package: "@haakco/hostingctl-linux-x64",
+    platform: "linux",
+    arch: "x64",
+    bunTarget: "bun-linux-x64",
+    executable: "hostingctl",
+  },
+  {
+    id: "windows-x64",
+    package: "@haakco/hostingctl-windows-x64",
+    platform: "win32",
+    arch: "x64",
+    bunTarget: "bun-windows-x64",
+    executable: "hostingctl.exe",
+  },
+];
+
+/**
+ * The metadata every published package carries, apart from its own name, version and target.
+ *
+ * The main package and the five platform packages are two surfaces of one product, so they carry one
+ * set of answers: the same licence, the same repository, the same documentation site. The distribution
+ * check compares the main package's own fields with these, so the two cannot drift apart.
+ */
+export const packageFields = {
+  license: "UNLICENSED",
+  homepage: "https://hosting.haak.co/docs/cli",
+  bugs: { url: "https://github.com/haakco/hosting/issues" },
+  author: { name: "HaakCo", url: "https://haak.co" },
+  publishConfig: { access: "public", registry: "https://registry.npmjs.org/" },
+  repository: { type: "git", url: "git+https://github.com/haakco/hosting.git" },
+};