@shogo-ai/worker 1.7.4

package/src/lib/__tests__/config.test.ts

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+import { describe, it, expect, beforeEach, afterEach, mock } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync, statSync, existsSync, readFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * The config/credentials store reads HOME at module-load time. To test
+ * different home dirs we mock `paths.ts` per-test so config.ts picks up
+ * a tmpdir-rooted CONFIG_FILE / HOME_DIR pair without us having to
+ * mutate process.env.HOME (which is racy across the rest of the suite).
+ */
+
+let tmp: string;
+
+function setupTmpHome(): string {
+  tmp = mkdtempSync(join(tmpdir(), 'shogo-config-'));
+  const homeDir = join(tmp, '.shogo');
+  const configFile = join(homeDir, 'config.json');
+  mock.module('../paths.ts', () => ({
+    HOME_DIR: homeDir,
+    CONFIG_FILE: configFile,
+    CREDENTIALS_FILE: join(homeDir, 'credentials.json'),
+    DEVICE_ID_FILE: join(homeDir, 'device-id'),
+    PID_FILE: join(homeDir, 'worker.pid'),
+    LOGS_DIR: join(homeDir, 'logs'),
+    WORKER_LOG: join(homeDir, 'logs', 'worker.log'),
+    WORKER_ERR: join(homeDir, 'logs', 'worker.err.log'),
+    RUNTIME_DIR: join(homeDir, 'runtime'),
+    RUNTIME_BIN: join(homeDir, 'runtime', 'agent-runtime'),
+    RUNTIME_VERSION_FILE: join(homeDir, 'runtime', 'version.json'),
+    ensureHome: () => {
+      mkdirSync(homeDir, { recursive: true, mode: 0o700 });
+      mkdirSync(join(homeDir, 'logs'), { recursive: true, mode: 0o700 });
+    },
+    ensureRuntimeDir: () => {
+      mkdirSync(join(homeDir, 'runtime'), { recursive: true, mode: 0o700 });
+    },
+  }));
+  return configFile;
+}
+
+describe('config: load + save round-trip', () => {
+  let configFile: string;
+  beforeEach(() => {
+    configFile = setupTmpHome();
+  });
+  afterEach(() => {
+    mock.restore();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('loadConfig returns {} when no file exists', async () => {
+    const { loadConfig } = await import('../config.ts');
+    expect(loadConfig()).toEqual({});
+  });
+
+  it('saveConfig writes JSON with mode 0600', async () => {
+    const { saveConfig, loadConfig } = await import('../config.ts');
+    saveConfig({ apiKey: 'shogo_sk_test', cloudUrl: 'https://example.com' });
+
+    expect(existsSync(configFile)).toBe(true);
+    const parsed = JSON.parse(readFileSync(configFile, 'utf-8'));
+    expect(parsed.apiKey).toBe('shogo_sk_test');
+    expect(parsed.cloudUrl).toBe('https://example.com');
+    if (process.platform !== 'win32') {
+      const st = statSync(configFile);
+      expect(st.mode & 0o077).toBe(0);
+    }
+    expect(loadConfig().apiKey).toBe('shogo_sk_test');
+  });
+
+  it('loadConfig throws on corrupt JSON', async () => {
+    mkdirSync(join(tmp, '.shogo'), { recursive: true });
+    writeFileSync(configFile, '{not json');
+    const { loadConfig } = await import('../config.ts');
+    expect(() => loadConfig()).toThrow(/Corrupt config/);
+  });
+
+  it('mergeConfig prefers override over base, drops undefined', async () => {
+    const { mergeConfig } = await import('../config.ts');
+    expect(
+      mergeConfig({ apiKey: 'a', cloudUrl: 'old' }, { cloudUrl: 'new', name: undefined }),
+    ).toEqual({ apiKey: 'a', cloudUrl: 'new' });
+  });
+});
+
+describe('config: resolveConfig precedence', () => {
+  let prevEnvKey: string | undefined;
+
+  beforeEach(() => {
+    setupTmpHome();
+    prevEnvKey = process.env.SHOGO_API_KEY;
+    delete process.env.SHOGO_API_KEY;
+  });
+  afterEach(() => {
+    mock.restore();
+    if (prevEnvKey === undefined) delete process.env.SHOGO_API_KEY;
+    else process.env.SHOGO_API_KEY = prevEnvKey;
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('throws when no API key resolves anywhere', async () => {
+    const { resolveConfig } = await import('../config.ts');
+    expect(() => resolveConfig()).toThrow(/No API key/);
+  });
+
+  it('reads API key from explicit override (highest precedence)', async () => {
+    const { resolveConfig, saveConfig } = await import('../config.ts');
+    saveConfig({ apiKey: 'shogo_sk_file' });
+    process.env.SHOGO_API_KEY = 'shogo_sk_env';
+    expect(resolveConfig({ apiKey: 'shogo_sk_override' }).apiKey).toBe('shogo_sk_override');
+  });
+
+  it('falls back to env var when no override is given', async () => {
+    const { resolveConfig, saveConfig } = await import('../config.ts');
+    saveConfig({ apiKey: 'shogo_sk_file' });
+    process.env.SHOGO_API_KEY = 'shogo_sk_env';
+    expect(resolveConfig().apiKey).toBe('shogo_sk_env');
+  });
+
+  it('falls back to file when no override or env is set', async () => {
+    const { resolveConfig, saveConfig } = await import('../config.ts');
+    saveConfig({ apiKey: 'shogo_sk_file' });
+    expect(resolveConfig().apiKey).toBe('shogo_sk_file');
+  });
+
+  it('fills defaults for cloudUrl + port', async () => {
+    const { resolveConfig, saveConfig } = await import('../config.ts');
+    saveConfig({ apiKey: 'shogo_sk_file' });
+    const cfg = resolveConfig();
+    expect(cfg.cloudUrl).toBe('https://studio.shogo.ai');
+    expect(cfg.port).toBe(8002);
+  });
+});

package/src/lib/__tests__/runtime-resolver.test.ts

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resolveRuntime, formatMissingRuntimeError } from '../runtime-resolver.ts';
+
+/**
+ * Resolver priority chain:
+ *   1. --runtime-bin flag
+ *   2. SHOGO_AGENT_RUNTIME_BIN env var
+ *   3. ~/.shogo/runtime/agent-runtime (the "home" path; we can't easily
+ *      override that without mocking paths.ts, so we just assert it's
+ *      consulted via the missing-binary message).
+ *   4. PATH search for the system bin name
+ *
+ * These tests construct a tmpdir with a fake executable and exercise the
+ * first two + the PATH branch directly.
+ */
+
+describe('runtime-resolver: resolveRuntime', () => {
+  let tmp: string;
+  let realBin: string;
+  let dummyDir: string;
+  let dummyBin: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'shogo-resolver-'));
+    realBin = join(tmp, 'fake-runtime');
+    writeFileSync(realBin, '#!/bin/sh\necho hi\n');
+    chmodSync(realBin, 0o755);
+
+    dummyDir = join(tmp, 'pathdir');
+    mkdirSync(dummyDir);
+    dummyBin = join(dummyDir, 'shogo-agent-runtime');
+    writeFileSync(dummyBin, '#!/bin/sh\necho hi\n');
+    chmodSync(dummyBin, 0o755);
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('--runtime-bin flag wins when set and the file is executable', () => {
+    const result = resolveRuntime({ flag: realBin, env: { PATH: '' } });
+    expect(result?.path).toBe(realBin);
+    expect(result?.source).toBe('flag');
+  });
+
+  it('falls through when the flag points at a non-existent path', () => {
+    const result = resolveRuntime({
+      flag: join(tmp, 'does-not-exist'),
+      env: { SHOGO_AGENT_RUNTIME_BIN: realBin, PATH: '' },
+    });
+    expect(result?.path).toBe(realBin);
+    expect(result?.source).toBe('env');
+  });
+
+  it('falls through when the flag points at a non-executable file', () => {
+    const nonExec = join(tmp, 'non-exec');
+    writeFileSync(nonExec, 'plain text');
+    chmodSync(nonExec, 0o644);
+
+    const result = resolveRuntime({
+      flag: nonExec,
+      env: { SHOGO_AGENT_RUNTIME_BIN: realBin, PATH: '' },
+    });
+    expect(result?.source).toBe('env');
+  });
+
+  it('SHOGO_AGENT_RUNTIME_BIN wins when no flag is set', () => {
+    const result = resolveRuntime({ env: { SHOGO_AGENT_RUNTIME_BIN: realBin, PATH: '' } });
+    expect(result?.path).toBe(realBin);
+    expect(result?.source).toBe('env');
+  });
+
+  it('falls back to PATH when flag/env/home are all unavailable', () => {
+    const result = resolveRuntime({
+      env: { PATH: dummyDir },
+      systemBinName: 'shogo-agent-runtime',
+    });
+    expect(result?.path).toBe(dummyBin);
+    expect(result?.source).toBe('path');
+  });
+
+  it('returns null when nothing resolves', () => {
+    const result = resolveRuntime({
+      env: { PATH: tmp /* tmp has no bin matching the system name */ },
+      systemBinName: 'definitely-not-on-path-xyz',
+    });
+    expect(result).toBeNull();
+  });
+});
+
+describe('runtime-resolver: formatMissingRuntimeError', () => {
+  it('mentions the flag if one was passed', () => {
+    const msg = formatMissingRuntimeError({ flag: '/tmp/foo' });
+    expect(msg).toContain('--runtime-bin /tmp/foo');
+  });
+
+  it('mentions SHOGO_AGENT_RUNTIME_BIN when set', () => {
+    const msg = formatMissingRuntimeError({ env: { SHOGO_AGENT_RUNTIME_BIN: '/opt/foo' } });
+    expect(msg).toContain('SHOGO_AGENT_RUNTIME_BIN');
+    expect(msg).toContain('/opt/foo');
+  });
+
+  it('always includes the install hint', () => {
+    const msg = formatMissingRuntimeError();
+    expect(msg).toContain('shogo runtime install');
+  });
+});

package/src/lib/api-discovery.ts

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Finds the apps/api entry to spawn as the tunnel host.
+ *
+ * In the monorepo (dev), we resolve the workspace sibling.
+ * When published, the worker ships a bundled apps/api copy at ./dist/api/entry.js.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+interface Resolved {
+  entry: string;
+  runner: 'bun' | 'node';
+  mode: 'monorepo' | 'bundled';
+}
+
+export function findApiEntry(): Resolved {
+  const packageRoot = resolve(__dirname, '..', '..');
+  const monorepoRoot = resolve(packageRoot, '..', '..');
+  const monorepoEntry = join(monorepoRoot, 'apps', 'api', 'src', 'entry.ts');
+  const bundledEntry = join(packageRoot, 'dist', 'api', 'entry.js');
+
+  if (existsSync(bundledEntry)) {
+    return { entry: bundledEntry, runner: 'node', mode: 'bundled' };
+  }
+  if (existsSync(monorepoEntry)) {
+    return { entry: monorepoEntry, runner: 'bun', mode: 'monorepo' };
+  }
+  throw new Error(
+    `Cannot locate apps/api entry. Looked in:\n  ${bundledEntry}\n  ${monorepoEntry}`,
+  );
+}

package/src/lib/cloud-login.ts

@@ -0,0 +1,321 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * CLI cloud-login — pure poll-based device flow.
+ *
+ * The CLI asks the cloud to mint a one-time pending-state, opens the
+ * bridge page in the user's browser, then polls the cloud until the
+ * bridge page approves the request — at which point the cloud returns
+ * the minted device-tagged API key exactly once and discards the
+ * state. The Shogo desktop app uses the exact same handshake (driven
+ * from `apps/desktop/src/main.ts → runCloudSignIn`); the only thing
+ * that differs is the `client=cli` URL hint we send so the bridge
+ * page renders the right copy.
+ *
+ * Sequence:
+ *   1. CLI → POST /api/cli/login/start (with device metadata)
+ *      cloud stores pending state, replies { state, userCode, authUrl,
+ *      expiresInMs, pollIntervalMs }.
+ *   2. CLI prints the URL + userCode and opens it in the browser.
+ *   3. User signs in at <cloudUrl>/auth/cli-link?state=... and clicks
+ *      "Approve". The bridge page POSTs /api/cli/login/approve which
+ *      mints the key on the cloud and pins it to `state`.
+ *   4. CLI polls GET /api/cli/login/poll?state=... at pollIntervalMs:
+ *        pending  → keep polling
+ *        approved → returns { key, email, workspace, deviceId } once,
+ *                   then the state is deleted.
+ *        denied   → user clicked "Cancel" on the bridge page.
+ *        expired  → 5-minute TTL elapsed.
+ *
+ * Notes:
+ *   - The userCode (last 6 hex of state, uppercased) is shown in both
+ *     the CLI and the browser so the user can confirm the device they
+ *     are approving matches the terminal they typed `shogo login` in.
+ *   - No localhost listener, no protocol handler, no deep links —
+ *     works behind firewalls / over SSH / from a remote tmux session.
+ */
+import { spawn } from 'node:child_process';
+import { hostname, platform as osPlatform, arch } from 'node:os';
+import pc from 'picocolors';
+
+export interface CloudLoginResult {
+  /** The minted shogo_sk_ key. */
+  key: string;
+  /** User email reported by cloud. */
+  email: string | null;
+  /** Workspace name the key was minted for. */
+  workspace: string | null;
+  /** Stable device id we sent up; cloud echoes it back. */
+  deviceId: string;
+}
+
+export interface CloudLoginOptions {
+  cloudUrl: string;
+  /** "cli" | "desktop" — hint sent to the cloud and echoed on the
+   * bridge page so the UI can label the approval flow correctly.
+   * Default: "cli". */
+  client?: 'cli' | 'desktop';
+  /** Override the device label shown in the dashboard. Defaults to hostname. */
+  deviceName?: string;
+  /** Override the platform string shown in the dashboard
+   * (e.g. "darwin-arm64"). Defaults to `${os.platform()}-${os.arch()}`. */
+  devicePlatform?: string;
+  /** Stable id for this machine. Caller should persist this so re-logins
+   * dedupe to the same device row. */
+  deviceId: string;
+  /** App version label sent to cloud. */
+  appVersion?: string;
+  /** Optional pre-select for the bridge picker. */
+  workspaceId?: string;
+  /** Cap on total wait — defaults to whatever the cloud says (usually 5min). */
+  timeoutMs?: number;
+  /** Browser-open behaviour. Three modes:
+   *   - undefined / true: spawn the platform default opener (open /
+   *     xdg-open / cmd start). Suitable for the CLI.
+   *   - false: never open the browser; caller surfaces the URL.
+   *   - function: custom opener (e.g. Electron's `shell.openExternal`).
+   *     Errors thrown from the function are swallowed so flaky openers
+   *     don't kill the flow — the URL is still printed via `log`. */
+  openBrowser?: boolean | ((url: string) => void | Promise<void>);
+  /** Custom logger — defaults to console.log. */
+  log?: (line: string) => void;
+  /** Override poll interval in ms. Defaults to whatever the cloud returns. */
+  pollIntervalMs?: number;
+  /** Install process-level SIGINT/SIGTERM handlers that abort the poll
+   * loop. Default: true (right for the CLI). Set false when embedding
+   * inside a long-lived host process (e.g. Electron main) where the
+   * caller already manages signal lifecycle and an unrelated Ctrl+C
+   * shouldn't unwind the host. */
+  installSignalHandlers?: boolean;
+  /** Test seam: replace the real fetch. */
+  fetchImpl?: typeof fetch;
+  /** Test seam: an AbortSignal to stop polling early. */
+  abortSignal?: AbortSignal;
+}
+
+export class CloudLoginError extends Error {
+  constructor(
+    message: string,
+    public readonly kind: 'timeout' | 'denied' | 'cancelled' | 'expired' | 'transport',
+  ) {
+    super(message);
+    this.name = 'CloudLoginError';
+  }
+}
+
+interface StartResponse {
+  ok: boolean;
+  error?: string;
+  state: string;
+  userCode: string;
+  authUrl: string;
+  expiresInMs: number;
+  pollIntervalMs: number;
+}
+
+interface PollResponse {
+  ok: boolean;
+  status: 'pending' | 'approved' | 'denied' | 'expired';
+  key?: string;
+  email?: string | null;
+  workspace?: string | null;
+  deviceId?: string;
+  error?: string;
+}
+
+export async function runCloudLogin(opts: CloudLoginOptions): Promise<CloudLoginResult> {
+  const cloudUrl = opts.cloudUrl.replace(/\/$/, '');
+  const client = opts.client ?? 'cli';
+  const deviceName = opts.deviceName ?? hostname();
+  const devicePlatform = opts.devicePlatform ?? `${osPlatform()}-${arch()}`;
+  const appVersion = opts.appVersion ?? readWorkerVersion();
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const fetchImpl = opts.fetchImpl ?? fetch;
+
+  // 1. Start
+  const startRes = await fetchImpl(`${cloudUrl}/api/cli/login/start`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      deviceId: opts.deviceId,
+      deviceName,
+      devicePlatform,
+      deviceAppVersion: appVersion,
+      workspaceId: opts.workspaceId,
+      client,
+    }),
+    signal: AbortSignal.timeout(10_000),
+  }).catch((err) => {
+    throw new CloudLoginError(
+      `Cannot reach Shogo Cloud at ${cloudUrl}: ${err?.message ?? err}`,
+      'transport',
+    );
+  });
+  if (!startRes.ok) {
+    const text = await startRes.text().catch(() => '');
+    throw new CloudLoginError(
+      `Cloud rejected /api/cli/login/start (HTTP ${startRes.status}): ${text || 'no body'}`,
+      'transport',
+    );
+  }
+  const start = (await startRes.json().catch(() => ({} as any))) as StartResponse;
+  if (!start?.ok || !start.state || !start.authUrl) {
+    throw new CloudLoginError(
+      `Cloud returned a malformed start response: ${start?.error ?? JSON.stringify(start)}`,
+      'transport',
+    );
+  }
+
+  const pollIntervalMs = clampPollInterval(opts.pollIntervalMs ?? start.pollIntervalMs);
+  const timeoutMs = opts.timeoutMs ?? start.expiresInMs;
+  const deadline = Date.now() + timeoutMs;
+
+  // 2. Print + open browser
+  log('');
+  log(pc.bold('Sign in to Shogo Cloud'));
+  log(pc.dim('  cloud:     ') + cloudUrl);
+  log(pc.dim('  device:    ') + `${deviceName} (${devicePlatform})`);
+  log(pc.dim('  user code: ') + pc.cyan(start.userCode));
+  log('');
+  log('  Open this URL in your browser to approve:');
+  log('  ' + pc.cyan(start.authUrl));
+  log('');
+
+  if (opts.openBrowser !== false) {
+    if (typeof opts.openBrowser === 'function') {
+      // Caller-supplied opener (e.g. Electron `shell.openExternal`). We
+      // intentionally swallow errors here so a flaky opener doesn't
+      // kill the flow — the URL is already in `log` for copy/paste.
+      try {
+        await opts.openBrowser(start.authUrl);
+      } catch { /* user can copy/paste */ }
+    } else {
+      openInBrowser(start.authUrl).catch(() => { /* user can copy/paste */ });
+    }
+  }
+
+  log(pc.dim('Waiting for approval...'));
+
+  // 3. Poll loop
+  const installSignals = opts.installSignalHandlers ?? true;
+  const sigHandler = () => {
+    // We can't actually throw out of a signal handler — Node won't
+    // propagate it up the stack. Setting the abort signal is the right
+    // way to unwind the poll loop.
+    abortLocal.abort();
+  };
+  // Internal abort controller composes the caller's signal with our
+  // own signal-handler-driven cancellation, so the poll loop only
+  // needs to watch one signal.
+  const abortLocal = new AbortController();
+  if (opts.abortSignal) {
+    if (opts.abortSignal.aborted) abortLocal.abort();
+    else opts.abortSignal.addEventListener('abort', () => abortLocal.abort(), { once: true });
+  }
+  if (installSignals) {
+    process.once('SIGINT', sigHandler);
+    process.once('SIGTERM', sigHandler);
+  }
+
+  try {
+    while (true) {
+      if (abortLocal.signal.aborted) {
+        throw new CloudLoginError('Aborted by caller.', 'cancelled');
+      }
+      if (Date.now() >= deadline) {
+        throw new CloudLoginError(
+          `Timed out after ${Math.round(timeoutMs / 1000)}s waiting for approval.`,
+          'timeout',
+        );
+      }
+
+      const pollRes = await fetchImpl(
+        `${cloudUrl}/api/cli/login/poll?state=${encodeURIComponent(start.state)}`,
+        {
+          method: 'GET',
+          headers: { accept: 'application/json' },
+          signal: AbortSignal.timeout(10_000),
+        },
+      ).catch((err) => {
+        // Soft network errors during polling shouldn't kill the flow —
+        // user might have a flaky connection. Log and back off.
+        log(pc.dim(`  (poll error: ${err?.message ?? err} — retrying)`));
+        return null;
+      });
+
+      if (pollRes && pollRes.ok) {
+        const data = (await pollRes.json().catch(() => ({} as any))) as PollResponse;
+        if (data?.status === 'approved' && data.key) {
+          return {
+            key: data.key,
+            email: data.email ?? null,
+            workspace: data.workspace ?? null,
+            deviceId: data.deviceId ?? opts.deviceId,
+          };
+        }
+        if (data?.status === 'denied') {
+          throw new CloudLoginError('Sign-in was denied in the browser.', 'denied');
+        }
+        if (data?.status === 'expired') {
+          throw new CloudLoginError('Sign-in request expired before it was approved.', 'expired');
+        }
+        // status === 'pending' (or unknown) → keep polling
+      }
+
+      await sleep(pollIntervalMs, abortLocal.signal);
+    }
+  } finally {
+    if (installSignals) {
+      process.removeListener('SIGINT', sigHandler);
+      process.removeListener('SIGTERM', sigHandler);
+    }
+  }
+}
+
+function clampPollInterval(ms: number): number {
+  if (!Number.isFinite(ms) || ms <= 0) return 2000;
+  return Math.min(Math.max(ms, 1000), 10_000);
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new CloudLoginError('Aborted by caller.', 'cancelled'));
+    const t = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(t);
+      reject(new CloudLoginError('Aborted by caller.', 'cancelled'));
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+function readWorkerVersion(): string {
+  try {
+    const url = new URL('../../package.json', import.meta.url);
+    const pkg = JSON.parse(require('node:fs').readFileSync(url, 'utf-8'));
+    return pkg?.version ? `shogo-cli/${pkg.version}` : 'shogo-cli/unknown';
+  } catch {
+    return 'shogo-cli/unknown';
+  }
+}
+
+function openInBrowser(url: string): Promise<void> {
+  return new Promise((resolve) => {
+    const cmd =
+      process.platform === 'darwin' ? 'open'
+      : process.platform === 'win32' ? 'cmd'
+      : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '""', url] : [url];
+    try {
+      const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+      child.on('error', () => resolve());
+      child.unref();
+      resolve();
+    } catch {
+      resolve();
+    }
+  });
+}

package/src/lib/config.ts

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Reads/writes ~/.shogo/config.json. The worker reads this at start,
+ * and the `config` / `login` commands write to it.
+ */
+import { readFileSync, writeFileSync, existsSync, chmodSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { CONFIG_FILE, ensureHome } from './paths.ts';
+
+export interface WorkerConfig {
+  apiKey?: string;
+  cloudUrl?: string;
+  name?: string;
+  workerDir?: string;
+  port?: number;
+}
+
+const DEFAULTS: Required<Pick<WorkerConfig, 'cloudUrl' | 'port'>> = {
+  cloudUrl: 'https://studio.shogo.ai',
+  port: 8002,
+};
+
+export function loadConfig(): WorkerConfig {
+  if (!existsSync(CONFIG_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'));
+  } catch (err) {
+    throw new Error(`Corrupt config at ${CONFIG_FILE}: ${(err as Error).message}`);
+  }
+}
+
+export function saveConfig(cfg: WorkerConfig): void {
+  ensureHome();
+  writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+  chmodSync(CONFIG_FILE, 0o600);
+}
+
+export function mergeConfig(base: WorkerConfig, override: WorkerConfig): WorkerConfig {
+  return { ...base, ...Object.fromEntries(Object.entries(override).filter(([, v]) => v !== undefined)) };
+}
+
+export function resolveConfig(override: WorkerConfig = {}): Required<WorkerConfig> & { apiKey: string } {
+  const fileCfg = loadConfig();
+  const env: WorkerConfig = {
+    apiKey: process.env.SHOGO_API_KEY,
+    cloudUrl: process.env.SHOGO_CLOUD_URL,
+    name: process.env.SHOGO_INSTANCE_NAME,
+    workerDir: process.env.SHOGO_WORKER_DIR,
+    port: process.env.PORT ? parseInt(process.env.PORT, 10) : undefined,
+  };
+  const merged = mergeConfig(mergeConfig(fileCfg, env), override);
+  if (!merged.apiKey) {
+    throw new Error('No API key. Run `shogo login` or pass --api-key / set SHOGO_API_KEY.');
+  }
+  return {
+    apiKey: merged.apiKey,
+    cloudUrl: merged.cloudUrl ?? DEFAULTS.cloudUrl,
+    name: merged.name ?? hostname(),
+    workerDir: merged.workerDir ?? process.cwd(),
+    port: merged.port ?? DEFAULTS.port,
+  };
+}