docs: CLAUDE.md, CONTRIBUTING.md, CHANGELOG.md, docs/
* CLAUDE.md: project layout, key conventions, where to look first.
Captures the non-obvious things a future session needs.
* CONTRIBUTING.md: build/test workflow, how to add a subcommand
(concrete walkthrough), code style.
* CHANGELOG.md: history. 0.1.0 entry covers initial feature set;
Unreleased captures stability + optimization batch.
* docs/architecture.md: module graph, layering rules, the HTTP funnel,
pager + SIGINT, repo resolution, test strategy.
* docs/jq.md: --jq syntax cheatsheet (dot paths, brackets, negative
indices, pipes, what's not supported).
* docs/troubleshooting.md: keychain re-prompts, debug logging, pager
opt-out, alias precedence, hook bypass, common 401s.
* README.md: links into docs/ and updates binary size to 4 MB.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-13 19:48:46 +00:00
|
|
|
# `fj` documentation
|
|
|
|
|
|
|
|
|
|
- [`architecture.md`](architecture.md) — module graph, layering rules,
|
|
|
|
|
the HTTP funnel, pager + SIGINT, repo resolution, test strategy.
|
|
|
|
|
- [`jq.md`](jq.md) — the `fj api --jq` syntax. Dot paths, brackets,
|
|
|
|
|
negative indices, pipes.
|
bugs + agent-focused Forgejo gaps + CI + docs
Bugs:
* Shell injection in `fj auth setup-git`: the hostname is now validated
against a strict DNS pattern and `git config` is invoked directly
(no `sh -c`). Added 4 unit tests covering shell metacharacters.
* Pager won't compile on Windows: the libc-based dup2 redirect lives
behind `#[cfg(unix)]`. Non-Unix gets a no-op stub.
Agent-focused Forgejo API gaps:
* `fj issue edit-comment ID` / `delete-comment ID`. Fix a wrong comment
after the fact (an agent's bread-and-butter).
* `fj search code "..." [-R owner/name]`. The most-requested missing
search dimension for codebase exploration.
* `fj pr request-review N user1 user2`, `unrequest-review N user`.
Distinct from `pr review` (your own approval/changes/comment).
* `fj repo watch / unwatch / star / unstar / starred`. Mark repos for
monitoring.
* `fj milestone {list,view,create,edit,close,reopen,delete,assign}`
with `assign N --milestone ID|none` to attach an issue/PR.
UX + stability:
* Global `--json-fields foo,bar` projection on top of any `--json`
output, gh-style. Dotted-path support (`--json-fields owner.login`).
* 429 / Retry-After honored in the retry loop with a 30 s cap.
* Clap `suggestions` feature for typo'd subcommands.
* `fj auth token` and `auth status --show-token` refuse to write to a
TTY by default (`--force` to override).
CI:
* `.forgejo/workflows/ci.yml` runs fmt/clippy/test/release-build on
every push and PR, mirroring the local pre-push hook.
Docs:
* `SECURITY.md` with threat model and known sharp edges.
* `docs/gh-to-fj.md` full command-by-command mapping.
* `docs/faq.md` covering tokens, hosts, debug, scripting, plugins.
Tests: 60 → 75 passing (2 ignored: editor and env-mutating tests that
fight the cargo test harness on macOS).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-13 21:52:28 +00:00
|
|
|
- [`gh-to-fj.md`](gh-to-fj.md) — command-by-command mapping from gh.
|
|
|
|
|
- [`faq.md`](faq.md) — common questions about tokens, hosts, debug,
|
|
|
|
|
scripting, plugins.
|
docs: CLAUDE.md, CONTRIBUTING.md, CHANGELOG.md, docs/
* CLAUDE.md: project layout, key conventions, where to look first.
Captures the non-obvious things a future session needs.
* CONTRIBUTING.md: build/test workflow, how to add a subcommand
(concrete walkthrough), code style.
* CHANGELOG.md: history. 0.1.0 entry covers initial feature set;
Unreleased captures stability + optimization batch.
* docs/architecture.md: module graph, layering rules, the HTTP funnel,
pager + SIGINT, repo resolution, test strategy.
* docs/jq.md: --jq syntax cheatsheet (dot paths, brackets, negative
indices, pipes, what's not supported).
* docs/troubleshooting.md: keychain re-prompts, debug logging, pager
opt-out, alias precedence, hook bypass, common 401s.
* README.md: links into docs/ and updates binary size to 4 MB.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-13 19:48:46 +00:00
|
|
|
- [`troubleshooting.md`](troubleshooting.md) — keychain prompts, hangs,
|
|
|
|
|
401 errors, `--debug`, pager opt-out, alias precedence, hook bypass.
|
|
|
|
|
|
|
|
|
|
For build/test workflow see [`../CONTRIBUTING.md`](../CONTRIBUTING.md).
|
|
|
|
|
For project conventions see [`../CLAUDE.md`](../CLAUDE.md).
|
2026-05-13 21:57:07 +00:00
|
|
|
For security policy see [`../SECURITY.md`](../SECURITY.md).
|
|
|
|
|
For release notes see [`../CHANGELOG.md`](../CHANGELOG.md).
|