@tsufbarkai/relay-stream 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# @relay/stream
+
+Stream your terminal output to a Relay session in real time.
+
+## Install
+
+```bash
+npm install -g @relay/stream
+```
+
+## Usage
+
+All modes require `--relay <id>` and `--token <jwt>` (or the environment variables `RELAY_ID` and `RELAY_TOKEN`). Use `--url <base>` to point at a non-default API server (defaults to `http://localhost:3002`).
+
+### Pipe mode
+
+Pipe any command's output into a Relay tile:
+
+```bash
+some-command | relay-stream --relay <id> --token <jwt>
+```
+
+### Wrap mode
+
+Wrap a command — stdout and stderr are captured and streamed:
+
+```bash
+relay-stream --relay <id> --token <jwt> -- npm test
+```
+
+### PTY mode
+
+Stream a full interactive terminal session with ANSI colors and cursor control:
+
+```bash
+relay-stream --relay <id> --token <jwt> --pty
+relay-stream --relay <id> --token <jwt> --pty -- python3
+```
+
+PTY mode requires the optional `node-pty-prebuilt-multiarch` dependency, which is installed automatically on supported platforms. If it fails to install (e.g. missing build tools), pipe and wrap modes still work.
+
+## Options
+
+| Flag | Env variable | Description |
+|---|---|---|
+| `--relay <id>` | `RELAY_ID` | Relay ID to stream to (required) |
+| `--token <jwt>` | `RELAY_TOKEN` | JWT auth token (required) |
+| `--url <base>` | `RELAY_URL` | API base URL (default: `http://localhost:3002`) |
+| `--label <name>` | — | Display label for the stream tile |
+| `--pty` | — | Enable PTY mode |
+
+## License
+
+MIT

package/bin/relay-stream.js

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+'use strict';
+
+// ─── HTTP helper ─────────────────────────────────────────────────────────────
+
+function post(url, body, token) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const lib = parsed.protocol === 'https:' ? require('https') : require('http');
+    const data = JSON.stringify(body);
+    const req = lib.request(
+      {
+        hostname: parsed.hostname,
+        port: parsed.port,
+        path: parsed.pathname + parsed.search,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(data),
+          Authorization: `Bearer ${token}`,
+        },
+      },
+      (res) => {
+        let body = '';
+        res.on('data', (d) => (body += d));
+        res.on('end', () => {
+          try {
+            resolve({ status: res.statusCode, body: JSON.parse(body) });
+          } catch {
+            resolve({ status: res.statusCode, body });
+          }
+        });
+      }
+    );
+    req.on('error', reject);
+    req.write(data);
+    req.end();
+  });
+}
+
+// ─── Arg parsing ─────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const result = {
+    token: process.env.RELAY_TOKEN || null,
+    relay: process.env.RELAY_ID || null,
+    url: process.env.RELAY_URL || 'http://localhost:3002',
+    label: null,
+    pty: false,
+    command: [],
+  };
+
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === '--') {
+      result.command = argv.slice(i + 1);
+      break;
+    } else if (arg === '--token' && argv[i + 1]) {
+      result.token = argv[++i];
+    } else if (arg === '--relay' && argv[i + 1]) {
+      result.relay = argv[++i];
+    } else if (arg === '--url' && argv[i + 1]) {
+      result.url = argv[++i];
+    } else if (arg === '--label' && argv[i + 1]) {
+      result.label = argv[++i];
+    } else if (arg === '--pty') {
+      result.pty = true;
+    }
+    i++;
+  }
+
+  return result;
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.token) {
+    process.stderr.write('Error: --token or RELAY_TOKEN required\n');
+    process.exit(1);
+  }
+  if (!args.relay) {
+    process.stderr.write('Error: --relay or RELAY_ID required\n');
+    process.exit(1);
+  }
+
+  const { token, relay, url: baseUrl, label, command, pty: isPtyMode } = args;
+  const isWrapMode = !isPtyMode && command.length > 0;
+  const tileLabel =
+    label ||
+    (isPtyMode
+      ? command.length > 0
+        ? command.join(' ')
+        : 'terminal session'
+      : isWrapMode
+        ? command.join(' ')
+        : 'stdin stream');
+
+  // ── Create stream tile ───────────────────────────────────────────────────
+  let tileId;
+  try {
+    const tileBody = { type: 'stream', content: '', label: tileLabel, status: 'running' };
+    if (isPtyMode) tileBody.terminal = true;
+    const res = await post(
+      `${baseUrl}/api/relays/${relay}/tiles`,
+      tileBody,
+      token
+    );
+    if (res.status < 200 || res.status >= 300) {
+      process.stderr.write(
+        `[relay-stream] failed to create tile (HTTP ${res.status}): ${JSON.stringify(res.body)}\n`
+      );
+      process.exit(1);
+    }
+    tileId = res.body.id;
+  } catch (err) {
+    process.stderr.write(`[relay-stream] failed to create tile: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  process.stderr.write(
+    `[relay-stream] streaming to relay ${relay}, tile ${tileId}\n[relay-stream] ${baseUrl}/api/relays/${relay}/tiles/${tileId}\n`
+  );
+
+  // ── Buffer + flush machinery ─────────────────────────────────────────────
+  const FLUSH_INTERVAL_MS = 200;
+  const FLUSH_SIZE_BYTES = 4 * 1024; // 4 KB
+
+  let buffer = '';
+  let flushTimer = null;
+
+  async function flushBuffer() {
+    if (!buffer) return;
+    const chunk = buffer;
+    buffer = '';
+    try {
+      const res = await post(
+        `${baseUrl}/api/relays/${relay}/tiles/${tileId}/stream`,
+        { chunk },
+        token
+      );
+      if (res.status < 200 || res.status >= 300) {
+        process.stderr.write(
+          `[relay-stream] stream chunk failed (HTTP ${res.status}): ${JSON.stringify(res.body)}\n`
+        );
+      }
+    } catch (err) {
+      process.stderr.write(`[relay-stream] stream chunk error: ${err.message}\n`);
+    }
+  }
+
+  function scheduleFlush() {
+    if (!flushTimer) {
+      flushTimer = setTimeout(async () => {
+        flushTimer = null;
+        await flushBuffer();
+      }, FLUSH_INTERVAL_MS);
+    }
+  }
+
+  function appendChunk(text) {
+    buffer += text;
+    if (Buffer.byteLength(buffer) >= FLUSH_SIZE_BYTES) {
+      if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+      }
+      flushBuffer();
+    } else {
+      scheduleFlush();
+    }
+  }
+
+  async function closeStream(exitCode) {
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    await flushBuffer();
+
+    const status = exitCode === 0 ? 'done' : 'error';
+    try {
+      const res = await post(
+        `${baseUrl}/api/relays/${relay}/tiles/${tileId}/stream/close`,
+        { status },
+        token
+      );
+      if (res.status < 200 || res.status >= 300) {
+        process.stderr.write(
+          `[relay-stream] close failed (HTTP ${res.status}): ${JSON.stringify(res.body)}\n`
+        );
+      }
+    } catch (err) {
+      process.stderr.write(`[relay-stream] close error: ${err.message}\n`);
+    }
+    process.stderr.write('[relay-stream] done\n');
+  }
+
+  // ── Mode: pty (interactive terminal) ────────────────────────────────────
+  if (isPtyMode) {
+    let pty;
+    try {
+      pty = require('node-pty-prebuilt-multiarch');
+    } catch {
+      process.stderr.write(
+        'PTY mode requires node-pty-prebuilt-multiarch. Install it with: npm install node-pty-prebuilt-multiarch\n'
+      );
+      process.exit(1);
+    }
+
+    const shell = String(command.length > 0 ? command[0] : (process.env.SHELL || '/bin/bash'));
+    const shellArgs = command.length > 1 ? command.slice(1) : [];
+
+    if (!shell) {
+      process.stderr.write('[relay-stream] could not determine shell to spawn\n');
+      process.exit(1);
+    }
+
+    const ptyProcess = pty.spawn(shell, shellArgs, {
+      name: 'xterm-256color',
+      cols: process.stdout.columns || 120,
+      rows: process.stdout.rows || 30,
+      env: process.env,
+    });
+
+    // Forward PTY output to stdout and relay buffer
+    ptyProcess.onData((data) => {
+      process.stdout.write(data);
+      appendChunk(data);
+    });
+
+    // Forward stdin to PTY
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+    process.stdin.on('data', (data) => {
+      ptyProcess.write(data.toString());
+    });
+
+    // Handle terminal resize
+    process.stdout.on('resize', () => {
+      ptyProcess.resize(process.stdout.columns, process.stdout.rows);
+    });
+
+    // Cleanup helper
+    let exiting = false;
+    async function cleanup(exitCode) {
+      if (exiting) return;
+      exiting = true;
+      try {
+        if (process.stdin.isTTY) process.stdin.setRawMode(false);
+      } catch {}
+      await closeStream(exitCode);
+      process.exit(exitCode);
+    }
+
+    // Handle signals
+    process.on('SIGINT', () => {
+      ptyProcess.kill();
+      cleanup(0);
+    });
+    process.on('SIGTERM', () => {
+      ptyProcess.kill();
+      cleanup(0);
+    });
+
+    // Handle PTY exit
+    ptyProcess.onExit(({ exitCode }) => {
+      cleanup(exitCode ?? 0);
+    });
+
+    return; // let PTY drive exit
+  }
+
+  // ── Mode: wrap (spawn child) ─────────────────────────────────────────────
+  if (isWrapMode) {
+    const { spawn } = require('child_process');
+    const [cmd, ...cmdArgs] = command;
+    const child = spawn(cmd, cmdArgs, {
+      stdio: ['inherit', 'pipe', 'pipe'],
+      env: process.env,
+    });
+
+    child.stdout.on('data', (chunk) => {
+      process.stdout.write(chunk);
+      appendChunk(chunk.toString());
+    });
+
+    child.stderr.on('data', (chunk) => {
+      process.stderr.write(chunk);
+      appendChunk(chunk.toString());
+    });
+
+    child.on('close', async (code) => {
+      const exitCode = code ?? 1;
+      await closeStream(exitCode);
+      process.exit(exitCode);
+    });
+
+    child.on('error', async (err) => {
+      process.stderr.write(`[relay-stream] failed to spawn command: ${err.message}\n`);
+      await closeStream(1);
+      process.exit(1);
+    });
+
+    return; // let child drive exit
+  }
+
+  // ── Mode: pipe (read from stdin) ─────────────────────────────────────────
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+
+  rl.on('line', (line) => {
+    appendChunk(line + '\n');
+  });
+
+  rl.on('close', async () => {
+    await closeStream(0);
+    process.exit(0);
+  });
+
+  process.stdin.on('error', async (err) => {
+    process.stderr.write(`[relay-stream] stdin error: ${err.message}\n`);
+    await closeStream(1);
+    process.exit(1);
+  });
+}
+
+main().catch((err) => {
+  process.stderr.write(`[relay-stream] unexpected error: ${err.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@tsufbarkai/relay-stream",
+  "version": "0.1.0",
+  "description": "Stream your terminal to a Relay session",
+  "bin": {
+    "relay-stream": "./bin/relay-stream.js"
+  },
+  "files": [
+    "bin/"
+  ],
+  "keywords": [
+    "relay",
+    "terminal",
+    "stream",
+    "pty",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tsufbarkai/relay.git",
+    "directory": "packages/relay-cli"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "postinstall": "node -e \"require('fs').chmodSync(require('path').join(__dirname, 'bin/relay-stream.js'), '755')\""
+  },
+  "optionalDependencies": {
+    "node-pty-prebuilt-multiarch": "^0.10.0"
+  }
+}