llm-wiki-compiler 0.6.0 → 0.7.0

package/dist/viewer/assets/viewer.css

@@ -0,0 +1,314 @@
+/* llmwiki viewer — minimal typography + layout. Dark-mode-friendly defaults. */
+
+:root {
+  color-scheme: light dark;
+  --bg: #ffffff;
+  --bg-muted: #f7f7f8;
+  --surface: #ffffff;
+  --surface-raised: #fbfbfc;
+  --fg: #16181d;
+  --fg-muted: #5f6470;
+  --border: #e1e2e6;
+  --accent: #2a6df4;
+  --accent-soft: rgba(42, 109, 244, 0.1);
+  --missing: #b00020;
+  --max-content-width: 72ch;
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Helvetica, Arial, sans-serif;
+  font-size: 16px;
+  line-height: 1.55;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #16181d;
+    --bg-muted: #1e2026;
+    --surface: #14161b;
+    --surface-raised: #20232a;
+    --fg: #e7e8ec;
+    --fg-muted: #9ea3ad;
+    --border: #2c2f36;
+    --accent: #7eb1ff;
+    --accent-soft: rgba(126, 177, 255, 0.14);
+    --missing: #ff8a8a;
+  }
+}
+
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--fg); }
+a { color: var(--accent); text-decoration: none; }
+a:hover, a:focus-visible { text-decoration: underline; }
+
+/* Universal visible-focus ring so keyboard navigation is always
+ * obvious. Spec §Slice 5 acceptance: "keyboard focus states are
+ * visible." */
+:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
+.visually-hidden {
+  position: absolute;
+  width: 1px; height: 1px;
+  padding: 0; margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.skip-link {
+  position: absolute; top: -100px; left: 0;
+  padding: 0.5rem 1rem; background: var(--accent); color: #fff; z-index: 100;
+}
+.skip-link:focus { top: 0; }
+
+.app-header {
+  padding: 0.75rem 1rem; border-bottom: 1px solid var(--border);
+  background: var(--surface);
+  display: flex; align-items: center; justify-content: space-between; gap: 1rem;
+}
+.app-brand {
+  display: inline-flex;
+  align-items: center;
+  min-width: 0;
+  gap: 0.6rem;
+}
+.app-logo {
+  width: 2rem;
+  height: 2rem;
+  flex: none;
+  object-fit: contain;
+}
+.app-title { font-size: 1.05rem; }
+.github-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.35rem 0.65rem;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  color: var(--fg);
+  background: var(--surface-raised);
+  font-weight: 700;
+  line-height: 1;
+}
+.github-link:hover,
+.github-link:focus-visible {
+  background: var(--accent-soft);
+  text-decoration: none;
+}
+.github-mark {
+  width: 1.25rem;
+  height: 1.25rem;
+  flex: none;
+  fill: currentColor;
+}
+.github-stars {
+  font-size: 1.05em;
+  font-variant-numeric: tabular-nums;
+}
+
+.app-layout {
+  display: grid;
+  grid-template-columns: 240px minmax(0, 1fr) 260px;
+  gap: 0;
+  min-height: calc(100vh - 3rem);
+}
+
+.sidebar {
+  border-right: 1px solid var(--border);
+  background: var(--bg-muted);
+  padding: 1rem;
+  overflow-y: auto;
+}
+.sidebar.search-active [data-sidebar] { display: none; }
+.sidebar h2 {
+  font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.05em;
+  color: var(--fg-muted); margin: 1rem 0 0.5rem;
+}
+.sidebar details { margin: 0.65rem 0; }
+.sidebar summary {
+  cursor: pointer;
+  font-weight: 700;
+  color: var(--fg);
+  margin-bottom: 0.35rem;
+}
+.sidebar ul { list-style: none; padding: 0; margin: 0; }
+.sidebar li a {
+  display: block;
+  padding: 0.28rem 0.5rem;
+  border-radius: 6px;
+  color: var(--fg);
+  line-height: 1.35;
+}
+.sidebar li a:hover, .sidebar li a:focus-visible { background: var(--surface); }
+.sidebar li a[aria-current="page"] { background: var(--accent); color: #fff; }
+
+.sidebar-search {
+  margin-bottom: 0.75rem;
+}
+.sidebar-search input[type="search"] {
+  width: 100%;
+  padding: 0.4rem 0.6rem;
+  background: var(--bg); color: var(--fg);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  font-size: 0.95rem;
+}
+
+.search-results {
+  list-style: none;
+  margin: 0 0 1rem;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.15rem;
+}
+.search-results[hidden] { display: none; }
+.search-results .empty {
+  font-style: italic;
+  color: var(--fg-muted);
+  padding: 0.4rem 0.5rem;
+}
+.search-results a {
+  display: block;
+  padding: 0.55rem 0.6rem;
+  border-radius: 6px;
+  color: var(--fg);
+}
+.search-results a:hover,
+.search-results a:focus-visible {
+  background: var(--surface);
+}
+.search-results .result-title {
+  display: block;
+  font-weight: 600;
+}
+.search-results .result-snippet {
+  display: block;
+  font-size: 0.85rem;
+  color: var(--fg-muted);
+  margin-top: 0.1rem;
+}
+.search-results .result-kind {
+  font-size: 0.75rem;
+  color: var(--fg-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin-right: 0.4rem;
+}
+
+.main-pane {
+  padding: 2rem;
+  width: min(100%, var(--max-content-width));
+  overflow-x: auto;
+}
+.main-pane:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.main-pane h1, .main-pane h2, .main-pane h3 { line-height: 1.25; }
+.main-pane h1 { margin-top: 0; }
+.main-pane pre {
+  background: var(--bg-muted); padding: 0.75rem 1rem; border-radius: 6px;
+  overflow-x: auto;
+}
+.main-pane code { background: var(--bg-muted); padding: 0.1em 0.3em; border-radius: 3px; }
+.main-pane pre code { background: none; padding: 0; }
+
+.support-rail {
+  border-left: 1px solid var(--border);
+  padding: 1rem; background: var(--bg-muted); font-size: 0.875rem;
+}
+.support-rail dt { font-weight: 700; color: var(--fg-muted); margin-top: 0.7rem; }
+.support-rail dd { margin: 0.25rem 0; }
+
+.placeholder { color: var(--fg-muted); font-style: italic; }
+[data-missing="true"] {
+  color: var(--missing);
+  text-decoration: underline dotted;
+  text-underline-offset: 0.18em;
+}
+
+.warning-banner {
+  background: rgba(176, 0, 32, 0.08); color: var(--missing);
+  padding: 0.5rem 0.75rem; border-radius: 4px; margin-bottom: 1rem;
+}
+
+.health-dashboard {
+  display: grid;
+  gap: 1rem;
+}
+.metric-list {
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  column-gap: 1rem;
+  row-gap: 0.25rem;
+  margin: 0;
+}
+.metric-list .metric { display: contents; }
+.health-dashboard dt { color: var(--fg-muted); }
+.health-dashboard dd { margin: 0; font-variant-numeric: tabular-nums; }
+
+.home-dashboard {
+  width: min(100%, 58rem);
+}
+.metric-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(8.5rem, 1fr));
+  gap: 0.75rem;
+  margin: 1.25rem 0;
+}
+.metric-grid .metric {
+  padding: 0.85rem;
+  background: var(--surface-raised);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+}
+.metric-grid dt {
+  color: var(--fg-muted);
+  font-size: 0.82rem;
+}
+.metric-grid dd {
+  margin: 0.15rem 0 0;
+  font-size: 1.65rem;
+  font-weight: 750;
+  line-height: 1.1;
+  font-variant-numeric: tabular-nums;
+}
+.home-action a {
+  display: inline-flex;
+  padding: 0.5rem 0.7rem;
+  border-radius: 6px;
+  background: var(--accent-soft);
+}
+.recent-section { margin-top: 1.5rem; }
+.recent-list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: grid;
+  gap: 0.35rem;
+}
+.recent-list a {
+  display: block;
+  padding: 0.5rem 0;
+  border-bottom: 1px solid var(--border);
+}
+
+@media (max-width: 800px) {
+  .app-layout {
+    grid-template-columns: 1fr;
+    grid-template-rows: auto auto auto auto;
+  }
+  .sidebar {
+    border-right: none;
+    border-bottom: 1px solid var(--border);
+    overflow-y: auto;
+    max-height: 16rem;
+  }
+  .support-rail {
+    border-left: none;
+    border-top: 1px solid var(--border);
+  }
+  .main-pane {
+    padding: 1rem;
+  }
+}

package/dist/viewer/assets/viewer.js

@@ -0,0 +1,363 @@
+/**
+ * llmwiki viewer — vanilla-JS client.
+ *
+ * Three responsibilities, kept deliberately small:
+ *   1. First paint from the server-embedded `<script type="application/json"
+ *      id="page-index">` blob so the sidebar shows pages before any fetch.
+ *   2. Full data from `/api/pages` once the page loads — replaces the
+ *      first-paint sidebar with grouped concepts/queries, and renders
+ *      the dashboard home.
+ *   3. Hash router (`#/`, `#/concepts/<slug>`, `#/queries/<slug>`,
+ *      `#/index`, `#/health`) that fetches `/api/page/...`,
+ *      `/api/index`, or `/api/health` and drops the result into the
+ *      main pane. The server returns already-sanitized HTML in `html`
+ *      (see `src/viewer/render.ts`), so the client only has to set
+ *      `innerHTML` and link up the support rail.
+ *
+ * No external dependencies, no client-side markdown rendering, no
+ * inline event handlers — the spec's CSP only allows scripts from
+ * `'self'`. The search-input wiring lives in `viewer-search.js`.
+ */
+
+import { wireSearch } from "./viewer-search.js";
+import { renderSidebar, markActive } from "./viewer-sidebar.js";
+import { renderProjectRail, renderSupportRail, clearSupportRail } from "./viewer-rail.js";
+
+const PAGE_INDEX_SELECTOR = "#page-index";
+const MAIN_SELECTOR = "[data-main-pane]";
+const TITLE_SELECTOR = "[data-app-title]";
+
+/** Parse the server-embedded page-index JSON. Empty list if absent or malformed. */
+function readEmbeddedIndex() {
+  const node = document.querySelector(PAGE_INDEX_SELECTOR);
+  if (!node || !node.textContent) return { pages: [] };
+  try {
+    const data = JSON.parse(node.textContent);
+    return Array.isArray(data?.pages) ? { pages: data.pages } : { pages: [] };
+  } catch {
+    return { pages: [] };
+  }
+}
+
+
+/**
+ * Parse `location.hash` into a route descriptor. Malformed percent-
+ * encoding in the slug segment falls back to the home route so a typo
+ * or hand-edited URL cannot throw from `decodeURIComponent` and crash
+ * the client (`#/concepts/%E0%A4%A` is the canonical bad-input case).
+ */
+function parseRoute(hash) {
+  if (!hash || hash === "#" || hash === "#/" || hash === "") return { kind: "home" };
+  if (hash === "#/index") return { kind: "index" };
+  if (hash === "#/health") return { kind: "health" };
+  const match = hash.match(/^#\/(concepts|queries)\/(.+)$/);
+  if (!match) return { kind: "home" };
+  let slug;
+  try {
+    slug = decodeURIComponent(match[2]);
+  } catch {
+    return { kind: "home" };
+  }
+  return { kind: "page", directory: match[1], slug };
+}
+
+/** Render the home dashboard from the `/api/pages` envelope. */
+function renderHome(envelope) {
+  const main = document.querySelector(MAIN_SELECTOR);
+  if (!main) return;
+  main.innerHTML = "";
+  main.className = "main-pane home-dashboard";
+  const title = document.createElement("h1");
+  title.textContent = envelope.project?.title || "llmwiki";
+  main.appendChild(title);
+  main.appendChild(buildCountsBlock(envelope.counts || {}));
+  if (envelope.index?.available) main.appendChild(buildIndexLink(envelope.index.href));
+  if (Array.isArray(envelope.recentPages) && envelope.recentPages.length > 0) {
+    main.appendChild(buildRecentBlock(envelope.recentPages));
+  }
+  renderProjectRail(envelope);
+}
+
+/** Render a `<dl>` of project counts on the home dashboard. */
+function buildCountsBlock(counts) {
+  const dl = buildDefinitionList([
+    ["Concepts", counts.concepts ?? 0],
+    ["Saved queries", counts.queries ?? 0],
+    ["Source files", counts.sourceFiles ?? 0],
+    ["Pending reviews", counts.pendingReviews ?? 0],
+  ]);
+  dl.className = "metric-grid";
+  return dl;
+}
+
+/** Build a `<dl>` from a list of `[label, value]` rows. */
+function buildDefinitionList(rows) {
+  const dl = document.createElement("dl");
+  for (const [label, value] of rows) {
+    const row = document.createElement("div");
+    row.className = "metric";
+    const dt = document.createElement("dt");
+    dt.textContent = label;
+    const dd = document.createElement("dd");
+    dd.textContent = String(value);
+    row.appendChild(dt);
+    row.appendChild(dd);
+    dl.appendChild(row);
+  }
+  return dl;
+}
+
+/** Build the link that takes the user to the compiled wiki/index.md page. */
+function buildIndexLink(href) {
+  const p = document.createElement("p");
+  p.className = "home-action";
+  const a = document.createElement("a");
+  a.href = href;
+  a.textContent = "Browse the compiled index →";
+  p.appendChild(a);
+  return p;
+}
+
+/** Render the recent-pages list on the home dashboard. */
+function buildRecentBlock(recent) {
+  const h2 = document.createElement("h2");
+  h2.textContent = "Recently updated";
+  const ul = document.createElement("ul");
+  ul.className = "recent-list";
+  for (const page of recent) {
+    const li = document.createElement("li");
+    const a = document.createElement("a");
+    a.href = `#/${encodeURIComponent(page.pageDirectory)}/${encodeURIComponent(page.slug)}`;
+    a.textContent = page.title || page.slug;
+    li.appendChild(a);
+    ul.appendChild(li);
+  }
+  const wrap = document.createElement("section");
+  wrap.className = "recent-section";
+  wrap.appendChild(h2);
+  wrap.appendChild(ul);
+  return wrap;
+}
+
+/** Fetch and render the page at the current hash route. */
+async function renderRoute() {
+  const route = parseRoute(location.hash);
+  markActive();
+  const main = document.querySelector(MAIN_SELECTOR);
+  if (!main) return;
+  main.className = "main-pane";
+  if (route.kind === "home") return loadAndRenderHome();
+  if (route.kind === "index") return renderIndexPane(main);
+  if (route.kind === "health") return renderHealthPane(main);
+  return renderPagePane(main, route.directory, route.slug);
+}
+
+/** Fetch /api/health and render the dashboard. */
+async function renderHealthPane(main) {
+  try {
+    const health = await fetchJson("/api/health");
+    main.innerHTML = "";
+    const h1 = document.createElement("h1");
+    h1.textContent = "Health";
+    main.appendChild(h1);
+    main.appendChild(buildHealthDashboard(health));
+    clearSupportRail();
+  } catch (err) {
+    renderError(`Could not load /api/health: ${err.message}`);
+  }
+}
+
+/** Build the health dashboard DOM from the `/api/health` payload. */
+function buildHealthDashboard(health) {
+  const wrap = document.createElement("section");
+  wrap.className = "health-dashboard";
+  const metrics = buildDefinitionList([
+    ["Concepts", health.concepts ?? 0],
+    ["Saved queries", health.queries ?? 0],
+    ["Compiled sources", health.sources ?? 0],
+    ["Source files", health.sourceFiles ?? 0],
+    ["Pending reviews", health.pendingReviews ?? 0],
+  ]);
+  metrics.className = "metric-list";
+  wrap.appendChild(metrics);
+  wrap.appendChild(buildLintBlock(health.lint));
+  return wrap;
+}
+
+/** Render the lint summary, or a "lint has not been run yet" placeholder. */
+function buildLintBlock(lint) {
+  const wrap = document.createElement("section");
+  const h2 = document.createElement("h2");
+  h2.textContent = "Lint";
+  wrap.appendChild(h2);
+  if (!lint) {
+    const note = document.createElement("p");
+    note.className = "placeholder";
+    note.textContent = "No cached lint summary yet — run `llmwiki lint`.";
+    wrap.appendChild(note);
+    return wrap;
+  }
+  wrap.appendChild(buildDefinitionList([
+    ["Warnings", lint.warnings ?? 0],
+    ["Errors", lint.errors ?? 0],
+    ["Last run", lint.at ?? ""],
+  ]));
+  return wrap;
+}
+
+/** Fetch /api/pages and render the dashboard. */
+async function loadAndRenderHome() {
+  try {
+    const envelope = await fetchJson("/api/pages");
+    document.querySelector(TITLE_SELECTOR).textContent = envelope.project?.title || "llmwiki";
+    renderSidebar(envelope.pages || []);
+    renderHome(envelope);
+  } catch (err) {
+    renderError(`Could not load /api/pages: ${err.message}`);
+  }
+}
+
+/** Fetch /api/index and render the rendered HTML coming back from the server. */
+async function renderIndexPane(main) {
+  clearSupportRail();
+  try {
+    const payload = await fetchJson("/api/index");
+    main.innerHTML = "";
+    const h1 = document.createElement("h1");
+    h1.textContent = "Index";
+    main.appendChild(h1);
+    appendRenderedBody(main, payload.html);
+  } catch (err) {
+    if (err.status === 404) {
+      main.innerHTML = "";
+      const note = document.createElement("p");
+      note.className = "placeholder";
+      note.textContent = "wiki/index.md is not available. Run `llmwiki compile`.";
+      main.appendChild(note);
+    } else {
+      renderError(`Could not load /api/index: ${err.message}`);
+    }
+  }
+}
+
+/** Fetch /api/page/:dir/:slug and render. */
+async function renderPagePane(main, directory, slug) {
+  try {
+    const payload = await fetchJson(
+      `/api/page/${encodeURIComponent(directory)}/${encodeURIComponent(slug)}`,
+    );
+    main.innerHTML = "";
+    const h1 = document.createElement("h1");
+    h1.textContent = payload.title || slug;
+    main.appendChild(h1);
+    if (payload.pageDirectory === "queries") {
+      const question = document.createElement("p");
+      question.className = "query-question";
+      question.textContent = `Question: ${payload.title || slug}`;
+      main.appendChild(question);
+    }
+    appendWarnings(main, payload.warnings || []);
+    const body = appendRenderedBody(main, payload.html);
+    removeDuplicateLeadingHeading(body, payload.title || slug);
+    renderSupportRail(payload);
+  } catch (err) {
+    if (err.status === 404) {
+      main.innerHTML = "";
+      const note = document.createElement("p");
+      note.className = "placeholder";
+      note.textContent = `Page not found: ${directory}/${slug}`;
+      main.appendChild(note);
+      clearSupportRail();
+    } else {
+      renderError(`Could not load page: ${err.message}`);
+    }
+  }
+}
+
+/**
+ * Append the server-sanitized HTML body to `main`. The server always
+ * returns sanitized markup in `payload.html` (see Slice 4 — `src/viewer/
+ * render.ts`), so the client only sets `innerHTML` on a wrapper. Empty
+ * `html` means the page had no body after the frontmatter block;
+ * surface a visible "no content" placeholder rather than rendering an
+ * empty pane.
+ */
+function appendRenderedBody(main, html) {
+  if (typeof html === "string" && html.length > 0) {
+    const body = document.createElement("div");
+    body.className = "rendered-body";
+    body.innerHTML = html;
+    main.appendChild(body);
+    return body;
+  }
+  const note = emptyBodyNote();
+  main.appendChild(note);
+  return note;
+}
+
+/** Drop a duplicated first Markdown H1 when it matches the viewer page title. */
+function removeDuplicateLeadingHeading(body, title) {
+  if (!body || !title) return;
+  const first = body.firstElementChild;
+  if (!first || first.tagName !== "H1") return;
+  if (first.textContent?.trim() !== title.trim()) return;
+  first.remove();
+}
+
+/** Render every payload warning as a banner above the page body. */
+function appendWarnings(main, warnings) {
+  for (const w of warnings) {
+    const banner = document.createElement("div");
+    banner.className = "warning-banner";
+    banner.textContent = w.message || w.code;
+    main.appendChild(banner);
+  }
+}
+
+/** Visible "no content" fallback for pages whose body is empty after frontmatter. */
+function emptyBodyNote() {
+  const note = document.createElement("p");
+  note.className = "placeholder";
+  note.textContent = "No rendered content.";
+  return note;
+}
+
+/** Render a top-of-main error banner without crashing the rest of the UI. */
+function renderError(message) {
+  const main = document.querySelector(MAIN_SELECTOR);
+  if (!main) return;
+  main.innerHTML = "";
+  const banner = document.createElement("div");
+  banner.className = "warning-banner";
+  banner.textContent = message;
+  main.appendChild(banner);
+  clearSupportRail();
+}
+
+/** Promise-returning fetch helper that surfaces non-2xx statuses as errors. */
+async function fetchJson(pathname) {
+  const res = await fetch(pathname, { credentials: "same-origin" });
+  if (!res.ok) {
+    const err = new Error(`HTTP ${res.status}`);
+    err.status = res.status;
+    throw err;
+  }
+  return res.json();
+}
+
+/** Bootstrap: first-paint from embedded blob, then full fetch + router. */
+function main() {
+  const embedded = readEmbeddedIndex();
+  renderSidebar(embedded.pages);
+  wireSearch({ fetchJson });
+  window.addEventListener("hashchange", () => {
+    void renderRoute();
+  });
+  void renderRoute();
+}
+
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", main, { once: true });
+} else {
+  main();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-wiki-compiler",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A knowledge compiler CLI — raw sources in, interlinked wiki out",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "dev:view": "node scripts/dev-viewer.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "fallow:ci": "bash scripts/fallow-ci.sh",
@@ -50,9 +51,11 @@
     "dotenv": "^17.4.0",
     "js-yaml": "^4.1.1",
     "jsdom": "^25.0.0",
+    "markdown-it": "^14.1.1",
     "openai": "^4.0.0",
     "p-limit": "^6.0.0",
     "pdf-parse": "^2.4.5",
+    "sanitize-html": "^2.17.3",
     "turndown": "^7.2.0",
     "youtube-transcript": "^1.3.1",
     "zod": "^3.25.76"
@@ -61,6 +64,8 @@
     "@copilotkit/aimock": "^1.15.1",
     "@types/js-yaml": "^4.0.9",
     "@types/jsdom": "^21.1.0",
+    "@types/markdown-it": "^14.1.2",
+    "@types/sanitize-html": "^2.16.1",
     "@types/turndown": "^5.0.0",
     "fallow": "2.42.0",
     "husky": "^9.1.7",