icoa-cli 2.19.86 → 2.19.88
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.
- package/dist/commands/ai4ctf.js +1 -1
- package/dist/commands/ctf4ai-demo.js +2 -2
- package/dist/commands/exam.js +28 -0
- package/dist/commands/tutorial.d.ts +12 -0
- package/dist/commands/tutorial.js +124 -0
- package/dist/index.js +14 -0
- package/dist/repl.js +21 -8
- package/package.json +1 -1
package/dist/commands/ai4ctf.js
CHANGED
|
@@ -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();
|
package/dist/commands/exam.js
CHANGED
|
@@ -1795,6 +1795,34 @@ export function registerExamCommand(program) {
|
|
|
1795
1795
|
await playDemoIntro();
|
|
1796
1796
|
saveConfig({ demoIntroSeen: true });
|
|
1797
1797
|
}
|
|
1798
|
+
// T2-6: Pre-start confirmation. Prevents accidental launches (user typed
|
|
1799
|
+
// `demo` instead of exploring the menu). No timer pressure, but exam
|
|
1800
|
+
// state + AI budget get allocated the moment the first question lands,
|
|
1801
|
+
// so a 1-line "are you ready?" gate is cheap insurance. Ctrl+C here
|
|
1802
|
+
// cleanly exits via the REPL's SIGINT handler.
|
|
1803
|
+
console.log();
|
|
1804
|
+
console.log(chalk.white(' Demo: ') + chalk.gray(`${DEMO_PICK_SIZE} questions drawn from a pool of ${DEMO_POOL_SIZE}. No timer. Free practice.`));
|
|
1805
|
+
console.log(chalk.gray(' You can pause with ') + chalk.cyan('Ctrl+C') + chalk.gray(' or leave with ') + chalk.cyan('back') + chalk.gray(' at any time.'));
|
|
1806
|
+
await new Promise((resolve) => {
|
|
1807
|
+
process.stdout.write(chalk.bold.yellow(' Press Enter to begin... '));
|
|
1808
|
+
const wasRaw = process.stdin.isTTY ? process.stdin.isRaw : false;
|
|
1809
|
+
if (process.stdin.isTTY && process.stdin.setRawMode) {
|
|
1810
|
+
process.stdin.setRawMode(false);
|
|
1811
|
+
}
|
|
1812
|
+
const onData = (chunk) => {
|
|
1813
|
+
const s = chunk.toString();
|
|
1814
|
+
if (s.includes('\n') || s.includes('\r')) {
|
|
1815
|
+
process.stdin.removeListener('data', onData);
|
|
1816
|
+
if (process.stdin.isTTY && process.stdin.setRawMode) {
|
|
1817
|
+
process.stdin.setRawMode(wasRaw);
|
|
1818
|
+
}
|
|
1819
|
+
process.stdout.write('\n');
|
|
1820
|
+
resolve();
|
|
1821
|
+
}
|
|
1822
|
+
};
|
|
1823
|
+
process.stdin.on('data', onData);
|
|
1824
|
+
process.stdin.resume();
|
|
1825
|
+
});
|
|
1798
1826
|
const DEMO_QUESTIONS = pickDemoQuestions(DEMO_PICK_SIZE);
|
|
1799
1827
|
const DEMO_SESSION = getLocalizedDemoSession();
|
|
1800
1828
|
// Demo uses separate state file — doesn't conflict with real exam
|
|
@@ -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';
|
|
@@ -104,6 +105,18 @@ program
|
|
|
104
105
|
// Force hacker theme: black background + green text
|
|
105
106
|
setTerminalTheme();
|
|
106
107
|
checkForUpdates();
|
|
108
|
+
// T2-7: UTF-8 locale sanity check. Non-UTF-8 terminals mangle the box-
|
|
109
|
+
// drawing banner, the ✓/✗/⚠ glyphs used throughout the CLI, and any
|
|
110
|
+
// Cyrillic/CJK/Arabic/Devanagari/etc. translation text. Warn once at
|
|
111
|
+
// startup (not blocking) so students see a concrete fix hint instead of
|
|
112
|
+
// wondering why "哪个命令..." appears as "????..." on their machine.
|
|
113
|
+
const envLang = process.env.LANG || process.env.LC_ALL || process.env.LC_CTYPE || '';
|
|
114
|
+
if (!/UTF-?8/i.test(envLang)) {
|
|
115
|
+
console.log(chalk.yellow('⚠ Your terminal locale is not UTF-8 (LANG=' + (envLang || '(unset)') + ').'));
|
|
116
|
+
console.log(chalk.gray(' Non-English text and box characters may display as "?" or garbled glyphs.'));
|
|
117
|
+
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(')'));
|
|
118
|
+
console.log();
|
|
119
|
+
}
|
|
107
120
|
console.log(BANNER);
|
|
108
121
|
// If running interactively (no extra args or --resume), start REPL
|
|
109
122
|
if (process.argv.length <= 2 || opts.resume) {
|
|
@@ -130,6 +143,7 @@ registerEnvCommand(program);
|
|
|
130
143
|
registerAi4ctfCommand(program);
|
|
131
144
|
registerExamCommand(program);
|
|
132
145
|
registerCtf4aiDemoCommand(program);
|
|
146
|
+
registerTutorialCommand(program);
|
|
133
147
|
// Hidden command: switch AI model
|
|
134
148
|
program
|
|
135
149
|
.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('
|
|
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('
|
|
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.'));
|
|
@@ -565,7 +567,9 @@ export async function startRepl(program, resumeMode) {
|
|
|
565
567
|
// A demo is "active" if `startedAt` is within the last 30 minutes. That window
|
|
566
568
|
// covers an intentional "back to check something and come right back" case but
|
|
567
569
|
// clears anything left over from a prior session.
|
|
568
|
-
|
|
570
|
+
// T3-9: `menu` is a universal alias for `back` — more discoverable for
|
|
571
|
+
// K-12 beginners. Both drop to the Selection menu (or pause active exam).
|
|
572
|
+
if (input === 'back' || input === 'menu') {
|
|
569
573
|
const state = getExamState();
|
|
570
574
|
const isRealExam = state && state.session.examId !== 'demo-free';
|
|
571
575
|
const isActiveDemo = state && state.session.examId === 'demo-free' && (() => {
|
|
@@ -724,10 +728,19 @@ export async function startRepl(program, resumeMode) {
|
|
|
724
728
|
console.log(chalk.green(' Access granted! Token bound to this device.'));
|
|
725
729
|
}
|
|
726
730
|
else if (result === 'already_bound') {
|
|
727
|
-
console.log(
|
|
731
|
+
console.log();
|
|
732
|
+
console.log(chalk.red(' Token already activated on a different device.'));
|
|
733
|
+
console.log(chalk.gray(' Each token binds to the first device that uses it. If you lost the device,'));
|
|
734
|
+
console.log(chalk.gray(' contact your proctor to have the token re-issued for a new device.'));
|
|
728
735
|
}
|
|
729
736
|
else {
|
|
730
|
-
console.log(
|
|
737
|
+
console.log();
|
|
738
|
+
console.log(chalk.red(' Token not recognized.'));
|
|
739
|
+
console.log(chalk.gray(' Possible reasons:'));
|
|
740
|
+
console.log(chalk.white(' • ') + chalk.gray('Typo — tokens are case-insensitive, 10 chars, start with a 2-letter country code (e.g. ') + chalk.cyan('UAK7M2R9Q4') + chalk.gray(')'));
|
|
741
|
+
console.log(chalk.white(' • ') + chalk.gray('Expired — ask your proctor or organizer for a fresh token'));
|
|
742
|
+
console.log(chalk.white(' • ') + chalk.gray('Network — verify connection to ') + chalk.cyan('practice.icoa2026.au'));
|
|
743
|
+
console.log(chalk.gray(' Still stuck? type ') + chalk.cyan('help') + chalk.gray(' or try ') + chalk.cyan('exam demo') + chalk.gray(' for a free practice round.'));
|
|
731
744
|
}
|
|
732
745
|
console.log();
|
|
733
746
|
rl.prompt();
|