tools

type ActivationResult struct {
	Kind  string `json:"kind"`
	Name  string `json:"name"`
	Group string `json:"group,omitempty"`
	// ToolCount is len(ActivatedTools); kept as a separate field for
	// backwards compatibility with clients that read it directly.
	ToolCount int `json:"toolCount"`
	// ActivatedTools enumerates every tool name brought online by this
	// activation. For Tier-2 tool-name activations, this is the full
	// containing group — the LLM sees exactly what other capabilities
	// it just gained alongside the requested one. Empty for Tier-1
	// single-tool activation by design.
	ActivatedTools []string `json:"activatedTools,omitempty"`
	// TotalVisibleTools is the post-activation tools/list count after
	// bootstrap and policy filtering. Zero means the activator could not
	// compute the session total and activationPayload omits it.
	TotalVisibleTools int `json:"totalVisibleTools,omitempty"`
	// VisibleActivatedTools is ActivatedTools filtered through the same
	// post-activation tools/list visibility gate. nil preserves legacy
	// activation callbacks; non-nil means activationPayload should expose
	// this filtered set as activated_tools.
	VisibleActivatedTools []string `json:"visibleActivatedTools,omitempty"`
	// ActivatedToolsHiddenByBootstrap names activated tools that remained
	// hidden because the active bootstrap config did not expose them.
	ActivatedToolsHiddenByBootstrap []string `json:"activatedToolsHiddenByBootstrap,omitempty"`
	// ActivatedToolsBlockedByPolicy names activated tools that remained
	// hidden because policy enforcement filtered them from tools/list.
	ActivatedToolsBlockedByPolicy []string `json:"activatedToolsBlockedByPolicy,omitempty"`
}

type DateRange struct {
	Start string `json:"start"`
	End   string `json:"end"`
}

type DaySummary struct {
	Date         string  `json:"date"`
	Entries      int     `json:"entries"`
	TotalSeconds int64   `json:"totalSeconds"`
	TotalHours   float64 `json:"totalHours"`
}

type DeactivationResult struct {
	Kind              string   `json:"kind"`
	Name              string   `json:"name"`
	Group             string   `json:"group,omitempty"`
	ToolCount         int      `json:"toolCount"`
	DeactivatedTools  []string `json:"deactivatedTools,omitempty"`
	TotalVisibleTools int      `json:"totalVisibleTools,omitempty"`
}

type FindAndUpdateEntryData struct {
	Entry          clockify.TimeEntry      `json:"entry"`
	MatchedBy      map[string]any          `json:"matchedBy"`
	UpdatedFields  []string                `json:"updatedFields"`
	MatchedEntryID string                  `json:"matched_entry_id,omitempty"`
	Current        *TimeEntryUpdatePreview `json:"current,omitempty"`
	Proposed       map[string]any          `json:"proposed_changes,omitempty"`
	DryRun         bool                    `json:"dry_run,omitempty"`
	Note           string                  `json:"note,omitempty"`
}

type IdentityData struct {
	User        clockify.User `json:"user"`
	WorkspaceID string        `json:"workspaceId"`
}

type LogTimeData struct {
	Entry           clockify.TimeEntry `json:"entry"`
	ResolvedProject string             `json:"resolvedProject,omitempty"`
}

type ProjectSummary struct {
	ProjectID    string  `json:"projectId,omitempty"`
	ProjectName  string  `json:"projectName"`
	Entries      int     `json:"entries"`
	TotalSeconds int64   `json:"totalSeconds"`
	TotalHours   float64 `json:"totalHours"`
}

type QuickReportData struct {
	Range               DateRange            `json:"range"`
	Totals              SummaryTotals        `json:"totals"`
	TopProject          *ProjectSummary      `json:"topProject,omitempty"`
	RunningEntries      []clockify.TimeEntry `json:"runningEntries,omitempty"`
	EntriesSample       []clockify.TimeEntry `json:"entriesSample,omitempty"`
	ProjectsRepresented int                  `json:"projectsRepresented"`
	SuggestedActions    []ToolSuggestion     `json:"suggestedActions"`
}

type ResultEnvelope struct {
	OK     bool           `json:"ok"`
	Action string         `json:"action"`
	Data   any            `json:"data,omitempty"`
	Meta   map[string]any `json:"meta,omitempty"`
}

type Service struct {
	Client          *clockify.Client
	WorkspaceID     string
	DefaultTimezone *time.Location        // from CLOCKIFY_TIMEZONE; nil falls back to time.Now().Location() for flexible date/time inputs.
	DedupeConfig    *dedupe.Config        // optional, set during wiring
	PolicyDescribe  func() map[string]any // set during wiring; returns policy description
	Bootstrap       *bootstrap.Config     // set during wiring; describes current bootstrap visibility
	ActivateGroup   func(context.Context, string) (ActivationResult, error)
	ActivateTool    func(context.Context, string) (ActivationResult, error)
	DeactivateGroup func(context.Context, string) (DeactivationResult, error)
	GroupActivation func(string) (allowed bool, reason string)
	// WebhookValidateDNS, when true, makes CreateWebhook/UpdateWebhook
	// resolve the webhook host via the system resolver and reject any
	// reply that contains a private/reserved IP. Config defaults this
	// on for every profile so a hostname pointing at 169.254.169.254
	// (cloud-metadata) or 10.0.0.x cannot turn the Clockify webhook
	// delivery into an SSRF probe. Operators can explicitly opt out
	// for trusted air-gapped tests.
	WebhookValidateDNS bool
	// WebhookHostResolver overrides the LookupIPAddr call for tests.
	// nil = use net.DefaultResolver.
	WebhookHostResolver func(context.Context, string) ([]netip.Addr, error)
	// WebhookAllowedDomains is an optional escape-hatch list of webhook
	// hostnames that bypass the WebhookValidateDNS private-IP check.
	// Each entry is matched against the parsed URL's host (lowercased)
	// either by exact equality (`webhook.example.com`) or by suffix
	// when the entry begins with a dot (`.example.com` matches
	// `webhook.example.com` and `api.example.com` but NOT
	// `attacker.example.com.evil.com`). Empty list = no bypass; the
	// DNS check applies to every host. Operators use this to admit
	// known-trusted hostnames in split-horizon DNS environments where
	// the hostname legitimately resolves to a private IP only on the
	// control-plane network. See `docs/runbooks/webhook-dns-validation.md`
	// §4b for the use case. Production wiring (env var + Config field)
	// follows in a later commit; tests inject this field directly.
	WebhookAllowedDomains []string
	// Notifier delivers server→client notifications (progress, resource updates,
	// etc.) emitted by tool handlers. nil = drop silently.
	Notifier mcp.Notifier
	// EmitResourceUpdate publishes notifications/resources/updated for a URI
	// with an optional delta envelope. Wired from runtime.go to
	// Server.NotifyResourceUpdated so the subscription gate lives in the
	// protocol core rather than in every mutation handler. nil = drop silently
	// (tests without a Server wired).
	EmitResourceUpdate func(uri string, delta mcp.ResourceUpdateDelta)
	// SubscriptionGate reports whether any client is currently subscribed
	// to a URI. When wired (runtime.go sets it to
	// Server.HasResourceSubscription), emitResourceUpdate short-circuits
	// before the ReadResource round-trip so unsubscribed mutations don't
	// pay for a redundant fetch. nil = gate disabled; every emit pays for
	// the re-read (W3-era behaviour, preserved for tests).
	SubscriptionGate func(uri string) bool
	// ReportMaxEntries is the hard cap on the number of time entries a report
	// tool will aggregate. 0 disables the cap. Wired from CLOCKIFY_REPORT_MAX_ENTRIES.
	ReportMaxEntries int
	// DeltaFormat selects the diff algorithm for resource notifications.
	// "merge" (default) uses RFC 7396 merge patch; "jsonpatch" uses RFC 6902.
	DeltaFormat string
	// contains filtered or unexported fields
}

type SummaryData struct {
	Range            DateRange            `json:"range"`
	Totals           SummaryTotals        `json:"totals"`
	ByProject        []ProjectSummary     `json:"byProject"`
	SuggestedActions []ToolSuggestion     `json:"suggestedActions"`
	Entries          []clockify.TimeEntry `json:"entries,omitempty"`
}

type SummaryTotals struct {
	Entries        int     `json:"entries"`
	RunningEntries int     `json:"runningEntries"`
	TotalSeconds   int64   `json:"totalSeconds"`
	TotalHours     float64 `json:"totalHours"`
}

type Tier2Group struct {
	Name        string
	Description string
	Keywords    []string
	ToolNames   []string
	Builder     func(s *Service) []mcp.ToolDescriptor
}

type TimeEntryDraft struct {
	Start       string `json:"start"`
	End         string `json:"end"`
	ProjectID   string `json:"projectId,omitempty"`
	Project     string `json:"project,omitempty"`
	Description string `json:"description"`
	Billable    *bool  `json:"billable,omitempty"`
}

type TimeEntryRef struct {
	ID          string `json:"id"`
	Description string `json:"description,omitempty"`
	ProjectID   string `json:"projectId,omitempty"`
	ProjectName string `json:"projectName,omitempty"`
	Start       string `json:"start,omitempty"`
	End         string `json:"end,omitempty"`
}

type TimeEntryUpdatePreview struct {
	Description string `json:"description"`
	ProjectID   string `json:"project_id,omitempty"`
	Start       string `json:"start,omitempty"`
	End         string `json:"end,omitempty"`
	Billable    bool   `json:"billable"`
}

type TimesheetFillGapData struct {
	DryRun    bool               `json:"dryRun"`
	Proposed  TimeEntryDraft     `json:"proposed"`
	Entry     clockify.TimeEntry `json:"entry,omitempty"`
	Overlaps  []TimeEntryRef     `json:"overlaps,omitempty"`
	Validated bool               `json:"validated"`
}

type TimesheetIssue struct {
	Type            string   `json:"type"`
	Severity        string   `json:"severity"`
	Message         string   `json:"message"`
	EntryID         string   `json:"entryId,omitempty"`
	RelatedEntryIDs []string `json:"relatedEntryIds,omitempty"`
	Start           string   `json:"start,omitempty"`
	End             string   `json:"end,omitempty"`
}

type TimesheetReviewData struct {
	Range            DateRange            `json:"range"`
	Totals           SummaryTotals        `json:"totals"`
	ByDay            []DaySummary         `json:"byDay"`
	ByProject        []ProjectSummary     `json:"byProject"`
	Issues           []TimesheetIssue     `json:"issues"`
	SuggestedActions []ToolSuggestion     `json:"suggestedActions"`
	Entries          []clockify.TimeEntry `json:"entries,omitempty"`
}

type ToolSuggestion struct {
	Tool        string         `json:"tool"`
	Reason      string         `json:"reason"`
	Arguments   map[string]any `json:"arguments,omitempty"`
	MissingArgs []string       `json:"missingArgs,omitempty"`
}

type WeeklySummaryData struct {
	Range            DateRange            `json:"range"`
	Totals           SummaryTotals        `json:"totals"`
	ByDay            []DaySummary         `json:"byDay"`
	ByProject        []ProjectSummary     `json:"byProject"`
	SuggestedActions []ToolSuggestion     `json:"suggestedActions"`
	Entries          []clockify.TimeEntry `json:"entries,omitempty"`
	UnassignedKey    string               `json:"unassignedKey,omitempty"`
}

type WorkspaceContext struct {
	WorkspaceID string `json:"workspaceId"`
}