icoa-cli 2.19.356 → 2.19.357

package/dist/index.js

@@ -1,2 +1,356 @@
 #!/usr/bin/env node
-import{Command as o}from"commander";import chalk from"chalk";import{registerCtfCommands as e}from"./commands/ctf.js";import{registerRefCommand as n}from"./commands/ref.js";import{registerShellCommand as s}from"./commands/shell.js";import{registerFilesCommand as r}from"./commands/files.js";import{registerViewCommand as t}from"./commands/view.js";import{registerConnectCommand as i}from"./commands/connect.js";import{registerChallengeCommand as a}from"./commands/challenge.js";import{registerNoteCommand as l}from"./commands/note.js";import{registerLogCommand as m}from"./commands/log.js";import{registerLangCommand as c}from"./commands/lang.js";import{registerSetupCommand as g}from"./commands/setup.js";import{registerEnvCommand as d}from"./commands/env.js";import{registerAienvCommand as p}from"./commands/aienv.js";import{registerIpynbCommand as y}from"./commands/ipynb.js";import{registerAi4ctfCommand as h}from"./commands/ai4ctf.js";import{registerExamCommand as f}from"./commands/exam.js";import{registerCtf4aiDemoCommand as u}from"./commands/ctf4ai-demo.js";import{registerThemeCommand as w}from"./commands/theme.js";import{registerLearnCommand as T}from"./commands/learn.js";import{registerCtf4VlaCommand as b}from"./commands/ctf4vla.js";import{registerDemo2Command as v}from"./commands/demo2.js";import{registerSimCommand as I}from"./commands/sim.js";import{registerArenaCommand as $}from"./commands/arena.js";import{getConfig as j,saveConfig as A}from"./lib/config.js";import{startRepl as C}from"./repl.js";import{RELAUNCH_CODE as E}from"./lib/menu-nav.js";import{setTerminalTheme as _}from"./lib/theme.js";import{checkForUpdates as S}from"./lib/update-check.js";import{detectIcoaInstalls as x}from"./lib/platform.js";import{ICOA_BIG as L}from"./lib/banner.js";import{readFileSync as N}from"node:fs";import{fileURLToPath as O}from"node:url";import{dirname as k,join as F}from"node:path";const R=k(O(import.meta.url)),U=JSON.parse(N(F(R,"..","package.json"),"utf-8")).version,P=chalk.cyan("  ─────────────────────────────────────────────────────"),M=`\n${P}\n\n${L.map(o=>`   ${chalk.bold.white(o)}`).join("\n")}\n\n   ${chalk.yellow("International Cyber Olympiad in AI 2026")}\n   ${chalk.bold.magenta("The World's First AI-Native CLI Operating System")}\n   ${chalk.bold.magenta("for Cybersecurity & AI Security Competition")}\n   ${chalk.bold.magenta("and Olympiad for K-12")}\n\n   ${chalk.green.bold("AI4CTF")}  ${chalk.gray("[Day 1]")}    ${chalk.white("AI as your teammate")}\n   ${chalk.red.bold("CTF4AI")}  ${chalk.gray("[Day 2]")}    ${chalk.white("Challenge & evaluate AI systems")}\n   ${chalk.cyan.bold("CTF4EAI")} ${chalk.gray("[Pioneer]")}  ${chalk.white("Embodied AI security")}\n   ${chalk.bold.yellow("AI is your teammate. AI is your target. AI is embodied.")}\n\n   ${chalk.white("Sydney, Australia")}  ${chalk.gray("Jun 27 - Jul 2, 2026")}\n   ${chalk.cyan.underline("https://icoa2026.au")}\n\n   ${chalk.gray(`CLI-Native Competition Terminal  v${U}`)}\n\n${P}\n`;process.on("uncaughtException",o=>{"__REPL_NO_EXIT__"!==o.message&&(console.error(chalk.red("Error:"),o.message),process.exit(1))}),process.on("unhandledRejection",o=>{const e=o instanceof Error?o.message:String(o);"__REPL_NO_EXIT__"!==e&&(console.error(chalk.red("Error:"),e),process.exit(1))});{const o=process.argv.slice(2).some(o=>["-V","--version","-h","--help"].includes(o));if(!0===process.stdin.isTTY&&"1"!==process.env.ICOA_SUPERVISED&&!o){const{spawnSync:o}=await import("node:child_process");process.on("SIGINT",()=>{}),process.on("SIGTERM",()=>{});let e=0,n=!1;do{const s=o(process.execPath,process.argv.slice(1),{stdio:"inherit",env:{...process.env,ICOA_SUPERVISED:"1",...n?{ICOA_RELAUNCH:"1"}:{}}});if(s.signal){e=0;break}e=s.status,n=!0}while(e===E);process.exit(e??0)}}const G=new o;if(G.name("icoa").version(U).description("ICOA CLI — CLI-Native CTF Competition Terminal").option("--resume","Resume previous session").action(async o=>{const e=j();_("high-contrast"===e.themeVariant?"high-contrast":"dark"),S(),function(){const o=x();if(o.length<=1)return;const e=o[0];if([...o.map(o=>o.version||"0.0.0")].sort((o,e)=>function(o,e){const n=o.split(".").map(o=>parseInt(o,10)||0),s=e.split(".").map(o=>parseInt(o,10)||0);for(let o=0;o<3;o++)if((n[o]||0)!==(s[o]||0))return(n[o]||0)-(s[o]||0);return 0}(e,o))[0]!==e.version){console.log(),console.log(chalk.yellow.bold("  ⚠ Multiple icoa installations detected on PATH:"));for(let e=0;e<o.length;e++){const n=o[e],s=n.version?`v${n.version}`:"(version unreadable)",r=0===e?chalk.yellow("→"):" ",t=0===e?chalk.gray(" ← currently running (older — shadowing newer install)"):chalk.gray(" ← shadowed");console.log(`     ${r} ${chalk.cyan(n.path.padEnd(28))} ${chalk.white(s)}${t}`)}console.log(),console.log(chalk.yellow("  The first install on PATH wins. To use the newer one, remove the older:")),console.log(),e.pkgDir?console.log(`     ${chalk.bold.cyan(`sudo rm -rf ${e.pkgDir} ${e.path}`)}`):console.log(`     ${chalk.bold.cyan(`sudo rm -rf ${e.path}  # also delete its node_modules dir`)}`),console.log(),console.log(chalk.gray("  Then re-run icoa to confirm version banner shows the newer release.")),console.log()}}();const n=process.env.LANG||process.env.LC_ALL||process.env.LC_CTYPE||"";if(!/UTF-?8/i.test(n))if("win32"===process.platform){let o="";try{const{execFileSync:e}=await import("node:child_process");o=e("chcp.com",[],{encoding:"utf-8",timeout:1500,stdio:["ignore","pipe","ignore"]}).trim()}catch{}o.includes("65001")||(console.log(chalk.yellow(`⚠ Windows terminal is not using UTF-8 (current: ${o||"unknown"}).`)),console.log(chalk.gray('  Non-English text (Ukrainian, Chinese, Japanese, etc.) may show as "?" or garbled glyphs.')),console.log(chalk.gray("  Fix (run before ")+chalk.cyan("icoa")+chalk.gray("): ")+chalk.cyan("chcp 65001")),console.log(chalk.gray("  Or stay in English inside the CLI: ")+chalk.cyan("lang en")),console.log())}else console.log(chalk.yellow(`⚠ Your terminal locale is not UTF-8 (LANG=${n||"(unset)"}).`)),console.log(chalk.gray('  Non-English text and box characters may display as "?" or garbled glyphs.')),console.log(chalk.gray("  Fix: ")+chalk.cyan("export LANG=en_US.UTF-8")+chalk.gray(" (or your locale, e.g. ")+chalk.cyan("zh_CN.UTF-8")+chalk.gray(", ")+chalk.cyan("uk_UA.UTF-8")+chalk.gray(")")),console.log();if(console.log(M),process.argv.length<=2||o.resume)return o.resume||"1"===process.env.ICOA_RELAUNCH||await async function(){const o=process.stdin;if(o.isTTY&&"function"==typeof o.setRawMode)return new Promise(e=>{let n=!1;const s=()=>{if(!n){n=!0,o.removeListener("data",r);try{o.setRawMode(!1)}catch{}o.pause(),e()}},r=()=>s();o.setRawMode(!0),o.resume(),o.once("data",r),console.log(chalk.gray("   (press any key to continue...)")),setTimeout(s,3e3)});await new Promise(o=>setTimeout(o,3e3))}(),void C(G,!!o.resume)}),e(G),n(G),s(G),r(G),t(G),i(G),a(G),l(G),m(G),c(G),g(G),d(G),p(G),y(G),h(G),f(G),u(G),w(G),T(G),b(G),v(G),I(G),$(G),G.command("model",{hidden:!0}).argument("[name]","model name to switch to").action(o=>{const e=j().geminiModel||"gemini-2.5-flash-lite";o?(A({geminiModel:o}),console.log(),console.log(chalk.green("  Model switched: ")+chalk.gray(e)+chalk.white(" -> ")+chalk.bold.white(o)),console.log()):(console.log(),console.log(chalk.gray("  Current model: ")+chalk.white(e)),console.log(),console.log(chalk.gray("  Available models:")),console.log(chalk.bold.white("    Gemini 3.x (Latest)")),console.log(chalk.white("    model gemini-3.5-flash          ")+chalk.gray("Newest stable, paid Tier 1+")),console.log(chalk.white("    model gemini-3-flash-preview    ")+chalk.gray("Preview")),console.log(chalk.bold.white("    Gemini 2.5 (Stable)")),console.log(chalk.white("    model gemini-2.5-flash-lite     ")+chalk.gray("Fastest, default, free tier")),console.log(chalk.white("    model gemini-2.5-flash          ")+chalk.gray("Heavier, thinking enabled")),console.log(chalk.white("    model gemini-2.5-pro            ")+chalk.gray("Strong reasoning, paid")),console.log(chalk.bold.white("    Open Source")),console.log(chalk.white("    model gemma-4-31b-it            ")+chalk.gray("Free, open-source")),console.log(chalk.white("    model <any-model-id>            ")+chalk.gray("Custom model")),console.log(),console.log(chalk.gray("  Translation uses gemini-3.5-flash for best quality.")),console.log())}),"1"===process.env.ICOA_RESET_STATE)try{const{clearExamState:o}=await import("./lib/exam-state.js");o(),console.log(chalk.yellow("⚠ ICOA_RESET_STATE=1 — local exam state wiped.")),console.log(chalk.gray("  (Token NOT revoked server-side. Re-enter a fresh token with `exam <token>`.)")),console.log()}catch(o){console.log(chalk.red("⚠ ICOA_RESET_STATE: could not clear state — ")+chalk.gray(String(o)))}G.parse();
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { registerCtfCommands } from './commands/ctf.js';
+import { registerRefCommand } from './commands/ref.js';
+import { registerShellCommand } from './commands/shell.js';
+import { registerFilesCommand } from './commands/files.js';
+import { registerViewCommand } from './commands/view.js';
+import { registerConnectCommand } from './commands/connect.js';
+import { registerChallengeCommand } from './commands/challenge.js';
+import { registerNoteCommand } from './commands/note.js';
+import { registerLogCommand } from './commands/log.js';
+import { registerLangCommand } from './commands/lang.js';
+import { registerSetupCommand } from './commands/setup.js';
+import { registerEnvCommand } from './commands/env.js';
+import { registerAienvCommand } from './commands/aienv.js';
+import { registerIpynbCommand } from './commands/ipynb.js';
+import { registerAi4ctfCommand } from './commands/ai4ctf.js';
+import { registerExamCommand } from './commands/exam.js';
+import { registerCtf4aiDemoCommand } from './commands/ctf4ai-demo.js';
+import { registerThemeCommand } from './commands/theme.js';
+import { registerLearnCommand } from './commands/learn.js';
+import { registerCtf4VlaCommand } from './commands/ctf4vla.js';
+import { registerDemo2Command } from './commands/demo2.js';
+import { registerSimCommand } from './commands/sim.js';
+import { registerArenaCommand } from './commands/arena.js';
+import { getConfig, saveConfig } from './lib/config.js';
+import { startRepl } from './repl.js';
+import { RELAUNCH_CODE } from './lib/menu-nav.js';
+import { setTerminalTheme } from './lib/theme.js';
+import { checkForUpdates } from './lib/update-check.js';
+import { detectIcoaInstalls } from './lib/platform.js';
+import { ICOA_BIG } from './lib/banner.js';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_VERSION = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8')).version;
+const LINE = chalk.cyan('  ─────────────────────────────────────────────────────');
+const BANNER = `
+${LINE}
+
+${ICOA_BIG.map((l) => `   ${chalk.bold.white(l)}`).join('\n')}
+
+   ${chalk.yellow('International Cyber Olympiad in AI 2026')}
+   ${chalk.bold.magenta("The World's First AI-Native CLI Operating System")}
+   ${chalk.bold.magenta('for Cybersecurity & AI Security Competition')}
+   ${chalk.bold.magenta('and Olympiad for K-12')}
+
+   ${chalk.green.bold('AI4CTF')}  ${chalk.gray('[Day 1]')}    ${chalk.white('AI as your teammate')}
+   ${chalk.red.bold('CTF4AI')}  ${chalk.gray('[Day 2]')}    ${chalk.white('Challenge & evaluate AI systems')}
+   ${chalk.cyan.bold('CTF4EAI')} ${chalk.gray('[Pioneer]')}  ${chalk.white('Embodied AI security')}
+   ${chalk.bold.yellow('AI is your teammate. AI is your target. AI is embodied.')}
+
+   ${chalk.white('Sydney, Australia')}  ${chalk.gray('Jun 27 - Jul 2, 2026')}
+   ${chalk.cyan.underline('https://icoa2026.au')}
+
+   ${chalk.gray(`CLI-Native Competition Terminal  v${PKG_VERSION}`)}
+
+${LINE}
+`;
+// Global error handlers
+process.on('uncaughtException', (err) => {
+    if (err.message === '__REPL_NO_EXIT__')
+        return;
+    console.error(chalk.red('Error:'), err.message);
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    const msg = reason instanceof Error ? reason.message : String(reason);
+    if (msg === '__REPL_NO_EXIT__')
+        return;
+    console.error(chalk.red('Error:'), msg);
+    process.exit(1);
+});
+// ─── Single-process supervisor (fixes the menu-bounce slowdown) ────────────
+// Interactive sessions relaunch on `menu`. The old approach (returnToMainMenu
+// spawning a child while the parent stayed alive) STACKED node processes: K
+// bounces left K+1 live processes all holding the inherited TTY, which slowed
+// the CLI to a crawl and dropped keystrokes ("learn" → "lan"). A 4-deep chain
+// was observed in prod (2026-06-04).
+//
+// Fix: a thin supervisor runs the real CLI as a child via spawnSync and
+// relaunches it ONLY when it exits with RELAUNCH_CODE (what `menu` now does).
+// Exactly one worker is ever alive, so navigation stays fast regardless of how
+// many times the user bounces to the menu.
+//
+// Scoped to interactive TTY sessions only — one-shot flags (--version/--help)
+// and non-TTY/piped runs skip the supervisor entirely, so scripted/CI usage is
+// byte-for-byte unchanged. The worker is marked with ICOA_SUPERVISED=1 so it
+// skips this block and runs the real CLI below.
+{
+    const argvRest = process.argv.slice(2);
+    const isOneShot = argvRest.some((a) => ['-V', '--version', '-h', '--help'].includes(a));
+    const wantSupervisor = process.stdin.isTTY === true && process.env.ICOA_SUPERVISED !== '1' && !isOneShot;
+    if (wantSupervisor) {
+        const { spawnSync } = await import('node:child_process');
+        // The supervisor must survive Ctrl+C: the worker owns SIGINT (exam pause,
+        // inquirer cancel) and decides its own exit code. If the supervisor died
+        // on SIGINT the whole session would drop to the shell mid-exam.
+        process.on('SIGINT', () => { });
+        process.on('SIGTERM', () => { });
+        let exitCode = 0;
+        let relaunch = false;
+        do {
+            const res = spawnSync(process.execPath, process.argv.slice(1), {
+                stdio: 'inherit',
+                env: {
+                    ...process.env,
+                    ICOA_SUPERVISED: '1',
+                    // After the first launch, tell the worker it's a relaunch so it can
+                    // skip the 3s intro pause (the banner still shows — it IS the menu).
+                    ...(relaunch ? { ICOA_RELAUNCH: '1' } : {}),
+                },
+            });
+            if (res.signal) {
+                // Worker killed by a signal (e.g. SIGKILL) — don't relaunch.
+                exitCode = 0;
+                break;
+            }
+            exitCode = res.status;
+            relaunch = true;
+        } while (exitCode === RELAUNCH_CODE);
+        process.exit(exitCode ?? 0);
+    }
+}
+// Pause for ms, skippable by any key press (so users can read the banner)
+async function pauseWithSkip(ms) {
+    const stdin = process.stdin;
+    if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') {
+        await new Promise((r) => setTimeout(r, ms));
+        return;
+    }
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            stdin.removeListener('data', onKey);
+            try {
+                stdin.setRawMode(false);
+            }
+            catch { }
+            stdin.pause();
+            resolve();
+        };
+        const onKey = () => finish();
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.once('data', onKey);
+        console.log(chalk.gray('   (press any key to continue...)'));
+        setTimeout(finish, ms);
+    });
+}
+/**
+ * Detect duplicate icoa installations on PATH and warn at startup if the
+ * shell is currently resolving to a stale older copy. Catches the
+ * "8 versions behind, sudo install changes nothing" failure mode (real
+ * incident, 2026-05-05) that happens when npm prefix changed across
+ * Node.js install methods (apt vs nodesource vs nvm) without cleaning up
+ * previous global installs. Silent when there's only one install (the
+ * normal case).
+ */
+function warnIfDuplicateInstall() {
+    const installs = detectIcoaInstalls();
+    if (installs.length <= 1)
+        return;
+    const first = installs[0];
+    // If first is the newest version of all detected installs, the shadowing
+    // is benign — the right binary is winning. Skip the warning.
+    const versions = installs.map((i) => i.version || '0.0.0');
+    const sorted = [...versions].sort((a, b) => cmpSemver(b, a));
+    if (sorted[0] === first.version)
+        return;
+    console.log();
+    console.log(chalk.yellow.bold('  ⚠ Multiple icoa installations detected on PATH:'));
+    for (let i = 0; i < installs.length; i++) {
+        const it = installs[i];
+        const verStr = it.version ? `v${it.version}` : '(version unreadable)';
+        const arrow = i === 0 ? chalk.yellow('→') : ' ';
+        const note = i === 0 ? chalk.gray(' ← currently running (older — shadowing newer install)') : chalk.gray(' ← shadowed');
+        console.log(`     ${arrow} ${chalk.cyan(it.path.padEnd(28))} ${chalk.white(verStr)}${note}`);
+    }
+    console.log();
+    console.log(chalk.yellow('  The first install on PATH wins. To use the newer one, remove the older:'));
+    console.log();
+    if (first.pkgDir) {
+        console.log(`     ${chalk.bold.cyan(`sudo rm -rf ${first.pkgDir} ${first.path}`)}`);
+    }
+    else {
+        console.log(`     ${chalk.bold.cyan(`sudo rm -rf ${first.path}  # also delete its node_modules dir`)}`);
+    }
+    console.log();
+    console.log(chalk.gray('  Then re-run icoa to confirm version banner shows the newer release.'));
+    console.log();
+}
+// Tiny semver comparator — handles 1.2.3 / 10.20.300 etc. but NOT pre-release
+// suffixes (we don't ship those). Returns positive if a > b.
+function cmpSemver(a, b) {
+    const pa = a.split('.').map((x) => parseInt(x, 10) || 0);
+    const pb = b.split('.').map((x) => parseInt(x, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] || 0) !== (pb[i] || 0))
+            return (pa[i] || 0) - (pb[i] || 0);
+    }
+    return 0;
+}
+const program = new Command();
+program
+    .name('icoa')
+    // T4-X2: version now reads live from package.json (PKG_VERSION).
+    // Was hardcoded to '1.2.0' which made `icoa --version` misreport on every
+    // release — bug since v1.2.0 era, finally fixed.
+    .version(PKG_VERSION)
+    .description('ICOA CLI — CLI-Native CTF Competition Terminal')
+    .option('--resume', 'Resume previous session')
+    .action(async (opts) => {
+    // Terminal theme — Darcula by default, 'high-contrast' for low-vision users.
+    // Variant stored in config.themeVariant; toggled via `theme` REPL command.
+    const cfg = getConfig();
+    setTerminalTheme(cfg.themeVariant === 'high-contrast' ? 'high-contrast' : 'dark');
+    checkForUpdates();
+    warnIfDuplicateInstall();
+    // T2-7: UTF-8 locale sanity check. Non-UTF-8 terminals mangle the box-
+    // drawing banner, the ✓/✗/⚠ glyphs used throughout the CLI, and any
+    // Cyrillic/CJK/Arabic/Devanagari/etc. translation text. Warn once at
+    // startup (not blocking) so students see a concrete fix hint instead of
+    // wondering why "哪个命令..." appears as "????..." on their machine.
+    const envLang = process.env.LANG || process.env.LC_ALL || process.env.LC_CTYPE || '';
+    if (!/UTF-?8/i.test(envLang)) {
+        if (process.platform === 'win32') {
+            // Windows cmd.exe default code page (437 US, 936 CN, etc.) mangles
+            // non-Latin script. Fix is `chcp 65001`, not Unix-style `export LANG`.
+            // Skip the warning if the code page is already 65001 (PowerShell +
+            // Windows Terminal often set it automatically).
+            let codepage = '';
+            try {
+                const { execFileSync } = await import('node:child_process');
+                codepage = execFileSync('chcp.com', [], {
+                    encoding: 'utf-8',
+                    timeout: 1500,
+                    stdio: ['ignore', 'pipe', 'ignore'],
+                }).trim();
+            }
+            catch {
+                /* chcp.com unavailable or timed out */
+            }
+            if (!codepage.includes('65001')) {
+                console.log(chalk.yellow(`⚠ Windows terminal is not using UTF-8 (current: ${codepage || 'unknown'}).`));
+                console.log(chalk.gray('  Non-English text (Ukrainian, Chinese, Japanese, etc.) may show as "?" or garbled glyphs.'));
+                console.log(chalk.gray('  Fix (run before ') + chalk.cyan('icoa') + chalk.gray('): ') + chalk.cyan('chcp 65001'));
+                console.log(chalk.gray('  Or stay in English inside the CLI: ') + chalk.cyan('lang en'));
+                console.log();
+            }
+        }
+        else {
+            console.log(chalk.yellow(`⚠ Your terminal locale is not UTF-8 (LANG=${envLang || '(unset)'}).`));
+            console.log(chalk.gray('  Non-English text and box characters may display as "?" or garbled glyphs.'));
+            console.log(chalk.gray('  Fix: ') +
+                chalk.cyan('export LANG=en_US.UTF-8') +
+                chalk.gray(' (or your locale, e.g. ') +
+                chalk.cyan('zh_CN.UTF-8') +
+                chalk.gray(', ') +
+                chalk.cyan('uk_UA.UTF-8') +
+                chalk.gray(')'));
+            console.log();
+        }
+    }
+    console.log(BANNER);
+    // If running interactively (no extra args or --resume), start REPL
+    if (process.argv.length <= 2 || opts.resume) {
+        // Brief pause so users can read the banner + logo before mode selector appears.
+        // Skip on --resume (user is coming back) and on a supervisor relaunch
+        // (ICOA_RELAUNCH=1 — they just hit `menu`, no need to re-watch the intro).
+        if (!opts.resume && process.env.ICOA_RELAUNCH !== '1') {
+            await pauseWithSkip(3000);
+        }
+        startRepl(program, !!opts.resume);
+        return;
+    }
+});
+registerCtfCommands(program);
+registerRefCommand(program);
+registerShellCommand(program);
+registerFilesCommand(program);
+registerViewCommand(program);
+registerConnectCommand(program);
+registerChallengeCommand(program);
+registerNoteCommand(program);
+registerLogCommand(program);
+registerLangCommand(program);
+registerSetupCommand(program);
+registerEnvCommand(program);
+registerAienvCommand(program);
+registerIpynbCommand(program);
+registerAi4ctfCommand(program);
+registerExamCommand(program);
+registerCtf4aiDemoCommand(program);
+registerThemeCommand(program);
+registerLearnCommand(program);
+registerCtf4VlaCommand(program);
+registerDemo2Command(program);
+registerSimCommand(program);
+registerArenaCommand(program);
+// Hidden command: switch AI model
+program
+    .command('model', { hidden: true })
+    .argument('[name]', 'model name to switch to')
+    .action((name) => {
+    const config = getConfig();
+    const current = config.geminiModel || 'gemini-2.5-flash-lite';
+    if (!name) {
+        console.log();
+        console.log(chalk.gray('  Current model: ') + chalk.white(current));
+        console.log();
+        console.log(chalk.gray('  Available models:'));
+        console.log(chalk.bold.white('    Gemini 3.x (Latest)'));
+        console.log(chalk.white('    model gemini-3.5-flash          ') + chalk.gray('Newest stable, paid Tier 1+'));
+        console.log(chalk.white('    model gemini-3-flash-preview    ') + chalk.gray('Preview'));
+        console.log(chalk.bold.white('    Gemini 2.5 (Stable)'));
+        console.log(chalk.white('    model gemini-2.5-flash-lite     ') + chalk.gray('Fastest, default, free tier'));
+        console.log(chalk.white('    model gemini-2.5-flash          ') + chalk.gray('Heavier, thinking enabled'));
+        console.log(chalk.white('    model gemini-2.5-pro            ') + chalk.gray('Strong reasoning, paid'));
+        console.log(chalk.bold.white('    Open Source'));
+        console.log(chalk.white('    model gemma-4-31b-it            ') + chalk.gray('Free, open-source'));
+        console.log(chalk.white('    model <any-model-id>            ') + chalk.gray('Custom model'));
+        console.log();
+        console.log(chalk.gray('  Translation uses gemini-3.5-flash for best quality.'));
+        console.log();
+    }
+    else {
+        saveConfig({ geminiModel: name });
+        console.log();
+        console.log(chalk.green('  Model switched: ') + chalk.gray(current) + chalk.white(' -> ') + chalk.bold.white(name));
+        console.log();
+    }
+});
+// Proctor-only escape hatch: `ICOA_RESET_STATE=1 icoa` wipes any abandoned
+// exam state *before* any subcommand or REPL runs. Fires for ALL invocations
+// (including `icoa exam <token>`) so proctors have a one-liner recovery that
+// works regardless of which subcommand the student would run next.
+// The token itself is untouched server-side.
+if (process.env.ICOA_RESET_STATE === '1') {
+    try {
+        const { clearExamState } = await import('./lib/exam-state.js');
+        clearExamState();
+        console.log(chalk.yellow('⚠ ICOA_RESET_STATE=1 — local exam state wiped.'));
+        console.log(chalk.gray('  (Token NOT revoked server-side. Re-enter a fresh token with `exam <token>`.)'));
+        console.log();
+    }
+    catch (e) {
+        console.log(chalk.red('⚠ ICOA_RESET_STATE: could not clear state — ') + chalk.gray(String(e)));
+    }
+}
+program.parse();

package/dist/lib/access.js

@@ -1 +1,184 @@
-import{createHash as t,randomUUID as e}from"node:crypto";import{execSync as n}from"node:child_process";import{platform as r}from"node:os";import{getConfig as i,saveConfig as o,getIcoaDir as s}from"./config.js";import{readFileSync as c,writeFileSync as a,existsSync as u}from"node:fs";import{join as f}from"node:path";const p=/^ICOA-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$/;export function isFirstRunOrUpgrade(t){return i().lastVersion!==t}export function markVersionSeen(t){o({lastVersion:t})}const l=new Set(["ref","help","exit","quit","q","clear","cls","activate"]);export function isActivated(){return!!i().accessToken}export function getDeviceFingerprint(){const s=i();if(s.deviceFingerprint)return s.deviceFingerprint;let a=s.installSalt;a||(a=e(),o({installSalt:a}));const f=function(){try{if("darwin"===r()){const t=n("ioreg -rd1 -c IOPlatformExpertDevice | grep IOPlatformUUID",{encoding:"utf-8"}).match(/"([A-F0-9-]+)"/);if(t)return t[1]}else if("linux"===r()){if(u("/etc/machine-id"))return c("/etc/machine-id","utf-8").trim()}else if("win32"===r())return n('powershell -Command "(Get-CimInstance Win32_ComputerSystemProduct).UUID"',{encoding:"utf-8"}).trim()}catch{}return""}();return t("sha256").update(`${f}|${a}`).digest("hex")}export function activateToken(e){if(!function(t){return p.test(t.trim().toUpperCase())}(e))return"invalid";const n=getDeviceFingerprint(),r=f(s(),"token-bindings.json");let i={};if(u(r))try{i=JSON.parse(c(r,"utf-8"))}catch{}const l=function(e){return t("sha256").update(e.trim().toUpperCase()).digest("hex")}(e),d=i[l];return d&&d!==n?"already_bound":(i[l]=n,a(r,JSON.stringify(i,null,2)),o({accessToken:e.trim().toUpperCase(),deviceFingerprint:n}),"ok")}export function isDeviceMatch(){const t=i();return!t.deviceFingerprint||t.deviceFingerprint===getDeviceFingerprint()}export function isFreeCommand(t){return l.has(t.toLowerCase())}const d=()=>f(s(),"session-state.json");function m(){return{startedAt:(new Date).toISOString(),lastExitAt:null,lastResumeAt:null,exitCount:0,totalAwaySeconds:0}}function g(){const t=d();if(!u(t))return m();try{return{...m(),...JSON.parse(c(t,"utf-8"))}}catch{return m()}}function x(t){const e={...g(),...t};a(d(),JSON.stringify(e,null,2))}export function recordExit(){const t=g();t.lastExitAt=(new Date).toISOString(),t.exitCount++,x(t)}export function recordResume(){const t=g();if(!t.lastExitAt)return null;const e=new Date(t.lastExitAt).getTime(),n=Date.now(),r=Math.round((n-e)/1e3);return t.lastResumeAt=(new Date).toISOString(),t.totalAwaySeconds+=r,x(t),{awaySeconds:r,exitCount:t.exitCount}}
+import { createHash, randomUUID } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { platform } from 'node:os';
+import { getConfig, saveConfig, getIcoaDir } from './config.js';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+// Access-token format check. The shipped SHA-256 hash table (~300 valid tokens)
+// was REMOVED 2026-06-21 (B3): it was a redundant-for-security UX gate, and
+// shipping the hashes let anyone enumerate valid tokens offline. The real
+// boundary is server-side — exam/learn/AI all re-validate the token + device
+// against the server's `exam_tokens` table at point of use (token-api.py). So
+// the client now only format-checks; `activate` is a UX unlock, and every
+// privileged action stays server-authoritative. Already-activated users are
+// grandfathered (isActivated() trusts a stored accessToken). See
+// docs/POST_COMPETITION_AUDIT_STANDARD.md §10 (B3).
+const TOKEN_FORMAT = /^ICOA-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$/;
+// Check if first run or version upgrade
+export function isFirstRunOrUpgrade(currentVersion) {
+    const config = getConfig();
+    return config.lastVersion !== currentVersion;
+}
+export function markVersionSeen(version) {
+    saveConfig({ lastVersion: version });
+}
+// Free commands that don't require token
+const FREE_COMMANDS = new Set(['ref', 'help', 'exit', 'quit', 'q', 'clear', 'cls', 'activate']);
+function hashToken(token) {
+    return createHash('sha256').update(token.trim().toUpperCase()).digest('hex');
+}
+function validateToken(token) {
+    // Format only (B3). A well-formed token unlocks the UI; whether it is a real,
+    // unspent, device-matched token is decided server-side at point of use.
+    return TOKEN_FORMAT.test(token.trim().toUpperCase());
+}
+export function isActivated() {
+    // UX gate only (B3). Grandfather anyone already activated (stored accessToken),
+    // else require a format-valid token via activate(). Nothing more to check
+    // client-side — the server is authoritative for every privileged action.
+    const config = getConfig();
+    return !!config.accessToken;
+}
+// Stable hardware identifier: the OS-reported machine UUID. Returns '' when it
+// cannot be read reliably. We deliberately do NOT fall back to a MAC address
+// (the old behaviour): MACs change with network-interface state — Wi-Fi vs
+// ethernet, VPN up/down, USB NICs, macOS private-address randomization — and
+// were the classic source of fingerprint drift. The empty-string fallback is
+// fine because the value is always folded with the persisted install salt and
+// then frozen (see getDeviceFingerprint), so it is only ever read once.
+function _getStableHardwareId() {
+    try {
+        if (platform() === 'darwin') {
+            const out = execSync('ioreg -rd1 -c IOPlatformExpertDevice | grep IOPlatformUUID', { encoding: 'utf-8' });
+            const match = out.match(/"([A-F0-9-]+)"/);
+            if (match)
+                return match[1];
+        }
+        else if (platform() === 'linux') {
+            if (existsSync('/etc/machine-id')) {
+                return readFileSync('/etc/machine-id', 'utf-8').trim();
+            }
+        }
+        else if (platform() === 'win32') {
+            const out = execSync('powershell -Command "(Get-CimInstance Win32_ComputerSystemProduct).UUID"', {
+                encoding: 'utf-8',
+            });
+            return out.trim();
+        }
+    }
+    catch {
+        /* hardware UUID unavailable — fall through to the salt-only fingerprint */
+    }
+    return '';
+}
+// Device fingerprint (NAT-resilient + drift-proof):
+//
+// The Apr-26 Ukraine deployment surfaced a fingerprint *collapse* — students
+// behind a centralized proxy all had identical hostname/platform/arch/MAC at
+// the egress, so 30+ students hashed to one device. v2.19.185 fixed that by
+// mixing a random per-install salt into the hash.
+//
+// This revision fixes the opposite failure — fingerprint *drift*: the salted
+// hash still folded in volatile signals (the MAC fallback, an intermittently
+// readable hardware UUID), so the SAME machine could hash differently between
+// runs and falsely trip the "different device" lockout on re-entry / a second
+// terminal. Fix: (1) the persisted install salt is the stable anchor, (2) only
+// the stable hardware UUID is folded in (never a MAC), and (3) once a
+// fingerprint is stored it is authoritative and returned verbatim — never
+// recomputed. That last rule also preserves backward-compat for every already-
+// bound install (pre-185 salt-less and v185 salted alike): each matches itself.
+export function getDeviceFingerprint() {
+    const config = getConfig();
+    // Authoritative once bound — return the stored value, never recompute.
+    if (config.deviceFingerprint)
+        return config.deviceFingerprint;
+    // First fingerprint on this install: persisted salt + stable hardware UUID.
+    let salt = config.installSalt;
+    if (!salt) {
+        salt = randomUUID();
+        saveConfig({ installSalt: salt });
+    }
+    const hw = _getStableHardwareId();
+    return createHash('sha256').update(`${hw}|${salt}`).digest('hex');
+}
+export function activateToken(token) {
+    if (!validateToken(token))
+        return 'invalid';
+    const fingerprint = getDeviceFingerprint();
+    const bindingFile = join(getIcoaDir(), 'token-bindings.json');
+    // Load existing bindings
+    let bindings = {};
+    if (existsSync(bindingFile)) {
+        try {
+            bindings = JSON.parse(readFileSync(bindingFile, 'utf-8'));
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const tokenHash = hashToken(token);
+    const existingDevice = bindings[tokenHash];
+    if (existingDevice && existingDevice !== fingerprint) {
+        // Token already bound to a different device
+        return 'already_bound';
+    }
+    // Bind token to this device
+    bindings[tokenHash] = fingerprint;
+    writeFileSync(bindingFile, JSON.stringify(bindings, null, 2));
+    saveConfig({ accessToken: token.trim().toUpperCase(), deviceFingerprint: fingerprint });
+    return 'ok';
+}
+export function isDeviceMatch() {
+    const config = getConfig();
+    if (!config.deviceFingerprint)
+        return true; // Legacy: no fingerprint yet
+    return config.deviceFingerprint === getDeviceFingerprint();
+}
+export function isFreeCommand(cmd) {
+    return FREE_COMMANDS.has(cmd.toLowerCase());
+}
+// Session tracking for anti-cheat
+const SESSION_FILE = () => join(getIcoaDir(), 'session-state.json');
+function getDefaultSession() {
+    return {
+        startedAt: new Date().toISOString(),
+        lastExitAt: null,
+        lastResumeAt: null,
+        exitCount: 0,
+        totalAwaySeconds: 0,
+    };
+}
+function getSession() {
+    const file = SESSION_FILE();
+    if (!existsSync(file))
+        return getDefaultSession();
+    try {
+        return { ...getDefaultSession(), ...JSON.parse(readFileSync(file, 'utf-8')) };
+    }
+    catch {
+        return getDefaultSession();
+    }
+}
+function saveSession(session) {
+    const current = getSession();
+    const merged = { ...current, ...session };
+    writeFileSync(SESSION_FILE(), JSON.stringify(merged, null, 2));
+}
+export function recordExit() {
+    const session = getSession();
+    session.lastExitAt = new Date().toISOString();
+    session.exitCount++;
+    saveSession(session);
+}
+export function recordResume() {
+    const session = getSession();
+    if (!session.lastExitAt)
+        return null;
+    const exitTime = new Date(session.lastExitAt).getTime();
+    const now = Date.now();
+    const awaySeconds = Math.round((now - exitTime) / 1000);
+    session.lastResumeAt = new Date().toISOString();
+    session.totalAwaySeconds += awaySeconds;
+    saveSession(session);
+    return { awaySeconds, exitCount: session.exitCount };
+}