cyberhub-pracenv 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to **cyberhub-pracenv** (`chpe`) are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.1] - 2026-06-26
+
+### Added
+- **`changelog` command** — view this changelog from inside the platform so you
+  can see what has changed across versions without leaving the shell.
+- **`requirements` command (alias `rq`)** — show the rank ladder and how many
+  more points are needed to reach the next rank. The rank thresholds now live in
+  one place (`ui.RANKS`) shared by `rankFor` and this view.
+- **`scoreboard` command** — an operative leaderboard listing every user with
+  their rank, points, and solved count. A secret `sb` shortcut is also available.
+- A secret `ch` shortcut for the `challenges`/`ls` listing.
+
+### Changed
+- `help` now lists the `changelog`, `requirements`, and `scoreboard` commands.
+  The `ch` and `sb` shortcuts are intentionally left undocumented.
+
+## [1.1.0] - 2026-06-25
+
+### Fixed
+- **Uploaded challenges no longer disappear after a restart.** Challenges created
+  with `upload` (and files attached with `addfile`) are now mirrored into the
+  bundled `data/challenges/` seed, and launch-time seeding now *tops up* any
+  challenge missing from the per-user data dir instead of only seeding when it is
+  empty. A reset or wiped `~/.cyberhub-pracenv/` is restored from the seed, so
+  uploads survive restarts and reinstalls and are version-control friendly. The
+  seed mirror is best-effort, so a read-only install location can never break an
+  upload.
+
+### Changed
+- **Reworked the `stats` command** into a full breakdown: an overall progress bar,
+  a progress bar per difficulty, a progress bar per category, and a detailed table
+  of solved challenges (id, title, category, difficulty, points) sorted by
+  difficulty. Solved entries that no longer exist are flagged.
+
+### Added
+- Progress-bar renderer (`ui.progressBar`) used throughout the new `stats` view.
+- `CHANGELOG.md` (this file).
+- `CHPE_SEED_DIR` environment override so tests redirect the seed/mirror location
+  away from the real project data; added regression tests covering upload
+  persistence across a data-dir reset.
+
+## [1.0.0] - 2026-06-25
+
+### Added
+- Initial release: a fully terminal-based, beginner-friendly CTF practice platform
+  in the ICOA terminal style, installed globally and run as an interactive shell.
+- Commands: `challenges`/`ls`, `open`, `files`, `cat`, `get`, `submit`, `stats`,
+  `admin`, `clear`, `help`, `exit`, plus admin commands `upload`, `addfile`,
+  `rmchallenge`, `passwd`, `logout`.
+- Single local profile with points, ranks, and per-category progress; admin mode
+  unlocked by a password (default `admin`).
+- YAML-based challenges with attached files, seeded from a bundled sample set into
+  `~/.cyberhub-pracenv/` on first run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberhub-pracenv",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "A beginner-friendly, fully terminal-based cybersecurity (CTF) practice platform in the ICOA terminal style.",
   "keywords": [
     "cybersecurity",
@@ -24,7 +24,8 @@
     "bin/",
     "src/",
     "data/",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "start": "node bin/cyberhub.js",

package/src/commands.js

@@ -6,6 +6,7 @@
 //
 // The command table at the bottom drives both dispatch and the `help` listing.
 
+const fs = require('fs');
 const path = require('path');
 const store = require('./store');
 const auth = require('./auth');
@@ -38,6 +39,9 @@ function cmdHelp(ctx) {
     ['get <id> <file>', 'Copy an attached file into your launch directory'],
     ['submit <id> <flag>', 'Submit a flag to solve a challenge'],
     ['stats (whoami)', 'Show your full user breakdown'],
+    ['scoreboard', 'Show the operative leaderboard'],
+    ['requirements (rq)', 'Show the points needed to rank up'],
+    ['changelog', 'Show what has changed across versions'],
     ['admin', 'Unlock admin mode (requires the admin password)'],
     ['clear', 'Clear the screen'],
     ['help', 'Show this help'],
@@ -198,21 +202,50 @@ function cmdSubmit(ctx, args) {
   }
 }
 
+// Known difficulties listed in ramp-up order; anything else sorts after these
+// alphabetically so custom difficulties still appear.
+const DIFFICULTY_ORDER = ['easy', 'medium', 'hard', 'insane', 'expert', 'elite'];
+
+function difficultyRank(diff) {
+  const i = DIFFICULTY_ORDER.indexOf(String(diff).toLowerCase());
+  return i === -1 ? DIFFICULTY_ORDER.length : i;
+}
+
+// Print a list of "label  progress-bar" lines with the labels padded to a
+// common width so the bars line up.
+function printBarGroup(ctx, entries) {
+  if (entries.length === 0) return;
+  const labelWidth = Math.max(...entries.map((e) => e.label.length));
+  for (const e of entries) {
+    const label = e.label + ' '.repeat(labelWidth - e.label.length);
+    print(ctx, `    ${c.accent(label)}  ${ui.progressBar(e.solved, e.total)}`);
+  }
+}
+
 function cmdStats(ctx) {
   const profile = store.getProfile();
   const challenges = store.listChallenges();
   const total = challenges.length;
+  const solvedSet = new Set(profile.solved);
   const solvedCount = profile.solved.length;
 
-  // Per-category progress.
+  // Bucket challenges by difficulty and category for the progress breakdowns.
+  const byDiff = {};
   const byCat = {};
   for (const ch of challenges) {
+    const diff = (ch.difficulty || 'unknown').toLowerCase();
     const cat = ch.category || 'misc';
+    byDiff[diff] = byDiff[diff] || { total: 0, solved: 0 };
     byCat[cat] = byCat[cat] || { total: 0, solved: 0 };
+    byDiff[diff].total += 1;
     byCat[cat].total += 1;
-    if (profile.solved.includes(ch.id)) byCat[cat].solved += 1;
+    if (solvedSet.has(ch.id)) {
+      byDiff[diff].solved += 1;
+      byCat[cat].solved += 1;
+    }
   }
 
+  // --- Summary -------------------------------------------------------------
   print(ctx, c.title('User breakdown'));
   print(ctx, `  ${c.bold('Operative')}    : ${profile.name}`);
   print(ctx, `  ${c.bold('Rank')}         : ${c.accent(ui.rankFor(profile.points))}`);
@@ -222,26 +255,65 @@ function cmdStats(ctx) {
   print(ctx, `  ${c.bold('Member since')} : ${new Date(profile.createdAt).toLocaleString()}`);
   print(ctx, `  ${c.bold('Admin mode')}   : ${auth.isAdmin() ? c.ok('ON') : c.dim('off')}`);
 
+  // --- Overall progress bar ------------------------------------------------
+  print(ctx, '', c.bold('  Overall progress:'));
+  print(ctx, `    ${ui.progressBar(solvedCount, total)}`);
+
+  // --- Progress bar per difficulty ----------------------------------------
+  print(ctx, '', c.bold('  Progress by difficulty:'));
+  const diffEntries = Object.keys(byDiff)
+    .sort((a, b) => difficultyRank(a) - difficultyRank(b) || a.localeCompare(b))
+    .map((diff) => ({ label: diff, solved: byDiff[diff].solved, total: byDiff[diff].total }));
+  if (diffEntries.length > 0) {
+    printBarGroup(ctx, diffEntries);
+  } else {
+    print(ctx, c.dim('    No challenges available yet.'));
+  }
+
+  // --- Progress bar per category ------------------------------------------
   print(ctx, '', c.bold('  Progress by category:'));
-  const catRows = Object.keys(byCat)
+  const catEntries = Object.keys(byCat)
     .sort()
-    .map((cat) => ({
-      category: cat,
-      progress: `${byCat[cat].solved} / ${byCat[cat].total}`,
-    }));
-  if (catRows.length > 0) {
-    print(ctx, ui.table(catRows, [
-      { key: 'category', label: 'Category', color: c.accent },
-      { key: 'progress', label: 'Solved' },
-    ]));
+    .map((cat) => ({ label: cat, solved: byCat[cat].solved, total: byCat[cat].total }));
+  if (catEntries.length > 0) {
+    printBarGroup(ctx, catEntries);
+  } else {
+    print(ctx, c.dim('    No challenges available yet.'));
   }
 
-  if (solvedCount > 0) {
-    print(ctx, '', c.bold('  Solved challenges:'));
-    for (const id of profile.solved) {
-      const ch = store.getChallenge(id);
-      print(ctx, '    ' + c.ok('✔ ') + c.accent(id) + (ch ? c.dim('  ' + ch.title) : ''));
-    }
+  // --- Detailed breakdown of solved challenges ----------------------------
+  print(ctx, '', c.bold('  Solved challenges:'));
+  if (solvedCount === 0) {
+    print(ctx, c.dim('    Nothing solved yet — run `challenges` to get started.'));
+    return;
+  }
+  const solvedRows = profile.solved
+    .map((id) => store.getChallenge(id))
+    .filter(Boolean)
+    .sort(
+      (a, b) =>
+        difficultyRank(a.difficulty) - difficultyRank(b.difficulty) ||
+        String(a.id).localeCompare(String(b.id))
+    )
+    .map((ch) => ({
+      id: ch.id,
+      title: ch.title,
+      category: ch.category,
+      difficulty: ch.difficulty,
+      points: ch.points,
+    }));
+  print(ctx, ui.table(solvedRows, [
+    { key: 'id', label: 'ID', color: c.accent },
+    { key: 'title', label: 'Title' },
+    { key: 'category', label: 'Category' },
+    { key: 'difficulty', label: 'Difficulty' },
+    { key: 'points', label: 'Pts', color: c.ok },
+  ]));
+
+  // Note any solved ids whose challenge file is no longer present.
+  const missing = profile.solved.filter((id) => !store.getChallenge(id));
+  if (missing.length > 0) {
+    print(ctx, c.dim(`    (${missing.length} solved challenge(s) no longer exist: ${missing.join(', ')})`));
   }
 }
 
@@ -377,6 +449,83 @@ function cmdClear(ctx) {
   print(ctx, c.title('CyberHub Practice Environment') + c.dim('  —  type `help` for commands'));
 }
 
+// Show the bundled CHANGELOG.md so operatives can see what has changed without
+// leaving the platform. The markdown is lightly styled for the terminal.
+function cmdChangelog(ctx) {
+  const file = path.join(__dirname, '..', 'CHANGELOG.md');
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (_err) {
+    print(ctx, c.err('Changelog is not available.'));
+    return;
+  }
+  print(ctx, c.title('Changelog'));
+  for (const line of text.replace(/\s+$/, '').split('\n')) {
+    if (/^#{1,6}\s/.test(line)) {
+      print(ctx, c.accent(line.replace(/^#{1,6}\s+/, '')));
+    } else if (/^\s*[-*]\s/.test(line)) {
+      print(ctx, c.dim('  • ') + line.replace(/^\s*[-*]\s+/, ''));
+    } else {
+      print(ctx, line);
+    }
+  }
+}
+
+// Show the rank ladder and how far the operative is from the next rank.
+function cmdRequirements(ctx) {
+  const profile = store.getProfile();
+  const points = profile.points || 0;
+  const current = ui.rankFor(points);
+
+  print(ctx, c.title('Rank requirements'));
+  const rows = ui.RANKS.map((r) => ({
+    cur: r.name === current ? '➤' : ' ',
+    rank: r.name,
+    points: r.min,
+  }));
+  print(ctx, ui.table(rows, [
+    { key: 'cur', label: ' ', color: c.ok },
+    { key: 'rank', label: 'Rank', color: c.accent },
+    { key: 'points', label: 'Min points' },
+  ]));
+
+  print(ctx, '');
+  print(ctx, ` ${c.bold('You')} : ${c.accent(current)} with ${c.ok(points)} pts`);
+  const next = ui.nextRank(points);
+  if (next) {
+    print(ctx, c.dim(` ${next.min - points} more point(s) to reach ${next.name}.`));
+  } else {
+    print(ctx, c.dim(' You have reached the top rank. Outstanding.'));
+  }
+}
+
+// Show a leaderboard of operatives. The platform uses a single local profile,
+// so the scoreboard ranks that operative — but it is built to render any number
+// of profiles so it keeps working if more are ever added.
+function cmdScoreboard(ctx) {
+  const total = store.listChallenges().length;
+  const users = [store.getProfile()];
+  const rows = users
+    .slice()
+    .sort((a, b) => (b.points || 0) - (a.points || 0))
+    .map((u, i) => ({
+      pos: i + 1,
+      name: u.name,
+      rank: ui.rankFor(u.points || 0),
+      points: u.points || 0,
+      solved: `${(u.solved || []).length}/${total}`,
+    }));
+  print(ctx, c.title('Scoreboard'));
+  print(ctx, ui.table(rows, [
+    { key: 'pos', label: '#', color: c.dim },
+    { key: 'name', label: 'Operative', color: c.accent },
+    { key: 'rank', label: 'Rank' },
+    { key: 'points', label: 'Pts', color: c.ok },
+    { key: 'solved', label: 'Solved' },
+  ]));
+}
+
 function cmdExit(ctx) {
   print(ctx, c.dim('Stay sharp. Goodbye.'));
   ctx.requestExit();
@@ -391,6 +540,7 @@ const COMMANDS = {
   '?': cmdHelp,
   challenges: cmdChallenges,
   ls: cmdChallenges,
+  ch: cmdChallenges, // secret shortcut (intentionally undocumented)
   open: cmdOpen,
   show: cmdOpen,
   files: cmdFiles,
@@ -401,6 +551,11 @@ const COMMANDS = {
   stats: cmdStats,
   whoami: cmdStats,
   profile: cmdStats,
+  scoreboard: cmdScoreboard,
+  sb: cmdScoreboard, // secret shortcut (intentionally undocumented)
+  requirements: cmdRequirements,
+  rq: cmdRequirements,
+  changelog: cmdChangelog,
   admin: cmdAdmin,
   login: cmdAdmin,
   logout: cmdLogout,

package/src/store.js

@@ -26,8 +26,15 @@ const FILES_DIR = path.join(DATA_DIR, 'files');
 const CONFIG_PATH = path.join(DATA_DIR, 'config.json');
 const PROFILE_PATH = path.join(DATA_DIR, 'profile.json');
 
-// Bundled seed data shipped with the package.
-const SEED_DIR = path.join(__dirname, '..', 'data', 'challenges');
+// Bundled seed data shipped with the package. Uploaded challenges are mirrored
+// back into here so they (a) live alongside the project and are version-control
+// friendly, and (b) survive a wipe/reset of the per-user data dir — the seeding
+// step below tops the user dir back up from this directory on every launch.
+// CHPE_SEED_DIR lets tests redirect the seed/mirror location so they never write
+// into the real bundled project data.
+const SEED_DIR = process.env.CHPE_SEED_DIR
+  ? path.resolve(process.env.CHPE_SEED_DIR)
+  : path.join(__dirname, '..', 'data', 'challenges');
 const SEED_FILES_DIR = path.join(SEED_DIR, 'files');
 
 const DEFAULT_ADMIN_PASSWORD = 'admin';
@@ -90,17 +97,29 @@ function init() {
     });
   }
 
-  // Seed sample challenges + their files only when the user has none yet.
-  if (listChallengeIds().length === 0) {
-    if (fs.existsSync(SEED_DIR)) {
-      for (const entry of fs.readdirSync(SEED_DIR)) {
-        if (entry.endsWith('.yml') || entry.endsWith('.yaml')) {
-          fs.copyFileSync(path.join(SEED_DIR, entry), path.join(CHALLENGES_DIR, entry));
-        }
+  // Top the user dir up from the bundled seed on every launch: copy across any
+  // challenge (and its files) that the seed has but the user dir is missing.
+  // This both provides the starter set on first run and restores challenges —
+  // including ones uploaded in a previous session and mirrored into the seed —
+  // if the per-user data dir was emptied or reset. Existing user challenges are
+  // never overwritten.
+  if (fs.existsSync(SEED_DIR)) {
+    for (const entry of fs.readdirSync(SEED_DIR)) {
+      if (!entry.endsWith('.yml') && !entry.endsWith('.yaml')) continue;
+      const dest = path.join(CHALLENGES_DIR, entry);
+      if (!fs.existsSync(dest)) {
+        fs.copyFileSync(path.join(SEED_DIR, entry), dest);
       }
     }
-    if (fs.existsSync(SEED_FILES_DIR)) {
-      copyRecursive(SEED_FILES_DIR, FILES_DIR);
+  }
+  if (fs.existsSync(SEED_FILES_DIR)) {
+    for (const id of fs.readdirSync(SEED_FILES_DIR)) {
+      const srcDir = path.join(SEED_FILES_DIR, id);
+      if (!fs.statSync(srcDir).isDirectory()) continue;
+      const destDir = path.join(FILES_DIR, id);
+      if (!fs.existsSync(destDir)) {
+        copyRecursive(srcDir, destDir);
+      }
     }
   }
 }
@@ -229,6 +248,16 @@ function createChallenge(challenge) {
   return id;
 }
 
+// Mirror a write into the bundled seed directory. Best-effort: a read-only
+// install location (e.g. a global npm prefix) must never break an upload.
+function mirrorToSeed(fn) {
+  try {
+    fn();
+  } catch (_err) {
+    /* seed mirror is optional; ignore failures */
+  }
+}
+
 function saveChallenge(challenge) {
   ensureDir(CHALLENGES_DIR);
   const id = String(challenge.id).trim();
@@ -242,7 +271,14 @@ function saveChallenge(challenge) {
     flag: challenge.flag || '',
     files: Array.isArray(challenge.files) ? challenge.files : [],
   };
-  fs.writeFileSync(challengePath(id), yaml.dump(doc, { lineWidth: 100 }), 'utf8');
+  const text = yaml.dump(doc, { lineWidth: 100 });
+  fs.writeFileSync(challengePath(id), text, 'utf8');
+  // Also persist into the bundled seed so the challenge lives with the project
+  // and is restored if the per-user data dir is ever reset.
+  mirrorToSeed(() => {
+    ensureDir(SEED_DIR);
+    fs.writeFileSync(path.join(SEED_DIR, `${id}.yml`), text, 'utf8');
+  });
 }
 
 function deleteChallenge(id) {
@@ -259,6 +295,15 @@ function deleteChallenge(id) {
   if (fs.existsSync(dir)) {
     fs.rmSync(dir, { recursive: true, force: true });
   }
+  // Remove the seed mirror too, otherwise the challenge would be restored on the
+  // next launch by the top-up seeding step.
+  mirrorToSeed(() => {
+    for (const f of [path.join(SEED_DIR, `${id}.yml`), path.join(SEED_DIR, `${id}.yaml`)]) {
+      if (fs.existsSync(f)) fs.unlinkSync(f);
+    }
+    const seedFileDir = path.join(SEED_FILES_DIR, id);
+    if (fs.existsSync(seedFileDir)) fs.rmSync(seedFileDir, { recursive: true, force: true });
+  });
   return removed;
 }
 
@@ -296,6 +341,13 @@ function attachFile(id, sourcePath) {
   ensureDir(challengeFileDir(id));
   fs.copyFileSync(sourcePath, challengeFilePath(id, name));
 
+  // Mirror the attached file into the bundled seed alongside the challenge yml.
+  mirrorToSeed(() => {
+    const seedFileDir = path.join(SEED_FILES_DIR, id);
+    ensureDir(seedFileDir);
+    fs.copyFileSync(sourcePath, path.join(seedFileDir, name));
+  });
+
   if (!challenge.files.includes(name)) {
     challenge.files.push(name);
     saveChallenge(challenge);

package/src/ui.js

@@ -80,12 +80,45 @@ function table(rows, columns) {
   return [header, sep, ...body].join('\n');
 }
 
+// Render a text progress bar: filled blocks for the done portion, dim blocks for
+// the rest, followed by a `done/total (pct%)` readout. A fully-complete bar is
+// highlighted green; partial progress is cyan.
+function progressBar(done, total, width = 24) {
+  const safeTotal = Math.max(0, Number(total) || 0);
+  const safeDone = Math.max(0, Math.min(Number(done) || 0, safeTotal));
+  const ratio = safeTotal > 0 ? safeDone / safeTotal : 0;
+  const filled = Math.round(ratio * width);
+  const pct = Math.round(ratio * 100);
+  const complete = safeTotal > 0 && safeDone === safeTotal;
+  const fillColor = complete ? c.ok : c.accent;
+  const bar = fillColor('█'.repeat(filled)) + c.dim('░'.repeat(width - filled));
+  return `${bar} ${safeDone}/${safeTotal} ${c.dim(`(${pct}%)`)}`;
+}
+
+// The rank ladder: the minimum points required to hold each rank, ascending.
+// rankFor() and the in-platform `requirements` command both read from this so
+// the thresholds live in exactly one place.
+const RANKS = [
+  { name: 'Recruit', min: 0 },
+  { name: 'Script Kiddie', min: 100 },
+  { name: 'Pentester', min: 300 },
+  { name: 'Operator', min: 600 },
+  { name: 'Elite', min: 1000 },
+];
+
 function rankFor(points) {
-  if (points >= 1000) return 'Elite';
-  if (points >= 600) return 'Operator';
-  if (points >= 300) return 'Pentester';
-  if (points >= 100) return 'Script Kiddie';
-  return 'Recruit';
+  const pts = Number(points) || 0;
+  let rank = RANKS[0].name;
+  for (const r of RANKS) {
+    if (pts >= r.min) rank = r.name;
+  }
+  return rank;
+}
+
+// The next rank above the given points, or null if already at the top.
+function nextRank(points) {
+  const pts = Number(points) || 0;
+  return RANKS.find((r) => r.min > pts) || null;
 }
 
 module.exports = {
@@ -93,5 +126,8 @@ module.exports = {
   BANNER,
   welcomeScreen,
   table,
+  progressBar,
+  RANKS,
   rankFor,
+  nextRank,
 };