projview 0.8.2 → 1.0.0

package/README.md

@@ -1,8 +1,11 @@
 # projview
 
-ephemeral local previewer for **markdown** + **mermaid** files. run it in any
-directory, get a soft-dark cartoonish localhost view of every `.md` / `.mmd`
-under it, close it and nothing's left behind.
+a fast, zero-config local viewer for **markdown** + **mermaid** files. run it in
+any directory, get a soft-dark cartoonish localhost view of every `.md` / `.mmd`
+under it - rendered diagrams, search, live reload - close it and nothing's left
+behind.
+
+that's the product. point it at a docs folder, read comfortably, ctrl-c, gone.
 
 ## install
 
@@ -26,10 +29,28 @@ projview ./docs --port 5000
 projview /path/to/notes --no-open
 ```
 
-## use it from scripts or an AI
+## what you get
+
+| | |
+| --- | --- |
+| tree nav | every `.md` / `.mmd` under the root (skips `node_modules`, `dist`, dot-dirs) |
+| rendering | markdown + syntax-highlighted code + **mermaid diagrams** (with pan/zoom) |
+| search | `⌘K` palette - fuzzy filenames + full-text content with line snippets |
+| live reload | edit a file, the browser updates |
+| ephemeral | in-memory by default; nothing written to disk, nothing left behind |
+
+see [samples/architecture.md](samples/architecture.md) for a mermaid demo.
+
+---
+
+## beyond viewing (optional)
+
+the viewer is the point - everything below is opt-in and entirely ignorable.
 
-projview also has a **machine interface** - subcommands that print JSON to stdout
-and exit (no server, no browser), so an agent or script can query your docs:
+### machine interface
+
+subcommands that print JSON to stdout and exit (no server, no browser), if a
+script or agent wants to query the same docs:
 
 ```bash
 projview search "<query>" [path]   # ranked: filename matches + in-content hits w/ line snippets
@@ -37,7 +58,6 @@ projview tree [path]               # the file tree as JSON
 projview comment add <file> "…"    # leave a comment (--heading <id> to anchor a section)
 projview comments [file]           # list comments as JSON
 projview usage [path]              # views + searches recorded by the viewer
-projview search "mermaid" --demo   # quick test on the bundled docs
 ```
 
 ```jsonc
@@ -48,31 +68,18 @@ projview search "mermaid" --demo   # quick test on the bundled docs
                  "snippets": [ { "line": 68, "text": "### live reload" } ] } ] }
 ```
 
-## what it does
-
-| step | detail |
-| --- | --- |
-| walk | recursively finds `.md` / `.mmd`, skips `node_modules`, `dist`, dot-dirs |
-| index | builds an in-memory tree (nothing written to disk by default) |
-| serve | spawns a localhost site + opens your browser |
-| live | edits to files reload in the browser automatically |
-| comment | leave notes on a file, a section, or a text selection (browser or CLI) |
-
-> ephemeral by default - ctrl-c and it's gone. opt into persistence below.
+### comments
 
-## comments
+notes on a whole file, a heading, or a selected passage - from the viewer (the
+💬 button) or the CLI / HTTP API. text comments **re-anchor** as the doc changes
+and flag themselves *orphaned* only if the quoted text truly disappears. they
+need a persistent store to survive a restart; writes are **localhost-only** (an
+exposed instance is read-only).
 
-Leave notes on a whole file, a heading/section, or a selected passage - from the
-viewer (the 💬 button, bottom-right) or via the CLI / HTTP API. Text comments
-**re-anchor** as the doc changes and only flag themselves *orphaned* if the quoted
-text truly disappears. Comments persist when you opt into a store
-(`--persist` / `--store-url`); writes are **localhost-only** (an exposed instance
-is read-only).
+### persistence
 
-## persistence (opt-in)
-
-By default the index is in-memory and nothing is written to disk. Opt in for a
-faster warm start, or a queryable store an AI can read:
+by default the index is in-memory. opt in for a faster warm start, persistent
+comments, or a queryable store:
 
 ```bash
 projview docs --persist                                # sqlite cache in ~/.projview/cache
@@ -87,7 +94,5 @@ projview docs --store-url "$DATABASE_URL"              # your own postgres (need
 | `superlite` (JSON) | `--store superlite --persist` |
 | `custom` (sqlite/postgres URL) | `--store-url <url>` (or `DATABASE_URL`) |
 
-On re-run it reloads the cache and only re-reads files whose mtime changed.
-Connection strings come from env/`~/.projview` - never commit credentials.
-
-see [samples/architecture.md](samples/architecture.md) for a mermaid demo.
+on re-run it reloads the cache and only re-reads files whose mtime changed.
+connection strings come from env/`~/.projview` - never commit credentials.

package/docs/ai-tests/comments.md

@@ -0,0 +1,118 @@
+# comments - AI test
+
+An AI-driven test of projview's **comment machine interface** (`projview comment
+add` / `comments` / `comment resolve|rm`, JSON on stdout). The scenario: an agent
+reviews a doc set, leaves anchored review notes, and a second reader pulls them
+back - no browser involved.
+
+## experimental parameters
+
+| parameter | value |
+| --- | --- |
+| tool | `projview` (global install) |
+| version | `0.8.2` |
+| commands | `comment add`, `comments`, `comment resolve`, `comment rm`, `usage` |
+| dataset | the bundled demo docs (`--demo`) |
+| store | a persistent sqlite file (`--store-url sqlite://…`) - comments need a store |
+| output | JSON per comment: `{ id, file, anchor, body, author, createdAt, resolved }` |
+
+> Comments ride a **persistent store**. With the default ephemeral store the
+> agent is warned the note won't survive exit, so pass `--persist` or
+> `--store-url`.
+
+## method
+
+An agent leaves review notes targeting different anchor types, then the notes are
+listed, one resolved, and one deleted:
+
+| # | file | anchor | aspect under test |
+| --- | --- | --- | --- |
+| 1 | `README.md` | file | whole-file note + agent self-tag (`--author claude`) |
+| 2 | `getting-started.md` | heading | section anchor to a stable `pv-` heading id |
+| 3 | lifecycle | — | list → resolve → delete over the CLI |
+
+## results
+
+### 1. leave an anchored, agent-tagged comment
+
+```bash
+DB="sqlite:///tmp/review.sqlite"
+projview comment add README.md "clear intro - add a 'what it is NOT' line" \
+  --author claude --store-url "$DB" --demo
+```
+
+```jsonc
+{ "id": "be15fdb7-…", "file": "README.md",
+  "anchor": { "type": "file" },
+  "body": "clear intro - add a 'what it is NOT' line",
+  "author": "claude", "resolved": false }
+```
+
+✅ The agent self-tags via `--author claude`, so AI notes are distinguishable
+from human ones. Without `--author`, the author defaults to the git/OS user.
+
+### 2. anchor to a section (heading)
+
+```bash
+projview comment add getting-started.md "could link forward to the api reference" \
+  --heading pv-headings-h1-h6 --author claude --store-url "$DB" --demo
+```
+
+`anchor` becomes `{ "type": "heading", "id": "pv-headings-h1-h6" }`. Heading ids
+are the `pv-`-prefixed slugs projview renders, so a section note survives edits to
+the section body.
+
+✅ Three anchor flavours exist: `file`, `heading`, and `text` (a quote selector,
+created from the viewer - it re-anchors on edits and flags itself *orphaned* only
+if the quoted text truly disappears).
+
+### 3. read them back
+
+```bash
+projview comments --store-url "$DB" --demo            # all comments, as a JSON array
+projview comments README.md --store-url "$DB" --demo  # filtered to one file
+```
+
+An agent can diff, summarise, or act on the returned objects programmatically.
+
+### 4. resolve + delete
+
+```bash
+projview comment resolve <id> --store-url "$DB" --demo   # -> { …, "resolved": true }
+projview comment rm <id>      --store-url "$DB" --demo   # -> { "deleted": "<id>" }
+```
+
+✅ Full lifecycle over the CLI: create → list → resolve/reopen → delete. A
+missing id exits non-zero with a clear message.
+
+### 5. usage
+
+```bash
+projview usage --store-url "$DB" --demo
+# { "total": 0, "byType": {}, "topFiles": [], "recentSearches": [] }
+```
+
+`usage` is empty here because the **viewer** (not the CLI) records `view` /
+`search` events; run the server and browse, then `usage` aggregates what was
+looked at.
+
+## observations & limitations
+
+- **Authorship**: explicit `--author` wins; otherwise the git `user.name` (or the
+  OS username). UI-created comments default to the server's git/OS user.
+- **Persistence is required** for CLI comments to survive - the default store is
+  ephemeral and `comment add` warns when it isn't writable beyond the session.
+- **Anchors**: `file` and `heading` are creatable from the CLI; `text` quote
+  anchors come from the viewer (they need a live text selection).
+- **Writes are localhost-only** over HTTP - an exposed (`0.0.0.0`) instance is
+  read-only (`403` on write). The CLI writes the store directly, so it isn't gated.
+
+## reproduce
+
+```bash
+npm i -g projview@latest
+DB="sqlite:///tmp/review.sqlite"
+projview comment add README.md "a note" --author claude --store-url "$DB" --demo
+projview comments --store-url "$DB" --demo
+projview usage --store-url "$DB" --demo
+```

package/docs/how-to-set-up.md

@@ -67,7 +67,7 @@ npm install
 npm run demo                 # preview the bundled docs/  (alias for --demo)
 npm start                    # index the current directory
 node bin/projview.js ./docs  # or call the CLI directly
-npm test                     # run the test suite (node:test, 49 tests)
+npm test                     # run the test suite (node:test, 54 tests)
 ```
 
 See the [project README](README.md) for the architecture and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projview",
-  "version": "0.8.2",
+  "version": "1.0.0",
   "description": "Ephemeral local previewer for markdown + mermaid files in any directory",
   "type": "module",
   "bin": {

package/public/anchor.js

@@ -0,0 +1,38 @@
+/* text-quote re-anchoring - the pure part.
+ *
+ * findQuote() locates a {exact, prefix, suffix} selector in a flat string and
+ * returns the best start offset, disambiguating repeated text by surrounding
+ * context. It touches no DOM, so it's unit-testable directly (no jsdom). The
+ * caller (comments.js) maps the offset back to a DOM Range. */
+
+export const commonPrefix = (a, b) => {
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  return i;
+};
+export const commonSuffix = (a, b) => {
+  let i = 0;
+  while (i < a.length && i < b.length && a[a.length - 1 - i] === b[b.length - 1 - i]) i++;
+  return i;
+};
+
+// Best start offset of anchor.exact in `text`, or -1 if it isn't present.
+// When `exact` repeats, the candidate whose surrounding text best matches
+// prefix/suffix wins (ties -> earliest).
+export function findQuote(text, anchor) {
+  const exact = anchor.exact || '';
+  if (!exact) return -1;
+  const prefix = anchor.prefix || '';
+  const suffix = anchor.suffix || '';
+  let best = -1;
+  let bestScore = -1;
+  let idx = text.indexOf(exact);
+  while (idx !== -1) {
+    const before = text.slice(Math.max(0, idx - prefix.length), idx);
+    const after = text.slice(idx + exact.length, idx + exact.length + suffix.length);
+    const score = commonSuffix(before, prefix) + commonPrefix(after, suffix);
+    if (score > bestScore) { bestScore = score; best = idx; }
+    idx = text.indexOf(exact, idx + 1);
+  }
+  return best;
+}

package/public/comments.js

@@ -10,6 +10,7 @@
 import { $, esc } from './dom.js';
 import { state } from './store.js';
 import { toast } from './toast.js';
+import { findQuote } from './anchor.js';
 
 const contentEl = $('content');
 const viewerEl = $('viewer');
@@ -155,24 +156,11 @@ function pointAt(segs, offset) {
   return last ? { node: last.node, offset: last.node.nodeValue.length } : null;
 }
 
-const commonPrefix = (a, b) => { let i = 0; while (i < a.length && i < b.length && a[i] === b[i]) i++; return i; };
-const commonSuffix = (a, b) => { let i = 0; while (i < a.length && i < b.length && a[a.length - 1 - i] === b[b.length - 1 - i]) i++; return i; };
-
-// Resolve a {exact, prefix, suffix} quote selector to a Range, disambiguating
-// repeats by surrounding context. Returns null if `exact` isn't present.
+// Resolve a {exact, prefix, suffix} quote selector to a DOM Range (using the
+// pure finder in anchor.js). Returns null if `exact` isn't present (orphan).
 function resolveText(anchor, ctx) {
-  const { text } = ctx;
   const exact = anchor.exact || '';
-  if (!exact) return null;
-  let best = -1, bestScore = -1;
-  let idx = text.indexOf(exact);
-  while (idx !== -1) {
-    const before = text.slice(Math.max(0, idx - (anchor.prefix?.length || 0)), idx);
-    const after = text.slice(idx + exact.length, idx + exact.length + (anchor.suffix?.length || 0));
-    const score = commonSuffix(before, anchor.prefix || '') + commonPrefix(after, anchor.suffix || '');
-    if (score > bestScore) { bestScore = score; best = idx; }
-    idx = text.indexOf(exact, idx + 1);
-  }
+  const best = exact ? findQuote(ctx.text, anchor) : -1;
   if (best === -1) return null;
   const a = pointAt(ctx.segs, best);
   const b = pointAt(ctx.segs, best + exact.length);