ronin-skillforce 0.0.0-stage → 0.1.0

package/bin/commands/trail.js

@@ -0,0 +1,211 @@
+/**
+ * RON-250 — give Coach the real course and keep its review trail on disk.
+ *
+ * `skillforce context [slug] --json` prints one explicit context object (absolute course
+ * path, section, objectives, active exercise, recent trail) so Coach never guesses a path.
+ *
+ * `skillforce trail <slug> --stdin <<'EOF' {"learner","asked","concept","evidence?","watch?"} EOF`
+ * (or the same fields as `--learner ..` flags) appends one review round to `LEARNING-LOG.md` → `## 🗣️ Reasoning Trail` (max 5 rounds per
+ * section, oldest dropped), then commits programming course worktrees.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { isAbsolute, join, relative } from 'path';
+import { findCourses, parseLecture, readCourse, todayISO } from '../course-reader.js';
+import { saveCourse } from './create.js';
+import { style } from '../registry-helpers.js';
+
+export const MAX_ROUNDS = 5;
+const TRAIL_RE = /^##\s+.*reasoning trail/i;
+const ROUND_RE = /^Round\s+\d+\b/;
+
+/** Pick the course by slug; with no slug only a single course is accepted — never guess. */
+export function resolveCourse(cwd, slug) {
+  const courses = findCourses(cwd);
+  if (slug) {
+    const hit = courses.find((c) => c.slug === slug);
+    if (hit) return hit;
+    throw new Error(`No course "${slug}" under learning/ or courses/. Found: ${courses.map((c) => c.slug).join(', ') || 'none'}.`);
+  }
+  if (courses.length === 1) return courses[0];
+  if (!courses.length) throw new Error('No course found under learning/ or courses/. Run professor:new-topic first.');
+  throw new Error(`Several courses found — pass the slug: ${courses.map((c) => c.slug).join(', ')}.`);
+}
+
+const sectionKey = (section) => String(section).trim().split(/\s+/)[0];
+
+const sectionHeadRe = (key) =>
+  new RegExp(`^###\\s+Section\\s+${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(\\s|$)`);
+
+/** Lines of `### Section <key>` inside the trail region, or [] when absent. */
+function trailBlock(text, key) {
+  const lines = text.split('\n');
+  const t = lines.findIndex((l) => TRAIL_RE.test(l));
+  if (t === -1) return [];
+  const headRe = sectionHeadRe(key);
+  let h = -1;
+  for (let i = t + 1; i < lines.length && !/^##\s/.test(lines[i]); i++) {
+    if (headRe.test(lines[i])) { h = i; break; }
+  }
+  if (h === -1) return [];
+  let end = h + 1;
+  while (end < lines.length && !/^#{2,3}\s/.test(lines[end])) end++;
+  return lines.slice(h + 1, end);
+}
+
+/** Split a section block into preface lines (watch flags) and rounds (arrays of lines). */
+function splitRounds(block) {
+  const preface = [];
+  const rounds = [];
+  for (const line of block) {
+    if (ROUND_RE.test(line)) rounds.push([line]);
+    else if (rounds.length) { if (line.trim()) rounds[rounds.length - 1].push(line); }
+    else if (line.trim()) preface.push(line);
+  }
+  return { preface, rounds };
+}
+
+/** Explicit context Coach must use. */
+export function buildContext({ cwd, slug }) {
+  const found = resolveCourse(cwd, slug);
+  const course = readCourse(found.dir, { slug: found.slug });
+  const lecturePath = join(found.dir, 'LECTURE.md');
+  const lecture = existsSync(lecturePath) ? parseLecture(readFileSync(lecturePath, 'utf-8')) : null;
+  const logPath = join(found.dir, 'LEARNING-LOG.md');
+  const section = course.currentSection;
+  const block = section && existsSync(logPath)
+    ? trailBlock(readFileSync(logPath, 'utf-8'), String(section.n)) : [];
+  const { preface, rounds } = splitRounds(block);
+  const exercise = course.activeExercise
+    ? (isAbsolute(course.activeExercise) ? course.activeExercise : join(found.dir, course.activeExercise))
+    : null;
+  return {
+    slug: found.slug,
+    dir: found.dir,
+    kind: course.kind,
+    title: course.title,
+    section: section ? `${section.n} — ${section.title}` : null,
+    objectives: lecture?.objectives || [],
+    activeExercise: exercise && existsSync(exercise) ? exercise : null,
+    learningLog: logPath,
+    watch: preface.filter((l) => /watch-this/i.test(l)).map((l) => l.trim()),
+    trail: rounds.map((r) => r.join('\n')),
+  };
+}
+
+const oneLine = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+
+/** Pure: return LEARNING-LOG.md text with one more round for `section`. */
+export function appendRound(text, { slug, section, learner, asked, concept, evidence, watch, date }) {
+  let src = text && text.trim()
+    ? text
+    : `---\ncourse: ${slug}\nupdated: ${date}\n---\n\n# Learning Log\n`;
+  src = src.replace(/^(---\n[\s\S]*?^updated:\s*).*$/m, `$1${date}`);
+  const lines = src.replace(/\n+$/, '').split('\n');
+
+  let t = lines.findIndex((l) => TRAIL_RE.test(l));
+  if (t === -1) {
+    const firstH2 = lines.findIndex((l) => /^##\s/.test(l));
+    if (firstH2 === -1) lines.push('', '## 🗣️ Reasoning Trail');
+    else lines.splice(firstH2, 0, '## 🗣️ Reasoning Trail', '');
+    t = lines.findIndex((l) => TRAIL_RE.test(l));
+  }
+  let regionEnd = t + 1;
+  while (regionEnd < lines.length && !/^##\s/.test(lines[regionEnd])) regionEnd++;
+
+  const key = sectionKey(section);
+  const block = trailBlock(lines.join('\n'), key);
+  let h = -1;
+  for (let i = t + 1; i < regionEnd; i++) {
+    if (sectionHeadRe(key).test(lines[i])) { h = i; break; }
+  }
+  if (h === -1) {
+    let at = regionEnd;
+    while (at > t + 1 && !lines[at - 1].trim()) at--;
+    lines.splice(at, 0, '', `### Section ${section}`);
+    h = at + 1;
+  }
+
+  const { preface, rounds } = splitRounds(block);
+  const keep = preface.filter((l) => !(watch && /watch-this/i.test(l)));
+  if (watch) keep.push(`⚠️ watch-this: ${oneLine(watch)}`);
+  rounds.push([
+    `Round 0 — ${date}`,
+    `  Learner: "${oneLine(learner)}"`,
+    `  Coach asked: "${oneLine(asked)}"`,
+    ...(evidence ? [`  Evidence: ${oneLine(evidence)}`] : []),
+    `  Concept: ${oneLine(concept)}`,
+  ]);
+  const kept = rounds.slice(-MAX_ROUNDS).map((r, i) => [r[0].replace(/^Round\s+\d+/, `Round ${i + 1}`), ...r.slice(1)]);
+
+  const body = ['', ...(keep.length ? [...keep, ''] : []), ...kept.flatMap((r) => [...r, '']).slice(0, -1)];
+  lines.splice(h + 1, block.length, ...body, ...(h + 1 + block.length < lines.length ? [''] : []));
+  return { text: `${lines.join('\n').replace(/\n{3,}/g, '\n\n')}\n`, rounds: kept.length };
+}
+
+export function recordRound({ cwd, slug, section, learner, asked, concept, evidence, watch, date = todayISO() }) {
+  if (!slug) throw new Error('Pass the course slug — trail never guesses which course to write.');
+  for (const [name, v] of [['--learner', learner], ['--asked', asked], ['--concept', concept]]) {
+    if (!oneLine(v)) throw new Error(`Missing ${name} — nothing was recorded.`);
+  }
+  const ctx = buildContext({ cwd, slug });
+  const target = section || ctx.section;
+  if (!target) throw new Error('No current section in COURSE.md — pass --section "N — Title".');
+  const path = ctx.learningLog;
+  const before = existsSync(path) ? readFileSync(path, 'utf-8') : '';
+  const { text, rounds } = appendRound(before, { slug, section: target, learner, asked, concept, evidence, watch, date });
+  writeFileSync(path, text);
+  let saved = false;
+  try {
+    saved = saveCourse({ cwd, slug, message: `course(${slug}): review round, section ${sectionKey(target)}` }).committed;
+  } catch { /* file is written; commit is best-effort (plain folders, missing git identity) */ }
+  return { recorded: true, path, section: target, rounds, saved };
+}
+
+function flagValue(args, name) {
+  const i = args.indexOf(name);
+  return i !== -1 && args[i + 1] !== undefined && !args[i + 1].startsWith('--') ? args[i + 1] : null;
+}
+
+const VALUE_FLAGS = ['--section', '--learner', '--asked', '--concept', '--evidence', '--watch', '--date'];
+
+function positionals(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    if (VALUE_FLAGS.includes(args[i])) { i++; continue; }
+    if (!args[i].startsWith('--')) out.push(args[i]);
+  }
+  return out;
+}
+
+/** `context` and `trail` share this module; cli.js passes the command name. */
+export async function run({ args = [], cwd = process.cwd(), command = 'context' } = {}) {
+  const slug = positionals(args)[0] || null;
+  const json = args.includes('--json');
+  try {
+    if (command === 'trail') {
+      // Agents pass learner text as JSON on stdin (quoted heredoc) so the shell never expands it.
+      const fromStdin = args.includes('--stdin') ? JSON.parse(readFileSync(0, 'utf-8')) : {};
+      const f = (n) => fromStdin[n.slice(2)] ?? flagValue(args, n);
+      const r = recordRound({
+        cwd, slug, section: f('--section'), learner: f('--learner'), asked: f('--asked'),
+        concept: f('--concept'), evidence: f('--evidence'), watch: f('--watch'), date: f('--date') || undefined,
+      });
+      if (json) console.log(JSON.stringify(r));
+      else {
+        console.log(style('success', `Recorded review round ${r.rounds} for Section ${r.section} in ${relative(cwd, r.path)}`
+          + (r.saved ? ' (committed)' : '')));
+      }
+      return;
+    }
+    const ctx = buildContext({ cwd, slug });
+    if (json) { console.log(JSON.stringify(ctx, null, 2)); return; }
+    console.log(`${ctx.title} (${ctx.slug}, ${ctx.kind}) — ${ctx.dir}`);
+    console.log(`Section: ${ctx.section || '—'}`);
+    console.log(`Active exercise: ${ctx.activeExercise || '—'}`);
+    console.log(`Trail rounds this section: ${ctx.trail.length}`);
+  } catch (err) {
+    if (json) console.log(JSON.stringify({ error: err.message }));
+    else console.error(style('error', err.message));
+    process.exitCode = 1;
+  }
+}

package/bin/commands/web.js

@@ -0,0 +1,350 @@
+/**
+ * bin/commands/web.js — the `skillforce web` command.
+ *
+ * Studio-only by default: no API-key discovery/prompt and no `.env`, keychain or agent-home scan.
+ * Legacy mode is the explicit opt-in (`--legacy` or `PROFESSOR_LEGACY=1`) and keeps the old
+ * Anthropic/OpenAI fallback prompt. The server itself owns legacy-dev Vite startup (D-08).
+ */
+import { existsSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+import inquirer from 'inquirer';
+import ora from 'ora';
+import { buildPairingUrl } from './studio.js';
+import * as security from '../../web/security.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, '..', '..');
+const DEFAULT_PORT = '3000';
+
+/** Usage text for `web --help`. */
+export const WEB_USAGE = `
+Usage: skillforce web [port] [options]
+
+Start the Studio bridge server; --production also serves the built Studio app
+from the same port.
+
+Options:
+  [port]            Port to listen on (default ${DEFAULT_PORT})
+  --production      Serve the built Studio app (requires an existing Studio build)
+  --rotate-token    Generate a new pairing token and exit
+  --legacy          Deprecated: mount the legacy web UI (PROFESSOR_LEGACY=1)
+  --cloud           Deprecated: legacy only — no effect without --legacy
+  -h, --help        Show this help and exit
+`.trim();
+
+/** True when `-h` or `--help` is present. */
+export function wantsHelp(args = []) {
+  const list = Array.isArray(args) ? args : [];
+  return list.includes('--help') || list.includes('-h');
+}
+
+
+/** True when `pkg` resolves from `dir` (or an ancestor `node_modules`, e.g. the package root). */
+function canResolveFrom(dir, pkg) {
+  try {
+    createRequire(join(dir, 'index.js')).resolve(pkg);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Parse `web` flags and the single positional port. The port is returned as a **string** (or `null`
+ * when absent) so existing callers can pass it through unchanged; unknown flags never become a port.
+ *
+ * @param {string[]} [args]
+ * @returns {{ legacy: boolean, production: boolean, cloud: boolean, rotateToken: boolean,
+ *             port: string|null }}
+ */
+export function parseWebArgs(args = []) {
+  const list = Array.isArray(args) ? args : [];
+  let port = null;
+  for (const arg of list) {
+    if (typeof arg !== 'string' || arg.startsWith('--')) continue;
+    if (port === null) port = arg;
+  }
+  return {
+    legacy: list.includes('--legacy'),
+    production: list.includes('--production'),
+    cloud: list.includes('--cloud'),
+    rotateToken: list.includes('--rotate-token'),
+    port,
+  };
+}
+
+/**
+ * User-facing UI port. Legacy dev is served by Vite on 5173; every other mode serves the UI on the
+ * API port (Studio-only or legacy production).
+ *
+ * @param {{ legacy?: boolean, production?: boolean, port?: string|null }} [opts]
+ * @returns {string}
+ */
+export function resolveWebUiPort({ legacy = false, production = false, port = null } = {}) {
+  if (legacy && !production) return '5173';
+  return port || DEFAULT_PORT;
+}
+
+/**
+ * @param {{ args: string[], cwd: string, chalk: any, style: (kind: string, text: string) => string,
+ *           startServerImpl?: Function }} ctx
+ */
+export async function run({ args = [], style, startServerImpl } = {}) {
+  if (wantsHelp(args)) {
+    console.log(WEB_USAGE);
+    return null;
+  }
+
+  const { execSync } = await import('child_process');
+  const webDir = join(REPO_ROOT, 'web');
+  const options = parseWebArgs(args);
+  const isProduction = options.production;
+  const legacy = options.legacy || process.env.PROFESSOR_LEGACY === '1';
+  const cloudOnly = options.cloud;
+
+  if (!existsSync(webDir)) {
+    console.error(style('error', 'Web UI not found. Ensure the package is fully installed.'));
+    process.exit(1);
+  }
+
+  if (isProduction) process.env.NODE_ENV = 'production';
+  if (legacy) process.env.PROFESSOR_LEGACY = '1';
+
+  const positionalPort =
+    options.port || (!isProduction ? process.env.PORT : null) || DEFAULT_PORT;
+
+  let rotatedToken = null;
+  if (options.rotateToken) {
+    try {
+      rotatedToken = security.rotateStudioToken({ env: process.env });
+    } catch (err) {
+      console.error(
+        style('error', err.code === 'env_token_immutable' ? err.message : `Could not rotate token: ${err.message}`)
+      );
+      throw err;
+    }
+    const startRequested = options.legacy || options.production || options.cloud || options.port !== null;
+    const { pairingUrl } = buildPairingUrl({
+      studioPort: resolveWebUiPort({ legacy, production: isProduction, port: positionalPort }),
+      apiPort: positionalPort,
+      token: rotatedToken,
+    });
+    console.log('');
+    console.log(`   Pairing token: ${security.maskToken(rotatedToken)}`);
+    console.log(`   Pairing URL:   ${pairingUrl}`);
+    console.log('');
+    if (!startRequested) return null;
+  }
+
+  if (isProduction) {
+    if (legacy) {
+      const distPath = join(webDir, 'client', 'dist');
+      if (!existsSync(distPath)) {
+        console.error(style('warning', 'Production build not found.'));
+        console.error('   From repo root: npm run build');
+        console.error('   Then: npx ronin-skillforce web --legacy --production');
+        process.exit(1);
+      }
+    } else {
+      const studioIndex = join(REPO_ROOT, 'studio', 'dist', 'index.html');
+      if (!existsSync(studioIndex)) {
+        console.error(style('warning', 'Studio build not found.'));
+        console.error('   Run: npx ronin-skillforce studio');
+        console.error('   Or:  npm run build:studio');
+        process.exit(1);
+      }
+    }
+  }
+
+  // `express`/`cors` are root dependencies, so an installed package needs no nested install.
+  if (!canResolveFrom(webDir, 'express') && !existsSync(join(webDir, 'node_modules'))) {
+    const spinner = ora('Installing web dependencies…').start();
+    try {
+      execSync('npm install', { cwd: webDir, stdio: 'pipe' });
+      spinner.succeed('Web dependencies installed.');
+    } catch (err) {
+      spinner.fail('Web dependencies failed.');
+      const message = String(err?.message || err);
+      if (err?.code === 'EACCES' || /EACCES|permission denied|read-only/i.test(message)) {
+        console.error(style('error',
+          'Cannot install web dependencies: the package directory is read-only (npx cache). ' +
+          'Install globally (`npm i -g ronin-skillforce`) or run from a git clone.'));
+      } else {
+        console.error(style('error', `Check your network and try: cd ${webDir} && npm install`));
+      }
+      process.exit(1);
+    }
+  }
+
+  // Mirror web/server.js: the legacy Vite dev server only runs when NODE_ENV is not production,
+  // so its client dependencies are only needed then.
+  const clientDir = join(webDir, 'client');
+  const needsLegacyDevClient = legacy && !isProduction && process.env.NODE_ENV !== 'production';
+  if (needsLegacyDevClient && existsSync(clientDir) && !existsSync(join(clientDir, 'node_modules'))) {
+    const spinner = ora('Installing client dependencies…').start();
+    try {
+      execSync('npm install', { cwd: clientDir, stdio: 'pipe' });
+      spinner.succeed('Client dependencies installed.');
+    } catch {
+      spinner.fail('Client dependencies failed.');
+      console.error(style('error', `Check your network and try: cd ${clientDir} && npm install`));
+      process.exit(1);
+    }
+  }
+
+  async function findApiKey() {
+    if (process.env.ANTHROPIC_API_KEY) return { key: process.env.ANTHROPIC_API_KEY, source: 'env' };
+    if (process.env.CLAUDE_API_KEY)    return { key: process.env.CLAUDE_API_KEY,    source: 'env' };
+    if (process.env.OPENAI_API_KEY)    return { key: process.env.OPENAI_API_KEY,    source: 'env' };
+
+    const envFile = join(process.cwd(), '.env');
+    if (existsSync(envFile)) {
+      try {
+        const lines = readFileSync(envFile, 'utf-8').split('\n');
+        for (const line of lines) {
+          const m = line.match(/^(ANTHROPIC_API_KEY|CLAUDE_API_KEY|OPENAI_API_KEY)\s*=\s*(.+)$/);
+          if (m) return { key: m[2].trim().replace(/^["']|["']$/g, ''), source: '.env' };
+        }
+      } catch {}
+    }
+
+    if (process.platform === 'darwin') {
+      try {
+        const { execSync: _exec } = await import('child_process');
+        for (const svc of ['anthropic-api-key', 'Anthropic API Key', 'ANTHROPIC_API_KEY']) {
+          try {
+            const raw = _exec(`security find-generic-password -s "${svc}" -w`, {
+              encoding: 'utf-8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
+            if (raw?.startsWith('sk-ant-api')) return { key: raw, source: `keychain:${svc}` };
+          } catch {}
+        }
+      } catch {}
+    }
+
+    const home = process.env.HOME || '';
+    for (const p of [
+      join(home, '.claude', 'settings.json'),
+      join(home, '.anthropic', 'config.json'),
+    ]) {
+      if (existsSync(p)) {
+        try {
+          const s = JSON.parse(readFileSync(p, 'utf-8'));
+          const k = s.ANTHROPIC_API_KEY || s.apiKey || s.api_key;
+          if (k) return { key: k, source: p };
+        } catch {}
+      }
+    }
+    return null;
+  }
+
+  function hasLocalProvider() {
+    for (const cmd of ['claude', 'ollama', 'cursor-agent', 'opencode']) {
+      try {
+        execSync(`which ${cmd}`, { stdio: 'ignore' });
+        return true;
+      } catch {}
+    }
+    return false;
+  }
+
+  if (legacy) {
+    let found = await findApiKey();
+    const localProviderAvailable = hasLocalProvider();
+    const shouldPromptForApiKey = cloudOnly || !localProviderAvailable;
+    if (!found && shouldPromptForApiKey) {
+      if (!process.stdin.isTTY) {
+        console.log(style('info', 'No API key. Chat disabled.\n'));
+      } else {
+        console.log('');
+        console.log(style('info', 'No Anthropic API key detected.'));
+        console.log('   Get one at: https://console.anthropic.com/settings/keys');
+        console.log('   (Key will be saved to .env if you paste one; otherwise chat will be disabled.)');
+        console.log('');
+        const { apiKeyInput } = await inquirer.prompt([{
+          type: 'input',
+          name: 'apiKeyInput',
+          message: 'Paste your API key (or press Enter to skip):',
+        }]);
+        const trimmed = (apiKeyInput || '').trim();
+        if (trimmed && trimmed.startsWith('sk-')) {
+          const envPath = join(process.cwd(), '.env');
+          const line = `ANTHROPIC_API_KEY=${trimmed}\n`;
+          try {
+            const existing = existsSync(envPath) ? readFileSync(envPath, 'utf-8') : '';
+            if (!existing.includes('ANTHROPIC_API_KEY')) {
+              writeFileSync(envPath, existing + line);
+              console.log(`   ${style('success', "Saved to .env — won't ask again.")}\n`);
+            }
+          } catch {}
+          found = { key: trimmed, source: '.env (just saved)' };
+        } else {
+          console.log('   Skipping. Chat disabled.\n');
+        }
+      }
+    }
+
+    const apiKey = found?.key;
+    if (apiKey) {
+      console.log(style('success', `API key loaded (${found.source}).\n`));
+      process.env.ANTHROPIC_API_KEY = apiKey;
+    } else if (localProviderAvailable) {
+      console.log(style('info', 'No API key found. Local providers will be used when available.\n'));
+    }
+  }
+
+  process.env.PORT = positionalPort;
+
+  let defaultCourses = './courses';
+  if (existsSync('./courses')) {
+    if (readdirSync('./courses').length === 0) defaultCourses = './learning';
+  } else if (existsSync('./learning')) {
+    defaultCourses = './learning';
+  }
+  process.env.COURSES_DIR = process.env.COURSES_DIR || defaultCourses;
+
+  const token =
+    rotatedToken ||
+    security.ensureStudioToken({
+      env: process.env,
+      legacyFile: security.legacyTokenPath(REPO_ROOT),
+    });
+  const expectedUiPort = resolveWebUiPort({
+    legacy,
+    production: isProduction,
+    port: positionalPort,
+  });
+
+  const mode = isProduction ? 'production' : 'development';
+  console.log('');
+  console.log(style('info', 'Starting Professor Web UI…'));
+  console.log(`   Mode: ${mode} | Port: ${positionalPort} | Courses: ${process.env.COURSES_DIR}`);
+  console.log(`   Pairing token: ${security.maskToken(token)}`);
+
+  const loadServer = startServerImpl || (await import(join(webDir, 'server.js'))).startServer;
+  const started = await loadServer({
+    legacy,
+    port: positionalPort,
+    host: process.env.HOST,
+    logBanner: false,
+  });
+  const uiUrl = started?.uiUrl || `http://localhost:${expectedUiPort}`;
+  const uiPort = (() => {
+    try {
+      return new URL(uiUrl).port || expectedUiPort;
+    } catch {
+      return expectedUiPort;
+    }
+  })();
+  const { pairingUrl } = buildPairingUrl({
+    studioPort: uiPort,
+    apiPort: positionalPort,
+    token,
+  });
+  console.log(`   UI:            ${uiUrl}`);
+  console.log(`   Pairing URL:   ${pairingUrl}`);
+  console.log('');
+  return started;
+}