Add selective account run implementation plan

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 13:55:02 +07:00
parent b439eee164
commit fc335dee3f
1 changed files with 546 additions and 0 deletions
@@ -0,0 +1,546 @@
 # Selective Account Run Implementation Plan
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 **Goal:** Let the user run a migration for only the checkbox-selected accounts; with no selection, run all (unchanged).
 **Architecture:** A pure `selectAccounts` filter narrows the orchestrator's account slice before the test gate; the run HTTP handler parses an optional `account_ids` body and passes it through. The accounts table gains row checkboxes and a "select all" header, and the single "Run migration" button becomes "Run selected (N)" when a selection exists. Copy is already idempotent (dedup by message key), so a re-run of selected accounts skips copied messages and delivers the missing tail.
 **Tech Stack:** Go 1.x (net/http, encoding/json, standard testing), React + TypeScript + Vite, existing REST/WS client.
 ## Global Constraints
 - Backend module path: `github.com/vasyansk/imap-copier`.
 - `Run` with an empty/nil account-ID set MUST behave exactly as today (all accounts) — the scheduler depends on it.
 - Preserve existing `handleRun` error mapping: `ErrNotTested` → 409 "accounts must pass connection tests first"; `ErrAlreadyRunning` → 409 "task is already running".
 - Frontend has no unit-test harness; frontend tasks verify via `npm run build` + `tsc --noEmit` + manual app check.
 - Follow existing code style: no new dependencies.
 ---
 ### Task 1: Orchestrator account filter + `Run` signature
 **Files:**
 - Modify: `internal/orchestrator/orchestrator.go`
 - Test: `internal/orchestrator/orchestrator_test.go`
 **Interfaces:**
 - Produces:
  - `func selectAccounts(accs []store.Account, ids []int64) []store.Account` — returns `accs` unchanged when `ids` is empty/nil; otherwise returns only the accounts whose `ID` is in `ids`, preserving input order.
  - `var ErrNoAccountsSelected = errors.New("no matching accounts selected")`
  - `func (o *Orchestrator) Run(ctx context.Context, taskID int64, trigger string, accountIDs []int64) (int64, error)` — new trailing `accountIDs` param.
 - [ ] **Step 1: Write the failing test**
 Add to `internal/orchestrator/orchestrator_test.go`:
 ```go
 func TestSelectAccounts(t *testing.T) {
 	accs := []store.Account{{ID: 1}, {ID: 2}, {ID: 3}}
 	if got := selectAccounts(accs, nil); len(got) != 3 {
 		t.Fatalf("nil ids must return all, got %d", len(got))
 	}
 	if got := selectAccounts(accs, []int64{}); len(got) != 3 {
 		t.Fatalf("empty ids must return all, got %d", len(got))
 	}
 	got := selectAccounts(accs, []int64{3, 1})
 	if len(got) != 2 || got[0].ID != 1 || got[1].ID != 3 {
 		t.Fatalf("must keep matching ids in input order, got %+v", got)
 	}
 	if got := selectAccounts(accs, []int64{99}); len(got) != 0 {
 		t.Fatalf("unknown ids must yield empty, got %d", len(got))
 	}
 }
 ```
 - [ ] **Step 2: Run test to verify it fails**
 Run: `go test ./internal/orchestrator/ -run TestSelectAccounts -v`
 Expected: FAIL — `undefined: selectAccounts`.
 - [ ] **Step 3: Add the filter helper and sentinel error**
 In `internal/orchestrator/orchestrator.go`, add the sentinel next to the existing `var ErrNotTested`/`ErrAlreadyRunning`:
 ```go
 var ErrNoAccountsSelected = errors.New("no matching accounts selected")
 ```
 Add the helper (place it near `gateOK`):
 ```go
 // selectAccounts narrows accs to those whose ID is in ids, preserving input
 // order. An empty or nil ids means "all accounts" — the scheduler and the
 // unfiltered manual run rely on this.
 func selectAccounts(accs []store.Account, ids []int64) []store.Account {
 	if len(ids) == 0 {
 		return accs
 	}
 	want := make(map[int64]struct{}, len(ids))
 	for _, id := range ids {
 		want[id] = struct{}{}
 	}
 	out := make([]store.Account, 0, len(ids))
 	for _, a := range accs {
 		if _, ok := want[a.ID]; ok {
 			out = append(out, a)
 		}
 	}
 	return out
 }
 ```
 - [ ] **Step 4: Run test to verify it passes**
 Run: `go test ./internal/orchestrator/ -run TestSelectAccounts -v`
 Expected: PASS.
 - [ ] **Step 5: Thread `accountIDs` through `Run`**
 In `internal/orchestrator/orchestrator.go`, change the `Run` signature and apply the filter after loading accounts. Replace:
 ```go
 func (o *Orchestrator) Run(ctx context.Context, taskID int64, trigger string) (int64, error) {
 	task, err := o.store.GetTask(ctx, taskID)
 	if err != nil {
 		return 0, err
 	}
 	accs, err := o.store.ListAccountsByTask(ctx, taskID)
 	if err != nil {
 		return 0, err
 	}
 	if !gateOK(accs) {
 		return 0, ErrNotTested
 	}
 ```
 with:
 ```go
 func (o *Orchestrator) Run(ctx context.Context, taskID int64, trigger string, accountIDs []int64) (int64, error) {
 	task, err := o.store.GetTask(ctx, taskID)
 	if err != nil {
 		return 0, err
 	}
 	accs, err := o.store.ListAccountsByTask(ctx, taskID)
 	if err != nil {
 		return 0, err
 	}
 	accs = selectAccounts(accs, accountIDs)
 	// A non-empty request that matched nothing is a client error, distinct
 	// from "not tested".
 	if len(accountIDs) > 0 && len(accs) == 0 {
 		return 0, ErrNoAccountsSelected
 	}
 	if !gateOK(accs) {
 		return 0, ErrNotTested
 	}
 ```
 The rest of `Run` (endpoints, `TryMarkTaskRunning`, `CreateRun`, `go o.runAll(...)`) is unchanged — it already operates over the `accs` slice.
 - [ ] **Step 6: Update the two `Run` call sites so the package compiles**
 In `internal/scheduler/scheduler.go`, change:
 ```go
 if _, err := s.orch.Run(ctx, id, "scheduled"); err != nil {
 ```
 to:
 ```go
 if _, err := s.orch.Run(ctx, id, "scheduled", nil); err != nil {
 ```
 In `internal/httpapi/run.go`, inside `handleRun`, change:
 ```go
 runID, err := s.orch.Run(r.Context(), taskID, "manual")
 ```
 to (IDs wired in Task 2; for now pass `nil` to keep it compiling):
 ```go
 runID, err := s.orch.Run(r.Context(), taskID, "manual", nil)
 ```
 - [ ] **Step 7: Verify the whole backend builds and tests pass**
 Run: `go build ./... && go test ./internal/orchestrator/ ./internal/scheduler/ -v`
 Expected: build succeeds; all tests PASS.
 - [ ] **Step 8: Commit**
 ```bash
 git add internal/orchestrator/orchestrator.go internal/orchestrator/orchestrator_test.go internal/scheduler/scheduler.go internal/httpapi/run.go
 git commit -m "Add selectAccounts filter and accountIDs param to orchestrator.Run"
 ```
 ---
 ### Task 2: `handleRun` parses optional `account_ids`
 **Files:**
 - Modify: `internal/httpapi/run.go`
 - Test: `internal/httpapi/run_test.go`
 **Interfaces:**
 - Consumes: `orchestrator.Run(ctx, taskID, "manual", accountIDs)`, `orchestrator.ErrNoAccountsSelected` (Task 1).
 - Produces:
  - `func parseRunAccountIDs(r *http.Request) ([]int64, error)` — returns `nil` for an empty body; otherwise decodes `{"account_ids":[...]}` and returns the slice (possibly empty). Returns an error on malformed JSON.
 - [ ] **Step 1: Write the failing test**
 Add to `internal/httpapi/run_test.go` (the `strings` import is already present):
 ```go
 func TestParseRunAccountIDs(t *testing.T) {
 	// empty body => nil (run all)
 	req := httptest.NewRequest("POST", "/api/tasks/1/run", strings.NewReader(""))
 	ids, err := parseRunAccountIDs(req)
 	if err != nil || ids != nil {
 		t.Fatalf("empty body must yield nil ids, got %v err=%v", ids, err)
 	}
 	// explicit selection
 	req = httptest.NewRequest("POST", "/api/tasks/1/run", strings.NewReader(`{"account_ids":[3,7]}`))
 	ids, err = parseRunAccountIDs(req)
 	if err != nil || len(ids) != 2 || ids[0] != 3 || ids[1] != 7 {
 		t.Fatalf("must parse account_ids, got %v err=%v", ids, err)
 	}
 	// malformed JSON => error
 	req = httptest.NewRequest("POST", "/api/tasks/1/run", strings.NewReader(`{bad`))
 	if _, err := parseRunAccountIDs(req); err == nil {
 		t.Fatal("malformed body must error")
 	}
 }
 ```
 - [ ] **Step 2: Run test to verify it fails**
 Run: `go test ./internal/httpapi/ -run TestParseRunAccountIDs -v`
 Expected: FAIL — `undefined: parseRunAccountIDs`.
 - [ ] **Step 3: Implement `parseRunAccountIDs` and wire it into `handleRun`**
 In `internal/httpapi/run.go`, add the imports `encoding/json` and `io` to the existing import block, then add the helper:
 ```go
 // parseRunAccountIDs reads an optional {"account_ids":[...]} run body. An empty
 // body means "all accounts" and yields a nil slice. Malformed JSON is an error.
 func parseRunAccountIDs(r *http.Request) ([]int64, error) {
 	raw, err := io.ReadAll(r.Body)
 	if err != nil {
 		return nil, err
 	}
 	if len(bytes.TrimSpace(raw)) == 0 {
 		return nil, nil
 	}
 	var body struct {
 		AccountIDs []int64 `json:"account_ids"`
 	}
 	if err := json.Unmarshal(raw, &body); err != nil {
 		return nil, err
 	}
 	return body.AccountIDs, nil
 }
 ```
 Add `"bytes"` to the import block as well (used by `bytes.TrimSpace`).
 Then replace the body of `handleRun`'s run call. Change:
 ```go
 	runID, err := s.orch.Run(r.Context(), taskID, "manual", nil)
 	if errors.Is(err, orchestrator.ErrNotTested) {
 		http.Error(w, "accounts must pass connection tests first", http.StatusConflict)
 		return
 	}
 	if errors.Is(err, orchestrator.ErrAlreadyRunning) {
 		http.Error(w, "task is already running", http.StatusConflict)
 		return
 	}
 ```
 to:
 ```go
 	accountIDs, err := parseRunAccountIDs(r)
 	if err != nil {
 		http.Error(w, "bad request body", http.StatusBadRequest)
 		return
 	}
 	runID, err := s.orch.Run(r.Context(), taskID, "manual", accountIDs)
 	if errors.Is(err, orchestrator.ErrNoAccountsSelected) {
 		http.Error(w, "no matching accounts selected", http.StatusBadRequest)
 		return
 	}
 	if errors.Is(err, orchestrator.ErrNotTested) {
 		http.Error(w, "accounts must pass connection tests first", http.StatusConflict)
 		return
 	}
 	if errors.Is(err, orchestrator.ErrAlreadyRunning) {
 		http.Error(w, "task is already running", http.StatusConflict)
 		return
 	}
 ```
 - [ ] **Step 4: Run test to verify it passes**
 Run: `go test ./internal/httpapi/ -run TestParseRunAccountIDs -v`
 Expected: PASS.
 - [ ] **Step 5: Verify the whole backend builds and the httpapi suite passes**
 Run: `go build ./... && go test ./internal/httpapi/ -v`
 Expected: build succeeds; all tests PASS.
 - [ ] **Step 6: Commit**
 ```bash
 git add internal/httpapi/run.go internal/httpapi/run_test.go
 git commit -m "Parse optional account_ids in run handler"
 ```
 ---
 ### Task 3: Frontend `runTask` accepts account IDs
 **Files:**
 - Modify: `web/src/api.ts:141`
 **Interfaces:**
 - Produces: `runTask(id: number, accountIds?: number[]) => Promise<...>` — sends `{account_ids}` JSON only when a non-empty list is given; otherwise a bare POST (all accounts).
 - [ ] **Step 1: Update `runTask`**
 In `web/src/api.ts`, replace:
 ```ts
 export const runTask = (id: number) => api(`/api/tasks/${id}/run`, { method: 'POST' })
 ```
 with:
 ```ts
 export const runTask = (id: number, accountIds?: number[]) =>
  api(`/api/tasks/${id}/run`, accountIds?.length ? jsonBody({ account_ids: accountIds }) : { method: 'POST' })
 ```
 - [ ] **Step 2: Verify typecheck**
 Run: `cd web && npx tsc --noEmit`
 Expected: no errors from `api.ts` (pre-existing warnings elsewhere, if any, are unrelated).
 - [ ] **Step 3: Commit**
 ```bash
 git add web/src/api.ts
 git commit -m "runTask accepts optional accountIds"
 ```
 ---
 ### Task 4: Accounts table checkboxes + selective Run button
 **Files:**
 - Modify: `web/src/pages/TaskDetail.tsx`
 - Modify: `web/src/app.css`
 **Interfaces:**
 - Consumes: `runTask(id, accountIds?)` (Task 3).
 - Produces: no exported interface; internal UI state only.
 - [ ] **Step 1: Add selection state and helpers**
 In `web/src/pages/TaskDetail.tsx`, add a state hook next to the other `useState` declarations (near line 90):
 ```tsx
  const [selected, setSelected] = useState<Set<number>>(new Set())
 ```
 - [ ] **Step 2: Compute selectable rows and the effective run set**
 After the existing `const { task, accounts } = data` / `allTested` block (near line 369), add:
 ```tsx
  const isRunning = task.status === 'running'
  // A row is selectable only when both connection tests pass and no run is live.
  const selectableIds = accounts
    .filter((a) => a.test_src_status === 'ok' && a.test_dst_status === 'ok')
    .map((a) => a.id)
  const selectableSet = new Set(selectableIds)
  // Effective set: the checked accounts, or all accounts when nothing is checked.
  const effectiveSelected = accounts.filter((a) => selected.has(a.id))
  const runSet = effectiveSelected.length > 0 ? effectiveSelected : accounts
  const runReady =
    runSet.length > 0 && runSet.every((a) => a.test_src_status === 'ok' && a.test_dst_status === 'ok')
  const allSelectableChecked =
    selectableIds.length > 0 && selectableIds.every((id) => selected.has(id))
  const someSelectableChecked = selectableIds.some((id) => selected.has(id))
  function toggleOne(accId: number, checked: boolean) {
    setSelected((prev) => {
      const next = new Set(prev)
      if (checked) next.add(accId)
      else next.delete(accId)
      return next
    })
  }
  function toggleAll(checked: boolean) {
    setSelected(checked ? new Set(selectableIds) : new Set())
  }
 ```
 - [ ] **Step 3: Make `onRun` send the selection**
 Replace the existing `onRun` function (near line 331):
 ```tsx
  async function onRun() {
    setBusy('run')
    setError(null)
    try {
      await runTask(id)
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Failed to start run')
    } finally {
      setBusy(null)
    }
  }
 ```
 with:
 ```tsx
  async function onRun() {
    setBusy('run')
    setError(null)
    try {
      const ids = accounts.filter((a) => selected.has(a.id)).map((a) => a.id)
      await runTask(id, ids.length ? ids : undefined)
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Failed to start run')
    } finally {
      setBusy(null)
    }
  }
 ```
 - [ ] **Step 4: Update the Run button label and gate**
 Replace the run button (near line 421):
 ```tsx
          <button className="btn btn-primary" onClick={onRun} disabled={busy !== null || !allTested || task.status === 'running'}>
            {busy === 'run' ? 'Starting…' : 'Run migration'}
          </button>
          {!allTested && accounts.length > 0 && <span className="hint">run unlocks once every account tests OK on both sides</span>}
 ```
 with:
 ```tsx
          <button className="btn btn-primary" onClick={onRun} disabled={busy !== null || !runReady || isRunning}>
            {busy === 'run'
              ? 'Starting…'
              : effectiveSelected.length > 0
                ? `Run selected (${effectiveSelected.length})`
                : 'Run migration'}
          </button>
          {!runReady && accounts.length > 0 && (
            <span className="hint">
              {effectiveSelected.length > 0
                ? 'selected accounts must pass both connection tests'
                : 'run unlocks once every account tests OK on both sides'}
            </span>
          )}
 ```
 - [ ] **Step 5: Add the checkbox header column**
 In the accounts table `<thead><tr>` (near line 542), add a leading `<th>` before `<th>Account</th>`:
 ```tsx
                <th className="chk-col">
                  <input
                    type="checkbox"
                    aria-label="Select all accounts"
                    checked={allSelectableChecked}
                    ref={(el) => {
                      if (el) el.indeterminate = !allSelectableChecked && someSelectableChecked
                    }}
                    disabled={isRunning || selectableIds.length === 0}
                    onChange={(e) => toggleAll(e.target.checked)}
                  />
                </th>
 ```
 - [ ] **Step 6: Add the per-row checkbox cell and fix the empty-row colspan**
 In the empty-row branch (near line 557), change `colSpan={9}` to `colSpan={10}`.
 In the account `<tr>` map (near line 561), add a leading `<td>` as the first child, before the `<td>` with `acct-ident`:
 ```tsx
                    <td className="chk-col">
                      <input
                        type="checkbox"
                        aria-label={`Select ${a.src_login}`}
                        checked={selected.has(a.id)}
                        disabled={isRunning || !selectableSet.has(a.id)}
                        onChange={(e) => toggleOne(a.id, e.target.checked)}
                      />
                    </td>
 ```
 - [ ] **Step 7: Add checkbox column CSS**
 In `web/src/app.css`, append:
 ```css
 .tbl .chk-col {
  width: 32px;
  text-align: center;
  padding-right: 0;
 }
 .tbl .chk-col input[type='checkbox'] {
  cursor: pointer;
 }
 .tbl .chk-col input[type='checkbox']:disabled {
  cursor: not-allowed;
  opacity: 0.4;
 }
 ```
 - [ ] **Step 8: Build and typecheck**
 Run: `cd web && npx tsc --noEmit && npm run build`
 Expected: typecheck clean (any pre-existing oxlint/fast-refresh warnings are unrelated); Vite build succeeds.
 - [ ] **Step 9: Manual verification in the running app**
 Start the app, open a task with ≥2 accounts that have passed both tests:
 1. With nothing checked, the button reads "Run migration" and runs all accounts (confirm `account_started` WS events for every account).
 2. Check a subset; the button reads "Run selected (N)". Run it; confirm only the checked accounts start, and the unchecked accounts' Copied/Skipped/Status are untouched.
 3. Confirm checkboxes for untested accounts are disabled, and the header checkbox toggles only the selectable rows.
 - [ ] **Step 10: Commit**
 ```bash
 git add web/src/pages/TaskDetail.tsx web/src/app.css
 git commit -m "Add account selection checkboxes and selective run button"
 ```
 ---
 ## Notes for the executor
 - Tasks 1 and 2 are backend and must land in order (Task 2 depends on the new `Run` signature and `ErrNoAccountsSelected`). Task 3 and 4 are frontend; Task 4 depends on Task 3.
 - The orchestrator's `Run` is integration-heavy (spawns goroutines, needs a real store/hub), so it is not unit-tested directly; the pure `selectAccounts` filter and the `parseRunAccountIDs` helper carry the backend test coverage, and Task 4 Step 9 covers the end-to-end behavior manually.