icoa-cli 2.19.356 → 2.19.357

package/dist/lib/paper-upgrade.js

@@ -1 +1,119 @@
-import chalk from"chalk";import{isNativeWindowsCmd as o,isInWSL as e,hasPython as l}from"./platform.js";export function showCToBUpgradePrompt(n,t){if(!function(o){return!!o&&/-2026-c$/i.test(o.trim())}(n))return;if(!t)return;const s=o(),a=e(),r=l();console.log(chalk.cyan("  ─────────────────────────────────────────────")),console.log(),console.log(chalk.bold.white("  ★ Ready for more? Paper B — K-12 with AI")),console.log(),console.log(chalk.gray("  Paper B adds ")+chalk.white("AI4CTF")+chalk.gray(" (chat with AI to find hidden flags) and ")+chalk.white("CTF4AI")+chalk.gray(" (break AI security).")),console.log(chalk.gray("  150 points total · 90 minutes · same command interface you already know.")),console.log(),s?(console.log(chalk.bold.white("  To take Paper B on Windows, install WSL2 + Ubuntu 22:")),console.log(),console.log(chalk.white("    1. Open PowerShell as Administrator")),console.log(chalk.gray('       (right-click PowerShell → "Run as administrator")')),console.log(chalk.white("    2. Run: ")+chalk.cyan("wsl --install -d Ubuntu-22.04")),console.log(chalk.white("    3. Reboot when prompted, create a Linux username + password")),console.log(chalk.white("    4. Inside Ubuntu, install Node.js 22 and this CLI:")),console.log(chalk.gray("         ")+chalk.cyan("curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -")),console.log(chalk.gray("         ")+chalk.cyan("sudo apt install -y nodejs")),console.log(chalk.gray("         ")+chalk.cyan("sudo npm install -g icoa-cli")),console.log(),console.log(chalk.gray("  Setup takes 30-60 min the first time. You only do this once."))):a?(console.log(chalk.bold.white("  You are on WSL2 — your setup is almost ready:")),console.log(),r?(console.log(chalk.green("    ✓ Python 3 already installed. You are ready.")),console.log()):(console.log(chalk.white("    Install Python 3 (for Paper B practical questions):")),console.log(chalk.gray("      ")+chalk.cyan("sudo apt install -y python3 python3-pip")),console.log())):"darwin"===process.platform?(console.log(chalk.bold.white("  On macOS, install Python 3 for Paper B practicals:")),console.log(),console.log(chalk.white("    With Homebrew:")),console.log(chalk.gray("      ")+chalk.cyan("brew install python@3.12")),console.log(),console.log(chalk.white("    Without Homebrew: download from ")+chalk.cyan.underline("https://python.org")),r&&(console.log(),console.log(chalk.green("    ✓ Python 3 already detected. You are ready."))),console.log()):(console.log(chalk.bold.white("  On Linux, install Python 3 for Paper B practicals:")),console.log(),console.log(chalk.white("    Ubuntu / Debian:")),console.log(chalk.gray("      ")+chalk.cyan("sudo apt install -y python3 python3-pip")),console.log(chalk.white("    Fedora / RHEL:")),console.log(chalk.gray("      ")+chalk.cyan("sudo dnf install -y python3 python3-pip")),r&&(console.log(),console.log(chalk.green("    ✓ Python 3 already detected. You are ready."))),console.log()),console.log(chalk.bold.white("  Then get a Paper B token from your organizer.")),console.log(chalk.gray("  Each token is one-shot and bound to one device.")),console.log(),console.log(chalk.gray("  Detailed step-by-step guide: ")+chalk.cyan.underline("https://icoa2026.au/selectionguide/")),console.log()}
+/**
+ * Paper C → Paper B upgrade prompt.
+ *
+ * Shown after a successful Paper C submission. Paper C is the K-12 entry
+ * funnel (MCQ only, no tools). Paper B is the next step — adds AI4CTF
+ * and CTF4AI practical challenges for 150-point total. The upgrade path
+ * depends on which platform the student is on.
+ *
+ * Policy:
+ * - Only triggered after Paper C submission (examId ends in `-c` or
+ *   starts with a country code + `-2026-c`).
+ * - Only triggered if student passed. Students who failed C should
+ *   retry C before being pushed toward a harder paper.
+ * - Always points at https://icoa2026.au/selectionguide/ for detailed
+ *   platform-specific install instructions, so the CLI copy stays
+ *   concise and the canonical guide lives in one place.
+ * - Never prescribes a token — students must request one from their
+ *   organizer. This prevents the CLI from implying self-service token
+ *   issuance.
+ */
+import chalk from 'chalk';
+import { isNativeWindowsCmd, isInWSL, hasPython } from './platform.js';
+/**
+ * True when the just-submitted exam is a C paper (MCQ entry funnel).
+ * Matches `ua-2026-c`, `pe-2026-c`, `cn-2026-c`, etc. Case-insensitive.
+ */
+function isCPaper(examId) {
+    if (!examId)
+        return false;
+    return /-2026-c$/i.test(examId.trim());
+}
+/**
+ * Renders the C→B upgrade prompt to stdout. No-op if conditions aren't met.
+ *
+ * @param examId   The submitted exam ID (from state.session.examId before clear)
+ * @param passed   Whether the student met the passing bar
+ */
+export function showCToBUpgradePrompt(examId, passed) {
+    if (!isCPaper(examId))
+        return;
+    if (!passed)
+        return;
+    const onCmd = isNativeWindowsCmd();
+    const onWSL = isInWSL();
+    const pyReady = hasPython();
+    console.log(chalk.cyan('  ─────────────────────────────────────────────'));
+    console.log();
+    console.log(chalk.bold.white('  ★ Ready for more? Paper B — K-12 with AI'));
+    console.log();
+    console.log(chalk.gray('  Paper B adds ') +
+        chalk.white('AI4CTF') +
+        chalk.gray(' (chat with AI to find hidden flags) and ') +
+        chalk.white('CTF4AI') +
+        chalk.gray(' (break AI security).'));
+    console.log(chalk.gray('  150 points total · 90 minutes · same command interface you already know.'));
+    console.log();
+    if (onCmd) {
+        // Windows cmd / PowerShell — needs WSL2 path for full Paper B
+        console.log(chalk.bold.white('  To take Paper B on Windows, install WSL2 + Ubuntu 22:'));
+        console.log();
+        console.log(chalk.white('    1. Open PowerShell as Administrator'));
+        console.log(chalk.gray('       (right-click PowerShell → "Run as administrator")'));
+        console.log(chalk.white('    2. Run: ') + chalk.cyan('wsl --install -d Ubuntu-22.04'));
+        console.log(chalk.white('    3. Reboot when prompted, create a Linux username + password'));
+        console.log(chalk.white('    4. Inside Ubuntu, install Node.js 22 and this CLI:'));
+        console.log(chalk.gray('         ') + chalk.cyan('curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -'));
+        console.log(chalk.gray('         ') + chalk.cyan('sudo apt install -y nodejs'));
+        console.log(chalk.gray('         ') + chalk.cyan('sudo npm install -g icoa-cli'));
+        console.log();
+        console.log(chalk.gray('  Setup takes 30-60 min the first time. You only do this once.'));
+    }
+    else if (onWSL) {
+        // Already on WSL2 — just need Python for practicals
+        console.log(chalk.bold.white('  You are on WSL2 — your setup is almost ready:'));
+        console.log();
+        if (!pyReady) {
+            console.log(chalk.white('    Install Python 3 (for Paper B practical questions):'));
+            console.log(chalk.gray('      ') + chalk.cyan('sudo apt install -y python3 python3-pip'));
+            console.log();
+        }
+        else {
+            console.log(chalk.green('    ✓ Python 3 already installed. You are ready.'));
+            console.log();
+        }
+    }
+    else if (process.platform === 'darwin') {
+        // macOS
+        console.log(chalk.bold.white('  On macOS, install Python 3 for Paper B practicals:'));
+        console.log();
+        console.log(chalk.white('    With Homebrew:'));
+        console.log(chalk.gray('      ') + chalk.cyan('brew install python@3.12'));
+        console.log();
+        console.log(chalk.white('    Without Homebrew: download from ') + chalk.cyan.underline('https://python.org'));
+        if (pyReady) {
+            console.log();
+            console.log(chalk.green('    ✓ Python 3 already detected. You are ready.'));
+        }
+        console.log();
+    }
+    else {
+        // Linux native (not WSL)
+        console.log(chalk.bold.white('  On Linux, install Python 3 for Paper B practicals:'));
+        console.log();
+        console.log(chalk.white('    Ubuntu / Debian:'));
+        console.log(chalk.gray('      ') + chalk.cyan('sudo apt install -y python3 python3-pip'));
+        console.log(chalk.white('    Fedora / RHEL:'));
+        console.log(chalk.gray('      ') + chalk.cyan('sudo dnf install -y python3 python3-pip'));
+        if (pyReady) {
+            console.log();
+            console.log(chalk.green('    ✓ Python 3 already detected. You are ready.'));
+        }
+        console.log();
+    }
+    console.log(chalk.bold.white('  Then get a Paper B token from your organizer.'));
+    console.log(chalk.gray('  Each token is one-shot and bound to one device.'));
+    console.log();
+    console.log(chalk.gray('  Detailed step-by-step guide: ') + chalk.cyan.underline('https://icoa2026.au/selectionguide/'));
+    console.log();
+}

package/dist/lib/platform.js

@@ -1 +1,99 @@
-import{execFileSync as o}from"node:child_process";import{lstatSync as t,realpathSync as n,readFileSync as r}from"node:fs";import{dirname as e}from"node:path";export function isInWSL(){return!(!process.env.WSL_DISTRO_NAME&&!process.env.WSLENV)}export function isNativeWindowsCmd(){return"win32"===process.platform&&!isInWSL()}export function hasPython(){const t=[["python3",["--version"]],["python",["--version"]],["py",["-3","--version"]]];for(const[n,r]of t)try{return o(n,r,{encoding:"utf-8",timeout:1500,stdio:["ignore","pipe","ignore"]}),!0}catch{}return!1}export function detectIcoaInstalls(){if(isNativeWindowsCmd())return[];let i=[];try{i=o("which",["-a","icoa"],{encoding:"utf-8",timeout:1500,stdio:["ignore","pipe","ignore"]}).trim().split("\n").filter(Boolean)}catch{return[]}return i.map(o=>{const i={path:o};try{let s=o;t(o).isSymbolicLink()&&(s=n(o));const c=e(s),p=e(c);i.pkgDir=p;const a=JSON.parse(r(`${p}/package.json`,"utf-8"));i.version=a.version}catch{}return i})}
+/**
+ * Platform detection primitives — 3 exported probes:
+ *   isInWSL()            — running inside a WSL distribution
+ *   isNativeWindowsCmd() — cmd.exe or PowerShell, NOT WSL
+ *   hasPython()          — any python3 / python / py binary reachable
+ *
+ * Callers (repl.ts menu, exam.ts setup gate, exam.ts peek logic) inline
+ * the policy decisions — e.g. `!isNativeWindowsCmd()` for "show exam setup"
+ * and `isNativeWindowsCmd()` for "recommend C paper". This file stays as a
+ * thin detection layer; policy lives with its caller.
+ *
+ * Context: Windows middle-school students (12-14 y/o) are an expected cohort
+ * for ICOA 2026. Observed in-field: students blocked by WSL install complexity.
+ * Windows native cmd + Node.js handles MCQ + AI chat but not Q31-36 practical
+ * (Unix grep / strings / pwntools). Decision (v2.19.97 + v2.19.110): C paper
+ * is the cmd / setup-less entry funnel. See the peek-based gate in exam.ts.
+ */
+import { execFileSync } from 'node:child_process';
+import { lstatSync, realpathSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Heuristic: true when running inside a WSL distribution. Node.js reports
+ * `process.platform === 'linux'` in that case, but WSL sets specific env vars.
+ */
+export function isInWSL() {
+    return !!(process.env.WSL_DISTRO_NAME || process.env.WSLENV);
+}
+/**
+ * True when the user is on Windows native (cmd.exe or PowerShell), NOT a
+ * WSL distribution.
+ */
+export function isNativeWindowsCmd() {
+    return process.platform === 'win32' && !isInWSL();
+}
+/**
+ * Probe whether any Python 3 binary is reachable. Silent — no stderr leaks
+ * to the user. Used to decide whether Q31-35 practical questions are even
+ * theoretically doable on this machine.
+ *
+ * Uses execFileSync (no shell) so probe failures don't leak cmd.exe's
+ * "not recognized as internal or external command" messages to stdout.
+ */
+export function hasPython() {
+    const probes = [
+        ['python3', ['--version']],
+        ['python', ['--version']],
+        ['py', ['-3', '--version']],
+    ];
+    for (const [bin, args] of probes) {
+        try {
+            execFileSync(bin, args, {
+                encoding: 'utf-8',
+                timeout: 1500,
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+            return true;
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return false;
+}
+export function detectIcoaInstalls() {
+    if (isNativeWindowsCmd())
+        return []; // `which -a` not on Windows native
+    let paths = [];
+    try {
+        const out = execFileSync('which', ['-a', 'icoa'], {
+            encoding: 'utf-8',
+            timeout: 1500,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        paths = out.split('\n').filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+    return paths.map((p) => {
+        const out = { path: p };
+        try {
+            let target = p;
+            if (lstatSync(p).isSymbolicLink())
+                target = realpathSync(p);
+            // target is .../node_modules/icoa-cli/dist/index.js
+            // pkgDir is .../node_modules/icoa-cli
+            // package.json is .../node_modules/icoa-cli/package.json
+            const distDir = dirname(target); // .../icoa-cli/dist
+            const pkgDir = dirname(distDir); // .../icoa-cli
+            out.pkgDir = pkgDir;
+            const pkg = JSON.parse(readFileSync(`${pkgDir}/package.json`, 'utf-8'));
+            out.version = pkg.version;
+        }
+        catch {
+            /* fall through with version undefined */
+        }
+        return out;
+    });
+}

package/dist/lib/render-card.js

@@ -1 +1,112 @@
-import chalk from"chalk";export function detectCaps(){const t=process.stdout.columns||80,o=process.env.LANG||process.env.LC_ALL||"",n=/utf-?8/i.test(o)||""===o||"C.UTF-8"===o;return"ascii"!==(process.env.ICOA_RENDER||"").toLowerCase()&&"C"!==o&&"POSIX"!==o&&n?{tier:"T1",cols:t,utf8:n}:{tier:"T0",cols:t,utf8:!1}}function t(t,o){return"T0"===o.tier&&t.art_t0||t.width_cols&&t.width_cols>o.cols-6&&t.art_t0?t.art_t0:t.art??t.art_t0??""}function o(t){try{const o=t.split(".").reduce((t,o)=>t[o],chalk);return"function"==typeof o?o:chalk.gray}catch{return chalk.gray}}function n(t,n){let c="";for(const e of t){const t=" "===e?void 0:n[e];c+=t?o(t)(e):chalk.gray(e)}return c}export function renderCharts(o,c,e=detectCaps(),r={}){if(!o||0===o.length)return;if(!c)return;const s=!1!==r.frameLeft,i=s?chalk.cyan("  │ "):"  ",l=s?chalk.cyan("  │"):"";let f=0;for(const r of o){const o=c[r];if(!o)continue;if("code"===o.type){const t=o.code??"";if(""===t.trim())continue;console.log(l);for(const o of t.split("\n"))console.log(i+chalk.cyan(o));f++;continue}const s=t(o,e);if(""===s)continue;const a=chalk.level>0&&o.color_map&&Object.keys(o.color_map).length>0;console.log(l);for(const t of s.split("\n"))console.log(i+(a?n(t,o.color_map):chalk.gray(t)));f++}f>0&&console.log(l)}
+/**
+ * Chart rendering helper — pulls ASCII chart art out of a Curriculum.charts
+ * lookup and prints it between a card's title and body.
+ *
+ * Design contract: [[reference-chart-lang-neutral]]
+ *   - Fixed slot order:   title  →  charts  →  body
+ *   - Charts are English-only and never translated; 22 languages share one art.
+ *   - Card stores `chart_ids: string[]`; art lives in `curriculum.charts[id]`.
+ *
+ * Capability picker (pilot scope = T0 / T1):
+ *   - T0   pure-ASCII fallback   — picked when LANG=C / non-UTF-8 / chart wider than
+ *                                  available columns / explicit user opt-out
+ *   - T1   Unicode-safe default  — used on the 4 baseline terminals (macOS Terminal,
+ *                                  gnome-terminal, WSL2 Windows Terminal, Chromebook
+ *                                  Crostini); see CLAUDE.md cross-platform baseline.
+ *
+ * Output respects the learn-render frame style: each line gets a `│   ` left
+ * border so charts visually sit inside the same three-sided frame as body text.
+ */
+import chalk from 'chalk';
+export function detectCaps() {
+    const cols = process.stdout.columns || 80;
+    const lang = process.env.LANG || process.env.LC_ALL || '';
+    const utf8 = /utf-?8/i.test(lang) || lang === '' || lang === 'C.UTF-8';
+    // ICOA_RENDER=ascii forces T0 (also documented in [[reference-rendering-tiers]]).
+    const override = (process.env.ICOA_RENDER || '').toLowerCase();
+    if (override === 'ascii' || lang === 'C' || lang === 'POSIX' || !utf8) {
+        return { tier: 'T0', cols, utf8: false };
+    }
+    return { tier: 'T1', cols, utf8 };
+}
+function pickArt(chart, caps) {
+    // Width fit: if T1 art is wider than the terminal, fall back to T0 — same
+    // idea as the spike-rich-display fallback.
+    if (caps.tier === 'T0' && chart.art_t0)
+        return chart.art_t0;
+    if (chart.width_cols && chart.width_cols > caps.cols - 6 && chart.art_t0) {
+        return chart.art_t0;
+    }
+    return chart.art ?? chart.art_t0 ?? '';
+}
+// Resolve a (possibly dotted, e.g. "bold.green") chalk colour spec into a
+// styling function. Falls back to gray for unknown specs.
+function chalkChain(spec) {
+    try {
+        const fn = spec.split('.').reduce((acc, part) => acc[part], chalk);
+        return typeof fn === 'function' ? fn : chalk.gray;
+    }
+    catch {
+        return chalk.gray;
+    }
+}
+// Apply a char→colour map to one art line. Unmapped chars (and spaces) stay
+// gray — matches the pre-color_map look. ANSI escapes are zero-width so this
+// never disturbs alignment. Caller gates on chalk.level > 0.
+function colorizeArtLine(line, colorMap) {
+    let out = '';
+    for (const ch of line) {
+        const spec = ch === ' ' ? undefined : colorMap[ch];
+        out += spec ? chalkChain(spec)(ch) : chalk.gray(ch);
+    }
+    return out;
+}
+/**
+ * Render chart art for a list of chart_ids. Each chart prints on its own
+ * "block" with a blank separator line above. Lines are left-padded with the
+ * three-sided-frame left bar to match learn-render body style.
+ *
+ * Pass `frameLeft = false` for standalone (non-card-frame) contexts.
+ */
+export function renderCharts(chartIds, charts, caps = detectCaps(), opts = {}) {
+    if (!chartIds || chartIds.length === 0)
+        return;
+    if (!charts)
+        return;
+    const frameLeft = opts.frameLeft !== false;
+    const leftBar = frameLeft ? chalk.cyan('  │ ') : '  ';
+    const leftBarEmpty = frameLeft ? chalk.cyan('  │') : '';
+    let rendered = 0;
+    for (const id of chartIds) {
+        const chart = charts[id];
+        if (!chart)
+            continue; // silent miss — server denormalisation may have lagged
+        // Code-as-insight (6th genre): monospace CODE-LOCK render — cyan, no wrap,
+        // no width-fit (≤~20 ASCII lines, English comments → renders everywhere).
+        if (chart.type === 'code') {
+            const code = chart.code ?? '';
+            if (code.trim() === '')
+                continue;
+            console.log(leftBarEmpty);
+            for (const line of code.split('\n')) {
+                console.log(leftBar + chalk.cyan(line));
+            }
+            rendered++;
+            continue;
+        }
+        // Chart genres: pick T0/T1 art, then optionally apply color_map (render
+        // layer only, after selection — escapes stay zero-width). Mono terminals
+        // (chalk.level === 0, e.g. NO_COLOR / piped) skip colour automatically.
+        const art = pickArt(chart, caps);
+        if (art === '')
+            continue;
+        const useColor = chalk.level > 0 && chart.color_map && Object.keys(chart.color_map).length > 0;
+        console.log(leftBarEmpty); // blank line above each chart
+        for (const line of art.split('\n')) {
+            console.log(leftBar + (useColor ? colorizeArtLine(line, chart.color_map) : chalk.gray(line)));
+        }
+        rendered++;
+    }
+    if (rendered > 0)
+        console.log(leftBarEmpty); // single trailing blank
+}

package/dist/lib/repl-asker.js

@@ -1 +1,67 @@
-import{Interface as e,createInterface as o}from"node:readline";import{getMainRl as n}from"./main-rl.js";export function makeReplAsker(){const r=n(),s=null!==r,t=s?r.listeners("line").slice():[];s&&r.removeAllListeners("line");const l=s?r:o({input:process.stdin,output:process.stdout}),i=s?l.prompt:null;return s&&(l.prompt=e.prototype.prompt),{ask:e=>new Promise(o=>{const n=e=>{l.removeListener("close",r),o(e)},r=()=>{l.removeListener("line",n),o(null)};l.once("line",n),l.once("close",r),l.setPrompt(e),l.prompt()}),close:()=>{if(s){i&&(r.prompt=i),r.removeAllListeners("line");for(const e of t)r.on("line",e)}else l.close()}}}
+/**
+ * BUG-008-safe `question()`-style asker for standalone Commander sub-flows that
+ * are ALSO dispatched bare from inside the main REPL (e.g. `arena`, `eai`).
+ *
+ * The problem: the main REPL holds a `terminal: true` readline.Interface on
+ * process.stdin. A sub-flow that creates its OWN `createInterface` makes a SECOND
+ * interface read stdin — both echo every keystroke ("a" → "aa") and both fire
+ * 'line'. `pause()` does NOT help (the new rl's constructor calls resume()).
+ *
+ * The fix (listener-swap, per CLAUDE.md BUG-008): when a main REPL rl exists,
+ * REUSE it — detach its 'line' listeners, drive it ourselves question-by-question
+ * with one-shot listeners, then restore the saved listeners on close. No second
+ * readline is ever created inside the REPL. When there is no main rl (the flow
+ * was launched as `icoa <cmd>` from the system shell), create a standalone one.
+ *
+ * The asker resolves to `null` when the stream closes (EOF / Ctrl-D) so callers
+ * can exit cleanly instead of crashing on "readline was closed".
+ */
+import { Interface as ReadlineInterface, createInterface } from 'node:readline';
+import { getMainRl } from './main-rl.js';
+export function makeReplAsker() {
+    const mainRl = getMainRl();
+    const usingMainRl = mainRl !== null;
+    const savedMainListeners = usingMainRl
+        ? mainRl.listeners('line').slice()
+        : [];
+    if (usingMainRl)
+        mainRl.removeAllListeners('line');
+    const rl = usingMainRl
+        ? mainRl
+        : createInterface({ input: process.stdin, output: process.stdout });
+    // The main REPL monkey-patches rl.prompt() (src/repl.ts) to force
+    // computePrompt() for any mode it doesn't recognize — which would clobber our
+    // sub-flow prompt, showing e.g. `icoa 2026>` instead of `icoa ctf4eai>`. Swap
+    // in the NATIVE readline prompt for the session so our setPrompt() sticks, and
+    // restore the patched one on close() so the REPL prompt behaves again after.
+    const savedPrompt = usingMainRl ? rl.prompt : null;
+    if (usingMainRl)
+        rl.prompt = ReadlineInterface.prototype.prompt;
+    const ask = (q) => new Promise((resolve) => {
+        const onLine = (line) => {
+            rl.removeListener('close', onClose);
+            resolve(line);
+        };
+        const onClose = () => {
+            rl.removeListener('line', onLine);
+            resolve(null);
+        };
+        rl.once('line', onLine);
+        rl.once('close', onClose);
+        rl.setPrompt(q);
+        rl.prompt();
+    });
+    const close = () => {
+        if (usingMainRl) {
+            if (savedPrompt)
+                mainRl.prompt = savedPrompt;
+            mainRl.removeAllListeners('line');
+            for (const l of savedMainListeners)
+                mainRl.on('line', l);
+        }
+        else {
+            rl.close();
+        }
+    };
+    return { ask, close };
+}

package/dist/lib/sample-runner.js

@@ -1 +1,227 @@
-import{chmodSync as e,existsSync as n,mkdirSync as t,readFileSync as s,writeFileSync as r}from"node:fs";import{homedir as a}from"node:os";import{join as i}from"node:path";const o=i(a(),".icoa","bin");export const RUNNER_PY=i(o,"icoa-judge.py");const p=i(o,"icoa-judge");function l(e){try{return(s(e,"utf-8").split("\n",2)[1]||"").includes("ICOA-RUNNER v1")}catch{return!1}}export function placeSampleRunner(){try{if(n(RUNNER_PY)&&l(RUNNER_PY))return{ok:!0,path:RUNNER_PY,updated:!1};if(t(o,{recursive:!0}),r(RUNNER_PY,'#!/usr/bin/env python3\n# ICOA-RUNNER v1\n"""icoa-judge — tiny local sample-test runner for the ioipy Python informatics track.\n\nRuns YOUR Python solution against sample input/expected-output pairs, compares stdout,\nand reports PASS / WRONG / TLE / RUNTIME-ERROR plus the wall-clock time of each run.\n\nThis is a self-check on the SAMPLE cases only — a rough "is it correct and fast enough?"\nfeel. It is NOT the real judge (no hidden tests, no authoritative time/memory limit).\n\nUSAGE\n  icoa-judge SOLUTION.py [SAMPLES]\n    SAMPLES can be:\n      - a directory holding  1.in/1.out, 2.in/2.out, ...  (also accepts .ans/.expected/.exp)\n      - a single  case.in  (its expected output is the sibling  case.out)\n      - two files:  case.in  case.out\n      - omitted: auto-search ./samples, ./tests, a samples/ next to SOLUTION.py, or *.in here\n\nOPTIONS\n  --tl SECONDS   per-case soft time limit (default 5.0 — Python-friendly; a TLE here is a\n                 hint, not a verdict; the real limit is the contest\'s)\n  --py CMD       interpreter for your solution (default: python3; try  --py pypy3  for speed)\n  --raw          exact byte compare (default: whitespace-normalized — trailing spaces and\n                 trailing blank lines are ignored, the usual contest checker behaviour)\n"""\nimport argparse, glob, os, subprocess, sys, time\n\nOUT_EXTS = (".out", ".ans", ".expected", ".exp")\nC = sys.stdout.isatty()\ndef col(s, c): return f"\\033[{c}m{s}\\033[0m" if C else s\ndef green(s): return col(s, "32")\ndef red(s): return col(s, "31")\ndef yellow(s): return col(s, "33")\ndef gray(s): return col(s, "90")\n\ndef find_expected(in_path):\n    stem = in_path[:-3] if in_path.endswith(".in") else os.path.splitext(in_path)[0]\n    for ext in OUT_EXTS:\n        if os.path.exists(stem + ext):\n            return stem + ext\n    return None\n\ndef collect_cases(args):\n    sols_dir = os.path.dirname(os.path.abspath(args.solution)) or "."\n    # explicit: two files (in + out)\n    if args.samples and args.expected:\n        return [(args.samples, args.expected)]\n    # explicit: a single .in file\n    if args.samples and os.path.isfile(args.samples) and args.samples.endswith(".in"):\n        exp = find_expected(args.samples)\n        return [(args.samples, exp)] if exp else []\n    # explicit: a directory\n    if args.samples and os.path.isdir(args.samples):\n        search = [args.samples]\n    else:\n        search = ["samples", "tests", os.path.join(sols_dir, "samples"), "."]\n    for d in search:\n        if not os.path.isdir(d):\n            continue\n        ins = sorted(glob.glob(os.path.join(d, "*.in")))\n        cases = [(i, find_expected(i)) for i in ins]\n        cases = [(i, o) for (i, o) in cases if o]\n        if cases:\n            return cases\n    return []\n\ndef normalize(text, raw):\n    if raw:\n        return text\n    lines = [ln.rstrip() for ln in text.replace("\\r\\n", "\\n").split("\\n")]\n    while lines and lines[-1] == "":\n        lines.pop()\n    return "\\n".join(lines)\n\ndef first_diff(exp, got):\n    e, g = exp.split("\\n"), got.split("\\n")\n    for i in range(max(len(e), len(g))):\n        ev = e[i] if i < len(e) else "<no line>"\n        gv = g[i] if i < len(g) else "<no line>"\n        if ev != gv:\n            return i + 1, ev, gv\n    return None\n\ndef run_case(py, solution, in_path, tl):\n    with open(in_path, "rb") as f:\n        data = f.read()\n    t0 = time.perf_counter()\n    try:\n        p = subprocess.run([py, solution], input=data, stdout=subprocess.PIPE,\n                           stderr=subprocess.PIPE, timeout=tl)\n    except subprocess.TimeoutExpired:\n        return ("TLE", time.perf_counter() - t0, "", "")\n    except FileNotFoundError:\n        sys.exit(red(f"interpreter not found: {py}  (install it, or pass --py python3)"))\n    dt = time.perf_counter() - t0\n    if p.returncode != 0:\n        err = p.stderr.decode("utf-8", "replace").strip().splitlines()\n        return ("RE", dt, p.stdout.decode("utf-8", "replace"), (err[-1] if err else f"exit {p.returncode}"))\n    return ("OK", dt, p.stdout.decode("utf-8", "replace"), "")\n\ndef main():\n    ap = argparse.ArgumentParser(prog="icoa-judge", add_help=True)\n    ap.add_argument("solution")\n    ap.add_argument("samples", nargs="?")\n    ap.add_argument("expected", nargs="?")\n    ap.add_argument("--tl", type=float, default=5.0)\n    ap.add_argument("--py", default="python3")\n    ap.add_argument("--raw", action="store_true")\n    args = ap.parse_args()\n\n    if not os.path.isfile(args.solution):\n        sys.exit(red(f"solution file not found: {args.solution}"))\n    cases = collect_cases(args)\n    if not cases:\n        sys.exit(yellow("no sample cases found. Put 1.in/1.out next to your solution (or in "\n                        "./samples), or pass a directory / a case.in case.out pair."))\n\n    print(gray(f"icoa-judge — {args.py} · {len(cases)} sample case(s) · TL {args.tl:g}s "\n               f"(sample self-check, not the real judge)"))\n    passed = 0\n    slow = False\n    for idx, (in_path, exp_path) in enumerate(cases, 1):\n        name = os.path.basename(in_path)\n        status, dt, got, extra = run_case(args.py, args.solution, in_path, args.tl)\n        ms = f"{dt * 1000:7.1f} ms"\n        if status == "TLE":\n            print(f"  {red(\'TLE \')}  {name:<16} {gray(\'> \' + format(args.tl, \'g\') + \'s\')}")\n            slow = True\n            continue\n        if status == "RE":\n            print(f"  {red(\'ERR \')}  {name:<16} {gray(ms)}   {red(extra)}")\n            continue\n        exp = normalize(open(exp_path, encoding=\'utf-8\', errors=\'replace\').read(), args.raw)\n        out = normalize(got, args.raw)\n        if out == exp:\n            print(f"  {green(\'PASS\')}  {name:<16} {gray(ms)}")\n            passed += 1\n            if dt > 0.5 * args.tl:\n                slow = True\n        else:\n            d = first_diff(exp, out)\n            where = f"line {d[0]}" if d else "output"\n            print(f"  {red(\'WRONG\')} {name:<16} {gray(ms)}   {gray(where)}")\n            if d:\n                print(gray(f"        expected: {d[1][:70]}"))\n                print(gray(f"        got:      {d[2][:70]}"))\n\n    print()\n    tag = green("ALL PASS") if passed == len(cases) else yellow(f"{passed}/{len(cases)} passed")\n    print(f"  {tag}")\n    if slow and args.py != "pypy3":\n        print(gray("  (some runs were slow — if the real judge TLEs, try  --py pypy3,  faster I/O, "\n                   "or an iterative form. Sample timing is only a rough guide.)"))\n    sys.exit(0 if passed == len(cases) else 1)\n\nif __name__ == "__main__":\n    main()\n',"utf-8"),"win32"!==process.platform){try{e(RUNNER_PY,493)}catch{}r(p,`#!/bin/sh\nexec python3 "${RUNNER_PY}" "$@"\n`,"utf-8");try{e(p,493)}catch{}}return{ok:!0,path:RUNNER_PY,updated:!0}}catch(e){return{ok:!1,path:RUNNER_PY,updated:!1,why:e instanceof Error?e.message:String(e)}}}export function sampleRunnerInstalled(){return n(RUNNER_PY)&&l(RUNNER_PY)}
+// Local sample-test runner for the ioipy (Python informatics) track — Hard Rule §4.
+//
+// A tiny STDLIB-ONLY Python script shipped to the student's machine by `env setup`.
+// It runs their Python solution against sample input/output pairs, diffs stdout against
+// the expected output (whitespace-normalized), and prints a rough wall-clock time so they
+// get a *feel* for whether a solution is fast enough. It is deliberately NOT the
+// server-authoritative online judge (that hidden-test layer is the deferred §3 project) —
+// it only checks the SAMPLE cases the student already has, which is exactly what the learn
+// cards (P2+) ask them to do ("implement in Python and run it on the provided samples").
+//
+// The script content travels as a string in the compiled JS, so there is no asset to
+// bundle / resolve at runtime. `placeSampleRunner()` writes it to ~/.icoa/bin/.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// Bump when the embedded script below changes, so an existing stale copy is rewritten.
+const SAMPLE_RUNNER_VERSION = '1';
+const RUNNER_DIR = join(homedir(), '.icoa', 'bin');
+export const RUNNER_PY = join(RUNNER_DIR, 'icoa-judge.py');
+const RUNNER_SHIM = join(RUNNER_DIR, 'icoa-judge');
+// The shipped runner. Pure Python 3 stdlib (subprocess, argparse, time, glob, sys, os).
+// `# ICOA-RUNNER vN` on line 2 lets us detect/refresh a stale copy.
+const JUDGE_SCRIPT = `#!/usr/bin/env python3
+# ICOA-RUNNER v${SAMPLE_RUNNER_VERSION}
+"""icoa-judge — tiny local sample-test runner for the ioipy Python informatics track.
+
+Runs YOUR Python solution against sample input/expected-output pairs, compares stdout,
+and reports PASS / WRONG / TLE / RUNTIME-ERROR plus the wall-clock time of each run.
+
+This is a self-check on the SAMPLE cases only — a rough "is it correct and fast enough?"
+feel. It is NOT the real judge (no hidden tests, no authoritative time/memory limit).
+
+USAGE
+  icoa-judge SOLUTION.py [SAMPLES]
+    SAMPLES can be:
+      - a directory holding  1.in/1.out, 2.in/2.out, ...  (also accepts .ans/.expected/.exp)
+      - a single  case.in  (its expected output is the sibling  case.out)
+      - two files:  case.in  case.out
+      - omitted: auto-search ./samples, ./tests, a samples/ next to SOLUTION.py, or *.in here
+
+OPTIONS
+  --tl SECONDS   per-case soft time limit (default 5.0 — Python-friendly; a TLE here is a
+                 hint, not a verdict; the real limit is the contest's)
+  --py CMD       interpreter for your solution (default: python3; try  --py pypy3  for speed)
+  --raw          exact byte compare (default: whitespace-normalized — trailing spaces and
+                 trailing blank lines are ignored, the usual contest checker behaviour)
+"""
+import argparse, glob, os, subprocess, sys, time
+
+OUT_EXTS = (".out", ".ans", ".expected", ".exp")
+C = sys.stdout.isatty()
+def col(s, c): return f"\\033[{c}m{s}\\033[0m" if C else s
+def green(s): return col(s, "32")
+def red(s): return col(s, "31")
+def yellow(s): return col(s, "33")
+def gray(s): return col(s, "90")
+
+def find_expected(in_path):
+    stem = in_path[:-3] if in_path.endswith(".in") else os.path.splitext(in_path)[0]
+    for ext in OUT_EXTS:
+        if os.path.exists(stem + ext):
+            return stem + ext
+    return None
+
+def collect_cases(args):
+    sols_dir = os.path.dirname(os.path.abspath(args.solution)) or "."
+    # explicit: two files (in + out)
+    if args.samples and args.expected:
+        return [(args.samples, args.expected)]
+    # explicit: a single .in file
+    if args.samples and os.path.isfile(args.samples) and args.samples.endswith(".in"):
+        exp = find_expected(args.samples)
+        return [(args.samples, exp)] if exp else []
+    # explicit: a directory
+    if args.samples and os.path.isdir(args.samples):
+        search = [args.samples]
+    else:
+        search = ["samples", "tests", os.path.join(sols_dir, "samples"), "."]
+    for d in search:
+        if not os.path.isdir(d):
+            continue
+        ins = sorted(glob.glob(os.path.join(d, "*.in")))
+        cases = [(i, find_expected(i)) for i in ins]
+        cases = [(i, o) for (i, o) in cases if o]
+        if cases:
+            return cases
+    return []
+
+def normalize(text, raw):
+    if raw:
+        return text
+    lines = [ln.rstrip() for ln in text.replace("\\r\\n", "\\n").split("\\n")]
+    while lines and lines[-1] == "":
+        lines.pop()
+    return "\\n".join(lines)
+
+def first_diff(exp, got):
+    e, g = exp.split("\\n"), got.split("\\n")
+    for i in range(max(len(e), len(g))):
+        ev = e[i] if i < len(e) else "<no line>"
+        gv = g[i] if i < len(g) else "<no line>"
+        if ev != gv:
+            return i + 1, ev, gv
+    return None
+
+def run_case(py, solution, in_path, tl):
+    with open(in_path, "rb") as f:
+        data = f.read()
+    t0 = time.perf_counter()
+    try:
+        p = subprocess.run([py, solution], input=data, stdout=subprocess.PIPE,
+                           stderr=subprocess.PIPE, timeout=tl)
+    except subprocess.TimeoutExpired:
+        return ("TLE", time.perf_counter() - t0, "", "")
+    except FileNotFoundError:
+        sys.exit(red(f"interpreter not found: {py}  (install it, or pass --py python3)"))
+    dt = time.perf_counter() - t0
+    if p.returncode != 0:
+        err = p.stderr.decode("utf-8", "replace").strip().splitlines()
+        return ("RE", dt, p.stdout.decode("utf-8", "replace"), (err[-1] if err else f"exit {p.returncode}"))
+    return ("OK", dt, p.stdout.decode("utf-8", "replace"), "")
+
+def main():
+    ap = argparse.ArgumentParser(prog="icoa-judge", add_help=True)
+    ap.add_argument("solution")
+    ap.add_argument("samples", nargs="?")
+    ap.add_argument("expected", nargs="?")
+    ap.add_argument("--tl", type=float, default=5.0)
+    ap.add_argument("--py", default="python3")
+    ap.add_argument("--raw", action="store_true")
+    args = ap.parse_args()
+
+    if not os.path.isfile(args.solution):
+        sys.exit(red(f"solution file not found: {args.solution}"))
+    cases = collect_cases(args)
+    if not cases:
+        sys.exit(yellow("no sample cases found. Put 1.in/1.out next to your solution (or in "
+                        "./samples), or pass a directory / a case.in case.out pair."))
+
+    print(gray(f"icoa-judge — {args.py} · {len(cases)} sample case(s) · TL {args.tl:g}s "
+               f"(sample self-check, not the real judge)"))
+    passed = 0
+    slow = False
+    for idx, (in_path, exp_path) in enumerate(cases, 1):
+        name = os.path.basename(in_path)
+        status, dt, got, extra = run_case(args.py, args.solution, in_path, args.tl)
+        ms = f"{dt * 1000:7.1f} ms"
+        if status == "TLE":
+            print(f"  {red('TLE ')}  {name:<16} {gray('> ' + format(args.tl, 'g') + 's')}")
+            slow = True
+            continue
+        if status == "RE":
+            print(f"  {red('ERR ')}  {name:<16} {gray(ms)}   {red(extra)}")
+            continue
+        exp = normalize(open(exp_path, encoding='utf-8', errors='replace').read(), args.raw)
+        out = normalize(got, args.raw)
+        if out == exp:
+            print(f"  {green('PASS')}  {name:<16} {gray(ms)}")
+            passed += 1
+            if dt > 0.5 * args.tl:
+                slow = True
+        else:
+            d = first_diff(exp, out)
+            where = f"line {d[0]}" if d else "output"
+            print(f"  {red('WRONG')} {name:<16} {gray(ms)}   {gray(where)}")
+            if d:
+                print(gray(f"        expected: {d[1][:70]}"))
+                print(gray(f"        got:      {d[2][:70]}"))
+
+    print()
+    tag = green("ALL PASS") if passed == len(cases) else yellow(f"{passed}/{len(cases)} passed")
+    print(f"  {tag}")
+    if slow and args.py != "pypy3":
+        print(gray("  (some runs were slow — if the real judge TLEs, try  --py pypy3,  faster I/O, "
+                   "or an iterative form. Sample timing is only a rough guide.)"))
+    sys.exit(0 if passed == len(cases) else 1)
+
+if __name__ == "__main__":
+    main()
+`;
+function isCurrent(path) {
+    try {
+        const head = readFileSync(path, 'utf-8').split('\n', 2)[1] || '';
+        return head.includes(`ICOA-RUNNER v${SAMPLE_RUNNER_VERSION}`);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write the runner to ~/.icoa/bin/icoa-judge.py (+ a `icoa-judge` shell shim on POSIX).
+ * Idempotent: rewrites only if missing or stale (older version line). Stdlib-only —
+ * needs nothing installed beyond a working python3 the student already has.
+ */
+export function placeSampleRunner() {
+    try {
+        if (existsSync(RUNNER_PY) && isCurrent(RUNNER_PY)) {
+            return { ok: true, path: RUNNER_PY, updated: false };
+        }
+        mkdirSync(RUNNER_DIR, { recursive: true });
+        writeFileSync(RUNNER_PY, JUDGE_SCRIPT, 'utf-8');
+        if (process.platform !== 'win32') {
+            try {
+                chmodSync(RUNNER_PY, 0o755);
+            }
+            catch {
+                /* non-fatal */
+            }
+            // Convenience shim so the student can type `icoa-judge ...` once ~/.icoa/bin is on PATH.
+            writeFileSync(RUNNER_SHIM, `#!/bin/sh\nexec python3 "${RUNNER_PY}" "$@"\n`, 'utf-8');
+            try {
+                chmodSync(RUNNER_SHIM, 0o755);
+            }
+            catch {
+                /* non-fatal */
+            }
+        }
+        return { ok: true, path: RUNNER_PY, updated: true };
+    }
+    catch (e) {
+        return { ok: false, path: RUNNER_PY, updated: false, why: e instanceof Error ? e.message : String(e) };
+    }
+}
+/** Is a current copy of the runner present? (for `env` status display) */
+export function sampleRunnerInstalled() {
+    return existsSync(RUNNER_PY) && isCurrent(RUNNER_PY);
+}