paris-immersion 0.1.13 → 0.1.15

package/dist/commands/install.js

@@ -10,6 +10,7 @@ import { renderClaudeMd } from '../templates/claude-md.js';
 import { renderSettingsJson } from '../templates/settings.js';
 import { renderParisCoachSkill } from '../templates/skill.js';
 import { renderHookScript } from '../templates/hook.js';
+import { renderTostudyCommand } from '../templates/tostudy-command.js';
 export async function installCommand(opts) {
     const creds = await readCredentials();
     if (!creds) {
@@ -89,6 +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());
+    // /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.d.ts

@@ -38,11 +38,6 @@ export interface ServeHandle {
     close: () => void;
 }
 export declare function resolveKickoff(cwd: string): string;
-/**
- * Spawn the coached pty (`claude '/tostudy-<curso>'` 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

package/dist/commands/serve.js

@@ -1,11 +1,12 @@
 import { WebSocketServer } from 'ws';
 import { createRequire } from 'node:module';
-import { promises as fs, chmodSync, existsSync, statSync, readdirSync, readFileSync } from 'node:fs';
+import { promises as fs, chmodSync, existsSync, statSync, readdirSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 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 { c } from '../lib/colors.js';
 /**
  * Restore the executable bit on node-pty's `spawn-helper`. Some install paths
@@ -119,6 +120,10 @@ export function resolveKickoff(cwd) {
     if (names.size === 0)
         return COURSE_TUTOR_PROMPT;
     const all = [...names];
+    // Nosso /tostudy (escrito pelo install/serve, sempre presente) é a rota
+    // CONFIÁVEL — preferimos ele: o aluno e o tutor sempre rodam via /tostudy.
+    if (all.some((n) => n.toLowerCase() === 'tostudy'))
+        return '/tostudy';
     // Curso ATIVO deste workspace = fonte da verdade pra escolher entre vários cursos.
     let slug = '';
     try {
@@ -148,10 +153,34 @@ export function resolveKickoff(cwd) {
  * 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.
  */
+/**
+ * Garante que o slash-command `/tostudy` exista no workspace ANTES do Claude
+ * subir (slash-commands carregam no startup — criados depois não aparecem sem
+ * reload). O `paris install` já escreve, mas reescrevemos aqui pra cobrir
+ * workspaces antigos e manter o conteúdo fresco a cada serve. Best-effort.
+ */
+function ensureTostudyCommand(cwd) {
+    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) {
     const req = createRequire(import.meta.url);
     ensureSpawnHelperExecutable(req);
     const ptyMod = req('node-pty');
+    // Escreve /tostudy ANTES de resolver o kickoff + subir o Claude.
+    ensureTostudyCommand(cwd);
     const kickoff = resolveKickoff(cwd);
     const shell = process.env.SHELL || (process.platform === 'win32' ? 'powershell.exe' : 'bash');
     const shellArgs = process.platform === 'win32'
@@ -214,6 +243,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');

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.13');
+    .version('0.1.15');
 program
     .command('login')
     .description('Autenticar com sua conta Paris (device-code OR --token direto)')

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.

package/dist/templates/hook.js

@@ -139,7 +139,7 @@ async function main() {
   if (inCourse) {
     lines.push('## FASE DO CURSO DE ONBOARDING')
     lines.push('O aluno está na etapa do curso **' + course.title + '** (progresso: **' + course.lessonsCompleted + '/' + course.totalLessons + '**).')
-    lines.push('Conduza o curso da ToStudy DIRETO pela CLI (o aluno já chega logado no install): rode no bash **tostudy courses --json**, depois **tostudy select <id>** pra ativar o curso, e ensine lição por lição com **tostudy next** / **tostudy progress** / **tostudy lesson** / **tostudy hint**. Se existir um slash-command **/tostudy-<curso>**, pode usá-lo. NÃO trabalhe em missões da imersão enquanto o curso não terminar. (Fallback: ferramentas MCP **get_course**/**complete_lesson** do paris.)')
+    lines.push('Rode **/tostudy** pra conduzir o curso da ToStudy (o comando está instalado no workspace e o aluno já chega logado). Ele ativa o curso e ensina lição por lição. NÃO trabalhe em missões da imersão enquanto o curso não terminar. (Fallback: ferramentas MCP **get_course**/**complete_lesson** do paris.)')
     if (PHASE === 'session-start') {
       lines.push('')
       lines.push('**Comece falando primeiro**: rode /tostudy e dê as boas-vindas. O aluno ainda não digitou nada.')

package/dist/templates/tostudy-command.d.ts

@@ -0,0 +1,10 @@
+/**
+ * O slash-command `/tostudy` que O NOSSO LADO escreve no workspace
+ * (`<ws>/.claude/commands/tostudy.md`). É a rota CONFIÁVEL pra iniciar o curso:
+ * o `@tostudy-ai/cli` só instala um comando específico do curso (`/tostudy-<slug>`)
+ * SE rodar `init` — e mesmo então, se o Claude já tinha subido, ele não recarrega
+ * slash-commands. Escrevendo `/tostudy` nós mesmos (no `paris install` E no
+ * `paris serve`, antes do Claude subir), garantimos que `/tostudy` SEMPRE exista
+ * e SEMPRE funcione, conduzindo o curso real via a tostudy CLI.
+ */
+export declare function renderTostudyCommand(): string;

package/dist/templates/tostudy-command.js

@@ -0,0 +1,37 @@
+/**
+ * O slash-command `/tostudy` que O NOSSO LADO escreve no workspace
+ * (`<ws>/.claude/commands/tostudy.md`). É a rota CONFIÁVEL pra iniciar o curso:
+ * o `@tostudy-ai/cli` só instala um comando específico do curso (`/tostudy-<slug>`)
+ * SE rodar `init` — e mesmo então, se o Claude já tinha subido, ele não recarrega
+ * slash-commands. Escrevendo `/tostudy` nós mesmos (no `paris install` E no
+ * `paris serve`, antes do Claude subir), garantimos que `/tostudy` SEMPRE exista
+ * e SEMPRE funcione, conduzindo o curso real via a tostudy CLI.
+ */
+export function renderTostudyCommand() {
+    return `---
+description: Inicia ou retoma o curso de onboarding da imersão (tutor ToStudy no terminal)
+---
+
+Você é o **tutor do curso de onboarding** da imersão Paris Group, rodando no terminal do aluno. Conduza o curso da ToStudy em **português**, no ritmo do aluno. O aluno já chega logado na conta dele da ToStudy (auto-login no install).
+
+## 1. Prepare o curso (em silêncio, antes de falar)
+
+1. Rode \`tostudy courses --json\` para ver o curso em que o aluno está matriculado.
+2. Rode \`tostudy select <id-ou-número-do-curso>\` para ativá-lo (escolha o curso da imersão; normalmente só há um).
+3. Rode \`tostudy progress --json\` para ver onde ele parou.
+
+## 2. Ensine lição por lição
+
+- \`tostudy next\` — avança para a próxima lição (marca a atual como concluída).
+- \`tostudy lesson\` / \`tostudy theory\` — conteúdo da lição atual.
+- \`tostudy hint\` — dica progressiva quando o aluno travar.
+- \`tostudy validate\` — valida exercícios.
+- \`tostudy progress\` — status atual (lição X de Y, %).
+
+Explique cada lição com suas palavras, traga exemplos do contexto de negócio do aluno e só avance quando ele entender. **Comece dando as boas-vindas** e já ensinando a primeira lição — o aluno ainda não digitou nada. NÃO trabalhe em missões da imersão enquanto o curso não terminar.
+
+## 3. Fallback (se a ToStudy não estiver disponível)
+
+Use as ferramentas MCP do paris: \`get_course\` (currículo + progresso) e \`complete_lesson\` (marcar lição concluída).
+`;
+}

package/package.json

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