Task Provider System

Overview

The task provider system is a pluggable architecture for displaying project tasks from any source. Providers are executable scripts that output standardized JSON.

Architecture

.navi.yaml (per-project)     ~/.navi/config.yaml (global)
    │                              │
    ▼                              ▼
Config Parser (internal/task/config.go)
    │
    ▼
Provider Discovery (internal/task/discover.go)
    │
    ▼
Provider Execution (internal/task/provider.go)
    │
    ├── Execute script with args from config
    ├── Parse stdout as JSON
    └── Validate against ProviderResult schema
    │
    ▼
Result Cache (internal/task/cache.go)
    │
    ├── Cache by project + provider
    └── TTL from config (default 30s)
    │
    ▼
TUI Task Panel (internal/tui/tasks.go, taskview.go)

Key Types

// Task represents a single task item
type Task struct {
    ID       string
    Title    string
    Status   string
    Assignee string
    Labels   []string
    Priority int
    URL      string
    Created  time.Time
    Updated  time.Time
}

// TaskGroup represents a collection of related tasks
type TaskGroup struct {
    ID     string
    Title  string
    Status string
    URL    string
    Tasks  []Task
}

// ProviderResult is the output from a task provider
type ProviderResult struct {
    Groups []TaskGroup
    Tasks  []Task
}

Provider Contract

A provider script must:

1. Be executable
2. Accept arguments from the config’s args field
3. Output valid JSON to stdout matching the ProviderResult schema
4. Exit with code 0 on success

Built-in Providers

markdown-tasks (providers/markdown-tasks.sh)

Scans a directory of markdown files for task definitions. Groups tasks by parent directory, parses task status from markdown content.

github-issues (providers/github-issues.sh)

Uses the gh CLI to fetch issues from a GitHub repository. Groups by milestone or project.

Caching

Provider results are cached to avoid frequent script execution:

• Cache key: project path + provider name
• Default TTL: 30 seconds (configurable via interval in .navi.yaml)
• Cache is invalidated on manual refresh (r key in task panel)