portable-agent-layer 0.68.0 → 0.70.0

package/src/tools/ledger/server.ts

@@ -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

@@ -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),
+  };
+}