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/`)

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.
docker/compose.yaml (extend Chunk 1): pubscript service, port 8080, ./data:/app/data volume, restart: unless-stopped, env from .env.
docker/languagetool/compose.yaml: optional LanguageTool sidecar (Chunk 7) — documented, not required.
Backup scripts (docker/backup.sh): pg_dump-style SQLite snapshot (cp the .sqlite file with WAL checkpoint) → timestamped .sqlite.bak; restore script.
docker/README.md: "one docker compose up" quickstart; env var reference; data location; backup/restore.

2. Tauri desktop bundles (`desktop/`)

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.
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).
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.
Icons: generate per-platform icon sets (scripts in desktop/icons/).

3. Parity proof

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.
Contract suite (Chunk 2) already runs Local vs. Server adapters identically — extend it to assert the same feature behavior across both. CI gate.
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/`)

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).
Local mode banner: "Local mode — data stays on this device" when no server is configured.

5. Import & backup (UI)

Import (apps/web/src/features/import/): import a .md file into a project (Chunk 3); import an EPUB (parse → chapters) as a bonus.
Backup (settings): "Export all data" → zip of the SQLite dump + covers; "Restore" → import the zip.

Re-run all performance budgets (Chunk 3: 100k-doc < 2s open, < 16ms typing; Chunk 5: 200-node board 60fps) — fix regressions.
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

README.md (extend Chunk 1): full quickstart for web + desktop + self-host.
docs/ROLE_PROMPTS.md, docs/DATA_MODEL.md, docs/EDITOR.md, docs/BOARDS.md, docs/PARITY.md — all complete.

8. Tests

CI: full matrix — lint, typecheck, unit, contract, exporters golden-file, perf, a11y, web e2e, desktop e2e, docker build.
All performance + a11y budgets pass.

Acceptance criteria (all must pass)

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).

5.3 KiB Raw Blame History Unescape Escape