@plosson/agentio 0.7.1 → 0.7.3

package/src/server/siteio-runner.ts

@@ -0,0 +1,329 @@
+/**
+ * Thin wrapper around the `siteio` CLI for `agentio mcp teleport`. Every
+ * siteio command we need to invoke goes through this module, which
+ * delegates to an injected `spawn` function. Tests inject a mock; the
+ * production wiring injects a tiny adapter over `Bun.spawn`.
+ *
+ * Why the indirection: `siteio` is an external dependency I can't run
+ * in CI, and I don't want the teleport command tests to require a real
+ * `siteio` binary on PATH. The runner captures the exact argv + env
+ * that would be invoked, the mock returns stubbed output, and the
+ * test asserts the argv lines up with the intended workflow.
+ */
+
+export interface SpawnedProcess {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface SpawnOptions {
+  /** Full argv, including the binary name at argv[0]. */
+  cmd: string[];
+  /** Optional extra env vars (merged over process.env inside the adapter). */
+  env?: Record<string, string>;
+}
+
+export type SpawnFn = (opts: SpawnOptions) => Promise<SpawnedProcess>;
+
+/**
+ * Default production `spawn` implementation that shells out to Bun.spawn.
+ * Tests pass their own mock instead.
+ */
+export const defaultSpawn: SpawnFn = async (opts) => {
+  const proc = Bun.spawn(opts.cmd, {
+    stdout: 'pipe',
+    stderr: 'pipe',
+    env: { ...process.env, ...(opts.env ?? {}) },
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { exitCode, stdout, stderr };
+};
+
+/* ------------------------------------------------------------------ */
+/* SiteioRunner                                                        */
+/* ------------------------------------------------------------------ */
+
+export interface SiteioApp {
+  name: string;
+  /** URL the app is (or will be) deployed at. Present when siteio has
+   *  assigned a subdomain. */
+  url?: string;
+  /** Free-form additional fields from siteio's JSON output — we pass
+   *  them through without interpretation. */
+  [key: string]: unknown;
+}
+
+export interface SiteioRunner {
+  /** `siteio --version` → true on exit 0, false on any error. */
+  isInstalled(): Promise<boolean>;
+  /** `siteio status` → true on exit 0 (i.e. currently logged in). */
+  isLoggedIn(): Promise<boolean>;
+  /** `siteio apps list --json`, filtered to the named app. */
+  findApp(name: string): Promise<SiteioApp | null>;
+  /**
+   * `siteio apps create <name>` with either:
+   *   - inline-Dockerfile mode (`-f <path>`), or
+   *   - git mode (`-g <url> --branch <branch> --dockerfile <path>`).
+   * Exactly one of the two must be provided.
+   */
+  createApp(args: CreateAppArgs): Promise<void>;
+  /**
+   * `siteio apps set <name> [-e KEY=value]... [-v vol:path]...`.
+   *
+   * Per siteio's update semantics (see app-storage.ts:62-91 in the
+   * siteio repo): env vars MERGE additively (existing keys preserved
+   * unless overridden), but volumes REPLACE the entire mount list.
+   * Callers that want to preserve other volumes should read appInfo
+   * first and union the entries.
+   *
+   * At least one of envVars/volumes must be provided.
+   */
+  setApp(args: {
+    name: string;
+    envVars?: Record<string, string>;
+    /** Map of `volumeName` → `mountPath`, e.g. `{ 'agentio-data-mcp': '/data' }`. */
+    volumes?: Record<string, string>;
+  }): Promise<void>;
+  /** `siteio apps deploy <name> [-f <path>] [--no-cache]`. */
+  deploy(args: {
+    name: string;
+    dockerfilePath?: string;
+    noCache?: boolean;
+  }): Promise<void>;
+  /** `siteio apps restart <name>`. Required after `apps set -e` to pick up new env vars. */
+  restartApp(name: string): Promise<void>;
+  /** `siteio apps info <name> --json` — used to surface the deployed URL. */
+  appInfo(name: string): Promise<SiteioApp | null>;
+}
+
+/**
+ * Arguments for `siteio apps create`. Must be either inline-Dockerfile
+ * mode OR git mode; passing both (or neither) is rejected at runtime.
+ */
+export type CreateAppArgs =
+  | {
+      name: string;
+      port: number;
+      dockerfilePath: string;
+      git?: undefined;
+    }
+  | {
+      name: string;
+      port: number;
+      dockerfilePath?: undefined;
+      git: {
+        repoUrl: string;
+        branch: string;
+        /** Path to the Dockerfile inside the repo, e.g. "docker/Dockerfile.teleport". */
+        dockerfilePath: string;
+      };
+    };
+
+export interface SiteioRunnerError extends Error {
+  command: string[];
+  exitCode: number;
+  stderr: string;
+}
+
+function makeError(
+  cmd: string[],
+  result: SpawnedProcess,
+  context: string
+): SiteioRunnerError {
+  const err = new Error(
+    `siteio ${cmd.slice(1).join(' ')} failed (${context}): exit ${result.exitCode}\n${result.stderr.trim()}`
+  ) as SiteioRunnerError;
+  err.command = cmd;
+  err.exitCode = result.exitCode;
+  err.stderr = result.stderr;
+  return err;
+}
+
+export function createSiteioRunner(
+  spawn: SpawnFn = defaultSpawn
+): SiteioRunner {
+  return {
+    async isInstalled() {
+      try {
+        const r = await spawn({ cmd: ['siteio', '--version'] });
+        return r.exitCode === 0;
+      } catch {
+        return false;
+      }
+    },
+
+    async isLoggedIn() {
+      try {
+        const r = await spawn({ cmd: ['siteio', 'status'] });
+        return r.exitCode === 0;
+      } catch {
+        return false;
+      }
+    },
+
+    async findApp(name) {
+      const cmd = ['siteio', 'apps', 'list', '--json'];
+      const r = await spawn({ cmd });
+      if (r.exitCode !== 0) {
+        throw makeError(cmd, r, 'list apps');
+      }
+      // siteio's CLI mixes progress output on stdout before the JSON
+      // payload (e.g. "- Fetching apps\n{...}"). Find the JSON body by
+      // looking for the first `{` or `[` that starts a line.
+      const jsonStart = r.stdout.search(/^[\[{]/m);
+      const jsonText =
+        jsonStart >= 0 ? r.stdout.slice(jsonStart) : r.stdout;
+
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(jsonText);
+      } catch {
+        throw new Error(
+          `siteio apps list --json returned unparseable output:\n${r.stdout}`
+        );
+      }
+
+      // Normalize the shape: siteio ships {success, data: [...]} in
+      // recent versions, older versions may return {apps: [...]} or a
+      // bare [...]. Accept all three.
+      let apps: SiteioApp[];
+      if (Array.isArray(parsed)) {
+        apps = parsed as SiteioApp[];
+      } else if (
+        parsed &&
+        typeof parsed === 'object' &&
+        Array.isArray((parsed as { data?: unknown }).data)
+      ) {
+        apps = (parsed as { data: SiteioApp[] }).data;
+      } else if (
+        parsed &&
+        typeof parsed === 'object' &&
+        Array.isArray((parsed as { apps?: unknown }).apps)
+      ) {
+        apps = (parsed as { apps: SiteioApp[] }).apps;
+      } else {
+        throw new Error(
+          `siteio apps list --json: expected an array (or {data:[...]} / {apps:[...]}), got:\n${r.stdout}`
+        );
+      }
+
+      const match = apps.find(
+        (a) => a && typeof a === 'object' && a.name === name
+      );
+      return match ?? null;
+    },
+
+    async createApp(args) {
+      // Enforce exactly-one-of semantics at runtime too (the type system
+      // enforces this at the call site, but a caller coming from JS or
+      // forcing a cast could still break the contract).
+      const hasInline = typeof args.dockerfilePath === 'string';
+      const hasGit = args.git != null;
+      if (hasInline === hasGit) {
+        throw new Error(
+          `createApp: exactly one of dockerfilePath or git must be provided (got inline=${hasInline}, git=${hasGit})`
+        );
+      }
+
+      const cmd = ['siteio', 'apps', 'create', args.name];
+      if (hasInline) {
+        cmd.push('-f', args.dockerfilePath as string);
+      } else {
+        const g = args.git!;
+        cmd.push(
+          '-g',
+          g.repoUrl,
+          '--branch',
+          g.branch,
+          '--dockerfile',
+          g.dockerfilePath
+        );
+      }
+      cmd.push('-p', String(args.port));
+
+      const r = await spawn({ cmd });
+      if (r.exitCode !== 0) {
+        throw makeError(cmd, r, `create ${args.name}`);
+      }
+    },
+
+    async setApp(args) {
+      const envEntries = Object.entries(args.envVars ?? {});
+      const volEntries = Object.entries(args.volumes ?? {});
+      if (envEntries.length === 0 && volEntries.length === 0) {
+        throw new Error(
+          `setApp(${args.name}): no envVars or volumes provided — siteio would reject the call`
+        );
+      }
+      const cmd = ['siteio', 'apps', 'set', args.name];
+      for (const [key, value] of envEntries) {
+        cmd.push('-e', `${key}=${value}`);
+      }
+      for (const [name, path] of volEntries) {
+        cmd.push('-v', `${name}:${path}`);
+      }
+      const r = await spawn({ cmd });
+      if (r.exitCode !== 0) {
+        throw makeError(cmd, r, `set on ${args.name}`);
+      }
+    },
+
+    async deploy(args) {
+      const cmd = ['siteio', 'apps', 'deploy', args.name];
+      if (args.dockerfilePath) {
+        cmd.push('-f', args.dockerfilePath);
+      }
+      if (args.noCache) {
+        cmd.push('--no-cache');
+      }
+      const r = await spawn({ cmd });
+      if (r.exitCode !== 0) {
+        throw makeError(cmd, r, `deploy ${args.name}`);
+      }
+    },
+
+    async restartApp(name) {
+      const cmd = ['siteio', 'apps', 'restart', name];
+      const r = await spawn({ cmd });
+      if (r.exitCode !== 0) {
+        throw makeError(cmd, r, `restart ${name}`);
+      }
+    },
+
+    async appInfo(name) {
+      const cmd = ['siteio', 'apps', 'info', name, '--json'];
+      const r = await spawn({ cmd });
+      if (r.exitCode !== 0) {
+        // app doesn't exist or siteio errored — caller can treat null
+        // as "could not read info" rather than blow up the whole
+        // teleport just because we couldn't get a URL to print.
+        return null;
+      }
+      // Strip any progress-line prefix before the JSON body (siteio's
+      // CLI prints status lines on stdout before the --json payload).
+      const jsonStart = r.stdout.search(/^[\[{]/m);
+      const jsonText =
+        jsonStart >= 0 ? r.stdout.slice(jsonStart) : r.stdout;
+      try {
+        const parsed = JSON.parse(jsonText);
+        if (!parsed || typeof parsed !== 'object') return null;
+        // Unwrap {success, data: {...}} shape if present.
+        if (
+          'data' in parsed &&
+          parsed.data &&
+          typeof parsed.data === 'object'
+        ) {
+          return parsed.data as SiteioApp;
+        }
+        return parsed as SiteioApp;
+      } catch {
+        return null;
+      }
+    },
+  };
+}

package/src/server/test-helpers.ts

@@ -0,0 +1,201 @@
+import type { Subprocess } from 'bun';
+
+/**
+ * Shared test helpers for subprocess-based integration tests. Not a test
+ * file itself — imported by `*.test.ts` files that spawn the agentio
+ * daemon.
+ *
+ * The main job of this module is to work around a port-allocation race
+ * in `findFreePort` + `Bun.spawn`:
+ *
+ *   1. We ask the OS for a free port via `Bun.serve({ port: 0 })`.
+ *   2. We stop the probe, freeing the port.
+ *   3. We spawn `agentio server start --port <that port>`.
+ *
+ * Between steps 2 and 3 another process (another parallel test, or
+ * anything on the host) can grab the port, and the subprocess then
+ * fails with `Failed to start server. Is port N in use?`.
+ *
+ * `startServerSubprocess` wraps the whole cycle in a retry loop that
+ * catches the "port in use" failure and re-rolls a fresh port, up to
+ * a few attempts.
+ */
+
+export interface StartSubprocessOptions {
+  home: string;
+  extraArgs?: string[];
+  extraEnv?: Record<string, string>;
+  /** Max retries on port allocation failure. Default 4. */
+  maxRetries?: number;
+}
+
+export interface StartedSubprocess {
+  proc: Subprocess<'ignore', 'pipe', 'pipe'>;
+  port: number;
+  apiKey: string;
+  startupLog: string;
+}
+
+export async function findFreePort(): Promise<number> {
+  const probe = Bun.serve({ port: 0, fetch: () => new Response('') });
+  const port = probe.port;
+  probe.stop(true);
+  if (typeof port !== 'number') {
+    throw new Error('Bun.serve did not return a numeric port');
+  }
+  return port;
+}
+
+export async function startServerSubprocess(
+  opts: StartSubprocessOptions
+): Promise<StartedSubprocess> {
+  const maxRetries = opts.maxRetries ?? 4;
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    const port = await findFreePort();
+
+    const env: Record<string, string> = {
+      ...process.env,
+      HOME: opts.home,
+      AGENTIO_SERVER_PORT: '',
+      AGENTIO_SERVER_HOST: '',
+      AGENTIO_SERVER_API_KEY: '',
+      ...(opts.extraEnv ?? {}),
+    };
+    for (const k of [
+      'AGENTIO_SERVER_PORT',
+      'AGENTIO_SERVER_HOST',
+      'AGENTIO_SERVER_API_KEY',
+    ]) {
+      if (!opts.extraEnv?.[k]) delete env[k];
+    }
+
+    const proc = Bun.spawn(
+      [
+        'bun',
+        'run',
+        'src/index.ts',
+        'server',
+        'start',
+        '--foreground',
+        '--port',
+        String(port),
+        ...(opts.extraArgs ?? []),
+      ],
+      { stdout: 'pipe', stderr: 'pipe', env }
+    );
+
+    // Race stdout reads against proc.exited + a hard timeout so we can
+    // cleanly distinguish "starting up" from "already died".
+    const decoder = new TextDecoder();
+    let buffer = '';
+    const reader = proc.stdout.getReader();
+    const deadline = Date.now() + 10_000;
+    let ready = false;
+    let died = false;
+
+    try {
+      while (!ready) {
+        if (Date.now() > deadline) {
+          proc.kill('SIGKILL');
+          throw new Error(`startup timeout at attempt ${attempt + 1}:\n${buffer}`);
+        }
+        const { done, value } = await Promise.race([
+          reader.read(),
+          new Promise<{ done: true; value: undefined }>((resolve) =>
+            setTimeout(
+              () => resolve({ done: true, value: undefined }),
+              Math.max(100, deadline - Date.now())
+            )
+          ),
+        ]);
+        if (done) {
+          died = true;
+          break;
+        }
+        buffer += decoder.decode(value);
+        if (buffer.includes('Server ready')) {
+          ready = true;
+          break;
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+
+    if (!ready) {
+      const stderr = await new Response(proc.stderr).text().catch(() => '');
+      const combined = `${buffer}\n${stderr}`;
+      // If this was a port collision, retry with a fresh port.
+      if (
+        died &&
+        (combined.includes('Is port') ||
+          combined.includes('EADDRINUSE') ||
+          combined.includes('address already in use'))
+      ) {
+        lastError = new Error(
+          `port ${port} collided on attempt ${attempt + 1}: ${combined.trim()}`
+        );
+        // Make sure the process is gone before looping.
+        try {
+          proc.kill('SIGKILL');
+          await proc.exited;
+        } catch {
+          /* ignore */
+        }
+        continue;
+      }
+      // Any other startup failure: throw immediately.
+      try {
+        proc.kill('SIGKILL');
+        await proc.exited;
+      } catch {
+        /* ignore */
+      }
+      throw new Error(
+        `server failed to start (attempt ${attempt + 1}):\n${combined}`
+      );
+    }
+
+    const apiKey = buffer.match(/API Key: (\S+)/)?.[1] ?? '';
+    if (!apiKey) {
+      proc.kill('SIGKILL');
+      await proc.exited;
+      throw new Error(
+        `could not parse API key from startup log:\n${buffer}`
+      );
+    }
+
+    return {
+      proc: proc as Subprocess<'ignore', 'pipe', 'pipe'>,
+      port,
+      apiKey,
+      startupLog: buffer,
+    };
+  }
+
+  throw new Error(
+    `startServerSubprocess: exhausted ${maxRetries} retries. Last error: ${lastError?.message ?? 'unknown'}`
+  );
+}
+
+export async function shutdown(
+  proc: Subprocess<'ignore', 'pipe', 'pipe'>,
+  signal: 'SIGTERM' | 'SIGINT' = 'SIGTERM',
+  timeoutMs = 5000
+): Promise<number> {
+  proc.kill(signal);
+  const result = await Promise.race([
+    proc.exited.then((code) => ({ ok: true as const, code })),
+    new Promise<{ ok: false }>((resolve) =>
+      setTimeout(() => resolve({ ok: false as const }), timeoutMs)
+    ),
+  ]);
+  if (!result.ok) {
+    proc.kill('SIGKILL');
+    await proc.exited;
+    throw new Error(`process did not exit on ${signal} within ${timeoutMs}ms`);
+  }
+  return result.code;
+}

package/src/types/config.ts

@@ -1,3 +1,5 @@
+import type { ServerConfig } from './server';
+
 export interface GatewayServerConfig {
   // Server binding (for running a gateway daemon)
   port?: number;          // Port to bind (default: 7890)
@@ -57,6 +59,7 @@ export interface Config {
   };
   env?: Record<string, string>;
   gateway?: GatewayConfig;
+  server?: ServerConfig;
 }
 
 export type ServiceName = 'gdocs' | 'gdrive' | 'gmail' | 'gcal' | 'gtasks' | 'gchat' | 'gsheets' | 'github' | 'jira' | 'slack' | 'telegram' | 'whatsapp' | 'discourse' | 'sql';

package/src/types/server.ts

@@ -0,0 +1,61 @@
+/**
+ * Configuration for the agentio HTTP MCP server (`agentio server start`).
+ *
+ * Stored under `config.server` in `~/.config/agentio/config.json`, mirroring
+ * how the gateway daemon stores its own config under `config.gateway`.
+ */
+export interface ServerConfig {
+  /** Operator API key. Auto-generated on first boot if missing. */
+  apiKey?: string;
+  /** Port to bind (default: 9999). */
+  port?: number;
+  /** Host to bind (default: '0.0.0.0'). */
+  host?: string;
+  /** Dynamically registered OAuth clients (RFC 7591). */
+  clients?: OAuthClient[];
+  /** Issued bearer tokens (RFC 6749). */
+  tokens?: ServerToken[];
+}
+
+/**
+ * An OAuth client registered via Dynamic Client Registration. Public clients
+ * only — no client_secret. Identified by an opaque client_id.
+ */
+export interface OAuthClient {
+  clientId: string;
+  clientName?: string;
+  redirectUris: string[];
+  /** Unix epoch milliseconds. */
+  createdAt: number;
+}
+
+/**
+ * An issued bearer token. Opaque, 32 random bytes base64url. Persists across
+ * server restarts; expires after 30 days unless revoked.
+ */
+export interface ServerToken {
+  token: string;
+  clientId: string;
+  /** The `?services=...` query the client supplied at /authorize. */
+  scope: string;
+  /** Unix epoch milliseconds. */
+  issuedAt: number;
+  /** Unix epoch milliseconds. */
+  expiresAt: number;
+}
+
+/**
+ * A short-lived authorization code. Stored in-memory only — never persisted
+ * to disk. The full flow takes seconds, so a process restart between
+ * /authorize and /token is acceptable cause for re-auth.
+ */
+export interface AuthCode {
+  code: string;
+  clientId: string;
+  redirectUri: string;
+  /** PKCE S256 challenge from /authorize. */
+  codeChallenge: string;
+  scope: string;
+  /** Unix epoch milliseconds. */
+  expiresAt: number;
+}