@shogo-ai/worker 1.7.4

package/src/commands/runtime.ts

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * `shogo runtime` subcommands — manage the locally-installed
+ * agent-runtime binary that the worker spawns per-project.
+ *
+ *   shogo runtime install [--channel <stable|beta|nightly>] [--version <x>] [--force] [--base-url <url>]
+ *   shogo runtime version
+ *   shogo runtime where
+ *   shogo runtime update [--channel <...>]
+ *
+ * The runtime is AGPL-3.0-or-later (see packages/agent-runtime). The
+ * worker (MIT) installs it as a separate on-disk binary and spawns it
+ * as a child process — no library link.
+ */
+import pc from 'picocolors';
+import {
+  type Channel,
+  detectTarget,
+  getRuntimePaths,
+  installRuntime,
+  readInstalledVersion,
+} from '../lib/runtime-install.ts';
+import { resolveRuntime, formatMissingRuntimeError } from '../lib/runtime-resolver.ts';
+
+interface InstallFlags {
+  channel?: Channel;
+  version?: string;
+  baseUrl?: string;
+  force?: boolean;
+}
+
+export async function runRuntimeInstall(flags: InstallFlags = {}): Promise<void> {
+  const result = await installRuntime({
+    channel: flags.channel,
+    version: flags.version,
+    baseUrl: flags.baseUrl,
+    force: flags.force,
+  });
+  console.log();
+  console.log(pc.green('✓'), `agent-runtime ${pc.bold(result.version)} installed (${result.target})`);
+  console.log(`  ${pc.dim('path:    ')} ${result.binPath}`);
+  console.log(`  ${pc.dim('source:  ')} ${result.source}`);
+  console.log(`  ${pc.dim('sha256:  ')} ${result.sha256}`);
+  console.log(`  ${pc.dim('channel: ')} ${result.channel}`);
+}
+
+export function runRuntimeVersion(): void {
+  const installed = readInstalledVersion();
+  if (!installed) {
+    console.log(pc.yellow('No agent-runtime installed.'));
+    console.log(`Run ${pc.cyan('shogo runtime install')} to download the latest.`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`${pc.bold('agent-runtime')} ${installed.version}`);
+  console.log(`  ${pc.dim('target:      ')} ${installed.target}`);
+  console.log(`  ${pc.dim('channel:     ')} ${installed.channel}`);
+  console.log(`  ${pc.dim('installed at:')} ${installed.installedAt}`);
+  console.log(`  ${pc.dim('source:      ')} ${installed.source}`);
+}
+
+export function runRuntimeWhere(): void {
+  const resolved = resolveRuntime();
+  const paths = getRuntimePaths();
+  if (!resolved) {
+    console.log(pc.yellow('agent-runtime binary not found on this machine.'));
+    console.log();
+    console.log(pc.dim('Default install path:'), paths.runtimeBin);
+    console.log();
+    console.log(formatMissingRuntimeError());
+    process.exitCode = 1;
+    return;
+  }
+  console.log(resolved.path);
+  if (process.env.SHOGO_DEBUG || process.env.VERBOSE) {
+    console.log(pc.dim(`  (resolved via: ${resolved.source})`));
+  }
+}
+
+interface UpdateFlags {
+  channel?: Channel;
+  baseUrl?: string;
+}
+
+export async function runRuntimeUpdate(flags: UpdateFlags = {}): Promise<void> {
+  const installed = readInstalledVersion();
+  const targetChannel = flags.channel ?? installed?.channel ?? 'stable';
+  if (installed) {
+    console.log(
+      `${pc.dim('current:')} ${installed.version} (${installed.target}, ${installed.channel})`,
+    );
+  } else {
+    console.log(pc.dim('No existing install — installing fresh...'));
+  }
+  // installRuntime resolves the latest in-channel version on its own;
+  // pass force:true so we always reinstall when the user explicitly
+  // ran `update` (matches `npm update` / `brew upgrade` muscle memory).
+  await runRuntimeInstall({ channel: targetChannel, baseUrl: flags.baseUrl, force: true });
+}
+
+export function getDetectedTarget(): string {
+  return detectTarget();
+}

package/src/commands/start.ts

@@ -0,0 +1,252 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * `shogo worker start` — pair this machine with Shogo Cloud.
+ *
+ * Two execution modes:
+ *
+ *   --foreground   Run the tunnel + runtime-manager in this process,
+ *                  log to stdout, exit on SIGINT/SIGTERM. This is the
+ *                  shape used inside the spawned detached child below
+ *                  (so we never duplicate the wire-up code) and the
+ *                  shape `shogo runtime install && shogo worker start --foreground`
+ *                  uses for CI / `systemd --user` setups.
+ *
+ *   (default)      Detach: re-spawn `shogo worker start --foreground`
+ *                  as a background process via `spawnWorker`, write
+ *                  the pid file, return immediately. The PID file is
+ *                  what `shogo worker stop / status / logs` poll.
+ *
+ * Foreground path responsibilities (in order):
+ *   1. Resolve config (api key, cloud url, name, worker dir).
+ *   2. Apply HTTPS_PROXY into the process env so outbound fetch picks
+ *      it up via Node/Bun's automatic dispatcher.
+ *   3. Locate the AGPL agent-runtime binary on disk; abort with a
+ *      friendly install hint if missing.
+ *   4. Optional --debug preflight (proxy reachability + cloud ping).
+ *   5. Construct WorkerRuntimeManager with cloud-routed default spawn
+ *      config (every per-project runtime gets cloudUrl + apiKey).
+ *   6. Construct WorkerTunnel with the runtime manager as its resolver.
+ *   7. Install signal handlers (SIGINT / SIGTERM / SIGHUP) that stop
+ *      the tunnel, stop all per-project runtimes, then exit.
+ *   8. Wait forever; the cloud drives traffic in via the tunnel WS.
+ */
+import pc from 'picocolors';
+import { existsSync } from 'node:fs';
+import { resolveConfig } from '../lib/config.ts';
+import { spawnWorker } from '../lib/process-manager.ts';
+import { makeChecks, runPreflight } from '../lib/preflight.ts';
+import { resolveProxy, applyProxyToEnv } from '../lib/transport.ts';
+import { resolveRuntime, formatMissingRuntimeError } from '../lib/runtime-resolver.ts';
+import { WorkerRuntimeManager, type ProjectSpawnConfig } from '../lib/runtime-manager.ts';
+import { WorkerTunnel } from '../lib/tunnel.ts';
+
+export interface StartFlags {
+  name?: string;
+  workerDir?: string;
+  apiKey?: string;
+  cloudUrl?: string;
+  port?: string;
+  proxy?: string;
+  project?: string;
+  runtimeBin?: string;
+  debug?: boolean;
+  foreground?: boolean;
+}
+
+export async function runStart(flags: StartFlags): Promise<void> {
+  const cfg = resolveConfig({
+    name: flags.name,
+    workerDir: flags.workerDir,
+    apiKey: flags.apiKey,
+    cloudUrl: flags.cloudUrl,
+    port: flags.port ? parseInt(flags.port, 10) : undefined,
+  });
+
+  const proxy = resolveProxy(flags.proxy);
+
+  if (!flags.foreground) {
+    // Detached default — re-launch this same CLI with --foreground in
+    // a child process so the user gets their shell back. The actual
+    // tunnel + runtime-manager work happens in `runStartForeground()`
+    // below in the spawned process.
+    return runDetached({ cfg, proxy, flags });
+  }
+
+  // Foreground path: surface a friendly missing-binary error BEFORE
+  // we open the tunnel — the binary is always required and it's a
+  // much better failure mode to tell the user up front than to fail
+  // on the first inbound /agent/* request.
+  const resolved = resolveRuntime({ flag: flags.runtimeBin });
+  if (!resolved) {
+    console.error(pc.red(formatMissingRuntimeError({ flag: flags.runtimeBin })));
+    process.exit(1);
+  }
+
+  applyProxyToEnv(process.env, proxy);
+
+  if (flags.debug) {
+    const ok = await runPreflight(
+      makeChecks({
+        cloudUrl: cfg.cloudUrl,
+        apiKey: cfg.apiKey,
+        workerDir: cfg.workerDir,
+        proxy,
+      }),
+    );
+    if (!ok) process.exit(1);
+  }
+
+  console.log(pc.bold('\nShogo Worker — Starting'));
+  console.log(pc.dim('  name        ') + cfg.name);
+  console.log(pc.dim('  worker-dir  ') + cfg.workerDir);
+  console.log(pc.dim('  cloud       ') + cfg.cloudUrl);
+  console.log(pc.dim('  runtime     ') + `${resolved.path} ${pc.dim(`(via ${resolved.source})`)}`);
+  if (flags.project) console.log(pc.dim('  project     ') + flags.project);
+  if (proxy) {
+    console.log(pc.dim('  proxy       ') + `${proxy.url} ${pc.dim(`(from ${proxy.source})`)}`);
+  }
+  console.log('');
+
+  const defaultSpawnConfig: ProjectSpawnConfig = {
+    cloudUrl: cfg.cloudUrl,
+    apiKey: cfg.apiKey,
+    // No projectDir on the worker — the agent-runtime fetches workspace
+    // state from the cloud using its API key. CWD defaults to a tmp
+    // dir per `WorkerRuntimeManager.resolveCwd()`.
+  };
+
+  const runtimeManager = new WorkerRuntimeManager({
+    runtimeBin: flags.runtimeBin,
+    defaultSpawnConfig,
+  });
+
+  // Eagerly resolve so the cached `resolved` is reused — also exits early
+  // if a race deleted the binary between the check above and now.
+  if (!runtimeManager.resolveBinary()) {
+    console.error(pc.red(formatMissingRuntimeError({ flag: flags.runtimeBin })));
+    process.exit(1);
+  }
+
+  const tunnel = new WorkerTunnel({
+    apiKey: cfg.apiKey,
+    cloudUrl: cfg.cloudUrl,
+    name: cfg.name,
+    kind: 'cli-worker',
+    resolver: runtimeManager,
+    onAuthRevoked: (reason) => {
+      console.error(pc.red(`✗ Cloud auth revoked: ${reason}`));
+      console.error(pc.dim(`  Run \`shogo login\` to re-authenticate; this worker will keep polling at the auth-failure backoff until then.`));
+    },
+  });
+
+  let shuttingDown = false;
+  const shutdown = async (signal: NodeJS.Signals) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    console.log(pc.dim(`\nReceived ${signal} — shutting down...`));
+    try { tunnel.stop(); } catch { /* already stopped */ }
+    try { await runtimeManager.stopAll(); } catch (err: any) {
+      console.warn(pc.yellow(`stopAll: ${err?.message ?? err}`));
+    }
+    process.exit(0);
+  };
+  process.once('SIGINT', () => void shutdown('SIGINT'));
+  process.once('SIGTERM', () => void shutdown('SIGTERM'));
+  process.once('SIGHUP', () => void shutdown('SIGHUP'));
+
+  tunnel.start();
+  console.log(pc.green('✓ Worker running. Ctrl-C to stop.'));
+
+  // Pin the foreground process. The shutdown handler above will
+  // process.exit() when the user terminates.
+  await new Promise<void>(() => { /* never resolves */ });
+}
+
+interface DetachedOpts {
+  cfg: { apiKey: string; cloudUrl: string; name: string; workerDir: string; port: number };
+  proxy: ReturnType<typeof resolveProxy>;
+  flags: StartFlags;
+}
+
+/**
+ * Detach implementation: figure out the right argv to re-invoke this
+ * CLI with `worker start --foreground`, spawn it via `spawnWorker`
+ * (which writes the PID file + redirects stdio to ~/.shogo/logs/),
+ * then exit. The child becomes the long-running worker.
+ */
+function runDetached({ cfg, proxy, flags }: DetachedOpts): void {
+  const { entry, runner } = resolveSelfEntry();
+
+  const env: NodeJS.ProcessEnv = applyProxyToEnv(
+    {
+      ...process.env,
+      SHOGO_API_KEY: cfg.apiKey,
+      SHOGO_CLOUD_URL: cfg.cloudUrl,
+      SHOGO_INSTANCE_NAME: cfg.name,
+      SHOGO_WORKER_DIR: cfg.workerDir,
+      SHOGO_LOCAL_MODE: 'true',
+      PORT: String(cfg.port),
+    },
+    proxy,
+  );
+
+  // We pass `--foreground` to the spawned child so it takes the
+  // foreground branch above. Anything else the user passed is also
+  // forwarded so e.g. `--project <id>` survives detachment.
+  const argv = buildChildArgv(flags);
+
+  const { pid } = spawnWorker({
+    entry,
+    runner,
+    env: { ...env, SHOGO_DETACHED_ARGS: argv.join(' ') },
+    cwd: cfg.workerDir,
+    detach: true,
+    inheritStdio: false,
+  });
+
+  console.log(pc.bold('\nShogo Worker — Started'));
+  console.log(pc.dim('  pid:  ') + pid);
+  console.log(pc.dim('  name: ') + cfg.name);
+  console.log(pc.dim('  logs: ') + '~/.shogo/logs/worker.log');
+  console.log(pc.dim('  stop: ') + 'shogo worker stop');
+}
+
+function buildChildArgv(flags: StartFlags): string[] {
+  const out: string[] = ['worker', 'start', '--foreground'];
+  if (flags.name) out.push('--name', flags.name);
+  if (flags.workerDir) out.push('--worker-dir', flags.workerDir);
+  if (flags.apiKey) out.push('--api-key', flags.apiKey);
+  if (flags.cloudUrl) out.push('--cloud-url', flags.cloudUrl);
+  if (flags.port) out.push('--port', flags.port);
+  if (flags.proxy) out.push('--proxy', flags.proxy);
+  if (flags.project) out.push('--project', flags.project);
+  if (flags.runtimeBin) out.push('--runtime-bin', flags.runtimeBin);
+  if (flags.debug) out.push('--debug');
+  return out;
+}
+
+/**
+ * Find the entry point + runner the detached child should use.
+ *
+ * Priority:
+ *   1. The currently-executing argv[1] if it's an existing file (eg.
+ *      a globally installed `shogo` bin or `bun src/cli.ts` in the
+ *      monorepo).
+ *   2. The compiled binary at /usr/local/bin/shogo on PATH (best-effort).
+ *   3. The bin shim shipped with this package.
+ */
+function resolveSelfEntry(): { entry: string; runner: 'bun' | 'node' } {
+  // process.execPath is the bun/node binary; argv[1] is the script.
+  const execPath = process.execPath;
+  const isBun = /\bbun(?:-[^/\\]*)?$/.test(execPath) || typeof (globalThis as any).Bun !== 'undefined';
+  const argvScript = process.argv[1];
+  if (argvScript && existsSync(argvScript)) {
+    return { entry: argvScript, runner: isBun ? 'bun' : 'node' };
+  }
+  // Fallback: the compiled bin shim shipped with the package.
+  // Resolved relative to this file via import.meta.url so it works
+  // both in monorepo and when published.
+  const shim = new URL('../../bin/shogo.mjs', import.meta.url).pathname;
+  return { entry: shim, runner: isBun ? 'bun' : 'node' };
+}

package/src/commands/status.ts

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+import pc from 'picocolors';
+import { readPid, isRunning } from '../lib/process-manager.ts';
+import { loadConfig } from '../lib/config.ts';
+
+export async function runStatus(): Promise<void> {
+  const pid = readPid();
+  if (!pid) {
+    console.log(pc.yellow('● stopped') + pc.dim(' (no pid file)'));
+    return;
+  }
+  if (!isRunning(pid)) {
+    console.log(pc.red('● dead') + pc.dim(` (stale pid ${pid})`));
+    return;
+  }
+  const cfg = loadConfig();
+  console.log(pc.green('● running') + pc.dim(` (pid ${pid})`));
+  if (cfg.name) console.log(pc.dim(`  name:  `) + cfg.name);
+  if (cfg.cloudUrl) console.log(pc.dim(`  cloud: `) + cfg.cloudUrl);
+  if (cfg.workerDir) console.log(pc.dim(`  dir:   `) + cfg.workerDir);
+}

package/src/commands/stop.ts

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+import pc from 'picocolors';
+import { stopWorker } from '../lib/process-manager.ts';
+
+export async function runStop(): Promise<void> {
+  const { killedPid } = stopWorker('SIGTERM');
+  if (killedPid === null) {
+    console.log(pc.dim('No worker running.'));
+    return;
+  }
+  console.log(pc.green(`✓ Worker stopped (pid=${killedPid}).`));
+}

package/src/lib/__tests__/cloud-login.test.ts

@@ -0,0 +1,218 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+import { describe, it, expect } from 'bun:test';
+import { runCloudLogin, CloudLoginError } from '../cloud-login.ts';
+
+/**
+ * Drive `runCloudLogin` against a scripted fetch implementation so we
+ * can exercise the start → poll → approved happy path plus all four
+ * documented terminal states (denied / expired / state-mismatch via
+ * malformed responses / network error).
+ *
+ * The CLI client should:
+ *   - never auto-open a browser when openBrowser:false
+ *   - poll until status='approved' or terminal state
+ *   - return the key + email + workspace from the approved poll exactly
+ *     once and not call any further endpoints
+ *   - throw CloudLoginError with the right `kind` for each failure mode
+ */
+
+function scripted(handlers: Array<(url: string) => Response | Promise<Response>>) {
+  let i = 0;
+  const fetchImpl = async (input: RequestInfo | URL, _init?: RequestInit) => {
+    const url = typeof input === 'string' ? input : input.toString();
+    if (i >= handlers.length) {
+      throw new Error(`scripted fetch ran out of handlers at request #${i + 1} (${url})`);
+    }
+    return handlers[i++](url);
+  };
+  return { fetchImpl: fetchImpl as unknown as typeof fetch, calls: () => i };
+}
+
+function jsonResponse(body: unknown, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+describe('runCloudLogin', () => {
+  it('returns the minted key on the second poll (start → pending → approved)', async () => {
+    const { fetchImpl } = scripted([
+      (url) => {
+        expect(url).toEndWith('/api/cli/login/start');
+        return jsonResponse({
+          ok: true,
+          state: 'abcdef0123456789',
+          userCode: '456789',
+          authUrl: 'https://cloud.example.com/auth/cli-link?state=abcdef0123456789',
+          expiresInMs: 60_000,
+          pollIntervalMs: 1_000,
+        });
+      },
+      (url) => {
+        expect(url).toContain('/api/cli/login/poll?state=abcdef0123456789');
+        return jsonResponse({ ok: true, status: 'pending' });
+      },
+      (url) => {
+        expect(url).toContain('/api/cli/login/poll?state=abcdef0123456789');
+        return jsonResponse({
+          ok: true,
+          status: 'approved',
+          key: 'shogo_sk_test_key_123',
+          email: 'user@example.com',
+          workspace: 'My Workspace',
+          deviceId: 'dev-abc',
+        });
+      },
+    ]);
+
+    const result = await runCloudLogin({
+      cloudUrl: 'https://cloud.example.com',
+      deviceId: 'dev-abc',
+      openBrowser: false,
+      pollIntervalMs: 1, // tighten so the test runs fast
+      log: () => { /* silence */ },
+      fetchImpl,
+    });
+
+    expect(result.key).toBe('shogo_sk_test_key_123');
+    expect(result.email).toBe('user@example.com');
+    expect(result.workspace).toBe('My Workspace');
+    expect(result.deviceId).toBe('dev-abc');
+  });
+
+  it('throws CloudLoginError(kind="denied") when the user clicks Cancel', async () => {
+    const { fetchImpl } = scripted([
+      () =>
+        jsonResponse({
+          ok: true,
+          state: 's',
+          userCode: 'XXXXXX',
+          authUrl: 'https://cloud.example.com/auth/cli-link?state=s',
+          expiresInMs: 60_000,
+          pollIntervalMs: 1,
+        }),
+      () => jsonResponse({ ok: true, status: 'denied' }),
+    ]);
+
+    await expect(
+      runCloudLogin({
+        cloudUrl: 'https://cloud.example.com',
+        deviceId: 'dev-abc',
+        openBrowser: false,
+        pollIntervalMs: 1,
+        log: () => { /* silence */ },
+        fetchImpl,
+      }),
+    ).rejects.toBeInstanceOf(CloudLoginError);
+  });
+
+  it('throws CloudLoginError(kind="expired") when the cloud says expired', async () => {
+    const { fetchImpl } = scripted([
+      () =>
+        jsonResponse({
+          ok: true,
+          state: 's',
+          userCode: 'XXXXXX',
+          authUrl: 'https://cloud.example.com/auth/cli-link?state=s',
+          expiresInMs: 60_000,
+          pollIntervalMs: 1,
+        }),
+      () => jsonResponse({ ok: true, status: 'expired' }),
+    ]);
+
+    try {
+      await runCloudLogin({
+        cloudUrl: 'https://cloud.example.com',
+        deviceId: 'dev-abc',
+        openBrowser: false,
+        pollIntervalMs: 1,
+        log: () => { /* silence */ },
+        fetchImpl,
+      });
+      throw new Error('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(CloudLoginError);
+      expect((err as CloudLoginError).kind).toBe('expired');
+    }
+  });
+
+  it('respects abortSignal and throws cancelled', async () => {
+    const ac = new AbortController();
+    const { fetchImpl } = scripted([
+      () =>
+        jsonResponse({
+          ok: true,
+          state: 's',
+          userCode: 'XXXXXX',
+          authUrl: 'https://cloud.example.com/auth/cli-link?state=s',
+          expiresInMs: 60_000,
+          pollIntervalMs: 50,
+        }),
+      () => {
+        // Abort right before the next sleep so the wait raises cancelled.
+        ac.abort();
+        return jsonResponse({ ok: true, status: 'pending' });
+      },
+    ]);
+
+    try {
+      await runCloudLogin({
+        cloudUrl: 'https://cloud.example.com',
+        deviceId: 'dev-abc',
+        openBrowser: false,
+        pollIntervalMs: 50,
+        log: () => { /* silence */ },
+        fetchImpl,
+        abortSignal: ac.signal,
+      });
+      throw new Error('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(CloudLoginError);
+      expect((err as CloudLoginError).kind).toBe('cancelled');
+    }
+  });
+
+  it('throws transport when start endpoint is unreachable', async () => {
+    const fetchImpl = (async () => {
+      throw new Error('ECONNREFUSED');
+    }) as unknown as typeof fetch;
+
+    try {
+      await runCloudLogin({
+        cloudUrl: 'https://cloud.example.com',
+        deviceId: 'dev-abc',
+        openBrowser: false,
+        pollIntervalMs: 1,
+        log: () => { /* silence */ },
+        fetchImpl,
+      });
+      throw new Error('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(CloudLoginError);
+      expect((err as CloudLoginError).kind).toBe('transport');
+    }
+  });
+
+  it('throws transport when start returns malformed body', async () => {
+    const { fetchImpl } = scripted([
+      () => jsonResponse({ ok: false, error: 'bad request' }, 400),
+    ]);
+
+    try {
+      await runCloudLogin({
+        cloudUrl: 'https://cloud.example.com',
+        deviceId: 'dev-abc',
+        openBrowser: false,
+        pollIntervalMs: 1,
+        log: () => { /* silence */ },
+        fetchImpl,
+      });
+      throw new Error('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(CloudLoginError);
+      expect((err as CloudLoginError).kind).toBe('transport');
+    }
+  });
+});