From f2c0b3fb6a428f25e99ef5deb76cd00056cb4f55 Mon Sep 17 00:00:00 2001 From: Holger Selover-Stephan Date: Fri, 13 Nov 2026 07:18:42 +0000 Subject: [PATCH 01/10] =?UTF-8?q?test:=20red=20pin=20=E2=80=94=20the=20con?= =?UTF-8?q?formance=20suite=20against=20the=20hadron-cli=20runner's=20rule?= =?UTF-8?q?s=20(hadron-memory/hadron-cli#1963)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The suite builds the adapter and drives it the way the hadron-cli intake runner does (585bd9d6, internal/intake): ` `, no shell, one JSON object on stdin with contractVersion, one JSON object on stdout. The runner's bounds are copied, not imported (the package is internal to the CLI module), and each names its source. A fake GitHub stands in for the API. Red on the stub main: every call exits 1, "not implemented yet". Worker: Jonas (cli-engineer) Co-Authored-By: Claude Opus 5.5 --- .gitignore | 8 + LICENSE | 21 + cmd/hadron-task-adapter-github/main.go | 13 + conformance/conformance_test.go | 538 +++++++++++++++++++++++++ conformance/runner_rules.go | 150 +++++++ go.mod | 3 + internal/fakegithub/fakegithub.go | 384 ++++++++++++++++++ 7 files changed, 1117 insertions(+) create mode 100644 .gitignore create mode 100644 LICENSE create mode 100644 cmd/hadron-task-adapter-github/main.go create mode 100644 conformance/conformance_test.go create mode 100644 conformance/runner_rules.go create mode 100644 go.mod create mode 100644 internal/fakegithub/fakegithub.go diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a53331a --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +# A team's own adapter configuration (repositories, labels, team map) and any +# credential stay out of this public repository. Only config.example.json is +# committed. +/config.json +*.local.json +.env +/bin/ +/dist/ diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..bd04856 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Hadron Memory + +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. diff --git a/cmd/hadron-task-adapter-github/main.go b/cmd/hadron-task-adapter-github/main.go new file mode 100644 index 0000000..aff998d --- /dev/null +++ b/cmd/hadron-task-adapter-github/main.go @@ -0,0 +1,13 @@ +// Command hadron-task-adapter-github is the GitHub intake adapter for Hadron +// teams (cor:agt:120:04). +package main + +import ( + "fmt" + "os" +) + +func main() { + fmt.Fprintln(os.Stderr, "hadron-task-adapter-github: not implemented yet") + os.Exit(1) +} diff --git a/conformance/conformance_test.go b/conformance/conformance_test.go new file mode 100644 index 0000000..fba4fda --- /dev/null +++ b/conformance/conformance_test.go @@ -0,0 +1,538 @@ +package conformance + +import ( + "bytes" + "encoding/json" + "fmt" + "os" + "os/exec" + "path/filepath" + "regexp" + "runtime" + "strings" + "testing" + "time" + + "github.com/hadron-memory/hadron-task-adapter-github/internal/fakegithub" +) + +// The suite runs the BUILT adapter the way the hadron-cli runner does: +// ` `, no shell, one JSON object on stdin carrying +// contractVersion, the answer one JSON object on stdout with exit 0. + +const token = "ghp_FAKEconformanceTOKEN0000000000000000" + +var bin string + +func TestMain(m *testing.M) { + dir, err := os.MkdirTemp("", "adapter-conformance-") + if err != nil { + panic(err) + } + bin = filepath.Join(dir, "hadron-task-adapter-github") + if runtime.GOOS == "windows" { + bin += ".exe" + } + build := exec.Command("go", "build", "-o", bin, "../cmd/hadron-task-adapter-github") + build.Stdout, build.Stderr = os.Stderr, os.Stderr + if err := build.Run(); err != nil { + fmt.Fprintln(os.Stderr, "building the adapter failed:", err) + os.Exit(1) + } + code := m.Run() + _ = os.RemoveAll(dir) + os.Exit(code) +} + +type env struct { + t *testing.T + gh *fakegithub.Server + config string + vars []string +} + +func newEnv(t *testing.T, cfg map[string]any) *env { + t.Helper() + gh := fakegithub.New(token) + t.Cleanup(gh.Close) + cfg["apiUrl"] = gh.URL + b, _ := json.Marshal(cfg) + p := filepath.Join(t.TempDir(), "config.json") + if err := os.WriteFile(p, b, 0o600); err != nil { + t.Fatal(err) + } + return &env{t: t, gh: gh, config: p, vars: []string{"GITHUB_TOKEN=" + token}} +} + +type result struct { + code int + stdout, stderr []byte +} + +// call runs one adapter call with the runner's request shape. +func (e *env) call(name string, req map[string]any) result { + e.t.Helper() + body := map[string]any{"contractVersion": ContractVersion} + for k, v := range req { + body[k] = v + } + stdin, _ := json.Marshal(body) + return e.raw([]string{name}, stdin) +} + +func (e *env) raw(args []string, stdin []byte) result { + e.t.Helper() + cmd := exec.Command(bin, args...) + cmd.Stdin = bytes.NewReader(stdin) + cmd.Env = append([]string{"PATH=" + os.Getenv("PATH"), "HOME=" + e.t.TempDir(), "TASK_ADAPTER_GITHUB_CONFIG=" + e.config}, e.vars...) + var out, errb bytes.Buffer + cmd.Stdout, cmd.Stderr = &out, &errb + err := cmd.Run() + code := 0 + if ee, ok := err.(*exec.ExitError); ok { + code = ee.ExitCode() + } else if err != nil { + e.t.Fatal(err) + } + return result{code: code, stdout: out.Bytes(), stderr: errb.Bytes()} +} + +func (e *env) ok(name string, req map[string]any, out any) { + e.t.Helper() + r := e.call(name, req) + if r.code != 0 { + e.t.Fatalf("%s exited %d: %s", name, r.code, r.stderr) + } + if err := OneObject(r.stdout, out); err != nil { + e.t.Fatalf("%s: %v", name, err) + } + e.noToken(r) +} + +func (e *env) noToken(r result) { + e.t.Helper() + if bytes.Contains(r.stdout, []byte(token)) || bytes.Contains(r.stderr, []byte(token)) { + e.t.Fatalf("the GitHub credential was printed:\nstdout %s\nstderr %s", r.stdout, r.stderr) + } +} + +// walk pages list-untracked as the runner's Walk does, applying its checks: +// a page bound, no repeated cursor, and an item seen once is not offered +// again. between runs after each page, before the next is asked for. +func (e *env) walk(forWorker string, limit int, between func([]Item)) []Item { + e.t.Helper() + seen := map[string]bool{"": true} + got := []Item{} + cursor := "" + for pages := 0; ; pages++ { + if pages >= MaxPages { + e.t.Fatalf("the list did not end within %d pages", MaxPages) + } + req := map[string]any{"limit": limit} + if cursor != "" { + req["cursor"] = cursor + } + if forWorker != "" { + req["for"] = forWorker + } + var p Page + e.ok("list-untracked", req, &p) + if err := CheckPage(p); err != nil { + e.t.Fatal(err) + } + if len(p.Items) > limit { + e.t.Fatalf("asked for %d, got %d", limit, len(p.Items)) + } + got = append(got, p.Items...) + if between != nil { + between(p.Items) + } + if p.NextCursor == nil { + return got + } + if seen[*p.NextCursor] { + e.t.Fatalf("the adapter repeated a cursor: %q", *p.NextCursor) + } + seen[*p.NextCursor] = true + cursor = *p.NextCursor + } +} + +func ids(items []Item) []string { + out := []string{} + for _, it := range items { + out = append(out, it.ExternalID) + } + return out +} + +func day(n int) time.Time { return time.Date(2026, 11, n, 12, 0, 0, 0, time.UTC) } + +func TestDescribeConforms(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + var d Describe + e.ok("describe", nil, &d) + if err := CheckDescribe(d); err != nil { + t.Fatal(err) + } +} + +// describe answers even with no configuration and no credential: the runner +// asks it first, to check the contract version, before anything else. +func TestDescribeNeedsNoConfigOrCredential(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + e.config = filepath.Join(t.TempDir(), "missing.json") + e.vars = nil + var d Describe + e.ok("describe", nil, &d) + if err := CheckDescribe(d); err != nil { + t.Fatal(err) + } +} + +// The walk lists every eligible open issue of every repository exactly once, +// oldest first across repositories (then repository, then number), and +// leaves out excluded, not-ready and already-marked issues. +func TestWalkListsEveryEligibleIssueOnceOldestFirst(t *testing.T) { + e := newEnv(t, map[string]any{ + "repositories": []string{"acme/app", "Acme/Lib"}, + "readyLabel": "cleared", + "excludeLabels": []string{"epic"}, + }) + e.gh.AddRepo("acme/app", + fakegithub.Issue{Number: 1, Title: "app one", CreatedAt: day(1), Labels: []string{"Cleared"}}, + fakegithub.Issue{Number: 2, Title: "not ready", CreatedAt: day(2)}, + fakegithub.Issue{Number: 3, Title: "an epic", CreatedAt: day(3), Labels: []string{"cleared", "EPIC"}}, + fakegithub.Issue{Number: 4, Title: "already marked", CreatedAt: day(4), Labels: []string{"cleared", "hadron-tracked"}}, + fakegithub.Issue{Number: 5, Title: "closed", CreatedAt: day(5), State: "CLOSED", Labels: []string{"cleared"}}, + fakegithub.Issue{Number: 6, Title: "app six", CreatedAt: day(8), Labels: []string{"cleared"}}, + ) + e.gh.AddRepo("Acme/Lib", + fakegithub.Issue{Number: 9, Title: "lib nine", CreatedAt: day(2), Labels: []string{"cleared"}}, + fakegithub.Issue{Number: 7, Title: "lib seven", CreatedAt: day(6), Labels: []string{"cleared"}}, + ) + for _, limit := range []int{1, 2, 100} { + got := ids(e.walk("", limit, nil)) + want := []string{ + e.gh.URL("acme/app", 1), e.gh.URL("Acme/Lib", 9), e.gh.URL("Acme/Lib", 7), e.gh.URL("acme/app", 6), + } + if strings.Join(got, " ") != strings.Join(want, " ") { + t.Fatalf("limit %d:\n got %v\nwant %v", limit, got, want) + } + } + // The external id is GitHub's own canonical URL, in GitHub's spelling. + if got := e.gh.URL("Acme/Lib", 9); got != "https://github.com/Acme/Lib/issues/9" { + t.Fatalf("fixture: %s", got) + } +} + +// The set shrinks while others claim: items marked tracked between pages +// must not make the walk skip anything that is still untracked. +func TestMarksBetweenPagesSkipNothing(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + issues := []fakegithub.Issue{} + for i := 1; i <= 7; i++ { + issues = append(issues, fakegithub.Issue{Number: i, Title: fmt.Sprint("t", i), CreatedAt: day(i)}) + } + e.gh.AddRepo("acme/app", issues...) + got := e.walk("", 2, func(page []Item) { + for _, it := range page { + var ans map[string]any + e.ok("mark-tracked", map[string]any{"externalId": it.ExternalID, "task": map[string]any{"id": "t-" + it.ExternalID}, "worker": map[string]any{"name": "W"}}, &ans) + } + }) + if len(got) != 7 { + t.Fatalf("a walk with marks between pages listed %d of 7: %v", len(got), ids(got)) + } + if left := e.walk("", 100, nil); len(left) != 0 { + t.Fatalf("marked items are listed again: %v", ids(left)) + } +} + +func TestMarkThenUntrackRoundTrip(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}, "trackedLabel": "in-hadron"}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 4, Title: "x", CreatedAt: day(1), Labels: []string{"bug"}}) + id := e.gh.URL("acme/app", 4) + var ans map[string]any + e.ok("mark-tracked", map[string]any{"externalId": id, + "task": map[string]any{"id": "01abc", "handle": "AT1.2", "portalUrl": "https://hadronmemory.com/app/u/x"}, + "worker": map[string]any{"id": "w1", "name": "Jonas", "role": "cli-engineer", "model": "m"}}, &ans) + if l := e.gh.Labels("acme/app", 4); strings.Join(l, ",") != "bug,in-hadron" { + t.Fatalf("labels after mark: %v", l) + } + if len(e.gh.Comments) != 0 { + t.Fatalf("a comment was posted without comment: true in the config: %v", e.gh.Comments) + } + // A second mark (a re-mark after a reassignment) is not refused: the + // mark never decides a claim. + e.ok("mark-tracked", map[string]any{"externalId": id, "task": map[string]any{"id": "01abc"}, "worker": map[string]any{"name": "Other"}}, &ans) + if got := e.walk("", 20, nil); len(got) != 0 { + t.Fatalf("a marked item is listed: %v", ids(got)) + } + e.ok("untrack", map[string]any{"externalId": id}, &ans) + if l := e.gh.Labels("acme/app", 4); strings.Join(l, ",") != "bug" { + t.Fatalf("labels after untrack: %v", l) + } + // untrack of an item that carries no mark is not an error. + e.ok("untrack", map[string]any{"externalId": id}, &ans) + if got := ids(e.walk("", 20, nil)); len(got) != 1 || got[0] != id { + t.Fatalf("an untracked item is listed again: %v", got) + } +} + +func TestMarkCommentIsOptInAndCarriesTheServersURL(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}, "comment": true}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 4, Title: "x", CreatedAt: day(1)}) + var ans map[string]any + e.ok("mark-tracked", map[string]any{"externalId": e.gh.URL("acme/app", 4), + "task": map[string]any{"id": "01abc", "handle": "AT1.2", "portalUrl": "https://hadronmemory.com/app/u/hrn:agenttask:x"}, + "worker": map[string]any{"name": "Jonas\n@everyone", "role": "cli-engineer"}}, &ans) + if len(e.gh.Comments) != 1 { + t.Fatalf("comments: %v", e.gh.Comments) + } + c := e.gh.Comments[0].Body + if !strings.Contains(c, "https://hadronmemory.com/app/u/hrn:agenttask:x") || !strings.Contains(c, "AT1.2") { + t.Fatalf("comment does not name the task as the server printed it: %q", c) + } + // Text from Hadron is quoted as code, on one line, so a name cannot + // mention anyone or break the comment's layout. + if !strings.Contains(c, "`Jonas @everyone`") || strings.Contains(c, "Jonas\n") { + t.Fatalf("worker text reached the comment unneutralised: %q", c) + } +} + +func TestGetAndNormalize(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + e.gh.AddRepo("Acme/App", fakegithub.Issue{Number: 12, Title: "the title", Body: "the body", CreatedAt: day(1), Labels: []string{"hadron-tracked"}}) + id := e.gh.URL("acme/app", 12) + var got struct { + Item struct { + ExternalID, Title, Body, State, URL string + Tracked bool + } + } + e.ok("get", map[string]any{"externalId": id}, &got) + if got.Item.ExternalID != id || got.Item.Title != "the title" || got.Item.Body != "the body" || got.Item.State != "open" || got.Item.URL != id || !got.Item.Tracked { + t.Fatalf("get: %+v", got.Item) + } + for _, ref := range []string{"acme/app#12", "ACME/APP#12", "https://github.com/acme/app/issues/12/", "#12"} { + var n struct{ ExternalID string } + e.ok("normalize", map[string]any{"ref": ref}, &n) + if n.ExternalID != id { + t.Fatalf("normalize %q = %q, want GitHub's canonical %q", ref, n.ExternalID, id) + } + } +} + +func TestForSelectsTheMappedTeam(t *testing.T) { + e := newEnv(t, map[string]any{ + "repositories": []string{"acme/app"}, + "teams": []map[string]any{ + {"for": []string{"Ada", "hrn:worker:example.com:team:ada"}, "label": "team-ada"}, + {"for": []string{"Xan"}, "label": "team-xan"}, + {"for": []string{"Bo"}, "noTeam": true}, + }, + }) + e.gh.AddRepo("acme/app", + fakegithub.Issue{Number: 1, Title: "a", CreatedAt: day(1), Labels: []string{"team-ada"}}, + fakegithub.Issue{Number: 2, Title: "x", CreatedAt: day(2), Labels: []string{"Team-Xan"}}, + fakegithub.Issue{Number: 3, Title: "none", CreatedAt: day(3), Labels: []string{"bug"}}, + ) + cases := map[string][]string{ + "Ada": {e.gh.URL("acme/app", 1)}, + "ada": {e.gh.URL("acme/app", 1)}, + "hrn:worker:example.com:team:ada": {e.gh.URL("acme/app", 1)}, + "Xan": {e.gh.URL("acme/app", 2)}, + "Bo": {e.gh.URL("acme/app", 3)}, + "": {e.gh.URL("acme/app", 1), e.gh.URL("acme/app", 2), e.gh.URL("acme/app", 3)}, + } + for who, want := range cases { + if got := ids(e.walk(who, 20, nil)); strings.Join(got, " ") != strings.Join(want, " ") { + t.Fatalf("for %q: got %v want %v", who, got, want) + } + } + r := e.call("list-untracked", map[string]any{"limit": 20, "for": "Nobody"}) + if r.code == 0 { + t.Fatalf("an unmapped --for listed instead of refusing: %s", r.stdout) + } +} + +// Labels past the first page of 100 are still read: they decide the filters. +func TestLabelsPastOnePageDecideTheFilters(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}, "excludeLabels": []string{"wontfix"}}) + many := []string{} + for i := 0; i < 130; i++ { + many = append(many, fmt.Sprint("l", i)) + } + e.gh.AddRepo("acme/app", + fakegithub.Issue{Number: 1, Title: "excluded late", CreatedAt: day(1), Labels: append(append([]string{}, many...), "wontfix")}, + fakegithub.Issue{Number: 2, Title: "fine", CreatedAt: day(2), Labels: many}, + ) + if got := ids(e.walk("", 20, nil)); len(got) != 1 || got[0] != e.gh.URL("acme/app", 2) { + t.Fatalf("got %v", got) + } +} + +// A tracker failure refuses the call: never a partial list presented as whole. +func TestTrackerFailureRefusesTheCall(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app", "acme/lib"}}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 1, Title: "a", CreatedAt: day(1)}) + e.gh.AddRepo("acme/lib", fakegithub.Issue{Number: 1, Title: "b", CreatedAt: day(2)}) + e.gh.Fail("acme/lib", 502) + e.gh.EchoInErrors(token) + r := e.call("list-untracked", map[string]any{"limit": 20}) + if r.code == 0 { + t.Fatalf("a failing repository still produced an answer: %s", r.stdout) + } + if len(bytes.TrimSpace(r.stdout)) != 0 { + t.Fatalf("a refused call wrote stdout: %s", r.stdout) + } + e.noToken(r) +} + +func TestCredentialIsTheTeamsNeverHadrons(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 1, Title: "a", CreatedAt: day(1)}) + e.vars = []string{"HADRON_TOKEN=" + token} + r := e.call("list-untracked", map[string]any{"limit": 20}) + if r.code == 0 { + t.Fatalf("listed with no GitHub credential (only a Hadron one): %s", r.stdout) + } + if n := len(e.gh.Requests); n != 0 { + t.Fatalf("GitHub was called without the team's credential: %v", e.gh.Requests) + } + e.noToken(r) + // A credential named by tokenEnv is used. + e2 := newEnv(t, map[string]any{"repositories": []string{"acme/app"}, "tokenEnv": "ACME_GH"}) + e2.gh.AddRepo("acme/app", fakegithub.Issue{Number: 1, Title: "a", CreatedAt: day(1)}) + e2.vars = []string{"ACME_GH=" + token} + if got := e2.walk("", 20, nil); len(got) != 1 { + t.Fatalf("tokenEnv credential: %v", ids(got)) + } +} + +func TestRequestDisciplineIsRefused(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + cases := map[string]struct { + args []string + stdin string + }{ + "unknown call": {[]string{"list-everything"}, `{"contractVersion":1}`}, + "no call": {nil, `{"contractVersion":1}`}, + "two arguments": {[]string{"list-untracked", "--all"}, `{"contractVersion":1}`}, + "other version": {[]string{"list-untracked"}, `{"contractVersion":2}`}, + "no version": {[]string{"list-untracked"}, `{}`}, + "not json": {[]string{"list-untracked"}, `hello`}, + "two documents": {[]string{"list-untracked"}, `{"contractVersion":1}{"contractVersion":1}`}, + "limit out of rng": {[]string{"list-untracked"}, `{"contractVersion":1,"limit":101}`}, + "foreign repo mark": {[]string{"mark-tracked"}, `{"contractVersion":1,"externalId":"https://github.com/other/repo/issues/1","task":{"id":"t"},"worker":{}}`}, + "not an issue url": {[]string{"get"}, `{"contractVersion":1,"externalId":"https://github.com/acme/app/pull/1"}`}, + "forged cursor": {[]string{"list-untracked"}, `{"contractVersion":1,"cursor":"v1.bm90IGEgY3Vyc29y"}`}, + } + for name, c := range cases { + t.Run(name, func(t *testing.T) { + r := e.raw(c.args, []byte(c.stdin)) + if r.code == 0 { + t.Fatalf("accepted: %s", r.stdout) + } + if len(bytes.TrimSpace(r.stdout)) != 0 { + t.Fatalf("a refusal wrote stdout: %s", r.stdout) + } + if len(r.stderr) == 0 { + t.Fatal("a refusal gave no reason on stderr") + } + }) + } +} + +// A cursor carries its query: one issued for another --for, or before the +// configuration changed, is refused rather than resumed somewhere wrong. +func TestCursorIsBoundToItsQuery(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}, "teams": []map[string]any{{"for": []string{"Ada"}, "label": "a"}, {"for": []string{"Xan"}, "label": "x"}}}) + for i := 1; i <= 3; i++ { + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: i, Title: "t", CreatedAt: day(i), Labels: []string{"a", "x"}}) + } + var p Page + e.ok("list-untracked", map[string]any{"limit": 1, "for": "Ada"}, &p) + if p.NextCursor == nil { + t.Fatal("no cursor") + } + if r := e.call("list-untracked", map[string]any{"limit": 1, "for": "Xan", "cursor": *p.NextCursor}); r.code == 0 { + t.Fatalf("a cursor for Ada was resumed for Xan: %s", r.stdout) + } +} + +// The cursor stays inside the runner's bound with the most repositories the +// configuration allows, every one of them part-way through. +func TestCursorFitsTheRunnersBoundAtMaxRepositories(t *testing.T) { + repos := []string{} + for i := 0; i < 30; i++ { + repos = append(repos, fmt.Sprintf("a-rather-long-organisation-name/a-rather-long-repository-name-%02d", i)) + } + e := newEnv(t, map[string]any{"repositories": repos}) + for i, r := range repos { + e.gh.AddRepo(r, + fakegithub.Issue{Number: 100000 + i, Title: "t", CreatedAt: day(1).Add(time.Duration(i) * time.Minute)}, + fakegithub.Issue{Number: 200000 + i, Title: "t", CreatedAt: day(20)}, + ) + } + var p Page + e.ok("list-untracked", map[string]any{"limit": 30}, &p) + if p.NextCursor == nil || len(p.Items) != 30 { + t.Fatalf("items %d cursor %v", len(p.Items), p.NextCursor) + } + if err := CheckPage(p); err != nil { + t.Fatal(err) + } + if got := len(e.walk("", 100, nil)); got != 60 { + t.Fatalf("walk: %d of 60", got) + } +} + +func TestCheckReports(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app", "acme/gone"}}) + e.gh.AddRepo("acme/app") + var c struct { + OK bool + Checks []struct { + Name string + OK bool + Detail string + } + } + e.ok("check", nil, &c) + if c.OK { + t.Fatalf("check passed with an unreadable repository: %+v", c) + } + e.vars = nil + e.ok("check", nil, &c) + if c.OK || len(c.Checks) == 0 || c.Checks[0].OK { + t.Fatalf("check passed with no credential: %+v", c) + } +} + +// Nothing team-specific and no credential is committed to this public +// repository: no configuration file but the example, and nothing shaped like +// a GitHub token except this suite's own labelled fakes. +func TestRepositoryCarriesNoCredentialOrTeamConfig(t *testing.T) { + out, err := exec.Command("git", "-C", "..", "ls-files").Output() + if err != nil { + t.Skip("not a git checkout:", err) + } + tokenShape := regexp.MustCompile(`(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{20,}`) + for _, f := range strings.Fields(string(out)) { + base := filepath.Base(f) + if strings.HasSuffix(base, ".json") && base != "config.example.json" { + t.Errorf("%s: a JSON file is committed; adapter configuration stays with the team", f) + } + b, err := os.ReadFile(filepath.Join("..", f)) + if err != nil { + t.Fatal(err) + } + for _, m := range tokenShape.FindAllString(string(b), -1) { + if !strings.Contains(m, "FAKE") { + t.Errorf("%s: something shaped like a GitHub token is committed", f) + } + } + } +} diff --git a/conformance/runner_rules.go b/conformance/runner_rules.go new file mode 100644 index 0000000..799e12b --- /dev/null +++ b/conformance/runner_rules.go @@ -0,0 +1,150 @@ +// Package conformance holds the hadron-cli intake runner's rules for an +// adapter's answers, and a suite that runs the built adapter against them. +// +// The rules are copied from hadron-cli at 585bd9d6 (internal/intake/intake.go, +// hadron-cli#1961, the invocation format of cor:agt:120:04), because that +// package is internal to the CLI module and cannot be imported. They are +// copied, not paraphrased: each constant names its source. When the CLI's +// runner changes a bound, change it here in the same breath and name the new +// revision in RunnerRevision. +package conformance + +import ( + "bytes" + "encoding/json" + "fmt" + "strings" + "unicode" + "unicode/utf8" +) + +// RunnerRevision is the hadron-cli commit whose runner these rules copy. +const RunnerRevision = "585bd9d6" + +// ContractVersion is the contract version the runner speaks (intake.ContractVersion). +const ContractVersion = 1 + +// Bounds, as in hadron-cli internal/intake/intake.go at RunnerRevision. +const ( + MaxOutputBytes = 1 << 20 // stdout of one call + MaxItemsPerPage = 100 + MaxPages = 50 + ServerExternalIDMax = 512 // code points + MaxExternalIDLen = 2048 + MaxCursorLen = 4096 + MaxTextLen = 1024 +) + +// CoreCalls are the calls every adapter answers (cor:agt:120:04, The Grammar). +var CoreCalls = []string{"describe", "list-untracked", "mark-tracked", "untrack", "get"} + +// Describe is what the runner reads from `describe`. +type Describe struct { + Name string `json:"name"` + ContractVersion int `json:"contractVersion"` + Calls []string `json:"calls"` + Filters []string `json:"filters"` + Order string `json:"order"` +} + +// Item and Page are what the runner reads from `list-untracked`. +type Item struct { + ExternalID string `json:"externalId"` + Title string `json:"title"` +} + +type Page struct { + Items []Item `json:"items"` + NextCursor *string `json:"nextCursor"` +} + +// OneObject applies the runner's checks on any answer: at most +// MaxOutputBytes, valid UTF-8, exactly one JSON object and nothing after it. +func OneObject(stdout []byte, out any) error { + if len(stdout) > MaxOutputBytes { + return fmt.Errorf("more than %d bytes on stdout", MaxOutputBytes) + } + raw := bytes.TrimSpace(stdout) + if len(raw) == 0 || raw[0] != '{' { + return fmt.Errorf("stdout is not one JSON object: %q", trunc(raw)) + } + if !utf8.Valid(raw) { + return fmt.Errorf("stdout is not valid UTF-8") + } + if err := json.Unmarshal(raw, out); err != nil { + return fmt.Errorf("stdout is not one well-formed JSON object: %v", err) + } + return nil +} + +// CheckDescribe applies the runner's describe checks, plus the contract's +// rule that every core call is answered. +func CheckDescribe(d Describe) error { + if d.ContractVersion != ContractVersion { + return fmt.Errorf("contractVersion %d, the runner speaks %d", d.ContractVersion, ContractVersion) + } + if strings.TrimSpace(d.Name) == "" || len(d.Name) > MaxTextLen { + return fmt.Errorf("name %q is empty or longer than %d bytes", d.Name, MaxTextLen) + } + for _, c := range CoreCalls { + found := false + for _, have := range d.Calls { + found = found || have == c + } + if !found { + return fmt.Errorf("describe.calls does not list the core call %q", c) + } + } + return nil +} + +// CheckPage applies the runner's per-page checks, and the external id's own +// checks (cor:agt:120:02: 1 to 512 characters, no whitespace, control or +// invisible format characters, no userinfo), which the server applies to the +// claim the runner writes. +func CheckPage(p Page) error { + if len(p.Items) > MaxItemsPerPage { + return fmt.Errorf("%d items in one page, more than %d", len(p.Items), MaxItemsPerPage) + } + for i, it := range p.Items { + if err := CheckExternalID(it.ExternalID); err != nil { + return fmt.Errorf("item %d: %v", i, err) + } + if len(it.Title) > MaxTextLen { + return fmt.Errorf("item %d: title longer than %d bytes", i, MaxTextLen) + } + } + if p.NextCursor != nil && len(*p.NextCursor) > MaxCursorLen { + return fmt.Errorf("nextCursor is %d bytes, more than %d", len(*p.NextCursor), MaxCursorLen) + } + return nil +} + +// CheckExternalID is the external id's checks. +func CheckExternalID(id string) error { + if id == "" { + return fmt.Errorf("no externalId") + } + if len(id) > MaxExternalIDLen || utf8.RuneCountInString(id) > ServerExternalIDMax { + return fmt.Errorf("externalId longer than %d characters", ServerExternalIDMax) + } + for _, r := range id { + if unicode.IsSpace(r) || unicode.IsControl(r) || unicode.Is(unicode.Cf, r) { + return fmt.Errorf("externalId %q has whitespace, control or invisible format characters", id) + } + } + if scheme, rest, ok := strings.Cut(id, "://"); ok && scheme != "" { + host, _, _ := strings.Cut(rest, "/") + if strings.Contains(host, "@") { + return fmt.Errorf("externalId %q carries userinfo", id) + } + } + return nil +} + +func trunc(b []byte) string { + if len(b) > 80 { + return string(b[:80]) + "…" + } + return string(b) +} diff --git a/go.mod b/go.mod new file mode 100644 index 0000000..63aad72 --- /dev/null +++ b/go.mod @@ -0,0 +1,3 @@ +module github.com/hadron-memory/hadron-task-adapter-github + +go 1.26.11 diff --git a/internal/fakegithub/fakegithub.go b/internal/fakegithub/fakegithub.go new file mode 100644 index 0000000..5e4d5f2 --- /dev/null +++ b/internal/fakegithub/fakegithub.go @@ -0,0 +1,384 @@ +// Package fakegithub is an in-memory stand-in for the slice of the GitHub API +// the adapter uses: the GraphQL issue list and issue read, and the REST label, +// comment, rate-limit and repository endpoints. It exists for the adapter's +// own tests and its conformance suite; it is not a general GitHub fake. +package fakegithub + +import ( + "encoding/base64" + "encoding/json" + "fmt" + "io" + "net/http" + "net/http/httptest" + "sort" + "strconv" + "strings" + "sync" + "time" +) + +// Issue is one issue of a fake repository. +type Issue struct { + Number int + Title string + Body string + State string // OPEN or CLOSED + CreatedAt time.Time + Labels []string +} + +// Comment is a comment the adapter posted. +type Comment struct { + Repo string // owner/name as the request spelled it + Number int + Body string +} + +// Server is a fake GitHub. Its methods are safe for concurrent use. +type Server struct { + *httptest.Server + + // Token is the only credential the fake accepts ("Bearer "). + Token string + + mu sync.Mutex + // repos is keyed by the lower-cased "owner/name"; canon keeps GitHub's + // own spelling, which is what an issue URL carries. + repos map[string][]*Issue + canon map[string]string + fail map[string]int // lower-cased "owner/name" -> HTTP status for any read of it + echo string // when set, error bodies carry this text (to test redaction) + Comments []Comment + Requests []string // "METHOD path" or "GRAPHQL op", in order +} + +// New starts a fake GitHub that accepts token. +func New(token string) *Server { + s := &Server{Token: token, repos: map[string][]*Issue{}, canon: map[string]string{}, fail: map[string]int{}} + s.Server = httptest.NewServer(http.HandlerFunc(s.serve)) + return s +} + +// AddRepo creates a repository spelled as GitHub spells it ("Owner/Name"). +func (s *Server) AddRepo(full string, issues ...Issue) { + s.mu.Lock() + defer s.mu.Unlock() + k := strings.ToLower(full) + s.canon[k] = full + for i := range issues { + is := issues[i] + if is.State == "" { + is.State = "OPEN" + } + s.repos[k] = append(s.repos[k], &is) + } +} + +// Fail makes every read of a repository answer with status. +func (s *Server) Fail(full string, status int) { + s.mu.Lock() + defer s.mu.Unlock() + s.fail[strings.ToLower(full)] = status +} + +// EchoInErrors makes error bodies include text, as a misbehaving proxy might. +func (s *Server) EchoInErrors(text string) { + s.mu.Lock() + defer s.mu.Unlock() + s.echo = text +} + +// Labels returns an issue's current labels. +func (s *Server) Labels(full string, number int) []string { + s.mu.Lock() + defer s.mu.Unlock() + if is := s.find(strings.ToLower(full), number); is != nil { + return append([]string(nil), is.Labels...) + } + return nil +} + +// SetLabels replaces an issue's labels (a teammate relabelling by hand). +func (s *Server) SetLabels(full string, number int, labels ...string) { + s.mu.Lock() + defer s.mu.Unlock() + if is := s.find(strings.ToLower(full), number); is != nil { + is.Labels = append([]string(nil), labels...) + } +} + +// URL is the canonical issue URL GitHub would print. +func (s *Server) URL(full string, number int) string { + s.mu.Lock() + defer s.mu.Unlock() + return fmt.Sprintf("https://github.com/%s/issues/%d", s.canon[strings.ToLower(full)], number) +} + +func (s *Server) find(k string, number int) *Issue { + for _, is := range s.repos[k] { + if is.Number == number { + return is + } + } + return nil +} + +func (s *Server) record(r string) { + s.Requests = append(s.Requests, r) +} + +func (s *Server) writeErr(w http.ResponseWriter, status int, msg string) { + if s.echo != "" { + msg += " " + s.echo + } + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(status) + _ = json.NewEncoder(w).Encode(map[string]string{"message": msg}) +} + +func writeJSON(w http.ResponseWriter, status int, v any) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(status) + _ = json.NewEncoder(w).Encode(v) +} + +func (s *Server) serve(w http.ResponseWriter, r *http.Request) { + s.mu.Lock() + defer s.mu.Unlock() + if r.Header.Get("Authorization") != "Bearer "+s.Token { + s.record("UNAUTHORIZED " + r.URL.Path) + s.writeErr(w, http.StatusUnauthorized, "Bad credentials") + return + } + if r.Method == http.MethodPost && r.URL.Path == "/graphql" { + s.graphql(w, r) + return + } + s.record(r.Method + " " + r.URL.Path) + if r.URL.Path == "/rate_limit" && r.Method == http.MethodGet { + writeJSON(w, 200, map[string]any{"resources": map[string]any{"core": map[string]int{"remaining": 4999}}}) + return + } + parts := strings.Split(strings.TrimPrefix(r.URL.Path, "/"), "/") + if len(parts) < 3 || parts[0] != "repos" { + s.writeErr(w, 404, "Not Found") + return + } + k := strings.ToLower(parts[1] + "/" + parts[2]) + if st := s.fail[k]; st != 0 { + s.writeErr(w, st, "Server Error") + return + } + if _, ok := s.canon[k]; !ok { + s.writeErr(w, 404, "Not Found") + return + } + if len(parts) == 3 && r.Method == http.MethodGet { + writeJSON(w, 200, map[string]any{"full_name": s.canon[k]}) + return + } + if len(parts) < 6 || parts[3] != "issues" { + s.writeErr(w, 404, "Not Found") + return + } + n, err := strconv.Atoi(parts[4]) + is := s.find(k, n) + if err != nil || is == nil { + s.writeErr(w, 404, "Not Found") + return + } + switch { + case parts[5] == "labels" && len(parts) == 6 && r.Method == http.MethodGet: + per, _ := strconv.Atoi(r.URL.Query().Get("per_page")) + page, _ := strconv.Atoi(r.URL.Query().Get("page")) + if per <= 0 { + per = 30 + } + if page <= 0 { + page = 1 + } + out := []map[string]string{} + for i := (page - 1) * per; i < len(is.Labels) && i < page*per; i++ { + out = append(out, map[string]string{"name": is.Labels[i]}) + } + writeJSON(w, 200, out) + case parts[5] == "labels" && len(parts) == 6 && r.Method == http.MethodPost: + var body struct { + Labels []string `json:"labels"` + } + if json.NewDecoder(r.Body).Decode(&body) != nil { + s.writeErr(w, 422, "Invalid request") + return + } + for _, l := range body.Labels { + if !hasFold(is.Labels, l) { + is.Labels = append(is.Labels, l) + } + } + writeJSON(w, 200, labelObjs(is.Labels)) + case parts[5] == "labels" && len(parts) == 7 && r.Method == http.MethodDelete: + name := parts[6] + kept := is.Labels[:0:0] + found := false + for _, l := range is.Labels { + if strings.EqualFold(l, name) { + found = true + continue + } + kept = append(kept, l) + } + if !found { + s.writeErr(w, 404, "Label does not exist") + return + } + is.Labels = kept + writeJSON(w, 200, labelObjs(is.Labels)) + case parts[5] == "comments" && len(parts) == 6 && r.Method == http.MethodPost: + var body struct { + Body string `json:"body"` + } + b, _ := io.ReadAll(r.Body) + if json.Unmarshal(b, &body) != nil || body.Body == "" { + s.writeErr(w, 422, "Invalid request") + return + } + s.Comments = append(s.Comments, Comment{Repo: parts[1] + "/" + parts[2], Number: n, Body: body.Body}) + writeJSON(w, 201, map[string]any{"id": len(s.Comments)}) + default: + s.writeErr(w, 404, "Not Found") + } +} + +func hasFold(list []string, v string) bool { + for _, l := range list { + if strings.EqualFold(l, v) { + return true + } + } + return false +} + +func labelObjs(ls []string) []map[string]string { + out := []map[string]string{} + for _, l := range ls { + out = append(out, map[string]string{"name": l}) + } + return out +} + +type gqlReq struct { + Query string `json:"query"` + OperationName string `json:"operationName"` + Variables map[string]any `json:"variables"` +} + +func str(v any) string { + s, _ := v.(string) + return s +} + +func num(v any) int { + f, _ := v.(float64) + return int(f) +} + +func labelConn(labels []string, first int) map[string]any { + nodes := []map[string]string{} + for i := 0; i < len(labels) && i < first; i++ { + nodes = append(nodes, map[string]string{"name": labels[i]}) + } + return map[string]any{"nodes": nodes, "pageInfo": map[string]bool{"hasNextPage": len(labels) > first}} +} + +func (s *Server) graphql(w http.ResponseWriter, r *http.Request) { + var q gqlReq + if err := json.NewDecoder(r.Body).Decode(&q); err != nil { + s.writeErr(w, 400, "Problems parsing JSON") + return + } + s.record("GRAPHQL " + q.OperationName) + owner, name := str(q.Variables["owner"]), str(q.Variables["name"]) + k := strings.ToLower(owner + "/" + name) + if st := s.fail[k]; st != 0 { + s.writeErr(w, st, "Server Error") + return + } + full, ok := s.canon[k] + if !ok { + writeJSON(w, 200, map[string]any{"data": map[string]any{"repository": nil}, + "errors": []map[string]string{{"type": "NOT_FOUND", "message": fmt.Sprintf("Could not resolve to a Repository with the name '%s'.", owner+"/"+name)}}}) + return + } + labelsFirst := num(q.Variables["labelsFirst"]) + if labelsFirst <= 0 { + labelsFirst = 100 + } + switch q.OperationName { + case "ListOpenIssues": + open := []*Issue{} + for _, is := range s.repos[k] { + if is.State == "OPEN" { + open = append(open, is) + } + } + sort.SliceStable(open, func(i, j int) bool { + if !open[i].CreatedAt.Equal(open[j].CreatedAt) { + return open[i].CreatedAt.Before(open[j].CreatedAt) + } + return open[i].Number < open[j].Number + }) + start := 0 + if after := str(q.Variables["after"]); after != "" { + raw, err := base64.StdEncoding.DecodeString(after) + n, err2 := strconv.Atoi(strings.TrimPrefix(string(raw), "cursor:v2:")) + if err != nil || err2 != nil { + writeJSON(w, 200, map[string]any{"errors": []map[string]string{{"message": "`" + after + "` does not appear to be a valid cursor."}}}) + return + } + // GitHub's cursor names a position, not an issue: resume after + // the issue with that number in the current order. + start = len(open) + for i, is := range open { + if is.Number == n { + start = i + 1 + break + } + } + } + first := num(q.Variables["first"]) + edges := []map[string]any{} + end := start + for i := start; i < len(open) && len(edges) < first; i++ { + is := open[i] + edges = append(edges, map[string]any{ + "cursor": base64.StdEncoding.EncodeToString([]byte("cursor:v2:" + strconv.Itoa(is.Number))), + "node": map[string]any{ + "number": is.Number, "title": is.Title, + "url": fmt.Sprintf("https://github.com/%s/issues/%d", full, is.Number), + "createdAt": is.CreatedAt.UTC().Format(time.RFC3339), + "labels": labelConn(is.Labels, labelsFirst), + }, + }) + end = i + 1 + } + writeJSON(w, 200, map[string]any{"data": map[string]any{"repository": map[string]any{"issues": map[string]any{ + "edges": edges, + "pageInfo": map[string]any{"hasNextPage": end < len(open)}, + }}}}) + case "GetIssue": + is := s.find(k, num(q.Variables["number"])) + if is == nil { + writeJSON(w, 200, map[string]any{"data": map[string]any{"repository": map[string]any{"issue": nil}}, + "errors": []map[string]string{{"type": "NOT_FOUND", "message": "Could not resolve to an Issue."}}}) + return + } + writeJSON(w, 200, map[string]any{"data": map[string]any{"repository": map[string]any{"issue": map[string]any{ + "number": is.Number, "title": is.Title, "body": is.Body, "state": is.State, + "url": fmt.Sprintf("https://github.com/%s/issues/%d", full, is.Number), + "labels": labelConn(is.Labels, labelsFirst), + }}}}) + default: + writeJSON(w, 200, map[string]any{"errors": []map[string]string{{"message": "unknown operation " + q.OperationName}}}) + } +} From 0ddc21ff72eff730988364aa973882a05f74b955 Mon Sep 17 00:00:00 2001 From: Holger Selover-Stephan Date: Fri, 13 Nov 2026 07:28:30 +0000 Subject: [PATCH 02/10] feat: the GitHub intake adapter, contract version 1 (hadron-memory/hadron-cli#1963) A standalone executable answering the intake adapter contract (cor:agt:120:04) in the hadron-cli runner's invocation format (#1961, 585bd9d6): describe, list-untracked, mark-tracked, untrack, get, and the optional normalize and check. - The label model (repositories, ready, exclude and team labels, the for -> team map) is the team's configuration file, outside this repo; the token is the team's own, from the environment, never a HADRON_ variable. - The mark is a label (a comment is opt-in). Filtering happens after GitHub's paging, so marks between pages never make a walk skip. - One order across repositories (oldest first, then repository, then number); the opaque cursor holds GitHub's cursor per repository and a fingerprint of its query, and stays inside the runner's 4096-byte bound. - Any GitHub failure refuses the whole call; labels past the first 100 are read; the token is never printed. Turns the red conformance suite green; adds unit tests for the configuration and reference parsing, CI (build, cross-build, race tests, golangci-lint, govulncheck), the README and docs/design.md. Worker: Jonas (cli-engineer) Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 54 ++++ .golangci.yml | 25 ++ README.md | 153 ++++++++++- cmd/hadron-task-adapter-github/main.go | 22 +- config.example.json | 12 + conformance/conformance_test.go | 56 ++-- docs/design.md | 115 +++++++++ internal/adapter/adapter.go | 233 +++++++++++++++++ internal/adapter/calls.go | 287 +++++++++++++++++++++ internal/adapter/config.go | 342 +++++++++++++++++++++++++ internal/adapter/config_test.go | 164 ++++++++++++ internal/adapter/github.go | 168 ++++++++++++ internal/adapter/list.go | 338 ++++++++++++++++++++++++ internal/adapter/refs.go | 130 ++++++++++ internal/fakegithub/fakegithub.go | 38 ++- 15 files changed, 2108 insertions(+), 29 deletions(-) create mode 100644 .github/workflows/ci.yml create mode 100644 .golangci.yml create mode 100644 config.example.json create mode 100644 docs/design.md create mode 100644 internal/adapter/adapter.go create mode 100644 internal/adapter/calls.go create mode 100644 internal/adapter/config.go create mode 100644 internal/adapter/config_test.go create mode 100644 internal/adapter/github.go create mode 100644 internal/adapter/list.go create mode 100644 internal/adapter/refs.go diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..9b02f63 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,54 @@ +name: CI + +# Third-party actions are pinned to a full commit SHA (the tag in a trailing +# comment), as in hadron-cli, so a moved upstream tag cannot change what runs. + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 + - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6 + with: + go-version-file: go.mod + - name: Build + run: go build ./... + # The adapter runs wherever the hadron CLI runs. + - name: Cross-build + run: | + for t in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64; do + GOOS=${t%/*} GOARCH=${t#*/} go build -o /dev/null ./cmd/hadron-task-adapter-github + done + # Includes the conformance suite: the built adapter driven by the + # hadron-cli runner's rules against a fake GitHub. + - name: Test + run: go test -race ./... + + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 + - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6 + with: + go-version-file: go.mod + - uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v9 + with: + skip-cache: true + + vuln: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 + - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6 + with: + go-version-file: go.mod + - name: govulncheck + run: go run golang.org/x/vuln/cmd/govulncheck@v1.5.0 ./... diff --git a/.golangci.yml b/.golangci.yml new file mode 100644 index 0000000..aff864a --- /dev/null +++ b/.golangci.yml @@ -0,0 +1,25 @@ +version: "2" + +linters: + default: standard + enable: + - misspell + - unconvert + - unparam + settings: + errcheck: + exclude-functions: + - fmt.Fprint + - fmt.Fprintf + - fmt.Fprintln + - (io.ReadCloser).Close + - (*os.File).Close + +# Formatting is a gate: `golangci-lint run` reports a gofmt diff as an issue. +formatters: + enable: + - gofmt + +issues: + max-issues-per-linter: 0 + max-same-issues: 0 diff --git a/README.md b/README.md index a88b2e8..dcdeb8a 100644 --- a/README.md +++ b/README.md @@ -1 +1,152 @@ -# hadron-task-adapter-github \ No newline at end of file +# hadron-task-adapter-github + +The GitHub **intake adapter** for [Hadron](https://hadronmemory.com) teams. The +`hadron` CLI runs it to find the GitHub issues no task of the team tracks yet, +and to mark the issues a task claims. Hadron itself never calls GitHub: the +adapter runs on the team's host with the team's own GitHub credential. + +The adapter implements the public, versioned intake adapter contract +(`cor:agt:120:04` in the Hadron specs), contract version **1**, in the +invocation format of the hadron CLI's adapter runner +([hadron-cli#1961](https://github.com/hadron-memory/hadron-cli/issues/1961)). + +## Install + +```sh +go install github.com/hadron-memory/hadron-task-adapter-github/cmd/hadron-task-adapter-github@latest +``` + +It needs a `hadron` CLI that has `team task find-untracked --adapter` +(hadron-cli#1961). + +## Use + +```sh +export GITHUB_TOKEN=… # the team's own GitHub token, never a Hadron one +export TASK_ADAPTER_GITHUB_CONFIG=~/.config/hadron-task-adapter-github/config.json + +hadron team task find-untracked --adapter hadron-task-adapter-github # list +hadron team task find-untracked --adapter hadron-task-adapter-github --track # claim and mark +``` + +`HADRON_INTAKE_ADAPTER=hadron-task-adapter-github` saves passing `--adapter`. + +You can also call the adapter directly to try a configuration: + +```sh +echo '{"contractVersion":1}' | hadron-task-adapter-github check +echo '{"contractVersion":1,"limit":5}' | hadron-task-adapter-github list-untracked +``` + +## Configuration + +The configuration is a JSON file, read from `$TASK_ADAPTER_GITHUB_CONFIG`, or +by default from `hadron-task-adapter-github/config.json` under the user +configuration directory (`~/.config` on Linux, `~/Library/Application Support` +on macOS). It holds the team's label model and no credential. **Keep it out of +this repository**, and out of any public one: it names the team's repositories, +labels and workers. [`config.example.json`](config.example.json) shows every +key. + +| Key | Meaning | +|---|---| +| `repositories` | `"owner/name"`, 1 to 30. Their **open issues** are the intake (pull requests are not). | +| `readyLabel` | The label that marks an issue ready for intake. | +| `ready` | `only` (list only ready issues; the default when `readyLabel` is set), `exclude`, or `any` (the default without one). | +| `excludeLabels` | An issue carrying any of these is never listed. | +| `teams` | Maps the CLI's `--for X` to a team: `{"for": ["Name", ""], "label": "team-x"}` lists the issues carrying `team-x`; `{"for": [...], "noTeam": true}` lists the issues carrying no team's label. A `--for` that no team maps is refused. Without `--for`, the list is not narrowed by team. | +| `trackedLabel` | The adapter's mark. Default `hadron-tracked`. | +| `comment` | `true` also posts a comment on mark naming the task (and its portal link, as the server printed it) and the worker. Off by default: on a public repository it publishes the team's worker names. | +| `tokenEnv` | The environment variable holding the token. Default: `GITHUB_TOKEN`, then `GH_TOKEN`. | +| `apiUrl`, `graphqlUrl`, `webHost` | For GitHub Enterprise Server: `https://HOST/api/v3`, `https://HOST/api/graphql`, `HOST`. Default github.com. Only `https` is accepted (plain `http` only to the loopback interface). | + +Labels are compared without regard to case. Unknown keys are refused, so a +misspelt key fails loudly instead of widening the intake. + +### The credential + +The adapter reads the team's GitHub token from the environment. It is sent only +in the `Authorization` header to the configured API, and never printed: error +text from GitHub is scrubbed of it. The hadron CLI never passes its own +`HADRON_*` credentials to an adapter, so a `HADRON_` variable cannot be the +token. + +A fine-grained token needs, on each configured repository: **Issues: read and +write** (to read issues and to add or remove the mark) and **Metadata: read**. + +Create the `trackedLabel` in each repository before the first claim +(`gh label create hadron-tracked -R owner/name`). `check` reports a repository +where it is missing. + +## The calls + +Every call is `hadron-task-adapter-github `, one argument and no shell. +The request is one JSON object on stdin, always with `"contractVersion": 1`; +the answer is one JSON object on stdout and exit 0. A refusal is a non-zero +exit, a one-line reason on stderr and nothing on stdout. + +| Call | Request | Answer | +|---|---|---| +| `describe` | (nothing else) | `name`, `version`, `contractVersion` (1), `calls`, `filters` (`["for"]`), `order` (`created-asc`). Answered whatever version the caller speaks. | +| `list-untracked` | `limit` (1 to 100, default 20), `cursor`, `for` | `items`: `[{externalId, title}]`; `nextCursor`, or `null` at the end of the list. | +| `mark-tracked` | `externalId`, `task` {`id`, `handle`, `portalUrl`}, `worker` {`id`, `name`, `role`, `model`} | `{"marked": true, …}` | +| `untrack` | `externalId` | `{"untracked": true, …}`. An issue with no mark is not an error. | +| `get` | `externalId` | `item`: `externalId` (as asked), `title`, `body`, `state` (`open`/`closed`), `url` (GitHub's canonical URL now), `tracked`. | +| `normalize` (optional) | `ref`: an issue URL, `owner/name#N`, or `#N` with one repository configured | `externalId`: GitHub's canonical issue URL. | +| `check` (optional) | (nothing else) | `ok`, and `checks`: the configuration, the credential, and for each repository that it is readable and has the `trackedLabel`. Always exit 0. | + +The optional calls `report` and `changed-since` are not answered yet. + +- **The external id** is the issue's canonical URL exactly as GitHub prints it, + for example `https://github.com/hadron-memory/hadron-server/issues/4084`: + one spelling for one issue, every time. The CLI writes it as given, and hands + the same string back to `mark-tracked`, `get` and `untrack`, which accept + only that shape and only for a configured repository. +- **The list's order** is oldest first across all repositories, then + repository, then issue number. +- **The cursor** is opaque. It records, for each repository, GitHub's own + position, and the query it belongs to: a cursor from another `--for` or from + before the configuration changed is refused, not resumed somewhere wrong. The + set of open issues does not change when an issue is marked (the mark is a + label, and filtering happens in the adapter), so a cursor taken before others + claimed still resumes at the right place and skips nothing. +- **The mark** is the `trackedLabel`, and optionally a comment. It never makes + or decides a claim: the claim is the CLI's task create. A second mark of the + same issue (after a reassignment) is an ordinary call, never a refusal. +- **Never partial.** A GitHub error, a rate limit, or an answer the adapter + does not understand refuses the whole call; a list is never cut short and + presented as whole. Labels past GitHub's first page of 100 are read too, + since they decide the filters. +- **Labels never reach Hadron.** No answer carries an issue's labels. + +### Exit codes + +| Code | Meaning | +|---|---| +| 0 | answered | +| 1 | GitHub refused, failed, or answered something unusable | +| 2 | the request: an unknown call, not one JSON object, another contract version, a bad argument or cursor | +| 3 | the configuration or the credential | + +The hadron CLI reads any non-zero exit as the adapter's refusal. + +## Development + +```sh +go test -race ./... # includes the conformance suite +golangci-lint run # the CI lint, gofmt included +``` + +[`conformance/`](conformance) builds the adapter and drives it the way the +hadron CLI's runner does, against a fake GitHub +([`internal/fakegithub`](internal/fakegithub)), checking every answer against +the runner's rules. Those rules are copied from hadron-cli (its runner package +is internal to the CLI module), and `conformance/runner_rules.go` names the +hadron-cli revision they were copied from. When the runner changes a bound, +change it there too. + +The design, and the decisions it rests on, is in [`docs/design.md`](docs/design.md). + +## License + +MIT, as hadron-cli. diff --git a/cmd/hadron-task-adapter-github/main.go b/cmd/hadron-task-adapter-github/main.go index aff998d..dbcf2a3 100644 --- a/cmd/hadron-task-adapter-github/main.go +++ b/cmd/hadron-task-adapter-github/main.go @@ -1,13 +1,27 @@ // Command hadron-task-adapter-github is the GitHub intake adapter for Hadron -// teams (cor:agt:120:04). +// teams: the hadron CLI runs it to list a team's GitHub issues that no task +// tracks yet, and to mark the ones a task claims (cor:agt:120:04). See the +// README for the calls, the configuration and the credential. package main import ( - "fmt" + "context" "os" + "os/signal" + "syscall" + + "github.com/hadron-memory/hadron-task-adapter-github/internal/adapter" ) func main() { - fmt.Fprintln(os.Stderr, "hadron-task-adapter-github: not implemented yet") - os.Exit(1) + ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) + code := adapter.Run(ctx, adapter.Env{ + Args: os.Args[1:], + Stdin: os.Stdin, + Stdout: os.Stdout, + Stderr: os.Stderr, + Getenv: os.Getenv, + }) + stop() + os.Exit(code) } diff --git a/config.example.json b/config.example.json new file mode 100644 index 0000000..8f89c12 --- /dev/null +++ b/config.example.json @@ -0,0 +1,12 @@ +{ + "repositories": ["your-org/your-repo", "your-org/another-repo"], + "readyLabel": "ready", + "ready": "only", + "excludeLabels": ["epic", "wontfix"], + "teams": [ + { "for": ["WorkerName", "hrn:worker:example.com:your-team-app:workername"], "label": "team-a" }, + { "for": ["AnotherWorker"], "noTeam": true } + ], + "trackedLabel": "hadron-tracked", + "comment": false +} diff --git a/conformance/conformance_test.go b/conformance/conformance_test.go index fba4fda..071f316 100644 --- a/conformance/conformance_test.go +++ b/conformance/conformance_test.go @@ -56,7 +56,10 @@ func newEnv(t *testing.T, cfg map[string]any) *env { gh := fakegithub.New(token) t.Cleanup(gh.Close) cfg["apiUrl"] = gh.URL - b, _ := json.Marshal(cfg) + b, err := json.Marshal(cfg) + if err != nil { + t.Fatal(err) + } p := filepath.Join(t.TempDir(), "config.json") if err := os.WriteFile(p, b, 0o600); err != nil { t.Fatal(err) @@ -214,14 +217,14 @@ func TestWalkListsEveryEligibleIssueOnceOldestFirst(t *testing.T) { for _, limit := range []int{1, 2, 100} { got := ids(e.walk("", limit, nil)) want := []string{ - e.gh.URL("acme/app", 1), e.gh.URL("Acme/Lib", 9), e.gh.URL("Acme/Lib", 7), e.gh.URL("acme/app", 6), + e.gh.IssueURL("acme/app", 1), e.gh.IssueURL("Acme/Lib", 9), e.gh.IssueURL("Acme/Lib", 7), e.gh.IssueURL("acme/app", 6), } if strings.Join(got, " ") != strings.Join(want, " ") { t.Fatalf("limit %d:\n got %v\nwant %v", limit, got, want) } } // The external id is GitHub's own canonical URL, in GitHub's spelling. - if got := e.gh.URL("Acme/Lib", 9); got != "https://github.com/Acme/Lib/issues/9" { + if got := e.gh.IssueURL("Acme/Lib", 9); got != "https://github.com/Acme/Lib/issues/9" { t.Fatalf("fixture: %s", got) } } @@ -252,7 +255,7 @@ func TestMarksBetweenPagesSkipNothing(t *testing.T) { func TestMarkThenUntrackRoundTrip(t *testing.T) { e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}, "trackedLabel": "in-hadron"}) e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 4, Title: "x", CreatedAt: day(1), Labels: []string{"bug"}}) - id := e.gh.URL("acme/app", 4) + id := e.gh.IssueURL("acme/app", 4) var ans map[string]any e.ok("mark-tracked", map[string]any{"externalId": id, "task": map[string]any{"id": "01abc", "handle": "AT1.2", "portalUrl": "https://hadronmemory.com/app/u/x"}, @@ -284,7 +287,7 @@ func TestMarkCommentIsOptInAndCarriesTheServersURL(t *testing.T) { e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}, "comment": true}) e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 4, Title: "x", CreatedAt: day(1)}) var ans map[string]any - e.ok("mark-tracked", map[string]any{"externalId": e.gh.URL("acme/app", 4), + e.ok("mark-tracked", map[string]any{"externalId": e.gh.IssueURL("acme/app", 4), "task": map[string]any{"id": "01abc", "handle": "AT1.2", "portalUrl": "https://hadronmemory.com/app/u/hrn:agenttask:x"}, "worker": map[string]any{"name": "Jonas\n@everyone", "role": "cli-engineer"}}, &ans) if len(e.gh.Comments) != 1 { @@ -304,7 +307,7 @@ func TestMarkCommentIsOptInAndCarriesTheServersURL(t *testing.T) { func TestGetAndNormalize(t *testing.T) { e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) e.gh.AddRepo("Acme/App", fakegithub.Issue{Number: 12, Title: "the title", Body: "the body", CreatedAt: day(1), Labels: []string{"hadron-tracked"}}) - id := e.gh.URL("acme/app", 12) + id := e.gh.IssueURL("acme/app", 12) var got struct { Item struct { ExternalID, Title, Body, State, URL string @@ -339,12 +342,12 @@ func TestForSelectsTheMappedTeam(t *testing.T) { fakegithub.Issue{Number: 3, Title: "none", CreatedAt: day(3), Labels: []string{"bug"}}, ) cases := map[string][]string{ - "Ada": {e.gh.URL("acme/app", 1)}, - "ada": {e.gh.URL("acme/app", 1)}, - "hrn:worker:example.com:team:ada": {e.gh.URL("acme/app", 1)}, - "Xan": {e.gh.URL("acme/app", 2)}, - "Bo": {e.gh.URL("acme/app", 3)}, - "": {e.gh.URL("acme/app", 1), e.gh.URL("acme/app", 2), e.gh.URL("acme/app", 3)}, + "Ada": {e.gh.IssueURL("acme/app", 1)}, + "ada": {e.gh.IssueURL("acme/app", 1)}, + "hrn:worker:example.com:team:ada": {e.gh.IssueURL("acme/app", 1)}, + "Xan": {e.gh.IssueURL("acme/app", 2)}, + "Bo": {e.gh.IssueURL("acme/app", 3)}, + "": {e.gh.IssueURL("acme/app", 1), e.gh.IssueURL("acme/app", 2), e.gh.IssueURL("acme/app", 3)}, } for who, want := range cases { if got := ids(e.walk(who, 20, nil)); strings.Join(got, " ") != strings.Join(want, " ") { @@ -368,7 +371,7 @@ func TestLabelsPastOnePageDecideTheFilters(t *testing.T) { fakegithub.Issue{Number: 1, Title: "excluded late", CreatedAt: day(1), Labels: append(append([]string{}, many...), "wontfix")}, fakegithub.Issue{Number: 2, Title: "fine", CreatedAt: day(2), Labels: many}, ) - if got := ids(e.walk("", 20, nil)); len(got) != 1 || got[0] != e.gh.URL("acme/app", 2) { + if got := ids(e.walk("", 20, nil)); len(got) != 1 || got[0] != e.gh.IssueURL("acme/app", 2) { t.Fatalf("got %v", got) } } @@ -413,6 +416,14 @@ func TestCredentialIsTheTeamsNeverHadrons(t *testing.T) { func TestRequestDisciplineIsRefused(t *testing.T) { e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + // Every repository and issue the cases name exists and is readable, so + // each refusal is the adapter's own, not GitHub's. + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 1, Title: "a", CreatedAt: day(1)}) + e.gh.AddRepo("other/repo", fakegithub.Issue{Number: 1, Title: "b", CreatedAt: day(1)}) + var sane Page + e.ok("list-untracked", map[string]any{"limit": 20}, &sane) + var got map[string]any + e.ok("get", map[string]any{"externalId": e.gh.IssueURL("acme/app", 1)}, &got) cases := map[string]struct { args []string stdin string @@ -490,9 +501,9 @@ func TestCursorFitsTheRunnersBoundAtMaxRepositories(t *testing.T) { } func TestCheckReports(t *testing.T) { - e := newEnv(t, map[string]any{"repositories": []string{"acme/app", "acme/gone"}}) + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) e.gh.AddRepo("acme/app") - var c struct { + type report struct { OK bool Checks []struct { Name string @@ -500,7 +511,22 @@ func TestCheckReports(t *testing.T) { Detail string } } + var c report + e.ok("check", nil, &c) + if c.OK { + t.Fatalf("check passed with the tracked label not defined in the repository: %+v", c) + } + e.gh.DefineLabel("acme/app", "Hadron-Tracked") + c = report{} e.ok("check", nil, &c) + if !c.OK { + t.Fatalf("check failed on a sound setup: %+v", c) + } + e2 := newEnv(t, map[string]any{"repositories": []string{"acme/app", "acme/gone"}}) + e2.gh.AddRepo("acme/app") + e2.gh.DefineLabel("acme/app", "hadron-tracked") + c = report{} + e2.ok("check", nil, &c) if c.OK { t.Fatalf("check passed with an unreadable repository: %+v", c) } diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 0000000..6379f72 --- /dev/null +++ b/docs/design.md @@ -0,0 +1,115 @@ +# Design, as built + +[hadron-cli#1963](https://github.com/hadron-memory/hadron-cli/issues/1963): the +GitHub intake adapter, published in this public repository. + +Governing: `cor:agt:120` r10 (Task integrations: D2 the team's own credential, +D5 a public contract, D7 the label model in the adapter's configuration, D11 an +opaque cursor, D14 the mark never makes a claim), `cor:agt:120:04` (the intake +adapter contract), `cor:agt:120:02` (the external id and its checks). The +invocation format is the hadron CLI owner's, built in hadron-cli#1961 (merged +585bd9d6): `internal/intake` and `docs/plans/1961-intake-adapter-runner.md` +there. + +## Shape + +One Go executable with no dependencies beyond the standard library, so +`go install` is the whole installation. `cmd/` is a thin `main`; +`internal/adapter` is the protocol, the calls, the configuration and the +GitHub client; `internal/fakegithub` is the test stand-in; `conformance/` is +the suite against the runner's rules. + +GitHub is read through GraphQL: one query per repository page, issues in +creation order with their labels and per-issue cursors. Labels are written +through REST (add, remove), and REST also reads labels past GraphQL's first +page of 100. + +## Decisions taken here, and why + +**The mark is a label.** Removing a label is a clean `untrack`, the label is +visible on GitHub without reading comments, and it is what `list-untracked` +filters on. A comment naming the task and worker is opt-in (`comment: true`) +because on a public repository it publishes the team's worker names and links. +Hadron text in a comment is quoted as inline code on one line, so a name cannot +mention, link or reflow. The portal URL is linked only as the server printed +it, and only a plain https URL. + +**Filtering happens in the adapter, after GitHub's paging.** The GitHub list +is all open issues in creation order. The tracked label, the excluded labels, +the team and the ready label are applied to each issue as it is read. So a +mark (a label) never removes an issue from the sequence GitHub pages over, and +a cursor taken before others claimed still resumes at the right place. This is +the property `cor:agt:120:04` asks the opaque cursor to protect ("the set +shrinks while others claim"); `TestMarksBetweenPagesSkipNothing` pins it. Using +GitHub's search API with `-label:hadron-tracked` instead would page over a set +that shrinks between pages, and skip. + +**One order across repositories.** Oldest first, then repository, then number: +the order of today's server-side integration (cor:agt:120:03, D7), so a team +moving from it sees the same list. Each call merges the repositories' next +issues; the cursor keeps GitHub's cursor per repository (or `null` once one is +done), so nothing is re-read or skipped. + +**The cursor carries its query.** It embeds a fingerprint of the +configuration's filters, its repositories and `for`. A cursor resumed under a +different query is refused (exit 2), not silently resumed at a position that +means something else. With 30 repositories, the configuration's cap, the +cursor stays inside the runner's 4096-byte bound (pinned). + +**Bounded work per call.** A call reads at most one GitHub page per repository +plus 20 more, then answers with the eligible issues it has and a cursor. A long +run of ineligible issues therefore costs reads, not a timeout. Every call +consumes at least one issue, so the cursor always moves and the runner never +sees a repeated cursor. + +**Never a partial answer.** Any GitHub error, a GraphQL `errors` entry, a rate +limit, an issue that lacks a field, or an empty page that still promises more +refuses the whole call. A list is never cut short and presented as whole. + +**The external id is GitHub's URL, checked.** Each listed id is the issue URL +GitHub printed, checked to be `https://///issues/` +for the repository and number it was read as, and against `cor:agt:120:02`'s +checks. The ids handed back (`mark-tracked`, `untrack`, `get`) are parsed +strictly to that shape and must name a configured repository, so the adapter +acts on nothing else. + +**`for` is mapped, or refused.** The runner passes `--for X` as written. The +team map lists, per team, the worker names and URNs it covers, compared without +regard to case. A `for` that no team maps is refused: silently listing every +team's issues for an unknown worker would hand work to the wrong team. Without +`for`, the list is not narrowed by team. + +**The credential.** The token comes from `GITHUB_TOKEN`, `GH_TOKEN` or the +variable `tokenEnv` names, never a `HADRON_` variable (the CLI strips those +from an adapter's environment, and `tokenEnv` refuses one). It goes only into +the `Authorization` header, to an https endpoint (plain http only to the +loopback interface, for a local fake or proxy). GitHub's own error text is +scrubbed of it before it is repeated. + +**`describe` needs nothing.** It answers without a configuration or a +credential, and whatever contract version the request names: it is how the +CLI learns the adapter's version before asking anything else. + +**Request shapes the runner does not yet send.** At 585bd9d6 the runner calls +`describe`, `list-untracked` and `mark-tracked`. `untrack` and `get` (core) and +`normalize` and `check` (optional) are answered here with the shapes the README +states: `{externalId}` for `untrack` and `get`, `{ref}` for `normalize`, nothing +for `check`. hadron-cli#1962 (reconcile and release) is the first caller of +`untrack` and `get`; if it settles another shape, this adapter follows it. + +## Conformance + +The runner's checks live in hadron-cli's `internal/intake`, which another +module cannot import. `conformance/runner_rules.go` copies them (the bounds, +one JSON object on stdout, the external id's checks, the walk's cursor rules) +and names the hadron-cli revision they come from. The suite builds the adapter +and runs it as the runner does, against `internal/fakegithub`. + +Exposing the runner's checks as an importable package in hadron-cli, so this +suite imports them instead of copying, is a hadron-cli change and is left for +a follow-up there. + +## Not built + +- `report` and `changed-since` (optional calls). +- A release pipeline (goreleaser, tags). `go install` works from a tag or `main`. diff --git a/internal/adapter/adapter.go b/internal/adapter/adapter.go new file mode 100644 index 0000000..3a9ac37 --- /dev/null +++ b/internal/adapter/adapter.go @@ -0,0 +1,233 @@ +// Package adapter is the GitHub intake adapter: the calls of the intake +// adapter contract (cor:agt:120:04) answered against GitHub issues, invoked +// the way the hadron-cli runner invokes an adapter (hadron-cli#1961): +// +// hadron-task-adapter-github +// +// with one JSON object on stdin, which always carries "contractVersion", and +// one JSON object on stdout with exit 0. Any refusal is a non-zero exit, a +// one-line reason on stderr, and nothing on stdout. +package adapter + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "fmt" + "io" + "time" +) + +// ContractVersion is the contract version this adapter speaks. +const ContractVersion = 1 + +// Name is the adapter's name in describe. +const Name = "hadron-task-adapter-github" + +// Version is the adapter's own version, set at build time. +var Version = "dev" + +// Exit codes. Any non-zero exit is a refusal to the runner; the codes only +// tell a person which kind. +const ( + ExitOK = 0 + ExitTracker = 1 // GitHub refused, failed or answered something unusable + ExitUsage = 2 // the request: unknown call, bad JSON, another contract version, a bad argument + ExitConfig = 3 // the configuration or the credential +) + +const ( + maxRequestBytes = 1 << 20 + callTimeout = 50 * time.Second // inside the runner's 60 s + defaultLimit = 20 +) + +// Calls lists every call this adapter answers (describe.calls). +var Calls = []string{"describe", "list-untracked", "mark-tracked", "untrack", "get", "normalize", "check"} + +type exitError struct { + code int + msg string +} + +func (e *exitError) Error() string { return e.msg } + +func usageErr(f string, a ...any) error { return &exitError{ExitUsage, fmt.Sprintf(f, a...)} } +func configErr(f string, a ...any) error { return &exitError{ExitConfig, fmt.Sprintf(f, a...)} } + +// Env is what a run sees of its process. +type Env struct { + Args []string // the arguments after the program name + Stdin io.Reader + Stdout io.Writer + Stderr io.Writer + Getenv func(string) string +} + +// Run answers one call and returns the process's exit code. +func Run(ctx context.Context, e Env) int { + ctx, cancel := context.WithTimeout(ctx, callTimeout) + defer cancel() + out, err := run(ctx, e) + if err == nil { + b, merr := json.Marshal(out) + if merr == nil { + b = append(b, '\n') + if _, werr := e.Stdout.Write(b); werr == nil { + return ExitOK + } + } + err = &exitError{ExitTracker, "the answer could not be written"} + } + code := ExitTracker + var ee *exitError + if errors.As(err, &ee) { + code = ee.code + } + fmt.Fprintf(e.Stderr, "%s: %s\n", Name, oneLine(err.Error(), 600)) + return code +} + +func run(ctx context.Context, e Env) (any, error) { + if len(e.Args) != 1 { + return nil, usageErr("expected exactly one argument, the call (one of %v)", Calls) + } + call := e.Args[0] + known := false + for _, c := range Calls { + known = known || c == call + } + if !known { + return nil, usageErr("%q is not a call this adapter answers (one of %v)", oneLine(call, 40), Calls) + } + req, err := readRequest(e.Stdin) + if err != nil { + return nil, err + } + var version struct { + ContractVersion *int `json:"contractVersion"` + } + _ = json.Unmarshal(req, &version) + // describe answers whatever version the caller speaks: it is how the + // caller learns which one this adapter speaks. + if call == "describe" { + return describe(), nil + } + if version.ContractVersion == nil || *version.ContractVersion != ContractVersion { + got := "none" + if version.ContractVersion != nil { + got = fmt.Sprint(*version.ContractVersion) + } + return nil, usageErr("the request speaks contract version %s; this adapter speaks %d", got, ContractVersion) + } + if call == "check" { + return check(ctx, e.Getenv), nil + } + cfg, err := LoadConfig(e.Getenv) + if err != nil { + return nil, configErr("%v", err) + } + token, err := cfg.Token(e.Getenv) + if err != nil { + return nil, configErr("%v", err) + } + s := &session{cfg: cfg, gh: newGitHub(cfg, token)} + switch call { + case "list-untracked": + return s.listUntracked(ctx, req) + case "mark-tracked": + return s.markTracked(ctx, req) + case "untrack": + return s.untrack(ctx, req) + case "get": + return s.get(ctx, req) + case "normalize": + return s.normalize(ctx, req) + } + return nil, usageErr("%q is not answered", call) +} + +// readRequest reads exactly one JSON object from stdin. +func readRequest(r io.Reader) (json.RawMessage, error) { + b, err := io.ReadAll(io.LimitReader(r, maxRequestBytes+1)) + if err != nil { + return nil, usageErr("the request could not be read") + } + if len(b) > maxRequestBytes { + return nil, usageErr("the request is larger than %d bytes", maxRequestBytes) + } + b = bytes.TrimSpace(b) + if len(b) == 0 || b[0] != '{' { + return nil, usageErr("the request is not one JSON object") + } + var raw json.RawMessage + dec := json.NewDecoder(bytes.NewReader(b)) + if err := dec.Decode(&raw); err != nil { + return nil, usageErr("the request is not one well-formed JSON object") + } + if dec.More() { + return nil, usageErr("the request carries more than one JSON value") + } + return raw, nil +} + +func decode(req json.RawMessage, call string, v any) error { + if err := json.Unmarshal(req, v); err != nil { + return usageErr("the %s request has a field of the wrong type: %v", call, err) + } + return nil +} + +type describeAnswer struct { + Name string `json:"name"` + Version string `json:"version"` + ContractVersion int `json:"contractVersion"` + Calls []string `json:"calls"` + Filters []string `json:"filters"` + Order string `json:"order"` +} + +func describe() describeAnswer { + return describeAnswer{ + Name: Name, + Version: Version, + ContractVersion: ContractVersion, + Calls: Calls, + // `for` is the only filter a caller passes; the label model is the + // configuration's. + Filters: []string{"for"}, + Order: "created-asc", + } +} + +type session struct { + cfg *Config + gh *githubClient +} + +func (s *session) listUntracked(ctx context.Context, req json.RawMessage) (any, error) { + var r struct { + Limit *int `json:"limit"` + Cursor string `json:"cursor"` + For string `json:"for"` + } + if err := decode(req, "list-untracked", &r); err != nil { + return nil, err + } + limit := defaultLimit + if r.Limit != nil { + limit = *r.Limit + } + if limit < 1 || limit > 100 { + return nil, usageErr("limit %d is outside 1 to 100", limit) + } + items, next, err := (&lister{cfg: s.cfg, gh: s.gh}).list(ctx, r.Cursor, r.For, limit) + if err != nil { + return nil, err + } + return struct { + Items []listedItem `json:"items"` + NextCursor *string `json:"nextCursor"` + }{items, next}, nil +} diff --git a/internal/adapter/calls.go b/internal/adapter/calls.go new file mode 100644 index 0000000..06d1885 --- /dev/null +++ b/internal/adapter/calls.go @@ -0,0 +1,287 @@ +package adapter + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "net/http" + "strings" +) + +// configuredIssue reads an external id the CLI hands back and checks it names +// an issue of a configured repository. The adapter acts only on the +// repositories its configuration lists. +func (s *session) configuredIssue(call, externalID string) (issueRef, error) { + if externalID == "" { + return issueRef{}, usageErr("%s needs an externalId", call) + } + ref, err := parseIssueURL(externalID, s.cfg.WebHost) + if err != nil { + return issueRef{}, usageErr("%s: %q: %v", call, oneLine(externalID, 120), err) + } + if !s.cfg.hasRepo(ref.Owner, ref.Name) { + return issueRef{}, usageErr("%s: %s/%s is not a repository in the adapter's configuration", call, ref.Owner, ref.Name) + } + return ref, nil +} + +func issuePath(ref issueRef, rest string) string { + return fmt.Sprintf("/repos/%s/%s/issues/%d%s", escapePath(ref.Owner), escapePath(ref.Name), ref.Number, rest) +} + +type markRequest struct { + ExternalID string `json:"externalId"` + Task struct { + ID string `json:"id"` + Handle string `json:"handle"` + PortalURL string `json:"portalUrl"` + } `json:"task"` + Worker struct { + ID string `json:"id"` + Name string `json:"name"` + Role string `json:"role"` + Model string `json:"model"` + } `json:"worker"` +} + +// markTracked puts the tracked label on the issue, and when the +// configuration asks for it, a comment naming the task and the worker. It +// never refuses because the issue is already marked: the mark shows a claim, +// it never makes or decides one (cor:agt:120, D14). A re-mark after a +// reassignment is an ordinary call. +func (s *session) markTracked(ctx context.Context, req json.RawMessage) (any, error) { + var r markRequest + if err := decode(req, "mark-tracked", &r); err != nil { + return nil, err + } + ref, err := s.configuredIssue("mark-tracked", r.ExternalID) + if err != nil { + return nil, err + } + if r.Task.ID == "" { + return nil, usageErr("mark-tracked needs the task's id") + } + body := map[string][]string{"labels": {s.cfg.TrackedLabel}} + if _, err := s.gh.rest(ctx, http.MethodPost, issuePath(ref, "/labels"), body, nil, http.StatusOK); err != nil { + return nil, fmt.Errorf("labelling %s/%s#%d: %w", ref.Owner, ref.Name, ref.Number, err) + } + commented := false + if s.cfg.Comment { + if _, err := s.gh.rest(ctx, http.MethodPost, issuePath(ref, "/comments"), map[string]string{"body": markComment(r)}, nil, http.StatusCreated); err != nil { + // The label is on: the item shows as tracked. Say the comment + // failed rather than pretend the whole mark did. + return nil, fmt.Errorf("%s/%s#%d is labelled %q, but the comment failed: %w", ref.Owner, ref.Name, ref.Number, s.cfg.TrackedLabel, err) + } + commented = true + } + return map[string]any{"marked": true, "externalId": r.ExternalID, "label": s.cfg.TrackedLabel, "commented": commented}, nil +} + +// code quotes text from Hadron as inline code on one line, so a name cannot +// mention anyone, link anywhere or change the comment's layout. +func code(s string) string { + s = strings.ReplaceAll(oneLine(s, 120), "`", "'") + if s == "" { + return "" + } + return "`" + s + "`" +} + +func markComment(r markRequest) string { + var b strings.Builder + b.WriteString("Tracked in Hadron") + task := r.Task.Handle + if task == "" { + task = r.Task.ID + } + fmt.Fprintf(&b, " as task %s", code(task)) + // The portal URL is the server's, passed as printed (cor:agt:120:04); + // the adapter builds none, and links only a plain https URL. + if u := r.Task.PortalURL; strings.HasPrefix(u, "https://") && checkExternalID(u) == nil && !strings.ContainsAny(u, "()[]<>`") { + fmt.Fprintf(&b, " (%s)", u) + } + if r.Worker.Name != "" { + fmt.Fprintf(&b, ", by %s", code(r.Worker.Name)) + if r.Worker.Role != "" { + fmt.Fprintf(&b, " (%s)", code(r.Worker.Role)) + } + } + b.WriteString(".") + return b.String() +} + +// untrack removes the tracked label. An issue that carries no mark is not an +// error: the outcome the caller wants already holds. +func (s *session) untrack(ctx context.Context, req json.RawMessage) (any, error) { + var r struct { + ExternalID string `json:"externalId"` + } + if err := decode(req, "untrack", &r); err != nil { + return nil, err + } + ref, err := s.configuredIssue("untrack", r.ExternalID) + if err != nil { + return nil, err + } + status, err := s.gh.rest(ctx, http.MethodDelete, issuePath(ref, "/labels/"+escapePath(s.cfg.TrackedLabel)), nil, nil, http.StatusOK) + if err != nil { + var ae *apiError + // GitHub answers 404 "Label does not exist" for a label the issue + // does not carry. Any other 404 (no such issue, no access) is an + // error. + noMark := errors.As(err, &ae) && status == http.StatusNotFound && strings.Contains(strings.ToLower(ae.Message), "label does not exist") + if !noMark { + return nil, fmt.Errorf("unlabelling %s/%s#%d: %w", ref.Owner, ref.Name, ref.Number, err) + } + } + return map[string]any{"untracked": true, "externalId": r.ExternalID}, nil +} + +const getQuery = `query GetIssue($owner:String!,$name:String!,$number:Int!,$labelsFirst:Int!){ + repository(owner:$owner,name:$name){ + issue(number:$number){number title body state url labels(first:$labelsFirst){nodes{name} pageInfo{hasNextPage}}} + } +}` + +type issueDetail struct { + Number int `json:"number"` + Title string `json:"title"` + Body string `json:"body"` + State string `json:"state"` + URL string `json:"url"` + Labels labelConn `json:"labels"` +} + +func (s *session) readIssue(ctx context.Context, ref issueRef) (*issueDetail, error) { + var data struct { + Repository *struct { + Issue *issueDetail `json:"issue"` + } `json:"repository"` + } + err := s.gh.graphql(ctx, "GetIssue", getQuery, map[string]any{"owner": ref.Owner, "name": ref.Name, "number": ref.Number, "labelsFirst": labelsPerIssue}, &data) + var nf *notFoundError + if errors.As(err, &nf) || err == nil && (data.Repository == nil || data.Repository.Issue == nil) { + return nil, fmt.Errorf("%s/%s#%d: no such issue, or the credential cannot read it", ref.Owner, ref.Name, ref.Number) + } + if err != nil { + return nil, fmt.Errorf("reading %s/%s#%d: %w", ref.Owner, ref.Name, ref.Number, err) + } + return data.Repository.Issue, nil +} + +// get returns one item. Its externalId is the one asked about, as given; +// url is GitHub's canonical URL now (it differs after a transfer or a rename). +func (s *session) get(ctx context.Context, req json.RawMessage) (any, error) { + var r struct { + ExternalID string `json:"externalId"` + } + if err := decode(req, "get", &r); err != nil { + return nil, err + } + ref, err := s.configuredIssue("get", r.ExternalID) + if err != nil { + return nil, err + } + is, err := s.readIssue(ctx, ref) + if err != nil { + return nil, err + } + labels, err := (&lister{cfg: s.cfg, gh: s.gh}).labels(ctx, repo{Owner: ref.Owner, Name: ref.Name, Key: ref.Key}, issueNode{Number: is.Number, Labels: is.Labels}) + if err != nil { + return nil, err + } + tracked := false + for _, l := range labels { + tracked = tracked || strings.EqualFold(l, s.cfg.TrackedLabel) + } + // Labels themselves are not returned: tracker labels never reach Hadron + // (cor:agt:120, D7). + return map[string]any{"item": map[string]any{ + "externalId": r.ExternalID, + "title": boundTitle(is.Title), + "body": is.Body, + "state": strings.ToLower(is.State), + "url": is.URL, + "tracked": tracked, + }}, nil +} + +// normalize turns a short reference into the issue's canonical external id, +// as GitHub prints it. +func (s *session) normalize(ctx context.Context, req json.RawMessage) (any, error) { + var r struct { + Ref string `json:"ref"` + } + if err := decode(req, "normalize", &r); err != nil { + return nil, err + } + ref, err := s.cfg.parseShortRef(r.Ref) + if err != nil { + return nil, usageErr("normalize: %q: %v", oneLine(r.Ref, 120), err) + } + if !s.cfg.hasRepo(ref.Owner, ref.Name) { + return nil, usageErr("normalize: %s/%s is not a repository in the adapter's configuration", ref.Owner, ref.Name) + } + is, err := s.readIssue(ctx, ref) + if err != nil { + return nil, err + } + l := &lister{cfg: s.cfg} + id, err := l.externalID(repo{Owner: ref.Owner, Name: ref.Name, Key: ref.Key}, issueNode{Number: is.Number, URL: is.URL}) + if err != nil { + return nil, err + } + return map[string]any{"externalId": id}, nil +} + +type checkResult struct { + Name string `json:"name"` + OK bool `json:"ok"` + Detail string `json:"detail,omitempty"` +} + +// check says whether the configuration is valid, the credential present and +// accepted, and each repository readable. It answers (exit 0) whatever it +// finds; ok is true only when every check passed. +func check(ctx context.Context, getenv func(string) string) any { + results := []checkResult{} + answer := func() any { + ok := true + for _, r := range results { + ok = ok && r.OK + } + return map[string]any{"ok": ok, "checks": results} + } + cfg, err := LoadConfig(getenv) + if err != nil { + results = append(results, checkResult{Name: "configuration", OK: false, Detail: oneLine(err.Error(), 300)}) + return answer() + } + token, err := cfg.Token(getenv) + if err != nil { + results = append(results, checkResult{Name: "credential", OK: false, Detail: oneLine(err.Error(), 300)}) + return answer() + } + gh := newGitHub(cfg, token) + if _, err := gh.rest(ctx, http.MethodGet, "/rate_limit", nil, nil, http.StatusOK); err != nil { + results = append(results, checkResult{Name: "credential", OK: false, Detail: oneLine(err.Error(), 300)}) + return answer() + } + results = append(results, checkResult{Name: "credential", OK: true}) + for _, r := range cfg.repos() { + name := "repository " + r.Owner + "/" + r.Name + if _, err := gh.rest(ctx, http.MethodGet, "/repos/"+escapePath(r.Owner)+"/"+escapePath(r.Name), nil, nil, http.StatusOK); err != nil { + results = append(results, checkResult{Name: name, OK: false, Detail: oneLine(err.Error(), 300)}) + continue + } + results = append(results, checkResult{Name: name, OK: true}) + lname := "label " + cfg.TrackedLabel + " in " + r.Owner + "/" + r.Name + if _, err := gh.rest(ctx, http.MethodGet, "/repos/"+escapePath(r.Owner)+"/"+escapePath(r.Name)+"/labels/"+escapePath(cfg.TrackedLabel), nil, nil, http.StatusOK); err != nil { + results = append(results, checkResult{Name: lname, OK: false, Detail: "create it first (gh label create " + cfg.TrackedLabel + " -R " + r.Owner + "/" + r.Name + "): " + oneLine(err.Error(), 200)}) + continue + } + results = append(results, checkResult{Name: lname, OK: true}) + } + return answer() +} diff --git a/internal/adapter/config.go b/internal/adapter/config.go new file mode 100644 index 0000000..33dbbb4 --- /dev/null +++ b/internal/adapter/config.go @@ -0,0 +1,342 @@ +package adapter + +import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "io" + "io/fs" + "net/url" + "os" + "path/filepath" + "regexp" + "strings" + "unicode" +) + +// ConfigEnv names the configuration file. The adapter takes no flags (the +// runner passes exactly one argument, the call), so this and the default +// path are the only ways to point it at a team's configuration. +const ConfigEnv = "TASK_ADAPTER_GITHUB_CONFIG" + +// Limits on the configuration. +const ( + MaxRepositories = 30 // keeps the cursor inside the runner's 4096-byte bound + MaxLabelLen = 100 + MaxExcludeLabels = 50 + MaxTeams = 50 + MaxForPerTeam = 20 + DefaultTracked = "hadron-tracked" + DefaultAPIURL = "https://api.github.com" + DefaultWebHost = "github.com" + maxConfigFileSize = 256 << 10 +) + +// Config is a team's adapter configuration: today's label model +// (cor:agt:120, D7: tracker labels never reach Hadron, they live here), the +// repositories, and how the adapter marks an item tracked. It holds no +// credential: the token is read from the environment. +type Config struct { + // Repositories are "owner/name"; their open issues are the intake. + Repositories []string `json:"repositories"` + // ReadyLabel marks an issue ready for intake. + ReadyLabel string `json:"readyLabel,omitempty"` + // Ready is "only" (list only ready issues; the default when ReadyLabel + // is set), "exclude" or "any" (the default when it is not). + Ready string `json:"ready,omitempty"` + // ExcludeLabels: an issue carrying any of them is never listed. + ExcludeLabels []string `json:"excludeLabels,omitempty"` + // Teams maps the runner's `for` (a worker's name or URN) to a team label, + // or to the issues carrying no team label at all. + Teams []Team `json:"teams,omitempty"` + // TrackedLabel is the adapter's mark. Default "hadron-tracked". + TrackedLabel string `json:"trackedLabel,omitempty"` + // Comment also posts a comment naming the task and worker on mark-tracked. + // Off by default: on a public repository it publishes the team's names. + Comment bool `json:"comment,omitempty"` + // TokenEnv names the environment variable holding the team's GitHub + // token. Unset: GITHUB_TOKEN, then GH_TOKEN. + TokenEnv string `json:"tokenEnv,omitempty"` + // APIURL is the REST base (GitHub Enterprise Server: https://HOST/api/v3). + APIURL string `json:"apiUrl,omitempty"` + // GraphQLURL defaults to APIURL + "/graphql" (Enterprise Server: https://HOST/api/graphql). + GraphQLURL string `json:"graphqlUrl,omitempty"` + // WebHost is the host of issue URLs. Default github.com. + WebHost string `json:"webHost,omitempty"` +} + +// Team is one entry of the team map. +type Team struct { + For []string `json:"for"` + Label string `json:"label,omitempty"` + NoTeam bool `json:"noTeam,omitempty"` +} + +// repo is one configured repository. +type repo struct { + Owner, Name string + Key string // lower-cased "owner/name" +} + +var repoSegment = regexp.MustCompile(`^[A-Za-z0-9._-]+$`) + +// validSegment is one segment of "owner/name": GitHub's characters, and never +// "." or "..", which would make a path out of a name. +func validSegment(s string) bool { + return repoSegment.MatchString(s) && s != "." && s != ".." +} + +// ConfigPath is where the configuration is read from. +func ConfigPath(getenv func(string) string) (string, error) { + if p := getenv(ConfigEnv); p != "" { + return p, nil + } + dir, err := os.UserConfigDir() + if err != nil { + return "", fmt.Errorf("no configuration: set %s, or create it under the user configuration directory", ConfigEnv) + } + return filepath.Join(dir, "hadron-task-adapter-github", "config.json"), nil +} + +// LoadConfig reads and validates the configuration. +func LoadConfig(getenv func(string) string) (*Config, error) { + p, err := ConfigPath(getenv) + if err != nil { + return nil, err + } + b, err := readBounded(p, maxConfigFileSize) + if errors.Is(err, fs.ErrNotExist) { + return nil, fmt.Errorf("no configuration at %s (set %s to its path; see config.example.json)", p, ConfigEnv) + } + if err != nil { + return nil, fmt.Errorf("reading the configuration %s: %v", p, err) + } + return ParseConfig(b) +} + +func readBounded(p string, max int64) ([]byte, error) { + f, err := os.Open(p) + if err != nil { + return nil, err + } + defer f.Close() + b, err := io.ReadAll(io.LimitReader(f, max+1)) + if err != nil { + return nil, err + } + if int64(len(b)) > max { + return nil, fmt.Errorf("larger than %d bytes", max) + } + return b, nil +} + +// ParseConfig decodes and validates a configuration. Unknown keys are +// refused: a misspelt label key would otherwise silently widen the intake. +func ParseConfig(b []byte) (*Config, error) { + dec := json.NewDecoder(bytes.NewReader(b)) + dec.DisallowUnknownFields() + var c Config + if err := dec.Decode(&c); err != nil { + return nil, fmt.Errorf("configuration: %v", err) + } + if dec.More() { + return nil, errors.New("configuration: more than one JSON value") + } + if err := c.validate(); err != nil { + return nil, fmt.Errorf("configuration: %v", err) + } + return &c, nil +} + +func checkLabel(field, l string) error { + if l == "" || len([]rune(l)) > MaxLabelLen { + return fmt.Errorf("%s: a label is 1 to %d characters", field, MaxLabelLen) + } + for _, r := range l { + if unicode.IsControl(r) || unicode.Is(unicode.Cf, r) { + return fmt.Errorf("%s: a label may not contain control or invisible format characters", field) + } + } + return nil +} + +func (c *Config) validate() error { + if len(c.Repositories) == 0 || len(c.Repositories) > MaxRepositories { + return fmt.Errorf("repositories: list 1 to %d repositories", MaxRepositories) + } + seen := map[string]bool{} + for i, r := range c.Repositories { + parts := strings.Split(r, "/") + if len(parts) != 2 || !validSegment(parts[0]) || !validSegment(parts[1]) { + return fmt.Errorf("repositories[%d]: %q is not \"owner/name\"", i, r) + } + k := strings.ToLower(r) + if seen[k] { + return fmt.Errorf("repositories[%d]: %q is listed twice", i, r) + } + seen[k] = true + } + if c.ReadyLabel != "" { + if err := checkLabel("readyLabel", c.ReadyLabel); err != nil { + return err + } + } + switch c.Ready { + case "": + c.Ready = "any" + if c.ReadyLabel != "" { + c.Ready = "only" + } + case "only", "exclude": + if c.ReadyLabel == "" { + return fmt.Errorf("ready: %q needs a readyLabel", c.Ready) + } + case "any": + default: + return fmt.Errorf("ready: %q is not one of only, exclude, any", c.Ready) + } + if len(c.ExcludeLabels) > MaxExcludeLabels { + return fmt.Errorf("excludeLabels: at most %d", MaxExcludeLabels) + } + for i, l := range c.ExcludeLabels { + if err := checkLabel(fmt.Sprintf("excludeLabels[%d]", i), l); err != nil { + return err + } + } + if len(c.Teams) > MaxTeams { + return fmt.Errorf("teams: at most %d", MaxTeams) + } + who := map[string]bool{} + for i, t := range c.Teams { + at := fmt.Sprintf("teams[%d]", i) + if len(t.For) == 0 || len(t.For) > MaxForPerTeam { + return fmt.Errorf("%s.for: name 1 to %d workers (names or URNs)", at, MaxForPerTeam) + } + for j, f := range t.For { + if strings.TrimSpace(f) == "" || len(f) > 512 { + return fmt.Errorf("%s.for[%d]: a worker name or URN of 1 to 512 bytes", at, j) + } + k := strings.ToLower(f) + if who[k] { + return fmt.Errorf("%s.for[%d]: %q is mapped to another team already", at, j, f) + } + who[k] = true + } + switch { + case t.NoTeam && t.Label != "": + return fmt.Errorf("%s: a team has a label or noTeam, not both", at) + case !t.NoTeam: + if err := checkLabel(at+".label", t.Label); err != nil { + return err + } + } + } + if c.TrackedLabel == "" { + c.TrackedLabel = DefaultTracked + } + if err := checkLabel("trackedLabel", c.TrackedLabel); err != nil { + return err + } + if strings.EqualFold(c.TrackedLabel, c.ReadyLabel) { + return errors.New("trackedLabel: must differ from readyLabel") + } + if c.TokenEnv != "" { + if !regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`).MatchString(c.TokenEnv) { + return fmt.Errorf("tokenEnv: %q is not an environment variable name", c.TokenEnv) + } + // The hadron CLI strips HADRON_* credentials from the adapter's + // environment (cor:agt:120, D2): such a variable never arrives. + if strings.HasPrefix(strings.ToUpper(c.TokenEnv), "HADRON_") { + return errors.New("tokenEnv: a HADRON_ variable is never passed to the adapter; the GitHub token is the team's own") + } + } + if c.APIURL == "" { + c.APIURL = DefaultAPIURL + } + c.APIURL = strings.TrimRight(c.APIURL, "/") + if err := checkEndpoint("apiUrl", c.APIURL); err != nil { + return err + } + if c.GraphQLURL == "" { + c.GraphQLURL = c.APIURL + "/graphql" + } + if err := checkEndpoint("graphqlUrl", c.GraphQLURL); err != nil { + return err + } + if c.WebHost == "" { + c.WebHost = DefaultWebHost + } + if strings.ContainsAny(c.WebHost, "/@: \t") { + return fmt.Errorf("webHost: %q is a host name, not a URL", c.WebHost) + } + return nil +} + +// checkEndpoint: the token is sent there, so it is https, or plain http only +// to the loopback interface (a local fake or proxy). +func checkEndpoint(field, raw string) error { + u, err := url.Parse(raw) + if err != nil || u.Host == "" || u.User != nil || u.RawQuery != "" || u.Fragment != "" { + return fmt.Errorf("%s: %q is not a plain https URL", field, raw) + } + switch u.Scheme { + case "https": + return nil + case "http": + h := u.Hostname() + if h == "localhost" || h == "127.0.0.1" || h == "::1" { + return nil + } + } + return fmt.Errorf("%s: %q must be https (http only to the loopback interface)", field, raw) +} + +func (c *Config) repos() []repo { + out := make([]repo, 0, len(c.Repositories)) + for _, r := range c.Repositories { + o, n, _ := strings.Cut(r, "/") + out = append(out, repo{Owner: o, Name: n, Key: strings.ToLower(r)}) + } + return out +} + +func (c *Config) hasRepo(owner, name string) bool { + k := strings.ToLower(owner + "/" + name) + for _, r := range c.repos() { + if r.Key == k { + return true + } + } + return false +} + +// team resolves the runner's `for`. ok is false when `for` is given and no +// team maps it. +func (c *Config) team(forWorker string) (t *Team, ok bool) { + if forWorker == "" { + return nil, true + } + for i := range c.Teams { + for _, f := range c.Teams[i].For { + if strings.EqualFold(f, forWorker) { + return &c.Teams[i], true + } + } + } + return nil, false +} + +// Token returns the team's GitHub token from the environment. +func (c *Config) Token(getenv func(string) string) (string, error) { + names := []string{"GITHUB_TOKEN", "GH_TOKEN"} + if c.TokenEnv != "" { + names = []string{c.TokenEnv} + } + for _, n := range names { + if v := strings.TrimSpace(getenv(n)); v != "" { + return v, nil + } + } + return "", fmt.Errorf("no GitHub credential: set %s to the team's own GitHub token (never a Hadron one)", strings.Join(names, " or ")) +} diff --git a/internal/adapter/config_test.go b/internal/adapter/config_test.go new file mode 100644 index 0000000..6361a8e --- /dev/null +++ b/internal/adapter/config_test.go @@ -0,0 +1,164 @@ +package adapter + +import ( + "os" + "path/filepath" + "strings" + "testing" +) + +func TestConfigRefusals(t *testing.T) { + cases := map[string]string{ + "no repositories": `{"repositories":[]}`, + "not owner/name": `{"repositories":["acme"]}`, + "path in name": `{"repositories":["acme/app/x"]}`, + "dot name": `{"repositories":["acme/.."]}`, + "dot owner": `{"repositories":["../app"]}`, + "duplicate repo": `{"repositories":["acme/app","ACME/App"]}`, + "unknown key": `{"repositories":["acme/app"],"readyLable":"x"}`, + "two values": `{"repositories":["acme/app"]}{}`, + "ready only without label": `{"repositories":["acme/app"],"ready":"only"}`, + "ready unknown": `{"repositories":["acme/app"],"readyLabel":"r","ready":"some"}`, + "control in label": "{\"repositories\":[\"acme/app\"],\"readyLabel\":\"a\\u0007b\"}", + "format char in label": "{\"repositories\":[\"acme/app\"],\"excludeLabels\":[\"a\\u200bb\"]}", + "team without for": `{"repositories":["acme/app"],"teams":[{"for":[],"label":"t"}]}`, + "team with label and none": `{"repositories":["acme/app"],"teams":[{"for":["a"],"label":"t","noTeam":true}]}`, + "team without label": `{"repositories":["acme/app"],"teams":[{"for":["a"]}]}`, + "worker in two teams": `{"repositories":["acme/app"],"teams":[{"for":["Ada"],"label":"t"},{"for":["ada"],"label":"u"}]}`, + "tracked equals ready": `{"repositories":["acme/app"],"readyLabel":"x","trackedLabel":"X"}`, + "hadron token env": `{"repositories":["acme/app"],"tokenEnv":"HADRON_GITHUB_TOKEN"}`, + "bad token env": `{"repositories":["acme/app"],"tokenEnv":"A-B"}`, + "plain http to remote": `{"repositories":["acme/app"],"apiUrl":"http://api.example.com"}`, + "userinfo in api url": `{"repositories":["acme/app"],"apiUrl":"https://u:p@api.example.com"}`, + "web host with scheme": `{"repositories":["acme/app"],"webHost":"https://github.com"}`, + "thirty-one repositories": `{"repositories":[` + manyRepos(31) + `]}`, + "graphql url to plain http": `{"repositories":["acme/app"],"graphqlUrl":"http://example.com/graphql"}`, + } + for name, raw := range cases { + t.Run(name, func(t *testing.T) { + if _, err := ParseConfig([]byte(raw)); err == nil { + t.Fatalf("accepted %s", raw) + } + }) + } +} + +func manyRepos(n int) string { + parts := []string{} + for i := 0; i < n; i++ { + parts = append(parts, `"o/r`+strings.Repeat("x", i)+`"`) + } + return strings.Join(parts, ",") +} + +func TestConfigDefaults(t *testing.T) { + c, err := ParseConfig([]byte(`{"repositories":["acme/app"],"readyLabel":"cleared"}`)) + if err != nil { + t.Fatal(err) + } + if c.Ready != "only" || c.TrackedLabel != DefaultTracked || c.APIURL != DefaultAPIURL || c.GraphQLURL != DefaultAPIURL+"/graphql" || c.WebHost != DefaultWebHost { + t.Fatalf("defaults: %+v", c) + } + c, err = ParseConfig([]byte(`{"repositories":["acme/app"],"apiUrl":"https://ghe.example.com/api/v3/","graphqlUrl":"https://ghe.example.com/api/graphql","webHost":"ghe.example.com"}`)) + if err != nil { + t.Fatal(err) + } + if c.Ready != "any" || c.APIURL != "https://ghe.example.com/api/v3" { + t.Fatalf("enterprise: %+v", c) + } +} + +func TestTokenLookup(t *testing.T) { + c, _ := ParseConfig([]byte(`{"repositories":["acme/app"]}`)) + env := map[string]string{"GH_TOKEN": "b"} + if tok, err := c.Token(func(k string) string { return env[k] }); err != nil || tok != "b" { + t.Fatalf("GH_TOKEN: %q %v", tok, err) + } + env["GITHUB_TOKEN"] = "a" + if tok, _ := c.Token(func(k string) string { return env[k] }); tok != "a" { + t.Fatalf("GITHUB_TOKEN first: %q", tok) + } + c.TokenEnv = "TEAM_GH" + if _, err := c.Token(func(k string) string { return env[k] }); err == nil { + t.Fatal("tokenEnv set but empty: fell back to another variable") + } +} + +func TestConfigFileIsBounded(t *testing.T) { + p := filepath.Join(t.TempDir(), "c.json") + if err := os.WriteFile(p, []byte(`{"repositories":["acme/app"],"readyLabel":"`+strings.Repeat("a", maxConfigFileSize)+`"}`), 0o600); err != nil { + t.Fatal(err) + } + if _, err := LoadConfig(func(k string) string { + if k == ConfigEnv { + return p + } + return "" + }); err == nil || !strings.Contains(err.Error(), "larger than") { + t.Fatalf("an oversized configuration: %v", err) + } +} + +func TestParseIssueURL(t *testing.T) { + good := map[string]issueRef{ + "https://github.com/Acme/App/issues/12": {Owner: "Acme", Name: "App", Key: "acme/app", Number: 12}, + } + for raw, want := range good { + got, err := parseIssueURL(raw, "github.com") + if err != nil || got != want { + t.Fatalf("%s: %+v %v", raw, got, err) + } + } + for _, raw := range []string{ + "http://github.com/acme/app/issues/1", + "https://evil.example/acme/app/issues/1", + "https://u@github.com/acme/app/issues/1", + "https://github.com:443/acme/app/issues/1", + "https://github.com/acme/app/pull/1", + "https://github.com/acme/app/issues/1/", + "https://github.com/acme/app/issues/01", + "https://github.com/acme/app/issues/0", + "https://github.com/acme/app/issues/1?x=1", + "https://github.com/acme/app/issues/1#c", + "https://github.com/acme/app/issues/1/comments", + "https://github.com/acme/../issues/1", + "https://github.com/acme/app%2fx/issues/1", + } { + if _, err := parseIssueURL(raw, "github.com"); err == nil { + t.Errorf("accepted %s", raw) + } + } +} + +func TestCheckExternalID(t *testing.T) { + for _, bad := range []string{"", "https://github.com/a/b/issues/1 ", "https://x/\u200b", "https://u:p@github.com/a", strings.Repeat("a", 513)} { + if checkExternalID(bad) == nil { + t.Errorf("accepted %q", bad) + } + } + if err := checkExternalID(strings.Repeat("é", 512)); err != nil { + t.Errorf("512 code points refused: %v", err) + } +} + +func TestOneLineAndBoundTitle(t *testing.T) { + if got := oneLine("a\n\tb\u202ec\x1b[31m", 50); got != "a b c [31m" { + t.Fatalf("oneLine: %q", got) + } + long := strings.Repeat("é", 700) // 1400 bytes + got := boundTitle(long) + if len(got) > 1024 || !strings.HasSuffix(got, "…") { + t.Fatalf("boundTitle: %d bytes", len(got)) + } +} + +// The example the README points at is a valid configuration. +func TestExampleConfigParses(t *testing.T) { + b, err := os.ReadFile(filepath.Join("..", "..", "config.example.json")) + if err != nil { + t.Fatal(err) + } + if _, err := ParseConfig(b); err != nil { + t.Fatalf("config.example.json: %v", err) + } +} diff --git a/internal/adapter/github.go b/internal/adapter/github.go new file mode 100644 index 0000000..d01c744 --- /dev/null +++ b/internal/adapter/github.go @@ -0,0 +1,168 @@ +package adapter + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "io" + "net/http" + "net/url" + "strings" + "time" +) + +const ( + maxResponseBytes = 16 << 20 + requestTimeout = 20 * time.Second + userAgent = "hadron-task-adapter-github" +) + +// githubClient calls GitHub with the team's token. The token is only ever +// put in the Authorization header: no error message, log line or answer +// carries it, and GitHub's own error text is scrubbed of it before it is +// repeated. +type githubClient struct { + http *http.Client + api, gql string + token string +} + +func newGitHub(c *Config, token string) *githubClient { + return &githubClient{http: &http.Client{Timeout: requestTimeout}, api: c.APIURL, gql: c.GraphQLURL, token: token} +} + +// apiError is a GitHub answer the adapter will not use. +type apiError struct { + Status int + Message string +} + +func (e *apiError) Error() string { + if e.Status == 0 { + return "GitHub: " + e.Message + } + return fmt.Sprintf("GitHub answered %d: %s", e.Status, e.Message) +} + +func (g *githubClient) scrub(s string) string { + if g.token != "" { + s = strings.ReplaceAll(s, g.token, "[redacted]") + } + return oneLine(s, 200) +} + +func (g *githubClient) do(ctx context.Context, method, endpoint string, body any) (int, []byte, error) { + var rd io.Reader + if body != nil { + b, err := json.Marshal(body) + if err != nil { + return 0, nil, err + } + rd = bytes.NewReader(b) + } + req, err := http.NewRequestWithContext(ctx, method, endpoint, rd) + if err != nil { + return 0, nil, err + } + req.Header.Set("Authorization", "Bearer "+g.token) + req.Header.Set("Accept", "application/vnd.github+json") + req.Header.Set("X-GitHub-Api-Version", "2022-11-28") + req.Header.Set("User-Agent", userAgent) + if body != nil { + req.Header.Set("Content-Type", "application/json") + } + resp, err := g.http.Do(req) + if err != nil { + // A transport error can quote the URL, never the header; scrub anyway. + return 0, nil, &apiError{Message: g.scrub(err.Error())} + } + defer resp.Body.Close() + b, err := io.ReadAll(io.LimitReader(resp.Body, maxResponseBytes+1)) + if err != nil { + return 0, nil, &apiError{Status: resp.StatusCode, Message: "the answer could not be read"} + } + if len(b) > maxResponseBytes { + return 0, nil, &apiError{Status: resp.StatusCode, Message: "the answer is larger than the adapter reads"} + } + if resp.StatusCode == http.StatusForbidden || resp.StatusCode == http.StatusTooManyRequests { + if resp.Header.Get("X-RateLimit-Remaining") == "0" || resp.Header.Get("Retry-After") != "" { + return resp.StatusCode, b, &apiError{Status: resp.StatusCode, Message: "rate limited; try again later"} + } + } + return resp.StatusCode, b, nil +} + +func (g *githubClient) errorFrom(status int, b []byte) error { + var m struct { + Message string `json:"message"` + } + _ = json.Unmarshal(b, &m) + msg := m.Message + if msg == "" { + msg = http.StatusText(status) + } + return &apiError{Status: status, Message: g.scrub(msg)} +} + +// rest makes one REST call. ok lists the statuses that are an answer; any +// other is an error. out may be nil. +func (g *githubClient) rest(ctx context.Context, method, path string, body any, out any, ok ...int) (int, error) { + status, b, err := g.do(ctx, method, g.api+path, body) + if err != nil { + return status, err + } + for _, s := range ok { + if status == s { + if out != nil && len(b) > 0 { + if err := json.Unmarshal(b, out); err != nil { + return status, &apiError{Status: status, Message: "an answer the adapter does not understand"} + } + } + return status, nil + } + } + return status, g.errorFrom(status, b) +} + +// graphql makes one GraphQL query. Any error in the answer fails the call: +// a partial answer is never read as a whole one. +func (g *githubClient) graphql(ctx context.Context, op, query string, vars map[string]any, out any) error { + status, b, err := g.do(ctx, http.MethodPost, g.gql, map[string]any{"query": query, "operationName": op, "variables": vars}) + if err != nil { + return err + } + if status != http.StatusOK { + return g.errorFrom(status, b) + } + var env struct { + Data json.RawMessage `json:"data"` + Errors []struct { + Type string `json:"type"` + Message string `json:"message"` + } `json:"errors"` + } + if err := json.Unmarshal(b, &env); err != nil { + return &apiError{Status: status, Message: "an answer the adapter does not understand"} + } + if len(env.Errors) > 0 { + e := env.Errors[0] + if e.Type == "NOT_FOUND" { + return ¬FoundError{msg: g.scrub(e.Message)} + } + return &apiError{Status: status, Message: g.scrub(e.Message)} + } + if len(env.Data) == 0 || string(env.Data) == "null" { + return &apiError{Status: status, Message: "an answer with no data"} + } + if err := json.Unmarshal(env.Data, out); err != nil { + return &apiError{Status: status, Message: "an answer the adapter does not understand"} + } + return nil +} + +type notFoundError struct{ msg string } + +func (e *notFoundError) Error() string { return "GitHub: " + e.msg } + +func escapePath(s string) string { return url.PathEscape(s) } diff --git a/internal/adapter/list.go b/internal/adapter/list.go new file mode 100644 index 0000000..0b42003 --- /dev/null +++ b/internal/adapter/list.go @@ -0,0 +1,338 @@ +package adapter + +import ( + "context" + "crypto/sha256" + "encoding/base64" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "net/http" + "strings" + "time" +) + +const ( + issuesPerRequest = 100 + labelsPerIssue = 100 + maxLabelPages = 10 // REST fallback: 1000 labels on one issue + // A call reads at most this many GitHub pages beyond the first of each + // repository, then answers with what it has and a cursor. Filtering + // happens here, so a run of ineligible issues costs reads, not items. + extraFetchesPerCall = 20 + cursorPrefix = "v1." +) + +const listQuery = `query ListOpenIssues($owner:String!,$name:String!,$after:String,$first:Int!,$labelsFirst:Int!){ + repository(owner:$owner,name:$name){ + issues(states:OPEN,first:$first,after:$after,orderBy:{field:CREATED_AT,direction:ASC}){ + pageInfo{hasNextPage} + edges{cursor node{number title url createdAt labels(first:$labelsFirst){nodes{name} pageInfo{hasNextPage}}}} + } + } +}` + +type labelConn struct { + Nodes []struct{ Name string } `json:"nodes"` + PageInfo struct { + HasNextPage bool `json:"hasNextPage"` + } `json:"pageInfo"` +} + +type issueNode struct { + Number int `json:"number"` + Title string `json:"title"` + URL string `json:"url"` + CreatedAt time.Time `json:"createdAt"` + Labels labelConn `json:"labels"` +} + +type issueEdge struct { + Cursor string `json:"cursor"` + Node issueNode `json:"node"` +} + +// repoWalk is the position in one repository's open issues, oldest first. +type repoWalk struct { + repo + after string // GitHub's cursor after the last issue consumed; "" = the start + done bool + fetched bool + more bool + buf []issueEdge +} + +// cursorState is what the adapter's opaque cursor carries: a fingerprint of +// the query (the configuration's filters, its repositories and `for`), and +// per configured repository GitHub's own cursor, or null once it is done. +type cursorState struct { + Query string `json:"q"` + Pos []*string `json:"p"` +} + +func (c *Config) fingerprint(forWorker string) string { + b, _ := json.Marshal([]any{c.Repositories, c.ReadyLabel, c.Ready, c.ExcludeLabels, c.Teams, c.TrackedLabel, strings.ToLower(forWorker)}) + sum := sha256.Sum256(b) + return hex.EncodeToString(sum[:8]) +} + +func encodeCursor(s cursorState) string { + b, _ := json.Marshal(s) + return cursorPrefix + base64.RawURLEncoding.EncodeToString(b) +} + +func decodeCursor(raw string, want string, n int) (cursorState, error) { + bad := errors.New("the cursor is not one this adapter issued") + if !strings.HasPrefix(raw, cursorPrefix) { + return cursorState{}, bad + } + b, err := base64.RawURLEncoding.DecodeString(strings.TrimPrefix(raw, cursorPrefix)) + if err != nil { + return cursorState{}, bad + } + var s cursorState + if err := json.Unmarshal(b, &s); err != nil || len(s.Pos) != n { + return cursorState{}, bad + } + if s.Query != want { + return cursorState{}, errors.New("the cursor was issued for another query or before the configuration changed; start the list again") + } + return s, nil +} + +// lister lists untracked issues. +type lister struct { + cfg *Config + gh *githubClient +} + +func (l *lister) fetch(ctx context.Context, w *repoWalk) error { + vars := map[string]any{"owner": w.Owner, "name": w.Name, "first": issuesPerRequest, "labelsFirst": labelsPerIssue} + if w.after != "" { + vars["after"] = w.after + } + var data struct { + Repository *struct { + Issues *struct { + PageInfo struct { + HasNextPage bool `json:"hasNextPage"` + } `json:"pageInfo"` + Edges []issueEdge `json:"edges"` + } `json:"issues"` + } `json:"repository"` + } + if err := l.gh.graphql(ctx, "ListOpenIssues", listQuery, vars, &data); err != nil { + return fmt.Errorf("reading %s/%s: %w", w.Owner, w.Name, err) + } + if data.Repository == nil || data.Repository.Issues == nil { + return fmt.Errorf("reading %s/%s: GitHub returned no issue list", w.Owner, w.Name) + } + iss := data.Repository.Issues + for _, e := range iss.Edges { + if e.Cursor == "" || e.Node.URL == "" || e.Node.Number <= 0 || e.Node.CreatedAt.IsZero() { + return fmt.Errorf("reading %s/%s: GitHub returned an incomplete issue", w.Owner, w.Name) + } + } + w.buf, w.more, w.fetched = iss.Edges, iss.PageInfo.HasNextPage, true + // An empty page that still promises more would never make progress. + if len(w.buf) == 0 && w.more { + return fmt.Errorf("reading %s/%s: GitHub returned an empty page that promises more", w.Owner, w.Name) + } + return nil +} + +// labels returns all of an issue's labels, reading past the first page. +func (l *lister) labels(ctx context.Context, r repo, n issueNode) ([]string, error) { + out := make([]string, 0, len(n.Labels.Nodes)) + if !n.Labels.PageInfo.HasNextPage { + for _, x := range n.Labels.Nodes { + out = append(out, x.Name) + } + return out, nil + } + for page := 1; ; page++ { + if page > maxLabelPages { + return nil, fmt.Errorf("%s/%s#%d carries more than %d labels", r.Owner, r.Name, n.Number, maxLabelPages*100) + } + var got []struct{ Name string } + path := fmt.Sprintf("/repos/%s/%s/issues/%d/labels?per_page=100&page=%d", escapePath(r.Owner), escapePath(r.Name), n.Number, page) + if _, err := l.gh.rest(ctx, http.MethodGet, path, nil, &got, http.StatusOK); err != nil { + return nil, fmt.Errorf("reading the labels of %s/%s#%d: %w", r.Owner, r.Name, n.Number, err) + } + for _, x := range got { + out = append(out, x.Name) + } + if len(got) < 100 { + return out, nil + } + } +} + +// eligible applies the label model to one issue (labels compared without +// regard to case). +func (l *lister) eligible(labels []string, t *Team) bool { + has := map[string]bool{} + for _, x := range labels { + has[strings.ToLower(x)] = true + } + if has[strings.ToLower(l.cfg.TrackedLabel)] { + return false + } + for _, x := range l.cfg.ExcludeLabels { + if has[strings.ToLower(x)] { + return false + } + } + if t != nil { + if t.NoTeam { + for _, other := range l.cfg.Teams { + if !other.NoTeam && has[strings.ToLower(other.Label)] { + return false + } + } + } else if !has[strings.ToLower(t.Label)] { + return false + } + } + ready := l.cfg.ReadyLabel != "" && has[strings.ToLower(l.cfg.ReadyLabel)] + switch l.cfg.Ready { + case "only": + return ready + case "exclude": + return !ready + } + return true +} + +// before is the list's order: oldest first, then repository, then number. +func before(a, b *repoWalk) bool { + x, y := a.buf[0].Node, b.buf[0].Node + if !x.CreatedAt.Equal(y.CreatedAt) { + return x.CreatedAt.Before(y.CreatedAt) + } + if a.Key != b.Key { + return a.Key < b.Key + } + return x.Number < y.Number +} + +type listedItem struct { + ExternalID string `json:"externalId"` + Title string `json:"title"` +} + +// list answers one list-untracked page: up to limit eligible issues in the +// list's order, and the cursor to resume after the last issue consumed (nil +// when every repository is done). +// +// The set of open issues does not shrink when an issue is marked: the mark is +// a label, and filtering happens here, after GitHub's paging. So a cursor +// taken before others marked issues still resumes at the right place. +func (l *lister) list(ctx context.Context, cursor, forWorker string, limit int) ([]listedItem, *string, error) { + team, ok := l.cfg.team(forWorker) + if !ok { + return nil, nil, usageErr("no team in the adapter's configuration is mapped to the worker %q", oneLine(forWorker, 80)) + } + repos := l.cfg.repos() + fp := l.cfg.fingerprint(forWorker) + walks := make([]*repoWalk, len(repos)) + for i, r := range repos { + walks[i] = &repoWalk{repo: r} + } + if cursor != "" { + s, err := decodeCursor(cursor, fp, len(repos)) + if err != nil { + return nil, nil, usageErr("%v", err) + } + for i, p := range s.Pos { + if p == nil { + walks[i].done = true + } else { + walks[i].after = *p + } + } + } + items := []listedItem{} + budget := len(walks) + extraFetchesPerCall + stopped := false + for len(items) < limit { + var head *repoWalk + for _, w := range walks { + if w.done { + continue + } + if len(w.buf) == 0 { + if w.fetched && !w.more { + w.done = true + continue + } + if budget == 0 { + stopped = true + break + } + budget-- + if err := l.fetch(ctx, w); err != nil { + return nil, nil, err + } + if len(w.buf) == 0 { + w.done = true + continue + } + } + if head == nil || before(w, head) { + head = w + } + } + // Out of reads before every repository showed its next issue: the + // order cannot be decided, so answer with what is decided. + if stopped || head == nil { + break + } + e := head.buf[0] + head.buf = head.buf[1:] + head.after = e.Cursor + if len(head.buf) == 0 && !head.more { + head.done = true + } + labels, err := l.labels(ctx, head.repo, e.Node) + if err != nil { + return nil, nil, err + } + if !l.eligible(labels, team) { + continue + } + id, err := l.externalID(head.repo, e.Node) + if err != nil { + return nil, nil, err + } + items = append(items, listedItem{ExternalID: id, Title: boundTitle(e.Node.Title)}) + } + allDone := true + pos := make([]*string, len(walks)) + for i, w := range walks { + if !w.done { + allDone = false + a := w.after + pos[i] = &a + } + } + if allDone { + return items, nil, nil + } + next := encodeCursor(cursorState{Query: fp, Pos: pos}) + return items, &next, nil +} + +// externalID is the issue's canonical URL as GitHub prints it, checked to be +// an issue URL of the repository it was read from and a valid external id. +func (l *lister) externalID(r repo, n issueNode) (string, error) { + ref, err := parseIssueURL(n.URL, l.cfg.WebHost) + if err != nil || ref.Key != r.Key || ref.Number != n.Number { + return "", fmt.Errorf("GitHub returned %q for %s/%s#%d, which is not that issue's URL", oneLine(n.URL, 120), r.Owner, r.Name, n.Number) + } + if err := checkExternalID(n.URL); err != nil { + return "", fmt.Errorf("GitHub returned an issue URL that is not a valid external id: %v", err) + } + return n.URL, nil +} diff --git a/internal/adapter/refs.go b/internal/adapter/refs.go new file mode 100644 index 0000000..8bad79c --- /dev/null +++ b/internal/adapter/refs.go @@ -0,0 +1,130 @@ +package adapter + +import ( + "errors" + "fmt" + "net/url" + "strconv" + "strings" + "unicode" + "unicode/utf8" +) + +// issueRef is an issue named by an external id or a short reference. +type issueRef struct { + Owner, Name string + Key string // lower-cased owner/name + Number int +} + +// parseIssueURL reads https://///issues/, exactly: +// no userinfo, query, fragment, port or trailing path. It is how an external +// id the CLI hands back is read, so it accepts only the shape list-untracked +// produces. +func parseIssueURL(raw, host string) (issueRef, error) { + u, err := url.Parse(raw) + if err != nil { + return issueRef{}, errors.New("not a URL") + } + if u.Scheme != "https" || !strings.EqualFold(u.Host, host) || u.User != nil || u.RawQuery != "" || u.Fragment != "" || u.Opaque != "" { + return issueRef{}, fmt.Errorf("not an issue URL on %s", host) + } + parts := strings.Split(strings.TrimPrefix(u.EscapedPath(), "/"), "/") + if len(parts) != 4 || parts[2] != "issues" || !validSegment(parts[0]) || !validSegment(parts[1]) { + return issueRef{}, fmt.Errorf("not an issue URL (https://%s///issues/)", host) + } + n, err := strconv.Atoi(parts[3]) + if err != nil || n <= 0 || strconv.Itoa(n) != parts[3] { + return issueRef{}, errors.New("the issue number is not a positive number") + } + return issueRef{Owner: parts[0], Name: parts[1], Key: strings.ToLower(parts[0] + "/" + parts[1]), Number: n}, nil +} + +// parseShortRef reads the forms normalize accepts: an issue URL in any case +// and with a trailing slash, "owner/name#N", and "#N" when exactly one +// repository is configured. +func (c *Config) parseShortRef(ref string) (issueRef, error) { + ref = strings.TrimSpace(ref) + if strings.HasPrefix(strings.ToLower(ref), "https://") { + return parseIssueURL(strings.TrimSuffix(ref, "/"), c.WebHost) + } + repoPart, num, ok := strings.Cut(ref, "#") + if !ok { + return issueRef{}, errors.New(`a reference is an issue URL, "owner/name#N" or "#N"`) + } + n, err := strconv.Atoi(num) + if err != nil || n <= 0 { + return issueRef{}, errors.New("the issue number is not a positive number") + } + if repoPart == "" { + if len(c.Repositories) != 1 { + return issueRef{}, errors.New(`"#N" names an issue only when exactly one repository is configured`) + } + repoPart = c.Repositories[0] + } + o, name, ok := strings.Cut(repoPart, "/") + if !ok || !validSegment(o) || !validSegment(name) { + return issueRef{}, errors.New(`a reference is an issue URL, "owner/name#N" or "#N"`) + } + return issueRef{Owner: o, Name: name, Key: strings.ToLower(o + "/" + name), Number: n}, nil +} + +// checkExternalID applies the external id's checks (cor:agt:120:02): 1 to +// 512 characters, no whitespace, control or invisible format characters, no +// userinfo. The server applies them too; checking here refuses a bad id +// before the CLI tries to claim it. +func checkExternalID(id string) error { + if id == "" || utf8.RuneCountInString(id) > 512 { + return errors.New("an external id is 1 to 512 characters") + } + for _, r := range id { + if unicode.IsSpace(r) || unicode.IsControl(r) || unicode.Is(unicode.Cf, r) { + return errors.New("an external id has no whitespace, control or invisible format characters") + } + } + if u, err := url.Parse(id); err == nil && u.User != nil { + return errors.New("an external id carries no userinfo") + } + return nil +} + +// oneLine makes outside text safe for one line of a terminal or a message: +// control and invisible format characters become spaces, runs of spaces +// collapse, and it is cut to max runes. +func oneLine(s string, max int) string { + var b strings.Builder + space := false + n := 0 + for _, r := range s { + if r == utf8.RuneError || unicode.IsControl(r) || unicode.Is(unicode.Cf, r) || unicode.IsSpace(r) { + if !space && b.Len() > 0 { + b.WriteByte(' ') + } + space = true + continue + } + if n == max { + b.WriteString("…") + break + } + b.WriteRune(r) + space = false + n++ + } + return strings.TrimSpace(b.String()) +} + +// boundTitle keeps a title inside the runner's 1024-byte bound, cutting on a +// character boundary. GitHub's own 256-character limit keeps real titles far +// inside it. +func boundTitle(s string) string { + const max = 1000 + if len(s) <= max { + return s + } + cut := max + for cut > 0 && !utf8.RuneStart(s[cut]) { + cut-- + } + return s[:cut] + "…" +} diff --git a/internal/fakegithub/fakegithub.go b/internal/fakegithub/fakegithub.go index 5e4d5f2..41beb7a 100644 --- a/internal/fakegithub/fakegithub.go +++ b/internal/fakegithub/fakegithub.go @@ -45,17 +45,19 @@ type Server struct { mu sync.Mutex // repos is keyed by the lower-cased "owner/name"; canon keeps GitHub's // own spelling, which is what an issue URL carries. - repos map[string][]*Issue - canon map[string]string - fail map[string]int // lower-cased "owner/name" -> HTTP status for any read of it - echo string // when set, error bodies carry this text (to test redaction) - Comments []Comment - Requests []string // "METHOD path" or "GRAPHQL op", in order + repos map[string][]*Issue + canon map[string]string + fail map[string]int // lower-cased "owner/name" -> HTTP status for any read of it + // repoLabels are the labels defined in a repository (not on an issue). + repoLabels map[string][]string + echo string // when set, error bodies carry this text (to test redaction) + Comments []Comment + Requests []string // "METHOD path" or "GRAPHQL op", in order } // New starts a fake GitHub that accepts token. func New(token string) *Server { - s := &Server{Token: token, repos: map[string][]*Issue{}, canon: map[string]string{}, fail: map[string]int{}} + s := &Server{Token: token, repos: map[string][]*Issue{}, canon: map[string]string{}, fail: map[string]int{}, repoLabels: map[string][]string{}} s.Server = httptest.NewServer(http.HandlerFunc(s.serve)) return s } @@ -75,6 +77,14 @@ func (s *Server) AddRepo(full string, issues ...Issue) { } } +// DefineLabel creates a label in a repository's label list. +func (s *Server) DefineLabel(full, label string) { + s.mu.Lock() + defer s.mu.Unlock() + k := strings.ToLower(full) + s.repoLabels[k] = append(s.repoLabels[k], label) +} + // Fail makes every read of a repository answer with status. func (s *Server) Fail(full string, status int) { s.mu.Lock() @@ -108,8 +118,8 @@ func (s *Server) SetLabels(full string, number int, labels ...string) { } } -// URL is the canonical issue URL GitHub would print. -func (s *Server) URL(full string, number int) string { +// IssueURL is the canonical issue URL GitHub would print. +func (s *Server) IssueURL(full string, number int) string { s.mu.Lock() defer s.mu.Unlock() return fmt.Sprintf("https://github.com/%s/issues/%d", s.canon[strings.ToLower(full)], number) @@ -178,6 +188,16 @@ func (s *Server) serve(w http.ResponseWriter, r *http.Request) { writeJSON(w, 200, map[string]any{"full_name": s.canon[k]}) return } + if len(parts) == 5 && parts[3] == "labels" && r.Method == http.MethodGet { + for _, l := range s.repoLabels[k] { + if strings.EqualFold(l, parts[4]) { + writeJSON(w, 200, map[string]string{"name": l}) + return + } + } + s.writeErr(w, 404, "Not Found") + return + } if len(parts) < 6 || parts[3] != "issues" { s.writeErr(w, 404, "Not Found") return From 3a44c9184ada96cc5f687b49e0b3e78bf966daab Mon Sep 17 00:00:00 2001 From: Holger Selover-Stephan Date: Fri, 13 Nov 2026 07:43:17 +0000 Subject: [PATCH 03/10] test: red pins for the LOCAL P2s at 0ddc21ff (hadron-memory/hadron-cli#1963) Joost's LOCAL review (PR #1, comment 6847116727): - a request or configuration with a trailing ] or } is accepted, and a mark is written before anything refuses it; - long opaque GitHub positions at the most repositories emit a cursor past the runner's 4096 bytes; the old maximum test used short fake positions and could not show it (the fake can now pad its cursors); - an issue URL GitHub returns is repeated in the refusal unscrubbed, so a credential echoed in it is printed. Worker: Jonas (cli-engineer) Co-Authored-By: Claude Opus 5.5 --- conformance/conformance_test.go | 71 ++++++++++++++++++++++++++++--- internal/adapter/config_test.go | 4 +- internal/fakegithub/fakegithub.go | 41 +++++++++++++++--- 3 files changed, 104 insertions(+), 12 deletions(-) diff --git a/conformance/conformance_test.go b/conformance/conformance_test.go index 071f316..eba5b3d 100644 --- a/conformance/conformance_test.go +++ b/conformance/conformance_test.go @@ -474,13 +474,15 @@ func TestCursorIsBoundToItsQuery(t *testing.T) { } // The cursor stays inside the runner's bound with the most repositories the -// configuration allows, every one of them part-way through. +// configuration allows, every one of them part-way through, with GitHub +// positions longer than any seen (their length is not promised). func TestCursorFitsTheRunnersBoundAtMaxRepositories(t *testing.T) { repos := []string{} - for i := 0; i < 30; i++ { + for i := 0; i < 20; i++ { repos = append(repos, fmt.Sprintf("a-rather-long-organisation-name/a-rather-long-repository-name-%02d", i)) } e := newEnv(t, map[string]any{"repositories": repos}) + e.gh.PadCursors(129) for i, r := range repos { e.gh.AddRepo(r, fakegithub.Issue{Number: 100000 + i, Title: "t", CreatedAt: day(1).Add(time.Duration(i) * time.Minute)}, @@ -488,15 +490,72 @@ func TestCursorFitsTheRunnersBoundAtMaxRepositories(t *testing.T) { ) } var p Page - e.ok("list-untracked", map[string]any{"limit": 30}, &p) - if p.NextCursor == nil || len(p.Items) != 30 { + e.ok("list-untracked", map[string]any{"limit": 20}, &p) + if p.NextCursor == nil || len(p.Items) != 20 { t.Fatalf("items %d cursor %v", len(p.Items), p.NextCursor) } if err := CheckPage(p); err != nil { t.Fatal(err) } - if got := len(e.walk("", 100, nil)); got != 60 { - t.Fatalf("walk: %d of 60", got) + if got := len(e.walk("", 100, nil)); got != 40 { + t.Fatalf("walk: %d of 40", got) + } +} + +// Positions too long to fit refuse the call: a page is never answered with +// a cursor the runner would refuse. +func TestACursorThatCannotFitIsARefusalNotAnAnswer(t *testing.T) { + repos := []string{} + for i := 0; i < 20; i++ { + repos = append(repos, fmt.Sprintf("acme/r%02d", i)) + } + e := newEnv(t, map[string]any{"repositories": repos}) + e.gh.PadCursors(400) + for i, r := range repos { + e.gh.AddRepo(r, + fakegithub.Issue{Number: 1, Title: "t", CreatedAt: day(1).Add(time.Duration(i) * time.Minute)}, + fakegithub.Issue{Number: 2, Title: "t", CreatedAt: day(20)}, + ) + } + r := e.call("list-untracked", map[string]any{"limit": 20}) + if r.code == 0 { + var p Page + if err := OneObject(r.stdout, &p); err == nil && CheckPage(p) == nil { + return // fitted after all: fine + } + t.Fatalf("answered with a cursor the runner refuses: %d bytes", len(r.stdout)) + } + if len(bytes.TrimSpace(r.stdout)) != 0 { + t.Fatalf("a refusal wrote stdout") + } +} + +// Text GitHub returns is never repeated with the credential in it: not +// only GitHub's error messages, but data the adapter refuses. +func TestARefusedIssueURLDoesNotEchoTheCredential(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 1, Title: "a", CreatedAt: day(1)}) + e.gh.SuffixURLs("?echo=" + token) + r := e.call("list-untracked", map[string]any{"limit": 20}) + if r.code == 0 { + t.Fatalf("a malformed issue URL was listed: %s", r.stdout) + } + e.noToken(r) +} + +// A request with anything after its one object is refused before any write. +func TestTrailingTextAfterTheRequestIsRefusedBeforeAnyWrite(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 4, Title: "x", CreatedAt: day(1)}) + req := `{"contractVersion":1,"externalId":"` + e.gh.IssueURL("acme/app", 4) + `","task":{"id":"t"},"worker":{}}` + for _, suffix := range []string{"]", "}", " x", "{}", "null"} { + r := e.raw([]string{"mark-tracked"}, []byte(req+suffix)) + if r.code == 0 { + t.Fatalf("suffix %q accepted: %s", suffix, r.stdout) + } + if l := e.gh.Labels("acme/app", 4); len(l) != 0 { + t.Fatalf("suffix %q: the mark was written before the refusal: %v", suffix, l) + } } } diff --git a/internal/adapter/config_test.go b/internal/adapter/config_test.go index 6361a8e..f84b85f 100644 --- a/internal/adapter/config_test.go +++ b/internal/adapter/config_test.go @@ -17,6 +17,9 @@ func TestConfigRefusals(t *testing.T) { "duplicate repo": `{"repositories":["acme/app","ACME/App"]}`, "unknown key": `{"repositories":["acme/app"],"readyLable":"x"}`, "two values": `{"repositories":["acme/app"]}{}`, + "trailing bracket": `{"repositories":["acme/app"]}]`, + "trailing brace": `{"repositories":["acme/app"]}}`, + "twenty-one repositories": `{"repositories":[` + manyRepos(21) + `]}`, "ready only without label": `{"repositories":["acme/app"],"ready":"only"}`, "ready unknown": `{"repositories":["acme/app"],"readyLabel":"r","ready":"some"}`, "control in label": "{\"repositories\":[\"acme/app\"],\"readyLabel\":\"a\\u0007b\"}", @@ -31,7 +34,6 @@ func TestConfigRefusals(t *testing.T) { "plain http to remote": `{"repositories":["acme/app"],"apiUrl":"http://api.example.com"}`, "userinfo in api url": `{"repositories":["acme/app"],"apiUrl":"https://u:p@api.example.com"}`, "web host with scheme": `{"repositories":["acme/app"],"webHost":"https://github.com"}`, - "thirty-one repositories": `{"repositories":[` + manyRepos(31) + `]}`, "graphql url to plain http": `{"repositories":["acme/app"],"graphqlUrl":"http://example.com/graphql"}`, } for name, raw := range cases { diff --git a/internal/fakegithub/fakegithub.go b/internal/fakegithub/fakegithub.go index 41beb7a..6f89e5f 100644 --- a/internal/fakegithub/fakegithub.go +++ b/internal/fakegithub/fakegithub.go @@ -51,8 +51,13 @@ type Server struct { // repoLabels are the labels defined in a repository (not on an issue). repoLabels map[string][]string echo string // when set, error bodies carry this text (to test redaction) - Comments []Comment - Requests []string // "METHOD path" or "GRAPHQL op", in order + // cursorPad lengthens every issue cursor to at least this many bytes + // (GitHub's cursors are opaque and their length is not promised). + cursorPad int + // urlSuffix is appended to every issue URL in a list (a misbehaving proxy). + urlSuffix string + Comments []Comment + Requests []string // "METHOD path" or "GRAPHQL op", in order } // New starts a fake GitHub that accepts token. @@ -99,6 +104,20 @@ func (s *Server) EchoInErrors(text string) { s.echo = text } +// PadCursors makes every issue cursor at least n bytes long. +func (s *Server) PadCursors(n int) { + s.mu.Lock() + defer s.mu.Unlock() + s.cursorPad = n +} + +// SuffixURLs appends text to every issue URL a list returns. +func (s *Server) SuffixURLs(text string) { + s.mu.Lock() + defer s.mu.Unlock() + s.urlSuffix = text +} + // Labels returns an issue's current labels. func (s *Server) Labels(full string, number int) []string { s.mu.Lock() @@ -287,6 +306,17 @@ func labelObjs(ls []string) []map[string]string { return out } +func (s *Server) cursor(number int) string { + raw := "cursor:v2:" + strconv.Itoa(number) + if s.cursorPad > 0 { + raw += "|" + for len(base64.StdEncoding.EncodeToString([]byte(raw))) < s.cursorPad { + raw += "x" + } + } + return base64.StdEncoding.EncodeToString([]byte(raw)) +} + type gqlReq struct { Query string `json:"query"` OperationName string `json:"operationName"` @@ -351,7 +381,8 @@ func (s *Server) graphql(w http.ResponseWriter, r *http.Request) { start := 0 if after := str(q.Variables["after"]); after != "" { raw, err := base64.StdEncoding.DecodeString(after) - n, err2 := strconv.Atoi(strings.TrimPrefix(string(raw), "cursor:v2:")) + pos, _, _ := strings.Cut(strings.TrimPrefix(string(raw), "cursor:v2:"), "|") + n, err2 := strconv.Atoi(pos) if err != nil || err2 != nil { writeJSON(w, 200, map[string]any{"errors": []map[string]string{{"message": "`" + after + "` does not appear to be a valid cursor."}}}) return @@ -372,10 +403,10 @@ func (s *Server) graphql(w http.ResponseWriter, r *http.Request) { for i := start; i < len(open) && len(edges) < first; i++ { is := open[i] edges = append(edges, map[string]any{ - "cursor": base64.StdEncoding.EncodeToString([]byte("cursor:v2:" + strconv.Itoa(is.Number))), + "cursor": s.cursor(is.Number), "node": map[string]any{ "number": is.Number, "title": is.Title, - "url": fmt.Sprintf("https://github.com/%s/issues/%d", full, is.Number), + "url": fmt.Sprintf("https://github.com/%s/issues/%d", full, is.Number) + s.urlSuffix, "createdAt": is.CreatedAt.UTC().Format(time.RFC3339), "labels": labelConn(is.Labels, labelsFirst), }, From b22f1eb8b15ef7d5d58e85726e309ad92daf790a Mon Sep 17 00:00:00 2001 From: Holger Selover-Stephan Date: Fri, 13 Nov 2026 07:44:18 +0000 Subject: [PATCH 04/10] fix: request/config EOF discipline, a cursor that always fits, every refusal scrubbed (hadron-memory/hadron-cli#1963) Folds Joost's three LOCAL P2s at 0ddc21ff: - the request and the configuration must end at their one JSON object: Decoder.More reports false before a stray "]" or "}", so only io.EOF from the next Token proves nothing follows; refused before any write; - the repository cap drops from 30 to 20, which fits GitHub positions up to about 140 bytes each in the runner's 4096-byte cursor; a call whose cursor would still not fit is refused, never answered with it; - Run scrubs the credential from every refusal message, whatever its source (GitHub's error text was already scrubbed; data GitHub returned and the adapter refused was not). The client-level scrub stays as a second layer. Worker: Jonas (cli-engineer) Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- docs/design.md | 7 +++++-- internal/adapter/adapter.go | 21 ++++++++++++++++----- internal/adapter/config.go | 9 ++++++--- internal/adapter/list.go | 7 +++++++ 5 files changed, 35 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index dcdeb8a..079b3e9 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ key. | Key | Meaning | |---|---| -| `repositories` | `"owner/name"`, 1 to 30. Their **open issues** are the intake (pull requests are not). | +| `repositories` | `"owner/name"`, 1 to 20. Their **open issues** are the intake (pull requests are not). | | `readyLabel` | The label that marks an issue ready for intake. | | `ready` | `only` (list only ready issues; the default when `readyLabel` is set), `exclude`, or `any` (the default without one). | | `excludeLabels` | An issue carrying any of these is never listed. | diff --git a/docs/design.md b/docs/design.md index 6379f72..d14b7f2 100644 --- a/docs/design.md +++ b/docs/design.md @@ -53,8 +53,11 @@ done), so nothing is re-read or skipped. **The cursor carries its query.** It embeds a fingerprint of the configuration's filters, its repositories and `for`. A cursor resumed under a different query is refused (exit 2), not silently resumed at a position that -means something else. With 30 repositories, the configuration's cap, the -cursor stays inside the runner's 4096-byte bound (pinned). +means something else. With 20 repositories, the configuration's cap, and GitHub +positions up to about 140 bytes each (real ones are about 60), the cursor +stays inside the runner's 4096-byte bound (pinned with padded positions). A +call whose cursor would not fit is refused, never answered with a cursor the +runner would refuse. **Bounded work per call.** A call reads at most one GitHub page per repository plus 20 more, then answers with the eligible issues it has and a cursor. A long diff --git a/internal/adapter/adapter.go b/internal/adapter/adapter.go index 3a9ac37..2f0d540 100644 --- a/internal/adapter/adapter.go +++ b/internal/adapter/adapter.go @@ -16,6 +16,7 @@ import ( "errors" "fmt" "io" + "strings" "time" ) @@ -69,7 +70,8 @@ type Env struct { func Run(ctx context.Context, e Env) int { ctx, cancel := context.WithTimeout(ctx, callTimeout) defer cancel() - out, err := run(ctx, e) + var token string + out, err := run(ctx, e, &token) if err == nil { b, merr := json.Marshal(out) if merr == nil { @@ -85,11 +87,17 @@ func Run(ctx context.Context, e Env) int { if errors.As(err, &ee) { code = ee.code } - fmt.Fprintf(e.Stderr, "%s: %s\n", Name, oneLine(err.Error(), 600)) + // Every refusal is scrubbed of the credential, whatever its source: + // GitHub's error text, or data GitHub returned that the adapter refuses. + msg := err.Error() + if token != "" { + msg = strings.ReplaceAll(msg, token, "[redacted]") + } + fmt.Fprintf(e.Stderr, "%s: %s\n", Name, oneLine(msg, 600)) return code } -func run(ctx context.Context, e Env) (any, error) { +func run(ctx context.Context, e Env, tokenOut *string) (any, error) { if len(e.Args) != 1 { return nil, usageErr("expected exactly one argument, the call (one of %v)", Calls) } @@ -132,6 +140,7 @@ func run(ctx context.Context, e Env) (any, error) { if err != nil { return nil, configErr("%v", err) } + *tokenOut = token s := &session{cfg: cfg, gh: newGitHub(cfg, token)} switch call { case "list-untracked": @@ -166,8 +175,10 @@ func readRequest(r io.Reader) (json.RawMessage, error) { if err := dec.Decode(&raw); err != nil { return nil, usageErr("the request is not one well-formed JSON object") } - if dec.More() { - return nil, usageErr("the request carries more than one JSON value") + // More is not an end-of-input check: it reports false before a stray + // "]" or "}". Only io.EOF after the object proves nothing follows. + if _, err := dec.Token(); err != io.EOF { + return nil, usageErr("the request carries text after its JSON object") } return raw, nil } diff --git a/internal/adapter/config.go b/internal/adapter/config.go index 33dbbb4..1daaf27 100644 --- a/internal/adapter/config.go +++ b/internal/adapter/config.go @@ -22,7 +22,10 @@ const ConfigEnv = "TASK_ADAPTER_GITHUB_CONFIG" // Limits on the configuration. const ( - MaxRepositories = 30 // keeps the cursor inside the runner's 4096-byte bound + // MaxRepositories keeps the cursor inside the runner's 4096-byte bound + // with GitHub positions up to about 140 bytes each (real ones are about + // 60). A longer position refuses the call instead (list.go). + MaxRepositories = 20 MaxLabelLen = 100 MaxExcludeLabels = 50 MaxTeams = 50 @@ -140,8 +143,8 @@ func ParseConfig(b []byte) (*Config, error) { if err := dec.Decode(&c); err != nil { return nil, fmt.Errorf("configuration: %v", err) } - if dec.More() { - return nil, errors.New("configuration: more than one JSON value") + if _, err := dec.Token(); err != io.EOF { + return nil, errors.New("configuration: text after the JSON object") } if err := c.validate(); err != nil { return nil, fmt.Errorf("configuration: %v", err) diff --git a/internal/adapter/list.go b/internal/adapter/list.go index 0b42003..5213748 100644 --- a/internal/adapter/list.go +++ b/internal/adapter/list.go @@ -22,6 +22,8 @@ const ( // happens here, so a run of ineligible issues costs reads, not items. extraFetchesPerCall = 20 cursorPrefix = "v1." + // MaxCursorLen is the hadron CLI runner's bound on nextCursor. + MaxCursorLen = 4096 ) const listQuery = `query ListOpenIssues($owner:String!,$name:String!,$after:String,$first:Int!,$labelsFirst:Int!){ @@ -321,6 +323,11 @@ func (l *lister) list(ctx context.Context, cursor, forWorker string, limit int) return items, nil, nil } next := encodeCursor(cursorState{Query: fp, Pos: pos}) + // The runner refuses a cursor past its bound; GitHub does not promise + // how long its positions are. Never answer with one that cannot be used. + if len(next) > MaxCursorLen { + return nil, nil, fmt.Errorf("the cursor would be %d bytes, more than the %d the hadron CLI accepts (GitHub's positions are unusually long); configure fewer repositories", len(next), MaxCursorLen) + } return items, &next, nil } From 362c9bf48e18acf9bedb4ca66fa113bd3cd873d4 Mon Sep 17 00:00:00 2001 From: Holger Selover-Stephan Date: Fri, 13 Nov 2026 07:47:04 +0000 Subject: [PATCH 05/10] =?UTF-8?q?test:=20red=20pin=20=E2=80=94=20a=20comme?= =?UTF-8?q?nt=20failure=20after=20the=20label=20reads=20as=20a=20refused?= =?UTF-8?q?=20mark=20(hadron-memory/hadron-cli#1963)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Gloria's BLIND P2 at 0ddc21ff. Worker: Jonas (cli-engineer) Co-Authored-By: Claude Opus 5.5 --- conformance/conformance_test.go | 22 ++++++++++++++++++++++ internal/fakegithub/fakegithub.go | 18 ++++++++++++++++-- 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/conformance/conformance_test.go b/conformance/conformance_test.go index eba5b3d..94717d6 100644 --- a/conformance/conformance_test.go +++ b/conformance/conformance_test.go @@ -304,6 +304,28 @@ func TestMarkCommentIsOptInAndCarriesTheServersURL(t *testing.T) { } } +// The label is the mark; the comment is decoration. A comment that fails +// after the label landed must not turn the call into a refusal: the runner +// would read the issue as unmarked while it no longer lists. +func TestMarkCommentFailureAfterTheLabelStillAnswersMarked(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}, "comment": true}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 4, Title: "x", CreatedAt: day(1)}) + e.gh.FailComments(403) + e.gh.EchoInErrors(token) + var ans map[string]any + e.ok("mark-tracked", map[string]any{"externalId": e.gh.IssueURL("acme/app", 4), + "task": map[string]any{"id": "01abc"}, "worker": map[string]any{"name": "W"}}, &ans) + if ans["marked"] != true || ans["commented"] != false { + t.Fatalf("answer after a failed comment: %v", ans) + } + if msg, _ := ans["commentError"].(string); msg == "" || strings.Contains(msg, token) { + t.Fatalf("commentError missing or unscrubbed: %v", ans) + } + if l := e.gh.Labels("acme/app", 4); strings.Join(l, ",") != "hadron-tracked" { + t.Fatalf("labels after mark: %v", l) + } +} + func TestGetAndNormalize(t *testing.T) { e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) e.gh.AddRepo("Acme/App", fakegithub.Issue{Number: 12, Title: "the title", Body: "the body", CreatedAt: day(1), Labels: []string{"hadron-tracked"}}) diff --git a/internal/fakegithub/fakegithub.go b/internal/fakegithub/fakegithub.go index 6f89e5f..a2ce945 100644 --- a/internal/fakegithub/fakegithub.go +++ b/internal/fakegithub/fakegithub.go @@ -56,8 +56,11 @@ type Server struct { cursorPad int // urlSuffix is appended to every issue URL in a list (a misbehaving proxy). urlSuffix string - Comments []Comment - Requests []string // "METHOD path" or "GRAPHQL op", in order + // commentFail, when set, answers every comment POST with this status + // (the label POST before it still succeeds). + commentFail int + Comments []Comment + Requests []string // "METHOD path" or "GRAPHQL op", in order } // New starts a fake GitHub that accepts token. @@ -97,6 +100,13 @@ func (s *Server) Fail(full string, status int) { s.fail[strings.ToLower(full)] = status } +// FailComments makes every comment POST answer with status. +func (s *Server) FailComments(status int) { + s.mu.Lock() + defer s.mu.Unlock() + s.commentFail = status +} + // EchoInErrors makes error bodies include text, as a misbehaving proxy might. func (s *Server) EchoInErrors(text string) { s.mu.Lock() @@ -274,6 +284,10 @@ func (s *Server) serve(w http.ResponseWriter, r *http.Request) { is.Labels = kept writeJSON(w, 200, labelObjs(is.Labels)) case parts[5] == "comments" && len(parts) == 6 && r.Method == http.MethodPost: + if s.commentFail != 0 { + s.writeErr(w, s.commentFail, "comment refused") + return + } var body struct { Body string `json:"body"` } From c6b55d29f79ff2479b55119d93a84a9f5f29bf6a Mon Sep 17 00:00:00 2001 From: Holger Selover-Stephan Date: Fri, 13 Nov 2026 07:48:01 +0000 Subject: [PATCH 06/10] fix: a comment failure after the label answers marked, commented:false (hadron-memory/hadron-cli#1963) The label is the mark. Refusing after it landed told the runner the mark failed while the issue was marked and no longer listed. The answer now carries commented:false and a scrubbed commentError. Worker: Jonas (cli-engineer) Co-Authored-By: Claude Opus 5.5 --- README.md | 5 ++++- docs/design.md | 5 ++++- internal/adapter/calls.go | 23 ++++++++++++++--------- 3 files changed, 22 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 079b3e9..c4eb46f 100644 --- a/README.md +++ b/README.md @@ -112,7 +112,10 @@ The optional calls `report` and `changed-since` are not answered yet. claimed still resumes at the right place and skips nothing. - **The mark** is the `trackedLabel`, and optionally a comment. It never makes or decides a claim: the claim is the CLI's task create. A second mark of the - same issue (after a reassignment) is an ordinary call, never a refusal. + same issue (after a reassignment) is an ordinary call, never a refusal. Once + the label is on, the call succeeds: a comment that then fails is answered as + `"commented": false` with a `commentError`, not as a refusal, since the issue + is marked and no longer lists. - **Never partial.** A GitHub error, a rate limit, or an answer the adapter does not understand refuses the whole call; a list is never cut short and presented as whole. Labels past GitHub's first page of 100 are read too, diff --git a/docs/design.md b/docs/design.md index d14b7f2..cb9e5f3 100644 --- a/docs/design.md +++ b/docs/design.md @@ -32,7 +32,10 @@ filters on. A comment naming the task and worker is opt-in (`comment: true`) because on a public repository it publishes the team's worker names and links. Hadron text in a comment is quoted as inline code on one line, so a name cannot mention, link or reflow. The portal URL is linked only as the server printed -it, and only a plain https URL. +it, and only a plain https URL. Because the label alone is the mark, a comment +that fails after the label landed does not refuse the call: the answer says +`"commented": false` and carries the scrubbed `commentError`. Refusing would +tell the runner the mark failed while the issue is marked and no longer lists. **Filtering happens in the adapter, after GitHub's paging.** The GitHub list is all open issues in creation order. The tracked label, the excluded labels, diff --git a/internal/adapter/calls.go b/internal/adapter/calls.go index 06d1885..b598775 100644 --- a/internal/adapter/calls.go +++ b/internal/adapter/calls.go @@ -47,9 +47,10 @@ type markRequest struct { // markTracked puts the tracked label on the issue, and when the // configuration asks for it, a comment naming the task and the worker. It -// never refuses because the issue is already marked: the mark shows a claim, -// it never makes or decides one (cor:agt:120, D14). A re-mark after a -// reassignment is an ordinary call. +// never refuses once the label is on: a failed comment is reported as +// commented:false with a commentError. It never refuses because the issue +// is already marked: the mark shows a claim, it never makes or decides one +// (cor:agt:120, D14). A re-mark after a reassignment is an ordinary call. func (s *session) markTracked(ctx context.Context, req json.RawMessage) (any, error) { var r markRequest if err := decode(req, "mark-tracked", &r); err != nil { @@ -66,16 +67,20 @@ func (s *session) markTracked(ctx context.Context, req json.RawMessage) (any, er if _, err := s.gh.rest(ctx, http.MethodPost, issuePath(ref, "/labels"), body, nil, http.StatusOK); err != nil { return nil, fmt.Errorf("labelling %s/%s#%d: %w", ref.Owner, ref.Name, ref.Number, err) } - commented := false + ans := map[string]any{"marked": true, "externalId": r.ExternalID, "label": s.cfg.TrackedLabel, "commented": false} if s.cfg.Comment { if _, err := s.gh.rest(ctx, http.MethodPost, issuePath(ref, "/comments"), map[string]string{"body": markComment(r)}, nil, http.StatusCreated); err != nil { - // The label is on: the item shows as tracked. Say the comment - // failed rather than pretend the whole mark did. - return nil, fmt.Errorf("%s/%s#%d is labelled %q, but the comment failed: %w", ref.Owner, ref.Name, ref.Number, s.cfg.TrackedLabel, err) + // The label is the mark, and it is on: the issue no longer + // lists. Refusing now would tell the runner the mark failed + // while the issue is in fact marked, stranding it outside + // intake. The comment is decoration, so its failure is + // reported in a successful answer, scrubbed like a refusal. + ans["commentError"] = s.gh.scrub(err.Error()) + return ans, nil } - commented = true + ans["commented"] = true } - return map[string]any{"marked": true, "externalId": r.ExternalID, "label": s.cfg.TrackedLabel, "commented": commented}, nil + return ans, nil } // code quotes text from Hadron as inline code on one line, so a name cannot From bebb7928457db4fb1501ba661c16eef5d8f609ce Mon Sep 17 00:00:00 2001 From: Holger Selover-Stephan Date: Fri, 13 Nov 2026 07:59:50 +0000 Subject: [PATCH 07/10] =?UTF-8?q?test:=20red=20pin=20=E2=80=94=20a=20refus?= =?UTF-8?q?al=20cut=20short=20before=20the=20scrub=20prints=20a=20fragment?= =?UTF-8?q?=20of=20the=20credential=20(hadron-memory/hadron-cli#1963)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit LOCAL delta finding at c6b55d29. Worker: Jonas (cli-engineer) Co-Authored-By: Claude Opus 5.5 --- conformance/conformance_test.go | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/conformance/conformance_test.go b/conformance/conformance_test.go index 94717d6..e10fc95 100644 --- a/conformance/conformance_test.go +++ b/conformance/conformance_test.go @@ -114,8 +114,11 @@ func (e *env) ok(name string, req map[string]any, out any) { func (e *env) noToken(r result) { e.t.Helper() - if bytes.Contains(r.stdout, []byte(token)) || bytes.Contains(r.stderr, []byte(token)) { - e.t.Fatalf("the GitHub credential was printed:\nstdout %s\nstderr %s", r.stdout, r.stderr) + // A fragment counts: a message cut short before it was scrubbed would + // print the credential's first characters (LOCAL delta at c6b55d29). + frag := []byte(token[:12]) + if bytes.Contains(r.stdout, frag) || bytes.Contains(r.stderr, frag) { + e.t.Fatalf("the GitHub credential (or a fragment of it) was printed:\nstdout %s\nstderr %s", r.stdout, r.stderr) } } @@ -565,6 +568,28 @@ func TestARefusedIssueURLDoesNotEchoTheCredential(t *testing.T) { e.noToken(r) } +// Untrusted text is cut to a bounded length in a refusal. The credential is +// scrubbed before the cut, so a cut that lands inside it leaks no prefix. +func TestACredentialCutShortInARefusalLeaksNoFragment(t *testing.T) { + for pad := 40; pad <= 120; pad += 4 { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 1, Title: "a", CreatedAt: day(1)}) + e.gh.SuffixURLs("?pad=" + strings.Repeat("x", pad) + "&echo=" + token) + r := e.call("list-untracked", map[string]any{"limit": 20}) + if r.code == 0 { + t.Fatalf("pad %d: a malformed issue URL was listed: %s", pad, r.stdout) + } + e.noToken(r) + // The same for an id the runner hands back. + bad := "https://github.com/acme/app/pull/1?pad=" + strings.Repeat("x", pad) + "&echo=" + token + r = e.call("get", map[string]any{"externalId": bad}) + if r.code == 0 { + t.Fatalf("pad %d: a pull URL was read as an issue: %s", pad, r.stdout) + } + e.noToken(r) + } +} + // A request with anything after its one object is refused before any write. func TestTrailingTextAfterTheRequestIsRefusedBeforeAnyWrite(t *testing.T) { e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) From 7ea5d7475be5dbad3229d1986a0ae007eca90ba9 Mon Sep 17 00:00:00 2001 From: Holger Selover-Stephan Date: Fri, 13 Nov 2026 08:00:50 +0000 Subject: [PATCH 08/10] fix: scrub the credential before cutting untrusted text short (hadron-memory/hadron-cli#1963) oneLine cut a refused issue URL (or a handed-back id) to 120 runes before Run scrubbed the full token, so a cut inside the token printed its prefix. githubClient.clip scrubs first, then cuts; every quote of upstream or request text in a refusal or a check detail goes through it. Worker: Jonas (cli-engineer) Co-Authored-By: Claude Opus 5.5 --- internal/adapter/calls.go | 10 +++++----- internal/adapter/github.go | 9 ++++++++- internal/adapter/list.go | 4 ++-- 3 files changed, 15 insertions(+), 8 deletions(-) diff --git a/internal/adapter/calls.go b/internal/adapter/calls.go index b598775..76e3bd2 100644 --- a/internal/adapter/calls.go +++ b/internal/adapter/calls.go @@ -18,7 +18,7 @@ func (s *session) configuredIssue(call, externalID string) (issueRef, error) { } ref, err := parseIssueURL(externalID, s.cfg.WebHost) if err != nil { - return issueRef{}, usageErr("%s: %q: %v", call, oneLine(externalID, 120), err) + return issueRef{}, usageErr("%s: %q: %v", call, s.gh.clip(externalID, 120), err) } if !s.cfg.hasRepo(ref.Owner, ref.Name) { return issueRef{}, usageErr("%s: %s/%s is not a repository in the adapter's configuration", call, ref.Owner, ref.Name) @@ -223,7 +223,7 @@ func (s *session) normalize(ctx context.Context, req json.RawMessage) (any, erro } ref, err := s.cfg.parseShortRef(r.Ref) if err != nil { - return nil, usageErr("normalize: %q: %v", oneLine(r.Ref, 120), err) + return nil, usageErr("normalize: %q: %v", s.gh.clip(r.Ref, 120), err) } if !s.cfg.hasRepo(ref.Owner, ref.Name) { return nil, usageErr("normalize: %s/%s is not a repository in the adapter's configuration", ref.Owner, ref.Name) @@ -270,20 +270,20 @@ func check(ctx context.Context, getenv func(string) string) any { } gh := newGitHub(cfg, token) if _, err := gh.rest(ctx, http.MethodGet, "/rate_limit", nil, nil, http.StatusOK); err != nil { - results = append(results, checkResult{Name: "credential", OK: false, Detail: oneLine(err.Error(), 300)}) + results = append(results, checkResult{Name: "credential", OK: false, Detail: gh.clip(err.Error(), 300)}) return answer() } results = append(results, checkResult{Name: "credential", OK: true}) for _, r := range cfg.repos() { name := "repository " + r.Owner + "/" + r.Name if _, err := gh.rest(ctx, http.MethodGet, "/repos/"+escapePath(r.Owner)+"/"+escapePath(r.Name), nil, nil, http.StatusOK); err != nil { - results = append(results, checkResult{Name: name, OK: false, Detail: oneLine(err.Error(), 300)}) + results = append(results, checkResult{Name: name, OK: false, Detail: gh.clip(err.Error(), 300)}) continue } results = append(results, checkResult{Name: name, OK: true}) lname := "label " + cfg.TrackedLabel + " in " + r.Owner + "/" + r.Name if _, err := gh.rest(ctx, http.MethodGet, "/repos/"+escapePath(r.Owner)+"/"+escapePath(r.Name)+"/labels/"+escapePath(cfg.TrackedLabel), nil, nil, http.StatusOK); err != nil { - results = append(results, checkResult{Name: lname, OK: false, Detail: "create it first (gh label create " + cfg.TrackedLabel + " -R " + r.Owner + "/" + r.Name + "): " + oneLine(err.Error(), 200)}) + results = append(results, checkResult{Name: lname, OK: false, Detail: "create it first (gh label create " + cfg.TrackedLabel + " -R " + r.Owner + "/" + r.Name + "): " + gh.clip(err.Error(), 200)}) continue } results = append(results, checkResult{Name: lname, OK: true}) diff --git a/internal/adapter/github.go b/internal/adapter/github.go index d01c744..2ce5a89 100644 --- a/internal/adapter/github.go +++ b/internal/adapter/github.go @@ -46,10 +46,17 @@ func (e *apiError) Error() string { } func (g *githubClient) scrub(s string) string { + return g.clip(s, 200) +} + +// clip quotes untrusted text on one line, cut to max runes, with the +// credential scrubbed FIRST: a cut that lands inside the credential would +// otherwise leave a prefix that no later scrub can recognise. +func (g *githubClient) clip(s string, max int) string { if g.token != "" { s = strings.ReplaceAll(s, g.token, "[redacted]") } - return oneLine(s, 200) + return oneLine(s, max) } func (g *githubClient) do(ctx context.Context, method, endpoint string, body any) (int, []byte, error) { diff --git a/internal/adapter/list.go b/internal/adapter/list.go index 5213748..8b86da6 100644 --- a/internal/adapter/list.go +++ b/internal/adapter/list.go @@ -234,7 +234,7 @@ type listedItem struct { func (l *lister) list(ctx context.Context, cursor, forWorker string, limit int) ([]listedItem, *string, error) { team, ok := l.cfg.team(forWorker) if !ok { - return nil, nil, usageErr("no team in the adapter's configuration is mapped to the worker %q", oneLine(forWorker, 80)) + return nil, nil, usageErr("no team in the adapter's configuration is mapped to the worker %q", l.gh.clip(forWorker, 80)) } repos := l.cfg.repos() fp := l.cfg.fingerprint(forWorker) @@ -336,7 +336,7 @@ func (l *lister) list(ctx context.Context, cursor, forWorker string, limit int) func (l *lister) externalID(r repo, n issueNode) (string, error) { ref, err := parseIssueURL(n.URL, l.cfg.WebHost) if err != nil || ref.Key != r.Key || ref.Number != n.Number { - return "", fmt.Errorf("GitHub returned %q for %s/%s#%d, which is not that issue's URL", oneLine(n.URL, 120), r.Owner, r.Name, n.Number) + return "", fmt.Errorf("GitHub returned %q for %s/%s#%d, which is not that issue's URL", l.gh.clip(n.URL, 120), r.Owner, r.Name, n.Number) } if err := checkExternalID(n.URL); err != nil { return "", fmt.Errorf("GitHub returned an issue URL that is not a valid external id: %v", err) From 1d8c659383cc7463a8e434949106fb85f7cc8870 Mon Sep 17 00:00:00 2001 From: Holger Selover-Stephan Date: Fri, 13 Nov 2026 08:04:15 +0000 Subject: [PATCH 09/10] =?UTF-8?q?test:=20red=20pin=20=E2=80=94=20a=20crede?= =?UTF-8?q?ntial=20prefix=20that=20arrives=20already=20cut=20survives=20th?= =?UTF-8?q?e=20scrub=20(hadron-memory/hadron-cli#1963)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ada's ruling on the LOCAL delta F3: redact any prefix of the token, and pin no fragment at any cut length (the conformance probe now walks every offset). Worker: Jonas (cli-engineer) Co-Authored-By: Claude Opus 5.5 --- conformance/conformance_test.go | 8 +++++--- internal/adapter/config_test.go | 29 +++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+), 3 deletions(-) diff --git a/conformance/conformance_test.go b/conformance/conformance_test.go index e10fc95..94b1f39 100644 --- a/conformance/conformance_test.go +++ b/conformance/conformance_test.go @@ -115,8 +115,9 @@ func (e *env) ok(name string, req map[string]any, out any) { func (e *env) noToken(r result) { e.t.Helper() // A fragment counts: a message cut short before it was scrubbed would - // print the credential's first characters (LOCAL delta at c6b55d29). - frag := []byte(token[:12]) + // print the credential's first characters (LOCAL delta at c6b55d29). Eight + // runes is the fragment the adapter redacts anywhere. + frag := []byte(token[:8]) if bytes.Contains(r.stdout, frag) || bytes.Contains(r.stderr, frag) { e.t.Fatalf("the GitHub credential (or a fragment of it) was printed:\nstdout %s\nstderr %s", r.stdout, r.stderr) } @@ -571,7 +572,8 @@ func TestARefusedIssueURLDoesNotEchoTheCredential(t *testing.T) { // Untrusted text is cut to a bounded length in a refusal. The credential is // scrubbed before the cut, so a cut that lands inside it leaks no prefix. func TestACredentialCutShortInARefusalLeaksNoFragment(t *testing.T) { - for pad := 40; pad <= 120; pad += 4 { + // Every pad from 0 to 130 puts the cut at every offset inside the token. + for pad := 0; pad <= 130; pad++ { e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 1, Title: "a", CreatedAt: day(1)}) e.gh.SuffixURLs("?pad=" + strings.Repeat("x", pad) + "&echo=" + token) diff --git a/internal/adapter/config_test.go b/internal/adapter/config_test.go index f84b85f..1a36852 100644 --- a/internal/adapter/config_test.go +++ b/internal/adapter/config_test.go @@ -164,3 +164,32 @@ func TestExampleConfigParses(t *testing.T) { t.Fatalf("config.example.json: %v", err) } } + +// A fragment of the credential is redacted wherever a cut can leave one: +// text that arrives already truncated (a proxy echoing a cut token), and a +// cut of ours that lands inside it (Ada's ruling on the LOCAL delta F3). +func TestClipRedactsAnyFragmentOfTheCredential(t *testing.T) { + const tok = "ghp_FAKEunitTOKEN000000000000000000000000" + g := &githubClient{token: tok} + // Text that arrives already cut: any prefix right before the ellipsis, + // and any prefix of 8 runes or more anywhere. + for k := 1; k < len(tok); k++ { + for _, tail := range []string{"…", " and more"} { + in := "bad URL https://github.com/a/b/issues/1?echo=" + tok[:k] + tail + got := g.clip(in, 200) + if strings.Contains(got, tok[:k]+"…") || (k >= 8 && strings.Contains(got, tok[:k])) { + t.Fatalf("prefix %d (tail %q) survived: %q", k, tail, got) + } + } + } + // A cut of ours, at every length. + for max := 1; max < 120; max++ { + got := g.clip(strings.Repeat("x", 40)+tok+" tail", max) + if strings.Contains(got, tok[:8]) || strings.Contains(got, "g…") { + t.Fatalf("cut at %d leaked: %q", max, got) + } + } + if got := g.clip("plain text, no credential", 200); got != "plain text, no credential" { + t.Fatalf("clean text changed: %q", got) + } +} From 5a61ed8076fb5f30547369cfc30d50c2c17aa2fa Mon Sep 17 00:00:00 2001 From: Holger Selover-Stephan Date: Fri, 13 Nov 2026 08:07:02 +0000 Subject: [PATCH 10/10] fix: redact any fragment of the credential, before the cut (hadron-memory/hadron-cli#1963) redact replaces the whole token, any prefix of 8 runes or more, and any prefix right before a cut's ellipsis (text can arrive already cut). clip and Run redact the raw text first and cut after. Worker: Jonas (cli-engineer) Co-Authored-By: Claude Opus 5.5 --- internal/adapter/adapter.go | 7 +------ internal/adapter/config_test.go | 4 ++++ internal/adapter/github.go | 27 ++++++++++++++++++++++++--- 3 files changed, 29 insertions(+), 9 deletions(-) diff --git a/internal/adapter/adapter.go b/internal/adapter/adapter.go index 2f0d540..aa7fa5c 100644 --- a/internal/adapter/adapter.go +++ b/internal/adapter/adapter.go @@ -16,7 +16,6 @@ import ( "errors" "fmt" "io" - "strings" "time" ) @@ -89,11 +88,7 @@ func Run(ctx context.Context, e Env) int { } // Every refusal is scrubbed of the credential, whatever its source: // GitHub's error text, or data GitHub returned that the adapter refuses. - msg := err.Error() - if token != "" { - msg = strings.ReplaceAll(msg, token, "[redacted]") - } - fmt.Fprintf(e.Stderr, "%s: %s\n", Name, oneLine(msg, 600)) + fmt.Fprintf(e.Stderr, "%s: %s\n", Name, oneLine(redact(err.Error(), token), 600)) return code } diff --git a/internal/adapter/config_test.go b/internal/adapter/config_test.go index 1a36852..781632f 100644 --- a/internal/adapter/config_test.go +++ b/internal/adapter/config_test.go @@ -189,6 +189,10 @@ func TestClipRedactsAnyFragmentOfTheCredential(t *testing.T) { t.Fatalf("cut at %d leaked: %q", max, got) } } + // The whole credential is replaced exactly, leaving none of it behind. + if got := g.clip("a "+tok+" b", 200); got != "a [redacted] b" { + t.Fatalf("whole credential: %q", got) + } if got := g.clip("plain text, no credential", 200); got != "plain text, no credential" { t.Fatalf("clean text changed: %q", got) } diff --git a/internal/adapter/github.go b/internal/adapter/github.go index 2ce5a89..da1d0e5 100644 --- a/internal/adapter/github.go +++ b/internal/adapter/github.go @@ -53,10 +53,31 @@ func (g *githubClient) scrub(s string) string { // credential scrubbed FIRST: a cut that lands inside the credential would // otherwise leave a prefix that no later scrub can recognise. func (g *githubClient) clip(s string, max int) string { - if g.token != "" { - s = strings.ReplaceAll(s, g.token, "[redacted]") + return oneLine(redact(s, g.token), max) +} + +// minFragment is the shortest prefix of the credential redacted wherever +// it appears; a shorter one is redacted only where a cut left it. +const minFragment = 8 + +// redact removes the credential from s: whole, as any prefix of at least +// minFragment runes, and as any prefix at all right before the ellipsis a +// cut leaves. Text can arrive already cut (a proxy echoing a truncated +// token), and a cut can land inside the credential. +func redact(s, token string) string { + if token == "" { + return s + } + s = strings.ReplaceAll(s, token, "[redacted]") + for k := len(token) - 1; k >= 1; k-- { + p := token[:k] + if k >= minFragment { + s = strings.ReplaceAll(s, p, "[redacted]") + } else { + s = strings.ReplaceAll(s, p+"…", "[redacted]…") + } } - return oneLine(s, max) + return s } func (g *githubClient) do(ctx context.Context, method, endpoint string, body any) (int, []byte, error) {