icoa-cli 2.19.89 → 2.19.91

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';
@@ -105,8 +106,10 @@ program
     .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
@@ -147,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

@@ -179,16 +179,23 @@ function printSelectionMenu() {
         console.log(chalk.gray('   ─────────────────────────────────────────────'));
     }
     else {
-        // State 2: fully prepared. Show the token entry CTA.
+        // State 2: fully prepared. Exam entry is the primary CTA — list it FIRST
+        // and make the token format + origin obvious. Students landing here have
+        // already done demo; without a concrete example they stare at "<token>"
+        // and don't know what to type or where the token comes from.
         const plural = stats.attempts === 1 ? 'attempt' : 'attempts';
         console.log(chalk.green('   ✓ Demo completed ') + chalk.gray(`(${stats.attempts} ${plural})`));
         console.log(chalk.green('   ✓ Environment ready'));
         console.log(chalk.yellow('   → Enter your exam token to begin.'));
+        console.log(chalk.gray('     (10-char code from your organizer, starts with your country code like ') + chalk.cyan('UA') + chalk.gray(' — case-insensitive)'));
         console.log();
         console.log(chalk.gray('   ─────────────────────────────────────────────'));
+        console.log(chalk.bold.yellow('     exam <token>') + chalk.gray('    Enter exam (primary action — use your organizer-issued token)'));
+        console.log(chalk.gray('                     format: ') + chalk.white('exam UAxxxxxxxx') + chalk.gray('  (2-letter country prefix + 8 chars)'));
+        console.log(chalk.gray('   ─────────────────────────────────────────────'));
+        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.bold.yellow('     exam <token>') + chalk.gray('    Enter exam with access token'));
         console.log(chalk.white('     lang es') + chalk.gray('         Switch language (17 supported)'));
         console.log(chalk.gray('   ─────────────────────────────────────────────'));
     }
@@ -984,7 +991,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',
+                    'ai4ctf', 'exam', 'ctf4ai', 'tutorial', 'theme',
                     'clear', 'cls', 'quit', 'exit', 'back', 'menu', 'help',
                     'continue', 'activate', 'demo', 'challenges', 'status', 'scoreboard',
                     'join', 'logout',

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.89",
+  "version": "2.19.91",
   "description": "ICOA CLI — The world's first CLI-native CTF competition terminal",
   "type": "module",
   "bin": {