icoa-cli 2.19.80 → 2.19.82

package/dist/commands/env.js

@@ -272,8 +272,125 @@ 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';
+    // Prefer the versioned binary if available. On macOS with Homebrew, `python3`
+    // often points to the latest (e.g. 3.13) while python@3.12 is also installed
+    // at /opt/homebrew/opt/python@3.12/bin/python3.12. Don't force the user to
+    // reinstall just because the default changed.
+    const pyProbes = [
+        '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',
+    ];
+    for (const cmd of pyProbes) {
+        try {
+            const out = execSync(cmd, { encoding: 'utf-8', timeout: 3000 }).trim();
+            const ver = out.replace('Python ', '');
+            const parts = ver.split('.').map(Number);
+            // Only accept as "ok" if this probe returned 3.12. Otherwise keep trying.
+            if (parts[0] === 3 && parts[1] === 12) {
+                currentPy = ver;
+                pyStatus = 'ok';
+                break;
+            }
+            // Remember the last-seen version for fallback reporting
+            currentPy = ver;
+            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 { /* try next probe */ }
+    }
+    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/repl.js

@@ -100,6 +100,39 @@ 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() {
+    // 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.
+    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',
+    ];
+    let lastVersion = '';
+    let lastStatus = 'missing';
+    for (const cmd of probes) {
+        try {
+            const out = execSyncFn(cmd, { 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' };
+            lastVersion = version;
+            if (maj === 3 && min >= 10 && min < 12)
+                lastStatus = 'old';
+            else if (maj === 3 && min > 12)
+                lastStatus = 'new';
+            else
+                lastStatus = 'missing';
+        }
+        catch { /* try next probe */ }
+    }
+    return { ok: lastStatus !== 'missing', version: lastVersion, status: lastStatus };
+}
 function printSelectionMenu() {
     const stats = getDemoStats();
     const setupDone = isExamSetupComplete();
@@ -107,6 +140,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 +800,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.80",
+  "version": "2.19.82",
   "description": "ICOA CLI — The world's first CLI-native CTF competition terminal",
   "type": "module",
   "bin": {