sync

Documentation

Index

• func ConsumeChangelog(cacheDir string) error
• func ExpandMarkers(content string, markers []Marker, results map[int]string) string
• func FetchArchive(rawURL, destDir, token string) error
• func FetchMarker(m Marker, client *http.Client) (string, error)
• func MostRecentSync(stateDir string) *time.Time
• func WriteChangelog(cacheDir string, syncedAt time.Time, entries []ChangelogEntry) error
• type ChangelogEntry
  • func CollectChangelog(packsDirs []string) ([]ChangelogEntry, error)
  • func ReadChangelog(cacheDir string) ([]ChangelogEntry, time.Time, error)
• type Engine
  • func NewEngine(stateDir string, defaultTTL time.Duration, ttls map[string]time.Duration) *Engine
  • func (e *Engine) GetMarkerState(packID string, index int) (MarkerState, bool)
  • func (e *Engine) IsStale(category string) bool
  • func (e *Engine) MarkAllSynced(categories []string) error
  • func (e *Engine) MarkSynced(category string) error
  • func (e *Engine) PacksBlock() map[string]PackState
  • func (e *Engine) RecordMarkerState(packID string, index int, ms MarkerState) error
  • func (e *Engine) SetPackHasMarkers(packID string, hasMarkers bool) error
• type Marker
  • func ScanMarkers(packID, content string) ([]Marker, []string)
• type MarkerState
• type PackState
• type SyncState
  • func LoadSyncStateForTest(dir string) SyncState

Functions

func ConsumeChangelog

func ConsumeChangelog(cacheDir string) error

ConsumeChangelog deletes sync-changelog.json from cacheDir. No-op if the file does not exist.

func ExpandMarkers

func ExpandMarkers(content string, markers []Marker, results map[int]string) string

ExpandMarkers substitutes sync:fetch marker lines in content with fetched results. results maps marker.Index → replacement string. Markers with no result entry are left unchanged.

func FetchArchive

func FetchArchive(rawURL, destDir, token string) error

FetchArchive downloads a zip archive from rawURL and extracts it to destDir. If token is non-empty it is sent as an Authorization header. Existing files are overwritten; directories are created as needed. GitHub/GitLab archives include a top-level directory prefix which is stripped.

func FetchMarker

func FetchMarker(m Marker, client *http.Client) (string, error)

FetchMarker fetches m.URL and returns the content, truncated per m.MaxLines / m.MaxTokens. client may be nil; a default 10-second timeout client is used in that case.

func MostRecentSync

func MostRecentSync(stateDir string) *time.Time

MostRecentSync returns a pointer to the most recent non-zero category sync time recorded in stateDir, or nil if no syncs have been recorded.

func WriteChangelog

func WriteChangelog(cacheDir string, syncedAt time.Time, entries []ChangelogEntry) error

WriteChangelog writes changelog entries to sync-changelog.json in cacheDir. Returns nil without writing if entries is empty.

Types

type ChangelogEntry

type ChangelogEntry struct {
	Pack string `json:"pack"`
	Text string `json:"text"`
}

ChangelogEntry is a single human-curated change note from a pack.

func CollectChangelog

func CollectChangelog(packsDirs []string) ([]ChangelogEntry, error)

CollectChangelog scans pack.yaml files across one or more pack directories and extracts changelog entries. Directories that don't exist are silently skipped.

func ReadChangelog

func ReadChangelog(cacheDir string) ([]ChangelogEntry, time.Time, error)

ReadChangelog reads sync-changelog.json from cacheDir. Returns nil entries and zero time if the file is missing.

type Engine

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

Engine tracks sync timestamps and marker state.

func NewEngine

func NewEngine(stateDir string, defaultTTL time.Duration, ttls map[string]time.Duration) *Engine

NewEngine creates an Engine that stores state in stateDir.

func (*Engine) GetMarkerState

func (e *Engine) GetMarkerState(packID string, index int) (MarkerState, bool)

GetMarkerState retrieves the last fetch result for a marker.

func (*Engine) IsStale

func (e *Engine) IsStale(category string) bool

IsStale reports whether the given category needs a refresh.

func (*Engine) MarkAllSynced

func (e *Engine) MarkAllSynced(categories []string) error

MarkAllSynced records the current time for all given categories in a single write.

func (*Engine) MarkSynced

func (e *Engine) MarkSynced(category string) error

MarkSynced records the current time as the last sync time for category.

func (*Engine) PacksBlock

func (e *Engine) PacksBlock() map[string]PackState

PacksBlock returns the full packs map, or nil if no packs have been recorded yet.

func (*Engine) RecordMarkerState

func (e *Engine) RecordMarkerState(packID string, index int, ms MarkerState) error

RecordMarkerState persists the result of a marker fetch.

func (*Engine) SetPackHasMarkers

func (e *Engine) SetPackHasMarkers(packID string, hasMarkers bool) error

SetPackHasMarkers records whether a pack contains sync:fetch markers.

type Marker

type Marker struct {
	PackID    string
	Index     int // zero-based position in the file
	URL       string
	MaxLines  int // 0 = no limit
	MaxTokens int // 0 = no limit; MaxLines takes precedence when both set
	Label     string
	TTLHours  int // 0 = use pack/engine default
	LineNum   int
	Format    string // "raw" | "text" | "markdown"; empty string treated as "markdown" by FetchMarker
	Selector  string // CSS selector for DOM scoping; empty = whole body; ignored for "raw"
}

Marker represents a parsed <!-- sync:fetch ... --> directive.

func ScanMarkers

func ScanMarkers(packID, content string) ([]Marker, []string)

ScanMarkers parses content for sync:fetch markers. Markers inside fenced code blocks (``` delimiters) are skipped. Returns parsed markers and any parse warnings (not errors — sync continues regardless).

type MarkerState

type MarkerState struct {
	URL         string    `json:"url"`
	LastFetched time.Time `json:"last_fetched"`
	TTLHours    int       `json:"ttl_hours"`
	OK          bool      `json:"ok"`
}

MarkerState records the result of the last fetch for a single marker.

type PackState

type PackState struct {
	HasMarkers bool `json:"has_markers"`
}

PackState records whether a pack has dynamic fetch markers.

type SyncState

type SyncState struct {
	Version    int                    `json:"version"`
	Categories map[string]time.Time   `json:"categories"`
	Packs      map[string]PackState   `json:"packs"`
	Markers    map[string]MarkerState `json:"markers"`
}

SyncState is the versioned on-disk format of sync-state.json.

func LoadSyncStateForTest

func LoadSyncStateForTest(dir string) SyncState

LoadSyncStateForTest exposes the internal state loader for tests.