@keeroklab/cli 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,67 @@
+# @keeroklab/cli
+
+CLI wrapper for **Keerok Lab** — live Claude Code supervision for training sessions.
+
+Students connect to a supervised session where the instructor can monitor terminals in real-time, send messages, and manage API budgets.
+
+## Quick Start
+
+```bash
+npx @keeroklab/cli connect <token> --server https://keerok.tech
+```
+
+Your instructor will provide the `<token>` via email or the session page.
+
+## Requirements
+
+- **Node.js 18+** — [Download](https://nodejs.org)
+- A terminal (macOS Terminal, iTerm2, Windows Terminal, etc.)
+
+## What happens when you connect
+
+1. Your token is validated against the server
+2. A secure WebSocket connection is established
+3. `claude` (Claude Code CLI) is launched in your terminal
+4. Your terminal output is streamed to the instructor's dashboard (read-only)
+
+## Options
+
+```
+Usage: keerok-lab connect <token> [options]
+
+Arguments:
+  token                 Connection token provided by the instructor
+
+Options:
+  -s, --server <url>    Server URL (default: "https://keerok.tech")
+  -c, --command <cmd>   Command to run (default: "claude")
+  -h, --help            Display help
+```
+
+## Security
+
+- Your API key is **encrypted (AES-256/Fernet)** and never stored in plain text
+- The key is only active during the session and **revoked automatically** when it ends
+- The instructor sees your terminal in **read-only** mode (no write access)
+- No personal data is kept after the session ends
+
+## How It Works
+
+```
+Student terminal                Keerok Server              Instructor dashboard
+     │                              │                              │
+     ├── validate token ──────────► │                              │
+     │◄── session config ─────────  │                              │
+     │                              │                              │
+     ├══ WebSocket ═══════════════► │ ◄═══════════════ WebSocket ══┤
+     │                              │                              │
+     │   terminal output ─────────► │ ──── terminal stream ──────► │
+     │                              │                              │
+     │◄── instructor message ────── │ ◄── send message ───────────┤
+     │◄── budget warning ────────── │                              │
+     │◄── session ended ─────────── │ ◄── end session ────────────┤
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keeroklab/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI wrapper for Keerok Lab — live Claude Code supervision",
   "type": "module",
   "bin": {
@@ -12,19 +12,28 @@
   "files": [
     "src/"
   ],
-  "keywords": ["claude", "lab", "supervision", "terminal", "claude-code", "keerok"],
+  "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"
+    "url": "https://github.com/vincentrandon/keeroklab-cli"
   },
   "homepage": "https://keerok.tech",
+  "bugs": {
+    "url": "https://github.com/vincentrandon/keeroklab-cli/issues"
+  },
   "license": "MIT",
   "dependencies": {
+    "chalk": "^5.3.0",
     "commander": "^12.0.0",
-    "node-pty": "^1.0.0",
-    "ws": "^8.16.0",
-    "chalk": "^5.3.0"
+    "ws": "^8.16.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/pty-capture.js

@@ -1,59 +1,60 @@
 /**
- * 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.
+ * pty-capture.js — Spawns a process and captures output.
+ * Uses child_process.spawn with pipes to capture terminal output
+ * and forward it to both stdout and the WebSocket handler.
  */
 
-import pty from 'node-pty';
+import { spawn } from 'child_process';
 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',
-      },
-    }
-  );
+  const child = spawn(shell, ['-c', command], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      TERM: 'xterm-256color',
+      FORCE_COLOR: '1',
+      COLUMNS: String(cols),
+      LINES: String(rows),
+    },
+  });
 
-  // Forward PTY output to both stdout and the handler
-  term.onData((data) => {
+  // Forward stdout to both terminal and handler
+  child.stdout.on('data', (data) => {
     process.stdout.write(data);
-    handlers.onData?.(data);
+    handlers.onData?.(data.toString());
   });
 
-  term.onExit(({ exitCode }) => {
-    handlers.onExit?.(exitCode);
+  // Forward stderr to both terminal and handler
+  child.stderr.on('data', (data) => {
+    process.stderr.write(data);
+    handlers.onData?.(data.toString());
   });
 
-  // Forward stdin to PTY
+  child.on('exit', (code) => {
+    handlers.onExit?.(code ?? 0);
+  });
+
+  // Forward stdin to child
   if (process.stdin.isTTY) {
     process.stdin.setRawMode(true);
   }
   process.stdin.resume();
   process.stdin.on('data', (data) => {
-    term.write(data.toString());
+    if (child.stdin.writable) {
+      child.stdin.write(data);
+    }
   });
 
   // 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);
   });
 
@@ -62,13 +63,15 @@ export function spawnPty(command, handlers) {
 
   return {
     kill() {
-      term.kill();
+      child.kill();
     },
     write(data) {
-      term.write(data);
+      if (child.stdin.writable) {
+        child.stdin.write(data);
+      }
     },
-    resize(cols, rows) {
-      term.resize(cols, rows);
+    resize() {
+      // child_process doesn't support resize, but we notify the handler
     },
   };
 }