// Package plugin defines the contract for MengStack plugins.
//
// A plugin is a self-contained extension that follows the same 4-layer
// architecture as built-in modules. Each plugin provides:
//
//   - FxOption: dependency injection wiring (repositories, services, handlers)
//   - SetupRoutes: HTTP route registration on the Gin engine
//   - Init: optional startup hook for background workers, caches, etc.
//
// To create a plugin:
//  1. Create a package under internal/modules/<name>/
//  2. Follow the 4-layer pattern: domain → infrastructure → application → interfaces
//  3. Implement the Plugin interface
//  4. Register in internal/app/app.go's plugin list
package plugin

import (
	"io/fs"

	"github.com/gin-gonic/gin"
	"go.uber.org/fx"
	"mengstack/internal/kernel/tenant"
)

// Metadata describes a plugin's identity.
type Metadata struct {
	Name        string
	Version     string
	Description string
}

// Plugin is the contract every MengStack plugin must implement.
type Plugin interface {
	// Metadata returns the plugin's identity.
	Metadata() Metadata

	// Permissions returns the plugin's declared permissions.
	// The sandbox enforces these at runtime — operations not declared are rejected.
	Permissions() Permissions

	// FxOption returns the fx.Module for dependency injection.
	FxOption() fx.Option

	// SetupRoutes registers HTTP routes on the Gin engine.
	// authMW is the JWT authentication middleware.
	// tenantResolver resolves tenant ID from request headers/query.
	SetupRoutes(engine *gin.Engine, authMW gin.HandlerFunc, tenantResolver tenant.Resolver)

	// Init is called after all dependencies are resolved and before
	// the HTTP server starts. Use it for background workers, warm-up
	// caches, or external service connections.
	// Returning nil indicates success.
	Init() error

	// MigrationsFS returns the plugin's embedded migration SQL files.
	// Return nil if the plugin has no migrations.
	MigrationsFS() fs.FS
}