@shogo-ai/worker 1.7.4

package/src/lib/device-id.ts

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Stable per-machine UUID stored at ~/.shogo/device-id.
+ *
+ * The cloud uses (workspaceId, deviceId) as a dedupe key — when the
+ * same machine re-runs `shogo login`, the previous device-tagged API
+ * key is auto-revoked so we don't accumulate "ghost" device rows in
+ * the dashboard. Stability across re-logins is what makes this work,
+ * so we persist the id at first generation rather than rolling a new
+ * one each time.
+ */
+import { readFileSync, writeFileSync, existsSync, chmodSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { DEVICE_ID_FILE, ensureHome } from './paths.ts';
+
+export function getOrCreateDeviceId(): string {
+  if (existsSync(DEVICE_ID_FILE)) {
+    const value = readFileSync(DEVICE_ID_FILE, 'utf-8').trim();
+    if (value) return value;
+  }
+  ensureHome();
+  const id = randomUUID();
+  writeFileSync(DEVICE_ID_FILE, id, { mode: 0o600 });
+  chmodSync(DEVICE_ID_FILE, 0o600);
+  return id;
+}

package/src/lib/paths.ts

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Path helpers for the Shogo Worker CLI.
+ * Config, PID, and logs live under ~/.shogo/ on all platforms.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+
+export const HOME_DIR = join(homedir(), '.shogo');
+export const CONFIG_FILE = join(HOME_DIR, 'config.json');
+export const CREDENTIALS_FILE = join(HOME_DIR, 'credentials.json');
+/** Stable per-machine UUID. Generated on first `shogo login`, persisted
+ * verbatim, sent up as `deviceId` so cloud dedupes across re-logins. */
+export const DEVICE_ID_FILE = join(HOME_DIR, 'device-id');
+export const PID_FILE = join(HOME_DIR, 'worker.pid');
+export const LOGS_DIR = join(HOME_DIR, 'logs');
+export const WORKER_LOG = join(LOGS_DIR, 'worker.log');
+export const WORKER_ERR = join(LOGS_DIR, 'worker.err.log');
+
+/** Default install location for the AGPL agent-runtime binary. */
+export const RUNTIME_DIR = join(HOME_DIR, 'runtime');
+export const RUNTIME_BIN = join(RUNTIME_DIR, process.platform === 'win32' ? 'agent-runtime.exe' : 'agent-runtime');
+export const RUNTIME_VERSION_FILE = join(RUNTIME_DIR, 'version.json');
+
+export function ensureHome(): void {
+  mkdirSync(HOME_DIR, { recursive: true, mode: 0o700 });
+  mkdirSync(LOGS_DIR, { recursive: true, mode: 0o700 });
+}
+
+export function ensureRuntimeDir(): void {
+  ensureHome();
+  mkdirSync(RUNTIME_DIR, { recursive: true, mode: 0o700 });
+}

package/src/lib/preflight.ts

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Preflight checks for `shogo worker start --debug`.
+ *
+ * Verifies: runtime version, worker directory, proxy (when set), all three
+ * allowlist hosts (control/tunnel/artifacts), and API-key validity. The
+ * allowlist probes match what `docs/my-machines-networking.md` tells
+ * security teams to open, so if preflight passes we know the firewall is
+ * correctly configured.
+ *
+ * The `criticality` field on each host controls the overall pass/fail:
+ *   - fatal    → must reach. Preflight fails.
+ *   - graceful → should reach, but the worker will start anyway (we only
+ *                warn, because tunnel-direct + artifacts are optional per
+ *                the failure-modes table).
+ */
+import pc from 'picocolors';
+import { existsSync } from 'node:fs';
+import { deriveAllowlist, probeProxy, type ProxyConfig, type AllowlistHost } from './transport.ts';
+
+export interface Check {
+  name: string;
+  /** 'fatal' ⇒ overall preflight fails; 'graceful' ⇒ prints a warning only. */
+  criticality?: 'fatal' | 'graceful';
+  run(): Promise<{ ok: boolean; detail?: string }>;
+}
+
+const DEFAULT_PROBE_TIMEOUT_MS = 5000;
+
+async function probeHealth(url: string, timeoutMs: number): Promise<{ ok: boolean; detail: string }> {
+  try {
+    const ctl = new AbortController();
+    const t = setTimeout(() => ctl.abort(), timeoutMs);
+    const r = await fetch(`${url.replace(/\/$/, '')}/health`, { signal: ctl.signal }).catch(() => null);
+    clearTimeout(t);
+    if (!r) return { ok: false, detail: 'no response (firewall? DNS?)' };
+    return { ok: true, detail: `HTTP ${r.status}` };
+  } catch (err: any) {
+    return { ok: false, detail: err?.message ?? 'unknown error' };
+  }
+}
+
+export const makeChecks = (opts: {
+  cloudUrl: string;
+  apiKey: string;
+  workerDir: string;
+  proxy?: ProxyConfig | null;
+}): Check[] => {
+  const checks: Check[] = [
+    {
+      name: 'Runtime (node >= 20)',
+      criticality: 'fatal',
+      async run() {
+        const [major] = process.versions.node.split('.').map(Number);
+        return (major ?? 0) >= 20
+          ? { ok: true, detail: `node v${process.versions.node}` }
+          : { ok: false, detail: `node v${process.versions.node} — need >=20` };
+      },
+    },
+    {
+      name: 'Worker directory exists',
+      criticality: 'fatal',
+      async run() {
+        return existsSync(opts.workerDir)
+          ? { ok: true, detail: opts.workerDir }
+          : { ok: false, detail: `${opts.workerDir} does not exist` };
+      },
+    },
+  ];
+
+  if (opts.proxy) {
+    checks.push({
+      name: `Proxy reachable (${safeHost(opts.proxy.url)})`,
+      criticality: 'fatal',
+      async run() {
+        return probeProxy(opts.proxy!);
+      },
+    });
+  }
+
+  const allowlist = deriveAllowlist(opts.cloudUrl);
+  for (const entry of allowlist) {
+    checks.push({
+      name: `Reach ${entry.host}${entry.purpose !== 'control' ? pc.dim(` (${entry.purpose})`) : ''}`,
+      criticality: entry.criticality,
+      run: () => probeHealth(entry.url, DEFAULT_PROBE_TIMEOUT_MS),
+    });
+  }
+
+  checks.push({
+    name: 'API key valid',
+    criticality: 'fatal',
+    async run() {
+      try {
+        const r = await fetch(`${opts.cloudUrl}/api/instances/heartbeat`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', 'x-api-key': opts.apiKey },
+          body: JSON.stringify({
+            hostname: 'preflight',
+            name: 'preflight',
+            os: 'preflight',
+            arch: 'preflight',
+            metadata: { preflight: true },
+          }),
+        });
+        if (r.status === 401 || r.status === 403) {
+          return { ok: false, detail: `HTTP ${r.status} — key rejected` };
+        }
+        return r.ok
+          ? { ok: true, detail: `HTTP ${r.status}` }
+          : { ok: false, detail: `HTTP ${r.status}` };
+      } catch (err: any) {
+        return { ok: false, detail: err?.message ?? 'unknown error' };
+      }
+    },
+  });
+
+  return checks;
+};
+
+function safeHost(raw: string): string {
+  try { return new URL(raw).host; } catch { return raw; }
+}
+
+export async function runPreflight(checks: Check[]): Promise<boolean> {
+  console.log(pc.bold('\nShogo Worker — Preflight\n'));
+  let fatalFailed = false;
+  let gracefulFailed = 0;
+  for (const c of checks) {
+    process.stdout.write(`  ${pc.dim('...')} ${c.name}`);
+    const result = await c.run();
+    process.stdout.write('\r');
+    if (result.ok) {
+      console.log(
+        `  ${pc.green('✓')} ${c.name}${result.detail ? pc.dim(` — ${result.detail}`) : ''}`,
+      );
+    } else if (c.criticality === 'graceful') {
+      console.log(
+        `  ${pc.yellow('◦')} ${c.name}${result.detail ? pc.dim(` — ${result.detail}`) : ''}${pc.yellow(' (optional — worker will still start)')}`,
+      );
+      gracefulFailed++;
+    } else {
+      console.log(
+        `  ${pc.red('✗')} ${c.name}${result.detail ? pc.dim(` — ${result.detail}`) : ''}`,
+      );
+      fatalFailed = true;
+    }
+  }
+  if (!fatalFailed && gracefulFailed === 0) {
+    console.log(pc.green('\nAll checks passed.\n'));
+  } else if (!fatalFailed) {
+    console.log(pc.yellow(`\nStarting with ${gracefulFailed} optional host(s) blocked. See docs/my-machines-networking.md.\n`));
+  } else {
+    console.log(pc.red('\nPreflight failed — fix blocking issues before starting.\n'));
+  }
+  return !fatalFailed;
+}

package/src/lib/process-manager.ts

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Manages the lifecycle of the spawned apps/api worker process.
+ *
+ * Single-instance enforcement via a PID file at ~/.shogo/worker.pid:
+ * one worker per machine is intentional — mirrors Cursor's `agent worker`
+ * behaviour so the cloud-side instance identity stays 1:1 with a machine
+ * rather than multiplexing across forks.
+ *
+ * Signal hygiene: callers that hold the CLI process in the foreground
+ * (`shogo worker start --foreground`) should invoke `installShutdownHooks()`
+ * so Ctrl-C / SIGTERM tears down the child and clears the PID file.
+ * The detached codepath doesn't need it — once `child.unref()` runs the
+ * CLI exits and the child owns its own PID file.
+ */
+import { spawn, type ChildProcess } from 'node:child_process';
+import { existsSync, openSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { PID_FILE, WORKER_LOG, WORKER_ERR, ensureHome } from './paths.ts';
+
+export interface SpawnOpts {
+  entry: string;
+  runner: 'bun' | 'node';
+  env: NodeJS.ProcessEnv;
+  cwd: string;
+  detach?: boolean;
+  inheritStdio?: boolean;
+}
+
+export function readPid(): number | null {
+  if (!existsSync(PID_FILE)) return null;
+  const raw = readFileSync(PID_FILE, 'utf-8').trim();
+  const n = parseInt(raw, 10);
+  return Number.isFinite(n) ? n : null;
+}
+
+export function isRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function clearPid(): void {
+  try { unlinkSync(PID_FILE); } catch {}
+}
+
+export function spawnWorker(opts: SpawnOpts): { pid: number; child: ChildProcess } {
+  ensureHome();
+
+  const existingPid = readPid();
+  if (existingPid && isRunning(existingPid)) {
+    throw new Error(`Worker already running (pid=${existingPid}). Run \`shogo worker stop\` first.`);
+  }
+  if (existingPid) clearPid();
+
+  const stdio: ("ignore" | "inherit" | number)[] = opts.inheritStdio
+    ? ['ignore', 'inherit', 'inherit']
+    : ['ignore', openSync(WORKER_LOG, 'a'), openSync(WORKER_ERR, 'a')];
+
+  const child = spawn(opts.runner, [opts.entry], {
+    cwd: opts.cwd,
+    env: opts.env,
+    detached: !!opts.detach,
+    stdio: stdio as any,
+  });
+
+  if (!child.pid) throw new Error('Failed to spawn worker process.');
+  writeFileSync(PID_FILE, String(child.pid), { mode: 0o600 });
+
+  if (opts.detach) child.unref();
+  return { pid: child.pid, child };
+}
+
+/**
+ * Install SIGINT / SIGTERM / exit handlers that forward the signal to the
+ * foreground child and clear the PID file. Idempotent — safe to call twice.
+ *
+ * Only meaningful for foreground runs; detached workers own their own
+ * lifecycle after `child.unref()`.
+ */
+export function installShutdownHooks(child: ChildProcess): void {
+  let shutdownStarted = false;
+  const shutdown = (signal: NodeJS.Signals) => {
+    if (shutdownStarted) return;
+    shutdownStarted = true;
+    try { child.kill(signal); } catch { /* already gone */ }
+    clearPid();
+  };
+
+  process.once('SIGINT', () => shutdown('SIGINT'));
+  process.once('SIGTERM', () => shutdown('SIGTERM'));
+  process.once('SIGHUP', () => shutdown('SIGHUP'));
+  process.once('exit', () => {
+    if (!shutdownStarted) clearPid();
+  });
+
+  // Propagate child's exit to this process for foreground runs.
+  child.on('exit', (code, signal) => {
+    clearPid();
+    if (signal) process.exit(128 + (signalToInt(signal) ?? 0));
+    process.exit(code ?? 0);
+  });
+}
+
+function signalToInt(signal: NodeJS.Signals): number | undefined {
+  const map: Record<string, number> = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGTERM: 15 };
+  return map[signal];
+}
+
+export function stopWorker(signal: NodeJS.Signals = 'SIGTERM'): { killedPid: number | null } {
+  const pid = readPid();
+  if (!pid) return { killedPid: null };
+  if (!isRunning(pid)) {
+    clearPid();
+    return { killedPid: null };
+  }
+  try { process.kill(pid, signal); } catch {}
+  clearPid();
+  return { killedPid: pid };
+}