icoa-cli 2.3.3 → 2.5.3

package/dist/commands/connect.js

@@ -12,7 +12,7 @@ export function registerConnectCommand(program) {
         logCommand(`connect ${id}`);
         const config = getConfig();
         if (!isConnected()) {
-            printError('Not connected. Run: icoa ctf join <url>');
+            printError('Not connected. Run: join <url>');
             return;
         }
         const client = new CTFdClient(config.ctfdUrl, config.token);

package/dist/commands/ctf.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { input, select } from '@inquirer/prompts';
+import { input } from '@inquirer/prompts';
 import { CTFdClient } from '../lib/ctfd-client.js';
 import { getConfig, saveConfig, getBudget } from '../lib/config.js';
 import { logCommand, logSubmission } from '../lib/logger.js';
@@ -30,45 +30,38 @@ export function registerCtfCommands(program) {
         logCommand(`ctf join ${url}`);
         console.log();
         printInfo(`Connecting to ${chalk.bold(url)}`);
-        const authMethod = await select({
-            message: 'Authentication method:',
-            choices: [
-                { name: 'Access Token (from CTFd Settings)', value: 'token' },
-                { name: 'Username & Password', value: 'login' },
-            ],
-        });
+        const username = await input({ message: 'Username:' });
+        const password = await input({ message: 'Password:' });
         let token = '';
         let sessionCookie = '';
         let csrfNonce = '';
-        if (authMethod === 'token') {
-            token = await input({ message: 'Enter your CTFd Access Token:' });
-        }
-        else {
-            const username = await input({ message: 'Username:' });
-            const password = await input({ message: 'Password:' });
-            const spinner = createSpinner('Logging in...');
-            spinner.start();
-            try {
-                const client = new CTFdClient(url, '');
-                const result = await client.loginWithCredentials(username, password);
-                token = result.token;
-                sessionCookie = result.session;
-                csrfNonce = result.csrf;
-                spinner.succeed('Login successful');
+        const spinner = createSpinner('Logging in...');
+        spinner.start();
+        try {
+            const client = new CTFdClient(url, '');
+            const result = await client.loginWithCredentials(username, password);
+            token = result.token;
+            sessionCookie = result.session;
+            csrfNonce = result.csrf;
+            if (token) {
+                spinner.succeed('Login successful — API token auto-generated');
             }
-            catch (err) {
-                spinner.fail('Login failed');
-                printError(err.message);
-                return;
+            else {
+                spinner.succeed('Login successful (session mode)');
             }
         }
+        catch (err) {
+            spinner.fail('Login failed');
+            printError(err.message);
+            return;
+        }
         // Test connection
-        const spinner = createSpinner('Testing connection...');
-        spinner.start();
+        const spinner2 = createSpinner('Testing connection...');
+        spinner2.start();
         try {
             const client = new CTFdClient(url, token, sessionCookie, csrfNonce);
             const user = await client.testConnection();
-            spinner.succeed('Connected successfully');
+            spinner2.succeed('Connected successfully');
             console.log();
             printKeyValue('User', user.name);
             printKeyValue('Score', String(user.score || 0));
@@ -85,6 +78,7 @@ export function registerCtfCommands(program) {
                     userName: user.name,
                     teamId: user.team_id,
                     sessionCookie: sessionCookie,
+                    country: user.country || '',
                 };
                 if (meta.start) {
                     configUpdate.competitionStartsAt = new Date(meta.start * 1000).toISOString();
@@ -119,10 +113,15 @@ export function registerCtfCommands(program) {
                 });
             }
             console.log();
-            printSuccess('Connection saved. You are ready to compete!');
+            printSuccess('Connection saved. You are ready!');
+            console.log();
+            console.log(chalk.gray('  Next:'));
+            console.log(chalk.white('    exam list      ') + chalk.gray('View available exams'));
+            console.log(chalk.white('    challenges     ') + chalk.gray('View CTF challenges'));
+            console.log(chalk.white('    status         ') + chalk.gray('Check score & budget'));
         }
         catch (err) {
-            spinner.fail('Connection failed');
+            spinner2.fail('Connection failed');
             printError(err.message);
         }
     });
@@ -258,7 +257,7 @@ export function registerCtfCommands(program) {
             // Show files
             if (challenge.files && challenge.files.length > 0) {
                 console.log();
-                printInfo(`Files (${challenge.files.length}): use ${chalk.white(`icoa files ${id}`)} to download`);
+                printInfo(`Files (${challenge.files.length}): use ${chalk.white(`files ${id}`)} to download`);
             }
             // Show hints
             if (challenge.hints && challenge.hints.length > 0) {
@@ -267,11 +266,11 @@ export function registerCtfCommands(program) {
             // Show connection info
             if (challenge.connection_info) {
                 console.log();
-                printInfo(`Quick connect: ${chalk.white(`icoa connect ${id}`)}`);
+                printInfo(`Quick connect: ${chalk.white(`connect ${id}`)}`);
             }
             // Show helpful next actions
             console.log();
-            console.log(chalk.gray(`  Next: icoa hint "how to approach this?" | icoa ctf submit ${id} "icoa{flag}"`));
+            console.log(chalk.gray(`  Next: hint "how to approach this?" | submit ${id} "icoa{flag}"`));
         }
         catch (err) {
             spinner.fail('Failed to load challenge');

package/dist/commands/exam.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerExamCommand(program: Command): void;

package/dist/commands/exam.js

@@ -0,0 +1,376 @@
+import chalk from 'chalk';
+import { confirm } from '@inquirer/prompts';
+import { ExamClient } from '../lib/exam-client.js';
+import { getConfig } from '../lib/config.js';
+import { getExamState, saveExamState, clearExamState, getExamDeadline } from '../lib/exam-state.js';
+import { logCommand } from '../lib/logger.js';
+import { printSuccess, printError, printWarning, printInfo, printTable, printHeader, printKeyValue, createSpinner, formatCountdown, } from '../lib/ui.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function drawProgress(percent, label) {
+    const width = 30;
+    const filled = Math.round((percent / 100) * width);
+    const empty = width - filled;
+    const bar = chalk.green('█'.repeat(filled)) + chalk.gray('░'.repeat(empty));
+    const pct = String(percent).padStart(3) + '%';
+    process.stdout.write(`\r  ${bar} ${pct}  ${chalk.gray(label)}`);
+}
+function requireExamConnection() {
+    const config = getConfig();
+    if (!config.ctfdUrl || !config.token) {
+        printError('Not connected. Run: join <url>');
+        return null;
+    }
+    return new ExamClient(config.ctfdUrl, config.token);
+}
+function checkTimeRemaining() {
+    const deadline = getExamDeadline();
+    if (!deadline)
+        return true;
+    if (new Date() >= deadline) {
+        printError('Time expired! Use "exam submit" to submit your answers.');
+        return false;
+    }
+    return true;
+}
+function printTimeRemaining() {
+    const deadline = getExamDeadline();
+    if (deadline) {
+        const now = new Date();
+        if (now < deadline) {
+            printKeyValue('Time Remaining', chalk.yellow.bold(formatCountdown(deadline)));
+        }
+        else {
+            printKeyValue('Time', chalk.red.bold('EXPIRED'));
+        }
+    }
+}
+function printQuestion(q, answer) {
+    const state = getExamState();
+    const total = state?.session.questionCount || '?';
+    console.log();
+    console.log(chalk.bold.white(`  Q${q.number}/${total}`) + (q.category ? chalk.gray(` [${q.category}]`) : ''));
+    console.log(`  ${q.text}`);
+    console.log();
+    for (const key of ['A', 'B', 'C', 'D']) {
+        const selected = answer === key;
+        const prefix = selected ? chalk.green.bold(`  ▸ ${key}.`) : chalk.gray(`    ${key}.`);
+        const text = selected ? chalk.green.bold(q.options[key]) : chalk.white(q.options[key]);
+        console.log(`${prefix} ${text}`);
+    }
+    console.log();
+}
+export function registerExamCommand(program) {
+    const exam = program.command('exam').description('National selection exam');
+    // ─── exam list ───
+    exam
+        .command('list')
+        .description('List available exams')
+        .action(async () => {
+        logCommand('exam list');
+        const client = requireExamConnection();
+        if (!client)
+            return;
+        const spinner = createSpinner('Loading exams...');
+        spinner.start();
+        try {
+            const exams = await client.getExams();
+            spinner.stop();
+            if (!exams || exams.length === 0) {
+                printInfo('No exams available.');
+                return;
+            }
+            printHeader('Available Exams');
+            const rows = exams.map((e) => {
+                const statusColor = e.status === 'submitted' ? chalk.green
+                    : e.status === 'in_progress' ? chalk.yellow
+                        : chalk.white;
+                return [
+                    chalk.white(e.id),
+                    e.name,
+                    chalk.cyan(e.country),
+                    String(e.questionCount),
+                    `${e.durationMinutes} min`,
+                    statusColor(e.status),
+                ];
+            });
+            printTable(['ID', 'Name', 'Country', 'Questions', 'Duration', 'Status'], rows);
+            console.log();
+            console.log(chalk.gray('  Start an exam: exam start <id>'));
+        }
+        catch (err) {
+            spinner.fail('Failed to load exams');
+            printError(err.message);
+        }
+    });
+    // ─── exam start <id> ───
+    exam
+        .command('start <id>')
+        .description('Start an exam (begins timer)')
+        .action(async (examId) => {
+        logCommand(`exam start ${examId}`);
+        // Check if already in an exam
+        const existing = getExamState();
+        if (existing) {
+            printWarning(`Exam "${existing.session.examName}" is already in progress.`);
+            printInfo('Use "exam review" to check progress or "exam submit" to submit.');
+            return;
+        }
+        const client = requireExamConnection();
+        if (!client)
+            return;
+        const proceed = await confirm({
+            message: 'Start the exam? The timer will begin immediately.',
+            default: true,
+        });
+        if (!proceed)
+            return;
+        console.log();
+        try {
+            // Step 1: Connect
+            drawProgress(0, 'Connecting to exam server...');
+            const { session, questions } = await client.startExam(examId);
+            // Step 2-4: Visual loading steps
+            drawProgress(30, 'Loading questions...');
+            await sleep(200);
+            drawProgress(60, 'Preparing exam environment...');
+            await sleep(200);
+            drawProgress(90, 'Starting timer...');
+            await sleep(150);
+            saveExamState({ session, questions, answers: {} });
+            drawProgress(100, 'Ready!');
+            console.log();
+            console.log();
+            printHeader(session.examName);
+            printKeyValue('Questions', String(session.questionCount));
+            printKeyValue('Duration', `${session.durationMinutes} minutes`);
+            printKeyValue('Country', session.country);
+            printTimeRemaining();
+            // Show first question
+            if (questions.length > 0) {
+                printQuestion(questions[0]);
+            }
+            console.log(chalk.gray('  Commands: exam q <n> | exam answer <n> <A-D> | exam review | exam submit'));
+        }
+        catch (err) {
+            console.log();
+            printError(err.message);
+        }
+    });
+    // ─── exam q [n] ───
+    exam
+        .command('q [n]')
+        .description('View question (or all questions)')
+        .action((n) => {
+        logCommand(`exam q ${n || 'all'}`);
+        const state = getExamState();
+        if (!state) {
+            printError('No exam in progress. Use "exam start <id>" to begin.');
+            return;
+        }
+        printTimeRemaining();
+        if (n) {
+            const num = parseInt(n);
+            const q = state.questions.find((q) => q.number === num);
+            if (!q) {
+                printError(`Question ${n} not found (1-${state.questions.length}).`);
+                return;
+            }
+            printQuestion(q, state.answers[num]);
+        }
+        else {
+            // Show all questions summary
+            printHeader(`${state.session.examName}`);
+            const answered = Object.keys(state.answers).length;
+            printKeyValue('Progress', `${answered}/${state.session.questionCount} answered`);
+            console.log();
+            for (const q of state.questions) {
+                const ans = state.answers[q.number];
+                const status = ans ? chalk.green(`[${ans}]`) : chalk.gray('[ ]');
+                const cat = q.category ? chalk.gray(` [${q.category}]`) : '';
+                console.log(`  ${status} ${chalk.white(`Q${q.number}`)}${cat} ${chalk.gray(q.text.substring(0, 60))}${q.text.length > 60 ? '...' : ''}`);
+            }
+            console.log();
+        }
+    });
+    // ─── exam answer <n> <choice> ───
+    exam
+        .command('answer <n> <choice>')
+        .description('Answer question N with choice A/B/C/D')
+        .action((n, choice) => {
+        logCommand(`exam answer ${n} ${choice}`);
+        const state = getExamState();
+        if (!state) {
+            printError('No exam in progress. Use "exam start <id>" to begin.');
+            return;
+        }
+        if (!checkTimeRemaining())
+            return;
+        const num = parseInt(n);
+        const q = state.questions.find((q) => q.number === num);
+        if (!q) {
+            printError(`Question ${n} not found (1-${state.questions.length}).`);
+            return;
+        }
+        const c = choice.toUpperCase();
+        if (!['A', 'B', 'C', 'D'].includes(c)) {
+            printError('Choice must be A, B, C, or D.');
+            return;
+        }
+        state.answers[num] = c;
+        saveExamState(state);
+        const answered = Object.keys(state.answers).length;
+        const total = state.session.questionCount;
+        printSuccess(`Q${num}: ${c} saved (${answered}/${total} answered)`);
+        if (num < state.questions.length) {
+            console.log(chalk.gray(`  Next: exam q ${num + 1}`));
+        }
+        else if (answered === total) {
+            console.log(chalk.gray('  All answered! Use: exam review'));
+        }
+    });
+    // ─── exam review ───
+    exam
+        .command('review')
+        .description('Review all answers before submitting')
+        .action(() => {
+        logCommand('exam review');
+        const state = getExamState();
+        if (!state) {
+            printError('No exam in progress.');
+            return;
+        }
+        printHeader(`Review: ${state.session.examName}`);
+        printTimeRemaining();
+        console.log();
+        const cols = 6;
+        let line = '  ';
+        for (const q of state.questions) {
+            const ans = state.answers[q.number];
+            if (ans) {
+                line += chalk.green(`Q${String(q.number).padStart(2)} [${ans}]  `);
+            }
+            else {
+                line += chalk.yellow(`Q${String(q.number).padStart(2)} [ ]  `);
+            }
+            if (q.number % cols === 0) {
+                console.log(line);
+                line = '  ';
+            }
+        }
+        if (line.trim())
+            console.log(line);
+        const answered = Object.keys(state.answers).length;
+        const total = state.session.questionCount;
+        const unanswered = total - answered;
+        console.log();
+        printKeyValue('Answered', chalk.green.bold(`${answered}/${total}`));
+        if (unanswered > 0) {
+            const missing = state.questions
+                .filter((q) => !state.answers[q.number])
+                .map((q) => q.number)
+                .join(', ');
+            printKeyValue('Unanswered', chalk.yellow(`${unanswered} (Q${missing})`));
+        }
+        console.log();
+        console.log(chalk.gray('  Ready? Use "exam submit" to submit for grading.'));
+    });
+    // ─── exam submit ───
+    exam
+        .command('submit')
+        .description('Submit exam for grading')
+        .action(async () => {
+        logCommand('exam submit');
+        const state = getExamState();
+        if (!state) {
+            printError('No exam in progress.');
+            return;
+        }
+        const answered = Object.keys(state.answers).length;
+        const total = state.session.questionCount;
+        const unanswered = total - answered;
+        let msg = `Submit ${answered}/${total} answers?`;
+        if (unanswered > 0) {
+            msg += chalk.yellow(` ${unanswered} unanswered.`);
+        }
+        msg += ' This cannot be undone.';
+        const proceed = await confirm({ message: msg, default: false });
+        if (!proceed)
+            return;
+        const client = requireExamConnection();
+        if (!client)
+            return;
+        console.log();
+        try {
+            drawProgress(0, 'Uploading answers...');
+            const result = await client.submitExam(state.session.examId, state.answers);
+            drawProgress(50, 'Grading...');
+            await sleep(300);
+            drawProgress(100, 'Complete!');
+            console.log();
+            clearExamState();
+            console.log();
+            printHeader('Exam Result');
+            printKeyValue('Score', chalk.bold(`${result.score}/${result.total}`));
+            printKeyValue('Percentage', chalk.bold(`${result.percentage}%`));
+            printKeyValue('Status', result.passed ? chalk.green.bold('PASSED') : chalk.red.bold('NOT PASSED'));
+            console.log();
+        }
+        catch (err) {
+            console.log();
+            printError(err.message);
+        }
+    });
+    // ─── exam result ───
+    exam
+        .command('result [id]')
+        .description('View exam result')
+        .action(async (examId) => {
+        logCommand(`exam result ${examId || ''}`);
+        const client = requireExamConnection();
+        if (!client)
+            return;
+        if (!examId) {
+            const state = getExamState();
+            if (state) {
+                examId = state.session.examId;
+            }
+            else {
+                printError('Specify exam ID: exam result <id>');
+                return;
+            }
+        }
+        const spinner = createSpinner('Loading result...');
+        spinner.start();
+        try {
+            const result = await client.getResult(examId);
+            spinner.succeed('Result loaded');
+            console.log();
+            printHeader(result.examName);
+            printKeyValue('Score', chalk.bold(`${result.score}/${result.total}`));
+            printKeyValue('Percentage', chalk.bold(`${result.percentage}%`));
+            printKeyValue('Status', result.passed ? chalk.green.bold('PASSED') : chalk.red.bold('NOT PASSED'));
+            printKeyValue('Submitted', result.submittedAt);
+            console.log();
+        }
+        catch (err) {
+            spinner.fail('Failed to load result');
+            printError(err.message);
+        }
+    });
+    // Default action: show status or help
+    exam.action(() => {
+        logCommand('exam');
+        const state = getExamState();
+        if (state) {
+            printHeader(`In Progress: ${state.session.examName}`);
+            printTimeRemaining();
+            const answered = Object.keys(state.answers).length;
+            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'));
+        }
+        else {
+            printInfo('No exam in progress. Use "exam list" to see available exams.');
+        }
+    });
+}

package/dist/commands/files.js

@@ -13,7 +13,7 @@ export function registerFilesCommand(program) {
         logCommand(`files ${id}`);
         const config = getConfig();
         if (!isConnected()) {
-            printError('Not connected. Run: icoa ctf join <url>');
+            printError('Not connected. Run: join <url>');
             return;
         }
         const client = new CTFdClient(config.ctfdUrl, config.token);

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.3')}
+   ${chalk.gray('CLI-Native Competition Terminal  v2.5.3')}
 
 ${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,7 +1,7 @@
 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';
@@ -28,14 +28,42 @@ const BLOCKED_COMMANDS = new Set([
     'iptables', 'ufw', // firewall
 ]);
 const INTERCEPT = '__REPL_NO_EXIT__';
-const VERSION = '2.3.3';
+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 (every launch) ───
+    const { select: selectMode, confirm: confirmMode } = await import('@inquirer/prompts');
+    const savedMode = config.mode || '';
+    const 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' },
+    ];
+    const defaultIndex = savedMode ? choices.findIndex((c) => c.value === savedMode) : 0;
+    console.log(chalk.gray('   Use ↑↓ to select, Enter to confirm.'));
+    console.log();
+    let mode = await selectMode({
+        message: 'Mode',
+        choices,
+        default: choices[defaultIndex >= 0 ? defaultIndex : 0].value,
+    });
+    if (mode === 'olympiad' && savedMode !== 'olympiad') {
+        console.log();
+        console.log(chalk.yellow('   This mode will download ~500MB of CTF tools and AI models.'));
+        const proceed = await confirmMode({ message: 'Continue?', default: true });
+        if (!proceed) {
+            mode = 'selection';
+            console.log(chalk.gray('   Switched to National Selection mode.'));
+        }
+    }
+    if (mode !== savedMode)
+        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
@@ -91,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({
@@ -176,7 +229,7 @@ export async function startRepl(program, resumeMode) {
         }
         // Help
         if (input === 'help' || input === '?') {
-            printReplHelp(isActivated());
+            printReplHelp(isActivated(), mode);
             rl.prompt();
             return;
         }
@@ -209,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();
@@ -226,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
@@ -378,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();
@@ -405,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.3",
+  "version": "2.5.3",
   "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",

package/refs/icoa.txt

@@ -1,11 +1,16 @@
-ICOA CLI v2 — Quick Reference
+ICOA CLI v2.5 — Quick Reference
 ==============================
 
+MODES (selected on first run)
+  National Selection     Lightweight exam-only mode
+  International Olympiad Full CTF competition mode
+  Organizer              Partner management mode
+  setup → Switch Mode    Change mode anytime
+
 GETTING STARTED
-  activate <token>       Unlock with your access token
-  join <url>             Connect to CTFd competition
-  env                    Check tool environment (109 commands)
-  env setup              One-click install all tools
+  join <url>             Connect to server
+  activate <token>       Unlock (Olympiad mode only)
+  env                    Check tool environment (Olympiad only)
   help                   Show all commands
 
 COMPETITION
@@ -16,6 +21,15 @@ COMPETITION
   status                 Hint budget, score, rank, time
   time                   Competition countdown
 
+EXAM (National Selection)
+  exam list              Available exams for your country
+  exam start <id>        Begin exam (starts timer)
+  exam q [n]             View question n (or all)
+  exam answer <n> <A-D>  Answer question n
+  exam review            Review all answers
+  exam submit            Submit for grading
+  exam result            View your score
+
 AI HINTS
   hint <question>        Level A — General guidance (50 uses)
   hint-b <question>      Level B — Deep analysis (10 uses)