Feature request: OKF bundle viewer (static render + local live server)

[jchable]

Motivation

Today, exploring an OKF bundle means reading raw markdown files or using okf graph --dot | dot -Tsvg for the link graph. There's no way to browse a bundle interactively: see concept frontmatter, follow links between concepts, or search full-text without piping through the CLI verbs one at a time. A viewer would make bundles approachable to people who aren't already comfortable with the CLI — useful for onboarding, demos, and day-to-day authoring.

What it should do

• Static rendering: generate a browsable HTML site from a bundle — one page per concept (frontmatter + rendered markdown body), an index page (reusing OKF4net.IndexGenerator), inter-concept links rewired to the generated pages, and client-side full-text search over an index derived from ConceptSearch.
• Local live server: the same rendering, served on the fly instead of written to disk — useful while actively editing a bundle, no manual regeneration step.

Both modes are read-only and localhost-only (no auth/remote-access story needed). Markdown rendering doesn't need to cover full CommonMark — just what OKF bundle bodies actually use (headings, lists, bold/italic, links, code blocks).

Reuses existing building blocks — OKF4net.IndexGenerator, LinkScanner, ConceptSearch, Bundle — no bundle-parsing logic should be duplicated.

Implementation approach — open to discussion

This repo has a hard zero-third-party-dependency rule for the core library and CLI (see CLAUDE.md), with one documented exception (OKF4net.Mcp, which depends on Microsoft.Extensions.Hosting/ModelContextProtocol because it's a leaf tool, not a published library). A viewer needs to pick a lane; three options, roughly in order of "fits current architecture" to "most capable/least effort":

1. Zero-dependency (System.Net.HttpListener) — a new src/OKF4net.Viewer/ project, BCL-only, referencing only OKF4net (same pattern as OKF4net.Catalog). New CLI verbs (e.g. okf render <bundle> --out <dir>, okf serve <bundle> [--port]) delegate to it. Stays fully consistent with the project's dependency policy, at the cost of hand-rolling the HTTP plumbing.
2. ASP.NET Core — same shape, but the server itself uses ASP.NET Core, following the precedent already set for OKF4net.Mcp. Better serving ergonomics (routing, static file middleware, etc.), but it's a new exception to the zero-dependency rule that would need documenting in CLAUDE.md if chosen, and arguably a bigger one than MCP's (this would be reachable from the main CLI, not a separate leaf tool).
3. Standalone web tool (npm/front-end) — a separate front-end project (under web/ or a new samples//tools/ directory) that consumes a bundle via static files or a small JSON endpoint, entirely outside the .NET library/CLI. Zero impact on the core dependency graph, but it's a second toolchain (Node/npm) to maintain and doesn't ship as part of the okf binary.

Markdown-to-HTML rendering in the browser is expected to use a small vendored client-side JS library regardless of which server approach is picked (not a NuGet dependency) — writing a full CommonMark parser server-side isn't the goal here.

Out of scope

• Authentication / remote access — localhost-only.
• Editing bundles through the viewer — read-only.
• Full CommonMark conformance in the rendered output.

Files likely touched

Depends on the approach chosen above; at minimum README.md and CHANGELOG.md for the new capability, plus new project(s) under src/ and/or web//samples/.

[jchable]

Half of this shipped: the static-render slice landed on dev in #48 as okf render <bundle> --out <dir>. Leaving this issue open — the live-server half is still outstanding, and it is the more interesting half.

What ships now

A new zero-dependency src/OKF4net.Viewer/ project (SiteModel → HtmlWriter → ViewerAssets) backing a new CLI verb. One page per concept (frontmatter table in document order + rendered body), a generated index reusing IndexGenerator, inter-concept links rewired with broken links flagged, and backlinks. Markdown renders client-side via a vendored marked v15.0.12 (MIT).

The generated site is self-contained and opens straight from the filesystem — no server, no build step.

Two decisions worth knowing before picking up the rest

Search was deliberately left out of this slice. A static site has no server to run ConceptSearch, and reimplementing its scoring weights in JavaScript would fork the single shared scorer the project keeps in one place on purpose. This is the main thing the live server unlocks: with a server in the loop, ConceptSearch runs where it already lives, with no duplication.

OKF4net.Viewer is not published to NuGet. It ships inside the okf binary. The live-server work is expected to reshape ViewerSite/ViewerPage (a server can stream, and will likely need to carry a search index), so publishing now would freeze a SemVer contract that is about to move. Worth revisiting once the model settles.

Implementation notes that carry over

The client-side rendering path is where the sharp edges were, and they apply to the live server too since it will serve the same pages:

• marked does not sanitize (its sanitize option was removed) and Renderer.image() interpolates the alt attribute with no escaping at all, so ![foo" onerror="alert(1)](x.png) breaks out of the attribute with no raw-HTML token involved. Patching renderer hooks cannot bound that class of bug; the defence is a DOM sanitizer applied before insertion.
• xunit cannot execute JavaScript, so the sanitizer's real guard is tools/viewer-security-check/ (Node/jsdom, against the genuinely vendored files), run in CI as the viewer sanitizer (JS) job. Source-text assertions in the C# suite are smoke checks only.

Still open here

The local live server: same rendering, served on the fly instead of written to disk, plus the full-text search that becomes possible with it. The implementation approach named in the original description — zero-dep HttpListener, ASP.NET Core, or a standalone web tool — is still open and undecided; the static slice deliberately avoided settling it, since it needed no HTTP stack at all.

[jchable]

Closing: the static-render half shipped, the live-server half is dropped.

What shipped

okf render landed, then moved to its own binary: okf-render <bundle> --out <dir> (src/OKF4net.Render over src/OKF4net.Viewer), split out of okf so the CI-facing validator does not carry the viewer's vendored JavaScript — measured at +164 KiB on the AOT binary that every okf validate run paid for and never executed.

One page per concept (frontmatter table in document order + rendered body), a generated index reusing IndexGenerator, inter-concept links rewired with broken ones flagged, backlinks, and a site that opens straight off the filesystem with no server. It ships for Windows, Linux and macOS, with a winget package (Coderise.OKF4net.Render) and a curl | sh installer.

Why the live server is dropped rather than deferred

Working through what it would actually buy: one saved command invocation per edit. With okf-render you re-run the command and refresh; with a server you refresh. That is a real difference, but a thin one — a file-watcher loop re-running okf-render gets most of it for a fraction of the cost.

Search was the only capability that genuinely required a process in the loop. A static site has nowhere to run the shared ConceptSearch scorer, and mirroring its weights in JavaScript would fork the one implementation this project deliberately keeps single-copy.

And that requirement is satisfied by something already on the roadmap: a VS Code extension viewer. An extension host is a process, so it can call the .NET side for search instead of duplicating the scorer — and it delivers the always-fresh, interactive browsing this issue wanted, from inside the editor, without a local HTTP server, a port, or a dependency decision (HttpListener vs ASP.NET Core vs a separate web tool) that this issue left open and that the static slice was careful never to preempt.

The roadmap entry for that extension is detailed, including which parts of OKF4net.Viewer transfer: Assets/viewer.js is a self-contained IIFE that a webview can run as-is — which matters, because the DOM sanitizer in it is the security-critical part and took several rounds to get right, so reusing it beats writing a second renderer. HtmlWriter/HtmlSafeJson do not transfer: output layout and write-containment are static-site concerns, and a webview receives its payload by postMessage rather than escaped into an HTML <script> element.

Documentation

ROADMAP.md, README.md, CHANGELOG.md and CLAUDE.md all promised a "planned okf serve". Corrected in #83 — there is no okf serve and none is planned.

Reopen if a use case turns up that the editor extension genuinely cannot serve.