Documentation
¶
Index ¶
- Constants
- func HashExternalTask(ext ExternalTask) string
- func HashLocalFile(path string) (string, error)
- func Register(s Source)
- func RegisteredNames() []string
- func SaveState(dir, sourceName string, state *SyncState) error
- func Unregister(name string)
- func UpdateSyncedTaskFile(filePath string, mapped MappedTask) error
- func WriteTaskFile(dir, id string, mapped MappedTask, externalID, sourceName string) (string, error)
- type Config
- type Engine
- type ExternalTask
- type FieldMap
- type ImportAction
- type ImportConfig
- type ImportResult
- type MappedTask
- type Source
- type SourceConfig
- type SyncAction
- type SyncConfig
- type SyncError
- type SyncResult
- type SyncState
- type TaskState
Constants ¶
const ( ConflictSkip = "skip" // default: skip conflicting tasks ConflictRemote = "remote" // overwrite local with remote ConflictLocal = "local" // keep local, update state hashes )
ConflictStrategy controls how conflicts are resolved during sync.
Variables ¶
This section is empty.
Functions ¶
func HashExternalTask ¶
func HashExternalTask(ext ExternalTask) string
HashExternalTask returns a deterministic hash of an external task's content.
func HashLocalFile ¶
HashLocalFile returns the SHA-256 hash of a file's contents.
func RegisteredNames ¶
func RegisteredNames() []string
RegisteredNames returns the sorted names of all registered sources.
func Unregister ¶
func Unregister(name string)
Unregister removes a source from the registry. Intended for testing.
func UpdateSyncedTaskFile ¶
func UpdateSyncedTaskFile(filePath string, mapped MappedTask) error
UpdateSyncedTaskFile updates an existing synced task file.
func WriteTaskFile ¶
func WriteTaskFile(dir, id string, mapped MappedTask, externalID, sourceName string) (string, error)
WriteTaskFile creates a new task markdown file and returns the file path.
Types ¶
type Config ¶
type Config struct {
Sync SyncConfig `yaml:"sync"`
}
Config is the top-level project configuration.
type Engine ¶
Engine orchestrates syncing tasks from external sources.
func (*Engine) RunSync ¶
func (e *Engine) RunSync(srcCfg SourceConfig) (*SyncResult, error)
RunSync syncs tasks for a single source configuration.
type ExternalTask ¶
type ExternalTask struct {
ExternalID string
Title string
Description string
Status string
Priority string
Assignee string
Labels []string
CreatedAt time.Time
UpdatedAt time.Time
URL string
Extra map[string]string
}
ExternalTask represents a task fetched from an external source.
type FieldMap ¶
type FieldMap struct {
Status map[string]string `yaml:"status"`
Priority map[string]string `yaml:"priority"`
LabelsToTags bool `yaml:"labels_to_tags"`
AssigneeToOwner bool `yaml:"assignee_to_owner"`
}
FieldMap configures how external fields are mapped to taskmd frontmatter.
type ImportAction ¶
type ImportAction struct {
ExternalID string
LocalID string
FilePath string
Title string
Reason string // "created" or "skipped_duplicate"
}
ImportAction describes a single import operation.
type ImportConfig ¶
type ImportConfig struct {
SourceName string
SourceCfg SourceConfig
OutputDir string
ScanDir string
DryRun bool
Verbose bool
}
ImportConfig holds configuration for a one-shot import run.
type ImportResult ¶
type ImportResult struct {
Created []ImportAction
Skipped []ImportAction
Errors []SyncError
}
ImportResult holds the outcome of an import run.
func RunImport ¶
func RunImport(cfg ImportConfig) (*ImportResult, error)
RunImport fetches tasks from an external source and writes them as local task files. Unlike RunSync, it performs no state tracking — it is a one-shot operation that detects duplicates via external_id in existing task files.
type MappedTask ¶
type MappedTask struct {
Title string
Description string
Status string
Priority string
Owner string
Tags []string
URL string
}
MappedTask holds the result of mapping an ExternalTask to taskmd fields.
func MapExternalTask ¶
func MapExternalTask(ext ExternalTask, fm FieldMap) MappedTask
MapExternalTask converts an ExternalTask to taskmd fields using the FieldMap.
type Source ¶
type Source interface {
Name() string
ValidateConfig(cfg SourceConfig) error
FetchTasks(cfg SourceConfig) ([]ExternalTask, error)
}
Source defines the interface that external task providers must implement.
type SourceConfig ¶
type SourceConfig struct {
Name string `yaml:"name"`
Project string `yaml:"project"`
BaseURL string `yaml:"base_url"`
TokenEnv string `yaml:"token_env"`
UserEnv string `yaml:"user_env"`
OutputDir string `yaml:"output_dir"`
FieldMap FieldMap `yaml:"field_map"`
Filters map[string]any `yaml:"filters"`
Extra map[string]string `yaml:"extra"`
}
SourceConfig describes a single external source.
type SyncAction ¶
type SyncAction struct {
ExternalID string
LocalID string
FilePath string
Title string
Reason string
}
SyncAction describes a single sync operation.
type SyncConfig ¶
type SyncConfig struct {
Sources []SourceConfig `yaml:"sources"`
}
SyncConfig holds the sync-specific configuration.
func LoadConfig ¶
func LoadConfig(dir string) (*SyncConfig, error)
LoadConfig reads the project config from dir/.taskmd.yaml and returns the sync section.
type SyncResult ¶
type SyncResult struct {
Created []SyncAction
Updated []SyncAction
Skipped []SyncAction
Conflicts []SyncAction
Errors []SyncError
}
SyncResult holds the outcome of a sync run.
type SyncState ¶
type SyncState struct {
Source string `yaml:"source"`
Tasks map[string]TaskState `yaml:"tasks"`
LastSync time.Time `yaml:"last_sync"`
}
SyncState tracks the last-synced state for a single source.
type TaskState ¶
type TaskState struct {
ExternalID string `yaml:"external_id"`
LocalID string `yaml:"local_id"`
FilePath string `yaml:"file_path"`
ExternalHash string `yaml:"external_hash"`
LocalHash string `yaml:"local_hash"`
LastSynced time.Time `yaml:"last_synced"`
}
TaskState tracks the sync state of a single task.