Schwitzz
159 lines
7.7 KiB
Markdown
159 lines
7.7 KiB
Markdown
# PubScript
|
||
|
||
**A self-hostable, multi-user writing studio for novelists — one codebase that runs as a web application and as a native Linux desktop application, with a local-first AI co-writing engine built in.**
|
||
|
||
---
|
||
|
||
## Key Features
|
||
|
||
- **Manuscript Writing Studio**: Rich-text manuscript editor powered by TipTap 3 with an OnlyOffice/Word-inspired formatting ribbon, **34 curated typography options** (serif, display, sans-serif, and monospace), adjustable font sizes, line spacing, column width, first-line paragraph indentation, scene breaks (`* * *`), footnotes, `@` character mentions, line numbers, and a distraction-free **Focus Mode** (`F2`).
|
||
- **Autosave & Revision History**: Continuous background autosave with per-chapter revision snapshots (`rev #1`, `rev #2`, …) and one-click revision restore directly from the sidebar or context rail.
|
||
- **Offline Spell & Grammar Checking**: Browser-safe Hunspell WebAssembly spellchecker + built-in prose grammar/style checks with inline squiggles and instant replacement popovers.
|
||
- **AI Co-Writing Studio**:
|
||
- First-class support for local AI servers (**Ollama**, **llama.cpp**, **LM Studio**, any OpenAI-compatible endpoint) alongside **OpenAI**, **Anthropic**, **Google Gemini**, and **OpenRouter**.
|
||
- Configurable role agents (**Editor**, **Reader**, **Publisher**, **Co-Author**, or custom agents) with per-agent system prompts, temperature, context window (`ctx`), max output tokens, and extended thinking/reasoning controls.
|
||
- **Granular Text-Anchored Inline Suggestions**: Suggestions peg directly to verbatim phrases, clauses, and sentences in your manuscript. Stepping through suggestions highlights the exact span in the editor (`Accept` applies the edit in place and advances to the next suggestion; `Deny` dismisses it; `Copy to Note` moves it to session notes).
|
||
- Resizable AI sidebar (with snap-to-default `370px`), live thinking indicator, and non-intrusive context usage & throughput (`t/s`) telemetry.
|
||
- **Story Structure, World-Building & Whiteboard**:
|
||
- **Guided Story Structure Wizard**: Interactive project setup recommending **Save the Cat! (15 Beats)**, **Three-Act Structure**, **Seven-Point Story Structure**, or **Custom / Discovery** templates.
|
||
- **Entities & Lore**: Dedicated views for **People**, **Places & World**, and **Notes** with automatic backlink tracking across chapters.
|
||
- **Plot Beats & Interactive Whiteboard**: Drag-and-drop Act I–III plot beat cards and a ReactFlow canvas for mapping chapters, characters, world items, and custom connection lines.
|
||
- **Publishing-Grade Manuscript Export**: Deterministic export to **Markdown (`.md`)**, **HTML (`.html`)**, **EPUB 3 (`.epub`)**, **DOCX (`.docx`)**, **ODT (`.odt`)**, and **Print-Ready PDF (`.pdf`)**.
|
||
- **Multi-User Administration**: Built-in Admin console for user creation, role assignment (`Author` / `Admin`), account enable/disable, instance statistics, and filterable audit logs.
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
### Option 1: Linux Desktop Application (`.deb` — Ubuntu / Debian / Linux Mint)
|
||
|
||
Download `pubscript_0.1.0_amd64.deb` from the [GitHub Releases](https://github.com/Schwitzz/PubScript/releases) page (or build it from source using `pnpm package:deb`), then install it with `apt` or `dpkg`:
|
||
|
||
```bash
|
||
# Install using apt (automatically resolves any missing system dependencies)
|
||
sudo apt install ./pubscript_0.1.0_amd64.deb
|
||
|
||
# Or install directly with dpkg
|
||
sudo dpkg -i pubscript_0.1.0_amd64.deb
|
||
```
|
||
|
||
Launch **PubScript** from your desktop application menu or from a terminal:
|
||
|
||
```bash
|
||
pubscript
|
||
```
|
||
|
||
- **Desktop Data Directory**: `~/.local/share/pubscript/` (contains `pubscript.sqlite` and persistent WebKit `IndexedDB` / `localStorage` data).
|
||
- **Uninstall**: `sudo apt remove pubscript`
|
||
|
||
---
|
||
|
||
### Option 2: Self-Hosted Docker Deployment (Recommended for Web & Multi-User)
|
||
|
||
A single container builds and serves the production web application, runs the Fastify REST + WebSocket API, and persists SQLite data on a mounted volume.
|
||
|
||
```bash
|
||
git clone https://github.com/Schwitzz/PubScript.git
|
||
cd PubScript
|
||
docker compose -f docker/compose.yaml up -d --build
|
||
```
|
||
|
||
- **Web App & API**: `http://localhost:8080`
|
||
- **Health Check**: `curl http://localhost:8080/api/health`
|
||
- **Persistent Data**: Stored in `./data/pubscript.sqlite` on the host.
|
||
|
||
#### Environment Variables (`docker/compose.yaml`)
|
||
|
||
| Variable | Default | Description |
|
||
|---|---|---|
|
||
| `PORT` | `8080` | HTTP port inside the container |
|
||
| `PUBSCRIPT_DB` | `/app/data/pubscript.sqlite` | Path to the SQLite database file |
|
||
| `PUBSCRIPT_ADMIN_EMAIL` | `admin@pubscript.local` | Bootstrap administrator email |
|
||
| `PUBSCRIPT_ORIGIN` | `http://localhost:8080` | Allowed CORS origin |
|
||
| `PUBSCRIPT_TOKEN_TTL` | `2592000` (30 days) | Session token lifetime in seconds |
|
||
|
||
---
|
||
|
||
### Option 3: Build & Run from Source
|
||
|
||
#### Prerequisites
|
||
|
||
- **Node.js** `>= 22`
|
||
- **pnpm** `9.15.9` (`corepack enable && corepack prepare pnpm@9.15.9 --activate`)
|
||
- Build tools for native SQLite/Argon2 bindings (`python3`, `make`, `g++`)
|
||
- *(Optional, for building the Linux `.deb` desktop package)*: `dpkg-deb`, `gcc`, `pkg-config`, `libgtk-3-dev`, `libwebkit2gtk-4.1-0`
|
||
|
||
#### 1. Install Dependencies
|
||
|
||
```bash
|
||
git clone https://github.com/Schwitzz/PubScript.git
|
||
cd PubScript
|
||
pnpm install --frozen-lockfile
|
||
```
|
||
|
||
#### 2. Run in Development Mode
|
||
|
||
Start the API server (`:8081`) and Vite web dev server (`:5173`):
|
||
|
||
```bash
|
||
# Terminal 1 — Fastify + SQLite API Server (port 8081)
|
||
PORT=8081 PUBSCRIPT_ORIGIN=http://localhost:5173 pnpm --filter @pubscript/server dev
|
||
|
||
# Terminal 2 — Vite React Web App (port 5173, proxies /api and /ws to :8081)
|
||
pnpm --filter @pubscript/web dev
|
||
```
|
||
|
||
Open **`http://localhost:5173`** in your browser.
|
||
|
||
#### 3. Build for Production
|
||
|
||
```bash
|
||
pnpm build
|
||
PORT=8080 pnpm --filter @pubscript/server start
|
||
```
|
||
|
||
When `apps/web/dist` is built, the server automatically serves both the production web bundle and the `/api` endpoints on `http://localhost:8080`.
|
||
|
||
#### 4. Compile the Native Linux `.deb` Desktop Package
|
||
|
||
```bash
|
||
pnpm package:deb
|
||
```
|
||
|
||
Produces `dist/pubscript_0.1.0_amd64.deb` (and `./pubscript_0.1.0_amd64.deb` in the repository root).
|
||
|
||
---
|
||
|
||
## Verification & Quality Gates
|
||
|
||
```bash
|
||
pnpm typecheck # Strict TypeScript check across all workspace packages
|
||
pnpm test # Unit & integration test suites across all packages
|
||
pnpm contract # StorageAdapter contract suite (Local + Server parity)
|
||
pnpm lint # ESLint across all packages
|
||
pnpm build # Production bundle build
|
||
```
|
||
|
||
---
|
||
|
||
## Repository Layout
|
||
|
||
| Path | Description |
|
||
|---|---|
|
||
| `apps/web/` | React 19 + Vite application (Writing Studio, AI Sidebar, Characters, World, Plot, Whiteboard, Admin, Settings) |
|
||
| `packages/core/` | Shared domain types, ULIDs, token budgeting, backlinks, consistency engine, `StorageAdapter` contract |
|
||
| `packages/editor/` | TipTap 3 / ProseMirror schema, formatting extensions, node views, Markdown serializer, Hunspell spell & grammar services |
|
||
| `packages/ai/` | AI provider client, SSE streaming, token budget enforcement, Dexie/IndexedDB session store, suggestion & note builders |
|
||
| `packages/exporters/` | Deterministic manuscript exporters (`Markdown`, `HTML`, `EPUB`, `DOCX`, `ODT`, `PDF`) |
|
||
| `packages/ui/` | Design tokens, theme engine (`Ink`, `Parchment`, `Nocturne`, `Terminal`), density engine, UI component kit |
|
||
| `server/` | Fastify + SQLite multi-tenant API server, authentication, WebSocket sync, and admin routes |
|
||
| `desktop/` | Native Linux GTK3 + WebKit2GTK desktop wrapper (`pubscript-desktop.c`) and `.deb` packager (`build-deb.sh`) |
|
||
| `docker/` | Multi-stage `Dockerfile`, `compose.yaml`, and container entrypoint |
|
||
| `docs/` | Architecture & data model documentation (`DATA_MODEL.md`, `CONVENTIONS.md`) |
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
Licensed under the **GNU General Public License v3.0** — see [LICENSE](./LICENSE) for details.
|