relay-flow 0.0.1 → 0.2.0-alpha

package/internal/task/jira/acli/acli.go

@@ -0,0 +1,306 @@
+// Package acli wraps the Atlassian `acli` CLI behind a small fakeable
+// interface. Every call is real; there is no dry-run mode.
+//
+// 9.5 external-call logging: each CLI method emits one debug line BEFORE
+// the call (operation, key, transition target / jql as applicable) and one
+// info line AFTER with only the outcome (ok/error), never the payload.
+package acli
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"os/exec"
+	"strings"
+)
+
+// Client is the fakeable Jira CLI seam used by the Jira task adapter.
+type Client interface {
+	// Search runs a JQL query and returns the raw acli search JSON — a
+	// BARE ARRAY of issue objects (acli's wire shape, not the Jira REST
+	// {"issues":[...]} envelope).
+	Search(ctx context.Context, jql string) ([]byte, error)
+	// ValidateAssignee probes whether Jira recognizes the configured user.
+	ValidateAssignee(ctx context.Context, assignee string) error
+	// ValidateStatus probes whether a project exposes the configured status.
+	ValidateStatus(ctx context.Context, project, status string) error
+	// View returns the raw Jira issue JSON for one key.
+	View(ctx context.Context, key string) ([]byte, error)
+	// CreateSubtask creates a child work item and returns its id and key.
+	CreateSubtask(ctx context.Context, parentKey, title, description string) (id, key string, err error)
+	// Assign sets a work item's assignee by email or account ID.
+	Assign(ctx context.Context, key, assignee string) error
+	// Transition moves a work item to a status.
+	Transition(ctx context.Context, key, status string) error
+	// EnsureLabel adds the label when absent.
+	EnsureLabel(ctx context.Context, key, label string) error
+	// UpdateDescription replaces a work item's description.
+	UpdateDescription(ctx context.Context, key, description string) error
+	// ListComments returns the work item's comment bodies.
+	ListComments(ctx context.Context, key string) ([]string, error)
+	// AddComment posts a comment.
+	AddComment(ctx context.Context, key, body string) error
+}
+
+// CLI is the production Client backed by the acli binary.
+type CLI struct{}
+
+func New() *CLI { return &CLI{} }
+
+func (CLI) Search(ctx context.Context, jql string) ([]byte, error) {
+	slog.Debug("jira call", "op", "search", "jql", jql)
+	// acli's default search fields omit labels; request every field the
+	// normalizer consumes (subtasks are not searchable via --fields).
+	out, err := runOut(ctx, "jira", "workitem", "search",
+		"--jql", jql,
+		"--fields", "key,summary,status,issuetype,labels,assignee",
+		"--json")
+	logOutcome("search", "", err)
+	return out, err
+}
+
+func (CLI) ValidateAssignee(ctx context.Context, assignee string) error {
+	slog.Debug("jira call", "op", "validate-assignee", "assignee", assignee)
+	jql := fmt.Sprintf("assignee = %q", assignee)
+	_, err := runOut(ctx, "jira", "workitem", "search", "--jql", jql, "--limit", "1", "--json")
+	logOutcome("validate-assignee", "", err)
+	if err != nil {
+		return fmt.Errorf("assignee %q is not a valid Jira user: %w", assignee, err)
+	}
+	return nil
+}
+
+func (CLI) ValidateStatus(ctx context.Context, project, status string) error {
+	slog.Debug("jira call", "op", "validate-status", "project", project, "status", status)
+	jql := fmt.Sprintf("project = %s AND status = %q", project, status)
+	_, err := runOut(ctx, "jira", "workitem", "search", "--jql", jql, "--limit", "1", "--json")
+	logOutcome("validate-status", "", err, "project", project, "status", status)
+	if err != nil {
+		return fmt.Errorf("status %q is not valid in project %s: %w", status, project, err)
+	}
+	return nil
+}
+
+func (CLI) View(ctx context.Context, key string) ([]byte, error) {
+	slog.Debug("jira call", "op", "view", "key", key)
+	out, err := runOut(ctx, "jira", "workitem", "view", key,
+		"--fields", "summary,description,status,components,issuetype,parent,labels,comment,assignee,subtasks",
+		"--json")
+	logOutcome("view", key, err)
+	return out, err
+}
+
+func (CLI) CreateSubtask(ctx context.Context, parentKey, title, description string) (string, string, error) {
+	slog.Debug("jira call", "op", "create-subtask", "key", parentKey, "title", title)
+	// acli requires --project alongside --summary/--type; derive it from the
+	// parent key's project prefix (e.g. PAY-1 -> PAY).
+	project := parentKey
+	if i := strings.Index(parentKey, "-"); i > 0 {
+		project = parentKey[:i]
+	}
+	out, err := runOut(ctx, "jira", "workitem", "create",
+		"--type", "Sub-task", "--parent", parentKey,
+		"--project", project,
+		"--summary", title, "--description", description, "--json")
+	if err != nil {
+		logOutcome("create-subtask", parentKey, err)
+		return "", "", err
+	}
+	var env struct {
+		ID  string `json:"id"`
+		Key string `json:"key"`
+	}
+	if err := json.Unmarshal(out, &env); err != nil {
+		logOutcome("create-subtask", parentKey, err)
+		return "", "", fmt.Errorf("acli create subtask: parse json: %w", err)
+	}
+	slog.Info("jira outcome", "op", "create-subtask", "key", parentKey, "child", env.Key)
+	return env.ID, env.Key, nil
+}
+
+func (CLI) Assign(ctx context.Context, key, assignee string) error {
+	slog.Debug("jira call", "op", "assign", "key", key, "assignee", assignee)
+	err := runChecked(ctx, "jira", "workitem", "edit", "--key", key, "--assignee", assignee, "--yes", "--json")
+	logOutcome("assign", key, err)
+	return err
+}
+
+func (CLI) Transition(ctx context.Context, key, status string) error {
+	slog.Debug("jira call", "op", "transition", "key", key, "target", status)
+	err := runChecked(ctx, "jira", "workitem", "transition", "--key", key, "--status", status, "--yes", "--json")
+	logOutcome("transition", key, err, "target", status)
+	return err
+}
+
+func (c CLI) EnsureLabel(ctx context.Context, key, label string) error {
+	slog.Debug("jira call", "op", "ensure-label", "key", key, "label", label)
+	raw, err := c.View(ctx, key)
+	if err != nil {
+		logOutcome("ensure-label", key, err, "label", label)
+		return err
+	}
+	var v struct {
+		Fields struct {
+			Labels []string `json:"labels"`
+		} `json:"fields"`
+	}
+	if err := json.Unmarshal(raw, &v); err != nil {
+		logOutcome("ensure-label", key, err, "label", label)
+		return fmt.Errorf("acli view %s: parse labels: %w", key, err)
+	}
+	for _, l := range v.Fields.Labels {
+		if l == label {
+			slog.Info("jira outcome", "op", "ensure-label", "key", key, "label", label, "result", "already-present")
+			return nil
+		}
+	}
+	all := append(append([]string{}, v.Fields.Labels...), label)
+	err = runChecked(ctx, "jira", "workitem", "edit", "--key", key, "--labels", strings.Join(all, ","), "--yes", "--json")
+	logOutcome("ensure-label", key, err, "label", label)
+	return err
+}
+
+func (CLI) UpdateDescription(ctx context.Context, key, description string) error {
+	slog.Debug("jira call", "op", "update-description", "key", key)
+	err := runChecked(ctx, "jira", "workitem", "edit", "--key", key, "--description", description, "--yes", "--json")
+	logOutcome("update-description", key, err)
+	return err
+}
+
+// adfText extracts plain text from an Atlassian Document Format tree by
+// concatenating every text node in document order.
+func adfText(raw json.RawMessage) string {
+	var node struct {
+		Text    string            `json:"text"`
+		Content []json.RawMessage `json:"content"`
+	}
+	if err := json.Unmarshal(raw, &node); err != nil {
+		return ""
+	}
+	var parts []string
+	if node.Text != "" {
+		parts = append(parts, node.Text)
+	}
+	for _, child := range node.Content {
+		if text := adfText(child); text != "" {
+			parts = append(parts, text)
+		}
+	}
+	return strings.Join(parts, " ")
+}
+
+func (CLI) ListComments(ctx context.Context, key string) ([]string, error) {
+	slog.Debug("jira call", "op", "list-comments", "key", key)
+	raw, err := runOut(ctx, "jira", "workitem", "view", key, "--fields", "comment", "--json")
+	if err != nil {
+		logOutcome("list-comments", key, err)
+		return nil, err
+	}
+	var v struct {
+		Fields struct {
+			Comment struct {
+				Comments []struct {
+					Body json.RawMessage `json:"body"`
+				} `json:"comments"`
+			} `json:"comment"`
+		} `json:"fields"`
+	}
+	if err := json.Unmarshal(raw, &v); err != nil {
+		logOutcome("list-comments", key, err)
+		return nil, fmt.Errorf("acli comments %s: parse json: %w", key, err)
+	}
+	var out []string
+	for _, c := range v.Fields.Comment.Comments {
+		out = append(out, adfText(c.Body))
+	}
+	slog.Info("jira outcome", "op", "list-comments", "key", key, "count", len(out))
+	return out, nil
+}
+
+func (CLI) AddComment(ctx context.Context, key, body string) error {
+	slog.Debug("jira call", "op", "add-comment", "key", key)
+	err := runChecked(ctx, "jira", "workitem", "comment", "create", "--key", key, "--body", body, "--json")
+	logOutcome("add-comment", key, err)
+	return err
+}
+
+// logOutcome writes the one-line info record for a jira call's outcome.
+// Payloads are never logged: the raw error embeds the full acli argv
+// (including comment bodies, descriptions, JQL), so only the trailing
+// stderr/stdout fragment after the last colon is kept. extra carries
+// structured extras (e.g. the transition target).
+func logOutcome(op, key string, err error, extra ...any) {
+	attrs := []any{"op", op}
+	if key != "" {
+		attrs = append(attrs, "key", key)
+	}
+	attrs = append(attrs, extra...)
+	if err != nil {
+		attrs = append(attrs, "result", "error", "error", sanitizeErr(err))
+	} else {
+		attrs = append(attrs, "result", "ok")
+	}
+	slog.Info("jira outcome", attrs...)
+}
+
+// sanitizeErr strips the leading "acli [args...]:" prefix from acli error
+// strings so info-level outcome lines never leak argv payloads (comment
+// bodies, descriptions, JQL). Keeps the wrapped exit error + trailing
+// stderr fragment, which carry the actual failure reason. Handles both
+// "acli [args]: ..." (runOut/runChecked) and "acli <op>: ..." (local
+// wrapping) shapes.
+func sanitizeErr(err error) string {
+	if err == nil {
+		return ""
+	}
+	s := err.Error()
+	// Strip "acli [args...]: " (runOut shape: "acli %v: %w: %s").
+	if strings.HasPrefix(s, "acli [") {
+		if i := strings.Index(s, "]: "); i >= 0 {
+			return s[i+3:]
+		}
+	}
+	// Strip "acli <op>: " (parse-error wraps).
+	if strings.HasPrefix(s, "acli ") {
+		if i := strings.Index(s, ": "); i >= 0 {
+			return s[i+2:]
+		}
+	}
+	return s
+}
+
+func runOut(ctx context.Context, args ...string) ([]byte, error) {
+	cmd := exec.CommandContext(ctx, "acli", args...)
+	var stderr strings.Builder
+	cmd.Stderr = &stderr
+	out, err := cmd.Output()
+	if err != nil {
+		return nil, fmt.Errorf("acli %v: %w: %s", args, err, strings.TrimSpace(stderr.String()))
+	}
+	return out, nil
+}
+
+// runChecked runs a mutating acli command. acli exits 0 even when the
+// operation fails server-side, so the JSON envelope is inspected.
+func runChecked(ctx context.Context, args ...string) error {
+	out, err := runOut(ctx, args...)
+	if err != nil {
+		return err
+	}
+	var env struct {
+		Results []struct {
+			Status  string `json:"status"`
+			Message string `json:"message"`
+			ID      string `json:"id"`
+		} `json:"results"`
+	}
+	if jsonErr := json.Unmarshal(out, &env); jsonErr == nil && env.Results != nil {
+		for _, r := range env.Results {
+			if !strings.EqualFold(r.Status, "SUCCESS") {
+				return fmt.Errorf("acli %v: %s: %s", args, r.ID, r.Message)
+			}
+		}
+	}
+	return nil
+}

package/internal/task/jira/acli/acli_test.go

@@ -0,0 +1,208 @@
+package acli
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// 9.5: info-level outcome logs must never embed argv payloads. sanitizeErr
+// strips the leading "acli [args...]:" prefix while keeping the wrapped
+// exit error and trailing stderr fragment that carry the failure reason.
+func TestSanitizeErr(t *testing.T) {
+	argvShape := errors.New(`acli [jira workitem comment create --key PAY-1 --body SECRET-BODY --json]: exit status 1: permission denied`)
+	got := sanitizeErr(argvShape)
+	if strings.Contains(got, "SECRET-BODY") || strings.Contains(got, "--body") {
+		t.Fatalf("sanitizeErr leaked argv payload: %q", got)
+	}
+	if !strings.Contains(got, "exit status 1") || !strings.Contains(got, "permission denied") {
+		t.Fatalf("sanitizeErr dropped failure reason: %q", got)
+	}
+
+	parseShape := errors.New(`acli create subtask: parse json: invalid character 'x'`)
+	got = sanitizeErr(parseShape)
+	if !strings.Contains(got, "parse json") {
+		t.Fatalf("sanitizeErr dropped parse context: %q", got)
+	}
+
+	if got := sanitizeErr(nil); got != "" {
+		t.Fatalf("sanitizeErr(nil) = %q, want empty", got)
+	}
+
+	plain := errors.New("some other error")
+	if got := sanitizeErr(plain); got != "some other error" {
+		t.Fatalf("sanitizeErr(plain) = %q, got %q", "some other error", got)
+	}
+}
+
+// 9.12 command-shape regression: acli's workitem create/edit take the
+// description via --description (there is no --body flag on those
+// subcommands); only comment create takes --body. A fake `acli` binary on
+// PATH captures argv so the exact wire shape is asserted.
+func TestCommandShape(t *testing.T) {
+	dir := t.TempDir()
+	argvFile := filepath.Join(dir, "argv.json")
+	fake := "#!/bin/sh\n" +
+		"for a in \"$@\"; do printf '<%s>' \"$a\"; done > " + argvFile + "\n" +
+		"printf '{\"id\":\"1\",\"key\":\"PAY-2\"}'\n"
+	bin := filepath.Join(dir, "acli")
+	if err := os.WriteFile(bin, []byte(fake), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+
+	readArgv := func() string {
+		raw, err := os.ReadFile(argvFile)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return string(raw)
+	}
+	assertShape := func(argv, wantFlag, forbidFlag string) {
+		if !strings.Contains(argv, wantFlag) {
+			t.Fatalf("argv %q missing %s", argv, wantFlag)
+		}
+		if strings.Contains(argv, forbidFlag) {
+			t.Fatalf("argv %q contains unsupported %s", argv, forbidFlag)
+		}
+	}
+
+	ctx := context.Background()
+	c := New()
+
+	if _, _, err := c.CreateSubtask(ctx, "PAY-1", "t", "d"); err != nil {
+		t.Fatal(err)
+	}
+	argv := readArgv()
+	wantCreate := "<jira><workitem><create><--type><Sub-task><--parent><PAY-1><--project><PAY><--summary><t><--description><d><--json>"
+	if argv != wantCreate {
+		t.Fatalf("create argv = %q, want %q", argv, wantCreate)
+	}
+	assertShape(argv, "<--description><d>", "--body")
+	// 9.14: acli rejects workitem create when --summary/--type are set
+	// without --project; the project is derived from the parent key prefix.
+	if !strings.Contains(argv, "<--project><PAY>") {
+		t.Fatalf("argv %q missing <--project><PAY> derived from parent key PAY-1", argv)
+	}
+	// 9.15: live GHCOS acli accepts the issue-type name "Sub-task" and
+	// rejects "Subtask" with its allowed issue-type list.
+	for _, want := range []string{"<--summary><t>", "<--type><Sub-task>", "<--parent><PAY-1>"} {
+		if !strings.Contains(argv, want) {
+			t.Fatalf("argv %q missing %s", argv, want)
+		}
+	}
+
+	if err := c.UpdateDescription(ctx, "PAY-1", "d"); err != nil {
+		t.Fatal(err)
+	}
+	argv = readArgv()
+	if want := "<jira><workitem><edit><--key><PAY-1><--description><d><--yes><--json>"; argv != want {
+		t.Fatalf("description argv = %q, want %q", argv, want)
+	}
+	assertShape(argv, "<--description><d>", "--body")
+
+	if err := c.Assign(ctx, "PAY-1", "reviewer@example.com"); err != nil {
+		t.Fatal(err)
+	}
+	argv = readArgv()
+	if want := "<jira><workitem><edit><--key><PAY-1><--assignee><reviewer@example.com><--yes><--json>"; argv != want {
+		t.Fatalf("assignment argv = %q, want %q", argv, want)
+	}
+
+	if err := c.AddComment(ctx, "PAY-1", "b"); err != nil {
+		t.Fatal(err)
+	}
+	argv = readArgv()
+	if want := "<jira><workitem><comment><create><--key><PAY-1><--body><b><--json>"; argv != want {
+		t.Fatalf("comment argv = %q, want %q", argv, want)
+	}
+	assertShape(argv, "<--body><b>", "--description")
+}
+
+func TestListCommentsParsesADF(t *testing.T) {
+	dir := t.TempDir()
+	fixture, err := filepath.Abs("testdata/acli_comments.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	fake := "#!/bin/sh\ncat " + fixture + "\n"
+	bin := filepath.Join(dir, "acli")
+	if err := os.WriteFile(bin, []byte(fake), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+
+	comments, err := New().ListComments(context.Background(), "GHCOS-40357")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(comments) != 1 {
+		t.Fatalf("comments = %v, want one", comments)
+	}
+	if want := "visit-123:summary"; !strings.Contains(comments[0], want) {
+		t.Fatalf("comment %q does not contain marker %q", comments[0], want)
+	}
+}
+
+func TestValidationUsesNonMutatingSearchAndRealOutput(t *testing.T) {
+	dir := t.TempDir()
+	argvFile := filepath.Join(dir, "argv")
+	success, err := filepath.Abs("testdata/search_success.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	invalidStatus, err := filepath.Abs("testdata/search_invalid_status.txt")
+	if err != nil {
+		t.Fatal(err)
+	}
+	invalidAssignee, err := filepath.Abs("testdata/search_invalid_assignee.txt")
+	if err != nil {
+		t.Fatal(err)
+	}
+	fake := "#!/bin/sh\n" +
+		"for a in \"$@\"; do printf '<%s>' \"$a\"; done > " + argvFile + "\n" +
+		"case \"$*\" in\n" +
+		"  *missing-user*) cat " + invalidAssignee + " >&2; exit 1;;\n" +
+		"  *DO\\ Done*) cat " + invalidStatus + " >&2; exit 1;;\n" +
+		"  *) cat " + success + ";;\n" +
+		"esac\n"
+	bin := filepath.Join(dir, "acli")
+	if err := os.WriteFile(bin, []byte(fake), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+
+	c := New()
+	if err := c.ValidateAssignee(context.Background(), "Raj Popat"); err != nil {
+		t.Fatal(err)
+	}
+	argv, err := os.ReadFile(argvFile)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := string(argv), `<jira><workitem><search><--jql><assignee = "Raj Popat"><--limit><1><--json>`; got != want {
+		t.Fatalf("assignee argv = %q, want %q", got, want)
+	}
+	if err := c.ValidateAssignee(context.Background(), "missing-user"); err == nil || !strings.Contains(err.Error(), "user does not exist") {
+		t.Fatalf("invalid assignee error = %v", err)
+	}
+
+	if err := c.ValidateStatus(context.Background(), "PAY", "In Progress"); err != nil {
+		t.Fatal(err)
+	}
+	argv, err = os.ReadFile(argvFile)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := string(argv), `<jira><workitem><search><--jql><project = PAY AND status = "In Progress"><--limit><1><--json>`; got != want {
+		t.Fatalf("status argv = %q, want %q", got, want)
+	}
+
+	err = c.ValidateStatus(context.Background(), "PAY", "DO Done")
+	if err == nil || !strings.Contains(err.Error(), "does not exist for the field 'status'") {
+		t.Fatalf("invalid status error = %v", err)
+	}
+}

package/internal/task/jira/acli/testdata/acli_comments.json

@@ -0,0 +1,55 @@
+{
+  "changelog": null,
+  "editmeta": null,
+  "expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
+  "fields": {
+    "comment": {
+      "comments": [
+        {
+          "body": {
+            "content": [
+              {
+                "content": [
+                  {
+                    "text": "Summary complete.",
+                    "type": "text"
+                  },
+                  {
+                    "type": "hardBreak"
+                  },
+                  {
+                    "text": "<!-- visit-123:summary -->",
+                    "type": "text"
+                  }
+                ],
+                "type": "paragraph"
+              }
+            ],
+            "type": "doc",
+            "version": 1
+          },
+          "created": "2026-08-25T12:04:04.133-0400",
+          "id": "71668",
+          "jsdPublic": true,
+          "self": "https://jira.example/rest/api/3/issue/137388/comment/71668",
+          "updated": "2026-08-25T12:04:04.133-0400"
+        }
+      ],
+      "maxResults": 1,
+      "self": "https://jira.example/rest/api/3/issue/137388/comment",
+      "startAt": 0,
+      "total": 1
+    }
+  },
+  "fieldsToInclude": null,
+  "id": "137388",
+  "key": "GHCOS-40357",
+  "names": null,
+  "operations": null,
+  "properties": null,
+  "renderedFields": null,
+  "schema": null,
+  "self": "https://jira.example/rest/api/3/issue/137388",
+  "transitions": null,
+  "versionedRepresentations": null
+}

package/internal/task/jira/acli/testdata/search_invalid_assignee.txt

@@ -0,0 +1 @@
+✗ Error: failed to parse JQL query: user does not exist or cannot be viewed.

package/internal/task/jira/acli/testdata/search_invalid_status.txt

@@ -0,0 +1 @@
+✗ Error: failed to parse JQL query: the value 'DO Done' does not exist for the field 'status'.

package/internal/task/jira/acli/testdata/search_success.json

@@ -0,0 +1 @@
+[]