pluginapi

type ActionExportResult struct {
	// Action name, e.g. "actions.clipboard.copy"
	Action string
	// Requested keybindings that were requested to be exported
	Requested []keybinding.Keybinding
	// Exported keybindings that were actually exported (may be fewer due to editor limitations)
	Exported []keybinding.Keybinding
	// Reason explains why some keybindings were not exported (optional)
	Reason string
}

type ConfigDetectOptions struct {
	// Whether to in sandbox mode, in sandbox mode, shell command lookup is not effective, like `code` command for vscode can not be found
	Sandbox bool
}

type EditorSupportOnlyOneKeybindingPerActionError struct {
	SkipKeybinding *keybinding.Keybinding
}

type EditorType string

type ExportSkipAction struct {
	// Action name, e.g. "actions.clipboard.copy"
	Action string
	// Error description about why this action is skipped
	Error error
}

type ExportSkipReport struct {
	SkipActions []ExportSkipAction
}

type ExportedReport struct {
	Actions []ActionExportResult
}

type ImportSkipAction struct {
	// EditorSpecificAction is the action name in the editor-specific format
	EditorSpecificAction string
	Error                error
}

type ImportSkipReport struct {
	SkipActions []ImportSkipAction
}

type Plugin interface {
	// EditorType returns the unique identifier for the plugin (e.g., "vscode", "zed").
	EditorType() EditorType

	// ConfigDetect returns the default path to the editor's configuration file based on the platform.
	// Return multiple paths if the editor has multiple configuration files.
	ConfigDetect(opts ConfigDetectOptions) (paths []string, installed bool, err error)

	// Importer returns an instance of PluginImporter for the plugin.
	// Return ErrNotSupported if the plugin does not support importing.
	Importer() (PluginImporter, error)

	// Exporter returns an instance of PluginExporter for the plugin.
	// Return ErrNotSupported if the plugin does not support exporting.
	Exporter() (PluginExporter, error)
}

type PluginExportOption struct {
	// ExistingConfig provides a reader for the editor's current keymap
	// configuration. If provided, the exporter will merge the settings
	// instead of overwriting the entire file, preserving any keybindings
	// not managed by onekeymap. If nil, the export will be destructive,
	// creating a new file from scratch.
	ExistingConfig io.Reader

	// TargetPlatform specifies the target platform for the exported keybindings.
	// This affects how modifier keys are formatted (e.g., "cmd" for macOS, "win" for Windows).
	// If empty, defaults to the current runtime platform.
	TargetPlatform platform.Platform
}

type PluginExportReport struct {
	// The diff between the base and the exported keymap.
	// If base is nil or diff is not supported, this field will be nil.
	Diff *string

	// If BaseEditorConfig and ExportEditorConfig set, and Diff is not set, export exportService will calculate diff for plugin by using json diff
	// BaseEditorConfig contains the original editor-specific configuration before export.
	BaseEditorConfig any
	// ExportEditorConfig contains the editor-specific configuration after export.
	ExportEditorConfig any

	// SkipReport reports actions that were not exported and why.
	SkipReport ExportSkipReport

	ExportedReport ExportedReport
}

type PluginExporter interface {
	// Export takes a universal KeymapSetting and writes it to an editor-specific
	// configuration destination.
	Export(
		ctx context.Context,
		destination io.Writer,
		setting keymap.Keymap,
		opts PluginExportOption,
	) (*PluginExportReport, error)
}

type PluginImportOption struct {
	// SourcePlatform specifies the platform of the source keybindings being imported.
	// This affects how modifier keys are parsed (e.g., "cmd" for macOS, "win" for Windows).
	// If empty, defaults to the current runtime platform.
	SourcePlatform platform.Platform
}

type PluginImportReport struct {
	// SkipReport contains details about actions that were skipped during the import operation.
	SkipReport ImportSkipReport
}

type PluginImportResult struct {
	Keymap keymap.Keymap

	Report PluginImportReport
}

type PluginImporter interface {
	// Import reads the editor's configuration source and converts it into the
	// universal onekeymap KeymapSetting format.
	Import(ctx context.Context, source io.Reader, opts PluginImportOption) (PluginImportResult, error)
}

type UnsupportedExportActionError struct {
	Note string
}