projview 0.6.0 → 0.7.0

package/bin/projview.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 import path from 'node:path';
-import { spawn } from 'node:child_process';
+import os from 'node:os';
+import { spawn, execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { readFileSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { startServer } from '../src/server.js';
 import { buildTree, countFiles } from '../src/walk.js';
 import { buildIndex, search } from '../src/search.js';
-import { resolveStoreConfig, createStore } from '../src/store.js';
+import { resolveStoreConfig, createStore, isPersistent } from '../src/store.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const DEMO_DIR = path.join(__dirname, '..', 'docs');   // bundled sample docs
@@ -50,6 +51,8 @@ function parseSubArgs(args) {
     else if (a === '--store-url') o.storeUrl = args[++i];
     else if (a === '--persist') o.persist = true;
     else if (a === '--demo') o.demo = true;
+    else if (a === '--heading') o.heading = args[++i];
+    else if (a === '--author') o.author = args[++i];
     else if (a.startsWith('-')) { /* ignore unknown flag in a subcommand */ }
     else o.positional.push(a);
   }
@@ -80,6 +83,84 @@ function cmdTree(args) {
   process.stdout.write(JSON.stringify({ root: path.basename(root) || root, files: countFiles(tree), tree }, null, 2) + '\n');
 }
 
+const print = (obj) => process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+
+// Resolve the comment author: explicit flag > git user.name > OS username.
+// Agents pass --author (e.g. "claude") so AI-authored comments are distinguishable.
+function resolveAuthor(explicit) {
+  if (explicit) return explicit;
+  try {
+    const name = execSync('git config user.name', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    if (name) return name;
+  } catch { /* no git / no user.name */ }
+  try { return os.userInfo().username || null; } catch { return null; }
+}
+
+// projview comment <add|resolve|reopen|rm> ...   (writes ride the store)
+async function cmdComment(args) {
+  const sub = args[0];
+  const o = parseSubArgs(args.slice(1));
+  const cfg = resolveStoreConfig(o);
+  const root = o.demo ? DEMO_DIR : process.cwd();
+  const store = createStore(cfg, root);
+  try {
+    if (sub === 'add') {
+      const [file, body] = o.positional;
+      if (!file || !body) {
+        console.error('usage: projview comment add <file> "<body>" [--heading <id>] [--author <name>] [--persist | --store-url <url>]');
+        process.exit(1);
+      }
+      if (!isPersistent(cfg)) {
+        console.error('⚠ no persistent store - this comment will NOT be saved on exit. Re-run with --persist or --store-url <url>.');
+      }
+      if (!existsSync(path.resolve(root, file))) {
+        console.error(`note: "${file}" not found under ${root} - saving the comment anyway.`);
+      }
+      const anchor = o.heading ? { type: 'heading', id: o.heading } : { type: 'file' };
+      print(await store.addComment({ file, body, anchor, author: resolveAuthor(o.author) }));
+      return;
+    }
+    if (sub === 'resolve' || sub === 'reopen') {
+      const id = o.positional[0];
+      if (!id) { console.error(`usage: projview comment ${sub} <id> [--persist | --store-url <url>]`); process.exit(1); }
+      const c = await store.updateComment(id, { resolved: sub === 'resolve' });
+      if (!c) { console.error(`no comment with id ${id} in this store`); process.exit(1); }
+      print(c);
+      return;
+    }
+    if (sub === 'rm' || sub === 'delete') {
+      const id = o.positional[0];
+      if (!id) { console.error('usage: projview comment rm <id> [--persist | --store-url <url>]'); process.exit(1); }
+      if (!(await store.deleteComment(id))) { console.error(`no comment with id ${id} in this store`); process.exit(1); }
+      print({ deleted: id });
+      return;
+    }
+    console.error('usage: projview comment <add|resolve|reopen|rm> ...');
+    process.exit(1);
+  } finally {
+    await store.close();
+  }
+}
+
+// projview comments [file]   -> list comments (all, or for one file) as JSON
+async function cmdComments(args) {
+  const o = parseSubArgs(args);
+  const root = o.demo ? DEMO_DIR : process.cwd();
+  const store = createStore(resolveStoreConfig(o), root);
+  const list = await store.listComments(o.positional[0]);
+  await store.close();
+  print(list);
+}
+
+// projview usage [path]   -> aggregated usage stats (views / searches) as JSON
+async function cmdUsage(args) {
+  const o = parseSubArgs(args);
+  const store = createStore(resolveStoreConfig(o), subRoot(o, 0));
+  const stats = await store.usageStats();
+  await store.close();
+  print(stats);
+}
+
 function openBrowser(url) {
   const cmd = process.platform === 'darwin' ? 'open'
     : process.platform === 'win32' ? 'cmd' : 'xdg-open';
@@ -92,9 +173,13 @@ function openBrowser(url) {
 const HELP = `projview - ephemeral previewer for markdown + mermaid
 
 usage:
-  projview [path] [options]            start the viewer (default)
-  projview search <query> [path]       print ranked search results as JSON
-  projview tree [path]                 print the file tree as JSON
+  projview [path] [options]                start the viewer (default)
+  projview search <query> [path]           print ranked search results as JSON
+  projview tree [path]                     print the file tree as JSON
+  projview comment add <file> "<text>"     leave a comment (--heading <id> for a section)
+  projview comments [file]                 list comments as JSON
+  projview comment resolve|reopen|rm <id>  resolve, reopen, or delete a comment
+  projview usage [path]                    print usage stats (views / searches) as JSON
 
   (subcommands print to stdout and exit - no server. --demo works with them too,
    e.g. projview search "websockets" --demo)
@@ -109,11 +194,14 @@ options:
       --persist       keep the index in ~/.projview/cache and reuse it next run
       --store <kind>  store backend: memory | superlite | lite  (default: memory)
       --store-url <url>  custom store: sqlite://<file> or postgres://<...>  (or set DATABASE_URL)
+      --heading <id>  (comment add) anchor the comment to a heading/section id
+      --author <name> (comment add) author to record (default: git/OS user)
   -v, --version       print the version and exit
   -h, --help          show this help
 
 ephemeral by default - nothing is persisted unless you opt in with --persist /
---store / --store-url. ctrl-c removes any ephemeral store.`;
+--store / --store-url. ctrl-c removes any ephemeral store. Comments + usage need a
+persistent store to survive (you'll be warned when adding a comment without one).`;
 
 async function main() {
   const argv = process.argv.slice(2);
@@ -121,6 +209,9 @@ async function main() {
   // machine subcommands -> JSON to stdout, then exit (no server)
   if (argv[0] === 'search') return cmdSearch(argv.slice(1));
   if (argv[0] === 'tree') return cmdTree(argv.slice(1));
+  if (argv[0] === 'comment') return cmdComment(argv.slice(1));
+  if (argv[0] === 'comments') return cmdComments(argv.slice(1));
+  if (argv[0] === 'usage') return cmdUsage(argv.slice(1));
 
   const opts = parseArgs(argv);
   if (opts.help) { console.log(HELP); return; }

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

@@ -11,7 +11,7 @@ previewer for markdown + mermaid files.
 
 | need | version |
 | --- | --- |
-| Node.js | **18+** |
+| Node.js | **22+** (the `lite` sqlite store uses the built-in `node:sqlite`) |
 | npm | ships with Node |
 
 No build step. By default indexing is in-memory and nothing is written to disk -
@@ -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, 29 tests)
+npm test                     # run the test suite (node:test, 45 tests)
 ```
 
 See the [project README](README.md) for the architecture and the
@@ -82,10 +82,15 @@ See the [project README](README.md) for the architecture and the
 | `projview [path]` | start the viewer (default) |
 | `projview search <query> [path]` | print ranked search results as JSON, then exit |
 | `projview tree [path]` | print the file tree as JSON, then exit |
+| `projview comment add <file> "<body>"` | leave a comment (`--heading <id>` for a section) |
+| `projview comments [file]` | list comments as JSON |
+| `projview comment resolve\|reopen\|rm <id>` | resolve, reopen, or delete a comment |
+| `projview usage [path]` | print usage stats (views / searches) as JSON |
 
-The `search` and `tree` subcommands are projview's **machine interface** - JSON on
-stdout, no server, no browser - built for agents and scripts. See
-[ai-tests/search.md](ai-tests/search.md) for a worked test.
+The subcommands are projview's **machine interface** - JSON on stdout, no server,
+no browser - built for agents and scripts. `search`/`tree` are read-only;
+`comment` writes ride a persistent store (you're warned if you comment without
+one). See [ai-tests/search.md](ai-tests/search.md) for a worked test.
 
 **Options**
 
@@ -98,6 +103,8 @@ stdout, no server, no browser - built for agents and scripts. See
 | `--persist` | keep the index in `~/.projview/cache` and reuse it next run |
 | `--store <kind>` | store backend: `memory` \| `superlite` \| `lite` (default: `memory`; `lite` when `--persist`) |
 | `--store-url <url>` | use a custom store: `sqlite://<file>` or `postgres://<...>` |
+| `--heading <id>` | (`comment add`) anchor the comment to a heading/section id |
+| `--author <name>` | (`comment add`) author to record (default: git/OS user) |
 | `-v`, `--version` | print the version and exit |
 | `-h`, `--help` | show help |
 
@@ -113,8 +120,9 @@ stdout, no server, no browser - built for agents and scripts. See
 
 ## persistence & stores
 
-By default projview is **ephemeral** - the index lives in memory and nothing is
-written to disk. Opt in to persistence when you want a faster warm start or a
+By default projview is **ephemeral** - the index (plus any comments and usage
+events) lives in memory and nothing is written to disk. Opt in to persistence
+when you want a faster warm start, comments that survive a restart, or a
 queryable store an AI can read:
 
 | backend | what | how |

package/docs/reference/api.md

@@ -5,7 +5,8 @@ and scroll-spy (the active section should track as you scroll).
 
 ## overview
 
-projview exposes a tiny HTTP surface. Everything is read-only and in-memory.
+projview exposes a tiny HTTP surface. It never writes your files - the only
+state it records is its own usage events (views / searches) into the store.
 
 ## endpoints
 
@@ -37,6 +38,35 @@ line-numbered snippets. See [the AI search test](../ai-tests/search.md).
 `projview tree [path]` returns `{ root, files, tree[] }` - the same structure
 `/api/tree` serves.
 
+### projview comment
+
+Leave / manage comments (they ride a persistent store - use `--persist` or
+`--store-url`, else you'll be warned the comment won't survive exit):
+
+| command | meaning |
+| --- | --- |
+| `projview comment add <file> "<body>"` | add a comment (whole file) |
+| `projview comment add <file> "<body>" --heading <id>` | anchor it to a section |
+| `projview comment resolve\|reopen <id>` | toggle resolved |
+| `projview comment rm <id>` | delete it |
+
+`--author <name>` overrides the recorded author (default: git/OS user). Agents
+pass e.g. `--author claude` so AI-authored comments are distinguishable. A
+comment is `{ id, file, anchor, body, author, createdAt, resolved }`; the
+`anchor` is `{type:'file'}`, `{type:'heading', id}`, or a `{type:'text', exact,
+prefix, suffix, section}` quote selector (text anchors come from the viewer).
+
+### projview comments
+
+`projview comments [file]` lists comments as JSON - all of them, or just one
+file's.
+
+### projview usage
+
+`projview usage [path]` returns `{ total, byType, topFiles[], recentSearches[] }`.
+The viewer records a `view` per file opened and a `search` per query, so usage
+accumulates over a session (persisted only with a persistent store).
+
 ## the walker
 
 ### ignored directories
@@ -87,8 +117,9 @@ A chokidar watcher broadcasts change/tree events over SSE.
 
 ## stores (persistence)
 
-The index is in-memory by default (ephemeral). Opt into a pluggable store with
-`--persist` / `--store` / `--store-url`:
+The index - plus **comments** and **usage events** - is in-memory by default
+(ephemeral). Opt into a pluggable store with `--persist` / `--store` /
+`--store-url` so comments and usage survive a restart:
 
 ### backends
 

package/package.json

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

package/src/server.js

@@ -80,7 +80,10 @@ export async function startServer(root, { port = 4321, host = '127.0.0.1', store
 
     // --- search (fuzzy filenames + full-text contents) ---
     if (pathname === '/api/search') {
-      sendJson(res, search(url.searchParams.get('q') || ''));
+      const q = url.searchParams.get('q') || '';
+      const results = search(q);
+      if (q.trim()) { try { await store.recordEvent({ type: 'search', query: q.trim(), count: results.files.length + results.content.length }); } catch { /* usage is best-effort */ } }
+      sendJson(res, results);
       return;
     }
 
@@ -94,6 +97,7 @@ export async function startServer(root, { port = 4321, host = '127.0.0.1', store
       }
       try {
         const content = await fsp.readFile(abs, 'utf8');
+        try { await store.recordEvent({ type: 'view', file: rel }); } catch { /* usage is best-effort */ }
         sendJson(res, { path: rel, ext: path.extname(abs).toLowerCase(), html: renderFile(path.extname(abs).toLowerCase(), content) });
       } catch {
         sendJson(res, { error: 'not found' }, 404);

package/src/store.js

@@ -1,20 +1,30 @@
-/* pluggable persistence for the index.
+/* pluggable persistence for the index, comments + usage.
  *
- * A Store persists indexed entries so a re-spawn can warm-start. Backends:
- *   memory    - no persistence (ephemeral default; nothing written)
+ * A Store persists three things so a re-spawn can warm-start and so comments /
+ * usage survive a session:
+ *   entries  - indexed files { path, name, ext, mtime, content }
+ *   comments - notes on a file or a portion of it (see anchor model below)
+ *   events   - usage signals { ts, type, file?, query?, count? }
+ *
+ * Backends:
+ *   memory    - no disk persistence (ephemeral default; lives only this session)
  *   superlite - a JSON file
  *   lite      - sqlite via node:sqlite (built-in)
  *   custom    - a connection URL: sqlite://<file> or postgres://<...> (lazy `pg`)
  *
- * An entry is { path, name, ext, mtime, content }. Everything above the store
- * stays storage-agnostic - search still runs in memory over loaded entries.
+ * A comment's `anchor` is one of:
+ *   { type: 'file' }                                  whole document
+ *   { type: 'heading', id }                           a section (stable pv- id)
+ *   { type: 'text', exact, prefix, suffix, section }  a quoted range (re-anchored
+ *                                                      client-side; see 3c)
+ * Everything above the store stays storage-agnostic.
  */
 
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 
 // node:sqlite is flagged "experimental" and emits a noisy warning on use; we
 // opted into it deliberately, so quiet just that one notice (others pass through).
@@ -33,6 +43,42 @@ const keyFor = (root) => createHash('sha256').update(path.resolve(root)).digest(
 const ensureDir = (d) => fs.mkdirSync(d, { recursive: true });
 const redact = (url) => url.replace(/\/\/[^@/]*@/, '//***@');   // hide creds in logs
 
+// Normalize loose input into a full comment / event record (defaults + ids).
+const newComment = (c) => ({
+  id: c.id || randomUUID(),
+  file: c.file,
+  anchor: c.anchor || { type: 'file' },
+  body: c.body,
+  author: c.author ?? null,
+  createdAt: c.createdAt || Date.now(),
+  resolved: !!c.resolved
+});
+const newEvent = (e) => ({
+  id: randomUUID(),
+  ts: e.ts || Date.now(),
+  type: e.type,
+  file: e.file ?? null,
+  query: e.query ?? null,
+  count: e.count ?? null
+});
+
+// Aggregate raw events into something a human / agent can read at a glance.
+function summarizeEvents(events) {
+  const byType = {};
+  const fileCounts = {};
+  const searches = [];
+  for (const e of events) {
+    byType[e.type] = (byType[e.type] || 0) + 1;
+    if (e.file) fileCounts[e.file] = (fileCounts[e.file] || 0) + 1;
+    if (e.type === 'search' && e.query) searches.push(e.query);
+  }
+  const topFiles = Object.entries(fileCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10)
+    .map(([file, count]) => ({ file, count }));
+  return { total: events.length, byType, topFiles, recentSearches: searches.slice(-10).reverse() };
+}
+
 function readConfigFile() {
   try { return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')); } catch { return {}; }
 }
@@ -65,21 +111,77 @@ export function createStore(config, root) {
   }
 }
 
+// True when a store keeps comments/usage across restarts. The CLI/server warn
+// when it's false so a comment isn't silently lost on exit.
+export function isPersistent(config) {
+  const cfg = config || { kind: 'memory' };
+  if (cfg.kind === 'memory') return false;
+  if (cfg.kind === 'custom') return true;             // the user's own DB
+  return !!cfg.persist;                                // superlite/lite: only with --persist
+}
+
 function fileFor(root, persist, ext) {
   const dir = persist ? CACHE_DIR : EPHEMERAL_DIR;
   ensureDir(dir);
   return path.join(dir, `${keyFor(root)}.${ext}`);
 }
 
+/* ---------- shared in-memory comment/event layer (memory + superlite) ---------- */
+
+// Holds comments + events in memory; calls flush() after each mutation so a
+// disk-backed wrapper (superlite) can persist. memory passes a no-op flush.
+function inMemoryDocs(flush = async () => {}) {
+  const comments = new Map();   // id -> comment
+  const events = [];            // append-only (stable ref - never reassigned)
+  return {
+    comments,
+    events,
+    async addComment(c) {
+      const comment = newComment(c);
+      comments.set(comment.id, comment);
+      await flush();
+      return comment;
+    },
+    async listComments(file) {
+      const all = [...comments.values()].sort((a, b) => a.createdAt - b.createdAt);
+      return file ? all.filter((c) => c.file === file) : all;
+    },
+    async updateComment(id, patch) {
+      const c = comments.get(id);
+      if (!c) return null;
+      Object.assign(c, patch, { id: c.id });   // id is immutable
+      await flush();
+      return c;
+    },
+    async deleteComment(id) {
+      const ok = comments.delete(id);
+      await flush();
+      return ok;
+    },
+    async recordEvent(e) {
+      events.push(newEvent(e));
+      await flush();
+    },
+    async usageStats() { return summarizeEvents(events); }
+  };
+}
+
 /* ---------- backends ---------- */
 
 function memoryStore() {
+  const docs = inMemoryDocs();
   return {
     kind: 'memory',
     async load() { return null; },
     async save() {},
     async update() {},
     async remove() {},
+    addComment: docs.addComment,
+    listComments: docs.listComments,
+    updateComment: docs.updateComment,
+    deleteComment: docs.deleteComment,
+    recordEvent: docs.recordEvent,
+    usageStats: docs.usageStats,
     async close() {},
     describe() { return 'in-memory (ephemeral - nothing persisted)'; }
   };
@@ -87,29 +189,38 @@ function memoryStore() {
 
 function superliteStore(root, persist) {
   const file = fileFor(root, persist, 'json');
-  let map = null;   // path -> entry, lazily loaded
+  const entries = new Map();   // path -> entry
+  let loaded = false;
+  const flush = () => fsp.writeFile(file, JSON.stringify({
+    builtAt: Date.now(),
+    entries: [...entries.values()],
+    comments: [...docs.comments.values()],
+    events: docs.events
+  }));
+  const docs = inMemoryDocs(() => (loaded ? flush() : Promise.resolve()));
   const ensure = async () => {
-    if (map) return map;
+    if (loaded) return;
     try {
       const d = JSON.parse(await fsp.readFile(file, 'utf8'));
-      map = new Map((d.entries || []).map((e) => [e.path, e]));
-    } catch { map = new Map(); }
-    return map;
+      for (const e of d.entries || []) entries.set(e.path, e);
+      for (const c of d.comments || []) docs.comments.set(c.id, c);
+      for (const ev of d.events || []) docs.events.push(ev);
+    } catch { /* fresh */ }
+    loaded = true;
   };
-  const flush = () => fsp.writeFile(file, JSON.stringify({ builtAt: Date.now(), entries: [...map.values()] }));
   return {
     kind: 'superlite',
     file,
-    async load() {
-      const m = await ensure();
-      return m.size ? { entries: [...m.values()] } : null;
-    },
-    async save(entries) {
-      map = new Map(entries.map((e) => [e.path, e]));
-      await flush();
-    },
-    async update(entry) { (await ensure()).set(entry.path, entry); await flush(); },
-    async remove(p) { (await ensure()).delete(p); await flush(); },
+    async load() { await ensure(); return entries.size ? { entries: [...entries.values()] } : null; },
+    async save(es) { await ensure(); entries.clear(); for (const e of es) entries.set(e.path, e); await flush(); },
+    async update(entry) { await ensure(); entries.set(entry.path, entry); await flush(); },
+    async remove(p) { await ensure(); entries.delete(p); await flush(); },
+    async addComment(c) { await ensure(); return docs.addComment(c); },
+    async listComments(f) { await ensure(); return docs.listComments(f); },
+    async updateComment(id, patch) { await ensure(); return docs.updateComment(id, patch); },
+    async deleteComment(id) { await ensure(); return docs.deleteComment(id); },
+    async recordEvent(e) { await ensure(); return docs.recordEvent(e); },
+    async usageStats() { await ensure(); return docs.usageStats(); },
     async close({ keep } = {}) {
       if (!persist && !keep) { try { await fsp.unlink(file); } catch { /* gone */ } }
     },
@@ -120,13 +231,22 @@ function superliteStore(root, persist) {
 // sqlite-backed store at an explicit file. cleanup=true removes the file on close.
 function sqliteAt(file, { cleanup }) {
   let db = null;
+  const toComment = (r) => ({
+    id: r.id, file: r.file, anchor: JSON.parse(r.anchor || '{"type":"file"}'),
+    body: r.body, author: r.author, createdAt: r.createdAt, resolved: !!r.resolved
+  });
   const open = async () => {
     if (db) return db;
     const { DatabaseSync } = await import('node:sqlite');
     db = new DatabaseSync(file);
     db.exec('CREATE TABLE IF NOT EXISTS files (path TEXT PRIMARY KEY, name TEXT, ext TEXT, mtime REAL, content TEXT)');
+    db.exec('CREATE TABLE IF NOT EXISTS comments (id TEXT PRIMARY KEY, file TEXT, anchor TEXT, body TEXT, author TEXT, createdAt REAL, resolved INTEGER)');
+    db.exec('CREATE TABLE IF NOT EXISTS events (id TEXT PRIMARY KEY, ts REAL, type TEXT, file TEXT, query TEXT, count INTEGER)');
     return db;
   };
+  const writeComment = (d, c) => d
+    .prepare('INSERT OR REPLACE INTO comments (id, file, anchor, body, author, createdAt, resolved) VALUES (?, ?, ?, ?, ?, ?, ?)')
+    .run(c.id, c.file, JSON.stringify(c.anchor), c.body, c.author, c.createdAt, c.resolved ? 1 : 0);
   return {
     kind: 'lite',
     file,
@@ -152,6 +272,41 @@ function sqliteAt(file, { cleanup }) {
       const d = await open();
       d.prepare('DELETE FROM files WHERE path = ?').run(p);
     },
+    async addComment(c) {
+      const d = await open();
+      const comment = newComment(c);
+      writeComment(d, comment);
+      return comment;
+    },
+    async listComments(file) {
+      const d = await open();
+      const rows = file
+        ? d.prepare('SELECT * FROM comments WHERE file = ? ORDER BY createdAt').all(file)
+        : d.prepare('SELECT * FROM comments ORDER BY createdAt').all();
+      return rows.map(toComment);
+    },
+    async updateComment(id, patch) {
+      const d = await open();
+      const row = d.prepare('SELECT * FROM comments WHERE id = ?').get(id);
+      if (!row) return null;
+      const c = { ...toComment(row), ...patch, id };
+      writeComment(d, c);
+      return c;
+    },
+    async deleteComment(id) {
+      const d = await open();
+      return d.prepare('DELETE FROM comments WHERE id = ?').run(id).changes > 0;
+    },
+    async recordEvent(e) {
+      const d = await open();
+      const ev = newEvent(e);
+      d.prepare('INSERT INTO events (id, ts, type, file, query, count) VALUES (?, ?, ?, ?, ?, ?)')
+        .run(ev.id, ev.ts, ev.type, ev.file, ev.query, ev.count);
+    },
+    async usageStats() {
+      const d = await open();
+      return summarizeEvents(d.prepare('SELECT type, file, query FROM events').all());
+    },
     async close({ keep } = {}) {
       if (db) { db.close(); db = null; }
       if (cleanup && !keep) { try { await fsp.unlink(file); } catch { /* gone */ } }
@@ -176,6 +331,11 @@ function customStore(url) {
 
 function postgresStore(url) {
   let client = null;
+  const toComment = (r) => ({
+    id: r.id, file: r.file,
+    anchor: typeof r.anchor === 'string' ? JSON.parse(r.anchor) : (r.anchor || { type: 'file' }),
+    body: r.body, author: r.author, createdAt: Number(r.createdat), resolved: !!r.resolved
+  });
   const open = async () => {
     if (client) return client;
     let pg;
@@ -183,11 +343,16 @@ function postgresStore(url) {
     catch { throw new Error('the postgres store needs the "pg" package - run: npm i pg'); }
     client = new pg.Client({ connectionString: url });
     await client.connect();
-    await client.query(
-      'CREATE TABLE IF NOT EXISTS projview_files (path TEXT PRIMARY KEY, name TEXT, ext TEXT, mtime DOUBLE PRECISION, content TEXT)'
-    );
+    await client.query('CREATE TABLE IF NOT EXISTS projview_files (path TEXT PRIMARY KEY, name TEXT, ext TEXT, mtime DOUBLE PRECISION, content TEXT)');
+    await client.query('CREATE TABLE IF NOT EXISTS projview_comments (id TEXT PRIMARY KEY, file TEXT, anchor TEXT, body TEXT, author TEXT, createdat DOUBLE PRECISION, resolved BOOLEAN)');
+    await client.query('CREATE TABLE IF NOT EXISTS projview_events (id TEXT PRIMARY KEY, ts DOUBLE PRECISION, type TEXT, file TEXT, query TEXT, count INTEGER)');
     return client;
   };
+  const writeComment = (c) => client.query(
+    'INSERT INTO projview_comments (id, file, anchor, body, author, createdat, resolved) VALUES ($1, $2, $3, $4, $5, $6, $7)' +
+      ' ON CONFLICT (id) DO UPDATE SET file = $2, anchor = $3, body = $4, author = $5, createdat = $6, resolved = $7',
+    [c.id, c.file, JSON.stringify(c.anchor), c.body, c.author, c.createdAt, c.resolved]
+  );
   return {
     kind: 'custom',
     async load() {
@@ -220,7 +385,43 @@ function postgresStore(url) {
       const c = await open();
       await c.query('DELETE FROM projview_files WHERE path = $1', [p]);
     },
-    async close() { if (client) { await client.end(); client = null; } },   // never drop the user's table
+    async addComment(c) {
+      await open();
+      const comment = newComment(c);
+      await writeComment(comment);
+      return comment;
+    },
+    async listComments(file) {
+      const c = await open();
+      const { rows } = file
+        ? await c.query('SELECT * FROM projview_comments WHERE file = $1 ORDER BY createdat', [file])
+        : await c.query('SELECT * FROM projview_comments ORDER BY createdat');
+      return rows.map(toComment);
+    },
+    async updateComment(id, patch) {
+      const c = await open();
+      const { rows } = await c.query('SELECT * FROM projview_comments WHERE id = $1', [id]);
+      if (!rows.length) return null;
+      const merged = { ...toComment(rows[0]), ...patch, id };
+      await writeComment(merged);
+      return merged;
+    },
+    async deleteComment(id) {
+      const c = await open();
+      return (await c.query('DELETE FROM projview_comments WHERE id = $1', [id])).rowCount > 0;
+    },
+    async recordEvent(e) {
+      const c = await open();
+      const ev = newEvent(e);
+      await c.query('INSERT INTO projview_events (id, ts, type, file, query, count) VALUES ($1, $2, $3, $4, $5, $6)',
+        [ev.id, ev.ts, ev.type, ev.file, ev.query, ev.count]);
+    },
+    async usageStats() {
+      const c = await open();
+      const { rows } = await c.query('SELECT type, file, query FROM projview_events');
+      return summarizeEvents(rows);
+    },
+    async close() { if (client) { await client.end(); client = null; } },   // never drop the user's tables
     describe() { return `custom/postgres ${redact(url)}`; }
   };
 }