@procedures/gh 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @procedures/gh
 
+## 0.5.0
+
+### Patch Changes
+
+- Updated dependencies [0f75644]
+- Updated dependencies [09e5566]
+- Updated dependencies [ab77f75]
+- Updated dependencies [a47bee6]
+- Updated dependencies [bc74091]
+  - @procedures/client@0.5.0
+  - @procedures/shell@0.5.0
+
+## 0.4.0
+
+### Minor Changes
+
+- 2c02cf0: Three new procedures: `gh.workflow.run`, `gh.run.download` and `gh.api`.
+  
+  - `gh.workflow.run` starts a workflow run on a ref, with each input as `-f key=value`. When `gh` prints the URL of the new run, the output has `url` and `run`. It declares `writes: ["network"]`, and it is not destructive.
+  - `gh.run.download` downloads the artifacts of a run into `dir`, by `names` or `patterns`. It declares `writes: ["fs"]`. `gh` does not replace a file that exists, so it is not destructive.
+  - `gh.api` sends a request to the GitHub API and gives the parsed JSON as `data`. It always sends `--method` (default `GET`). A string field goes as `-f`, another value as `-F`. A JSON `body` goes as `--input` from a temporary file. `paginate` joins the pages of an array. `repo` goes to `gh` as `GH_REPO`.
+  - The method of `gh.api` is an input, and `PUT` or `DELETE` can replace or remove data. Thus `gh.api` declares `writes: ["network"]` and is destructive.
+  
+  These procedures are not MCP tools.
+
+### Patch Changes
+
+- Updated dependencies [d919678]
+- Updated dependencies [057d69a]
+- Updated dependencies [b2a1a1e]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [afd6a19]
+- Updated dependencies [057d69a]
+- Updated dependencies [4c51727]
+- Updated dependencies [4e751da]
+  - @procedures/client@0.4.0
+  - @procedures/shell@0.4.0
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -6,7 +6,7 @@
 npm install @procedures/gh
 ```
 
-The GitHub CLI (`gh`) as procedures: pull requests, workflow runs, releases and issues. Each procedure runs `gh` through `shell.run` of `@procedures/shell`, with an argument list and no shell. The output is the JSON of `gh --json`.
+The GitHub CLI (`gh`) as procedures: pull requests, workflow runs, artifacts, releases, issues and the GitHub API. Each procedure runs `gh` through `shell.run` of `@procedures/shell`, with an argument list and no shell. The output is the JSON of `gh --json`.
 
 `gh` must be on the `PATH`, with a login (`gh auth login`).
 
@@ -21,18 +21,40 @@ The GitHub CLI (`gh`) as procedures: pull requests, workflow runs, releases and
 | `gh.run.list` | The workflow runs: workflow, branch, status, limit | reads |
 | `gh.run.view` | One workflow run with its jobs | reads |
 | `gh.run.rerun` | Run a workflow run again, or only its failed jobs | writes |
+| `gh.run.download` | Download the artifacts of a run: names, patterns, folder | writes `fs` |
+| `gh.workflow.run` | Start a workflow run: workflow, ref, inputs | writes |
 | `gh.release.list` | The releases of a repository | reads |
 | `gh.release.view` | The release of a tag, or the latest release | reads |
 | `gh.issue.list` | The issues: state, label, author, search, limit | reads |
 | `gh.issue.view` | One issue, with its comments | reads |
 | `gh.issue.create` | Open an issue | writes |
 | `gh.issue.comment` | Add a comment to an issue or a pull request | writes |
+| `gh.api` | Send a request to the GitHub API: endpoint, method, fields, body, paginate | writes, destructive |
 
 - A read declares `reads: ["network"]` and changes nothing. A write declares `writes: ["network"]`. It makes something new, so it is not destructive, and a second call makes a second one.
 - Each procedure takes `repo` (owner/name), `cwd` and `timeoutMs`. Without `repo`, `gh` uses the repository of the folder.
 - A value that `gh` reads as an argument (a number, a branch, a label) must not start with `-`. A title or a body is the value of its option, so it can start with `-`.
 - A failed command throws an error with the exit code and the text of `gh`. `gh.pr.checks` reports a pending check as an error that tells you to ask again.
 
+### Workflow runs and artifacts
+
+- `gh.workflow.run` sends each input as `-f key=value`. When GitHub gives the new run, `gh` prints its URL. Then the output has `url` and `run`, the id of the run.
+- Without `run` in the output, find the run with `gh.run.list`. Use the `workflow` and `branch` filters.
+- `gh.run.download` writes the files of the artifacts into `dir`. It declares `writes: ["fs"]`.
+- `gh` puts each artifact in a folder with its name. When the input selects one artifact, the files go directly into `dir`.
+- `gh` does not replace a file that exists. The download then fails. Thus the procedure is not destructive.
+
+### The GitHub API
+
+- `gh.api` always sends `--method`. The default is `GET`. Without this option, `gh` changes `GET` to `POST` when the call has fields.
+- A string field goes as `-f`, and `gh` sends it as text. A number, a boolean or `null` goes as `-F`, and `gh` converts its type.
+- `GET` sends the fields in the query. The other methods send them in the JSON body.
+- `body` is a JSON value. The procedure writes it to a temporary file for `--input`, and removes the file after the call.
+- `gh api` has no `--repo` option. The procedure gives `repo` to `gh` as `GH_REPO`. Then `gh` replaces `{owner}` and `{repo}` in the endpoint.
+- The output is `{ data }`, the parsed JSON. An empty response (HTTP 204) gives `null`.
+- With `paginate: true`, the pages of an array become one array. The pages of an object become an array of the pages.
+- The method is an input, and `PUT` or `DELETE` can replace or remove data. Thus `gh.api` declares `writes: ["network"]` and keeps the default: destructive.
+
 ## Use
 
 ```typescript
@@ -47,6 +69,11 @@ const { items } = await client.exec(["gh", "run", "list"], { repo: "owner/name",
 mark gh run list --repo owner/name --status failure
 ```
 
+```typescript
+const { run } = await client.exec(["gh", "workflow", "run"], { workflow: "ci.yml", ref: "main", inputs: { shards: "4" } });
+const { data } = await client.exec(["gh", "api"], { endpoint: "repos/{owner}/{repo}/pulls", repo: "owner/name", paginate: true });
+```
+
 ## Tests
 
 `pnpm --filter @procedures/gh test` runs the procedures with a fake shell. The tests examine each argument list, the JSON of `gh`, the failures and the values that cannot become options.