paris-immersion 0.1.11 → 0.1.13

package/dist/commands/daemon.d.ts

@@ -4,3 +4,10 @@
  * instalador chama `install`; o `paris logout` chama `uninstall`.
  */
 export declare function daemonCommand(action: string): Promise<void>;
+/**
+ * `paris restart` — religa o agente do terminal embutido. Sempre dá certo:
+ * libera a porta (mata serve preso) e reinstala/reinicia o serviço persistente,
+ * que sobe um serve NOVO com serve-token fresco e reconecta ao relay. É o comando
+ * que a UI do curso oferece quando o terminal não conecta sozinho.
+ */
+export declare function restartCommand(): Promise<void>;

package/dist/commands/daemon.js

@@ -1,4 +1,4 @@
-import { installDaemon, uninstallDaemon, daemonStatus } from '../lib/daemon.js';
+import { installDaemon, uninstallDaemon, daemonStatus, restartDaemon } from '../lib/daemon.js';
 import { c } from '../lib/colors.js';
 /**
  * `paris daemon <install|uninstall|status>` — gerencia o serviço persistente
@@ -33,3 +33,22 @@ export async function daemonCommand(action) {
     console.log(c.yellow("Uso: paris daemon <install|uninstall|status>"));
     process.exitCode = 1;
 }
+/**
+ * `paris restart` — religa o agente do terminal embutido. Sempre dá certo:
+ * libera a porta (mata serve preso) e reinstala/reinicia o serviço persistente,
+ * que sobe um serve NOVO com serve-token fresco e reconecta ao relay. É o comando
+ * que a UI do curso oferece quando o terminal não conecta sozinho.
+ */
+export async function restartCommand() {
+    try {
+        process.stdout.write(c.dim('Religando o agente do terminal embutido…\n'));
+        const { mechanism } = await restartDaemon();
+        console.log(c.green('✓ Agente reiniciado.') + c.dim(` (${mechanism})`));
+        console.log(c.dim('  Volte para a aba do curso — o terminal reconecta sozinho em alguns segundos.'));
+    }
+    catch (err) {
+        console.log(c.yellow(`! Não consegui reiniciar o serviço: ${err instanceof Error ? err.message : String(err)}`));
+        console.log(c.dim('  Tente: paris daemon install'));
+        process.exitCode = 1;
+    }
+}

package/dist/commands/serve.d.ts

@@ -37,15 +37,6 @@ export interface ServeHandle {
     port: number;
     close: () => void;
 }
-/**
- * Descobre o slash-command do tutor pra injetar no kickoff. O `@tostudy-ai/cli`
- * instala o comando com nome ESPECÍFICO do curso (`.claude/commands/tostudy-<slug>.md`),
- * NÃO `/tostudy` — então cravar `/tostudy` dava "Unknown command: /tostudy" e o
- * curso não iniciava. Aqui varremos `.claude/commands/tostudy*.md` e usamos o
- * comando real; com vários cursos, casamos com o `slug` ativo do
- * `.tostudy/workspace.json`. Override explícito via PARIS_COACH_KICKOFF.
- * Fallback `/tostudy` (legado / antes do `tostudy` instalar o comando).
- */
 export declare function resolveKickoff(cwd: string): string;
 /**
  * Spawn the coached pty (`claude '/tostudy-<curso>'` inside the provisioned

package/dist/commands/serve.js

@@ -79,6 +79,21 @@ const DEFAULT_ALLOWED_ORIGINS = [
  * `.tostudy/workspace.json`. Override explícito via PARIS_COACH_KICKOFF.
  * Fallback `/tostudy` (legado / antes do `tostudy` instalar o comando).
  */
+// Fallback ROBUSTO quando o slash-command `/tostudy-<slug>` não existe (o
+// `@tostudy-ai/cli` não rodou `init` no workspace, ou rodou DEPOIS do Claude
+// subir — slash-commands carregam no startup, então um comando criado depois dá
+// "Unknown command: /tostudy"). Em vez de cravar `/tostudy` (que erra), passamos
+// um prompt de tutor em TEXTO: o Claude conduz o curso direto pela tostudy CLI
+// (select/next/progress), sem depender de nenhum comando instalado. Sem apóstrofo
+// no texto (o kickoff vai dentro de aspas simples no shell).
+const COURSE_TUTOR_PROMPT = 'Você é o tutor do curso de onboarding da imersão Paris Group, rodando no terminal do aluno. ' +
+    'Comece AGORA falando primeiro, em português — o aluno ainda não digitou nada. ' +
+    'Antes de ensinar, prepare o curso da ToStudy em silêncio: rode no bash "tostudy courses --json" para ver o curso matriculado; ' +
+    'rode "tostudy select <id-ou-número-do-curso>" para ativá-lo; e "tostudy progress --json" para ver onde o aluno parou. ' +
+    'Depois conduza lição por lição, no ritmo do aluno, usando: "tostudy next" (avançar), "tostudy lesson" e "tostudy theory" (conteúdo da lição), ' +
+    '"tostudy hint" (dica) e "tostudy progress" (status). ' +
+    'Se o tostudy não estiver disponível ou sem curso ativo, use as ferramentas MCP get_course e complete_lesson do paris como fallback. ' +
+    'Dê as boas-vindas e já comece a primeira lição.';
 export function resolveKickoff(cwd) {
     const override = process.env.PARIS_COACH_KICKOFF;
     if (override)
@@ -102,7 +117,7 @@ export function resolveKickoff(cwd) {
         }
     }
     if (names.size === 0)
-        return '/tostudy';
+        return COURSE_TUTOR_PROMPT;
     const all = [...names];
     // Curso ATIVO deste workspace = fonte da verdade pra escolher entre vários cursos.
     let slug = '';
@@ -126,7 +141,7 @@ export function resolveKickoff(cwd) {
     const courseSpecific = all.filter((n) => /^tostudy-.+/i.test(n)).sort();
     if (courseSpecific.length)
         return '/' + courseSpecific[0];
-    return '/tostudy';
+    return COURSE_TUTOR_PROMPT;
 }
 /**
  * Spawn the coached pty (`claude '/tostudy-<curso>'` inside the provisioned
@@ -337,6 +352,16 @@ export async function serveCommand(opts) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
+        // EADDRINUSE não é erro: o serviço em background (daemon) já tem um `paris
+        // serve` segurando a porta. Não precisa rodar de novo — o terminal embutido
+        // conecta no que já está rodando. Se ele NÃO conectar, é melhor reiniciar
+        // (religa com serve-token fresco) do que falhar com vermelho assustador.
+        if (/EADDRINUSE/i.test(msg)) {
+            console.log(c.green('✓ paris já está rodando') + c.dim(` (porta ${portNum} em uso pelo serviço em background).`));
+            console.log(c.dim('  O terminal do curso conecta no agente que já está ativo.'));
+            console.log(c.dim('  Se o terminal não conectar, rode: ') + c.bold('paris restart'));
+            process.exit(0);
+        }
         console.error(c.red(`Falha ao iniciar paris serve: ${msg}`));
         process.exit(1);
     }

package/dist/index.js

@@ -9,11 +9,11 @@ import { reopenCommand } from './commands/reopen.js';
 import { graduateCommand } from './commands/graduate.js';
 import { logoutCommand } from './commands/logout.js';
 import { serveCommand } from './commands/serve.js';
-import { daemonCommand } from './commands/daemon.js';
+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.11');
+    .version('0.1.13');
 program
     .command('login')
     .description('Autenticar com sua conta Paris (device-code OR --token direto)')
@@ -61,6 +61,10 @@ program
     .command('daemon <action>')
     .description('Serviço persistente do paris serve (install | uninstall | status)')
     .action(daemonCommand);
+program
+    .command('restart')
+    .description('Religa o agente do terminal embutido (libera a porta + reinicia o serviço). Use se o terminal não conectar.')
+    .action(restartCommand);
 program.parseAsync().catch((err) => {
     console.error('\n[paris] erro:', err?.message ?? err);
     process.exit(1);

package/dist/lib/daemon.d.ts

@@ -4,3 +4,18 @@ export declare function installDaemon(): Promise<{
 /** Best-effort — nunca lança (usado no logout, não pode travar). */
 export declare function uninstallDaemon(): Promise<void>;
 export declare function daemonStatus(): Promise<boolean>;
+/**
+ * Mata, best-effort, qualquer processo escutando na porta do serve (default
+ * 31000). Cobre o caso de um `paris serve` "preso" (manual ou daemon zumbi)
+ * segurando a porta — origem do `EADDRINUSE` e do terminal que não conecta.
+ */
+export declare function killServePort(port?: number): Promise<void>;
+/**
+ * Reinicia o agente do terminal embutido de forma que SEMPRE dá certo: libera a
+ * porta (mata serve preso) e re-registra o serviço persistente (que sobe um serve
+ * NOVO — com serve-token fresco, reconectando ao relay). É o que o comando
+ * copiável da UI roda quando o terminal não conecta sozinho.
+ */
+export declare function restartDaemon(port?: number): Promise<{
+    mechanism: string;
+}>;

package/dist/lib/daemon.js

@@ -244,3 +244,46 @@ export async function daemonStatus() {
             return false;
     }
 }
+/**
+ * Mata, best-effort, qualquer processo escutando na porta do serve (default
+ * 31000). Cobre o caso de um `paris serve` "preso" (manual ou daemon zumbi)
+ * segurando a porta — origem do `EADDRINUSE` e do terminal que não conecta.
+ */
+export async function killServePort(port = 31000) {
+    try {
+        if (platform() === 'win32') {
+            await execFileAsync('powershell', [
+                '-NoProfile',
+                '-Command',
+                `Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue | ` +
+                    `Select-Object -ExpandProperty OwningProcess -Unique | ` +
+                    `ForEach-Object { Stop-Process -Id $_ -Force -ErrorAction SilentlyContinue }`,
+            ]).catch(() => { });
+            return;
+        }
+        // macOS / Linux: lsof → PIDs escutando na porta → kill.
+        const { stdout } = await execFileAsync('lsof', ['-ti', `tcp:${port}`, '-sTCP:LISTEN']).catch(() => ({ stdout: '' }));
+        const pids = stdout
+            .split('\n')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        for (const pid of pids) {
+            await execFileAsync('kill', ['-TERM', pid]).catch(() => { });
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Reinicia o agente do terminal embutido de forma que SEMPRE dá certo: libera a
+ * porta (mata serve preso) e re-registra o serviço persistente (que sobe um serve
+ * NOVO — com serve-token fresco, reconectando ao relay). É o que o comando
+ * copiável da UI roda quando o terminal não conecta sozinho.
+ */
+export async function restartDaemon(port = 31000) {
+    await killServePort(port);
+    // pequena folga pro SO liberar o socket antes do novo bind
+    await new Promise((r) => setTimeout(r, 600));
+    return installDaemon();
+}

package/dist/lib/relay-agent.js

@@ -45,23 +45,40 @@ 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)
+    const fetchInfo = async () => {
+        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;
+            return (await res.json());
+        }
+        catch {
             return null;
-        info = (await res.json());
+        }
+    };
+    // Primeira busca decide se o relay está configurado (senão → modo local-only).
+    // Retry só quando a API está inalcançável (fetchInfo → null): cobre o blip de
+    // rede no boot (o daemon sobe antes da rede) sem penalizar o dev local (a API
+    // responde 200 na 1ª tentativa). KeepAlive mantém o serve, mas sem este retry o
+    // agente relay nunca subia se a 1ª busca caísse no boot.
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    let initial = await fetchInfo();
+    for (let i = 0; i < 6 && !initial; i++) {
+        await sleep(5000);
+        initial = await fetchInfo();
     }
-    catch {
+    if (!initial || !initial.relayUrl || !initial.token || !initial.e2eKeyB64)
         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');
+    // Mutáveis: o serve-token é de vida curta e é RENOVADO a cada (re)conexão (o
+    // loginToken/JWT do aluno é estável). Sem isso, o daemon que sobe no boot fica
+    // preso com um token expirado, o relay rejeita o agente, e o terminal embutido
+    // fica "Esperando o paris CLI subir" pra sempre mesmo com o serve rodando.
+    let relayUrl = initial.relayUrl;
+    let token = initial.token;
+    let key = Buffer.from(initial.e2eKeyB64, 'base64'); // chave E2E é estável por participante
     if (key.length !== 32)
         return null;
     let ws = null;
@@ -167,7 +184,19 @@ export async function startRelayAgent(opts) {
             }
         }, 80);
     };
-    const connect = () => {
+    const connect = async () => {
+        if (closed)
+            return;
+        // Renova token + relayUrl + chave a cada tentativa (o serve-token expira;
+        // o loginToken é estável). É isto que conserta o "agente preso no boot".
+        const fresh = await fetchInfo();
+        if (fresh?.relayUrl && fresh.token && fresh.e2eKeyB64) {
+            relayUrl = fresh.relayUrl;
+            token = fresh.token;
+            const k = Buffer.from(fresh.e2eKeyB64, 'base64');
+            if (k.length === 32)
+                key = k;
+        }
         if (closed)
             return;
         const url = `${relayUrl.replace(/\/$/, '')}/agent?token=${encodeURIComponent(token)}`;

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('Rode a skill **/tostudy** (o tutor da ToStudy) pra conduzir o curso — o aluno já chega logado na conta dele da ToStudy (auto-login no install). NÃO trabalhe em missões da imersão enquanto o curso não terminar. (Fallback: se a ToStudy não estiver disponível, use as ferramentas MCP **get_course**/**complete_lesson** do paris.)')
+    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.)')
     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/package.json

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