@karmaniverous/jeeves-server 3.0.0-0

package/guides/exports.md

@@ -0,0 +1,239 @@
+# Exporting & Downloads
+
+Jeeves Server can export files as PDF, DOCX, or ZIP — turning Markdown into business-ready documents with one click.
+
+## Export Types
+
+| Format | Available For | How It Works |
+|--------|--------------|--------------|
+| **PDF** | Markdown, Mermaid, PlantUML | Puppeteer (Markdown) or diagram renderer (Mermaid/PlantUML) |
+| **DOCX** | Markdown files | HTML converted via `@turbodocx/html-to-docx` |
+| **SVG** | Mermaid (`.mmd`), PlantUML (`.puml`, `.pu`, `.plantuml`) | Rendered via Mermaid CLI or PlantUML jar/server |
+| **PNG** | Mermaid, PlantUML | Rendered via Mermaid CLI or PlantUML jar/server |
+| **EPS** | PlantUML (jar only) | Vector export via PlantUML jar |
+| **ZIP** | Directories | Entire directory tree compressed via [`archiver`](https://github.com/archiverjs/node-archiver) |
+| **Raw** | Any file | Direct file download |
+
+## Using Exports
+
+### From the UI
+
+The **Download dropdown** (⬇️ icon) in the header shows available export options based on the current file type. Click an option and the file downloads directly — a spinner shows during generation, replaced by a checkmark on completion.
+
+### Via URL Parameters
+
+Append to any file URL:
+
+```
+# PDF export
+/browse/d/docs/design.md?export=pdf
+
+# DOCX export
+/browse/d/docs/design.md?export=docx
+
+# Raw file download
+/browse/d/docs/design.md?raw=1
+```
+
+These work with both insider keys (`?key=<insider-key>&export=pdf`) and outsider share links.
+
+### Programmatic Access
+
+```bash
+# Download PDF via curl
+curl -o design.pdf "https://jeeves.example.com/path/d/docs/design.md?key=<key>&export=pdf"
+
+# Download DOCX
+curl -o design.docx "https://jeeves.example.com/path/d/docs/design.md?key=<key>&export=docx"
+
+# Download raw file
+curl -o design.md "https://jeeves.example.com/path/d/docs/design.md?key=<key>&raw=1"
+```
+
+## PDF Export
+
+PDF generation uses [**Puppeteer**](https://github.com/puppeteer/puppeteer) with your installed Chrome/Chromium. The server:
+
+1. Launches headless Chrome
+2. Loads the rendered markdown page (authenticating with the `_internal` key)
+3. Prints to PDF with print-quality settings
+4. Returns the PDF as a download
+
+### Requirements
+
+- **Chrome/Chromium** must be installed on the server
+- **`chromePath`** must point to the executable in `jeeves.config.ts`
+- **`_internal` key** must be configured (Puppeteer uses it to authenticate)
+
+```typescript
+chromePath: 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+keys: {
+  _internal: 'random-seed-string',  // Required for PDF/DOCX export
+},
+```
+
+### What you see is what you get
+
+PDFs render from the same HTML as the browser view, but:
+- **Prose width setting is ignored** — exports always use full width
+- **Dark mode is ignored** — exports always render in light mode
+- **TOC sidebar is excluded** — the document stands alone
+- **Code blocks retain syntax highlighting** — colors print correctly
+
+### Troubleshooting
+
+**"Export failed" error:**
+- Verify `chromePath` points to a valid Chrome/Chromium executable
+- Ensure the `_internal` key is configured in `keys`
+- Check server logs for Puppeteer errors
+
+**Blank or login page in PDF:**
+- The `_internal` key's derived insider key must be valid
+- Verify with: `curl -s "http://localhost:<port>/insider-key" -H "X-API-Key: <_internal-seed>"`
+
+**Timeout on large documents:**
+- Large markdown files with many code blocks or diagrams take longer to render
+- The server has a default timeout; very large documents may need optimization
+
+## DOCX Export
+
+DOCX generation converts the rendered HTML to a Word document using [`@turbodocx/html-to-docx`](https://github.com/nickmessing/turbodocx). This happens server-side without Chrome.
+
+DOCX exports:
+- Preserve headings, tables, lists, and basic formatting
+- Include code blocks (without syntax highlighting colors)
+- Embed images as inline content
+- Work independently of the `_internal` key (no Puppeteer needed)
+
+## Mermaid Export
+
+Mermaid diagrams (`.mmd` files) can be exported as SVG, PNG, or PDF via the [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli) (`mmdc`).
+
+### Requirements
+
+- **Mermaid CLI** must be installed (via npm)
+- **`mermaidCliPath`** must point to the `mmdc` binary in `jeeves.config.ts`
+- **Puppeteer/Chrome** is required by Mermaid CLI for rendering
+
+```typescript
+mermaidCliPath: '/usr/local/bin/mmdc',
+```
+
+### Export endpoint
+
+```
+GET /api/mermaid-export/<path>?format=svg|png|pdf
+```
+
+## PlantUML Export
+
+PlantUML files (`.puml`, `.pu`, `.plantuml`) can be exported as SVG, PNG, PDF, or EPS.
+
+### Rendering pipeline
+
+PlantUML uses a **fallback rendering pipeline** — each method is tried in order until one succeeds:
+
+1. **Local Java jar** — fastest, supports `!include` directives for complex diagrams with shared libraries. Requires Java and the PlantUML jar.
+2. **Configured PlantUML servers** — self-hosted or private PlantUML server instances, tried in order.
+3. **Public community server** (`plantuml.com`) — always appended as the last resort. Cannot resolve `!include` directives.
+
+### Configuration
+
+```typescript
+plantuml: {
+  jarPath: '/opt/plantuml/plantuml.jar',   // Local jar path (optional)
+  javaPath: '/usr/bin/java',               // Java binary (optional, defaults to 'java')
+  servers: ['https://internal.plantuml.example.com/plantuml'],  // Private servers (optional)
+},
+```
+
+If `plantuml` is omitted entirely, only the public community server is used.
+
+### Export formats
+
+| Format | Jar | Server |
+|--------|-----|--------|
+| SVG | ✅ | ✅ |
+| PNG | ✅ | ✅ |
+| PDF | ✅ | ❌ |
+| EPS | ✅ | ❌ |
+
+### Export endpoint
+
+```
+GET /api/plantuml-export/<path>?format=svg|png|pdf|eps
+```
+
+### `!include` support
+
+Only the **local jar** method resolves `!include` directives. If your diagrams reference shared PlantUML libraries (e.g., AWS icons, company style files), you must configure `jarPath`. The jar runs with `cwd` set to the diagram's parent directory, so relative includes resolve naturally.
+
+## Embedded Diagrams in Markdown
+
+Markdown files can contain **inline diagram source** in fenced code blocks. Following the [GitHub convention](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/), code blocks tagged `mermaid` or `plantuml` (also `puml`) are rendered as inline SVG diagrams when the page is displayed.
+
+````markdown
+```mermaid
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Do it]
+    B -->|No| D[Skip]
+```
+
+```plantuml
+@startuml
+Alice -> Bob: Hello
+Bob --> Alice: Hi!
+@enduml
+```
+````
+
+### How it works
+
+Diagram blocks are detected during markdown parsing, replaced with placeholders, and rendered server-side after HTML generation:
+- **Mermaid** — rendered via Mermaid CLI (`mmdc`) to SVG
+- **PlantUML** — rendered via the same fallback pipeline as `.puml` files (jar → servers → community)
+
+If rendering fails, the source code is displayed with a small error label.
+
+### Showing source instead of rendering
+
+To display diagram source as a code block (without rendering), use a different language hint:
+
+````markdown
+```text
+graph TD
+    A --> B
+```
+````
+
+### PDF/DOCX export
+
+Embedded diagrams appear in PDF and DOCX exports as rendered SVGs — what you see in the browser is what you get in the export.
+
+## ZIP Export
+
+Directories can be downloaded as ZIP archives. The header shows a ZIP download option when viewing a directory.
+
+### Size limit
+
+The `maxZipSizeMb` config setting (default: 100 MB) prevents accidentally zipping enormous directories:
+
+```typescript
+maxZipSizeMb: 100,  // Refuse ZIP for directories larger than this
+```
+
+When the total directory size exceeds this limit, the ZIP option is disabled with a message explaining why.
+
+### What's included
+
+The ZIP contains the entire directory tree — all files and subdirectories. No files are excluded.
+
+## Export for Outsiders
+
+Outsiders (people using share links) can also export files:
+- **PDF and DOCX** exports work on shared markdown files
+- **Raw download** works on any shared file
+- **ZIP** works on shared directories (within the size limit)
+
+The share link's authentication covers the export — no additional credentials needed.

package/guides/setup.md

@@ -0,0 +1,313 @@
+# Setup & Configuration
+
+## Prerequisites
+
+- **Node.js** ≥ 18
+- **Chrome or Chromium** — required for PDF export (Puppeteer uses it headlessly)
+- **A domain or IP** where the server will be accessible (for Google OAuth callbacks)
+
+## Installation
+
+```bash
+git clone https://github.com/karmaniverous/jeeves-server.git
+cd jeeves-server
+npm install
+```
+
+## Configuration
+
+Jeeves Server uses a **TypeScript configuration file** validated at startup by a [Zod](https://github.com/colinhacks/zod) schema. The schema at `src/config/schema.ts` is the single source of truth — all types are derived from it.
+
+### Create your config
+
+```bash
+cp jeeves.config.template.ts jeeves.config.ts
+```
+
+Edit `jeeves.config.ts` with your values. This file is **gitignored** — it contains secrets and is never committed.
+
+### Config structure
+
+```typescript
+import type { JeevesConfig } from './src/config/schema.js';
+
+export default {
+  port: 1934,
+  chromePath: 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+  auth: { ... },
+  insiders: { ... },
+  keys: { ... },
+  events: { ... },
+} satisfies JeevesConfig;
+```
+
+The `satisfies` keyword gives you type checking without losing literal types — your editor will autocomplete and validate as you type.
+
+### Platform-specific settings
+
+**Windows** — drives are auto-discovered; no `roots` config needed:
+```typescript
+chromePath: 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+```
+
+**Linux** — configure filesystem roots for the file browser:
+```typescript
+chromePath: '/usr/bin/chromium-browser',
+roots: {
+  home: '/home',
+  projects: '/opt/projects',
+},
+mermaidCliPath: '/opt/mermaid-cli',  // optional
+plantuml: {                          // optional
+  jarPath: '/opt/plantuml/plantuml.jar',
+  javaPath: '/usr/bin/java',         // defaults to 'java' on PATH
+  servers: [],                       // private servers; community server always appended
+},
+```
+
+On Windows, `roots` is ignored. On Linux, if omitted, it defaults to `{ root: '/' }`.
+
+### Config is immutable at runtime
+
+Once the server starts, the config is loaded once and never written to. Mutable state (like auto-generated insider keys) lives in a separate `state.json` file that the server manages itself.
+
+---
+
+## Authentication Modes
+
+Jeeves Server supports two authentication methods, configured via `auth.modes`:
+
+```typescript
+auth: {
+  modes: ['google', 'keys'],  // Active modes, in priority order
+  // ...
+}
+```
+
+You can enable one or both. The order matters — modes are checked in the order listed.
+
+### Google OAuth (`'google'`)
+
+**Best for:** Teams where insiders log in via browser.
+
+Users authenticate with their Google account. The server checks their email against the `insiders` map to determine access.
+
+**Requirements when enabled:**
+- `auth.google.clientId` and `auth.google.clientSecret` — from [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
+- `auth.sessionSecret` — a random string for signing session cookies
+- At least one entry in `insiders`
+
+**Google Cloud setup:**
+1. Create a project (or use an existing one)
+2. Go to **APIs & Services → Credentials → Create Credentials → OAuth client ID**
+3. Application type: **Web application**
+4. Authorized redirect URI: `https://your-domain.com/auth/google/callback`
+5. Copy the client ID and client secret into your config
+
+**Session secret generation:**
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+### Key-Based Auth (`'keys'`)
+
+**Best for:** Headless access, bot integrations, simple setups without Google.
+
+Users authenticate by appending `?key=<value>` to any URL. The server derives keys from configured seeds using HMAC-SHA256 and checks the provided key against all known derived keys.
+
+**Requirements when enabled:**
+- At least one entry in `keys`
+
+**How keys work:** You configure a **seed** (a random secret string). The server derives the actual insider key from it via HMAC. You never put the derived key in the config — only the seed. To get the derived key for use in URLs:
+
+```bash
+# Via the API (requires X-API-Key header with any seed)
+curl -H "X-API-Key: <seed>" https://your-domain.com/insider-key
+```
+
+### Both Modes Together
+
+```typescript
+auth: {
+  modes: ['keys', 'google'],  // Keys checked first
+}
+```
+
+When both are active:
+- Browser users can log in with Google for a session-based experience
+- Bots and scripts can use `?key=` for stateless access
+- Both methods work on every endpoint
+
+### Choosing a Mode
+
+| Scenario | Recommended |
+|----------|-------------|
+| Team of humans accessing via browser | `['google']` |
+| Bot/script access only | `['keys']` |
+| Humans + bots on the same server | `['google', 'keys']` |
+| Quick local setup, no Google credentials | `['keys']` |
+
+---
+
+## Insiders
+
+The `insiders` map defines **who** has full browsing access. Each entry is an email address with optional path scopes:
+
+```typescript
+insiders: {
+  // Full access
+  'alice@example.com': {},
+
+  // Restricted to specific paths (allow-only)
+  'contractor@example.com': {
+    scopes: ['/d/projects/client-x/*'],
+  },
+
+  // Broad access with cutouts (allow/deny)
+  'team-member@example.com': {
+    scopes: {
+      allow: ['/d/*'],
+      deny: ['/d/secrets/*', '/d/.private/*'],
+    },
+  },
+},
+```
+
+With Google auth, insiders log in via OAuth and the server checks their email. With key auth, each insider gets a derived URL key.
+
+See the [Insiders, Outsiders & Sharing](sharing.md) guide for the full access model.
+
+---
+
+## Keys
+
+The `keys` map defines **named API keys** for machine access:
+
+```typescript
+keys: {
+  // Unscoped — full access to all paths
+  primary: 'a-random-64-char-hex-string',
+
+  // Scoped — restricted to specific paths
+  'webhook-notion': {
+    key: 'another-random-hex-string',
+    scopes: ['/event'],
+  },
+
+  // Reserved: internal server operations (Puppeteer export)
+  _internal: 'yet-another-random-hex-string',
+},
+```
+
+**Generate seeds with:**
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+### The `_internal` key
+
+The `_internal` key is reserved for the server's own use — specifically, Puppeteer uses it to authenticate when rendering PDFs and DOCX files. It **must not** have scopes (enforced by the schema).
+
+If you don't configure `_internal`, PDF/DOCX export will not work.
+
+### Key names
+
+Key names are used for logging and identification. Choose meaningful names: `primary`, `webhook-notion`, `ci-bot`, etc.
+
+---
+
+## Event Gateway
+
+The event gateway receives webhooks at `POST /event`, validates them against JSON Schema rules, and dispatches matched events to shell commands via a durable JSONL queue.
+
+```typescript
+events: {
+  'notion-page-update': {
+    // JSON Schema to match against incoming body
+    schema: {
+      type: 'object',
+      properties: { type: { const: 'page.content_updated' } },
+      required: ['type'],
+    },
+    // Command to execute when matched
+    cmd: 'node /path/to/handler.js',
+    // Optional: transform body before passing to command
+    map: {
+      pageId: { '$': { method: '$.lib._.get', params: ['$.input', 'data.page_id'] } },
+    },
+    // Optional: override default timeout
+    timeoutMs: 60000,
+  },
+},
+```
+
+Webhook callers authenticate with a scoped key:
+```bash
+curl -X POST "https://your-domain.com/event?key=<webhook-key>" \
+  -H "Content-Type: application/json" \
+  -d '{"type": "page.content_updated", "data": {"page_id": "abc123"}}'
+```
+
+---
+
+## Building
+
+```bash
+# Full build (server TypeScript + React client)
+npm run build                                      # Compiles server → dist/
+cd client && npx vite build --outDir ../dist/client && cd ..  # Builds React SPA → dist/client/
+```
+
+> ⚠️ `npm run build` deletes the entire `dist/` directory (including `dist/client/`). Always rebuild the client after the server.
+
+---
+
+## Running
+
+```bash
+node dist/server.js
+```
+
+### As a Windows service
+
+```bash
+nssm install JeevesServer "node" "/path/to/dist/server.js"
+nssm start JeevesServer
+```
+
+### Health check
+
+```
+GET /health
+```
+
+Returns `200 OK` with no authentication required.
+
+---
+
+## File Layout
+
+```
+jeeves-server/
+├── jeeves.config.ts          # Your config (gitignored)
+├── jeeves.config.template.ts # Config template (committed)
+├── state.json                # Runtime state (gitignored, auto-managed)
+├── src/                      # Server source (TypeScript)
+│   ├── config/
+│   │   ├── schema.ts         # Zod schema (source of truth)
+│   │   ├── index.ts          # Config loader (jiti for TS)
+│   │   └── types.ts          # Runtime types
+│   ├── auth/                 # Google OAuth + key verification
+│   ├── routes/               # Fastify route handlers
+│   ├── services/             # Export, markdown, event queue
+│   └── server.ts             # Entry point
+├── client/                   # React SPA source
+│   └── src/
+│       ├── pages/            # FileBrowser, FileViewer, About
+│       ├── components/       # Header, dropdowns, viewers
+│       └── lib/              # API client, auth, theme
+├── dist/                     # Compiled output (gitignored)
+│   ├── server.js             # Compiled server
+│   └── client/               # Built React SPA
+└── guides/                   # Documentation
+```