fj/CHANGELOG.md

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.4.0] - 2026-05-02

Audit-driven hardening pass. Three reviewers (Codex + two Claude agents
with non-overlapping focuses) found 13 issues across cmd/ and internal/;
this release ships fixes for all 13.

### BREAKING

- `--json=fields` syntax removed. The flag was a string with
  `NoOptDefVal=" "` sentinel — `--json` alone meant "everything",
  `--json=fields` projected. That produced `--json string[=" "]` in
  `--help` and required a literal `=` because `--json fields` was parsed
  as the bare flag plus a positional. **Migration**: `--json=fields` →
  `--json-fields fields`. Bare `--json` still means "all fields as JSON".
  `--json` and `--json-fields` are mutually exclusive; `--jq` composes
  with either.

### Added

- `fj api --json` / `--json-fields` / `--jq` — projection and jq filtering
  for raw API responses. Routes through the same `addJSONFlags` helpers
  as the other list commands. Closes the inconsistency where `fj api`
  was the only command returning raw JSON without these knobs.
- `fj api --paginate` — follows RFC 5988 `Link: rel="next"` headers and
  concatenates JSON array pages, gh-compatible. Validates same-origin
  before forwarding the bearer token to the next URL.
- `cmd/paginate.go` — generic `paginateGitea[T any]` helper. Applied to
  `repo list`, `pr list`, `issue list`. Previously only `release list`
  walked pages; the others passed `PageSize: limit` directly to the
  gitea SDK, which silently caps PageSize at 50, so `--limit > 50` was
  truncated without warning.
- `CLAUDE.md` — guide for Claude Code sessions: layout, codex review
  pattern, release process, homebrew tap update steps.

### Changed

- `--json` flag rebuilt as a plain `Bool`. `--json-fields` keeps
  comma-separated projection. Both registered via `addJSONFlags` and
  marked `MutuallyExclusive`.
- `cmd/actions.go` — `run` and `workflow` subtrees converted from
  package-level `var`s to factory functions (`newRunCmd`,
  `newWorkflowCmd`, ...). `cmd/aliases.go` shrank from 142 → 17 lines
  and now calls those same factories with a `parentLabel` parameter that
  disambiguates the alias variant. Result: `diff` of `fj run list
  --help` flags vs `fj actions run list --help` flags is now empty.
  Drift between the two paths is structurally impossible.
- `fj api` now uses `internal/api.SharedHTTPClient` (30s timeout, pooled
  connections) instead of a zero-value `&http.Client{}` with no timeout.
  A hung Forgejo no longer pins the CLI indefinitely.
- `fj api` response body bounded by `io.LimitReader` at 64 MB to prevent
  OOM-on-self.
- `cmd/auth.go` removed redundant local `--hostname` declarations on
  three subcommands. The persistent flag on rootCmd is now the only
  declaration; previously local declarations shadowed it, so
  `fj --hostname=X auth login` and `fj auth login --hostname=X` went
  through different code paths.
- `--token` on `auth login` emits a stderr warning when used (visible
  in `ps auxe` and shell history). Flag not removed; just discoverable.
- Error handling: `Hint` is now a structured field on `CLIError`.
  JSON-error consumers get clean structure; the human renderer still
  appends `\nHint: ...`. Dropped substring matching of `"401"`/`"403"`
  against rendered error strings (would match issue #403); now relies
  exclusively on typed `*api.APIError`.
- Network errors (`no such host`, `connection refused`, `i/o timeout`)
  return a structured `CLIError` with code `ErrNetworkError` and a hint.
- Config dir created with mode 0700 instead of 0755.

### Fixed

- `--config <path>` now actually honored. Previously fed only into
  Viper; every command that touched config went through
  `internal/config.Load()` / `Save()` which always read the default
  path. So `fj --config other.yaml auth login` writes to other.yaml now.
- `fj run list --json`, `fj workflow list --json`, `fj wiki view --json`
  now produce JSON. `cmd/aliases.go` registered `--json` as `Bool` but
  handlers called `wantJSON()` which does `GetString("json")` — pflag
  returned a type-error that `wantJSON` silently swallowed.
  `cmd/wiki.go` had the inverse bug (`GetBool` against an
  `addJSONFlags`-registered string flag). Both routed through
  `addJSONFlags`/`wantJSON`/`outputJSON` consistently now.
- `migrateConfigDir` opens dst with `O_TRUNC`. Previously a partially-
  pre-existing dst file would have legacy contents overwrite a prefix
  and leave stale tail bytes — silent YAML/token corruption. Refactored
  close handling into `copyOneConfigFile`.

### Security

- `fj api` endpoint path traversal closed. `fj api '/../admin/users'`
  previously normalized through `http.NewRequest` to
  `https://host/admin/users` — silently sending authenticated traffic
  to non-API paths. Endpoint is now parsed via `url.Parse`, `..`
  segments rejected, then `JoinPath` onto the `/api/v1` base.
  URL-encoded `%2E%2E` is also caught because Go decodes before our
  split.
- `fj api --paginate` validates same-origin before forwarding the
  bearer token to a `Link: rel="next"` URL. Refuses to reattach
  `Authorization` if the next URL's scheme isn't `https` or its host
  doesn't match the configured one.
- `initConfig` warns on stderr if the resolved config file is world or
  group readable (`mode & 0o077 != 0`).

## [0.3.0c] - 2026-03-21

### Added

#### Label Management
- `fj label list` - List repository labels
- `fj label create` - Create a label with color and description
- `fj label edit` - Edit label name, color, or description
- `fj label delete` - Delete a label

#### Milestone Management
- `fj milestone list` - List milestones with state filtering
- `fj milestone view` - View milestone details
- `fj milestone create` - Create a milestone with description and due date
- `fj milestone edit` - Edit milestone title, description, due date, or state
- `fj milestone delete` - Delete a milestone

#### Wiki Management
- `fj wiki list` - List wiki pages
- `fj wiki view` - View wiki page content
- `fj wiki create` - Create a wiki page from flag or file
- `fj wiki edit` - Edit a wiki page
- `fj wiki delete` - Delete a wiki page

#### Issue Dependencies
- `fj issue edit --add-dependency <number>` - Add issue dependency
- `fj issue edit --remove-dependency <number>` - Remove issue dependency

## [0.3.0b] - 2026-03-21

### Added

#### Repository Management
- `fj repo edit` - Edit repository settings (visibility, description, homepage, default branch)

### Fixed
- `fj repo create --public` flag was defined but never read; now properly wired up

## [0.3.0a] - 2026-03-21

### Added

#### Raw API Access
- `fj api <endpoint>` - Make authenticated REST API requests to any Forgejo/Gitea endpoint
  - HTTP method selection (`--method`/`-X`), auto-switches to POST when fields are provided
  - JSON field assembly (`--field`/`-f`) with type inference (bool, int, float, null, string)
  - Raw string fields (`--raw-field`/`-F`)
  - Request body from file or stdin (`--input`)
  - Custom headers (`--header`/`-H`)
  - Path interpolation (`{owner}`, `{repo}`) from git context
  - Response header display (`--include`/`-i`)

#### Pull Request Management
- `fj pr diff <number>` - View the diff for a pull request
  - Colorized output (`--color auto/always/never`)
  - Changed file names only (`--name-only`)
  - Diffstat summary (`--stat`)
- `fj pr comment <number>` - Add a comment to a pull request
  - Body from flag (`--body`/`-b`) or file (`--body-file`, `-` for stdin)
  - JSON output (`--json`)
- `fj pr review <number>` - Submit a review on a pull request
  - Approve (`--approve`/`-a`), request changes (`--request-changes`/`-r`), or comment (`--comment`/`-c`)
  - Body from flag or file
  - JSON output (`--json`)

#### Agentic / Machine-Readable Output
- `--json-errors` global flag for structured JSON error output on stderr
  - Error codes: `auth_required`, `not_found`, `api_error`, `invalid_input`, `git_detection_failed`, `network_error`
  - HTTP status code and detail included when available
  - Automatic mapping of API errors (401/403 → `auth_required`, 404 → `not_found`)

## [0.3.0] - 2026-03-13

### Added

#### Forgejo Actions
- `fj actions run watch <run-id>` - Poll a run until completion
- `fj actions run rerun <run-id>` - Trigger a rerun of a workflow run
- `fj actions run cancel <run-id>` - Cancel an in-progress workflow run
- `fj actions workflow enable <workflow>` - Enable a workflow
- `fj actions workflow disable <workflow>` - Disable a workflow

#### Repository Management
- `fj repo create <name>` - Create a new repository with full option set: `--private`/`--public`, `--description`, `--add-readme`, `--gitignore`, `--license`, `--homepage`, `--clone`, `--team`

#### Issue Management
- `fj issue create -l <label>` - Assign labels when creating an issue
- `fj issue edit --add-label` / `--remove-label` - Add or remove labels on existing issues
- `fj issue close -c <comment>` - Close an issue with an optional comment

#### Workflow Management
- `fj actions workflow list/view/run` - List, view, and trigger workflows

#### Auth Helpers
- `fj auth token` - Print the stored token for the current host
- `fj auth logout` - Remove authentication for a host

#### Shell Completions and Man Pages
- `fj completion [bash|zsh|fish|powershell]` - Generate shell completion scripts
- `fj manpages --dir <path>` - Generate man pages for all commands

#### JSON Output
- `--json` flag for all list and view commands: PRs, issues, releases, workflow runs, workflows

### Fixed
- Respect `$XDG_CONFIG_HOME` for config file location (was always using `~/.config`)

## [0.2.0] - 2026-01-09

### Added

#### Release Management
- `fj release list` - List releases for a repository
- `fj release view` - View details of a specific release (supports "latest" keyword)
- `fj release create` - Create new releases with optional asset uploads
- `fj release upload` - Upload assets to existing releases with optional clobber support
- `fj release delete` - Delete releases (preserves Git tags)

#### Issue Management
- `fj issue edit` - Edit existing issues with support for updating title, body, and labels

#### Pull Request Management
- `fj pr create --assignee` - Assign users when creating pull requests

#### Repository Detection
- Automatic hostname detection from git remote URLs
- Improved multi-instance support with auto-detection from git context

### Improved
- Enhanced documentation with AUR and Homebrew installation instructions
- Added functional tests for release management and issue editing
- Added Makefile `install` target for easier local installation
- Added `.editorconfig` for consistent code formatting

### Development
- CI: Added nightly builds for continuous testing
- Expanded functional test coverage for new features

## [0.1.0] - 2025-12-16

### Added

#### Core Features
- Initial release of fj - Forgejo CLI tool
- Multi-instance support for any Forgejo/Gitea instance
- Automatic repository detection from git context (optional `-R` flag)
- Secure authentication with personal access tokens
- Configuration management via `~/.config/fj/config.yaml`

#### Pull Request Management
- `fj pr list` - List pull requests with filtering by state
- `fj pr view` - View detailed pull request information
- `fj pr create` - Create new pull requests
- `fj pr merge` - Merge pull requests with configurable merge methods

#### Issue Management
- `fj issue list` - List issues with state filtering
- `fj issue view` - View detailed issue information
- `fj issue create` - Create new issues
- `fj issue comment` - Add comments to issues
- `fj issue close` - Close issues

#### Repository Operations
- `fj repo view` - View repository details
- `fj repo list` - List user repositories
- `fj repo clone` - Clone repositories with protocol selection (HTTPS/SSH)
- `fj repo fork` - Fork repositories

#### Forgejo Actions Support
- `fj actions run list` - List workflow runs with status and metadata
- `fj actions run view` - View detailed run information, jobs, and logs
  - Support for `--verbose`, `--log`, `--log-failed`, and `--job` flags
- `fj actions secret list` - List repository secrets
- `fj actions secret create` - Create repository secrets
- `fj actions secret delete` - Delete repository secrets
- `fj actions variable list` - List repository variables
- `fj actions variable get` - Get variable values
- `fj actions variable create` - Create repository variables
- `fj actions variable update` - Update repository variables
- `fj actions variable delete` - Delete repository variables

#### Authentication
- `fj auth login` - Interactive authentication with Forgejo instances
- `fj auth status` - Check authentication status
- Environment variable support (`FJ_HOST`, `FJ_TOKEN`)

#### Development
- Comprehensive unit test suite
- Functional end-to-end tests
- CI/CD pipeline with automated testing
- Code quality checks and linting

### Technical Details
- Built with Go 1.23+
- Uses Gitea SDK for API interactions
- Cobra framework for CLI structure
- Viper for configuration management

[0.3.0c]: https://forgejo.zerova.net/public/fj/releases/tag/v0.3.0c
[0.3.0b]: https://forgejo.zerova.net/public/fj/releases/tag/v0.3.0b
[0.3.0a]: https://forgejo.zerova.net/public/fj/releases/tag/v0.3.0a
[0.3.0]: https://codeberg.org/romaintb/fj/releases/tag/v0.3.0
[0.2.0]: https://codeberg.org/romaintb/fj/releases/tag/v0.2.0
[0.1.0]: https://codeberg.org/romaintb/fj/releases/tag/v0.1.0