icoa-cli 2.19.92 → 2.19.94

package/dist/commands/exam.js

@@ -1578,10 +1578,36 @@ export function registerExamCommand(program) {
         .description('Enter exam with access token (no login needed)')
         .action(async (code) => {
         logCommand(`exam token ${code}`);
-        const { getRealExamState, saveExamState: saveExamStateFn } = await import('../lib/exam-state.js');
+        const { getRealExamState, saveExamState: saveExamStateFn, clearExamState: clearState } = await import('../lib/exam-state.js');
         const existing = getRealExamState();
         if (existing) {
             const existingToken = existing.session.token;
+            // Auto-recover from abandoned/expired sessions. If the stored state's
+            // deadline is >30 min in the past, the session is unusable (past the
+            // server's submit grace window). If user types a DIFFERENT token in
+            // this state, they clearly mean "start fresh". Clear silently rather
+            // than locking them out forever. Prevents the stale-A-paper-content +
+            // "Could not reload questions in new language" lockout.
+            const deadlineNow = getExamDeadline();
+            const typedDiffers = !!existingToken && existingToken.trim().toUpperCase() !== code.trim().toUpperCase();
+            const expiredPast30min = deadlineNow ? (deadlineNow.getTime() + 30 * 60 * 1000) < Date.now() : false;
+            if (typedDiffers && expiredPast30min) {
+                clearState();
+                console.log();
+                console.log(chalk.gray('  (previous exam session expired — cleared state, starting fresh with your new token)'));
+                console.log();
+                // Fall through to the fresh-start flow below (skip the "already in progress" guard)
+                // Re-run this action: easiest to just continue out of the `if (existing)` block
+                // by setting a flag. We do that by falling through — but since we're inside
+                // `if (existing)`, we need to proceed. Easiest: re-invoke the inner start flow.
+                // Actually: since we cleared state, the subsequent code paths will treat it
+                // as a fresh session. But we're inside `if (existing)`. Jump to the fresh path
+                // by executing a goto-equivalent via function call. Simplest: return here
+                // after instructing the user to retype the command.
+                console.log(chalk.white('  Please re-type: ') + chalk.bold.cyan(`exam ${code}`));
+                console.log();
+                return;
+            }
             // Migration path: pre-v2.19.55 sessions didn't persist the token on
             // state. Those sessions can't use `lang` or submit via the new token
             // path. If the user re-types the matching token, attach it so the
@@ -1624,6 +1650,9 @@ export function registerExamCommand(program) {
                 console.log();
                 console.log(chalk.yellow('  Note: you typed a different token. Each exam token is bound to'));
                 console.log(chalk.yellow('  one device + one session. You cannot switch tokens mid-exam.'));
+                console.log();
+                console.log(chalk.gray('  If you need to abandon this session (e.g. expired / wrong paper),'));
+                console.log(chalk.gray('  run ') + chalk.bold.cyan('exam reset') + chalk.gray(' to wipe local state, then re-enter the new token.'));
             }
             console.log();
             return;
@@ -1782,6 +1811,53 @@ export function registerExamCommand(program) {
         }
     });
     // ─── exam demo ───
+    exam
+        .command('reset', { hidden: true })
+        .description('Abandon current exam session and wipe local state (recovery only)')
+        .action(async () => {
+        logCommand('exam reset');
+        const { getRealExamState, clearExamState: clearState } = await import('../lib/exam-state.js');
+        const existing = getRealExamState();
+        if (!existing) {
+            console.log();
+            console.log(chalk.gray('  No active exam session to reset.'));
+            console.log();
+            return;
+        }
+        const tok = existing.session.token;
+        console.log();
+        console.log(chalk.yellow('  ⚠  Reset will abandon your current exam session on this device.'));
+        console.log(chalk.gray('     Exam:  ') + chalk.white(existing.session.examName));
+        if (tok)
+            console.log(chalk.gray('     Token: ') + chalk.white(tok));
+        console.log(chalk.gray('     The token itself is NOT revoked server-side. If your session is'));
+        console.log(chalk.gray('     still active and not submitted, re-entering the same token resumes it.'));
+        console.log();
+        console.log(chalk.gray('  Type ') + chalk.bold.cyan('reset') + chalk.gray(' to confirm, or anything else to cancel:'));
+        // Typed-word confirmation — matches existing exam submit confirm pattern
+        const confirmWord = await new Promise((resolve) => {
+            process.stdout.write('  > ');
+            const onData = (chunk) => {
+                const s = chunk.toString().trim();
+                if (s.includes('\n') || s.includes('\r') || s.length > 0) {
+                    process.stdin.removeListener('data', onData);
+                    resolve(s.replace(/[\r\n]/g, ''));
+                }
+            };
+            process.stdin.on('data', onData);
+            process.stdin.resume();
+        });
+        if (confirmWord.toLowerCase() !== 'reset') {
+            console.log(chalk.gray('  Cancelled.'));
+            console.log();
+            return;
+        }
+        clearState();
+        console.log();
+        console.log(chalk.green('  ✓ Exam state cleared.'));
+        console.log(chalk.gray('  You can now enter a new token with ') + chalk.bold.cyan('exam <token>'));
+        console.log();
+    });
     exam
         .command('demo')
         .description('Try a free practice exam (no account needed)')

package/dist/commands/lang.js

@@ -133,7 +133,12 @@ export function registerLangCommand(program) {
                     console.log(chalk.white(`  Resume: exam q ${currentQ}`));
                 }
                 else {
-                    console.log(chalk.yellow('  Could not reload questions in new language. Try again later.'));
+                    // Most common cause here: the stored session's token was already
+                    // submitted on the server (409) or the exam window has closed.
+                    // Surface the recovery path so the user isn't locked out.
+                    console.log(chalk.yellow('  Could not reload questions in new language.'));
+                    console.log(chalk.gray('  The saved session may be expired or already submitted server-side.'));
+                    console.log(chalk.gray('  To abandon it and start fresh: ') + chalk.bold.cyan('back') + chalk.gray(' → ') + chalk.bold.cyan('exam reset') + chalk.gray(' → ') + chalk.bold.cyan('exam <new-token>'));
                 }
             }
             catch {

package/dist/index.js

@@ -15,7 +15,6 @@ import { registerEnvCommand } from './commands/env.js';
 import { registerAi4ctfCommand } from './commands/ai4ctf.js';
 import { registerExamCommand } from './commands/exam.js';
 import { registerCtf4aiDemoCommand } from './commands/ctf4ai-demo.js';
-import { registerTutorialCommand } from './commands/tutorial.js';
 import { registerThemeCommand } from './commands/theme.js';
 import { getConfig, saveConfig } from './lib/config.js';
 import { startRepl } from './repl.js';
@@ -149,7 +148,6 @@ registerEnvCommand(program);
 registerAi4ctfCommand(program);
 registerExamCommand(program);
 registerCtf4aiDemoCommand(program);
-registerTutorialCommand(program);
 registerThemeCommand(program);
 // Hidden command: switch AI model
 program

package/dist/repl.js

@@ -162,8 +162,8 @@ function printSelectionMenu() {
         console.log();
         console.log(chalk.gray('   ─────────────────────────────────────────────'));
         console.log(chalk.bold.cyan('     demo') + chalk.gray(`            ${demoLine}`));
-        console.log(chalk.white('     lang es') + chalk.gray('         Switch language (17 supported)'));
-        console.log(chalk.gray('                     e.g. lang es (Español), lang zh, lang fr'));
+        console.log(chalk.white('     lang') + chalk.gray('            List all supported languages'));
+        console.log(chalk.white('     lang es') + chalk.gray('         Switch language (e.g. lang es, lang zh, lang fr)'));
         console.log(chalk.gray('   ─────────────────────────────────────────────'));
     }
     else if (!setupDone) {
@@ -175,7 +175,8 @@ function printSelectionMenu() {
         console.log(chalk.gray('   ─────────────────────────────────────────────'));
         console.log(chalk.white('     demo') + chalk.gray(`            ${demoLine}`));
         console.log(chalk.bold.yellow('     exam setup') + chalk.gray('      Install tools for national selection (~150MB)'));
-        console.log(chalk.white('     lang es') + chalk.gray('         Switch language (17 supported)'));
+        console.log(chalk.white('     lang') + chalk.gray('            List all supported languages'));
+        console.log(chalk.white('     lang es') + chalk.gray('         Switch language (e.g. lang es, lang zh, lang fr)'));
         console.log(chalk.gray('   ─────────────────────────────────────────────'));
     }
     else {
@@ -196,7 +197,8 @@ function printSelectionMenu() {
         console.log(chalk.gray('   Other commands:'));
         console.log(chalk.white('     demo') + chalk.gray(`            ${demoLine}`));
         console.log(chalk.white('     exam setup') + chalk.gray('      Re-verify tool environment'));
-        console.log(chalk.white('     lang es') + chalk.gray('         Switch language (17 supported)'));
+        console.log(chalk.white('     lang') + chalk.gray('            List all supported languages'));
+        console.log(chalk.white('     lang es') + chalk.gray('         Switch language (e.g. lang es, lang zh, lang fr)'));
         console.log(chalk.gray('   ─────────────────────────────────────────────'));
     }
     console.log(chalk.gray('   ') +
@@ -982,7 +984,7 @@ export async function startRepl(program, resumeMode) {
                 const KNOWN_CMDS = [
                     'ctf', 'hint', 'hint-b', 'hint-c', 'hint-budget', 'ref', 'shell',
                     'files', 'connect', 'note', 'log', 'lang', 'setup', 'env',
-                    'ai4ctf', 'exam', 'ctf4ai', 'tutorial', 'theme',
+                    'ai4ctf', 'exam', 'ctf4ai', 'theme',
                     'clear', 'cls', 'quit', 'exit', 'back', 'menu', 'help',
                     'continue', 'activate', 'demo', 'challenges', 'status', 'scoreboard',
                     'join', 'logout',

package/package.json

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

package/dist/commands/tutorial.d.ts

@@ -1,12 +0,0 @@
-/**
- * `tutorial` command — a 30-second interactive walk-through for K-12 beginners
- * who have never used a command-line tool before. Explains the 4 core
- * mechanics of ICOA CLI: typing commands, answering questions, getting help,
- * and exiting safely. No real exam state touched — pure narration + press-Enter.
- *
- * Triggered by: typing `tutorial` at the REPL prompt.
- * Advertised in: printSelectionMenu tip footer and help listings.
- */
-import { Command } from 'commander';
-export declare function runTutorial(): Promise<void>;
-export declare function registerTutorialCommand(program: Command): void;

package/dist/commands/tutorial.js

@@ -1,127 +0,0 @@
-/**
- * `tutorial` command — a 30-second interactive walk-through for K-12 beginners
- * who have never used a command-line tool before. Explains the 4 core
- * mechanics of ICOA CLI: typing commands, answering questions, getting help,
- * and exiting safely. No real exam state touched — pure narration + press-Enter.
- *
- * Triggered by: typing `tutorial` at the REPL prompt.
- * Advertised in: printSelectionMenu tip footer and help listings.
- */
-import chalk from 'chalk';
-function waitForEnter(promptText = '  Press Enter to continue... ') {
-    // Raw-stdin read (matches pattern used by exam start + demo confirm).
-    // A second readline on process.stdin fights the parent REPL, so we read
-    // raw bytes and resolve on \n or \r.
-    return new Promise((resolve) => {
-        process.stdout.write(chalk.bold.yellow(promptText));
-        const wasRaw = process.stdin.isTTY ? process.stdin.isRaw : false;
-        if (process.stdin.isTTY && process.stdin.setRawMode) {
-            process.stdin.setRawMode(false);
-        }
-        const onData = (chunk) => {
-            const s = chunk.toString();
-            if (s.includes('\n') || s.includes('\r')) {
-                process.stdin.removeListener('data', onData);
-                if (process.stdin.isTTY && process.stdin.setRawMode) {
-                    process.stdin.setRawMode(wasRaw);
-                }
-                process.stdout.write('\n');
-                resolve();
-            }
-        };
-        process.stdin.on('data', onData);
-        process.stdin.resume();
-    });
-}
-function divider() {
-    console.log(chalk.gray('   ─────────────────────────────────────────────'));
-}
-function screenHeader(n, total, title) {
-    console.log();
-    console.log(chalk.cyan(`   ─── Step ${n} / ${total} · ${title} ───`));
-    console.log();
-}
-export async function runTutorial() {
-    console.log();
-    console.log(chalk.bold.green('   📚  ICOA CLI — 30-Second Tutorial'));
-    console.log(chalk.gray('   Never used a command-line before? You\'ll be fine. 4 steps total.'));
-    console.log();
-    await waitForEnter();
-    // ─── Step 1 ───────────────────────────────────────────────────────
-    screenHeader(1, 4, 'Typing commands');
-    console.log(chalk.white('   The CLI waits for you to ') + chalk.bold('type a command and press Enter') + chalk.white('.'));
-    console.log();
-    console.log(chalk.gray('   For example, when you see the prompt:'));
-    console.log();
-    console.log('      ' + chalk.cyan('icoa> '));
-    console.log();
-    console.log(chalk.gray('   You type a word like ') + chalk.cyan('help') + chalk.gray(' or ') + chalk.cyan('demo') + chalk.gray(' and press Enter.'));
-    console.log(chalk.gray('   If you type something wrong, nothing bad happens — try again.'));
-    console.log();
-    await waitForEnter();
-    // ─── Step 2 ───────────────────────────────────────────────────────
-    screenHeader(2, 4, 'Answering questions');
-    console.log(chalk.white('   Multiple-choice questions show 4 options (A / B / C / D).'));
-    console.log(chalk.gray('   Example:'));
-    console.log();
-    divider();
-    console.log(chalk.white('     Q1. Which command shows the current directory?'));
-    console.log(chalk.gray('       A) cd     B) pwd     C) ls     D) dir'));
-    divider();
-    console.log();
-    console.log(chalk.gray('   To answer, type: ') + chalk.cyan('exam answer 1 B') + chalk.gray('  (question number + letter)'));
-    console.log(chalk.gray('   Or the shortcut:  ') + chalk.cyan('B') + chalk.gray('                 (letter alone on the current question)'));
-    console.log();
-    console.log(chalk.gray('   After you answer, the CLI auto-saves — you won\'t lose work if you exit.'));
-    console.log();
-    await waitForEnter();
-    // ─── Step 3 ───────────────────────────────────────────────────────
-    screenHeader(3, 4, 'Getting help when stuck');
-    console.log(chalk.white('   Stuck? Several ways to get help, from gentlest to most revealing:'));
-    console.log();
-    console.log('   ' + chalk.cyan('help') + chalk.gray('        — list all available commands'));
-    console.log('   ' + chalk.cyan('help        ') + chalk.gray('(or ') + chalk.cyan('?') + chalk.gray(')  — same, shorter to type'));
-    console.log('   ' + chalk.cyan('ref grep') + chalk.gray('    — quick reference for a specific tool'));
-    console.log();
-    console.log(chalk.white('   Inside a question:'));
-    console.log('   ' + chalk.cyan('help') + chalk.gray('        — eliminate one wrong multiple-choice option'));
-    console.log('   ' + chalk.cyan('hint a') + chalk.gray('      — general direction (practical questions only)'));
-    console.log('   ' + chalk.cyan('hint b') + chalk.gray('      — specific technique'));
-    console.log('   ' + chalk.cyan('hint c') + chalk.gray('      — near-solution (masked, 50% revealed)'));
-    console.log();
-    console.log(chalk.gray('   The exam has a budget for each — using one doesn\'t end the question.'));
-    console.log();
-    await waitForEnter();
-    // ─── Step 4 ───────────────────────────────────────────────────────
-    screenHeader(4, 4, 'Exiting & pausing safely');
-    console.log(chalk.white('   Three escape hatches, each with a different meaning:'));
-    console.log();
-    console.log('   ' + chalk.cyan('back') + chalk.gray(' or ') + chalk.cyan('menu') + chalk.gray('   — return to the main menu; exam stays saved, timer keeps running'));
-    console.log('   ' + chalk.cyan('exit') + chalk.gray('           — same as back (from any prompt)'));
-    console.log('   ' + chalk.cyan('quit') + chalk.gray('           — close the CLI entirely; next time use ') + chalk.cyan('icoa --resume'));
-    console.log('   ' + chalk.cyan('Ctrl+C') + chalk.gray('         — pause + show where you are (no data loss)'));
-    console.log();
-    console.log(chalk.gray('   Closing your terminal window is also safe — your answers are on disk.'));
-    console.log();
-    await waitForEnter();
-    // ─── Final ────────────────────────────────────────────────────────
-    console.log();
-    console.log(chalk.bold.green('   ✨  That\'s it. You\'re ready.'));
-    console.log();
-    console.log(chalk.white('   Try next:'));
-    console.log('     ' + chalk.cyan('demo') + chalk.gray('            — free practice (10 questions, no timer)'));
-    console.log('     ' + chalk.cyan('exam <token>') + chalk.gray('    — real exam (when you have an organizer-issued token)'));
-    console.log('     ' + chalk.cyan('lang es') + chalk.gray('         — switch UI language (17 supported)'));
-    console.log('     ' + chalk.cyan('theme high-contrast') + chalk.gray(' — low-vision-friendly colors (restart after)'));
-    console.log();
-    console.log(chalk.gray('   Full beginner guide: ') + chalk.cyan.underline('https://github.com/newaipanda/ICOA_CLI/blob/main/docs/getting-started-k12.md'));
-    console.log();
-}
-export function registerTutorialCommand(program) {
-    program
-        .command('tutorial')
-        .description('30-second walk-through for first-time CLI users')
-        .action(async () => {
-        await runTutorial();
-    });
-}