pkg

type Cursor struct {
	LastUpdatedAt libtime.DateTime  `json:"last_updated_at"`
	HeadSHAs      map[string]string `json:"head_shas"`
}

type GitHubClient interface {
	// SearchPRs issues a GitHub Search query for open PRs updated since cursor.
	// page=1 for the first call; use SearchResult.NextPage for subsequent calls.
	SearchPRs(
		ctx context.Context,
		scope string,
		since libtime.DateTime,
		page int,
	) (SearchResult, error)

	// GetPRDetails fetches head SHA, clone URL, branch, state and draft flag for
	// a single PR via pulls/N (re-confirming draft/state against search-index lag).
	GetPRDetails(ctx context.Context, owner, repo string, number int) (PRDetails, error)

	// ListPRFiles returns the paths of every file touched by the PR diff
	// (paginated pulls/N/files).
	ListPRFiles(ctx context.Context, owner, repo string, number int) ([]string, error)

	// GetContent returns the decoded bytes of a repo file at the given ref.
	// A missing file surfaces as an error for which IsNotFound reports true.
	GetContent(ctx context.Context, owner, repo, filePath, ref string) ([]byte, error)

	// ListDir returns the entry paths (files and subdirs) directly under the
	// given directory path at ref. A missing directory surfaces as an error for
	// which IsNotFound reports true.
	ListDir(ctx context.Context, owner, repo, dirPath, ref string) ([]string, error)

	// IsNotFound reports whether err is a GitHub 404 (missing file/dir/ref).
	IsNotFound(err error) bool
}

type Metrics interface {
	// IncPollCycle increments the poll cycle counter with the given result label.
	// result: "success", "rate_limited", "github_error"
	IncPollCycle(result string)
	// IncPublished increments the published counter with the given status label.
	// status: "create", "skipped", "error"
	IncPublished(status string)
	// IncReposScanned increments the scanned-PR counter (sanity check on the scope filter).
	IncReposScanned()
	// IncFilterSkipped increments the filter-skipped counter with the given reason.
	// reason: "out_of_scope", "details_error", "empty_sha", "not_draft", "not_open",
	// "no_dark_factory_yaml", "no_spec_in_diff", "prompts_in_flight", "evaluate_error"
	IncFilterSkipped(reason string)
}

type PRDetails struct {
	// HeadSHA is the commit hash of the PR's head branch. Used as the `ref`
	// the agent checks out and as the per-task dedup key.
	HeadSHA string
	// CloneURL is the HTTPS clone URL of the head repo (e.g.
	// `https://github.com/owner/repo.git`). Emitted as `clone_url`.
	CloneURL string
	// Branch is the head branch name (e.g. `dark-factory/foo`). Emitted as `branch`.
	Branch string
	// State is the PR state ("open" / "closed"), re-confirmed via pulls/N.
	State string
	// IsDraft indicates whether the PR is a draft, re-confirmed via pulls/N.
	IsDraft bool
	// Title is the PR title.
	Title string
	// UpdatedAt is the PR last-updated timestamp; drives the cursor watermark.
	UpdatedAt libtime.DateTime
}

type PullRequest struct {
	GlobalID  int64
	Number    int
	Owner     string
	Repo      string
	Title     string
	HTMLURL   string
	IsDraft   bool
	UpdatedAt libtime.DateTime
}

type SearchResult struct {
	PullRequests  []PullRequest
	HasNextPage   bool
	NextPage      int
	RateRemaining int
	RateResetAt   libtime.DateTime
}

type TaskConfig struct {
	Stage       string
	MaxSlugLen  int
	MaxTitleLen int
	TaskSuffix  string
	// TargetVault routes the CreateTaskCommand to a specific vault controller
	// (matched verbatim against the controller's VAULT_NAME). Empty leaves it
	// unset so the controller's legacy default-vault fallback applies.
	TargetVault string
}

type Watcher interface {
	Poll(ctx context.Context) error
}