117 lines
6.9 KiB
Markdown
117 lines
6.9 KiB
Markdown
# Libre Study Conventions
|
|
|
|
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
|
|
|
|
- This repo owns the application shell, interface, local storage, search behavior, import behavior, and desktop packaging.
|
|
- This repo does not own source Bible texts, commentaries, maps, lexicons, or study notes.
|
|
- Bible and study resources should enter the app through importable packages generated by `libre-bible-data`.
|
|
- Keep app code and resource data separate unless a tiny fallback seed is needed for development.
|
|
|
|
## 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.
|
|
- Phase completion means the version bump, code/docs changes, and validation result are committed locally and pushed to Gitea.
|
|
- The normal flow is local edit, local verify, local commit, push to Gitea, then publish or release from the pushed state.
|
|
- Do not publish release artifacts from a dirty worktree unless Jason explicitly asks for that exact operation.
|
|
- Keep source-control bookkeeping quiet unless Jason asks about it or a source-control problem affects the work.
|
|
- Use the actual project scripts instead of ad hoc equivalents.
|
|
- Use browser dev mode for fast visual iteration:
|
|
|
|
```powershell
|
|
npm.cmd run dev:web
|
|
```
|
|
|
|
- Use Tauri dev mode when testing native behavior:
|
|
|
|
```powershell
|
|
npm.cmd run dev:tauri
|
|
```
|
|
|
|
- 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.
|
|
|
|
## Publishing Model
|
|
|
|
- Gitea is the Git host and backup/publishing surface, not the primary app UI.
|
|
- Public Gitea host: `https://git.christit.com`.
|
|
- Remote URL:
|
|
|
|
```text
|
|
https://git.christit.com/libre-study/libre-study.git
|
|
git@git.christit.com:libre-study/libre-study.git
|
|
```
|
|
|
|
- Public download pages, catalogs, release notes, and package indexes should be generated from repo metadata where possible.
|
|
- Do not hand-maintain public catalog details that can be derived from committed manifests, package catalogs, tags, or releases.
|
|
- Release artifacts should be traceable to a pushed commit.
|
|
- Signed installers and updater metadata should only be produced from intentional release commits.
|
|
- Generated app metadata, package indexes, update manifests, and release notes should be regenerated by scripts rather than hand-corrected after the fact.
|
|
|
|
## Backup Copies
|
|
|
|
- Source control is the main recovery layer, but local `.old` backups are still useful before large, risky, or release-bound edits.
|
|
- Put backups near the affected file or module, not in random temp locations.
|
|
- Prefer backup filenames with timestamp plus short reason, for example `App.tsx.20260712-study-layout.old`.
|
|
- Do not create `.old` backups for every tiny edit. Use them when rollback clarity is worth the extra file.
|
|
|
|
## Changelogs
|
|
|
|
- Keep changelogs newest-first when changelogs are introduced.
|
|
- Use a `## Current` section when helpful, followed by dated release sections.
|
|
- Keep entries concrete and operational: what changed, what behavior was preserved, and what was verified.
|
|
- Mark reconstructed history clearly if it is built from artifacts, old packages, or prior notes.
|
|
|
|
## Data Boundary
|
|
|
|
- The app should import from `libre-bible-data` packages rather than scraping or downloading Bible sources directly.
|
|
- The app should prefer LibreBible machine catalogs over direct file guesses. Catalog paths may come from `LIBREBIBLE_CATALOG_PATH`, a sibling `libre-bible-data` checkout, or later a public ChristIT.com catalog.
|
|
- The local SQLite database is an app cache and user workspace, not the canonical source of public Bible data.
|
|
- User-created tags, highlights, notes, saved searches, layouts, and reading state belong to Libre Study.
|
|
- Translation text, Strong's links, study notes, commentaries, maps, and source metadata belong to `libre-bible-data`.
|
|
|
|
## Product Direction
|
|
|
|
- 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
|
|
|
|
- Prefer TypeScript for UI and Rust/Tauri commands for native filesystem/database work.
|
|
- Keep UI components decoupled from Tauri `invoke` calls through a client layer so browser dev mode remains usable.
|
|
- 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.
|
|
- For normal HotView feature work, run the checks relevant to touched code, typically:
|
|
|
|
```powershell
|
|
npm.cmd run lint
|
|
npx.cmd tsc --noEmit -p tsconfig.app.json
|
|
```
|
|
|
|
- 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.
|