// Core type definitions for fluxrec.
//
// Based on scholscan/core/types.go (vendored rev 7c1a5ef) but trimmed hard:
// academic metadata (authors, journal, DOI, enrichment config) is out.
// fluxrec's world is Miniflux entries, labels, and scores.
package core

import (
	"io"
	"time"
)

// Article is a title-carrying item moving through the pipeline
// (Miniflux entry at serve time, scored candidate in the digest).
type Article struct {
	Title       string     `json:"title"`
	Content     string     `json:"content,omitempty"`
	URL         string     `json:"url"`
	Source      string     `json:"source,omitempty"` // feed title
	PublishedAt *time.Time `json:"published_at,omitempty"`
	Score       *float64   `json:"score,omitempty"`
}

// Label values for LabelRow.Label. Short strings so labels.jsonl stays
// human-greppable.
const (
	LabelPos = "pos"
	LabelNeg = "neg"
)

// LabelRow is one row of labels.jsonl, the canonical label store.
// Written by `export`, read by `train`.
//
// EntryID is Miniflux's entry ID; for stars made on rec-feed items it resolves
// to the *original* entry via the guid contract, so a row always describes the
// original article.
type LabelRow struct {
	EntryID    int64     `json:"entry_id"`
	URL        string    `json:"url"`
	Title      string    `json:"title"`
	FeedID     int64     `json:"feed_id"`
	FeedTitle  string    `json:"feed_title"`
	Label      string    `json:"label"` // LabelPos or LabelNeg
	CapturedAt time.Time `json:"captured_at"`
}

// Command defines the interface that all CLI subcommands must implement.
type Command interface {
	// Name returns the command name (e.g., "export", "train").
	Name() string

	// Init parses command-line arguments and initializes the command.
	// It should return flag.ErrHelp if --help was requested.
	Init(args []string) error

	// Run executes the command, reading from stdin and writing to stdout.
	// The command should handle its own error reporting.
	Run(stdin io.Reader, stdout io.Writer) error
}