feat: gitea: queries

docs/README.md

@@ -3,6 +3,7 @@
 - [Using the `hectic` Attic Cache](./attic-cache.md)
 - [Minecraft incident log](./minecraft-incidents.md)
 - [Project Zomboid backups](./project-zomboid-backups.md)
+- [Gitea Kanban CLI](./gitea-kanban-cli.md)
 
 ## Gitea runner labels
 

docs/gitea-kanban-cli.md

@@ -0,0 +1,126 @@
+# Gitea Kanban CLI
+
+`gitea-kanban` is the non-interactive interface for native Gitea Projects.
+It shares its configuration, API client, models, permissions, and operations
+with `gitea-kanban-tui`.
+
+## Installation
+
+The Nix package installs both binaries:
+
+```sh
+nix build .#gitea-kanban-tui
+./result/bin/gitea-kanban --help
+./result/bin/gitea-kanban-tui --help
+```
+
+For development:
+
+```sh
+cargo run --manifest-path package/gitea-kanban-tui/Cargo.toml \
+  --bin gitea-kanban -- --help
+```
+
+## Configuration
+
+Configuration can be supplied with flags or environment variables. A project
+selector is required, and exactly one selector must be supplied.
+
+| Flag | Environment | Description |
+| --- | --- | --- |
+| `--url` | `GITEA_URL` | Gitea base URL |
+| `--token-file PATH` | `GITEA_TOKEN_FILE` | File containing API token |
+| — | `GITEA_TOKEN` | Token fallback when no token file is configured |
+| `--project NAME` | `GITEA_PROJECT` | Exact, case-sensitive project name |
+| `--project-id ID` | `GITEA_PROJECT_ID` | Project ID; useful for duplicate names |
+| `OWNER` | `GITEA_OWNER` | Repository owner |
+| `REPO` | `GITEA_REPO` | Repository name |
+
+Precedence:
+
+1. Command-line flags and positional arguments.
+2. Token file from `--token-file` or `GITEA_TOKEN_FILE`.
+3. `GITEA_TOKEN` when no token file is configured.
+
+Token files must be regular files and must not be group- or world-readable on
+Unix. Remote URLs must use HTTPS. Plain HTTP is accepted only for literal
+loopback IP addresses (`127.0.0.1` or `::1`) during local development.
+
+Example:
+
+```sh
+export GITEA_URL=https://gitea.example
+export GITEA_TOKEN_FILE="$HOME/.config/gitea/token"
+gitea-kanban --project Kanban owner repo board
+```
+
+## Commands
+
+### `board`
+
+Print selected project, columns, and issues:
+
+```sh
+gitea-kanban --project Kanban owner repo board
+```
+
+Output includes issue numbers and titles. Server-provided terminal control
+characters are removed before output.
+
+### `create`
+
+Create an issue and assign it to selected project. The issue starts in the
+project's default column.
+
+```sh
+gitea-kanban --project Kanban owner repo create \
+  --title "Fix deployment" \
+  --body "Investigate failed rollout"
+```
+
+### `edit`
+
+Replace issue title and body. Issue must be assigned to selected project.
+
+```sh
+gitea-kanban --project Kanban owner repo edit 42 \
+  --title "Updated title" \
+  --body "Updated description"
+```
+
+### `move`
+
+Move an issue to a project column. `ISSUE_ID` is the global Gitea issue ID,
+not the repository issue number. `--sorting` is optional.
+
+```sh
+gitea-kanban --project Kanban owner repo move 123 --column-id 7
+gitea-kanban --project Kanban owner repo move 123 --column-id 7 --sorting 2
+```
+
+### `delete`
+
+Delete an issue assigned to selected project. This is irreversible and requires
+explicit confirmation with `--yes`:
+
+```sh
+gitea-kanban --project Kanban owner repo delete 42 --yes
+```
+
+Deletion also requires repository administrator permission in this Gitea fork.
+
+## Permissions and server behavior
+
+- The repository Projects unit must be enabled.
+- Project operations require repository Projects write permission.
+- Issue create/edit follows Gitea issue permissions.
+- Delete requires repository administrator permission.
+- Closed projects, archived repositories, disabled Projects units, foreign
+  project IDs, and issues outside selected project are rejected.
+- API failures return a non-zero exit status. Authentication and HTTP status
+  guidance is shown without printing server response bodies or tokens.
+
+## Related interface
+
+Use `gitea-kanban-tui` for keyboard navigation over the same native Projects
+API. Both binaries use the same configuration and server-side authorization.