hub-runner 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# hub-runner
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runs a hub workspace's Mac bots on this Mac. It runs under launchd, so no app has to be open.
+
+```
+npm i -g hub-runner --min-release-age=0
+hub-runner login
+hub-runner start
+```
+
+`login` signs in with Vercel, asks which workspace this Mac runs bots for, and stores a session of the runner's own in `~/.hub/local/credentials.json`. The Vercel token is revoked once the hub has the session.
+
+| Command | What it does |
+|---|---|
+| `hub-runner start [--take-over]` | Starts the runner under launchd (`~/Library/LaunchAgents/dev.hub.runner.plist`). It starts again at every login and is not restarted after a crash: run `start` again. `--take-over` claims the Mac slot from another Mac. |
+| `hub-runner stop` | Stops it. |
+| `hub-runner restart` | Lets the open turns finish, then starts it again. |
+| `hub-runner status` | The runner's state, pid, version, bots, and whether launchd has it loaded. Exits 1 when it isn't running. |
+| `hub-runner logs [-f]` | The log, `~/.hub/local/runner.log`. |
+| `hub-runner logout` | Stops it and deletes the stored session. |
+
+## Update
+
+```
+npm i -g hub-runner@latest --min-release-age=0 && hub-runner restart
+```
+
+`restart` lets the turns open now finish, so no bot is cut off.
+
+`--min-release-age=0` lets the newest release install when your npm config holds packages back for a few days (`min-release-age`). It applies to this one install, and hub-runner has no dependencies, so nothing else skips the wait.
+
+## Notes
+
+- Node 24 or later, and `pnpm` on your PATH when you run `start`: the runner uses both to set the bots up.
+- The hub is `https://hosted-hub.playground-vercel.tools`; set `HUB_URL` when you run `login` for another one.
+- The HubHosted app only shows the runner's state. Quitting, signing out of or replacing the app doesn't touch the runner.
+- If the runner doesn't start, `hub-runner status` and `hub-runner logs` say why.

package/bin/hub-runner.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { credentialsFile, logFile } from '../lib/paths.mjs';
+import { kickstart, loaded, start, stop } from '../lib/launchd.mjs';
+import { login } from '../lib/login.mjs';
+import { alive, live, read, statuses, stillRunning } from '../lib/state.mjs';
+
+const USAGE = `hub-runner login | start [--take-over] | stop | restart | status | logs [-f] | logout
+
+  login      sign in with Vercel and choose the workspace this Mac runs bots for
+  start      start the runner under launchd (it starts again at every login); --take-over claims it from another Mac
+  stop       stop the runner
+  restart    let the open turns finish, then start the runner again (after \`npm i -g hub-runner@latest --min-release-age=0\`)
+  status     what the runner is doing; exits 1 when it isn't running
+  logs       the runner's log; -f follows it
+  logout     stop the runner and forget the sign-in`;
+
+/** SIGUSR2 drains the runner (open turns finish, nothing new starts) and it exits 6; then launchd starts it again. */
+async function restart() {
+  const runner = live();
+  if (runner) {
+    console.log(`waiting for open turns on pid ${runner.pid} to finish`);
+    process.kill(runner.pid, 'SIGUSR2');
+    while (alive(runner.pid)) await sleep(250);
+    const { exitCode } = read(runner.pid);
+    if (exitCode !== 6) throw new Error(`the runner ended during the drain with exit code ${exitCode}, not 6: see \`hub-runner logs\`, then run \`hub-runner start\``);
+  }
+  kickstart();
+}
+
+function status() {
+  const [latest] = statuses();
+  const running = latest && stillRunning(latest) && latest.state === 'running';
+  const state = !latest ? 'never started' : latest.exitCode === undefined && !stillRunning(latest) ? 'killed' : latest.exitCode !== undefined ? `${latest.state} (exit ${latest.exitCode})` : latest.state;
+  console.log([state, latest?.pid && `pid ${latest.pid}`, latest?.build && `version ${latest.build}`, loaded() ? 'loaded in launchd' : 'not loaded in launchd', latest?.bots?.length && `bots ${latest.bots.map((b) => b.name).join(' ')}`].filter(Boolean).join(', '));
+  if (latest?.setup) console.log(`workspace setup failed at ${latest.setup.commit}: ${latest.setup.reason}`);
+  if (latest?.holder) console.log(`held by ${latest.holder.deviceName}`);
+  process.exitCode = running ? 0 : 1;
+}
+
+function logs(follow) {
+  if (!existsSync(logFile())) throw new Error(`no log yet at ${logFile()}`);
+  if (!follow) return process.stdout.write(readFileSync(logFile()));
+  spawn('tail', ['-n', '200', '-f', logFile()], { stdio: 'inherit' }).on('exit', (code) => process.exit(code ?? 0));
+}
+
+const [command, ...args] = process.argv.slice(2);
+try {
+  if (process.getuid() === 0) throw new Error('run hub-runner without sudo: the runner is a launchd job of your own user, and root has none');
+  switch (command) {
+    case 'login': await login(); break;
+    case 'start': start({ takeOver: args.includes('--take-over') }); console.log('started: see `hub-runner status`'); break;
+    case 'stop': stop(); break;
+    case 'restart': await restart(); break;
+    case 'status': status(); break;
+    case 'logs': logs(args.includes('-f')); break;
+    case 'logout': stop(); rmSync(credentialsFile(), { force: true }); break;
+    default: console.error(USAGE); process.exitCode = command ? 2 : 0;
+  }
+} catch (e) {
+  console.error(e.message);
+  process.exitCode = 1;
+}

package/lib/device.mjs

@@ -0,0 +1,7 @@
+import { execFileSync } from 'node:child_process';
+import { hostname } from 'node:os';
+
+/** What the hub shows for this Mac: its System Settings name, else its hostname (a Mac has the first; CI hasn't). */
+export function deviceName() {
+  try { return execFileSync('scutil', ['--get', 'ComputerName'], { encoding: 'utf8' }).trim() || hostname(); } catch { return hostname(); }
+}

package/lib/launchd.mjs

@@ -0,0 +1,85 @@
+// The runner's launchd job: a plist in the user's LaunchAgents, loaded in the GUI domain, so it starts at login and
+// outlives every app. `RunAtLoad` without `KeepAlive`: a crash waits for `hub-runner start`.
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { LABEL, credentialsFile, logFile, mainFile, plistFile, runnerDir, version } from './paths.mjs';
+import { deviceName } from './device.mjs';
+
+const xml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const domain = () => `gui/${process.getuid()}`;
+const launchctl = (args, { check = true } = {}) => {
+  const run = spawnSync('launchctl', args, { encoding: 'utf8' });
+  if (run.error) throw run.error;
+  if (check && run.status !== 0) throw new Error(`launchctl ${args.join(' ')} failed (${run.status}): ${(run.stderr || run.stdout).trim()}`);
+  return run.status === 0;
+};
+
+export const loaded = () => launchctl(['print', `${domain()}/${LABEL}`], { check: false });
+
+const EXIT_TIMEOUT_S = 60;
+
+// `bootout` returns while the old runner may still be draining (up to ExitTimeOut), and a `bootstrap` before launchd
+// drops the job fails with error 5. So wait for the job to leave the domain.
+function bootout() {
+  launchctl(['bootout', `${domain()}/${LABEL}`]);
+  const until = Date.now() + (EXIT_TIMEOUT_S + 5) * 1000;
+  const tick = new Int32Array(new SharedArrayBuffer(4));
+  while (loaded()) {
+    if (Date.now() > until) throw new Error(`launchd still holds ${LABEL} ${EXIT_TIMEOUT_S + 5}s after bootout: see \`hub-runner logs\``);
+    Atomics.wait(tick, 0, 0, 250);
+  }
+}
+
+export function plist({ takeOver }) {
+  const pnpm = execFileSync('/bin/sh', ['-c', 'command -v pnpm'], { encoding: 'utf8' }).trim();
+  const env = { HUB_PNPM: pnpm, PATH: process.env.PATH, HUB_RUNNER_DIR: runnerDir(), HUB_RUNNER_BUILD: version(), HUB_DEVICE_NAME: deviceName(), ...(takeOver ? { HUB_RUNNER_TAKE_OVER: '1' } : {}) };
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xml(process.execPath)}</string>
+    <string>${xml(mainFile())}</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xml(runnerDir())}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${Object.entries(env).map(([k, v]) => `    <key>${k}</key>\n    <string>${xml(v)}</string>`).join('\n')}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>ExitTimeOut</key>
+  <integer>${EXIT_TIMEOUT_S}</integer>
+  <key>StandardOutPath</key>
+  <string>${xml(logFile())}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(logFile())}</string>
+</dict>
+</plist>
+`;
+}
+
+export function start({ takeOver = false } = {}) {
+  if (!existsSync(credentialsFile())) throw new Error('not signed in: run `hub-runner login` first');
+  mkdirSync(runnerDir(), { recursive: true });
+  mkdirSync(dirname(plistFile()), { recursive: true });
+  writeFileSync(plistFile(), plist({ takeOver }));
+  if (loaded()) bootout();
+  launchctl(['bootstrap', domain(), plistFile()]);
+}
+
+export function stop() {
+  if (loaded()) bootout();
+}
+
+/** Starts the loaded job again, or loads it from the plist the last `start` wrote. */
+export function kickstart() {
+  if (loaded()) launchctl(['kickstart', '-k', `${domain()}/${LABEL}`]);
+  else if (existsSync(plistFile())) launchctl(['bootstrap', domain(), plistFile()]);
+  else throw new Error('not started yet: run `hub-runner start`');
+}

package/lib/login.mjs

@@ -0,0 +1,86 @@
+// `hub-runner login`: Sign in with Vercel (the device flow, with the Vercel CLI's client the app uses too:
+// native/Sources/HubCore/VercelOAuth.swift), pick the account's workspace, and have the hub store a session of the
+// runner's own for it. The Vercel token is revoked once the hub has the session: the runner never holds it.
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { chmodSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { DEFAULT_HUB, credentialsFile } from './paths.mjs';
+
+const CLIENT_ID = 'cl_HYyOPBNtFMfHhaUn9L4QPfTZz6TP47bp';
+const HUB_TEAM = 'team_TtmJZYmD3tcLBLqWOhoVawd1';
+const api = () => (process.env.HUB_VERCEL_API || 'https://api.vercel.com').replace(/\/$/, '');
+
+async function exchange(url, init) {
+  const res = await fetch(url, init);
+  const body = await res.json().catch(() => ({}));
+  if (res.ok) return body;
+  const error = typeof body.error === 'string' ? body.error : body.error?.code ?? `http_${res.status}`;
+  throw Object.assign(new Error(body.error_description ?? body.error?.message ?? body.error ?? `${init.method ?? 'GET'} ${new URL(url).pathname} answered ${res.status}`), { code: error, status: res.status });
+}
+const form = (url, fields) => exchange(url, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams(fields) });
+const json = (url, method, token, extra = {}, body) => exchange(url, { method, headers: { authorization: `Bearer ${token}`, ...extra, ...(body ? { 'content-type': 'application/json' } : {}) }, body: body && JSON.stringify(body) });
+
+async function deviceFlow(say) {
+  const start = await form(`${api()}/login/oauth/device-authorization`, { client_id: CLIENT_ID, scope: 'openid offline_access' });
+  say(`Open ${start.verification_uri_complete} and approve the code ${start.user_code}.`);
+  if (process.platform === 'darwin') spawn('open', [start.verification_uri_complete], { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
+  let interval = start.interval ?? 5;
+  const until = Date.now() + (start.expires_in ?? 600) * 1000;
+  while (Date.now() < until) {
+    await sleep(interval * 1000);
+    try {
+      return await form(`${api()}/login/oauth/token`, { client_id: CLIENT_ID, grant_type: 'urn:ietf:params:oauth:grant-type:device_code', device_code: start.device_code });
+    } catch (e) {
+      if (e.code === 'authorization_pending') continue;
+      if (e.code === 'slow_down') { interval += 5; continue; }
+      throw e;
+    }
+  }
+  throw new Error('the sign-in code expired: run `hub-runner login` again');
+}
+
+/** The hub is protected by Vercel; its project's automation secret, as the app reads it, lets the runner through. */
+async function protectionBypass(hub, token) {
+  const project = new URL(hub).hostname.split('.')[0], query = `?teamId=${HUB_TEAM}`;
+  const secretOf = (j) => Object.entries(j.protectionBypass ?? {}).find(([, v]) => v.scope === 'automation-bypass')?.[0];
+  const existing = secretOf(await json(`${api()}/v9/projects/${project}${query}`, 'GET', token));
+  if (existing) return existing;
+  const created = secretOf(await json(`${api()}/v1/projects/${project}/protection-bypass${query}`, 'PATCH', token, {}, {}));
+  if (!created) throw new Error(`Vercel gave no automation secret for ${project}`);
+  return created;
+}
+
+async function pick(workspaces, say) {
+  if (workspaces.length === 1) return workspaces[0];
+  say('Workspaces:');
+  workspaces.forEach((w, i) => say(`  ${i + 1}. ${w.name}`));
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    for (;;) {
+      const chosen = workspaces[Number(await rl.question('Which one runs on this Mac? ')) - 1];
+      if (chosen) return chosen;
+    }
+  } finally { rl.close(); }
+}
+
+export async function login({ say = console.log } = {}) {
+  const hub = (process.env.HUB_URL || DEFAULT_HUB).replace(/\/$/, '');
+  const tokens = await deviceFlow(say);
+  const bypass = await protectionBypass(hub, tokens.access_token);
+  const headers = { 'x-vercel-protection-bypass': bypass };
+  const { workspaces } = await json(`${hub}/api/workspaces`, 'GET', tokens.access_token, headers);
+  if (!workspaces.length) throw new Error('this Vercel account has no hub workspace: sign in to the Hub app once to create one');
+  const workspace = await pick(workspaces, say);
+  const session = randomBytes(32).toString('hex');
+  await json(`${hub}/api/workspaces/${encodeURIComponent(workspace.id)}/session`, 'POST', tokens.access_token, headers, { session });
+  await form(`${api()}/login/oauth/token/revoke`, { client_id: CLIENT_ID, token: tokens.refresh_token });
+  const file = credentialsFile();
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(`${file}.tmp`, JSON.stringify({ hubUrl: hub, session, workspace: workspace.id, bypass }), { mode: 0o600 });
+  chmodSync(`${file}.tmp`, 0o600);
+  renameSync(`${file}.tmp`, file);
+  say(`Signed in to ${workspace.name}. Run \`hub-runner start\`.`);
+}

package/lib/paths.mjs

@@ -0,0 +1,12 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const LABEL = 'dev.hub.runner';
+export const DEFAULT_HUB = 'https://hosted-hub.playground-vercel.tools';
+export const runnerDir = () => process.env.HUB_RUNNER_DIR || join(homedir(), '.hub', 'local');
+export const credentialsFile = () => join(runnerDir(), 'credentials.json');
+export const logFile = () => join(runnerDir(), 'runner.log');
+export const plistFile = () => join(homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+export const mainFile = () => new URL('../main.mjs', import.meta.url).pathname;
+export const version = () => JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;

package/lib/state.mjs

@@ -0,0 +1,29 @@
+// The runner's status files (hosted-hub/runner/status.ts): status/<pid>.json in its dir, one per process.
+import { execFileSync } from 'node:child_process';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { runnerDir } from './paths.mjs';
+
+export const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { if (e.code === 'EPERM') return true; if (e.code === 'ESRCH') return false; throw e; } };
+
+/** When `pid` started, in ms; undefined when no such process. `lstart` has whole seconds. */
+const startedAt = (pid) => {
+  try { return Date.parse(execFileSync('/bin/ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf8', env: { ...process.env, LC_ALL: 'C' }, stdio: ['ignore', 'pipe', 'ignore'] }).trim()) || undefined; } catch { return undefined; }
+};
+
+/** Whether the process that wrote a status file still runs: its pid is alive and started before the file was last written (a pid reused later started after). */
+export const stillRunning = (s) => s.exitCode === undefined && alive(s.pid) && (startedAt(s.pid) ?? Infinity) <= s.writtenAt + 1000;
+
+/** Every status file, newest write first, with when it was written. */
+export function statuses() {
+  const dir = join(runnerDir(), 'status');
+  let names;
+  try { names = readdirSync(dir).filter((n) => n.endsWith('.json')); } catch (e) { if (e.code === 'ENOENT') return []; throw e; }
+  return names.map((n) => join(dir, n)).map((path) => ({ path, mtime: statSync(path).mtimeMs })).sort((a, b) => b.mtime - a.mtime)
+    .map(({ path, mtime }) => ({ ...JSON.parse(readFileSync(path, 'utf8')), writtenAt: mtime }));
+}
+
+/** The runner that is running now: its status file has no exit code and its process is the one that wrote it. */
+export const live = () => statuses().find(stillRunning);
+
+export const read = (pid) => JSON.parse(readFileSync(join(runnerDir(), 'status', `${pid}.json`), 'utf8'));