cairnline.go

// Package cairnline exposes the embeddable project coordination core.
//
// The root package is the public API intended for applications such as Hecate.
// Concrete storage internals remain in internal packages; NewMCPServer exposes
// the MCP protocol server so an embedding host can mount Cairnline's tool and
// resource surface on its own transport.
package cairnline

import (
	"context"
	"time"

	"github.com/hecatehq/cairnline/internal/app"
	"github.com/hecatehq/cairnline/internal/core"
	"github.com/hecatehq/cairnline/internal/mcp"
	"github.com/hecatehq/cairnline/internal/sqlitestore"
)

var (
	ErrNotFound  = core.ErrNotFound
	ErrInvalid   = core.ErrInvalid
	ErrDuplicate = core.ErrDuplicate
	ErrConflict  = core.ErrConflict
)

type Store = core.Store
type Service = core.Service
type ServiceOption = core.ServiceOption
type MemoryStore = core.MemoryStore
type SQLiteStore = sqlitestore.Store

type Project = core.Project
type Root = core.Root
type Source = core.Source
type ProjectSkill = core.ProjectSkill
type RequiredPermissions = core.RequiredPermissions
type Role = core.Role
type WorkItem = core.WorkItem
type WorkItemCloseoutReadiness = core.WorkItemCloseoutReadiness
type ProjectSetupReadiness = core.ProjectSetupReadiness
type ProjectSetupReadinessSummary = core.ProjectSetupReadinessSummary
type ProjectSetupReadinessCheck = core.ProjectSetupReadinessCheck
type ProjectSetupReadinessAction = core.ProjectSetupReadinessAction
type ProjectHealth = core.ProjectHealth
type ProjectHealthSummary = core.ProjectHealthSummary
type ProjectHealthAttentionItem = core.ProjectHealthAttentionItem
type AssistantProposal = core.AssistantProposal
type AssistantProposalRecord = core.AssistantProposalRecord
type AssistantApplyAttempt = core.AssistantApplyAttempt
type AssistantAction = core.AssistantAction
type AssistantTarget = core.AssistantTarget
type AssistantApplyResult = core.AssistantApplyResult
type AssistantActionResult = core.AssistantActionResult
type ProjectOperationsBrief = core.ProjectOperationsBrief
type ProjectOperationsCounts = core.ProjectOperationsCounts
type ProjectOperationItem = core.ProjectOperationItem
type ProjectActivity = core.ProjectActivity
type ProjectActivityCounts = core.ProjectActivityCounts
type ProjectActivityBuckets = core.ProjectActivityBuckets
type ProjectActivityItem = core.ProjectActivityItem
type ReviewFollowUpReadiness = core.ReviewFollowUpReadiness
type DesiredAgent = core.DesiredAgent
type ExecutionRef = core.ExecutionRef
type Assignment = core.Assignment
type AssignmentClaimLease = core.AssignmentClaimLease
type AssignmentCoordination = core.AssignmentCoordination
type QueuedAssignmentUpdate = core.QueuedAssignmentUpdate
type AssignmentPreparation = core.AssignmentPreparation
type AssignmentCompatibilityFilter = core.AssignmentCompatibilityFilter
type AssignmentContext = core.AssignmentContext
type AssignmentLaunchPacket = core.AssignmentLaunchPacket
type Artifact = core.Artifact
type Evidence = core.Evidence
type Review = core.Review
type Handoff = core.Handoff
type HandoffPatch = core.HandoffPatch
type HandoffUpdate = core.HandoffUpdate
type HandoffStatusUpdate = core.HandoffStatusUpdate
type HandoffDelete = core.HandoffDelete
type AcceptHandoffWithFollowUpCommand = core.AcceptHandoffWithFollowUpCommand
type HandoffFollowUpResult = core.HandoffFollowUpResult
type MemoryEntry = core.MemoryEntry
type MemoryCandidate = core.MemoryCandidate
type MemoryCandidateSourceRef = core.MemoryCandidateSourceRef
type MemoryCandidateFilter = core.MemoryCandidateFilter
type MemoryCandidatePromotion = core.MemoryCandidatePromotion
type Snapshot = core.Snapshot

const (
	SnapshotVersion                = core.SnapshotVersion
	DefaultAssignmentClaimLeaseTTL = core.DefaultAssignmentClaimLeaseTTL

	WorkStatusReady = core.WorkStatusReady
	WorkStatusDone  = core.WorkStatusDone
	PriorityNormal  = core.PriorityNormal

	ExecutionManual          = core.ExecutionManual
	ExecutionMCPPull         = core.ExecutionMCPPull
	ExecutionExternalAdapter = core.ExecutionExternalAdapter
	ExecutionOrchestrated    = core.ExecutionOrchestrated

	AssignmentQueued           = core.AssignmentQueued
	AssignmentClaimed          = core.AssignmentClaimed
	AssignmentRunning          = core.AssignmentRunning
	AssignmentAwaitingApproval = core.AssignmentAwaitingApproval
	AssignmentReview           = core.AssignmentReview
	AssignmentCompleted        = core.AssignmentCompleted
	AssignmentFailed           = core.AssignmentFailed
	AssignmentCancelled        = core.AssignmentCancelled

	DesiredAgentAny = core.DesiredAgentAny

	HandoffFollowUpIntentAcceptAndEnsure = core.HandoffFollowUpIntentAcceptAndEnsure
	HandoffFollowUpCreated               = core.HandoffFollowUpCreated
	HandoffFollowUpLinkedExisting        = core.HandoffFollowUpLinkedExisting
	HandoffFollowUpAlreadySatisfied      = core.HandoffFollowUpAlreadySatisfied

	SkillFormatMarkdown  = core.SkillFormatMarkdown
	SkillStatusAvailable = core.SkillStatusAvailable
	SkillStatusMissing   = core.SkillStatusMissing
	SkillStatusInvalid   = core.SkillStatusInvalid
	SkillStatusConflict  = core.SkillStatusConflict
	SkillTrustWorkspace  = core.SkillTrustWorkspace
	SkillPathAgents      = core.SkillPathAgents
	SkillPathHecate      = core.SkillPathHecate
	SkillPathCairnline   = core.SkillPathCairnline
	SkillPathClaude      = core.SkillPathClaude
	SkillPathGemini      = core.SkillPathGemini

	EvidenceTrustOperator = core.EvidenceTrustOperator

	ReviewVerdictApproved         = core.ReviewVerdictApproved
	ReviewVerdictChangesRequested = core.ReviewVerdictChangesRequested
	ReviewVerdictBlocked          = core.ReviewVerdictBlocked
	ReviewVerdictRisk             = core.ReviewVerdictRisk
	ReviewVerdictPass             = core.ReviewVerdictPass
	ReviewVerdictConcerns         = core.ReviewVerdictConcerns
	ReviewRiskLow                 = core.ReviewRiskLow
	ReviewRiskMedium              = core.ReviewRiskMedium
	ReviewRiskHigh                = core.ReviewRiskHigh
	ReviewRiskUnknown             = core.ReviewRiskUnknown
	ReviewStatusRecorded          = core.ReviewStatusRecorded

	HandoffStatusOpen       = core.HandoffStatusOpen
	HandoffStatusAccepted   = core.HandoffStatusAccepted
	HandoffStatusSuperseded = core.HandoffStatusSuperseded
	HandoffStatusDismissed  = core.HandoffStatusDismissed

	MemoryTrustOperator   = core.MemoryTrustOperator
	MemoryTrustGenerated  = core.MemoryTrustGenerated
	MemorySourceOperator  = core.MemorySourceOperator
	MemorySourceGenerated = core.MemorySourceGenerated

	MemoryCandidatePending  = core.MemoryCandidatePending
	MemoryCandidatePromoted = core.MemoryCandidatePromoted
	MemoryCandidateRejected = core.MemoryCandidateRejected
	MemoryCandidateProposed = core.MemoryCandidateProposed

	ProjectOperationsStatusClear     = core.ProjectOperationsStatusClear
	ProjectOperationsStatusAttention = core.ProjectOperationsStatusAttention

	ProjectSetupStatusReady    = core.ProjectSetupStatusReady
	ProjectSetupStatusTodo     = core.ProjectSetupStatusTodo
	ProjectSetupStatusOptional = core.ProjectSetupStatusOptional

	ProjectSetupActionSetupProject   = core.ProjectSetupActionSetupProject
	ProjectSetupActionCreateWorkItem = core.ProjectSetupActionCreateWorkItem
	ProjectSetupActionUpdateProject  = core.ProjectSetupActionUpdateProject
	ProjectSetupActionManageContext  = core.ProjectSetupActionManageContext
	ProjectSetupActionManageRoles    = core.ProjectSetupActionManageRoles

	ProjectHealthStatusClear     = core.ProjectHealthStatusClear
	ProjectHealthStatusAttention = core.ProjectHealthStatusAttention

	AssistantProposalSourceAPI       = core.AssistantProposalSourceAPI
	AssistantProposalSourceAssistant = core.AssistantProposalSourceAssistant

	AssistantProposalStatusProposed     = core.AssistantProposalStatusProposed
	AssistantProposalStatusNeedsConfirm = core.AssistantProposalStatusNeedsConfirm
	AssistantProposalStatusApplied      = core.AssistantProposalStatusApplied
	AssistantProposalStatusPartial      = core.AssistantProposalStatusPartial
	AssistantProposalStatusRejected     = core.AssistantProposalStatusRejected

	AssistantActionCreateProject         = core.AssistantActionCreateProject
	AssistantActionUpdateProject         = core.AssistantActionUpdateProject
	AssistantActionAttachProjectRoot     = core.AssistantActionAttachProjectRoot
	AssistantActionRemoveProjectRoot     = core.AssistantActionRemoveProjectRoot
	AssistantActionSetProjectDefaults    = core.AssistantActionSetProjectDefaults
	AssistantActionCreateRole            = core.AssistantActionCreateRole
	AssistantActionUpdateRole            = core.AssistantActionUpdateRole
	AssistantActionCreateWorkItem        = core.AssistantActionCreateWorkItem
	AssistantActionUpdateWorkItem        = core.AssistantActionUpdateWorkItem
	AssistantActionCreateAssignment      = core.AssistantActionCreateAssignment
	AssistantActionCreateEvidence        = core.AssistantActionCreateEvidence
	AssistantActionCreateReview          = core.AssistantActionCreateReview
	AssistantActionCreateHandoff         = core.AssistantActionCreateHandoff
	AssistantActionUpdateHandoff         = core.AssistantActionUpdateHandoff
	AssistantActionCreateMemoryCandidate = core.AssistantActionCreateMemoryCandidate

	AssistantApplyStatusApplied      = core.AssistantApplyStatusApplied
	AssistantApplyStatusNeedsConfirm = core.AssistantApplyStatusNeedsConfirm
	AssistantApplyStatusPartial      = core.AssistantApplyStatusPartial
	AssistantApplyStatusRejected     = core.AssistantApplyStatusRejected

	ProjectOperationKindAssignment      = core.ProjectOperationKindAssignment
	ProjectOperationKindCloseoutReady   = core.ProjectOperationKindCloseoutReady
	ProjectOperationKindHandoff         = core.ProjectOperationKindHandoff
	ProjectOperationKindMemoryCandidate = core.ProjectOperationKindMemoryCandidate
	ProjectOperationKindMissingEvidence = core.ProjectOperationKindMissingEvidence
	ProjectOperationKindReviewFollowUp  = core.ProjectOperationKindReviewFollowUp
	ProjectOperationKindProjectSetup    = core.ProjectOperationKindProjectSetup
	ProjectOperationKindSkill           = core.ProjectOperationKindSkill
	ProjectOperationKindWorkItem        = core.ProjectOperationKindWorkItem
	ProjectOperationActionRecoverClaim  = core.ProjectOperationActionRecoverClaim

	ProjectOperationSeverityBlocked = core.ProjectOperationSeverityBlocked
	ProjectOperationSeverityAction  = core.ProjectOperationSeverityAction
	ProjectOperationSeverityActive  = core.ProjectOperationSeverityActive
	ProjectOperationSeverityReady   = core.ProjectOperationSeverityReady
	ProjectOperationSeverityInfo    = core.ProjectOperationSeverityInfo

	ProjectActivityBucketActive    = core.ProjectActivityBucketActive
	ProjectActivityBucketBlocked   = core.ProjectActivityBucketBlocked
	ProjectActivityBucketCompleted = core.ProjectActivityBucketCompleted
	ProjectActivityBucketOther     = core.ProjectActivityBucketOther

	LaunchPacketKindAssignment = core.LaunchPacketKindAssignment
)

func NewService(store Store, options ...ServiceOption) *Service {
	return core.NewService(store, options...)
}

// WithAssignmentClaimLeaseTTL configures the pre-start lease used by portable
// worker claims created through ClaimAssignmentWithLease and MCP. Positive
// values are rounded up to whole seconds with a one-second minimum.
func WithAssignmentClaimLeaseTTL(ttl time.Duration) ServiceOption {
	return core.WithAssignmentClaimLeaseTTL(ttl)
}

func NewMemoryStore() *MemoryStore {
	return core.NewMemoryStore()
}

func NewMemoryService() *Service {
	return NewService(NewMemoryStore())
}

func OpenSQLiteStore(ctx context.Context, path string) (*SQLiteStore, error) {
	return sqlitestore.Open(ctx, path)
}

func NewSQLiteService(ctx context.Context, path string) (*Service, *SQLiteStore, error) {
	store, err := OpenSQLiteStore(ctx, path)
	if err != nil {
		return nil, nil, err
	}
	return NewService(store), store, nil
}

// MCPServer is the MCP protocol server that exposes Cairnline's coordination
// tools and resources. Build one with NewMCPServer, then mount it on a custom
// transport via HandleMessage or run the built-in stdio loop with Serve.
// DeclareExtension advertises optional protocol extensions during initialize.
type MCPServer = mcp.Server

// NewMCPServer builds an MCP server with Cairnline's full tool and resource set
// registered against service. version is reported in serverInfo and the
// coordination.capabilities tool.
func NewMCPServer(service *Service, version string) *MCPServer {
	return app.NewServer(service, version)
}