icoa-cli 2.19.40 → 2.19.42

package/dist/commands/exam.js

@@ -8,6 +8,8 @@ import { logCommand } from '../lib/logger.js';
 import { printSuccess, printError, printWarning, printInfo, printTable, printHeader, printKeyValue, createSpinner, formatCountdown, } from '../lib/ui.js';
 import { t } from '../lib/i18n.js';
 import { getDeviceFingerprint } from '../lib/access.js';
+import { getExamSetup, saveExamSetup, isExamSetupComplete } from '../lib/exam-setup.js';
+import { execSync } from 'node:child_process';
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // Fire-and-forget event POST to /api/icoa/demo-stats. Used for demo-flow
 // choice points (demo enter, retry, back) where we want a server-side
@@ -582,6 +584,9 @@ export function registerExamCommand(program) {
             state._helpMax = help.max;
             state._helpPerQ = help.perQ;
             state._eliminated = help.eliminated;
+            if (!state.interactions)
+                state.interactions = [];
+            state.interactions.push({ ts: new Date().toISOString(), q: currentQ, type: 'help_used', result: `eliminated ${toRemove}` });
             saveExamState(state);
             console.log();
             console.log(chalk.yellow(`  💡 Option ${toRemove} eliminated!`) + chalk.gray(`  (help ${help.used}/${help.max})`));
@@ -605,6 +610,9 @@ export function registerExamCommand(program) {
             state._helpMax = help.max;
             state._helpPerQ = help.perQ;
             state._eliminated = help.eliminated;
+            if (!state.interactions)
+                state.interactions = [];
+            state.interactions.push({ ts: new Date().toISOString(), q: currentQ, type: 'help_used', result: `eliminated ${toRemove}` });
             saveExamState(state);
             console.log();
             console.log(chalk.yellow(`  💡 Option ${toRemove} eliminated!`) + chalk.gray(`  (help ${help.used}/${help.max})`));
@@ -674,6 +682,17 @@ export function registerExamCommand(program) {
                 return;
             }
         }
+        // Log interaction
+        const prevAnswer = state.answers[num];
+        if (!state.interactions)
+            state.interactions = [];
+        state.interactions.push({
+            ts: new Date().toISOString(),
+            q: num,
+            type: prevAnswer ? 'answer_changed' : 'answer_submitted',
+            input: c,
+            result: prevAnswer ? `changed from ${prevAnswer}` : 'new',
+        });
         state.answers[num] = c;
         state._lastQ = num;
         saveExamState(state);
@@ -966,8 +985,13 @@ export function registerExamCommand(program) {
                 const res = await fetch(`${serverUrl}/api/icoa/exams/${state.session.examId}/submit`, {
                     method: 'POST',
                     headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify({ token: examToken, answers: state.answers }),
-                    signal: AbortSignal.timeout(10000),
+                    body: JSON.stringify({
+                        token: examToken,
+                        answers: state.answers,
+                        interactions: state.interactions || [],
+                        aiUsage: state.aiUsage || { ai4ctf: 0, ctf4ai: 0 },
+                    }),
+                    signal: AbortSignal.timeout(15000),
                 });
                 if (!res.ok) {
                     const err = await res.json().catch(() => ({ message: 'Submit failed' }));
@@ -1048,8 +1072,29 @@ export function registerExamCommand(program) {
             printInfo('Use "exam review" or "exam submit" first.');
             return;
         }
+        // Gate: require exam setup
+        if (!isExamSetupComplete()) {
+            console.log();
+            printWarning('Pre-exam setup required before entering a token.');
+            console.log(chalk.gray('  → ') + chalk.bold.cyan('exam setup'));
+            console.log();
+            return;
+        }
+        // Auto-set language from token country prefix
+        const COUNTRY_LANG = {
+            UA: 'uk', PE: 'es', CN: 'zh', AU: 'en', JP: 'ja', KR: 'ko',
+            BR: 'pt', SA: 'ar', FR: 'fr', DE: 'de', IN: 'hi', ID: 'id',
+            TH: 'th', VN: 'vi', TR: 'tr', RU: 'ru', EG: 'ar', HT: 'ht',
+            PH: 'en', MY: 'en', SG: 'en', ZA: 'en',
+        };
+        const countryPrefix = code.trim().substring(0, 2).toUpperCase();
+        const detectedLang = COUNTRY_LANG[countryPrefix];
         const config = getConfig();
         const serverUrl = config.ctfdUrl || 'https://practice.icoa2026.au';
+        const lang = detectedLang || config.language || 'en';
+        if (detectedLang && detectedLang !== (config.language || 'en')) {
+            saveConfig({ language: detectedLang });
+        }
         console.log();
         drawProgress(0, 'Validating token...');
         try {
@@ -1059,7 +1104,7 @@ export function registerExamCommand(program) {
                 body: JSON.stringify({
                     token: code.trim(),
                     deviceHash: getDeviceFingerprint(),
-                    lang: config.language || 'en',
+                    lang,
                 }),
                 signal: AbortSignal.timeout(10000),
             });
@@ -1073,19 +1118,49 @@ export function registerExamCommand(program) {
             }
             drawProgress(30, 'Loading exam...');
             const json = await res.json();
-            const { session, questions } = json.data;
-            drawProgress(60, 'Preparing questions...');
+            const { session, questions, languages } = json.data;
+            drawProgress(60, 'Preparing...');
             await sleep(200);
-            drawProgress(90, 'Starting timer...');
-            await sleep(150);
-            saveExamState({ session, questions, answers: {} });
             drawProgress(100, 'Ready!');
             console.log();
             console.log();
+            // ── Exam info page (timer NOT started yet) ──
             printHeader(session.examName);
-            printKeyValue('Questions', String(session.questionCount));
+            console.log();
+            printKeyValue('Questions', `${session.questionCount} (30 MCQ + 10 practical)`);
             printKeyValue('Duration', `${session.durationMinutes} minutes`);
-            printTimeRemaining();
+            printKeyValue('Total', `${session.totalScore || 150} points`);
+            printKeyValue('Pass', `${session.passingScore || 75} points (50%)`);
+            console.log();
+            console.log(chalk.white('  Assistance:'));
+            console.log(chalk.gray('    Help:    10 uses + 5 hidden bonus (MCQ only)'));
+            console.log(chalk.gray('    Hints:   A(5) B(3) C(1) — practical only'));
+            console.log(chalk.gray('    AI:      25K AI4CTF + 25K CTF4AI tokens'));
+            if (languages && languages.length > 1) {
+                console.log(chalk.gray(`    Lang:    ${languages.join(', ')} — switch with: lang <code>`));
+            }
+            console.log();
+            console.log(chalk.yellow('  Rules:'));
+            console.log(chalk.gray('    • All interactions are recorded for audit'));
+            console.log(chalk.gray('    • Timer auto-submits when time expires'));
+            console.log(chalk.gray('    • You may exit and resume with the same token'));
+            console.log();
+            // ── Wait for confirmation ──
+            const readline = await import('node:readline');
+            const rlConfirm = readline.createInterface({ input: process.stdin, output: process.stdout });
+            await new Promise((resolve) => {
+                rlConfirm.question(chalk.bold.yellow('  Press Enter to start the exam timer... '), () => {
+                    rlConfirm.close();
+                    resolve();
+                });
+            });
+            // ── Timer starts NOW ──
+            const confirmedAt = new Date().toISOString();
+            session.confirmedAt = confirmedAt;
+            saveExamState({ session, questions, answers: {}, interactions: [], aiUsage: { ai4ctf: 0, ctf4ai: 0 } });
+            console.log();
+            printSuccess('Exam started! Timer is running.');
+            printKeyValue('Time Remaining', `${session.durationMinutes}:00`);
             if (questions.length > 0) {
                 printQuestion(questions[0]);
             }
@@ -1236,7 +1311,137 @@ export function registerExamCommand(program) {
         printKeyValue('Duration', 'No time limit');
         printQuestion(retryQuestions[0]);
     });
-    // Default action: show status or help
+    // ─── exam setup ───
+    exam
+        .command('setup')
+        .description('Install Python environment for practical exam questions')
+        .action(async () => {
+        logCommand('exam setup');
+        // Gate: require at least 1 demo attempt
+        const stats = getDemoStats();
+        if (stats.attempts === 0) {
+            console.log();
+            printWarning('Complete the demo first before setting up.');
+            console.log(chalk.gray('  → ') + chalk.bold.cyan('exam demo'));
+            console.log();
+            return;
+        }
+        // Skip if already set up
+        const existingSetup = getExamSetup();
+        if (existingSetup) {
+            console.log();
+            console.log(chalk.green('  ✓ ') + chalk.green('Environment already set up'));
+            console.log(chalk.gray(`    Completed: ${existingSetup.completedAt.split('T')[0]}`));
+            console.log(chalk.gray(`    Python: ${existingSetup.pythonVersion}`));
+            console.log(chalk.gray(`    Packages: ${existingSetup.installedPackages.length} installed`));
+            if (existingSetup.failedPackages.length > 0) {
+                console.log(chalk.yellow(`    Failed: ${existingSetup.failedPackages.join(', ')}`));
+            }
+            console.log();
+            console.log(chalk.white('  Next step: ') + chalk.bold.cyan('exam <token>'));
+            console.log();
+            return;
+        }
+        console.log();
+        printHeader('Exam Environment Setup');
+        console.log();
+        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+
+        const pythonBin = 'python3';
+        let pythonVersion = '';
+        try {
+            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)) {
+                printError(`Python ${pythonVersion} found, but 3.12+ required.`);
+                printInfo('Install: https://www.python.org/downloads/');
+                return;
+            }
+            console.log(chalk.green(`  ✓ Python ${pythonVersion}`));
+        }
+        catch {
+            printError('Python 3 not found.');
+            printInfo('Install: https://www.python.org/downloads/');
+            return;
+        }
+        // Step 2: Check pip
+        try {
+            execSync(`${pythonBin} -m pip --version`, { stdio: 'ignore', timeout: 5000 });
+            console.log(chalk.green('  ✓ pip available'));
+        }
+        catch {
+            console.log(chalk.yellow('  ⚠ pip not found, trying ensurepip...'));
+            try {
+                execSync(`${pythonBin} -m ensurepip --upgrade`, { stdio: 'ignore', timeout: 30000 });
+                console.log(chalk.green('  ✓ pip installed'));
+            }
+            catch {
+                printError('Could not install pip.');
+                return;
+            }
+        }
+        // Step 3: Install packages
+        const PACKAGES = [
+            'pwntools', 'cryptography', 'requests', 'beautifulsoup4',
+            'numpy', 'pillow', 'scapy', 'sympy', 'z3-solver',
+            'pycryptodome', 'ROPgadget', 'volatility3', 'regex',
+        ];
+        const IMPORT_MAP = {
+            'beautifulsoup4': 'bs4', 'pycryptodome': 'Crypto', 'z3-solver': 'z3',
+            'pillow': 'PIL', 'pwntools': 'pwn', 'ROPgadget': 'ropgadget',
+        };
+        console.log();
+        console.log(chalk.white(`  Installing ${PACKAGES.length} packages...`));
+        console.log();
+        const installed = [];
+        const failed = [];
+        for (const pkg of PACKAGES) {
+            try {
+                execSync(`${pythonBin} -m pip install "${pkg}" --quiet 2>/dev/null`, {
+                    encoding: 'utf-8', timeout: 180000, stdio: 'pipe',
+                });
+                const importName = IMPORT_MAP[pkg] || pkg;
+                execSync(`${pythonBin} -c "import ${importName}"`, { stdio: 'ignore', timeout: 10000 });
+                let ver = '';
+                try {
+                    const showOut = execSync(`${pythonBin} -m pip show "${pkg}" 2>/dev/null`, {
+                        encoding: 'utf-8', timeout: 5000,
+                    });
+                    const m = showOut.match(/^Version:\s*(.+)$/m);
+                    if (m)
+                        ver = m[1].trim();
+                }
+                catch { }
+                console.log(chalk.green(`  ✓ ${pkg}`) + (ver ? chalk.gray(` (${ver})`) : ''));
+                installed.push(ver ? `${pkg}==${ver}` : pkg);
+            }
+            catch {
+                console.log(chalk.red(`  ✗ ${pkg}`));
+                failed.push(pkg);
+            }
+        }
+        // Save state
+        saveExamSetup({
+            completedAt: new Date().toISOString(),
+            pythonVersion,
+            installedPackages: installed,
+            failedPackages: failed,
+        });
+        console.log();
+        if (failed.length === 0) {
+            printSuccess(`Environment ready! All ${PACKAGES.length} packages installed.`);
+        }
+        else {
+            printWarning(`${installed.length}/${PACKAGES.length} packages installed. ${failed.length} failed: ${failed.join(', ')}`);
+        }
+        console.log();
+        console.log(chalk.white('  Next step: ') + chalk.bold.cyan('exam <token>'));
+        console.log();
+    });
+    // Default action: progressive onboarding dashboard
     exam.action(() => {
         logCommand('exam');
         const state = getExamState();
@@ -1247,14 +1452,29 @@ export function registerExamCommand(program) {
             printKeyValue('Progress', `${answered}/${state.session.questionCount} answered`);
             console.log();
             console.log(chalk.gray('  exam q [n]  | exam answer <n> <A-D> | exam review | exam submit'));
+            return;
+        }
+        const stats = getDemoStats();
+        const setup = getExamSetup();
+        console.log();
+        printHeader('ICOA National Selection Exam');
+        console.log();
+        if (stats.attempts === 0) {
+            console.log(chalk.yellow('  ○ ') + chalk.yellow('Recommended: complete demo first'));
+            console.log(chalk.gray('    → ') + chalk.bold.cyan('exam demo'));
         }
         else {
-            console.log();
-            console.log(chalk.white('  No exam in progress.'));
-            console.log();
-            console.log(chalk.white('    exam demo       ') + chalk.gray('Try free practice exam (no account needed)'));
-            console.log(chalk.white('    exam list       ') + chalk.gray('View exams (requires login)'));
-            console.log();
+            console.log(chalk.green('  ● ') + chalk.green(`Demo completed (${stats.attempts} attempt${stats.attempts !== 1 ? 's' : ''})`));
+            if (!setup) {
+                console.log(chalk.yellow('  ○ ') + chalk.yellow('Pre-exam setup required'));
+                console.log(chalk.gray('    → ') + chalk.bold.cyan('exam setup'));
+            }
+            else {
+                console.log(chalk.green('  ● ') + chalk.green('Environment ready'));
+                console.log(chalk.yellow('  ○ ') + chalk.yellow('Enter exam token to begin'));
+                console.log(chalk.gray('    → ') + chalk.bold.cyan('exam <token>'));
+            }
         }
+        console.log();
     });
 }

package/dist/lib/exam-setup.d.ts

@@ -0,0 +1,9 @@
+export interface ExamSetupState {
+    completedAt: string;
+    pythonVersion: string;
+    installedPackages: string[];
+    failedPackages: string[];
+}
+export declare function getExamSetup(): ExamSetupState | null;
+export declare function saveExamSetup(state: ExamSetupState): void;
+export declare function isExamSetupComplete(): boolean;

package/dist/lib/exam-setup.js

@@ -0,0 +1,23 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getIcoaDir } from './config.js';
+const SETUP_FILE = () => join(getIcoaDir(), 'exam-setup.json');
+export function getExamSetup() {
+    try {
+        if (!existsSync(SETUP_FILE()))
+            return null;
+        return JSON.parse(readFileSync(SETUP_FILE(), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveExamSetup(state) {
+    try {
+        writeFileSync(SETUP_FILE(), JSON.stringify(state, null, 2));
+    }
+    catch { }
+}
+export function isExamSetupComplete() {
+    return getExamSetup() !== null;
+}

package/dist/lib/exam-state.d.ts

@@ -4,3 +4,4 @@ export declare function saveExamState(state: ExamState): void;
 export declare function clearExamState(): void;
 export declare function isExamActive(): boolean;
 export declare function getExamDeadline(): Date | null;
+export declare function addInteraction(interaction: import('../types/index.js').ExamInteraction): void;

package/dist/lib/exam-state.js

@@ -32,6 +32,17 @@ export function getExamDeadline() {
         return null;
     if (!state.session.durationMinutes)
         return null; // 0 = no time limit
-    const start = new Date(state.session.startedAt).getTime();
+    // Use confirmedAt (when user pressed Enter) as the real start, fallback to startedAt
+    const startTime = state.session.confirmedAt || state.session.startedAt;
+    const start = new Date(startTime).getTime();
     return new Date(start + state.session.durationMinutes * 60 * 1000);
 }
+export function addInteraction(interaction) {
+    const state = getExamState();
+    if (!state)
+        return;
+    if (!state.interactions)
+        state.interactions = [];
+    state.interactions.push(interaction);
+    saveExamState(state);
+}

package/dist/lib/gemini.js

@@ -184,6 +184,9 @@ export async function createChatSession(context, customSystemPrompt) {
             });
             if (!res.ok) {
                 const err = await res.json().catch(() => ({ message: 'AI proxy error' }));
+                if (res.status === 429) {
+                    throw new Error(chalk.yellow('⏳ ') + (err.message || 'Too many requests. Please wait a moment and try again.'));
+                }
                 throw new Error(err.message || `AI proxy returned ${res.status}`);
             }
             const json = await res.json();

package/dist/repl.js

@@ -429,7 +429,7 @@ export async function startRepl(program, resumeMode) {
             rl.prompt();
             return;
         }
-        // ICOA exam token detection (e.g., "ICOA-PE-001")
+        // ICOA exam token detection: legacy "ICOA-PE-001" or new Crockford "UAHXP7SWMM"
         if (/^ICOA-[A-Z]{2,3}-\d{1,6}$/i.test(input.trim())) {
             processing = true;
             try {
@@ -440,6 +440,29 @@ export async function startRepl(program, resumeMode) {
             rl.prompt();
             return;
         }
+        // New 10-char Crockford Base32 token (e.g., UAHXP7SWMM) — no hyphen
+        if (/^[A-Z]{2}[0-9A-HJKMNP-TV-Z]{8}$/i.test(input.trim())) {
+            processing = true;
+            try {
+                await program.parseAsync(['node', 'icoa', 'exam', 'token', input.trim().toUpperCase()]);
+            }
+            catch { }
+            processing = false;
+            rl.prompt();
+            return;
+        }
+        // "exam UAHXP7SWMM" — 10-char token after exam prefix
+        const examTokenMatch = input.match(/^exam\s+([A-Z]{2}[0-9A-HJKMNP-TV-Z]{8})$/i);
+        if (examTokenMatch) {
+            processing = true;
+            try {
+                await program.parseAsync(['node', 'icoa', 'exam', 'token', examTokenMatch[1].toUpperCase()]);
+            }
+            catch { }
+            processing = false;
+            rl.prompt();
+            return;
+        }
         // "exam AU" / "exam PE" — shortcut to exam list <country>
         const examCountryMatch = input.match(/^exam\s+([A-Z]{2,3})$/i);
         if (examCountryMatch) {

package/dist/types/index.d.ts

@@ -159,14 +159,31 @@ export interface ExamSession {
     examId: string;
     examName: string;
     startedAt: string;
+    confirmedAt?: string;
     durationMinutes: number;
     questionCount: number;
+    totalScore?: number;
+    passingScore?: number;
     country: string;
+    token?: string;
+}
+export interface ExamInteraction {
+    ts: string;
+    q: number;
+    type: 'prompt_attempt' | 'hint_used' | 'help_used' | 'ai_hint' | 'answer_submitted' | 'answer_changed';
+    input?: string;
+    result?: string;
+    tokens?: number;
 }
 export interface ExamState {
     session: ExamSession;
     questions: ExamQuestion[];
     answers: Record<number, string>;
+    interactions?: ExamInteraction[];
+    aiUsage?: {
+        ai4ctf: number;
+        ctf4ai: number;
+    };
 }
 export interface ExamResult {
     examId: string;

package/package.json

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