adapter

type AIAdapter interface {
	// Complete sends a prompt and returns the completion.
	Complete(ctx context.Context, prompt string, system string) (string, error)
}

type AgentAdapter interface {
	// Invoke spawns the agent as a subprocess. It blocks until the agent exits.
	Invoke(ctx context.Context, req InvokeRequest) (*InvokeResult, error)
	// Capabilities describes what the agent harness supports.
	Capabilities() Capabilities
}

type Capabilities struct {
	MCP          bool
	Headless     bool
	Skills       bool
	SystemPrompt bool
}

type CommsAdapter interface {
	// Notify sends a structured message to the configured channel.
	Notify(ctx context.Context, msg Notification) error
	// NotifyUser sends a notification directly to a specific user by handle,
	// bypassing the channel broadcast. Adapters that cannot resolve a handle
	// to a user, or that have no per-user delivery mechanism at all, return
	// ErrRecipientUnknown so the caller can fall back to Notify. Like every
	// comms call it is best-effort and never fatal.
	NotifyUser(ctx context.Context, handle string, msg Notification) error
	// PostStandup posts a formatted standup to the standup channel.
	PostStandup(ctx context.Context, standup StandupReport) error
	// FetchMentions returns recent mentions of spec IDs in configured channels.
	FetchMentions(ctx context.Context, since time.Time) ([]Mention, error)
}

type DeployAdapter interface {
	// Trigger initiates a deployment for the given repos to the target environment.
	Trigger(ctx context.Context, repos []string, env string) (*DeployRun, error)
	// Status polls the deployment run for current state.
	Status(ctx context.Context, run *DeployRun) (*DeployStatus, error)
}

type DeployRun struct {
	ID     string
	Repo   string
	Env    string
	Status string
	URL    string
}

type DeployStatus struct {
	RunID   string
	Status  string // "pending", "running", "success", "failure"
	URL     string
	Message string
}

type DocsAdapter interface {
	// FetchSections retrieves the current content of the spec from the docs provider,
	// keyed by section slug.
	FetchSections(ctx context.Context, specID string) (map[string]string, error)
	// PushFull publishes the complete spec to the docs provider.
	PushFull(ctx context.Context, specID string, content string) error
	// PageURL returns the URL of the spec's page in the docs provider.
	PageURL(ctx context.Context, specID string) (string, error)
}

type InvokeRequest struct {
	SpecID        string   // active spec id (e.g. SPEC-042)
	WorkDir       string   // working directory the agent runs in
	ContextFile   string   // consolidated markdown fallback for non-MCP agents
	MCPConfigPath string   // engine-generated; runs `spec mcp-server --spec <id>`
	SystemPrompt  string   // assembled build instructions
	SkillPaths    []string // reproducibility skill paths (may be empty)
	Prompt        string   // kickoff prompt (may be empty)
	Headless      bool     // -p mode for `spec fix --auto` / CI
}

type InvokeResult struct {
	// ExitReason is why the session ended: "completed", "error",
	// "interrupted", or "" when it could not be determined.
	ExitReason string `json:"exitReason,omitempty"`
	// ErrorClass categorises a failure (e.g. "auto_retry_exhausted",
	// "compaction_failed", "nonzero_exit"). Empty on success.
	ErrorClass string `json:"errorClass,omitempty"`
	// ErrorMessage is the harness-reported failure detail, when present.
	ErrorMessage string `json:"errorMessage,omitempty"`
	// Tokens aggregates token usage across the session, when the harness
	// reports it.
	Tokens TokenUsage `json:"tokens,omitempty"`
	// Raw holds a bounded tail of the harness output, retained for debugging
	// when structured parsing yields nothing.
	Raw string `json:"raw,omitempty"`
}

type Mention struct {
	SpecID    string
	Channel   string
	Author    string
	Preview   string
	Timestamp time.Time
}

type Notification struct {
	SpecID  string
	Title   string
	Message string
	Channel string
	Mention string // e.g., "@alice"
}

type PMAdapter interface {
	// FindEpic returns the key of an existing epic linked to the spec, or ""
	// when none exists. It is the idempotency guard for CreateEpic.
	FindEpic(ctx context.Context, specID string) (epicKey string, err error)
	// CreateEpic creates a new epic/issue linked to a spec and returns its key.
	CreateEpic(ctx context.Context, spec SpecMeta) (epicKey string, err error)
	// LinkEpic records a back-link from the PM issue to the spec so board
	// consumers can navigate PM -> spec. specURL may be empty.
	LinkEpic(ctx context.Context, epicKey, specID, specURL string) error
	// UpdateStatus syncs the spec's pipeline stage to the PM tool's board
	// status. A stage with no configured mapping is a clean no-op.
	UpdateStatus(ctx context.Context, epicKey string, status string) error
	// FetchUpdates returns status changes from the PM tool since last sync.
	FetchUpdates(ctx context.Context, epicKey string) (*PMUpdate, error)
	// SyncStories reconciles per-step stories under an epic, returning the
	// resulting story links. A no-op when story sync is disabled.
	SyncStories(ctx context.Context, epicKey string, stories []StorySpec) ([]StoryLink, error)
	// Validate checks credentials and configuration against the live PM tool.
	Validate(ctx context.Context) error
}

type PMUpdate struct {
	Status    string
	Assignee  string
	UpdatedAt time.Time
}

type PRDetail struct {
	PullRequest
	ReviewComments    int
	UnresolvedThreads int
}

type PullRequest struct {
	Number    int
	Title     string
	Repo      string
	Branch    string
	Author    string
	URL       string
	Status    string // "open", "merged", "closed"
	Approved  bool
	CIStatus  string // "passing", "failing", "pending"
	CreatedAt time.Time
}

type Registry struct {
	// contains filtered or unexported fields
}

type RepoAdapter interface {
	// ListPRs returns open PRs matching a spec's branch pattern across its repos.
	ListPRs(ctx context.Context, repos []string, specID string) ([]PullRequest, error)
	// PRStatus returns the review/CI status of a specific PR.
	PRStatus(ctx context.Context, repo string, prNumber int) (*PRDetail, error)
	// SetPRDescription updates a PR's description.
	SetPRDescription(ctx context.Context, repo string, prNumber int, body string) error
	// RequestedReviews returns PRs where the current user is a requested reviewer.
	RequestedReviews(ctx context.Context, user string) ([]PullRequest, error)
	// InvolvedPRs returns open PRs that involve the user in any capacity —
	// authored, assigned, review-requested, or mentioned. Unlike
	// RequestedReviews, this includes the user's own PRs.
	InvolvedPRs(ctx context.Context, user string) ([]PullRequest, error)
	// OpenDraftPR opens a DRAFT pull request from head into base, returning its
	// number and URL. Draft-only by design: merge stays a human action, so no
	// merge call is exposed on this interface.
	OpenDraftPR(ctx context.Context, repo, head, base, title, body string) (number int, url string, err error)
	// SetPRBase retargets an open PR's base branch, used to re-chain a stack as
	// parent PRs merge.
	SetPRBase(ctx context.Context, repo string, prNumber int, base string) error
}

type SpecMeta struct {
	ID      string
	Title   string
	Status  string
	EpicKey string
	Repos   []string

	// Problem is a short excerpt of the problem statement, used to give the
	// PM epic meaningful context instead of just an id.
	Problem string
	// Labels are applied to the created issue (in addition to config labels).
	Labels []string
	// Cycle is the team cycle/iteration label.
	Cycle string
	// URL is a back-link to the canonical spec document.
	URL string
}

type StandupReport struct {
	UserName  string
	Date      string
	Yesterday []string
	Today     []string
	Blockers  []string
}

type StoryLink struct {
	StepID   string
	StoryKey string
	Status   string
}

type StorySpec struct {
	// StepID is a stable identifier for the step, used as the idempotency key.
	StepID      string
	Repo        string
	Description string
	// Status is the spec step status: pending | in-progress | complete | blocked.
	Status string
}

type TokenUsage struct {
	Input  int `json:"input,omitempty"`
	Output int `json:"output,omitempty"`
	Total  int `json:"total,omitempty"`
}