app

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 18, 2026 License: MIT Imports: 48 Imported by: 0

Documentation

Overview

Package app owns GitContribute use cases and capability composition.

Service methods are the shared application boundary for the CLI, MCP server, and terminal UI. Methods that read the corpus remain offline; methods that access GitHub, write local state, invoke git, or execute validation commands expose those effects explicitly. Product rules belong here rather than in a presentation adapter.

Index

Constants

View Source 
const (
	FacetIssueComments    = "issue_comments"
	FacetPRDetails        = "pr_details"
	FacetPRReviews        = "pr_reviews"
	FacetPRReviewComments = "pr_review_comments"
)

Thread facets that selective hydration can retrieve.

Variables

This section is empty.

Functions

This section is empty.

Types

type CollisionCheckResult 

type CollisionCheckResult struct {
	HypothesisID   string              `json:"hypothesis_id,omitempty"`
	OpportunityID  string              `json:"opportunity_id,omitempty"`
	Repo           domain.RepoRef      `json:"repo"`
	Query          string              `json:"query"`
	Findings       []evidence.Evidence `json:"findings"`
	SourceRevision string              `json:"source_revision"`
	Limit          int                 `json:"limit"`
	Total          int                 `json:"total"`
}

CollisionCheckResult is the set of open pull requests that may collide with a workflow item.

type DuplicateCandidatesResult 

type DuplicateCandidatesResult struct {
	Repo           string     `json:"repo"`
	Kind           string     `json:"kind"`
	Number         int        `json:"number"`
	ClusterID      int64      `json:"cluster_id,omitempty"`
	StableID       string     `json:"stable_id,omitempty"`
	Canonical      ThreadRef  `json:"canonical,omitempty"`
	SourceRevision string     `json:"source_revision"`
	Limit          int        `json:"limit"`
	Total          int        `json:"total"`
	Candidates     []Neighbor `json:"candidates"`
}

DuplicateCandidatesResult is the response for a duplicate-candidate query.

type DuplicateCheckResult 

type DuplicateCheckResult struct {
	HypothesisID   string              `json:"hypothesis_id,omitempty"`
	OpportunityID  string              `json:"opportunity_id,omitempty"`
	Repo           domain.RepoRef      `json:"repo"`
	Query          string              `json:"query"`
	Findings       []evidence.Evidence `json:"findings"`
	SourceRevision string              `json:"source_revision"`
	Limit          int                 `json:"limit"`
	Total          int                 `json:"total"`
}

DuplicateCheckResult is the set of possible duplicate threads for a workflow item.

type EvidenceSummary 

type EvidenceSummary struct {
	Supporting    int `json:"supporting"`
	Contradicting int `json:"contradicting"`
	Inconclusive  int `json:"inconclusive"`
	Stale         int `json:"stale"`
	Invalid       int `json:"invalid"`
	Total         int `json:"total"`
}

EvidenceSummary counts evidence by relation.

type ExplainMatchResult 

type ExplainMatchResult struct {
	Score   float64  `json:"score"`
	Reasons []string `json:"reasons"`
}

ExplainMatchResult exposes the factual signals that contribute to a match score. It performs no network access.

type HydrateOptions 

type HydrateOptions struct {
	// Facets lists the facets to retrieve. An empty list hydrates all facets
	// applicable to the thread kind.
	Facets []string
	// MaxPages bounds pagination per facet. Zero defaults to 50.
	MaxPages int
}

HydrateOptions controls selective thread hydration.

type HydrateRepositoryOptions 

type HydrateRepositoryOptions struct {
	Facets   []string
	MaxPages int
	State    string
	Numbers  []int
}

HydrateRepositoryOptions controls repository-wide thread hydration.

type HydrateResult 

type HydrateResult struct {
	Repo     cli.RepoRef
	Number   int
	Kind     string
	Facets   []HydratedFacet
	Pages    int
	Requests int
	Capped   bool
	Message  string
}

HydrateResult reports the outcome of hydrating a thread.

type HydratedFacet 

type HydratedFacet struct {
	Facet    string
	Count    int
	Pages    int
	Complete bool
}

HydratedFacet reports coverage and counts for one hydrated facet.

type JobExecutor 

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

JobExecutor submits durable jobs, runs them asynchronously, and supports cancellation, progress recording, and safe shutdown.

Each executor registers a unique owner in the corpus and heartbeats while it is open. Startup only reconciles jobs whose owner is missing or has a stale heartbeat; live owners from other processes are never failed. Workers poll the corpus for cancellation requests so a job cancelled by another process stops promptly.

func (*JobExecutor) Cancel 

func (e *JobExecutor) Cancel(ctx context.Context, id string) error

Cancel requests cancellation for a job. Queued jobs are marked cancelled immediately; running jobs have their context cancelled and finish as cancelled.

func (*JobExecutor) Close 

func (e *JobExecutor) Close() error

Close cancels all running jobs and waits for their goroutines to finish before returning.

func (*JobExecutor) Get 

func (e *JobExecutor) Get(ctx context.Context, id string) (*corpus.Job, error)

Get returns a job by opaque ID.

func (*JobExecutor) List 

func (e *JobExecutor) List(ctx context.Context, status string, limit int) ([]corpus.Job, error)

List returns recent jobs, optionally filtered by status.

func (*JobExecutor) Submit 

func (e *JobExecutor) Submit(ctx context.Context, kind string, request any, fn JobFunc) (string, error)

Submit persists a queued job and runs it asynchronously.

type JobFunc 

type JobFunc func(ctx context.Context, report func(progress, statistics string) error) (any, error)

JobFunc performs asynchronous work for a job. It receives a context that is cancelled when the job is cancelled or the executor closes, and a report callback that records progress and statistics in the corpus.

type MCPReader 

type MCPReader struct{ *Service }

MCPReader adapts Service to the mcpserver.Reader interface. It is a thin wrapper because Go does not allow two methods named Search on one type.

func (*MCPReader) BuildRepositoryDossier 

func (r *MCPReader) BuildRepositoryDossier(ctx context.Context, in mcpserver.BuildRepositoryDossierInput) (mcpserver.JobReference, error)

BuildRepositoryDossier submits a durable job that builds a repository dossier.

func (*MCPReader) CancelJob 

func (r *MCPReader) CancelJob(ctx context.Context, in mcpserver.CancelJobInput) (mcpserver.GetJobOutput, error)

CancelJob cancels a durable job and returns its updated state.

func (*MCPReader) CheckCollisions 

func (r *MCPReader) CheckCollisions(ctx context.Context, in mcpserver.CheckCollisionsInput) (mcpserver.CheckOutput, error)

CheckCollisions finds open pull request collisions for a hypothesis or opportunity.

func (*MCPReader) CheckDuplicates 

func (r *MCPReader) CheckDuplicates(ctx context.Context, in mcpserver.CheckDuplicatesInput) (mcpserver.CheckOutput, error)

CheckDuplicates finds duplicate-candidate threads for a hypothesis or opportunity.

func (*MCPReader) CreateWorkspace 

func (r *MCPReader) CreateWorkspace(ctx context.Context, in mcpserver.CreateWorkspaceInput) (mcpserver.JobReference, error)

CreateWorkspace submits a durable job that clones a remote and creates a worktree.

func (*MCPReader) DefineValidation 

func (r *MCPReader) DefineValidation(ctx context.Context, in mcpserver.DefineValidationInput) (mcpserver.ValidationOutput, error)

DefineValidation stores a validation definition.

func (*MCPReader) Dossier 

func (r *MCPReader) Dossier(ctx context.Context, in mcpserver.RepoInput) (mcpserver.DossierOutput, error)

Dossier builds a source-backed repository dossier from local corpus data.

func (*MCPReader) Evidence 

func (r *MCPReader) Evidence(ctx context.Context, in mcpserver.EvidenceInput) (mcpserver.EvidenceOutput, error)

Evidence reads evidence for a local investigation or opportunity.

func (*MCPReader) ExplainMatch 

func (r *MCPReader) ExplainMatch(ctx context.Context, in mcpserver.ExplainMatchInput) (mcpserver.ExplainMatchOutput, error)

ExplainMatch explains why a search result matched.

func (*MCPReader) FindClusters 

func (r *MCPReader) FindClusters(ctx context.Context, in mcpserver.FindClustersInput) (mcpserver.FindClustersOutput, error)

FindClusters lists duplicate-candidate clusters for a repository from the local corpus without recomputing them.

func (*MCPReader) FindNeighbors 

func (r *MCPReader) FindNeighbors(ctx context.Context, in mcpserver.FindNeighborsInput) (mcpserver.FindNeighborsOutput, error)

FindNeighbors ranks similar local threads without network access.

func (*MCPReader) GetCoverage 

func (r *MCPReader) GetCoverage(ctx context.Context, in mcpserver.GetCoverageInput) (mcpserver.GetCoverageOutput, error)

GetCoverage returns facet coverage and freshness for a repository.

func (*MCPReader) GetJob 

func (r *MCPReader) GetJob(ctx context.Context, in mcpserver.GetJobInput) (mcpserver.GetJobOutput, error)

GetJob reads a durable job by ID.

func (*MCPReader) HydrateRepository 

func (r *MCPReader) HydrateRepository(ctx context.Context, in mcpserver.HydrateRepositoryInput) (mcpserver.JobReference, error)

HydrateRepository submits a durable job that hydrates repository threads.

func (*MCPReader) HydrateThread 

func (r *MCPReader) HydrateThread(ctx context.Context, in mcpserver.HydrateThreadInput) (mcpserver.HydrateThreadOutput, error)

HydrateThread explicitly reads selected GitHub facets into the local corpus.

func (*MCPReader) Investigation 

func (r *MCPReader) Investigation(ctx context.Context, in mcpserver.InvestigationInput) (mcpserver.InvestigationOutput, error)

Investigation reads a local investigation workspace from the corpus.

func (*MCPReader) Lens 

func (r *MCPReader) Lens(ctx context.Context, in mcpserver.LensInput) (mcpserver.LensOutput, error)

Lens reads a saved lens definition from the local corpus.

func (*MCPReader) ListOpportunities 

func (r *MCPReader) ListOpportunities(ctx context.Context, in mcpserver.ListOpportunitiesInput) (mcpserver.ListOpportunitiesOutput, error)

ListOpportunities lists opportunities for a local investigation.

func (*MCPReader) Opportunity 

func (r *MCPReader) Opportunity(ctx context.Context, in mcpserver.OpportunityInput) (mcpserver.OpportunityOutput, error)

Opportunity reads a local contribution opportunity.

func (*MCPReader) PrepareContribution 

func (r *MCPReader) PrepareContribution(ctx context.Context, in mcpserver.PrepareContributionInput) (mcpserver.DraftOutput, error)

PrepareContribution renders a contribution draft for an opportunity.

func (*MCPReader) PromoteOpportunity 

func (r *MCPReader) PromoteOpportunity(ctx context.Context, in mcpserver.PromoteOpportunityInput) (mcpserver.OpportunityOutput, error)

PromoteOpportunity promotes a hypothesis to an opportunity.

func (*MCPReader) Readiness 

func (r *MCPReader) Readiness(ctx context.Context, in mcpserver.ReadinessInput) (mcpserver.ReadinessOutput, error)

Readiness reads a local contribution readiness report through MCP.

func (*MCPReader) RecordHypothesis 

func (r *MCPReader) RecordHypothesis(ctx context.Context, in mcpserver.RecordHypothesisInput) (mcpserver.HypothesisOutput, error)

RecordHypothesis records a fully structured hypothesis.

func (*MCPReader) Repository 

func (r *MCPReader) Repository(ctx context.Context, in mcpserver.RepoInput) (mcpserver.RepositoryOutput, error)

Repository reads a repository projection from the local corpus.

func (*MCPReader) RunValidation 

func (r *MCPReader) RunValidation(ctx context.Context, in mcpserver.RunValidationInput) (mcpserver.JobReference, error)

RunValidation submits a durable validation run.

func (*MCPReader) Search 

func (r *MCPReader) Search(ctx context.Context, in mcpserver.SearchInput) (mcpserver.SearchOutput, error)

Search performs a local-only corpus search through the MCP interface.

func (*MCPReader) SearchCode 

func (r *MCPReader) SearchCode(ctx context.Context, in mcpserver.SearchCodeInput) (mcpserver.SearchCodeOutput, error)

SearchCode searches indexed code snapshots in the local corpus.

func (*MCPReader) SearchRepositories 

func (r *MCPReader) SearchRepositories(ctx context.Context, in mcpserver.SearchRepositoriesInput) (mcpserver.SearchRepositoriesOutput, error)

SearchRepositories performs a local-only repository search.

func (*MCPReader) StartCrawl 

func (r *MCPReader) StartCrawl(ctx context.Context, in mcpserver.StartCrawlInput) (mcpserver.JobReference, error)

StartCrawl submits a durable crawl job.

func (*MCPReader) StartInvestigation 

func (r *MCPReader) StartInvestigation(ctx context.Context, in mcpserver.StartInvestigationInput) (mcpserver.InvestigationOutput, error)

StartInvestigation creates a new investigation workspace.

func (*MCPReader) SyncRepository 

func (r *MCPReader) SyncRepository(ctx context.Context, in mcpserver.SyncRepositoryInput) (mcpserver.SyncRepositoryOutput, error)

SyncRepository explicitly reads GitHub and updates the local corpus.

func (*MCPReader) Thread 

func (r *MCPReader) Thread(ctx context.Context, in mcpserver.ThreadInput) (mcpserver.ThreadOutput, error)

Thread reads one issue or pull request from the local corpus.

func (*MCPReader) ThreadByNumber 

func (r *MCPReader) ThreadByNumber(ctx context.Context, in mcpserver.ThreadByNumberInput) (mcpserver.ThreadOutput, error)

ThreadByNumber reads an issue or pull request by repository and number only.

type MCPRunner 

type MCPRunner struct{ *Service }

MCPRunner implements cli.MCPRunner by starting an MCP server over stdio.

func (*MCPRunner) Run 

func (r *MCPRunner) Run(ctx context.Context, opts cli.MCPOptions) error

Run starts the MCP server using the requested transport.

type Neighbor 

type Neighbor struct {
	Kind   string  `json:"kind"`
	Owner  string  `json:"owner"`
	Repo   string  `json:"repo"`
	Number int     `json:"number"`
	Title  string  `json:"title"`
	State  string  `json:"state"`
	Score  float64 `json:"score"`
	Reason string  `json:"reason"`
}

Neighbor is one ranked thread near a query.

type NeighborsResult 

type NeighborsResult struct {
	Repo           string     `json:"repo"`
	Kind           string     `json:"kind"`
	Number         int        `json:"number"`
	Limit          int        `json:"limit"`
	Total          int        `json:"total"`
	SourceRevision string     `json:"source_revision"`
	Neighbors      []Neighbor `json:"neighbors"`
}

NeighborsResult is the response for a local nearest-thread query.

type PrepareReviewReportInput 

type PrepareReviewReportInput struct {
	OpportunityID string
	WorkspaceID   string
}

PrepareReviewReportInput scopes a review report to an opportunity and/or workspace.

type PullRequestCollision 

type PullRequestCollision struct {
	Number  int     `json:"number"`
	Title   string  `json:"title"`
	Author  string  `json:"author"`
	BaseRef string  `json:"base_ref"`
	Score   float64 `json:"score"`
	Reason  string  `json:"reason"`
}

PullRequestCollision is a competing open pull request with a score and reason.

type PullRequestCollisionResult 

type PullRequestCollisionResult struct {
	Repo           string                 `json:"repo"`
	Number         int                    `json:"number"`
	Limit          int                    `json:"limit"`
	Total          int                    `json:"total"`
	SourceRevision string                 `json:"source_revision"`
	Collisions     []PullRequestCollision `json:"collisions"`
}

PullRequestCollisionResult is the response for a focused open-PR collision query.

type RecordEvidenceInput 

type RecordEvidenceInput struct {
	InvestigationID  string
	HypothesisID     string
	OpportunityID    string
	Type             string
	Relation         string
	Description      string
	SourceRefs       []domain.SourceRef
	SourceProvenance []evidence.SourceRevision
}

RecordEvidenceInput carries a new evidence item for an investigation, hypothesis, or opportunity.

type ReviewReport 

type ReviewReport struct {
	OpportunityID        string               `json:"opportunity_id,omitempty"`
	WorkspaceID          string               `json:"workspace_id,omitempty"`
	Repo                 cli.RepoRef          `json:"repo"`
	OpportunityStatus    string               `json:"opportunity_status,omitempty"`
	CollisionStatus      string               `json:"collision_status,omitempty"`
	CollisionFindings    []evidence.Evidence  `json:"collision_findings"`
	DiffMetadata         *WorkspaceDiffResult `json:"diff_metadata,omitempty"`
	EvidenceSummary      EvidenceSummary      `json:"evidence_summary"`
	SuggestedReviewOrder []ReviewStep         `json:"suggested_review_order"`
	RenderedAt           time.Time            `json:"rendered_at"`
}

ReviewReport is a read-only preparation artifact with collision findings, complete diff metadata, and a suggested review order.

type ReviewStep 

type ReviewStep struct {
	Path      string `json:"path"`
	Priority  int    `json:"priority"`
	Rationale string `json:"rationale"`
}

ReviewStep is one suggested review item with a stable priority.

type Service 

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

Service is the product-owned application layer that satisfies cli.Service. MCP reads are exposed through MCPReader.

func New 

func New(paths *config.Paths, version string, logger *slog.Logger) (*Service, error)

New creates a Service and resolves local configuration. GitHub credentials are resolved lazily only when a network-reading operation is requested.

func (*Service) Acquire 

func (s *Service) Acquire(ctx context.Context, repo cli.RepoRef, remote string) (*cli.AcquisitionResult, error)

Acquire clones or fetches a repository into the managed cache, records the resolved remote URL/default branch/commit SHA/acquired time, and indexes the clean checkout into the corpus. It does not execute repository code.

func (*Service) AddCollectionMembers 

func (s *Service) AddCollectionMembers(ctx context.Context, name string, members []cli.CollectionMember) (*cli.CollectionResult, error)

AddCollectionMembers idempotently adds typed references to a collection.

func (*Service) AddGHArchiveSource 

func (s *Service) AddGHArchiveSource(ctx context.Context, name string, events []string) (*cli.SourceResult, error)

AddGHArchiveSource stores a named GH Archive event filter without fetching data.

func (*Service) AddHypothesis 

func (s *Service) AddHypothesis(ctx context.Context, investigationID, title, description, category string) (*cli.HypothesisResult, error)

AddHypothesis records a hypothesis under an investigation.

func (*Service) AddLens 

func (s *Service) AddLens(ctx context.Context, name string, def lens.Definition) (*cli.LensResult, error)

AddLens validates and stores a lens definition.

func (*Service) AddRepoSource 

func (s *Service) AddRepoSource(ctx context.Context, name string, refs []cli.RepoRef) (*cli.SourceResult, error)

AddRepoSource stores a named, explicit set of repositories without fetching them.

func (*Service) AddSearchSource 

func (s *Service) AddSearchSource(ctx context.Context, name, query string) (*cli.SourceResult, error)

AddSearchSource stores a named GitHub repository-search source without executing it.

func (*Service) ArchiveSync 

func (s *Service) ArchiveSync(ctx context.Context, repo cli.RepoRef, opts cli.ArchiveSyncOptions) (*cli.SyncResult, error)

ArchiveSync adapts CLI archive options to the application sync contract.

func (*Service) ArchiveThreads 

func (s *Service) ArchiveThreads(ctx context.Context, repo cli.RepoRef, kind, state string, limit int) (*cli.ThreadListResult, error)

ArchiveThreads returns bounded current thread projections without network access.

func (*Service) BuildDossierForCLI 

func (s *Service) BuildDossierForCLI(ctx context.Context, repo cli.RepoRef) (any, error)

BuildDossierForCLI builds and persists a dossier from local corpus data.

func (*Service) BuildRepositoryDossier 

func (s *Service) BuildRepositoryDossier(ctx context.Context, repo cli.RepoRef) (*domain.Dossier, error)

BuildRepositoryDossier builds a deterministic dossier from local corpus data, persists it safely, and returns the result.

func (*Service) CancelJob 

func (s *Service) CancelJob(ctx context.Context, id string) (*cli.JobResult, error)

CancelJob records and applies a cancellation request, then returns current state.

func (*Service) CheckCollisionsForCLI 

func (s *Service) CheckCollisionsForCLI(ctx context.Context, target, id string, limit int) (any, error)

CheckCollisionsForCLI runs local open-work collision analysis for a target.

func (*Service) CheckDuplicatesForCLI 

func (s *Service) CheckDuplicatesForCLI(ctx context.Context, target, id string, limit int) (any, error)

CheckDuplicatesForCLI runs local duplicate analysis for a hypothesis or opportunity.

func (*Service) CheckHypothesisCollisions 

func (s *Service) CheckHypothesisCollisions(ctx context.Context, hypothesisID string, limit int) (*CollisionCheckResult, error)

CheckHypothesisCollisions searches the local corpus for open pull requests that may collide with a hypothesis.

func (*Service) CheckHypothesisDuplicates 

func (s *Service) CheckHypothesisDuplicates(ctx context.Context, hypothesisID string, limit int) (*DuplicateCheckResult, error)

CheckHypothesisDuplicates searches the local corpus for threads similar to a hypothesis, returning each finding as evidence.

func (*Service) CheckOpportunityCollisions 

func (s *Service) CheckOpportunityCollisions(ctx context.Context, opportunityID string, limit int) (*CollisionCheckResult, error)

CheckOpportunityCollisions searches the local corpus for open pull requests that may collide with an opportunity.

func (*Service) CheckOpportunityDuplicates 

func (s *Service) CheckOpportunityDuplicates(ctx context.Context, opportunityID string, limit int) (*DuplicateCheckResult, error)

CheckOpportunityDuplicates searches the local corpus for threads similar to an opportunity.

func (*Service) Close 

func (s *Service) Close() error

Close cancels and waits for active jobs, then closes the corpus database connection.

func (*Service) Cluster 

func (s *Service) Cluster(ctx context.Context, id string, limit int) (*cli.ClusterResult, error)

Cluster returns a single cluster by stable id.

func (*Service) Clusters 

func (s *Service) Clusters(ctx context.Context, repo cli.RepoRef, limit int) (*cli.ClusterListResult, error)

Clusters computes and lists duplicate-candidate clusters for a repository.

func (*Service) CompareValidation 

func (s *Service) CompareValidation(ctx context.Context, baseRunID, candidateRunID string) (*cli.ValidationComparisonResult, error)

CompareValidation compares a base validation run with a candidate validation run.

func (*Service) Configure 

func (s *Service) Configure(ctx context.Context, opts cli.ConfigureOptions) (*cli.ConfigureResult, error)

Configure validates and atomically saves supported typed settings. Runtime environment overrides are deliberately not persisted.

func (*Service) ContributionRadar 

func (s *Service) ContributionRadar(ctx context.Context, opts cli.RadarOptions) (*radar.Report, error)

ContributionRadar ranks a bounded set of locally stored open issues. It is a strict corpus read: it neither resolves a GitHub reader nor writes state.

func (*Service) ControlStatus 

func (s *Service) ControlStatus(ctx context.Context) (*cli.ControlStatusResult, error)

ControlStatus returns local corpus counts and freshness without network access or implicit hydration.

func (*Service) Coverage 

func (s *Service) Coverage(ctx context.Context, repo cli.RepoRef) (*cli.CoverageResult, error)

Coverage returns repository-level facet coverage without network access.

func (*Service) Crawl 

func (s *Service) Crawl(ctx context.Context, name string, opts cli.CrawlOptions) (*cli.CrawlResult, error)

Crawl performs one explicit, bounded read for a saved discovery source and persists its checkpoint only after the bounded operation succeeds.

func (*Service) CreateCollection 

func (s *Service) CreateCollection(ctx context.Context, name string) (*cli.CollectionResult, error)

CreateCollection creates a named collection.

func (*Service) CreateHypothesis 

func (s *Service) CreateHypothesis(ctx context.Context, investigationID string, input investigation.CreateHypothesisInput) (*investigation.Hypothesis, error)

CreateHypothesis records a fully structured hypothesis under an investigation.

func (*Service) CreateWorkspace 

func (s *Service) CreateWorkspace(ctx context.Context, investigationID string, opts cli.WorkspaceCreateOptions) (*cli.WorkspaceResult, error)

CreateWorkspace creates a managed worktree for an investigation.

func (*Service) DefineValidation 

func (s *Service) DefineValidation(ctx context.Context, investigationID string, opts cli.DefineValidationOptions) (*cli.ValidationResult, error)

DefineValidation stores a validation definition for an investigation.

func (*Service) Doctor 

func (s *Service) Doctor(ctx context.Context) (*cli.DoctorResult, error)

Doctor performs bounded local diagnostics. It reports authentication source availability but never returns credential values or command output.

func (*Service) Dossier 

func (s *Service) Dossier(ctx context.Context, repo cli.RepoRef) (*cli.DossierResult, error)

Dossier builds a deterministic, local-corpus-backed repository dossier.

func (*Service) DuplicateCandidates 

func (s *Service) DuplicateCandidates(ctx context.Context, repo cli.RepoRef, kind string, number int, limit int) (*DuplicateCandidatesResult, error)

DuplicateCandidates returns the included members of the duplicate-candidate cluster containing the query thread, excluding the query itself. It returns a deterministic order, transparent scores, the cluster stable id, canonical member, and source revision. If the thread is not in a cluster, the result is empty.

func (*Service) ExplainLens 

func (s *Service) ExplainLens(ctx context.Context, name, ref string, opts cli.LensExplainOptions) (*cli.LensExplainResult, error)

ExplainLens returns the saved definition, candidate facts, normalized signals, weighted contributions, final score, population context, and missing signals for a candidate under a saved lens. It performs no network access.

func (*Service) ExplainMatch 

func (s *Service) ExplainMatch(ctx context.Context, query string, match cli.SearchMatch) (*ExplainMatchResult, error)

ExplainMatch returns factual score reasons for a search match without network access. The returned reasons describe title/body term matches, source freshness, and coverage signals.

func (*Service) ExplainReadiness 

func (s *Service) ExplainReadiness(ctx context.Context, checkID string) (*cli.ReadinessCheck, error)

ExplainReadiness re-evaluates readiness and returns the requested check.

func (*Service) ExportDossier 

func (s *Service) ExportDossier(ctx context.Context, repo cli.RepoRef, format string) (*cli.ExportResult, error)

ExportDossier builds and renders a deterministic redacted dossier bundle.

func (*Service) ExportEvidence 

func (s *Service) ExportEvidence(ctx context.Context, investigationID, format string) (*cli.ExportResult, error)

ExportEvidence renders a deterministic redacted investigation evidence bundle.

func (*Service) ExportLocalMetadata 

func (s *Service) ExportLocalMetadata(ctx context.Context, opts cli.MetadataExportOptions) (*cli.MetadataExportResult, error)

ExportLocalMetadata returns a bounded, redacted, deterministic JSON export of local tracking metadata. It does not include tokens, credentials, or absolute local paths.

func (*Service) ExtractSeeds 

func (s *Service) ExtractSeeds(ctx context.Context, repo cli.RepoRef, opts domain.ExtractSeedsOptions) ([]domain.Seed, error)

ExtractSeeds derives evidence-backed contribution seeds from locally stored merged PRs, closed-unmerged PRs, and issues. It performs no network access.

func (*Service) ExtractSeedsForCLI 

func (s *Service) ExtractSeedsForCLI(ctx context.Context, repo cli.RepoRef, classes []string, limit int) (any, error)

ExtractSeedsForCLI derives bounded contribution seeds from stored threads.

func (*Service) GetContribution 

func (s *Service) GetContribution(ctx context.Context, id string) (*cli.ContributionResult, error)

GetContribution returns contribution metadata by durable id.

func (*Service) GetDossierForCLI 

func (s *Service) GetDossierForCLI(ctx context.Context, repo cli.RepoRef) (any, error)

GetDossierForCLI returns the latest persisted dossier without network access.

func (*Service) GetJob 

func (s *Service) GetJob(ctx context.Context, id string) (*cli.JobResult, error)

GetJob returns one durable job by opaque ID.

func (*Service) GetRepositoryDossier 

func (s *Service) GetRepositoryDossier(ctx context.Context, repo cli.RepoRef) (*domain.Dossier, error)

GetRepositoryDossier returns the most recently persisted dossier for a repository.

func (*Service) Hydrate 

func (s *Service) Hydrate(ctx context.Context, repo cli.RepoRef, number int, opts cli.HydrateOptions) (*cli.HydrateResult, error)

Hydrate adapts the explicit CLI hydration contract to selective hydration.

func (*Service) HydrateRepository 

func (s *Service) HydrateRepository(ctx context.Context, repo cli.RepoRef, opts HydrateRepositoryOptions) (*HydrateResult, error)

HydrateRepository hydrates selected facets for threads in a repository. It is explicit, bounded, cancellation-aware, and aggregates per-thread results.

func (*Service) HydrateThread 

func (s *Service) HydrateThread(ctx context.Context, repo cli.RepoRef, number int, opts HydrateOptions) (*HydrateResult, error)

HydrateThread fetches the requested facets for an issue or pull request and stores immutable facet observations. It is explicit, bounded, paginated, cancellation-aware, and records independent facet coverage plus run completion/failure statistics.

func (*Service) ImportLocalMetadata 

func (s *Service) ImportLocalMetadata(ctx context.Context, opts cli.MetadataImportOptions) (*cli.MetadataImportResult, error)

ImportLocalMetadata imports a bounded JSON bundle of local tracking metadata idempotently.

func (*Service) Index 

func (s *Service) Index(ctx context.Context, repo cli.RepoRef, path string) (*cli.IndexResult, error)

Index records a bounded immutable code snapshot from a clean local checkout.

func (*Service) Init 

func (s *Service) Init(ctx context.Context) (*cli.InitResult, error)

Init opens or creates the configured corpus and persists a default configuration if one does not already exist.

func (*Service) Jobs 

func (s *Service) Jobs(ctx context.Context) (*JobExecutor, error)

Jobs returns the durable job executor, opening the corpus if needed.

func (*Service) ListCollections 

func (s *Service) ListCollections(ctx context.Context) (*cli.CollectionListResult, error)

ListCollections returns all named collections.

func (*Service) ListContributionOutcomes 

func (s *Service) ListContributionOutcomes(ctx context.Context, contributionID string) (*cli.ContributionOutcomeListResult, error)

ListContributionOutcomes returns lifecycle outcomes for a contribution.

func (*Service) ListContributions 

func (s *Service) ListContributions(ctx context.Context, opts cli.ListContributionsOptions) (*cli.ContributionListResult, error)

ListContributions returns contribution metadata in prepared-at order.

func (*Service) ListHypotheses 

func (s *Service) ListHypotheses(ctx context.Context, investigationID string) (*cli.HypothesisListResult, error)

ListHypotheses returns hypotheses for an investigation.

func (*Service) ListInvestigations 

func (s *Service) ListInvestigations(ctx context.Context) (*cli.InvestigationListResult, error)

ListInvestigations returns all investigations.

func (*Service) ListJobs 

func (s *Service) ListJobs(ctx context.Context, status string, limit int) (*cli.JobListResult, error)

ListJobs returns bounded durable jobs for CLI and MCP adapters.

func (*Service) ListLenses 

func (s *Service) ListLenses(ctx context.Context) (*cli.LensListResult, error)

ListLenses returns all saved lenses in stable order.

func (*Service) ListOpportunities 

func (s *Service) ListOpportunities(ctx context.Context, investigationID string) (*cli.OpportunityListResult, error)

ListOpportunities returns opportunities, optionally filtered to one investigation.

func (*Service) ListSources 

func (s *Service) ListSources(ctx context.Context) (*cli.SourceListResult, error)

ListSources returns all saved discovery sources from the local corpus.

func (*Service) ListTriageEvents 

func (s *Service) ListTriageEvents(ctx context.Context, opts cli.ListTriageEventsOptions) (*cli.TriageEventListResult, error)

ListTriageEvents returns local triage outcomes in source-event order.

func (*Service) Load 

func (s *Service) Load(ctx context.Context) (tui.Data, error)

Load implements tui.Reader using bounded local corpus reads only.

func (*Service) MCPReader 

func (s *Service) MCPReader() mcpserver.Reader

MCPReader returns an MCP adapter backed by this service. Read methods remain offline; methods named sync or hydrate are explicit network-read operations.

func (*Service) Metadata 

func (s *Service) Metadata(ctx context.Context) (*cli.MetadataResult, error)

Metadata reports deterministic application and local capability metadata. It neither opens the corpus nor performs network access.

func (*Service) NeighborQuery 

func (s *Service) NeighborQuery(ctx context.Context, repo cli.RepoRef, kind string, number, limit int) (*cli.NeighborListResult, error)

NeighborQuery returns transparent local nearest-thread results.

func (*Service) Neighbors 

func (s *Service) Neighbors(ctx context.Context, repo cli.RepoRef, kind string, number int, limit int) (*NeighborsResult, error)

Neighbors returns a bounded, ranked list of threads most similar to the query thread. Results include transparent scores, reasons, and the source revision of the candidate population. No network access occurs.

func (*Service) NewMCPRunner 

func (s *Service) NewMCPRunner() cli.MCPRunner

NewMCPRunner returns a cli.MCPRunner backed by the service.

func (*Service) OpportunityReadiness 

func (s *Service) OpportunityReadiness(ctx context.Context, opportunityID string) (*cli.ReadinessResult, error)

OpportunityReadiness evaluates local, source-backed readiness checks for one opportunity.

func (*Service) PrepareIssue 

func (s *Service) PrepareIssue(ctx context.Context, opportunityID string, opts cli.PrepareIssueOptions) (*cli.DraftResult, error)

PrepareIssue renders and stores an issue draft for an opportunity.

func (*Service) PreparePullRequest 

func (s *Service) PreparePullRequest(ctx context.Context, opportunityID string, opts cli.PreparePROptions) (*cli.DraftResult, error)

PreparePullRequest renders and stores a pull request draft for an opportunity.

func (*Service) PrepareReviewForCLI 

func (s *Service) PrepareReviewForCLI(ctx context.Context, opportunityID, workspaceID string) (any, error)

PrepareReviewForCLI creates a local review report from an opportunity and workspace.

func (*Service) PrepareReviewReport 

func (s *Service) PrepareReviewReport(ctx context.Context, input PrepareReviewReportInput) (*ReviewReport, error)

PrepareReviewReport assembles a review report for an opportunity and/or workspace.

func (*Service) PromoteOpportunity 

func (s *Service) PromoteOpportunity(ctx context.Context, hypothesisID, problem, scope, impact, effort string, confidence float64) (*cli.OpportunityResult, error)

PromoteOpportunity converts a proposed hypothesis into an opportunity.

func (*Service) PromoteOpportunityWithInput 

func (s *Service) PromoteOpportunityWithInput(ctx context.Context, hypothesisID string, input investigation.PromoteOpportunityInput) (*investigation.Opportunity, error)

PromoteOpportunityWithInput promotes a hypothesis with dependencies and maintainer-alignment evidence.

func (*Service) PullRequestCollisions 

func (s *Service) PullRequestCollisions(ctx context.Context, repo cli.RepoRef, number int, limit int) (*PullRequestCollisionResult, error)

PullRequestCollisions returns a bounded, ranked list of open pull requests that may collide with the query PR. It uses only existing local data: base branch from the stored PR payload, explicit cross-references in the title/body, and shared author. No network access occurs and no semantic file overlap is invented.

func (*Service) RecordContribution 

func (s *Service) RecordContribution(ctx context.Context, opts cli.RecordContributionOptions) (*cli.ContributionResult, error)

RecordContribution stores prepared or submitted contribution metadata for an opportunity, keeping it separate from live GitHub state.

func (*Service) RecordContributionOutcome 

func (s *Service) RecordContributionOutcome(ctx context.Context, opts cli.RecordContributionOutcomeOptions) (*cli.ContributionOutcomeResult, error)

RecordContributionOutcome stores a lifecycle outcome for a contribution.

func (*Service) RecordEvidence 

func (s *Service) RecordEvidence(ctx context.Context, input RecordEvidenceInput) (*evidence.Evidence, error)

RecordEvidence stores an evidence item scoped to its parent workflow.

func (*Service) RecordEvidenceForCLI 

func (s *Service) RecordEvidenceForCLI(ctx context.Context, opts cli.RecordEvidenceOptions) (any, error)

RecordEvidenceForCLI maps CLI evidence fields to the application evidence model.

func (*Service) RecordTriageEvent 

func (s *Service) RecordTriageEvent(ctx context.Context, opts cli.RecordTriageEventOptions) (*cli.TriageEventResult, error)

RecordTriageEvent records a local triage or feedback outcome for a typed target.

func (*Service) RepositoryHealth 

func (s *Service) RepositoryHealth(ctx context.Context, repo cli.RepoRef) (*health.Report, error)

RepositoryHealth returns a deterministic repository health report derived from already stored corpus facts. It performs no network access.

func (*Service) RepositoryHealthWithOptions 

func (s *Service) RepositoryHealthWithOptions(ctx context.Context, repo cli.RepoRef, opts health.Options) (*health.Report, error)

RepositoryHealthWithOptions returns a deterministic repository health report using the provided analysis window and stale threshold.

func (*Service) RunHistory 

func (s *Service) RunHistory(ctx context.Context, limit int) (*cli.RunListResult, error)

RunHistory returns bounded durable run metadata.

func (*Service) RunValidation 

func (s *Service) RunValidation(ctx context.Context, id string, opts cli.RunValidationOptions) (*cli.ValidationRunResult, error)

RunValidation executes a stored validation definition against the base or candidate workspace.

func (*Service) Search 

func (s *Service) Search(ctx context.Context, query string, opts cli.SearchOptions) (*cli.SearchResult, error)

Search performs a local-only corpus search and supports repo and kind filters.

func (*Service) SetArchiveFetcher 

func (s *Service) SetArchiveFetcher(f discovery.ArchiveFetcher)

SetArchiveFetcher overrides the GH Archive fetcher. It is intended for tests.

func (*Service) SetClock 

func (s *Service) SetClock(clock func() time.Time)

SetClock overrides the time source. It is intended for tests.

func (*Service) SetCollisionForCLI 

func (s *Service) SetCollisionForCLI(ctx context.Context, id, status, rationale string) (any, error)

SetCollisionForCLI records a reviewed collision status and rationale.

func (*Service) SetGitHubReader 

func (s *Service) SetGitHubReader(r github.Reader)

SetGitHubReader overrides the GitHub reader. It is intended for tests.

func (*Service) SetOpportunityStatus 

func (s *Service) SetOpportunityStatus(ctx context.Context, id, status, rationale string) (*cli.OpportunityResult, error)

SetOpportunityStatus transitions an opportunity with a recorded rationale.

func (*Service) Setup 

func (s *Service) Setup(ctx context.Context, opts cli.SetupOptions) (*cli.SetupReport, error)

Setup initializes local state, optionally installs the published CLI through npm, and registers the MCP server with selected coding clients. Terminal and MCP setup are independent capabilities: either can be selected alone, and a terminal-install failure does not prevent MCP from using its pinned npx fallback. Any failed step still makes the overall CLI command unsuccessful.

Dry-run setup validates and reports the same capability plan without invoking npm or writing local state. Setup performs no GitHub access and never executes repository-controlled code.

func (*Service) ShowEvidence 

func (s *Service) ShowEvidence(ctx context.Context, investigationID string) (*cli.EvidenceResult, error)

ShowEvidence returns the evidence packet for an investigation.

func (*Service) ShowInvestigation 

func (s *Service) ShowInvestigation(ctx context.Context, id string) (*cli.InvestigationResult, error)

ShowInvestigation returns an investigation by ID.

func (*Service) ShowLens 

func (s *Service) ShowLens(ctx context.Context, name string) (*cli.LensResult, error)

ShowLens returns a saved lens by name.

func (*Service) ShowOpportunity 

func (s *Service) ShowOpportunity(ctx context.Context, id string) (*cli.OpportunityResult, error)

ShowOpportunity returns an opportunity by ID.

func (*Service) ShowSource 

func (s *Service) ShowSource(ctx context.Context, name string) (*cli.SourceResult, error)

ShowSource returns one saved discovery source from the local corpus.

func (*Service) ShowValidation 

func (s *Service) ShowValidation(ctx context.Context, id string) (*cli.ValidationResult, error)

ShowValidation returns a stored validation definition without executing it.

func (*Service) ShowWorkspace 

func (s *Service) ShowWorkspace(ctx context.Context, id string) (*cli.WorkspaceResult, error)

ShowWorkspace returns a workspace by ID with its current dirty state.

func (*Service) StartInvestigation 

func (s *Service) StartInvestigation(ctx context.Context, repo cli.RepoRef, commitSHA, lens string) (*cli.InvestigationResult, error)

StartInvestigation creates a new investigation scoped to a repository.

func (*Service) StartInvestigationFromThread 

func (s *Service) StartInvestigationFromThread(ctx context.Context, requested research.ThreadRef) (*cli.ThreadInvestigationResult, error)

StartInvestigationFromThread atomically creates an investigation and seed hypothesis from one exact local observation. It performs no network access or process execution.

func (*Service) Status 

func (s *Service) Status(ctx context.Context) (*cli.StatusResult, error)

Status reports whether the corpus is healthy and counts local records.

func (*Service) Sync 

func (s *Service) Sync(ctx context.Context, repo cli.RepoRef) (*cli.SyncResult, error)

Sync fetches all repository threads. It preserves the original archive API while SyncWithOptions provides bounded incremental and exact refreshes.

func (*Service) SyncWithOptions 

func (s *Service) SyncWithOptions(ctx context.Context, repo cli.RepoRef, syncOpts SyncOptions) (*cli.SyncResult, error)

SyncWithOptions fetches a repository and a bounded thread selection from GitHub, then writes ordered observations to the local corpus.

func (*Service) TailSource 

func (s *Service) TailSource(ctx context.Context, name string, opts cli.TailOptions) (*cli.TailResult, error)

TailSource repeatedly advances a named source until cancellation. Each iteration is an ordinary idempotent crawl and therefore retains its own run record, checkpoint, request budget, and failure state.

func (*Service) ThreadResearchBrief 

func (s *Service) ThreadResearchBrief(ctx context.Context, ref research.ThreadRef) (*research.Brief, error)

ThreadResearchBrief builds a deterministic brief from the local corpus. It performs no network access, local mutation, or process execution.

func (*Service) TransitionHypothesis 

func (s *Service) TransitionHypothesis(ctx context.Context, hypothesisID, status, rationale string) (*investigation.Hypothesis, error)

TransitionHypothesis advances a hypothesis through its lifecycle with rationale.

func (*Service) TransitionHypothesisForCLI 

func (s *Service) TransitionHypothesisForCLI(ctx context.Context, id, status, rationale string) (any, error)

TransitionHypothesisForCLI validates and records a rationale-bearing status change.

func (*Service) UpdateHypothesis 

func (s *Service) UpdateHypothesis(ctx context.Context, hypothesisID string, input investigation.UpdateHypothesisInput) (*investigation.Hypothesis, error)

UpdateHypothesis deliberately overwrites a hypothesis with rationale.

func (*Service) UpdateHypothesisForCLI 

func (s *Service) UpdateHypothesisForCLI(ctx context.Context, id string, opts cli.HypothesisUpdateOptions) (any, error)

UpdateHypothesisForCLI maps CLI update options to the structured application input.

func (*Service) UpdateOpportunityCollisionStatus 

func (s *Service) UpdateOpportunityCollisionStatus(ctx context.Context, opportunityID, status, rationale string) (*investigation.Opportunity, error)

UpdateOpportunityCollisionStatus explicitly sets the collision status with rationale.

func (*Service) Upgrade 

func (s *Service) Upgrade(ctx context.Context, opts cli.UpgradeOptions) (*cli.UpgradeReport, error)

Upgrade checks npm for the latest release and updates persistent npm installations when explicitly authorized.

func (*Service) WorkspaceDiff 

func (s *Service) WorkspaceDiff(ctx context.Context, id string) (*WorkspaceDiffResult, error)

WorkspaceDiff returns the current diff of a workspace against its recorded base, including changed files and a suggested review order.

func (*Service) WorkspaceDiffForCLI 

func (s *Service) WorkspaceDiffForCLI(ctx context.Context, id string) (any, error)

WorkspaceDiffForCLI returns bounded diff metadata for a managed workspace.

type SyncOptions 

type SyncOptions struct {
	State    string
	Since    time.Time
	Numbers  []int
	MaxPages int
}

SyncOptions bounds and filters an explicit repository synchronization.

type ThreadRef 

type ThreadRef struct {
	Kind   string `json:"kind"`
	Owner  string `json:"owner"`
	Repo   string `json:"repo"`
	Number int    `json:"number"`
}

ThreadRef identifies a thread with minimal fields.

type WorkspaceDiffResult 

type WorkspaceDiffResult struct {
	ID               string       `json:"id"`
	Repo             cli.RepoRef  `json:"repo"`
	BaseSHA          string       `json:"base_sha"`
	CandidateSHA     string       `json:"candidate_sha"`
	MergeBase        string       `json:"merge_base"`
	Dirty            bool         `json:"dirty"`
	HasUntracked     bool         `json:"has_untracked"`
	Diff             string       `json:"diff"`
	ChangedFiles     []string     `json:"changed_files"`
	ChangedFileCount int          `json:"changed_file_count"`
	DiffBytes        int          `json:"diff_bytes"`
	ReviewOrder      []ReviewStep `json:"review_order"`
}

WorkspaceDiffResult is the complete diff metadata for a workspace.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.