npm - @profoundry-us/highball - Versions diffs - 0.1.0 → 0.3.0 - Mend

@profoundry-us/highball 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/ONBOARDING.md CHANGED Viewed

@@ -21,6 +21,13 @@ local tarball path they provide. In a repo with no `package.json`, create
 a minimal private one first (`{ "name": "<repo>", "private": true }`) and
 gitignore `node_modules/` if it isn't already.
+**Never run bare `npx highball` where the package is NOT installed**: the
+unscoped npm name `highball` belongs to an unrelated package, and npx
+would fetch that instead of this runner. Installed locally, the bare name
+is safe (npx resolves `node_modules/.bin` first — that's why install is
+step 0); for a one-off without installing, use the scoped form,
+`npx @profoundry-us/highball <command>`.
 ## 1. Survey the repo before writing anything
 Answer these by reading, not assuming:

package/README.md CHANGED Viewed

@@ -13,6 +13,12 @@ block, they just aren't recorded.
 Published releases: `npm install --save-dev @profoundry-us/highball`.
+Install before running anything: with the package in `node_modules`, the
+short `npx highball …` form resolves to this runner's binary. Without it,
+bare `npx highball` would fetch the unrelated unscoped `highball` package
+from the registry — for uninstalled one-offs, always use the scoped form
+(`npx @profoundry-us/highball <command>`).
 From a local tarball (pre-release):
 ```bash
@@ -80,6 +86,40 @@ The runner computes the branch's changed-file list once (it owns git) and
 hands it to every rule via `HIGHBALL_CHANGED_FILES` — check scripts stay pure
 analyzers and need no git in their execution context.
+## The MCP dashboard widget
+`highball mcp` serves the journal over MCP (stdio) with three tools —
+`list_runs`, `get_run`, `run_checks` — and an
+[MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) widget:
+in hosts that render Apps (Claude Desktop and friends), asking about your
+checks produces an interactive inline dashboard — click a run for per-rule
+detail with expandable command output, re-run fast or full checks from a
+button. In hosts without Apps support the same tools answer in plain text,
+per the extension's graceful-degradation rule. Register it as
+`command: npx`, `args: ["highball", "mcp"]` (or absolute paths for hosts
+that spawn outside your shell PATH).
+The split is capability-driven, not guesswork: the server reads the
+client's initialize capabilities (`io.modelcontextprotocol/ui`) — hosts
+that render MCP Apps get a short text summary plus the widget; everything
+else gets the full picture as aligned plain text. Widget development has
+its own harness — `npm run harness`, open http://localhost:3777 — which
+plays the host role against the real `assets/dashboard.html` and live
+journal data, so widget edits are a reload away instead of a Claude
+Desktop restart.
+## Run history without a dashboard
+Every run also appends to a local journal (`~/.highball/runs/<project>.jsonl`,
+pruned to the last 200) — unconditionally, whether or not reporting is
+configured. `npx highball runs` lists recent runs; `npx highball runs 3`
+shows one run's detail with failure output, and `--logs` prints every
+rule's captured output, GitHub-Actions-style — the journal keeps the last
+10KB per rule, pass or fail, while the dashboard receives failure tails
+only. So the runner is self-sufficient out of the box: the hosted
+dashboard adds team visibility, history beyond your machine, and
+attribution — it's never required to see what happened.
 ## Roadmap
 AI-judged rules (`rubric:` — headless Claude applying a markdown rubric to

package/assets/dashboard.html ADDED Viewed

@@ -0,0 +1,331 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>
+  :root {
+    --bg: #ffffff; --fg: #1a1a2e; --muted: #6b7280; --line: #e5e7eb;
+    --card: #f9fafb; --green: #16a34a; --green-bg: #dcfce7;
+    --red: #dc2626; --red-bg: #fee2e2; --gray-bg: #f3f4f6;
+    --accent: #4f39fa;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #111118; --fg: #e5e7eb; --muted: #9ca3af; --line: #2a2a35;
+      --card: #1a1a24; --green: #4ade80; --green-bg: #14321f;
+      --red: #f87171; --red-bg: #3b1518; --gray-bg: #23232e;
+      --accent: #8f85ff;
+    }
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; padding: 12px; background: var(--bg); color: var(--fg);
+    font: 13px/1.5 -apple-system, "Segoe UI", system-ui, sans-serif;
+  }
+  .head { display: flex; align-items: center; gap: 8px; margin-bottom: 10px; flex-wrap: wrap; }
+  .head h1 { font-size: 14px; margin: 0; }
+  .head .spacer { flex: 1; }
+  button {
+    font: inherit; font-size: 12px; border: 1px solid var(--line); border-radius: 6px;
+    background: var(--card); color: var(--fg); padding: 3px 10px; cursor: pointer;
+  }
+  button:hover { border-color: var(--accent); }
+  button.primary { background: var(--accent); border-color: var(--accent); color: #fff; }
+  .row {
+    display: flex; align-items: center; gap: 10px; padding: 7px 10px;
+    border: 1px solid var(--line); border-radius: 8px; background: var(--card);
+    margin-bottom: 6px; cursor: pointer;
+  }
+  .row:hover { border-color: var(--accent); }
+  .row .when, .row .meta { color: var(--muted); font-size: 12px; }
+  .group {
+    color: var(--muted); font-size: 11.5px; font-style: italic;
+    margin: 12px 2px 6px; white-space: nowrap; overflow: hidden;
+    text-overflow: ellipsis;
+  }
+  .group:first-child { margin-top: 2px; }
+  .row .spacer { flex: 1; }
+  .chip {
+    font-size: 11px; font-weight: 600; padding: 1px 8px; border-radius: 999px;
+    white-space: nowrap;
+  }
+  .chip.passed { color: var(--green); background: var(--green-bg); }
+  .chip.failed { color: var(--red); background: var(--red-bg); }
+  .chip.todo { color: var(--muted); background: var(--gray-bg); }
+  .mono { font-family: ui-monospace, Menlo, monospace; font-size: 12px; }
+  details.rule {
+    border: 1px solid var(--line); border-radius: 8px; background: var(--card);
+    margin-bottom: 6px;
+  }
+  details.rule > summary {
+    display: flex; align-items: center; gap: 10px; padding: 7px 10px;
+    cursor: pointer; list-style: none;
+  }
+  details.rule > summary::-webkit-details-marker { display: none; }
+  /* A rule with nothing to reveal (todo: no command ran) is NOT a details —
+     it must not advertise a chevron or a pointer cursor it can't honor. */
+  .rule.static > .rowline {
+    display: flex; align-items: center; gap: 10px; padding: 7px 10px;
+  }
+  .rule.static {
+    border: 1px solid var(--line); border-radius: 8px; background: var(--card);
+    margin-bottom: 6px;
+  }
+  .panel { border-top: 1px solid var(--line); padding: 4px 12px 10px; }
+  .panel-label {
+    font-size: 10px; text-transform: uppercase; letter-spacing: 0.08em;
+    opacity: 0.55; margin: 8px 0 4px;
+  }
+  .panel-note { font-size: 12px; opacity: 0.6; margin: 8px 0 2px; }
+  details.rule pre {
+    margin: 0; padding: 8px 10px; border-radius: 6px; background: var(--gray-bg);
+    overflow-x: auto; font-size: 11.5px; line-height: 1.45;
+    font-family: ui-monospace, Menlo, monospace; white-space: pre-wrap;
+  }
+  .empty { color: var(--muted); padding: 18px 6px; text-align: center; }
+  .glyph { width: 14px; text-align: center; font-weight: 700; }
+  .glyph.passed { color: var(--green); }
+  .glyph.failed { color: var(--red); }
+  .glyph.todo { color: var(--muted); }
+</style>
+</head>
+<body>
+<div id="app"><div class="empty">Loading Highball runs…</div></div>
+<script>
+(() => {
+  // Minimal MCP Apps client: JSON-RPC 2.0 over postMessage to the host.
+  // Kept dependency-free on purpose — the protocol surface this widget
+  // needs is initialize, tool-result notifications, and tools/call.
+  const pending = new Map();
+  let nextId = 1;
+  const post = (msg) => window.parent.postMessage(msg, "*");
+  const request = (method, params) => new Promise((resolve, reject) => {
+    const id = nextId++;
+    pending.set(id, { resolve, reject });
+    post({ jsonrpc: "2.0", id, method, params });
+  });
+  const notify = (method, params) => post({ jsonrpc: "2.0", method, params });
+  window.addEventListener("message", (event) => {
+    const msg = event.data;
+    if (!msg || msg.jsonrpc !== "2.0") return;
+    if (msg.id !== undefined && msg.method === undefined) {
+      const waiter = pending.get(msg.id);
+      if (waiter) {
+        pending.delete(msg.id);
+        msg.error ? waiter.reject(msg.error) : waiter.resolve(msg.result);
+      }
+      return;
+    }
+    if (msg.method === "ui/notifications/tool-result") {
+      toolInFlight = false;
+      const result = msg.params?.result ?? msg.params ?? {};
+      if (result.structuredContent) render(result.structuredContent);
+      return;
+    }
+    // The host streams tool-input while the originating tool is still
+    // executing (e.g. run_checks taking seconds) — don't let the
+    // impatient self-fetch clobber the view; the result is coming.
+    if (msg.method === "ui/notifications/tool-input" ||
+        msg.method === "ui/notifications/tool-input-partial") {
+      toolInFlight = true;
+      return;
+    }
+    if (msg.id !== undefined) {
+      post({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: "not supported" } });
+    }
+  });
+  async function callTool(name, args) {
+    const result = await request("tools/call", { name, arguments: args || {} });
+    if (result?.structuredContent) render(result.structuredContent);
+  }
+  // --- rendering ---------------------------------------------------------
+  const app = document.getElementById("app");
+  let context = { project: null, dir: null };
+  let toolInFlight = false;
+  function esc(text) {
+    return String(text ?? "").replace(/[&<>"]/g, (c) =>
+      ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+  }
+  function timeAgo(iso) {
+    const s = Math.max(0, (Date.now() - Date.parse(iso)) / 1000);
+    if (s < 60) return "just now";
+    if (s < 3600) return `${Math.round(s / 60)}m ago`;
+    if (s < 86400) return `${Math.round(s / 3600)}h ago`;
+    return `${Math.round(s / 86400)}d ago`;
+  }
+  function chip(status) {
+    return `<span class="chip ${esc(status)}">${esc(status)}</span>`;
+  }
+  function tally(results) {
+    const counts = {};
+    for (const r of results) counts[r.status] = (counts[r.status] || 0) + 1;
+    return [
+      counts.passed ? `${counts.passed}✓` : "",
+      counts.failed ? `${counts.failed}✗` : "",
+      counts.todo ? `${counts.todo} todo` : ""
+    ].filter(Boolean).join(" ");
+  }
+  function header(title, buttons) {
+    return `<div class="head"><h1>${title}</h1><span class="spacer"></span>${buttons}</div>`;
+  }
+  function rerunButtons() {
+    if (!context.dir) return "";
+    return `<button data-act="fast">Re-run fast</button>` +
+           `<button data-act="full">Full suite</button>`;
+  }
+  function render(sc) {
+    if (sc.runs && sc.project !== undefined) return renderList(sc);
+    if (sc.run) return renderDetail(sc);
+    if (sc.projects) return renderPicker(sc.projects);
+  }
+  // Nothing resolved server-side: offer the journaled projects as
+  // buttons instead of a dead end.
+  function renderPicker(projects) {
+    if (projects.length === 0) {
+      app.innerHTML = `<div class="empty">No runs journaled on this machine yet.</div>`;
+      return resize();
+    }
+    app.innerHTML =
+      header("Highball — pick a project", "") +
+      `<div class="empty" style="padding:10px 6px">` +
+      projects.map((slug) => `<button data-project="${esc(slug)}" style="margin:0 4px">${esc(slug)}</button>`).join("") +
+      `</div>`;
+    app.querySelectorAll("[data-project]").forEach((el) =>
+      el.addEventListener("click", () =>
+        callTool("list_runs", { project: el.dataset.project })));
+    resize();
+  }
+  function renderList(sc) {
+    context = { project: sc.project, dir: sc.dir ?? context.dir };
+    // Group header whenever the work (or session) changes between
+    // adjacent runs — the list is chronological, so contiguous runs with
+    // the same prompt are one stretch of work.
+    let lastGroup;
+    const rows = sc.runs.map((run) => {
+      const group = `${run.session ?? ""}·${run.work ?? ""}`;
+      const heading = group === lastGroup ? "" :
+        `<div class="group">${run.work ? "&ldquo;" + esc(run.work) + "&rdquo;" : "no session context"}</div>`;
+      lastGroup = group;
+      return heading + `
+      <div class="row" data-index="${run.index}">
+        <span class="chip ${esc(run.status)}">${run.status === "passed" ? "✓ passed" : "✗ failed"}</span>
+        <span class="when">${timeAgo(run.started_at)}</span>
+        <span class="meta">${run.trigger === "edit" ? "fast" : "full"}</span>
+        <span class="mono">${esc(run.branch || "-")}</span>
+        <span class="spacer"></span>
+        <span class="meta">${run.duration_ms != null ? (run.duration_ms / 1000).toFixed(1) + "s" : ""}</span>
+        <span class="meta">${esc(tally(run.results))}</span>
+      </div>`;
+    }).join("");
+    app.innerHTML =
+      header(`Highball · ${esc(sc.project)}`, rerunButtons()) +
+      (rows || `<div class="empty">No runs recorded yet.</div>`);
+    app.querySelectorAll(".row").forEach((el) =>
+      el.addEventListener("click", () =>
+        callTool("get_run", { project: context.project, index: Number(el.dataset.index) })));
+    wireRerun();
+    resize();
+  }
+  function renderDetail(sc) {
+    context = { project: sc.project ?? context.project, dir: sc.dir ?? context.dir };
+    const run = sc.run;
+    const rules = run.results.map((result) => {
+      const duration = result.duration_ms != null
+        ? `${(result.duration_ms / 1000).toFixed(1)}s` : "";
+      const row =
+        `<span class="glyph ${esc(result.status)}">${result.status === "passed" ? "✓" : result.status === "todo" ? "•" : "✗"}</span>` +
+        `<span>${esc(result.name)}</span>` +
+        `<span class="spacer"></span>` +
+        chip(result.status) +
+        `<span class="meta">${duration}</span>`;
+      // What the panel can actually show. Quiet rules (the AI judges print
+      // nothing when they pass) still have their command, so every rule that
+      // really ran stays worth opening.
+      const parts = [];
+      if (result.command) {
+        parts.push(`<div class="panel-label">Command</div><pre>$ ${esc(result.command)}</pre>`);
+      }
+      if (result.output_tail) {
+        parts.push(`<div class="panel-label">Output</div><pre>${esc(result.output_tail)}</pre>`);
+      }
+      // Journal records written before commands were recorded: keep real
+      // rules openable rather than silently turning them inert.
+      if (parts.length === 0 && result.status !== "todo") {
+        parts.push(`<div class="panel-note">No output captured for this rule.</div>`);
+      }
+      if (parts.length === 0) {
+        return `<div class="rule static"><div class="rowline">${row}</div></div>`;
+      }
+      return `<details class="rule"${result.status === "failed" ? " open" : ""}>` +
+        `<summary>${row}</summary><div class="panel">${parts.join("")}</div></details>`;
+    }).join("");
+    app.innerHTML =
+      header(
+        `Run #${run.index} · ${esc(context.project)} · ${run.trigger === "edit" ? "fast" : "full"} · ${esc(run.branch || "-")} <span class="meta">${timeAgo(run.started_at)}</span>`,
+        `<button data-act="back">← All runs</button>` + rerunButtons()
+      ) + rules;
+    app.querySelector('[data-act="back"]').addEventListener("click", () =>
+      callTool("list_runs", { project: context.project }));
+    wireRerun();
+    resize();
+  }
+  function wireRerun() {
+    app.querySelectorAll("[data-act=fast],[data-act=full]").forEach((el) =>
+      el.addEventListener("click", async () => {
+        el.disabled = true;
+        el.textContent = "Running…";
+        try {
+          await callTool("run_checks", { dir: context.dir, fast: el.dataset.act === "fast" });
+        } finally {
+          callTool("list_runs", { project: context.project });
+        }
+      }));
+  }
+  function resize() {
+    notify("ui/notifications/size-changed", {
+      height: Math.min(600, document.documentElement.scrollHeight + 8)
+    });
+  }
+  // --- boot --------------------------------------------------------------
+  (async () => {
+    try {
+      await request("ui/initialize", {
+        protocolVersion: "2026-01-26",
+        appInfo: { name: "highball-dashboard", version: "0.3.0" },
+        appCapabilities: {}
+      });
+      notify("ui/notifications/initialized");
+    } catch {
+      // Host may predate the handshake shape; the fallback fetch below
+      // still gives us data if tools/call works.
+    }
+    // If the host doesn't push the originating tool result promptly,
+    // fetch the list ourselves — makes the widget self-sufficient. But
+    // never while a tool is executing (tool-input arrived): the widget
+    // may be preloaded seconds before a slow run_checks resolves.
+    const selfFetch = (attempt) => {
+      if (!app.querySelector(".empty") || attempt > 20) return;
+      if (toolInFlight) return setTimeout(() => selfFetch(attempt + 1), 900);
+      callTool("list_runs", {}).catch(() => {});
+    };
+    setTimeout(() => selfFetch(0), 900);
+  })();
+})();
+</script>
+</body>
+</html>

package/bin/highball.js CHANGED Viewed

@@ -7,6 +7,8 @@ import { run } from "../lib/run.js";
 import { init } from "../lib/init.js";
 import { login } from "../lib/login.js";
 import { onboard } from "../lib/onboard.js";
+import { runs } from "../lib/runs.js";
+import { mcp } from "../lib/mcp.js";
 const [command, ...args] = process.argv.slice(2);
@@ -24,6 +26,13 @@ Usage:
   highball onboard          Print the setup guide written for this repo's
                             AI agent — tell your agent to run this and
                             follow it.
+  highball runs [n]         Local run history (newest first) from
+                            ~/.highball/runs — no dashboard needed.
+                            With a number, that run's detail; add
+                            --logs for every rule's captured output.
+  highball mcp              Serve run history over MCP (stdio), with an
+                            MCP Apps dashboard widget for hosts that
+                            render them (e.g. Claude Desktop).
 `;
 switch (command) {
@@ -39,6 +48,12 @@ switch (command) {
   case "onboard":
     process.exit(await onboard(args));
     break;
+  case "runs":
+    process.exit(await runs(args));
+    break;
+  case "mcp":
+    await mcp();
+    break;
   default:
     console.log(USAGE);
     process.exit(command === undefined || command === "--help" ? 0 : 1);

package/lib/journal.js ADDED Viewed

@@ -0,0 +1,58 @@
+// The local run journal: every run appends one JSONL line to
+// ~/.highball/runs/<project>.jsonl, whether or not remote reporting is
+// configured. This is what makes the runner useful with no dashboard at
+// all — `highball runs` reads it — and it lives outside the repo tree
+// (like credentials) so there's no gitignore to manage and no state to
+// leak into commits.
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+// Per-project cap. At ~1-2KB a line this bounds each file around a
+// couple hundred KB — enough history to be useful, never enough to care
+// about.
+const MAX_RUNS = 200;
+export function journalDir() {
+  return join(homedir(), ".highball", "runs");
+}
+export function journalPath(project, dir = journalDir()) {
+  return join(dir, `${project}.jsonl`);
+}
+export function appendRun(project, record, dir = journalDir()) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const path = journalPath(project, dir);
+  const lines = existsSync(path)
+    ? readFileSync(path, "utf8").split("\n").filter(Boolean)
+    : [];
+  lines.push(JSON.stringify(record));
+  writeFileSync(path, lines.slice(-MAX_RUNS).join("\n") + "\n");
+}
+// Newest first — the order every "recent runs" view wants.
+export function readRuns(project, dir = journalDir()) {
+  const path = journalPath(project, dir);
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .reverse();
+}
+export function journaledProjects(dir = journalDir()) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith(".jsonl"))
+    .map((name) => name.slice(0, -".jsonl".length))
+    .sort();
+}

package/lib/mcp.js ADDED Viewed

@@ -0,0 +1,245 @@
+// `highball mcp` — a stdio MCP server over the local run journal, with
+// an MCP Apps dashboard widget. This is the no-install view layer: hosts
+// that support MCP Apps (Claude Desktop et al.) render the widget inline;
+// every tool also returns meaningful text, per the extension's graceful-
+// degradation rule, so plain MCP hosts lose nothing but the pixels.
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  getUiCapability, registerAppResource, registerAppTool, RESOURCE_MIME_TYPE
+} from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+import { loadConfig } from "./config.js";
+import { journaledProjects, readRuns } from "./journal.js";
+const DASHBOARD_URI = "ui://highball/dashboard.html";
+const BIN_PATH = fileURLToPath(new URL("../bin/highball.js", import.meta.url));
+const VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8")
+).version;
+// The server may be launched from a repo (project inferable) or from a
+// host like Claude Desktop whose cwd is nowhere useful. Resolution order:
+// explicit argument, the cwd's checks.yml, then the journal with the
+// newest run — the repo being actively worked in IS the current project.
+// Journal records carry the repo dir (since runs record process.cwd()),
+// so every path out of here can ground the widget's re-run buttons.
+function resolveProject(explicit) {
+  if (explicit) return { project: explicit, dir: latestDirFor(explicit) };
+  try {
+    return { project: loadConfig().project, dir: process.cwd() };
+  } catch {
+    let current = null;
+    for (const project of journaledProjects()) {
+      const newest = readRuns(project)[0];
+      if (!newest) continue;
+      if (!current || newest.started_at > current.started_at) {
+        current = { project, started_at: newest.started_at };
+      }
+    }
+    if (!current) return { project: null, dir: null };
+    return { project: current.project, dir: latestDirFor(current.project) };
+  }
+}
+// Newest journal record that knows its repo dir (older records predate
+// the field).
+function latestDirFor(project) {
+  return readRuns(project).find((run) => run.dir)?.dir ?? null;
+}
+// List payloads stay lean — output tails ride only on get_run.
+function summarize(run, i) {
+  return {
+    index: i + 1,
+    started_at: run.started_at,
+    duration_ms: run.duration_ms,
+    trigger: run.trigger,
+    branch: run.branch,
+    commit: run.commit,
+    status: run.status,
+    session: run.session ?? null,
+    work: run.work ?? null,
+    reported_run_id: run.reported_run_id,
+    results: (run.results || []).map(({ id, name, status, duration_ms }) =>
+      ({ id, name, status, duration_ms }))
+  };
+}
+function reply(text, structuredContent) {
+  return { content: [ { type: "text", text } ], structuredContent };
+}
+// --- text rendering ------------------------------------------------------
+// Two audiences: hosts that advertised the MCP Apps UI capability get a
+// short summary (the widget carries the detail), everyone else gets the
+// full picture as aligned plain text — the extension's graceful-
+// degradation rule made concrete. Exported for tests.
+const glyphFor = (status) =>
+  status === "passed" ? "✓" : status === "todo" ? "•" : "✗";
+export function listText(project, runs) {
+  if (runs.length === 0) return `No runs recorded for ${project} yet.`;
+  const rows = runs.map((run) => [
+    `#${run.index}`,
+    run.status === "passed" ? "✓ passed" : "✗ FAILED",
+    run.trigger === "edit" ? "fast" : "full",
+    run.branch || "-",
+    run.duration_ms != null ? `${(run.duration_ms / 1000).toFixed(1)}s` : "-",
+    run.started_at,
+    run.results.map((result) => glyphFor(result.status)).join("")
+  ]);
+  const widths = rows[0].map((_, col) =>
+    Math.max(...rows.map((row) => row[col].length)));
+  const lines = [ `Runs for ${project} (newest first):` ];
+  let lastGroup;
+  runs.forEach((run, i) => {
+    // Group header whenever the work (or its session) changes between
+    // adjacent runs — the journal is chronological, so contiguous runs
+    // with the same prompt are one stretch of work.
+    const group = `${run.session ?? ""}·${run.work ?? ""}`;
+    if (group !== lastGroup) {
+      lastGroup = group;
+      lines.push(run.work ? `» ${run.work}` : "» (no session context)");
+    }
+    lines.push("  " + rows[i].map((cell, col) => cell.padEnd(widths[col])).join("  "));
+  });
+  return lines.join("\n");
+}
+export function detailText(project, index, run) {
+  const took = run.duration_ms != null
+    ? ` · took ${(run.duration_ms / 1000).toFixed(1)}s` : "";
+  const rules = run.results.map((result) => {
+    const duration = result.duration_ms != null
+      ? ` (${(result.duration_ms / 1000).toFixed(1)}s)` : "";
+    let line = `  ${glyphFor(result.status)} ${result.name} — ${result.status}${duration}`;
+    if (result.status === "failed" && result.output_tail) {
+      line += "\n" + result.output_tail.split("\n").map((l) => `      ${l}`).join("\n");
+    }
+    return line;
+  }).join("\n");
+  return `Run #${index} — ${project} · ${run.trigger === "edit" ? "fast checks" : "full suite"}` +
+    ` · ${run.branch || "-"} · ${(run.commit || "").slice(0, 7)} · ${run.status}${took}\n${rules}`;
+}
+export async function mcp() {
+  const server = new McpServer({ name: "highball", version: VERSION });
+  // Did this client advertise MCP Apps support in its initialize
+  // capabilities (io.modelcontextprotocol/ui)? Checked at call time —
+  // capabilities aren't known yet when tools are registered.
+  const uiHost = () => {
+    const capability = getUiCapability(server.server.getClientCapabilities());
+    return !!capability &&
+      (!capability.mimeTypes || capability.mimeTypes.includes(RESOURCE_MIME_TYPE));
+  };
+  registerAppTool(server, "list_runs", {
+    title: "Highball runs",
+    description:
+      "Recent Highball check runs for a project, from the machine-local " +
+      "journal (~/.highball/runs). Renders the runs dashboard widget.",
+    inputSchema: {
+      project: z.string().optional()
+        .describe("Project slug; defaults to the current repo's project")
+    },
+    _meta: { ui: { resourceUri: DASHBOARD_URI } }
+  }, async ({ project: explicit }) => {
+    const { project, dir } = resolveProject(explicit);
+    if (!project) {
+      const known = journaledProjects();
+      return reply(
+        `No project resolved. Journaled projects: ${known.join(", ") || "(none)"}`,
+        { projects: known }
+      );
+    }
+    const runs = readRuns(project).map(summarize);
+    return reply(
+      uiHost()
+        ? `${runs.length} runs for ${project} — rendered in the dashboard widget.`
+        : listText(project, runs.slice(0, 20)),
+      { project, dir, runs }
+    );
+  });
+  registerAppTool(server, "get_run", {
+    title: "Highball run detail",
+    description:
+      "One Highball run's full detail — per-rule statuses, durations, and " +
+      "captured command output. index counts from 1, newest first.",
+    inputSchema: {
+      index: z.number().int().min(1).describe("1-based index, newest first"),
+      project: z.string().optional()
+        .describe("Project slug; defaults to the current repo's project")
+    },
+    _meta: { ui: { resourceUri: DASHBOARD_URI } }
+  }, async ({ index, project: explicit }) => {
+    const { project, dir } = resolveProject(explicit);
+    if (!project) return reply("No project resolved.", {});
+    const history = readRuns(project);
+    const run = history[index - 1];
+    if (!run) return reply(`No run #${index} (${history.length} recorded).`, {});
+    return reply(
+      uiHost()
+        ? `Run #${index} for ${project}: ${run.status} — rendered in the dashboard widget.`
+        : detailText(project, index, run),
+      { project, dir, run: { ...summarize(run, index - 1), results: run.results } }
+    );
+  });
+  registerAppTool(server, "run_checks", {
+    title: "Run Highball checks",
+    description:
+      "Execute a repo's Highball checks (fast rules or the full suite). " +
+      "Blocks until done; the run lands in the journal and, when reporting " +
+      "is configured, on the dashboard.",
+    inputSchema: {
+      dir: z.string().optional()
+        .describe("Repo root containing .highball/checks.yml; defaults to cwd"),
+      fast: z.boolean().optional().describe("Only rules marked fast: true")
+    },
+    _meta: { ui: { resourceUri: DASHBOARD_URI } }
+  }, async ({ dir, fast }) => {
+    // No dir given → the current project's repo (from its journal), so
+    // widget-initiated re-runs work from hosts with no useful cwd.
+    const cwd = dir || resolveProject(null).dir || process.cwd();
+    const child = spawnSync(
+      process.execPath,
+      [ BIN_PATH, "run", ...(fast ? [ "--fast" ] : []) ],
+      { cwd, encoding: "utf8", timeout: 900_000, env: { ...process.env, NO_COLOR: "1" } }
+    );
+    const output = `${child.stdout || ""}${child.stderr || ""}`.slice(-4000);
+    let project = null;
+    let latest = null;
+    try {
+      project = loadConfig(cwd).project;
+      latest = readRuns(project)[0] || null;
+    } catch {
+      // No checks.yml at cwd — the child's own error output says so.
+    }
+    return reply(
+      `exit ${child.status}\n${output}`,
+      {
+        project,
+        dir: cwd,
+        exitCode: child.status,
+        run: latest ? { ...summarize(latest, 0), results: latest.results } : null
+      }
+    );
+  });
+  registerAppResource(server, "Highball Dashboard", DASHBOARD_URI, {}, async () => ({
+    contents: [ {
+      uri: DASHBOARD_URI,
+      mimeType: RESOURCE_MIME_TYPE,
+      text: readFileSync(new URL("../assets/dashboard.html", import.meta.url), "utf8")
+    } ]
+  }));
+  await server.connect(new StdioServerTransport());
+}

package/lib/report.js CHANGED Viewed

@@ -5,7 +5,9 @@
 import { execSync } from "node:child_process";
 import { hostname } from "node:os";
-export async function report({ url, token, rules, results, hook, fastOnly, startedAt }) {
+// Returns the server's run id on success, null when reporting was
+// skipped or failed — the caller journals it either way.
+export async function report({ url, token, rules, results, hook, fastOnly, startedAt, branch, commitSha }) {
   try {
     const base = new URL(url);
     const request = async (method, path, body) => {
@@ -29,8 +31,8 @@ export async function report({ url, token, rules, results, hook, fastOnly, start
       session_key:
         hook.session_id || process.env.HIGHBALL_SESSION_KEY || `manual-${hostname()}`,
       trigger: fastOnly ? "edit" : "stop",
-      branch: git("git branch --show-current"),
-      commit_sha: git("git rev-parse HEAD"),
+      branch,
+      commit_sha: commitSha,
       rules_snapshot: rules,
       started_at: startedAt.toISOString()
     });
@@ -57,12 +59,14 @@ export async function report({ url, token, rules, results, hook, fastOnly, start
       status: results.every((result) => result.passed) ? "passed" : "failed"
     });
     console.log(`reported to ${base.host} (run ${runId})`);
+    return runId;
   } catch (error) {
     console.error(`highball reporting skipped: ${error.message}`);
+    return null;
   }
 }
-function git(command) {
+export function git(command) {
   try {
     return execSync(`${command} 2>/dev/null`, { encoding: "utf8" }).trim();
   } catch {

package/lib/run.js CHANGED Viewed

@@ -5,7 +5,9 @@
 // dashboard must never block the agent.
 import { execSync, spawnSync } from "node:child_process";
 import { loadConfig, resolveReporting, commandFor } from "./config.js";
-import { report } from "./report.js";
+import { appendRun } from "./journal.js";
+import { git, report } from "./report.js";
+import { latestUserPrompt } from "./transcript.js";
 export async function run(args) {
   // When an AI-judged rule spawns a judge session inside this repo, the
@@ -66,10 +68,58 @@ export async function run(args) {
   }
   const failures = results.filter((result) => !result.passed);
+  const durationMs = Date.now() - startedAt.getTime();
+  const branch = git("git branch --show-current");
+  const commitSha = git("git rev-parse HEAD");
   const { url, token } = resolveReporting(config);
+  let reportedRunId = null;
   if (url && token) {
-    await report({ url, token, project: config.project, rules, results, hook, fastOnly, startedAt });
+    reportedRunId = await report({
+      url, token, rules, results, hook, fastOnly, startedAt, branch, commitSha
+    });
+  }
+  // The local journal is unconditional — `highball runs` works with no
+  // dashboard configured at all. Journal failures never fail the checks,
+  // same policy as reporting.
+  try {
+    appendRun(config.project, {
+      started_at: startedAt.toISOString(),
+      // The repo this run happened in — how the MCP server later resolves
+      // "the current project" and grounds the widget's re-run buttons.
+      dir: process.cwd(),
+      // Which agent session, and what it was working on — the grouping
+      // key and label for run history views. The hook payload points at
+      // the session transcript; its last real user prompt is the work.
+      session: hook.session_id || null,
+      work: latestUserPrompt(hook.transcript_path),
+      duration_ms: durationMs,
+      trigger: fastOnly ? "edit" : "stop",
+      branch,
+      commit: commitSha,
+      status: failures.length === 0 ? "passed" : "failed",
+      reported_run_id: reportedRunId,
+      results: results.map((result) => ({
+        id: result.rule.id,
+        name: result.rule.name,
+        status: result.todo ? "todo" : result.passed ? "passed" : "failed",
+        duration_ms: result.durationMs,
+        // The command that produced this result. Quiet rules journal no
+        // output at all (the AI judges print nothing when they pass), which
+        // left viewers with an expandable row wrapping an empty panel; the
+        // command is the one detail every real rule can always show. todo
+        // rules have no command — nothing ran — which is exactly what makes
+        // them inert rather than falsely clickable.
+        command: result.rule.run ?? null,
+        // Unlike the dashboard (failure tails only), the journal keeps
+        // every rule's output GitHub-Actions-style — it's the user's own
+        // disk, and `highball runs <n> --logs` is the payoff.
+        output_tail: result.output ? result.output.slice(-10_000) : null
+      }))
+    });
+  } catch (error) {
+    console.error(`highball journal skipped: ${error.message}`);
   }
   if (failures.length === 0) return 0;
@@ -105,8 +155,10 @@ async function readHookPayload() {
 // every rule invocation fail; scripts fall back to their own git.
 function changedFiles() {
   try {
-    const tracked = execSync("git diff --name-only HEAD", { encoding: "utf8" });
-    const untracked = execSync("git ls-files --others --exclude-standard", {
+    const tracked = execSync("git diff --name-only HEAD 2>/dev/null", {
+      encoding: "utf8"
+    });
+    const untracked = execSync("git ls-files --others --exclude-standard 2>/dev/null", {
       encoding: "utf8"
     });
     const list = `${tracked}\n${untracked}`

package/lib/runs.js ADDED Viewed

@@ -0,0 +1,156 @@
+// `highball runs [n] [--logs]` — the no-dashboard view of run history,
+// read from the local journal. Bare: a table of recent runs, newest
+// first. With a number: that run's detail — failure output by default,
+// every rule's captured output with --logs.
+import { loadConfig } from "./config.js";
+import { readRuns, journaledProjects } from "./journal.js";
+// TTY-gated ANSI (NO_COLOR respected, FORCE_COLOR overrides) — hook
+// shells and pipes get plain text.
+const COLORS_ON = process.env.FORCE_COLOR
+  ? true
+  : Boolean(process.stdout.isTTY && !process.env.NO_COLOR);
+const paint = (code, text) => (COLORS_ON ? `\x1b[${code}m${text}\x1b[0m` : text);
+const green = (text) => paint("32", text);
+const red = (text) => paint("31;1", text);
+const dim = (text) => paint("2", text);
+// Column math must use what the eye sees, not what the terminal parses.
+const visible = (text) => text.replace(/\x1b\[[0-9;]*m/g, "");
+const padEnd = (text, width) => text + " ".repeat(Math.max(0, width - visible(text).length));
+const padStart = (text, width) => " ".repeat(Math.max(0, width - visible(text).length)) + text;
+export async function runs(args) {
+  let project;
+  try {
+    project = loadConfig().project;
+  } catch {
+    const known = journaledProjects();
+    console.error(
+      "highball: not inside a configured repo (no .highball/checks.yml)."
+    );
+    if (known.length > 0) {
+      console.error(`Projects with local history: ${known.join(", ")}`);
+    }
+    return 1;
+  }
+  const history = readRuns(project);
+  if (history.length === 0) {
+    console.log(`No local runs recorded for ${project} yet — run \`highball run\`.`);
+    return 0;
+  }
+  const index = args.find((arg) => /^\d+$/.test(arg));
+  return index
+    ? detail(project, history, Number(index), args.includes("--logs"))
+    : list(project, history);
+}
+// Shared column formatter: widths from visible lengths, chosen columns
+// right-aligned so numbers and ✓/✗ line up whatever the text does.
+function formatRows(rows, rightAligned) {
+  const widths = rows[0].map((_, col) =>
+    Math.max(...rows.map((row) => visible(row[col]).length))
+  );
+  return rows.map((row) =>
+    "  " + row
+      .map((cell, col) =>
+        rightAligned.has(col) ? padStart(cell, widths[col]) : padEnd(cell, widths[col])
+      )
+      .join("  ")
+  );
+}
+function list(project, history) {
+  console.log(`Recent runs for ${project} (newest first):\n`);
+  const rows = history.map((run, i) => [
+    dim(`#${i + 1}`),
+    timeAgo(run.started_at),
+    run.trigger === "edit" ? "fast" : "full",
+    run.branch || "-",
+    dim(run.duration_ms != null ? `${(run.duration_ms / 1000).toFixed(1)}s` : "-"),
+    run.status === "passed" ? green("✓ passed") : red("✗ FAILED"),
+    tally(run.results)
+  ]);
+  const lines = formatRows(rows, new Set([ 4, 5, 6 ]));
+  // Group header whenever the work (or session) changes between adjacent
+  // runs — contiguous runs with the same prompt are one stretch of work.
+  let lastGroup;
+  history.forEach((run, i) => {
+    const group = `${run.session ?? ""}·${run.work ?? ""}`;
+    if (group !== lastGroup) {
+      lastGroup = group;
+      if (i > 0) console.log("");
+      console.log(dim(run.work ? `» ${run.work}` : "» (no session context)"));
+    }
+    console.log(lines[i]);
+  });
+  console.log(`\nDetail: highball runs <number> [--logs]`);
+  return 0;
+}
+function detail(project, history, number, showLogs) {
+  const run = history[number - 1];
+  if (!run) {
+    console.error(`highball: no run #${number} (${history.length} recorded).`);
+    return 1;
+  }
+  const took = run.duration_ms != null ? ` · took ${(run.duration_ms / 1000).toFixed(1)}s` : "";
+  const status = run.status === "passed" ? green("passed") : red("FAILED");
+  console.log(
+    `Run #${number} — ${project} · ${run.trigger === "edit" ? "fast checks" : "full suite"}` +
+      ` · ${run.branch || "-"} · ${(run.commit || "").slice(0, 7)}` +
+      ` · ${timeAgo(run.started_at)} · ${status}${dim(took)}`
+  );
+  if (run.reported_run_id) console.log(dim(`reported as run ${run.reported_run_id}`));
+  console.log("");
+  // Same table treatment as the list view: rule rows aligned in
+  // columns, output blocks interleaved beneath their rule's row.
+  const rows = run.results.map((result) => [
+    result.status === "passed" ? green("✓") : result.status === "todo" ? dim("•") : red("✗"),
+    result.status === "failed" ? red(result.name) : result.name,
+    result.status === "passed" ? green(result.status) : result.status === "todo" ? dim(result.status) : red(result.status.toUpperCase()),
+    result.duration_ms != null ? dim(`${(result.duration_ms / 1000).toFixed(1)}s`) : ""
+  ]);
+  const lines = formatRows(rows, new Set([ 2, 3 ]));
+  run.results.forEach((result, i) => {
+    console.log(lines[i]);
+    const wantOutput = result.status === "failed" || showLogs;
+    if (wantOutput && result.output_tail) {
+      console.log(indent(result.output_tail));
+    } else if (showLogs && !result.output_tail) {
+      console.log(indent(dim("(no output captured)")));
+    }
+  });
+  if (!showLogs) console.log(dim(`\nAll captured output: highball runs ${number} --logs`));
+  return 0;
+}
+function indent(text) {
+  return text
+    .replace(/\n$/, "")
+    .split("\n")
+    .map((line) => `      ${line}`)
+    .join("\n");
+}
+function tally(results) {
+  const counts = { passed: 0, failed: 0, todo: 0 };
+  for (const result of results) counts[result.status] = (counts[result.status] || 0) + 1;
+  return [
+    counts.passed ? green(`${counts.passed}✓`) : null,
+    counts.failed ? red(`${counts.failed}✗`) : null,
+    counts.todo ? dim(`${counts.todo} todo`) : null
+  ].filter(Boolean).join(" ");
+}
+function timeAgo(iso) {
+  const seconds = Math.max(0, (Date.now() - Date.parse(iso)) / 1000);
+  if (seconds < 60) return "just now";
+  if (seconds < 3600) return `${Math.round(seconds / 60)}m ago`;
+  if (seconds < 86_400) return `${Math.round(seconds / 3600)}h ago`;
+  return `${Math.round(seconds / 86_400)}d ago`;
+}

package/lib/transcript.js ADDED Viewed

@@ -0,0 +1,60 @@
+// Extracts "the work being done" from a Claude Code session transcript:
+// the last real user prompt. Hooks hand the runner transcript_path on
+// stdin, and the message that started the current turn is the best
+// zero-cost description of why these checks are running — no AI
+// summarization, no config, just the tail of a JSONL file.
+import { existsSync, readFileSync } from "node:fs";
+const MAX_LENGTH = 120;
+export function latestUserPrompt(transcriptPath) {
+  if (!transcriptPath || !existsSync(transcriptPath)) return null;
+  let lines;
+  try {
+    lines = readFileSync(transcriptPath, "utf8").split("\n");
+  } catch {
+    return null;
+  }
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!lines[i].trim()) continue;
+    let entry;
+    try {
+      entry = JSON.parse(lines[i]);
+    } catch {
+      continue;
+    }
+    if (entry.type !== "user" || entry.isMeta) continue;
+    const text = messageText(entry.message);
+    if (text) return truncate(text);
+  }
+  return null;
+}
+// A "user" line is only a prompt when it carries actual text — tool
+// results and command wrappers ride the user role too and must not
+// become work descriptions.
+function messageText(message) {
+  if (!message) return null;
+  const { content } = message;
+  let text = null;
+  if (typeof content === "string") text = content;
+  else if (Array.isArray(content)) {
+    text = content
+      .filter((item) => item.type === "text" && typeof item.text === "string")
+      .map((item) => item.text)
+      .join(" ");
+  }
+  if (!text) return null;
+  text = text.trim();
+  if (!text || text.startsWith("<")) return null;
+  if (text.startsWith("[Request interrupted")) return null;
+  return text;
+}
+function truncate(text) {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  return collapsed.length > MAX_LENGTH
+    ? collapsed.slice(0, MAX_LENGTH - 1) + "…"
+    : collapsed;
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@profoundry-us/highball",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Highball runner — local CI for AI coding agents: runs a repo's .highball/checks.yml rules, blocks the agent on failure, and reports runs to a Highball dashboard.",
   "keywords": [
     "ai",
@@ -25,6 +25,7 @@
   "files": [
     "bin",
     "lib",
+    "assets",
     "README.md",
     "ONBOARDING.md"
   ],
@@ -32,9 +33,12 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "harness": "node dev/harness/serve.js"
   },
   "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.5",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "yaml": "^2.5.0"
   },
   "license": "MIT"