@keeroklab/cli 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@keeroklab/cli",
+  "version": "0.1.0",
+  "description": "CLI wrapper for Keerok Lab — live Claude Code supervision",
+  "type": "module",
+  "bin": {
+    "keerok-lab": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "keywords": ["claude", "lab", "supervision", "terminal", "claude-code", "keerok"],
+  "author": "Keerok <hello@keerok.tech> (https://keerok.tech)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/keerok/lab-cli"
+  },
+  "homepage": "https://keerok.tech",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "node-pty": "^1.0.0",
+    "ws": "^8.16.0",
+    "chalk": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/env-injector.js

@@ -0,0 +1,32 @@
+/**
+ * env-injector.js — Validates the connection token and retrieves session config.
+ * GET /api/lab/validate-token/ with Bearer token.
+ */
+
+export async function validateToken(token, serverUrl) {
+  const url = `${serverUrl.replace(/\/$/, '')}/api/lab/validate-token/`;
+
+  const response = await fetch(url, {
+    method: 'GET',
+    headers: {
+      'Authorization': `Bearer ${token}`,
+    },
+  });
+
+  const data = await response.json();
+
+  if (!response.ok) {
+    return { valid: false, error: data.error || `HTTP ${response.status}` };
+  }
+
+  // Resolve relative ws_url to absolute if needed
+  if (data.ws_url && data.ws_url.startsWith('ws://localhost')) {
+    // Replace with server-relative URL
+    const wsScheme = serverUrl.startsWith('https') ? 'wss' : 'ws';
+    const host = new URL(serverUrl).host;
+    const path = new URL(`http://localhost${data.ws_url.replace(/^wss?:\/\/[^/]+/, '')}`).pathname;
+    data.ws_url = `${wsScheme}://${host}${path}`;
+  }
+
+  return data;
+}

package/src/index.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { validateToken } from './env-injector.js';
+import { createWsClient } from './ws-client.js';
+import { spawnPty } from './pty-capture.js';
+
+const program = new Command();
+
+program
+  .name('keerok-lab')
+  .description('CLI wrapper for Keerok Lab — live Claude Code supervision')
+  .version('0.1.0');
+
+program
+  .command('connect')
+  .description('Connect to a lab session')
+  .argument('<token>', 'Connection token provided by the instructor')
+  .option('-s, --server <url>', 'Server URL', 'https://keerok.tech')
+  .option('-c, --command <cmd>', 'Command to run', 'claude')
+  .action(async (token, options) => {
+    try {
+      console.log('\n🔬 Keerok Lab — Connecting...\n');
+
+      // Step 1: Validate token and get session config
+      const config = await validateToken(token, options.server);
+      if (!config.valid) {
+        console.error(`❌ ${config.error || 'Invalid token'}`);
+        process.exit(1);
+      }
+
+      console.log(`✅ Session: ${config.session_title}`);
+      console.log(`👤 Name: ${config.participant_name}`);
+      console.log(`🤖 Model: ${config.model_allowed}`);
+      if (config.budget_usd > 0) {
+        console.log(`💰 Budget: $${config.budget_usd.toFixed(2)}`);
+      }
+      if (config.instructions) {
+        console.log(`\n📋 Instructions:\n${config.instructions}\n`);
+      }
+
+      // Step 2: Connect WebSocket
+      const ws = createWsClient(config.ws_url, {
+        onSessionConfig: (data) => {
+          // API key received — inject into environment
+          if (data.api_key) {
+            process.env.ANTHROPIC_API_KEY = data.api_key;
+          }
+        },
+        onBudgetWarning: (data) => {
+          console.log(`\n⚠️  Budget warning: $${data.remaining_usd.toFixed(2)} remaining (${data.percentage.toFixed(0)}% used)\n`);
+        },
+        onBudgetExceeded: () => {
+          console.log('\n🚫 Budget exceeded — session terminated\n');
+          process.exit(1);
+        },
+        onInstructorMessage: (data) => {
+          console.log(`\n📩 Instructor: ${data.message}\n`);
+        },
+        onSessionPaused: () => {
+          console.log('\n⏸️  Session paused by instructor\n');
+        },
+        onSessionEnded: () => {
+          console.log('\n🏁 Session ended by instructor\n');
+          process.exit(0);
+        },
+        onRevoked: () => {
+          console.log('\n🚫 Access revoked by instructor\n');
+          process.exit(1);
+        },
+      });
+
+      // Wait for WS connection
+      await ws.waitForConnection();
+      console.log('🔗 WebSocket connected\n');
+      console.log('─'.repeat(50));
+      console.log(`Starting: ${options.command}`);
+      console.log('─'.repeat(50) + '\n');
+
+      // Step 3: Spawn PTY with the command
+      const pty = spawnPty(options.command, {
+        onData: (data) => {
+          // Forward terminal output to server
+          ws.send({
+            type: 'terminal_output',
+            data: Buffer.from(data).toString('base64'),
+          });
+        },
+        onResize: (cols, rows) => {
+          ws.send({ type: 'terminal_resize', cols, rows });
+        },
+        onExit: (code) => {
+          console.log(`\n\nProcess exited with code ${code}`);
+          ws.close();
+          process.exit(code);
+        },
+      });
+
+      // Heartbeat every 30s
+      const heartbeat = setInterval(() => {
+        ws.send({ type: 'heartbeat' });
+      }, 30000);
+
+      // Handle SIGINT gracefully
+      process.on('SIGINT', () => {
+        clearInterval(heartbeat);
+        pty.kill();
+        ws.close();
+        process.exit(0);
+      });
+
+    } catch (err) {
+      console.error(`\n❌ Error: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/pty-capture.js

@@ -0,0 +1,74 @@
+/**
+ * pty-capture.js — Spawns a PTY process and captures output.
+ * Uses node-pty to create a pseudo-terminal that captures all output
+ * including ANSI escape codes, colors, and cursor movements.
+ */
+
+import pty from 'node-pty';
+import os from 'os';
+
+export function spawnPty(command, handlers) {
+  const shell = os.platform() === 'win32' ? 'powershell.exe' : process.env.SHELL || '/bin/bash';
+  const args = command === shell ? [] : ['-c', command];
+  const useShell = command !== shell;
+
+  const cols = process.stdout.columns || 80;
+  const rows = process.stdout.rows || 24;
+
+  const term = pty.spawn(
+    useShell ? shell : command,
+    useShell ? args : [],
+    {
+      name: 'xterm-256color',
+      cols,
+      rows,
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        TERM: 'xterm-256color',
+      },
+    }
+  );
+
+  // Forward PTY output to both stdout and the handler
+  term.onData((data) => {
+    process.stdout.write(data);
+    handlers.onData?.(data);
+  });
+
+  term.onExit(({ exitCode }) => {
+    handlers.onExit?.(exitCode);
+  });
+
+  // Forward stdin to PTY
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(true);
+  }
+  process.stdin.resume();
+  process.stdin.on('data', (data) => {
+    term.write(data.toString());
+  });
+
+  // Handle terminal resize
+  process.stdout.on('resize', () => {
+    const newCols = process.stdout.columns;
+    const newRows = process.stdout.rows;
+    term.resize(newCols, newRows);
+    handlers.onResize?.(newCols, newRows);
+  });
+
+  // Send initial size
+  handlers.onResize?.(cols, rows);
+
+  return {
+    kill() {
+      term.kill();
+    },
+    write(data) {
+      term.write(data);
+    },
+    resize(cols, rows) {
+      term.resize(cols, rows);
+    },
+  };
+}

package/src/ws-client.js

@@ -0,0 +1,120 @@
+/**
+ * ws-client.js — WebSocket client with automatic reconnection.
+ */
+
+import WebSocket from 'ws';
+
+export function createWsClient(url, handlers) {
+  let ws = null;
+  let connected = false;
+  let reconnectAttempts = 0;
+  const maxReconnectAttempts = 20;
+  let reconnectTimer = null;
+  let connectionResolve = null;
+
+  function connect() {
+    ws = new WebSocket(url);
+
+    ws.on('open', () => {
+      connected = true;
+      reconnectAttempts = 0;
+      if (connectionResolve) {
+        connectionResolve();
+        connectionResolve = null;
+      }
+    });
+
+    ws.on('close', () => {
+      connected = false;
+      scheduleReconnect();
+    });
+
+    ws.on('error', (err) => {
+      // Errors are followed by 'close', so reconnect is handled there
+      if (connectionResolve) {
+        // If we haven't connected yet, reject
+        connectionResolve = null;
+      }
+    });
+
+    ws.on('message', (raw) => {
+      try {
+        const data = JSON.parse(raw.toString());
+        handleMessage(data, handlers);
+      } catch {
+        // Ignore malformed messages
+      }
+    });
+  }
+
+  function scheduleReconnect() {
+    if (reconnectAttempts >= maxReconnectAttempts) {
+      console.error('Max reconnect attempts reached. Exiting.');
+      process.exit(1);
+    }
+    const delay = Math.min(1000 * Math.pow(2, reconnectAttempts), 30000);
+    reconnectAttempts++;
+    reconnectTimer = setTimeout(() => connect(), delay);
+  }
+
+  function handleMessage(data, handlers) {
+    switch (data.type) {
+      case 'session_config':
+        handlers.onSessionConfig?.(data);
+        break;
+      case 'budget_warning':
+        handlers.onBudgetWarning?.(data);
+        break;
+      case 'budget_exceeded':
+        handlers.onBudgetExceeded?.(data);
+        break;
+      case 'instructor_message':
+        handlers.onInstructorMessage?.(data);
+        break;
+      case 'session_paused':
+        handlers.onSessionPaused?.(data);
+        break;
+      case 'session_ended':
+        handlers.onSessionEnded?.(data);
+        break;
+      case 'revoked':
+        handlers.onRevoked?.(data);
+        break;
+    }
+  }
+
+  // Initial connection
+  connect();
+
+  return {
+    send(data) {
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify(data));
+      }
+    },
+
+    close() {
+      clearTimeout(reconnectTimer);
+      if (ws) {
+        ws.close();
+      }
+    },
+
+    waitForConnection() {
+      if (connected) return Promise.resolve();
+      return new Promise((resolve, reject) => {
+        connectionResolve = resolve;
+        // Timeout after 10s
+        setTimeout(() => {
+          if (!connected) {
+            reject(new Error('WebSocket connection timeout'));
+          }
+        }, 10000);
+      });
+    },
+
+    get connected() {
+      return connected;
+    },
+  };
+}