@myvillage/cli 2.13.2 → 2.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "2.13.2",
+  "version": "2.14.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {

package/src/commands/runner.js

@@ -3,6 +3,15 @@
  */
 import { createRequire } from 'module';
 import { runRunner, readRunnerState } from '../agent-runtime/runner.js';
+import { getAccessToken } from '../utils/auth.js';
+import {
+  describeRunnerService,
+  stageRunnerService,
+  runnerServiceStatus,
+  canSudo,
+  runWithSudo,
+  shellLine,
+} from '../utils/runner-service.js';
 
 function getCliVersion() {
   try {
@@ -37,4 +46,106 @@ export function runnerStatusCommand() {
   }
   console.log(`Machine:    ${state.name} (${state.machineId})`);
   console.log(`Registered: ${state.registeredAt}`);
+  try {
+    const spec = describeRunnerService();
+    const { installed, running } = runnerServiceStatus(spec);
+    const label = !installed ? 'not installed (run `myvillage runner install-service`)' : running ? 'installed, running' : 'installed, not running';
+    console.log(`Service:    ${label}`);
+    if (installed) console.log(`Log:        ${spec.logFile}`);
+  } catch { /* unsupported platform: nothing to report */ }
+}
+
+function printCommands(commands, spec) {
+  for (const [i, argv] of commands.entries()) {
+    const note = spec.platform === 'launchd' && argv[1] === 'bootout' && i === 0 ? '   # fine if it says not found' : '';
+    console.log(`  ${shellLine(argv)}${note}`);
+  }
+}
+
+export function runnerInstallServiceCommand(options = {}) {
+  let spec;
+  try {
+    spec = describeRunnerService({
+      name: options.name,
+      kind: options.kind,
+      capacity: options.capacity,
+      interval: options.interval,
+    });
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+  if (process.getuid?.() === 0) {
+    console.error('Run this as the account the runner should run as, not as root. It will show or run the sudo steps itself.');
+    process.exit(1);
+  }
+
+  if (options.print) {
+    console.log(spec.content);
+    return;
+  }
+
+  // The service can't answer a login prompt, so the machine needs a credential
+  // before it boots unattended: a saved runner key, or a signed-in user.
+  const state = readRunnerState();
+  if (!state?.machineKey && !getAccessToken() && !process.env.MYVILLAGE_MACHINE_KEY) {
+    console.error('This machine has no runner credential yet. Run `myvillage login` (or `myvillage runner start` once) first.');
+    process.exit(1);
+  }
+
+  const copy = stageRunnerService(spec);
+  console.log(`Runner service for "${spec.user}" (${spec.platform}):`);
+  console.log(`  service file  ${spec.staged}   (copy: ${copy})`);
+  console.log(`  installs to   ${spec.target}`);
+  console.log(`  log           ${spec.logFile}`);
+  if (state?.pid) {
+    console.log('');
+    console.log(`Note: a runner is already running here (pid ${state.pid}). Stop it (Ctrl-C) once the service is up,`);
+    console.log('or the two will compete for the same agents.');
+  }
+  console.log('');
+
+  if (!options.yes && !canSudo()) {
+    console.log("This account isn't an admin, so an admin needs to run these once:");
+    printCommands(spec.install, spec);
+    console.log('');
+    console.log('Then check it with `myvillage runner status`.');
+    return;
+  }
+
+  console.log('Installing (sudo may ask for your password):');
+  printCommands(spec.install, spec);
+  const res = runWithSudo(spec.install, { ignoreFirstFailure: spec.platform === 'launchd' });
+  if (!res.ok) {
+    console.error(`\nFailed at: ${res.failed}`);
+    process.exit(1);
+  }
+  const { running } = runnerServiceStatus(spec);
+  console.log(running
+    ? '\nThe runner is installed and running. It will start at boot, before anyone logs in.'
+    : `\nInstalled, but it isn't running yet. Check ${spec.logFile}.`);
+}
+
+export function runnerUninstallServiceCommand(options = {}) {
+  let spec;
+  try {
+    spec = describeRunnerService();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+  if (!options.yes && !canSudo()) {
+    console.log("This account isn't an admin, so an admin needs to run these to remove the runner service:");
+    printCommands(spec.uninstall, spec);
+    console.log('Agents already running keep running until stopped (`myvillage agent stop <name>`).');
+    return;
+  }
+  console.log('Removing the runner service (sudo may ask for your password):');
+  printCommands(spec.uninstall, spec);
+  const res = runWithSudo(spec.uninstall);
+  if (!res.ok) {
+    console.error(`\nFailed at: ${res.failed}`);
+    process.exit(1);
+  }
+  console.log('\nRemoved. Agents already running keep running until stopped (`myvillage agent stop <name>`).');
 }

package/src/index.js

@@ -82,7 +82,12 @@ import {
   agentRememberCommand,
   agentRecipesListCommand,
 } from './commands/agent-local.js';
-import { runnerStartCommand, runnerStatusCommand } from './commands/runner.js';
+import {
+  runnerStartCommand,
+  runnerStatusCommand,
+  runnerInstallServiceCommand,
+  runnerUninstallServiceCommand,
+} from './commands/runner.js';
 import {
   agentRegisterClientCommand,
   agentListClientsCommand,
@@ -1115,6 +1120,21 @@ export function run() {
     .command('status')
     .description("Show this machine's runner registration")
     .action(runnerStatusCommand);
+  runnerCmd
+    .command('install-service')
+    .description('Start the runner at boot as this user (launchd on macOS, systemd on Linux)')
+    .option('--name <name>', 'Machine name (default: the name it registered with)')
+    .option('--kind <kind>', 'Machine kind: laptop|mac|pi|spark|cloud|other')
+    .option('--capacity <n>', 'Soft cap on concurrently-run agents')
+    .option('--interval <sec>', 'Reconcile/heartbeat interval in seconds')
+    .option('--print', 'Only print the service file; install nothing')
+    .option('--yes', 'Run the sudo steps even if this account does not look like an admin')
+    .action(runnerInstallServiceCommand);
+  runnerCmd
+    .command('uninstall-service')
+    .description('Stop the runner service and remove it')
+    .option('--yes', 'Run the sudo steps even if this account does not look like an admin')
+    .action(runnerUninstallServiceCommand);
 
   program.parse();
 }

package/src/utils/runner-service.js

@@ -0,0 +1,230 @@
+// Install the fleet runner as a boot-time service, so a machine keeps running
+// its assigned agents after a reboot or power cut with nobody logged in.
+//
+//   macOS → a LaunchDaemon in /Library/LaunchDaemons that runs as this user
+//   Linux → a systemd unit in /etc/systemd/system that runs as this user
+//
+// Both are system-level on purpose: a per-user LaunchAgent or user unit only
+// runs while someone is logged in. Installing one needs an admin, and the
+// account that runs agents usually isn't one, so the service file is staged
+// somewhere an admin can read it and the exact sudo commands are printed (or
+// run, when this account can sudo).
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const LOG_FILE = path.join(os.homedir(), '.myvillage', 'logs', 'runner.log');
+
+// The CLI's own entry point, resolved inside the installed package so it keeps
+// working across `npm update -g` (the package directory doesn't move).
+function cliEntryPath() {
+  return fs.realpathSync(fileURLToPath(new URL('../../bin/myvillage.js', import.meta.url)));
+}
+
+// Prefer a stable `node` on PATH over process.execPath when they are the same
+// binary: Homebrew's execPath points into a versioned Cellar dir that vanishes
+// on the next `brew upgrade`, while /opt/homebrew/bin/node follows it.
+function stableNodePath() {
+  const exec = fs.realpathSync(process.execPath);
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, 'node');
+    try {
+      if (fs.realpathSync(candidate) === exec) return candidate;
+    } catch { /* not here */ }
+  }
+  return process.execPath;
+}
+
+function servicePath(nodePath) {
+  const dirs = [path.dirname(nodePath)];
+  if (process.platform === 'darwin') dirs.push('/opt/homebrew/bin', '/opt/homebrew/sbin');
+  dirs.push('/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin');
+  return [...new Set(dirs)].join(':');
+}
+
+function runnerArgs(opts) {
+  const args = ['runner', 'start'];
+  if (opts.name) args.push('--name', String(opts.name));
+  if (opts.kind) args.push('--kind', String(opts.kind));
+  if (opts.capacity) args.push('--capacity', String(opts.capacity));
+  if (opts.interval) args.push('--interval', String(opts.interval));
+  return args;
+}
+
+const xml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+// systemd splits ExecStart on whitespace; quote anything that needs it.
+const sdQuote = (s) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(s) ? s : `"${String(s).replace(/(["\\])/g, '\\$1')}"`);
+
+/**
+ * Describe the service for this machine and user. Pure apart from resolving
+ * paths, so it can be inspected (`--print`) before anything is installed.
+ */
+export function describeRunnerService(opts = {}) {
+  const user = os.userInfo().username;
+  const home = os.homedir();
+  const nodePath = stableNodePath();
+  const cliPath = cliEntryPath();
+  const program = [nodePath, cliPath, ...runnerArgs(opts)];
+  const env = { HOME: home, USER: user, LOGNAME: user, PATH: servicePath(nodePath), LANG: 'en_US.UTF-8' };
+
+  if (process.platform === 'darwin') {
+    const label = `ai.myvillage.runner.${user}`;
+    const target = `/Library/LaunchDaemons/${label}.plist`;
+    const content = `<?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>${xml(label)}</string>
+	<key>UserName</key>
+	<string>${xml(user)}</string>
+	<key>ProgramArguments</key>
+	<array>
+${program.map((a) => `\t\t<string>${xml(a)}</string>`).join('\n')}
+	</array>
+	<key>WorkingDirectory</key>
+	<string>${xml(home)}</string>
+	<key>EnvironmentVariables</key>
+	<dict>
+${Object.entries(env).map(([k, v]) => `\t\t<key>${xml(k)}</key>\n\t\t<string>${xml(v)}</string>`).join('\n')}
+	</dict>
+	<key>RunAtLoad</key>
+	<true/>
+	<key>KeepAlive</key>
+	<true/>
+	<key>ThrottleInterval</key>
+	<integer>10</integer>
+	<!-- Agent daemons outlive a runner restart; the runner re-adopts them. -->
+	<key>AbandonProcessGroup</key>
+	<true/>
+	<key>StandardOutPath</key>
+	<string>${xml(LOG_FILE)}</string>
+	<key>StandardErrorPath</key>
+	<string>${xml(LOG_FILE)}</string>
+</dict>
+</plist>
+`;
+    const staged = `/Users/Shared/${label}.plist`;
+    return {
+      platform: 'launchd',
+      user,
+      label,
+      target,
+      staged,
+      content,
+      logFile: LOG_FILE,
+      install: [
+        ['launchctl', 'bootout', `system/${label}`], // ignore failure: not loaded yet
+        ['install', '-m', '644', '-o', 'root', '-g', 'wheel', staged, target],
+        ['launchctl', 'bootstrap', 'system', target],
+      ],
+      uninstall: [
+        ['launchctl', 'bootout', `system/${label}`],
+        ['rm', '-f', target],
+      ],
+      statusCommand: ['launchctl', 'print', `system/${label}`],
+    };
+  }
+
+  if (process.platform === 'linux') {
+    const unit = `myvillage-runner-${user}.service`;
+    const target = `/etc/systemd/system/${unit}`;
+    const content = `[Unit]
+Description=MyVillage fleet runner (${user})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${user}
+WorkingDirectory=${home}
+${Object.entries(env).map(([k, v]) => `Environment=${sdQuote(`${k}=${v}`)}`).join('\n')}
+ExecStart=${program.map(sdQuote).join(' ')}
+Restart=always
+RestartSec=10
+# Agent daemons outlive a runner restart; the runner re-adopts them.
+KillMode=process
+StandardOutput=append:${LOG_FILE}
+StandardError=append:${LOG_FILE}
+
+[Install]
+WantedBy=multi-user.target
+`;
+    const staged = path.join('/tmp', unit);
+    return {
+      platform: 'systemd',
+      user,
+      label: unit,
+      target,
+      staged,
+      content,
+      logFile: LOG_FILE,
+      install: [
+        ['install', '-m', '644', '-o', 'root', '-g', 'root', staged, target],
+        ['systemctl', 'daemon-reload'],
+        ['systemctl', 'enable', unit],
+        ['systemctl', 'restart', unit],
+      ],
+      uninstall: [
+        ['systemctl', 'disable', '--now', unit],
+        ['rm', '-f', target],
+        ['systemctl', 'daemon-reload'],
+      ],
+      statusCommand: ['systemctl', 'is-active', unit],
+    };
+  }
+
+  throw new Error(`Installing the runner as a service isn't supported on ${process.platform} yet (macOS and Linux only).`);
+}
+
+/** Write the service file where an admin (including another account) can read it. */
+export function stageRunnerService(spec) {
+  fs.mkdirSync(path.dirname(spec.logFile), { recursive: true });
+  fs.writeFileSync(spec.staged, spec.content, { mode: 0o644 });
+  fs.chmodSync(spec.staged, 0o644);
+  // Keep a private copy next to the runner's state for reference.
+  const copy = path.join(os.homedir(), '.myvillage', 'service', path.basename(spec.target));
+  fs.mkdirSync(path.dirname(copy), { recursive: true });
+  fs.writeFileSync(copy, spec.content, { mode: 0o644 });
+  return copy;
+}
+
+export const shellLine = (argv) => `sudo ${argv.map((a) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`)).join(' ')}`;
+
+/**
+ * Can this account run admin commands? macOS: member of `admin`. Linux: member
+ * of `sudo` or `wheel`, or root. A guess, not a guarantee; sudo still decides.
+ */
+export function canSudo() {
+  if (process.getuid?.() === 0) return true;
+  const res = spawnSync('id', ['-Gn'], { encoding: 'utf8' });
+  const groups = (res.stdout || '').trim().split(/\s+/);
+  return groups.includes(process.platform === 'darwin' ? 'admin' : 'sudo') || groups.includes('wheel');
+}
+
+/** Run each command under sudo with the terminal attached (sudo may prompt). */
+export function runWithSudo(commands, { ignoreFirstFailure = false } = {}) {
+  for (const [i, argv] of commands.entries()) {
+    const res = spawnSync('sudo', argv, { stdio: 'inherit' });
+    if (res.status !== 0 && !(ignoreFirstFailure && i === 0)) {
+      return { ok: false, failed: shellLine(argv) };
+    }
+  }
+  return { ok: true };
+}
+
+/** Installed and running? Never needs sudo. */
+export function runnerServiceStatus(spec) {
+  const installed = fs.existsSync(spec.target);
+  const res = spawnSync(spec.statusCommand[0], spec.statusCommand.slice(1), { encoding: 'utf8' });
+  const out = `${res.stdout || ''}${res.stderr || ''}`;
+  const running = spec.platform === 'launchd'
+    ? res.status === 0 && /\bstate = running\b/.test(out)
+    : res.status === 0 && out.trim() === 'active';
+  return { installed, running };
+}