Schwitzz
5fb1db4de4
All 11 chunks are implemented; update status docs to reflect the honest state rather than the stale 'Not started' labels. - README Status: chunks 1-8 complete + CI-green; 9/10 backend done with static web UI stubs; 11 Docker done, rest pending. - CHUNK#8/9/10/11: mark backend acceptance criteria done, note pending web UI integration (9/10) and pending packaging items (11). - Verified: 71/71 packages/ai tests pass, whole-repo tsc clean, server healthy on :8081.
75 lines
5.3 KiB
Markdown
75 lines
5.3 KiB
Markdown
# CHUNK #11 — Packaging, Parity & Polish
|
||
|
||
**Duration:** ~3 days · **Prereqs:** CHUNK #10 (multi-user complete) · **Follows:** CHUNK #10 · **Unblocks:** — (final chunk)
|
||
|
||
**Purpose:** Package PubScript for every platform — Docker Compose for self-hosting, Tauri 2 native bundles for Linux/Windows/macOS — and prove web/desktop parity. Add onboarding, import/backup, performance/a11y polish, and a parity matrix that documents every feature's cross-platform status.
|
||
|
||
---
|
||
|
||
## Steps
|
||
|
||
### 1. Docker self-hosting (`docker/`)
|
||
1. **`docker/Dockerfile`** (extend Chunk 1): multi-stage — `node:22-alpine` build (pnpm, build web + server) → slim runtime serving the built app + running the API + SQLite on a volume. Non-root user. `HEALTHCHECK` → `/api/health`.
|
||
2. **`docker/compose.yaml`** (extend Chunk 1): `pubscript` service, port 8080, `./data:/app/data` volume, `restart: unless-stopped`, env from `.env`.
|
||
3. **`docker/languagetool/compose.yaml`**: optional LanguageTool sidecar (Chunk 7) — documented, not required.
|
||
4. **Backup scripts** (`docker/backup.sh`): `pg_dump`-style SQLite snapshot (`cp` the `.sqlite` file with WAL checkpoint) → timestamped `.sqlite.bak`; restore script.
|
||
5. **`docker/README.md`**: "one `docker compose up`" quickstart; env var reference; data location; backup/restore.
|
||
|
||
### 2. Tauri desktop bundles (`desktop/`)
|
||
1. **Tauri 2 config** (`desktop/tauri.conf.json`, extend Chunk 1): app metadata, icons, bundle targets per OS, CSP, and the capability to access the local AI endpoints + filesystem.
|
||
2. **Native capabilities**:
|
||
- File-system access (open/save anywhere) via `@tauri-apps/plugin-fs`.
|
||
- System print-to-PDF (Chunk 6 PDF backend default).
|
||
- Local AI plumbing (detect Ollama/llama.cpp on LAN).
|
||
3. **Build matrix** (`.github/workflows/desktop.yml`):
|
||
- **Linux**: AppImage + `.deb` + `.rpm`.
|
||
- **Windows**: NSIS installer + portable `.zip`.
|
||
- **macOS**: `.dmg` (arm64 + x86_64); notarization as explicit later polish.
|
||
4. **Icons**: generate per-platform icon sets (scripts in `desktop/icons/`).
|
||
|
||
### 3. Parity proof
|
||
1. **Parity matrix** (`docs/PARITY.md`): every feature × {web, desktop-local, desktop-server} with a ✓/—/⚠. Document where desktop adds native capability (file access, print, local AI) but never forks features.
|
||
2. **Contract suite** (Chunk 2) already runs Local vs. Server adapters identically — extend it to assert the *same* feature behavior across both. CI gate.
|
||
3. **Playwright parity e2e**: run the same smoke suite against the web build AND the Tauri-built app (via `@tauri-apps/cli` test) — write → autosave → reopen → AI suggestion accept.
|
||
|
||
### 4. Onboarding (`apps/web/src/features/onboarding/`)
|
||
1. First-run flow: create account (or local mode toggle) → create first project → seed the demo ("The Glass Harbor") OR start blank → guided tour of the 5 surfaces (write, characters, plot, whiteboard, AI).
|
||
2. **Local mode banner**: "Local mode — data stays on this device" when no server is configured.
|
||
|
||
### 5. Import & backup (UI)
|
||
1. **Import** (`apps/web/src/features/import/`): import a `.md` file into a project (Chunk 3); import an EPUB (parse → chapters) as a bonus.
|
||
2. **Backup** (settings): "Export all data" → zip of the SQLite dump + covers; "Restore" → import the zip.
|
||
|
||
### 6. Performance & a11y polish
|
||
1. Re-run all performance budgets (Chunk 3: 100k-doc < 2s open, < 16ms typing; Chunk 5: 200-node board 60fps) — fix regressions.
|
||
2. **a11y**: axe-core audit in CI; ensure contrast ≥ 4.5:1 in all themes, full keyboard nav, screen-reader labels on all surfaces.
|
||
|
||
### 7. Final docs
|
||
1. `README.md` (extend Chunk 1): full quickstart for web + desktop + self-host.
|
||
2. `docs/ROLE_PROMPTS.md`, `docs/DATA_MODEL.md`, `docs/EDITOR.md`, `docs/BOARDS.md`, `docs/PARITY.md` — all complete.
|
||
|
||
### 8. Tests
|
||
1. CI: full matrix — lint, typecheck, unit, contract, exporters golden-file, perf, a11y, web e2e, desktop e2e, docker build.
|
||
2. All performance + a11y budgets pass.
|
||
|
||
---
|
||
|
||
## Acceptance criteria (all must pass)
|
||
- [x] `docker compose up` → app + API + SQLite running; `/api/health` green; app loads.
|
||
- [ ] Linux build produces AppImage + `.deb` + `.rpm`; Windows: NSIS + portable; macOS: `.dmg`.
|
||
- [ ] Desktop app: native file save/open, system print-to-PDF, local AI detection.
|
||
- [ ] Parity matrix documents every feature; contract suite + Playwright prove web/desktop parity.
|
||
- [ ] Onboarding flow guides a first-time user through all 5 surfaces.
|
||
- [ ] Import `.md`/`.epub`; backup/restore round-trips all data.
|
||
- [ ] All performance budgets pass (open, typing, board fps).
|
||
- [ ] a11y: axe-core clean, contrast ≥ 4.5:1, full keyboard nav.
|
||
- [ ] CI green end-to-end across the full matrix.
|
||
|
||
## Definition of done
|
||
PubScript ships as a self-hostable multi-user web app AND native desktop apps on three OSes, with proven parity, polished performance and accessibility, and complete docs. The full vision from PLAN.md is realized.
|
||
|
||
## Risks & fallbacks
|
||
- **Tauri cross-OS packaging friction** (esp. macOS notarization) → Linux-first; Windows as a CI matrix; macOS notarization is explicit later polish, not a v1 blocker.
|
||
- **Parity gaps slip through** → parity matrix + automated contract/playwright gates in CI make gaps visible.
|
||
- **Docker native-build issues** (better-sqlite3) → `node:22-alpine` with build tools; fall back to `node:22-slim` (documented in an ADR, Chunk 1).
|