@clastres/groundcontrol 0.1.0 → 0.1.2

package/README.md

@@ -5,7 +5,7 @@ Your AI agents, in your pocket. Every Claude Code session on this Mac becomes a
 ## Setup
 
 ```sh
-npx groundcontrol
+npx @clastres/groundcontrol
 ```
 
 Scan the QR code it prints with the Ground Control app. Done. No account.

package/daemon.mjs

@@ -15,6 +15,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn, execFile, execSync } from 'node:child_process';
 import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 
 const execFileP = promisify(execFile);
 
@@ -24,12 +26,23 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log(`
   GROUND CONTROL daemon
 
-  Usage: groundcontrol [options]
+  Usage: groundcontrol [command] [options]
 
   Shows the Claude Code sessions on this Mac in the Ground Control iPhone app.
   On first run it generates a pairing key and prints a QR code. Scan it with
   the app and you are connected. No account needed.
 
+  Commands:
+    (none)              Pair and set up the always on daemon (macOS): prints
+                        the QR, then keeps running in the background after
+                        you close the terminal. Starts at login, restarts
+                        by itself. Run it again anytime to update.
+    run                 Run the daemon in this terminal instead
+    qr                  Print the pairing QR code and exit
+    service status      Check the background daemon
+    service install     Set up the background daemon without pairing output
+    service uninstall   Remove the background daemon
+
   Options:
     --relay <url>   Use a custom relay (default: wss://relay.groundcontrol.chat)
     --version       Print version
@@ -41,10 +54,144 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   process.exit(0);
 }
 if (process.argv.includes('--version')) {
-  console.log('0.1.0');
+  console.log('0.1.2');
   process.exit(0);
 }
 
+// ---------- background service (launchd) ----------
+// The daemon installs itself as a launchd LaunchAgent so it needs no open
+// terminal: starts at login, restarts on crash. The service runs from a
+// self contained copy under ~/.groundcontrol/service because the npx cache
+// this file usually executes from is disposable.
+
+const subcommand = process.argv[2];
+const LABEL = 'chat.groundcontrol.daemon';
+const SERVICE_DIR = path.join(os.homedir(), '.groundcontrol', 'service');
+const PLIST_PATH = path.join(os.homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+const LOG_FILE = path.join(os.homedir(), '.groundcontrol', 'daemon.log');
+const THIS_FILE = fs.realpathSync(fileURLToPath(import.meta.url));
+const runsFromServiceDir = THIS_FILE.startsWith(SERVICE_DIR + path.sep);
+
+const launchctl = (args) => {
+  try { return execSync(`launchctl ${args}`, { stdio: 'pipe' }).toString(); }
+  catch (e) { return (e.stdout?.toString() || '') + (e.stderr?.toString() || ''); }
+};
+
+/// Find the root directory of an installed dependency, wherever npm put it.
+function packageDirOf(dep) {
+  let dir = path.dirname(createRequire(THIS_FILE).resolve(dep));
+  while (!(path.basename(dir) === dep && path.basename(path.dirname(dir)) === 'node_modules')) {
+    const parent = path.dirname(dir);
+    if (parent === dir) throw new Error(`cannot locate package directory for ${dep}`);
+    dir = parent;
+  }
+  return dir;
+}
+
+/// Stage a self contained copy of the daemon and register it with launchd.
+/// Returns true when launchd reports the job running.
+function installService() {
+  const uid = process.getuid();
+  launchctl(`bootout gui/${uid}/${LABEL}`);
+  fs.rmSync(SERVICE_DIR, { recursive: true, force: true });
+  fs.mkdirSync(path.join(SERVICE_DIR, 'node_modules'), { recursive: true });
+  fs.copyFileSync(THIS_FILE, path.join(SERVICE_DIR, 'daemon.mjs'));
+  fs.writeFileSync(
+    path.join(SERVICE_DIR, 'package.json'),
+    JSON.stringify({ name: 'groundcontrol-service', private: true, type: 'module' }, null, 2),
+  );
+  for (const dep of ['ws', 'qrcode-terminal']) {
+    fs.cpSync(packageDirOf(dep), path.join(SERVICE_DIR, 'node_modules', dep), { recursive: true });
+  }
+
+  const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  const nodeBin = fs.realpathSync(process.execPath);
+  const plist = `<?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>${esc(nodeBin)}</string>
+        <string>${esc(path.join(SERVICE_DIR, 'daemon.mjs'))}</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>${esc(SERVICE_DIR)}</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ThrottleInterval</key>
+    <integer>5</integer>
+    <key>StandardOutPath</key>
+    <string>${esc(LOG_FILE)}</string>
+    <key>StandardErrorPath</key>
+    <string>${esc(path.join(os.homedir(), '.groundcontrol', 'daemon.err.log'))}</string>
+</dict>
+</plist>
+`;
+  fs.mkdirSync(path.dirname(PLIST_PATH), { recursive: true });
+  fs.writeFileSync(PLIST_PATH, plist);
+  launchctl(`bootstrap gui/${uid} ${PLIST_PATH}`);
+  // launchd reports the job async; give it a moment to reach running state.
+  let out = '';
+  for (let i = 0; i < 5 && !out.includes('state = running'); i++) {
+    execSync('sleep 1');
+    out = launchctl(`print gui/${uid}/${LABEL}`);
+  }
+  return out.includes('state = running');
+}
+
+if (subcommand === 'service') {
+  const action = process.argv[3];
+  if (process.platform !== 'darwin') {
+    console.log('\n  The background service is macOS only for now. Keep the daemon');
+    console.log('  running in a terminal, tmux, or your own process manager.\n');
+    process.exit(1);
+  }
+
+  if (action === 'install') {
+    if (installService()) {
+      console.log('\n  Ground Control daemon is now running in the background.');
+      console.log('  It starts at login and restarts automatically if it stops.\n');
+      console.log(`  Log:       ${LOG_FILE}`);
+      console.log('  Pair:      groundcontrol qr');
+      console.log('  Check:     groundcontrol service status');
+      console.log('  Remove:    groundcontrol service uninstall\n');
+      process.exit(0);
+    }
+    console.log('\n  Install finished but the service is not reporting as running.');
+    console.log(`  Check ${LOG_FILE} and try: launchctl bootstrap gui/${process.getuid()} ${PLIST_PATH}\n`);
+    process.exit(1);
+  }
+
+  if (action === 'uninstall') {
+    launchctl(`bootout gui/${process.getuid()}/${LABEL}`);
+    try { fs.unlinkSync(PLIST_PATH); } catch {}
+    fs.rmSync(SERVICE_DIR, { recursive: true, force: true });
+    console.log('\n  Background service removed. Run the daemon manually with: groundcontrol run\n');
+    process.exit(0);
+  }
+
+  if (action === 'status') {
+    const out = launchctl(`print gui/${process.getuid()}/${LABEL}`);
+    if (out.includes('state = running')) {
+      console.log('\n  Running in the background.');
+    } else if (fs.existsSync(PLIST_PATH)) {
+      console.log('\n  Installed but not running. Reinstall with: groundcontrol service install');
+    } else {
+      console.log('\n  Not installed. Set it up with: groundcontrol service install');
+    }
+    console.log(`  Log: ${LOG_FILE}\n`);
+    process.exit(0);
+  }
+
+  console.log('\n  Usage: groundcontrol service <install|uninstall|status>\n');
+  process.exit(1);
+}
+
 const argRelay = (() => {
   const i = process.argv.indexOf('--relay');
   return i > -1 ? process.argv[i + 1] : null;
@@ -84,6 +231,32 @@ console.log(`  channel: ${CHANNEL}\n`);
 qrcode.generate(pairString, { small: true });
 console.log(`\n  Pairing code (paste into the app):\n\n  ${pairString}\n`);
 
+if (subcommand === 'qr') process.exit(0);
+
+// Default run on a Mac: install the background service so the daemon outlives
+// this terminal, then hand off to it. `groundcontrol run` stays foreground,
+// and the launchd copy in SERVICE_DIR must run itself rather than reinstall.
+if (subcommand !== 'run' && !runsFromServiceDir && process.platform === 'darwin') {
+  console.log('  Setting up the background daemon...');
+  if (installService()) {
+    console.log('\n  Done. The daemon now runs in the background: it starts at');
+    console.log('  login and restarts by itself. You can close this window.\n');
+    console.log('  Scan the QR above with the Ground Control app to pair.');
+    console.log('  Show it again:   npx @clastres/groundcontrol qr');
+    console.log('  Check status:    npx @clastres/groundcontrol service status');
+    console.log('  Turn it off:     npx @clastres/groundcontrol service uninstall\n');
+    process.exit(0);
+  }
+  console.log('\n  Could not set up the background service, running here instead.');
+  console.log('  Keep this window open to stay connected.\n');
+} else if (subcommand === 'run' || process.platform !== 'darwin') {
+  console.log('  Keep this window open to stay connected.');
+  if (process.platform === 'darwin') {
+    console.log('  Prefer background? npx @clastres/groundcontrol service install');
+  }
+  console.log('');
+}
+
 // ---------- crypto: wire format = base64( nonce(12) | ciphertext | tag(16) ) ----------
 
 function seal(obj) {
@@ -414,7 +587,14 @@ function connect() {
     if (str.startsWith('{"sys"')) return;
     try { handleCommand(open(str))?.catch?.(() => {}); } catch (e) { console.log('[daemon] bad message (wrong key?)'); }
   });
-  ws.on('close', () => { console.log('[daemon] relay disconnected, retrying in 3s'); setTimeout(connect, 3000); });
+  ws.on('close', (code) => {
+    if (code === 4001) {
+      console.log('[daemon] another daemon took over this channel, exiting. Run only one copy.');
+      process.exit(0);
+    }
+    console.log('[daemon] relay disconnected, retrying in 3s');
+    setTimeout(connect, 3000);
+  });
   ws.on('error', () => {});
 }
 

package/package.json

@@ -1,16 +1,29 @@
 {
   "name": "@clastres/groundcontrol",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "See and command your Claude Code sessions from your iPhone. Pairs the Ground Control app with the agents running on this Mac, end to end encrypted.",
-  "bin": { "groundcontrol": "./bin/groundcontrol.mjs" },
+  "bin": {
+    "groundcontrol": "./bin/groundcontrol.mjs"
+  },
   "type": "module",
-  "engines": { "node": ">=20" },
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
     "qrcode-terminal": "^0.12.0",
     "ws": "^8.18.0"
   },
-  "keywords": ["claude", "claude-code", "ai", "agents", "cli", "ios", "remote", "monitor"],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "agents",
+    "cli",
+    "ios",
+    "remote",
+    "monitor"
+  ],
   "homepage": "https://groundcontrol.chat",
   "author": "Carlos Lastres",
   "license": "MIT"
-}
+}