fj/CLAUDE.md

fj — project notes for Claude

fj is a Forgejo CLI, in the spirit of GitHub's gh. Multi-host, tokens in the OS keychain, ~10k LOC Rust with full feature parity to gh for the surface Forgejo exposes.

Layout

src/
  main.rs              entry: alias expansion, fj-<name> plugin dispatch
  cli/                 clap subcommand tree
    mod.rs             top-level Cli + dispatch + Ctrl+C race + pager
    context.rs         RepoFlag + resolve_repo (`-R` or git-remote detect)
    editor.rs          $EDITOR + body resolution helpers
    web.rs             cross-platform `--web` opener
    <subcommand>.rs    one file per command group (auth, repo, pr, …)
  api/                 typed wrappers around /api/v1
    mod.rs             split_repo + shared serde helpers
    <resource>.rs      one file per resource (issue, pull, release, …)
  client/              HTTP client
    mod.rs             Client, retry-on-5xx, debug logging, headers
    pagination.rs      Page<T> + Link header parser
    error.rs           ApiError
    integration_tests  wiremock-based tests
  config/              hosts.toml shape + load/save
  auth/                OS keychain wrapper
  git/                 git invocation + remote URL parser
  output/              tables, colors, relative_time, state_pill, pager
hooks/pre-push         local CI gate
scripts/               install-hooks.sh, e2e-smoke.sh
docs/                  architecture, jq syntax, troubleshooting

Build / test / hook

• cargo build --release produces a ~4 MB binary at target/release/fj.
• cargo test --all runs 60 tests (51 unit + 9 wiremock integration).
• cargo clippy --all-targets --all-features -- -D warnings is the lint bar. CI (the pre-push hook) treats warnings as errors.
• ./scripts/install-hooks.sh symlinks hooks/pre-push into .git/hooks.
• FJ_E2E=1 enables the live API smoke against stephen/fj-cli-test.
• FJ_SKIP_PREPUSH=1 bypasses the hook for genuine emergencies only.

Key conventions

• Every repo-scoped subcommand accepts -R/--repo AND auto-detects from the git remote (upstream then origin). The resolver is cli::context::resolve_repo.
• Bodies (--body) support: an inline string, - for stdin, or omit to open $EDITOR. See cli::editor.
• Lists with --limit > 50 transparently follow Link: rel=next via Client::get_all. Per-page cap is the Forgejo default (50).
• The simple jq projector lives in cli::api::extract_path. Supports .field, .0, .[0], [-1], and | pipes. See docs/jq.md.
• All commands respect --host / FJ_HOST, --debug / FJ_DEBUG, --no-pager, FJ_PAGER / PAGER.

Things to remember

• Tokens are stored in the OS keychain (service fj, key = hostname). Never serialized to disk. Re-prompts after rebuilds are expected on macOS because the binary hash changes; click "Always Allow."
• cargo test builds a separate test binary with a different hash, so it gets its own keychain prompt. Tests that need keychain access are the wiremock-backed ones in src/client/integration_tests.rs, which bypass the keychain via Client::for_base_url.
• The repo URL in Cargo.toml is https://rasterhub.com/rasterstate/fj.
• Commit author is Stephen Way <stephen@rasterstate.com>. The user has a CLAUDE.md preference: no em-dashes, terse responses, no preamble.
• MSRV is 1.82 (we use Option::is_none_or).

Where to look first

• Adding a new subcommand: copy an existing cli/<x>.rs (e.g. label). Wire into cli/mod.rs (Command enum, dispatch) and main.rs (KNOWN_SUBCOMMANDS). Typed API wrapper in api/<x>.rs.
• Adding a new Forgejo endpoint: api/<resource>.rs is the right home.
• Touching HTTP behavior: client/mod.rs::request_with_headers is the one spot all requests funnel through. Don't add a parallel code path.
• Test a new API surface: add to src/client/integration_tests.rs rather than tests/ (this is a binary crate, no [lib] target, so integration tests live inline).