icoa-cli 2.19.88 → 2.19.90

package/dist/commands/theme.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `theme` command — toggle terminal color scheme.
+ *
+ * Two variants:
+ *  - `dark` (default): Darcula — #2B2B2B bg + #A9B7C6 fg, easy on the eyes.
+ *  - `high-contrast`: pure black bg + pure white fg for low-vision users,
+ *    projectors, and cheap LCDs where Darcula's grays disappear.
+ *
+ * Change applies on next `icoa` launch (the current session keeps its paint
+ * to avoid flicker while students are mid-question).
+ */
+import { Command } from 'commander';
+export declare function registerThemeCommand(program: Command): void;

package/dist/commands/theme.js

@@ -0,0 +1,50 @@
+/**
+ * `theme` command — toggle terminal color scheme.
+ *
+ * Two variants:
+ *  - `dark` (default): Darcula — #2B2B2B bg + #A9B7C6 fg, easy on the eyes.
+ *  - `high-contrast`: pure black bg + pure white fg for low-vision users,
+ *    projectors, and cheap LCDs where Darcula's grays disappear.
+ *
+ * Change applies on next `icoa` launch (the current session keeps its paint
+ * to avoid flicker while students are mid-question).
+ */
+import chalk from 'chalk';
+import { getConfig, saveConfig } from '../lib/config.js';
+import { logCommand } from '../lib/logger.js';
+const VALID = ['dark', 'high-contrast'];
+export function registerThemeCommand(program) {
+    program
+        .command('theme [variant]')
+        .description('Switch color scheme (dark | high-contrast)')
+        .action((variant) => {
+        logCommand(`theme ${variant || ''}`);
+        const config = getConfig();
+        const current = config.themeVariant === 'high-contrast' ? 'high-contrast' : 'dark';
+        if (!variant) {
+            console.log();
+            console.log(chalk.gray('  Current theme: ') + chalk.white(current));
+            console.log();
+            console.log(chalk.gray('  Available themes:'));
+            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();
+            return;
+        }
+        if (!VALID.includes(variant)) {
+            console.log();
+            console.log(chalk.red(`  Unknown theme: ${variant}`));
+            console.log(chalk.gray('  Valid: ') + chalk.white(VALID.join(', ')));
+            console.log();
+            return;
+        }
+        saveConfig({ themeVariant: variant });
+        console.log();
+        console.log(chalk.green(`  ✓ Theme set to: ${variant}`));
+        console.log(chalk.gray('  Restart ') + chalk.cyan('icoa') + chalk.gray(' to see the new colors.'));
+        console.log();
+    });
+}

package/dist/commands/tutorial.js

@@ -112,6 +112,9 @@ export async function runTutorial() {
     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) {

package/dist/index.js

@@ -16,6 +16,7 @@ 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';
 import { setTerminalTheme } from './lib/theme.js';
@@ -98,12 +99,17 @@ async function pauseWithSkip(ms) {
 const program = new Command();
 program
     .name('icoa')
-    .version('1.2.0')
+    // 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) => {
-    // Force hacker theme: black background + green text
-    setTerminalTheme();
+    // 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();
     // T2-7: UTF-8 locale sanity check. Non-UTF-8 terminals mangle the box-
     // drawing banner, the ✓/✗/⚠ glyphs used throughout the CLI, and any
@@ -144,6 +150,7 @@ registerAi4ctfCommand(program);
 registerExamCommand(program);
 registerCtf4aiDemoCommand(program);
 registerTutorialCommand(program);
+registerThemeCommand(program);
 // Hidden command: switch AI model
 program
     .command('model', { hidden: true })

package/dist/lib/theme.d.ts

@@ -1,2 +1,3 @@
-export declare function setTerminalTheme(): void;
+export type ThemeVariant = 'dark' | 'high-contrast';
+export declare function setTerminalTheme(variant?: ThemeVariant): void;
 export declare function resetTerminalTheme(): void;

package/dist/lib/theme.js

@@ -19,20 +19,35 @@
 //
 // Legacy cmd.exe (pre-Win10 1809) can't run Node 22 anyway, so no separate
 // fallback path is needed.
-const OSC_INIT = '\x1b]10;#A9B7C6\x07' + // default fg
+const OSC_INIT_DARK = '\x1b]10;#A9B7C6\x07' + // default fg
     '\x1b]11;#2B2B2B\x07' + // default bg
     '\x1b]12;#A9B7C6\x07'; // cursor color
+// High-contrast: pure black bg + pure white fg. For students with low vision
+// or screens where Darcula's subtle grays wash out (e.g., projectors, cheap
+// LCDs under fluorescent light). Still works with existing chalk colors —
+// cyan/green/yellow/red all show up clearly against pure black.
+const OSC_INIT_HC = '\x1b]10;#FFFFFF\x07' +
+    '\x1b]11;#000000\x07' +
+    '\x1b]12;#FFFFFF\x07';
 const OSC_RESET = '\x1b]110\x07' + // reset default fg
     '\x1b]111\x07' + // reset default bg
     '\x1b]112\x07'; // reset cursor color
-const SGR_INIT_TRUECOLOR = '\x1b[38;2;169;183;198m' + // fg #A9B7C6
+const SGR_INIT_TRUECOLOR_DARK = '\x1b[38;2;169;183;198m' + // fg #A9B7C6
     '\x1b[48;2;43;43;43m' + // bg #2B2B2B
     '\x1b[2J' +
     '\x1b[H';
-const SGR_INIT_256 = '\x1b[38;5;250m' + // fg ≈ #BCBCBC
+const SGR_INIT_256_DARK = '\x1b[38;5;250m' + // fg ≈ #BCBCBC
     '\x1b[48;5;235m' + // bg ≈ #262626
     '\x1b[2J' +
     '\x1b[H';
+const SGR_INIT_TRUECOLOR_HC = '\x1b[38;2;255;255;255m' + // fg pure white
+    '\x1b[48;2;0;0;0m' + // bg pure black
+    '\x1b[2J' +
+    '\x1b[H';
+const SGR_INIT_256_HC = '\x1b[38;5;231m' + // fg white (231 = pure white in 256)
+    '\x1b[48;5;16m' + // bg black (16 = pure black in 256)
+    '\x1b[2J' +
+    '\x1b[H';
 const SGR_RESET = '\x1b[0m\x1b[2J\x1b[H';
 function supportsAnsi() {
     if (!process.stdout.isTTY)
@@ -58,13 +73,16 @@ function isAppleTerminal() {
     return process.env.TERM_PROGRAM === 'Apple_Terminal';
 }
 let armed = false;
-export function setTerminalTheme() {
+export function setTerminalTheme(variant = 'dark') {
     if (!supportsAnsi())
         return;
     if (isIcoaTerminal())
         return; // host is already Darcula; nothing to do
-    const sgr = isAppleTerminal() ? SGR_INIT_256 : SGR_INIT_TRUECOLOR;
-    process.stdout.write(OSC_INIT + sgr);
+    const osc = variant === 'high-contrast' ? OSC_INIT_HC : OSC_INIT_DARK;
+    const sgr = isAppleTerminal()
+        ? (variant === 'high-contrast' ? SGR_INIT_256_HC : SGR_INIT_256_DARK)
+        : (variant === 'high-contrast' ? SGR_INIT_TRUECOLOR_HC : SGR_INIT_TRUECOLOR_DARK);
+    process.stdout.write(osc + sgr);
     if (!armed) {
         armed = true;
         // Belt-and-braces cleanup on every exit path. Without these, Ctrl+C leaves

package/dist/repl.js

@@ -426,6 +426,9 @@ export async function startRepl(program, resumeMode) {
             console.log(chalk.white('     scoreboard') + chalk.gray('     Live rankings'));
             console.log(chalk.white('     help') + chalk.gray('           Full command list'));
             console.log(chalk.gray('   ─────────────────────────────────────────────'));
+            // T4-X1: parity with Selection-mode footer — give Olympiad users the
+            // same beginner escape-hatch hint so newcomers don't get stuck.
+            console.log(chalk.gray('   Tip: ') + chalk.cyan('help') + chalk.gray(' · ') + chalk.cyan('tutorial') + chalk.gray(' 30-sec tour · ') + chalk.cyan('Ctrl+C') + chalk.gray(' pauses · ') + chalk.cyan('quit') + chalk.gray(' closes'));
             console.log();
         }
         else if (activated) {
@@ -440,8 +443,9 @@ 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('   Also: ') + chalk.white('env') + chalk.gray(' check tools  ') + chalk.white('help') + chalk.gray(' all commands  ') + chalk.white('tutorial') + chalk.gray(' 30-sec tour'));
             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();
         }
         else {
@@ -457,7 +461,9 @@ export async function startRepl(program, resumeMode) {
             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('     help') + chalk.gray('            All available commands'));
+            console.log(chalk.white('     tutorial') + chalk.gray('        30-second walkthrough for first-timers'));
             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();
         }
     }
@@ -971,7 +977,30 @@ export async function startRepl(program, resumeMode) {
                 // Command tried to exit — continue REPL
             }
             else if (msg.includes('commander.unknownCommand')) {
-                console.log(chalk.yellow(`  Unknown command: ${cmd}. Type 'help' for commands.`));
+                // T4-12: typo suggestion via Levenshtein distance. Shorten the
+                // "unknown command" frustration by pointing to the likely-intended
+                // command when the user's input is within 2 edits of a real one.
+                const { distance } = await import('fastest-levenshtein');
+                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',
+                    'clear', 'cls', 'quit', 'exit', 'back', 'menu', 'help',
+                    'continue', 'activate', 'demo', 'challenges', 'status', 'scoreboard',
+                    'join', 'logout',
+                ];
+                const firstWord = cmd.split(/\s+/)[0] || cmd;
+                let best = { word: '', dist: Infinity };
+                for (const known of KNOWN_CMDS) {
+                    const d = distance(firstWord.toLowerCase(), known);
+                    if (d < best.dist)
+                        best = { word: known, dist: d };
+                }
+                console.log(chalk.yellow(`  Unknown command: ${cmd}.`));
+                if (best.dist > 0 && best.dist <= 2) {
+                    console.log(chalk.gray('  Did you mean: ') + chalk.bold.cyan(best.word) + chalk.gray('?'));
+                }
+                console.log(chalk.gray('  Type ') + chalk.cyan('help') + chalk.gray(' for the full command list.'));
             }
             else if (msg.includes('commander.')) {
                 // Internal Commander errors — ignore

package/dist/types/index.d.ts

@@ -106,6 +106,7 @@ export interface IcoaConfig {
     country: string;
     mode: IcoaMode | '';
     demoIntroSeen: boolean;
+    themeVariant?: 'dark' | 'high-contrast';
 }
 export type CompetitionState = 'pre_competition' | 'demo' | 'live' | 'finished' | 'unknown';
 export type IcoaMode = 'selection' | 'olympiad' | 'organizer';

package/dist/types/index.js

@@ -33,5 +33,6 @@ export const DEFAULT_CONFIG = {
     country: '',
     mode: '',
     demoIntroSeen: false,
+    themeVariant: 'dark',
 };
 export const SUPPORTED_LANGUAGES = ['en', 'zh', 'ja', 'ko', 'es', 'ar', 'fr', 'pt', 'ru', 'hi', 'de', 'id', 'th', 'vi', 'tr', 'uk', 'ht'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icoa-cli",
-  "version": "2.19.88",
+  "version": "2.19.90",
   "description": "ICOA CLI — The world's first CLI-native CTF competition terminal",
   "type": "module",
   "bin": {
@@ -32,6 +32,7 @@
     "chalk": "^5.4.1",
     "cli-table3": "^0.6.5",
     "commander": "^13.1.0",
+    "fastest-levenshtein": "^1.0.16",
     "marked": "^15.0.7",
     "marked-terminal": "^7.3.0",
     "ora": "^8.2.0"