@xhulz/nina 0.28.16

package/src/shell.mjs

@@ -0,0 +1,181 @@
+/**
+ * `nina` with no command, on a terminal: the banner once, then a prompt that runs commands under it.
+ *
+ * Every command prints the banner, and it stays that way — see `src/banner.mjs`. Run one after another,
+ * that put six lines of art between every two answers, and the owner asked for what Claude Code does: the
+ * name once at the top of a session, and the work below it. Each command still runs as its own process,
+ * exactly as it does from the shell, so nothing a command does to the process — an exit code, a change
+ * of directory, an interview that reads the terminal — can leave the session in a state the next command
+ * inherits. The session only tells it to leave the banner out.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+import { PINK, printBanner, useColor } from './banner.mjs';
+import { shellHistoryFile } from './paths.mjs';
+
+/** Words the session answers itself rather than handing to a command. */
+const LEAVE = new Set(['exit', 'quit', 'q']);
+
+/** The most commands kept for the arrow keys. */
+const HISTORY = 500;
+
+/**
+ * Splits a typed line into arguments the way a shell would for what these commands take: words, and
+ * quoted strings that keep their spaces.
+ *
+ * @param {string} line - What was typed.
+ * @returns {string[]}
+ */
+export function words(line) {
+  const out = [];
+  let word = null;
+  let quote = null;
+  for (let i = 0; i < line.length; i += 1) {
+    const c = line[i];
+    if (quote) {
+      if (c === quote) quote = null;
+      else if (c === '\\' && quote === '"' && i + 1 < line.length) word += line[(i += 1)];
+      else word += c;
+    } else if (c === '"' || c === "'") {
+      quote = c;
+      word ??= '';
+    } else if (/\s/.test(c)) {
+      if (word !== null) out.push(word);
+      word = null;
+    } else if (c === '\\' && i + 1 < line.length) {
+      word = (word ?? '') + line[(i += 1)];
+    } else {
+      word = (word ?? '') + c;
+    }
+  }
+  if (word !== null) out.push(word);
+  return out;
+}
+
+/**
+ * The commands typed in earlier sessions, newest first, as readline takes them.
+ *
+ * @returns {string[]}
+ */
+function pastCommands() {
+  try {
+    return readFileSync(shellHistoryFile(), 'utf8').split('\n').filter(Boolean).slice(-HISTORY).reverse();
+  } catch {
+    return [];
+  }
+}
+
+/** Keeps one command for the next session; a history that cannot be written costs only the arrow keys. */
+function keep(line) {
+  try {
+    mkdirSync(dirname(shellHistoryFile()), { recursive: true });
+    appendFileSync(shellHistoryFile(), `${line}\n`);
+  } catch {
+    // The session goes on without it.
+  }
+}
+
+/**
+ * Runs the session until `exit`, Ctrl-D, or Ctrl-C twice on an empty line.
+ *
+ * @param {{bin: string, version: string, commands: string[]}} options - The CLI to run each command
+ *   with, its version for the banner, and the command names, for Tab.
+ * @returns {Promise<number>} Process exit code.
+ */
+export function shell({ bin, version, commands }) {
+  const terminal = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const dim = (s) => (useColor() ? `\x1b[2m${s}\x1b[0m` : s);
+  const prompt = useColor() ? `\x1b[38;2;${PINK.join(';')}mnina ›\x1b[0m ` : 'nina › ';
+
+  printBanner(version);
+  console.log(dim('  type a command — stats, check, upgrade --to <version> — `help` lists them, `clear` starts the screen over, `exit` leaves\n'));
+
+  const names = [...commands, 'help', 'clear', 'exit'];
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt,
+    terminal,
+    history: terminal ? pastCommands() : [],
+    historySize: HISTORY,
+    removeHistoryDuplicates: true,
+    completer: (line) => {
+      const typed = words(line);
+      if (typed.length > 1 || /\s$/.test(line)) return [[], line];
+      const hits = names.filter((n) => n.startsWith(typed[0] ?? ''));
+      return [hits.length ? hits : names, line];
+    },
+  });
+
+  // A command interrupted with Ctrl-C takes the signal; the session, which receives it too, stays.
+  const stay = () => {};
+  process.on('SIGINT', stay);
+
+  // Ctrl-C clears what was typed; on an empty line it says how to leave, and a second one leaves.
+  let interrupted = false;
+  rl.on('SIGINT', () => {
+    if (rl.line.length > 0) {
+      interrupted = false;
+      rl.write(null, { ctrl: true, name: 'u' });
+      return;
+    }
+    if (interrupted) {
+      rl.close();
+      return;
+    }
+    interrupted = true;
+    process.stdout.write(`\n${dim('  (Ctrl-C again, or exit, to leave)')}\n`);
+    rl.prompt();
+  });
+
+  // Closed, the session reads nothing more: Node 24 goes on handing over the lines already read after
+  // `exit`, and the first of them ran a command and then prompted on a closed interface.
+  let closed = false;
+  return new Promise((done) => {
+    rl.on('line', (line) => {
+      if (closed) return;
+      interrupted = false;
+      const typed = words(line);
+      // Typed out of habit, the way it is run from the shell.
+      if (typed[0] === 'nina') typed.shift();
+      if (typed.length === 0) {
+        rl.prompt();
+        return;
+      }
+      if (terminal) keep(line.trim());
+      if (LEAVE.has(typed[0])) {
+        rl.close();
+        return;
+      }
+      if (typed[0] === 'clear') {
+        process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+        printBanner(version);
+        rl.prompt();
+        return;
+      }
+
+      // The command owns the terminal while it runs: line editing back to the terminal's, and its
+      // stdin the session's own, so an interview can read it. Piped input stays the session's.
+      if (terminal) process.stdin.setRawMode(false);
+      const run = spawnSync(process.execPath, [bin, ...typed], {
+        stdio: [terminal ? 'inherit' : 'ignore', 'inherit', 'inherit'],
+        env: { ...process.env, NINA_SHELL: '1' },
+      });
+      if (terminal) process.stdin.setRawMode(true);
+      if (run.status) console.log(dim(`  exit ${run.status}`));
+      else if (run.signal) console.log(dim(`  stopped (${run.signal})`));
+      process.stdout.write('\n');
+      rl.prompt();
+    });
+    rl.on('close', () => {
+      closed = true;
+      process.removeListener('SIGINT', stay);
+      if (terminal) process.stdout.write('\n');
+      done(0);
+    });
+    rl.prompt();
+  });
+}

package/src/steps.mjs

@@ -0,0 +1,78 @@
+/**
+ * Runs a sequence of steps and shows which one is working, which one finished, and which one
+ * stopped the sequence.
+ *
+ * This exists because a correct procedure nobody can remember is not a procedure. Moving a
+ * project forward was six commands in a fixed order, where getting the order wrong quietly
+ * overwrote the project's own file — so the order belongs in the tool, not in a message.
+ *
+ * The animation is a convenience, not the contract: a step reports the same text either way,
+ * so a log, a CI run and a pipe all read like the terminal does minus the dots.
+ */
+
+/** Frames of the ellipsis, slow enough to read and fast enough to look alive. */
+const FRAMES = ['.  ', '.. ', '...'];
+const TICK = 220;
+
+/**
+ * Whether to animate — a pipe, a CI log and a test all get plain lines instead.
+ *
+ * @param {NodeJS.WriteStream} stream
+ * @returns {boolean}
+ */
+function animates(stream) {
+  return Boolean(stream.isTTY) && !process.env.NINA_NO_SPINNER;
+}
+
+/**
+ * Runs the steps in order, stopping at the first failure.
+ *
+ * A step is `{label, run}` where `run` returns `{ok, detail, log}`: `detail` is the one-line
+ * summary that replaces the ellipsis, and `log` is what to print when it fails. A step may
+ * also carry `skip`, which reports it as not applicable rather than running it.
+ *
+ * @param {{label: string, skip?: boolean, run: () => {ok: boolean, detail?: string, log?: string}}[]} steps
+ * @param {{stream?: NodeJS.WriteStream}} [options]
+ * @returns {{failed: null | {label: string, log: string}, done: string[]}}
+ */
+export function runSteps(steps, options = {}) {
+  const stream = options.stream ?? process.stdout;
+  const live = animates(stream);
+  const done = [];
+
+  for (const step of steps) {
+    if (step.skip) {
+      stream.write(`  ·  ${step.label} — not applicable here\n`);
+      continue;
+    }
+
+    let frame = 0;
+    let timer = null;
+    if (live) {
+      stream.write(`  ${FRAMES[0]} ${step.label}`);
+      timer = setInterval(() => {
+        frame = (frame + 1) % FRAMES.length;
+        stream.write(`\r  ${FRAMES[frame]} ${step.label}`);
+      }, TICK);
+      timer.unref?.();
+    }
+
+    let result;
+    try {
+      result = step.run();
+    } catch (error) {
+      result = { ok: false, log: String(error?.stack ?? error) };
+    } finally {
+      if (timer) clearInterval(timer);
+      // `\r` alone leaves the tail of the longest line behind when the next one is shorter.
+      if (live) stream.write('\r\u001b[K');
+    }
+
+    const mark = result.ok ? '✓' : '✗';
+    stream.write(`  ${mark}  ${step.label}${result.detail ? ` — ${result.detail}` : ''}\n`);
+    if (!result.ok) return { failed: { label: step.label, log: result.log ?? '' }, done };
+    done.push(step.label);
+  }
+
+  return { failed: null, done };
+}

package/src/tools.mjs

@@ -0,0 +1,184 @@
+/**
+ * Whether every agent spec can actually do what it says: its `tools:` allowlist against what its
+ * body asks for, and every skill it names against what is installed.
+ *
+ * Written first in a consuming project, as its own detector, after a stage was twice instructed to
+ * do something the runtime never gave it the means to do: `Skill` was absent from all nine `tools:`
+ * lists while the specs made skills mandatory — 2 invocations in 743 runs — and devops was told to
+ * invoke Playwright through `Skill` when Playwright is an MCP server and no such skill exists.
+ * Neither surfaces on its own: the rule stays written, the agent reports success, and only a count
+ * over transcripts shows the zero. It lives here now so every project gets it, the same move that
+ * took the detector runner out of each project and into the package.
+ *
+ * Deliberately conservative. Skill and the browser tools are the two that actually went wrong and
+ * both are unambiguous; Bash is not inferred, because specs quote commands meant for other stages.
+ * A check that cries wolf gets ignored, which is the failure it exists to prevent.
+ */
+
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * A skill id carries a `-` or a `:`. Skills sections quote CLI words in backticks too — `validate`,
+ * `wrangler` — and every installed skill id is hyphenated or namespaced, so requiring one removes
+ * that whole class of false positive for nothing.
+ */
+const SKILL_ID = /^[a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)?$/;
+
+/**
+ * Every skill installed for a project, by the id an agent would invoke: user skills by name,
+ * plugin skills as `<plugin>:<name>`, and the project's own.
+ *
+ * @param {string} target - The project directory.
+ * @returns {Promise<Set<string>>}
+ */
+export async function installedSkills(target) {
+  const found = new Set();
+  const user = join(homedir(), '.claude', 'skills');
+  for (const e of await readdir(user, { withFileTypes: true }).catch(() => [])) {
+    if (existsSync(join(user, e.name, 'SKILL.md'))) found.add(e.name);
+  }
+  const cache = join(homedir(), '.claude', 'plugins', 'cache');
+  for (const market of await readdir(cache, { withFileTypes: true }).catch(() => [])) {
+    if (!market.isDirectory()) continue;
+    for (const plugin of await readdir(join(cache, market.name), { withFileTypes: true }).catch(() => [])) {
+      if (!plugin.isDirectory()) continue;
+      const pluginDir = join(cache, market.name, plugin.name);
+      for (const version of await readdir(pluginDir, { withFileTypes: true }).catch(() => [])) {
+        for (const skill of await readdir(join(pluginDir, version.name, 'skills'), { withFileTypes: true }).catch(() => [])) {
+          if (skill.isDirectory()) found.add(`${plugin.name}:${skill.name}`);
+        }
+      }
+    }
+  }
+  const own = join(target, '.claude', 'skills');
+  for (const e of await readdir(own, { withFileTypes: true }).catch(() => [])) {
+    if (e.isDirectory()) found.add(e.name);
+  }
+  return found;
+}
+
+/**
+ * The tools a spec's frontmatter grants.
+ *
+ * @param {string} spec - A composed agent spec.
+ * @returns {string[]}
+ */
+export function granted(spec) {
+  const line = /^tools:\s*(.+)$/m.exec(spec);
+  return line ? line[1].split(',').map((t) => t.trim()).filter(Boolean) : [];
+}
+
+/**
+ * What a spec's body requires, and which skills it names.
+ *
+ * @param {string} spec - A composed agent spec.
+ * @returns {{needs: Set<string>, skills: Set<string>}}
+ */
+export function required(spec) {
+  const needs = new Set();
+  const skills = new Set();
+  const start = spec.indexOf('## Skills you MUST consult');
+  if (start !== -1) {
+    const rest = spec.slice(start + 3);
+    const end = rest.indexOf('\n## ');
+    const section = end === -1 ? rest : rest.slice(0, end);
+    // A skill is named where the section lists one: in bold, or as the first cell of a table row. Any
+    // other name in backticks is prose — in some roles the project's own introduction composes inside
+    // this section, and a region it named, `us-east-1`, was reported as a skill that is not installed.
+    for (const line of section.split('\n')) {
+      const listed = [
+        ...[...line.matchAll(/\*\*`([^`]+)`\*\*/g)].map((m) => m[1]),
+        ...(/^\|\s*`([^`]+)`\s*\|/.exec(line)?.slice(1) ?? []),
+      ];
+      for (const token of listed) {
+        if (SKILL_ID.test(token) && (token.includes('-') || token.includes(':'))) skills.add(token);
+      }
+    }
+  }
+  if (skills.size > 0 || /\bSkill\b tool|via the `Skill`/.test(spec)) needs.add('Skill');
+  for (const [, tool] of spec.matchAll(/`?(browser_[a-z_]+)`?/g)) needs.add(`mcp__plugin_playwright_playwright__${tool}`);
+  return { needs, skills };
+}
+
+/**
+ * Every mismatch between what the specs ask for and what they are given.
+ *
+ * @param {Map<string, string>} specs - Role → composed spec text.
+ * @param {Set<string>|null} installed - Installed skills, or null to skip that half — the grant
+ *   check is a fact about the harness, the install check a fact about one machine.
+ * @returns {string[]}
+ */
+export function toolFindings(specs, installed) {
+  const out = [];
+  for (const [role, spec] of [...specs].sort(([a], [b]) => a.localeCompare(b))) {
+    const has = granted(spec);
+    const { needs, skills } = required(spec);
+    for (const need of needs) if (!has.includes(need)) out.push(`${role}: its spec needs \`${need}\`, and its tools: does not grant it`);
+    if (installed) for (const s of skills) if (!installed.has(s)) out.push(`${role}: names skill \`${s}\`, which is not installed`);
+  }
+  return out;
+}
+
+/** What each frontmatter key a spec must carry does, said when it is missing. */
+const REQUIRED_KEYS = {
+  name: 'it cannot be dispatched by name',
+  description: 'Claude Code does not load an agent without one, so the pipeline has no such stage, and nothing says so',
+  tools: 'the agent inherits every tool the session has',
+};
+
+/**
+ * Every spec whose frontmatter lacks what Claude Code needs to load it as it is meant to run. The
+ * `description` was the silent one: seven roles left it to the project, every new project composed them
+ * without it, and the main session simply had no reviewer, qa or secops to dispatch — the stages stayed
+ * in the graph, and an agent improvised in their place ran none of their rules.
+ *
+ * @param {Map<string, string>} specs - Role → composed spec text.
+ * @returns {string[]}
+ */
+export function frontmatterFindings(specs) {
+  const out = [];
+  for (const [role, spec] of [...specs].sort(([a], [b]) => a.localeCompare(b))) {
+    if (!spec.startsWith('---\n')) {
+      out.push(`${role}: does not open with frontmatter — Claude Code does not load it`);
+      continue;
+    }
+    const front = spec.slice(4, spec.indexOf('\n---', 4));
+    for (const [key, why] of Object.entries(REQUIRED_KEYS)) {
+      if (!new RegExp(`^${key}:\\s*\\S`, 'm').test(front)) out.push(`${role}: frontmatter has no \`${key}:\` — ${why}`);
+    }
+  }
+  return out;
+}
+
+/** The model values a spec may declare: an alias Claude Code knows, `inherit`, or a full model id. */
+const MODEL_VALUE = /^(opus|sonnet|haiku|fable|inherit|claude-[a-z0-9.-]+(\[[a-z0-9]+\])?)$/;
+
+/** The effort levels a spec may declare. Which of them a model accepts is Claude Code's to say. */
+const EFFORT_VALUE = /^(low|medium|high|xhigh|max)$/;
+
+/**
+ * Every spec whose `model:` or `effort:` is none of those. The model is a stage's largest cost
+ * decision and the effort its next, and `nina stats` reads both back against what ran; a typo there
+ * is a stage on a model nobody chose, or at the session's effort with nothing saying so.
+ *
+ * @param {Map<string, string>} specs - Role → composed spec text.
+ * @returns {string[]}
+ */
+export function modelFindings(specs) {
+  const out = [];
+  for (const [role, spec] of [...specs].sort(([a], [b]) => a.localeCompare(b))) {
+    const front = spec.startsWith('---\n') ? spec.slice(4, spec.indexOf('\n---', 4)) : '';
+    const model = /^model:[ \t]*(.*)$/m.exec(front)?.[1].trim();
+    if (model !== undefined && !MODEL_VALUE.test(model)) {
+      out.push(`${role}: \`model: ${model}\` is neither an alias (opus, sonnet, haiku, fable, inherit) nor a model id`);
+    }
+    const effort = /^effort:[ \t]*(.*)$/m.exec(front)?.[1].trim();
+    if (effort !== undefined && !EFFORT_VALUE.test(effort)) {
+      out.push(`${role}: \`effort: ${effort}\` is not one of low, medium, high, xhigh, max`);
+    }
+  }
+  return out;
+}