icoa-cli 1.0.0

package/dist/commands/hint.js

@@ -0,0 +1,107 @@
+import chalk from 'chalk';
+import { confirm } from '@inquirer/prompts';
+import { generateHint } from '../lib/gemini.js';
+import { checkBudget, deductBudget, getBudgetDisplay, isTokenCapReached } from '../lib/budget.js';
+import { getConfig } from '../lib/config.js';
+import { logHint } from '../lib/logger.js';
+import { printError, printInfo, printMarkdown, printHeader, createSpinner } from '../lib/ui.js';
+function getChallengeContext() {
+    const config = getConfig();
+    if (config.currentChallengeName && config.currentChallengeCategory) {
+        return {
+            name: config.currentChallengeName,
+            category: config.currentChallengeCategory,
+        };
+    }
+    return undefined;
+}
+async function handleHint(level, question) {
+    const config = getConfig();
+    // Check token cap
+    if (isTokenCapReached()) {
+        printError('Token cap reached. No more AI hints available.');
+        return;
+    }
+    // Check budget
+    const { allowed, remaining } = checkBudget(level);
+    if (!allowed) {
+        printError(`Level ${level} hint budget exhausted (0 remaining).`);
+        return;
+    }
+    // Level C confirmation
+    if (level === 'C') {
+        const proceed = await confirm({
+            message: `This will consume 1 of your ${remaining} remaining Critical Assists. Continue?`,
+            default: false,
+        });
+        if (!proceed) {
+            printInfo('Cancelled.');
+            return;
+        }
+    }
+    // Log BEFORE API call
+    logHint(level, question, config.currentChallengeId || undefined);
+    const context = getChallengeContext();
+    const levelNames = {
+        A: 'General Guidance',
+        B: 'Deep Analysis',
+        C: 'Critical Assist',
+    };
+    const spinner = createSpinner(`Getting Level ${level} hint (${levelNames[level]})...`);
+    spinner.start();
+    try {
+        const result = await generateHint(level, question, context);
+        spinner.stop();
+        // Deduct budget after successful response
+        deductBudget(level, result.tokensUsed);
+        printHeader(`Level ${level} Hint — ${levelNames[level]}`);
+        printMarkdown(result.text);
+        console.log();
+        console.log(chalk.gray(`  Tokens used: ${result.tokensUsed} | Level ${level} remaining: ${checkBudget(level).remaining}`));
+        console.log();
+    }
+    catch (err) {
+        spinner.fail('Hint generation failed');
+        printError(err.message);
+    }
+}
+function showBudget() {
+    printHeader('Hint Budget');
+    console.log(getBudgetDisplay());
+    console.log();
+}
+export function registerHintCommands(program) {
+    // ─── icoa hint <question> ───
+    // Special case: "icoa hint budget" shows budget instead of querying AI
+    program
+        .command('hint <question...>')
+        .description('Level A hint — General guidance (use "hint budget" to check remaining)')
+        .action(async (words) => {
+        if (words[0] === 'budget') {
+            showBudget();
+            return;
+        }
+        await handleHint('A', words.join(' '));
+    });
+    // ─── icoa hint-b <question> ───
+    program
+        .command('hint-b <question...>')
+        .description('Level B hint — Deep analysis')
+        .action(async (words) => {
+        await handleHint('B', words.join(' '));
+    });
+    // ─── icoa hint-c <question> ───
+    program
+        .command('hint-c <question...>')
+        .description('Level C hint — Critical assist (confirmation required)')
+        .action(async (words) => {
+        await handleHint('C', words.join(' '));
+    });
+    // ─── icoa hint-budget (alternative) ───
+    program
+        .command('hint-budget')
+        .description('Show remaining hint budget')
+        .action(() => {
+        showBudget();
+    });
+}

package/dist/commands/lang.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerLangCommand(program: Command): void;

package/dist/commands/lang.js

@@ -0,0 +1,42 @@
+import chalk from 'chalk';
+import { getConfig, saveConfig } from '../lib/config.js';
+import { logCommand } from '../lib/logger.js';
+import { printSuccess, printError, printInfo } from '../lib/ui.js';
+import { SUPPORTED_LANGUAGES } from '../types/index.js';
+const LANG_NAMES = {
+    en: 'English',
+    zh: '中文 (Chinese)',
+    ja: '日本語 (Japanese)',
+    ko: '한국어 (Korean)',
+    es: 'Español (Spanish)',
+};
+export function registerLangCommand(program) {
+    program
+        .command('lang [code]')
+        .description('Switch display language')
+        .action((code) => {
+        logCommand(`lang ${code || ''}`);
+        if (!code) {
+            const config = getConfig();
+            printInfo(`Current language: ${chalk.white(LANG_NAMES[config.language] || config.language)}`);
+            console.log();
+            console.log(chalk.gray('  Supported languages:'));
+            for (const lang of SUPPORTED_LANGUAGES) {
+                const current = config.language === lang ? chalk.yellow(' ← current') : '';
+                console.log(`    ${chalk.white(lang)}  ${LANG_NAMES[lang]}${current}`);
+            }
+            console.log();
+            console.log(chalk.gray('  Usage: icoa lang <code>'));
+            console.log(chalk.gray('  Example: icoa lang zh'));
+            console.log();
+            return;
+        }
+        if (!SUPPORTED_LANGUAGES.includes(code)) {
+            printError(`Unsupported language: ${code}`);
+            printInfo(`Supported: ${SUPPORTED_LANGUAGES.join(', ')}`);
+            return;
+        }
+        saveConfig({ language: code });
+        printSuccess(`Language set to: ${LANG_NAMES[code] || code}`);
+    });
+}

package/dist/commands/log.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerLogCommand(program: Command): void;

package/dist/commands/log.js

@@ -0,0 +1,36 @@
+import chalk from 'chalk';
+import { getSessionLog } from '../lib/logger.js';
+import { printHeader, printInfo, printTable } from '../lib/ui.js';
+export function registerLogCommand(program) {
+    program
+        .command('log')
+        .description('Display session history')
+        .action(() => {
+        const entries = getSessionLog();
+        if (entries.length === 0) {
+            printInfo('No session log entries yet.');
+            return;
+        }
+        printHeader('Session Log');
+        const rows = entries.map((entry) => {
+            const time = entry.timestamp.replace('T', ' ').substring(0, 19);
+            const levelColor = {
+                A: chalk.green,
+                B: chalk.yellow,
+                C: chalk.red,
+                command: chalk.blue,
+                submit: chalk.magenta,
+            };
+            const colorFn = levelColor[entry.level] || chalk.gray;
+            const input = entry.input.length > 60 ? entry.input.substring(0, 57) + '...' : entry.input;
+            return [
+                chalk.gray(time),
+                colorFn(entry.level.padEnd(7)),
+                input,
+            ];
+        });
+        printTable(['Time', 'Type', 'Content'], rows);
+        console.log(chalk.gray(`  ${entries.length} entries total`));
+        console.log();
+    });
+}

package/dist/commands/note.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerNoteCommand(program: Command): void;

package/dist/commands/note.js

@@ -0,0 +1,32 @@
+import { appendFileSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import chalk from 'chalk';
+import { printSuccess, printInfo, printHeader } from '../lib/ui.js';
+import { logCommand } from '../lib/logger.js';
+const NOTES_FILE = join(homedir(), 'icoa-notes.txt');
+export function registerNoteCommand(program) {
+    program
+        .command('note [text...]')
+        .description('Add or view personal notes')
+        .action((words) => {
+        logCommand(`note ${words?.join(' ') || ''}`);
+        if (!words || words.length === 0) {
+            // Display existing notes
+            if (!existsSync(NOTES_FILE)) {
+                printInfo('No notes yet. Add one with: icoa note "your note here"');
+                return;
+            }
+            const content = readFileSync(NOTES_FILE, 'utf-8');
+            printHeader('Notes');
+            console.log(content);
+            return;
+        }
+        // Add new note
+        const text = words.join(' ');
+        const timestamp = new Date().toISOString().replace('T', ' ').substring(0, 19);
+        const entry = `[${timestamp}] ${text}\n`;
+        appendFileSync(NOTES_FILE, entry);
+        printSuccess(`Note saved: ${chalk.gray(text)}`);
+    });
+}

package/dist/commands/ref.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerRefCommand(program: Command): void;

package/dist/commands/ref.js

@@ -0,0 +1,63 @@
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import { printHeader, printInfo, printError, printTable } from '../lib/ui.js';
+import { logCommand } from '../lib/logger.js';
+function getRefsDir() {
+    // When bundled, refs/ is at the package root alongside dist/
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    // Try multiple possible locations
+    const candidates = [
+        join(__dirname, '..', 'refs'), // from dist/index.js
+        join(__dirname, '..', '..', 'refs'), // from src/commands/
+        join(process.cwd(), 'refs'), // from CWD
+    ];
+    for (const dir of candidates) {
+        if (existsSync(dir))
+            return dir;
+    }
+    return candidates[0]; // fallback
+}
+export function registerRefCommand(program) {
+    program
+        .command('ref [topic]')
+        .description('Quick reference for tools and commands')
+        .action((topic) => {
+        logCommand(`ref ${topic || ''}`);
+        const refsDir = getRefsDir();
+        if (!topic) {
+            // List all available refs
+            printHeader('Available References');
+            if (!existsSync(refsDir)) {
+                printError('Reference files not found.');
+                return;
+            }
+            const files = readdirSync(refsDir)
+                .filter((f) => f.endsWith('.txt'))
+                .map((f) => f.replace('.txt', ''))
+                .sort();
+            if (files.length === 0) {
+                printInfo('No reference files available.');
+                return;
+            }
+            const rows = files.map((f) => [chalk.white(f)]);
+            printTable(['Topic'], rows);
+            console.log();
+            console.log(chalk.gray(`  Usage: icoa ref <topic>`));
+            console.log(chalk.gray(`  Example: icoa ref python`));
+            console.log();
+            return;
+        }
+        // Show specific ref
+        const filePath = join(refsDir, `${topic}.txt`);
+        if (!existsSync(filePath)) {
+            printError(`Reference not found: ${topic}`);
+            printInfo('Run "icoa ref" to see available topics.');
+            return;
+        }
+        const content = readFileSync(filePath, 'utf-8');
+        printHeader(`Reference: ${topic}`);
+        console.log(content);
+    });
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerSetupCommand(program: Command): void;

package/dist/commands/setup.js

@@ -0,0 +1,88 @@
+import chalk from 'chalk';
+import { input, select } from '@inquirer/prompts';
+import { getConfig } from '../lib/config.js';
+import { setApiKey } from '../lib/gemini.js';
+import { printSuccess, printError, printInfo, printHeader, printKeyValue } from '../lib/ui.js';
+import { logCommand } from '../lib/logger.js';
+export function registerSetupCommand(program) {
+    program
+        .command('setup')
+        .description('Configure ICOA CLI settings')
+        .action(async () => {
+        logCommand('setup');
+        const config = getConfig();
+        printHeader('ICOA CLI Setup');
+        console.log();
+        // Show current configuration
+        printKeyValue('CTFd URL', config.ctfdUrl || chalk.gray('Not configured'));
+        printKeyValue('CTFd Token', config.token ? chalk.green('Configured') : chalk.gray('Not configured'));
+        printKeyValue('Gemini API Key', config.geminiApiKey || process.env.GEMINI_API_KEY ? chalk.green('Configured') : chalk.gray('Not configured'));
+        printKeyValue('Language', config.language);
+        printKeyValue('Session ID', config.sessionId.substring(0, 8) + '...');
+        console.log();
+        const action = await select({
+            message: 'What would you like to configure?',
+            choices: [
+                { name: 'Gemini API Key', value: 'gemini' },
+                { name: 'CTFd Connection', value: 'ctfd' },
+                { name: 'Reset Hint Budget', value: 'budget' },
+                { name: 'View All Settings', value: 'view' },
+                { name: 'Exit', value: 'exit' },
+            ],
+        });
+        switch (action) {
+            case 'gemini': {
+                console.log();
+                printInfo('Get your API key from: https://aistudio.google.com/apikey');
+                console.log();
+                const key = await input({ message: 'Enter Gemini API Key:' });
+                if (key.trim()) {
+                    setApiKey(key.trim());
+                    printSuccess('Gemini API key saved.');
+                }
+                else {
+                    printError('No key provided.');
+                }
+                break;
+            }
+            case 'ctfd': {
+                printInfo('Use "icoa ctf join <url>" to connect to a CTFd instance.');
+                break;
+            }
+            case 'budget': {
+                const { confirm } = await import('@inquirer/prompts');
+                const proceed = await confirm({
+                    message: 'Reset hint budget to defaults (A:50, B:10, C:2)? This cannot be undone.',
+                    default: false,
+                });
+                if (proceed) {
+                    const { saveBudget } = await import('../lib/config.js');
+                    const { DEFAULT_BUDGET } = await import('../types/index.js');
+                    saveBudget({ ...DEFAULT_BUDGET });
+                    printSuccess('Hint budget reset to defaults.');
+                }
+                break;
+            }
+            case 'view': {
+                console.log();
+                printHeader('Full Configuration');
+                const full = getConfig();
+                for (const [key, value] of Object.entries(full)) {
+                    if (key === 'token' && value) {
+                        printKeyValue(key, value.toString().substring(0, 8) + '...');
+                    }
+                    else if (key === 'geminiApiKey' && value) {
+                        printKeyValue(key, value.toString().substring(0, 8) + '...');
+                    }
+                    else {
+                        printKeyValue(key, String(value ?? 'null'));
+                    }
+                }
+                console.log();
+                break;
+            }
+            case 'exit':
+                break;
+        }
+    });
+}

package/dist/commands/shell.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerShellCommand(program: Command): void;

package/dist/commands/shell.js

@@ -0,0 +1,55 @@
+import { execSync } from 'node:child_process';
+import chalk from 'chalk';
+import { printError, printInfo, printSuccess } from '../lib/ui.js';
+import { logCommand } from '../lib/logger.js';
+export function registerShellCommand(program) {
+    program
+        .command('shell')
+        .description('Open interactive shell in Docker sandbox')
+        .action(async () => {
+        logCommand('shell');
+        // Check if Docker is available
+        try {
+            execSync('docker info', { stdio: 'ignore' });
+        }
+        catch {
+            printError('Docker is not available.');
+            console.log();
+            console.log(chalk.gray('  Docker is required for the ICOA sandbox environment.'));
+            console.log(chalk.gray('  Install Docker from: https://docs.docker.com/get-docker/'));
+            console.log();
+            return;
+        }
+        const imageName = 'icoa/sandbox:2026';
+        const containerName = `icoa-sandbox-${Date.now()}`;
+        // Check if image exists
+        try {
+            execSync(`docker image inspect ${imageName}`, { stdio: 'ignore' });
+        }
+        catch {
+            printInfo(`Sandbox image not found. Pulling ${imageName}...`);
+            try {
+                execSync(`docker pull ${imageName}`, { stdio: 'inherit' });
+            }
+            catch {
+                printError(`Failed to pull ${imageName}.`);
+                printInfo('The sandbox image may not be published yet.');
+                printInfo('You can build it locally: cd docker && docker build -t icoa/sandbox:2026 .');
+                return;
+            }
+        }
+        printSuccess('Launching sandbox...');
+        console.log(chalk.gray("  Type 'exit' to return to ICOA CLI."));
+        console.log();
+        try {
+            execSync(`docker run --rm -it --name ${containerName} --network=host ${imageName} /bin/bash`, { stdio: 'inherit' });
+            console.log();
+            printSuccess('Sandbox session ended.');
+        }
+        catch {
+            // User likely just exited
+            console.log();
+            printInfo('Sandbox session ended.');
+        }
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { registerCtfCommands } from './commands/ctf.js';
+import { registerHintCommands } from './commands/hint.js';
+import { registerRefCommand } from './commands/ref.js';
+import { registerShellCommand } from './commands/shell.js';
+import { registerFilesCommand } from './commands/files.js';
+import { registerConnectCommand } from './commands/connect.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 { isConnected, getConfig } from './lib/config.js';
+const BANNER = `
+${chalk.cyan('╔══════════════════════════════════════════════════════════╗')}
+${chalk.cyan('║')}                                                          ${chalk.cyan('║')}
+${chalk.cyan('║')}   ${chalk.bold.white('██╗ ██████╗ ██████╗  █████╗')}                           ${chalk.cyan('║')}
+${chalk.cyan('║')}   ${chalk.bold.white('██║██╔════╝██╔═══██╗██╔══██╗')}                          ${chalk.cyan('║')}
+${chalk.cyan('║')}   ${chalk.bold.white('██║██║     ██║   ██║███████║')}                          ${chalk.cyan('║')}
+${chalk.cyan('║')}   ${chalk.bold.white('██║██║     ██║   ██║██╔══██║')}                          ${chalk.cyan('║')}
+${chalk.cyan('║')}   ${chalk.bold.white('██║╚██████╗╚██████╔╝██║  ██║')}                          ${chalk.cyan('║')}
+${chalk.cyan('║')}   ${chalk.bold.white('╚═╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═╝')}                         ${chalk.cyan('║')}
+${chalk.cyan('║')}                                                          ${chalk.cyan('║')}
+${chalk.cyan('║')}   ${chalk.yellow('International Cybersecurity Olympiad 2026')}               ${chalk.cyan('║')}
+${chalk.cyan('║')}   ${chalk.gray('CLI-Native CTF Competition Terminal  v1.0.0')}              ${chalk.cyan('║')}
+${chalk.cyan('║')}                                                          ${chalk.cyan('║')}
+${chalk.cyan('╚══════════════════════════════════════════════════════════╝')}
+`;
+// Global error handlers
+process.on('uncaughtException', (err) => {
+    console.error(chalk.red('Error:'), err.message);
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    const msg = reason instanceof Error ? reason.message : String(reason);
+    console.error(chalk.red('Error:'), msg);
+    process.exit(1);
+});
+const program = new Command();
+program
+    .name('icoa')
+    .version('1.0.0')
+    .description('ICOA CLI — CLI-Native CTF Competition Terminal')
+    .action(() => {
+    console.log(BANNER);
+    // Show quick status
+    if (isConnected()) {
+        const config = getConfig();
+        console.log(chalk.gray('  Connected to: ') + chalk.white(config.ctfdUrl));
+        console.log(chalk.gray('  User: ') + chalk.white(config.userName));
+        console.log();
+    }
+    else {
+        console.log(chalk.gray('  Not connected. Start with: ') + chalk.white('icoa ctf join <url>'));
+        console.log();
+    }
+    console.log(chalk.gray('  Quick start:'));
+    console.log(chalk.white('    icoa ctf join <url>     ') + chalk.gray('Connect to competition'));
+    console.log(chalk.white('    icoa ctf challenges     ') + chalk.gray('View challenges'));
+    console.log(chalk.white('    icoa hint <question>    ') + chalk.gray('Get AI hint'));
+    console.log(chalk.white('    icoa ref <topic>        ') + chalk.gray('Quick reference'));
+    console.log(chalk.white('    icoa shell              ') + chalk.gray('Open sandbox'));
+    console.log(chalk.white('    icoa setup              ') + chalk.gray('Configure settings'));
+    console.log(chalk.white('    icoa --help             ') + chalk.gray('All commands'));
+    console.log();
+});
+registerCtfCommands(program);
+registerHintCommands(program);
+registerRefCommand(program);
+registerShellCommand(program);
+registerFilesCommand(program);
+registerConnectCommand(program);
+registerNoteCommand(program);
+registerLogCommand(program);
+registerLangCommand(program);
+registerSetupCommand(program);
+program.parse();

package/dist/lib/budget.d.ts

@@ -0,0 +1,8 @@
+import type { HintLevel } from '../types/index.js';
+export declare function checkBudget(level: HintLevel): {
+    allowed: boolean;
+    remaining: number;
+};
+export declare function deductBudget(level: HintLevel, tokensUsed: number): void;
+export declare function getBudgetDisplay(): string;
+export declare function isTokenCapReached(): boolean;

package/dist/lib/budget.js

@@ -0,0 +1,29 @@
+import { getBudget, saveBudget } from './config.js';
+export function checkBudget(level) {
+    const budget = getBudget();
+    const key = level.toLowerCase();
+    return {
+        allowed: budget[key] > 0,
+        remaining: budget[key],
+    };
+}
+export function deductBudget(level, tokensUsed) {
+    const budget = getBudget();
+    const key = level.toLowerCase();
+    budget[key] = Math.max(0, budget[key] - 1);
+    budget.tokensUsed += tokensUsed;
+    saveBudget(budget);
+}
+export function getBudgetDisplay() {
+    const budget = getBudget();
+    return [
+        `  Level A (General Guidance):  ${budget.a}/50`,
+        `  Level B (Deep Analysis):     ${budget.b}/10`,
+        `  Level C (Critical Assist):   ${budget.c}/2`,
+        `  Token Usage:                 ${budget.tokensUsed.toLocaleString()}/${budget.tokenCap.toLocaleString()}`,
+    ].join('\n');
+}
+export function isTokenCapReached() {
+    const budget = getBudget();
+    return budget.tokensUsed >= budget.tokenCap;
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,7 @@
+import type { IcoaConfig, HintBudget } from '../types/index.js';
+export declare function getConfig(): IcoaConfig;
+export declare function saveConfig(config: Partial<IcoaConfig>): void;
+export declare function getBudget(): HintBudget;
+export declare function saveBudget(budget: HintBudget): void;
+export declare function getIcoaDir(): string;
+export declare function isConnected(): boolean;

package/dist/lib/config.js

@@ -0,0 +1,60 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { DEFAULT_CONFIG, DEFAULT_BUDGET } from '../types/index.js';
+const ICOA_DIR = join(homedir(), '.icoa');
+const CONFIG_FILE = join(ICOA_DIR, 'config.json');
+const BUDGET_FILE = join(ICOA_DIR, 'budget.json');
+function ensureDir() {
+    if (!existsSync(ICOA_DIR)) {
+        mkdirSync(ICOA_DIR, { recursive: true });
+    }
+}
+export function getConfig() {
+    ensureDir();
+    if (!existsSync(CONFIG_FILE)) {
+        const config = { ...DEFAULT_CONFIG, sessionId: randomUUID() };
+        writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+        return config;
+    }
+    try {
+        const raw = readFileSync(CONFIG_FILE, 'utf-8');
+        return { ...DEFAULT_CONFIG, ...JSON.parse(raw) };
+    }
+    catch {
+        return { ...DEFAULT_CONFIG, sessionId: randomUUID() };
+    }
+}
+export function saveConfig(config) {
+    ensureDir();
+    const current = getConfig();
+    const merged = { ...current, ...config };
+    writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2));
+}
+export function getBudget() {
+    ensureDir();
+    if (!existsSync(BUDGET_FILE)) {
+        writeFileSync(BUDGET_FILE, JSON.stringify(DEFAULT_BUDGET, null, 2));
+        return { ...DEFAULT_BUDGET };
+    }
+    try {
+        const raw = readFileSync(BUDGET_FILE, 'utf-8');
+        return { ...DEFAULT_BUDGET, ...JSON.parse(raw) };
+    }
+    catch {
+        return { ...DEFAULT_BUDGET };
+    }
+}
+export function saveBudget(budget) {
+    ensureDir();
+    writeFileSync(BUDGET_FILE, JSON.stringify(budget, null, 2));
+}
+export function getIcoaDir() {
+    ensureDir();
+    return ICOA_DIR;
+}
+export function isConnected() {
+    const config = getConfig();
+    return !!(config.ctfdUrl && config.token);
+}

package/dist/lib/ctfd-client.d.ts

@@ -0,0 +1,22 @@
+import type { CTFdChallenge, CTFdChallengeListItem, CTFdUser, CTFdTeam, CTFdScoreboardEntry, CTFdAttemptResponse } from '../types/index.js';
+export declare class CTFdClient {
+    private baseUrl;
+    private token;
+    constructor(baseUrl: string, token: string);
+    private request;
+    testConnection(): Promise<CTFdUser>;
+    getChallenges(): Promise<CTFdChallengeListItem[]>;
+    getChallenge(id: number): Promise<CTFdChallenge>;
+    submitFlag(challengeId: number, submission: string): Promise<CTFdAttemptResponse['data']>;
+    getScoreboard(): Promise<CTFdScoreboardEntry[]>;
+    getTeam(): Promise<CTFdTeam>;
+    getCompetitionMeta(): Promise<{
+        start: number | null;
+        end: number | null;
+        userMode: string;
+        csrfNonce: string;
+    }>;
+    getChallengeFiles(id: number): Promise<string[]>;
+    downloadFile(filePath: string, destDir: string): Promise<string>;
+    loginWithCredentials(username: string, password: string): Promise<string>;
+}