@ivan-murzak/runner-manager 0.0.0-bootstrap.1 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Murzak
+
+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,9 +1,102 @@
-# @ivan-murzak/runner-manager
+# @ivan-murzak/runner-manager (npm wrapper)
 
-Placeholder. This version exists only so that npm trusted publishing can be configured for
-this package name; npm cannot attach a trusted publisher to a package that does not exist.
+Local-first autoscaling manager for ephemeral GitHub Actions self-hosted
+runners, with a CLI and a Ratatui TUI.
 
-It carries no binary and is published under the `bootstrap` dist-tag, so it is not what
-`npm install` resolves. The first real release replaces it.
+> **Read this before you install.** Using this tool means installing the
+> project's published GitHub App, which declares **Repository → Administration:
+> Read and write** — a permission that also allows deleting, renaming and
+> transferring the repository, and adding or removing collaborators. It applies
+> even if you only ever use `runner-manager` as a read-only dashboard. The full
+> permission set and the narrower organization-scoped alternative are in
+> [What you are granting](#what-you-are-granting) below.
 
-Project: <https://github.com/IvanMurzak/GitHub-Runner-Scaler-UI>
+```sh
+npm i -g @ivan-murzak/runner-manager
+runner-manager --version
+```
+
+This package is a thin wrapper. The binary itself lives in one of five
+per-platform packages, declared here as `optionalDependencies`, so npm installs
+only the one that matches your OS and CPU:
+
+| Platform package | os / cpu | Rust target |
+|---|---|---|
+| `@ivan-murzak/runner-manager-win32-x64` | `win32` / `x64` | `x86_64-pc-windows-msvc` |
+| `@ivan-murzak/runner-manager-darwin-arm64` | `darwin` / `arm64` | `aarch64-apple-darwin` |
+| `@ivan-murzak/runner-manager-darwin-x64` | `darwin` / `x64` | `x86_64-apple-darwin` |
+| `@ivan-murzak/runner-manager-linux-x64` | `linux` / `x64` | `x86_64-unknown-linux-gnu` |
+| `@ivan-murzak/runner-manager-linux-arm64` | `linux` / `arm64` | `aarch64-unknown-linux-gnu` |
+
+Each platform package records, in its `package.json`, the release archive its
+binary was taken from and that archive's published SHA-256 — the same digest
+listed in the release's `SHA256SUMS`.
+
+## Read this before `service install`
+
+**An `npm i -g` binary does not have a fixed home, and this product records an
+absolute path.**
+
+`npm i -g` installs into the *active* Node installation's global prefix. If you
+manage Node with `nvm`, `fnm`, `volta`, `asdf`, Homebrew, or a Windows
+installer upgrade, that prefix is different for every Node version — something
+like:
+
+```text
+~/.nvm/versions/node/v20.11.0/bin/runner-manager
+~/.nvm/versions/node/v22.3.0/bin/runner-manager      <- after `nvm install 22`
+```
+
+`runner-manager service install` resolves and records the **absolute** path of
+the binary at the moment you run it. So switching Node versions after
+installing the service leaves the service pointing at a path that no longer
+exists, and nothing tells you until the next unattended boot, when the agent
+does not come up.
+
+`runner-manager service status` detects this and reports the recorded path as
+**stale** rather than reporting the service as healthy. If you see that:
+
+```sh
+npm i -g @ivan-murzak/runner-manager   # into the Node version you are now using
+runner-manager service install        # re-records the new absolute path
+```
+
+**If you want a boot-start service, prefer the install script.** It installs to
+`~/.local/bin` (macOS, Linux) or `%LOCALAPPDATA%\Programs\runner-manager`
+(Windows), neither of which moves when a toolchain moves:
+
+```sh
+curl -fsSL https://github.com/IvanMurzak/GitHub-Runner-Scaler-UI/releases/latest/download/install.sh | sh
+```
+
+```powershell
+irm https://github.com/IvanMurzak/GitHub-Runner-Scaler-UI/releases/latest/download/install.ps1 | iex
+```
+
+This package is the right choice when you already manage tooling with npm and
+you run `runner-manager` interactively or from a script, rather than as a
+boot-start service.
+
+## Windows on ARM
+
+npm will not install an `"cpu": ["x64"]` package onto an arm64 host, and no
+arm64 Windows build is published, so this package cannot serve Windows on ARM.
+The install script can: it uses the x64 build through the built-in emulation
+layer.
+
+## What you are granting
+
+Using this tool means installing the project's published GitHub App, and that
+App declares **Repository → Administration: Read and write**. That permission
+also allows deleting, renaming and transferring the repository, and adding or
+removing collaborators. It applies even if you only ever use `runner-manager`
+as a read-only dashboard.
+
+The full permission table, why the grant is unavoidable at repository scope,
+and why organization scope is materially narrower are in the
+[repository README](https://github.com/IvanMurzak/GitHub-Runner-Scaler-UI#what-you-are-granting).
+Read it before you run `auth login`.
+
+## Licence
+
+MIT. Source: <https://github.com/IvanMurzak/GitHub-Runner-Scaler-UI>

package/bin/runner-manager.cjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+//
+// The npm wrapper's entry point (task a3, D11).
+//
+// ---------------------------------------------------------------------------
+// WHY A SHIM AND NOT A postinstall DOWNLOAD.
+// ---------------------------------------------------------------------------
+// The other common shape for shipping a binary through npm is a `postinstall`
+// script that downloads it. That shape needs network access at install time,
+// breaks behind a proxy and inside an offline CI cache, and -- the part that
+// matters here -- it fetches an artifact that npm's own integrity hashes never
+// covered. The esbuild shape used instead puts each binary inside a real npm
+// package, so npm's registry integrity hash covers the exact bytes that end up
+// on disk, and `--ignore-scripts` (increasingly a default in locked-down CI)
+// does not silently produce an installation with no binary in it.
+//
+// ---------------------------------------------------------------------------
+// WHY THE PLATFORM PACKAGES ARE `optionalDependencies`.
+// ---------------------------------------------------------------------------
+// A package whose `os`/`cpu` do not match the host is SKIPPED when it is
+// optional and is a hard install failure when it is not. Five platform
+// packages on a normal `dependencies` line would therefore fail the install
+// for every user on four of the five platforms. The cost is that a genuinely
+// missing package is indistinguishable from a skipped one at install time,
+// which is what the diagnostics below exist to untangle at run time.
+//
+// ---------------------------------------------------------------------------
+// THIS FILE IS COMMITTED; THE package.json FILES BESIDE IT ARE GENERATED.
+// ---------------------------------------------------------------------------
+// `.github/scripts/channels.sh npm-manifests` writes the manifests at release
+// time so every version and every published digest comes from the release that
+// is happening. This file has no version in it and never needs one.
+
+"use strict";
+
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+// Must agree with `PUBLISHED_TARGETS` in `.github/scripts/channels.sh`.
+// `crates/app/tests/release_channels.rs` compares the two, because a package
+// renamed on one side and not the other produces a wrapper that installs
+// cleanly and then cannot find its own binary.
+const PLATFORMS = {
+  "darwin arm64": ["@ivan-murzak/runner-manager-darwin-arm64", "runner-manager"],
+  "darwin x64": ["@ivan-murzak/runner-manager-darwin-x64", "runner-manager"],
+  "linux arm64": ["@ivan-murzak/runner-manager-linux-arm64", "runner-manager"],
+  "linux x64": ["@ivan-murzak/runner-manager-linux-x64", "runner-manager"],
+  "win32 x64": ["@ivan-murzak/runner-manager-win32-x64", "runner-manager.exe"],
+};
+
+function fail(lines) {
+  for (const line of lines) {
+    process.stderr.write(line + "\n");
+  }
+  process.exit(1);
+}
+
+const key = process.platform + " " + process.arch;
+const entry = PLATFORMS[key];
+
+if (!entry) {
+  const extra = [];
+  if (process.platform === "win32") {
+    // Windows on ARM runs the x64 build through the built-in emulation layer,
+    // but npm will not install an `"cpu": ["x64"]` package onto an arm64 host,
+    // so this is the one platform npm cannot serve and the install script can.
+    extra.push(
+      "",
+      "Windows on ARM is supported by the install script, which uses the x64",
+      "build through the built-in emulation layer:",
+      "",
+      "  irm https://github.com/IvanMurzak/GitHub-Runner-Scaler-UI/releases/latest/download/install.ps1 | iex",
+    );
+  }
+  fail([
+    `runner-manager: no published binary for ${process.platform} ${process.arch}.`,
+    "",
+    "Published platforms: " + Object.keys(PLATFORMS).join(", ") + ".",
+    "Build from source instead:  cargo install runner-manager",
+    ...extra,
+  ]);
+}
+
+const [packageName, binaryName] = entry;
+
+let binary;
+try {
+  // Resolved through `package.json` rather than through the package's main
+  // entry point: these packages have no JavaScript in them at all, so there is
+  // no main to resolve.
+  binary = path.join(
+    path.dirname(require.resolve(packageName + "/package.json")),
+    "bin",
+    binaryName,
+  );
+} catch (error) {
+  fail([
+    `runner-manager: the platform package ${packageName} is not installed.`,
+    "",
+    "It is an optionalDependency, so npm skips it silently in three cases:",
+    "",
+    "  * the install ran with --no-optional or --omit=optional",
+    "  * the install ran on a different platform (a lockfile or a Docker",
+    "    image built on one OS and used on another)",
+    "  * the registry was unreachable when the optional dependency was fetched",
+    "",
+    "Reinstall with optional dependencies enabled:",
+    "",
+    "  npm install -g @ivan-murzak/runner-manager",
+    "",
+    `(resolution error: ${error && error.message ? error.message : error})`,
+  ]);
+}
+
+// `stdio: "inherit"` because this is a TUI as well as a CLI: the child needs
+// the real terminal, not a pipe, or Ratatui has no size to draw into and no
+// key events to read.
+//
+// The child's exit code is propagated. A wrapper that always exits 0 makes
+// every `runner-manager` invocation look successful to a shell script, to a
+// CI step, and to the service manager that restarts it on failure.
+const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+
+if (result.error) {
+  fail([
+    `runner-manager: could not execute ${binary}`,
+    "",
+    String(result.error.message || result.error),
+  ]);
+}
+
+// Killed by a signal: report it as a shell does, rather than as exit 0.
+if (result.signal) {
+  process.stderr.write(`runner-manager: terminated by signal ${result.signal}\n`);
+  process.exit(1);
+}
+
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "@ivan-murzak/runner-manager",
-  "version": "0.0.0-bootstrap.1",
-  "description": "Placeholder so trusted publishing can be configured. Not a release; see the repository.",
+  "version": "0.1.2",
+  "description": "Local-first autoscaling manager for ephemeral GitHub Actions self-hosted runners, with a CLI and a Ratatui TUI.",
   "license": "MIT",
   "author": "Ivan Murzak (https://github.com/IvanMurzak)",
   "homepage": "https://github.com/IvanMurzak/GitHub-Runner-Scaler-UI",
   "repository": { "type": "git", "url": "git+https://github.com/IvanMurzak/GitHub-Runner-Scaler-UI.git" },
-  "files": [ "README.md" ]
+  "engines": { "node": ">=18" },
+  "bin": { "runner-manager": "bin/runner-manager.cjs" },
+  "files": [ "bin/", "README.md" ],
+  "optionalDependencies": {
+    "@ivan-murzak/runner-manager-win32-x64": "0.1.2",
+    "@ivan-murzak/runner-manager-darwin-arm64": "0.1.2",
+    "@ivan-murzak/runner-manager-darwin-x64": "0.1.2",
+    "@ivan-murzak/runner-manager-linux-x64": "0.1.2",
+    "@ivan-murzak/runner-manager-linux-arm64": "0.1.2"
+  }
 }