namespace SboxSuperuser;

/// <summary>A host-owned registration scope tied to one module; declarations do not execute commands.</summary>
public interface IModuleRegistration
{
	/// <summary>Gets the owning module; registrations cannot impersonate another module.</summary>
	string ModuleId { get; }

	/// <summary>Declares a command and handler; implementations must validate ownership and collisions.</summary>
	void RegisterCommand( CommandDescriptor descriptor, CommandHandler handler );

	/// <summary>Declares a permission owned by this module; no grant is performed.</summary>
	void RegisterPermission( PermissionDescriptor descriptor );

	/// <summary>Tracks a listener or resource for reverse-order disposal on rollback or shutdown.</summary>
	void Track( IDisposable subscription );

	/// <summary>Approves an exact game capability type for this module's handlers.</summary>
	void RegisterService<T>( T service ) where T : class;

	/// <summary>Stages attributed commands through the verified engine discovery adapter.</summary>
	void DiscoverCommands();

	/// <summary>
	/// Adds a documentation page written in Markdown. Pages appear under the module's Guides in the order added,
	/// after its generated Overview and before its generated Commands and Permissions.
	/// </summary>
	void AddDocumentation( string title, string markdown );

	/// <summary>Adds a documentation page from a Markdown file in the mounted file system, such as "docs/guide.md".</summary>
	void AddDocumentationFile( string title, string path );

	/// <summary>
	/// Adds a window to the admin menu, built from headings, text, buttons, command forms and live command replies.
	/// Everything in it runs this module's commands through the usual checks. It is listed under Modules unless
	/// <paramref name="menu"/> names another tab: an existing one such as Moderation or Server, or a new tab. The
	/// Superuser tab is reserved; a menu named after it throws.
	/// </summary>
	void AddMenuWindow( string title, Action<AdminMenuWindow> build, string menu = null );
}