Files
kandev/apps/backend/internal/task/service/walkthrough_service.go
T
José Almeida 3e237e177a feat: add agent-authored code walkthroughs (#1647)
* feat: add code-walkthrough backend (MCP tool, service, persistence, WS events)

* feat: render agent code walkthroughs as line-anchored cards + editor window

* test: add code-walkthrough re-emit mock-agent scenario

* fix: rework code-walkthrough UX (floating card, line reveal, minimize, clickable file)

* fix: improve code walkthrough editor UX

* fix: backfill walkthrough launcher after websocket connect

* fix: improve walkthrough requests and editor anchors

* fix: clear walkthrough highlights on close

* feat: add walkthrough discard and prompt customization

* fix: send walkthrough requests through saved prompt

* fix: support postgres built-in prompt seeding

* fix: address walkthrough review feedback

* fix: address walkthrough review follow-ups

* fix: harden walkthrough lifecycle races

* fix: reuse walkthrough notification cleanup

* fix: guard stale walkthrough file opens

* fix: abort stale file opens before paint

* fix: stabilize github settings e2e readiness

* fix: use stable github settings e2e selector
2026-07-10 08:34:57 +01:00

199 lines
6.1 KiB
Go

package service
import (
"context"
"errors"
"fmt"
"strings"
"go.uber.org/zap"
"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/task/models"
)
// ErrTaskWalkthroughNotFound is returned when no walkthrough exists for a task.
var ErrTaskWalkthroughNotFound = models.ErrTaskWalkthroughNotFound
// ErrInvalidWalkthrough is returned when an agent submits a malformed walkthrough.
var ErrInvalidWalkthrough = errors.New("invalid walkthrough")
// Event-payload keys, hoisted to constants to satisfy goconst.
const (
wtFieldTaskID = "task_id"
wtFieldTitle = "title"
wtFieldCreatedAt = "created_at"
wtFieldUpdatedAt = "updated_at"
)
// walkthroughRepo is the minimal repository surface WalkthroughService needs.
// The SQLite repository satisfies it; declared locally so the service does not
// depend on the full aggregate repository interface.
type walkthroughRepo interface {
CreateTaskWalkthrough(ctx context.Context, wt *models.TaskWalkthrough) error
GetTaskWalkthrough(ctx context.Context, taskID string) (*models.TaskWalkthrough, error)
DeleteTaskWalkthrough(ctx context.Context, taskID string) error
}
// WalkthroughService provides agent-authored code-walkthrough business logic.
// Walkthroughs mirror task plans: one per task, agent-authored, persisted, and
// broadcast to the web UI via the event bus.
type WalkthroughService struct {
repo walkthroughRepo
eventBus bus.EventBus
logger *logger.Logger
}
// NewWalkthroughService creates a new walkthrough service.
func NewWalkthroughService(repo walkthroughRepo, eventBus bus.EventBus, log *logger.Logger) *WalkthroughService {
return &WalkthroughService{
repo: repo,
eventBus: eventBus,
logger: log.WithFields(zap.String("component", "walkthrough-service")),
}
}
// ShowWalkthroughRequest contains parameters for creating/replacing a walkthrough.
type ShowWalkthroughRequest struct {
TaskID string
Title string
Steps []models.WalkthroughStep
}
// ShowWalkthrough upserts a task's walkthrough (replacing any existing one) and
// publishes the matching created/updated event.
func (s *WalkthroughService) ShowWalkthrough(ctx context.Context, req ShowWalkthroughRequest) (*models.TaskWalkthrough, error) {
if req.TaskID == "" {
return nil, ErrTaskIDRequired
}
title, steps, err := normalizeWalkthroughRequest(req)
if err != nil {
return nil, err
}
existing, err := s.repo.GetTaskWalkthrough(ctx, req.TaskID)
if err != nil {
s.logger.Error("get existing walkthrough", zap.String("task_id", req.TaskID), zap.Error(err))
return nil, err
}
created := existing == nil
wt := &models.TaskWalkthrough{
TaskID: req.TaskID,
Title: title,
Steps: steps,
CreatedBy: createdByAgent,
}
if existing != nil {
wt.ID = existing.ID
wt.CreatedAt = existing.CreatedAt
}
if err := s.repo.CreateTaskWalkthrough(ctx, wt); err != nil {
s.logger.Error("upsert walkthrough", zap.String("task_id", req.TaskID), zap.Error(err))
return nil, err
}
if existing == nil && !wt.CreatedAt.Equal(wt.UpdatedAt) {
created = false
}
eventType := events.TaskWalkthroughUpdated
if created {
eventType = events.TaskWalkthroughCreated
}
s.publishEvent(ctx, eventType, wt)
return wt, nil
}
func normalizeWalkthroughRequest(req ShowWalkthroughRequest) (string, []models.WalkthroughStep, error) {
if len(req.Steps) == 0 {
return "", nil, invalidWalkthroughError("at least one step is required")
}
title := strings.TrimSpace(req.Title)
if title == "" {
title = "Walkthrough"
}
steps := make([]models.WalkthroughStep, 0, len(req.Steps))
for i, raw := range req.Steps {
step := models.WalkthroughStep{
Title: strings.TrimSpace(raw.Title),
Repo: strings.TrimSpace(raw.Repo),
File: strings.TrimSpace(raw.File),
Line: raw.Line,
LineEnd: raw.LineEnd,
Text: strings.TrimSpace(raw.Text),
}
if step.File == "" {
return "", nil, invalidWalkthroughError("step %d file is required", i+1)
}
if step.Text == "" {
return "", nil, invalidWalkthroughError("step %d text is required", i+1)
}
if step.Line <= 0 {
return "", nil, invalidWalkthroughError("step %d line must be positive", i+1)
}
if step.LineEnd != 0 && step.LineEnd < step.Line {
return "", nil, invalidWalkthroughError("step %d line_end must be greater than or equal to line", i+1)
}
steps = append(steps, step)
}
return title, steps, nil
}
func invalidWalkthroughError(format string, args ...interface{}) error {
return fmt.Errorf("%w: %s", ErrInvalidWalkthrough, fmt.Sprintf(format, args...))
}
// GetWalkthrough returns a task's walkthrough, or nil, nil when none exists.
func (s *WalkthroughService) GetWalkthrough(ctx context.Context, taskID string) (*models.TaskWalkthrough, error) {
if taskID == "" {
return nil, ErrTaskIDRequired
}
return s.repo.GetTaskWalkthrough(ctx, taskID)
}
// DeleteWalkthrough removes a task's walkthrough and publishes the deleted event.
func (s *WalkthroughService) DeleteWalkthrough(ctx context.Context, taskID string) error {
if taskID == "" {
return ErrTaskIDRequired
}
existing, err := s.repo.GetTaskWalkthrough(ctx, taskID)
if err != nil {
return err
}
if existing == nil {
return ErrTaskWalkthroughNotFound
}
if err := s.repo.DeleteTaskWalkthrough(ctx, taskID); err != nil {
if errors.Is(err, ErrTaskWalkthroughNotFound) {
return ErrTaskWalkthroughNotFound
}
return err
}
s.publishEvent(ctx, events.TaskWalkthroughDeleted, existing)
return nil
}
func (s *WalkthroughService) publishEvent(ctx context.Context, eventType string, wt *models.TaskWalkthrough) {
if s.eventBus == nil {
return
}
payload := map[string]interface{}{
"id": wt.ID,
wtFieldTaskID: wt.TaskID,
wtFieldTitle: wt.Title,
"steps": wt.Steps,
"created_by": wt.CreatedBy,
wtFieldCreatedAt: wt.CreatedAt,
wtFieldUpdatedAt: wt.UpdatedAt,
}
if err := s.eventBus.Publish(ctx, eventType, bus.NewEvent(eventType, "walkthrough-service", payload)); err != nil {
s.logger.Error("publish walkthrough event", zap.String("event_type", eventType), zap.Error(err))
}
}