Schwitz/PubScript
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

docs: update README with release installation instructions and remove development progress status

Browse Source
This commit is contained in:
Schwitzz
2026-10-30 13:49:15 -05:00
parent 053cc07294
commit 42733b4799
3 changed files with 154 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+140 -24
View File
@@ -1,42 +1,158 @@
# PubScript
A self-hostable, multi-user writing studio for novelists — one codebase that runs as a web app and as a native desktop app, with a local-first AI co-writing engine built in.
**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.**
See **[PLAN.md](./PLAN.md)** for the full vision, architecture, and data model. The `CHUNK#n.md` files are the executable work orders.
---
## Quickstart
## 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
pnpm i && pnpm dev # run the app shell at http://localhost:5173
pnpm test # run every workspace's unit tests
pnpm typecheck # strict TypeScript across the monorepo
pnpm build # build web + server
# 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
```
## Docker (self-host)
Launch **PubScript** from your desktop application menu or from a terminal:
```bash
docker compose -f docker/compose.yaml up --build
# → http://localhost:8080 (health: curl localhost:8080/api/health)
pubscript
```
One container serves the web app, runs the Fastify API, and stores SQLite on a volume.
- **Desktop Data Directory**: `~/.local/share/pubscript/` (contains `pubscript.sqlite` and persistent WebKit `IndexedDB` / `localStorage` data).
- **Uninstall**: `sudo apt remove pubscript`
## Repository layout
---
| Path | What it is |
### 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 |
|---|---|
| `PLAN.md` | Single source of truth for *what* and *why* |
| `CHUNK#n.md` | Executable, step-by-step work orders |
| `apps/web/` | React 19 + Vite app (runs in browser AND in Tauri) |
| `packages/core/` | Domain types, ULIDs, time, token budget, `StorageAdapter` contract |
| `packages/ui/` | Design tokens, theme engine (Ink / Parchment / Nocturne / Terminal), component kit |
| `server/` | Fastify + SQLite: auth, multi-tenant, WS, admin, AI proxy |
| `docker/` | Dockerfile + compose (one container serves app + API + data) |
| `docs/` | ADRs, data model reference, AI role prompts, parity matrix |
| `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`) |
## Status
---
**CHUNK #1 through #10 are complete and CI-green:** the monorepo with strict TypeScript, the collapsible app shell and theming/density system, the `packages/core` contracts, the Fastify multi-tenant server, the TipTap writing surface with an OnlyOffice/Word-inspired formatting toolbar (34 fonts, line numbers, focus mode, alignment, indentation, lists, scene breaks, footnotes), characters & world-building, the plot & whiteboard surface, the export pipeline (Markdown/HTML/EPUB/DOCX/ODT/PDF with an ExportDialog), offline hunspell-WASM spellcheck + grammar checking, the AI provider & agent layer (`packages/ai`) with full AI Settings and toggleable AI Chat Sidebar (`AISidebar.tsx`), the guided Project Structure Tutorial Wizard (`Projects.tsx`), and the Admin user/role/audit management interface (`AdminView.tsx`). `pnpm typecheck`, `pnpm test`, `pnpm lint`, and `pnpm build` all pass across the workspace.
## License
**CHUNK #11 (Packaging, Parity & Polish)** has Docker packaging (`docker/compose.yaml`), project template onboarding, and UI/UX polish complete.
Licensed under the **GNU General Public License v3.0** — see [LICENSE](./LICENSE) for details.