dreampiler/kandev
1
0
Fork 0
Code Issues 43 Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
a2b4fc0c6d18420bdbe993ffd02b97a94ebcd6ed
kandev/apps/backend/internal/linear/models.go
T
Nicolas Lenepveu e740417885 feat(linear): enrich issue watch filters with priority, labels, creator, estimate (#974) 
* feat(linear): enrich issue watch filters with priority, labels, creator, estimate

Adds priority, labels (multi-select), creator (team member select), and
estimate range filters to Linear issue watchers — closing the gap with
Linear's GraphQL filter surface so users can scope auto-run watchers
nearly as tightly as they would in Linear itself.

- Backend: extend SearchFilter, map new fields to IssueFilter, add
  ListLabels / ListUsers on the Client interface, expose them over HTTP
  (GET /api/v1/linear/labels, /users) and via SearchIssues query params.
- Frontend: extend LinearSearchFilter, fetch labels + users per team,
  render new filter controls in the watcher dialog, and split helpers
  into linear-issue-watch-form.ts + linear-issue-watch-fields.tsx so
  the dialog stays under file/function size limits.

* fix(linear): address reviewer feedback on enriched filter PR

- Reject invalid priority / malformed estimate query params with 400 instead
  of silently dropping them; reject estimateMin > estimateMax. Mirror the
  bounds check in the issue-watch validator so JSON-encoded watches go
  through the same gate.
- A11y: render label/state toggle Badges inside <button aria-pressed> so
  keyboard users can navigate and screen readers can announce state.
- Recover from per-team fetch failures so a transient network blip doesn't
  permanently mark a team as "fetched-empty" — clear the in-flight marker
  when any of states/labels/users fail, allowing remount to retry.
- Tighten priority typing: LinearSearchFilter.priority is 0|1|2|3|4, and
  LinearPriority is the source of truth on the form-state side. Promote
  FormState from a type alias to an interface per repo convention.

* fix(linear): align update error message and clear fetchedTeams on cancel

- UpdateIssueWatch's filter-empty error still listed only the original
  four fields; bring it in line with the create path so the message
  matches what filterIsEmpty actually accepts.
- linear-issue-watch-fields: clear the fetchedTeams marker on effect
  cancellation as well as failure, so a remount after a fast teamKey
  switch can retry instead of being stuck with whatever partial cache
  the prior effect produced.

* fix(linear): address PR #974 reviewer findings

- linear-issue-watch-fields: delete the fetchedTeams marker on effect
  cleanup so rapid team switches (A → B → A) refetch on return instead
  of being stranded mid-load. Capture the Set in a local so the cleanup
  closure references the exact instance the effect body added to.
- graphql_client: raise the labels/users page cap from 100 to Linear's
  max of 250 via a shared linearMaxPageSize constant and a $first
  variable. Documented that a workspace exceeding that would need
  cursor-pagination here AND lazy-load in the UI.
- service_issue_watch.validateFilterBounds + handlers parseSearchNumeric
  Filters: reject negative estimate values — Linear story points are
  non-negative, so a -1 would silently match nothing.

* fix(linear): collapse duplicate hint text on States/Labels rows

When no team was selected the row showed two stacked muted lines —
the field description and the multi-select's "Pick a team…" prose —
saying overlapping things. Swap the row description based on team
selection and let the multi-select render nothing when disabled, so
exactly one line is shown in either state.

Also tightens the new fields' descriptions to match the brevity of
the existing ones (Labels, Estimate min/max).

* fix(linear): reject NaN/Inf estimates and preserve team cache after success

CodeRabbit + cubic flagged two real issues in the previous round:

- strconv.ParseFloat accepts "NaN" / "+Inf" / "-Inf" without erroring,
  and "f < 0" passes through for NaN. Without an explicit math.IsNaN /
  math.IsInf guard those values would propagate into the GraphQL
  request and the eventual json.Marshal would 500 instead of 400.
  Add the guard for both estimate_min and estimate_max, with a
  regression test covering NaN, ±Inf, negative, and inverted range.

- useTeamsAndStates was deleting the per-team cache marker on every
  cleanup, so a normal team switch evicted a healthy cache and the
  next visit re-fetched all three datasets. Track a "loaded" flag and
  only evict on cleanup when the fetch didn't complete successfully.

Also extracts the duplicated "team_key" / "team_key required" wire
strings into package-level constants per the repo's
"3+ occurrences → constant" convention.

* test(linear): add handler tests for /labels and /users endpoints

Mirrors the existing TestHTTPListStates_* pair — required team_key
returns 400, and a happy path that asserts the team_key reaches the
client and the response is 200. Closes the coverage gap CodeRabbit
flagged on the two new endpoints introduced in this PR.

* feat(linear): make priority filter multi-select

Status and label filters are already multi-select; priority being a
single Select broke the symmetry and forced single-value thinking.
Linear's own filter UI is multi-select per priority, and the GraphQL
filter takes priority: { in: [...] } natively, so the wire change is
clean.

Backend
- SearchFilter.Priority *int → Priorities []int
- buildIssueFilter emits priority: { in: priorities } when non-empty
- validateFilterBounds checks each element ∈ [0,4]
- normalizeFilter de-dupes (preserves caller order)
- HTTP query param priority → priorities, parsed as CSV
- Tests updated, including priority=0 still expressible as
  Priorities=[0] (matches "No priority" issues only)

Frontend
- LinearSearchFilter.priority → priorities: LinearPriority[]
- FormState.priority → priorities
- PRIORITY_OPTIONS dropped the (any) sentinel; "No priority" sits at
  the end of the chip row
- PriorityMultiSelect added next to State/Label multi-selects
- Priority moved to its own full-width row matching States/Labels;
  Creator promoted to a stand-alone CreatorRow

Refactor
- searchLinearIssues query-param building extracted to a flat
  table-driven helper to keep cyclomatic complexity ≤ 15

* refactor(linear): regroup watcher dialog fields and add section separators

UX pass on the watcher dialog:

- Pulled Team out into its own full-width row and paired Assignee +
  Creator in a 2-col row so the people filters sit together — the old
  Team+Assignee pairing forced a context switch between scope and
  people filters mid-form.
- Added hairlines between the four conceptual blocks (Destination /
  Filter / Automation / Prompt / Settings). Each block answers a
  different question, so a consistent rhythm helps users scan the form
  by section instead of reading one long stack.

No behaviour change; pure layout.

* refactor(linear): use shared Separator for watcher dialog section breaks

Initially extracted a local SectionDivider, but @kandev/ui/separator
(Radix-based, shadcn) already exists and is used in 14 places across
the codebase — including the sibling Jira settings page. Use that
instead so the styling tracks the rest of the app.

* refactor(linear): split parseSearchNumericFilters to satisfy cyclop

Extract priority and estimate-bound parsing into helpers so the entry
point drops below the project's max cyclomatic complexity (15).

* fix(linear): reject non-finite/negative estimates and align fmt

- validateFilterBounds rejects NaN/+-Inf in addition to negatives, so a
  watch config can't be persisted with values that would later crash
  json.Marshal. Adds focused unit tests.
- parseEstimate on the frontend treats negatives as unset so the UI
  cannot submit estimateMin/Max < 0.
- gofmt-only alignment tweak in handlers_test.go test table.
2026-05-22 10:42:42 +01:00

255 lines
12 KiB
Go
Raw Blame History

// Package linear implements the Linear integration: a single install-wide
// configuration, a GraphQL client for issues and workflow states, and the HTTP
// and WebSocket handlers that expose these capabilities to the frontend.
package linear
import "time"
// AuthMethodAPIKey is the only auth method Linear supports today: a Personal
// API Key sent as the `Authorization` header (no Bearer prefix). The constant
// exists so the wire format mirrors the Jira integration's `authMethod` field
// and leaves room for OAuth in the future.
const AuthMethodAPIKey = "api_key"
// LinearConfig is the install-wide configuration for the Linear integration.
// The API key is stored separately in the encrypted secret store under
// SecretKey.
type LinearConfig struct {
AuthMethod string `json:"authMethod" db:"auth_method"`
DefaultTeamKey string `json:"defaultTeamKey" db:"default_team_key"`
HasSecret bool `json:"hasSecret" db:"-"`
// OrgSlug is captured from the most recent successful probe so the UI can
// build canonical issue URLs (linear.app/<slug>/issue/<id>) without an
// extra round-trip. Empty until the first probe succeeds.
OrgSlug string `json:"orgSlug,omitempty" db:"org_slug"`
// LastCheckedAt / LastOk / LastError are written by the background auth
// poller. They let the UI render a "connected/disconnected + checked Xs ago"
// indicator without doing its own probing.
LastCheckedAt *time.Time `json:"lastCheckedAt,omitempty" db:"last_checked_at"`
LastOk bool `json:"lastOk" db:"last_ok"`
LastError string `json:"lastError,omitempty" db:"last_error"`
CreatedAt time.Time `json:"createdAt" db:"created_at"`
UpdatedAt time.Time `json:"updatedAt" db:"updated_at"`
}
// SetConfigRequest is the payload sent by the UI to create or update the
// Linear configuration. When Secret is empty on update, the existing secret
// is retained; when non-empty it replaces the stored value.
type SetConfigRequest struct {
AuthMethod string `json:"authMethod"`
DefaultTeamKey string `json:"defaultTeamKey"`
Secret string `json:"secret"`
}
// TestConnectionResult reports what the backend learned when pinging Linear
// with the supplied credentials.
type TestConnectionResult struct {
OK bool `json:"ok"`
UserID string `json:"userId,omitempty"`
DisplayName string `json:"displayName,omitempty"`
Email string `json:"email,omitempty"`
OrgSlug string `json:"orgSlug,omitempty"`
OrgName string `json:"orgName,omitempty"`
Error string `json:"error,omitempty"`
}
// LinearIssue is the subset of Linear's issue payload that Kandev consumes.
// Kept small intentionally: the UI needs enough to prefill a task, show the
// current state, and surface a few familiar fields (assignee, priority, team)
// in the popover.
type LinearIssue struct {
ID string `json:"id"`
Identifier string `json:"identifier"` // e.g. "ENG-123"
Title string `json:"title"`
Description string `json:"description"`
// State mirrors Jira's status tuple (id, name, category) so frontend code
// styling status pills can branch on Category without per-integration
// switches. Linear's StateType values map onto: backlog/unstarted → "new",
// started → "indeterminate", completed/canceled → "done".
StateID string `json:"stateId"`
StateName string `json:"stateName"`
StateType string `json:"stateType"` // backlog | unstarted | started | completed | canceled | triage
StateCategory string `json:"stateCategory"`
TeamID string `json:"teamId"`
TeamKey string `json:"teamKey"`
Priority int `json:"priority"` // 0=none, 1=urgent, 2=high, 3=med, 4=low
PriorityLabel string `json:"priorityLabel,omitempty"`
AssigneeName string `json:"assigneeName,omitempty"`
AssigneeEmail string `json:"assigneeEmail,omitempty"`
AssigneeIcon string `json:"assigneeIcon,omitempty"`
CreatorName string `json:"creatorName,omitempty"`
CreatorIcon string `json:"creatorIcon,omitempty"`
Updated string `json:"updated,omitempty"`
URL string `json:"url"`
States []LinearWorkflowState `json:"states"`
}
// LinearWorkflowState is one of the team workflow states an issue can be
// transitioned into. Unlike Jira transitions (which are edges), Linear states
// are nodes — to "transition" we set the issue's stateId to one of the team's
// states. State IDs are stable per team.
type LinearWorkflowState struct {
ID string `json:"id"`
Name string `json:"name"`
Type string `json:"type"` // backlog | unstarted | started | completed | canceled | triage
Color string `json:"color,omitempty"`
Position int `json:"position"`
}
// LinearTeam is the minimal shape used by the team selector on the settings
// page and by the issue browser to scope searches.
type LinearTeam struct {
ID string `json:"id"`
Key string `json:"key"`
Name string `json:"name"`
}
// LinearLabel is an issue label belonging to a team. Labels are returned by
// `GET /api/v1/linear/teams/:key/labels` and surfaced in the filter UI for
// issue watches.
type LinearLabel struct {
ID string `json:"id"`
Name string `json:"name"`
Color string `json:"color,omitempty"`
}
// LinearUser is a workspace member returned by `GET /api/v1/linear/teams/:key/members`
// (and the generic users list). Used as options in creator/assignee selectors.
type LinearUser struct {
ID string `json:"id"`
Name string `json:"name"`
DisplayName string `json:"displayName,omitempty"`
Email string `json:"email,omitempty"`
AvatarURL string `json:"avatarUrl,omitempty"`
}
// SearchFilter is a structured search filter used by SearchIssues. Linear has
// no JQL equivalent, so we expose a small set of structured fields that map
// cleanly to GraphQL filter inputs.
//
// All fields are optional; an empty filter returns every issue the API key can
// see. Watcher creation rejects fully-empty filters via filterIsEmpty.
type SearchFilter struct {
Query string `json:"query,omitempty"` // free-text title/description/identifier match
TeamKey string `json:"teamKey,omitempty"` // restrict to one team
StateIDs []string `json:"stateIds,omitempty"` // restrict to specific workflow states
Assigned string `json:"assigned,omitempty"` // "me" | "unassigned" | "" (any)
// Priorities filters issues whose priority is in this set. Linear uses
// 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low. Empty slice means no
// priority filter; a slice with 0 in it includes "No priority" issues.
Priorities []int `json:"priorities,omitempty"`
// LabelIDs filters issues that have ANY of the given label UUIDs (Linear's
// labels filter is OR by default).
LabelIDs []string `json:"labelIds,omitempty"`
// CreatorID restricts to issues created by a specific user UUID. Empty
// means any creator.
CreatorID string `json:"creatorId,omitempty"`
// EstimateMin / EstimateMax bound the issue's point estimate. nil disables
// that bound; the two together act as a closed range.
EstimateMin *float64 `json:"estimateMin,omitempty"`
EstimateMax *float64 `json:"estimateMax,omitempty"`
}
// SearchResult is a page of issues from a search. Linear uses cursor-based
// pagination (endCursor + hasNextPage), which we expose here under the same
// shape as the Jira SearchResult so the frontend pagination component can be
// reused.
type SearchResult struct {
Issues []LinearIssue `json:"issues"`
MaxResults int `json:"maxResults"`
IsLast bool `json:"isLast"`
NextPageToken string `json:"nextPageToken,omitempty"`
}
// SecretKey is the secret-store key used for the install-wide Linear API key.
// Centralised so the service, store and provider migration agree.
const SecretKey = "linear:singleton:token"
// LegacySecretKeyForWorkspace returns the pre-singleton per-workspace secret
// key. Only used by the one-shot startup migration in provider.go to copy an
// existing token over to SecretKey.
func LegacySecretKeyForWorkspace(workspaceID string) string {
return "linear:" + workspaceID + ":token"
}
// DefaultIssueWatchPollInterval is the polling cadence assigned to a watcher
// when the caller does not specify one. Five minutes balances freshness
// against Linear rate limits when many workspaces have watches configured.
const DefaultIssueWatchPollInterval = 300
// IssueWatch configures periodic Linear search-polling. The filter is a
// structured SearchFilter (Linear has no JQL equivalent) persisted as JSON;
// the poller deserialises it back to SearchFilter at the store boundary.
//
// As with Jira, Linear issues have no repository affinity — the target
// workflow step's defaults determine where the resulting task runs.
type IssueWatch struct {
ID string `json:"id" db:"id"`
WorkspaceID string `json:"workspaceId" db:"workspace_id"`
WorkflowID string `json:"workflowId" db:"workflow_id"`
WorkflowStepID string `json:"workflowStepId" db:"workflow_step_id"`
Filter SearchFilter `json:"filter"`
AgentProfileID string `json:"agentProfileId" db:"agent_profile_id"`
ExecutorProfileID string `json:"executorProfileId" db:"executor_profile_id"`
Prompt string `json:"prompt" db:"prompt"`
Enabled bool `json:"enabled" db:"enabled"`
PollIntervalSeconds int `json:"pollIntervalSeconds" db:"poll_interval_seconds"`
LastPolledAt *time.Time `json:"lastPolledAt,omitempty" db:"last_polled_at"`
CreatedAt time.Time `json:"createdAt" db:"created_at"`
UpdatedAt time.Time `json:"updatedAt" db:"updated_at"`
}
// IssueWatchTask deduplicates task creation per (watch, issue) tuple. The
// UNIQUE constraint on (issue_watch_id, issue_identifier) prevents two
// concurrent pollers from racing to create duplicate tasks for the same
// issue. We key on Identifier (e.g. "ENG-123") rather than the GraphQL UUID
// because it's stable, what humans see, and present on every search result.
type IssueWatchTask struct {
ID string `json:"id" db:"id"`
IssueWatchID string `json:"issueWatchId" db:"issue_watch_id"`
IssueIdentifier string `json:"issueIdentifier" db:"issue_identifier"`
IssueURL string `json:"issueUrl" db:"issue_url"`
TaskID string `json:"taskId" db:"task_id"`
CreatedAt time.Time `json:"createdAt" db:"created_at"`
}
// NewLinearIssueEvent is published on the bus whenever the poller observes an
// issue matching a watch that has no existing dedup row. The orchestrator
// consumes this to create (and optionally auto-start) a Kandev task.
type NewLinearIssueEvent struct {
IssueWatchID string `json:"issueWatchId"`
WorkspaceID string `json:"workspaceId"`
WorkflowID string `json:"workflowId"`
WorkflowStepID string `json:"workflowStepId"`
AgentProfileID string `json:"agentProfileId"`
ExecutorProfileID string `json:"executorProfileId"`
Prompt string `json:"prompt"`
Issue *LinearIssue `json:"issue"`
}
// CreateIssueWatchRequest is the payload for POST /api/v1/linear/watches/issue.
type CreateIssueWatchRequest struct {
WorkspaceID string `json:"workspaceId"`
WorkflowID string `json:"workflowId"`
WorkflowStepID string `json:"workflowStepId"`
Filter SearchFilter `json:"filter"`
AgentProfileID string `json:"agentProfileId"`
ExecutorProfileID string `json:"executorProfileId"`
Prompt string `json:"prompt"`
PollIntervalSeconds int `json:"pollIntervalSeconds"`
Enabled *bool `json:"enabled,omitempty"`
}
// UpdateIssueWatchRequest is the payload for PATCH /api/v1/linear/watches/issue/:id.
// All fields are pointers so the caller can omit ones it doesn't want to change.
type UpdateIssueWatchRequest struct {
WorkflowID *string `json:"workflowId,omitempty"`
WorkflowStepID *string `json:"workflowStepId,omitempty"`
Filter *SearchFilter `json:"filter,omitempty"`
AgentProfileID *string `json:"agentProfileId,omitempty"`
ExecutorProfileID *string `json:"executorProfileId,omitempty"`
Prompt *string `json:"prompt,omitempty"`
Enabled *bool `json:"enabled,omitempty"`
PollIntervalSeconds *int `json:"pollIntervalSeconds,omitempty"`
}
Reference in New Issue View Git Blame Copy Permalink