paris-immersion 0.1.0 → 0.1.2

package/dist/commands/install.d.ts

@@ -2,3 +2,16 @@ export declare function installCommand(opts: {
     dir?: string;
     immersion?: string;
 }): Promise<void>;
+/**
+ * Locate the student's workspace, or create one if none exists. Used by
+ * `paris serve` so the onboarding embedded terminal always opens a *coached*
+ * Claude session — the student never has to know `paris install` exists. This
+ * is what guarantees the "magic moment": open the terminal, Claude greets you
+ * with today's mission. Returns the workspace dir + whether it was just created.
+ */
+export declare function ensureWorkspace(opts?: {
+    immersion?: string;
+}): Promise<{
+    dir: string;
+    created: boolean;
+}>;

package/dist/commands/install.js

@@ -1,4 +1,5 @@
 import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { apiAuthFetch } from '../lib/api.js';
@@ -22,14 +23,50 @@ export async function installCommand(opts) {
         return;
     }
     process.stdout.write(c.dim('Buscando contexto da imersão...\n'));
-    const slugQuery = opts.immersion ? `?immersion=${encodeURIComponent(opts.immersion)}` : '';
-    const boot = await apiAuthFetch(`/immersion-app/v1/workspace/bootstrap${slugQuery}`, {
+    const boot = await bootstrapWorkspace(opts.immersion);
+    const targetDir = path.resolve(opts.dir ?? `paris-${boot.immersion.slug}`);
+    await writeWorkspaceFiles(targetDir, boot, creds.api_url, creds.email);
+    console.log();
+    console.log(c.green(`✓ Workspace pronto em ${targetDir}`));
+    console.log();
+    console.log(c.bold('Próximo passo:'));
+    console.log(`  cd ${path.relative(process.cwd(), targetDir) || '.'}`);
+    console.log('  claude');
+    console.log();
+    console.log(c.dim(`Imersão: ${boot.immersion.name} · fase ${boot.phase} · dia ${boot.day_number}`));
+}
+/**
+ * Locate the student's workspace, or create one if none exists. Used by
+ * `paris serve` so the onboarding embedded terminal always opens a *coached*
+ * Claude session — the student never has to know `paris install` exists. This
+ * is what guarantees the "magic moment": open the terminal, Claude greets you
+ * with today's mission. Returns the workspace dir + whether it was just created.
+ */
+export async function ensureWorkspace(opts = {}) {
+    const existing = await findMarker();
+    if (existing)
+        return { dir: existing.dir, created: false };
+    const creds = await readCredentials();
+    if (!creds) {
+        throw new Error('Você precisa rodar `paris login` antes.');
+    }
+    const boot = await bootstrapWorkspace(opts.immersion);
+    // Predictable, findable location regardless of where `paris serve` was run.
+    const targetDir = path.join(homedir(), `paris-${boot.immersion.slug}`);
+    await writeWorkspaceFiles(targetDir, boot, creds.api_url, creds.email);
+    return { dir: targetDir, created: true };
+}
+async function bootstrapWorkspace(immersion) {
+    const slugQuery = immersion ? `?immersion=${encodeURIComponent(immersion)}` : '';
+    return apiAuthFetch(`/immersion-app/v1/workspace/bootstrap${slugQuery}`, {
         method: 'POST',
     });
-    const targetDir = path.resolve(opts.dir ?? `paris-${boot.immersion.slug}`);
+}
+/** Write the full workspace layout (marker, hooks, vendored MCP, settings, skill, CLAUDE.md). */
+async function writeWorkspaceFiles(targetDir, boot, apiUrl, email) {
     await fs.mkdir(targetDir, { recursive: true });
     // .paris/workspace.json — the marker.
-    await writeMarker(targetDir, { ...boot.marker, api_url: creds.api_url });
+    await writeMarker(targetDir, { ...boot.marker, api_url: apiUrl });
     // .paris/hooks/paris-hook.mjs — installed Claude Code hook.
     const hooksDir = path.join(targetDir, '.paris', 'hooks');
     await fs.mkdir(hooksDir, { recursive: true });
@@ -40,13 +77,12 @@ export async function installCommand(opts) {
     const mcpDir = path.join(targetDir, '.paris', 'mcp');
     await fs.mkdir(mcpDir, { recursive: true });
     await fs.writeFile(path.join(mcpDir, 'index.mjs'), await readVendoredMcpBundle(), { mode: 0o755 });
-    // .claude/settings.json — wires hooks + MCP server.
+    // .claude/settings.json — wires hooks + MCP server. Both settings.json (for
+    // interactive `claude`) and settings.local.json (the source `claude -p`
+    // reliably loads hooks from).
     const claudeDir = path.join(targetDir, '.claude');
     await fs.mkdir(claudeDir, { recursive: true });
-    // Write both settings.json (so the regular interactive `claude` picks it up)
-    // and settings.local.json (so `claude -p` does too — in -p mode, local
-    // settings are the reliably-loaded source for hooks).
-    const settingsPayload = renderSettingsJson({ apiUrl: creds.api_url });
+    const settingsPayload = renderSettingsJson({ apiUrl });
     await fs.writeFile(path.join(claudeDir, 'settings.json'), JSON.stringify(settingsPayload, null, 2));
     await fs.writeFile(path.join(claudeDir, 'settings.local.json'), JSON.stringify(settingsPayload, null, 2));
     // .claude/skills/paris-coach/SKILL.md
@@ -57,16 +93,8 @@ export async function installCommand(opts) {
     await fs.writeFile(path.join(targetDir, 'CLAUDE.md'), renderClaudeMd({
         immersionName: boot.immersion.name,
         immersionSlug: boot.immersion.slug,
-        participantEmail: creds.email,
+        participantEmail: email,
     }));
-    console.log();
-    console.log(c.green(`✓ Workspace pronto em ${targetDir}`));
-    console.log();
-    console.log(c.bold('Próximo passo:'));
-    console.log(`  cd ${path.relative(process.cwd(), targetDir) || '.'}`);
-    console.log('  claude');
-    console.log();
-    console.log(c.dim(`Imersão: ${boot.immersion.name} · fase ${boot.phase} · dia ${boot.day_number}`));
 }
 /**
  * Reads the bundled MCP server shipped with this package. Lives at

package/dist/commands/serve.d.ts

@@ -1,7 +1,20 @@
 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;
     /** When true, accept connections without spawning a pty — used by tests + dry-run handshake checks. */
     dryRun?: boolean;
 }

package/dist/commands/serve.js

@@ -1,12 +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:
@@ -32,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).
@@ -55,14 +124,22 @@ 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,
                 rows: 24,
-                cwd: process.cwd(),
+                cwd: opts.cwd ?? process.cwd(),
                 env: {
                     ...process.env,
                     TOSTUDY_MCP_ENABLED: '1',
@@ -156,9 +233,43 @@ export async function serveCommand(opts) {
         process.exit(1);
     }
     const allowedOrigins = (process.env.PARIS_SERVE_ORIGINS?.split(',').map((s) => s.trim()).filter(Boolean)) ?? DEFAULT_ALLOWED_ORIGINS;
+    // Guarantee the embedded `claude` opens inside a provisioned (coached)
+    // workspace. If the student already ran `paris install`, we reuse it; else we
+    // bootstrap one now so the onboarding terminal is never vanilla Claude. A
+    // failure here is non-fatal — we fall back to cwd so the terminal still works.
+    let cwd = process.cwd();
+    try {
+        const { dir, created } = await ensureWorkspace({});
+        cwd = dir;
+        console.log(created
+            ? `  ${c.green('✓')} workspace criado em ${c.bold(dir)}`
+            : `  ${c.dim('workspace:')} ${dir}`);
+    }
+    catch (err) {
+        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 });
+        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.0",
+  "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.",