pi-gogs-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 summerway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# pi-gogs-cli
+
+A [pi coding agent](https://github.com/earendil-works/pi-coding-agent) skill that ships **gogs-cli** — a GitHub-CLI-style (`gh`) command line for self-hosted [Gogs](https://gogs.io) instances. Usable by any agent (pi, Codex, Claude Code, ...) or by a human, on desktop, headless boxes, containers, and CI. Python 3 stdlib only — zero dependencies.
+
+## Why
+
+Gogs has a usable API for repos/issues/labels but **no pull-request API at all** (`/pulls` 404s), and its issues list excludes PRs. Existing CLIs either ignore PRs or drive a real browser. gogs-cli gives an agent full repo/issue/PR capability with one stateless tool:
+
+- **repo / issue / label** — plain Gogs API (`gh`-style verbs, `issue develop` branches off an issue gh-style)
+- **pr list/create/merge/close/reopen** — headless **webform engine**: session login + CSRF form POSTs against the Gogs Web UI itself, no browser, no OS dependency
+- every webform write is **verified through the API** before success is reported — a submitted form alone is never reported as success
+- `--json` on every command; structured `reason` warnings (exit 2) for `pr merge` no-ops (already merged / empty diff / conflict)
+
+## Install (pi)
+
+```bash
+pi install npm:pi-gogs-cli
+```
+
+The skill's `scripts/gogs-cli` lands under `~/.pi/agent/npm/pi-gogs-cli/...`; symlink it onto PATH:
+
+```bash
+ln -sf ~/.pi/agent/npm/pi-gogs-cli/skills/gogs-cli/scripts/gogs-cli ~/.local/bin/gogs-cli
+```
+
+Any other agent or a human can use the same checkout directly.
+
+## Configuration
+
+All config is loaded from disk, never printed.
+
+| File | Keys |
+|---|---|
+| `~/.config/gogs-cli/config` | `GOGS_TOKEN` (required for API ops), `GOGS_USERNAME` / `GOGS_PASSWORD` (webform PR ops) |
+| `~/.codex/local/gogs-workflow/.env` | legacy location, still honored |
+| `<repo-root>/.gogs.local.env` | `GOGS_BASE_URL`, `GOGS_WEB_BASE_URL`, `GOGS_USERNAME`, `GOGS_PASSWORD` |
+
+Repo-level wins. Create a token in Gogs under `user/settings/applications`.
+
+**Base resolution:** `GOGS_BASE_URL` is probed live; then each address in `GOGS_FALLBACK_URLS` (space/comma-separated) in order — first responder wins, cached per process:
+
+```bash
+GOGS_FALLBACK_URLS="http://192.168.1.10:10015 https://gogs.example.com"
+```
+
+Same invocation on-LAN and off-LAN, no config change. No built-in default; unconfigured runs exit with setup instructions.
+
+Default `OWNER/REPO` derives from `git remote get-url origin`.
+
+## Command surface
+
+```
+gogs-cli repo  view|list
+gogs-cli issue list|view|create|edit|close|reopen|comment|develop
+gogs-cli label list
+gogs-cli pr    list|view|create|merge|close|reopen
+```
+
+Full reference lives in the skill itself (`skills/gogs-cli/SKILL.md`) and is what agents see; the authoritative endpoint map is `skills/gogs-cli/references/gogs-api.md`.
+
+## Merge styles
+
+If the instance offers only one merge style (many Gogs setups expose `create_merge_commit` only), `--squash`/`--rebase` fall back to the offered style with a note. `--delete-branch` is accepted for `gh` compatibility but prints a reminder (manual delete).
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "pi-gogs-cli",
+  "version": "1.0.0",
+  "description": "pi coding agent skill: gh-style CLI for self-hosted Gogs — repos, issues, labels over the Gogs API; pull requests via headless Web-UI form POSTs (Gogs has no PR API). Python 3 stdlib only, cross-platform",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "pi-skill",
+    "gogs",
+    "cli",
+    "git",
+    "self-hosted"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/summerway/pi-gogs-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/summerway/pi-gogs-cli/issues"
+  },
+  "files": [
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "skills": ["./skills"]
+  }
+}

package/skills/gogs-cli/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: gogs-cli
+description: Reusable, agent-agnostic Gogs CLI mirroring the GitHub CLI (`gh`) command surface. Repos, issues (list/view/create/edit/close/reopen/comment, plus gh-style `issue develop` to branch from an issue), and labels (read-only) over the Gogs API; pull requests (Gogs exposes no PR API) via headless Web-UI form POSTs — list/create/merge/close/reopen, no browser needed. Every webform write is verified through the API before success is reported. Base URL comes from config with optional GOGS_FALLBACK_URLS probing, so the same invocation works from several networks. Use for anything read/write against a Gogs instance. Cross-platform (macOS/Linux/containers), Python 3 stdlib, stateless; no workflow mapping.
+---
+
+# gogs-cli
+
+A single command line tool for Gogs capability, usable by any agent (Codex,
+Claude Code, pi, ...) or by a human, on desktop or headless/container hosts.
+Mirrors the GitHub CLI (`gh`) command surface.
+
+- **Interface contract:** `references/gogs-api.md` is the authoritative endpoint
+  map, sourced from `https://gogs.io/api-reference/introduction`. It is the sole
+  reference for the command set; update it when the API or the instance changes.
+- **Encapsulation:** callers see only clean `gh`-style verbs. Whether an
+  operation is served by the Gogs API or by Web-UI form POSTs is hidden.
+- **Stateless:** no workflow mapping, no local database, no `LI/LPR` ids.
+
+## Setup
+
+`gogs-cli` is on PATH (e.g. `~/.local/bin/gogs-cli`, a symlink to this skill's
+`scripts/gogs-cli`). Python 3 stdlib only — no dependencies.
+
+Config (loaded from disk, never printed):
+- `~/.config/gogs-cli/config` → `GOGS_TOKEN` (required for API ops).
+  `~/.codex/local/gogs-workflow/.env` is honored as a legacy location.
+- `<repo-root>/.gogs.local.env` → `GOGS_BASE_URL`, `GOGS_WEB_BASE_URL`,
+  `GOGS_USERNAME`, `GOGS_PASSWORD` (web creds used only for webform PR ops).
+- Either file may hold any of these keys; repo-level wins. On headless/container
+  hosts put everything in the global file, with `GOGS_BASE_URL` pointing at the
+  internal address (e.g. `http://gogs:3000` over a shared Docker network).
+
+Default `OWNER/REPO` is derived from `git remote get-url origin`; pass an explicit
+`OWNER/REPO` positional to override.
+
+**Base resolution.** The Gogs web/API base is resolved at first use and cached
+for the process: the configured `GOGS_BASE_URL`/`GOGS_WEB_BASE_URL` is tried
+first, then each address in `GOGS_FALLBACK_URLS` (space- or comma-separated) in
+order — the first that responds is used. Set e.g.
+`GOGS_FALLBACK_URLS="http://192.168.1.10:10015 https://gogs.example.com"` so the
+same invocation works on-LAN (fast, direct) and off-LAN (public host) with no
+config change. There is no built-in default; with nothing configured the CLI
+exits with setup instructions.
+
+## Commands
+
+```
+# repo — API, read-only
+gogs-cli repo view  [OWNER/REPO] [--json]
+gogs-cli repo list  [--user USER] [--limit N] [--json]
+
+# issue — API
+gogs-cli issue list   [OWNER/REPO] [--state open|closed|all] [--label NAME...] [--assignee USER] [--limit N] [--json]
+gogs-cli issue view   [OWNER/REPO] NUMBER [--json]
+gogs-cli issue create --title T [--body B | -F FILE] [--assignee USER] [--label NAME...] [--milestone N] [OWNER/REPO] [--json]
+gogs-cli issue edit   [OWNER/REPO] NUMBER [--title T] [--body B | -F FILE] [--state open|closed] [--json]
+gogs-cli issue close  [OWNER/REPO] NUMBER [--json]
+gogs-cli issue reopen [OWNER/REPO] NUMBER [--json]
+gogs-cli issue comment [OWNER/REPO] NUMBER [--body B | -F FILE] [--json]
+gogs-cli issue develop [OWNER/REPO] NUMBER [--base B] [--name NAME] [--json]   # local branch off --base, named from the issue (gh-style)
+
+# label — API
+gogs-cli label list [OWNER/REPO] [--json]
+
+# pr — view via API; list/create/merge/close/reopen via Web UI (no PR API)
+gogs-cli pr list   [OWNER/REPO] [--state open|closed|all] [--limit N] [--json]   # Web UI scrape
+gogs-cli pr view   [OWNER/REPO] NUMBER [--json]                                   # API
+gogs-cli pr create [--base B] [--head H] --title T [--body B | -F FILE] [OWNER/REPO] [--json]  # --base default develop, --head default current branch
+gogs-cli pr merge  [OWNER/REPO] NUMBER [--merge|--squash|--rebase] [--delete-branch] [--json]
+gogs-cli pr close  [OWNER/REPO] NUMBER [--json]
+gogs-cli pr reopen [OWNER/REPO] NUMBER [--json]
+```
+
+`--json` switches any command to machine-readable JSON output (the raw API
+object) so other tools/agents can compose. `--label NAME` is resolved to label
+IDs via the labels API (Gogs accepts IDs only) — unknown name → error.
+
+Exit codes: 0 success · 1 failure · 2 soft warning — `pr merge` that cannot
+proceed (empty diff, conflict, already merged) exits 2 with a structured
+`reason` instead of failing hard (details below). `--delete-branch` is
+accepted for `gh` compatibility but **not automated**: it prints a reminder;
+delete the branch manually.
+
+## How PR ops work (no PR API exists)
+
+Gogs exposes **no** pull-request API (`/pulls` returns 404), and the issues list
+**excludes** PRs. So PR operations submit the Gogs Web UI's own forms directly —
+**webform**: Python-stdlib session login + CSRF form POSTs, no browser and no OS
+dependency, identical behavior on macOS, Linux, and containers:
+
+- `pr list` scrapes `/pulls?type=all&state=…` (paginated)
+- `pr create` POSTs the compare-page form (`title`/`content`); the redirect
+  target carries the new PR number
+- `pr merge` POSTs the `/pulls/N/merge` form (`merge_style`)
+- `pr close/reopen` POST the comment form's hidden `status` field
+  (`close`/`reopen`)
+- Web login uses `GOGS_USERNAME`/`GOGS_PASSWORD` from the env files
+
+For every write, `gogs-cli` **verifies the real remote state through the issues
+API** (e.g. `pull_request.merged === true`, or issue `state`) before reporting
+success — a submitted form alone is never reported as success.
+
+`pr merge` that **cannot proceed** (empty-diff / nothing-to-merge, conflict, or
+already-merged) is reported as a **non-zero warning (exit 2)**, not a hard
+failure: Gogs renders no merge form in these cases, so `gogs-cli` reads the
+page banner plus the issues-API `merged` flag and emits a structured `reason`
+(`empty_diff` · `conflict` · `already_merged` · `not_mergeable`) with Gogs's raw
+banner text — in both human and `--json` output. Genuine failures (auth error,
+submitted-but-not-merged, or `#N` is not a PR) still exit 1.
+
+If this Gogs offers only one merge style (e.g. `create_merge_commit` only),
+`--squash`/`--rebase` fall back to the offered style with a stderr note.
+
+Limitations: the `/pulls` closed tab groups merged PRs as "closed" — use
+`pr view N` for the precise merged state; `--base/--head` are not supported by
+`pr list`.
+
+## Token safety
+
+If `GOGS_TOKEN` is missing, `gogs-cli` stops and prints setup instructions — it
+never guesses or retries. Tokens and `.gogs.local.env` contents are never
+printed. Do not commit credentials or workflow mapping files.
+
+## Importing as a module
+
+`gogs_cli.py` is importable. Functions like `resolve_target`, `api`, `api_root`,
+`create`/`view` helpers, and the `webform_*` PR functions can be
+reused directly to avoid duplicating the API client.

package/skills/gogs-cli/references/gogs-api.md

@@ -0,0 +1,98 @@
+# Gogs API Reference (authoritative for `gogs-cli`)
+
+Source of truth for the `gogs-cli` command surface. Captured from the official
+Gogs API docs (`https://gogs.io/api-reference/introduction`, full index
+`https://gogs.io/llms.txt`) and verified against the local instance
+`http://192.168.100.3:10015` (HTTP status in parentheses, probed 2026-08-01).
+
+Any future change to `gogs-cli` commands MUST be justified against this map.
+The official API docs at `https://gogs.io/api-reference/introduction` are the
+sole interface reference; update this file when the API or the instance changes.
+
+## Conventions
+
+- Base path: `/api/v1`.
+- Auth: `Authorization: token <TOKEN>` (the token is read from
+  `~/.codex/local/gogs-workflow/.env` as `GOGS_TOKEN`; never printed).
+- `:owner/:repo` resolves from the `origin` git remote unless overridden.
+- List endpoints paginate with `?page=N` (~10/page). Gogs ignores `limit`; the
+  `type=` param (a Gitea feature) is also ignored. `state=all` is **not** honored
+  — pass a concrete `state=open`/`closed` and combine them for "all".
+
+## Repository (API — read only is wrapped)
+
+| Method | Path | Status | `gogs-cli` |
+|---|---|---|---|
+| GET | `/repos/:owner/:repo` | 200 | `repo view` |
+| GET | `/user/repos` | 200 | `repo list` (authenticated user) |
+| GET | `/users/:username/repos` | 200 | `repo list --user <name>` |
+| GET | `/repos/:owner/:repo/branches` | 200 | _(not wrapped; use `git`)_ |
+
+`repo create/delete/fork/collaborators` are management endpoints — intentionally
+**not** wrapped.
+
+## Issues (API)
+
+| Method | Path | Status | `gogs-cli` |
+|---|---|---|---|
+| GET | `/repos/:owner/:repo/issues` | 200 | `issue list` (supports `state`, `labels`, `assignee`) |
+| GET | `/repos/:owner/:repo/issues/:number` | 200 | `issue view` |
+| POST | `/repos/:owner/:repo/issues` | 201 | `issue create` (body: `title`, `body`, `assignee`, `milestone`, `labels` IDs) |
+| PATCH | `/repos/:owner/:repo/issues/:number` | 200 | `issue edit` / `issue close` / `issue reopen` (body: `state`) |
+| GET | `/repos/:owner/:repo/issues/:number/comments` | 200 | _(shown by `issue view`)_ |
+| POST | `/repos/:owner/:repo/issues/:number/comments` | 201 | `issue comment` |
+
+Notes:
+- `labels` on create/edit takes label **IDs**, not names. `gogs-cli --label NAME`
+  resolves names → IDs via `GET /repos/:owner/:repo/labels` (gh-compatible UX).
+- Closing = `PATCH /issues/:number {"state": "closed"}`; reopen = `{"state": "open"}`.
+
+## Labels (API)
+
+| Method | Path | Status | `gogs-cli` |
+|---|---|---|---|
+| GET | `/repos/:owner/:repo/labels` | 200 | `label list` |
+
+Only `label list` is wrapped (to support `--label` name resolution). Label
+create/edit/delete are management ops — not wrapped.
+
+## Pull Requests (NO API — ego black box)
+
+| Path | Status | Conclusion |
+|---|---|---|
+| `GET /repos/:owner/:repo/pulls` | **404** | No PR list endpoint |
+| `GET /repos/:owner/:repo/pulls/:number` | **404** | No PR get endpoint |
+| `POST /repos/:owner/:repo/pulls` | **absent** | No PR create endpoint |
+| merge/close/reopen | **absent** | No PR mutation endpoints |
+
+Gogs registers **no PR API routes**, and the issues list **excludes** PRs
+entirely (a PR is only observable via `GET /issues/:number`, which then carries a
+`pull_request` key). Therefore in `gogs-cli`:
+
+- **`pr view N`** — served by the **issues endpoint**: `GET /issues/N`, asserting
+  `pull_request` is present. Authoritative (includes `merged`, `base`, `head`).
+- **`pr list`** — **no API exists**; the issues list returns zero PRs. Served by
+  **ego-browser scraping the Web UI**: `/pulls?type=all&state=<open|closed>
+  &labels=0&milestone=0&assignee=0`. The ego profile auto-logs in via
+  `GOGS_USERNAME`/`GOGS_PASSWORD` when it hits `/user/login`. Limitation: the
+  closed tab groups merged PRs as "closed"; use `pr view N` for the precise
+  merged state. `--base/--head` are not filterable here.
+- **PR write** (`pr create`, `pr merge`, `pr close`, `pr reopen`) is performed by
+  **ego-browser on the Gogs Web UI as a black box** (`/compare/...`, `/pulls/:n`,
+  `/pulls/:n/merge`). After the browser action, `gogs-cli` **verifies the real
+  state via the issues API** (e.g. `pull_request.merged === true`, or issue
+  `state`) before reporting success — never trusts a click alone.
+- **`pr merge` nothing-to-merge detection**: when Gogs renders no merge button
+  (empty-diff / nothing-to-merge, conflict, or already-merged), `gogs-cli` reads
+  the page banner + the issues-API `merged` flag and returns a **non-zero warning
+  (exit 2)** carrying `reason` (`empty_diff` · `conflict` · `already_merged` ·
+  `not_mergeable`) and the raw banner text — distinct from a hard failure (exit 1).
+
+## Token setup
+
+When `GOGS_TOKEN` is missing, `gogs-cli` stops and instructs:
+
+1. Log in to the Gogs Web UI.
+2. Open `<base>/user/settings/applications`.
+3. Generate a token (e.g. named `gogs-cli`).
+4. Save to `~/.codex/local/gogs-workflow/.env` as `GOGS_TOKEN=<token>` (chmod 600).

package/skills/gogs-cli/scripts/gogs-cli

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""Console entry for gogs-cli. Resolves the symlink to the real script dir so
+the `gogs_cli` module can be imported, then delegates to gogs_cli.main()."""
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.realpath(__file__)))
+
+import gogs_cli  # noqa: E402
+
+if __name__ == "__main__":
+    gogs_cli.main()