@delorenj/pjangler 1.4.2 → 1.4.4

package/templates/hermes-agent/template/.scripts/providers/linear.sh

@@ -11,15 +11,27 @@
 #
 # Implements the contract in lib/ticket-provider.sh. All Linear access goes
 # through GraphQL so the same envelope works in unattended runs.
+# LINEAR_MAX_PAGES bounds issue pagination (default 1000).
+# GraphQL variable references are intentionally single-quoted shell literals.
+# shellcheck disable=SC2016
 set -eu
 
 OP="${1:-}"; shift 2>/dev/null || true
 ROLE_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
 ROLE_YAML="$ROLE_DIR/role.yaml"
+GRAPHQL_URL="${LINEAR_GRAPHQL_URL:-https://api.linear.app/graphql}"
 
 die() { echo "linear: $*" >&2; exit 1; }
 need_key() { [ -n "${LINEAR_API_KEY:-}" ] || die "LINEAR_API_KEY is not set"; }
 
+validated_uint() {
+  setting="$1"; value="$2"; minimum="$3"; maximum="$4"
+  case "$value" in ''|*[!0-9]*) die "$setting must be an integer from $minimum through $maximum" ;; esac
+  [ "$value" -ge "$minimum" ] && [ "$value" -le "$maximum" ] \
+    || die "$setting must be an integer from $minimum through $maximum"
+  printf '%s' "$value"
+}
+
 # tp_cfg KEY — read ticket_provider.<KEY> from role.yaml (best-effort, flat).
 tp_cfg() {
   [ -f "$ROLE_YAML" ] || return 0
@@ -55,11 +67,11 @@ PY
 gql() {
   need_key
   _vars="${2:-}"; [ -n "$_vars" ] || _vars='{}'
-  python3 - "$1" "$_vars" <<'PY'
+  python3 - "$1" "$_vars" "$GRAPHQL_URL" <<'PY'
 import json, os, sys, urllib.request, urllib.error
 q, variables = sys.argv[1], json.loads(sys.argv[2])
 req = urllib.request.Request(
-    "https://api.linear.app/graphql",
+    sys.argv[3],
     data=json.dumps({"query": q, "variables": variables}).encode(),
     headers={"Authorization": os.environ["LINEAR_API_KEY"],
              "Content-Type": "application/json"},
@@ -81,6 +93,10 @@ PROJECT="$(pj_cfg project)"; [ -n "$PROJECT" ] || PROJECT="$(tp_cfg project)"
 SM_IN_REVIEW="$(tp_cfg in_review)"; SM_IN_REVIEW="${SM_IN_REVIEW:-In Review}"
 SM_DONE="$(tp_cfg completed)"; SM_DONE="${SM_DONE:-Done}"
 SM_CANCELLED="$(tp_cfg cancelled)"; SM_CANCELLED="${SM_CANCELLED:-Canceled}"
+SM_STARTED="$(tp_cfg started)"
+SM_UNSTARTED="$(tp_cfg unstarted)"
+SM_BACKLOG="$(tp_cfg backlog)"
+MAX_PAGES="$(validated_uint LINEAR_MAX_PAGES "${LINEAR_MAX_PAGES:-1000}" 1 1000)"
 
 # All Linear ops require the API key; fail fast and clean before any pipe.
 need_key
@@ -90,7 +106,7 @@ case "$OP" in
     [ -n "$TEAM" ] || die "ticket_provider.team (Linear team key) not set in role.yaml"
     gql 'query($k:String!){ teams(filter:{key:{eq:$k}}){nodes{id key name}} }' \
         "$(printf '{"k":"%s"}' "$TEAM")" \
-      | python3 -c 'import sys,json; d=json.load(sys.stdin); t=(d.get("teams",{}).get("nodes") or [{}])[0]; print(json.dumps({"provider":"linear","board_id":t.get("id",""),"board_url":"https://linear.app/team/"+t.get("key","")}))'
+      | python3 -c 'import sys,json; d=json.load(sys.stdin); t=(d.get("teams",{}).get("nodes") or [{}])[0]; print(json.dumps({"provider":"linear","board_id":t.get("id",""),"board_url":"https://linear.app/team/"+t.get("key",""),"identifier":t.get("key","")}))'
     ;;
 
   active_milestone)
@@ -107,17 +123,57 @@ print(json.dumps({"id":m.get("id",""),"name":m.get("name",""),"state":p.get("sta
 
   list_issues)
     [ -n "$TEAM" ] || die "ticket_provider.team not set"
-    gql 'query($k:String!){ issues(first:100, filter:{team:{key:{eq:$k}}}){nodes{ id identifier title updatedAt url state{name type} assignee{name} }} }' \
-        "$(printf '{"k":"%s"}' "$TEAM")" \
-      | python3 -c 'import sys,json
-d=json.load(sys.stdin); out=[]
-for n in d.get("issues",{}).get("nodes") or []:
+    ISSUE_PAGE_DIR="$(mktemp -d "${TMPDIR:-/tmp}/linear-issues.XXXXXX")" || die "could not create pagination scratch directory"
+    ISSUE_PAGE_ROWS="$ISSUE_PAGE_DIR/rows"
+    ISSUE_PAGE_CURSORS="$ISSUE_PAGE_DIR/cursors"
+    : > "$ISSUE_PAGE_ROWS"
+    : > "$ISSUE_PAGE_CURSORS"
+    cleanup_issue_pages() {
+      rm -f "$ISSUE_PAGE_ROWS" "$ISSUE_PAGE_CURSORS"
+      rmdir "$ISSUE_PAGE_DIR" 2>/dev/null || true
+    }
+    trap cleanup_issue_pages 0
+    trap 'cleanup_issue_pages; exit 129' HUP
+    trap 'cleanup_issue_pages; exit 130' INT
+    trap 'cleanup_issue_pages; exit 143' TERM
+    AFTER=""
+    PAGE_COUNT=0
+    while :; do
+      PAGE_COUNT=$((PAGE_COUNT + 1))
+      [ "$PAGE_COUNT" -le "$MAX_PAGES" ] \
+        || die "pagination exceeded LINEAR_MAX_PAGES=$MAX_PAGES"
+      VARS="$(python3 -c 'import json,sys; print(json.dumps({"k":sys.argv[1],"after":sys.argv[2] or None}))' "$TEAM" "$AFTER")"
+      PAGE="$(gql 'query($k:String!,$after:String){ issues(first:100, after:$after, filter:{team:{key:{eq:$k}}}){nodes{ id identifier title updatedAt url state{name type} assignee{name} } pageInfo{hasNextPage endCursor}} }' "$VARS")"
+      printf '%s' "$PAGE" | python3 -c 'import sys,json
+d=json.load(sys.stdin)
+for n in (d.get("issues") or {}).get("nodes") or []:
     st=n.get("state") or {}
-    out.append({"id":n["id"],"key":n.get("identifier",""),"title":n.get("title",""),
-                "state":st.get("name",""),"state_type":st.get("type",""),
-                "updated_at":n.get("updatedAt",""),
-                "assignee":(n.get("assignee") or {}).get("name",""),"url":n.get("url","")})
-print(json.dumps(out))'
+    print(json.dumps({"id":n["id"],"key":n.get("identifier",""),"title":n.get("title",""),
+                      "state":st.get("name",""),"state_type":st.get("type",""),
+                      "updated_at":n.get("updatedAt",""),
+                      "assignee":(n.get("assignee") or {}).get("name",""),"url":n.get("url","")}))' \
+        >> "$ISSUE_PAGE_ROWS"
+      HAS_NEXT="$(printf '%s' "$PAGE" | python3 -c 'import sys,json; print("true" if ((json.load(sys.stdin).get("issues") or {}).get("pageInfo") or {}).get("hasNextPage") else "false")')"
+      [ "$HAS_NEXT" = "true" ] || break
+      NEXT="$(printf '%s' "$PAGE" | python3 -c 'import sys,json; print(str(((json.load(sys.stdin).get("issues") or {}).get("pageInfo") or {}).get("endCursor") or ""))')"
+      [ -n "$NEXT" ] || die "Linear pagination reported another page without an end cursor"
+      CURSOR_FINGERPRINT="$(python3 -c 'import hashlib,sys; print(hashlib.sha256(sys.argv[1].encode()).hexdigest())' "$NEXT")"
+      if grep -Fqx "$CURSOR_FINGERPRINT" "$ISSUE_PAGE_CURSORS"; then
+        die "Linear pagination cursor repeated"
+      fi
+      printf '%s\n' "$CURSOR_FINGERPRINT" >> "$ISSUE_PAGE_CURSORS"
+      AFTER="$NEXT"
+    done
+    python3 - "$ISSUE_PAGE_ROWS" <<'PY'
+import json
+import pathlib
+import sys
+
+rows = [json.loads(line) for line in pathlib.Path(sys.argv[1]).read_text().splitlines() if line]
+print(json.dumps(rows))
+PY
+    cleanup_issue_pages
+    trap - 0 HUP INT TERM
     ;;
 
   get_issue)
@@ -135,9 +191,23 @@ print(json.dumps({"id":i.get("id",""),"key":i.get("identifier",""),"title":i.get
 
   comment)
     ID="${1:?usage: comment <id> <body>}"; BODY="${2:?usage: comment <id> <body>}"
-    gql 'mutation($id:String!,$b:String!){ commentCreate(input:{issueId:$id,body:$b}){ comment{id} success } }' \
+    gql 'mutation($id:String!,$b:String!){ commentCreate(input:{issueId:$id,body:$b}){ comment{id issue{id}} success } }' \
         "$(python3 -c 'import json,sys; print(json.dumps({"id":sys.argv[1],"b":sys.argv[2]}))' "$ID" "$BODY")" \
-      | python3 -c 'import sys,json; d=json.load(sys.stdin); print((d.get("commentCreate",{}).get("comment") or {}).get("id",""))'
+      | EXPECTED_ID="$ID" python3 -c 'import sys,json,os
+document=json.load(sys.stdin)
+created=document.get("commentCreate") if isinstance(document,dict) else None
+if not isinstance(created,dict) or created.get("success") is not True:
+    raise SystemExit("linear: commentCreate did not report success")
+comment=created.get("comment")
+if not isinstance(comment,dict):
+    raise SystemExit("linear: commentCreate response omitted its comment object")
+comment_id=comment.get("id")
+if not isinstance(comment_id,str) or not comment_id.strip():
+    raise SystemExit("linear: commentCreate response omitted its comment id")
+issue=comment.get("issue")
+if not isinstance(issue,dict) or str(issue.get("id") or "").strip()!=os.environ["EXPECTED_ID"]:
+    raise SystemExit("linear: commentCreate response did not identify the requested issue")
+print(comment_id.strip())'
     ;;
 
   transition)
@@ -147,9 +217,9 @@ print(json.dumps({"id":i.get("id",""),"key":i.get("identifier",""),"title":i.get
       completed)  WANT_TYPE=completed; WANT_NAME="$SM_DONE" ;;
       cancelled)  WANT_TYPE=canceled;  WANT_NAME="$SM_CANCELLED" ;;
       in_review)  WANT_TYPE=started;   WANT_NAME="$SM_IN_REVIEW" ;;
-      started)    WANT_TYPE=started;   WANT_NAME="" ;;
-      unstarted)  WANT_TYPE=unstarted; WANT_NAME="" ;;
-      backlog)    WANT_TYPE=backlog;   WANT_NAME="" ;;
+      started)    WANT_TYPE=started;   WANT_NAME="$SM_STARTED" ;;
+      unstarted)  WANT_TYPE=unstarted; WANT_NAME="$SM_UNSTARTED" ;;
+      backlog)    WANT_TYPE=backlog;   WANT_NAME="$SM_BACKLOG" ;;
       *) die "invalid normalized state: $TARGET" ;;
     esac
     STATE_ID="$(gql 'query($id:String!){ issue(id:$id){ team{ states{nodes{id name type}} } } }' \
@@ -158,15 +228,58 @@ print(json.dumps({"id":i.get("id",""),"key":i.get("identifier",""),"title":i.get
 d=json.load(sys.stdin)
 states=((d.get("issue") or {}).get("team") or {}).get("states",{}).get("nodes") or []
 want_t=os.environ["WANT_TYPE"]; want_n=os.environ.get("WANT_NAME","")
-named=[s for s in states if want_n and s["name"].lower()==want_n.lower()]
-typed=[s for s in states if s.get("type")==want_t]
-pick=(named or typed or [{}])[0]
-print(pick.get("id",""))')"
+if want_n:
+    candidates=[s for s in states if str(s.get("name") or "").strip().casefold()==want_n.strip().casefold()]
+    basis=f"configured name {want_n!r}"
+else:
+    candidates=[s for s in states if s.get("type")==want_t]
+    basis=f"workflow type {want_t!r}"
+if len(candidates) != 1:
+    raise SystemExit(f"linear: {basis} resolved {len(candidates)} states; exactly one is required")
+pick=candidates[0]
+if pick.get("type") != want_t:
+    raise SystemExit(f"linear: configured state {want_n!r} has type {pick.get('type')!r}, expected {want_t!r}")
+state_id=str(pick.get("id") or "")
+if not state_id:
+    raise SystemExit("linear: resolved state omitted its id")
+print(state_id)')"
     [ -n "$STATE_ID" ] || die "no Linear state for normalized '$TARGET'"
-    gql 'mutation($id:String!,$s:String!){ issueUpdate(id:$id,input:{stateId:$s}){ success issue{identifier state{name}} } }' \
+    gql 'mutation($id:String!,$s:String!){ issueUpdate(id:$id,input:{stateId:$s}){ success issue{id identifier state{id name type}} } }' \
         "$(python3 -c 'import json,sys; print(json.dumps({"id":sys.argv[1],"s":sys.argv[2]}))' "$ID" "$STATE_ID")" \
-      | python3 -c 'import sys,json; u=json.load(sys.stdin).get("issueUpdate",{});
-print(("ok " + (u.get("issue") or {}).get("identifier","")) if u.get("success") else "FAILED"); sys.exit(0 if u.get("success") else 1)'
+      | EXPECTED_ID="$ID" EXPECTED_STATE_ID="$STATE_ID" python3 -c 'import sys,json,os
+u=json.load(sys.stdin).get("issueUpdate") or {}
+if u.get("success") is not True:
+    raise SystemExit("linear: issueUpdate did not report success")
+issue=u.get("issue") or {}
+if str(issue.get("id") or "") != os.environ["EXPECTED_ID"]:
+    raise SystemExit("linear: issueUpdate read-back did not identify the requested issue")
+state=issue.get("state") or {}
+if str(state.get("id") or "") != os.environ["EXPECTED_STATE_ID"]:
+    raise SystemExit("linear: issueUpdate read-back did not confirm the exact target state")
+print("ok " + str(issue.get("identifier") or issue.get("id") or ""))'
+    ;;
+
+  describe_board)
+    # Read-only team lookup by id, against an EXPLICIT workspace argument so no
+    # ambient binding can answer for the wrong org. Linear's team KEY is a real
+    # authoritative identifier — it prefixes every issue — so it is read back
+    # from Linear itself and never proposed locally.
+    DWS="${1:?usage: describe_board <workspace> <board_id>}"
+    DBID="${2:?usage: describe_board <workspace> <board_id>}"
+    gql 'query($id:String!){ team(id:$id){ id key name } organization{ urlKey } }' \
+        "$(printf '{"id":"%s"}' "$DBID")" \
+      | WS="$DWS" BID="$DBID" python3 -c 'import sys, json, os
+d = json.load(sys.stdin)
+t = d.get("team") or {}
+ident = str(t.get("key") or "")
+if not ident:
+    raise SystemExit("linear: team %s reported no authoritative key" % os.environ["BID"])
+print(json.dumps({
+    "board_id": str(t.get("id") or os.environ["BID"]),
+    "identifier": ident,
+    "workspace": str((d.get("organization") or {}).get("urlKey") or os.environ["WS"]),
+    "name": str(t.get("name") or ""),
+}))'
     ;;
 
   create_board)