plugin

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

type ExternalPluginRequest struct {
	// Phase is the name of the current hook phase.
	Phase string `json:"phase"`
	// Content is the text being processed (Markdown or HTML, depending on phase).
	Content string `json:"content"`
	// ChapterIndex is the zero-based chapter index (-1 for non-chapter contexts).
	ChapterIndex int `json:"chapter_index"`
	// ChapterFile is the source path of the current chapter.
	ChapterFile string `json:"chapter_file"`
	// OutputPath is the output file path (valid in AfterBuild phase only).
	OutputPath string `json:"output_path"`
	// OutputFormat is the output format name (valid in AfterBuild phase only).
	OutputFormat string `json:"output_format"`
	// Config holds the plugin-specific settings from book.yaml plugins[n].config.
	Config map[string]any `json:"config"`
	// Metadata is a shared key-value store for inter-plugin and inter-phase communication.
	Metadata map[string]any `json:"metadata"`
}

type ExternalPluginResponse struct {
	// Content is the modified text.  An empty string means "keep the original".
	Content string `json:"content"`
	// Stop instructs the manager to skip subsequent plugins for this phase.
	Stop bool `json:"stop"`
	// Error is an optional error message reported by the plugin.
	Error string `json:"error,omitempty"`
}

type HookContext struct {
	// Context is a standard Go context used for timeout and cancellation.
	Context context.Context

	// Config is the current build configuration.  Plugins may read but should
	// not modify it after the BeforeBuild phase.
	Config *config.BookConfig

	// Phase is the lifecycle phase that triggered this invocation.
	Phase Phase

	// Content is the text being processed.
	// In AfterParse it holds the chapter HTML; in BeforeRender / AfterRender it
	// holds the cover HTML (as a representative payload).
	// A plugin that returns a non-empty Content replaces this value.
	Content string

	// ChapterIndex is the zero-based index of the chapter being processed.
	// Set to -1 in non-chapter contexts.
	ChapterIndex int

	// ChapterFile is the source file path of the chapter (AfterParse only).
	ChapterFile string

	// OutputPath is the path of the generated output file (AfterBuild only).
	OutputPath string

	// OutputFormat is the output format name (AfterBuild only).
	OutputFormat string

	// Metadata is a shared key-value map for passing data between phases or
	// between consecutive plugins.
	// No sync protection is needed: each HookContext instance gets its own map,
	// and RunHook is always called sequentially from the build pipeline.
	Metadata map[string]any
}

type HookResult struct {
	// Content replaces HookContext.Content when non-empty.
	Content string

	// Stop instructs the Manager to skip all subsequent plugins for this phase.
	Stop bool
}

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

type Phase string

type Plugin interface {
	// Name returns the unique plugin identifier (lowercase, hyphen-separated).
	Name() string

	// Version returns the semantic version of the plugin (e.g. "1.0.0").
	Version() string

	// Description returns a short human-readable description of the plugin.
	Description() string

	// Init is called once before the build starts.  It receives the complete
	// BookConfig so the plugin can validate its configuration.
	Init(cfg *config.BookConfig) error

	// Hooks returns the list of phases this plugin wants to handle.
	// The Manager only calls Execute for phases listed here.
	Hooks() []Phase

	// Execute is invoked at each phase listed by Hooks.
	// It receives a HookContext with the current build state and returns a
	// HookResult (or nil) plus any error.
	Execute(hookCtx *HookContext) (*HookResult, error)

	// Cleanup is called after the build finishes, regardless of success.
	Cleanup() error
}

type PluginError struct {
	PluginName string
	Phase      string
	Err        error
}