icoa-cli 2.19.96 → 2.19.98

package/dist/commands/exam.js

@@ -1447,6 +1447,7 @@ export function registerExamCommand(program) {
                 interactions: (state.interactions || []).length,
                 durationMin: state.session.durationMinutes || 0,
                 confirmedAt: state.session.confirmedAt || state.session.startedAt,
+                examId: state.session.examId,
             };
             clearExamState();
             const elapsedSec = Math.max(0, Math.round((Date.now() - new Date(preSubmit.confirmedAt).getTime()) / 1000));
@@ -1524,6 +1525,11 @@ export function registerExamCommand(program) {
             console.log(chalk.gray('  · Keep sharpening: ') + chalk.white('demo') + chalk.gray(' is free, unlimited practice.'));
             console.log(chalk.gray('  · Reference guides for 38 tools: ') + chalk.white('ref'));
             console.log();
+            // v2.19.98 — Paper C → B upgrade funnel. Students who pass the entry
+            // MCQ paper get a platform-aware nudge toward Paper B (K-12 + AI).
+            // No-op for non-C papers and for non-passers. See src/lib/paper-upgrade.ts.
+            const { showCToBUpgradePrompt } = await import('../lib/paper-upgrade.js');
+            showCToBUpgradePrompt(preSubmit.examId, result.passed);
             console.log(chalk.yellow('  ICOA 2026 · Sydney, Australia · Jun 27 – Jul 2'));
             console.log(chalk.cyan.underline('  https://icoa2026.au'));
             console.log();
@@ -1658,7 +1664,16 @@ export function registerExamCommand(program) {
             return;
         }
         // Gate: require exam setup
-        if (!isExamSetupComplete()) {
+        // v2.19.97 — Windows cmd users bypass the exam-setup gate entirely.
+        // Their recommended path is C paper (MCQ only, no Python / no Unix tools),
+        // so forcing them through `exam setup` (which installs pip packages) would
+        // be both unnecessary and likely to fail. Server enforces token→exam_id
+        // binding (1:1 FK), so if they use a B/A token on cmd they'll still get
+        // routed to the correct exam; but the missing tools may cost them points
+        // on Q31-36. That's the trade-off they opted into.
+        const { isNativeWindowsCmd: _isNativeWindowsCmd } = await import('../lib/platform.js');
+        const cmdPath = _isNativeWindowsCmd();
+        if (!cmdPath && !isExamSetupComplete()) {
             console.log();
             printWarning('Pre-exam setup required before entering a token.');
             console.log(chalk.gray('  → ') + chalk.bold.cyan('exam setup'));

package/dist/lib/paper-upgrade.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Paper C → Paper B upgrade prompt.
+ *
+ * Shown after a successful Paper C submission. Paper C is the K-12 entry
+ * funnel (MCQ only, no tools). Paper B is the next step — adds AI4CTF
+ * and CTF4AI practical challenges for 150-point total. The upgrade path
+ * depends on which platform the student is on.
+ *
+ * Policy:
+ * - Only triggered after Paper C submission (examId ends in `-c` or
+ *   starts with a country code + `-2026-c`).
+ * - Only triggered if student passed. Students who failed C should
+ *   retry C before being pushed toward a harder paper.
+ * - Always points at https://icoa2026.au/selectionguide/ for detailed
+ *   platform-specific install instructions, so the CLI copy stays
+ *   concise and the canonical guide lives in one place.
+ * - Never prescribes a token — students must request one from their
+ *   organizer. This prevents the CLI from implying self-service token
+ *   issuance.
+ */
+/**
+ * True when the just-submitted exam is a C paper (MCQ entry funnel).
+ * Matches `ua-2026-c`, `pe-2026-c`, `cn-2026-c`, etc. Case-insensitive.
+ */
+export declare function isCPaper(examId: string | undefined): boolean;
+/**
+ * Renders the C→B upgrade prompt to stdout. No-op if conditions aren't met.
+ *
+ * @param examId   The submitted exam ID (from state.session.examId before clear)
+ * @param passed   Whether the student met the passing bar
+ */
+export declare function showCToBUpgradePrompt(examId: string | undefined, passed: boolean): void;

package/dist/lib/paper-upgrade.js

@@ -0,0 +1,117 @@
+/**
+ * Paper C → Paper B upgrade prompt.
+ *
+ * Shown after a successful Paper C submission. Paper C is the K-12 entry
+ * funnel (MCQ only, no tools). Paper B is the next step — adds AI4CTF
+ * and CTF4AI practical challenges for 150-point total. The upgrade path
+ * depends on which platform the student is on.
+ *
+ * Policy:
+ * - Only triggered after Paper C submission (examId ends in `-c` or
+ *   starts with a country code + `-2026-c`).
+ * - Only triggered if student passed. Students who failed C should
+ *   retry C before being pushed toward a harder paper.
+ * - Always points at https://icoa2026.au/selectionguide/ for detailed
+ *   platform-specific install instructions, so the CLI copy stays
+ *   concise and the canonical guide lives in one place.
+ * - Never prescribes a token — students must request one from their
+ *   organizer. This prevents the CLI from implying self-service token
+ *   issuance.
+ */
+import chalk from 'chalk';
+import { isNativeWindowsCmd, isInWSL, hasPython } from './platform.js';
+/**
+ * True when the just-submitted exam is a C paper (MCQ entry funnel).
+ * Matches `ua-2026-c`, `pe-2026-c`, `cn-2026-c`, etc. Case-insensitive.
+ */
+export function isCPaper(examId) {
+    if (!examId)
+        return false;
+    return /-2026-c$/i.test(examId.trim());
+}
+/**
+ * Renders the C→B upgrade prompt to stdout. No-op if conditions aren't met.
+ *
+ * @param examId   The submitted exam ID (from state.session.examId before clear)
+ * @param passed   Whether the student met the passing bar
+ */
+export function showCToBUpgradePrompt(examId, passed) {
+    if (!isCPaper(examId))
+        return;
+    if (!passed)
+        return;
+    const onCmd = isNativeWindowsCmd();
+    const onWSL = isInWSL();
+    const pyReady = hasPython();
+    console.log(chalk.cyan('  ─────────────────────────────────────────────'));
+    console.log();
+    console.log(chalk.bold.white('  ★ Ready for more? Paper B — K-12 with AI'));
+    console.log();
+    console.log(chalk.gray('  Paper B adds ') + chalk.white('AI4CTF') + chalk.gray(' (chat with AI to find hidden flags) and ')
+        + chalk.white('CTF4AI') + chalk.gray(' (break AI security).'));
+    console.log(chalk.gray('  150 points total · 90 minutes · same command interface you already know.'));
+    console.log();
+    if (onCmd) {
+        // Windows cmd / PowerShell — needs WSL2 path for full Paper B
+        console.log(chalk.bold.white('  To take Paper B on Windows, install WSL2 + Ubuntu 22:'));
+        console.log();
+        console.log(chalk.white('    1. Open PowerShell as Administrator'));
+        console.log(chalk.gray('       (right-click PowerShell → "Run as administrator")'));
+        console.log(chalk.white('    2. Run: ') + chalk.cyan('wsl --install -d Ubuntu-22.04'));
+        console.log(chalk.white('    3. Reboot when prompted, create a Linux username + password'));
+        console.log(chalk.white('    4. Inside Ubuntu, install Node.js 22 and this CLI:'));
+        console.log(chalk.gray('         ') + chalk.cyan('curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -'));
+        console.log(chalk.gray('         ') + chalk.cyan('sudo apt install -y nodejs'));
+        console.log(chalk.gray('         ') + chalk.cyan('sudo npm install -g icoa-cli'));
+        console.log();
+        console.log(chalk.gray('  Setup takes 30-60 min the first time. You only do this once.'));
+    }
+    else if (onWSL) {
+        // Already on WSL2 — just need Python for practicals
+        console.log(chalk.bold.white('  You are on WSL2 — your setup is almost ready:'));
+        console.log();
+        if (!pyReady) {
+            console.log(chalk.white('    Install Python 3 (for Paper B practical questions):'));
+            console.log(chalk.gray('      ') + chalk.cyan('sudo apt install -y python3 python3-pip'));
+            console.log();
+        }
+        else {
+            console.log(chalk.green('    ✓ Python 3 already installed. You are ready.'));
+            console.log();
+        }
+    }
+    else if (process.platform === 'darwin') {
+        // macOS
+        console.log(chalk.bold.white('  On macOS, install Python 3 for Paper B practicals:'));
+        console.log();
+        console.log(chalk.white('    With Homebrew:'));
+        console.log(chalk.gray('      ') + chalk.cyan('brew install python@3.12'));
+        console.log();
+        console.log(chalk.white('    Without Homebrew: download from ') + chalk.cyan.underline('https://python.org'));
+        if (pyReady) {
+            console.log();
+            console.log(chalk.green('    ✓ Python 3 already detected. You are ready.'));
+        }
+        console.log();
+    }
+    else {
+        // Linux native (not WSL)
+        console.log(chalk.bold.white('  On Linux, install Python 3 for Paper B practicals:'));
+        console.log();
+        console.log(chalk.white('    Ubuntu / Debian:'));
+        console.log(chalk.gray('      ') + chalk.cyan('sudo apt install -y python3 python3-pip'));
+        console.log(chalk.white('    Fedora / RHEL:'));
+        console.log(chalk.gray('      ') + chalk.cyan('sudo dnf install -y python3 python3-pip'));
+        if (pyReady) {
+            console.log();
+            console.log(chalk.green('    ✓ Python 3 already detected. You are ready.'));
+        }
+        console.log();
+    }
+    console.log(chalk.bold.white('  Then get a Paper B token from your organizer.'));
+    console.log(chalk.gray('  Each token is one-shot and bound to one device.'));
+    console.log();
+    console.log(chalk.gray('  Detailed step-by-step guide: ')
+        + chalk.cyan.underline('https://icoa2026.au/selectionguide/'));
+    console.log();
+}

package/dist/lib/platform.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Platform detection for Windows cmd.exe K-12 entry path.
+ *
+ * Context: Windows middle-school students (12-14 y/o) are the expected largest
+ * cohort for ICOA 2026. Observed in-field: 4-5 students blocked by WSL install
+ * complexity. Their viable path is Windows native cmd + Node.js, which handles
+ * MCQ + AI chat perfectly but not Q31-36 (Unix grep / strings / pwntools).
+ *
+ * Decision (v2.19.97): C paper (ua-2026-c) is the cmd entry funnel — 30 MCQ
+ * only, 45 min, 70 pts, no tools. Non-cmd users get B paper (full 150 pts).
+ *
+ * This module is the single source of truth for "should we show exam setup?"
+ * and "should we route this user to C paper?". Used by src/repl.ts menu
+ * rendering and src/commands/exam.ts pre-token guards.
+ */
+export interface PlatformInfo {
+    platform: NodeJS.Platform;
+    isWindowsNativeCmd: boolean;
+    isInWSL: boolean;
+    hasPython: boolean;
+}
+/**
+ * Heuristic: true when running inside a WSL distribution. Node.js reports
+ * `process.platform === 'linux'` in that case, but WSL sets specific env vars.
+ */
+export declare function isInWSL(): boolean;
+/**
+ * True when the user is on Windows native (cmd.exe or PowerShell), NOT a
+ * WSL distribution.
+ */
+export declare function isNativeWindowsCmd(): boolean;
+/**
+ * Probe whether any Python 3 binary is reachable. Silent — no stderr leaks
+ * to the user. Used to decide whether Q31-35 practical questions are even
+ * theoretically doable on this machine.
+ *
+ * Uses execFileSync (no shell) so probe failures don't leak cmd.exe's
+ * "not recognized as internal or external command" messages to stdout.
+ */
+export declare function hasPython(): boolean;
+export declare function getPlatformInfo(): PlatformInfo;
+/**
+ * Should the Selection-mode menu show the `exam setup` row?
+ *
+ * Windows native cmd: NO. Setup installs pip packages for Q31-35 practical
+ * which don't apply on the C-paper (cmd-recommended) path. Showing setup
+ * sends them chasing Python installs that may fail for 12-year-olds.
+ *
+ * Everyone else (macOS, Linux, WSL): YES. They can reach B-paper and setup
+ * is a legit pre-step.
+ */
+export declare function shouldShowExamSetup(): boolean;
+/**
+ * Is this user recommended to take the C paper (MCQ-only) rather than B?
+ * Currently: Windows native cmd users. Future: might expand based on age
+ * or partner-country policy.
+ */
+export declare function shouldRecommendCPaper(): boolean;

package/dist/lib/platform.js

@@ -0,0 +1,86 @@
+/**
+ * Platform detection for Windows cmd.exe K-12 entry path.
+ *
+ * Context: Windows middle-school students (12-14 y/o) are the expected largest
+ * cohort for ICOA 2026. Observed in-field: 4-5 students blocked by WSL install
+ * complexity. Their viable path is Windows native cmd + Node.js, which handles
+ * MCQ + AI chat perfectly but not Q31-36 (Unix grep / strings / pwntools).
+ *
+ * Decision (v2.19.97): C paper (ua-2026-c) is the cmd entry funnel — 30 MCQ
+ * only, 45 min, 70 pts, no tools. Non-cmd users get B paper (full 150 pts).
+ *
+ * This module is the single source of truth for "should we show exam setup?"
+ * and "should we route this user to C paper?". Used by src/repl.ts menu
+ * rendering and src/commands/exam.ts pre-token guards.
+ */
+import { execFileSync } from 'node:child_process';
+/**
+ * Heuristic: true when running inside a WSL distribution. Node.js reports
+ * `process.platform === 'linux'` in that case, but WSL sets specific env vars.
+ */
+export function isInWSL() {
+    return !!(process.env.WSL_DISTRO_NAME || process.env.WSLENV);
+}
+/**
+ * True when the user is on Windows native (cmd.exe or PowerShell), NOT a
+ * WSL distribution.
+ */
+export function isNativeWindowsCmd() {
+    return process.platform === 'win32' && !isInWSL();
+}
+/**
+ * Probe whether any Python 3 binary is reachable. Silent — no stderr leaks
+ * to the user. Used to decide whether Q31-35 practical questions are even
+ * theoretically doable on this machine.
+ *
+ * Uses execFileSync (no shell) so probe failures don't leak cmd.exe's
+ * "not recognized as internal or external command" messages to stdout.
+ */
+export function hasPython() {
+    const probes = [
+        ['python3', ['--version']],
+        ['python', ['--version']],
+        ['py', ['-3', '--version']],
+    ];
+    for (const [bin, args] of probes) {
+        try {
+            execFileSync(bin, args, {
+                encoding: 'utf-8',
+                timeout: 1500,
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+            return true;
+        }
+        catch { /* try next */ }
+    }
+    return false;
+}
+export function getPlatformInfo() {
+    return {
+        platform: process.platform,
+        isWindowsNativeCmd: isNativeWindowsCmd(),
+        isInWSL: isInWSL(),
+        hasPython: hasPython(),
+    };
+}
+/**
+ * Should the Selection-mode menu show the `exam setup` row?
+ *
+ * Windows native cmd: NO. Setup installs pip packages for Q31-35 practical
+ * which don't apply on the C-paper (cmd-recommended) path. Showing setup
+ * sends them chasing Python installs that may fail for 12-year-olds.
+ *
+ * Everyone else (macOS, Linux, WSL): YES. They can reach B-paper and setup
+ * is a legit pre-step.
+ */
+export function shouldShowExamSetup() {
+    return !isNativeWindowsCmd();
+}
+/**
+ * Is this user recommended to take the C paper (MCQ-only) rather than B?
+ * Currently: Windows native cmd users. Future: might expand based on age
+ * or partner-country policy.
+ */
+export function shouldRecommendCPaper() {
+    return isNativeWindowsCmd();
+}

package/dist/repl.js

@@ -10,6 +10,7 @@ import { getExamState, getRealExamState, getDemoState } from './lib/exam-state.j
 import { getDemoStats } from './lib/demo-stats.js';
 import { isExamSetupComplete } from './lib/exam-setup.js';
 import { DEMO_PICK_SIZE, DEMO_POOL_SIZE } from './lib/demo-exam.js';
+import { isNativeWindowsCmd } from './lib/platform.js';
 import { resetTerminalTheme } from './lib/theme.js';
 import { ensureSandbox, runInSandbox, isDockerAvailable } from './lib/sandbox.js';
 import { logCommand } from './lib/logger.js';
@@ -149,13 +150,21 @@ function printSelectionMenu() {
     const stats = getDemoStats();
     const setupDone = isExamSetupComplete();
     const demoLine = `Free practice — ${DEMO_PICK_SIZE} questions (from pool of ${DEMO_POOL_SIZE})`;
+    // v2.19.97 — Windows cmd K-12 entry path. Skip setup prompts + Python
+    // warnings for cmd users; they're routed to C paper (MCQ-only) which
+    // needs zero external tools.
+    const cmdMode = isNativeWindowsCmd();
     console.log();
     console.log('   ' + chalk.cyan.bold('[Selection Mode]'));
     console.log();
-    // Proactive Python check: only warn when it actually matters (user past demo
-    // and heading toward exam setup). Missing or version >= 3.13 shows yellow
-    // note pointing at `env python`. Quiet when 3.10-3.12 are installed.
-    if (stats.attempts > 0) {
+    if (cmdMode) {
+        console.log(chalk.gray('   Platform: ') + chalk.white('Windows cmd.exe') + chalk.gray(' — routed to Paper C (MCQ-only, 45 min, 70 pts, zero extra tools)'));
+        console.log();
+    }
+    else if (stats.attempts > 0) {
+        // Proactive Python check only matters for non-cmd users heading toward
+        // exam setup. Missing or version >= 3.13 shows yellow note pointing at
+        // `env python`. Quiet when 3.10-3.12 are installed.
         const py = checkPython();
         if (py.status === 'missing') {
             console.log(chalk.yellow('   ⚠ Python not detected. For exam practical questions:'));
@@ -178,8 +187,9 @@ function printSelectionMenu() {
         console.log(chalk.white('     lang es') + chalk.gray('         Switch language (e.g. lang es, lang zh, lang fr)'));
         console.log(chalk.gray('   ─────────────────────────────────────────────'));
     }
-    else if (!setupDone) {
+    else if (!setupDone && !cmdMode) {
         // State 1: demo done at least once, but exam environment not installed.
+        // Windows cmd users skip this state entirely — they don't need setup.
         const plural = stats.attempts === 1 ? 'attempt' : 'attempts';
         console.log(chalk.green('   ✓ Demo completed ') + chalk.gray(`(${stats.attempts} ${plural}${stats.bestPercentage > 0 ? ` · best ${stats.bestPercentage}%` : ''})`));
         console.log(chalk.yellow('   → Next: prepare your environment for the real exam.'));
@@ -192,13 +202,15 @@ function printSelectionMenu() {
         console.log(chalk.gray('   ─────────────────────────────────────────────'));
     }
     else {
-        // State 2: fully prepared. Exam entry is the primary CTA — list it FIRST
-        // and make the token format + origin obvious. Students landing here have
-        // already done demo; without a concrete example they stare at "<token>"
-        // and don't know what to type or where the token comes from.
+        // State 2: ready to enter exam. For cmd users this is reached immediately
+        // (no setup gate); for others it requires exam setup completion.
         const plural = stats.attempts === 1 ? 'attempt' : 'attempts';
-        console.log(chalk.green('   ✓ Demo completed ') + chalk.gray(`(${stats.attempts} ${plural})`));
-        console.log(chalk.green('   ✓ Environment ready'));
+        if (stats.attempts > 0) {
+            console.log(chalk.green('   ✓ Demo completed ') + chalk.gray(`(${stats.attempts} ${plural})`));
+        }
+        if (!cmdMode) {
+            console.log(chalk.green('   ✓ Environment ready'));
+        }
         console.log(chalk.yellow('   → Enter your exam token to begin.'));
         console.log(chalk.gray('     (10-char code from your organizer, starts with your country code like ') + chalk.cyan('UA') + chalk.gray(' — case-insensitive)'));
         console.log();
@@ -208,7 +220,9 @@ function printSelectionMenu() {
         console.log(chalk.gray('   ─────────────────────────────────────────────'));
         console.log(chalk.gray('   Other commands:'));
         console.log(chalk.white('     demo') + chalk.gray(`            ${demoLine}`));
-        console.log(chalk.white('     exam setup') + chalk.gray('      Re-verify tool environment'));
+        if (!cmdMode) {
+            console.log(chalk.white('     exam setup') + chalk.gray('      Re-verify tool environment'));
+        }
         console.log(chalk.white('     lang') + chalk.gray('            List all supported languages'));
         console.log(chalk.white('     lang es') + chalk.gray('         Switch language (e.g. lang es, lang zh, lang fr)'));
         console.log(chalk.gray('   ─────────────────────────────────────────────'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icoa-cli",
-  "version": "2.19.96",
+  "version": "2.19.98",
   "description": "ICOA CLI — The world's first CLI-native CTF competition terminal",
   "type": "module",
   "bin": {