npm - portable-agent-layer - Versions diffs - 0.69.0 → 0.70.0 - Mend

portable-agent-layer 0.69.0 → 0.70.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 (10) hide show

package/README.md +1 -0
package/assets/templates/ledger-page.html +213 -0
package/package.json +1 -1
package/src/cli/index.ts +8 -0
package/src/cli/ledger.ts +1 -17
package/src/cli/server.ts +195 -0
package/src/hooks/lib/paths.ts +2 -0
package/src/tools/ledger/query.ts +18 -0
package/src/tools/ledger/server.ts +111 -0
package/src/tools/ledger/view.ts +130 -0

package/README.md CHANGED Viewed

@@ -89,6 +89,7 @@ pal cli status        # check your setup
 | `pal cli machine [label <name>]` | Show or rename this install — where a record was written. Never leaves the machine |
 | `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
 | `pal cli ledger` | Query the action ledger — `log`, `show <id>`, `stats`, filtered by `--project`, `--since`, `--actor`, `--machine`, `--runtime`, `--outcome`, `--tool`, `--target` |
+| `pal cli server` | Local page over the action ledger for showing the log to a person — `start [--port <n>]`, `stop`, `status`. Loopback only, default port 7250; project and date window are chosen on the page |
 | `pal cli skill link <name>` | Link a personal `~/.pal/skills/<name>/` into every installed agent so it is discoverable |
 | `pal cli skill doctor <name>` | Evaluate a skill against the authoring best practices (folder/file-name match, name, description, body length, point-of-view, reference depth) |
 | `pal cli subagent link <name>` | Install a personal `~/.pal/agents/<name>.md` (merged multi-platform definition) into every installed agent, split per platform |

package/assets/templates/ledger-page.html ADDED Viewed

@@ -0,0 +1,213 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Action Ledger</title>
+<style>
+  :root {
+    --bg: #eef0f2;
+    --panel: #ffffff;
+    --ink: #1b2026;
+    --muted: #6b7480;
+    --line: #d5dae0;
+    --accent: #0f6e6e;
+    --accent-ink: #ffffff;
+    --block: #b4471c;
+    --block-bg: #fbf0ea;
+    --ok: #2f7a3e;
+    --ok-bg: #edf6ee;
+    --pending: #8a6d00;
+    --pending-bg: #fbf5df;
+    --agent: #4a3fa3;
+    --agent-bg: #efedf9;
+    --mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+    --sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; }
+  body { margin: 0; background: var(--bg); color: var(--ink); font: 13px/1.45 var(--sans); }
+  header {
+    display: flex; align-items: center; justify-content: space-between;
+    padding: 10px 16px; background: var(--panel); border-bottom: 1px solid var(--line);
+  }
+  header h1 { font-size: 14px; margin: 0; font-weight: 600; letter-spacing: .01em; }
+  header .model { font-family: var(--mono); font-size: 11px; color: var(--muted); }
+  header .who { font-size: 12px; color: var(--muted); }
+  header .who b { color: var(--ink); font-weight: 600; }
+  main { background: var(--panel); min-height: calc(100% - 45px); }
+  h2 {
+    font-size: 11px; text-transform: uppercase; letter-spacing: .06em; color: var(--muted);
+    margin: 0; padding: 12px 14px 8px; font-weight: 600;
+  }
+  .filters { display: flex; gap: 10px; padding: 0 14px 12px; flex-wrap: wrap; align-items: end; }
+  .filters label { display: block; font-size: 10px; text-transform: uppercase; letter-spacing: .05em; color: var(--muted); }
+  select, input { font: inherit; padding: 4px 6px; border: 1px solid var(--line); border-radius: 3px; }
+  .stats { display: grid; grid-template-columns: 1.4fr repeat(4, 1fr); gap: 1px; background: var(--line); border-top: 1px solid var(--line); border-bottom: 1px solid var(--line); }
+  .stat { background: var(--panel); padding: 12px 14px; }
+  .stat label { display: block; font-size: 10px; text-transform: uppercase; letter-spacing: .05em; color: var(--muted); }
+  .stat .n { font-size: 26px; font-weight: 600; font-variant-numeric: tabular-nums; line-height: 1.2; }
+  .stat.headline { background: var(--block-bg); }
+  .stat.headline .n { font-size: 40px; color: var(--block); }
+  .stat.applied .n { color: var(--ok); }
+  .stat.failed .n { color: var(--pending); }
+  .stat.denied .n, .stat.blocked .n { color: var(--block); }
+  .st { font-size: 11px; color: var(--muted); }
+  table { width: 100%; border-collapse: collapse; }
+  td, th { text-align: left; padding: 7px 14px; border-top: 1px solid var(--line); vertical-align: top; font-variant-numeric: tabular-nums; }
+  th { font-size: 10px; text-transform: uppercase; letter-spacing: .05em; color: var(--muted); border-top: 0; font-weight: 600; }
+  td.ts { font-family: var(--mono); font-size: 11px; color: var(--muted); white-space: nowrap; }
+  td.target { font-family: var(--mono); font-size: 11px; word-break: break-all; }
+  td.diff { font-family: var(--mono); font-size: 11px; }
+  .actor { display: inline-block; padding: 1px 6px; border-radius: 3px; font-size: 11px; }
+  .actor.human { background: #eef0f2; }
+  .actor.agent { background: var(--agent-bg); color: var(--agent); }
+  .out { display: inline-block; padding: 1px 6px; border-radius: 3px; font-size: 11px; font-weight: 600; }
+  .out.applied { background: var(--ok-bg); color: var(--ok); }
+  .out.failed { background: var(--pending-bg); color: var(--pending); }
+  .out.denied { background: var(--block-bg); color: var(--block); }
+  .out.blocked { background: var(--block-bg); color: var(--block); }
+  footer { font-family: var(--mono); font-size: 10.5px; color: var(--muted); padding: 10px 14px; border-top: 1px solid var(--line); }
+</style>
+</head>
+<body>
+<header>
+  <h1>Action Ledger</h1>
+  <span class="model" id="modelLine"></span>
+  <span class="who" id="who"></span>
+</header>
+<main>
+  <h2>Window</h2>
+  <div class="filters">
+    <div><label for="project">Project</label><select id="project"><option value="">all projects</option></select></div>
+    <div><label for="since">From</label><input type="date" id="since"></div>
+    <div><label for="until">To</label><input type="date" id="until"></div>
+  </div>
+  <div class="stats" id="stats"></div>
+  <h2>Action log</h2>
+  <table>
+    <thead><tr><th>When</th><th>Actor</th><th>Action</th><th>Target</th><th>Change</th><th>Outcome</th></tr></thead>
+    <tbody id="log"></tbody>
+  </table>
+  <footer id="footer">Every row is one action an agent tried to make. The ledger saw each from both sides, before and after. Nothing here was written by hand.</footer>
+</main>
+<script>
+const $ = id => document.getElementById(id);
+const OUTCOMES = ['applied', 'failed', 'denied', 'blocked'];
+let ledgerFiles = 0;
+function el(tag, cls, text) {
+  const node = document.createElement(tag);
+  if (cls) node.className = cls;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+const pad = n => String(n).padStart(2, '0');
+function when(ts) {
+  const d = new Date(ts);
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+const authorityWord = key => key === 'user' ? 'human' : key;
+function tally(counts, word = k => k) {
+  const parts = Object.entries(counts).sort((a, b) => b[1] - a[1]).map(([k, v]) => `${word(k)} ${v}`);
+  return parts.length ? parts.join(' · ') : '—';
+}
+function query() {
+  const p = new URLSearchParams();
+  if ($('project').value) p.set('project', $('project').value);
+  if ($('since').value) p.set('since', $('since').value);
+  if ($('until').value) p.set('until', `${$('until').value}T23:59:59.999Z`);
+  return p.toString();
+}
+function windowText() {
+  const from = $('since').value, to = $('until').value;
+  if (!from && !to) return 'all time';
+  return `${from || 'start'} → ${to || 'now'}`;
+}
+function renderStats(s) {
+  const strip = $('stats');
+  strip.replaceChildren();
+  const headline = el('div', 'stat headline');
+  headline.append(el('label', '', 'Refusals'), el('div', 'n', String(s.refusals)),
+    el('div', 'st', `denied ${s.outcomes.denied.total} · blocked ${s.outcomes.blocked.total}`));
+  strip.append(headline);
+  for (const key of OUTCOMES) {
+    const o = s.outcomes[key];
+    const card = el('div', `stat ${key}`);
+    card.append(el('label', '', key), el('div', 'n', String(o.total)),
+      el('div', 'st', tally(o.byAuthority, authorityWord)), el('div', 'st', tally(o.byRuntime)));
+    strip.append(card);
+  }
+}
+function actorCell(r) {
+  const td = el('td');
+  const agent = r.authority === 'agent';
+  td.append(el('span', `actor ${agent ? 'agent' : 'human'}`, agent ? `agent · ${r.runtime}` : r.actor));
+  td.append(el('div', 'st', agent ? `on behalf of ${r.actor}` : `via ${r.runtime}`));
+  return td;
+}
+function changeCell(r) {
+  const td = el('td', 'diff');
+  td.append(r.reason ? el('span', 'st', r.reason) : document.createTextNode(r.change));
+  return td;
+}
+function renderRows(rows) {
+  const body = $('log');
+  body.replaceChildren();
+  if (!rows.length) {
+    const td = el('td', 'st', 'No actions in this window.');
+    td.colSpan = 6;
+    const tr = el('tr'); tr.append(td); body.append(tr);
+    return;
+  }
+  for (const r of rows) {
+    const tr = el('tr');
+    const outcome = el('td'); outcome.append(el('span', `out ${r.outcome}`, r.outcome));
+    tr.append(el('td', 'ts', when(r.ts)), actorCell(r), el('td', '', r.tool), el('td', 'target', r.target), changeCell(r), outcome);
+    body.append(tr);
+  }
+}
+async function load() {
+  const res = await fetch(`/api/ledger?${query()}`);
+  const body = await res.json();
+  if (!res.ok) { $('modelLine').textContent = body.error; return; }
+  renderStats(body.stats);
+  renderRows(body.rows);
+  $('modelLine').textContent = `${body.stats.total} actions · ${windowText()} · ${ledgerFiles} ledger file(s)`;
+}
+async function loadProjects() {
+  const list = await (await fetch('/api/projects')).json();
+  for (const { slug } of list) {
+    const o = el('option', '', slug); o.value = slug; $('project').append(o);
+  }
+}
+async function loadStatus() {
+  const s = await (await fetch('/api/status')).json();
+  ledgerFiles = s.ledgerFiles;
+  $('who').replaceChildren('machine ', Object.assign(el('b', '', s.machine)));
+}
+for (const id of ['project', 'since', 'until']) $(id).addEventListener('change', load);
+Promise.all([loadProjects(), loadStatus()]).then(load);
+</script>
+</body>
+</html>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.69.0",
+  "version": "0.70.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/index.ts CHANGED Viewed

@@ -17,6 +17,7 @@
  *   doctor                            Check prerequisites and system health
  *   usage                             Summarize token usage and cost
  *   ledger <sub> [filters]            Query the action ledger (log · show · stats)
+ *   server start|stop|status          Local page over the ledger
  *   skill link <name>                 Link a personal ~/.pal/skills/<name>/ into installed agents
  *   skill doctor <name|--all>         Evaluate one skill, or every installed skill, against the authoring best practices
  *   subagent link <name>             Install a personal ~/.pal/agents/<name>.md into installed agents
@@ -239,6 +240,12 @@ async function runCli(command: string | undefined, args: string[]) {
       if (code !== 0) process.exit(code);
       break;
     }
+    case "server": {
+      const { runServer } = await import("./server");
+      const code = await runServer(args);
+      if (code !== 0) process.exit(code);
+      break;
+    }
     case "subagent": {
       const { runSubagent } = await import("./subagent");
       const code = await runSubagent(args);
@@ -308,6 +315,7 @@ function showHelp() {
                                             (search · graph · stats · hubs · find · show · add · ls)
     pal cli ledger <sub> [filters]          Query the action ledger (log · show · stats)
                                             e.g. ledger log --project X --since 7d
+    pal cli server start|stop|status        Local page over the ledger, for showing the log to a person
     pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents
     pal cli skill doctor <name|--all>       Evaluate one skill, or every installed skill
     pal cli skill author-model              Print the flagship model that authors skills for the active agent

package/src/cli/ledger.ts CHANGED Viewed

@@ -16,6 +16,7 @@ import type { LedgerEntry } from "../hooks/lib/ledger";
 import {
   type ChainVerdict,
   chainVerdict,
+  changedLines,
   changeShape,
   findEntry,
   type LedgerFilter,
@@ -145,23 +146,6 @@ function shortId(id: string): string {
   return id.slice(0, 11).padEnd(11);
 }
-function changedLines(entry: LedgerEntry): string {
-  const shape = changeShape(entry);
-  switch (shape.kind) {
-    case "redacted":
-      return "withheld";
-    case "truncated":
-      return "too large";
-    case "none":
-      return "no change";
-    default: {
-      const added = shape.delta.hunks.reduce((n, h) => n + h.insert.length, 0);
-      const removed = shape.delta.hunks.reduce((n, h) => n + h.remove, 0);
-      return `+${added} -${removed}`;
-    }
-  }
-}
 function cmdLog(args: string[]): number {
   const parsed = parseFilters(args);
   if (typeof parsed === "string") return fail(parsed);

package/src/cli/server.ts ADDED Viewed

@@ -0,0 +1,195 @@
+/**
+ * pal cli server — start, stop and inspect the local ledger page.
+ *
+ * The server itself is src/tools/ledger/server.ts, run detached so it
+ * outlives the shell that started it. This file only owns the lifecycle:
+ * spawning, waiting for it to answer, remembering its pid, and killing it.
+ */
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { spawnDetachedInference } from "../hooks/lib/detached-inference";
+import { paths } from "../hooks/lib/paths";
+import { DEFAULT_PORT, LOOPBACK, type ServerStatus } from "../tools/ledger/server";
+interface ServerState {
+  pid: number;
+  port: number;
+  startedAt: string;
+}
+const SERVER_SCRIPT = resolve(import.meta.dir, "..", "tools", "ledger", "server.ts");
+const STARTUP_TIMEOUT_MS = 3000;
+const PROBE_TIMEOUT_MS = 500;
+export async function runServer(args: string[]): Promise<number> {
+  const [sub, ...rest] = args;
+  switch (sub) {
+    case "start":
+      return cmdStart(rest);
+    case "stop":
+      return cmdStop();
+    case "status":
+      return cmdStatus();
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      showHelp();
+      return 0;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      showHelp();
+      return 1;
+  }
+}
+function showHelp(): void {
+  console.log(`
+  Usage:
+    pal cli server <subcommand>
+  Subcommands:
+    start [--port <n>]         Start the ledger page in the background (default port ${DEFAULT_PORT})
+    stop                       Stop it
+    status                     Show whether it is running, and where
+  The page listens on ${LOOPBACK} only.
+`);
+}
+function url(port: number): string {
+  return `http://${LOOPBACK}:${port}/`;
+}
+function readState(): ServerState | null {
+  const file = paths.serverState();
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf-8")) as ServerState;
+  } catch {
+    return null;
+  }
+}
+function writeState(state: ServerState): void {
+  writeFileSync(paths.serverState(), JSON.stringify(state, null, 2), "utf-8");
+}
+function clearState(): void {
+  const file = paths.serverState();
+  if (existsSync(file)) unlinkSync(file);
+}
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function probe(port: number): Promise<ServerStatus | null> {
+  try {
+    const res = await fetch(`${url(port)}api/status`, {
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+    });
+    return res.ok ? ((await res.json()) as ServerStatus) : null;
+  } catch {
+    return null;
+  }
+}
+async function waitUntilAnswering(port: number): Promise<ServerStatus | null> {
+  const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const status = await probe(port);
+    if (status) return status;
+    await Bun.sleep(100);
+  }
+  return null;
+}
+function parsePort(args: string[]): number | string {
+  const { values } = parseArgs({ args, options: { port: { type: "string" } } });
+  if (values.port === undefined) return DEFAULT_PORT;
+  const port = Number(values.port);
+  return Number.isInteger(port) && port > 0 && port < 65536
+    ? port
+    : `--port must be a port number, got ${values.port}`;
+}
+async function cmdStart(args: string[]): Promise<number> {
+  const port = parsePort(args);
+  if (typeof port === "string") return fail(port);
+  const running = await runningServer();
+  if (running) {
+    console.log(`Already running at ${url(running.port)} (pid ${running.pid})`);
+    return 0;
+  }
+  spawnDetachedInference(SERVER_SCRIPT, [`--port=${port}`], "ledger-server");
+  const status = await waitUntilAnswering(port);
+  if (!status)
+    return fail(
+      `The ledger page did not answer on port ${port} within ${STARTUP_TIMEOUT_MS / 1000}s. Is the port free?`
+    );
+  writeState({ pid: status.pid, port, startedAt: status.startedAt });
+  console.log(url(port));
+  return 0;
+}
+/** The state file is a claim; the process answering on that port is the fact. */
+async function runningServer(): Promise<ServerState | null> {
+  const state = readState();
+  if (!state || !alive(state.pid)) return null;
+  return (await probe(state.port)) ? state : null;
+}
+async function cmdStop(): Promise<number> {
+  const state = readState();
+  if (!state) {
+    console.log("Not running.");
+    return 0;
+  }
+  if (alive(state.pid)) {
+    process.kill(state.pid);
+    console.log(`Stopped pid ${state.pid}.`);
+  } else {
+    console.log(`Pid ${state.pid} was already gone; cleared the stale record.`);
+  }
+  clearState();
+  return 0;
+}
+async function cmdStatus(): Promise<number> {
+  const state = readState();
+  if (!state) {
+    console.log("Not running.");
+    return 1;
+  }
+  const status = alive(state.pid) ? await probe(state.port) : null;
+  if (!status) {
+    console.log(
+      `Not running (stale record for pid ${state.pid}; run \`pal cli server stop\`).`
+    );
+    return 1;
+  }
+  console.log(`
+  ${url(status.port)}
+  pid          ${status.pid}
+  started      ${status.startedAt}
+  ledger       ${status.ledgerFiles} file(s)
+  machine      ${status.machine}
+`);
+  return 0;
+}
+function fail(message: string): number {
+  console.error(message);
+  return 1;
+}

package/src/hooks/lib/paths.ts CHANGED Viewed

@@ -62,6 +62,7 @@ export const paths = {
   work: () => ensureDir(home("memory", "work")),
   backups: () => ensureDir(home("backups")),
   debug: () => ensureDir(home("debug")),
+  serverState: () => home("server.json"),
 } as const;
 // Platform directories (env override or cross-platform defaults)
@@ -87,6 +88,7 @@ export const assets = {
   copilotHooksTemplate: () => pkg("assets", "templates", "hooks.copilot.json"),
   codexHooksTemplate: () => pkg("assets", "templates", "hooks.codex.json"),
   codexRulesTemplate: () => pkg("assets", "templates", "rules.codex.rules"),
+  ledgerPageTemplate: () => pkg("assets", "templates", "ledger-page.html"),
   statuslineScriptBash: () => pkg("assets", "statusline.sh"),
   statuslineScriptPs1: () => pkg("assets", "statusline.ps1"),
   agentTools: () => pkg("src", "tools", "agent"),

package/src/tools/ledger/query.ts CHANGED Viewed

@@ -158,6 +158,24 @@ export function changeShape(entry: LedgerEntry): ChangeShape {
  * its before-state again. `reverted` is exactly that case, and there the delta
  * can be run forward for real, which is why it reports whether it did.
  */
+/** The change as a reader would want it summarised: a line count, or why there is none. */
+export function changedLines(entry: LedgerEntry): string {
+  const shape = changeShape(entry);
+  switch (shape.kind) {
+    case "redacted":
+      return "withheld";
+    case "truncated":
+      return "too large";
+    case "none":
+      return "no change";
+    default: {
+      const added = shape.delta.hunks.reduce((n, h) => n + h.insert.length, 0);
+      const removed = shape.delta.hunks.reduce((n, h) => n + h.remove, 0);
+      return `+${added} -${removed}`;
+    }
+  }
+}
 export type Standing =
   | { state: "in-place" }
   | { state: "reverted"; replays: boolean }

package/src/tools/ledger/server.ts ADDED Viewed

@@ -0,0 +1,111 @@
+/**
+ * A local page over the ledger, for showing the action log to someone who
+ * will not read a terminal.
+ *
+ * Loopback only, stateless, no store of its own: every request reads the
+ * ledger afresh through the same query the CLI uses, so the page and
+ * `pal cli ledger` can never disagree. The browser holds nothing but the
+ * current filter selection.
+ */
+import { readFileSync } from "node:fs";
+import { loadMachine } from "../../hooks/lib/machine";
+import { assets } from "../../hooks/lib/paths";
+import { readAllProjects } from "../../hooks/lib/projects";
+import { type LedgerFilter, ledgerFiles, parseSince } from "./query";
+import { ledgerView } from "./view";
+export const DEFAULT_PORT = 7250;
+export const LOOPBACK = "127.0.0.1";
+export interface ServerStatus {
+  pid: number;
+  port: number;
+  startedAt: string;
+  ledgerFiles: number;
+  machine: string;
+}
+function json(body: unknown, status = 200): Response {
+  return Response.json(body, { status });
+}
+/** A window the page cannot parse is an error, not the whole ledger. */
+function filterFromQuery(params: URLSearchParams): LedgerFilter | string {
+  const filter: LedgerFilter = {};
+  const project = params.get("project");
+  if (project) filter.project = project;
+  for (const key of ["since", "until"] as const) {
+    const spec = params.get(key);
+    if (!spec) continue;
+    const at = parseSince(spec);
+    if (!at) return `Unrecognised ${key}: ${spec}`;
+    filter[key] = at;
+  }
+  return filter;
+}
+function page(): Response {
+  return new Response(readFileSync(assets.ledgerPageTemplate()), {
+    headers: { "content-type": "text/html; charset=utf-8" },
+  });
+}
+function projects(): Response {
+  const slugs = readAllProjects()
+    .map((p) => p.name)
+    .sort((a, b) => a.localeCompare(b));
+  return json(slugs.map((slug) => ({ slug })));
+}
+function ledger(url: URL): Response {
+  const filter = filterFromQuery(url.searchParams);
+  if (typeof filter === "string") return json({ error: filter }, 400);
+  return json(ledgerView(filter));
+}
+function status(port: number, startedAt: string): Response {
+  const body: ServerStatus = {
+    pid: process.pid,
+    port,
+    startedAt,
+    ledgerFiles: ledgerFiles().length,
+    machine: loadMachine().label,
+  };
+  return json(body);
+}
+export function startLedgerServer(port: number = DEFAULT_PORT) {
+  const startedAt = new Date().toISOString();
+  return Bun.serve({
+    hostname: LOOPBACK,
+    port,
+    fetch(request, server) {
+      if (request.method !== "GET") return json({ error: "read only" }, 405);
+      const url = new URL(request.url);
+      switch (url.pathname) {
+        case "/":
+          return page();
+        case "/api/ledger":
+          return ledger(url);
+        case "/api/projects":
+          return projects();
+        case "/api/status":
+          return status(server.port ?? port, startedAt);
+        default:
+          return json({ error: "not found" }, 404);
+      }
+    },
+  });
+}
+function portFromArgv(argv: string[]): number {
+  const flag = argv.find((arg) => arg.startsWith("--port="));
+  const port = flag ? Number(flag.slice("--port=".length)) : DEFAULT_PORT;
+  return Number.isInteger(port) && port >= 0 ? port : DEFAULT_PORT;
+}
+if (import.meta.main) {
+  const server = startLedgerServer(portFromArgv(process.argv.slice(2)));
+  console.log(`http://${LOOPBACK}:${server.port}/`);
+}

package/src/tools/ledger/view.ts ADDED Viewed

@@ -0,0 +1,130 @@
+/**
+ * The ledger as a page reads it: counts first, rows second, every field
+ * already in the words a person would use. Ids become labels, anchors become
+ * "project / path", deltas become line counts. Nothing here is computed in
+ * the browser, so the numbers on the page are the numbers the tests check.
+ */
+import {
+  type ActorRegistryEntry,
+  actorDisplayName,
+  loadActor,
+  readActorRegistry,
+} from "../../hooks/lib/actor";
+import type { LedgerEntry } from "../../hooks/lib/ledger";
+import { anchorSlugOf, changedLines, type LedgerFilter, queryLedger } from "./query";
+export const PAGE_OUTCOMES = ["applied", "failed", "denied", "blocked"] as const;
+export type PageOutcome = (typeof PAGE_OUTCOMES)[number];
+export interface OutcomeCount {
+  total: number;
+  byAuthority: Record<string, number>;
+  byRuntime: Record<string, number>;
+}
+export interface LedgerViewStats {
+  total: number;
+  refusals: number;
+  outcomes: Record<PageOutcome, OutcomeCount>;
+}
+export interface LedgerViewRow {
+  id: string;
+  ts: string;
+  actor: string;
+  authority: string;
+  runtime: string;
+  tool: string;
+  target: string;
+  change: string;
+  outcome: string;
+  reason?: string;
+}
+export interface LedgerView {
+  window: { since: string | null; until: string | null };
+  stats: LedgerViewStats;
+  rows: LedgerViewRow[];
+}
+function emptyCount(): OutcomeCount {
+  return { total: 0, byAuthority: {}, byRuntime: {} };
+}
+function bump(counts: Record<string, number>, key: string): void {
+  counts[key] = (counts[key] ?? 0) + 1;
+}
+function isPageOutcome(outcome: string): outcome is PageOutcome {
+  return (PAGE_OUTCOMES as readonly string[]).includes(outcome);
+}
+export function viewStats(entries: LedgerEntry[]): LedgerViewStats {
+  const outcomes = Object.fromEntries(
+    PAGE_OUTCOMES.map((outcome) => [outcome, emptyCount()])
+  ) as Record<PageOutcome, OutcomeCount>;
+  for (const entry of entries) {
+    if (!isPageOutcome(entry.outcome)) continue;
+    const count = outcomes[entry.outcome];
+    count.total++;
+    bump(count.byAuthority, entry.authority);
+    bump(count.byRuntime, entry.runtime);
+  }
+  return {
+    total: entries.length,
+    refusals: outcomes.denied.total + outcomes.blocked.total,
+    outcomes,
+  };
+}
+export function displayTarget(target: string): string {
+  const slug = anchorSlugOf(target);
+  if (!slug) return target;
+  const rest = target.slice(`{proj:${slug}}`.length);
+  return rest ? `${slug} ${rest}` : slug;
+}
+function toRow(entry: LedgerEntry, registry: ActorRegistryEntry[]): LedgerViewRow {
+  const row: LedgerViewRow = {
+    id: entry.id,
+    ts: entry.ts,
+    actor: actorDisplayName(entry.actor, registry),
+    authority: entry.authority,
+    runtime: entry.runtime,
+    tool: entry.tool,
+    target: displayTarget(entry.target),
+    change: changedLines(entry),
+    outcome: entry.outcome,
+  };
+  if (entry.reason) row.reason = entry.reason;
+  return row;
+}
+/** The local actor first: on a fresh install the registry may not list them yet. */
+function knownActors(): ActorRegistryEntry[] {
+  const self = loadActor();
+  return [{ id: self.id, label: self.label }, ...readActorRegistry()];
+}
+export function viewRows(entries: LedgerEntry[]): LedgerViewRow[] {
+  const registry = knownActors();
+  return entries
+    .slice()
+    .reverse()
+    .map((entry) => toRow(entry, registry));
+}
+export function ledgerView(filter: LedgerFilter = {}): LedgerView {
+  const entries = queryLedger(filter);
+  return {
+    window: {
+      since: filter.since?.toISOString() ?? null,
+      until: filter.until?.toISOString() ?? null,
+    },
+    stats: viewStats(entries),
+    rows: viewRows(entries),
+  };
+}