icoa-cli 2.19.355 → 2.19.357

package/dist/lib/learn-state.js

@@ -1 +1,103 @@
-import{existsSync as e,mkdirSync as t,readFileSync as r,writeFileSync as a}from"node:fs";import{homedir as n}from"node:os";import{join as o}from"node:path";const s=o(n(),".icoa"),c=o(s,"learn-state.json");export function loadLearnState(){if(!e(c))return null;try{return JSON.parse(r(c,"utf-8"))}catch{return null}}export function saveLearnState(r){e(s)||t(s,{recursive:!0}),r.lastSeenAt=(new Date).toISOString(),a(c,JSON.stringify(r,null,2))}export function newLearnState(e,t,r){const a=(new Date).toISOString();return{token:e,curriculumId:t,currentCard:1,totalCards:r,startedAt:a,lastSeenAt:a,streakDays:1,longestStreak:1,cardsCompleted:[],mcqResults:{},checkResults:{},practicalsCompleted:[],bookmarks:[],achievements:[],totalSecondsActive:0}}export function updateStreak(e){const t=new Date(e.lastSeenAt),r=new Date,a=Math.floor(t.getTime()/864e5),n=Math.floor(r.getTime()/864e5)-a;0!==n&&(1===n?(e.streakDays+=1,e.streakDays>e.longestStreak&&(e.longestStreak=e.streakDays)):e.streakDays=1)}export function markCardComplete(e,t){e.cardsCompleted.includes(t)||e.cardsCompleted.push(t)}export function recordMCQ(e,t,r){e.mcqResults[String(t)]=r}export function recordCheck(e,t,r){e.checkResults||(e.checkResults={}),e.checkResults[String(t)]=r}export function markPracticalComplete(e,t){e.practicalsCompleted.includes(t)||e.practicalsCompleted.push(t)}export function addAchievement(e,t){e.achievements.includes(t)||e.achievements.push(t)}
+/**
+ * Learn-mode state persistence.
+ *
+ * Local file: ~/.icoa/learn-state.json
+ * Schema designed to mirror server-side learn_progress table for Phase 1 sync.
+ *
+ * Unlike exam state, learn state ENCOURAGES multi-device: same token can be
+ * resumed on any machine (Phase 1 server-sync), no device-hash binding.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const STATE_DIR = join(homedir(), '.icoa');
+const STATE_PATH = join(STATE_DIR, 'learn-state.json');
+function ensureDir() {
+    if (!existsSync(STATE_DIR))
+        mkdirSync(STATE_DIR, { recursive: true });
+}
+export function loadLearnState() {
+    if (!existsSync(STATE_PATH))
+        return null;
+    try {
+        return JSON.parse(readFileSync(STATE_PATH, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveLearnState(state) {
+    ensureDir();
+    state.lastSeenAt = new Date().toISOString();
+    writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
+}
+export function newLearnState(token, curriculumId, totalCards) {
+    const now = new Date().toISOString();
+    return {
+        token,
+        curriculumId,
+        currentCard: 1,
+        totalCards,
+        startedAt: now,
+        lastSeenAt: now,
+        streakDays: 1,
+        longestStreak: 1,
+        cardsCompleted: [],
+        mcqResults: {},
+        checkResults: {},
+        practicalsCompleted: [],
+        bookmarks: [],
+        achievements: [],
+        totalSecondsActive: 0,
+    };
+}
+/**
+ * Update streak based on last-seen-at vs today.
+ *  - Same day:    streak unchanged
+ *  - Next day:    streak + 1
+ *  - Gap > 1 day: streak resets to 1
+ */
+export function updateStreak(state) {
+    const last = new Date(state.lastSeenAt);
+    const now = new Date();
+    // Compare calendar days (UTC for simplicity)
+    const lastDay = Math.floor(last.getTime() / 86400000);
+    const nowDay = Math.floor(now.getTime() / 86400000);
+    const diff = nowDay - lastDay;
+    if (diff === 0)
+        return;
+    if (diff === 1) {
+        state.streakDays += 1;
+        if (state.streakDays > state.longestStreak)
+            state.longestStreak = state.streakDays;
+    }
+    else {
+        state.streakDays = 1; // reset
+    }
+}
+export function markCardComplete(state, cardNumber) {
+    // Records completion only — does NOT advance currentCard. The REPL's `ok`
+    // handler is the sole place that advances, to keep card flow predictable
+    // (no double-jumps from card N to N+2).
+    if (!state.cardsCompleted.includes(cardNumber)) {
+        state.cardsCompleted.push(cardNumber);
+    }
+}
+export function recordMCQ(state, cardNumber, result) {
+    state.mcqResults[String(cardNumber)] = result;
+}
+export function recordCheck(state, cardNumber, result) {
+    if (!state.checkResults)
+        state.checkResults = {};
+    state.checkResults[String(cardNumber)] = result;
+}
+export function markPracticalComplete(state, cardNumber) {
+    if (!state.practicalsCompleted.includes(cardNumber)) {
+        state.practicalsCompleted.push(cardNumber);
+    }
+}
+export function addAchievement(state, badge) {
+    if (!state.achievements.includes(badge)) {
+        state.achievements.push(badge);
+    }
+}

package/dist/lib/log-sync.js

@@ -1 +1,155 @@
-import{readFileSync as t,existsSync as n,writeFileSync as e,chmodSync as s}from"node:fs";import{join as i}from"node:path";import{getIcoaDir as o,getConfig as c}from"./config.js";import{getDeviceFingerprint as r}from"./access.js";import{getCliVersion as a}from"./version.js";const l=()=>i(o(),"sync-state.json");let u=null;function f(t){const n=l();e(n,JSON.stringify(t,null,2));try{s(n,384)}catch{}}async function y(){const e=c(),s=e.ctfdUrl||"https://practice.icoa2026.au",u=i(o(),"session.log");if(!n(u))return;const y=function(){const e=l();if(!n(e))return{lastSyncedLine:0,lastSyncAt:null,syncCount:0,failCount:0,seq:0};try{const n=JSON.parse(t(e,"utf-8"));return{lastSyncedLine:n.lastSyncedLine??0,lastSyncAt:n.lastSyncAt??null,syncCount:n.syncCount??0,failCount:n.failCount??0,seq:n.seq??0}}catch{return{lastSyncedLine:0,lastSyncAt:null,syncCount:0,failCount:0,seq:0}}}(),d=t(u,"utf-8").trim().split("\n").filter(Boolean);d.length<y.lastSyncedLine&&(y.lastSyncedLine=0);const p=d.slice(y.lastSyncedLine);if(0===p.length)return;const S={"Content-Type":"application/json"};let m;if(e.token)S.Authorization=`Token ${e.token}`,m=`user:${e.userId??"unknown"}`;else{const t=e.deviceFingerprint||r();S["X-Device-Fingerprint"]=t,m=`demo:${t.slice(0,12)}`}const g=y.seq??0,h=p.map((t,n)=>{let e;try{e=JSON.parse(t)}catch{e={raw:t}}return{...e,_seq:g+n+1}}),C=a(),I=h.map(t=>({...t,_cli:C})),L={identity:m,userId:e.userId,userName:e.userName,teamId:e.teamId,sessionId:e.sessionId,deviceFingerprint:e.deviceFingerprint||r(),lang:e.language||"en",clientVersion:C,timestamp:(new Date).toISOString(),seqRange:{from:g+1,to:g+h.length},entries:I};try{const t=new URL("/api/icoa/audit",s).href;(await fetch(t,{method:"POST",headers:S,body:JSON.stringify(L),signal:AbortSignal.timeout(1e4)})).ok?(y.lastSyncedLine=d.length,y.lastSyncAt=(new Date).toISOString(),y.syncCount++,y.seq=g+h.length,f(y)):(y.failCount++,f(y))}catch{y.failCount++,f(y)}}export function startLogSync(){setTimeout(()=>y(),5e3),u=setInterval(()=>y(),3e4)}export function stopLogSync(){u&&(clearInterval(u),u=null),y()}
+import { readFileSync, existsSync, writeFileSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { getIcoaDir, getConfig } from './config.js';
+import { getDeviceFingerprint } from './access.js';
+import { getCliVersion } from './version.js';
+// Every 30s, post new lines from ~/.icoa/session.log to the server audit
+// endpoint. Two auth modes:
+//
+//   1. Logged-in user (CTFd token present)  → Authorization: Token <token>,
+//      stored on the server as /opt/CTFd/audit/user-<userId>.jsonl
+//   2. Anonymous demo user (no token)       → X-Device-Fingerprint: <hash>,
+//      stored as /opt/CTFd/audit/demo-<fingerprint>.jsonl
+//
+// The demo path is what lets us observe the full prompt/command history of
+// users who never log in (the main demo audience).
+//
+// V7 fix (v2.19.181): Each entry carries a monotonic `seq` counter that
+// only increments (never resets, never decreases). Server stores last seq
+// per identity. Deleting session.log + sync-state.json no longer hides
+// activity — the seq jump tells the server a chunk was wiped.
+const SYNC_INTERVAL = 30_000;
+const DEFAULT_SERVER = 'https://practice.icoa2026.au';
+const SYNC_STATE_FILE = () => join(getIcoaDir(), 'sync-state.json');
+let syncTimer = null;
+function getSyncState() {
+    const file = SYNC_STATE_FILE();
+    if (!existsSync(file))
+        return { lastSyncedLine: 0, lastSyncAt: null, syncCount: 0, failCount: 0, seq: 0 };
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+        return {
+            lastSyncedLine: parsed.lastSyncedLine ?? 0,
+            lastSyncAt: parsed.lastSyncAt ?? null,
+            syncCount: parsed.syncCount ?? 0,
+            failCount: parsed.failCount ?? 0,
+            seq: parsed.seq ?? 0,
+        };
+    }
+    catch {
+        return { lastSyncedLine: 0, lastSyncAt: null, syncCount: 0, failCount: 0, seq: 0 };
+    }
+}
+function saveSyncState(state) {
+    const f = SYNC_STATE_FILE();
+    writeFileSync(f, JSON.stringify(state, null, 2));
+    try {
+        chmodSync(f, 0o600);
+    }
+    catch {
+        /* ignore Windows / restricted FS */
+    }
+}
+async function syncLogs() {
+    const config = getConfig();
+    const serverUrl = config.ctfdUrl || DEFAULT_SERVER;
+    const logPath = join(getIcoaDir(), 'session.log');
+    if (!existsSync(logPath))
+        return;
+    const state = getSyncState();
+    const allLines = readFileSync(logPath, 'utf-8').trim().split('\n').filter(Boolean);
+    // V7 monotonic guard: if the log shrank below our last-synced position
+    // (file was deleted/truncated), our cursor would otherwise stay ahead of
+    // the new content forever. Detect the shrink and resume from 0, but the
+    // server-side `seq` counter keeps climbing, so the gap is still evident
+    // to whoever audits the JSONL.
+    if (allLines.length < state.lastSyncedLine) {
+        state.lastSyncedLine = 0;
+    }
+    const newLines = allLines.slice(state.lastSyncedLine);
+    if (newLines.length === 0)
+        return;
+    // Pick auth mode: token for logged-in users, device fingerprint for anon.
+    const headers = { 'Content-Type': 'application/json' };
+    let identity;
+    if (config.token) {
+        headers.Authorization = `Token ${config.token}`;
+        identity = `user:${config.userId ?? 'unknown'}`;
+    }
+    else {
+        const fp = config.deviceFingerprint || getDeviceFingerprint();
+        headers['X-Device-Fingerprint'] = fp;
+        identity = `demo:${fp.slice(0, 12)}`;
+    }
+    // Tag each entry with a monotonic seq number. The seq counter lives in
+    // sync-state.json and only ever increments (V7 fix). If the contestant
+    // deletes session.log to hide activity, the next batch starts at seq=N+k
+    // and the server sees the jump.
+    const baseSeq = state.seq ?? 0;
+    const taggedEntries = newLines.map((line, idx) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            parsed = { raw: line };
+        }
+        return { ...parsed, _seq: baseSeq + idx + 1 };
+    });
+    const cliVersion = getCliVersion();
+    // V2.19.185: stamp every entry with the CLI version. Lets future forensic
+    // audits answer "which CLI version did this contestant run?" — see the
+    // Paper E dispatcher post-mortem (cross-country-audit-2026-05-23.pdf §6
+    // Gap #2). Top-level field also kept for backward search ergonomics.
+    const entriesWithVersion = taggedEntries.map((e) => ({ ...e, _cli: cliVersion }));
+    const payload = {
+        identity,
+        userId: config.userId,
+        userName: config.userName,
+        teamId: config.teamId,
+        sessionId: config.sessionId,
+        deviceFingerprint: config.deviceFingerprint || getDeviceFingerprint(),
+        lang: config.language || 'en',
+        clientVersion: cliVersion,
+        timestamp: new Date().toISOString(),
+        seqRange: { from: baseSeq + 1, to: baseSeq + taggedEntries.length },
+        entries: entriesWithVersion,
+    };
+    try {
+        const url = new URL('/api/icoa/audit', serverUrl).href;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (res.ok) {
+            state.lastSyncedLine = allLines.length;
+            state.lastSyncAt = new Date().toISOString();
+            state.syncCount++;
+            state.seq = baseSeq + taggedEntries.length;
+            saveSyncState(state);
+        }
+        else {
+            state.failCount++;
+            saveSyncState(state);
+        }
+    }
+    catch {
+        // Silent fail — network issues shouldn't break the CLI
+        state.failCount++;
+        saveSyncState(state);
+    }
+}
+export function startLogSync() {
+    setTimeout(() => syncLogs(), 5_000);
+    syncTimer = setInterval(() => syncLogs(), SYNC_INTERVAL);
+}
+export function stopLogSync() {
+    if (syncTimer) {
+        clearInterval(syncTimer);
+        syncTimer = null;
+    }
+    // Final sync before exit
+    syncLogs();
+}

package/dist/lib/logger.js

@@ -1 +1,49 @@
-import{appendFileSync as t,readFileSync as n,existsSync as o}from"node:fs";import{join as e}from"node:path";import{getConfig as i,getIcoaDir as s}from"./config.js";function r(){return e(s(),"session.log")}function m(n){try{t(r(),`${JSON.stringify(n)}\n`)}catch{}}export function logCommand(t){const n=i();m({timestamp:(new Date).toISOString(),level:"command",input:t,sessionId:n.sessionId})}export function logSubmission(t,n){const o=i();m({timestamp:(new Date).toISOString(),level:"submit",input:n,challengeId:t,sessionId:o.sessionId})}export function getSessionLog(){const t=r();if(!o(t))return[];try{return n(t,"utf-8").trim().split("\n").filter(Boolean).map(t=>JSON.parse(t))}catch{return[]}}
+import { appendFileSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getConfig, getIcoaDir } from './config.js';
+function getLogPath() {
+    return join(getIcoaDir(), 'session.log');
+}
+function logEntry(entry) {
+    try {
+        appendFileSync(getLogPath(), `${JSON.stringify(entry)}\n`);
+    }
+    catch {
+        // Silently fail — logging should never break the CLI
+    }
+}
+export function logCommand(command) {
+    const config = getConfig();
+    logEntry({
+        timestamp: new Date().toISOString(),
+        level: 'command',
+        input: command,
+        sessionId: config.sessionId,
+    });
+}
+export function logSubmission(challengeId, flag) {
+    const config = getConfig();
+    logEntry({
+        timestamp: new Date().toISOString(),
+        level: 'submit',
+        input: flag,
+        challengeId,
+        sessionId: config.sessionId,
+    });
+}
+export function getSessionLog() {
+    const logPath = getLogPath();
+    if (!existsSync(logPath))
+        return [];
+    try {
+        const raw = readFileSync(logPath, 'utf-8');
+        return raw
+            .trim()
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/main-rl.js

@@ -1 +1,7 @@
-let n=null;export function setMainRl(t){n=t}export function getMainRl(){return n}
+let _mainRl = null;
+export function setMainRl(rl) {
+    _mainRl = rl;
+}
+export function getMainRl() {
+    return _mainRl;
+}

package/dist/lib/menu-nav.js

@@ -1 +1,105 @@
-import{spawn as e}from"node:child_process";import chalk from"chalk";export const RELAUNCH_CODE=75;export function printMenuHint(){console.log(chalk.gray("  💡 Type ")+chalk.bold.cyan("menu")+chalk.gray(" anytime to return to the main menu (works from any screen)"))}export function menuHintInline(){return chalk.cyan("menu")+chalk.gray(" returns home")}export function returnToMainMenu(o){if(console.log(),console.log(chalk.gray("  Returning to main menu...")),console.log(),o?.removeAllListeners)try{o.removeAllListeners("close")}catch{}if(o)try{o.close()}catch{}try{process.stdin.isTTY&&process.stdin.setRawMode&&process.stdin.setRawMode(!1)}catch{}"1"===process.env.ICOA_SUPERVISED&&process.exit(75);const n=e(process.argv[0],process.argv.slice(1),{stdio:"inherit",env:process.env});n.on("exit",e=>process.exit(e??0)),n.on("error",e=>{console.error(chalk.yellow(`  Could not respawn CLI: ${e.message}`)),process.exit(1)})}
+/**
+ * Global "back to boot screen" navigation.
+ *
+ * The CLI has several sub-REPLs (ai4ctf, ctf4ai, ctf4vla, learn, demo2,
+ * exam REPL inside Selection mode) that own input handling once entered.
+ * `menu` is the universal escape hatch: from anywhere in the CLI, typing
+ * it returns the user to the launch banner + mode-selector picker.
+ *
+ * Implementation: re-execs the current node binary with the same argv,
+ * inheriting stdio. The new process re-runs startRepl from the top, which
+ * always shows the mode selector. The parent exits with the child's code.
+ *
+ * For real-exam state, the caller should gate via `menu confirm` to avoid
+ * surprise exits during a graded session. Exam progress is auto-saved on
+ * every answer, so even an unconfirmed exit is non-destructive — the
+ * confirmation is purely UX hygiene.
+ */
+import { spawn } from 'node:child_process';
+import chalk from 'chalk';
+/**
+ * Exit code the worker uses to ask the supervisor (in index.ts) to relaunch a
+ * fresh CLI process. Picked from the unreserved 64–113 sysexits range so it
+ * can't collide with a normal `process.exit(0|1)`. See index.ts for the
+ * supervisor loop that consumes it.
+ */
+export const RELAUNCH_CODE = 75;
+/**
+ * One-line standalone hint for sub-REPLs and mode landing screens.
+ * Prints a friendly cue that `menu` is always available.
+ */
+export function printMenuHint() {
+    console.log(chalk.gray('  💡 Type ') +
+        chalk.bold.cyan('menu') +
+        chalk.gray(' anytime to return to the main menu (works from any screen)'));
+}
+/**
+ * Inline fragment for embedding in existing Tip / footer lines.
+ * Returns a chalk-styled string like:  menu returns home
+ * so callers can splice it with ` · ` separators.
+ */
+export function menuHintInline() {
+    return chalk.cyan('menu') + chalk.gray(' returns home');
+}
+export function returnToMainMenu(rl) {
+    console.log();
+    console.log(chalk.gray('  Returning to main menu...'));
+    console.log();
+    // Critical: the parent REPL registers an rl.on('close') handler that
+    // calls realExit(0). If we close rl with that handler still attached,
+    // the parent process dies BEFORE the child finishes starting — user
+    // ends up back at their shell instead of at the mode selector.
+    if (rl?.removeAllListeners) {
+        try {
+            rl.removeAllListeners('close');
+        }
+        catch {
+            // Not an EventEmitter — fine
+        }
+    }
+    if (rl) {
+        try {
+            rl.close();
+        }
+        catch {
+            // Already closed — fine
+        }
+    }
+    // Restore cooked terminal mode before we exit/respawn so the next process
+    // inherits a clean TTY. Without this a lingering raw-mode flag from this
+    // process's readline/inquirer could corrupt keystroke handling in the fresh
+    // boot (was a contributor to the "learn → lan" dropped-character bug).
+    try {
+        if (process.stdin.isTTY && process.stdin.setRawMode) {
+            process.stdin.setRawMode(false);
+        }
+    }
+    catch {
+        // Not a TTY / no raw mode — fine.
+    }
+    // Preferred path: a supervisor process (index.ts) is wrapping this worker.
+    // Exit with the relaunch sentinel and let the supervisor start exactly ONE
+    // fresh process. This replaces the old spawn-and-stay-alive approach, where
+    // every `menu` spawned a child while the parent kept running — after K menu
+    // bounces you had K+1 node processes all holding the inherited TTY, which
+    // slowed the CLI to a crawl and dropped keystrokes (a 4-deep process chain
+    // was observed in prod, 2026-06-04). With the supervisor, only one worker is
+    // ever live, so navigation stays fast no matter how many times you bounce.
+    if (process.env.ICOA_SUPERVISED === '1') {
+        process.exit(RELAUNCH_CODE);
+    }
+    // Fallback (no supervisor — e.g. a non-TTY/piped run, or a one-shot
+    // invocation the supervisor skips): keep the original respawn so behavior is
+    // unchanged for any path the supervisor doesn't cover. stdio:'inherit'
+    // shares the TTY; the parent waits on the child's exit to keep the OS TTY
+    // ownership chain intact.
+    const child = spawn(process.argv[0], process.argv.slice(1), {
+        stdio: 'inherit',
+        env: process.env,
+    });
+    child.on('exit', (code) => process.exit(code ?? 0));
+    child.on('error', (err) => {
+        console.error(chalk.yellow(`  Could not respawn CLI: ${err.message}`));
+        process.exit(1);
+    });
+}

package/dist/lib/notebook-doc.d.ts

@@ -0,0 +1,38 @@
+/**
+ * notebook-doc — the pure cell model behind `icoa ipynb`'s cell-stepper
+ * (cells / show / edit / run / save). nbformat v4 is plain JSON, so parse and
+ * serialize live here with zero dependencies; keeping the module pure (no I/O,
+ * no chalk) means the whole document lifecycle is unit-tested without a kernel.
+ *
+ * Round-trip safety: cells loaded from disk keep their original outputs in
+ * `rawOutputs` and are written back verbatim on save unless the cell was
+ * re-run this session (then the fresh FoldedCell result wins).
+ */
+import type { FoldedCell } from './kernel-protocol.js';
+export type CellKind = 'code' | 'markdown';
+export interface NbCell {
+    kind: CellKind;
+    source: string;
+    /** Result of running the cell THIS session; null = not run yet. */
+    result: FoldedCell | null;
+    /** nbformat outputs as loaded from disk (preserved on save if not re-run). */
+    rawOutputs?: unknown[];
+    rawExecCount?: number | null;
+}
+/** Parse a .ipynb (nbformat v4) JSON string. Raw cells are dropped. */
+export declare function parseIpynb(json: string): NbCell[];
+/**
+ * Split a Python script into cells on `# %%` markers (jupytext percent
+ * format; the arena starter uses the same markers). Marker lines are
+ * separators and are dropped. No markers → the whole file is one cell.
+ */
+export declare function parsePercentPy(text: string): NbCell[];
+/** Serialize cells to a Jupyter-openable nbformat v4.5 JSON string. */
+export declare function serializeIpynb(cells: NbCell[]): string;
+/** One-char run state for the `cells` listing. */
+export declare function statusChar(cell: NbCell): string;
+/** First non-blank line, trimmed and truncated to `width` (with ellipsis). */
+export declare function cellPreview(cell: NbCell, width: number): string;
+/** Parse `run` arguments: '3' → [3], '1-5' → [1..5], 'all' → [1..count].
+ *  1-based, validated against count; null = not a valid range. */
+export declare function parseRunRange(arg: string, count: number): number[] | null;

package/dist/lib/notebook-doc.js

@@ -0,0 +1,137 @@
+/**
+ * notebook-doc — the pure cell model behind `icoa ipynb`'s cell-stepper
+ * (cells / show / edit / run / save). nbformat v4 is plain JSON, so parse and
+ * serialize live here with zero dependencies; keeping the module pure (no I/O,
+ * no chalk) means the whole document lifecycle is unit-tested without a kernel.
+ *
+ * Round-trip safety: cells loaded from disk keep their original outputs in
+ * `rawOutputs` and are written back verbatim on save unless the cell was
+ * re-run this session (then the fresh FoldedCell result wins).
+ */
+/** Parse a .ipynb (nbformat v4) JSON string. Raw cells are dropped. */
+export function parseIpynb(json) {
+    let obj;
+    try {
+        obj = JSON.parse(json);
+    }
+    catch {
+        throw new Error('not valid JSON');
+    }
+    const cellsRaw = obj?.cells;
+    if (!Array.isArray(cellsRaw))
+        throw new Error('not a Jupyter notebook (no cells array)');
+    const cells = [];
+    for (const c of cellsRaw) {
+        if (!c || typeof c !== 'object')
+            continue;
+        const t = c.cell_type;
+        if (t !== 'code' && t !== 'markdown')
+            continue;
+        const srcRaw = c.source;
+        const source = Array.isArray(srcRaw) ? srcRaw.join('') : typeof srcRaw === 'string' ? srcRaw : '';
+        const cell = { kind: t, source: source.replace(/\s+$/, ''), result: null };
+        if (t === 'code') {
+            const outs = c.outputs;
+            if (Array.isArray(outs) && outs.length > 0)
+                cell.rawOutputs = outs;
+            const ec = c.execution_count;
+            cell.rawExecCount = typeof ec === 'number' ? ec : null;
+        }
+        cells.push(cell);
+    }
+    return cells;
+}
+/**
+ * Split a Python script into cells on `# %%` markers (jupytext percent
+ * format; the arena starter uses the same markers). Marker lines are
+ * separators and are dropped. No markers → the whole file is one cell.
+ */
+export function parsePercentPy(text) {
+    const cells = [];
+    let cur = [];
+    const flush = () => {
+        const src = cur.join('\n').replace(/^\n+/, '').replace(/\s+$/, '');
+        if (src)
+            cells.push({ kind: 'code', source: src, result: null });
+        cur = [];
+    };
+    for (const line of text.split('\n')) {
+        if (/^#\s*%%/.test(line))
+            flush();
+        else
+            cur.push(line);
+    }
+    flush();
+    return cells;
+}
+/** Map one cell's outputs to nbformat: fresh result wins over disk outputs. */
+function outputsToNbformat(cell) {
+    if (cell.result) {
+        const outs = [];
+        for (const o of cell.result.outputs) {
+            if (o.kind === 'stream')
+                outs.push({ output_type: 'stream', name: o.name, text: o.text });
+            else if (o.kind === 'result')
+                outs.push({
+                    output_type: 'execute_result',
+                    execution_count: cell.result.execCount,
+                    data: o.data ?? { 'text/plain': o.text },
+                    metadata: {},
+                });
+            else if (o.kind === 'display')
+                outs.push({ output_type: 'display_data', data: o.data, metadata: {} });
+            else
+                outs.push({ output_type: 'error', ename: o.ename, evalue: o.evalue, traceback: o.traceback });
+        }
+        return { outputs: outs, execution_count: cell.result.execCount };
+    }
+    return { outputs: cell.rawOutputs ?? [], execution_count: cell.rawExecCount ?? null };
+}
+/** Serialize cells to a Jupyter-openable nbformat v4.5 JSON string. */
+export function serializeIpynb(cells) {
+    const nb = {
+        nbformat: 4,
+        nbformat_minor: 5,
+        metadata: {
+            kernelspec: { display_name: 'Python 3', language: 'python', name: 'python3' },
+            language_info: { name: 'python', version: '3.12' },
+        },
+        cells: cells.map((c) => c.kind === 'markdown'
+            ? { cell_type: 'markdown', metadata: {}, source: c.source }
+            : { cell_type: 'code', metadata: {}, source: c.source, ...outputsToNbformat(c) }),
+    };
+    return `${JSON.stringify(nb, null, 1)}\n`;
+}
+/** One-char run state for the `cells` listing. */
+export function statusChar(cell) {
+    if (cell.kind === 'markdown')
+        return 'md';
+    if (cell.result === null)
+        return '○';
+    return cell.result.ok ? '✓' : '✗';
+}
+/** First non-blank line, trimmed and truncated to `width` (with ellipsis). */
+export function cellPreview(cell, width) {
+    const first = cell.source.split('\n').find((l) => l.trim() !== '') ?? '';
+    const t = first.trim();
+    if (t.length <= width)
+        return t;
+    return `${t.slice(0, Math.max(0, width - 1))}…`;
+}
+/** Parse `run` arguments: '3' → [3], '1-5' → [1..5], 'all' → [1..count].
+ *  1-based, validated against count; null = not a valid range. */
+export function parseRunRange(arg, count) {
+    const a = arg.trim().toLowerCase();
+    if (!a)
+        return null;
+    if (a === 'all')
+        return Array.from({ length: count }, (_, i) => i + 1);
+    const m = a.match(/^(\d+)(?:-(\d+))?$/);
+    if (!m)
+        return null;
+    const from = Number(m[1]);
+    const to = m[2] ? Number(m[2]) : from;
+    if (from < 1 || to < from || to > count)
+        return null;
+    return Array.from({ length: to - from + 1 }, (_, i) => from + i);
+}

package/dist/lib/open-file.js

@@ -1 +1,55 @@
-import{spawn as e,execFileSync as r}from"node:child_process";export function openFileCommand(e,r=process.platform,n=process.env){return"darwin"===r?{cmd:"open",args:[e]}:"win32"===r?{cmd:"cmd.exe",args:["/c","start","",e]}:function(e){return!(!e.WSL_DISTRO_NAME&&!e.WSL_INTEROP)}(n)?{cmd:"explorer.exe",args:[e]}:{cmd:"xdg-open",args:[e]}}export function openFile(n){const{cmd:o,args:t}=openFileCommand(n);let c=t;if("explorer.exe"===o)try{const e=r("wslpath",["-w",n],{encoding:"utf-8"}).trim();e&&(c=[e])}catch{}try{return e(o,c,{stdio:"ignore",detached:!0}).unref(),!0}catch{return!1}}
+/**
+ * Cross-platform "open this file in the OS default app".
+ *
+ * Pure core `openFileCommand(path, platform, env)` → {cmd, args} is unit-testable
+ * across all four baseline targets without spawning; `openFile(path)` is the thin
+ * spawn wrapper. Extracted from arena.ts so `ipynb` (auto-open saved figures) and
+ * `arena` (open the downloaded baseline) share ONE opener — notably the WSL branch:
+ * xdg-open silently fails under WSL, so the file must be handed to Windows via
+ * explorer.exe — AND the Linux path must be translated to a Windows path first
+ * (explorer.exe can't resolve `/home/...`), else it "opens" nothing.
+ */
+import { spawn, execFileSync } from 'node:child_process';
+/** True when running under WSL. WSL2 sets WSL_DISTRO_NAME; WSL_INTEROP is also
+ *  present and survives some shells/sudo invocations that drop WSL_DISTRO_NAME. */
+function isWsl(env) {
+    return !!(env.WSL_DISTRO_NAME || env.WSL_INTEROP);
+}
+/** Decide the OS "open" command for `path`. Pure — platform + env are injected
+ *  so every baseline target (macOS / Linux / WSL / Windows) is unit-testable. */
+export function openFileCommand(path, platform = process.platform, env = process.env) {
+    if (platform === 'darwin')
+        return { cmd: 'open', args: [path] };
+    if (platform === 'win32')
+        return { cmd: 'cmd.exe', args: ['/c', 'start', '', path] };
+    // WSL has no Linux GUI — xdg-open silently fails. Hand the file to Windows.
+    if (isWsl(env))
+        return { cmd: 'explorer.exe', args: [path] };
+    return { cmd: 'xdg-open', args: [path] };
+}
+/** Open `path` in the OS default app (detached). Returns false if spawn throws. */
+export function openFile(path) {
+    const { cmd, args } = openFileCommand(path);
+    let finalArgs = args;
+    // explorer.exe cannot resolve a Linux path (`/home/...`). Translate it to a
+    // Windows path (`\\wsl.localhost\<distro>\...`) via wslpath so the Windows
+    // default app actually opens the file. Without this, view "succeeds" silently
+    // but nothing appears — the WSL bug students hit.
+    if (cmd === 'explorer.exe') {
+        try {
+            const win = execFileSync('wslpath', ['-w', path], { encoding: 'utf-8' }).trim();
+            if (win)
+                finalArgs = [win];
+        }
+        catch {
+            /* wslpath unavailable — fall back to the raw path */
+        }
+    }
+    try {
+        spawn(cmd, finalArgs, { stdio: 'ignore', detached: true }).unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}