ronin-skillforce 0.0.0-stage → 0.1.0

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('');
+}

package/bin/commands/create.js

@@ -0,0 +1,169 @@
+/**
+ * `skillforce create <slug> --kind <kind>` — create the course folder the
+ * way `professor:new-topic` promises, so the agent never improvises it (RON-249).
+ *
+ * - `programming`: a registered git worktree at `learning/<slug>/` on branch
+ *   `learning/<slug>`, verified after creation; rolled back on any failure.
+ * - other kinds: a plain `learning/<slug>/` folder.
+ *
+ * `skillforce save <slug> [-m msg]` commits the course worktree so its
+ * state lives in git history, not only in untracked files.
+ */
+import { execFileSync } from 'child_process';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from 'fs';
+import { isAbsolute, join, relative } from 'path';
+import { COURSE_KINDS } from '../course-reader.js';
+import { style } from '../registry-helpers.js';
+
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+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; }
+}
+
+/** Registered worktrees as `{ path, branch }` (branch without `refs/heads/`). */
+export function listWorktrees(cwd) {
+  const out = tryGit(cwd, ['worktree', 'list', '--porcelain']) || '';
+  const trees = [];
+  for (const block of out.split('\n\n')) {
+    const path = block.match(/^worktree (.+)$/m)?.[1];
+    if (!path) continue;
+    const branch = block.match(/^branch refs\/heads\/(.+)$/m)?.[1] || null;
+    trees.push({ path: realpathSync.native(path), branch });
+  }
+  return trees;
+}
+
+function isCourseWorktree(cwd, dir, branch) {
+  if (!existsSync(dir)) return false;
+  const real = realpathSync.native(dir);
+  return listWorktrees(cwd).some((t) => t.path === real && t.branch === branch);
+}
+
+/** Keep `learning/` out of the host repo's `git status` without touching tracked files. */
+function excludeLearningDir(root, cwd) {
+  const probe = join(cwd, 'learning');
+  if (tryGit(root, ['check-ignore', '-q', probe]) !== null) return;
+  const commonDir = git(root, ['rev-parse', '--git-common-dir']);
+  const infoDir = join(isAbsolute(commonDir) ? commonDir : join(root, commonDir), 'info');
+  mkdirSync(infoDir, { recursive: true });
+  const excludeFile = join(infoDir, 'exclude');
+  const line = `/${relative(root, probe).split('\\').join('/')}/`;
+  const current = existsSync(excludeFile) ? readFileSync(excludeFile, 'utf-8') : '';
+  if (current.split('\n').includes(line)) return;
+  appendFileSync(excludeFile, `${current && !current.endsWith('\n') ? '\n' : ''}${line}\n`);
+}
+
+/**
+ * Create (or reattach) the course directory. Throws with a user-facing message.
+ * @returns {{ slug: string, kind: string, dir: string, branch: string|null, created: boolean }}
+ */
+export function createCourse({ cwd, slug, kind }) {
+  if (!SLUG_RE.test(slug || '')) {
+    throw new Error(`Invalid slug ${JSON.stringify(slug)} — use lowercase a-z, 0-9 and single hyphens.`);
+  }
+  if (!COURSE_KINDS.includes(kind)) {
+    throw new Error(`Invalid kind ${JSON.stringify(kind)} — use one of: ${COURSE_KINDS.join(', ')}.`);
+  }
+  const dir = join(cwd, 'learning', slug);
+
+  if (kind !== 'programming') {
+    const created = !existsSync(dir);
+    mkdirSync(dir, { recursive: true });
+    return { slug, kind, dir, branch: null, created };
+  }
+
+  const root = tryGit(cwd, ['rev-parse', '--show-toplevel']);
+  if (!root) {
+    throw new Error('Programming courses require a git repository. Run `git init` and make a first commit.');
+  }
+  if (tryGit(root, ['rev-parse', '--verify', '-q', 'HEAD']) === null) {
+    throw new Error('This git repository has no commits yet. Make a first commit, then retry.');
+  }
+
+  const branch = `learning/${slug}`;
+  if (isCourseWorktree(root, dir, branch)) {
+    excludeLearningDir(root, cwd);
+    return { slug, kind, dir, branch, created: false };
+  }
+  if (existsSync(dir)) {
+    throw new Error(`${relative(cwd, dir)}/ already exists but is not the ${branch} worktree. ` +
+      'Move it aside or pick another slug — nothing was changed.');
+  }
+
+  const branchExists = tryGit(root, ['rev-parse', '--verify', '-q', `refs/heads/${branch}`]) !== null;
+  try {
+    // Reattach an existing branch (course restored after its worktree was pruned).
+    git(root, ['worktree', 'add', dir, ...(branchExists ? [branch] : ['-b', branch])]);
+    if (!isCourseWorktree(root, dir, branch)) throw new Error('worktree is not registered after creation');
+  } catch (err) {
+    tryGit(root, ['worktree', 'remove', '--force', dir]);
+    if (!branchExists) tryGit(root, ['branch', '-D', branch]);
+    rmSync(dir, { recursive: true, force: true });
+    tryGit(root, ['worktree', 'prune']);
+    const detail = (err.stderr || err.message || '').toString().trim();
+    throw new Error(`Could not create the course worktree — nothing was kept. ${detail}`);
+  }
+  excludeLearningDir(root, cwd);
+  return { slug, kind, dir, branch, created: true };
+}
+
+/**
+ * Commit everything in a course worktree. No-op for plain-folder courses.
+ * @returns {{ committed: boolean, reason?: string }}
+ */
+export function saveCourse({ cwd, slug, message }) {
+  if (!SLUG_RE.test(slug || '')) throw new Error(`Invalid slug ${JSON.stringify(slug)}.`);
+  const dir = join(cwd, 'learning', slug);
+  if (!existsSync(join(dir, 'COURSE.md'))) throw new Error(`No course at learning/${slug}/.`);
+  if (!isCourseWorktree(cwd, dir, `learning/${slug}`)) {
+    return { committed: false, reason: 'not a course worktree (plain-folder course)' };
+  }
+  git(dir, ['add', '-A']);
+  if (tryGit(dir, ['diff', '--cached', '--quiet']) !== null) {
+    return { committed: false, reason: 'nothing to save' };
+  }
+  git(dir, ['commit', '-q', '--no-verify', '-m', message || `course(${slug}): save progress`]);
+  return { committed: true };
+}
+
+function flagValue(args, name) {
+  const i = args.indexOf(name);
+  return i !== -1 && args[i + 1] && !args[i + 1].startsWith('-') ? args[i + 1] : null;
+}
+
+function positionals(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    if (['--kind', '-m', '--message'].includes(args[i])) { i++; continue; }
+    if (!args[i].startsWith('-')) out.push(args[i]);
+  }
+  return out;
+}
+
+/** `create` and `save` share this module; cli.js passes the command name. */
+export async function run({ args = [], cwd = process.cwd(), command = 'create' } = {}) {
+  const slug = positionals(args)[0];
+  const json = args.includes('--json');
+  try {
+    const result = command === 'save'
+      ? saveCourse({ cwd, slug, message: flagValue(args, '-m') || flagValue(args, '--message') })
+      : createCourse({ cwd, slug, kind: flagValue(args, '--kind') || 'programming' });
+    if (json) console.log(JSON.stringify(result));
+    else if (command === 'save') {
+      console.log(style(result.committed ? 'success' : 'info',
+        result.committed ? `Saved learning/${slug}/` : `Not saved: ${result.reason}`));
+    } else {
+      const where = result.branch ? `git worktree on branch ${result.branch}` : 'plain folder';
+      console.log(style('success', `${result.created ? 'Created' : 'Reusing'} learning/${slug}/ (${where})`));
+    }
+  } catch (err) {
+    if (json) console.log(JSON.stringify({ error: err.message }));
+    else console.error(style('error', err.message));
+    process.exitCode = 1;
+  }
+}