@karmaniverous/jeeves-server 3.0.0 → 3.1.0

package/guides/deployment.md

@@ -2,57 +2,75 @@
 
 How to run Jeeves Server in production.
 
-> Jeeves Server runs on **Windows** and **Linux**. Both platforms are tested in CI.
-
 ## Prerequisites
 
-- **Node.js** ≥ 18
+- **Node.js** ≥ 20
 - **Chrome or Chromium** — for PDF/DOCX export via Puppeteer
 - **A domain** with HTTPS — required for Google OAuth and secure sharing
-- **A reverse proxy** — nginx, Caddy, or similar (recommended)
+- **A reverse proxy** — Caddy, nginx, or similar (recommended)
+
+### Bundled Dependencies
 
-### Optional Dependencies
+- **Mermaid CLI** — bundled as a direct dependency (`@mermaid-js/mermaid-cli`). No separate install needed.
+- **PlantUML jar** — downloaded automatically during `npm install` (via `postinstall` script). Requires Java (JDK 11+) at runtime for local rendering.
 
-- **Java** (JDK 11+) — required for local PlantUML rendering with `!include` support. Without Java, PlantUML falls back to the community server (no `!include` support).
-- **PlantUML jar** — download from [plantuml.com/download](https://plantuml.com/download). Configure the path in `jeeves.config.ts` under `plantuml.jarPath`.
-- **Mermaid CLI** — for server-side Mermaid diagram rendering. Install with `npm install @mermaid-js/mermaid-cli` and configure `mermaidCliPath` in `jeeves.config.ts`.
+## Installation
+
+```bash
+npm install -g @karmaniverous/jeeves-server
+```
+
+Create your config file (see [Setup & Configuration](setup.md)):
+
+```bash
+# Example: JSON config
+cat > /etc/jeeves-server.config.json << 'EOF'
+{
+  "chromePath": "/usr/bin/chromium-browser",
+  "auth": { "modes": ["keys"] },
+  "keys": {
+    "_internal": "your-random-hex-seed",
+    "primary": "another-random-hex-seed"
+  }
+}
+EOF
+```
 
 ## Running the Server
 
 ### Direct
 
 ```bash
-node dist/server.js
+jeeves-server start --config /path/to/jeeves-server.config.json
 ```
 
-The server listens on the port configured in `jeeves.config.ts` (default: 1934) on all interfaces (`0.0.0.0`).
+The server listens on the configured port (default: 1934) on all interfaces.
 
 ### As a Windows Service (NSSM)
 
-[NSSM](https://nssm.cc/) (Non-Sucking Service Manager) turns any executable into a Windows service:
+Use the built-in CLI to generate NSSM install commands:
 
 ```bash
-# Install the service
-nssm install JeevesServer "C:\Program Files\nodejs\node.exe" "E:\jeeves-server\dist\server.js"
-
-# Configure working directory
-nssm set JeevesServer AppDirectory "E:\jeeves-server"
+jeeves-server service install --config "C:\\config\\jeeves-server.config.json"
+```
 
-# Configure stdout/stderr logging
-nssm set JeevesServer AppStdout "E:\jeeves-server\logs\service-stdout.log"
-nssm set JeevesServer AppStderr "E:\jeeves-server\logs\service-stderr.log"
+This prints the `nssm install` commands. Run them, then:
 
-# Start the service
-nssm start JeevesServer
+```bash
+jeeves-server service start
+jeeves-server service stop
+jeeves-server service restart
 ```
 
-**Service management:**
+Or use NSSM directly:
+
 ```bash
+nssm install JeevesServer "C:\\Program Files\\nodejs\\node.exe" "<global-npm-path>\\@karmaniverous\\jeeves-server\\dist\\src\\cli\\index.js" start --config "C:\\config\\jeeves-server.config.json"
+nssm set JeevesServer AppDirectory "<working-dir>"
+nssm set JeevesServer AppStdout "<log-dir>\\service.log"
+nssm set JeevesServer AppStderr "<log-dir>\\service-error.log"
+nssm set JeevesServer Start SERVICE_AUTO_START
 nssm start JeevesServer
-nssm stop JeevesServer
-nssm restart JeevesServer
-nssm status JeevesServer
-nssm remove JeevesServer confirm   # Uninstall
 ```
 
 ### As a systemd Service (Linux)
@@ -66,8 +84,7 @@ After=network.target
 [Service]
 Type=simple
 User=jeeves
-WorkingDirectory=/opt/jeeves-server
-ExecStart=/usr/bin/node /opt/jeeves-server/dist/server.js
+ExecStart=/usr/bin/env jeeves-server start --config /etc/jeeves-server.config.json
 Restart=on-failure
 RestartSec=5
 Environment=NODE_ENV=production
@@ -79,69 +96,11 @@ WantedBy=multi-user.target
 ```bash
 sudo systemctl enable jeeves-server
 sudo systemctl start jeeves-server
-sudo systemctl status jeeves-server
-```
-
-### Linux Quick Start (Ubuntu/Debian)
-
-```bash
-# System packages
-sudo apt-get update && sudo apt-get install -y curl git build-essential chromium-browser caddy
-
-# Node.js 22
-curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
-sudo apt-get install -y nodejs
-
-# Clone and build
-cd /opt
-sudo git clone https://github.com/karmaniverous/jeeves-server.git
-cd jeeves-server
-npm ci
-cd client && npm ci && npx vite build --outDir ../dist/client && cd ..
-npx tsc
-
-# Configure
-cp jeeves.config.template.ts jeeves.config.ts
-# Edit jeeves.config.ts — set chromePath, roots, auth, keys, etc.
-echo '{}' > state.json
-```
-
-**Linux-specific config options:**
-
-```typescript
-{
-  // Chromium path (required for PDF/DOCX export)
-  chromePath: '/usr/bin/chromium-browser',
-
-  // Filesystem roots for the file browser (replaces Windows drive letters)
-  roots: {
-    home: '/home',
-    projects: '/opt/projects',
-  },
-
-  // Mermaid CLI path (optional, for .mmd diagram rendering)
-  mermaidCliPath: '/opt/mermaid-cli',
-}
-```
-
-On Windows, `roots` is ignored — the file browser auto-discovers drive letters. On Linux, if `roots` is omitted, it defaults to `{ root: '/' }`.
-
-**Puppeteer config** (for Chromium on Linux):
-
-Create `puppeteer.json` in the server root:
-```json
-{
-  "executablePath": "/usr/bin/chromium-browser",
-  "args": ["--no-sandbox", "--disable-setuid-sandbox"]
-}
 ```
 
 ## Reverse Proxy
 
-Running behind a reverse proxy is recommended for:
-- **HTTPS termination** — required for Google OAuth and secure key transmission
-- **Domain routing** — serve on a clean domain/subdomain
-- **Rate limiting** and request filtering
+Running behind a reverse proxy is recommended for HTTPS termination, domain routing, and rate limiting.
 
 ### Caddy (simplest)
 
@@ -169,14 +128,7 @@ server {
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header X-Forwarded-Proto $scheme;
-
-        # Large file uploads (for webhook bodies)
         client_max_body_size 10M;
-
-        # WebSocket support (if needed in future)
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
     }
 }
 
@@ -189,99 +141,43 @@ server {
 
 ## HTTPS
 
-**HTTPS is required** when using Google OAuth — Google will not redirect to an HTTP callback URL (except `localhost` for development).
-
-**HTTPS is strongly recommended** even with key-only auth, because keys appear in URL parameters. Without HTTPS, keys are visible to network observers.
-
-### Options
-
-| Method | Effort | Best For |
-|--------|--------|----------|
-| **Caddy** | Minimal | Automatic HTTPS, zero config |
-| **Let's Encrypt + nginx** | Moderate | Fine-grained control |
-| **Cloudflare Tunnel** | Moderate | No port forwarding needed |
-
-## Google OAuth Setup for Production
+**HTTPS is required** when using Google OAuth — Google will not redirect to an HTTP callback URL (except `localhost`).
 
-When using Google OAuth in production:
-
-1. **Add your domain** to the Google Cloud Console OAuth consent screen
-2. **Set the redirect URI** to `https://your-domain.com/auth/google/callback`
-3. **Update `jeeves.config.ts`** with the production credentials
-
-> **Dev vs Prod:** You can use different Google OAuth client IDs for development and production. Each `jeeves.config.ts` is gitignored and instance-specific.
-
-### Multiple environments
-
-Run dev and prod on the same machine using different ports:
-
-```typescript
-// Dev: jeeves.config.ts (port 3457)
-port: 3457,
-auth: {
-  google: {
-    clientId: 'dev-client-id.apps.googleusercontent.com',
-    clientSecret: 'dev-secret',
-  },
-},
-
-// Prod: jeeves.config.ts (port 1934)
-port: 1934,
-auth: {
-  google: {
-    clientId: 'prod-client-id.apps.googleusercontent.com',
-    clientSecret: 'prod-secret',
-  },
-},
-```
-
-Each needs its own Google OAuth redirect URI registered.
+**HTTPS is strongly recommended** even with key-only auth, because keys appear in URL parameters.
 
 ## Health Checks
 
-The `/health` endpoint requires no authentication:
-
 ```bash
+# No auth required
 curl http://localhost:1934/health
-# Returns 200 OK
+
+# Detailed server status (no auth required)
+curl http://localhost:1934/api/status
 ```
 
-Use this for:
-- Load balancer health checks
-- Service monitoring (Uptime Kuma, Prometheus, etc.)
-- NSSM/systemd restart triggers
+The `/api/status` endpoint returns version, uptime, connected services, export capabilities, and event schemas. Add `?events=N` to include the N most recent event log entries. Use `/health` for simple load balancer checks and `/api/status` for monitoring dashboards.
 
 ## Updating
 
 ```bash
-cd /path/to/jeeves-server
-git pull
-
-# Full rebuild
-npm install
-npm run build
-cd client && npx vite build --outDir ../dist/client && cd ..
+# Update the global package
+npm install -g @karmaniverous/jeeves-server@latest
 
 # Restart the service
-nssm restart JeevesServer           # Windows
-sudo systemctl restart jeeves-server # Linux
+jeeves-server service restart    # or: nssm restart JeevesServer / systemctl restart jeeves-server
 ```
 
-> ⚠️ Remember: `npm run build` deletes `dist/` entirely. Always rebuild the client after the server.
-
 ## File Permissions
 
 The server needs:
-- **Read access** to any files you want to serve (drives, directories)
-- **Write access** to its own directory for `state.json` and `logs/`
+- **Read access** to any files you want to serve
+- **Write access** to its working directory for `state.json` and logs
 - **Execute access** to Chrome/Chromium for PDF export
 - **Execute access** to event handler commands
 
 ## Backups
 
 Key files to back up:
-- `jeeves.config.ts` — your configuration (secrets!)
+- Your config file (`jeeves-server.config.json`) — contains secrets
 - `state.json` — insider keys and rotation state
-- `logs/event-queue.jsonl` + `logs/event-queue.cursor` — pending events
-
-The server code itself is in git — no need to back up `dist/` or `node_modules/`.
+- Event queue files — `logs/event-queue.jsonl` + `logs/event-queue.cursor`

package/guides/event-gateway.md

@@ -8,37 +8,32 @@ Jeeves Server includes a webhook gateway that receives HTTP POST requests, valid
 
 ## Configuration
 
-Events are defined in `jeeves.config.ts`:
-
-```typescript
-events: {
-  'notion-page-update': {
-    // JSON Schema matched against the incoming POST body
-    schema: {
-      type: 'object',
-      properties: {
-        type: { const: 'page.content_updated' },
-      },
-      required: ['type'],
-    },
-
-    // Shell command to execute when matched
-    cmd: 'node /path/to/handler.js',
+Events are defined in your config file:
 
-    // Optional: transform the body before passing to the command
-    map: {
-      pageId: {
-        '$': { method: '$.lib._.get', params: ['$.input', 'data.page_id'] },
+```json
+{
+  "events": {
+    "notion-page-update": {
+      "schema": {
+        "type": "object",
+        "properties": {
+          "type": { "const": "page.content_updated" }
+        },
+        "required": ["type"]
       },
-      type: {
-        '$': { method: '$.lib._.get', params: ['$.input', 'type'] },
+      "cmd": "node /path/to/handler.js",
+      "map": {
+        "pageId": {
+          "$": { "method": "$.lib._.get", "params": ["$.input", "data.page_id"] }
+        },
+        "type": {
+          "$": { "method": "$.lib._.get", "params": ["$.input", "type"] }
+        }
       },
-    },
-
-    // Optional: override default timeout (ms)
-    timeoutMs: 60000,
-  },
-},
+      "timeoutMs": 60000
+    }
+  }
+}
 ```
 
 ### Schema matching
@@ -68,15 +63,15 @@ When `map` is omitted, the full webhook body is passed as-is.
 
 **Example — Notion sends a large payload, we extract just two fields:**
 
-```typescript
-map: {
-  pageId: {
-    '$': { method: '$.lib._.get', params: ['$.input', 'data.page_id'] },
-  },
-  type: {
-    '$': { method: '$.lib._.get', params: ['$.input', 'type'] },
+```json
+{
+  "pageId": {
+    "$": { "method": "$.lib._.get", "params": ["$.input", "data.page_id"] }
   },
-},
+  "type": {
+    "$": { "method": "$.lib._.get", "params": ["$.input", "type"] }
+  }
+}
 ```
 
 Input: `{ type: "page.content_updated", data: { page_id: "abc123", ... } }`
@@ -86,13 +81,15 @@ Output to command: `{ pageId: "abc123", type: "page.content_updated" }`
 
 Webhook callers must authenticate with a key that has scope access to `/event`:
 
-```typescript
-keys: {
-  'webhook-notion': {
-    key: 'random-seed-string',
-    scopes: ['/event'],
-  },
-},
+```json
+{
+  "keys": {
+    "webhook-notion": {
+      "key": "random-seed-string",
+      "scopes": ["/event"]
+    }
+  }
+}
 ```
 
 Your config contains a **seed** — a secret string that never leaves the server. The actual URL key is **derived** from the seed by the server. To get it:
@@ -171,16 +168,26 @@ process.stdin.on('end', () => {
 
 ## Global Settings
 
-```typescript
-// Default timeout for all event commands (ms)
-eventTimeoutMs: 30_000,
-
-// Purge log entries older than this (ms). Default: 30 days
-eventLogPurgeMs: 2_592_000_000,
+```json
+{
+  "eventTimeoutMs": 30000,
+  "eventLogPurgeMs": 2592000000
+}
 ```
 
 ## Monitoring
 
+### Via API
+
+```bash
+# Get 20 most recent event log entries (no auth required)
+curl http://localhost:1934/api/status?events=20
+```
+
+The `eventLog` array in the response contains entries newest-first, each with `ts`, `event`, `matched`, `exitCode`, and `durationMs`.
+
+### Via log files
+
 Check the event log for failures:
 
 ```bash
@@ -193,7 +200,7 @@ grep '"matched":false' logs/event-log.jsonl
 
 ## Example: Notion Webhook Integration
 
-1. **Configure the event** in `jeeves.config.ts` (see Configuration above)
+1. **Configure the event** in `your config file` (see Configuration above)
 2. **Create a scoped key** for the webhook
 3. **Register the webhook URL** in Notion:
    - Settings → Connections → Add a connection

package/guides/exports.md

@@ -62,14 +62,16 @@ PDF generation uses [**Puppeteer**](https://github.com/puppeteer/puppeteer) with
 ### Requirements
 
 - **Chrome/Chromium** must be installed on the server
-- **`chromePath`** must point to the executable in `jeeves.config.ts`
+- **`chromePath`** must point to the executable in `your config file`
 - **`_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
-},
+```json
+{
+  "chromePath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+  "keys": {
+    "_internal": "random-seed-string"
+  }
+}
 ```
 
 ### What you see is what you get
@@ -111,13 +113,7 @@ Mermaid diagrams (`.mmd` files) can be exported as SVG, PNG, or PDF via the [Mer
 
 ### 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',
-```
+Mermaid CLI is bundled as a direct dependency (`@mermaid-js/mermaid-cli`) — no separate installation or configuration needed. Chrome/Chromium is required for rendering.
 
 ### Export endpoint
 
@@ -139,12 +135,14 @@ PlantUML uses a **fallback rendering pipeline** — each method is tried in orde
 
 ### 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)
-},
+```json
+{
+  "plantuml": {
+    "jarPath": "/opt/plantuml/plantuml.jar",
+    "javaPath": "/usr/bin/java",
+    "servers": ["https://internal.plantuml.example.com/plantuml"]
+  }
+}
 ```
 
 If `plantuml` is omitted entirely, only the public community server is used.
@@ -219,7 +217,7 @@ Directories can be downloaded as ZIP archives. The header shows a ZIP download o
 
 The `maxZipSizeMb` config setting (default: 100 MB) prevents accidentally zipping enormous directories:
 
-```typescript
+```
 maxZipSizeMb: 100,  // Refuse ZIP for directories larger than this
 ```
 

package/guides/index.md

@@ -0,0 +1,21 @@
+---
+title: Service Guides
+children:
+  - ./setup.md
+  - ./sharing.md
+  - ./exports.md
+  - ./event-gateway.md
+  - ./deployment.md
+  - ./api-integration.md
+  - ../CHANGELOG.md
+---
+
+# Service Guides
+
+- [Setup & Configuration](./setup.md) — Installation, auth modes, cosmiconfig, named scopes, and config reference.
+- [Insiders, Outsiders & Sharing](./sharing.md) — The access model, HMAC key derivation, expiring links, and key rotation.
+- [Exporting & Downloads](./exports.md) — PDF, DOCX, SVG, PNG, and ZIP export via Puppeteer and bundled Mermaid/PlantUML.
+- [Event Gateway](./event-gateway.md) — Webhook receiving, JSON Schema matching, JsonMap body transforms, and durable queue processing.
+- [Deployment](./deployment.md) — Running as a service (NSSM/systemd), reverse proxy setup, HTTPS, and updates.
+- [API & Integration](./api-integration.md) — Endpoint reference, Windows path conversion, share link generation, and AI assistant usage.
+- [Changelog](../CHANGELOG.md) — Release history for `@karmaniverous/jeeves-server`.