icoa-cli 2.19.98 → 2.19.100

package/dist/commands/env.js

@@ -506,8 +506,9 @@ function showStatus() {
     console.log(chalk.gray('  ─────────────────────────────────────────────'));
     console.log(`  ${chalk.green(`✓ ${installed}/${total}`)}  ${missing > 0 ? chalk.red(`✗ ${missing} missing`) : chalk.green('All 110 ready!')}`);
     if (missing > 0) {
-        console.log(chalk.gray('  Install everything: ') + chalk.white('env setup'));
+        console.log(chalk.gray('  Install everything: ') + chalk.white('env setup') + chalk.gray('   (~5 min, one-time)'));
     }
+    console.log(chalk.gray('  You are back at the ') + chalk.cyan('icoa>') + chalk.gray(' prompt. ') + chalk.cyan('help') + chalk.gray(' for all commands.'));
     console.log();
 }
 async function installAll() {

package/dist/commands/lang.js

@@ -39,8 +39,8 @@ export function registerLangCommand(program) {
                 console.log(`    ${chalk.white(lang)}  ${LANG_NAMES[lang]}${current}`);
             }
             console.log();
-            console.log(chalk.gray('  Usage: lang <code>'));
-            console.log(chalk.gray('  Example: lang es'));
+            console.log(chalk.gray('  Switch now: ') + chalk.cyan('lang <code>') + chalk.gray('   (e.g. ') + chalk.cyan('lang es') + chalk.gray(')'));
+            console.log(chalk.gray('  No "back" needed — you are still at the ') + chalk.cyan('icoa>') + chalk.gray(' prompt.'));
             console.log();
             return;
         }

package/dist/commands/log.js

@@ -53,6 +53,8 @@ function showLog() {
     printTable(['Time', 'Type', 'Content'], rows);
     console.log(chalk.gray(`  ${entries.length} entries total`));
     console.log();
+    console.log(chalk.gray('  You are at the ') + chalk.cyan('icoa>') + chalk.gray(' prompt. Also: ') + chalk.cyan('log stats') + chalk.gray(' · ') + chalk.cyan('log export') + chalk.gray(' · ') + chalk.cyan('help') + chalk.gray(' all commands.'));
+    console.log();
 }
 async function exportLog() {
     const config = getConfig();

package/dist/commands/note.js

@@ -14,12 +14,20 @@ export function registerNoteCommand(program) {
         if (!words || words.length === 0) {
             // Display existing notes
             if (!existsSync(NOTES_FILE)) {
-                printInfo('No notes yet. Add one with: icoa note "your note here"');
+                printInfo('No notes yet. Add one with: note "your note here"');
+                console.log();
+                console.log(chalk.gray('  You are at the ') + chalk.cyan('icoa>') + chalk.gray(' prompt. Type another command or ') + chalk.cyan('help') + chalk.gray(' for the list.'));
+                console.log();
                 return;
             }
             const content = readFileSync(NOTES_FILE, 'utf-8');
             printHeader('Notes');
             console.log(content);
+            console.log();
+            console.log(chalk.gray('  ─────────────────────────────────────────────'));
+            console.log(chalk.gray('  End of notes. You are back at the ') + chalk.cyan('icoa>') + chalk.gray(' prompt.'));
+            console.log(chalk.gray('  Add one: ') + chalk.cyan('note "your text"') + chalk.gray('  ·  ') + chalk.cyan('help') + chalk.gray(' for all commands'));
+            console.log();
             return;
         }
         // Add new note

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: ref <topic>`));
-            console.log(chalk.gray(`  Example: ref python`));
+            console.log(chalk.gray('  Open one: ') + chalk.cyan('ref <topic>') + chalk.gray('   (e.g. ') + chalk.cyan('ref python') + chalk.gray(')'));
+            console.log(chalk.gray('  No "back" needed — ref just prints and returns to the ') + chalk.cyan('icoa>') + chalk.gray(' prompt.'));
             console.log();
             return;
         }
@@ -59,5 +59,10 @@ export function registerRefCommand(program) {
         const content = readFileSync(filePath, 'utf-8');
         printHeader(`Reference: ${topic}`);
         console.log(content);
+        console.log();
+        console.log(chalk.gray('  ─────────────────────────────────────────────'));
+        console.log(chalk.gray('  End of ') + chalk.cyan(`ref ${topic}`) + chalk.gray('. You are back at the ') + chalk.cyan('icoa>') + chalk.gray(' prompt.'));
+        console.log(chalk.gray('  Next: ') + chalk.cyan('ref') + chalk.gray(' list topics · ') + chalk.cyan('ref <topic>') + chalk.gray(' open another · ') + chalk.cyan('help') + chalk.gray(' all commands'));
+        console.log();
     });
 }

package/dist/commands/setup.js

@@ -13,6 +13,8 @@ export function registerSetupCommand(program) {
         const config = getConfig();
         printHeader('ICOA CLI Setup');
         console.log();
+        console.log(chalk.gray('  Tip: press ') + chalk.cyan('Ctrl+C') + chalk.gray(' any time to cancel setup and return to the ') + chalk.cyan('icoa>') + chalk.gray(' prompt — nothing is saved until you confirm.'));
+        console.log();
         // Show current configuration
         printKeyValue('CTFd URL', config.ctfdUrl || chalk.gray('Not configured'));
         printKeyValue('CTFd Token', config.token ? chalk.green('Configured') : chalk.gray('Not configured'));
@@ -21,83 +23,100 @@ export function registerSetupCommand(program) {
         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' },
-                { name: 'View All Settings', value: 'view' },
-                { name: 'Exit', value: 'exit' },
-            ],
-        });
-        switch (action) {
-            case 'mode': {
-                const newMode = await select({
-                    message: 'Select mode:',
-                    choices: [
-                        { name: 'National Selection — demo, exam, 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');
-                console.log();
-                const key = await input({ message: 'Enter Gemini API Key:' });
-                if (key.trim()) {
-                    setApiKey(key.trim());
-                    printSuccess('Gemini API key saved.');
+        try {
+            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' },
+                    { name: 'View All Settings', value: 'view' },
+                    { name: 'Exit', value: 'exit' },
+                ],
+            });
+            switch (action) {
+                case 'mode': {
+                    const newMode = await select({
+                        message: 'Select mode:',
+                        choices: [
+                            { name: 'National Selection — demo, exam, 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;
                 }
-                else {
-                    printError('No key provided.');
+                case 'gemini': {
+                    console.log();
+                    printInfo('Get your API key from: https://aistudio.google.com/apikey');
+                    console.log();
+                    const key = await input({ message: 'Enter Gemini API Key:' });
+                    if (key.trim()) {
+                        setApiKey(key.trim());
+                        printSuccess('Gemini API key saved.');
+                    }
+                    else {
+                        printError('No key provided.');
+                    }
+                    break;
                 }
-                break;
-            }
-            case 'ctfd': {
-                printInfo('Use "join <url>" to connect to a CTFd instance.');
-                break;
-            }
-            case 'budget': {
-                const { confirm } = await import('@inquirer/prompts');
-                const proceed = await confirm({
-                    message: 'Reset hint budget to defaults (A:50, B:10, C:2)? This cannot be undone.',
-                    default: false,
-                });
-                if (proceed) {
-                    const { saveBudget } = await import('../lib/config.js');
-                    const { DEFAULT_BUDGET } = await import('../types/index.js');
-                    saveBudget({ ...DEFAULT_BUDGET });
-                    printSuccess('Hint budget reset to defaults.');
+                case 'ctfd': {
+                    printInfo('Use "join <url>" to connect to a CTFd instance.');
+                    break;
                 }
-                break;
-            }
-            case 'view': {
-                console.log();
-                printHeader('Full Configuration');
-                const full = getConfig();
-                for (const [key, value] of Object.entries(full)) {
-                    if (key === 'token' && value) {
-                        printKeyValue(key, value.toString().substring(0, 8) + '...');
+                case 'budget': {
+                    const { confirm } = await import('@inquirer/prompts');
+                    const proceed = await confirm({
+                        message: 'Reset hint budget to defaults (A:50, B:10, C:2)? This cannot be undone.',
+                        default: false,
+                    });
+                    if (proceed) {
+                        const { saveBudget } = await import('../lib/config.js');
+                        const { DEFAULT_BUDGET } = await import('../types/index.js');
+                        saveBudget({ ...DEFAULT_BUDGET });
+                        printSuccess('Hint budget reset to defaults.');
                     }
-                    else if (key === 'geminiApiKey' && value) {
-                        printKeyValue(key, value.toString().substring(0, 8) + '...');
-                    }
-                    else {
-                        printKeyValue(key, String(value ?? 'null'));
+                    break;
+                }
+                case 'view': {
+                    console.log();
+                    printHeader('Full Configuration');
+                    const full = getConfig();
+                    for (const [key, value] of Object.entries(full)) {
+                        if (key === 'token' && value) {
+                            printKeyValue(key, value.toString().substring(0, 8) + '...');
+                        }
+                        else if (key === 'geminiApiKey' && value) {
+                            printKeyValue(key, value.toString().substring(0, 8) + '...');
+                        }
+                        else {
+                            printKeyValue(key, String(value ?? 'null'));
+                        }
                     }
+                    console.log();
+                    break;
                 }
+                case 'exit':
+                    break;
+            }
+            console.log();
+            console.log(chalk.gray('  Setup complete. You are back at the ') + chalk.cyan('icoa>') + chalk.gray(' prompt.'));
+            console.log();
+        }
+        catch (err) {
+            // @inquirer/prompts throws ExitPromptError on Ctrl+C. Swallow it cleanly
+            // so users don't see a scary stack trace — setup is entirely reversible,
+            // and every save in this wizard is behind an explicit confirm step.
+            if (err?.name === 'ExitPromptError') {
+                console.log();
+                console.log(chalk.gray('  Setup cancelled. You are back at the ') + chalk.cyan('icoa>') + chalk.gray(' prompt. Nothing was saved.'));
                 console.log();
-                break;
+                return;
             }
-            case 'exit':
-                break;
+            throw err;
         }
     });
 }

package/dist/commands/theme.js

@@ -29,8 +29,8 @@ export function registerThemeCommand(program) {
             console.log('    ' + chalk.white('dark           ') + chalk.gray('Darcula — gray on dark gray (default)'));
             console.log('    ' + chalk.white('high-contrast  ') + chalk.gray('Pure white on pure black — low vision / projectors'));
             console.log();
-            console.log(chalk.gray('  Usage: ') + chalk.cyan('theme <name>'));
-            console.log(chalk.gray('  Applies on next ') + chalk.cyan('icoa') + chalk.gray(' launch.'));
+            console.log(chalk.gray('  Switch: ') + chalk.cyan('theme <name>') + chalk.gray('   (applies on next ') + chalk.cyan('icoa') + chalk.gray(' launch)'));
+            console.log(chalk.gray('  No "back" needed — you are still at the ') + chalk.cyan('icoa>') + chalk.gray(' prompt.'));
             console.log();
             return;
         }

package/dist/repl.js

@@ -454,6 +454,10 @@ export async function startRepl(program, resumeMode) {
             console.log(chalk.white('     status') + chalk.gray('         Your score & hint budget'));
             console.log(chalk.white('     scoreboard') + chalk.gray('     Live rankings'));
             console.log(chalk.white('     help') + chalk.gray('           Full command list'));
+            console.log();
+            console.log(chalk.gray('   Tool environment:'));
+            console.log(chalk.white('     env') + chalk.gray('            See which of the 110 CTF tools are installed'));
+            console.log(chalk.white('     env setup') + chalk.gray('      Install anything missing (~5 min, one-time)'));
             console.log(chalk.gray('   ─────────────────────────────────────────────'));
             console.log(chalk.gray('   Tip: ') + chalk.cyan('help') + chalk.gray(' · ') + chalk.cyan('Ctrl+C') + chalk.gray(' pauses · ') + chalk.cyan('quit') + chalk.gray(' closes'));
             console.log();
@@ -470,7 +474,11 @@ export async function startRepl(program, resumeMode) {
             console.log(chalk.white('   Step 2  ') + chalk.bold.cyan('challenges') + chalk.gray('   Browse & solve challenges'));
             console.log(chalk.white('   Step 3  ') + chalk.bold.cyan('hint') + chalk.gray('         Ask AI when stuck'));
             console.log();
-            console.log(chalk.gray('   Also: ') + chalk.white('env') + chalk.gray(' check tools  ') + chalk.white('help') + chalk.gray(' all commands'));
+            console.log(chalk.gray('   Before Step 1 — make sure your tools are ready:'));
+            console.log(chalk.white('     env') + chalk.gray('            See which of the 110 CTF tools are installed'));
+            console.log(chalk.white('     env setup') + chalk.gray('      Install anything missing (~5 min, one-time)'));
+            console.log();
+            console.log(chalk.gray('   Also: ') + chalk.white('help') + chalk.gray(' all commands'));
             console.log(chalk.gray('   ─────────────────────────────────────────────'));
             console.log(chalk.gray('   Tip: ') + chalk.cyan('Ctrl+C') + chalk.gray(' pauses · ') + chalk.cyan('exit') + chalk.gray(' → menu · ') + chalk.cyan('quit') + chalk.gray(' closes CLI'));
             console.log();
@@ -486,7 +494,8 @@ export async function startRepl(program, resumeMode) {
             console.log(chalk.gray('   While waiting, explore:'));
             console.log(chalk.white('     ref linux') + chalk.gray('       Quick reference for Linux'));
             console.log(chalk.white('     ref web') + chalk.gray('         Quick reference for Web'));
-            console.log(chalk.white('     env') + chalk.gray('             Check your tools'));
+            console.log(chalk.white('     env') + chalk.gray('             See which of the 110 CTF tools are installed'));
+            console.log(chalk.white('     env setup') + chalk.gray('       Install anything missing (~5 min, one-time)'));
             console.log(chalk.white('     help') + chalk.gray('            All available commands'));
             console.log(chalk.gray('   ─────────────────────────────────────────────'));
             console.log(chalk.gray('   Tip: ') + chalk.cyan('Ctrl+C') + chalk.gray(' pauses · ') + chalk.cyan('exit') + chalk.gray(' → menu · ') + chalk.cyan('quit') + chalk.gray(' closes CLI'));
@@ -575,13 +584,30 @@ export async function startRepl(program, resumeMode) {
             rl.prompt();
             return;
         }
-        // Explicit quit — `quit` or `q` always closes the CLI.
-        if (input === 'quit' || input === 'q') {
-            if (getExamState()) {
+        // Explicit quit — `quit` / `q` close the CLI. During a live **real** exam
+        // (token-gated, timed, graded) we require `quit confirm` as a second step
+        // to prevent accidental loss of a 90-minute session to a single keystroke.
+        // Demo has no time pressure and no scoring, so demo quit stays one-step.
+        if (input === 'quit' || input === 'q' || input === 'quit confirm') {
+            const state = getExamState();
+            const isRealExam = state && state.session.examId !== 'demo-free';
+            if (isRealExam && input !== 'quit confirm') {
+                console.log();
+                console.log(chalk.yellow('  ⚠ A real exam is in progress.'));
+                console.log(chalk.gray('    Your answers are auto-saved on the server, but the exam timer keeps ticking'));
+                console.log(chalk.gray('    on the server side even if you close the CLI.'));
                 console.log();
-                console.log(chalk.yellow('  ⚠ An exam is in progress — progress is auto-saved.'));
-                console.log(chalk.gray('  Closing anyway. Resume with: ') + chalk.white('icoa --resume'));
+                console.log(chalk.white('  To leave the CLI but keep the exam alive, type: ') + chalk.bold.cyan('back'));
+                console.log(chalk.gray('    (recommended — you can resume with ') + chalk.cyan('exam q 1') + chalk.gray(' after relaunching icoa)'));
                 console.log();
+                console.log(chalk.white('  To really close ICOA CLI, type: ') + chalk.bold.cyan('quit confirm'));
+                console.log();
+                rl.prompt();
+                return;
+            }
+            if (state && state.session.examId === 'demo-free') {
+                console.log();
+                console.log(chalk.gray('  Demo paused. Resume with: ') + chalk.white('demo') + chalk.gray(' (fresh) or ') + chalk.white('exam q 1') + chalk.gray(' (continue).'));
             }
             stopLogSync();
             recordExit();
@@ -1077,16 +1103,21 @@ export async function startRepl(program, resumeMode) {
     rl.on('SIGINT', () => {
         console.log();
         if (isChatActive() || isCtf4aiActive()) {
-            console.log(chalk.yellow('  Type ') + chalk.bold.cyan('exit') + chalk.yellow(' to leave chat, or Ctrl+D to close ICOA CLI.'));
+            console.log(chalk.yellow('  Ctrl+C did not close ICOA CLI — you are still in the AI chat.'));
+            console.log(chalk.white('  Type ') + chalk.bold.cyan('exit') + chalk.white(' to leave the chat and return to the menu.'));
         }
         else if (getExamState()) {
-            console.log(chalk.yellow('  Exam paused. Your answers are auto-saved.'));
+            const isReal = getExamState().session.examId !== 'demo-free';
+            console.log(chalk.yellow('  Ctrl+C did NOT close ICOA CLI.'));
+            console.log(chalk.gray(`  Your ${isReal ? 'exam' : 'demo'} is paused and every answer is auto-saved.`));
+            console.log();
             console.log(chalk.white('  Resume: ') + chalk.cyan('exam q 1') +
                 chalk.gray('  ·  Back to menu: ') + chalk.cyan('back') +
-                chalk.gray('  ·  Close CLI: ') + chalk.cyan('quit'));
+                chalk.gray('  ·  Close CLI: ') + chalk.cyan(isReal ? 'quit confirm' : 'quit'));
         }
         else {
-            console.log(chalk.yellow('  Press Ctrl+D or type ') + chalk.bold.cyan('quit') + chalk.yellow(' to close. ') + chalk.bold.cyan('help') + chalk.yellow(' for commands.'));
+            console.log(chalk.yellow('  Ctrl+C did not close ICOA CLI — you are still at the ') + chalk.cyan('icoa>') + chalk.yellow(' prompt.'));
+            console.log(chalk.gray('  Keep typing — ') + chalk.cyan('help') + chalk.gray(' lists commands. (Only ') + chalk.cyan('quit') + chalk.gray(' or Ctrl+D actually close the CLI.)'));
         }
         console.log();
         rl.prompt();

package/package.json

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