feat: Unify books_dir into library tree (#46)

mik-tf commented

2026-02-13 16:44:15 +00:00

Owner

Summary

Replace the separate --books-dir (flat directory of {ns}_{book}.toml files) with a unified library tree at ~/hero/var/books/. Book TOMLs, exports, and AI metadata now all live together in {library}/books/{book}/.

Changes

Core

library.rs: Added library_book_toml_path() helper
scanner.rs: Added BooksScanner::scan_libraries() for nested {lib}/books/{book}/book.toml layout
server.rs: Renamed ServerConfig.books_dir → libraries_dir, removed export_dir field. All export/import/discover functions now place TOMLs into the library tree
main.rs: New --libraries-dir flag (env HERO_BOOKS_LIBRARIES_DIR, default ~/hero/var/books/). Deprecated --books-dir with auto-seed into library tree for backward compatibility
axum_server.rs, web/rpc.rs, webservice/server/rpc.rs, zinit_integration.rs: Updated all references from books_dir to libraries_dir

Scripts & CI

New: scripts/seed-books.sh — seeds flat {ns}_{book}.toml files into the library tree
Updated: Makefile — new seed-local/seed-git targets, updated demo/serve/run/dev
Updated: scripts/run_server.sh — simplified (no more books_dir arg)
Updated: scripts/test-all.sh — uses seed + default libraries_dir
Updated: .forgejo/workflows/test.yaml — seed step before server start

Documentation

Updated docs/manual/server.md — new CLI flags table, updated examples
Updated docs/manual/book_configuration.md — unified tree layout, seeding instructions
Updated docs/manual/concepts.md — expanded library tree diagram
Updated docs/manual/README.md — updated quick start
Updated docs/manual/ai_processing.md — --ai-concurrency flag

Backward Compatibility

--books-dir is kept as a hidden deprecated alias. When used:

Logs a deprecation warning
Auto-seeds flat .toml files into ~/hero/var/books/ library tree
Also copies libraries.txt if present
Server then uses the library tree as normal

Testing

✅ cargo check — compiles
✅ cargo test — 136 tests pass
✅ cargo clippy -- -D warnings — no warnings

Closes #46

## Summary Replace the separate `--books-dir` (flat directory of `{ns}_{book}.toml` files) with a unified library tree at `~/hero/var/books/`. Book TOMLs, exports, and AI metadata now all live together in `{library}/books/{book}/`. ## Changes ### Core - **`library.rs`**: Added `library_book_toml_path()` helper - **`scanner.rs`**: Added `BooksScanner::scan_libraries()` for nested `{lib}/books/{book}/book.toml` layout - **`server.rs`**: Renamed `ServerConfig.books_dir` → `libraries_dir`, removed `export_dir` field. All export/import/discover functions now place TOMLs into the library tree - **`main.rs`**: New `--libraries-dir` flag (env `HERO_BOOKS_LIBRARIES_DIR`, default `~/hero/var/books/`). Deprecated `--books-dir` with auto-seed into library tree for backward compatibility - **`axum_server.rs`**, **`web/rpc.rs`**, **`webservice/server/rpc.rs`**, **`zinit_integration.rs`**: Updated all references from `books_dir` to `libraries_dir` ### Scripts & CI - **New**: `scripts/seed-books.sh` — seeds flat `{ns}_{book}.toml` files into the library tree - **Updated**: `Makefile` — new `seed-local`/`seed-git` targets, updated `demo`/`serve`/`run`/`dev` - **Updated**: `scripts/run_server.sh` — simplified (no more books_dir arg) - **Updated**: `scripts/test-all.sh` — uses seed + default libraries_dir - **Updated**: `.forgejo/workflows/test.yaml` — seed step before server start ### Documentation - Updated `docs/manual/server.md` — new CLI flags table, updated examples - Updated `docs/manual/book_configuration.md` — unified tree layout, seeding instructions - Updated `docs/manual/concepts.md` — expanded library tree diagram - Updated `docs/manual/README.md` — updated quick start - Updated `docs/manual/ai_processing.md` — `--ai-concurrency` flag ## Backward Compatibility `--books-dir` is kept as a hidden deprecated alias. When used: 1. Logs a deprecation warning 2. Auto-seeds flat `.toml` files into `~/hero/var/books/` library tree 3. Also copies `libraries.txt` if present 4. Server then uses the library tree as normal ## Testing - ✅ `cargo check` — compiles - ✅ `cargo test` — 136 tests pass - ✅ `cargo clippy -- -D warnings` — no warnings Closes #46

mik-tf added 1 commit

2026-02-13 16:44:15 +00:00

feat: unify books_dir into library tree (#46 )

Test / test (pull_request) Successful in 3m1s

Details

Test / integration (pull_request) Has been cancelled

Details

06f774c095

Replace the separate --books-dir (flat directory of {ns}_{book}.toml files)
with a unified library tree at ~/hero/var/books/. Book TOMLs, exports, and
AI metadata now all live together in {library}/books/{book}/.

Changes:
- Add library_book_toml_path() helper to library.rs
- Add BooksScanner::scan_libraries() for nested layout scanning
- Rename ServerConfig.books_dir → libraries_dir, remove export_dir
- New CLI: --libraries-dir (env HERO_BOOKS_LIBRARIES_DIR), default ~/hero/var/books/
- Deprecated --books-dir with auto-seed into library tree (backward compat)
- All export/import/discover functions place TOMLs into library tree
- New scripts/seed-books.sh for seeding example books
- Updated Makefile with seed-local/seed-git targets
- Updated CI workflow, test-all.sh, run_server.sh
- Updated docs/manual/ (server.md, book_configuration.md, concepts.md,
  README.md, ai_processing.md)

Closes #46

mik-tf added 1 commit

2026-02-13 16:52:04 +00:00

test: add unit tests for libraries_dir unification

Test / test (pull_request) Successful in 2m58s

Details

Test / integration (pull_request) Failing after 4m55s

Details

c3d2b50f1f

- scan_libraries(): 7 tests covering nested layout, edge cases (empty,
  nonexistent, hidden dirs, missing book.toml, non-book TOMLs)
- toml_filename_to_book_name(): 3 tests for prefix stripping
- seed_flat_books_dir(): 6 tests covering namespace parsing from TOML
  content and filename, non-toml skipping, no-overwrite, libraries.txt
  copy, nonexistent source dir

mik-tf added 1 commit

2026-02-13 17:48:20 +00:00

fix: use parent dir name for book.toml in library tree scanner

Test / test (pull_request) Successful in 3m1s

Details

Test / integration (pull_request) Failing after 6m20s

Details

180fbe807f

- try_parse_book() now uses parent directory name instead of 'book'
  file stem when parsing book.toml files in the library tree layout
- find_exported_book() handles backward-compat {namespace}_{book}
  URL format (e.g., /book/coding_python finds coding/books/python/)
- Smoke test URLs updated to use new short book names
- Added unit test for parent dir name fallback

mik-tf added 1 commit

2026-02-13 18:00:41 +00:00

fix: update E2E tests for unified library tree book names

Test / test (pull_request) Successful in 3m44s

Details

Test / integration (pull_request) Successful in 6m10s

Details

e9520f5b8a

Book names are now just the book directory name (e.g., 'python')
instead of the old namespace-prefixed format ('coding_python').
Updated all 35 references across 6 E2E test files.

mik-tf commented

2026-02-19 01:10:54 +00:00

Author

Owner

Closing: all changes from this PR are already present in development branch (verified via git merge-base --is-ancestor). Work consolidated into a new PR covering build system alignment and remaining features.

Closing: all changes from this PR are already present in `development` branch (verified via `git merge-base --is-ancestor`). Work consolidated into a new PR covering build system alignment and remaining features.