pagedex 0.1.2 → 0.1.4

package/docs/README.md

@@ -0,0 +1,9 @@
+# pagedex Documentation
+
+User, integration, and developer guides for **pagedex**.
+
+- [Getting Started](./getting-started.md) — CLI flags, environment variables, UI features, wikilinks, Git sync, and mobile gestures.
+- [Supported File Types](./supported-files.md) — Markdown/MDX, sandboxed HTML + sibling assets, PDF, audio/video, CSV/TSV, SVG, code, and binaries.
+- [MCP & REST API](./mcp-and-api.md) — Connecting AI clients to `/mcp`, the 5 vault tools, REST endpoints, `/raw/*`, and SSE live reload.
+- [Security Model](./security.md) — Sandboxed HTML iframes, CSP/CORS behavior, `Origin: null` guard, and path protection.
+- [Development & Release](./development.md) — Running `pnpm dev`, unit & smoke tests, and npm packaging.

package/docs/development.md

@@ -0,0 +1,34 @@
+# Development & Release
+
+## Running in Development
+
+Start both the Hono API/MCP/Raw server (`:4321`) and Vite HMR dev server (`:5173`):
+
+```bash
+pnpm install
+PAGEDEX_ROOT=~/vault HOST=0.0.0.0 pnpm dev
+```
+
+- **Dev UI:** `http://<host>:5173` (Vite proxies `/api/v1`, `/raw`, and `/mcp` with `xfwd: true` to `127.0.0.1:4321`)
+- **API / Production UI:** `http://<host>:4321`
+
+## Build & Test
+
+```bash
+pnpm build   # Build production React bundle into dist/
+pnpm test    # Run node:test suite (test/api-mcp.test.js)
+pnpm smoke   # Run REST + multi-era MCP smoke checks against :4321
+```
+
+## npm Package Contents
+
+`package.json` restricts the published tarball via `"files"` and runs `prepublishOnly: "vite build"`:
+
+- **Included:** `package.json`, `README.md`, `docs/**`, `bin/pagedex.js`, `src/server/**`, and compiled `dist/**`.
+- **Excluded:** `src/client/**`, `.agents/`, `AGENTS.md`, `test/`, `vite.config.js`, `.github/`.
+
+Verify exact tarball contents before publishing with:
+
+```bash
+npm pack --dry-run
+```

package/docs/getting-started.md

@@ -0,0 +1,52 @@
+# Getting Started
+
+`pagedex` turns any local folder of notes, code, media, and HTML into a fast web catalog with full-text search, backlinks, Git sync, and an MCP server on a single port.
+
+## Requirements
+
+- **Node.js `>= 22.5.0`** (uses built-in `node:sqlite` for FTS5 trigram search)
+
+## Running with `npx`
+
+```bash
+# Serve the current directory on http://127.0.0.1:4321
+npx pagedex
+
+# Serve a specific folder and open it in your browser
+npx pagedex ~/vault --open
+
+# Expose on your LAN / Tailscale IP
+npx pagedex ~/vault --host 0.0.0.0 --port 4321
+```
+
+### CLI Options
+
+| Flag | Env Var | Default | Description |
+|---|---|---|---|
+| `[dir]` | `PAGEDEX_ROOT` / `VAULT_ROOT` | `process.cwd()` | Root directory to serve |
+| `-p, --port <port>` | `PORT` | `4321` | HTTP port |
+| `-H, --host <host>` | `HOST` | `127.0.0.1` | Bind address (`0.0.0.0` for LAN/Tailscale) |
+| `-o, --open` | — | `false` | Open browser on startup |
+| `-v, --version` | — | — | Print version |
+| `-h, --help` | — | — | Print CLI help |
+
+### Search Index Cache
+
+The SQLite FTS5 trigram index is stored **outside** your target folder at `~/.cache/pagedex/<sha256>.db`, so running `pagedex` never creates untracked files in your Git repository.
+
+Override the cache location with:
+- `PAGEDEX_INDEX_DIR` — directory for `<hash>.db` files
+- `PAGEDEX_INDEX_PATH` — exact `.db` file path
+
+## Web UI Highlights
+
+- **View Modes (top-right `⋮` menu):**
+  - **Download** — downloads any open file via `/api/v1/file?path=...&download=1`
+  - **Preview** — rendered Markdown, sandboxed HTML, PDF, audio/video, CSV/TSV tables, or images
+  - **Edit** — lazy-loaded Tiptap WYSIWYG editor for Markdown (`.md`, `.markdown`, `.mdx`)
+  - **Diff** — line-by-line Git diff with per-line, per-hunk, and per-file discard
+  - **Raw** — syntax-highlighted source (including SVG XML, HTML, CSV, and code)
+- **Wikilinks & Backlinks:** `[[note]]` and relative links resolve across the folder, and the outline panel lists incoming backlinks.
+- **Git Integration:** Browse changed files in the Changes tab, inspect hunks, discard changes, or commit & push directly from the UI.
+- **Live Reload (SSE):** External edits on disk (e.g. from your editor or an AI agent via MCP) refresh open files and the sidebar tree automatically via `/api/v1/events`.
+- **Mobile Friendly:** Edge-swipe gestures open the left file drawer and right outline drawer, with long-press context actions in the tree.

package/docs/mcp-and-api.md

@@ -0,0 +1,58 @@
+# MCP & REST API
+
+`pagedex` exposes both a multi-era **Model Context Protocol (MCP)** server and a **REST API** on the same port (`4321` by default).
+
+## MCP Server (`/mcp`)
+
+The `/mcp` endpoint supports three MCP protocol eras simultaneously:
+- **`2026-07-28`** (`server/discover` + Streamable HTTP)
+- **`2025-11-25`** (legacy Streamable HTTP `initialize`)
+- **`2024-11-05`** (legacy HTTP+SSE)
+
+### Example Client Config
+
+Point any HTTP-capable MCP client (Claude Code, Cursor, VS Code, etc.) at:
+
+```json
+{
+  "mcpServers": {
+    "pagedex": {
+      "url": "http://127.0.0.1:4321/mcp"
+    }
+  }
+}
+```
+
+### Exposed MCP Tools
+
+| Tool | Purpose |
+|---|---|
+| `list_vault` | List files/folders and metadata in the served root |
+| `read_note` | Read file contents and backlinks |
+| `search_vault` | Run SQLite FTS5 trigram full-text search |
+| `write_note` | Create, overwrite, append, or patch (`target` → `replacement`) files |
+| `delete_note` | Delete a file from disk and update the search index |
+
+## REST API (`/api/v1/*`)
+
+| Method & Path | Description |
+|---|---|
+| `GET /api/v1/health` | Health check and resolved `root` path |
+| `GET /api/v1/tree` | Full directory tree, `flatFiles`, `fileStats`, `backlinks` (`?sort=mtime\|name`, `?limit=`) |
+| `GET /api/v1/files` | Paginated file listing (`?sort=`, `?offset=`, `?limit=`, `?q=`) |
+| `GET /api/v1/search` | Full-text search (`?q=`, `?limit=`) |
+| `GET /api/v1/file` | Read/stream a file (`?path=`, optional `?download=1`, supports HTTP `Range`) |
+| `PUT / POST / PATCH /api/v1/file` | Create, append (`append: true`), or partial-edit (`target`, `replacement`) |
+| `DELETE /api/v1/file` | Delete file (`?path=`) |
+| `POST /api/v1/file/upload` | Multipart file upload into a target folder |
+| `POST /api/v1/file/rename` | Rename/move a file |
+| `POST /api/v1/dir/rename` | Rename/move a directory |
+| `GET /api/v1/changes` | Git working-tree changes |
+| `GET /api/v1/git/diff` | Parsed diff hunks for a file (`?path=`) |
+| `POST /api/v1/git/discard` | Discard line, hunk, or entire file changes |
+| `POST /api/v1/git/commit` | Commit selected files (and optional push) |
+| `GET /api/v1/events` | Server-Sent Events stream for live filesystem changes |
+
+## Static / Raw Route (`/raw/*`)
+
+`GET /raw/<relPath>` serves files by URL path rather than query string so HTML previews can load sibling assets (`style.css`, `app.js`, `data.json`) with relative URLs. See [Security Model](./security.md) for isolation details.

package/docs/security.md

@@ -0,0 +1,25 @@
+# Security Model
+
+## Sandboxed HTML Previews
+
+When previewing `.html` / `.htm` files:
+
+1. **Iframe isolation (`sandbox="allow-scripts"`):**
+   - `allow-same-origin` is intentionally omitted.
+   - The iframe runs with an opaque (`null`) origin, so scripts inside vault HTML cannot access `window.parent`, `localStorage`, cookies, or pagedex's DOM.
+   - Top-level navigation, popups, and form submissions are disabled.
+
+2. **`Origin: null` API guard (`src/server/index.js`):**
+   - Mutating requests (`POST`, `PUT`, `PATCH`, `DELETE`) to `/api/v1/*` with `Origin: null` are rejected with `403 Forbidden`, preventing CORS simple-request CSRF from sandboxed iframes.
+
+3. **Origin-scoped Content-Security-Policy (`src/server/routes/files.js`):**
+   - Responses for `/raw/*.html` and `/raw/*.htm` include a `Content-Security-Policy` header scoped to the request's origin (`x-forwarded-host` / `host` / `referer`), plus `'unsafe-inline' 'unsafe-eval' data: blob:`.
+   - This allows local sibling assets (`style.css`, `app.js`, `data.json`, images) while blocking outbound requests to external domains.
+
+4. **Path Guards (`src/server/paths.js`, `src/server/routes/files.js`):**
+   - All file access passes through `resolveSafe()` (prevents `..` traversal outside `VAULT_ROOT`).
+   - `/raw/*` blocks protected segments (`.git`, `node_modules`, `dist`) and `.env*` files.
+
+## Notes on LAN / Tailscale Hosting
+
+`pagedex` has no built-in user authentication. Bind to `127.0.0.1` (default) for local-only use, or use `--host 0.0.0.0` only on trusted private networks / Tailscale.

package/docs/supported-files.md

@@ -0,0 +1,33 @@
+# Supported File Types
+
+`pagedex` selects the viewer and search behavior by file extension and active view mode (`Preview`, `Edit`, `Diff`, `Raw`, plus `Download` in the top-right `⋮` menu).
+
+| Type | Extensions | Preview Mode | Raw / Edit | Search Indexed |
+|---|---|---|---|---|
+| **Markdown** | `.md`, `.markdown`, `.mdx` | Rendered HTML, wikilinks, backlinks, outline | WYSIWYG (`TiptapEditor`), Raw, Diff | Yes (FTS5) |
+| **HTML** | `.html`, `.htm` | Sandboxed `<iframe src="/raw/...">` | Syntax-highlighted XML/HTML | Yes |
+| **PDF** | `.pdf` | Built-in browser PDF `<iframe>` + Download | — | No |
+| **Audio** | `.mp3`, `.wav`, `.m4a`, `.ogg` | `<audio controls>` with HTTP `Range` seeking | — | No |
+| **Video** | `.mp4`, `.webm`, `.mov` | `<video controls>` with HTTP `Range` seeking | — | No |
+| **Tables** | `.csv`, `.tsv` | Styled HTML `<table>` | Raw text | Yes |
+| **Images** | `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.ico` | Inline `<img>` | — | No |
+| **SVG** | `.svg` | Inline `<img>` | Raw XML toggle | No |
+| **Text / Code** | `.txt`, `.js`, `.ts`, `.py`, `.json`, `.yaml`, etc. | Syntax-highlighted raw view | Raw / Diff | Yes (≤ 2 MB) |
+| **Other Binaries** | `.epub`, `.zip`, `.docx`, `.sqlite`, `.db`, etc. | Download card | — | No |
+
+## HTML + Sibling Files (`style.css`, `data.json`, `app.js`)
+
+HTML files in Preview mode are loaded from `/raw/<path>` rather than `srcDoc`, so relative paths inside your HTML resolve naturally against the same folder:
+
+```html
+<link rel="stylesheet" href="style.css" />
+<script src="app.js"></script>
+```
+
+```js
+fetch('data.json').then((r) => r.json())
+```
+
+## Audio & Video Seeking
+
+`/api/v1/file` and `/raw/*` support HTTP `Range` (`206 Partial Content` / `Accept-Ranges: bytes`), allowing smooth scrubbing in `<audio>` and `<video>` players without buffering the entire file up front.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pagedex",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Local-first Markdown knowledge viewer, editor, Git bridge, and MCP v2 server for any directory.",
   "license": "MIT",
   "repository": {
@@ -18,6 +18,7 @@
     "bin/",
     "src/server/",
     "dist/",
+    "docs/",
     "README.md"
   ],
   "scripts": {