@higherdev/cli 0.17.0 → 0.18.0

package/README.md

@@ -49,6 +49,7 @@ workspace-map config shapes are migrated automatically when they are read.
 | `hd env ls` | List workspace environment variable names |
 | `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 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 |
@@ -64,9 +65,15 @@ workspace-map config shapes are migrated automatically when they are read.
 | `hd upgrade --host HOST [--checkout DIR] [options]` | Refresh this host configuration |
 
 `hd init` uses `~/hdx` as its checkout by default. Pass `--checkout DIR` when the runner source is
-elsewhere. If the runner environment or service unit already exists, inspect the paths it prints and
+elsewhere. Pass `--address HOST` to store `RUNNER_SSH_ADDRESS` so `hd host roll` can SSH to that
+host. If the runner environment or service unit already exists, inspect the paths it prints and
 pass `--force` only when replacing that host configuration is intentional.
 
+`hd host roll` SSHes to the host address (`--address`, or `RUNNER_SSH_ADDRESS` from the host
+heartbeat), pulls the checkout, installs, and restarts the systemd unit. The runner drains live
+runs for up to 15 minutes (`RUNNER_DRAIN_TIMEOUT_MS`) before force-closing leftovers. The systemd
+unit `TimeoutStopSec` is one minute above that drain timeout.
+
 `hd workspace new` uses the operator's authenticated `gh`, defaults to the repository's real default
 branch, bootstraps an empty repository unless `--no-bootstrap` is set, and invites `mel-ilotus` with push
 access for user-owned repositories or admin for organization-owned repositories unless `--runner-user USER`

package/dist/host.js

@@ -53,6 +53,35 @@ export function launchdPlist(opts) {
 </plist>
 `;
 }
+export const DEFAULT_DRAIN_TIMEOUT_MS = 15 * 60_000;
+export const HOST_ROLL_USAGE = "usage: hd host roll [--host HOST] [--address ADDR] [--checkout DIR]";
+export function systemdStopTimeoutSec(drainTimeoutMs = DEFAULT_DRAIN_TIMEOUT_MS) {
+    return Math.ceil(drainTimeoutMs / 1_000) + 60;
+}
+export function formatDrainStatus(live, until, now = Date.now()) {
+    const remaining = Date.parse(until) - now;
+    const minutes = Number.isFinite(remaining) ? Math.max(0, Math.ceil(remaining / 60_000)) : 0;
+    const runs = live === 1 ? "1 run" : `${live} runs`;
+    return `draining: ${runs}, up to ${minutes}m`;
+}
+export function hostDrainFromStats(stats) {
+    if (!stats || typeof stats !== "object" || Array.isArray(stats))
+        return null;
+    const draining = stats.draining;
+    if (!draining || typeof draining !== "object" || Array.isArray(draining))
+        return null;
+    const live = Number(draining.live);
+    const until = draining.until;
+    if (!Number.isFinite(live) || live < 0 || typeof until !== "string")
+        return null;
+    return { live, until };
+}
+export function sshAddressFromStats(stats) {
+    if (!stats || typeof stats !== "object" || Array.isArray(stats))
+        return null;
+    const value = stats.ssh_address;
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
 export function systemdUnit(opts) {
     return `[Unit]
 Description=HDX runner
@@ -65,6 +94,7 @@ WorkingDirectory=${opts.workDir}
 ExecStart=${opts.nodePath} --experimental-strip-types ${opts.runnerPath}
 Restart=always
 RestartSec=5
+TimeoutStopSec=${systemdStopTimeoutSec(opts.drainTimeoutMs)}
 
 [Install]
 WantedBy=default.target
@@ -85,6 +115,8 @@ export function parseHostFlags(argv) {
             flags.host = next();
         else if (arg === "--checkout")
             flags.checkout = next();
+        else if (arg === "--address")
+            flags.address = next();
         else if (arg === "--force")
             flags.force = true;
         else if (arg === "--env-out")
@@ -104,6 +136,45 @@ export function parseHostFlags(argv) {
     }
     return flags;
 }
+export function parseHostRollFlags(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const next = () => {
+            const value = argv[i + 1];
+            if (!value || value.startsWith("--"))
+                throw new Error(`Missing value for ${arg}`);
+            i += 1;
+            return value;
+        };
+        if (arg === "--host")
+            flags.host = next();
+        else if (arg === "--address")
+            flags.address = next();
+        else if (arg === "--checkout")
+            flags.checkout = next();
+        else if (!arg.startsWith("-") && !flags.host)
+            flags.host = arg;
+        else
+            throw new Error(arg.startsWith("-") ? `Unknown option: ${arg}` : HOST_ROLL_USAGE);
+    }
+    return flags;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export function hostRollCommand(checkout) {
+    return [
+        "set -e",
+        `cd ${shellQuote(checkout)}`,
+        "git pull --ff-only",
+        "pnpm install",
+        "systemctl --user restart hdx-runner.service",
+    ].join(" && ");
+}
+async function defaultSsh(address, command) {
+    return execFileAsync("ssh", ["-o", "BatchMode=yes", address, "bash", "-lc", command], { encoding: "utf8" });
+}
 async function exists(file) {
     try {
         await access(file);
@@ -159,6 +230,9 @@ export async function initHost(flags, env = process.env) {
         RUNNER_HOST: host,
         WORKTREE_ROOT: worktreeRoot,
         GH_TOKEN: env.GH_TOKEN || existing.GH_TOKEN || "",
+        ...(flags.address || env.RUNNER_SSH_ADDRESS || existing.RUNNER_SSH_ADDRESS
+            ? { RUNNER_SSH_ADDRESS: flags.address || env.RUNNER_SSH_ADDRESS || existing.RUNNER_SSH_ADDRESS }
+            : {}),
     };
     await mkdir(path.dirname(envFile), { recursive: true });
     await writeFile(envFile, formatEnvFile(merged), { encoding: "utf8", mode: 0o600 });
@@ -198,3 +272,48 @@ export async function initHost(flags, env = process.env) {
     lines.push("Start the runner service to register this host.");
     return lines.join("\n");
 }
+const ROLL_WAIT_MS = DEFAULT_DRAIN_TIMEOUT_MS + 2 * 60_000;
+export async function hostRoll(flags, deps = {}) {
+    const log = deps.log ?? ((line) => console.log(line));
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const ssh = deps.ssh ?? defaultSsh;
+    const loadStatus = deps.getStatus ?? (await import("./api.js")).getStatus;
+    const snapshot = await loadStatus();
+    const host = flags.host ?? snapshot.workspace.default_host;
+    const address = flags.address ?? snapshot.host?.ssh_address ?? null;
+    if (!address) {
+        throw new Error(`hd host roll needs an SSH address for ${host}. Pass --address or set RUNNER_SSH_ADDRESS on the host.`);
+    }
+    const checkout = expandHome(flags.checkout ?? "~/hdx", homedir());
+    const command = hostRollCommand(checkout);
+    const lines = [`rolling ${host} at ${address}`];
+    log(lines[0]);
+    await ssh(address, command);
+    const restarted = `restarted ${host}; waiting for drain`;
+    lines.push(restarted);
+    log(restarted);
+    const before = snapshot.host?.last_seen_at ?? null;
+    const deadline = now() + (deps.waitMs ?? ROLL_WAIT_MS);
+    let lastDrain = "";
+    while (now() < deadline) {
+        const status = await loadStatus();
+        const drain = status.host?.draining ?? null;
+        if (drain) {
+            const line = formatDrainStatus(drain.live, drain.until, now());
+            if (line !== lastDrain) {
+                lastDrain = line;
+                lines.push(line);
+                log(line);
+            }
+        }
+        else if (status.host?.last_seen_at && status.host.last_seen_at !== before && status.host.runner_version) {
+            const line = `${host} runner ${status.host.runner_version}`;
+            lines.push(line);
+            log(line);
+            return lines;
+        }
+        await sleep(2_000);
+    }
+    throw new Error(`timed out waiting for ${host} to finish draining`);
+}

package/dist/index.js

@@ -2,7 +2,7 @@
 import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { approveEpic, answerDecision, cancelTicket, createEpic, deleteAgent, deleteEpic, getStatus, getWorkspace, listAgents, listEpics, listHostEnv, listMessages, listWorkspaceEnv, listTicketRunEvents, listTickets, listWorkspaces, postMessage, queueTicket, removeWorkspaceEnv, removeHostEnv, setPaused, setWorkspaceEnv, setHostEnv, showTicket, updateAgent, updateCaps, } from "./api.js";
-import { initHost, parseHostFlags } from "./host.js";
+import { formatDrainStatus, hostRoll, initHost, parseHostFlags, parseHostRollFlags } from "./host.js";
 import { login, parseLoginFlags } from "./login.js";
 import { loadConfig } from "./config.js";
 import { epicProgressRows, readEpicSpec } from "./epics.js";
@@ -63,6 +63,9 @@ async function cmdStatus() {
     const data = await getStatus();
     const state = data.workspace.paused ? c.yellow("off") : c.green("on");
     console.log(`${c.bold(data.workspace.name)}  ${c.dim(data.workspace.repo)}  ${state}\n`);
+    if (data.host?.draining) {
+        console.log(`${c.yellow(formatDrainStatus(data.host.draining.live, data.host.draining.until))}\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]}`))];
@@ -423,12 +426,23 @@ function githubSecretMissing(error) {
     return /404|not found|does not exist/i.test(message);
 }
 export async function cmdEnv(argv, deps = {}) {
-    const [action, ...args] = argv;
-    if (action === "ls") {
-        const { env } = await listWorkspaceEnv();
+    const parsed = flags(argv);
+    const [rawAction, ...args] = parsed.rest;
+    const action = !rawAction && parsed.bools.has("vercel") ? "ls" : rawAction;
+    if (action === "ls" && !args.length && !Object.keys(parsed.opts).length
+        && [...parsed.bools].every((name) => name === "vercel")) {
+        const showVercel = parsed.bools.has("vercel");
+        const [{ env }, detail] = await Promise.all([listWorkspaceEnv(), showVercel ? getWorkspace() : null]);
         if (!env.length)
             return console.log(c.dim("No workspace environment variables."));
-        console.log(table(["NAME", "UPDATED"], env.map((row) => [row.name, row.updated_at])));
+        if (!showVercel)
+            console.log(table(["NAME", "UPDATED"], env.map((row) => [row.name, row.updated_at])));
+        else {
+            const production = new Set(detail?.workspace.settings?.vercel?.production_env ?? []);
+            console.log(table(["NAME", "UPDATED", "VERCEL"], env.map((row) => [
+                row.name, row.updated_at, production.has(row.name) ? "yes" : "no",
+            ])));
+        }
         return;
     }
     if (action === "set" && args.length) {
@@ -471,11 +485,15 @@ export async function cmdEnv(argv, deps = {}) {
         console.log(`synced removal of ${name} to ${repo}`);
         return;
     }
-    fail("usage: hd env ls | set NAME=VALUE [NAME=VALUE...] | rm NAME");
+    fail("usage: hd env ls [--vercel] | set NAME=VALUE [NAME=VALUE...] | rm NAME");
 }
-async function cmdHost(argv) {
+async function cmdHost(argv, deps = {}) {
     const [scope, action, ...args] = argv;
-    const usage = "usage: hd host env ls | set NAME=VALUE [NAME=VALUE...] | rm NAME";
+    if (scope === "roll") {
+        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";
     if (scope !== "env")
         fail(usage);
     const host = (await getStatus()).workspace.default_host;
@@ -573,7 +591,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
             return;
         }
         if (cmd === "host") {
-            await cmdHost(rest);
+            await cmdHost(rest, deps);
             return;
         }
         if (cmd === "pause" || cmd === "off") {

package/dist/out.js

@@ -70,8 +70,8 @@ export function usage() {
         `  ${c.blue("hd workspace ls | use | new | set | rotate-key | grant-runner-access")} workspace operations`,
         `  ${c.blue("hd agents [add | rm | set]")}         manage agents`,
         `  ${c.blue("hd caps [set PROVIDER N]")}           provider concurrency`,
-        `  ${c.blue("hd env ls | set | rm")}               workspace environment`,
-        `  ${c.blue("hd host env ls | set | rm")}          host environment`,
+        `  ${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 logs KEY [-f]")}                  run events`,
         `  ${c.blue("hd msg KEY TEXT")}                   message a builder`,
         `  ${c.blue("hd inbox [--all] [--limit N] [--json]")} inbox messages`,

package/dist/tui/Dashboard.js

@@ -117,10 +117,11 @@ export function AgentsColumn({ board, width, rows, }) {
                 ]
                 : []),
             ...shown.map((row) => {
-                const tone = row.run ? "blue" : row.state === "offline" || row.state === "limited" ? "warning" : "muted";
-                return (_jsxs(Box, { flexWrap: "nowrap", children: [_jsxs(Text, { color: inkColor(tone), children: [DOT, " "] }), _jsxs(Text, { color: UI.text, wrap: "truncate", children: [row.name, _jsx(Text, { color: UI.dim, children: row.run
+                const tone = row.run ? "blue" : row.state === "offline" || row.state === "limited" || row.state === "draining"
+                    ? "warning" : "muted";
+                return (_jsxs(Box, { flexWrap: "nowrap", children: [_jsxs(Text, { color: inkColor(tone), children: [DOT, " "] }), _jsxs(Text, { color: UI.text, wrap: "truncate", children: [row.name, row.state === "draining" ? null : (_jsx(Text, { color: UI.dim, children: row.run
                                         ? ` · ${row.ticket?.key ?? row.run.kind} ${elapsed(row.run.started_at ?? row.run.created_at)}`
-                                        : ` · ${row.limitedUntil ? `limited until ${row.limitedUntil}` : row.state}` })] })] }, row.key));
+                                        : ` · ${row.limitedUntil ? `limited until ${row.limitedUntil}` : row.state}` }))] })] }, row.key));
             }),
             _jsx(More, { count: displayRows.length - shown.length }, "more"),
         ] }));

package/dist/tui/Panels.js

@@ -28,8 +28,10 @@ export function AgentsPanel({ board, width = 80, rows = 12, }) {
                 ]
                 : []),
             ...shown.map((row) => {
-                const tone = row.run ? "blue" : row.state === "offline" || row.state === "limited" ? "warning" : "muted";
-                const state = row.limitedUntil ? `limited until ${row.limitedUntil}` : row.state;
+                const tone = row.run ? "blue" : row.state === "offline" || row.state === "limited" || row.state === "draining"
+                    ? "warning" : "muted";
+                const state = row.state === "draining" ? ""
+                    : row.limitedUntil ? `limited until ${row.limitedUntil}` : row.state;
                 return (_jsxs(Text, { wrap: "truncate", children: [_jsxs(Text, { color: inkColor(tone), children: [DOT, " "] }), _jsx(Text, { color: UI.text, children: pad(truncate(row.name, 13), 14) }), _jsx(Text, { color: UI.dim, children: pad(row.agent?.role ?? row.run?.kind ?? "", 13) }), _jsx(Text, { color: UI.dim, children: pad(truncate(row.agent?.model ?? "", 23), 24) }), _jsx(Text, { color: UI.text, children: pad(state, row.limitedUntil ? 22 : 9) }), _jsxs(Text, { color: UI.dim, children: [row.ticket ? `${row.ticket.key} ` : "", row.run ? elapsed(row.run.started_at ?? row.run.created_at) : ""] })] }, row.key));
             }),
             _jsx(More, { count: displayRows.length - shown.length }, "more"),

package/dist/tui/agent-rows.js

@@ -1,3 +1,4 @@
+import { formatDrainStatus } from "../host.js";
 const LIMITED_UNTIL = /^(?:Waiting on )?(\w+) (?:limited )?until (\d{1,2}:\d{2})\.?$/;
 export function limitedUntilByProvider(tickets) {
     const limited = new Map();
@@ -22,7 +23,18 @@ function agentForRun(board, run) {
     return board.agents.find((agent) => agent.enabled && agent.role === role && agent.provider === run.provider) ?? null;
 }
 /** Expand live invocations into rows, then append enabled agents with no live run. */
-export function agentDisplayRows(board) {
+export function agentDisplayRows(board, now = Date.now()) {
+    const drain = board.hostDrain
+        ? [{
+                key: "drain",
+                name: formatDrainStatus(board.hostDrain.live, board.hostDrain.until, now),
+                agent: null,
+                run: null,
+                ticket: null,
+                state: "draining",
+                limitedUntil: null,
+            }]
+        : [];
     const activeAgents = new Set();
     const live = board.runs
         .filter((run) => run.status === "running" || run.status === "queued")
@@ -71,5 +83,5 @@ export function agentDisplayRows(board) {
             limitedUntil: until ?? null,
         };
     });
-    return [...live, ...idle];
+    return [...drain, ...live, ...idle];
 }

package/dist/tui/data.js

@@ -80,6 +80,7 @@ export async function loadSnapshot(config = loadConfig(), options = {}) {
             earlierHasMore: earlier.length > earlierLimit,
             availability,
             runs: status.recent_runs ?? status.live_runs,
+            hostDrain: status.host?.draining ?? null,
         },
         feed: feedData.entries,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@higherdev/cli",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "type": "module",
   "bin": {
     "hd": "dist/index.js"