ronin-skillforce 0.0.0-stage → 0.1.0

package/studio/src/lib/runner/index.js

@@ -0,0 +1,168 @@
+/**
+ * Runner interface (CODE-02, CODE-04) — the single entry point the Workspace UI calls.
+ *
+ *   run({ language, files, entry, tests, signal, onOutput }) -> RunResult
+ *
+ * Backend selection is deliberate and boring:
+ *   1. browser  — when the language is supported with no install (JS/TS, Python, SQL, HTML/CSS)
+ *   2. local    — otherwise, if the learner's local server answers `/toolchains`
+ *   3. error    — with an actionable hint telling them how to get the toolchain
+ *
+ * `onOutput` streams `{ stream: 'stdout'|'stderr'|'status', text }` as the run progresses.
+ * Nothing here ever writes, reveals or generates a solution — it only executes the learner's code.
+ */
+import { languageForPath, normalizeLanguage, isBrowserLanguage, isLocalLanguage, getLanguage } from './languages.js';
+import { runBrowser, DEFAULT_TIMEOUT_MS, MAX_OUTPUT_BYTES, RunnerError } from './browser.js';
+import { runLocal, checkToolchains, runnerBase } from './local.js';
+import { loadSettings } from '../settings.js';
+
+export { DEFAULT_TIMEOUT_MS, MAX_OUTPUT_BYTES };
+export { isBrowserLanguage, isLocalLanguage };
+
+/**
+ * @typedef {import('./browser.js').RunResult} RunResult
+ */
+
+/** @returns {boolean} whether a Web Worker can be constructed in this environment */
+export function canUseWorkers() {
+  return typeof Worker !== 'undefined';
+}
+
+/**
+ * Pure backend choice — exported so it can be unit-tested without a browser.
+ * @param {{ language: string, browserUsable?: boolean, localAvailable?: boolean, preferLocal?: boolean }} input
+ * @returns {'browser'|'local'|null}
+ */
+export function selectRunner({ language, browserUsable = true, localAvailable = false, preferLocal = false }) {
+  const browser = isBrowserLanguage(language);
+  if (preferLocal && localAvailable) return 'local';
+  if (browser && browserUsable) return 'browser';
+  if (isLocalLanguage(language) && localAvailable) return 'local';
+  if (browser && !browserUsable && localAvailable) return 'local';
+  return null;
+}
+
+/**
+ * The runner the UI should advertise for a language (no network).
+ * @param {string|null|undefined} language
+ * @param {{ toolchains?: Record<string, boolean>|null }} [opts]
+ */
+export function describeRunner(language, { toolchains = null } = {}) {
+  const lang = normalizeLanguage(language);
+  const spec = getLanguage(lang);
+  if (!spec) return { id: null, label: 'Unknown', kind: null, ready: false };
+  const browser = spec.backend === 'browser';
+  if (browser) return { id: lang, label: 'Browser', kind: 'browser', ready: true };
+  const command = spec.command;
+  const ready = Boolean(toolchains && command && toolchains[command]);
+  return { id: lang, label: 'Local server', kind: 'local', ready, command };
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.language
+ * @param {Record<string,string>|Array<{path:string,content:string}>} input.files
+ * @param {string|null} [input.entry]
+ * @param {any} [input.tests]
+ * @param {AbortSignal} [input.signal]
+ * @param {(chunk:{stream:string,text:string})=>void} [input.onOutput]
+ * @param {string} [input.courseSlug]
+ * @param {object} [input.settings]
+ * @param {number} [input.timeoutMs]
+ * @param {number} [input.maxOutputBytes]
+ * @param {boolean} [input.preferLocal]
+ * @returns {Promise<RunResult>}
+ */
+export async function run(input) {
+  const {
+    language,
+    files = {},
+    entry = null,
+    tests = null,
+    signal,
+    onOutput,
+    courseSlug = 'workspace',
+    settings = null,
+    timeoutMs,
+    maxOutputBytes,
+    preferLocal = false,
+  } = input || {};
+
+  const resolvedSettings = settings || safeSettings();
+  const lang = normalizeLanguage(language) || languageForPath(entry) || normalizeLanguage(Object.keys(files)[0]) || 'javascript';
+
+  const browserUsable = canUseWorkers();
+  const browserPath = { language: lang, files: fileMap(files), entry, tests, signal, onOutput, timeoutMs, maxOutputBytes };
+
+  if (isBrowserLanguage(lang) && browserUsable && !preferLocal) {
+    return runBrowser(browserPath);
+  }
+
+  // Local (or browser-as-fallback when a browser language but no workers, or preferLocal).
+  let localAvailable = false;
+  let localError = null;
+  if (!isBrowserLanguage(lang) || preferLocal) {
+    try {
+      const toolchains = await checkToolchains(resolvedSettings, { signal });
+      localAvailable = true;
+      const spec = getLanguage(lang);
+      if (spec?.command && toolchains && toolchains[spec.command] === false) {
+        throw localToolchainError(lang, spec.command);
+      }
+    } catch (err) {
+      localError = err;
+      localAvailable = false;
+    }
+  }
+
+  const choice = selectRunner({ language: lang, browserUsable, localAvailable, preferLocal });
+  if (choice === 'local') {
+    return runLocal({ settings: resolvedSettings, courseSlug, language: lang, files: fileMap(files), entry, signal, onOutput, timeoutMs });
+  }
+  if (choice === 'browser') {
+    return runBrowser(browserPath);
+  }
+
+  // No backend works — surface the most useful error.
+  if (localError) throw localError;
+  if (browserUsable && isBrowserLanguage(lang)) return runBrowser(browserPath);
+  if (!browserUsable && isBrowserLanguage(lang)) {
+    const err = new RunnerError('unavailable', `The ${lang} runner needs Web Workers, which this browser does not expose.`);
+    err.hint = 'Try a modern browser, or start the local server and use the local runner.';
+    throw err;
+  }
+  throw localToolchainError(lang, getLanguage(lang)?.command);
+}
+
+/**
+ * @param {string} language
+ * @param {string|undefined} command
+ */
+function localToolchainError(language, command) {
+  const label = getLanguage(language)?.label || language;
+  const err = new RunnerError(
+    'unavailable',
+    `${label} needs its toolchain installed and the local server running.`
+  );
+  err.hint = `Start the local server (\`npx ronin-skillforce web\`)${command ? ` and make sure \`${command}\` is on your PATH` : ''}. The local runner writes files to ~/.professor/workspaces/ so you can also open them in your editor. You can still write and save code without running it.`;
+  return err;
+}
+
+/** @param {Record<string,string>|Array<{path:string,content:string}>} files */
+function fileMap(files) {
+  if (!files) return {};
+  return Array.isArray(files)
+    ? Object.fromEntries(files.map((f) => [f.path, String(f.content ?? '')]))
+    : Object.fromEntries(Object.entries(files).map(([k, v]) => [k, String(v ?? '')]));
+}
+
+/** Settings without throwing when localStorage is unavailable (worker/node/tests). */
+function safeSettings() {
+  try {
+    return loadSettings();
+  } catch {
+    return {};
+  }
+}
+
+export { checkToolchains, runnerBase };

package/studio/src/lib/runner/languages.js

@@ -0,0 +1,258 @@
+/**
+ * Language metadata + detection for the code workspace (CODE-02, CODE-04).
+ *
+ * `backend` is the deliberate split the brief asks for:
+ *   - 'browser' — runs with no install (JS/TS, Python via Pyodide, SQL via sql.js, HTML/CSS preview)
+ *   - 'local'   — needs the learner's own toolchain through `web/studio-runner.js`
+ *
+ * This module is pure (no DOM, no imports) so it is unit-testable and safe to use everywhere.
+ */
+
+/** @typedef {'javascript'|'typescript'|'python'|'sql'|'html'|'css'|'go'|'java'|'rust'|'bash'} LanguageId */
+
+/**
+ * @typedef {object} LanguageSpec
+ * @property {LanguageId} id
+ * @property {string} label
+ * @property {string[]} extensions        lower-case, with the leading dot
+ * @property {'browser'|'local'} backend
+ * @property {string|null} codeMirror      CodeMirror language key (Editor.jsx maps it to a grammar)
+ * @property {string} entry                default entry filename
+ * @property {string} comment              line-comment token (used when writing seeds / hints)
+ * @property {string} [command]            local allowlist command
+ */
+
+/** @type {Record<LanguageId, LanguageSpec>} */
+export const LANGUAGES = {
+  javascript: {
+    id: 'javascript',
+    label: 'JavaScript',
+    extensions: ['.js', '.mjs', '.cjs', '.jsx'],
+    backend: 'browser',
+    codeMirror: 'javascript',
+    entry: 'main.js',
+    comment: '//',
+    command: 'node',
+  },
+  typescript: {
+    id: 'typescript',
+    label: 'TypeScript',
+    extensions: ['.ts', '.tsx', '.mts', '.cts'],
+    backend: 'browser',
+    codeMirror: 'typescript',
+    entry: 'main.ts',
+    comment: '//',
+  },
+  python: {
+    id: 'python',
+    label: 'Python',
+    extensions: ['.py', '.pyw'],
+    backend: 'browser',
+    codeMirror: 'python',
+    entry: 'main.py',
+    comment: '#',
+    command: 'python3',
+  },
+  sql: {
+    id: 'sql',
+    label: 'SQL',
+    extensions: ['.sql'],
+    backend: 'browser',
+    codeMirror: 'sql',
+    entry: 'main.sql',
+    comment: '--',
+    command: 'sqlite3',
+  },
+  html: {
+    id: 'html',
+    label: 'HTML',
+    extensions: ['.html', '.htm'],
+    backend: 'browser',
+    codeMirror: 'html',
+    entry: 'index.html',
+    comment: '<!--',
+  },
+  css: {
+    id: 'css',
+    label: 'CSS',
+    extensions: ['.css'],
+    backend: 'browser',
+    codeMirror: 'css',
+    entry: 'style.css',
+    comment: '/*',
+  },
+  go: {
+    id: 'go',
+    label: 'Go',
+    extensions: ['.go'],
+    backend: 'local',
+    codeMirror: 'go',
+    entry: 'main.go',
+    comment: '//',
+    command: 'go',
+  },
+  java: {
+    id: 'java',
+    label: 'Java',
+    extensions: ['.java'],
+    backend: 'local',
+    codeMirror: 'java',
+    entry: 'Main.java',
+    comment: '//',
+    command: 'javac',
+  },
+  rust: {
+    id: 'rust',
+    label: 'Rust',
+    extensions: ['.rs'],
+    backend: 'local',
+    codeMirror: 'rust',
+    entry: 'main.rs',
+    comment: '//',
+    command: 'rustc',
+  },
+  bash: {
+    id: 'bash',
+    label: 'Bash',
+    extensions: ['.sh', '.bash'],
+    backend: 'local',
+    codeMirror: null,
+    entry: 'main.sh',
+    comment: '#',
+    command: 'bash',
+  },
+};
+
+export const LANGUAGE_IDS = /** @type {LanguageId[]} */ (Object.keys(LANGUAGES));
+
+/**
+ * Aliases seen in fenced-code info strings / course metadata.
+ * @type {Record<string, LanguageId>}
+ */
+const ALIASES = {
+  js: 'javascript',
+  javascript: 'javascript',
+  mjs: 'javascript',
+  node: 'javascript',
+  jsx: 'javascript',
+  ts: 'typescript',
+  typescript: 'typescript',
+  tsx: 'typescript',
+  py: 'python',
+  python: 'python',
+  python3: 'python',
+  sql: 'sql',
+  sqlite: 'sql',
+  html: 'html',
+  htm: 'html',
+  css: 'css',
+  scss: 'css',
+  go: 'go',
+  golang: 'go',
+  java: 'java',
+  rust: 'rust',
+  rs: 'rust',
+  sh: 'bash',
+  bash: 'bash',
+  shell: 'bash',
+};
+
+/**
+ * Normalise a user/course-supplied language string to a known id.
+ * @param {string|null|undefined} value
+ * @returns {LanguageId|null}
+ */
+export function normalizeLanguage(value) {
+  if (!value) return null;
+  const key = String(value).trim().toLowerCase().replace(/^language-/, '');
+  if (ALIASES[key]) return ALIASES[key];
+  if (LANGUAGES[/** @type {LanguageId} */ (key)]) return /** @type {LanguageId} */ (key);
+  return null;
+}
+
+/**
+ * @param {string|null|undefined} path
+ * @returns {LanguageId|null}
+ */
+export function languageForPath(path) {
+  if (!path) return null;
+  const match = /\.([a-z0-9]+)$/i.exec(String(path));
+  if (!match) return null;
+  const ext = `.${match[1].toLowerCase()}`;
+  for (const spec of Object.values(LANGUAGES)) {
+    if (spec.extensions.includes(ext)) return spec.id;
+  }
+  return null;
+}
+
+/** @param {string} id */
+export function getLanguage(id) {
+  return LANGUAGES[/** @type {LanguageId} */ (id)] || null;
+}
+
+/** @param {string} id */
+export function isBrowserLanguage(id) {
+  return getLanguage(id)?.backend === 'browser';
+}
+
+/** @param {string} id */
+export function isLocalLanguage(id) {
+  return getLanguage(id)?.backend === 'local';
+}
+
+/** @param {string} id */
+export function defaultEntry(id) {
+  return getLanguage(id)?.entry || 'main.txt';
+}
+
+/**
+ * The languages the UI advertises for the "browser" runner.
+ * @returns {LanguageSpec[]}
+ */
+export function browserLanguages() {
+  return Object.values(LANGUAGES).filter((l) => l.backend === 'browser');
+}
+
+/**
+ * Guess a course's primary language from its kind + lesson text.
+ * Programming courses usually name the language in the goal/topics/title.
+ * @param {{ kind?: string, title?: string, goal?: string, topics?: string[]|string, language?: string }} course
+ * @returns {LanguageId|null}
+ */
+export function guessCourseLanguage(course = {}) {
+  const explicit = normalizeLanguage(course.language);
+  if (explicit) return explicit;
+
+  const haystack = [
+    course.title,
+    course.goal,
+    Array.isArray(course.topics) ? course.topics.join(' ') : course.topics,
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase();
+  if (!haystack) return null;
+
+  // Ordered so more specific names win over substrings ("javascript" before "java").
+  const ordered = [
+    'typescript',
+    'javascript',
+    'python',
+    'rust',
+    'golang',
+    'go',
+    'java',
+    'sql',
+    'html',
+    'css',
+    'bash',
+  ];
+  for (const needle of ordered) {
+    const re = new RegExp(`(^|[^a-z])${needle}([^a-z]|$)`);
+    if (re.test(haystack)) {
+      const id = normalizeLanguage(needle);
+      if (id) return id;
+    }
+  }
+  return null;
+}

package/studio/src/lib/runner/local.js

@@ -0,0 +1,139 @@
+/**
+ * Local runner client (CODE-04) — talks to `web/studio-runner.js` through the existing local
+ * agent bridge (`web/server.js` → `web/studio-api.js`), reusing the same token + CORS + LNA
+ * handling as the AI bridge (see ../ai/fetch-local.js).
+ *
+ * Endpoints (mounted by studio-api.js as `router.use('/run', createRunnerRouter(...))`):
+ *   GET  {bridge}/api/studio/run/toolchains  -> { node: true, python3: true, go: false, … }
+ *   POST {bridge}/api/studio/run             -> SSE: {"stdout"}, {"stderr"}, {"exit"}, [DONE]
+ *
+ * Files are written server-side to `${PROFESSOR_HOME:-~/.professor}/workspaces/<courseSlug>/` so
+ * the learner can open the same folder in a real editor.
+ */
+import { parseSSE } from '../ai/sse.js';
+import { localFetch, classifyNetworkError, mapHttpError } from '../ai/fetch-local.js';
+import { isAbortError, providerError } from '../ai/errors.js';
+import { DEFAULT_BRIDGE_URL } from '../ai/bridge.js';
+import { assertLoopbackBridgeUrl } from '../settings.js';
+
+const RUN_HINT = 'Start the local server (`npx ronin-skillforce web` or `npm start`), then retry. Or pick a language that runs in the browser.';
+
+/**
+ * @param {object} settings
+ * @returns {string} the runner API root (no trailing slash)
+ */
+export function runnerBase(settings = {}) {
+  const root = String(settings.bridge?.bridgeUrl || settings.bridgeUrl || DEFAULT_BRIDGE_URL).replace(/\/$/, '');
+  assertLoopbackBridgeUrl(root);
+  return `${root}/api/studio/run`;
+}
+
+/**
+ * @param {object} settings
+ * @returns {{ 'Content-Type': string, 'X-Studio-Token'?: string }}
+ */
+function headersFor(settings = {}) {
+  const token = settings.bridge?.bridgeToken || settings.bridgeToken;
+  return {
+    'Content-Type': 'application/json',
+    ...(token ? { 'X-Studio-Token': token } : {}),
+  };
+}
+
+/**
+ * Which toolchains are installed on the server.
+ * @param {object} settings
+ * @param {{ signal?: AbortSignal }} [opts]
+ * @returns {Promise<Record<string, boolean>>}
+ */
+export async function checkToolchains(settings = {}, { signal } = {}) {
+  const url = `${runnerBase(settings)}/toolchains`;
+  let res;
+  try {
+    res = await localFetch(url, { headers: headersFor(settings), signal });
+  } catch (err) {
+    if (isAbortError(err)) throw providerError('aborted', 'Stopped');
+    const mapped = classifyNetworkError(err, { url, what: 'the local runner', notRunningHint: RUN_HINT });
+    if (mapped.code === 'not_running') mapped.hint = RUN_HINT;
+    throw mapped;
+  }
+  if (!res.ok) throw await mapHttpError(res, { what: 'the local runner' });
+  return res.json();
+}
+
+/**
+ * @param {object} input
+ * @param {object} input.settings
+ * @param {string} [input.courseSlug]
+ * @param {string} input.language
+ * @param {Record<string,string>} input.files
+ * @param {string|null} [input.entry]
+ * @param {AbortSignal} [input.signal]
+ * @param {(chunk:{stream:'stdout'|'stderr',text:string})=>void} [input.onOutput]
+ * @param {number} [input.timeoutMs]
+ * @returns {Promise<import('./browser.js').RunResult>}
+ */
+export async function runLocal({
+  settings = {},
+  courseSlug = 'workspace',
+  language,
+  files = {},
+  entry = null,
+  signal,
+  onOutput,
+  timeoutMs,
+} = {}) {
+  const url = runnerBase(settings);
+  const started = Date.now();
+  let res;
+  try {
+    res = await localFetch(url, {
+      method: 'POST',
+      headers: headersFor(settings),
+      body: JSON.stringify({ courseSlug, language, files, entry, timeoutMs }),
+      signal,
+    });
+  } catch (err) {
+    if (isAbortError(err)) throw providerError('aborted', 'Stopped');
+    const mapped = classifyNetworkError(err, { url, what: 'the local runner', notRunningHint: RUN_HINT });
+    if (mapped.code === 'not_running') mapped.hint = RUN_HINT;
+    throw mapped;
+  }
+  if (!res.ok) throw await mapHttpError(res, { what: 'the local runner' });
+  if (!res.body) throw providerError('unknown', 'The local runner returned no stream');
+
+  let stdout = '';
+  let stderr = '';
+  let exitCode = null;
+  try {
+    for await (const data of parseSSE(res)) {
+      if (data === '[DONE]') break;
+      let json;
+      try {
+        json = JSON.parse(data);
+      } catch {
+        continue;
+      }
+      if (typeof json.stdout === 'string') {
+        stdout += json.stdout;
+        onOutput?.({ stream: 'stdout', text: json.stdout });
+      }
+      if (typeof json.stderr === 'string') {
+        stderr += json.stderr;
+        onOutput?.({ stream: 'stderr', text: json.stderr });
+      }
+      if (json.error) {
+        stderr += `${json.error}\n`;
+        onOutput?.({ stream: 'stderr', text: `${json.error}\n` });
+      }
+      if (typeof json.exit === 'number') exitCode = json.exit;
+    }
+  } catch (err) {
+    if (isAbortError(err)) {
+      return { stdout, stderr, exitCode, checks: [], durationMs: Date.now() - started, runner: 'local', aborted: true };
+    }
+    throw err;
+  }
+
+  return { stdout, stderr, exitCode: exitCode ?? 0, checks: [], durationMs: Date.now() - started, runner: 'local' };
+}

package/studio/src/lib/runner/path.js

@@ -0,0 +1,104 @@
+/**
+ * Path safety shared by the browser runner and `web/studio-runner.js` (PITFALLS: path traversal).
+ *
+ * A workspace file is addressed by a *relative* path (e.g. `main.py`, `src/util.py`). Anything
+ * absolute, containing a `..` segment, a NUL byte, or a Windows drive prefix is rejected so a
+ * crafted lesson/CLI payload can never write outside the workspace root.
+ *
+ * Pure module — no Node/DOM APIs — so both the SPA and the Express router import the same rules.
+ */
+
+const WINDOWS_DRIVE = /^[a-zA-Z]:[\\/]/;
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+const BACKSLASH = /\\/;
+
+/**
+ * @param {unknown} path
+ * @returns {boolean} true when `path` is a safe, relative, portable path
+ */
+export function isSafeRelPath(path) {
+  if (typeof path !== 'string') return false;
+  const value = path.trim();
+  if (!value) return false;
+  if (value.length > 512) return false;
+  if (CONTROL_CHARS.test(value)) return false;
+  if (value.startsWith('/') || value.startsWith('~')) return false;
+  if (WINDOWS_DRIVE.test(value)) return false;
+  if (BACKSLASH.test(value)) return false; // enforce forward slashes for portability
+  if (value.endsWith('/')) return false;
+
+  const segments = value.split('/');
+  for (const segment of segments) {
+    if (segment === '' || segment === '.' || segment === '..') return false;
+  }
+  return true;
+}
+
+/**
+ * A course slug becomes a single folder name under the workspaces root.
+ * @param {unknown} slug
+ * @returns {boolean}
+ */
+export function isSafeSlug(slug) {
+  if (typeof slug !== 'string') return false;
+  const value = slug.trim();
+  if (!value || value.length > 120) return false;
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(value)) return false;
+  if (value === '.' || value === '..') return false;
+  return true;
+}
+
+/**
+ * Kebab-case slug from an arbitrary title (used to derive a course folder name).
+ * @param {string} title
+ * @returns {string}
+ */
+export function slugify(title) {
+  const out = String(title || '')
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80);
+  return out || 'workspace';
+}
+
+/**
+ * Normalise a relative path's separators to forward slashes (does not resolve `..`).
+ * @param {string} path
+ * @returns {string}
+ */
+export function toPosix(path) {
+  return String(path || '').replace(/\\/g, '/');
+}
+
+/**
+ * Resolve `rel` under `root` **and** assert the result stays inside `root`.
+ * Uses only string ops so it behaves identically in the browser and in Node.
+ * @param {string} root
+ * @param {string} rel
+ * @returns {string} the joined path (with the root's existing separators)
+ * @throws {Error} when `rel` is unsafe
+ */
+export function resolveInside(root, rel) {
+  if (!isSafeRelPath(rel)) throw new Error(`Unsafe path: ${rel}`);
+  const sep = root.includes('\\') ? '\\' : '/';
+  const base = root.replace(/[\\/]+$/, '');
+  return `${base}${sep}${toPosix(rel).split('/').join(sep)}`;
+}
+
+/**
+ * Convert a `{ path: content }` map (or `[{path, content}]` list) into a normalised list.
+ * @param {Record<string,string>|Array<{path?:string, name?:string, content?:string}>|null|undefined} files
+ * @returns {Array<{ path: string, content: string }>}
+ */
+export function normalizeFiles(files) {
+  if (!files) return [];
+  const rows = Array.isArray(files)
+    ? files.map((f) => ({ path: f?.path ?? f?.name, content: f?.content ?? '' }))
+    : Object.entries(files).map(([path, content]) => ({ path, content }));
+  return rows
+    .filter((f) => typeof f.path === 'string' && f.path)
+    .map((f) => ({ path: toPosix(f.path), content: String(f.content ?? '') }));
+}