@higherdev/cli 0.34.0 → 0.36.0

package/README.md

@@ -50,6 +50,7 @@ workspace-map config shapes are migrated automatically when they are read.
 | `hd env set NAME=VALUE [NAME=VALUE...]` | Set workspace environment variables |
 | `hd env rm NAME` | Remove a workspace environment variable |
 | `hd host roll [--host HOST] [--address ADDR] [--checkout DIR]` | Pull, install, and restart a runner over SSH, then watch drain |
+| `hd host runner-install` | Register the default host as the org's `self-hosted, hdx` Actions runner |
 | `hd host env ls` | List environment variable names on the workspace's default host |
 | `hd host env set NAME=VALUE [NAME=VALUE...]` | Set host-only environment variables |
 | `hd host env rm NAME` | Remove a host-only environment variable |

package/dist/actions-runner.js

@@ -0,0 +1,126 @@
+import { execFile } from "node:child_process";
+import { access, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { homedir, arch } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+const exec = promisify(execFile);
+export const ACTIONS_RUNNER_TOOLS = ["node", "pnpm", "gh", "supabase", "docker"];
+/** One runner per repository: GitHub only shares runners across repositories for organizations. */
+export function actionsRunnerSlug(repo) {
+    return repo.replace("/", "-").toLowerCase().replace(/[^a-z0-9.-]+/g, "-");
+}
+export function actionsRunnerUnitName(repo) {
+    return `hdx-actions-runner-${actionsRunnerSlug(repo)}.service`;
+}
+export function actionsRunnerDirectory(home, repo) {
+    return path.join(home, ".local/share/hdx/actions-runner", actionsRunnerSlug(repo));
+}
+/** systemd takes WorkingDirectory= and ExecStart= unquoted; only % needs escaping there. */
+function unitPath(value) {
+    return value.replace(/%/g, "%%");
+}
+function unitEnvironment(name, value) {
+    return `"${name}=${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "%%")}"`;
+}
+/**
+ * A systemd user service inherits the supplementary groups the user manager had
+ * when it started, so a docker group granted later never reaches the runner.
+ * Starting through `sg <group>` picks the group up per membership in /etc/group.
+ */
+export function actionsRunnerExecStart(runnerDir, viaGroup) {
+    const service = path.join(runnerDir, "bin/runsvc.sh");
+    return viaGroup ? `/usr/bin/sg ${viaGroup} -c "${unitPath(service)}"` : unitPath(service);
+}
+export function actionsRunnerSystemdUnit(input) {
+    return `[Unit]
+Description=HDX GitHub Actions runner${input.repo ? ` for ${input.repo}` : ""}
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=${unitPath(input.runnerDir)}
+Environment=${unitEnvironment("PATH", input.path)}
+ExecStart=${actionsRunnerExecStart(input.runnerDir, input.viaGroup)}
+Restart=always
+RestartSec=5
+KillMode=process
+
+[Install]
+WantedBy=default.target
+`;
+}
+async function exists(target) {
+    try {
+        await access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function runnerArchitecture(value) {
+    if (value === "x64")
+        return "x64";
+    if (value === "arm64")
+        return "arm64";
+    throw new Error(`GitHub Actions runner does not support architecture ${value}.`);
+}
+export async function installActionsRunner(options, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    if (platform !== "linux")
+        throw new Error("hd host runner-install must run on the Linux host.");
+    if (process.getuid?.() === 0 && !deps.platform)
+        throw new Error("Run hd host runner-install as the runner user, not root.");
+    if (!/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(options.repo))
+        throw new Error("--repo must be OWNER/NAME.");
+    if (!options.token.trim())
+        throw new Error("--token is required.");
+    const run = deps.exec ?? ((file, args, commandOptions = {}) => exec(file, args, {
+        ...commandOptions, encoding: "utf8", maxBuffer: 4 * 1024 * 1024,
+    }));
+    const home = deps.home ?? homedir();
+    const runnerDir = options.runnerDir ?? actionsRunnerDirectory(home, options.repo);
+    const unitName = actionsRunnerUnitName(options.repo);
+    const unitPath = options.unitPath ?? path.join(home, ".config/systemd/user", unitName);
+    const pathValue = options.path ?? process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin";
+    for (const tool of ACTIONS_RUNNER_TOOLS) {
+        await run(tool, ["--version"], { env: process.env }).catch(() => {
+            throw new Error(`${tool} is required before installing the Actions runner.`);
+        });
+    }
+    await mkdir(runnerDir, { recursive: true });
+    const configured = await exists(path.join(runnerDir, ".runner"));
+    if (!await exists(path.join(runnerDir, "bin/runsvc.sh"))) {
+        const release = (await run("gh", ["api", "repos/actions/runner/releases/latest", "--jq", ".tag_name"])).stdout.trim();
+        if (!/^v\d+\.\d+\.\d+$/.test(release))
+            throw new Error(`Invalid Actions runner release ${release || "(empty)"}.`);
+        const version = release.slice(1);
+        const archive = `actions-runner-linux-${runnerArchitecture(deps.architecture ?? arch())}-${version}.tar.gz`;
+        await run("gh", ["release", "download", release, "--repo", "actions/runner", "--pattern", archive,
+            "--dir", runnerDir, "--clobber"]);
+        await run("tar", ["-xzf", path.join(runnerDir, archive), "-C", runnerDir]);
+        await unlink(path.join(runnerDir, archive));
+    }
+    if (!configured) {
+        await run(path.join(runnerDir, "config.sh"), ["--unattended", "--replace",
+            "--url", `https://github.com/${options.repo}`, "--token", options.token, "--name", options.host,
+            "--labels", `hdx,${options.host}`, "--work", "_work"], { cwd: runnerDir, env: process.env });
+    }
+    else {
+        // The runner writes .runner with a UTF-8 byte-order mark, which JSON.parse rejects.
+        const registration = JSON.parse((await readFile(path.join(runnerDir, ".runner"), "utf8")).replace(/^\uFEFF/, ""));
+        if (registration.agentName !== options.host || !registration.gitHubUrl?.toLowerCase().includes(`/${options.repo.toLowerCase()}`)) {
+            throw new Error(`Existing Actions runner in ${runnerDir} belongs to another host or repository.`);
+        }
+    }
+    // Jobs with service containers need the Docker socket; run through the docker group when the user has it.
+    const groups = (await run("id", ["-nG"]).catch(() => ({ stdout: "" }))).stdout.trim().split(/\s+/);
+    const viaGroup = groups.includes("docker") && await exists("/usr/bin/sg") ? "docker" : null;
+    await mkdir(path.dirname(unitPath), { recursive: true });
+    await writeFile(unitPath, actionsRunnerSystemdUnit({ runnerDir, path: pathValue, repo: options.repo, viaGroup }), "utf8");
+    await run("systemctl", ["--user", "daemon-reload"]);
+    await run("systemctl", ["--user", "enable", "--now", unitName]);
+    return [`GitHub Actions runner ${options.host} registered to ${options.repo}.`,
+        `labels: self-hosted, hdx, ${options.host}`, `systemd unit: ${unitPath}${viaGroup ? ` (via sg ${viaGroup})` : ""}`];
+}

package/dist/api.js

@@ -137,6 +137,9 @@ export async function setHostEnv(host, name, value, config = loadConfig()) {
 export async function removeHostEnv(host, name, config = loadConfig()) {
     return request(config, "DELETE", `/api/hosts/${encodeURIComponent(host)}/env`, { name });
 }
+export async function setHostCi(host, owner, config = loadConfig()) {
+    return request(config, "PATCH", `/api/hosts/${encodeURIComponent(host)}/ci`, { ci: "self-hosted", owner });
+}
 export async function getRoadmap(config = loadConfig()) {
     return request(config, "GET", `/api/w/${config.slug}/roadmap`);
 }

package/dist/host.js

@@ -64,6 +64,15 @@ export function formatDrainStatus(live, until, now = Date.now()) {
     const runs = live === 1 ? "1 run" : `${live} runs`;
     return `draining: ${runs}, up to ${minutes}m`;
 }
+export function formatCiMinutes(minutes) {
+    const reset = new Date(minutes.resets_at).toLocaleDateString("en-US", {
+        month: "short", day: "numeric", timeZone: "UTC",
+    });
+    const share = minutes.total_runs
+        ? `; ${Math.round(minutes.box_runs / minutes.total_runs * 100)}% of this month's runs used the box` : "";
+    return `GitHub Actions: ${minutes.used.toLocaleString("en-US")} of ${minutes.included.toLocaleString("en-US")}`
+        + ` hosted minutes used, resets ${reset}${share}`;
+}
 export function hostDrainFromStats(stats) {
     if (!stats || typeof stats !== "object" || Array.isArray(stats))
         return null;
@@ -174,7 +183,7 @@ export function hostRollCommand(checkout) {
         "npm i -g @higherdev/cli@latest",
     ].join(" && ");
 }
-async function defaultSsh(address, command) {
+export async function defaultSsh(address, command) {
     return execFileAsync("ssh", ["-o", "BatchMode=yes", address, "bash", "-lc", command], { encoding: "utf8" });
 }
 async function exists(file) {

package/dist/index.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
-import { approveEpic, answerDecision, cancelTicket, cancelRun, mergeTicket, createEpic, deleteAgent, deleteEpic, getStatus, getRoadmap, getWorkspace, listAgents, listEpics, listHostEnv, listMessages, listWorkspaceEnv, listTicketRunEvents, listTickets, listWorkspaces, postMessage, queueTicket, removeWorkspaceEnv, removeHostEnv, setPaused, setWorkspaceEnv, setHostEnv, showTicket, updateAgent, updateEpic, updateCaps, } from "./api.js";
-import { formatDrainStatus, hostRoll, initHost, parseHostFlags, parseHostRollFlags } from "./host.js";
+import { approveEpic, answerDecision, cancelTicket, cancelRun, mergeTicket, createEpic, deleteAgent, deleteEpic, getStatus, getRoadmap, getWorkspace, listAgents, listEpics, listHostEnv, listMessages, listWorkspaceEnv, listTicketRunEvents, listTickets, listWorkspaces, postMessage, queueTicket, removeWorkspaceEnv, removeHostEnv, setPaused, setWorkspaceEnv, setHostEnv, setHostCi, showTicket, updateAgent, updateEpic, updateCaps, } from "./api.js";
+import { defaultSsh, formatCiMinutes, formatDrainStatus, hostRoll, initHost, parseHostFlags, parseHostRollFlags } from "./host.js";
+import { installActionsRunner } from "./actions-runner.js";
 import { login, parseLoginFlags } from "./login.js";
 import { loadConfig } from "./config.js";
 import { beginUpdateCheck, pendingUpdateNotice, runUpdate, shouldUpdateCheck, } from "./update-check.js";
@@ -73,6 +74,8 @@ async function cmdStatus() {
     if (signedOut.length) {
         console.log(`${c.bold("Host")}  ${signedOut.map((row) => c.yellow(row.reason)).join("\n       ")}\n`);
     }
+    if (data.host?.ci_minutes)
+        console.log(`${c.bold("CI")}  ${formatCiMinutes(data.host.ci_minutes)}\n`);
     const waiting = [...new Set(data.tickets.map((ticket) => ticket.stuck_reason
             ?.match(/^Waiting on (\w+) until (\d{1,2}:\d{2})\.$/)).filter(Boolean)
             .map((match) => `${match?.[1]} waiting until ${match?.[2]}`))];
@@ -582,7 +585,53 @@ async function cmdHost(argv, deps = {}) {
         await hostRoll(parseHostRollFlags([action, ...args].filter((value) => Boolean(value))), deps);
         return;
     }
-    const usage = "usage: hd host roll [--host HOST] [--address ADDR] [--checkout DIR] | env ls | set NAME=VALUE [NAME=VALUE...] | rm NAME";
+    const usage = "usage: hd host runner-install [--repo OWNER/NAME --token TOKEN] | roll [--host HOST] [--address ADDR] [--checkout DIR] | env ls | set NAME=VALUE [NAME=VALUE...] | rm NAME";
+    if (scope === "runner-install") {
+        const parsed = flags([action, ...args].filter((value) => Boolean(value)));
+        if (parsed.rest.length || parsed.bools.size)
+            fail(usage);
+        if (parsed.opts.repo || parsed.opts.token) {
+            // Host mode: register one runner for one repository with a token minted by the owner.
+            // With --host it needs no hd login on the host, so the first runner can be bootstrapped
+            // from a checkout before any published CLI can reach the host.
+            if (!parsed.opts.repo || !parsed.opts.token)
+                fail(usage);
+            if (process.platform !== "linux" && !deps.installActionsRunner)
+                fail("Run this form on the Linux host.");
+            const host = parsed.opts.host ?? (await getStatus()).host?.id ?? (await getStatus()).workspace.default_host;
+            const lines = await (deps.installActionsRunner ?? installActionsRunner)({
+                host, repo: parsed.opts.repo, token: parsed.opts.token,
+            });
+            console.log(lines.join("\n"));
+            return;
+        }
+        const status = await getStatus();
+        const host = parsed.opts.host ?? status.host?.id ?? status.workspace.default_host;
+        // Owner mode: GitHub shares runners across repositories only for organizations, and a
+        // registration token needs admin on the repository, so mint one per workspace repository
+        // with the operator's gh here and hand each to the host over SSH. Tokens expire in an hour.
+        const address = status.host?.ssh_address;
+        if (!address)
+            fail(`hd host runner-install needs an SSH address for ${host}. Set RUNNER_SSH_ADDRESS on the host.`);
+        const workspaces = await listWorkspaces();
+        const repos = [...new Set(workspaces
+                .filter((workspace) => !("default_host" in workspace) || workspace.default_host === host)
+                .map((workspace) => workspace.repo))];
+        if (!repos.length)
+            fail(`No workspaces use host ${host}.`);
+        const gh = deps.gh ?? defaultGh;
+        for (const repo of repos) {
+            const token = (await gh(["api", "--method", "POST", `/repos/${repo}/actions/runners/registration-token`,
+                "--jq", ".token"])).trim();
+            if (!token)
+                fail(`GitHub did not return a runner registration token for ${repo}; you need admin on that repository.`);
+            const remote = await (deps.ssh ?? defaultSsh)(address, `hd --no-update-check host runner-install --host ${host} --repo ${repo} --token ${token}`);
+            console.log(remote.stdout.trim() || `Registered a runner for ${repo} on ${host}.`);
+        }
+        await setHostCi(host, repos[0].split("/")[0]);
+        console.log(`CI on ${host} enabled for ${repos.length} repositor${repos.length === 1 ? "y" : "ies"}; workflows move to [self-hosted, hdx] on the next reconcile.`);
+        return;
+    }
     if (scope !== "env")
         fail(usage);
     const host = (await getStatus()).workspace.default_host;

package/dist/out.js

@@ -73,7 +73,7 @@ export function usage() {
         `  ${c.blue("hd agents [add | rm | set]")}         manage agents`,
         `  ${c.blue("hd caps [set PROVIDER N]")}           provider concurrency`,
         `  ${c.blue("hd env ls [--vercel] | set | rm")}    workspace environment`,
-        `  ${c.blue("hd host roll | env ls | set | rm")}   roll a host or edit host env`,
+        `  ${c.blue("hd host runner-install | roll | env")} install CI, roll, or edit host env`,
         `  ${c.blue("hd logs KEY [-f]")}                  run events`,
         `  ${c.blue("hd msg KEY TEXT")}                   message a builder`,
         `  ${c.blue("hd attach PATH --ticket KEY | --to ROLE")} attach a file`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@higherdev/cli",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "type": "module",
   "repository": {
     "type": "git",