Files
kandev/docs/specs/integrations/system-design/watcher-remote-base-branches.md
T

144 lines
7.0 KiB
Markdown

---
status: draft
system: integrations
requirements:
- REQ-INTEGRATIONS-WATCHER-REMOTE-BASE-BRANCHES-001
---
# Watcher Remote Base Branches System Design
## Purpose and boundaries
The integration system owns the repository and base-branch values stored on a
watcher. The workspace system owns branch discovery and worktree materialization.
This design preserves branch identity between those systems without adding a
new watcher setting or persistence field.
The runtime behavior of local and remote worktree bases remains defined by the
[Worktree Base Refresh System Design](../../workspaces/system-design/worktree-base-refresh.md).
## Requirement mapping
| Acceptance criterion | Design section |
| --- | --- |
| `AC-INTEGRATIONS-WATCHER-REMOTE-BASE-BRANCHES-001.1` | [Branch projection](#branch-projection) |
| `AC-INTEGRATIONS-WATCHER-REMOTE-BASE-BRANCHES-001.2` | [Save and launch flow](#save-and-launch-flow) |
| `AC-INTEGRATIONS-WATCHER-REMOTE-BASE-BRANCHES-001.3` | [Compatibility](#compatibility) |
| `AC-INTEGRATIONS-WATCHER-REMOTE-BASE-BRANCHES-001.4` | [Shared picker interaction](#shared-picker-interaction) |
| `AC-INTEGRATIONS-WATCHER-REMOTE-BASE-BRANCHES-001.5` | [Responsive behavior](#responsive-behavior) |
## Components and responsibilities
- `internal/task/service.ListBranchesWithCurrent` returns branch records with
`name`, `type`, and `remote` identity.
- `useBranches` loads those records into the workspace branch cache.
- The New Task branch option helpers sort branch records, preserve qualified
remote values, expose search keywords, and render local or remote badges.
- `BranchSelector` supplies the full-width searchable combobox and refresh
action already reused by repository branch-policy settings.
- `WatcherRepositoryFields` projects supported branch records into the shared
watcher selector used by Jira, Linear, Sentry, and GitLab watcher dialogs.
- Each integration service validates and persists its existing `baseBranch`
field, and its watcher source copies that value into the generated task's
repository binding.
- `internal/worktree.Manager` resolves the stored base ref during launch under
the repository's existing worktree-refresh policy.
## Branch projection
`WatcherRepositoryFields` reuses `sortBranches` and `branchToOption` from the
New Task branch picker. Local branches use their short name. Remote branch
records from the supported `origin` remote use `origin/<name>`. Remote records
with another named remote are omitted because the watcher launch contract only
validates and refreshes `origin/<branch>` refs. Provider-backed records without
a remote name keep their short value. Exact projected refs are deduplicated
after that shared mapping, so repeated records do not create duplicate
combobox items while `main` and `origin/main` remain distinct.
A provider-backed branch record without a remote name keeps its short name.
Provider-backed repositories do not combine that record with a local branch
list, so this fallback does not erase a known remote identity.
## Shared picker interaction
Only the base-branch control changes presentation. The repository control
keeps its existing select behavior. The base-branch field uses the shared
`BranchSelector` and New Task branch options so it inherits:
- path-aware search through `scoreBranch`;
- the `local` badge for local refs and the `origin` badge for qualified remote
refs;
- preferred ordering for `main`, `master`, and `develop`; and
- the branch refresh action backed by `useBranches.refresh`.
The repository-default sentinel remains the first option and continues to map
to an empty persisted value. A stored value that is temporarily absent from
the fetched branch list remains visible as a fallback option, so opening the
dialog cannot visually replace a saved choice. Refresh updates the available
options without changing the selected watcher value.
The reusable boundary is the branch option model and the full-width
`BranchSelector` presentation. The compact New Task `Pill` trigger remains
task-specific because watcher dialogs need a labeled, full-width form field.
## Save and launch flow
1. The user selects a repository in a watcher dialog.
2. `useBranches` supplies local and remote branch records.
3. The shared searchable watcher field displays `origin/main` with an `origin`
badge and passes that exact string through `onBaseBranchChange`.
4. The integration's existing create or update request persists the qualified
ref without a schema change.
5. The watcher source copies the stored ref into `task_repositories.base_branch`.
6. Worktree launch applies the repository's `pull_before_worktree` policy. An
enabled policy refreshes the selected remote branch; the workspace system
owns refresh failure and fallback behavior.
The existing `securityutil.IsValidBaseBranchRef` contract accepts
`origin/<branch>` and continues to reject unsafe refs. The watcher selector
does not offer other named remotes because the worktree refresh and launch
contract is origin-specific.
## Compatibility
The repository-default sentinel still maps to an empty request value so the
integration service resolves the repository default. Local selections keep
their short names. Existing watchers with a stored local or qualified ref load
without conversion.
No backend, API, or database migration is required.
## Responsive behavior
The watcher dialog remains the single scroll owner. Desktop keeps the current
two-column repository and base-branch row. Phone keeps the current stacked row.
The searchable combobox popover is retained on phone because it is a temporary,
one-dimensional choice with built-in search and viewport-bounded width and
height. The trigger and option rows use touch-sized hit areas on coarse
pointers, and the option list owns its internal overflow. The component shares
values, filtering, selection, and refresh behavior across viewports; no
mobile-only branch state is introduced.
The nearest mobile precedent is the existing full-width branch-policy picker,
which already uses `BranchSelector` in a form surface. The implementation adds
scoped touch sizing where needed instead of introducing a global popover rule.
It does not change navigation, dialog geometry, or primary actions.
## Failure and recovery
A branch-list failure keeps the existing loading or default placeholder and
does not alter the saved watcher. A remote-refresh failure is handled by the
workspace worktree-refresh contract and is not converted into a local branch
selection by the watcher UI.
## Test strategy
- Focused component coverage proves local and supported origin records render as
distinct exact refs with badges; unsupported named remotes stay hidden; search
filters the choices; refresh invokes the branch hook; and duplicate exact
refs collapse without regressing disabled, default, and loading states.
- Desktop and mobile Playwright flows open the Jira watcher dialog, select and
save `origin/main`, reload the settings page, and verify the qualified value
remains selected. The mobile flow also verifies touch-sized branch rows,
viewport containment, internal list scrolling, and no document overflow.