@stage-labs/metro 0.1.0-beta.7 → 0.1.0-beta.71

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

@@ -0,0 +1,97 @@
+import { watch, type FSWatcher } from 'node:fs';
+import { join, parse as parsePath } from 'node:path';
+import { errMsg, log } from './log.js';
+import type { Pending } from './protocol.js';
+
+export const RESTART_BACKOFFS_MS = [1_000, 5_000, 30_000] as const;
+export const MAX_CONSECUTIVE_FAILS = 5;
+export const HOT_RELOAD_DEBOUNCE_MS = 300;
+export const TRAIN_EXT = /\.(ts|js|mjs)$/;
+
+export interface TrainState {
+  name: string;
+  path: string;
+  proc: ReturnType<typeof Bun.spawn> | null;
+  pending: Map<string, Pending>;
+  buf: string;
+  errBuf: string;
+  failCount: number;
+  restartTimer: ReturnType<typeof setTimeout> | null;
+  startedAt: string | null;
+  stopped: boolean;
+}
+
+export function startWatcher(
+  dir: string,
+  timers: Map<string, ReturnType<typeof setTimeout>>,
+  onChange: (name: string, path: string) => void,
+): FSWatcher | null {
+  try {
+    const w = watch(dir, (_event, filename) => {
+      if (!filename) return;
+      const base = filename;
+      if (!TRAIN_EXT.test(base) || base.startsWith('_') || base.startsWith('.'))
+        return;
+      const name = parsePath(base).name;
+      const existing = timers.get(name);
+      if (existing) clearTimeout(existing);
+      timers.set(
+        name,
+        setTimeout(() => {
+          timers.delete(name);
+          onChange(name, join(dir, base));
+        }, HOT_RELOAD_DEBOUNCE_MS),
+      );
+    });
+    w.on('error', (err) => {
+      log.warn({ err: errMsg(err) }, 'train hot-reload: watcher error');
+    });
+    log.info({ dir }, 'train hot-reload: watching');
+    return w;
+  } catch (err) {
+    log.warn(
+      { err: errMsg(err) },
+      'train hot-reload: watch unavailable (on-demand restart only)',
+    );
+    return null;
+  }
+}
+
+export function killGracefully(
+  proc: ReturnType<typeof Bun.spawn> | null,
+): Promise<unknown> | null {
+  if (proc?.exitCode !== null) return null;
+  try {
+    proc.kill('SIGTERM');
+  } catch {
+  }
+  const grace = setTimeout(() => {
+    try {
+      proc.kill('SIGKILL');
+    } catch {
+    }
+  }, 2_000);
+  return proc.exited.finally(() => {
+    clearTimeout(grace);
+  });
+}
+
+export async function pumpStream(
+  stream: unknown,
+  name: string,
+  kind: 'stdout' | 'stderr',
+  onChunk: (s: string) => void,
+): Promise<void> {
+  if (!stream || typeof stream === 'number') return;
+  const reader = (stream as ReadableStream<Uint8Array>).getReader();
+  const dec = new TextDecoder();
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      onChunk(dec.decode(value, { stream: true }));
+    }
+  } catch (err) {
+    log.debug({ name, err: errMsg(err) }, `train: ${kind} pump ended`);
+  }
+}

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/terminal-api.ts

@@ -0,0 +1,71 @@
+import { spawnSync } from 'node:child_process';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { ApiError } from './api-error.js';
+import { apiFailure, apiSession, bodyField, cors, readJsonBody, sendJson } from './api-http.js';
+import { log } from './log.js';
+import { mintTerminalTicket } from './terminal-tickets.js';
+
+const PREFIX = '/api/terminal';
+const TICKETS = `${PREFIX}/tickets`;
+export const TMUX_SESSION = 'metro';
+const SESSION_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/;
+
+export const tmuxCommand = (session: string): string[] => ['tmux', 'new-session', '-A', '-D', '-s', session, ';', 'set-option', '-g', 'mouse', 'on'];
+
+export interface TerminalApiDeps {
+  authorize: (subject: string) => void;
+  command?: (session: string) => string[];
+}
+
+function tmuxAvailable(deps: TerminalApiDeps): boolean {
+  if (deps.command !== undefined) return true;
+  const run = spawnSync('tmux', ['-V'], { stdio: 'ignore' });
+  return run.error === undefined && run.status === 0;
+}
+
+export function tmuxSessions(): string[] {
+  const run = spawnSync('tmux', ['list-sessions', '-F', '#{session_name}'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  if (run.error !== undefined || run.status !== 0) return [];
+  return run.stdout
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => SESSION_RE.test(l));
+}
+
+export function sessionOf(raw: unknown): string {
+  if (raw === undefined || raw === null || raw === '') return TMUX_SESSION;
+  if (typeof raw !== 'string' || !SESSION_RE.test(raw))
+    throw new ApiError('a session name is 1 to 32 letters, digits, dots, dashes or underscores', 400);
+  return raw;
+}
+
+export function handleTerminalRequest(req: IncomingMessage, res: ServerResponse, deps: TerminalApiDeps): boolean {
+  const path = (req.url ?? '').split('?')[0] ?? '';
+  if (path !== PREFIX && path !== TICKETS) return false;
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  const wanted = path === TICKETS ? 'POST' : 'GET';
+  if (req.method !== wanted) {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  apiSession(req)
+    .then(async (session) => {
+      if (!session) throw new ApiError('unauthorized', 401);
+      deps.authorize(session.subject);
+      if (path === PREFIX) {
+        sendJson(req, res, 200, { available: tmuxAvailable(deps), session: TMUX_SESSION, sessions: tmuxSessions() });
+        return;
+      }
+      const wanted = sessionOf(bodyField(await readJsonBody(req), 'session'));
+      const minted = mintTerminalTicket(session.subject, wanted);
+      log.info({ subject: session.subject, session: wanted }, 'terminal: ticket minted');
+      sendJson(req, res, 200, { ...minted, session: wanted, path: `${PREFIX}/${minted.ticket}` });
+    })
+    .catch((err: unknown) => {
+      apiFailure(req, res, err, 'terminal-api');
+    });
+  return true;
+}

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

@@ -0,0 +1,40 @@
+import { randomBytes } from 'node:crypto';
+
+const TTL_MS = 30_000;
+const MAX_OPEN = 20;
+
+export interface TerminalGrant {
+  subject: string;
+  session: string;
+}
+
+interface Pending extends TerminalGrant {
+  expiresAt: number;
+}
+
+const pending = new Map<string, Pending>();
+
+function prune(now: number): void {
+  for (const [ticket, entry] of pending) if (entry.expiresAt <= now) pending.delete(ticket);
+  while (pending.size >= MAX_OPEN) {
+    const oldest = pending.keys().next().value;
+    if (oldest === undefined) break;
+    pending.delete(oldest);
+  }
+}
+
+export function mintTerminalTicket(subject: string, session: string, now = Date.now()): { ticket: string; expiresAt: number } {
+  prune(now);
+  const ticket = randomBytes(32).toString('base64url');
+  const expiresAt = now + TTL_MS;
+  pending.set(ticket, { subject, session, expiresAt });
+  return { ticket, expiresAt };
+}
+
+export function takeTerminalTicket(ticket: string, now = Date.now()): TerminalGrant | null {
+  const entry = pending.get(ticket);
+  pending.delete(ticket);
+  return entry !== undefined && entry.expiresAt > now ? { subject: entry.subject, session: entry.session } : null;
+}
+
+export const pendingTerminalTickets = (): number => pending.size;

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

@@ -0,0 +1,114 @@
+import { spawn } from 'node:child_process';
+import type { IncomingMessage, Server } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { WebSocketServer, type RawData, type WebSocket } from 'ws';
+import { errMsg, log } from './log.js';
+import { isRecord } from './is-record.js';
+import { takeTerminalTicket, type TerminalGrant } from './terminal-tickets.js';
+
+const TICKET_PATH = /^\/api\/terminal\/([A-Za-z0-9_-]{43})$/;
+const MAX_MESSAGE = 1024 * 1024;
+const DEFAULT_COLS = 120;
+const DEFAULT_ROWS = 36;
+const MAX_DIMENSION = 500;
+
+export interface TerminalSocketDeps {
+  command: (session: string) => string[];
+  takeTicket?: (ticket: string) => TerminalGrant | null;
+}
+
+const rawBytes = (data: RawData): Buffer =>
+  Buffer.isBuffer(data) ? data : Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
+
+export const resizeWindowArgs = (session: string, cols: number, rows: number): string[] => [
+  'resize-window',
+  '-t',
+  `${session}:`,
+  '-x',
+  String(cols),
+  '-y',
+  String(rows),
+];
+
+function sizeTmuxWindow(command: string[], session: string, cols: number, rows: number): void {
+  if (command[0] !== 'tmux') return;
+  const child = spawn('tmux', resizeWindowArgs(session, cols, rows), { stdio: 'ignore' });
+  child.on('error', (err) => {
+    log.debug({ err: errMsg(err) }, 'terminal: resize-window failed');
+  });
+}
+
+const dimension = (raw: unknown, fallback: number): number =>
+  typeof raw === 'number' && Number.isInteger(raw) && raw > 1 && raw <= MAX_DIMENSION ? raw : fallback;
+
+function runTerminal(ws: WebSocket, command: string[], subject: string, session: string): void {
+  const terminal = new Bun.Terminal({
+    cols: DEFAULT_COLS,
+    rows: DEFAULT_ROWS,
+    data: (_term, chunk) => {
+      if (ws.readyState === ws.OPEN) ws.send(chunk);
+    },
+  });
+  const proc = Bun.spawn(command, {
+    terminal,
+    env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' },
+  });
+  log.info({ subject, pid: proc.pid, command: command[0] }, 'terminal: opened');
+  ws.on('message', (data, isBinary) => {
+    const bytes = rawBytes(data);
+    if (isBinary) {
+      terminal.write(bytes);
+      return;
+    }
+    try {
+      const control: unknown = JSON.parse(bytes.toString('utf8'));
+      if (isRecord(control) && 'cols' in control) {
+        const cols = dimension(control.cols, DEFAULT_COLS);
+        const rows = dimension(control.rows, DEFAULT_ROWS);
+        terminal.resize(cols, rows);
+        sizeTmuxWindow(command, session, cols, rows);
+      }
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'terminal: bad control frame');
+    }
+  });
+  ws.on('close', () => {
+    proc.kill();
+    terminal.close();
+    log.info({ subject, pid: proc.pid }, 'terminal: closed by the page');
+  });
+  proc.exited
+    .then((code) => {
+      if (ws.readyState === ws.OPEN) ws.close(1000, `exit ${String(code)}`);
+      terminal.close();
+    })
+    .catch((err: unknown) => {
+      log.warn({ err: errMsg(err) }, 'terminal: exit watch failed');
+    });
+}
+
+function refuse(socket: Duplex, status: number, text: string): void {
+  socket.write(`HTTP/1.1 ${String(status)} ${text}\r\nConnection: close\r\n\r\n`);
+  socket.destroy();
+}
+
+export function attachTerminalSockets(server: Server, deps: TerminalSocketDeps): void {
+  const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_MESSAGE });
+  const take = deps.takeTicket ?? takeTerminalTicket;
+  server.on('upgrade', (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+    const path = (req.url ?? '').split('?')[0] ?? '';
+    const found = TICKET_PATH.exec(path);
+    if (!found) {
+      refuse(socket, 404, 'Not Found');
+      return;
+    }
+    const grant = take(found[1] ?? '');
+    if (grant === null) {
+      refuse(socket, 401, 'Unauthorized');
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      runTerminal(ws, deps.command(grant.session), grant.subject, grant.session);
+    });
+  });
+}

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);
+}