akm-cli 0.10.261005-beta → 0.10.261007-beta

package/dist/assets/ui/lib.js

@@ -0,0 +1,238 @@
+// Shared helpers for the akm ui client: HTML escaping, the API client, formatting.
+//
+// Every string that reaches the DOM goes through `html` (a tagged template that
+// escapes each interpolated value) and `mount` (the only place in the client
+// that writes markup into the page). Nothing else assigns markup, so reading
+// this file is enough to audit how page content is escaped.
+
+const ENTITIES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+
+/** Escape text for use in element content or a quoted attribute value. */
+export function esc(value) {
+  return String(value ?? "").replace(/[&<>"']/g, (c) => ENTITIES[c]);
+}
+
+/** Markup that is already safe: only `html` creates one. */
+class SafeHtml {
+  constructor(text) {
+    this.text = text;
+  }
+}
+
+function part(value) {
+  if (value instanceof SafeHtml) return value.text;
+  if (Array.isArray(value)) return value.map(part).join("");
+  if (value === null || value === undefined || value === false) return "";
+  return esc(value);
+}
+
+/** Tagged template: literal parts are trusted markup, every interpolated value is escaped unless it is itself `html`. */
+export function html(strings, ...values) {
+  let out = strings[0];
+  for (let i = 0; i < values.length; i++) out += part(values[i]) + strings[i + 1];
+  return new SafeHtml(out);
+}
+
+/** Replace the contents of `element` with `safe`. The one markup write in the client. */
+export function mount(element, safe) {
+  if (!(safe instanceof SafeHtml)) throw new TypeError("mount() takes the result of html``");
+  element.innerHTML = safe.text;
+}
+
+// ---- token and API client --------------------------------------------------
+
+const TOKEN_KEY = "akm-ui-token";
+let token = null;
+
+/** Read the launch token from the URL (then drop it from the address bar) or from sessionStorage. */
+export function initToken() {
+  const params = new URLSearchParams(location.search);
+  token = params.get("token");
+  try {
+    if (token) sessionStorage.setItem(TOKEN_KEY, token);
+    else token = sessionStorage.getItem(TOKEN_KEY);
+  } catch {
+    // sessionStorage can be unavailable; the URL token still works for this load.
+  }
+  if (params.has("token")) history.replaceState(null, "", location.pathname + location.hash);
+}
+
+export class ApiError extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/** Send one request and resolve to the response's `data`; failures are an {@link ApiError} with the server's `code`. */
+async function request(url, init) {
+  let response;
+  try {
+    response = await fetch(url, init);
+  } catch {
+    throw new ApiError(0, "NETWORK", "Could not reach the akm ui server. It may have stopped; run `akm ui` again.");
+  }
+  let body = null;
+  try {
+    body = await response.json();
+  } catch {
+    // Fall through to the generic error below.
+  }
+  if (response.status === 401) {
+    throw new ApiError(401, "UNAUTHORIZED", "The session token is missing or no longer valid.");
+  }
+  if (!body || body.ok !== true) {
+    throw new ApiError(
+      response.status,
+      body?.code ?? "BAD_RESPONSE",
+      body?.error ?? `Unexpected response (HTTP ${response.status}).`,
+    );
+  }
+  return body.data;
+}
+
+/** GET `path` with optional query values (empty ones are dropped); resolves to the response's `data`. */
+export function api(path, query = {}) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined && value !== null && value !== "") search.set(key, String(value));
+  }
+  const url = search.size > 0 ? `${path}?${search}` : path;
+  return request(url, { headers: { "X-Akm-Ui-Token": token ?? "" }, cache: "no-store" });
+}
+
+/** POST `body` as JSON to `path`. Only the proposal accept/reject routes take one; the token goes in the header, never the URL. */
+export function post(path, body = {}) {
+  return request(path, {
+    method: "POST",
+    headers: { "X-Akm-Ui-Token": token ?? "", "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    cache: "no-store",
+  });
+}
+
+let metaPromise = null;
+/** `/api/meta`, fetched once. */
+export function getMeta() {
+  if (!metaPromise) {
+    metaPromise = api("/api/meta");
+    metaPromise.catch(() => {
+      metaPromise = null;
+    });
+  }
+  return metaPromise;
+}
+
+// ---- formatting ------------------------------------------------------------
+
+export function fmtNum(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value.toLocaleString() : "-";
+}
+
+export function fmtPct(value) {
+  return typeof value === "number" && Number.isFinite(value) ? `${Math.round(value * 100)}%` : "-";
+}
+
+export function fmtMs(ms) {
+  if (typeof ms !== "number" || !Number.isFinite(ms)) return "-";
+  if (ms < 1000) return `${Math.round(ms)} ms`;
+  const seconds = ms / 1000;
+  if (seconds < 60) return `${seconds < 10 ? seconds.toFixed(1) : Math.round(seconds)} s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ${Math.round(seconds - minutes * 60)}s`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h ${minutes - hours * 60}m`;
+}
+
+/** "3h ago" style age of an ISO timestamp. */
+export function ago(iso) {
+  const t = Date.parse(iso ?? "");
+  if (Number.isNaN(t)) return "-";
+  const seconds = Math.round((Date.now() - t) / 1000);
+  if (seconds < 0) return "just now";
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 48) return `${hours}h ago`;
+  return `${Math.round(hours / 24)}d ago`;
+}
+
+export function fmtDateTime(iso) {
+  const t = Date.parse(iso ?? "");
+  return Number.isNaN(t) ? "-" : new Date(t).toLocaleString();
+}
+
+/** A relative time with the absolute time as its tooltip. */
+export function when(iso) {
+  return html`<time datetime="${iso ?? ""}" title="${fmtDateTime(iso)}">${ago(iso)}</time>`;
+}
+
+// ---- small building blocks -------------------------------------------------
+
+export function assetHref(ref) {
+  return `#/asset?ref=${encodeURIComponent(ref)}`;
+}
+
+export function proposalHref(id) {
+  return `#/proposals/${encodeURIComponent(id)}`;
+}
+
+/** Status pill: `kind` is ok | warn | fail | neutral | info. */
+export function badge(text, kind = "neutral") {
+  return html`<span class="badge badge-${kind}">${text}</span>`;
+}
+
+export function statusKind(status) {
+  if (status === "pass" || status === "ok") return "ok";
+  if (status === "warn") return "warn";
+  if (status === "fail") return "fail";
+  return "neutral";
+}
+
+export function tableWrap(inner) {
+  return html`<div class="table-wrap">${inner}</div>`;
+}
+
+export function emptyState(title, detail = "") {
+  return html`<div class="state state-empty"><p class="state-title">${title}</p>${detail ? html`<p>${detail}</p>` : ""}</div>`;
+}
+
+export function loadingState(label = "Loading") {
+  return html`<div class="state state-loading" role="status"><span class="spinner" aria-hidden="true"></span>${label}...</div>`;
+}
+
+export function errorState(error) {
+  if (error instanceof ApiError && error.status === 401) {
+    return html`<div class="state state-error" role="alert">
+      <p class="state-title">Not signed in</p>
+      <p>${error.message} Open the URL printed by <code>akm ui</code> (it ends in <code>?token=...</code>) to start a session.</p>
+    </div>`;
+  }
+  const code = error instanceof ApiError ? error.code : "ERROR";
+  const message = error instanceof Error ? error.message : String(error);
+  return html`<div class="state state-error" role="alert">
+    <p class="state-title">Could not load this page</p>
+    <p>${message}</p>
+    <p class="muted"><code>${code}</code></p>
+  </div>`;
+}
+
+export function pageHeader(title, subtitle = "") {
+  return html`<header class="page-head"><h1>${title}</h1>${subtitle ? html`<p class="muted">${subtitle}</p>` : ""}</header>`;
+}
+
+/** A definition list from [label, value] pairs; null/undefined/empty values are skipped. */
+export function definitionList(pairs) {
+  const rows = pairs.filter(([, value]) => value !== null && value !== undefined && value !== "");
+  return html`<dl class="kv">${rows.map(([label, value]) => html`<dt>${label}</dt><dd>${value}</dd>`)}</dl>`;
+}
+
+export function pretty(value) {
+  return JSON.stringify(value, null, 2);
+}
+
+export function percent(part, total) {
+  return total > 0 ? Math.round((part / total) * 1000) / 10 : 0;
+}

package/dist/assets/ui/markdown.js

@@ -0,0 +1,103 @@
+// A deliberately tiny markdown renderer: headings, lists, fenced code, inline code, bold, links and [[wikilinks]].
+// It never touches raw text except through `html`, which escapes every interpolated value.
+
+import { assetHref, html } from "./lib.js";
+
+const SAFE_URL = /^(https?:\/\/|mailto:|#)/i;
+const INLINE = /`([^`]+)`|\[\[([^\]]+)\]\]|\[([^\]]+)\]\(([^)\s]+)\)|\*\*([^*]+)\*\*/g;
+
+function link(text, url) {
+  if (!SAFE_URL.test(url)) return html`${text}`;
+  const external = /^(https?:|mailto:)/i.test(url);
+  return external
+    ? html`<a href="${url}" target="_blank" rel="noopener noreferrer">${text}</a>`
+    : html`<a href="${url}">${text}</a>`;
+}
+
+/** Inline spans of one line of text. */
+export function inline(text) {
+  const out = [];
+  let last = 0;
+  for (const m of text.matchAll(INLINE)) {
+    out.push(text.slice(last, m.index));
+    if (m[1] !== undefined) out.push(html`<code>${m[1]}</code>`);
+    else if (m[2] !== undefined)
+      out.push(html`<a href="${assetHref(m[2].split("|")[0].trim())}"><code>${m[2]}</code></a>`);
+    else if (m[3] !== undefined) out.push(link(m[3], m[4]));
+    else out.push(html`<strong>${m[5]}</strong>`);
+    last = m.index + m[0].length;
+  }
+  out.push(text.slice(last));
+  return html`${out}`;
+}
+
+/** Render markdown text to safe HTML. */
+export function markdown(source) {
+  const lines = String(source ?? "")
+    .replace(/\r\n?/g, "\n")
+    .split("\n");
+  const blocks = [];
+  let paragraph = [];
+  let list = null;
+  const flushParagraph = () => {
+    if (paragraph.length > 0) blocks.push(html`<p>${inline(paragraph.join(" "))}</p>`);
+    paragraph = [];
+  };
+  const flushList = () => {
+    if (list) blocks.push(list.ordered ? html`<ol>${list.items}</ol>` : html`<ul>${list.items}</ul>`);
+    list = null;
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fence = /^```\s*(\S*)/.exec(line);
+    if (fence) {
+      flushParagraph();
+      flushList();
+      const code = [];
+      for (i++; i < lines.length && !/^```/.test(lines[i]); i++) code.push(lines[i]);
+      blocks.push(html`<pre class="code"><code>${code.join("\n")}</code></pre>`);
+      continue;
+    }
+    const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (heading) {
+      flushParagraph();
+      flushList();
+      const level = Math.min(heading[1].length + 1, 6);
+      blocks.push(html`<h${level}>${inline(heading[2])}</h${level}>`);
+      continue;
+    }
+    const item = /^\s*(?:([-*+])|(\d+)[.)])\s+(.*)$/.exec(line);
+    if (item) {
+      flushParagraph();
+      const ordered = item[2] !== undefined;
+      if (list && list.ordered !== ordered) flushList();
+      list ??= { ordered, items: [] };
+      list.items.push(html`<li>${inline(item[3])}</li>`);
+      continue;
+    }
+    if (line.trim() === "") {
+      flushParagraph();
+      flushList();
+      continue;
+    }
+    flushList();
+    paragraph.push(line.trim());
+  }
+  flushParagraph();
+  flushList();
+  return html`<div class="md">${blocks}</div>`;
+}
+
+/** Split leading `---` frontmatter from `content`: { fields: [[key, value]], body }. */
+export function splitFrontmatter(content) {
+  const text = String(content ?? "").replace(/\r\n?/g, "\n");
+  const m = /^---\n([\s\S]*?)\n---[ \t]*(?:\n|$)/.exec(text);
+  if (!m) return { fields: [], body: text };
+  const fields = [];
+  for (const line of m[1].split("\n")) {
+    const kv = /^([A-Za-z0-9_.-]+):\s*(.*)$/.exec(line);
+    if (kv) fields.push([kv[1], kv[2]]);
+    else if (fields.length > 0 && line.trim() !== "") fields[fields.length - 1][1] += `\n${line}`;
+  }
+  return { fields, body: text.slice(m[0].length) };
+}

package/dist/assets/ui/overview.js

@@ -0,0 +1,145 @@
+// Overview: health status, check results, metrics, recent improve runs and the 14-day usage chart.
+
+import { miniBar, usageChart } from "./charts.js";
+import {
+  api,
+  badge,
+  emptyState,
+  fmtMs,
+  fmtNum,
+  fmtPct,
+  getMeta,
+  html,
+  pageHeader,
+  pretty,
+  statusKind,
+  tableWrap,
+  when,
+} from "./lib.js";
+
+const GROUPS = [
+  { status: "fail", title: "Failing", open: true },
+  { status: "warn", title: "Warnings", open: true },
+  { status: "unknown", title: "Unknown", open: false },
+  { status: "pass", title: "Passing", open: false },
+];
+
+function checkItem(check) {
+  const evidence = check.evidence && Object.keys(check.evidence).length > 0 ? check.evidence : null;
+  return html`<li class="check">
+    <div class="check-head"><span class="dot dot-${statusKind(check.status)}" aria-hidden="true"></span><strong class="mono">${check.name}</strong>
+      <span class="muted small">${check.kind}, ${check.confidence} confidence</span></div>
+    <p class="check-msg">${check.message}</p>
+    ${evidence ? html`<details><summary>Evidence</summary><pre class="code">${pretty(evidence)}</pre></details>` : ""}
+  </li>`;
+}
+
+function healthSection(health) {
+  const checks = [...health.hardChecks, ...health.advisories];
+  return html`<section><h2>Health checks</h2>${GROUPS.map((g) => {
+    const items = checks.filter((c) => c.status === g.status);
+    if (items.length === 0) return "";
+    return html`<details class="group" ${g.open ? html`open` : ""}><summary><span class="dot dot-${statusKind(g.status)}" aria-hidden="true"></span>${g.title} <span class="num muted">${items.length}</span></summary><ul class="checks">${items.map(checkItem)}</ul></details>`;
+  })}${checks.length === 0 ? emptyState("No health checks ran.") : ""}</section>`;
+}
+
+function statusStrip(health, meta) {
+  const checks = health ? [...health.hardChecks, ...health.advisories] : [];
+  const count = (status) => checks.filter((c) => c.status === status).length;
+  const overall = health?.status ?? "unknown";
+  return html`<div class="strip">
+    <div class="strip-main"><span class="strip-label">Overall health</span>${badge(health ? overall : "unavailable", statusKind(overall))}</div>
+    <div class="strip-item"><span class="num big ${count("fail") > 0 ? "text-fail" : ""}">${count("fail")}</span><span class="muted">failing</span></div>
+    <div class="strip-item"><span class="num big ${count("warn") > 0 ? "text-warn" : ""}">${count("warn")}</span><span class="muted">warning</span></div>
+    <div class="strip-item"><span class="num big">${count("unknown")}</span><span class="muted">unknown</span></div>
+    <div class="strip-item"><span class="num big">${count("pass")}</span><span class="muted">passing</span></div>
+    <div class="strip-item strip-right"><span class="mono">akm ${meta ? meta.version : "?"}</span>${health ? html`<span class="muted small">window since ${when(health.since)}</span>` : ""}</div>
+  </div>`;
+}
+
+function tile(label, value, sub = "") {
+  return html`<div class="tile"><div class="tile-label">${label}</div><div class="tile-value num">${value}</div>${sub ? html`<div class="tile-sub muted">${sub}</div>` : ""}</div>`;
+}
+
+function metricsSection(m) {
+  if (!m) return "";
+  const u = m.usage;
+  const day = (iso) => String(iso).slice(0, 10);
+  return html`<section><h2>Metrics</h2><p class="muted">${day(m.window.since)} to ${day(m.window.until)}</p>
+    <div class="tiles">
+      ${tile("Searches", fmtNum(u.totals.searches), `${fmtNum(u.totals.zeroResultSearches)} with no results`)}
+      ${tile("Shows", fmtNum(u.totals.shows), `${fmtNum(u.totals.distinctAssets)} distinct assets`)}
+      ${tile("Curates", fmtNum(u.totals.curates))}
+      ${tile("Select rate", fmtPct(u.selectRate), `${fmtNum(u.totals.selects)} selects`)}
+      ${tile("Median search", fmtMs(u.searchMedianMs))}
+      ${tile("Feedback", `+${fmtNum(m.feedback.totals.positive)} / -${fmtNum(m.feedback.totals.negative)}`, "positive / negative")}
+      ${tile("LLM calls", fmtNum(m.llm.calls), `${fmtNum(m.llm.failures)} failed, ${fmtNum(m.llm.totalTokens)} tokens`)}
+      ${tile("Pending proposals", fmtNum(m.proposals.byStatus.pending ?? 0))}
+      ${tile("Task runs", fmtNum(m.tasks.runs), `${fmtNum(m.tasks.failed)} failed`)}
+      ${tile("Index builds", fmtNum(m.index.runs), `median ${fmtMs(m.index.medianMs)}`)}
+    </div>
+    ${m.proposals.acceptRateBySource.length > 0 ? html`<h3>Proposal outcomes by source</h3>${tableWrap(html`<table><thead><tr><th>Source</th><th class="r">Total</th><th class="r">Accepted</th><th class="r">Rejected</th><th class="r">Pending</th><th class="r">Accept rate</th></tr></thead><tbody>${m.proposals.acceptRateBySource.map((r) => html`<tr><td class="mono">${r.source}</td><td class="r num">${fmtNum(r.total)}</td><td class="r num">${fmtNum(r.accepted)}</td><td class="r num">${fmtNum(r.rejected)}</td><td class="r num">${fmtNum(r.pending)}</td><td class="r num">${fmtPct(r.acceptRate)}</td></tr>`)}</tbody></table>`)}` : ""}
+  </section>`;
+}
+
+function syncText(sync) {
+  if (!sync) return "-";
+  if (sync.skipped) return sync.reason ? `skipped (${sync.reason})` : "skipped";
+  return [sync.committed ? "committed" : "no changes", sync.pushed ? "pushed" : ""].filter(Boolean).join(", ");
+}
+
+function triageText(t) {
+  if (!t) return "-";
+  const parts = [
+    [t.promoted, "promoted"],
+    [t.rejected, "rejected"],
+    [t.deferred, "deferred"],
+    [t.failed, "failed"],
+    [t.skippedByCap, "capped"],
+  ]
+    .filter(([n]) => n > 0)
+    .map(([n, label]) => `${n} ${label}`);
+  return parts.length > 0 ? parts.join(", ") : "none";
+}
+
+function runsSection(runs) {
+  if (runs.length === 0) {
+    return html`<section><h2>Recent improve runs</h2>${emptyState("No improve runs yet.", "Runs appear here after akm improve completes.")}</section>`;
+  }
+  const maxDuration = Math.max(0, ...runs.map((r) => r.durationMs ?? 0));
+  const maxCalls = Math.max(0, ...runs.map((r) => r.modelCalls?.total ?? 0));
+  return html`<section><h2>Recent improve runs</h2><p class="muted">Last ${runs.length}, newest first. Bars share one scale per column.</p>
+    ${tableWrap(
+      html`<table class="runs"><thead><tr><th>Started</th><th>Result</th><th colspan="2">Duration</th><th colspan="2">Model calls</th><th>Sync</th><th>Triage</th></tr></thead><tbody>${runs.map(
+        (r) => {
+          const calls = r.modelCalls?.total ?? 0;
+          const failed = r.modelCalls?.failures ?? 0;
+          return html`<tr>
+        <td>${when(r.startedAt)}<div class="muted small mono">${r.id}</div></td>
+        <td>${r.ok ? badge("ok", "ok") : badge("failed", "fail")}</td>
+        <td class="r num">${fmtMs(r.durationMs)}</td><td>${miniBar(r.durationMs ?? 0, maxDuration, 0, `duration ${fmtMs(r.durationMs)}`)}</td>
+        <td class="r num">${calls}${failed > 0 ? html` <span class="text-fail">(${failed} failed)</span>` : ""}</td><td>${miniBar(calls, maxCalls, failed, `${calls} model calls, ${failed} failed`)}</td>
+        <td>${syncText(r.sync)}</td>
+        <td>${triageText(r.triage)}</td>
+      </tr>`;
+        },
+      )}</tbody></table>`,
+    )}</section>`;
+}
+
+function usageSection(days) {
+  const any = days.some((d) => d.search + d.curate + d.show + d.feedbackPositive + d.feedbackNegative > 0);
+  return html`<section><h2>Usage, last 14 days</h2>${any ? usageChart(days) : emptyState("No usage events in the last 14 days.", "Searches, shows, curates and feedback you make with akm are counted here.")}</section>`;
+}
+
+export async function render() {
+  const [data, meta] = await Promise.all([api("/api/overview"), getMeta().catch(() => null)]);
+  const errors = data.errors ? Object.entries(data.errors) : [];
+  return html`${pageHeader("Overview", "Health, usage and recent improve runs.")}
+    ${statusStrip(data.health, meta)}
+    ${errors.length > 0 ? html`<div class="notice notice-warn" role="alert"><strong>Some sections could not load.</strong><ul>${errors.map(([name, message]) => html`<li><span class="mono">${name}</span>: ${message}</li>`)}</ul></div>` : ""}
+    ${data.health ? healthSection(data.health) : ""}
+    ${metricsSection(data.metrics)}
+    ${runsSection(data.improveRuns ?? [])}
+    ${usageSection(data.usageByDay ?? [])}`;
+}