llm-wiki-compiler 0.8.0 → 0.9.0

package/dist/viewer/assets/viewer-rail.js

@@ -7,6 +7,16 @@
  * timestamps, plus a "Warnings" block fed by `payload.warnings`
  * (parser issues, unresolved citations, malformed citation entries).
  *
+ * Freshness badges (STALE, ORPHANED, CONTRADICTED, ARCHIVED) are
+ * rendered from `payload.freshness`. The design rule: badge ONLY the
+ * two actionable source-freshness states (stale, orphaned) plus the
+ * two provenance flags (contradicted, archived). `fresh` and
+ * `unverified` get NO badge — badging neutral/default states would
+ * stamp nearly the whole wiki. A "Freshness as of <generatedAt>"
+ * caption is shown on every page (keyed on the always-present
+ * `generatedAt`), anchoring the displayed freshness to snapshot/server-
+ * start time because the viewer does not live-watch the filesystem.
+ *
  * Fields render only when the frontmatter actually carries a value, so
  * a legacy page with no provenance metadata shows a compact rail
  * rather than a wall of `(none)` rows. Labels mirror `review show`
@@ -58,9 +68,11 @@ export function renderSupportRail(payload) {
   const support = document.querySelector(SUPPORT_SELECTOR);
   if (!support) return;
   support.innerHTML = "";
+  appendFreshnessBadges(support, payload);
   appendFrontmatterDl(support, extractFrontmatter(payload));
   const warnings = extractWarnings(payload);
   if (warnings.length > 0) support.appendChild(buildRailWarnings(warnings));
+  appendFreshnessCaption(support, payload);
 }
 
 /** Clear the support rail entirely (used on non-page routes). */
@@ -255,3 +267,62 @@ function buildWarningItem(warning) {
 function warningText(safe) {
   return safe.message || safe.code || "";
 }
+
+/**
+ * Badge specs: each entry is [modifier, label, predicate(freshness)].
+ * Only entries whose predicate is truthy produce a badge. Ordered by
+ * axis: source-freshness first (stale, orphaned), then provenance
+ * (contradicted, archived).
+ */
+const BADGE_SPECS = [
+  ["stale",       "STALE",       (f) => f.freshnessStatus === "stale"],
+  ["orphaned",    "ORPHANED",    (f) => f.freshnessStatus === "orphaned"],
+  ["contradicted","CONTRADICTED",(f) => f.contradicted],
+  ["archived",    "ARCHIVED",    (f) => f.archived],
+];
+
+/**
+ * Append freshness badges to the rail. Badges render ONLY for actionable
+ * states: STALE, ORPHANED (source-freshness axis) and CONTRADICTED,
+ * ARCHIVED (provenance axis). `fresh` and `unverified` get no badge —
+ * they are the neutral defaults and badging them would stamp nearly the
+ * whole wiki with noise.
+ */
+function appendFreshnessBadges(support, payload) {
+  const freshness = payload?.freshness;
+  if (!freshness) return;
+  const wrap = buildFreshnessBadgeWrap(freshness);
+  if (wrap) support.appendChild(wrap);
+}
+
+/** Build the badges container from the freshness object, or null if no badges apply. */
+function buildFreshnessBadgeWrap(freshness) {
+  const activeBadges = BADGE_SPECS.filter(([, , pred]) => pred(freshness));
+  if (activeBadges.length === 0) return null;
+  const wrap = document.createElement("div");
+  wrap.className = "freshness-badges";
+  for (const [modifier, label] of activeBadges) wrap.appendChild(buildBadge(modifier, label));
+  return wrap;
+}
+
+/** Build one badge `<span>` with a modifier class and text label. */
+function buildBadge(modifier, label) {
+  const span = document.createElement("span");
+  span.className = `freshness-badge badge-${modifier}`;
+  span.textContent = label;
+  return span;
+}
+
+/**
+ * Append the "Freshness as of <generatedAt>" caption when the payload
+ * carries a generatedAt timestamp. Explicitly honest: the viewer
+ * does not live-watch the filesystem, so this caption anchors the
+ * freshness data to the server-start time rather than implying live state.
+ */
+function appendFreshnessCaption(support, payload) {
+  if (!payload?.generatedAt) return;
+  const caption = document.createElement("p");
+  caption.className = "freshness-caption";
+  caption.textContent = `Freshness as of ${payload.generatedAt}`;
+  support.appendChild(caption);
+}

package/dist/viewer/assets/viewer-sidebar.js

@@ -11,12 +11,37 @@
  * includes `kind` so the grouping is correct from the first byte);
  * the full `/api/pages` envelope replaces the contents once it
  * arrives.
+ *
+ * A per-axis freshness filter (all / stale / orphaned / contradicted /
+ * archived) narrows the page list client-side over the already-loaded
+ * `/api/pages` rows. No new endpoint is needed — the filter is pure
+ * DOM manipulation over the in-memory page list.
  */
 
 const SIDEBAR_SELECTOR = "[data-sidebar]";
 const DEFAULT_KIND = "concept";
 const EMPTY_PLACEHOLDER_TEXT = "No pages yet — run `llmwiki compile`.";
 
+/**
+ * CSS class on the standing "Project" section. Shared between
+ * `buildProjectSection` (which sets it) and `reRenderSidebarGroups`
+ * (whose keep-selector preserves it across filter re-renders) so a
+ * rename can't silently break the re-render keep-list.
+ */
+const PROJECT_SECTION_CLASS = "sidebar-health";
+
+/** The active freshness filter. "all" means no narrowing. */
+let activeFreshnessFilter = "all";
+
+/** Available filter values and their human labels. */
+const FRESHNESS_FILTER_OPTIONS = [
+  { value: "all", label: "All" },
+  { value: "stale", label: "Stale" },
+  { value: "orphaned", label: "Orphaned" },
+  { value: "contradicted", label: "Contradicted" },
+  { value: "archived", label: "Archived" },
+];
+
 /**
  * Static (non-page) hash routes that have a dedicated sidebar link.
  * `markActive` highlights the entry via `a[data-route="<route>"]`
@@ -27,18 +52,43 @@ const STATIC_ROUTE_LINK_SELECTORS = new Map([
   ["#/health", 'a[data-route="health"]'],
 ]);
 
+/** Full page list captured at the last renderSidebar call for filter re-renders. */
+let lastPages = [];
+
 /** Render the sidebar groups + standing Health entry, then mark active. */
 export function renderSidebar(pages) {
+  lastPages = pages;
   const sidebar = document.querySelector(SIDEBAR_SELECTOR);
   if (!sidebar) return;
   sidebar.innerHTML = "";
   sidebar.appendChild(buildProjectSection());
-  const concepts = filterByDirectory(pages, "concepts");
-  const queries = filterByDirectory(pages, "queries");
+  sidebar.appendChild(buildFreshnessFilter());
+  renderFilteredGroups(sidebar, pages);
+  markActive();
+}
+
+/** Re-render only the page groups using the stored lastPages + active filter. */
+function reRenderSidebarGroups() {
+  const sidebar = document.querySelector(SIDEBAR_SELECTOR);
+  if (!sidebar) return;
+  // Remove everything after the project section and filter control.
+  const keep = sidebar.querySelectorAll(`section.${PROJECT_SECTION_CLASS}, .freshness-filter`);
+  const keepSet = new Set(Array.from(keep));
+  Array.from(sidebar.children).forEach((child) => {
+    if (!keepSet.has(child)) child.remove();
+  });
+  renderFilteredGroups(sidebar, lastPages);
+  markActive();
+}
+
+/** Append the filtered concept/query groups and the empty placeholder if needed. */
+function renderFilteredGroups(sidebar, pages) {
+  const filtered = applyFreshnessFilter(pages, activeFreshnessFilter);
+  const concepts = filterByDirectory(filtered, "concepts");
+  const queries = filterByDirectory(filtered, "queries");
   appendConceptGroups(sidebar, concepts);
   appendQueryGroup(sidebar, queries);
   appendEmptyPlaceholderIfNeeded(sidebar, concepts, queries);
-  markActive();
 }
 
 /** Filter pages to those whose `pageDirectory` matches the given bucket. */
@@ -180,7 +230,7 @@ function buildPageListItem(page) {
 /** Build the standing "Project" sidebar section with Health and Graph links. */
 function buildProjectSection() {
   const wrap = document.createElement("section");
-  wrap.className = "sidebar-health";
+  wrap.className = PROJECT_SECTION_CLASS;
   const heading = document.createElement("h2");
   heading.textContent = "Project";
   wrap.appendChild(heading);
@@ -219,3 +269,64 @@ function parseExpectedPageId(hash) {
   }
   return `${match[1]}/${slug}`;
 }
+
+/**
+ * Build the freshness-filter `<div>` with a `<select>` control. The
+ * filter is client-side over the already-loaded page rows — no new
+ * endpoint, no query params.
+ */
+function buildFreshnessFilter() {
+  const wrap = document.createElement("div");
+  wrap.className = "freshness-filter";
+  const label = document.createElement("label");
+  label.className = "freshness-filter-label";
+  label.setAttribute("for", "freshness-filter-select");
+  label.textContent = "Filter by freshness";
+  const select = document.createElement("select");
+  select.id = "freshness-filter-select";
+  select.className = "freshness-filter-select";
+  for (const { value, label: optLabel } of FRESHNESS_FILTER_OPTIONS) {
+    const option = document.createElement("option");
+    option.value = value;
+    option.textContent = optLabel;
+    if (value === activeFreshnessFilter) option.selected = true;
+    select.appendChild(option);
+  }
+  select.addEventListener("change", onFreshnessFilterChange);
+  wrap.appendChild(label);
+  wrap.appendChild(select);
+  return wrap;
+}
+
+/** Handle freshness filter selection change — update state and re-render. */
+function onFreshnessFilterChange(event) {
+  activeFreshnessFilter = event.target.value;
+  reRenderSidebarGroups();
+}
+
+/**
+ * Lookup table: filter value → predicate over a freshness object.
+ * Keeps `matchesFreshnessFilter` branch-free.
+ */
+const FRESHNESS_PREDICATES = {
+  stale:       (f) => f.freshnessStatus === "stale",
+  orphaned:    (f) => f.freshnessStatus === "orphaned",
+  contradicted:(f) => f.contradicted === true,
+  archived:    (f) => f.archived === true,
+};
+
+/**
+ * Apply the active freshness filter to the page list. "all" returns all
+ * pages; other values match the corresponding freshness flag on each page.
+ */
+function applyFreshnessFilter(pages, filter) {
+  if (filter === "all") return pages;
+  return pages.filter((page) => matchesFreshnessFilter(page, filter));
+}
+
+/** True when the page's freshness satisfies the active filter. */
+function matchesFreshnessFilter(page, filter) {
+  const f = page.freshness;
+  const predicate = FRESHNESS_PREDICATES[filter];
+  return f != null && predicate != null && predicate(f);
+}

package/dist/viewer/assets/viewer.css

@@ -314,6 +314,75 @@ a:hover, a:focus-visible { text-decoration: underline; }
   }
 }
 
+/* Freshness badges — shown in the support rail for STALE, ORPHANED,
+ * CONTRADICTED, ARCHIVED pages. fresh/unverified get no badge. */
+.freshness-badges {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.35rem;
+  margin-bottom: 0.6rem;
+}
+.freshness-badge {
+  display: inline-block;
+  padding: 0.15rem 0.45rem;
+  border-radius: 999px;
+  font-size: 0.72rem;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+.badge-stale    { background: rgba(200, 90, 0, 0.12); color: #b85c00; }
+.badge-orphaned { background: rgba(176, 0, 32, 0.10); color: var(--missing); }
+.badge-contradicted { background: rgba(100, 0, 180, 0.10); color: #6400b4; }
+.badge-archived { background: rgba(100, 100, 110, 0.12); color: var(--fg-muted); }
+@media (prefers-color-scheme: dark) {
+  .badge-stale    { background: rgba(255, 160, 60, 0.14); color: #ffa03c; }
+  .badge-contradicted { background: rgba(180, 100, 255, 0.14); color: #b464ff; }
+}
+
+/* Freshness caption — "Freshness as of <timestamp>" — always shown
+ * when freshness data is present to be honest about the frozen snapshot. */
+.freshness-caption {
+  font-size: 0.76rem;
+  color: var(--fg-muted);
+  margin-top: 0.75rem;
+  font-style: italic;
+}
+
+/* Corrupt-state banner — shown globally (and in the health pane) when stateStatus === "corrupt". */
+.corrupt-state-banner {
+  background: rgba(176, 0, 32, 0.08);
+  color: var(--missing);
+  border: 1px solid rgba(176, 0, 32, 0.2);
+  padding: 0.6rem 0.85rem;
+  border-radius: 6px;
+  margin-bottom: 1rem;
+  font-weight: 500;
+}
+
+/* Freshness filter — sidebar select control for filtering by freshness axis. */
+.freshness-filter {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  margin: 0.5rem 0 0.75rem;
+}
+.freshness-filter-label {
+  font-size: 0.72rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--fg-muted);
+}
+.freshness-filter-select {
+  width: 100%;
+  padding: 0.3rem 0.5rem;
+  background: var(--bg);
+  color: var(--fg);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  font-size: 0.9rem;
+}
+
 /* Graph pane */
 .graph-pane {
   width: 100%;

package/dist/viewer/assets/viewer.js

@@ -57,6 +57,8 @@ const HEALTH_METRIC_ROWS = [
   ["Saved queries", "queries"],
   ["Compiled sources", "sources"],
   ["Source files", "sourceFiles"],
+  ["Stale pages", "stale"],
+  ["Orphaned pages", "orphaned"],
   ["Pending reviews", "pendingReviews"],
 ];
 
@@ -268,6 +270,10 @@ async function renderHealthPane(main) {
 function buildHealthDashboard(health) {
   const wrap = document.createElement("section");
   wrap.className = "health-dashboard";
+  // The global banner (injected at bootstrap) covers every route including health;
+  // only add it here if bootstrap didn't already inject one (e.g. if /api/pages
+  // was not yet fetched when navigating directly to #/health).
+  prependBannerIfNeeded(wrap, health?.stateStatus);
   const rows = HEALTH_METRIC_ROWS.map(([label, key]) => [label, health?.[key] ?? 0]);
   const metrics = buildDefinitionList(rows);
   metrics.className = "metric-list";
@@ -276,6 +282,27 @@ function buildHealthDashboard(health) {
   return wrap;
 }
 
+/** Prepend a corrupt-state banner to `container` if one is not already in the document. */
+function prependBannerIfNeeded(container, stateStatus) {
+  if (stateStatus !== "corrupt") return;
+  if (document.querySelector(".corrupt-state-banner")) return;
+  container.prepend(buildCorruptStateBanner());
+}
+
+/**
+ * Build the corrupt-state warning banner. Displayed when `/api/health`
+ * reports `stateStatus === "corrupt"`, meaning the project's state.json
+ * could not be parsed at viewer startup and freshness data is unreliable.
+ */
+function buildCorruptStateBanner() {
+  const banner = document.createElement("div");
+  banner.className = "corrupt-state-banner";
+  banner.setAttribute("role", "alert");
+  banner.textContent =
+    "Warning: state.json is corrupt. Freshness data is unavailable. Re-run `llmwiki compile` to restore.";
+  return banner;
+}
+
 /** Render the lint summary, or a "lint has not been run yet" placeholder. */
 function buildLintBlock(lint) {
   const wrap = document.createElement("section");
@@ -305,6 +332,21 @@ function applyHomeEnvelope(envelope) {
   titleEl.textContent = projectTitle(envelope);
   renderSidebar(envelope?.pages || []);
   renderHome(envelope);
+  // Inject into .app-layout (outside <main>) so the banner persists across route changes.
+  injectGlobalCorruptBanner(envelope?.stateStatus);
+}
+
+/**
+ * Inject the corrupt-state banner into the app-layout container (above `main`)
+ * so it persists across route changes. Runs once at app bootstrap from the
+ * /api/pages envelope. No-ops when not corrupt or already injected.
+ */
+function injectGlobalCorruptBanner(stateStatus) {
+  if (stateStatus !== "corrupt") return;
+  if (document.querySelector(".corrupt-state-banner")) return;
+  const layout = document.querySelector(".app-layout");
+  if (!layout) return;
+  layout.prepend(buildCorruptStateBanner());
 }
 
 /** Fetch /api/index and render the rendered HTML coming back from the server. */
@@ -467,6 +509,12 @@ function main() {
   const embedded = readEmbeddedIndex();
   renderSidebar(embedded.pages);
   wireSearch({ fetchJson });
+  // Ensure the corrupt-state banner appears on every entry route, not just home.
+  // injectGlobalCorruptBanner is idempotent, so the home route's own /api/pages
+  // fetch won't double-render if both settle.
+  void fetchJson("/api/pages")
+    .then((env) => injectGlobalCorruptBanner(env?.stateStatus))
+    .catch(() => {});
   window.addEventListener("hashchange", () => {
     void renderRoute();
   });

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "llm-wiki-compiler",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "A knowledge compiler CLI — raw sources in, interlinked wiki out",
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "llmwiki": "dist/cli.js"
   },
@@ -16,7 +25,8 @@
     "test:watch": "vitest",
     "fallow:ci": "bash scripts/fallow-ci.sh",
     "prepublishOnly": "npm run release:check-docs:current && npm run build && npm pack --dry-run --ignore-scripts",
-    "prepare": "husky"
+    "prepare": "husky",
+    "test:pack": "vitest run --config /dev/null test/sdk/packaging.test.ts"
   },
   "keywords": [
     "knowledge",
@@ -46,7 +56,8 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.39.0",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.163",
+    "@anthropic-ai/sdk": "^0.101.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@mozilla/readability": "^0.5.0",
     "chokidar": "^4.0.0",
@@ -55,13 +66,13 @@
     "js-yaml": "^4.1.1",
     "jsdom": "^25.0.0",
     "markdown-it": "^14.1.1",
-    "openai": "^4.0.0",
+    "openai": "^6.42.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"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@copilotkit/aimock": "^1.15.1",