feat: initial version of the project

2025-12-08 09:49:07 +01:00 · 2025-12-08 09:49:07 +01:00 · 5b67d39aba
commit 5b67d39aba
13 changed files with 1538 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,214 @@
+# fgj - Forgejo CLI Tool
+
+`fgj` is a command-line tool for working with Forgejo instances (including Codeberg.org). It brings pull requests, issues, and other Forgejo concepts to the terminal, similar to what `gh` does for GitHub.
+
+## Features
+
+- Multi-instance support (works with any Forgejo instance)
+- Pull request management (create, list, view, merge)
+- Issue tracking (create, list, view, comment, close)
+- Repository operations (view, list, clone, fork)
+- Secure authentication with personal access tokens
+- AI coding agent friendly
+
+## Installation
+
+### From Source
+
+```bash
+git clone https://codeberg.org/romaintb/fgj.git
+cd fgj
+go build -o fgj
+sudo mv fgj /usr/local/bin/
+```
+
+### Using Go Install
+
+```bash
+go install codeberg.org/romaintb/fgj@latest
+```
+
+## Quick Start
+
+### 1. Authenticate
+
+First, authenticate with your Forgejo instance:
+
+```bash
+fgj auth login
+```
+
+You'll be prompted for:
+- Forgejo instance hostname (default: codeberg.org)
+- Personal access token
+
+To create a personal access token:
+1. Go to your Forgejo instance (e.g., https://codeberg.org)
+2. Navigate to Settings > Applications > Generate New Token
+3. Give it appropriate permissions (repo, issue, etc.)
+4. Copy the token and paste it when prompted
+
+### 2. Check Authentication Status
+
+```bash
+fgj auth status
+```
+
+## Usage
+
+### Pull Requests
+
+```bash
+# List pull requests
+fgj pr list -R owner/repo
+
+# View a specific pull request
+fgj pr view 123 -R owner/repo
+
+# Create a pull request
+fgj pr create -R owner/repo -t "PR Title" -b "PR Description" -H feature-branch -B main
+
+# Merge a pull request
+fgj pr merge 123 -R owner/repo --merge-method squash
+```
+
+### Issues
+
+```bash
+# List issues
+fgj issue list -R owner/repo
+
+# View an issue
+fgj issue view 456 -R owner/repo
+
+# Create an issue
+fgj issue create -R owner/repo -t "Issue Title" -b "Issue Description"
+
+# Comment on an issue
+fgj issue comment 456 -R owner/repo -b "My comment"
+
+# Close an issue
+fgj issue close 456 -R owner/repo
+```
+
+### Repositories
+
+```bash
+# View repository details
+fgj repo view owner/repo
+
+# List your repositories
+fgj repo list
+
+# Clone a repository
+fgj repo clone owner/repo
+
+# Clone via SSH
+fgj repo clone owner/repo -p ssh
+
+# Fork a repository
+fgj repo fork owner/repo
+```
+
+## Configuration
+
+Configuration is stored in `~/.config/fgj/config.yaml`:
+
+```yaml
+hosts:
+  codeberg.org:
+    hostname: codeberg.org
+    token: your_token_here
+    user: your_username
+    git_protocol: https
+  my-forgejo.com:
+    hostname: my-forgejo.com
+    token: another_token
+    user: another_username
+    git_protocol: ssh
+```
+
+### Environment Variables
+
+- `FGJ_HOST`: Override the default Forgejo instance
+- `FGJ_TOKEN`: Provide authentication token
+
+### Command-line Flags
+
+- `--hostname`: Specify Forgejo instance for a command
+- `--config`: Use a custom config file
+
+## Use with AI Coding Agents
+
+`fgj` is designed to work seamlessly with AI coding agents like Claude Code. Common patterns:
+
+```bash
+# Create PR from agent's changes
+fgj pr create -R owner/repo -t "feat: add new feature" -b "$(cat <<EOF
+## Summary
+- Added new feature X
+- Fixed bug Y
+
+Generated with AI assistance
+EOF
+)"
+
+# Check PR status during development
+fgj pr list -R owner/repo --state open
+
+# View PR details for review
+fgj pr view 123 -R owner/repo
+```
+
+## Supported Forgejo Instances
+
+`fgj` works with any Forgejo instance, including:
+
+- [Codeberg.org](https://codeberg.org) (default)
+- Self-hosted Forgejo instances
+- Gitea instances (compatible API)
+
+## Development
+
+### Building
+
+```bash
+go build -o fgj
+```
+
+### Testing
+
+```bash
+go test ./...
+```
+
+### Project Structure
+
+```
+fgj/
+├── cmd/                 # Command implementations
+│   ├── root.go         # Root command and config
+│   ├── auth.go         # Authentication commands
+│   ├── pr.go           # Pull request commands
+│   ├── issue.go        # Issue commands
+│   └── repo.go         # Repository commands
+├── internal/
+│   ├── api/            # API client wrapper
+│   └── config/         # Configuration management
+├── main.go             # Entry point
+└── go.mod              # Dependencies
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License
+
+## Acknowledgments
+
+- Inspired by GitHub's `gh` CLI tool
+- Built using the [Gitea SDK](https://code.gitea.io/sdk) (compatible with Forgejo)
+- Uses [Cobra](https://github.com/spf13/cobra) for CLI framework