icoa-cli 2.19.79 → 2.19.81

package/dist/commands/env.js

@@ -272,8 +272,109 @@ export function registerEnvCommand(program) {
     const envCmd = program.command('env').description('Manage competition environment');
     envCmd.command('status').alias('check').description('Check all 109 tools').action(() => showStatus());
     envCmd.command('setup').description('Install all Python libraries + system tools').action(async () => { await installAll(); });
+    envCmd.command('python').description('Show Python 3.12 install guide for your platform').action(() => showPythonInstallGuide());
     envCmd.action(() => showStatus());
 }
+// Lightweight Python 3.12 install guide for Selection mode (no 109-tool check).
+// Detects distro on Linux so contestants get the right command the first time.
+function showPythonInstallGuide() {
+    const os = platform();
+    console.log();
+    console.log(chalk.bold.white('  Python 3.12 — Installation Guide'));
+    console.log(chalk.gray('  ─────────────────────────────────────────────'));
+    console.log();
+    let currentPy = '';
+    let pyStatus = 'missing';
+    try {
+        const out = execSync('python3 --version', { encoding: 'utf-8', timeout: 3000 }).trim();
+        currentPy = out.replace('Python ', '');
+        const parts = currentPy.split('.').map(Number);
+        if (parts[0] === 3 && parts[1] === 12)
+            pyStatus = 'ok';
+        else if (parts[0] === 3 && parts[1] >= 10 && parts[1] < 12)
+            pyStatus = 'old';
+        else if (parts[0] === 3 && parts[1] > 12)
+            pyStatus = 'new';
+        else
+            pyStatus = 'missing';
+    }
+    catch {
+        pyStatus = 'missing';
+    }
+    if (pyStatus === 'ok') {
+        console.log(chalk.green(`  ✓ Python ${currentPy} — you're good!`));
+        console.log(chalk.gray('    Exam toolkit ready. Next: ') + chalk.bold.cyan('exam setup'));
+        console.log();
+        return;
+    }
+    if (pyStatus === 'old') {
+        console.log(chalk.yellow(`  ⚠ Python ${currentPy} — works, but 3.12 recommended`));
+    }
+    else if (pyStatus === 'new') {
+        console.log(chalk.yellow(`  ⚠ Python ${currentPy} — some packages (pwntools, scapy) lack wheels`));
+        console.log(chalk.gray('    Downgrading to 3.12 is strongly recommended'));
+    }
+    else {
+        console.log(chalk.red('  ✗ Python 3 not found'));
+    }
+    console.log();
+    if (os === 'darwin') {
+        console.log(chalk.bold.white('  macOS (Homebrew)'));
+        console.log();
+        console.log(chalk.green('    brew install python@3.12'));
+    }
+    else if (os === 'linux') {
+        let distro = 'ubuntu';
+        try {
+            const release = execSync('cat /etc/os-release 2>/dev/null', { encoding: 'utf-8', timeout: 2000 });
+            if (/fedora|rhel|centos/i.test(release))
+                distro = 'fedora';
+            else if (/arch|manjaro/i.test(release))
+                distro = 'arch';
+            else
+                distro = 'ubuntu';
+        }
+        catch { }
+        if (distro === 'ubuntu') {
+            console.log(chalk.bold.white('  Ubuntu / Debian / Kali (deadsnakes PPA)'));
+            console.log();
+            console.log(chalk.gray('  Copy-paste this one-liner:'));
+            console.log();
+            console.log(chalk.green('    sudo add-apt-repository ppa:deadsnakes/ppa -y && \\'));
+            console.log(chalk.green('      sudo apt update && \\'));
+            console.log(chalk.green('      sudo apt install -y python3.12 python3.12-venv python3.12-distutils && \\'));
+            console.log(chalk.green('      sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1'));
+        }
+        else if (distro === 'fedora') {
+            console.log(chalk.bold.white('  Fedora / RHEL / CentOS'));
+            console.log();
+            console.log(chalk.green('    sudo dnf install -y python3.12 python3.12-pip'));
+        }
+        else if (distro === 'arch') {
+            console.log(chalk.bold.white('  Arch / Manjaro (via pyenv)'));
+            console.log();
+            console.log(chalk.green('    sudo pacman -S pyenv && pyenv install 3.12 && pyenv global 3.12'));
+        }
+    }
+    else if (os === 'win32') {
+        console.log(chalk.bold.white('  Windows (WSL recommended)'));
+        console.log();
+        console.log(chalk.gray('  WSL + Ubuntu (best):'));
+        console.log(chalk.green('    wsl --install'));
+        console.log(chalk.gray('    Then inside Ubuntu, run the Ubuntu commands.'));
+        console.log();
+        console.log(chalk.gray('  Or native:'));
+        console.log(chalk.green('    winget install Python.Python.3.12'));
+    }
+    else {
+        console.log(chalk.gray('  https://www.python.org/downloads/'));
+    }
+    console.log();
+    console.log(chalk.white('  After installing, verify:'));
+    console.log(chalk.bold.cyan('    env python') + chalk.gray('       # re-check Python'));
+    console.log(chalk.bold.cyan('    exam setup') + chalk.gray('       # install the 13 exam packages'));
+    console.log();
+}
 function showStatus() {
     console.log();
     const os = platform();

package/dist/commands/exam.js

@@ -1925,7 +1925,7 @@ export function registerExamCommand(program) {
         console.log(chalk.white('  Installing Python packages for practical questions.'));
         console.log(chalk.gray('  Expected: 1-2 minutes · ~150MB disk'));
         console.log();
-        // Step 1: Check Python 3.12+
+        // Step 1: Check Python 3.10+ (all packages support 3.10, 3.12 recommended)
         const printPythonInstallGuide = (reason, currentVersion) => {
             const platform = process.platform;
             console.log();
@@ -1933,10 +1933,10 @@ export function registerExamCommand(program) {
                 printError('Python 3 not found.');
             }
             else {
-                printError(`Python ${currentVersion} found, but 3.12+ required for the exam.`);
+                printError(`Python ${currentVersion} found, but 3.10+ required for the exam.`);
             }
             console.log();
-            console.log(chalk.bold.white('  How to install Python 3.12:'));
+            console.log(chalk.bold.white('  How to install Python 3.10+ (3.12 recommended):'));
             console.log();
             if (platform === 'darwin') {
                 console.log(chalk.yellow('  macOS (Homebrew, recommended):'));
@@ -1978,11 +1978,16 @@ export function registerExamCommand(program) {
             const raw = execSync(`${pythonBin} --version`, { encoding: 'utf-8', timeout: 5000 }).trim();
             pythonVersion = raw.replace('Python ', '');
             const parts = pythonVersion.split('.').map(Number);
-            if (parts[0] < 3 || (parts[0] === 3 && parts[1] < 12)) {
+            if (parts[0] < 3 || (parts[0] === 3 && parts[1] < 10)) {
                 printPythonInstallGuide('too_old', pythonVersion);
                 return;
             }
-            console.log(chalk.green(`  ✓ Python ${pythonVersion}`));
+            if (parts[0] === 3 && parts[1] < 12) {
+                console.log(chalk.green(`  ✓ Python ${pythonVersion}`) + chalk.gray(' (works, but 3.12 recommended)'));
+            }
+            else {
+                console.log(chalk.green(`  ✓ Python ${pythonVersion}`));
+            }
         }
         catch {
             printPythonInstallGuide('missing');

package/dist/repl.js

@@ -100,6 +100,25 @@ const VERSION = '2.5.1';
 //   State 0 (no demo yet): recommend demo, hide exam setup / exam <token>
 //   State 1 (demo done, no setup): show demo completion + setup CTA, hide token
 //   State 2 (demo done + setup done): show token entry CTA
+// Quick Python version check (used in Selection menu startup warning).
+// Returns {ok, version, status}. Silent/defensive — any error means 'missing'.
+function checkPython() {
+    try {
+        const out = execSyncFn('python3 --version', { encoding: 'utf-8', timeout: 2000 }).trim();
+        const version = out.replace('Python ', '');
+        const [maj, min] = version.split('.').map(Number);
+        if (maj === 3 && min === 12)
+            return { ok: true, version, status: 'ok' };
+        if (maj === 3 && min >= 10 && min < 12)
+            return { ok: true, version, status: 'old' };
+        if (maj === 3 && min > 12)
+            return { ok: true, version, status: 'new' };
+        return { ok: false, version, status: 'missing' };
+    }
+    catch {
+        return { ok: false, version: '', status: 'missing' };
+    }
+}
 function printSelectionMenu() {
     const stats = getDemoStats();
     const setupDone = isExamSetupComplete();
@@ -107,6 +126,22 @@ function printSelectionMenu() {
     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) {
+        const py = checkPython();
+        if (py.status === 'missing') {
+            console.log(chalk.yellow('   ⚠ Python not detected. For exam practical questions:'));
+            console.log(chalk.gray('     → ') + chalk.bold.cyan('env python') + chalk.gray('  (platform install guide)'));
+            console.log();
+        }
+        else if (py.status === 'new') {
+            console.log(chalk.yellow(`   ⚠ Python ${py.version} may lack CTF wheels. Python 3.12 recommended:`));
+            console.log(chalk.gray('     → ') + chalk.bold.cyan('env python') + chalk.gray('  (install guide)'));
+            console.log();
+        }
+    }
     if (stats.attempts === 0) {
         // State 0: brand new user. Only demo matters right now.
         console.log(chalk.white('   New here? Start with ') + chalk.bold.cyan('demo') + chalk.white(' — it takes a few minutes.'));
@@ -751,7 +786,7 @@ export async function startRepl(program, resumeMode) {
         }
         const cmd = input.split(/\s+/)[0].toLowerCase();
         // ─── Mode-based command filtering ───
-        const selectionCommands = ['exam', 'demo', 'retry', 'nations', 'next', 'prev', 'continue', 'setup', 'lang', 'ref', 'ai4ctf', 'ctf4ai', 'mark', 'unmark', 'review', 'submit'];
+        const selectionCommands = ['exam', 'demo', 'retry', 'nations', 'next', 'prev', 'continue', 'setup', 'lang', 'ref', 'ai4ctf', 'ctf4ai', 'mark', 'unmark', 'review', 'submit', 'env'];
         const organizerCommands = ['join', 'exam', 'demo', 'retry', 'next', 'prev', 'logout', 'setup', 'lang', 'ref', 'ctf', 'mark', 'unmark', 'review', 'submit'];
         // Selection mode allows shell commands prefixed with ! — contestants
         // need !python3, !cat, !base64 etc. for practical questions (Q31-Q40).

package/package.json

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