paris-immersion 0.1.14 → 0.1.16

package/dist/commands/install.js

@@ -90,11 +90,15 @@ async function writeWorkspaceFiles(targetDir, boot, apiUrl, email) {
     const skillDir = path.join(claudeDir, 'skills', 'paris-coach');
     await fs.mkdir(skillDir, { recursive: true });
     await fs.writeFile(path.join(skillDir, 'SKILL.md'), renderParisCoachSkill());
-    // .claude/commands/tostudy.md — NOSSO slash-command /tostudy (rota confiável do
-    // curso). Garante que /tostudy sempre exista, independente do @tostudy-ai/cli.
-    const commandsDir = path.join(claudeDir, 'commands');
-    await fs.mkdir(commandsDir, { recursive: true });
-    await fs.writeFile(path.join(commandsDir, 'tostudy.md'), renderTostudyCommand());
+    // /tostudy.md — NOSSO slash-command (rota confiável do curso). Escrito nos DOIS
+    // lugares que o Claude carrega: o do PROJETO e o GLOBAL (~/.claude/commands) —
+    // o global é o que faz funcionar em máquinas que já rodaram `tostudy init`, e
+    // agora vale pra todo aluno novo também. Independe do @tostudy-ai/cli.
+    const tostudyCmd = renderTostudyCommand();
+    for (const dir of [path.join(claudeDir, 'commands'), path.join(homedir(), '.claude', 'commands')]) {
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(path.join(dir, 'tostudy.md'), tostudyCmd);
+    }
     // CLAUDE.md — workspace-level rules.
     await fs.writeFile(path.join(targetDir, 'CLAUDE.md'), renderClaudeMd({
         immersionName: boot.immersion.name,

package/dist/commands/serve.js

@@ -7,6 +7,7 @@ import { readCredentials } from '../lib/credentials.js';
 import { ensureWorkspace } from './install.js';
 import { startRelayAgent } from '../lib/relay-agent.js';
 import { renderTostudyCommand } from '../templates/tostudy-command.js';
+import { maybeSelfUpdate } from '../lib/self-update.js';
 import { c } from '../lib/colors.js';
 /**
  * Restore the executable bit on node-pty's `spawn-helper`. Some install paths
@@ -160,13 +161,19 @@ export function resolveKickoff(cwd) {
  * workspaces antigos e manter o conteúdo fresco a cada serve. Best-effort.
  */
 function ensureTostudyCommand(cwd) {
-    try {
-        const dir = path.join(cwd, '.claude', 'commands');
-        mkdirSync(dir, { recursive: true });
-        writeFileSync(path.join(dir, 'tostudy.md'), renderTostudyCommand());
-    }
-    catch {
-        /* best-effort — se falhar, o resolveKickoff cai no fallback de texto */
+    const body = renderTostudyCommand();
+    // Escreve nos DOIS lugares que o Claude Code carrega slash-commands: o do
+    // PROJETO (workspace) e o GLOBAL (~/.claude/commands). É justamente o comando
+    // global que faz o terminal funcionar em máquinas que já passaram por um
+    // `tostudy init` — replicamos isso pra TODA máquina, inclusive a do aluno novo.
+    for (const dir of [path.join(cwd, '.claude', 'commands'), path.join(homedir(), '.claude', 'commands')]) {
+        try {
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(path.join(dir, 'tostudy.md'), body);
+        }
+        catch {
+            /* best-effort — se um falhar, o outro cobre; senão cai no fallback de texto */
+        }
     }
 }
 export function spawnCoachPty(cwd) {
@@ -237,6 +244,11 @@ export async function startServeServer(opts) {
         wss.once('error', reject);
     });
     wss.on('connection', (ws) => {
+        // TCP_NODELAY: sem Nagle no socket local (caminho dev ws://localhost).
+        try {
+            ws._socket?.setNoDelay?.(true);
+        }
+        catch { /* noop */ }
         if (opts.dryRun) {
             // Tests use this branch — we just confirm the handshake passed.
             ws.send('READY\n');
@@ -329,6 +341,12 @@ export async function serveCommand(opts) {
         console.error(c.red('Não logado.') + ' Rode: ' + c.bold('paris login'));
         process.exit(1);
     }
+    // Auto-update no startup (throttle 3h): o aluno NUNCA roda comando de update à
+    // mão. Se há versão nova no npm, atualiza ANTES de servir e sai — o daemon
+    // (launchd/systemd KeepAlive) respawna na versão nova. Best-effort.
+    if (await maybeSelfUpdate((m) => console.log(`  ${c.dim(m)}`))) {
+        process.exit(0);
+    }
     const portNum = opts.port == null ? 31000 : Number(opts.port);
     if (!Number.isFinite(portNum) || portNum < 0 || portNum > 65535) {
         console.error(c.red(`Porta inválida: ${opts.port}`));
@@ -411,8 +429,11 @@ export async function serveCommand(opts) {
         .catch(() => { });
     console.log(`  ${c.dim('Ctrl+C pra encerrar.')}`);
     console.log();
+    let updateTimer;
     const shutdown = () => {
         try {
+            if (updateTimer)
+                clearInterval(updateTimer);
             relay?.close();
         }
         catch {
@@ -421,6 +442,18 @@ export async function serveCommand(opts) {
         handle.close();
         process.exit(0);
     };
+    // Auto-update periódico: a cada 3h, SE não houver sessão do curso em uso, se
+    // atualiza e reinicia (o daemon respawna na versão nova) — sem ninguém rodar
+    // nada. Gate por isBusy() pra nunca interromper o aluno no meio do curso.
+    updateTimer = setInterval(() => {
+        if (relay?.isBusy())
+            return;
+        void maybeSelfUpdate((m) => console.log(`  ${c.dim(m)}`)).then((updated) => {
+            if (updated)
+                shutdown();
+        });
+    }, 3 * 3600_000);
+    updateTimer.unref?.();
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
 }

package/dist/index.js

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

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

@@ -1,5 +1,7 @@
 export interface RelayAgentHandle {
     close: () => void;
+    /** true se há uma sessão do Claude viva (pty) — usado pra não auto-atualizar/reiniciar no meio do curso. */
+    isBusy: () => boolean;
 }
 /**
  * Inicia o agente relay. Busca o serve-token + info do relay na API (Bearer

package/dist/lib/relay-agent.js

@@ -100,12 +100,20 @@ export async function startRelayAgent(opts) {
     const MAX_OUT_BUF = 256 * 1024;
     let outBuf = '';
     let flushTimer;
+    // Adaptativo: o PRIMEIRO chunk de uma rajada (depois de um período de silêncio)
+    // sai NA HORA — o eco de uma tecla e o início da resposta do Claude não pagam a
+    // janela inteira de coalescing. Só a CAUDA da rajada (tokens que chegam dentro
+    // da janela, streaming token-a-token) é coalescida, mantendo a escrita lisa.
+    // "Fast first byte, smooth tail." lastFlushAt marca o último envio: se passou
+    // mais de COALESCE_MS desde então E o buffer estava vazio, é um novo burst.
+    let lastFlushAt = 0;
     const flushOut = () => {
         flushTimer = undefined;
         if (!outBuf)
             return;
         const data = outBuf;
         outBuf = '';
+        lastFlushAt = Date.now();
         if (ws && ws.readyState === WebSocket.OPEN) {
             try {
                 ws.send(seal(key, TYPE_DATA, Buffer.from(data, 'utf8')), { binary: true });
@@ -147,9 +155,14 @@ export async function startRelayAgent(opts) {
             return;
         }
         pty.onData((d) => {
+            // Novo burst = buffer vazio E sem timer armado E passou >COALESCE_MS desde o
+            // último flush (= veio depois de um silêncio, p.ex. o aluno apertou Enter e o
+            // Claude começa a responder). Captura ANTES do append (depois nunca é vazio).
+            const newBurst = !outBuf && !flushTimer && Date.now() - lastFlushAt >= COALESCE_MS;
             outBuf += d;
-            // Flush imediato se acumulou muito (evita um frame gigante); senão coalesce.
-            if (outBuf.length >= MAX_OUT_BUF) {
+            // Flush imediato se acumulou muito (evita um frame gigante) OU se é o primeiro
+            // chunk de um novo burst (latência baixa pro início da resposta); senão coalesce.
+            if (outBuf.length >= MAX_OUT_BUF || newBurst) {
                 if (flushTimer) {
                     clearTimeout(flushTimer);
                     flushTimer = undefined;
@@ -201,7 +214,17 @@ export async function startRelayAgent(opts) {
             return;
         const url = `${relayUrl.replace(/\/$/, '')}/agent?token=${encodeURIComponent(token)}`;
         ws = new WebSocket(url);
-        ws.on('open', () => log(`relay: conectado (${relayUrl})`));
+        ws.on('open', () => {
+            // TCP_NODELAY: terminal interativo manda frames pequenos; sem isso o Nagle
+            // os enfileira (~40ms/hop, pior ainda com delayed-ACK) → digitação e o 1º
+            // paint de cada resposta ficam visivelmente lentos. _socket é interno do
+            // `ws` — optional-chaining + try/catch degrada pro comportamento atual se mudar.
+            try {
+                ws._socket?.setNoDelay?.(true);
+            }
+            catch { /* noop */ }
+            log(`relay: conectado (${relayUrl})`);
+        });
         ws.on('message', (data, isBinary) => {
             if (!isBinary) {
                 // Controle do relay (texto): viewer-joined / viewer-left.
@@ -282,6 +305,7 @@ export async function startRelayAgent(opts) {
     };
     connect();
     return {
+        isBusy: () => !!pty,
         close: () => {
             closed = true;
             if (reconnect)

package/dist/lib/self-update.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Se houver uma versão MAIS NOVA no npm, atualiza global e retorna true (o
+ * chamador deve `process.exit(0)` pra o daemon respawnar na nova). Throttle de 3h.
+ * `force` ignora o throttle (usado no startup; o periódico respeita o throttle).
+ */
+export declare function maybeSelfUpdate(log?: (m: string) => void, force?: boolean): Promise<boolean>;

package/dist/lib/self-update.js

@@ -0,0 +1,76 @@
+/**
+ * Self-update do `paris serve`. O aluno NUNCA deve rodar um comando de update à
+ * mão — o serve (rodando como daemon) checa o npm, se atualiza sozinho e o
+ * KeepAlive do launchd/systemd respawna no binário novo. Best-effort: qualquer
+ * falha (offline, sem permissão) é engolida e o serve segue na versão atual.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+const execFileAsync = promisify(execFile);
+const PKG = 'paris-immersion';
+const THROTTLE_MS = 3 * 3600_000; // checa no máximo a cada 3h
+function currentVersion() {
+    try {
+        const req = createRequire(import.meta.url);
+        return req('../../package.json').version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** retorna 1 se a > b, -1 se a < b, 0 se igual (semver x.y.z, ignora pré-release). */
+function cmpSemver(a, b) {
+    const pa = a.split('.').map((n) => parseInt(n, 10) || 0);
+    const pb = b.split('.').map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) > (pb[i] ?? 0))
+            return 1;
+        if ((pa[i] ?? 0) < (pb[i] ?? 0))
+            return -1;
+    }
+    return 0;
+}
+async function stampPath() {
+    const dir = path.join(homedir(), '.paris');
+    await fs.mkdir(dir, { recursive: true }).catch(() => { });
+    return path.join(dir, '.update-check');
+}
+/**
+ * Se houver uma versão MAIS NOVA no npm, atualiza global e retorna true (o
+ * chamador deve `process.exit(0)` pra o daemon respawnar na nova). Throttle de 3h.
+ * `force` ignora o throttle (usado no startup; o periódico respeita o throttle).
+ */
+export async function maybeSelfUpdate(log = () => { }, force = false) {
+    if (process.env.PARIS_NO_SELF_UPDATE)
+        return false; // escape-hatch (dev/CI/offline forçado)
+    try {
+        const stamp = await stampPath();
+        if (!force) {
+            try {
+                const last = Number(await fs.readFile(stamp, 'utf8'));
+                if (Number.isFinite(last) && Date.now() - last < THROTTLE_MS)
+                    return false;
+            }
+            catch {
+                /* sem stamp — checa */
+            }
+        }
+        await fs.writeFile(stamp, String(Date.now())).catch(() => { });
+        const { stdout } = await execFileAsync('npm', ['view', PKG, 'version'], { timeout: 15000 });
+        const latest = stdout.trim();
+        const current = currentVersion();
+        if (!/^\d+\.\d+\.\d+/.test(latest) || cmpSemver(latest, current) <= 0)
+            return false;
+        log(`nova versão da CLI: ${current} → ${latest}. Atualizando…`);
+        await execFileAsync('npm', ['install', '-g', `${PKG}@${latest}`], { timeout: 120_000 });
+        log(`atualizado para ${latest}. Reiniciando o agente…`);
+        return true;
+    }
+    catch {
+        return false; // best-effort — nunca quebra o serve
+    }
+}

package/package.json

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