diff --git a/apps/backend/AGENTS.md b/apps/backend/AGENTS.md index 88c238a374..1b625666a6 100644 --- a/apps/backend/AGENTS.md +++ b/apps/backend/AGENTS.md @@ -219,7 +219,7 @@ Client (WS) ← Orchestrator ← Lifecycle Manager ←──── stream update - **Repository provider identity:** Provider-backed repositories are keyed by workspace, provider, normalized `provider_host` origin, full owner/namespace, and name. Persist `provider_host` when importing or resolving a remote; do not infer self-managed GitLab rows from owner/name alone. Legacy rows with an empty host have unknown identity and must fail closed for provider write/link operations. - **PR status sync coverage:** A `github_pr_watches` row is unique per (session, repository, branch) and gets re-pointed when the session's branch moves on, so watches are not a complete index of a task's PRs; a watch-only sweep leaves every PR from an earlier branch frozen at its last-observed state, which the UI renders as an open, mergeable PR long after it merged. `service_pr_unwatched.go` reconciles the `github_task_prs` rows no watch points at, and deliberately writes **lifecycle fields only** (`state` / `merged_at` / `closed_at`) — check and review aggregates belong to the watch-driven sync that actually fetches reviews and check runs, and the per-PR REST status marks its counts populated even with nothing to count, so widening this path to aggregates persists 0/0 over good data (it broke six PR-popover e2e specs exactly that way). Terminal and detached rows are excluded so the set stays bounded. - **Execution access:** Workspace-oriented handlers (files, shell, inference, ports, vscode, LSP) MUST use `GetOrEnsureExecution(ctx, sessionID)` — it recovers from backend restarts by creating executions on-demand. Only use `GetExecutionBySessionID` for operations that require a running agent process (prompt, cancel, mode). -- **Task lifecycle events:** Any code path that mutates a task row must publish via the event bus (`task.created` / `task.updated` / `task.deleted`) — either by going through `Service.CreateTask` / `UpdateTask` / `DeleteTask` / `ArchiveTask`, or by calling `publishTaskEvent` (or one of the `Publish*` helpers in `service_events.go`) directly. Walking `repository.TaskRepository` straight bypasses event publishing and breaks WS-driven UI like the All-Workflows kanban view. `HandoffService`'s cascade methods learned this the hard way — they now require a `TaskEventPublisher` wired via `SetTaskEventPublisher`. New cascade / bulk / cleanup paths must follow the same pattern. +- **Task lifecycle events:** Any code path that mutates a task row must publish via the event bus (`task.created` / `task.updated` / `task.deleted`) — either by going through `Service.CreateTask` / `UpdateTask` / `DeleteTask` / `ArchiveTask`, or by calling `publishTaskEvent` (or one of the `Publish*` helpers in `service_events.go`) directly. Walking `repository.TaskRepository` straight bypasses event publishing and breaks WS-driven UI like the All-Workflows kanban view. `HandoffService`'s cascade methods learned this the hard way — they now require a `TaskEventPublisher` wired via `SetTaskEventPublisher`. New cascade / bulk / cleanup paths must follow the same pattern. **Workflow steps** follow the same rule with their own publisher: step create/update/delete publish `workflow_step.created` / `.updated` / `.deleted` through `internal/workflow/stepevents.Publisher` (the WS gateway fans them out; the orchestrator re-evaluates queue admission off `.updated`). Both mutation surfaces — REST/WS in `internal/workflow/handlers`, MCP in `internal/mcp/handlers` — share that publisher and differ only in the source label they pass, so a new step-mutation path uses it rather than hand-rolling the payload; promoting a start step demotes the previous one, so also publish `.updated` for every entry in `DemotedStartSteps`. - **Testing:** Prefer `testing/synctest` (Go 1.24+) over `time.Sleep` for time-dependent tests. Use `synctest.Test` to wrap tests with tickers or timeouts — it advances fake time instantly when all goroutines are idle. When `synctest` is not feasible (e.g., tests spawning external processes like `git`), use channel-based synchronization (`<-started`, non-blocking `select`) instead of sleep-based waits. Reserve `time.Sleep` only for integration tests that need real subprocess execution time. - **Test cleanup:** Register `t.Cleanup` immediately after creating resources that need teardown (adapters, `io.Pipe` writers, background goroutines) — before any `t.Fatal`/`t.Fatalf` path. Late cleanup registration leaks pipes and goroutines on early failure. - **Joining production goroutines in tests:** When code spawns untracked goroutines (e.g. `fireWakeup`), don't rely on arbitrary sleeps. Join via an observable side effect — e.g. block on `EventTypeComplete` from `a.updatesCh` after unblocking the fake agent. Use short timeouts (~100ms) for in-process negative assertions; reserve multi-second waits for subprocess/integration tests only. diff --git a/apps/backend/internal/mcp/handlers/config_workflow_handlers.go b/apps/backend/internal/mcp/handlers/config_workflow_handlers.go index 4df7218dda..c3073de2fa 100644 --- a/apps/backend/internal/mcp/handlers/config_workflow_handlers.go +++ b/apps/backend/internal/mcp/handlers/config_workflow_handlers.go @@ -5,10 +5,10 @@ import ( "encoding/json" "github.com/kandev/kandev/internal/events" - "github.com/kandev/kandev/internal/events/bus" "github.com/kandev/kandev/internal/task/service" workflowctrl "github.com/kandev/kandev/internal/workflow/controller" wfmodels "github.com/kandev/kandev/internal/workflow/models" + "github.com/kandev/kandev/internal/workflow/stepevents" ws "github.com/kandev/kandev/pkg/websocket" "go.uber.org/zap" "gopkg.in/yaml.v3" @@ -279,44 +279,24 @@ func (h *Handlers) handleReorderWorkflowSteps(ctx context.Context, msg *ws.Messa return ws.NewResponse(msg.ID, msg.Action, map[string]interface{}{"success": true}) } +// workflowStepEventSource labels workflow-step events published by this surface. +const workflowStepEventSource = "mcp-handlers" + +// workflowStepEvents returns the shared workflow-step publisher for this +// surface. Unlike the REST handlers, this Handlers value is assembled field by +// field — NewHandlers plus the Set* wiring, and tests build it as a struct +// literal — so eventBus is not final at construction. Building the publisher +// at publish time reads whatever bus is actually wired; the allocation is +// negligible next to the bus dispatch. +func (h *Handlers) workflowStepEvents() *stepevents.Publisher { + return stepevents.NewPublisher(h.eventBus, workflowStepEventSource, h.logger) +} + // publishWorkflowStepEvent publishes a workflow step event to the event bus. func (h *Handlers) publishWorkflowStepEvent(ctx context.Context, eventType string, step *wfmodels.WorkflowStep) { - if h.eventBus == nil || step == nil { - return - } - data := map[string]interface{}{ - "step": map[string]interface{}{ - "id": step.ID, - "workflow_id": step.WorkflowID, - "name": step.Name, - "position": step.Position, - "color": step.Color, - "prompt": step.Prompt, - "events": step.Events, - "show_in_command_panel": step.ShowInCommandPanel, - "allow_manual_move": step.AllowManualMove, - "is_start_step": step.IsStartStep, - "auto_archive_after_hours": step.AutoArchiveAfterHours, - "wip_limit": step.WIPLimit, - "pull_from_step_id": step.PullFromStepID, - "agent_profile_id": step.AgentProfileID, - "stage_type": string(step.StageType), - "auto_advance_requires_signal": step.AutoAdvanceRequiresSignal, - "cancel_triggers_turn_complete": step.CancelTriggersTurnComplete, - "created_at": step.CreatedAt, - "updated_at": step.UpdatedAt, - }, - } - if err := h.eventBus.Publish(ctx, eventType, bus.NewEvent(eventType, "mcp-handlers", data)); err != nil { - h.logger.Error("failed to publish workflow step event", - zap.String("event_type", eventType), - zap.String("step_id", step.ID), - zap.Error(err)) - } + h.workflowStepEvents().Publish(ctx, eventType, step) } func (h *Handlers) publishWorkflowStepEvents(ctx context.Context, eventType string, steps []*wfmodels.WorkflowStep) { - for _, step := range steps { - h.publishWorkflowStepEvent(ctx, eventType, step) - } + h.workflowStepEvents().PublishAll(ctx, eventType, steps) } diff --git a/apps/backend/internal/mcp/handlers/workflow_step_parity_test.go b/apps/backend/internal/mcp/handlers/workflow_step_parity_test.go new file mode 100644 index 0000000000..02b4ae5b4e --- /dev/null +++ b/apps/backend/internal/mcp/handlers/workflow_step_parity_test.go @@ -0,0 +1,243 @@ +package handlers + +import ( + "bytes" + "context" + "database/sql" + "encoding/json" + "net/http" + "net/http/httptest" + "reflect" + "testing" + + "github.com/gin-gonic/gin" + "github.com/jmoiron/sqlx" + _ "github.com/mattn/go-sqlite3" + "github.com/stretchr/testify/require" + + eventtypes "github.com/kandev/kandev/internal/events" + eventbus "github.com/kandev/kandev/internal/events/bus" + workflowctrl "github.com/kandev/kandev/internal/workflow/controller" + workflowhandlers "github.com/kandev/kandev/internal/workflow/handlers" + wfmodels "github.com/kandev/kandev/internal/workflow/models" + "github.com/kandev/kandev/internal/workflow/repository" + workflowsvc "github.com/kandev/kandev/internal/workflow/service" + ws "github.com/kandev/kandev/pkg/websocket" +) + +// The MCP surface (this package) and the REST surface +// (internal/workflow/handlers) both mutate workflow steps and both publish +// workflow_step.* events that the WS gateway and the orchestrator queue +// reconciler consume. The tests below pin that the two emit equivalent +// payloads for the same mutation, so the surfaces cannot drift apart again. +// They live here because this is the only package that can construct both. + +type paritySurfaceEvent struct { + subject string + source string + step map[string]interface{} +} + +func recordParityStepEvents(t *testing.T, eventBus *eventbus.MemoryEventBus) *[]paritySurfaceEvent { + t.Helper() + var recorded []paritySurfaceEvent + for _, subject := range []string{ + eventtypes.WorkflowStepCreated, + eventtypes.WorkflowStepUpdated, + eventtypes.WorkflowStepDeleted, + } { + _, err := eventBus.Subscribe(subject, func(_ context.Context, ev *eventbus.Event) error { + data, ok := ev.Data.(map[string]interface{}) + require.True(t, ok) + step, ok := data["step"].(map[string]interface{}) + require.True(t, ok) + recorded = append(recorded, paritySurfaceEvent{subject: ev.Subject, source: ev.Source, step: step}) + return nil + }) + require.NoError(t, err) + } + return &recorded +} + +// setupParitySurfaces wires the MCP handlers and the REST router over one +// workflow store and one event bus. +func setupParitySurfaces(t *testing.T) (*Handlers, *gin.Engine, *eventbus.MemoryEventBus) { + t.Helper() + rawDB, err := sql.Open("sqlite3", ":memory:") + require.NoError(t, err) + rawDB.SetMaxOpenConns(1) + db := sqlx.NewDb(rawDB, "sqlite3") + t.Cleanup(func() { _ = db.Close() }) + + _, err = db.Exec(`CREATE TABLE IF NOT EXISTS workflows ( + id TEXT PRIMARY KEY, workspace_id TEXT NOT NULL DEFAULT '', + workflow_template_id TEXT DEFAULT '', name TEXT NOT NULL, + description TEXT DEFAULT '', created_at TIMESTAMP NOT NULL, updated_at TIMESTAMP NOT NULL + )`) + require.NoError(t, err) + + repo, err := repository.NewWithDB(db, db, nil) + require.NoError(t, err) + + log := testLogger(t) + svc := workflowsvc.NewService(repo, log) + ctrl := workflowctrl.NewController(svc) + eventBus := eventbus.NewMemoryEventBus(log) + + mcp := &Handlers{workflowSvc: svc, workflowCtrl: ctrl, eventBus: eventBus, logger: log.WithFields()} + + gin.SetMode(gin.TestMode) + router := gin.New() + workflowhandlers.RegisterRoutes(router, ws.NewDispatcher(), ctrl, eventBus, log) + + return mcp, router, eventBus +} + +func parityHTTPJSON(t *testing.T, router *gin.Engine, method, path string, body interface{}, wantStatus int) []byte { + t.Helper() + payload, err := json.Marshal(body) + require.NoError(t, err) + req := httptest.NewRequest(method, path, bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + rec := httptest.NewRecorder() + router.ServeHTTP(rec, req) + require.Equal(t, wantStatus, rec.Code, "body = %s", rec.Body.String()) + return rec.Body.Bytes() +} + +// assertStepPayloadsEquivalent compares two step payloads field by field, +// ignoring keys whose values legitimately differ between two separate +// mutations (identity and timestamps). +func assertStepPayloadsEquivalent(t *testing.T, mcpStep, httpStep map[string]interface{}, ignore ...string) { + t.Helper() + skip := map[string]bool{} + for _, key := range ignore { + skip[key] = true + } + mcpKeys := make([]string, 0, len(mcpStep)) + for key := range mcpStep { + mcpKeys = append(mcpKeys, key) + } + for _, key := range mcpKeys { + _, ok := httpStep[key] + require.True(t, ok, "REST payload is missing %q that the MCP payload carries", key) + } + require.Len(t, httpStep, len(mcpStep), "payload key counts differ: mcp=%v http=%v", mcpStep, httpStep) + for key, mcpValue := range mcpStep { + if skip[key] { + continue + } + require.True(t, reflect.DeepEqual(mcpValue, httpStep[key]), + "field %q differs: mcp=%#v http=%#v", key, mcpValue, httpStep[key]) + } +} + +func TestWorkflowStepCreateEventParityAcrossSurfaces(t *testing.T) { + mcp, router, eventBus := setupParitySurfaces(t) + ctx := context.Background() + recorded := recordParityStepEvents(t, eventBus) + + stepFields := map[string]interface{}{ + "workflow_id": "wf-parity", + "name": "Review", + "color": "#abcdef", + "prompt": "review the diff", + "allow_manual_move": true, + "show_in_command_panel": true, + "auto_advance_requires_signal": true, + "cancel_triggers_turn_complete": true, + "wip_limit": 4, + } + + mcpPayload := map[string]interface{}{"position": 0} + httpPayload := map[string]interface{}{"position": 1} + for key, value := range stepFields { + mcpPayload[key] = value + httpPayload[key] = value + } + + resp, err := mcp.handleCreateWorkflowStep(ctx, makeWSMessage(t, ws.ActionMCPCreateWorkflowStep, mcpPayload)) + require.NoError(t, err) + require.NotEqual(t, ws.MessageTypeError, resp.Type, "mcp create failed: %s", string(resp.Payload)) + + parityHTTPJSON(t, router, http.MethodPost, "/api/v1/workflow/steps", httpPayload, http.StatusCreated) + + require.Len(t, *recorded, 2, "each surface should publish exactly one created event") + mcpEvent, httpEvent := (*recorded)[0], (*recorded)[1] + require.Equal(t, eventtypes.WorkflowStepCreated, mcpEvent.subject) + require.Equal(t, eventtypes.WorkflowStepCreated, httpEvent.subject) + require.Equal(t, "mcp-handlers", mcpEvent.source) + require.Equal(t, "workflow-handlers", httpEvent.source) + assertStepPayloadsEquivalent(t, mcpEvent.step, httpEvent.step, "id", "position", "created_at", "updated_at") +} + +func TestWorkflowStepUpdateEventParityAcrossSurfaces(t *testing.T) { + mcp, router, eventBus := setupParitySurfaces(t) + ctx := context.Background() + + created := parityHTTPJSON(t, router, http.MethodPost, "/api/v1/workflow/steps", map[string]interface{}{ + "workflow_id": "wf-parity", + "name": "Backlog", + "position": 0, + }, http.StatusCreated) + var step wfmodels.WorkflowStep + require.NoError(t, json.Unmarshal(created, &step)) + + recorded := recordParityStepEvents(t, eventBus) + + update := map[string]interface{}{"name": "Triage", "wip_limit": 7, "prompt": "triage it"} + mcpUpdate := map[string]interface{}{"step_id": step.ID} + for key, value := range update { + mcpUpdate[key] = value + } + + resp, err := mcp.handleUpdateWorkflowStep(ctx, makeWSMessage(t, ws.ActionMCPUpdateWorkflowStep, mcpUpdate)) + require.NoError(t, err) + require.NotEqual(t, ws.MessageTypeError, resp.Type, "mcp update failed: %s", string(resp.Payload)) + + parityHTTPJSON(t, router, http.MethodPut, "/api/v1/workflow/steps/"+step.ID, update, http.StatusOK) + + require.Len(t, *recorded, 2, "each surface should publish exactly one updated event") + mcpEvent, httpEvent := (*recorded)[0], (*recorded)[1] + require.Equal(t, eventtypes.WorkflowStepUpdated, mcpEvent.subject) + require.Equal(t, eventtypes.WorkflowStepUpdated, httpEvent.subject) + require.Equal(t, "mcp-handlers", mcpEvent.source) + require.Equal(t, "workflow-handlers", httpEvent.source) + // Same step, same edit through both surfaces: only the write timestamp may differ. + assertStepPayloadsEquivalent(t, mcpEvent.step, httpEvent.step, "updated_at") +} + +func TestWorkflowStepDeleteEventParityAcrossSurfaces(t *testing.T) { + mcp, router, eventBus := setupParitySurfaces(t) + ctx := context.Background() + + newStep := func(name string, position int) wfmodels.WorkflowStep { + body := parityHTTPJSON(t, router, http.MethodPost, "/api/v1/workflow/steps", map[string]interface{}{ + "workflow_id": "wf-parity", + "name": name, + "position": position, + "color": "#abcdef", + }, http.StatusCreated) + var step wfmodels.WorkflowStep + require.NoError(t, json.Unmarshal(body, &step)) + return step + } + mcpStep := newStep("Doomed A", 0) + httpStep := newStep("Doomed A", 1) + + recorded := recordParityStepEvents(t, eventBus) + + resp, err := mcp.handleDeleteWorkflowStep(ctx, makeWSMessage(t, ws.ActionMCPDeleteWorkflowStep, map[string]interface{}{ + "step_id": mcpStep.ID, + })) + require.NoError(t, err) + require.NotEqual(t, ws.MessageTypeError, resp.Type, "mcp delete failed: %s", string(resp.Payload)) + + parityHTTPJSON(t, router, http.MethodDelete, "/api/v1/workflow/steps/"+httpStep.ID, nil, http.StatusOK) + + require.Len(t, *recorded, 2, "each surface should publish exactly one deleted event") + mcpEvent, httpEvent := (*recorded)[0], (*recorded)[1] + require.Equal(t, eventtypes.WorkflowStepDeleted, mcpEvent.subject) + require.Equal(t, eventtypes.WorkflowStepDeleted, httpEvent.subject) + assertStepPayloadsEquivalent(t, mcpEvent.step, httpEvent.step, "id", "position", "created_at", "updated_at") +} diff --git a/apps/backend/internal/workflow/handlers/handlers.go b/apps/backend/internal/workflow/handlers/handlers.go index e824b4b0bc..e3f5c5361a 100644 --- a/apps/backend/internal/workflow/handlers/handlers.go +++ b/apps/backend/internal/workflow/handlers/handlers.go @@ -17,22 +17,29 @@ import ( "github.com/kandev/kandev/internal/workflow/controller" "github.com/kandev/kandev/internal/workflow/models" "github.com/kandev/kandev/internal/workflow/service" + "github.com/kandev/kandev/internal/workflow/stepevents" ws "github.com/kandev/kandev/pkg/websocket" ) +// stepEventSource labels workflow-step events published by this surface. +const stepEventSource = "workflow-handlers" + // Handlers manages workflow HTTP and WebSocket handlers type Handlers struct { controller *controller.Controller eventBus bus.EventBus + stepEvents *stepevents.Publisher logger *logger.Logger } // NewHandlers creates new workflow handlers func NewHandlers(ctrl *controller.Controller, eventBus bus.EventBus, log *logger.Logger) *Handlers { + scoped := log.WithFields(zap.String("component", "workflow-handlers")) return &Handlers{ controller: ctrl, eventBus: eventBus, - logger: log.WithFields(zap.String("component", "workflow-handlers")), + stepEvents: stepevents.NewPublisher(eventBus, stepEventSource, scoped), + logger: scoped, } } @@ -165,12 +172,15 @@ func (h *Handlers) httpCreateStep(c *gin.Context) { c.JSON(http.StatusBadRequest, gin.H{"error": "workflow_id and name are required"}) return } - resp, err := h.controller.CreateStep(c.Request.Context(), req) + ctx := c.Request.Context() + resp, err := h.controller.CreateStep(ctx, req) if err != nil { h.logger.Error("failed to create step", zap.Error(err)) h.writeStepMutationError(c, err) return } + h.publishWorkflowStepEvents(ctx, events.WorkflowStepUpdated, resp.DemotedStartSteps) + h.publishWorkflowStepEvent(ctx, events.WorkflowStepCreated, resp.Step) c.JSON(http.StatusCreated, resp.Step) } @@ -181,12 +191,15 @@ func (h *Handlers) httpUpdateStep(c *gin.Context) { return } req.ID = c.Param("id") - resp, err := h.controller.UpdateStep(c.Request.Context(), req) + ctx := c.Request.Context() + resp, err := h.controller.UpdateStep(ctx, req) if err != nil { h.logger.Error("failed to update step", zap.Error(err)) h.writeStepMutationError(c, err) return } + h.publishWorkflowStepEvents(ctx, events.WorkflowStepUpdated, resp.DemotedStartSteps) + h.publishWorkflowStepEvent(ctx, events.WorkflowStepUpdated, resp.Step) c.JSON(http.StatusOK, resp.Step) } @@ -234,38 +247,11 @@ func (h *Handlers) httpDeleteStep(c *gin.Context) { } func (h *Handlers) publishWorkflowStepEvent(ctx context.Context, eventType string, step *models.WorkflowStep) { - if step == nil { - return - } - data := map[string]interface{}{ - "step": map[string]interface{}{ - "id": step.ID, - "workflow_id": step.WorkflowID, - "name": step.Name, - "position": step.Position, - "color": step.Color, - "prompt": step.Prompt, - "events": step.Events, - "show_in_command_panel": step.ShowInCommandPanel, - "allow_manual_move": step.AllowManualMove, - "is_start_step": step.IsStartStep, - "auto_archive_after_hours": step.AutoArchiveAfterHours, - "wip_limit": step.WIPLimit, - "pull_from_step_id": step.PullFromStepID, - "agent_profile_id": step.AgentProfileID, - "stage_type": string(step.StageType), - "auto_advance_requires_signal": step.AutoAdvanceRequiresSignal, - "cancel_triggers_turn_complete": step.CancelTriggersTurnComplete, - "created_at": step.CreatedAt, - "updated_at": step.UpdatedAt, - }, - } - if err := h.eventBus.Publish(ctx, eventType, bus.NewEvent(eventType, "workflow-handlers", data)); err != nil { - h.logger.Error("failed to publish workflow step event", - zap.String("event_type", eventType), - zap.String("step_id", step.ID), - zap.Error(err)) - } + h.stepEvents.Publish(ctx, eventType, step) +} + +func (h *Handlers) publishWorkflowStepEvents(ctx context.Context, eventType string, steps []*models.WorkflowStep) { + h.stepEvents.PublishAll(ctx, eventType, steps) } type httpReorderStepsRequest struct { diff --git a/apps/backend/internal/workflow/handlers/step_events_test.go b/apps/backend/internal/workflow/handlers/step_events_test.go new file mode 100644 index 0000000000..057e87a8dd --- /dev/null +++ b/apps/backend/internal/workflow/handlers/step_events_test.go @@ -0,0 +1,304 @@ +package handlers + +import ( + "bytes" + "context" + "database/sql" + "encoding/json" + "net/http" + "net/http/httptest" + "testing" + + "github.com/gin-gonic/gin" + "github.com/jmoiron/sqlx" + _ "github.com/mattn/go-sqlite3" + + "github.com/kandev/kandev/internal/common/logger" + "github.com/kandev/kandev/internal/events" + "github.com/kandev/kandev/internal/events/bus" + "github.com/kandev/kandev/internal/workflow/controller" + "github.com/kandev/kandev/internal/workflow/models" + "github.com/kandev/kandev/internal/workflow/repository" + "github.com/kandev/kandev/internal/workflow/service" +) + +type stepEvent struct { + subject string + source string + step map[string]interface{} +} + +type stepEventRecorder struct { + events []stepEvent +} + +// recordStepEvents subscribes to every workflow_step.* subject so a test can +// assert not only that the expected event fired but that no extra one did — a +// duplicate publish added elsewhere in the stack shows up here. +func recordStepEvents(t *testing.T, eventBus *bus.MemoryEventBus) *stepEventRecorder { + t.Helper() + rec := &stepEventRecorder{} + for _, subject := range []string{events.WorkflowStepCreated, events.WorkflowStepUpdated, events.WorkflowStepDeleted} { + if _, err := eventBus.Subscribe(subject, func(_ context.Context, ev *bus.Event) error { + data, ok := ev.Data.(map[string]interface{}) + if !ok { + t.Errorf("event data type = %T, want map", ev.Data) + return nil + } + step, ok := data["step"].(map[string]interface{}) + if !ok { + t.Errorf("step payload type = %T, want map", data["step"]) + return nil + } + rec.events = append(rec.events, stepEvent{subject: ev.Subject, source: ev.Source, step: step}) + return nil + }); err != nil { + t.Fatalf("subscribe %s: %v", subject, err) + } + } + return rec +} + +func (r *stepEventRecorder) subjects() []string { + subjects := make([]string, 0, len(r.events)) + for _, ev := range r.events { + subjects = append(subjects, ev.subject) + } + return subjects +} + +func (r *stepEventRecorder) only(t *testing.T, subject string) stepEvent { + t.Helper() + if len(r.events) != 1 { + t.Fatalf("published %v, want exactly one %s", r.subjects(), subject) + } + if r.events[0].subject != subject { + t.Fatalf("subject = %q, want %q", r.events[0].subject, subject) + } + if r.events[0].source != stepEventSource { + t.Fatalf("source = %q, want %q", r.events[0].source, stepEventSource) + } + return r.events[0] +} + +func setupStepRouter(t *testing.T) (*gin.Engine, *bus.MemoryEventBus, *repository.Repository) { + t.Helper() + rawDB, err := sql.Open("sqlite3", ":memory:") + if err != nil { + t.Fatalf("open sqlite: %v", err) + } + // Pin the pool to one connection: every connection to an in-memory SQLite + // DB gets its own database, so a second one would not see the schema. + rawDB.SetMaxOpenConns(1) + db := sqlx.NewDb(rawDB, "sqlite3") + t.Cleanup(func() { _ = db.Close() }) + + // The workflows table is owned by the task repo; the workflow repo's schema + // init reads it while seeding, so create it for the test. + if _, err = db.Exec(`CREATE TABLE IF NOT EXISTS workflows ( + id TEXT PRIMARY KEY, workspace_id TEXT NOT NULL DEFAULT '', + workflow_template_id TEXT DEFAULT '', name TEXT NOT NULL, + description TEXT DEFAULT '', created_at TIMESTAMP NOT NULL, updated_at TIMESTAMP NOT NULL + )`); err != nil { + t.Fatalf("create workflows table: %v", err) + } + + repo, err := repository.NewWithDB(db, db, nil) + if err != nil { + t.Fatalf("new repository: %v", err) + } + log := logger.Default() + eventBus := bus.NewMemoryEventBus(log) + h := NewHandlers(controller.NewController(service.NewService(repo, log)), eventBus, log) + + gin.SetMode(gin.TestMode) + router := gin.New() + h.registerHTTP(router) + return router, eventBus, repo +} + +func doJSON(t *testing.T, router *gin.Engine, method, path string, body interface{}) *httptest.ResponseRecorder { + t.Helper() + var payload []byte + if body != nil { + var err error + payload, err = json.Marshal(body) + if err != nil { + t.Fatalf("marshal body: %v", err) + } + } + req := httptest.NewRequest(method, path, bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + rec := httptest.NewRecorder() + router.ServeHTTP(rec, req) + return rec +} + +func createStepViaHTTP(t *testing.T, router *gin.Engine, body map[string]interface{}) *models.WorkflowStep { + t.Helper() + rec := doJSON(t, router, http.MethodPost, "/api/v1/workflow/steps", body) + if rec.Code != http.StatusCreated { + t.Fatalf("create status = %d, body = %s", rec.Code, rec.Body.String()) + } + var step models.WorkflowStep + if err := json.Unmarshal(rec.Body.Bytes(), &step); err != nil { + t.Fatalf("decode created step: %v", err) + } + return &step +} + +func TestHTTPCreateStepPublishesCreatedEvent(t *testing.T) { + router, eventBus, _ := setupStepRouter(t) + rec := recordStepEvents(t, eventBus) + + step := createStepViaHTTP(t, router, map[string]interface{}{ + "workflow_id": "workflow-1", + "name": "Backlog", + "position": 0, + "color": "#123456", + }) + + got := rec.only(t, events.WorkflowStepCreated) + if got.step["id"] != step.ID { + t.Errorf("event step id = %v, want %q", got.step["id"], step.ID) + } + if got.step["workflow_id"] != "workflow-1" || got.step["name"] != "Backlog" { + t.Errorf("unexpected step payload: %#v", got.step) + } +} + +func TestHTTPUpdateStepPublishesUpdatedEvent(t *testing.T) { + router, eventBus, _ := setupStepRouter(t) + step := createStepViaHTTP(t, router, map[string]interface{}{ + "workflow_id": "workflow-1", + "name": "Backlog", + "position": 0, + }) + rec := recordStepEvents(t, eventBus) + + resp := doJSON(t, router, http.MethodPut, "/api/v1/workflow/steps/"+step.ID, map[string]interface{}{ + "name": "Triage", + "wip_limit": 3, + }) + if resp.Code != http.StatusOK { + t.Fatalf("update status = %d, body = %s", resp.Code, resp.Body.String()) + } + + got := rec.only(t, events.WorkflowStepUpdated) + if got.step["id"] != step.ID || got.step["name"] != "Triage" { + t.Errorf("unexpected step payload: %#v", got.step) + } + if wip, ok := got.step["wip_limit"].(int); !ok || wip != 3 { + t.Errorf("wip_limit = %#v, want 3", got.step["wip_limit"]) + } +} + +func TestHTTPDeleteStepPublishesDeletedEvent(t *testing.T) { + router, eventBus, _ := setupStepRouter(t) + step := createStepViaHTTP(t, router, map[string]interface{}{ + "workflow_id": "workflow-1", + "name": "Backlog", + "position": 0, + }) + rec := recordStepEvents(t, eventBus) + + resp := doJSON(t, router, http.MethodDelete, "/api/v1/workflow/steps/"+step.ID, nil) + if resp.Code != http.StatusOK { + t.Fatalf("delete status = %d, body = %s", resp.Code, resp.Body.String()) + } + + got := rec.only(t, events.WorkflowStepDeleted) + if got.step["id"] != step.ID { + t.Errorf("event step id = %v, want %q", got.step["id"], step.ID) + } +} + +func TestHTTPCreateStepPublishesDemotedStartSteps(t *testing.T) { + router, eventBus, _ := setupStepRouter(t) + oldStart := createStepViaHTTP(t, router, map[string]interface{}{ + "workflow_id": "workflow-1", + "name": "Old Start", + "position": 0, + "is_start_step": true, + }) + rec := recordStepEvents(t, eventBus) + + newStart := createStepViaHTTP(t, router, map[string]interface{}{ + "workflow_id": "workflow-1", + "name": "New Start", + "position": 1, + "is_start_step": true, + }) + + if len(rec.events) != 2 { + t.Fatalf("published %v, want one updated (demoted) plus one created", rec.subjects()) + } + demoted, created := rec.events[0], rec.events[1] + if demoted.subject != events.WorkflowStepUpdated || demoted.step["id"] != oldStart.ID { + t.Errorf("first event = %s for step %v, want %s for %q", + demoted.subject, demoted.step["id"], events.WorkflowStepUpdated, oldStart.ID) + } + if isStart, ok := demoted.step["is_start_step"].(bool); !ok || isStart { + t.Errorf("demoted step is_start_step = %#v, want false", demoted.step["is_start_step"]) + } + if created.subject != events.WorkflowStepCreated || created.step["id"] != newStart.ID { + t.Errorf("second event = %s for step %v, want %s for %q", + created.subject, created.step["id"], events.WorkflowStepCreated, newStart.ID) + } +} + +func TestHTTPUpdateStepPublishesDemotedStartSteps(t *testing.T) { + router, eventBus, _ := setupStepRouter(t) + oldStart := createStepViaHTTP(t, router, map[string]interface{}{ + "workflow_id": "workflow-1", + "name": "Old Start", + "position": 0, + "is_start_step": true, + }) + promoted := createStepViaHTTP(t, router, map[string]interface{}{ + "workflow_id": "workflow-1", + "name": "Doing", + "position": 1, + }) + rec := recordStepEvents(t, eventBus) + + resp := doJSON(t, router, http.MethodPut, "/api/v1/workflow/steps/"+promoted.ID, map[string]interface{}{ + "is_start_step": true, + }) + if resp.Code != http.StatusOK { + t.Fatalf("update status = %d, body = %s", resp.Code, resp.Body.String()) + } + + if len(rec.events) != 2 { + t.Fatalf("published %v, want one updated per demoted step plus one for the updated step", rec.subjects()) + } + if rec.events[0].step["id"] != oldStart.ID || rec.events[1].step["id"] != promoted.ID { + t.Errorf("event step ids = %v, %v; want %q then %q", + rec.events[0].step["id"], rec.events[1].step["id"], oldStart.ID, promoted.ID) + } + for _, ev := range rec.events { + if ev.subject != events.WorkflowStepUpdated { + t.Errorf("subject = %q, want %q", ev.subject, events.WorkflowStepUpdated) + } + } +} + +func TestHTTPStepMutationFailurePublishesNothing(t *testing.T) { + router, eventBus, _ := setupStepRouter(t) + step := createStepViaHTTP(t, router, map[string]interface{}{ + "workflow_id": "workflow-1", + "name": "Backlog", + "position": 0, + }) + rec := recordStepEvents(t, eventBus) + + resp := doJSON(t, router, http.MethodPut, "/api/v1/workflow/steps/"+step.ID, map[string]interface{}{ + "wip_limit": -1, + }) + if resp.Code != http.StatusBadRequest { + t.Fatalf("update status = %d, want 400; body = %s", resp.Code, resp.Body.String()) + } + if len(rec.events) != 0 { + t.Fatalf("published %v for a rejected update, want none", rec.subjects()) + } +} diff --git a/apps/backend/internal/workflow/stepevents/stepevents.go b/apps/backend/internal/workflow/stepevents/stepevents.go new file mode 100644 index 0000000000..a5840b2701 --- /dev/null +++ b/apps/backend/internal/workflow/stepevents/stepevents.go @@ -0,0 +1,88 @@ +// Package stepevents publishes workflow-step lifecycle events onto the shared +// event bus. +// +// Two surfaces mutate workflow steps — the REST/WS handlers in +// internal/workflow/handlers and the MCP handlers in internal/mcp/handlers — +// and their subscribers (the WS gateway fan-out in internal/gateway/websocket +// and the orchestrator queue reconciler) must observe the same payload +// regardless of which surface performed the mutation. Owning the payload here +// keeps the two from drifting; each surface supplies only its own source label. +package stepevents + +import ( + "context" + + "go.uber.org/zap" + + "github.com/kandev/kandev/internal/common/logger" + "github.com/kandev/kandev/internal/events/bus" + "github.com/kandev/kandev/internal/workflow/models" +) + +// Bus is the publish-only slice of bus.EventBus this package needs. Both +// bus.EventBus and the narrower EventBus declared by the MCP handlers satisfy +// it, so either surface can hand over whatever it was wired with. +type Bus interface { + Publish(ctx context.Context, subject string, event *bus.Event) error +} + +// Publisher emits workflow-step events tagged with a caller-supplied source. +type Publisher struct { + bus Bus + source string + logger *logger.Logger +} + +// NewPublisher returns a Publisher that stamps every event with source, which +// is the publishing surface's provenance label (for example "mcp-handlers"). +func NewPublisher(eventBus Bus, source string, log *logger.Logger) *Publisher { + return &Publisher{bus: eventBus, source: source, logger: log} +} + +// Publish emits eventType carrying step. A nil publisher, a publisher wired +// without an event bus, and a nil step are all no-ops. +func (p *Publisher) Publish(ctx context.Context, eventType string, step *models.WorkflowStep) { + if p == nil || p.bus == nil || step == nil { + return + } + data := map[string]interface{}{"step": payload(step)} + if err := p.bus.Publish(ctx, eventType, bus.NewEvent(eventType, p.source, data)); err != nil && p.logger != nil { + p.logger.Error("failed to publish workflow step event", + zap.String("event_type", eventType), + zap.String("step_id", step.ID), + zap.Error(err)) + } +} + +// PublishAll emits eventType once per step, skipping nil entries. +func (p *Publisher) PublishAll(ctx context.Context, eventType string, steps []*models.WorkflowStep) { + for _, step := range steps { + p.Publish(ctx, eventType, step) + } +} + +// payload builds the wire representation of a step carried by every +// workflow_step.* event. Adding a field here reaches both surfaces at once. +func payload(step *models.WorkflowStep) map[string]interface{} { + return map[string]interface{}{ + "id": step.ID, + "workflow_id": step.WorkflowID, + "name": step.Name, + "position": step.Position, + "color": step.Color, + "prompt": step.Prompt, + "events": step.Events, + "show_in_command_panel": step.ShowInCommandPanel, + "allow_manual_move": step.AllowManualMove, + "is_start_step": step.IsStartStep, + "auto_archive_after_hours": step.AutoArchiveAfterHours, + "wip_limit": step.WIPLimit, + "pull_from_step_id": step.PullFromStepID, + "agent_profile_id": step.AgentProfileID, + "stage_type": string(step.StageType), + "auto_advance_requires_signal": step.AutoAdvanceRequiresSignal, + "cancel_triggers_turn_complete": step.CancelTriggersTurnComplete, + "created_at": step.CreatedAt, + "updated_at": step.UpdatedAt, + } +} diff --git a/apps/backend/internal/workflow/stepevents/stepevents_test.go b/apps/backend/internal/workflow/stepevents/stepevents_test.go new file mode 100644 index 0000000000..a249480f0a --- /dev/null +++ b/apps/backend/internal/workflow/stepevents/stepevents_test.go @@ -0,0 +1,198 @@ +package stepevents + +import ( + "context" + "errors" + "reflect" + "strings" + "testing" + "time" + + "github.com/kandev/kandev/internal/common/logger" + "github.com/kandev/kandev/internal/events" + "github.com/kandev/kandev/internal/events/bus" + "github.com/kandev/kandev/internal/workflow/models" +) + +type recordingBus struct { + published []*bus.Event + subjects []string + err error +} + +func (b *recordingBus) Publish(_ context.Context, subject string, event *bus.Event) error { + b.subjects = append(b.subjects, subject) + b.published = append(b.published, event) + return b.err +} + +func testLogger(t *testing.T) *logger.Logger { + t.Helper() + return logger.Default() +} + +// fullStep returns a step whose every field is set to a distinctive non-zero +// value, so a payload that drops one is visible. +func fullStep() *models.WorkflowStep { + created := time.Date(2026, 8, 1, 10, 0, 0, 0, time.UTC) + updated := time.Date(2026, 8, 2, 11, 0, 0, 0, time.UTC) + return &models.WorkflowStep{ + ID: "step-1", + WorkflowID: "workflow-1", + Name: "Review", + Position: 3, + Color: "#ff00ff", + Prompt: "review the diff", + Events: models.StepEvents{OnEnter: []models.OnEnterAction{{Type: models.OnEnterAutoStartAgent}}}, + AllowManualMove: true, + IsStartStep: true, + ShowInCommandPanel: true, + AutoArchiveAfterHours: 24, + AgentProfileID: "agent-1", + WIPLimit: 5, + PullFromStepID: "step-0", + StageType: models.StageTypeReview, + + AutoAdvanceRequiresSignal: true, + CancelTriggersTurnComplete: true, + CreatedAt: created, + UpdatedAt: updated, + } +} + +func publishOne(t *testing.T, source string, step *models.WorkflowStep) (*recordingBus, map[string]interface{}) { + t.Helper() + eventBus := &recordingBus{} + NewPublisher(eventBus, source, testLogger(t)).Publish(context.Background(), events.WorkflowStepUpdated, step) + if len(eventBus.published) != 1 { + t.Fatalf("published %d events, want 1", len(eventBus.published)) + } + data, ok := eventBus.published[0].Data.(map[string]interface{}) + if !ok { + t.Fatalf("event data type = %T, want map", eventBus.published[0].Data) + } + stepPayload, ok := data["step"].(map[string]interface{}) + if !ok { + t.Fatalf("step payload type = %T, want map", data["step"]) + } + return eventBus, stepPayload +} + +func TestPublishCarriesEveryStepField(t *testing.T) { + step := fullStep() + _, got := publishOne(t, "test-source", step) + + want := map[string]interface{}{ + "id": step.ID, + "workflow_id": step.WorkflowID, + "name": step.Name, + "position": step.Position, + "color": step.Color, + "prompt": step.Prompt, + "events": step.Events, + "show_in_command_panel": step.ShowInCommandPanel, + "allow_manual_move": step.AllowManualMove, + "is_start_step": step.IsStartStep, + "auto_archive_after_hours": step.AutoArchiveAfterHours, + "wip_limit": step.WIPLimit, + "pull_from_step_id": step.PullFromStepID, + "agent_profile_id": step.AgentProfileID, + "stage_type": string(step.StageType), + "auto_advance_requires_signal": step.AutoAdvanceRequiresSignal, + "cancel_triggers_turn_complete": step.CancelTriggersTurnComplete, + "created_at": step.CreatedAt, + "updated_at": step.UpdatedAt, + } + if !reflect.DeepEqual(got, want) { + t.Fatalf("payload mismatch:\n got = %#v\nwant = %#v", got, want) + } +} + +// TestPayloadCoversEveryModelField fails when a field is added to +// models.WorkflowStep without being added to the event payload, which would +// otherwise silently ship an incomplete step to every subscriber. +func TestPayloadCoversEveryModelField(t *testing.T) { + got := payload(fullStep()) + stepType := reflect.TypeOf(models.WorkflowStep{}) + + exported := 0 + for i := range stepType.NumField() { + field := stepType.Field(i) + // Only exported fields reach the wire, so unexported ones (a cached + // value, a mutex) must not count toward the expected key total. + if !field.IsExported() { + continue + } + exported++ + key := strings.Split(field.Tag.Get("json"), ",")[0] + if key == "" || key == "-" { + t.Fatalf("field %s has no usable json tag", field.Name) + } + if _, ok := got[key]; !ok { + t.Errorf("payload is missing %q (models.WorkflowStep.%s)", key, field.Name) + } + } + if len(got) != exported { + t.Errorf("payload has %d keys, model has %d exported fields — payload carries a key with no model field", + len(got), exported) + } +} + +func TestPublishUsesCallerSource(t *testing.T) { + for _, source := range []string{"workflow-handlers", "mcp-handlers"} { + eventBus, _ := publishOne(t, source, fullStep()) + if eventBus.published[0].Source != source { + t.Errorf("source = %q, want %q", eventBus.published[0].Source, source) + } + if eventBus.subjects[0] != events.WorkflowStepUpdated { + t.Errorf("subject = %q, want %q", eventBus.subjects[0], events.WorkflowStepUpdated) + } + } +} + +func TestPublishNoOps(t *testing.T) { + ctx := context.Background() + + t.Run("nil publisher", func(t *testing.T) { + var p *Publisher + p.Publish(ctx, events.WorkflowStepCreated, fullStep()) + p.PublishAll(ctx, events.WorkflowStepUpdated, []*models.WorkflowStep{fullStep()}) + }) + + t.Run("nil bus", func(t *testing.T) { + NewPublisher(nil, "test-source", testLogger(t)).Publish(ctx, events.WorkflowStepCreated, fullStep()) + }) + + t.Run("nil step", func(t *testing.T) { + eventBus := &recordingBus{} + NewPublisher(eventBus, "test-source", testLogger(t)).Publish(ctx, events.WorkflowStepCreated, nil) + if len(eventBus.published) != 0 { + t.Fatalf("published %d events for a nil step, want 0", len(eventBus.published)) + } + }) +} + +func TestPublishAllEmitsOnePerStep(t *testing.T) { + eventBus := &recordingBus{} + steps := []*models.WorkflowStep{ + {ID: "step-a", WorkflowID: "workflow-1"}, + nil, + {ID: "step-b", WorkflowID: "workflow-1"}, + } + NewPublisher(eventBus, "test-source", testLogger(t)). + PublishAll(context.Background(), events.WorkflowStepUpdated, steps) + + if len(eventBus.published) != 2 { + t.Fatalf("published %d events, want 2 (nil entries skipped)", len(eventBus.published)) + } +} + +func TestPublishSurvivesBusError(t *testing.T) { + eventBus := &recordingBus{err: errors.New("bus down")} + NewPublisher(eventBus, "test-source", testLogger(t)). + Publish(context.Background(), events.WorkflowStepDeleted, fullStep()) + + if len(eventBus.published) != 1 { + t.Fatalf("published %d events, want 1", len(eventBus.published)) + } +}