docs(workspace): document crate split + MCP-reuse contract (FJ-9) #17

Merged

David merged 1 commit from docs/verify-cli-free-document-layout-fj-9 into main

2026-05-25 19:56:18 +02:00

David commented

2026-05-25 19:30:15 +02:00

Owner

Closes FJ-9 (FJ-3 Phase 5 of 5: verify fj-client/fj-core are CLI-free + document the layout).

Per the human decision recorded on FJ-9 (blockers 1a + 2a), this is a pure documentation PR: no refactor, no dependency change.

What this does

Adds a "Workspace layout (FJ-3 crate split)" section to the root CLAUDE.md documenting the three workspace members and the MCP-reuse contract:

fj-client (lib): connection + credential layer.
fj-core (lib): CLI-agnostic domain logic (repo-name parsing, issue-template parser, per-command operation modules).
fj (binary): clap command tree, crossterm, fluent localization, and all rendering.

The MCP-reuse contract: neither library may depend on clap, crossterm, or any fluent-* crate, so a future Forgejo MCP can depend on fj-core. comrak is documented as the one intentional non-CLI parsing exception in fj-core (CommonMark issue-template parsing, added in FJ-7). The doc also records that the binary legitimately holds more raw LoC than the libraries combined because rendering, the clap tree, and fluent stay in the binary by design (so "majority of LoC in the libs" is explicitly not a success metric).

Verification (FJ-9 step 4)

cargo build -p fj-client -p fj-core: libs build standalone.
cargo tree -p fj-client -p fj-core -e normal | grep -E 'clap|crossterm|fluent': empty (amended grep per decision 1a; comrak is the documented exception).
LoC: fj-client 265 + fj-core 1968 = 2233 lib vs 9604 binary (expected per the crate-split contract, decision 2a).
just check, just pre-commit: pass.
docker run --rm forgejo-cli:local version: prints fj v0.6.0.

Lockfile note

Also syncs the workspace member version in Cargo.lock (forgejo-cli 0.5.0 -> 0.6.0) so cargo build --locked matches crates/fj/Cargo.toml. The lock was left stale by the v0.6.0 release commit; without this sync the locked CI build fails on main. No third-party dependency versions change.

Closes FJ-9 (FJ-3 Phase 5 of 5: verify fj-client/fj-core are CLI-free + document the layout). Per the human decision recorded on FJ-9 (blockers 1a + 2a), this is a pure documentation PR: no refactor, no dependency change. ## What this does Adds a "Workspace layout (FJ-3 crate split)" section to the root `CLAUDE.md` documenting the three workspace members and the MCP-reuse contract: - `fj-client` (lib): connection + credential layer. - `fj-core` (lib): CLI-agnostic domain logic (repo-name parsing, issue-template parser, per-command operation modules). - `fj` (binary): clap command tree, crossterm, fluent localization, and all rendering. The MCP-reuse contract: neither library may depend on `clap`, `crossterm`, or any `fluent-*` crate, so a future Forgejo MCP can depend on `fj-core`. `comrak` is documented as the one intentional non-CLI parsing exception in `fj-core` (CommonMark issue-template parsing, added in FJ-7). The doc also records that the binary legitimately holds more raw LoC than the libraries combined because rendering, the clap tree, and fluent stay in the binary by design (so "majority of LoC in the libs" is explicitly not a success metric). ## Verification (FJ-9 step 4) - `cargo build -p fj-client -p fj-core`: libs build standalone. - `cargo tree -p fj-client -p fj-core -e normal | grep -E 'clap|crossterm|fluent'`: empty (amended grep per decision 1a; `comrak` is the documented exception). - LoC: fj-client 265 + fj-core 1968 = 2233 lib vs 9604 binary (expected per the crate-split contract, decision 2a). - `just check`, `just pre-commit`: pass. - `docker run --rm forgejo-cli:local version`: prints `fj v0.6.0`. ## Lockfile note Also syncs the workspace member version in `Cargo.lock` (`forgejo-cli` 0.5.0 -> 0.6.0) so `cargo build --locked` matches `crates/fj/Cargo.toml`. The lock was left stale by the v0.6.0 release commit; without this sync the locked CI build fails on `main`. No third-party dependency versions change.

David added 1 commit

2026-05-25 19:30:15 +02:00

docs(workspace): document crate split + MCP-reuse contract (FJ-9)

Check / fmt + clippy + build + tests (pull_request) Successful in 37s

Details

Create release / Create release from merged PR (pull_request) Has been skipped

Details

94534e9795

FJ-3 Phase 5 verify-and-document task. Per the human decision recorded on FJ-9 (1a + 2a), this is a pure documentation change: no refactor, no dependency change.

Adds a "Workspace layout" section to the root CLAUDE.md describing the three workspace members (fj-client, fj-core, fj binary) and the MCP-reuse contract: fj-client and fj-core stay CLI-free so a future Forgejo MCP can depend on fj-core. The contract is verifiable with `cargo tree -p fj-client -p fj-core -e normal | grep -E 'clap|crossterm|fluent'` (empty). Documents comrak as the one intentional non-CLI parsing exception in fj-core (CommonMark issue-template parsing, added in FJ-7), and records that the binary legitimately holds more raw LoC than the libraries because rendering, the clap tree, and fluent stay in the binary by design.

Verification run for this issue: `cargo build -p fj-client -p fj-core` builds the libs standalone; the amended grep is empty; `just check`, `just pre-commit`, and the runtime image `docker run forgejo-cli:local version` (prints `fj v0.6.0`) all pass.

Also syncs the workspace member version in Cargo.lock (forgejo-cli 0.5.0 -> 0.6.0) so `cargo build --locked` matches crates/fj/Cargo.toml. The lock was left stale by the v0.6.0 release commit; without this sync the locked CI build fails. No third-party dependency versions change.

#FJ-9