extension

type Client struct {
	// Namespace is the SDK accessor (`nx.<namespace>.*`). Optional;
	// purely informational for now (surfaced via PluginRecord).
	Namespace string

	// Apply runs once during di.Start with the constructed *nexus.App
	// in scope. Use it to call app.SetClientAuthInfo, register
	// methods on app.ClientHandler(), etc. Return an error to abort
	// boot.
	Apply func(app *nexus.App) error
}

type ClientContributor interface {
	NexusContribute(ctx GenerateContext) ([]File, error)
}

type ContributorFunc func(ctx GenerateContext) ([]File, error)

type Dashboard struct {
	// Tab is an entry in the dashboard nav. nil → no tab (the plugin
	// only adds backend routes, no UI surface).
	Tab *Tab

	// Routes are mounted under /__nexus/<plugin-name>/<route.Path>.
	// Path may be empty (mounts at /__nexus/<plugin-name>) or start
	// with "/".
	Routes []Route

	// LiveEvents lists trace.Bus event names this plugin emits that
	// the dashboard should forward to its WebSocket clients. Empty
	// is fine — only set this if your plugin publishes custom events.
	LiveEvents []string
}

type File struct {
	Path string
	Body []byte
}

type Generate struct {
	OutDir func(app *nexus.App) (string, error)
	Render func(ctx GenerateContext) ([]File, error)
}

type GenerateContext struct {
	Registry     *registry.Registry
	Refs         map[string]registry.NamedType
	BasePath     string
	Extras       map[string]any
	Contributors []ClientContributor
}

type Lifecycle struct {
	// OnBoot fires during di.Start, before the HTTP listener binds.
	// Returning a non-nil error aborts boot.
	OnBoot func(ctx context.Context, app *nexus.App) error

	// OnReady fires after OnBoot and after the listener is bound.
	// Use for warming caches or kicking off background work that
	// depends on the app being ready to serve.
	OnReady func(ctx context.Context, app *nexus.App) error

	// OnShutdown fires during di.Stop. The context carries the
	// shutdown deadline.
	OnShutdown func(ctx context.Context) error
}

type Plugin struct {
	// Name uniquely identifies the plugin. Used as the dashboard
	// route prefix (/__nexus/<name>/...) and the discovery key.
	// Must be kebab-case and unique within an app.
	Name string

	// Version is a free-form version string surfaced on the
	// dashboard. Semver recommended but not enforced.
	Version string

	// Icon is a lucide-style icon name shown next to the plugin in the
	// dashboard. Optional — when empty the dashboard falls back to the
	// plugin's Tab icon (if any) and then to a default extension icon.
	Icon string

	// Options is the standard nexus option slice — same values you'd
	// pass to nexus.Module: Provide, Invoke, AsRest, AsQuery, Use, etc.
	// They run in order before the contribution-slot invokes below,
	// so plugin-owned engine.Use() calls land before plugin Dashboard
	// routes mount.
	Options []nexus.Option

	// Lifecycle attaches OnBoot/OnReady/OnShutdown callbacks via the
	// fx lifecycle. Optional.
	Lifecycle *Lifecycle

	// Dashboard contributes a nav tab + HTTP routes under
	// /__nexus/<name>/... so a plugin can ship its own admin
	// surface without touching the dashboard package. Optional.
	Dashboard *Dashboard

	// Client lets a plugin extend the generated SDK — declaring a
	// namespace and an Apply hook that runs once the App is built.
	// Optional.
	Client *Client

	// Generate marks the plugin as a codegen driver. Exactly one
	// plugin per app may set this; the second registration panics at
	// boot. The frontend extension sets it; most plugins don't. See
	// the Generate struct doc for the contract.
	Generate *Generate

	// Contributor adds plugin-specific files to whatever the active
	// Generate driver renders. Unlike Generate, Contributor is many-
	// per-app: auth might publish auth/index.ts, oauth2 might publish
	// oauth2/index.ts, and both ride alongside the frontend driver's
	// own _client.ts / index.ts. The driver merges Contributor output
	// into its file tree at Render time. Optional — only set this on
	// plugins that have framework-flavored code to ship.
	Contributor ClientContributor
}

type Route struct {
	Method  string // "GET", "POST", etc.
	Path    string // "" or "/subpath"
	Handler httpx.HandlerFunc
}

type Tab struct {
	ID    string // url-safe identifier; uniqueness is the plugin's responsibility
	Label string // human-readable label
	Icon  string // optional lucide-style icon name; UI falls back to a default
}