@stage-labs/metro 0.1.0-beta.4 → 0.1.0-beta.41

package/runtime/node_modules/@metro-labs/mcp/src/daemon/supervisor.ts

@@ -0,0 +1,320 @@
+import { mkdirSync, statSync, type FSWatcher } from 'node:fs';
+import { join } from 'node:path';
+import { errMsg, log } from './log.js';
+import { daemonSelf } from './events.js';
+import {
+  drainLines,
+  failAllPending,
+  listTrainFiles,
+  mintCallId,
+  parseTrainLine,
+  sendCall,
+  type TrainCallResponse,
+  type TrainEvent,
+} from './protocol.js';
+import {
+  HOT_RELOAD_DEBOUNCE_MS,
+  MAX_CONSECUTIVE_FAILS,
+  RESTART_BACKOFFS_MS,
+  killGracefully,
+  pumpStream,
+  startWatcher,
+  type TrainState,
+} from './supervisor-io.js';
+import { trainsDir } from './paths.js';
+
+const DYLD_FALLBACK_ENV: Record<string, string> =
+  process.platform === 'darwin'
+    ? {
+        DYLD_FALLBACK_LIBRARY_PATH: [
+          '/usr/lib',
+          process.env.DYLD_FALLBACK_LIBRARY_PATH,
+        ]
+          .filter(Boolean)
+          .join(':'),
+      }
+    : {};
+
+export class TrainSupervisor {
+  private trains = new Map<string, TrainState>();
+  private onEvent: ((event: TrainEvent, train: string) => void) | null = null;
+  private nextCallId = 1;
+  private watcher: FSWatcher | null = null;
+  private reloadTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  constructor(private dir: string = trainsDir()) {}
+
+  running(): string[] {
+    return [...this.trains.keys()];
+  }
+
+  onTrainEvent(handler: (event: TrainEvent, train: string) => void): void {
+    this.onEvent = handler;
+  }
+
+  start(): void {
+    mkdirSync(this.dir, { recursive: true });
+    for (const t of listTrainFiles(this.dir)) this.startTrain(t.name, t.path);
+    log.info(
+      { dir: this.dir, count: this.trains.size },
+      'train supervisor: started',
+    );
+    this.watchForReloads();
+  }
+
+  private watchForReloads(): void {
+    this.watcher = startWatcher(this.dir, this.reloadTimers, (name, path) => {
+      this.handleSourceChange(name, path);
+    });
+  }
+
+  requestReload(name: string): void {
+    const path = join(this.dir, `${name}.ts`);
+    const existing = this.reloadTimers.get(name);
+    if (existing) clearTimeout(existing);
+    this.reloadTimers.set(
+      name,
+      setTimeout(() => {
+        this.reloadTimers.delete(name);
+        this.handleSourceChange(name, path);
+      }, HOT_RELOAD_DEBOUNCE_MS),
+    );
+  }
+
+  async stopTrain(name: string): Promise<void> {
+    const t = this.trains.get(name);
+    if (!t) return;
+    const timer = this.reloadTimers.get(name);
+    if (timer) {
+      clearTimeout(timer);
+      this.reloadTimers.delete(name);
+    }
+    t.stopped = true;
+    if (t.restartTimer) {
+      clearTimeout(t.restartTimer);
+      t.restartTimer = null;
+    }
+    failAllPending(t.pending, `train '${name}' stopped`);
+    const wait = killGracefully(t.proc);
+    if (wait) await wait;
+    this.trains.delete(name);
+    log.info({ name }, 'train: stopped, last account detached');
+  }
+
+  private handleSourceChange(name: string, path: string): void {
+    try {
+      if (!statSync(path).isFile()) return;
+    } catch {
+      return;
+    }
+    if (this.trains.has(name)) {
+      log.info({ name }, 'train hot-reload: source changed, restarting');
+      this.restart(name).catch((err: unknown) => {
+        log.warn(
+          { name, err: errMsg(err) },
+          'train hot-reload: restart failed',
+        );
+      });
+      return;
+    }
+    log.info({ name }, 'train hot-reload: new train, spawning');
+    this.startTrain(name, path);
+  }
+
+  async stop(): Promise<void> {
+    if (this.watcher) {
+      try {
+        this.watcher.close();
+      } catch {
+      }
+      this.watcher = null;
+    }
+    for (const timer of this.reloadTimers.values()) clearTimeout(timer);
+    this.reloadTimers.clear();
+    const tasks: Promise<unknown>[] = [];
+    for (const t of this.trains.values()) {
+      t.stopped = true;
+      if (t.restartTimer) {
+        clearTimeout(t.restartTimer);
+        t.restartTimer = null;
+      }
+      failAllPending(t.pending, 'train shutting down');
+      const wait = killGracefully(t.proc);
+      if (wait) tasks.push(wait);
+    }
+    await Promise.all(tasks);
+  }
+
+  async restart(name: string): Promise<void> {
+    const t = this.trains.get(name);
+    if (!t) throw new Error(`no train named '${name}'`);
+    if (t.restartTimer) {
+      clearTimeout(t.restartTimer);
+      t.restartTimer = null;
+    }
+    failAllPending(t.pending, `train '${name}' restarting`);
+    t.stopped = true;
+    const wait = killGracefully(t.proc);
+    if (wait) await wait;
+    t.stopped = false;
+    t.failCount = 0;
+    t.proc = null;
+    this.spawn(t);
+  }
+
+  async call(
+    name: string,
+    action: string,
+    args: unknown,
+  ): Promise<TrainCallResponse> {
+    const t = this.trains.get(name);
+    if (!t)
+      throw new Error(
+        `no train named '${name}' (have: ${[...this.trains.keys()].join(', ') || '(none)'})`,
+      );
+    if (t.proc?.exitCode !== null)
+      throw new Error(`train '${name}' is not running`);
+    return sendCall(t as never, mintCallId(this.nextCallId++), action, args);
+  }
+
+  private startTrain(name: string, path: string): void {
+    if (this.trains.has(name)) {
+      log.warn({ name }, 'train supervisor: duplicate name, skipping');
+      return;
+    }
+    const state: TrainState = {
+      name,
+      path,
+      proc: null,
+      pending: new Map(),
+      buf: '',
+      errBuf: '',
+      failCount: 0,
+      restartTimer: null,
+      startedAt: null,
+      stopped: false,
+    };
+    this.trains.set(name, state);
+    this.spawn(state);
+  }
+
+  private spawn(state: TrainState): void {
+    if (state.stopped) return;
+    try {
+      const proc = Bun.spawn(['bun', 'run', state.path], {
+        stdin: 'pipe',
+        stdout: 'pipe',
+        stderr: 'pipe',
+        env: {
+          ...process.env,
+          ...DYLD_FALLBACK_ENV,
+          METRO_TRAIN_NAME: state.name,
+          METRO_SELF_URI: daemonSelf(),
+        },
+      });
+      state.proc = proc;
+      state.startedAt = new Date().toISOString();
+      state.buf = '';
+      state.errBuf = '';
+      log.info({ name: state.name, pid: proc.pid }, 'train: spawned');
+      const pumpFailed = (err: unknown): void => {
+        log.warn({ name: state.name, err: errMsg(err) }, 'train: pump failed');
+      };
+      this.pumpStdout(state).catch(pumpFailed);
+      this.pumpStderr(state).catch(pumpFailed);
+      proc.exited
+        .then((code) => {
+          this.onExit(state, code ?? 0);
+        })
+        .catch((err: unknown) => {
+          log.error(
+            { name: state.name, err: errMsg(err) },
+            'train: exit handler failed',
+          );
+        });
+    } catch (err) {
+      log.warn({ name: state.name, err: errMsg(err) }, 'train: spawn failed');
+      this.scheduleRestart(state);
+    }
+  }
+
+  private pumpStdout(state: TrainState): Promise<void> {
+    return pumpStream(state.proc?.stdout, state.name, 'stdout', (chunk) => {
+      state.buf += chunk;
+      state.buf = drainLines(state.name, state.buf, (line) => {
+        this.handleLine(state, line);
+      });
+    });
+  }
+
+  private pumpStderr(state: TrainState): Promise<void> {
+    return pumpStream(state.proc?.stderr, state.name, 'stderr', (chunk) => {
+      state.errBuf += chunk;
+      state.errBuf = drainLines(state.name, state.errBuf, (line) => {
+        log.warn({ train: state.name }, line);
+      });
+    });
+  }
+
+  private handleLine(state: TrainState, line: string): void {
+    const msg = parseTrainLine(state.name, line);
+    if (!msg || msg.op === 'ignore') return;
+    if (msg.op === 'response') {
+      const pending = state.pending.get(msg.id);
+      if (!pending) {
+        log.debug({ name: state.name, id: msg.id }, 'train: stale response');
+        return;
+      }
+      state.pending.delete(msg.id);
+      clearTimeout(pending.timer);
+      pending.resolve({
+        result: msg.result,
+        error: msg.error,
+        errorInfo: msg.errorInfo,
+      });
+      return;
+    }
+    if (msg.op === 'log') {
+      log.info({ name: state.name, msg: msg.text }, 'train log');
+      return;
+    }
+    this.onEvent?.(msg.event, state.name);
+  }
+
+  private onExit(state: TrainState, code: number): void {
+    log.warn({ name: state.name, code }, 'train: exited');
+    state.proc = null;
+    state.startedAt = null;
+    failAllPending(
+      state.pending,
+      `train '${state.name}' exited (code=${code}) before responding`,
+    );
+    if (state.stopped) return;
+    state.failCount++;
+    if (state.failCount >= MAX_CONSECUTIVE_FAILS) {
+      log.error(
+        { name: state.name, fails: state.failCount },
+        'train: too many consecutive failures, giving up (restart metro to retry)',
+      );
+      return;
+    }
+    this.scheduleRestart(state);
+  }
+
+  private scheduleRestart(state: TrainState): void {
+    if (state.stopped) return;
+    const idx = Math.min(state.failCount, RESTART_BACKOFFS_MS.length - 1);
+    const delay = RESTART_BACKOFFS_MS[idx];
+    log.info(
+      { name: state.name, delay, attempt: state.failCount },
+      'train: restart scheduled',
+    );
+    state.restartTimer = setTimeout(() => {
+      state.restartTimer = null;
+      this.spawn(state);
+      setTimeout(() => {
+        if (state.proc?.exitCode === null) state.failCount = 0;
+      }, 30_000);
+    }, delay);
+  }
+}

package/runtime/node_modules/@metro-labs/mcp/src/daemon/train-call.ts

@@ -0,0 +1,22 @@
+import type { TrainCallResponse } from './protocol.js';
+
+export type TrainCallBackend = (
+  train: string,
+  action: string,
+  args: unknown,
+) => Promise<TrainCallResponse>;
+
+let backend: TrainCallBackend | null = null;
+
+export function setTrainCallBackend(fn: TrainCallBackend): void {
+  backend = fn;
+}
+
+export function forwardTrainCall(
+  train: string,
+  action: string,
+  args: unknown,
+): Promise<TrainCallResponse> {
+  if (!backend) throw new Error('train-call backend not wired');
+  return backend(train, action, args);
+}

package/runtime/node_modules/@metro-labs/mcp/src/daemon/train-error.ts

@@ -0,0 +1,53 @@
+export interface TrainErrorInfo {
+  code: string;
+  message: string;
+  retryable?: boolean;
+  retryAfterMs?: number;
+}
+
+export class TrainError extends Error {
+  readonly code: string;
+  readonly retryable?: boolean;
+  readonly retryAfterMs?: number;
+  constructor(
+    code: string,
+    message: string,
+    opts?: { retryable?: boolean; retryAfterMs?: number },
+  ) {
+    super(message);
+    this.name = 'TrainError';
+    this.code = code;
+    this.retryable = opts?.retryable;
+    this.retryAfterMs = opts?.retryAfterMs;
+  }
+  toErrorInfo(): TrainErrorInfo {
+    return {
+      code: this.code,
+      message: this.message,
+      ...(this.retryable !== undefined ? { retryable: this.retryable } : {}),
+      ...(this.retryAfterMs !== undefined
+        ? { retryAfterMs: this.retryAfterMs }
+        : {}),
+    };
+  }
+}
+
+export function serializeTrainError(err: unknown): {
+  error: string;
+  errorInfo?: TrainErrorInfo;
+} {
+  if (err instanceof TrainError)
+    return { error: err.message, errorInfo: err.toErrorInfo() };
+  return { error: err instanceof Error ? err.message : String(err) };
+}
+
+export function coerceErrorInfo(v: unknown): TrainErrorInfo | undefined {
+  if (!v || typeof v !== 'object') return undefined;
+  const o = v as Record<string, unknown>;
+  if (typeof o.code !== 'string' || typeof o.message !== 'string')
+    return undefined;
+  const info: TrainErrorInfo = { code: o.code, message: o.message };
+  if (typeof o.retryable === 'boolean') info.retryable = o.retryable;
+  if (typeof o.retryAfterMs === 'number') info.retryAfterMs = o.retryAfterMs;
+  return info;
+}

package/runtime/node_modules/@metro-labs/mcp/src/daemon/tunnel.ts

@@ -0,0 +1,257 @@
+import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
+import { timingSafeEqual } from 'node:crypto';
+import { Resolver } from 'node:dns/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { STATE_DIR } from './paths.js';
+import { errMsg, log } from './log.js';
+import { readJson } from './secure-fs.js';
+
+const FILE = join(STATE_DIR, 'tunnel.json');
+const LEGACY_WEBHOOKS_FILE = join(STATE_DIR, 'webhooks.json');
+const RESTART_DELAY_MS = 2_000;
+
+interface NamedTunnel {
+  name: string;
+  hostname: string;
+}
+
+interface QuickTunnel {
+  quick: true;
+}
+
+export type TunnelConfig = NamedTunnel | QuickTunnel;
+
+const isQuick = (cfg: TunnelConfig): cfg is QuickTunnel => 'quick' in cfg;
+
+export const tunnelConfigFromEnv = (): TunnelConfig | null =>
+  process.env.METRO_TUNNEL?.trim() === 'quick' ? { quick: true } : null;
+
+const QUICK_URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+
+export const quickTunnelUrlIn = (text: string): string | null =>
+  QUICK_URL_RE.exec(text)?.[0] ?? null;
+
+let liveUrl: string | null = null;
+
+export const currentTunnelUrl = (): string | null => liveUrl;
+
+export type Resolves = (host: string) => Promise<boolean>;
+
+const PUBLIC_RESOLVERS = ['1.1.1.1', '1.0.0.1'];
+const RESOLVE_EVERY_MS = 3_000;
+const RESOLVE_GIVE_UP_MS = 180_000;
+
+export async function resolvesAtCloudflare(host: string): Promise<boolean> {
+  const resolver = new Resolver();
+  resolver.setServers(PUBLIC_RESOLVERS);
+  try {
+    return (await resolver.resolve4(host)).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function untilResolvable(host: string, resolves: Resolves): Promise<boolean> {
+  const deadline = Date.now() + RESOLVE_GIVE_UP_MS;
+  while (Date.now() < deadline) {
+    if (await resolves(host)) return true;
+    await new Promise((r) => setTimeout(r, RESOLVE_EVERY_MS));
+  }
+  return false;
+}
+
+export function configuredTunnelHost(): string | null {
+  const cfg = loadTunnelConfig();
+  return cfg !== null && !isQuick(cfg) ? cfg.hostname : null;
+}
+
+export interface Endpoint {
+  id: string;
+  webhookId?: string;
+  label: string;
+  secret?: string;
+  session?: string;
+  createdAt: string;
+}
+interface AccountRecord {
+  id?: unknown;
+  webhookId?: unknown;
+  label?: unknown;
+  secret?: unknown;
+  session?: unknown;
+  createdAt?: unknown;
+}
+
+export const webhookPort = (): number =>
+  Number(process.env.METRO_WEBHOOK_PORT) || 8420;
+
+const accountsFile = (): string =>
+  process.env.WEBHOOK_ACCOUNTS_FILE ??
+  join(homedir(), '.metro', 'webhook-accounts.json');
+
+const str = (v: unknown): string | undefined =>
+  typeof v === 'string' && v !== '' ? v : undefined;
+
+function toEndpoint(raw: AccountRecord): Endpoint | null {
+  const id = str(raw.id);
+  if (id === undefined) return null;
+  return {
+    id,
+    webhookId: str(raw.webhookId),
+    label: str(raw.label) ?? id,
+    secret: str(raw.secret),
+    session: str(raw.session),
+    createdAt: str(raw.createdAt) ?? '',
+  };
+}
+
+export function listEndpoints(): Endpoint[] {
+  const raw = readJson<AccountRecord[]>(accountsFile(), [], {
+    warn: 'webhook-accounts.json: malformed, ignoring',
+  });
+  if (!Array.isArray(raw)) return [];
+  return raw.map(toEndpoint).filter((e): e is Endpoint => e !== null);
+}
+
+export const findEndpointByWebhookId = (
+  webhookId: string,
+): Endpoint | undefined =>
+  listEndpoints().find((e) => e.webhookId === webhookId);
+
+export function tokenMatches(secret: string, given: string): boolean {
+  const want = Buffer.from(secret);
+  const got = Buffer.from(given);
+  return want.length === got.length && timingSafeEqual(want, got);
+}
+
+export function warnOnLegacyWebhooks(): void {
+  const legacy = readJson<{ endpoints?: unknown[] }>(LEGACY_WEBHOOKS_FILE, {});
+  const count = Array.isArray(legacy.endpoints) ? legacy.endpoints.length : 0;
+  if (count > 0)
+    log.warn(
+      { file: LEGACY_WEBHOOKS_FILE, endpoints: count },
+      'webhook: webhooks.json is no longer read — endpoints live in the accounts table; these endpoints are inactive',
+    );
+}
+
+export const loadTunnelConfig = (): TunnelConfig | null =>
+  readJson<TunnelConfig | null>(FILE, null, {
+    warn: 'tunnel.json: malformed, ignoring',
+  });
+
+function fetchTunnelToken(name: string): string | null {
+  const r = spawnSync('cloudflared', ['tunnel', 'token', name], {
+    encoding: 'utf8',
+  });
+  if (r.status !== 0) return null;
+  const token = r.stdout.trim();
+  return token.length > 0 ? token : null;
+}
+
+interface Plan {
+  args: string[];
+  env: NodeJS.ProcessEnv;
+  mode: string;
+}
+
+export class Tunnel {
+  private child: ChildProcess | null = null;
+  private closed = false;
+  private token: string | null | undefined = undefined;
+
+  constructor(
+    private cfg: TunnelConfig,
+    private port: number,
+    private onUrl: (url: string) => void = () => undefined,
+    private resolves: Resolves = resolvesAtCloudflare,
+  ) {}
+
+  get hostname(): string {
+    if (!isQuick(this.cfg)) return this.cfg.hostname;
+    return liveUrl === null ? '' : new URL(liveUrl).host;
+  }
+
+  private origin(): string {
+    return `http://127.0.0.1:${String(this.port)}`;
+  }
+
+  private plan(): Plan {
+    if (isQuick(this.cfg))
+      return {
+        args: ['--no-autoupdate', 'tunnel', '--url', this.origin()],
+        env: process.env,
+        mode: 'quick',
+      };
+    if (this.token === undefined) this.token = fetchTunnelToken(this.cfg.name);
+    const args = ['--no-autoupdate', 'tunnel', 'run', '--url', this.origin()];
+    if (!this.token) args.push(this.cfg.name);
+    return {
+      args,
+      env: this.token ? { ...process.env, TUNNEL_TOKEN: this.token } : process.env,
+      mode: this.token ? 'token' : 'named',
+    };
+  }
+
+  private noticeUrl(text: string): void {
+    if (!isQuick(this.cfg)) return;
+    const url = quickTunnelUrlIn(text);
+    if (url === null || url === liveUrl) return;
+    liveUrl = url;
+    log.info({ url }, 'quick tunnel up; waiting for its name to resolve');
+    this.announceWhenResolvable(url).catch((err: unknown) => {
+      log.warn({ err: errMsg(err) }, 'quick tunnel: announce failed');
+    });
+  }
+
+  private async announceWhenResolvable(url: string): Promise<void> {
+    const resolved = await untilResolvable(new URL(url).host, this.resolves);
+    if (liveUrl !== url) return;
+    if (!resolved) log.warn({ url }, 'quick tunnel name still not resolving; announcing anyway');
+    this.onUrl(url);
+  }
+
+  start(): void {
+    if (this.closed) return;
+    const plan = this.plan();
+    log.info(
+      { tunnel: isQuick(this.cfg) ? 'quick' : this.cfg.name, port: this.port, mode: plan.mode },
+      'cloudflared tunnel starting',
+    );
+    const child = spawn('cloudflared', plan.args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: plan.env,
+    });
+    this.child = child;
+    child.stderr?.on('data', (d: Buffer | string) => {
+      const text = (typeof d === 'string' ? d : d.toString('utf8')).trim();
+      log.debug({ cloudflared: text }, 'cloudflared');
+      this.noticeUrl(text);
+    });
+    child.on('exit', (code) => {
+      this.child = null;
+      liveUrl = null;
+      if (this.closed) return;
+      log.warn({ code }, 'cloudflared exited; restarting');
+      setTimeout(() => {
+        this.start();
+      }, RESTART_DELAY_MS);
+    });
+    child.on('error', (err) => {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        this.closed = true;
+        log.error(
+          'cloudflared is not installed, so there is no public address; install it and restart',
+        );
+        return;
+      }
+      log.warn({ err: errMsg(err) }, 'cloudflared spawn error');
+    });
+  }
+
+  stop(): void {
+    this.closed = true;
+    this.child?.kill();
+    this.child = null;
+  }
+}