icoa-cli 2.19.96 → 2.19.97

package/dist/commands/exam.js

@@ -1658,7 +1658,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/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.97",
   "description": "ICOA CLI — The world's first CLI-native CTF competition terminal",
   "type": "module",
   "bin": {