From 759a75f50e23957b3d73b37084e3372ff1695ab5 Mon Sep 17 00:00:00 2001 From: Jason Date: Wed, 15 Jul 2026 17:43:15 -0500 Subject: [PATCH] Document Libre Study project state --- CHANGELOG.md | 1 + CONVENTIONS.md | 34 ++++++++---- ROADMAP.md | 2 + docs/project-state-2026-07-15.md | 92 ++++++++++++++++++++++++++++++++ 4 files changed, 120 insertions(+), 9 deletions(-) create mode 100644 docs/project-state-2026-07-15.md diff --git a/CHANGELOG.md b/CHANGELOG.md index d3d2167..d099440 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ ## Unreleased - Changed the HotView HMR host from loopback-only `127.0.0.1` to the detected Tailscale IPv4 address, with a `VITE_HMR_HOST` override for other private intranet addresses. +- Updated conventions and project-state notes before the planned consolidation phase. ## 0.1.34 - 2026-07-15 diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 531f165..2daebe3 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -1,6 +1,6 @@ # Libre Study Conventions -Libre Study is the desktop-first Bible study application. Its job is to provide a fast, local, searchable, taggable study workspace that can consume normalized Bible and study-resource packages from `libre-bible-data`. +Libre Study is the platform-agnostic Bible study application. Its job is to provide a fast, searchable, taggable study workspace that can consume normalized Bible and study-resource packages from `libre-bible-data` while staying open-source and free to use where licensing permits. ## Repository Role @@ -12,6 +12,9 @@ Libre Study is the desktop-first Bible study application. Its job is to provide ## Development Workflow - Local development happens in the workspace repo on drive `W:`. +- During active product shaping, HotView/hot reload is the primary test loop. Do not spend cycles on web builds, local builds, installer builds, or hosted deployments unless Jason explicitly asks for a release/deploy pass. +- HotView should stay reachable on the private Tailscale/local intranet, not the public internet. The normal connected-device URL is `http://desktop:5174/`. +- Vite HMR should use the machine's Tailscale IPv4 address when available, with `VITE_HMR_HOST` as the private-address override. - The Christ Unscripted Gitea remote is the remote backup, collaboration, and publishing copy. - Do not treat work as durable until it is committed locally and pushed to Gitea. - Every named implementation phase should bump the app version and be recorded in Git both locally and remotely. @@ -32,7 +35,7 @@ npm.cmd run dev:web npm.cmd run dev:tauri ``` -- Use packaged builds only when testing installers, app signing, updater behavior, or desktop release behavior. +- Use packaged builds only when testing installers, app signing, updater behavior, desktop release behavior, or an explicitly requested release/deploy pass. - Browser dev mode may use mock/localStorage data. Tauri mode should use the native SQLite-backed commands. - If a command starts failing because of PowerShell, Bash, WSL, quoting, heredocs, pipes, regexes, `$` variables, or nested shell layers, stop retrying the same command shape. Move the logic into a script file or use argv-style execution. - Prefer PowerShell for normal Windows-local Node/Tauri work in this repo. Use WSL Bash only when a tool or script is genuinely Linux-oriented. @@ -78,10 +81,11 @@ git@git.christit.com:libre-study/libre-study.git ## Product Direction -- First target: Windows desktop. -- First study source: KJV with Strong's-linked data. -- Core experience: parallel reading, search, tags, notes, highlights, Strong's lookup, and saved study workspaces. -- Later targets may include macOS, Linux, web/PWA, and mobile, but do not let those future targets compromise the desktop study workflow. +- Product goal: a full-featured, open-source, free-to-use Bible study program where public resources are reusable and license-attributed. +- Current lead lane: HotView/browser development on the private Tailscale/local intranet. +- Platform target: one shared app core with adapters for browser/HotView, hosted web, Tauri desktop, and later PWA/mobile surfaces. +- Core experience: page-first reading, search, tags, notes, highlights, Strong's lookup, maps, audio, exports, and saved study workspaces. +- Desktop should remain account-optional/offline-capable when that lane resumes. Hosted web may add accounts, persistence, and collaboration after the single-user workflow is proven. ## Engineering Rules @@ -90,11 +94,23 @@ git@git.christit.com:libre-study/libre-study.git - Do not hardcode Windows-only paths in app logic unless wrapped behind a platform adapter. - Treat installer output as a release artifact, not a normal development artifact. - Public release readiness is separate from internal app maturity. A build can be useful for local testing without being ready for public distribution. -- Run at minimum: +- For normal HotView feature work, run the checks relevant to touched code, typically: ```powershell npm.cmd run lint -npm.cmd run build +npx.cmd tsc --noEmit -p tsconfig.app.json ``` -before considering app changes complete. +- For Vite config or Node-side tooling changes, also run: + +```powershell +npx.cmd tsc --noEmit -p tsconfig.node.json +``` + +- For Tauri/Rust changes, run: + +```powershell +cargo test +``` + +- Do not run builds as routine validation during HotView development unless explicitly requested. diff --git a/ROADMAP.md b/ROADMAP.md index 10d6409..b3f112c 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -57,6 +57,8 @@ Work one phase at a time. A helper, spike, or supporting infrastructure task for - Phase 6: Notes, exports, and optional sync. Complete. - Phase 7: Study resource depth and polish. Complete. +The next planned step is a consolidation pass that converts the completed foundation phases into durable product tracks. See [Project State - 2026-07-15](docs/project-state-2026-07-15.md). + Supporting infrastructure already landed but not currently active as a phase: hosted web preview, hosted login, and deploy scripting. These remain parked until the user explicitly asks for a release/deploy pass. ## Phase 1: App Foundation And Bible Page Reader diff --git a/docs/project-state-2026-07-15.md b/docs/project-state-2026-07-15.md new file mode 100644 index 0000000..2cde509 --- /dev/null +++ b/docs/project-state-2026-07-15.md @@ -0,0 +1,92 @@ +# Project State - 2026-07-15 + +## Eventual Goal + +Libre Study should become a full-featured Bible study program built around open-source code and freely usable resources wherever licensing permits. It should stay platform-agnostic: one shared app core, with adapters for browser/HotView, hosted web, Tauri desktop, and later PWA/mobile surfaces. + +LibreBible remains the public resource package lane. Libre Study remains the study workspace and user-data lane. + +## Where We Started + +The project began as a local Bible reader and Tauri/React shell. The early questions were whether it could consume real Bible data, whether the app could stay independent from a single platform, whether HotView could be the primary development loop, and whether the study surface would be useful enough to guide the architecture. + +## Where We Are Now + +The project has moved from prototype into early product architecture. + +Working HotView behavior includes: + +- KJV and NET Bible text. +- Strong's links and lexicon definitions. +- Strong's pronunciation text when the package provides it. +- KJV and NET footnotes and study notes. +- Matthew Henry Concise commentary. +- Easton and Smith dictionary entries. +- OpenBible place context and UBS route labels. +- KJV audio controls from the packaged Eliran Wong source. +- Session-aware resource toggles. +- Notes, timeline, imports, exports, and one-way Nextcloud WebDAV export. + +Architecture now includes: + +- `src/studyDataClient.ts` as the resource/query contract. +- `src/studyClient.ts` as the browser/Tauri adapter router. +- `src/workspace.ts` as the workspace/auth/session persistence contract. +- Browser/HotView JSON package loading from sibling `W:\libre-bible-data`. +- A Tauri/Rust/SQLite lane that exists but is not currently the lead development lane. +- Hosted login/persistence infrastructure that exists but is parked until explicitly resumed. + +## Current Development Loop + +HotView is the active loop. Do not run web builds, local builds, installer builds, or hosted deployments unless explicitly requested. + +The private intranet/Tailscale target is: + +```text +http://desktop:5174/ +``` + +Vite HMR detects the machine's Tailscale IPv4 address when available. `VITE_HMR_HOST` can override that if a device needs a different private address. This is a private development path, not a public internet deployment. + +## What We Learned + +- Phase completion should mean: source updated, docs/changelog updated, validation run, committed, and pushed to Gitea. +- Current repo state is more authoritative than memory or phase labels. +- KeePass should own project credentials and operating notes where practical. +- Passwords generated for project services should be around 16-20 characters, using uppercase, lowercase, and numbers, without special characters unless a service requires them. +- Nextcloud export is one-way WebDAV export for now, not a primary database or full sync system. +- Browser/HotView currently has the richest resource behavior; desktop hardening comes later. +- Public resource data belongs to LibreBible. User workspace data belongs to Libre Study. +- Do not show fake pronunciation playback controls until licensed pronunciation audio packages exist. +- `desktop` resolves to multiple local addresses on this machine; the Tailscale IPv4 path is the reliable HMR target. + +## Where We Are Not Yet + +Libre Study is not yet a mature public Bible study application. + +Missing or immature areas include: + +- Cross-references. +- More commentaries, lexicons, dictionaries, atlas images, and audio packages. +- Licensed pronunciation audio packages. +- Resource install/update/offline package management. +- Mature hosted persistence and account lifecycle. +- Desktop offline hardening and signed installers. +- PWA/mobile adaptation. +- Collaboration. +- Public web release readiness: privacy, terms, license pages, abuse protection, backups, and monitoring. + +## Recommended Next Step + +The next phase should be consolidation, not another feature sprint. + +Consolidation should turn the completed Phase 1-7 foundation into durable product tracks: + +- Study experience. +- Resource ecosystem. +- Persistence and sync. +- Platform adapters. +- Public responsibility. +- Collaboration. + +The goal is to preserve the platform-agnostic architecture before adding more features.