paris-immersion 0.1.1 → 0.1.2

package/dist/commands/serve.d.ts

@@ -1,7 +1,17 @@
 export interface ServeOptions {
     port: number;
     allowedOrigins: string[];
+    /** The login token from ~/.paris/credentials. Accepted on the WS handshake for
+     *  backward compatibility (legacy: web sent the login token directly). */
     token: string;
+    /** API base URL — used to verify serve-tokens the browser sends (the CLI has no
+     *  JWT_SECRET, so it delegates verification to POST /api/onboarding/v2/serve-verify). */
+    apiUrl?: string;
+    /** When set, a verified serve-token must resolve to this user/participant —
+     *  read from the workspace marker so one machine's serve can't be driven by a
+     *  token minted for a different student. */
+    expectedUserId?: string;
+    expectedParticipantId?: string;
     /** Working directory the embedded `claude` runs in. Defaults to process.cwd().
      *  serveCommand sets this to the provisioned workspace so the session is coached. */
     cwd?: string;

package/dist/commands/serve.js

@@ -1,13 +1,74 @@
 import { WebSocketServer } from 'ws';
 import { createRequire } from 'node:module';
+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 { c } from '../lib/colors.js';
+/**
+ * Restore the executable bit on node-pty's `spawn-helper`. Some install paths
+ * (pnpm store hardlinks, tarball extraction without same-permissions, certain
+ * CI caches) drop the +x bit on the prebuilt helper — and without it node-pty's
+ * posix_spawnp fails at runtime with "posix_spawnp failed", killing the embedded
+ * terminal on EVERY launch. We can't depend on the package shipping it correctly,
+ * so we fix it best-effort at startup. No-op on Windows (no spawn-helper there).
+ */
+function ensureSpawnHelperExecutable(req) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        const main = req.resolve('node-pty'); // <pkg>/lib/index.js
+        const helper = path.resolve(path.dirname(main), '..', 'prebuilds', `${process.platform}-${process.arch}`, 'spawn-helper');
+        if (existsSync(helper) && !(statSync(helper).mode & 0o111)) {
+            chmodSync(helper, 0o755);
+        }
+    }
+    catch {
+        /* best-effort — if we can't locate it, the spawn error path still reports cleanly */
+    }
+}
+/**
+ * Verify a serve-token the browser sent on the WS handshake. The CLI can't check
+ * the JWT signature locally (no JWT_SECRET), so it asks the API. Returns true only
+ * if the API confirms the token AND it resolves to the workspace's own student.
+ */
+async function verifyServeToken(token, opts) {
+    if (!token || !opts.apiUrl)
+        return false;
+    try {
+        const res = await fetch(`${opts.apiUrl}/api/onboarding/v2/serve-verify`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ token }),
+        });
+        if (!res.ok)
+            return false;
+        const data = (await res.json());
+        if (!data.valid)
+            return false;
+        if (opts.expectedUserId && data.userId && data.userId !== opts.expectedUserId)
+            return false;
+        if (opts.expectedParticipantId && data.participantId && data.participantId !== opts.expectedParticipantId)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 const DEFAULT_ALLOWED_ORIGINS = [
     'https://app.paris-group.com',
     'https://paris-immersion.vercel.app',
     'http://localhost:3010',
 ];
+// Initial prompt fed to `claude` when the embedded terminal opens, so the course
+// starts immediately instead of sitting at an idle prompt. Invoca a skill do
+// tutor ToStudy (`/tostudy`, do @tostudy-ai/cli) — o aluno chega aqui já logado
+// na conta dele da ToStudy (auto-login no install via cli-auth-code), então o
+// `/tostudy` roda o curso real direto. Override com PARIS_COACH_KICKOFF se uma
+// 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';
 /**
  * Start a localhost WebSocket server that brokers a pty (running `claude`) to a
  * connected browser-side xterm.js. Two gates protect the channel:
@@ -33,11 +94,18 @@ export async function startServeServer(opts) {
                 return;
             }
             const url = new URL(info.req.url ?? '/', 'http://localhost');
-            if (url.searchParams.get('token') !== opts.token) {
-                cb(false, 401, 'invalid token');
+            const qToken = url.searchParams.get('token') ?? '';
+            // Fast path: the login token (creds.token) — backward compatible with
+            // older web clients that sent it directly.
+            if (qToken && qToken === opts.token) {
+                cb(true);
                 return;
             }
-            cb(true);
+            // Otherwise treat it as a serve-token (purpose 'onboarding-serve', minted by
+            // GET /api/onboarding/v2/serve-token) and let the API verify it.
+            void verifyServeToken(qToken, opts).then((ok) => {
+                cb(ok, ok ? undefined : 401, ok ? undefined : 'invalid token');
+            });
         },
     });
     // Wait for the listening event so handle.port is final (random port if 0).
@@ -56,9 +124,17 @@ export async function startServeServer(opts) {
             // 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');
-            const shellArgs = process.platform === 'win32' ? ['-NoLogo'] : ['-l', '-c', 'claude'];
+            // 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,
@@ -173,9 +249,27 @@ export async function serveCommand(opts) {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(c.yellow(`  ! sem workspace coachado (${msg}). Abrindo Claude em ${cwd}.`));
     }
+    // Read api_url + the workspace's owner so we can verify serve-tokens (and bind
+    // them to this student). Best-effort — falls back to login-token-only auth.
+    let apiUrl = '';
+    let expectedUserId;
+    let expectedParticipantId;
+    try {
+        const creds = await readCredentials();
+        apiUrl = creds?.api_url ?? '';
+        const markerRaw = await fs.readFile(path.join(cwd, '.paris', 'workspace.json'), 'utf8');
+        const marker = JSON.parse(markerRaw);
+        expectedUserId = marker.student_user_id;
+        expectedParticipantId = marker.participant_id;
+        if (!apiUrl && marker.api_url)
+            apiUrl = marker.api_url;
+    }
+    catch {
+        /* best-effort — verifyServeToken just no-ops without apiUrl */
+    }
     let handle;
     try {
-        handle = await startServeServer({ port: portNum, allowedOrigins, token, cwd });
+        handle = await startServeServer({ port: portNum, allowedOrigins, token, cwd, apiUrl, expectedUserId, expectedParticipantId });
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);

package/dist/templates/hook.js

@@ -76,9 +76,10 @@ async function main() {
     return
   }
 
-  const [workspace, current] = await Promise.all([
+  const [workspace, current, course] = await Promise.all([
     apiGet(apiUrl, '/immersion-app/v1/workspace', creds.token),
     apiGet(apiUrl, '/immersion-app/v1/missions/current', creds.token),
+    apiGet(apiUrl, '/immersion-app/v1/course', creds.token),
   ])
 
   if (!workspace) {
@@ -87,6 +88,11 @@ async function main() {
   }
   if (workspace.status === 'graduated') return
 
+  // Onboarding: enquanto o curso não termina, o terminal roda o tutor do curso
+  // (/tostudy) — isso tem prioridade sobre as missões da imersão (que nem existem
+  // na fase pre).
+  const inCourse = !!(course && course.courseCompleted === false)
+
   const lines = []
   if (PHASE === 'session-start') {
     lines.push('# Paris Immersion — contexto da sessão')
@@ -94,28 +100,40 @@ async function main() {
     lines.push('Imersão: **' + workspace.immersion.name + '** (\\'' + workspace.immersion.slug + '\\')')
     lines.push('Dia: **' + workspace.day_number + '** · fase: **' + workspace.phase + '**')
     lines.push('')
-    lines.push('Você (Claude) é o coach técnico desse aluno. Siga as regras do CLAUDE.md e da skill paris-coach. **Comece falando primeiro** com um resumo do dia e a tarefa atual — o aluno NÃO digitou nada ainda.')
-    lines.push('')
   } else {
     lines.push('# Paris — refresh de contexto')
     lines.push('')
   }
 
-  if (current && current.current) {
-    lines.push('## Tarefa atual')
-    lines.push('- **id:** \\'' + current.current.id + '\\'')
-    lines.push('- **título:** ' + current.current.title)
-    lines.push('- **tipo:** ' + current.current.deliverable_type)
-    lines.push('- **status:** ' + current.current.status)
-    if (current.current.description) lines.push('- **descrição:** ' + current.current.description)
-    if (current.current.socio_prompt) {
+  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.)')
+    if (PHASE === 'session-start') {
       lines.push('')
-      lines.push('### Sócio prompt')
-      lines.push(current.current.socio_prompt)
+      lines.push('**Comece falando primeiro**: rode /tostudy e dê as boas-vindas. O aluno ainda não digitou nada.')
     }
   } else {
-    lines.push('## Sem tarefa em foco')
-    lines.push('Pergunte ao aluno em que ele quer trabalhar.')
+    if (PHASE === 'session-start') {
+      lines.push('Você (Claude) é o coach técnico desse aluno. Siga as regras do CLAUDE.md e da skill paris-coach. **Comece falando primeiro** com um resumo do dia e a tarefa atual — o aluno NÃO digitou nada ainda.')
+      lines.push('')
+    }
+    if (current && current.current) {
+      lines.push('## Tarefa atual')
+      lines.push('- **id:** \\'' + current.current.id + '\\'')
+      lines.push('- **título:** ' + current.current.title)
+      lines.push('- **tipo:** ' + current.current.deliverable_type)
+      lines.push('- **status:** ' + current.current.status)
+      if (current.current.description) lines.push('- **descrição:** ' + current.current.description)
+      if (current.current.socio_prompt) {
+        lines.push('')
+        lines.push('### Sócio prompt')
+        lines.push(current.current.socio_prompt)
+      }
+    } else {
+      lines.push('## Sem tarefa em foco')
+      lines.push('Pergunte ao aluno em que ele quer trabalhar.')
+    }
   }
 
   process.stdout.write(lines.join('\\n') + '\\n')

package/dist/templates/settings.js

@@ -9,7 +9,11 @@
  */
 export function renderSettingsJson(opts) {
     return {
-        $schema: 'https://json.schemastore.org/claude-code-settings',
+        $schema: 'https://json.schemastore.org/claude-code-settings.json',
+        // Auto-confia no MCP do projeto (paris-immersion) — sem isso o Claude Code
+        // pode não conectar o server numa sessão não-interativa (terminal embutido),
+        // e o tutor abre sem as tools get_course/complete_lesson.
+        enableAllProjectMcpServers: true,
         mcpServers: {
             'paris-immersion': {
                 command: 'node',

package/package.json

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

package/templates/mcp/index.mjs

@@ -18024,6 +18024,18 @@ function buildTools() {
         transcript_excerpt: input.transcript_excerpt
       })
     },
+    {
+      name: "get_course",
+      description: "Retorna o curso de onboarding (Terminal + Claude Code): li\xE7\xF5es, objetivos e o progresso do aluno. Use NO IN\xCDCIO pra saber o que ensinar e de onde retomar.",
+      inputSchema: external_exports.object({}),
+      handler: async (_, { client }) => client.get("/immersion-app/v1/course")
+    },
+    {
+      name: "complete_lesson",
+      description: "Marca uma li\xE7\xE3o do curso de onboarding como conclu\xEDda. Progresso \xE9 MONOT\xD4NICO (nunca regride) e reconcilia com a conta ToStudy do aluno pelo e-mail. S\xD3 chame quando o aluno realmente cumprir o objetivo da li\xE7\xE3o. Quando a \xFAltima fecha, o curso conclui e a fase avan\xE7a.",
+      inputSchema: external_exports.object({ lesson_id: external_exports.string().min(1) }),
+      handler: async (input, { client }) => client.post(`/immersion-app/v1/course/lessons/${input.lesson_id}/complete`, {})
+    },
     {
       name: "reopen_task",
       description: "Reabrir uma tarefa marcada como conclu\xEDda. O aluno (voc\xEA) precisa de uma raz\xE3o.",