From 81cafa98ea7a58f41210f550f6bbed4e78cf9cd2 Mon Sep 17 00:00:00 2001 From: Corvid Agent <0xopenbytes@gmail.com> Date: Thu, 21 May 2026 18:12:05 -0700 Subject: [PATCH] docs: refresh README to cover v0.6.5 surface; tighten CHANGELOG format MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README was stale at v0.6.0 — still mentioned `/tmp/fledge-gh-*` (changed in v0.6.5) and didn't document any of the write ops (prs comment / review / merge / close), the `repo` subcommand family (file / clone / workspace / workspace-push / workspace-clean), the `-R` flag (added in v0.6.1), or `prs --head` (v0.6.4). Rewrote it to cover the full current surface and added a worked example of the five-step edit-and-PR loop so users can see how the pieces fit together. CHANGELOG: kept the historical record (Keep a Changelog convention), but normalized the formatting — em-dashes between version + date, moved the v0.6.3 free-floating paragraph into a proper summary line above its bullets, lightly tightened v0.6.0 / v0.6.4 / v0.6.5 prose without dropping any content. Also dropped the "Other" section in v0.2.0/v0.2.1 by reclassifying its bullets as Features / Fixes. --- CHANGELOG.md | 81 ++++++++++------------- README.md | 181 ++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 164 insertions(+), 98 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d076f0..d690208 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,88 +1,79 @@ # Changelog -## [v0.6.5] - 2026-05-21 +All notable changes are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [Semantic Versioning](https://semver.org/) once we tag 1.0. + +## [v0.6.5] — 2026-05-21 ### Fixes -- `repo workspace` now creates clones under `~/.fledge/workspaces/--XXXXXX/` instead of `/tmp/fledge-gh-XXXXXX/`. macOS auto-prunes `/tmp` and well-meaning disk-cleanup sweeps wipe it, both of which were destroying agent workspaces mid-task. The new location is stable across reboots and shows up alongside the rest of fledge state. -- `repo workspace-clean` and `repo workspace-push` still accept the legacy `/tmp/fledge-gh-*` prefix so any in-flight workspaces from v0.6.4 and earlier can be pushed or cleaned without manual intervention. +- `repo workspace` now creates clones under `~/.fledge/workspaces/--XXXXXX/` instead of `/tmp/fledge-gh-XXXXXX/`. macOS auto-prunes `/tmp` and well-meaning disk-cleanup sweeps wipe it, both of which were destroying agent workspaces mid-task. The new location is stable across reboots. +- `workspace-clean` and `workspace-push` still accept the legacy `/tmp/fledge-gh-*` prefix so in-flight workspaces from v0.6.4 aren't orphaned by the upgrade. - Override the workspace root with `FLEDGE_WORKSPACES_DIR` for tests / CI / custom layouts. -## [v0.6.4] - 2026-05-21 +## [v0.6.4] — 2026-05-21 ### Features -- `repo workspace-push [-b BRANCH] [-m MSG]` — closes the agent edit-and-PR loop. Optionally checks out / creates a branch, optionally stages + commits any uncommitted changes (when `-m` is given), then `git push -u origin HEAD`. Same `/tmp/fledge-gh-*` safety guard as the other workspace commands. In `--json` mode emits `{branch, repo, path}` so the agent can chain straight into `prs create -R … -H …`. -- `prs create --head ` — wires gh's `--head` through so an agent can create a PR for a branch that lives in a different working tree (the typical post-`workspace-push` case where the cwd isn't the cloned repo). +- `repo workspace-push [-b BRANCH] [-m MSG]` — closes the edit-and-PR loop. Optionally checks out / creates a branch, optionally stages + commits any uncommitted changes (when `-m` is given), then `git push -u origin HEAD`. With `--json` emits `{branch, repo, path}` so callers can chain straight into `prs create -R … -H …`. +- `prs create --head ` — wires gh's `--head` through so a PR can be opened for a branch that lives in a different working tree (the typical post-`workspace-push` case). -## [v0.6.3] - 2026-05-21 +## [v0.6.3] — 2026-05-21 ### Features -- `repo clone [DIR]` — structured clone command, wraps `gh repo clone` (inherits your `gh auth` for private repos). Optional `--depth N` for shallow clones. -- `repo workspace [-r REF] [--depth N]` — the higher-level "give me a sandbox" command for agents. Creates a fresh `/tmp/fledge-gh---XXXXXX/` dir, clones the repo there (optionally shallow + at a specific ref), and prints the absolute path on stdout. The `-r REF` is wired through to git's `--branch` so shallow + ref work together. -- `repo workspace-clean ` — `rm -rf`s a workspace dir. Refuses to remove anything that doesn't live under `/tmp/fledge-gh-`, so a bad agent path can't wipe arbitrary files. +A structured path for cloning a repo for edit work, instead of falling back to `shell-exec git clone …` which is auto-denied by the Tier 1.5 safety gate in merlin's `--yes` mode. -These give agents driven from non-interactive bridges (Discord/Telegram) a structured path to clone a repo for edit work, instead of falling back to `shell-exec git clone ...` which is auto-denied by the Tier 1.5 safety gate in merlin's `--yes` mode. +- `repo clone [DIR]` — thin wrapper over `gh repo clone`, inherits your `gh auth` for private repos. Optional `--depth N` for shallow clones. +- `repo workspace [-r REF] [--depth N]` — higher-level "give me a sandbox". Creates a fresh dir, clones the repo there (optionally shallow + at a specific ref via git's `--branch`), and prints the absolute path on stdout. +- `repo workspace-clean ` — `rm -rf` with a safety guard that refuses anything not under the workspace root. -## [v0.6.2] - 2026-05-21 +## [v0.6.2] — 2026-05-21 ### Fixes -- `repo view` now also accepts `OWNER/NAME` as a positional argument, matching `gh repo view`'s native syntax. Previously the agent's natural-looking `repo view CorvidLabs/corvid-verify` failed with `unknown argument` and forced an awkward retry with `-R`. -- `repo file` now detects whether the path resolves to a file or a directory and renders accordingly: file → decoded contents (as before), directory → `nametypesize` listing. Previously a directory path hit `jq: expected an object but got: array` and the agent had no way to browse remote repos. +- `repo view` now also accepts `OWNER/NAME` as a positional, matching `gh repo view`'s native syntax. Previously the natural-looking `repo view CorvidLabs/corvid-verify` failed with `unknown argument`. +- `repo file` now detects whether PATH resolves to a file or a directory and renders accordingly: file → decoded contents (as before); directory → `nametypesize` listing. Previously a directory path hit `jq: expected an object but got: array`. -## [v0.6.1] - 2026-05-21 +## [v0.6.1] — 2026-05-21 ### Fixes -- Add `-R, --repo OWNER/NAME` flag to `prs`, `issues`, and `checks` so agents can target any repo without first changing into a clone. Previously every PR / issue subcommand defaulted to `gh`'s cwd-based detection, which silently pointed at the wrong repo when the agent was running in a different working tree — leading to spurious 404s when looking up a PR in a different project. -- `checks -R OWNER/NAME` now falls back to that repo's default branch when `--branch` isn't given, instead of using the local current branch (which has no meaning cross-repo). +- Add `-R, --repo OWNER/NAME` flag to `prs`, `issues`, and `checks` so callers can target any repo without first changing into a clone. Previously each subcommand defaulted to `gh`'s cwd-based detection, which silently pointed at the wrong repo and gave spurious 404s. +- `checks -R OWNER/NAME` now falls back to that repo's default branch when `--branch` isn't given, instead of using the local current branch. -## [v0.6.0] - 2026-05-21 +## [v0.6.0] — 2026-05-21 ### Features -- `prs view`: add `--diff` and `--comments` flags to append the unified diff and conversation comments + reviews to the view output. -- `prs comment -b BODY`: post a comment on a pull request. -- `prs review `: submit a review — one of `--approve`, `--request-changes`, or `--comment-review`, plus `--body`. -- `prs merge `: merge a PR with `--squash` (default), `--merge`, or `--rebase`. -- `prs close ` / `prs reopen `: close without merging or reopen. -- `issues view`: add `--comments` flag to append the issue conversation. -- `issues comment -b BODY`: post a comment on an issue. -- `issues close ` / `issues reopen `. +Expanded the read-only surface (`checks`, `issues view/list/create`, `prs view/list/create`) with the write ops and repo-content access that real workflows actually need. + +- `prs view`: `--diff` and `--comments` flags to append the unified diff and conversation comments + reviews. +- `prs comment -b BODY`, `prs merge [--squash|--merge|--rebase]`, `prs close `, `prs reopen `. +- `prs review ` — submit a review (`--approve` / `--request-changes` / `--comment-review`, plus `--body`). +- `issues view --comments`, `issues comment -b BODY`, `issues close `, `issues reopen `. - New `repo` subcommand: - `repo view [-R OWNER/NAME] [--json]` — repo metadata. - - `repo file [-R OWNER/NAME] [-r REF] [--json]` — read a file's contents at any ref via `gh api repos/.../contents/...`. Closes the gap where agents fell back to authenticated-failing `web-fetch` against `raw.githubusercontent.com`. + - `repo file [-R OWNER/NAME] [-r REF] [--json]` — file contents at any ref, via `gh api repos/.../contents/...`. Closes the gap where consumers had to `web-fetch raw.githubusercontent.com` URLs that fail on auth. -## [v0.5.0] - 2026-05-13 +## [v0.5.0] — 2026-05-13 ### Features -- Add `fledge github poll` subcommand for daemon event polling (#5) - - Polls GitHub for new issues and PRs via the `gh` CLI - - Outputs JSON array of Event objects matching the Merlin daemon schema - - Supports `--since`, `--types`, `--label`, `--repo`, `--limit`, `--state` options - - Uses python3 for JSON transformation +- Add `fledge github poll` subcommand for daemon event polling (#5). Polls GitHub for new issues and PRs via the `gh` CLI; outputs a JSON array of Event objects matching the Merlin daemon schema. Supports `--since`, `--types`, `--label`, `--repo`, `--limit`, `--state`. -## [v0.2.1] - 2026-04-25 +## [v0.2.1] — 2026-04-25 -### Other +### Fixes -- Fix: resolve dispatcher symlink to find sibling helpers (f6dd786) +- Resolve dispatcher symlink to find sibling helpers (f6dd786). -## [v0.2.0] - 2026-04-25 +## [v0.2.0] — 2026-04-25 ### Features -- initial scaffold — checks, issues, prs (663d27e) +- Initial scaffold — `checks`, `issues`, `prs` (663d27e). +- Nest commands under `fledge github` (a43948f). ### Fixes -- add missing plugin.toml manifest (37e9680) - -### Other - -- Bump: version 0.2.0 (671593a) -- Refactor: nest commands under `fledge github` (a43948f) - +- Add missing `plugin.toml` manifest (37e9680). diff --git a/README.md b/README.md index 1ea8fb8..d06cdac 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![CI](https://github.com/CorvidLabs/fledge-plugin-github/actions/workflows/ci.yml/badge.svg)](https://github.com/CorvidLabs/fledge-plugin-github/actions/workflows/ci.yml) -GitHub commands for [fledge](https://github.com/CorvidLabs/fledge) — view CI checks, issues, pull requests, and poll for daemon events through the `gh` CLI. +GitHub commands for [fledge](https://github.com/CorvidLabs/fledge) — list/view/create/comment/review/merge pull requests, list/view/create/comment/close issues, read repo files at any ref, clone repos into managed workspaces, view CI checks, and poll for daemon events — all through the `gh` CLI. These commands lived in fledge core through v0.14, then moved to this plugin as part of the v0.15 tight-core refactor. The plugin keeps fledge's binary lean for users on GitLab, Gitea, or self-hosted Git, and lets the GitHub-specific surface evolve independently. @@ -16,93 +16,166 @@ Requires the [`gh` CLI](https://cli.github.com/) installed and authenticated (`g ## Commands -All commands are nested under `fledge github` so the GitHub-specific surface stays out of the way for users on other forges. +All commands are nested under `fledge github` so the GitHub-specific surface stays out of the way for users on other forges. **Every PR/issue/checks subcommand accepts `-R OWNER/NAME`** to target a repo other than the one in the current directory. -### `fledge github checks [--branch ] [--json]` - -Show CI/CD check-run status for a branch. Defaults to the current branch. +### `fledge github prs` — list, view, create, comment, review, merge, close, reopen ``` -$ fledge github checks -* CI checks for main: - - ✅ test (macos-latest) success 37s - ✅ test (ubuntu-latest) success 41s - ✅ test (windows-latest) success 2m 22s - ✅ lint success 30s - ✅ spec-check success 4s - - 5 checks: 5 passed +fledge github prs [list] List open PRs (default) +fledge github prs view View a specific PR +fledge github prs create Create a new PR +fledge github prs comment -b BODY Post a comment +fledge github prs review ... Submit a review +fledge github prs merge [--squash|...] Merge the PR +fledge github prs close Close without merging +fledge github prs reopen Reopen a closed PR ``` -JSON output is the raw GitHub API response from `repos/{owner}/{repo}/commits/{branch}/check-runs`. - -### `fledge github issues [list | view | create | comment | close | reopen ] [OPTIONS]` - -Browse, create, and write to issues. Lists by default. +**List / view options:** `--state {open,closed,merged,all}`, `--limit `, `-R OWNER/NAME`, `--json`. On `view`: `--diff` appends the unified diff, `--comments` appends conversation comments + reviews. -``` -$ fledge github issues --state all --limit 5 -$ fledge github issues view 42 --comments -$ fledge github issues create --title "Bug: something broke" -$ fledge github issues comment 42 -b "Reproduced on 0.3.1." -$ fledge github issues close 42 -$ fledge github issues reopen 42 -``` +**Create options:** `-t/--title`, `-b/--body`, `--base BRANCH`, `-H/--head BRANCH`, `--draft`, `--fill`, `--ai`, `-R OWNER/NAME`, `--json`. `--ai` generates the title and body by sending your commits and diff to `fledge ask`; you confirm, edit, or abort before the PR is opened. -List/view options: `--state {open,closed,all}`, `--limit `, `--label