icoa-cli 2.19.87 → 2.19.89

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -229,7 +229,7 @@ export async function handleChatMessage(input) {
229
229
  }
230
230
  return 'continue';
231
231
  }
232
- if (input === 'exit' || input === 'back' || input === 'quit') {
232
+ if (input === 'exit' || input === 'back' || input === 'quit' || input === 'menu') {
233
233
  chatActive = false;
234
234
  chatSession = null;
235
235
  // Anonymous stats
@@ -104,7 +104,7 @@ export async function handleCtf4aiMessage(input) {
104
104
  if (examCtf4aiCtx) {
105
105
  return handleExamCtf4aiMessage(input);
106
106
  }
107
- if (input === 'exit' || input === 'back' || input === 'quit') {
107
+ if (input === 'exit' || input === 'back' || input === 'quit' || input === 'menu') {
108
108
  ctf4aiActive = false;
109
109
  ctf4aiSession = null;
110
110
  fetch('https://practice.icoa2026.au/api/icoa/demo-stats', {
@@ -388,7 +388,7 @@ async function handleExamCtf4aiMessage(input) {
388
388
  return 'continue';
389
389
  }
390
390
  // Exit
391
- if (lower === 'exit' || lower === 'back' || lower === 'quit') {
391
+ if (lower === 'exit' || lower === 'back' || lower === 'quit' || lower === 'menu') {
392
392
  const savedQ = examCtf4aiCtx.qNum;
393
393
  const { getExamState } = await import('../lib/exam-state.js');
394
394
  const exitState = getExamState();
@@ -0,0 +1,12 @@
1
+ /**
2
+ * `tutorial` command — a 30-second interactive walk-through for K-12 beginners
3
+ * who have never used a command-line tool before. Explains the 4 core
4
+ * mechanics of ICOA CLI: typing commands, answering questions, getting help,
5
+ * and exiting safely. No real exam state touched — pure narration + press-Enter.
6
+ *
7
+ * Triggered by: typing `tutorial` at the REPL prompt.
8
+ * Advertised in: printSelectionMenu tip footer and help listings.
9
+ */
10
+ import { Command } from 'commander';
11
+ export declare function runTutorial(): Promise<void>;
12
+ export declare function registerTutorialCommand(program: Command): void;
@@ -0,0 +1,124 @@
1
+ /**
2
+ * `tutorial` command — a 30-second interactive walk-through for K-12 beginners
3
+ * who have never used a command-line tool before. Explains the 4 core
4
+ * mechanics of ICOA CLI: typing commands, answering questions, getting help,
5
+ * and exiting safely. No real exam state touched — pure narration + press-Enter.
6
+ *
7
+ * Triggered by: typing `tutorial` at the REPL prompt.
8
+ * Advertised in: printSelectionMenu tip footer and help listings.
9
+ */
10
+ import chalk from 'chalk';
11
+ function waitForEnter(promptText = ' Press Enter to continue... ') {
12
+ // Raw-stdin read (matches pattern used by exam start + demo confirm).
13
+ // A second readline on process.stdin fights the parent REPL, so we read
14
+ // raw bytes and resolve on \n or \r.
15
+ return new Promise((resolve) => {
16
+ process.stdout.write(chalk.bold.yellow(promptText));
17
+ const wasRaw = process.stdin.isTTY ? process.stdin.isRaw : false;
18
+ if (process.stdin.isTTY && process.stdin.setRawMode) {
19
+ process.stdin.setRawMode(false);
20
+ }
21
+ const onData = (chunk) => {
22
+ const s = chunk.toString();
23
+ if (s.includes('\n') || s.includes('\r')) {
24
+ process.stdin.removeListener('data', onData);
25
+ if (process.stdin.isTTY && process.stdin.setRawMode) {
26
+ process.stdin.setRawMode(wasRaw);
27
+ }
28
+ process.stdout.write('\n');
29
+ resolve();
30
+ }
31
+ };
32
+ process.stdin.on('data', onData);
33
+ process.stdin.resume();
34
+ });
35
+ }
36
+ function divider() {
37
+ console.log(chalk.gray(' ─────────────────────────────────────────────'));
38
+ }
39
+ function screenHeader(n, total, title) {
40
+ console.log();
41
+ console.log(chalk.cyan(` ─── Step ${n} / ${total} · ${title} ───`));
42
+ console.log();
43
+ }
44
+ export async function runTutorial() {
45
+ console.log();
46
+ console.log(chalk.bold.green(' 📚 ICOA CLI — 30-Second Tutorial'));
47
+ console.log(chalk.gray(' Never used a command-line before? You\'ll be fine. 4 steps total.'));
48
+ console.log();
49
+ await waitForEnter();
50
+ // ─── Step 1 ───────────────────────────────────────────────────────
51
+ screenHeader(1, 4, 'Typing commands');
52
+ console.log(chalk.white(' The CLI waits for you to ') + chalk.bold('type a command and press Enter') + chalk.white('.'));
53
+ console.log();
54
+ console.log(chalk.gray(' For example, when you see the prompt:'));
55
+ console.log();
56
+ console.log(' ' + chalk.cyan('icoa> '));
57
+ console.log();
58
+ console.log(chalk.gray(' You type a word like ') + chalk.cyan('help') + chalk.gray(' or ') + chalk.cyan('demo') + chalk.gray(' and press Enter.'));
59
+ console.log(chalk.gray(' If you type something wrong, nothing bad happens — try again.'));
60
+ console.log();
61
+ await waitForEnter();
62
+ // ─── Step 2 ───────────────────────────────────────────────────────
63
+ screenHeader(2, 4, 'Answering questions');
64
+ console.log(chalk.white(' Multiple-choice questions show 4 options (A / B / C / D).'));
65
+ console.log(chalk.gray(' Example:'));
66
+ console.log();
67
+ divider();
68
+ console.log(chalk.white(' Q1. Which command shows the current directory?'));
69
+ console.log(chalk.gray(' A) cd B) pwd C) ls D) dir'));
70
+ divider();
71
+ console.log();
72
+ console.log(chalk.gray(' To answer, type: ') + chalk.cyan('exam answer 1 B') + chalk.gray(' (question number + letter)'));
73
+ console.log(chalk.gray(' Or the shortcut: ') + chalk.cyan('B') + chalk.gray(' (letter alone on the current question)'));
74
+ console.log();
75
+ console.log(chalk.gray(' After you answer, the CLI auto-saves — you won\'t lose work if you exit.'));
76
+ console.log();
77
+ await waitForEnter();
78
+ // ─── Step 3 ───────────────────────────────────────────────────────
79
+ screenHeader(3, 4, 'Getting help when stuck');
80
+ console.log(chalk.white(' Stuck? Several ways to get help, from gentlest to most revealing:'));
81
+ console.log();
82
+ console.log(' ' + chalk.cyan('help') + chalk.gray(' — list all available commands'));
83
+ console.log(' ' + chalk.cyan('help ') + chalk.gray('(or ') + chalk.cyan('?') + chalk.gray(') — same, shorter to type'));
84
+ console.log(' ' + chalk.cyan('ref grep') + chalk.gray(' — quick reference for a specific tool'));
85
+ console.log();
86
+ console.log(chalk.white(' Inside a question:'));
87
+ console.log(' ' + chalk.cyan('help') + chalk.gray(' — eliminate one wrong multiple-choice option'));
88
+ console.log(' ' + chalk.cyan('hint a') + chalk.gray(' — general direction (practical questions only)'));
89
+ console.log(' ' + chalk.cyan('hint b') + chalk.gray(' — specific technique'));
90
+ console.log(' ' + chalk.cyan('hint c') + chalk.gray(' — near-solution (masked, 50% revealed)'));
91
+ console.log();
92
+ console.log(chalk.gray(' The exam has a budget for each — using one doesn\'t end the question.'));
93
+ console.log();
94
+ await waitForEnter();
95
+ // ─── Step 4 ───────────────────────────────────────────────────────
96
+ screenHeader(4, 4, 'Exiting & pausing safely');
97
+ console.log(chalk.white(' Three escape hatches, each with a different meaning:'));
98
+ console.log();
99
+ console.log(' ' + chalk.cyan('back') + chalk.gray(' or ') + chalk.cyan('menu') + chalk.gray(' — return to the main menu; exam stays saved, timer keeps running'));
100
+ console.log(' ' + chalk.cyan('exit') + chalk.gray(' — same as back (from any prompt)'));
101
+ console.log(' ' + chalk.cyan('quit') + chalk.gray(' — close the CLI entirely; next time use ') + chalk.cyan('icoa --resume'));
102
+ console.log(' ' + chalk.cyan('Ctrl+C') + chalk.gray(' — pause + show where you are (no data loss)'));
103
+ console.log();
104
+ console.log(chalk.gray(' Closing your terminal window is also safe — your answers are on disk.'));
105
+ console.log();
106
+ await waitForEnter();
107
+ // ─── Final ────────────────────────────────────────────────────────
108
+ console.log();
109
+ console.log(chalk.bold.green(' ✨ That\'s it. You\'re ready.'));
110
+ console.log();
111
+ console.log(chalk.white(' Try next:'));
112
+ console.log(' ' + chalk.cyan('demo') + chalk.gray(' — free practice (10 questions, no timer)'));
113
+ console.log(' ' + chalk.cyan('exam <token>') + chalk.gray(' — real exam (when you have an organizer-issued token)'));
114
+ console.log(' ' + chalk.cyan('lang es') + chalk.gray(' — switch UI language (17 supported)'));
115
+ console.log();
116
+ }
117
+ export function registerTutorialCommand(program) {
118
+ program
119
+ .command('tutorial')
120
+ .description('30-second walk-through for first-time CLI users')
121
+ .action(async () => {
122
+ await runTutorial();
123
+ });
124
+ }
package/dist/index.js CHANGED
@@ -15,6 +15,7 @@ import { registerEnvCommand } from './commands/env.js';
15
15
  import { registerAi4ctfCommand } from './commands/ai4ctf.js';
16
16
  import { registerExamCommand } from './commands/exam.js';
17
17
  import { registerCtf4aiDemoCommand } from './commands/ctf4ai-demo.js';
18
+ import { registerTutorialCommand } from './commands/tutorial.js';
18
19
  import { getConfig, saveConfig } from './lib/config.js';
19
20
  import { startRepl } from './repl.js';
20
21
  import { setTerminalTheme } from './lib/theme.js';
@@ -97,7 +98,10 @@ async function pauseWithSkip(ms) {
97
98
  const program = new Command();
98
99
  program
99
100
  .name('icoa')
100
- .version('1.2.0')
101
+ // T4-X2: version now reads live from package.json (PKG_VERSION).
102
+ // Was hardcoded to '1.2.0' which made `icoa --version` misreport on every
103
+ // release — bug since v1.2.0 era, finally fixed.
104
+ .version(PKG_VERSION)
101
105
  .description('ICOA CLI — CLI-Native CTF Competition Terminal')
102
106
  .option('--resume', 'Resume previous session')
103
107
  .action(async (opts) => {
@@ -142,6 +146,7 @@ registerEnvCommand(program);
142
146
  registerAi4ctfCommand(program);
143
147
  registerExamCommand(program);
144
148
  registerCtf4aiDemoCommand(program);
149
+ registerTutorialCommand(program);
145
150
  // Hidden command: switch AI model
146
151
  program
147
152
  .command('model', { hidden: true })
package/dist/repl.js CHANGED
@@ -197,9 +197,9 @@ function printSelectionMenu() {
197
197
  // need to be visible without cluttering the main command list above.
198
198
  console.log(chalk.gray(' ') +
199
199
  chalk.gray('Tip: ') + chalk.cyan('help') + chalk.gray(' for commands · ') +
200
+ chalk.cyan('tutorial') + chalk.gray(' for 30-sec walkthrough · ') +
200
201
  chalk.cyan('Ctrl+C') + chalk.gray(' pauses · ') +
201
- chalk.cyan('exit') + chalk.gray(' → menu · ') +
202
- chalk.cyan('quit') + chalk.gray(' closes CLI'));
202
+ chalk.cyan('quit') + chalk.gray(' closes'));
203
203
  console.log();
204
204
  }
205
205
  export async function startRepl(program, resumeMode) {
@@ -227,10 +227,12 @@ export async function startRepl(program, resumeMode) {
227
227
  // ─── Mode selection (every launch) ───
228
228
  const { select: selectMode, confirm: confirmMode } = await import('@inquirer/prompts');
229
229
  const savedMode = config.mode || '';
230
+ // T3-10: Mode labels clarified for K-12 newcomers who don't know the
231
+ // difference between "selection" and "olympiad" at first glance.
230
232
  const modeChoices = [
231
- { name: ` ${chalk.bold('National Selection')} ${chalk.gray('·')} ${chalk.gray('demo, exam, lightweight')}`, value: 'selection' },
232
- { name: ` ${chalk.bold('International Olympiad')} ${chalk.gray('·')} ${chalk.gray('CTF x AI (~500MB)')}`, value: 'olympiad' },
233
- { name: ` ${chalk.bold('National/Regional Partner')} ${chalk.gray('·')} ${chalk.gray('Organizer management')}`, value: 'organizer' },
233
+ { name: ` ${chalk.bold('National Selection')} ${chalk.gray('·')} ${chalk.green('K-12 recommended')} ${chalk.gray('demo, exam, lightweight')}`, value: 'selection' },
234
+ { name: ` ${chalk.bold('International Olympiad')} ${chalk.gray('·')} ${chalk.yellow('Advanced')} ${chalk.gray('CTF x AI (~500MB)')}`, value: 'olympiad' },
235
+ { name: ` ${chalk.bold('National/Regional Partner')} ${chalk.gray('·')} ${chalk.cyan('Organizers')} ${chalk.gray(' token & competition mgmt')}`, value: 'organizer' },
234
236
  { name: ` ${chalk.gray('About ICOA')} ${chalk.gray('·')} ${chalk.gray('Info & contact')}`, value: 'about' },
235
237
  ];
236
238
  console.log(chalk.gray(' Use ') + chalk.yellow('↑') + chalk.gray(' or ') + chalk.yellow('↓') + chalk.gray(' to select, ') + chalk.yellow('Enter') + chalk.gray(' to confirm.'));
@@ -424,6 +426,9 @@ export async function startRepl(program, resumeMode) {
424
426
  console.log(chalk.white(' scoreboard') + chalk.gray(' Live rankings'));
425
427
  console.log(chalk.white(' help') + chalk.gray(' Full command list'));
426
428
  console.log(chalk.gray(' ─────────────────────────────────────────────'));
429
+ // T4-X1: parity with Selection-mode footer — give Olympiad users the
430
+ // same beginner escape-hatch hint so newcomers don't get stuck.
431
+ 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'));
427
432
  console.log();
428
433
  }
429
434
  else if (activated) {
@@ -438,8 +443,9 @@ export async function startRepl(program, resumeMode) {
438
443
  console.log(chalk.white(' Step 2 ') + chalk.bold.cyan('challenges') + chalk.gray(' Browse & solve challenges'));
439
444
  console.log(chalk.white(' Step 3 ') + chalk.bold.cyan('hint') + chalk.gray(' Ask AI when stuck'));
440
445
  console.log();
441
- console.log(chalk.gray(' Also: ') + chalk.white('env') + chalk.gray(' check tools ') + chalk.white('help') + chalk.gray(' all commands'));
446
+ 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'));
442
447
  console.log(chalk.gray(' ─────────────────────────────────────────────'));
448
+ 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'));
443
449
  console.log();
444
450
  }
445
451
  else {
@@ -455,7 +461,9 @@ export async function startRepl(program, resumeMode) {
455
461
  console.log(chalk.white(' ref web') + chalk.gray(' Quick reference for Web'));
456
462
  console.log(chalk.white(' env') + chalk.gray(' Check your tools'));
457
463
  console.log(chalk.white(' help') + chalk.gray(' All available commands'));
464
+ console.log(chalk.white(' tutorial') + chalk.gray(' 30-second walkthrough for first-timers'));
458
465
  console.log(chalk.gray(' ─────────────────────────────────────────────'));
466
+ 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'));
459
467
  console.log();
460
468
  }
461
469
  }
@@ -565,7 +573,9 @@ export async function startRepl(program, resumeMode) {
565
573
  // A demo is "active" if `startedAt` is within the last 30 minutes. That window
566
574
  // covers an intentional "back to check something and come right back" case but
567
575
  // clears anything left over from a prior session.
568
- if (input === 'back') {
576
+ // T3-9: `menu` is a universal alias for `back` — more discoverable for
577
+ // K-12 beginners. Both drop to the Selection menu (or pause active exam).
578
+ if (input === 'back' || input === 'menu') {
569
579
  const state = getExamState();
570
580
  const isRealExam = state && state.session.examId !== 'demo-free';
571
581
  const isActiveDemo = state && state.session.examId === 'demo-free' && (() => {
@@ -967,7 +977,30 @@ export async function startRepl(program, resumeMode) {
967
977
  // Command tried to exit — continue REPL
968
978
  }
969
979
  else if (msg.includes('commander.unknownCommand')) {
970
- console.log(chalk.yellow(` Unknown command: ${cmd}. Type 'help' for commands.`));
980
+ // T4-12: typo suggestion via Levenshtein distance. Shorten the
981
+ // "unknown command" frustration by pointing to the likely-intended
982
+ // command when the user's input is within 2 edits of a real one.
983
+ const { distance } = await import('fastest-levenshtein');
984
+ const KNOWN_CMDS = [
985
+ 'ctf', 'hint', 'hint-b', 'hint-c', 'hint-budget', 'ref', 'shell',
986
+ 'files', 'connect', 'note', 'log', 'lang', 'setup', 'env',
987
+ 'ai4ctf', 'exam', 'ctf4ai', 'tutorial',
988
+ 'clear', 'cls', 'quit', 'exit', 'back', 'menu', 'help',
989
+ 'continue', 'activate', 'demo', 'challenges', 'status', 'scoreboard',
990
+ 'join', 'logout',
991
+ ];
992
+ const firstWord = cmd.split(/\s+/)[0] || cmd;
993
+ let best = { word: '', dist: Infinity };
994
+ for (const known of KNOWN_CMDS) {
995
+ const d = distance(firstWord.toLowerCase(), known);
996
+ if (d < best.dist)
997
+ best = { word: known, dist: d };
998
+ }
999
+ console.log(chalk.yellow(` Unknown command: ${cmd}.`));
1000
+ if (best.dist > 0 && best.dist <= 2) {
1001
+ console.log(chalk.gray(' Did you mean: ') + chalk.bold.cyan(best.word) + chalk.gray('?'));
1002
+ }
1003
+ console.log(chalk.gray(' Type ') + chalk.cyan('help') + chalk.gray(' for the full command list.'));
971
1004
  }
972
1005
  else if (msg.includes('commander.')) {
973
1006
  // Internal Commander errors — ignore
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "icoa-cli",
3
- "version": "2.19.87",
3
+ "version": "2.19.89",
4
4
  "description": "ICOA CLI — The world's first CLI-native CTF competition terminal",
5
5
  "type": "module",
6
6
  "bin": {
@@ -32,6 +32,7 @@
32
32
  "chalk": "^5.4.1",
33
33
  "cli-table3": "^0.6.5",
34
34
  "commander": "^13.1.0",
35
+ "fastest-levenshtein": "^1.0.16",
35
36
  "marked": "^15.0.7",
36
37
  "marked-terminal": "^7.3.0",
37
38
  "ora": "^8.2.0"