@5n7/clv 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +159 -0
  2. package/dist/cli.js +3847 -0
  3. package/dist/template.html +3708 -0
  4. package/package.json +69 -0
package/README.md ADDED
@@ -0,0 +1,159 @@
1
+ # clv
2
+
3
+ `clv` turns Markdown that Claude Code writes into a rich, live preview you can read in any browser. Claude embeds small JSON blocks (`` ```clv:<type> ``) in its review or explanation output; `clv` parses them, validates each against a schema, and renders them as callouts, annotated code, diffs, charts, dependency graphs, step-by-step walkthroughs, and more.
4
+
5
+ - **Live preview** — `clv review.md` opens the document in your browser and live-reloads it on every save, preserving scroll position.
6
+ - **Multi-file** — point `clv` at several files or a directory and navigate them from a sidebar (flat/tree view, filename/heading-title toggle, search) at one localhost address.
7
+ - **Background daemon** — re-running `clv` adds files to the already-running session instead of starting a new server; the open files are persisted and restored on restart.
8
+ - **Static export** — `clv --output out.html` writes a single self-contained HTML file (all JS, CSS, fonts, and images inlined; no network calls). Open it offline, email it, or commit it.
9
+ - **Graceful** — unknown or malformed blocks render as a clearly marked fallback instead of failing the whole document.
10
+
11
+ ## Usage
12
+
13
+ The npm package is published as `@5n7/clv`, but the command it installs is `clv`. Run it ad hoc with `bunx`, or install it globally for repeated use:
14
+
15
+ ```bash
16
+ # One-off, no install:
17
+ bunx @5n7/clv review.md
18
+
19
+ # Or install globally; the command is then `clv`:
20
+ bun add -g @5n7/clv
21
+ clv review.md
22
+ ```
23
+
24
+ The examples below use `bunx @5n7/clv`; if you have installed globally, drop the `bunx` and call `clv` directly.
25
+
26
+ ```bash
27
+ # Open a file in your browser with live reload
28
+ bunx @5n7/clv review.md
29
+
30
+ # Open every Markdown file in a directory (recurse with -R)
31
+ bunx @5n7/clv docs/
32
+ bunx @5n7/clv -R docs/
33
+
34
+ # Add more files to the already-running session
35
+ bunx @5n7/clv notes.md design.md
36
+
37
+ # Local development against this repo
38
+ bun run src/cli/index.ts review.md
39
+ ```
40
+
41
+ `clv <paths...>` starts (or reuses) a background live preview server on `localhost:7421` and opens your browser to it. The paths may be files or directories; `clv` watches them and live-reloads the browser whenever a file changes, preserving scroll position. When more than one file is open, a sidebar lets you navigate between them and the active file is reflected in the URL (`?file=<id>`).
42
+
43
+ The server runs as a detached daemon and outlives the command that launched it. Re-running `clv` with new paths registers them into the running session rather than spawning a second server, and the open files are persisted so they reappear if the daemon is restarted.
44
+
45
+ `--theme` and `--watch`/`--no-watch` are fixed when the daemon starts and apply for its whole lifetime. Re-running `clv` with different values only registers the new paths — it does not re-theme or toggle watching the running daemon (you'll get a notice when the value you pass is ignored). Run `clv shutdown` and start again to change them.
46
+
47
+ ```bash
48
+ # Inspect the running daemon (port, pid, file count)
49
+ bunx @5n7/clv status
50
+
51
+ # Stop the daemon
52
+ bunx @5n7/clv shutdown
53
+ ```
54
+
55
+ Run `clv doc` to print the full showcase document (all 14 block types) to stdout, or `clv doc <block>` (e.g. `clv doc callout`) to print a single block's schema and a worked example — handy for learning the block format or piping into a file. A file literally named `doc` is shadowed by the subcommand; use `./doc` or `clv doc.md` to preview such a file.
56
+
57
+ ### Static export
58
+
59
+ To produce a single self-contained HTML file instead of starting a server, pass `--output`. This converts the Markdown and writes the file without opening a browser:
60
+
61
+ ```bash
62
+ # Write one self-contained HTML file (no server, no browser)
63
+ bunx @5n7/clv review.md --output review.html
64
+
65
+ # Pipe Claude Code's output straight in
66
+ claude -p "review this PR" | bunx @5n7/clv --output review.html
67
+ ```
68
+
69
+ A piped document with no `--output` is rendered to a temporary file and opened directly, so the bare pipe still works as a one-shot view:
70
+
71
+ ```bash
72
+ # View a piped document once, without a server
73
+ claude -p "review this PR" | bunx @5n7/clv
74
+ ```
75
+
76
+ ### CLI options
77
+
78
+ | Flag | Default | Description |
79
+ | ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80
+ | `<paths...>` | stdin | Markdown files or directories to serve. Reads standard input when omitted. |
81
+ | `doc [block]` | — | Print clv format help to stdout and exit: no block = full showcase (all 14 types); `doc <block>` = one block's schema + example. Must be the first argument; shadows a file named `doc`. |
82
+ | `status` | — | Show the running clv daemon (port, pid, files) and exit. Must be the first argument; targets `--port` (default `7421`); shadows a file named `status`. |
83
+ | `shutdown` | — | Stop the running clv daemon and exit. Must be the first argument; targets `--port` (default `7421`); shadows a file named `shutdown`. |
84
+ | `--output <path>` | — | Static export: write HTML to `<path>` and exit (no server, no browser). |
85
+ | `--port <number>` | `7421` | Live preview server port. |
86
+ | `-w`, `--watch` | on | Watch files and live-reload. On by default; use `--no-watch` to disable. |
87
+ | `--no-watch` | — | Disable file watching / live-reload. |
88
+ | `-R`, `--recursive` | false | Recurse into subdirectories when a directory is given. |
89
+ | `--no-open` | false | Do not auto-launch the browser. |
90
+ | `--title <string>` | `"clv"` | HTML `<title>`. |
91
+ | `--theme <auto\|light\|dark>` | `auto` | Color scheme. `auto` follows `prefers-color-scheme`. |
92
+ | `--strict` | false | With `--output` (static export): exit 1 if any block fails validation (default: render fallback and continue). Ignored in live preview mode. |
93
+ | `-h`, `--help` | — | Print usage and exit. |
94
+ | `-v`, `--version` | — | Print version and exit. |
95
+
96
+ ## Block catalog
97
+
98
+ Each block is a fenced code block whose info string is `clv:<type>` with an optional attribute list, and whose body is a single JSON object:
99
+
100
+ ````markdown
101
+ ```clv:callout title="N+1 detected"
102
+ { "kind": "warning", "body": "ListOrders issues one query per row." }
103
+ ```
104
+ ````
105
+
106
+ Header attributes (`title="…"` etc.) are merged into the payload; on conflict the JSON body wins. The body must be plain JSON — no comments, no trailing commas. Every block also accepts the optional fields `title`, `collapsed`, and `id`. For Mermaid you may use a bare `` ```mermaid `` fence instead of `clv:mermaid`; the whole body is the diagram source.
107
+
108
+ | Type | What it renders |
109
+ | --------------- | -------------------------------------------------------------------------------------------------------- |
110
+ | `clv:callout` | Colored alert (info / tip / warning / danger / critical) with a Markdown body. |
111
+ | `clv:chart` | Bar, line, area, pie, or scatter chart over tabular data. |
112
+ | `clv:checklist` | Quality-gate list with pass / fail / na / skip status and a tally bar. |
113
+ | `clv:code` | Syntax-highlighted code with per-line severity annotations and highlighted lines. |
114
+ | `clv:diff` | Before/after code diff (split or unified). |
115
+ | `clv:findings` | Review findings grouped by severity; each can link to a `clv:code` block. |
116
+ | `clv:graph` | Node/edge diagram (dependency graph, call graph) with dagre layout. |
117
+ | `clv:metrics` | Grid of KPI cards with deltas and up / down / neutral trends. |
118
+ | `clv:mermaid` | Mermaid diagram. |
119
+ | `clv:steps` | Step player with Prev/Next, keyboard nav, and dots; each step is Markdown plus an optional nested block. |
120
+ | `clv:table` | Sortable data table; columns can be syntax-highlighted. |
121
+ | `clv:tabs` | Tabbed panels; each tab is Markdown or a nested block. |
122
+ | `clv:timeline` | Numbered vertical rail of phases/events, each with a severity. |
123
+ | `clv:tree` | Changed-file tree with per-file status badges and optional anchors. |
124
+
125
+ See [`examples/review.md`](examples/review.md) for a document that exercises all 14 types plus a deliberate unknown-block fallback. Copy [`docs/output-style-clv.md`](docs/output-style-clv.md) into `CLAUDE.md` or `~/.claude/output-styles/` so Claude emits valid blocks; that file has the full schema for each type.
126
+
127
+ ## Self-contained output
128
+
129
+ `--output` produces a single HTML file that embeds bundled JS, CSS, WOFF2 fonts (IBM Plex Sans/Serif, JetBrains Mono), and the document JSON (`window.__CLV_DATA__`). It makes no network requests at runtime. The live preview server serves the same React viewer, but fetches documents over an HTTP API and pushes updates over a WebSocket so the page reloads as you edit.
130
+
131
+ Design tokens use CSS `oklch()` and `color-mix()`. You need a recent browser (Chrome/Edge 111+, Safari 16.4+, Firefox 113+). Older browsers render but colors may degrade.
132
+
133
+ ## Implementation notes
134
+
135
+ - **Graph:** uses [`@xyflow/react`](https://reactflow.dev) v12 with `@dagrejs/dagre` layout. `layout: "force"` falls back to dagre; `layout: "manual"` uses per-node `x`/`y` only when every node provides them, otherwise dagre.
136
+ - **Markdown:** prose fields are rendered with `react-markdown` in the browser.
137
+
138
+ ## Known limitations
139
+
140
+ When a finding's context link targets a `clv:code` block nested inside `clv:tabs` or `clv:steps`, only the active tab or current step is mounted, so the hash jump may be a no-op until the user opens that tab or step. The inline snippet shown when a finding is expanded is unaffected.
141
+
142
+ ## Build from source
143
+
144
+ Requires [Bun](https://bun.sh).
145
+
146
+ ```bash
147
+ bun install
148
+ bun run build # web SPA (dist/template.html), then CLI bundle (dist/cli.js)
149
+ ```
150
+
151
+ `build:web` runs Vite with `vite-plugin-singlefile`; `build:cli` bundles `src/cli/index.ts` and text-imports the template so the CLI has no runtime file dependency. The published package ships `dist/` only.
152
+
153
+ For UI work without the CLI:
154
+
155
+ ```bash
156
+ bun run dev:web # Vite dev server; sample document in dev-data.ts
157
+ ```
158
+
159
+ Other scripts: `bun run fmt`, `bun run fmt:check`, `bunx oxlint`.