icoa-cli 2.3.2 → 2.5.2

package/dist/commands/ref.js

@@ -44,8 +44,8 @@ export function registerRefCommand(program) {
             const rows = files.map((f) => [chalk.white(f)]);
             printTable(['Topic'], rows);
             console.log();
-            console.log(chalk.gray(`  Usage: icoa ref <topic>`));
-            console.log(chalk.gray(`  Example: icoa ref python`));
+            console.log(chalk.gray(`  Usage: ref <topic>`));
+            console.log(chalk.gray(`  Example: ref python`));
             console.log();
             return;
         }
@@ -53,7 +53,7 @@ export function registerRefCommand(program) {
         const filePath = join(refsDir, `${topic}.txt`);
         if (!existsSync(filePath)) {
             printError(`Reference not found: ${topic}`);
-            printInfo('Run "icoa ref" to see available topics.');
+            printInfo('Run "ref" to see available topics.');
             return;
         }
         const content = readFileSync(filePath, 'utf-8');

package/dist/commands/setup.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import { input, select } from '@inquirer/prompts';
-import { getConfig } from '../lib/config.js';
+import { getConfig, saveConfig } from '../lib/config.js';
 import { setApiKey } from '../lib/gemini.js';
 import { printSuccess, printError, printInfo, printHeader, printKeyValue } from '../lib/ui.js';
 import { logCommand } from '../lib/logger.js';
@@ -18,11 +18,13 @@ export function registerSetupCommand(program) {
         printKeyValue('CTFd Token', config.token ? chalk.green('Configured') : chalk.gray('Not configured'));
         printKeyValue('Gemini API Key', config.geminiApiKey || process.env.GEMINI_API_KEY ? chalk.green('Configured') : chalk.gray('Not configured'));
         printKeyValue('Language', config.language);
+        printKeyValue('Mode', config.mode || chalk.gray('Not set'));
         printKeyValue('Session ID', config.sessionId.substring(0, 8) + '...');
         console.log();
         const action = await select({
             message: 'What would you like to configure?',
             choices: [
+                { name: 'Switch Mode', value: 'mode' },
                 { name: 'Gemini API Key', value: 'gemini' },
                 { name: 'CTFd Connection', value: 'ctfd' },
                 { name: 'Reset Hint Budget', value: 'budget' },
@@ -31,6 +33,19 @@ export function registerSetupCommand(program) {
             ],
         });
         switch (action) {
+            case 'mode': {
+                const newMode = await select({
+                    message: 'Select mode:',
+                    choices: [
+                        { name: 'National Selection — Exam only, lightweight', value: 'selection' },
+                        { name: 'International Olympiad — Full CTF with AI assistance', value: 'olympiad' },
+                        { name: 'National/Regional Partner — Organizer management', value: 'organizer' },
+                    ],
+                });
+                saveConfig({ mode: newMode });
+                printSuccess(`Mode switched to: ${newMode}. Restart ICOA CLI to apply.`);
+                break;
+            }
             case 'gemini': {
                 console.log();
                 printInfo('Get your API key from: https://aistudio.google.com/apikey');
@@ -46,7 +61,7 @@ export function registerSetupCommand(program) {
                 break;
             }
             case 'ctfd': {
-                printInfo('Use "icoa ctf join <url>" to connect to a CTFd instance.');
+                printInfo('Use "join <url>" to connect to a CTFd instance.');
                 break;
             }
             case 'budget': {

package/dist/index.js

@@ -13,6 +13,7 @@ import { registerLangCommand } from './commands/lang.js';
 import { registerSetupCommand } from './commands/setup.js';
 import { registerEnvCommand } from './commands/env.js';
 import { registerAi4ctfCommand } from './commands/ai4ctf.js';
+import { registerExamCommand } from './commands/exam.js';
 import { getConfig, saveConfig } from './lib/config.js';
 import { startRepl } from './repl.js';
 import { setTerminalTheme } from './lib/theme.js';
@@ -37,7 +38,7 @@ ${LINE}
    ${chalk.white('Sydney, Australia')}  ${chalk.gray('Jun 27 - Jul 2, 2026')}
    ${chalk.cyan.underline('https://icoa2026.au')}
 
-   ${chalk.gray('CLI-Native Competition Terminal  v2.3.2')}
+   ${chalk.gray('CLI-Native Competition Terminal  v2.5.2')}
 
 ${LINE}
 `;
@@ -83,6 +84,7 @@ registerLangCommand(program);
 registerSetupCommand(program);
 registerEnvCommand(program);
 registerAi4ctfCommand(program);
+registerExamCommand(program);
 // Hidden command: switch AI model
 program
     .command('model', { hidden: true })

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

@@ -0,0 +1,14 @@
+import type { ExamListItem, ExamQuestion, ExamSession, ExamResult } from '../types/index.js';
+export declare class ExamClient {
+    private baseUrl;
+    private token;
+    constructor(baseUrl: string, token: string);
+    private request;
+    getExams(): Promise<ExamListItem[]>;
+    startExam(examId: string): Promise<{
+        session: ExamSession;
+        questions: ExamQuestion[];
+    }>;
+    submitExam(examId: string, answers: Record<number, string>): Promise<ExamResult>;
+    getResult(examId: string): Promise<ExamResult>;
+}

package/dist/lib/exam-client.js

@@ -0,0 +1,41 @@
+export class ExamClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+        this.token = token;
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}:9090/api/icoa/exams${path}`;
+        const res = await fetch(url, {
+            method,
+            headers: {
+                Authorization: `Token ${this.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: body ? JSON.stringify(body) : undefined,
+            signal: AbortSignal.timeout(10000),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => 'Unknown error');
+            throw new Error(`Exam API error (${res.status}): ${text}`);
+        }
+        const json = await res.json();
+        if (json.success === false) {
+            throw new Error(json.message || 'Exam API error');
+        }
+        return json.data;
+    }
+    async getExams() {
+        return this.request('GET', '');
+    }
+    async startExam(examId) {
+        return this.request('POST', `/${examId}/start`);
+    }
+    async submitExam(examId, answers) {
+        return this.request('POST', `/${examId}/submit`, { answers });
+    }
+    async getResult(examId) {
+        return this.request('GET', `/${examId}/result`);
+    }
+}

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

@@ -0,0 +1,6 @@
+import type { ExamState } from '../types/index.js';
+export declare function getExamState(): ExamState | null;
+export declare function saveExamState(state: ExamState): void;
+export declare function clearExamState(): void;
+export declare function isExamActive(): boolean;
+export declare function getExamDeadline(): Date | null;

package/dist/lib/exam-state.js

@@ -0,0 +1,35 @@
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { getIcoaDir } from './config.js';
+function stateFile() {
+    return join(getIcoaDir(), 'exam-state.json');
+}
+export function getExamState() {
+    const f = stateFile();
+    if (!existsSync(f))
+        return null;
+    try {
+        return JSON.parse(readFileSync(f, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveExamState(state) {
+    writeFileSync(stateFile(), JSON.stringify(state, null, 2));
+}
+export function clearExamState() {
+    const f = stateFile();
+    if (existsSync(f))
+        unlinkSync(f);
+}
+export function isExamActive() {
+    return getExamState() !== null;
+}
+export function getExamDeadline() {
+    const state = getExamState();
+    if (!state)
+        return null;
+    const start = new Date(state.session.startedAt).getTime();
+    return new Date(start + state.session.durationMinutes * 60 * 1000);
+}

package/dist/postinstall.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Post-install script: shows a progress bar during ICOA CLI setup.
+ * Runs automatically after `npm install -g icoa-cli`.
+ */
+export {};

package/dist/postinstall.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * Post-install script: shows a progress bar during ICOA CLI setup.
+ * Runs automatically after `npm install -g icoa-cli`.
+ */
+const steps = [
+    'Initializing ICOA CLI...',
+    'Loading competition modules...',
+    'Configuring exam system...',
+    'Setting up references...',
+    'Finalizing installation...',
+];
+const BAR_WIDTH = 30;
+const TOTAL = 100;
+function drawBar(percent, label) {
+    const filled = Math.round((percent / TOTAL) * BAR_WIDTH);
+    const empty = BAR_WIDTH - filled;
+    const bar = '\x1b[32m' + '█'.repeat(filled) + '\x1b[90m' + '░'.repeat(empty) + '\x1b[0m';
+    const pct = String(percent).padStart(3) + '%';
+    process.stdout.write(`\r  ${bar} ${pct}  \x1b[90m${label}\x1b[0m`);
+}
+async function run() {
+    console.log();
+    console.log('  \x1b[1m\x1b[37m██╗ ██████╗ ██████╗  █████╗\x1b[0m');
+    console.log('  \x1b[1m\x1b[37m██║██╔════╝██╔═══██╗██╔══██╗\x1b[0m');
+    console.log('  \x1b[1m\x1b[37m██║██║     ██║   ██║███████║\x1b[0m');
+    console.log('  \x1b[1m\x1b[37m██║██║     ██║   ██║██╔══██║\x1b[0m');
+    console.log('  \x1b[1m\x1b[37m██║╚██████╗╚██████╔╝██║  ██║\x1b[0m');
+    console.log('  \x1b[1m\x1b[37m╚═╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═╝\x1b[0m');
+    console.log();
+    for (let i = 0; i < steps.length; i++) {
+        const startPct = Math.round((i / steps.length) * TOTAL);
+        const endPct = Math.round(((i + 1) / steps.length) * TOTAL);
+        for (let p = startPct; p <= endPct; p++) {
+            drawBar(p, steps[i]);
+            await new Promise((r) => setTimeout(r, 15));
+        }
+    }
+    console.log();
+    console.log();
+    console.log('  \x1b[32m✓\x1b[0m ICOA CLI installed successfully!');
+    console.log();
+    console.log('  \x1b[90mGet started:\x1b[0m');
+    console.log('    \x1b[1m\x1b[37micoa\x1b[0m              \x1b[90mLaunch and select your mode\x1b[0m');
+    console.log('    \x1b[1m\x1b[37micoa --help\x1b[0m        \x1b[90mShow all commands\x1b[0m');
+    console.log();
+}
+run().catch(() => { });
+export {};

package/dist/repl.js

@@ -1,9 +1,10 @@
 import { createInterface } from 'node:readline';
 import { spawn, execSync as execSyncFn } from 'node:child_process';
 import chalk from 'chalk';
-import { isConnected, getConfig } from './lib/config.js';
+import { isConnected, getConfig, saveConfig } from './lib/config.js';
 import { isActivated, activateToken, isFreeCommand, isDeviceMatch, recordExit, recordResume, isFirstRunOrUpgrade, markVersionSeen } from './lib/access.js';
 import { setReplMode } from './lib/ui.js';
+import { isChatActive, handleChatMessage } from './commands/ai4ctf.js';
 import { resetTerminalTheme } from './lib/theme.js';
 import { ensureSandbox, runInSandbox, isDockerAvailable } from './lib/sandbox.js';
 import { logCommand } from './lib/logger.js';
@@ -27,14 +28,42 @@ const BLOCKED_COMMANDS = new Set([
     'iptables', 'ufw', // firewall
 ]);
 const INTERCEPT = '__REPL_NO_EXIT__';
-const VERSION = '2.3.2';
+const VERSION = '2.5.1';
 export async function startRepl(program, resumeMode) {
     const config = getConfig();
     const connected = isConnected();
     const realExit = process.exit.bind(process);
     const activated = isActivated();
-    // First run or upgrade: prompt to install env
-    if (isFirstRunOrUpgrade(VERSION)) {
+    // ─── Mode selection (first run) ───
+    let mode = config.mode || '';
+    if (!mode) {
+        const { select, confirm } = await import('@inquirer/prompts');
+        console.log(chalk.white('   Welcome! Please select your mode.'));
+        console.log(chalk.gray('   Use ↑↓ arrow keys to move, Enter to confirm.'));
+        console.log(chalk.gray('   You can switch mode later via: setup'));
+        console.log();
+        mode = await select({
+            message: 'Mode',
+            choices: [
+                { name: `  ${chalk.bold('National Selection')}         ${chalk.gray('·')}  ${chalk.gray('Exam only, lightweight')}`, value: 'selection' },
+                { name: `  ${chalk.bold('International Olympiad')}     ${chalk.gray('·')}  ${chalk.gray('CTF x AI (~500MB)')}`, value: 'olympiad' },
+                { name: `  ${chalk.bold('National/Regional Partner')}  ${chalk.gray('·')}  ${chalk.gray('Organizer management')}`, value: 'organizer' },
+            ],
+        });
+        if (mode === 'olympiad') {
+            console.log();
+            console.log(chalk.yellow('   This mode will download ~500MB of CTF tools and AI models.'));
+            const proceed = await confirm({ message: 'Continue?', default: true });
+            if (!proceed) {
+                mode = 'selection';
+                console.log(chalk.gray('   Switched to National Selection mode.'));
+            }
+        }
+        saveConfig({ mode });
+        console.log();
+    }
+    // First run or upgrade: prompt to install env (olympiad only)
+    if (mode === 'olympiad' && isFirstRunOrUpgrade(VERSION)) {
         markVersionSeen(VERSION);
         console.log(chalk.gray('   Checking competition environment...'));
         // Quick check: count missing Python libs
@@ -90,41 +119,66 @@ export async function startRepl(program, resumeMode) {
             console.log();
         }
     }
-    // Device mismatch check
-    if (activated && !isDeviceMatch()) {
-        console.log(chalk.red('   Token was activated on a different device.'));
-        console.log(chalk.gray('   Contact organizer for assistance.'));
-        console.log();
-    }
-    else if (connected) {
-        console.log(chalk.green(`   Welcome back, ${config.userName}!`));
-        console.log(chalk.gray(`   Connected to ${config.ctfdUrl}`));
-        console.log();
-    }
-    else if (activated) {
-        ensureWorkspace();
-        console.log(chalk.green('   Welcome, competitor! Ready to hack.'));
-        console.log(chalk.gray(`   Workspace: ${WORKSPACE}`));
-        console.log();
-        console.log(chalk.gray('   Quick Start'));
-        console.log(chalk.gray('   ─────────────'));
-        console.log(chalk.white('   join <url>       ') + chalk.gray('Connect to competition'));
-        console.log(chalk.white('   challenges       ') + chalk.gray('View challenges'));
-        console.log(chalk.white('   hint <question>  ') + chalk.gray('Ask AI for help'));
-        console.log(chalk.white('   env              ') + chalk.gray('Check your tools'));
-        console.log(chalk.white('   help             ') + chalk.gray('All commands'));
-        console.log();
+    // ─── Mode-specific welcome ───
+    if (mode === 'selection' || mode === 'organizer') {
+        // Lightweight modes: skip activate/device checks
+        const modeLabel = mode === 'selection'
+            ? chalk.cyan.bold('[Selection Mode]')
+            : chalk.yellow.bold('[Organizer Mode]');
+        if (connected) {
+            console.log(chalk.green(`   Welcome back, ${config.userName}!`) + '  ' + modeLabel);
+            console.log(chalk.gray(`   Connected to ${config.ctfdUrl}`));
+            console.log(chalk.gray('   Switch mode: setup'));
+            console.log();
+        }
+        else {
+            console.log('   ' + modeLabel + chalk.gray('  (switch via: setup)'));
+            console.log();
+            console.log(chalk.gray('   Quick Start'));
+            console.log(chalk.gray('   ─────────────'));
+            console.log(chalk.white('   join <url>       ') + chalk.gray('Connect to exam server'));
+            console.log(chalk.white('   exam list        ') + chalk.gray('View available exams'));
+            console.log(chalk.white('   help             ') + chalk.gray('All commands'));
+            console.log();
+        }
     }
     else {
-        console.log(chalk.white('   Welcome to ICOA CLI!'));
-        console.log();
-        console.log(chalk.gray('   Quick Start'));
-        console.log(chalk.gray('   ─────────────'));
-        console.log(chalk.white('   activate <token> ') + chalk.gray('Unlock with your access token'));
-        console.log(chalk.white('   ref <topic>      ') + chalk.gray('Browse tool references'));
-        console.log(chalk.white('   env              ') + chalk.gray('Check your tools'));
-        console.log(chalk.white('   help             ') + chalk.gray('All commands'));
-        console.log();
+        // Olympiad mode: full flow with activate/device checks
+        if (activated && !isDeviceMatch()) {
+            console.log(chalk.red('   Token was activated on a different device.'));
+            console.log(chalk.gray('   Contact organizer for assistance.'));
+            console.log();
+        }
+        else if (connected) {
+            console.log(chalk.green(`   Welcome back, ${config.userName}!`));
+            console.log(chalk.gray(`   Connected to ${config.ctfdUrl}`));
+            console.log();
+        }
+        else if (activated) {
+            ensureWorkspace();
+            console.log(chalk.green('   Welcome, competitor! Ready to hack.'));
+            console.log(chalk.gray(`   Workspace: ${WORKSPACE}`));
+            console.log();
+            console.log(chalk.gray('   Quick Start'));
+            console.log(chalk.gray('   ─────────────'));
+            console.log(chalk.white('   join <url>       ') + chalk.gray('Connect to competition'));
+            console.log(chalk.white('   challenges       ') + chalk.gray('View challenges'));
+            console.log(chalk.white('   hint <question>  ') + chalk.gray('Ask AI for help'));
+            console.log(chalk.white('   env              ') + chalk.gray('Check your tools'));
+            console.log(chalk.white('   help             ') + chalk.gray('All commands'));
+            console.log();
+        }
+        else {
+            console.log(chalk.white('   Welcome to ICOA CLI!'));
+            console.log();
+            console.log(chalk.gray('   Quick Start'));
+            console.log(chalk.gray('   ─────────────'));
+            console.log(chalk.white('   activate <token> ') + chalk.gray('Unlock with your access token'));
+            console.log(chalk.white('   ref <topic>      ') + chalk.gray('Browse tool references'));
+            console.log(chalk.white('   env              ') + chalk.gray('Check your tools'));
+            console.log(chalk.white('   help             ') + chalk.gray('All commands'));
+            console.log();
+        }
     }
     program.exitOverride();
     program.configureOutput({
@@ -147,6 +201,18 @@ export async function startRepl(program, resumeMode) {
             return;
         const input = line.trim();
         if (!input) {
+            rl.setPrompt(isChatActive() ? chalk.magenta('ai4ctf> ') : chalk.green('icoa> '));
+            rl.prompt();
+            return;
+        }
+        // If in AI chat mode, route to chat handler
+        if (isChatActive()) {
+            processing = true;
+            const result = await handleChatMessage(input);
+            processing = false;
+            if (result === 'exit') {
+                rl.setPrompt(chalk.green('icoa> '));
+            }
             rl.prompt();
             return;
         }
@@ -163,7 +229,7 @@ export async function startRepl(program, resumeMode) {
         }
         // Help
         if (input === 'help' || input === '?') {
-            printReplHelp(isActivated());
+            printReplHelp(isActivated(), mode);
             rl.prompt();
             return;
         }
@@ -196,9 +262,24 @@ export async function startRepl(program, resumeMode) {
             rl.prompt();
             return;
         }
-        // Token check — only ref allowed without activation or device mismatch
         const cmd = input.split(/\s+/)[0].toLowerCase();
-        if ((!isActivated() || !isDeviceMatch()) && !isFreeCommand(cmd)) {
+        // ─── Mode-based command filtering ───
+        const selectionCommands = ['join', 'exam', 'setup', 'lang', 'ref', 'ctf'];
+        const organizerCommands = ['join', 'exam', 'setup', 'lang', 'ref', 'ctf'];
+        if (mode === 'selection' && !selectionCommands.includes(cmd)) {
+            console.log(chalk.gray('  Not available in Selection mode. Switch via: setup'));
+            console.log();
+            rl.prompt();
+            return;
+        }
+        if (mode === 'organizer' && !organizerCommands.includes(cmd)) {
+            console.log(chalk.gray('  Not available in Organizer mode. Switch via: setup'));
+            console.log();
+            rl.prompt();
+            return;
+        }
+        // Token check — only in olympiad mode
+        if (mode === 'olympiad' && (!isActivated() || !isDeviceMatch()) && !isFreeCommand(cmd)) {
             console.log(chalk.yellow('  Restricted mode. ') + chalk.gray('Enter your access token:'));
             console.log(chalk.white('    activate <token>'));
             console.log();
@@ -213,6 +294,7 @@ export async function startRepl(program, resumeMode) {
             'scoreboard', 'sb', 'status', 'time', 'hint', 'hint-b', 'hint-c',
             'hint-budget', 'ref', 'shell', 'files', 'connect', 'note',
             'log', 'lang', 'setup', 'env', 'ai4ctf', 'model', 'ctf',
+            'exam',
         ];
         if (!knownCommands.includes(cmd)) {
             // Block dangerous commands
@@ -287,8 +369,6 @@ export async function startRepl(program, resumeMode) {
         process.exit = (() => {
             throw new Error(INTERCEPT);
         });
-        // Pause main readline so sub-REPLs (ai4ctf) can use stdin
-        rl.pause();
         try {
             await program.parseAsync(['node', 'icoa', ...args]);
         }
@@ -310,7 +390,10 @@ export async function startRepl(program, resumeMode) {
         finally {
             process.exit = realExit;
             processing = false;
-            rl.resume();
+        }
+        // Switch prompt if entering chat mode
+        if (isChatActive()) {
+            rl.setPrompt(chalk.magenta('ai4ctf> '));
         }
         console.log();
         rl.prompt();
@@ -364,15 +447,37 @@ function mapCommand(input) {
         'hint', 'hint-b', 'hint-c', 'hint-budget',
         'ref', 'shell', 'files', 'connect', 'note',
         'log', 'lang', 'setup', 'env', 'ai4ctf', 'model',
-        'ctf',
+        'ctf', 'exam',
     ];
     if (directCommands.includes(cmd)) {
         return [cmd, ...rest];
     }
     return parts;
 }
-function printReplHelp(activated) {
+function printReplHelp(activated, mode = 'olympiad') {
     console.log();
+    // ─── Selection / Organizer: lightweight help ───
+    if (mode === 'selection' || mode === 'organizer') {
+        console.log(chalk.bold.white('  Exam'));
+        console.log(chalk.white('    join <url>          ') + chalk.gray('Connect to exam server'));
+        console.log(chalk.white('    exam list           ') + chalk.gray('Available exams'));
+        console.log(chalk.white('    exam start <id>     ') + chalk.gray('Begin an exam'));
+        console.log(chalk.white('    exam q [n]          ') + chalk.gray('View questions'));
+        console.log(chalk.white('    exam answer <n> <X> ') + chalk.gray('Answer question'));
+        console.log(chalk.white('    exam review         ') + chalk.gray('Review all answers'));
+        console.log(chalk.white('    exam submit         ') + chalk.gray('Submit for grading'));
+        console.log(chalk.white('    exam result         ') + chalk.gray('View your score'));
+        console.log();
+        console.log(chalk.bold.white('  System'));
+        console.log(chalk.white('    ref [topic]         ') + chalk.gray('Quick reference'));
+        console.log(chalk.white('    setup               ') + chalk.gray('Settings / switch mode'));
+        console.log(chalk.white('    lang [code]         ') + chalk.gray('Switch language'));
+        console.log(chalk.white('    clear               ') + chalk.gray('Clear screen'));
+        console.log(chalk.white('    exit                ') + chalk.gray('Quit'));
+        console.log();
+        return;
+    }
+    // ─── Olympiad: full help ───
     if (!activated) {
         console.log(chalk.bold.yellow('  Restricted Mode — activate with a token to unlock all commands'));
         console.log();
@@ -391,6 +496,15 @@ function printReplHelp(activated) {
     console.log(chalk.white('    status              ') + chalk.gray('Competition status'));
     console.log(chalk.white('    time                ') + chalk.gray('Countdown timer'));
     console.log();
+    console.log(chalk.bold.white('  Exam'));
+    console.log(chalk.white('    exam list           ') + chalk.gray('Available exams'));
+    console.log(chalk.white('    exam start <id>     ') + chalk.gray('Begin an exam'));
+    console.log(chalk.white('    exam q [n]          ') + chalk.gray('View questions'));
+    console.log(chalk.white('    exam answer <n> <X> ') + chalk.gray('Answer question'));
+    console.log(chalk.white('    exam review         ') + chalk.gray('Review all answers'));
+    console.log(chalk.white('    exam submit         ') + chalk.gray('Submit for grading'));
+    console.log(chalk.white('    exam result         ') + chalk.gray('View your score'));
+    console.log();
     console.log(chalk.bold.white('  AI'));
     console.log(chalk.white('    ai4ctf              ') + chalk.gray('Chat with your AI teammate'));
     console.log(chalk.white('    hint <question>     ') + chalk.gray('Level A — General guidance'));

package/dist/types/index.d.ts

@@ -102,8 +102,11 @@ export interface IcoaConfig {
     deviceFingerprint: string;
     lastVersion: string;
     sessionCookie: string;
+    country: string;
+    mode: IcoaMode | '';
 }
 export type CompetitionState = 'pre_competition' | 'demo' | 'live' | 'finished' | 'unknown';
+export type IcoaMode = 'selection' | 'olympiad' | 'organizer';
 export type HintLevel = 'A' | 'B' | 'C';
 export interface HintBudget {
     a: number;
@@ -128,3 +131,44 @@ export declare const DEFAULT_BUDGET: HintBudget;
 export declare const DEFAULT_CONFIG: IcoaConfig;
 export declare const SUPPORTED_LANGUAGES: readonly ["en", "zh", "ja", "ko", "es"];
 export type SupportedLanguage = typeof SUPPORTED_LANGUAGES[number];
+export interface ExamListItem {
+    id: string;
+    name: string;
+    country: string;
+    questionCount: number;
+    durationMinutes: number;
+    status: 'available' | 'in_progress' | 'submitted';
+}
+export interface ExamQuestion {
+    number: number;
+    text: string;
+    category?: string;
+    options: {
+        A: string;
+        B: string;
+        C: string;
+        D: string;
+    };
+}
+export interface ExamSession {
+    examId: string;
+    examName: string;
+    startedAt: string;
+    durationMinutes: number;
+    questionCount: number;
+    country: string;
+}
+export interface ExamState {
+    session: ExamSession;
+    questions: ExamQuestion[];
+    answers: Record<number, string>;
+}
+export interface ExamResult {
+    examId: string;
+    examName: string;
+    score: number;
+    total: number;
+    percentage: number;
+    passed: boolean;
+    submittedAt: string;
+}

package/dist/types/index.js

@@ -30,5 +30,7 @@ export const DEFAULT_CONFIG = {
     deviceFingerprint: '',
     lastVersion: '',
     sessionCookie: '',
+    country: '',
+    mode: '',
 };
 export const SUPPORTED_LANGUAGES = ['en', 'zh', 'ja', 'ko', 'es'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icoa-cli",
-  "version": "2.3.2",
+  "version": "2.5.2",
   "description": "ICOA CLI — The world's first CLI-native CTF competition terminal",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "start": "node dist/index.js"
+    "start": "node dist/index.js",
+    "postinstall": "node dist/postinstall.js 2>/dev/null || true"
   },
   "keywords": [
     "ctf",