icoa-cli 2.19.95 → 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/index.js

@@ -117,10 +117,35 @@ program
     // wondering why "哪个命令..." appears as "????..." on their machine.
     const envLang = process.env.LANG || process.env.LC_ALL || process.env.LC_CTYPE || '';
     if (!/UTF-?8/i.test(envLang)) {
-        console.log(chalk.yellow('⚠ Your terminal locale is not UTF-8 (LANG=' + (envLang || '(unset)') + ').'));
-        console.log(chalk.gray('  Non-English text and box characters may display as "?" or garbled glyphs.'));
-        console.log(chalk.gray('  Fix: ') + chalk.cyan('export LANG=en_US.UTF-8') + chalk.gray(' (or your locale, e.g. ') + chalk.cyan('zh_CN.UTF-8') + chalk.gray(', ') + chalk.cyan('uk_UA.UTF-8') + chalk.gray(')'));
-        console.log();
+        if (process.platform === 'win32') {
+            // Windows cmd.exe default code page (437 US, 936 CN, etc.) mangles
+            // non-Latin script. Fix is `chcp 65001`, not Unix-style `export LANG`.
+            // Skip the warning if the code page is already 65001 (PowerShell +
+            // Windows Terminal often set it automatically).
+            let codepage = '';
+            try {
+                const { execFileSync } = await import('node:child_process');
+                codepage = execFileSync('chcp.com', [], {
+                    encoding: 'utf-8',
+                    timeout: 1500,
+                    stdio: ['ignore', 'pipe', 'ignore'],
+                }).trim();
+            }
+            catch { /* chcp.com unavailable or timed out */ }
+            if (!codepage.includes('65001')) {
+                console.log(chalk.yellow('⚠ Windows terminal is not using UTF-8 (current: ' + (codepage || 'unknown') + ').'));
+                console.log(chalk.gray('  Non-English text (Ukrainian, Chinese, Japanese, etc.) may show as "?" or garbled glyphs.'));
+                console.log(chalk.gray('  Fix (run before ') + chalk.cyan('icoa') + chalk.gray('): ') + chalk.cyan('chcp 65001'));
+                console.log(chalk.gray('  Or stay in English inside the CLI: ') + chalk.cyan('lang en'));
+                console.log();
+            }
+        }
+        else {
+            console.log(chalk.yellow('⚠ Your terminal locale is not UTF-8 (LANG=' + (envLang || '(unset)') + ').'));
+            console.log(chalk.gray('  Non-English text and box characters may display as "?" or garbled glyphs.'));
+            console.log(chalk.gray('  Fix: ') + chalk.cyan('export LANG=en_US.UTF-8') + chalk.gray(' (or your locale, e.g. ') + chalk.cyan('zh_CN.UTF-8') + chalk.gray(', ') + chalk.cyan('uk_UA.UTF-8') + chalk.gray(')'));
+            console.log();
+        }
     }
     console.log(BANNER);
     // If running interactively (no extra args or --resume), start REPL

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';
@@ -106,17 +107,29 @@ function checkPython() {
     // Probe python3.12 first — macOS Homebrew installs python@3.12 alongside a
     // newer default python3, and we don't want to flag a 3.12-ready machine just
     // because the default alias moved to 3.13.
+    // On Windows (cmd/PowerShell), the binary is `python` not `python3`, and the
+    // Python launcher `py -3` is also common. Include these so Windows K-12
+    // students don't get a spurious "Python missing" warning when Python IS
+    // installed. We also stdio: ignore stderr so cmd.exe's "not recognized as
+    // internal or external command" error doesn't leak to the user.
     const probes = [
         'python3.12 --version',
         '/opt/homebrew/opt/python@3.12/bin/python3.12 --version',
         '/usr/local/opt/python@3.12/bin/python3.12 --version',
         'python3 --version',
+        'python --version', // Windows default name
+        'py -3.12 --version', // Windows Python Launcher
+        'py -3 --version', // Windows Python Launcher (any 3.x)
     ];
     let lastVersion = '';
     let lastStatus = 'missing';
     for (const cmd of probes) {
         try {
-            const out = execSyncFn(cmd, { encoding: 'utf-8', timeout: 2000 }).trim();
+            const out = execSyncFn(cmd, {
+                encoding: 'utf-8',
+                timeout: 2000,
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
             const version = out.replace('Python ', '');
             const [maj, min] = version.split('.').map(Number);
             if (maj === 3 && min === 12)
@@ -137,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:'));
@@ -166,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.'));
@@ -180,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();
@@ -196,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('   ─────────────────────────────────────────────'));
@@ -905,6 +931,24 @@ export async function startRepl(program, resumeMode) {
                     .replace(/^python3?\s/, `${py12} `)
                     .replace(/^(python3|python)$/, py12);
             }
+            else if (process.platform === 'win32') {
+                // Windows: the binary is `python` (not `python3`). Python Launcher `py -3`
+                // is also common. Rewrite `python3 xyz` → `python xyz` or `py -3 xyz` so
+                // students who followed Unix-oriented practical-question hints don't get
+                // "'python3' is not recognized". Prefer `py -3` if the launcher exists
+                // (handles multi-version installs); fall back to plain `python`.
+                const pyCmd = (() => {
+                    try {
+                        execSyncFn('py -3 --version', { stdio: ['ignore', 'ignore', 'ignore'], timeout: 1500 });
+                        return 'py -3';
+                    }
+                    catch { }
+                    return 'python';
+                })();
+                resolvedInput = resolvedInput
+                    .replace(/^python3?(\.\d+)?\s/, `${pyCmd} `)
+                    .replace(/^python3?(\.\d+)?$/, pyCmd);
+            }
             else {
                 // Linux/WSL: python → python3 (or python3.12 if available)
                 const py12 = (() => { try {

package/package.json

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