ronin-skillforce 0.0.0-stage → 0.2.0-beta.0

package/bin/commands/archive.js

@@ -0,0 +1,192 @@
+/**
+ * `skillforce archive <slug> [--json]` — retire a course without losing learner work.
+ *
+ * - Copies the whole `learning/<slug>/` directory, minus `.git`, to
+ *   `.course_archive/<slug>[-N]` (an existing archive is never overwritten).
+ * - Programming courses keep their commits on branch `archive/<slug>` instead of `-D`.
+ * - Plain-folder courses are removed only after the copy is verified.
+ */
+import { execFileSync } from 'child_process';
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+} from 'fs';
+import { basename, join, relative } from 'path';
+import { listWorktrees, saveCourse, excludeRepoPath, SLUG_RE } from './create.js';
+import { style } from '../registry-helpers.js';
+
+function git(cwd, args) {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+}
+
+function tryGit(cwd, args) {
+  try { return git(cwd, args); } catch { return null; }
+}
+
+/** First non-existing path among `<base>`, `<base>-2`, `<base>-3`, … */
+export function nextFreePath(base) {
+  if (!existsSync(base)) return base;
+  for (let n = 2; ; n++) {
+    const candidate = `${base}-${n}`;
+    if (!existsSync(candidate)) return candidate;
+  }
+}
+
+function nextFreeBranch(cwd, base) {
+  if (tryGit(cwd, ['rev-parse', '--verify', '-q', `refs/heads/${base}`]) === null) return base;
+  for (let n = 2; ; n++) {
+    const candidate = `${base}-${n}`;
+    const exists = tryGit(cwd, ['rev-parse', '--verify', '-q', `refs/heads/${candidate}`]);
+    if (exists === null) return candidate;
+  }
+}
+
+/** Every entry under `dir`, as paths relative to it, skipping any `.git` entry. */
+function entries(dir, prefix = '') {
+  const out = [];
+  for (const name of readdirSync(dir).sort()) {
+    if (name === '.git') continue;
+    const rel = prefix ? join(prefix, name) : name;
+    const abs = join(dir, name);
+    const stat = lstatSync(abs);
+    out.push({ rel, stat });
+    if (stat.isDirectory()) out.push(...entries(abs, rel));
+  }
+  return out;
+}
+
+/** Throw unless every source entry exists in the copy with the same type and byte size. */
+export function verifyCopy(src, dest) {
+  for (const { rel, stat } of entries(src)) {
+    const copy = join(dest, rel);
+    if (!existsSync(copy)) throw new Error(`Archive copy is missing ${rel}.`);
+    const copied = lstatSync(copy);
+    if (copied.isDirectory() !== stat.isDirectory()) {
+      throw new Error(`Archive copy has the wrong type for ${rel}.`);
+    }
+    if (!stat.isDirectory() && copied.size !== stat.size) {
+      throw new Error(`Archive copy size differs for ${rel}.`);
+    }
+  }
+}
+
+/** Collapse multiline git stderr into one readable line. */
+function detail(err) {
+  return (err.stderr || err.message || '').toString().trim().split('\n')[0];
+}
+
+function archiveProgramming({ root, cwd, slug, courseDir, branch, target }) {
+  let archiveBranch = branch;
+  if (!branch || !branch.startsWith('archive/')) {
+    try {
+      saveCourse({ cwd, slug });
+    } catch (err) {
+      throw new Error(`Could not commit learning/${slug}/ — nothing was removed. ${detail(err)} ` +
+        `The copy is at ${relative(cwd, target)}.`);
+    }
+    const dirty = tryGit(courseDir, ['status', '--porcelain']);
+    if (dirty === null) {
+      throw new Error(`Could not read the status of learning/${slug}/ — nothing was removed. ` +
+        `The copy is at ${relative(cwd, target)}.`);
+    }
+    if (dirty !== '') {
+      throw new Error(`learning/${slug}/ still has uncommitted changes — nothing was removed. ` +
+        `The copy is at ${relative(cwd, target)}.`);
+    }
+    archiveBranch = nextFreeBranch(root, `archive/${slug}`);
+    try {
+      git(courseDir, ['branch', '-m', archiveBranch]);
+    } catch (err) {
+      throw new Error(`Could not rename the course branch to ${archiveBranch} — nothing was ` +
+        `removed. ${detail(err)} The copy is at ${relative(cwd, target)}.`);
+    }
+  }
+
+  try {
+    git(root, ['worktree', 'remove', courseDir]);
+  } catch (err) {
+    throw new Error(`Could not remove learning/${slug}/ (it is still registered on branch ` +
+      `${archiveBranch}). ${detail(err)} The copy is at ${relative(cwd, target)}.`);
+  }
+  return { archivedTo: relative(cwd, target), branch: archiveBranch, removed: true };
+}
+
+/**
+ * Archive one course. Throws with a user-facing message on any failure; the course is then
+ * still in `learning/<slug>/` unless the error says git removed it.
+ * @returns {{ archivedTo: string, branch: string|null, removed: boolean, warning?: string }}
+ */
+export function archiveCourse({ cwd, slug, verify = verifyCopy }) {
+  if (!SLUG_RE.test(slug || '')) {
+    throw new Error(`Invalid slug ${JSON.stringify(slug)} — use lowercase a-z, 0-9 and single hyphens.`);
+  }
+  const courseDir = join(cwd, 'learning', slug);
+  if (!existsSync(join(courseDir, 'COURSE.md'))) {
+    throw new Error(`No course at learning/${slug}/.`);
+  }
+
+  let warning;
+  const root = tryGit(cwd, ['rev-parse', '--show-toplevel']);
+  if (root) {
+    try {
+      excludeRepoPath(root, cwd, join(cwd, '.course_archive'));
+    } catch (err) {
+      warning = `Could not add .course_archive/ to git info/exclude: ${detail(err)}`;
+    }
+  }
+
+  const target = nextFreePath(join(cwd, '.course_archive', slug));
+  cpSync(courseDir, target, {
+    recursive: true,
+    filter: (source) => basename(source) !== '.git',
+  });
+  verify(courseDir, target);
+
+  const worktree = root
+    ? listWorktrees(root).find((tree) => tree.path === realpathSync.native(courseDir))
+    : null;
+  if (worktree) {
+    const result = archiveProgramming({ root, cwd, slug, courseDir, branch: worktree.branch, target });
+    return warning ? { ...result, warning } : result;
+  }
+
+  rmSync(courseDir, { recursive: true });
+  const result = { archivedTo: relative(cwd, target), branch: null, removed: true };
+  return warning ? { ...result, warning } : result;
+}
+
+function positionals(args) {
+  return args.filter((arg) => !arg.startsWith('-'));
+}
+
+/** CLI entry point for `skillforce archive`. */
+export async function run({ args = [], cwd = process.cwd() } = {}) {
+  const slug = positionals(args)[0];
+  const json = args.includes('--json');
+  try {
+    const result = archiveCourse({ cwd, slug });
+    if (json) {
+      console.log(JSON.stringify({
+        archivedTo: result.archivedTo,
+        branch: result.branch,
+        removed: result.removed,
+      }));
+      return;
+    }
+    console.log(style('success', `Archived learning/${slug}/ → ${result.archivedTo}`));
+    if (result.branch) console.log(style('info', `History kept on branch ${result.branch}.`));
+    if (result.warning) console.log(style('warning', result.warning));
+  } catch (err) {
+    if (json) console.log(JSON.stringify({ error: err.message }));
+    else console.error(style('error', err.message));
+    process.exitCode = 1;
+  }
+}

package/bin/commands/capstone-status.js

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join, relative } from 'path';
+import { resolveCourse } from './trail.js';
+import { style } from '../registry-helpers.js';
+
+const HEADER_RE = /^(\s*[-*]?\s*\*\*Capstone status\*\*\s*:?\s*).*$/mi;
+const EMOJI_RE = /(⬜|🔄|✅|🔒)/;
+const LIST_ROW_RE = /^\s*(?:[-*+]\s*)?(⬜|🔄|✅|🔒)/;
+
+export const CAPSTONE_STATES = {
+  locked: { emoji: '🔒', label: 'Locked', header: '🔒 Locked (complete all sections to unlock)' },
+  active: { emoji: '🔄', label: 'In progress', header: '🔄 In progress' },
+  done: { emoji: '✅', label: 'Complete', header: '✅ Complete' },
+};
+
+/** Keep the `**Capstone status**` header and the capstone row telling the same story. */
+export function setCapstoneStatus(text, status) {
+  const state = CAPSTONE_STATES[status];
+  if (!state) throw new Error(`Unknown capstone status "${status}" — use locked, active or done.`);
+  if (!HEADER_RE.test(text)) {
+    throw new Error('No **Capstone status** line in COURSE.md — nothing was updated.');
+  }
+
+  const lines = text.replace(HEADER_RE, (m, prefix) => `${prefix}${state.header}`).split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (!/capstone/i.test(lines[i])) continue;
+
+    if (/^\s*\|.*\|\s*$/.test(lines[i])) {
+      const cells = lines[i].split('|');
+      const at = cells.findIndex((c, idx) =>
+        idx > 0 && idx < cells.length - 1 && EMOJI_RE.test(c) && !/capstone/i.test(c));
+      if (at === -1) continue;
+      cells[at] = ` ${state.emoji} ${state.label} `;
+      lines[i] = cells.join('|');
+      continue;
+    }
+
+    if (LIST_ROW_RE.test(lines[i])) {
+      lines[i] = lines[i].replace(EMOJI_RE, state.emoji);
+    }
+  }
+  return lines.join('\n');
+}
+
+export function recordCapstoneStatus({ cwd, slug, status }) {
+  if (!slug) throw new Error('Pass the course slug — capstone-status never guesses which course to write.');
+  if (!status) throw new Error('Pass --set locked|active|done — nothing was updated.');
+  const found = resolveCourse(cwd, slug);
+  const path = join(found.dir, 'COURSE.md');
+  if (!existsSync(path)) throw new Error(`No COURSE.md in ${found.dir}`);
+  const next = setCapstoneStatus(readFileSync(path, 'utf-8'), status);
+  writeFileSync(path, next);
+  return { updated: true, path, section: found.slug, status };
+}
+
+function flagValue(args, name) {
+  const i = args.indexOf(name);
+  return i !== -1 && args[i + 1] !== undefined && !args[i + 1].startsWith('--') ? args[i + 1] : null;
+}
+
+function positionals(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--set') { i++; continue; }
+    if (!args[i].startsWith('--')) out.push(args[i]);
+  }
+  return out;
+}
+
+export async function run({ args = [], cwd = process.cwd() } = {}) {
+  const slug = positionals(args)[0] || null;
+  const json = args.includes('--json');
+  try {
+    const r = recordCapstoneStatus({ cwd, slug, status: flagValue(args, '--set') });
+    if (json) console.log(JSON.stringify(r));
+    else console.log(style('success', `Capstone status set to ${r.status} in ${relative(cwd, r.path)}`));
+  } catch (err) {
+    if (json) console.log(JSON.stringify({ error: err.message }));
+    else console.error(style('error', err.message));
+    process.exitCode = 1;
+  }
+}

package/bin/commands/check.js

@@ -0,0 +1,298 @@
+/**
+ * `skillforce check [slug]` — run the active exercise's self-checks
+ * with the right toolchain. Shows pass/fail per check, never solutions.
+ */
+import { appendFileSync, existsSync, readFileSync, statSync } from 'fs';
+import { join, extname } from 'path';
+import { spawn } from 'child_process';
+import inquirer from 'inquirer';
+import {
+  findCourses, parseLecture, readCourse, resolveExercise, todayISO,
+} from '../course-reader.js';
+import { resolveActiveCourse } from './next.js';
+import { style } from '../registry-helpers.js';
+
+const TIMEOUT_MS = 30000;
+
+function flagValue(args, name) {
+  const i = args.indexOf(name);
+  if (i === -1) return null;
+  const next = args[i + 1];
+  return next && !next.startsWith('--') ? next : true;
+}
+
+function positionals(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--dir') { i++; continue; }
+    if (args[i].startsWith('--')) continue;
+    out.push(args[i]);
+  }
+  return out;
+}
+
+/**
+ * Map a file extension to a runner strategy.
+ * @param {string} file
+ * @returns {{ kind: 'run'|'tsx'|'explain'|'rubric', cmd?: string, args?: string[], note?: string }}
+ */
+export function resolveRunner(file) {
+  const ext = extname(file).toLowerCase();
+  switch (ext) {
+    case '.py': return { kind: 'run', cmd: 'python3', args: [file] };
+    case '.js':
+    case '.mjs': return { kind: 'run', cmd: 'node', args: [file] };
+    case '.ts':
+    case '.tsx': return { kind: 'tsx', cmd: 'npx', args: ['--yes', 'tsx', file] };
+    case '.go': return { kind: 'run', cmd: 'go', args: ['run', file] };
+    case '.rs':
+      return { kind: 'explain', note: 'Rust: compile with `rustc <file> -o out && ./out`.' };
+    case '.sql':
+      return {
+        kind: 'explain',
+        note: 'SQL: no DB is configured — review the expected result in the file.',
+      };
+    case '.md': return { kind: 'rubric' };
+    default:
+      return {
+        kind: 'explain',
+        note: `No CLI runner for "${ext || 'this file'}" — open it and follow its instructions.`,
+      };
+  }
+}
+
+/**
+ * Parse self-check output into per-check pass/fail results.
+ * @param {{ stdout?: string, stderr?: string, code?: number }} result
+ * @returns {{ checks: object[], allPass: boolean, code: number, errorLine: string|null }}
+ */
+export function parseCheckOutput({ stdout = '', stderr = '', code = 0 } = {}) {
+  const checks = [];
+  const lines = `${stdout}\n${stderr}`.split('\n');
+  for (const line of lines) {
+    let m = line.match(/^\s*[✓✔]\s*(.+?)\s*$/);
+    if (m) { checks.push({ name: m[1], pass: true }); continue; }
+    m = line.match(/^\s*[✗✘×]\s*(.+?)\s*$/);
+    if (m) { checks.push({ name: m[1], pass: false }); continue; }
+    m = line.match(/^\s*PASS\s*[:—–-]\s*(.+?)\s*$/i);
+    if (m) { checks.push({ name: m[1], pass: true }); continue; }
+    m = line.match(/^\s*FAIL\s*[:—–-]\s*(.+?)\s*$/i);
+    if (m) { checks.push({ name: m[1], pass: false }); continue; }
+  }
+
+  const trimmed = lines.map((l) => l.trim()).filter(Boolean);
+  // `console.assert` (JS) and Python `assert` failures: the former does not set
+  // a non-zero exit code, so scan the output too.
+  const assertRe = /assert(ion)?\s*(error|fail(ed)?)|ERR_ASSERTION/i;
+  const assertion = trimmed.find((l) => assertRe.test(l)) || null;
+  const errorLine = assertion
+    || trimmed.find((l) => /assert|error:/i.test(l))
+    || trimmed.find((l) => /error|traceback|exception|not ok/i.test(l))
+    || trimmed[0] || null;
+
+  const allPass = code === 0 && !checks.some((c) => !c.pass) && !assertion;
+  return { checks, allPass, code, errorLine, assertionFailed: Boolean(assertion) };
+}
+
+function runProcess(cmd, args, cwd) {
+  return new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let child;
+    try {
+      child = spawn(cmd, args, { cwd, shell: false });
+    } catch (err) {
+      resolve({ stdout, stderr: err.message, code: 127 });
+      return;
+    }
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+    const timer = setTimeout(() => {
+      try { child.kill('SIGKILL'); } catch {}
+      finish({ stdout, stderr: `${stderr}\nTimed out after 30s`, code: 124 });
+    }, TIMEOUT_MS);
+
+    child.stdout?.on('data', (d) => { stdout += d; });
+    child.stderr?.on('data', (d) => { stderr += d; });
+    child.on('error', (err) => finish({ stdout, stderr: `${stderr}\n${err.message}`, code: 127 }));
+    child.on('close', (code) => finish({ stdout, stderr, code: code ?? 1 }));
+  });
+}
+
+function whichPath(cmd) {
+  const sep = process.platform === 'win32' ? ';' : ':';
+  const exts = process.platform === 'win32' ? ['.cmd', '.exe', ''] : [''];
+  for (const dir of (process.env.PATH || '').split(sep)) {
+    for (const ext of exts) {
+      const full = join(dir, cmd + ext);
+      try { if (statSync(full).isFile()) return full; } catch {}
+    }
+  }
+  return null;
+}
+
+function checklistFrom(filePath, lecture) {
+  if (filePath && existsSync(filePath)) {
+    const text = readFileSync(filePath, 'utf-8');
+    const items = text.split('\n')
+      .map((l) => l.match(/^\s*[-*]\s*\[[ xX]\]\s*(.+?)\s*$/))
+      .filter(Boolean)
+      .map((m) => m[1]);
+    if (items.length) return items;
+  }
+  return lecture?.successCriteria || [];
+}
+
+async function runRubric({ course, exerciseFile, lecture }) {
+  const items = checklistFrom(exerciseFile, lecture);
+
+  console.log('');
+  console.log(`  📋 Self-assessment: ${course.slug}`);
+  if (!items.length) {
+    console.log('  No rubric items found in the exercise. Read it and self-assess.');
+    console.log('');
+    return;
+  }
+  for (const [i, item] of items.entries()) console.log(`    ${i + 1}. ${item}`);
+  console.log('');
+
+  if (!process.stdin.isTTY) {
+    console.log(style('info', 'Run this in a terminal to self-assess each item (y/n).'));
+    console.log('');
+    return;
+  }
+
+  const answers = [];
+  for (const item of items) {
+    const { done } = await inquirer.prompt([{
+      type: 'confirm', name: 'done', message: item, default: true,
+    }]);
+    answers.push({ item, done });
+  }
+
+  const passed = answers.filter((a) => a.done).length;
+  const verdict = passed === answers.length ? 'solid' : '⚠️ needs work';
+  const section = course.currentSection
+    ? `${course.currentSection.n} — ${course.currentSection.title}`
+    : 'General';
+  const entry = [
+    '',
+    `### ${section}`,
+    '',
+    `- Date: ${todayISO()}`,
+    '- Check: self-assessed (CLI check)',
+    ...answers.map((a) => `- Q: "${a.item}" → A: ${a.done ? 'yes' : 'no'}`),
+    `- Verdict: ${verdict}`,
+    '',
+  ].join('\n');
+
+  const logPath = join(course.dir, 'LEARNING-LOG.md');
+  const header = existsSync(logPath) ? '' : '# Learning Log\n\n## 📝 Section Entries\n';
+  try {
+    appendFileSync(logPath, header + entry);
+    console.log('');
+    const saved = `Self-assessment saved (${passed}/${answers.length} criteria met).`;
+    console.log(style('success', saved));
+  } catch (err) {
+    console.log(style('warning', `Could not save self-assessment: ${err.message}`));
+  }
+  console.log('');
+}
+
+/**
+ * @param {{ args: string[], cwd?: string }} ctx
+ */
+export async function run({ args = [], cwd = process.cwd() } = {}) {
+  const slug = positionals(args)[0] || null;
+  const dir = flagValue(args, '--dir');
+  const courses = findCourses(cwd, { dir: typeof dir === 'string' ? dir : undefined });
+  if (courses.length === 0) {
+    console.log(style('info', 'No course found. Start one with /professor:new-topic.'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const descriptors = courses.map((c) => readCourse(c.dir, { slug: c.slug }));
+  const course = resolveActiveCourse(descriptors, slug);
+  if (!course) {
+    console.log(style('error', `Course "${slug}" not found.`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const lecturePath = join(course.dir, 'LECTURE.md');
+  const lecture = existsSync(lecturePath) ? parseLecture(readFileSync(lecturePath, 'utf-8')) : null;
+
+  const exercise = resolveExercise(course, { lecture });
+  if (!exercise.path) {
+    const hint = `No active exercise for "${course.slug}". Run professor:next first.`;
+    console.log(style('info', hint));
+    process.exitCode = 1;
+    return;
+  }
+  if (!exercise.exists) {
+    console.log('');
+    console.log(style('error', `Exercise not found: ${exercise.path}`));
+    console.log(`    Expected at: ${join(course.dir, exercise.path)}`);
+    console.log('    Run professor:next to create it.');
+    console.log('');
+    process.exitCode = 1;
+    return;
+  }
+
+  const exerciseFile = join(course.dir, exercise.path);
+  const runner = resolveRunner(exerciseFile);
+  console.log('');
+  console.log(style('info', `Check: ${course.slug} → ${exercise.path}`));
+
+  if (runner.kind === 'rubric') {
+    await runRubric({ course, exerciseFile, lecture });
+    return;
+  }
+
+  if (runner.kind === 'explain') {
+    console.log(`  ℹ️  ${runner.note}`);
+    console.log('');
+    return;
+  }
+
+  const tsxAvailable = whichPath('tsx')
+    || existsSync(join(course.dir, 'node_modules', '.bin', 'tsx'));
+  if (runner.kind === 'tsx' && !tsxAvailable) {
+    console.log('  ℹ️  TypeScript needs `tsx` (or `ts-node`) to run from the CLI.');
+    console.log('      Install it:  npm i -D tsx   — or run with `npx tsx <file>`.');
+    console.log('');
+    return;
+  }
+
+  const result = await runProcess(runner.cmd, runner.args, course.dir);
+  const parsed = parseCheckOutput(result);
+
+  if (parsed.checks.length) {
+    for (const check of parsed.checks) {
+      const mark = check.pass ? '✓' : '✗';
+      const line = `  ${mark} ${check.name}`;
+      console.log(check.pass ? line : style('error', line));
+    }
+  }
+
+  console.log('');
+  if (parsed.allPass) {
+    const message = parsed.checks.length
+      ? 'All checks passed.'
+      : 'Ran cleanly (no explicit checks).';
+    console.log(style('success', message));
+  } else {
+    console.log(style('error', `Check failed (exit ${parsed.code}). First error:`));
+    if (parsed.errorLine) console.log(`    ${parsed.errorLine}`);
+    console.log('    Fix it yourself, then run check again. (No solution given.)');
+    process.exitCode = 1;
+  }
+  console.log('');
+}