ronin-skillforce 0.1.0 → 0.2.0-beta.0

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/create.js

@@ -3,7 +3,8 @@
  * 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.
+ *   `learning/<slug>`, verified after creation; rolled back on any failure. A new
+ *   branch is an orphan branch, so the course starts with no host files or history.
  * - other kinds: a plain `learning/<slug>/` folder.
  *
  * `skillforce save <slug> [-m msg]` commits the course worktree so its
@@ -15,7 +16,7 @@ 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]+)*$/;
+export 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();
@@ -25,6 +26,23 @@ function tryGit(cwd, args) {
   try { return git(cwd, args); } catch { return null; }
 }
 
+function gitOutput(cwd, args) {
+  try {
+    return execFileSync('git', args, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (err) {
+    return `${err.stdout || ''}${err.stderr || ''}`;
+  }
+}
+
+/**
+ * Whether `git worktree add --orphan` exists, probed from the usage text (`-h` changes nothing).
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function supportsOrphanWorktree(cwd) {
+  return /--orphan\b/.test(gitOutput(cwd, ['worktree', 'add', '-h']));
+}
+
 /** Registered worktrees as `{ path, branch }` (branch without `refs/heads/`). */
 export function listWorktrees(cwd) {
   const out = tryGit(cwd, ['worktree', 'list', '--porcelain']) || '';
@@ -44,25 +62,49 @@ function isCourseWorktree(cwd, dir, branch) {
   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;
+/** An existing ref that would stop git from writing `refs/heads/<branch>` (D/F conflict). */
+function refBlocked(root, branch) {
+  const parts = branch.split('/');
+  for (let i = 1; i < parts.length; i++) {
+    const ancestor = `refs/heads/${parts.slice(0, i).join('/')}`;
+    if (tryGit(root, ['rev-parse', '--verify', '-q', ancestor]) !== null) return true;
+  }
+  const descendants = tryGit(
+    root, ['for-each-ref', '--count=1', '--format=%(refname)', `refs/heads/${branch}/`],
+  );
+  return (descendants || '') !== '';
+}
+
+/**
+ * Keep a path inside the host repo out of `git status` without touching tracked files.
+ * @returns {string|null} the exclude line ensured, or null when git already ignores the path.
+ */
+export function excludeRepoPath(root, cwd, target) {
+  const abs = isAbsolute(target) ? target : join(cwd, target);
+  if (tryGit(root, ['check-ignore', '-q', abs]) !== null) return null;
   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 line = `/${relative(root, abs).split('\\').join('/')}/`;
   const current = existsSync(excludeFile) ? readFileSync(excludeFile, 'utf-8') : '';
-  if (current.split('\n').includes(line)) return;
+  if (current.split('\n').includes(line)) return line;
   appendFileSync(excludeFile, `${current && !current.endsWith('\n') ? '\n' : ''}${line}\n`);
+  return line;
+}
+
+/** Keep `learning/` out of the host repo's `git status`. */
+function excludeLearningDir(root, cwd) {
+  return excludeRepoPath(root, cwd, join(cwd, 'learning'));
 }
 
 /**
  * Create (or reattach) the course directory. Throws with a user-facing message.
+ * @param {{ cwd: string, slug: string, kind: string, orphanStrategy?: 'auto'|'fallback' }} options
+ *   `orphanStrategy: 'fallback'` forces the multi-step orphan procedure (tests only).
  * @returns {{ slug: string, kind: string, dir: string, branch: string|null, created: boolean }}
  */
-export function createCourse({ cwd, slug, kind }) {
+export function createCourse({ cwd, slug, kind, orphanStrategy = 'auto' }) {
   if (!SLUG_RE.test(slug || '')) {
     throw new Error(`Invalid slug ${JSON.stringify(slug)} — use lowercase a-z, 0-9 and single hyphens.`);
   }
@@ -96,14 +138,29 @@ export function createCourse({ cwd, slug, kind }) {
   }
 
   const branchExists = tryGit(root, ['rev-parse', '--verify', '-q', `refs/heads/${branch}`]) !== null;
+  if (!branchExists && refBlocked(root, branch)) {
+    throw new Error(`Cannot create the ${branch} branch — an existing branch name blocks it. ` +
+      'Rename or delete it — nothing was kept.');
+  }
+  const useFallback = orphanStrategy === 'fallback' || !supportsOrphanWorktree(root);
   try {
-    // Reattach an existing branch (course restored after its worktree was pruned).
-    git(root, ['worktree', 'add', dir, ...(branchExists ? [branch] : ['-b', branch])]);
+    if (branchExists) {
+      // Reattach an existing branch (course restored after its worktree was pruned).
+      git(root, ['worktree', 'add', dir, branch]);
+    } else if (useFallback) {
+      git(root, ['worktree', 'add', '--detach', dir]);
+      git(dir, ['switch', '--orphan', branch]);
+    } else {
+      git(root, ['worktree', 'add', '--orphan', '-b', branch, dir]);
+    }
     if (!isCourseWorktree(root, dir, branch)) throw new Error('worktree is not registered after creation');
+    if (!branchExists && tryGit(dir, ['rev-parse', '--verify', '-q', 'HEAD']) !== null) {
+      throw new Error(`branch ${branch} is not orphan`);
+    }
   } catch (err) {
     tryGit(root, ['worktree', 'remove', '--force', dir]);
     if (!branchExists) tryGit(root, ['branch', '-D', branch]);
-    rmSync(dir, { recursive: true, force: true });
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* a path through a file (ENOTDIR) has nothing to remove */ }
     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}`);

package/bin/commands/import.js

@@ -1,9 +1,9 @@
 /**
  * `skillforce import [slug|--all] [--dry-run]` (CLI-07) — bring CLI courses into Studio.
  *
- * Reads `learning/{slug}/` (primary) and legacy `courses/{slug}/` through `course-reader.js` and
- * writes them into the shared Studio SQLite DB. Everything goes through the repository or the same
- * StorageAdapter, so Studio sees identical rows:
+ * Reads `learning/{slug}/` through `course-reader.js` and writes them into the shared Studio SQLite
+ * DB. Everything goes through the repository or the same StorageAdapter, so Studio sees identical
+ * rows:
  *
  *   COURSE.md          → courses (title, level, kind, goal) + lessons (sections, status, dates)
  *   lectures/NN-*.md   → lesson_versions (ordered)
@@ -496,14 +496,14 @@ export async function run(ctx = {}) {
   const selected = slug ? courses.filter((c) => c.slug === slug) : courses;
 
   if (slug && selected.length === 0) {
-    console.error(style('error', `No course "${slug}" found in learning/ or courses/.`));
+    console.error(style('error', `No course "${slug}" found in learning/.`));
     process.exitCode = 1;
     return { courses: 0, error: `not found: ${slug}` };
   }
 
   if (selected.length === 0) {
     console.log('');
-    console.log(style('info', 'No courses found in learning/ or courses/.'));
+    console.log(style('info', 'No courses found in learning/.'));
     console.log('');
     return { courses: 0 };
   }

package/bin/commands/status.js

@@ -64,7 +64,7 @@ export async function run({ args = [], cwd = process.cwd(), chalk } = {}) {
       return;
     }
     console.log('');
-    console.log(style('info', 'No courses found in learning/ or courses/.'));
+    console.log(style('info', 'No courses found in learning/.'));
     console.log('');
     console.log('  Start one in your agent:   /professor:new-topic');
     console.log('  Or install a course:       npx ronin-skillforce install <name>');

package/bin/commands/studio-autostart.js

@@ -0,0 +1,414 @@
+/**
+ * `skillforce studio --autostart on|off`, `--status` and `--stop` (RON-297).
+ *
+ * Every launchd, process-list and signal call below uses an argument array and is injectable, so
+ * tests never load a real LaunchAgent, never list a real process and never signal one.
+ */
+import { execFileSync } from 'child_process';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, isAbsolute, join } from 'path';
+import { maskToken, readTokenFile, tokenFilePath } from '../../web/security.js';
+import {
+  isPidAlive,
+  logFilePath,
+  probeStudioHealth,
+  readState,
+  removeState,
+} from './studio-state.js';
+
+export const LABEL = 'com.ronin-skillforce.studio';
+export const LAUNCH_AGENT_FILE = `${LABEL}.plist`;
+export const UNSUPPORTED_PLATFORM = 'Studio auto-start is only supported on macOS yet.';
+export const STABLE_INSTALL_HINT = 'Install it globally first: npm i -g ronin-skillforce';
+
+/**
+ * Absolute plist path. launchd only reads `~/Library/LaunchAgents`, so this uses the OS home and
+ * never `PROFESSOR_HOME`.
+ * @param {{ home?: string }} [opts]
+ * @returns {string}
+ */
+export function launchAgentPath({ home = homedir() } = {}) {
+  return join(home, 'Library', 'LaunchAgents', LAUNCH_AGENT_FILE);
+}
+
+/** Escape the five XML entities; a home directory may legitimately contain `&`. */
+function xmlEscape(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/** Show a path under the user's home with `~` so status output stays short. */
+export function displayPath(file, { home = homedir() } = {}) {
+  const prefix = `${home}/`;
+  return file.startsWith(prefix) ? `~/${file.slice(prefix.length)}` : file;
+}
+
+/**
+ * Build the LaunchAgent plist. `ProgramArguments` point at the absolute Node executable and the
+ * absolute CLI entry, never at `npx`: launchd has no shell PATH, no network and no version pinning.
+ *
+ * @param {{ nodePath: string, cliPath: string, port: number, apiPort: number,
+ *           professorHome?: string, pathEnv?: string, logPath: string }} opts
+ * @returns {string}
+ */
+export function buildLaunchAgentPlist({
+  nodePath,
+  cliPath,
+  port,
+  apiPort,
+  professorHome,
+  pathEnv,
+  logPath,
+} = {}) {
+  for (const [name, value] of Object.entries({ nodePath, cliPath, logPath })) {
+    if (typeof value !== 'string' || value === '') {
+      throw new Error(`Cannot build the LaunchAgent plist: ${name} is missing.`);
+    }
+  }
+  for (const [name, value] of Object.entries({ port, apiPort })) {
+    if (!Number.isInteger(Number(value)) || Number(value) <= 0) {
+      throw new Error(`Cannot build the LaunchAgent plist: ${name} is not a port.`);
+    }
+  }
+
+  const args = [
+    nodePath,
+    cliPath,
+    'studio',
+    '--no-open',
+    '--strict-port',
+    '--port',
+    String(port),
+    '--api-port',
+    String(apiPort),
+  ];
+  const env = [];
+  if (professorHome) {
+    env.push(`    <key>PROFESSOR_HOME</key>`, `    <string>${xmlEscape(professorHome)}</string>`);
+  }
+  if (pathEnv) {
+    env.push(`    <key>PATH</key>`, `    <string>${xmlEscape(pathEnv)}</string>`);
+  }
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" ' +
+      '"http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+    '  <key>Label</key>',
+    `  <string>${LABEL}</string>`,
+    '  <key>ProgramArguments</key>',
+    '  <array>',
+    ...args.map((arg) => `    <string>${xmlEscape(arg)}</string>`),
+    '  </array>',
+    ...(env.length
+      ? ['  <key>EnvironmentVariables</key>', '  <dict>', ...env, '  </dict>']
+      : []),
+    '  <key>RunAtLoad</key>',
+    '  <true/>',
+    '  <key>KeepAlive</key>',
+    '  <dict>',
+    '    <key>SuccessfulExit</key>',
+    '    <false/>',
+    '  </dict>',
+    '  <key>ThrottleInterval</key>',
+    '  <integer>30</integer>',
+    '  <key>StandardOutPath</key>',
+    `  <string>${xmlEscape(logPath)}</string>`,
+    '  <key>StandardErrorPath</key>',
+    `  <string>${xmlEscape(logPath)}</string>`,
+    '</dict>',
+    '</plist>',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Refuse to install an agent that points into a throwaway path. A npx cache entry is deleted
+ * whenever npm feels like it, which would leave a LaunchAgent that fails at every login.
+ *
+ * @param {{ cliPath: string, execPath?: string }} opts
+ * @returns {{ cliPath: string, nodePath: string }}
+ */
+export function assertStableInstall({ cliPath, execPath = process.execPath } = {}) {
+  if (typeof cliPath !== 'string' || !isAbsolute(cliPath) || !existsSync(cliPath)) {
+    throw new Error(
+      `Studio auto-start needs a stable install: the CLI entry point (${cliPath || 'unknown'}) ` +
+        `was not found. ${STABLE_INSTALL_HINT}`
+    );
+  }
+  const unstable = [cliPath, execPath].find((value) => String(value).includes('/_npx/'));
+  if (unstable) {
+    throw new Error(
+      `Studio auto-start needs a stable install: this copy runs from the npx cache ` +
+        `(${unstable}), which can be deleted at any time. ${STABLE_INSTALL_HINT}`
+    );
+  }
+  return { cliPath, nodePath: execPath };
+}
+
+/**
+ * The three launchctl calls this feature needs, with argv arrays and no shell.
+ * @param {{ exec?: Function, uid?: number, platform?: string }} [opts]
+ * @returns {{ bootstrap: (plistPath: string) => object, bootout: () => object,
+ *             kill: (signal?: string) => object }}
+ */
+export function createLaunchctl({
+  exec = execFileSync,
+  uid = typeof process.getuid === 'function' ? process.getuid() : null,
+  platform = process.platform,
+} = {}) {
+  const run = (args) => {
+    try {
+      const stdout = exec('launchctl', args, { stdio: 'pipe', encoding: 'utf8' });
+      return { ok: true, stdout: String(stdout || ''), stderr: '' };
+    } catch (err) {
+      return {
+        ok: false,
+        stdout: String(err?.stdout || ''),
+        stderr: String(err?.stderr || err?.message || ''),
+      };
+    }
+  };
+  const domain = `gui/${uid}`;
+  return {
+    domain,
+    bootstrap: (plistPath) => run(['bootstrap', domain, plistPath]),
+    bootout: () => run(['bootout', `${domain}/${LABEL}`]),
+    kill: (signal = 'SIGTERM') => run(['kill', signal, `${domain}/${LABEL}`]),
+  };
+}
+
+/** True for the "already loaded" answers `launchctl bootstrap` gives on a re-install. */
+function isAlreadyLoaded(result) {
+  const text = `${result.stderr} ${result.stdout}`;
+  return /already|Bootstrap failed: 5|Input\/output error/i.test(text);
+}
+
+/**
+ * Install (or re-install) the LaunchAgent: log directory, plist, then `launchctl bootstrap`.
+ * Re-running is idempotent — the previous registration is removed first and retried once.
+ *
+ * @param {{ port: number, apiPort: number, cliPath: string, execPath?: string,
+ *           env?: Record<string,string|undefined>, userHome?: string, platform?: string,
+ *           exec?: Function, uid?: number }} opts
+ * @returns {{ plistPath: string, logPath: string }}
+ */
+export function enableAutostart({
+  port,
+  apiPort,
+  cliPath,
+  execPath = process.execPath,
+  env = process.env,
+  userHome = homedir(),
+  platform = process.platform,
+  exec = execFileSync,
+  uid,
+} = {}) {
+  if (platform !== 'darwin') throw new Error(UNSUPPORTED_PLATFORM);
+
+  const install = assertStableInstall({ cliPath, execPath });
+  const plistPath = launchAgentPath({ home: userHome });
+  const logPath = logFilePath({ env });
+  mkdirSync(dirname(logPath), { recursive: true });
+  mkdirSync(dirname(plistPath), { recursive: true });
+
+  const plist = buildLaunchAgentPlist({
+    nodePath: install.nodePath,
+    cliPath: install.cliPath,
+    port,
+    apiPort,
+    professorHome: env.PROFESSOR_HOME,
+    pathEnv: env.PATH,
+    logPath,
+  });
+  writeFileSync(plistPath, plist, { mode: 0o644 });
+
+  const launchctl = createLaunchctl({ exec, uid, platform });
+  launchctl.bootout();
+  let result = launchctl.bootstrap(plistPath);
+  if (!result.ok && isAlreadyLoaded(result)) {
+    launchctl.bootout();
+    result = launchctl.bootstrap(plistPath);
+  }
+  if (!result.ok) {
+    throw new Error(
+      `launchctl bootstrap failed for ${plistPath}: ${result.stderr.trim() || 'unknown error'}`
+    );
+  }
+  return { plistPath, logPath };
+}
+
+/**
+ * Remove the LaunchAgent and its plist. Safe to call when nothing was installed.
+ * @param {{ userHome?: string, platform?: string, exec?: Function, uid?: number }} [opts]
+ * @returns {{ plistPath: string, removed: boolean }}
+ */
+export function disableAutostart({
+  userHome = homedir(),
+  platform = process.platform,
+  exec = execFileSync,
+  uid,
+} = {}) {
+  if (platform !== 'darwin') throw new Error(UNSUPPORTED_PLATFORM);
+
+  const plistPath = launchAgentPath({ home: userHome });
+  createLaunchctl({ exec, uid, platform }).bootout();
+  const removed = existsSync(plistPath);
+  if (removed) rmSync(plistPath, { force: true });
+  return { plistPath, removed };
+}
+
+/**
+ * @param {{ userHome?: string }} [opts]
+ * @returns {{ enabled: boolean, plistPath: string }}
+ */
+export function autostartInfo({ userHome = homedir() } = {}) {
+  const plistPath = launchAgentPath({ home: userHome });
+  return { enabled: existsSync(plistPath), plistPath };
+}
+
+/**
+ * Collect what `--status` reports. Reads only: no file or token is created, nothing is started.
+ *
+ * @param {{ env?: Record<string,string|undefined>, userHome?: string, kill?: Function,
+ *           fetchImpl?: typeof fetch }} [opts]
+ * @returns {Promise<{ status: 'running'|'unhealthy'|'stopped', state: object|null,
+ *                     token: string|null, autostart: { enabled: boolean, plistPath: string },
+ *                     logPath: string }>}
+ */
+export async function collectStatus({
+  env = process.env,
+  userHome = homedir(),
+  kill = process.kill,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const state = readState({ env });
+  const token = readTokenFile(tokenFilePath(env));
+  const alive = Boolean(state) && isPidAlive(state.pid, { kill });
+  const answering =
+    alive && (await probeStudioHealth({ apiUrl: state.apiUrl, token, fetchImpl }));
+  const status = answering ? 'running' : alive ? 'unhealthy' : 'stopped';
+  return {
+    status,
+    state,
+    token,
+    autostart: autostartInfo({ userHome }),
+    logPath: logFilePath({ env }),
+  };
+}
+
+/**
+ * Render the `--status` report. The token appears in full only inside the pairing URL; the separate
+ * token line is masked.
+ *
+ * @param {{ status: string, state: object|null, token: string|null, pairingUrl?: string|null,
+ *           autostart: { enabled: boolean, plistPath: string }, logPath: string,
+ *           userHome?: string }} report
+ * @returns {string}
+ */
+export function formatStatus({
+  status,
+  state,
+  token,
+  pairingUrl,
+  autostart,
+  logPath,
+  userHome = homedir(),
+}) {
+  const autostartLine = `  Autostart:   ${autostart.enabled ? `on (${LABEL})` : 'off'}`;
+  const logLine = `  Log:         ${displayPath(logPath, { home: userHome })}`;
+
+  if (status === 'running' && state) {
+    return [
+      `Professor Studio: running (pid ${state.pid})`,
+      `  Studio URL:  ${state.studioUrl}`,
+      pairingUrl
+        ? `  Pairing URL: ${pairingUrl}`
+        : '  Pairing URL: (no token yet — run: skillforce studio --rotate-token)',
+      `  Token:       ${maskToken(token)}`,
+      autostartLine,
+      logLine,
+    ].join('\n');
+  }
+  if (status === 'unhealthy' && state) {
+    return [
+      `Professor Studio: not answering (pid ${state.pid} from studio.json)`,
+      `  Studio URL:  ${state.studioUrl}`,
+      autostartLine,
+      logLine,
+    ].join('\n');
+  }
+  return ['Professor Studio: not running', autostartLine, logLine].join('\n');
+}
+
+/** The `ps -o command=` line for a pid, or `null` when the process is gone. */
+function readCommandLine(pid, { exec = execFileSync } = {}) {
+  try {
+    const command = exec('ps', ['-o', 'command=', '-p', String(pid)], {
+      stdio: 'pipe',
+      encoding: 'utf8',
+    });
+    return String(command || '').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** A pid is ours only when its command line is a Studio CLI run. */
+export function isStudioCommand(command) {
+  if (!command) return false;
+  return command.includes('cli.js') && command.includes('studio');
+}
+
+/**
+ * Stop Studio: the LaunchAgent first when it is installed, otherwise the pid from `studio.json`.
+ * A pid whose command line is not a Studio CLI run is never signalled.
+ *
+ * @param {{ env?: Record<string,string|undefined>, userHome?: string, platform?: string,
+ *           exec?: Function, uid?: number, kill?: Function }} [opts]
+ * @returns {Promise<{ stopped: boolean, via?: 'launchctl'|'pid', pid?: number|null,
+ *                     reason?: 'not_running'|'stale', refused?: boolean, command?: string|null }>}
+ */
+export async function stopStudio({
+  env = process.env,
+  userHome = homedir(),
+  platform = process.platform,
+  exec = execFileSync,
+  uid,
+  kill = process.kill,
+} = {}) {
+  const state = readState({ env });
+  const { plistPath } = autostartInfo({ userHome });
+
+  if (existsSync(plistPath)) {
+    const result = createLaunchctl({ exec, uid, platform }).kill('SIGTERM');
+    if (result.ok) {
+      removeState({ env });
+      return { stopped: true, via: 'launchctl', pid: state?.pid ?? null };
+    }
+  }
+
+  if (!state) return { stopped: false, reason: 'not_running' };
+  if (!isPidAlive(state.pid, { kill })) {
+    removeState({ env });
+    return { stopped: false, reason: 'stale', pid: state.pid };
+  }
+
+  const command = readCommandLine(state.pid, { exec });
+  if (!isStudioCommand(command)) {
+    return { stopped: false, refused: true, pid: state.pid, command };
+  }
+
+  try {
+    kill(state.pid, 'SIGTERM');
+  } catch (err) {
+    if (err?.code !== 'ESRCH') throw err;
+  }
+  removeState({ env });
+  return { stopped: true, via: 'pid', pid: state.pid };
+}