From 42733b4799c2fdf6467adf9eb8cdd33b4e7053cb Mon Sep 17 00:00:00 2001 From: Schwitzz Date: Fri, 30 Oct 2026 13:49:15 -0500 Subject: [PATCH] docs: update README with release installation instructions and remove development progress status --- Features and Bugs.txt | 24 ------- PLAN.md | 60 ++++------------ README.md | 164 +++++++++++++++++++++++++++++++++++------- 3 files changed, 154 insertions(+), 94 deletions(-) delete mode 100644 Features and Bugs.txt diff --git a/Features and Bugs.txt b/Features and Bugs.txt deleted file mode 100644 index 0adaf30..0000000 --- a/Features and Bugs.txt +++ /dev/null @@ -1,24 +0,0 @@ -Features and Bugs: -1. (bug) - Whiteboard. Clicking add > Character and add > World leads to blank screen. -2. (bug) - Whiteboard. Nodes are not dragging. -3. (bug) - Whiteboard. Nodes cannot be edited after placement. -4. (bug) - connecting lines cannot be deleted. -5. (bug) - There are no AI settings to set up provider, edit agents, set temp/ctx/prompts, etc. -6. (feature) - AI.Make AI chat window a sidebar that can be toggled. Include provider, model, archived chats, agent, and load/reload button. -7. (feature) - AI. make navigation a sidebar with toggle. Untoggled will hid all but the icons. -8. (feature) - Write. Needs microsoft word-like formatting features. Line spacing, bold, italics, justification, etc. The whole formatting suite. Reference open source software like Only Office for an example. Favor icons over text buttons. -9. (feature) - All. Change the persistent "PubScript" + icon to the logo. Remove PS logo on the other persistent header. -10. (feature) - Entities. Revise the "+ New" flow. Use an add button on the individual tabs, not catch all new with drop down. -11. (bug) - Plot. Dragging beats deletes them. -12. (feature) - Plot. remove + Add Beat button. Redundant, keep the + on each Act. -13. (bug) - Projects. Clicking in this page does nothing. Cannot add new project. Cannot open existing project. Cannot delete projects. -14. (feature) - Projects. Adding new project should open up a tutorial to draft a template. Ask pertinent questions about the writing to help user determine what kind of Act/Beat methodology to use. Also create option to skip tutorial and build skeleton of project manually. -15. (bug) - Settings. Theme buttons do nothing to change theme. Some theme buttons are invisible. Remove persistent theme drop down. Use the theme dropdown in the settings. -16. (bug) - Settings. Density selections change nothing. -17. (feature) - Settings. Need many more fonts. -18. (bug) - Settings. Typography settings change UI elements. Use system Sans for UI, lock it in. Let the typography settings be managed on the writing screen with the formatting / toolbar (see item 8). -19. (bug) - Settings. Show line numbers does not work. Remove from settings, add to write toolbar. -20. (bug) - Settings. Focus and Typewrite mode do nothing. Same if toggeld from the write screen. Remove Typewrite feature, it's dumb. -21. (feature) - Persistent. Search feature should be a text box. remove hotkey reference. -22. (bug) - Admin. Admin features not working. No users. No ability to manage useres. Screen shows "Unexpected token '<', " This file is the single source of truth for *what* we are building and *why*. -> The `CHUNK#n.md` files are the executable, step-by-step work orders for *how*. -> A human and a strictly-instructed coding agent can both follow them. +> This file is the single source of truth for the architecture, design decisions, and data model of PubScript. --- @@ -89,24 +87,23 @@ The **StorageAdapter contract** (defined once in `packages/core`) is the seam th ``` PubScript/ -├── PLAN.md ← this file -├── CHUNK#1.md … CHUNK#11.md ← executable work orders +├── PLAN.md ← architecture & design specification +├── README.md ← installation, quickstart & usage guide ├── package.json ← pnpm workspace root ├── pnpm-workspace.yaml ├── apps/ -│ └── web/ ← the React 19 app (Vite). Runs in browser AND in Tauri. -├── desktop/ ← Tauri 2 shell (Rust). Loads apps/web's build. +│ └── web/ ← the React 19 app (Vite) +├── desktop/ ← Native Linux desktop shell & .deb packager ├── packages/ │ ├── core/ ← domain types, IDs, time, token budget, StorageAdapter contract │ ├── ui/ ← design tokens, theme engine, app shell, component kit │ ├── editor/ ← TipTap schema, decorations, spellcheck integration -│ ├── boards/ ← React Flow whiteboard, beat board, timeline │ ├── exporters/ ← md / html / epub / docx / odt / pdf + shared flat model │ └── ai/ ← provider adapters, role engine, context builder, suggestion protocol ├── server/ ← Fastify + SQLite: auth, multi-tenant, WS, admin, AI proxy -├── docker/ ← Dockerfile, compose.yaml, entrypoint, backup scripts -├── .github/workflows/ ← CI (lint, typecheck, test, build, docker, desktop matrix) -└── docs/ ← ADRs, data model reference, AI role prompts, parity matrix +├── docker/ ← Dockerfile, compose.yaml, entrypoint +├── .github/workflows/ ← CI (lint, typecheck, test, contract, build, docker) +└── docs/ ← Data model reference & conventions ``` ### 3.3 Data model (core domain) @@ -261,41 +258,12 @@ Desktop adds: native file-system access (open/save anywhere), system print-to-PD --- -## 9. Execution Plan — the chunks - -Each chunk is a 1–3 day work order in `CHUNK#n.md`, written so a human *or* a strictly-instructed coding agent can execute it top-to-bottom. Each has prerequisites, numbered steps with exact paths/commands, and testable acceptance criteria. - -| # | Chunk | ~Days | Status | Delivers | -|---|---|---|---|---| -| 1 | **Scaffold & Foundations** | 1 | ✅ Done | Monorepo, strict TS, tooling, app shell, theme system, CI, settings store | -| 2 | **Data Model, Storage & Auth** | 3 | ✅ Done | Full domain types, StorageAdapter, Local + Server adapters, Fastify auth/multi-tenant, autosave, contract tests | -| 3 | **Writing Surface** | 3 | ✅ Done | TipTap editor ✅, document tree ✅, focus mode ✅, Markdown I/O ✅, autosave ✅, writing view wired to storage adapter ✅, fonts/logo ✅ | -| 4 | **Characters & World-Building** | 2 | ✅ Done | Entity schema ✅, character sheets ✅, world items ✅, fuzzy search ✅, mentions ✅, backlinks ✅, entity UI (sheets/search/relationships/map) ✅, consistency UI ✅, palette search ✅, context rail ✅, seed extension ✅, DATA_MODEL.md ✅ | -| 5 | **Plot & Whiteboard** | 3 | ✅ Done | Beat board + templates ✅, timeline ✅, React Flow whiteboard ✅, cross-links ✅, status/locking ✅, progress bar ✅ | -| 6 | **Export Pipeline** | 3 | ✅ Done | MD/HTML/EPUB/DOCX/ODT + PDF, export dialog, CI validation | -| 7 | **Spell & Grammar** | 2 | ✅ Done | hunspell-WASM spellcheck, LanguageTool grammar, decorations + panel | -| 8 | **AI Provider Layer** | 2 | ✅ Done | Provider config + discovery, streaming, thinking params, token budget | - | 9 | **AI Roles & Suggestions** | 3 | ✅ Done | Editor/Reader/Publisher/Co-Author, context builder, tools, accept/reject/pin in `packages/ai`, AI Settings (providers/agents/temp/ctx/prompts), and toggleable `AISidebar` (`apps/web/src/features/ai/AISidebar.tsx`) | -| 10 | **Multi-User Admin & Sharing** | 2 | ✅ Done | Admin API, roles, project sharing, audit, multi-tenant isolation in `server/`, plus full `AdminView` web UI (`apps/web/src/features/admin/AdminView.tsx`) | -| 11 | **Packaging, Parity & Polish** | 3 | ✅ Web + Docker + Onboarding done | Docker compose ✅, Project & Template Tutorial Wizard ✅, formatting ribbon & theme/density polish ✅ | - -**Total: ~27 focused working days**, sequenced so each chunk is independently shippable and testable. - -**Progress:** Chunks #1–#8 are complete and CI-green; #9 and #10 have their full backend/protocol layer implemented and tested but their web UI is still a stub; #11 has Docker done and the rest not started. CHUNK #1 is built and CI-green (`pnpm typecheck`, `pnpm test`, `pnpm lint`, `pnpm build` all pass; `pnpm dev` serves the themed app shell). CHUNKs #2–#7 are committed and CI-green. CHUNK #4's data layer (entity schema, fuzzy search, backlinks, consistency check, `@mention` autocomplete) and entity UI layer (character/world sheets, fuzzy search, relationship editor + map, consistency UI, palette search, context rail, seed extension, `docs/DATA_MODEL.md`) are all built and green. CHUNK #5 delivers the plot & whiteboard surface: a beat board with genre templates (Three-Act, Save-the-Cat, Seven-Point, Custom), status/locking and a progress bar, a filterable timeline, and a React Flow 11 whiteboard with chapter/entity cross-links and an "Add beats to board" import. CHUNK #6 delivers the export pipeline: a shared flat model feeding Markdown, single-file HTML, EPUB 3, DOCX, ODT, and PDF exporters, plus an ExportDialog and golden-file + round-trip tests with deterministic ZIP/PDF metadata. CHUNK #7 delivers offline spellcheck (hunspell compiled to WASM, runs fully in-browser) and optional self-hostable LanguageTool grammar/style checking, rendered as inline red/blue squiggles with a side panel to jump/apply/ignore/add-to-dictionary; dictionaries are base64-decoded browser-safe (atob + TextDecoder), spell + grammar hits merge into a single decoration pipeline, and a docker compose snippet runs LanguageTool opt-in. Remaining chunk-level items (Playwright E2E + 200-node perf tests) are blocked on E2E infrastructure that is not yet in the repo; unit + contract tests cover the new logic. - ---- - -## 10. Risks & Mitigations +## 9. Risks & Mitigations | Risk | Mitigation | |---|---| -| Tauri cross-OS packaging friction (esp. macOS notarization) | Linux-first; treat Windows as a CI matrix; macOS notarization is explicit later polish, not a v1 blocker | -| Large-document editor performance | ProseMirror is built for this; we add perf budgets + Playwright timing tests and keep decorations memoized | -| AI suggestion rendering over live-editing text (range drift) | Suggestions carry stable node anchors, not raw offsets; re-resolved on every transaction | -| Local vs. server data divergence | Contract test suite enforces identical behavior; local mode is clearly labeled in the UI | -| EPUB/ODT spec edge cases | Golden-file tests + `epubcheck` in CI; DOCX via the maintained `docx` package | -| Scope creep in AI roles | Roles are prompt + tools, not new UI surfaces; the suggestion protocol is the single integration point | - ---- - -*Status (verified Oct 2026): Chunks #1–#10 are complete and CI-green (`pnpm typecheck`, `pnpm test`, `pnpm lint`, `pnpm build` all pass; `pnpm dev` serves the app shell on `:5173`; the API server runs on `:8081`). Both the AI Studio toggleable sidebar + provider/agent settings (`AISidebar.tsx`, `Settings.tsx`) and the Admin user/audit management UI (`AdminView.tsx`) are wired and verified. Chunk #11 has Docker packaging, the guided project/template onboarding wizard, OnlyOffice-style formatting toolbar, and theme/density/typography polish complete.* +| Large-document editor performance | ProseMirror is built for this; decorations and spellcheck runs are debounced and block-scoped | +| AI suggestion rendering over live-editing text (range drift) | Suggestions carry verbatim text anchors (`originalText`), re-resolved on inline edits | +| Local vs. server data divergence | Contract test suite enforces identical behavior across `LocalAdapter` and `ServerAdapter` | +| EPUB/ODT spec edge cases | Golden-file tests in CI; deterministic timestamps across ZIP/PDF formats | +| Scope creep in AI roles | Roles are prompt + tools, unified under a single inline suggestion and session notes protocol | diff --git a/README.md b/README.md index 3d52ace..c550045 100644 --- a/README.md +++ b/README.md @@ -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.