paris-immersion 0.1.2 → 0.1.3

package/dist/commands/serve.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Minimal pty-like interface — we type-erase node-pty so the file compiles
+ * cleanly without the native module being installed (it's loaded lazily at
+ * runtime via dynamic require).
+ */
+type IPty = {
+    write: (s: string) => void;
+    resize: (cols: number, rows: number) => void;
+    onData: (cb: (d: string) => void) => void;
+    onExit?: (cb: (e: {
+        exitCode: number;
+        signal?: number;
+    }) => void) => void;
+    kill: (signal?: string) => void;
+};
 export interface ServeOptions {
     port: number;
     allowedOrigins: string[];
@@ -22,6 +37,12 @@ export interface ServeHandle {
     port: number;
     close: () => void;
 }
+/**
+ * Spawn the coached pty (`claude '/tostudy'` inside the provisioned workspace).
+ * Shared by the local ws server and the relay agent. Throws if node-pty can't
+ * load/spawn — callers report it on their channel.
+ */
+export declare function spawnCoachPty(cwd: string): IPty;
 /**
  * Start a localhost WebSocket server that brokers a pty (running `claude`) to a
  * connected browser-side xterm.js. Two gates protect the channel:
@@ -42,3 +63,4 @@ export declare function readServeToken(): Promise<string>;
 export declare function serveCommand(opts: {
     port?: string | number;
 }): Promise<void>;
+export {};

package/dist/commands/serve.js

@@ -4,6 +4,7 @@ import { promises as fs, chmodSync, existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { readCredentials } from '../lib/credentials.js';
 import { ensureWorkspace } from './install.js';
+import { startRelayAgent } from '../lib/relay-agent.js';
 import { c } from '../lib/colors.js';
 /**
  * Restore the executable bit on node-pty's `spawn-helper`. Some install paths
@@ -69,6 +70,31 @@ const DEFAULT_ALLOWED_ORIGINS = [
 // turma precisar de outro entrypoint (ex.: o tutor-paris `get_course` como
 // fallback quando não há curso ToStudy configurado).
 const COACH_KICKOFF = process.env.PARIS_COACH_KICKOFF || '/tostudy';
+/**
+ * Spawn the coached pty (`claude '/tostudy'` inside the provisioned workspace).
+ * Shared by the local ws server and the relay agent. Throws if node-pty can't
+ * load/spawn — callers report it on their channel.
+ */
+export function spawnCoachPty(cwd) {
+    const req = createRequire(import.meta.url);
+    ensureSpawnHelperExecutable(req);
+    const ptyMod = req('node-pty');
+    const shell = process.env.SHELL || (process.platform === 'win32' ? 'powershell.exe' : 'bash');
+    const shellArgs = process.platform === 'win32'
+        ? ['-NoLogo', '-Command', `claude "${COACH_KICKOFF.replace(/"/g, '`"')}"`]
+        : ['-l', '-c', `claude '${COACH_KICKOFF.replace(/'/g, `'\\''`)}'`];
+    return ptyMod.spawn(shell, shellArgs, {
+        name: 'xterm-color',
+        cols: 80,
+        rows: 24,
+        cwd,
+        env: {
+            ...process.env,
+            TOSTUDY_MCP_ENABLED: '1',
+            PARIS_MCP_ENABLED: '1',
+        },
+    });
+}
 /**
  * Start a localhost WebSocket server that brokers a pty (running `claude`) to a
  * connected browser-side xterm.js. Two gates protect the channel:
@@ -119,33 +145,13 @@ export async function startServeServer(opts) {
             ws.send('READY\n');
             return;
         }
-        let pty;
+        let p;
         try {
-            // Lazy require — keeps `paris serve --help` working even if the native
-            // node-pty binary failed to compile/install on this platform.
-            const req = createRequire(import.meta.url);
-            ensureSpawnHelperExecutable(req);
-            const ptyMod = req('node-pty');
-            const shell = process.env.SHELL || (process.platform === 'win32' ? 'powershell.exe' : 'bash');
-            // Auto-start the coach: launch `claude` with an initial prompt so the
-            // student opens the terminal to Claude ALREADY running the course (it
-            // speaks first), instead of an idle prompt. The SessionStart hook has
-            // already injected the immersion/day/task context; the kickoff just tells
-            // Claude to begin now without waiting for input.
-            const shellArgs = process.platform === 'win32'
-                ? ['-NoLogo', '-Command', `claude "${COACH_KICKOFF.replace(/"/g, '`"')}"`]
-                : ['-l', '-c', `claude '${COACH_KICKOFF.replace(/'/g, `'\\''`)}'`];
-            pty = ptyMod.spawn(shell, shellArgs, {
-                name: 'xterm-color',
-                cols: 80,
-                rows: 24,
-                cwd: opts.cwd ?? process.cwd(),
-                env: {
-                    ...process.env,
-                    TOSTUDY_MCP_ENABLED: '1',
-                    PARIS_MCP_ENABLED: '1',
-                },
-            });
+            // Lazy require inside spawnCoachPty — keeps `paris serve --help` working
+            // even if the native node-pty binary failed to compile on this platform.
+            // The coach starts immediately (claude '/tostudy') so the student opens to
+            // Claude already running the course instead of an idle prompt.
+            p = spawnCoachPty(opts.cwd ?? process.cwd());
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -153,7 +159,6 @@ export async function startServeServer(opts) {
             ws.close(1011, 'pty_unavailable');
             return;
         }
-        const p = pty;
         p.onData((d) => {
             try {
                 ws.send(d);
@@ -280,9 +285,32 @@ export async function serveCommand(opts) {
     console.log(c.bold('paris serve'));
     console.log(`  ${c.green('✓')} WebSocket em ${c.bold(`ws://localhost:${handle.port}`)}`);
     console.log(`  ${c.dim('origens permitidas:')} ${allowedOrigins.join(', ')}`);
+    // Relay (prod): a página em HTTPS não consegue abrir ws://localhost (mixed
+    // content / PNA), então também ficamos disponíveis via wss no relay. É
+    // best-effort: sem relay configurado na API, isto é no-op e o modo local
+    // (ws://localhost, usado pela web em http://localhost:3010) segue normal.
+    let relay = null;
+    void startRelayAgent({
+        apiUrl,
+        loginToken: token,
+        cwd,
+        log: (m) => console.log(`  ${c.dim(m)}`),
+    })
+        .then((h) => {
+        relay = h;
+        if (h)
+            console.log(`  ${c.green('✓')} relay ativo (terminal embutido funciona via HTTPS)`);
+    })
+        .catch(() => { });
     console.log(`  ${c.dim('Ctrl+C pra encerrar.')}`);
     console.log();
     const shutdown = () => {
+        try {
+            relay?.close();
+        }
+        catch {
+            /* noop */
+        }
         handle.close();
         process.exit(0);
     };

package/dist/index.js

@@ -12,7 +12,7 @@ import { serveCommand } from './commands/serve.js';
 const program = new Command()
     .name('paris')
     .description('Paris Immersion — CLI do aluno (login, workspace, tarefas)')
-    .version('0.1.0');
+    .version('0.1.3');
 program
     .command('login')
     .description('Autenticar com sua conta Paris (device-code OR --token direto)')

package/dist/lib/relay-agent.d.ts

@@ -0,0 +1,14 @@
+export interface RelayAgentHandle {
+    close: () => void;
+}
+/**
+ * Inicia o agente relay. Busca o serve-token + info do relay na API (Bearer
+ * creds.token), e se o relay estiver configurado, mantém a conexão wss e spawna
+ * o pty quando um viewer entra. Retorna null quando não há relay (modo local-only).
+ */
+export declare function startRelayAgent(opts: {
+    apiUrl: string;
+    loginToken: string;
+    cwd: string;
+    log?: (msg: string) => void;
+}): Promise<RelayAgentHandle | null>;

package/dist/lib/relay-agent.js

@@ -0,0 +1,193 @@
+/**
+ * Relay agent — o lado `paris serve` do terminal embutido quando a página roda
+ * em HTTPS (prod). Em vez do browser conectar `ws://localhost` (bloqueado por
+ * mixed content / PNA), o serve disca PRA FORA num relay `wss://` e o browser
+ * conecta no mesmo relay. O relay só casa a sala (= participantId) e encaminha
+ * frames BINÁRIOS cifrados E2E — nunca tem a chave.
+ *
+ * Protocolo: docs/superpowers/specs/2026-06-01-embedded-terminal-relay-e2e-design.md
+ */
+import crypto from 'node:crypto';
+import { WebSocket } from 'ws';
+import { spawnCoachPty } from '../commands/serve.js';
+const TYPE_DATA = 0x00;
+const TYPE_RESIZE = 0x01;
+/** plaintext = type(1) || body → frame = nonce(12) || AES-256-GCM(enc||tag). */
+function seal(key, type, body) {
+    const nonce = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, nonce);
+    const enc = Buffer.concat([cipher.update(Buffer.concat([Buffer.from([type]), body])), cipher.final()]);
+    return Buffer.concat([nonce, enc, cipher.getAuthTag()]);
+}
+function open(key, frame) {
+    try {
+        if (frame.length < 12 + 16)
+            return null;
+        const nonce = frame.subarray(0, 12);
+        const tag = frame.subarray(frame.length - 16);
+        const enc = frame.subarray(12, frame.length - 16);
+        const decipher = crypto.createDecipheriv('aes-256-gcm', key, nonce);
+        decipher.setAuthTag(tag);
+        const pt = Buffer.concat([decipher.update(enc), decipher.final()]);
+        return { type: pt[0], body: pt.subarray(1) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Inicia o agente relay. Busca o serve-token + info do relay na API (Bearer
+ * creds.token), e se o relay estiver configurado, mantém a conexão wss e spawna
+ * o pty quando um viewer entra. Retorna null quando não há relay (modo local-only).
+ */
+export async function startRelayAgent(opts) {
+    if (!opts.apiUrl || !opts.loginToken)
+        return null;
+    const log = opts.log ?? (() => { });
+    let info;
+    try {
+        const res = await fetch(`${opts.apiUrl.replace(/\/$/, '')}/api/onboarding/v2/serve-token`, {
+            headers: { authorization: `Bearer ${opts.loginToken}` },
+            signal: AbortSignal.timeout(8000),
+        });
+        if (!res.ok)
+            return null;
+        info = (await res.json());
+    }
+    catch {
+        return null;
+    }
+    const { token, relayUrl, e2eKeyB64 } = info;
+    if (!relayUrl || !token || !e2eKeyB64)
+        return null; // relay não configurado → local-only
+    const key = Buffer.from(e2eKeyB64, 'base64');
+    if (key.length !== 32)
+        return null;
+    let ws = null;
+    let pty;
+    let closed = false;
+    let reconnect;
+    let killTimer;
+    // Mantém o Claude vivo por uma janela após o viewer sair, pra que uma
+    // reconexão (ex.: Safari derruba o ws periodicamente) REATACHE na MESMA sessão
+    // em vez de reiniciar o curso. O resize que o viewer manda ao reconectar faz a
+    // TUI do Claude repintar a tela atual.
+    const PTY_GRACE_MS = 60_000;
+    const killPty = () => {
+        if (pty) {
+            try {
+                pty.kill();
+            }
+            catch {
+                /* noop */
+            }
+            pty = undefined;
+        }
+    };
+    const startPty = () => {
+        if (pty)
+            return; // já tem Claude vivo — não reinicia (reatacha)
+        try {
+            pty = spawnCoachPty(opts.cwd);
+        }
+        catch (err) {
+            log(`relay: pty spawn falhou (${err instanceof Error ? err.message : String(err)})`);
+            return;
+        }
+        pty.onData((d) => {
+            if (ws && ws.readyState === WebSocket.OPEN) {
+                try {
+                    ws.send(seal(key, TYPE_DATA, Buffer.from(d, 'utf8')), { binary: true });
+                }
+                catch {
+                    /* ws caiu no meio */
+                }
+            }
+        });
+        pty.onExit?.(() => killPty());
+    };
+    const connect = () => {
+        if (closed)
+            return;
+        const url = `${relayUrl.replace(/\/$/, '')}/agent?token=${encodeURIComponent(token)}`;
+        ws = new WebSocket(url);
+        ws.on('open', () => log(`relay: conectado (${relayUrl})`));
+        ws.on('message', (data, isBinary) => {
+            if (!isBinary) {
+                // Controle do relay (texto): viewer-joined / viewer-left.
+                try {
+                    const m = JSON.parse(data.toString());
+                    if (m.t === 'viewer-joined') {
+                        if (killTimer) {
+                            clearTimeout(killTimer);
+                            killTimer = undefined;
+                        }
+                        startPty(); // no-op se já tem Claude vivo → reatacha na mesma sessão
+                    }
+                    else if (m.t === 'viewer-left') {
+                        // Não mata na hora — janela de graça pra reconexão reatachar.
+                        if (killTimer)
+                            clearTimeout(killTimer);
+                        killTimer = setTimeout(() => {
+                            killTimer = undefined;
+                            killPty();
+                        }, PTY_GRACE_MS);
+                    }
+                }
+                catch {
+                    /* frame de controle malformado — ignora */
+                }
+                return;
+            }
+            // Frame E2E do viewer (stdin/resize) — decifra e aplica no pty.
+            const msg = open(key, data);
+            if (!msg || !pty)
+                return;
+            if (msg.type === TYPE_DATA) {
+                pty.write(msg.body.toString('utf8'));
+            }
+            else if (msg.type === TYPE_RESIZE) {
+                const [cols, rows] = msg.body.toString('utf8').split(',').map(Number);
+                if (Number.isFinite(cols) && Number.isFinite(rows)) {
+                    try {
+                        pty.resize(cols, rows);
+                    }
+                    catch {
+                        /* race de resize */
+                    }
+                }
+            }
+        });
+        ws.on('close', () => {
+            // NÃO mata o pty aqui — mantém o Claude vivo pra reatachar quando o ws
+            // reconectar (o viewer-left + grace timer e o shutdown cuidam de matar).
+            if (!closed)
+                reconnect = setTimeout(connect, 2000);
+        });
+        ws.on('error', () => {
+            try {
+                ws?.close();
+            }
+            catch {
+                /* noop */
+            }
+        });
+    };
+    connect();
+    return {
+        close: () => {
+            closed = true;
+            if (reconnect)
+                clearTimeout(reconnect);
+            if (killTimer)
+                clearTimeout(killTimer);
+            killPty();
+            try {
+                ws?.close();
+            }
+            catch {
+                /* noop */
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paris-immersion",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Paris Immersion CLI — login, install workspace, status, task control. Para alunos das imersões da Paris Group.",
   "homepage": "https://parisgroup.ai",
   "repository": {