@toon-protocol/rig 4.5.0 → 4.7.0

package/README.md

@@ -212,7 +212,7 @@ rig pr status <event-id> applied
 | `rig issue list` / `rig issue show <id>` | free | the repo's issues + comments from the terminal |
 | `rig pr list` / `rig pr show <id>` | free | the repo's patches/PRs; `show` prints the full patch text (pipe to `git am`) |
 | `rig issue create` | **paid** | file an issue (kind:1621) |
-| `rig comment <root-event-id>` | **paid** | comment (kind:1622) on an issue/patch |
+| `rig comment <target-event-id>` | **paid** | comment (NIP-22 kind:1111) on an issue/patch, or reply to a comment |
 | `rig pr create` | **paid** | publish a patch (kind:1617) from real `git format-patch` |
 | `rig pr status <event-id> <state>` | **paid** | set issue/patch status (kind:1630–1633) |
 | `rig site publish [ref]` | **paid** | deploy a pushed repo as a permaweb site: build the ar.io path manifest (repo paths → Arweave txids) and upload it as one paid store write; prints the gateway URL |
@@ -459,10 +459,58 @@ rig ci serve --relay wss://<relay> --repo <owner-npub>/<repo-id> [--repo …]
 | `--gateway <url>` | `RIG_ARWEAVE_GATEWAY`, else rig's preferred Arweave gateway | the gateway that serves the store's raw bytes: prefix for log/artifact URLs (`<gateway>/raw/<txId>`) **and** the first gateway the coordinator reads a commit's objects from (same `/raw/` route), ahead of the shared public list — name a private or local gateway (the sandbox's) and the coordinator needs nothing else to read |
 | `--act-bin <path>` | `act` on PATH (or `RIG_ACT_BIN`) | the act binary |
 | `--platform <label>=<image>` | `ubuntu-latest=catthehacker/ubuntu:act-latest` | `runs-on` label → Docker image (repeatable) |
+| `--pull` / `--no-pull` | act's default (pull before each run) | whether act pulls the runner image named by `--platform` before each run |
 | `--workdir <dir>` | `<state-dir>/work` | where commits are materialized |
 | `--once` | | stop after the first run concludes (its 9842 and final 39842 are on the relay) — one `rig ci trigger` answered by one bounded serve; ignored or refused triggers do not count |
 | `--json` | | one JSON document with the coordinator, relay, repos and state dir on start |
 
+**Two act behaviours decide whether a real workflow passes**, and a workflow
+whose steps only `echo` hides both:
+
+- **Write `actions/checkout@v4`, exactly as you would on GitHub.** act copies
+  the materialized tree into the job container *at that step*, not when the
+  container starts, and short-circuits it to a local `docker cp` — so the step
+  needs no network and no node in the image. A workflow without it
+  runs its tools against an **empty** container — the steps execute, the files
+  are not there:
+
+  ```
+  error: could not find `Cargo.toml` in `/…/work/<repo>-<sha>-1` or any parent directory
+  ```
+
+  That path is the checkout the coordinator materialized under `--workdir`
+  (`<repo-id>-<short sha>-<n>`), as the job container sees it.
+- **The default image is not GitHub's hosted runner.** `ubuntu-latest` maps to
+  `catthehacker/ubuntu:act-latest`, which carries no language toolchain, so a
+  workflow that expects a preinstalled `cargo`, `go` or JDK fails at its first
+  step. Either point `--platform` at an image that has one
+  (`--platform ubuntu-latest=rust:1-bookworm`) or install it in a step. The
+  official `rust` images ship neither rustfmt nor clippy —
+  `rustup component add rustfmt clippy` is a step, not a given — and an image
+  you built locally needs `--no-pull` (below).
+
+A workflow that survives both, run by a coordinator started with
+`--platform ubuntu-latest=rust:1-bookworm`:
+
+```yaml
+# .github/workflows/ci.yml
+name: ci
+on: [push]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4 # act resolves this to the local copy
+      - run: rustup component add rustfmt clippy
+      - run: cargo fmt --check
+      - run: cargo clippy -- -D warnings
+      - run: cargo test
+```
+
+A runner image built or loaded on the coordinator host and never pushed to a
+registry needs `--no-pull`: without it act force-pulls the image named by
+`--platform` and every run fails in *Set up job* with `pull access denied`.
+
 On start the coordinator publishes an **Advertisement** (19843: runner family
 `act`, its selectors, admission `maintainer-request`, execution
 `request-required`, billing `out-of-band`, and a fresh `secrets-key`) and renews
@@ -510,9 +558,10 @@ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v rig-ci-state:/st
 The entrypoint is `rig`, so every verb works (`docker run --rm rig-ci --version`),
 and every environment variable rig honours means the same inside the image
 (`TOON_CLIENT_HOME` is `/state`). act launches each job as a container on the
-daemon behind the mounted socket and copies the checkout in, so no host path
-has to match. Against the [sandbox](#dogfooding-rigs-own-ciyml-on-the-sandbox)
-on the same host, run on the host network with the sandbox's own `localhost`
+daemon behind the mounted socket and copies the checkout in at the
+`actions/checkout` step, so no host path has to match. Against the
+[sandbox](#dogfooding-rigs-own-ciyml-on-the-sandbox) on the same host, run on
+the host network with the sandbox's own `localhost`
 addresses — a client dials the endpoint a node **advertises**, and the sandbox
 hub advertises `http://127.0.0.1:3200/ilp` so host-run smokes can reach it
 (sandbox-only; a real connector advertises its public URL, which the default
@@ -565,6 +614,11 @@ git commit --allow-empty -m 'ci: dogfood' && rig push --yes
 rig ci status HEAD --json | jq .summary
 ```
 
+`RIG_ARWEAVE_GATEWAY` in that common env also steers the READ path: `rig clone`
+and `rig fetch` try `http://localhost:3000/raw/<txId>` first, so a repo pushed to
+the sandbox clones back out of it even though the public gateways never see those
+objects (see [Reading through your own gateway](#reading-through-your-own-gateway)).
+
 The same flow, end to end and asserted, is
 `src/__integration__/ci-sandbox.integration.test.ts`; it runs only with
 `RIG_CI_SANDBOX=1` and skips itself unless the sandbox's relay, hub, store edge
@@ -744,7 +798,12 @@ per-event fee is quoted and confirmed before publishing; `--yes` skips, `--json`
 without `--yes` is a free estimate:
 
 - `rig issue create --title <t> [--body <b> | --body-file <f> | stdin] [--label <l>]…` — kind:1621.
-- `rig comment <root-event-id> --body <b> [--parent-author <pubkey>] [--marker root|reply]` — kind:1622.
+- `rig comment <target-event-id> --body <b>` — NIP-22 kind:1111. The target is the
+  kind:1621 issue / kind:1617 patch (a top-level comment) or an existing kind:1111
+  comment (a reply). rig reads the target off the relay first, for free, so the
+  thread root's kind and author come from the wire: root scope is uppercase
+  `E`/`K`/`P`, the parent lowercase `e`/`k`/`p`, plus the repo `a` tag. Comments
+  published this way are invisible to rig releases older than 4.6.
 - `rig pr create --title <t> (--range <A..B> | --patch-file <f>) [--body <b> | --body-file <f>] [--branch <name>]` —
   kind:1617; `--range` runs real `git format-patch --stdout` locally and derives the
   `commit`/`parent-commit` tags. A multi-commit range publishes ONE event carrying
@@ -769,9 +828,41 @@ clone never leaves a partial repo. `rig fetch [remote]` is the same pipeline as
 delta: only locally-missing objects are downloaded, and `refs/remotes/<remote>/*`
 (tags → `refs/tags/*`) move with a `git fetch`-style report.
 
+### Reading through your own gateway
+
+By default both commands read from rig's shared public gateway list. A repository
+whose objects live only on a **private, local or air-gapped** gateway is invisible
+there — so `--gateway <url>` (or `RIG_ARWEAVE_GATEWAY`, the same variable `rig push`,
+`rig site` and `rig ci serve` honour) puts that gateway **first**, on the store's
+raw-bytes route `<url>/raw/<txId>`, with the public list kept behind it as the
+fallback. It is the read-path twin of `rig ci serve --gateway`.
+
+```sh
+export RIG_ARWEAVE_GATEWAY=http://localhost:3000   # the dev sandbox's gateway
+rig clone ws://localhost:7100 <owner-npub>/<repo-id>
+rig fetch                                          # or: rig fetch --gateway http://localhost:3000
+```
+
+`/raw/` and not `/<txId>`: an ar.io node serves raw transaction bytes there whether
+or not it does sandboxed-subdomain redirects, and the TOON store's own gateway
+answers on that route alone. Public gateways serve the same bytes on both, so with
+nothing configured the list is exactly as it always was.
+
+The **`Git-SHA` lookup follows the gateway too**. A kind:30618 object map is capped,
+so a SHA it does not carry is resolved by asking a gateway's GraphQL endpoint which
+transaction carries that object — and a configured gateway is asked at
+`<url>/graphql`, never `arweave.net` (which would answer about a *different*
+network, or leak the query off an air-gapped stack). Object bytes are
+content-addressed and SHA-verified, so any mirror may serve them; a tag query is a
+statement about one network, so it goes only to the network you named. Configure
+nothing and it is the shared `arweave.net` resolver, unchanged. A gateway that does
+not serve GraphQL therefore resolves nothing — name one that does (every ar.io node
+does), or leave the variable unset.
+
 `rig issue list|show` and `rig pr list|show` are pure relay reads (kind:1621/1617 by
-the repo `#a` tag; state from kind:1630-1633, latest wins; kind:1622 comments under
-`show`).
+the repo `#a` tag; state from kind:1630-1633, latest wins; comments under `show` —
+NIP-22 kind:1111 matched on the uppercase `E` root tag, merged with legacy kind:1622
+by `created_at`).
 
 ## Library
 
@@ -784,7 +875,9 @@ it — that stays behind the `Publisher` seam:
   a deprecated alias; it is no longer a cap).
 - `nip34-events.ts` — NIP-34 event builders returning `UnsignedEvent`:
   `buildRepoAnnouncement` (30617), `buildRepoRefs` (30618), `buildIssue` (1621),
-  `buildComment` (1622), `buildPatch` (1617), `buildStatus` (1630–1633).
+  `buildComment` (NIP-22 1111; `LEGACY_COMMENT_KIND` = 1622 stays exported for
+  READING old threads and is never written), `buildPatch` (1617),
+  `buildStatus` (1630–1633).
 - `repo-reader.ts` — `GitRepoReader`, read-only local-repo access via injection-safe
   `execFile` git plumbing.
 - `remote-state.ts` — `fetchRemoteState`, the "what does the remote have?" reader.