Types(fix): Give each settings operation its own options class

CHANGES.md

@@ -7,6 +7,9 @@
 - Types: declare `libtmux.Session`, `Window`, `WindowLink`, `Pane`, `Client`
   and `Buffer` handle classes. Each lists only the methods tmux accepts for
   that kind; `Server:handle` returns the class that matches the record.
+- Types: give each option, hook and environment operation its own options
+  class, listing only the fields that operation accepts. `run_hook` takes
+  `process` alone; `hidden` belongs to `set_environment`.
 
 ## 0.1.0alpha1-1 (2026-09-20)
 

lua/libtmux/_internal/entity.lua

@@ -388,26 +388,28 @@ end
 --- Options and hooks, shared by sessions, windows and panes.
 --- Scopes are limited to the handle's own kind; global scopes belong to the Server.
 ---@class libtmux.Configurable<T>: libtmux.Entity<T>
----@field get_option fun(self:libtmux.Configurable<T>,name:string,options?:libtmux.SettingOptions):
+---@field get_option fun(self:libtmux.Configurable<T>,name:string,
+--- options?:libtmux.SettingGetOptions):
 --- libtmux.Request<libtmux.OptionRecord> Reads one option.
----@field list_options fun(self:libtmux.Configurable<T>,options?:libtmux.SettingOptions):
+---@field list_options fun(self:libtmux.Configurable<T>,options?:libtmux.SettingListOptions):
 --- libtmux.Request<libtmux.OptionRecord[]> Lists the options set at this scope.
 ---@field set_option fun(self:libtmux.Configurable<T>,name:string,value:libtmux.OptionInput,
---- options?:libtmux.SettingOptions):
+--- options?:libtmux.SettingSetOptions):
 --- libtmux.Request<boolean> Sets one option.
 ---@field unset_option fun(self:libtmux.Configurable<T>,name:string,
---- options?:libtmux.SettingOptions):
+--- options?:libtmux.SettingUnsetOptions):
 --- libtmux.Request<boolean> Unsets one option.
----@field get_hook fun(self:libtmux.Configurable<T>,name:string,options?:libtmux.SettingOptions):
+---@field get_hook fun(self:libtmux.Configurable<T>,name:string,options?:libtmux.SettingGetOptions):
 --- libtmux.Request<libtmux.HookRecord> Reads one hook.
----@field list_hooks fun(self:libtmux.Configurable<T>,options?:libtmux.SettingOptions):
+---@field list_hooks fun(self:libtmux.Configurable<T>,options?:libtmux.SettingListOptions):
 --- libtmux.Request<libtmux.HookRecord[]> Lists the hooks set at this scope.
 ---@field set_hook fun(self:libtmux.Configurable<T>,name:string,value:libtmux.HookProgram,
---- options?:libtmux.SettingOptions):
+--- options?:libtmux.SettingSetOptions):
 --- libtmux.Request<boolean> Sets one hook.
----@field unset_hook fun(self:libtmux.Configurable<T>,name:string,options?:libtmux.SettingOptions):
+---@field unset_hook fun(self:libtmux.Configurable<T>,name:string,
+--- options?:libtmux.SettingUnsetOptions):
 --- libtmux.Request<boolean> Unsets one hook.
----@field run_hook fun(self:libtmux.Configurable<T>,name:string,options?:libtmux.SettingOptions):
+---@field run_hook fun(self:libtmux.Configurable<T>,name:string,options?:libtmux.RunHookOptions):
 --- libtmux.Request<boolean> Runs one hook now.
 
 --- A tmux session.
@@ -425,12 +427,12 @@ end
 ---@field attach fun(self:libtmux.Session):libtmux.Request<boolean>
 --- Requires an interactive terminal capability; current adapters return unsupported_tty.
 ---@field get_environment fun(self:libtmux.Session,name:string,
---- options?:libtmux.EnvironmentOptions):
+--- options?:libtmux.EnvironmentGetOptions):
 --- libtmux.Request<libtmux.EnvironmentRecord> Reads one environment variable.
----@field list_environment fun(self:libtmux.Session,options?:libtmux.EnvironmentOptions):
+---@field list_environment fun(self:libtmux.Session,options?:libtmux.EnvironmentListOptions):
 --- libtmux.Request<libtmux.EnvironmentRecord[]> Lists this session's environment.
 ---@field set_environment fun(self:libtmux.Session,name:string,value:string,
---- options?:libtmux.EnvironmentOptions):
+--- options?:libtmux.EnvironmentSetOptions):
 --- libtmux.Request<boolean> Sets one environment variable.
 ---@field unset_environment fun(self:libtmux.Session,name:string,
 --- options?:libtmux.EnvironmentOptions):

lua/libtmux/_internal/environment.lua

@@ -434,11 +434,18 @@ end
 ---@field inherited boolean True only for a global fallback requested through a session.
 ---@field target? libtmux.Reference Session storage identity; omitted for global storage.
 
+--- What every environment operation accepts; unset and remove take no more.
 ---@class libtmux.EnvironmentOptions
 ---@field scope? "global"|"session" Must match the receiving handle.
 ---@field process? libtmux.CreationProcessOptions
----@field inherit? boolean Reads only; session fallback to global, default false.
----@field include_hidden? boolean Lists only; default true.
----@field hidden? boolean Set only; default false.
+
+---@class libtmux.EnvironmentGetOptions: libtmux.EnvironmentOptions
+---@field inherit? boolean Session fallback to global; default false.
+
+---@class libtmux.EnvironmentListOptions: libtmux.EnvironmentGetOptions
+---@field include_hidden? boolean Default true.
+
+---@class libtmux.EnvironmentSetOptions: libtmux.EnvironmentOptions
+---@field hidden? boolean Default false.
 
 return M

lua/libtmux/_internal/server.lua

@@ -601,30 +601,31 @@ end
 ---@field error? libtmux.Error
 
 ---@class libtmux.Server
----@field get_option fun(self:libtmux.Server,name:string,options?:libtmux.SettingOptions):
+---@field get_option fun(self:libtmux.Server,name:string,options?:libtmux.SettingGetOptions):
 --- libtmux.Request<libtmux.OptionRecord>
----@field list_options fun(self:libtmux.Server,options?:libtmux.SettingOptions):
+---@field list_options fun(self:libtmux.Server,options?:libtmux.SettingListOptions):
 --- libtmux.Request<libtmux.OptionRecord[]>
 ---@field set_option fun(self:libtmux.Server,name:string,value:libtmux.OptionInput,
---- options?:libtmux.SettingOptions):
+--- options?:libtmux.SettingSetOptions):
 --- libtmux.Request<boolean>
----@field unset_option fun(self:libtmux.Server,name:string,options?:libtmux.SettingOptions):
+---@field unset_option fun(self:libtmux.Server,name:string,options?:libtmux.SettingUnsetOptions):
 --- libtmux.Request<boolean>
----@field get_hook fun(self:libtmux.Server,name:string,options?:libtmux.SettingOptions):
+---@field get_hook fun(self:libtmux.Server,name:string,options?:libtmux.SettingGetOptions):
 --- libtmux.Request<libtmux.HookRecord>
----@field list_hooks fun(self:libtmux.Server,options?:libtmux.SettingOptions):
+---@field list_hooks fun(self:libtmux.Server,options?:libtmux.SettingListOptions):
 --- libtmux.Request<libtmux.HookRecord[]>
 ---@field set_hook fun(self:libtmux.Server,name:string,value:libtmux.HookProgram,
---- options?:libtmux.SettingOptions):
+--- options?:libtmux.SettingSetOptions):
 --- libtmux.Request<boolean>
----@field unset_hook fun(self:libtmux.Server,name:string,options?:libtmux.SettingOptions):
+---@field unset_hook fun(self:libtmux.Server,name:string,options?:libtmux.SettingUnsetOptions):
 --- libtmux.Request<boolean>
----@field get_environment fun(self:libtmux.Server,name:string,options?:libtmux.EnvironmentOptions):
+---@field get_environment fun(self:libtmux.Server,name:string,
+--- options?:libtmux.EnvironmentGetOptions):
 --- libtmux.Request<libtmux.EnvironmentRecord>
----@field list_environment fun(self:libtmux.Server,options?:libtmux.EnvironmentOptions):
+---@field list_environment fun(self:libtmux.Server,options?:libtmux.EnvironmentListOptions):
 --- libtmux.Request<libtmux.EnvironmentRecord[]>
 ---@field set_environment fun(self:libtmux.Server,name:string,value:string,
---- options?:libtmux.EnvironmentOptions):
+--- options?:libtmux.EnvironmentSetOptions):
 --- libtmux.Request<boolean>
 ---@field unset_environment fun(self:libtmux.Server,name:string,
 --- options?:libtmux.EnvironmentOptions):

lua/libtmux/_internal/settings.lua

@@ -651,11 +651,26 @@ end
 
 ---@alias libtmux.OptionInput string|number|boolean|libtmux.HookProgram|libtmux.OptionArrayInput
 
+--- What every option and hook operation accepts. Each operation's own class
+--- adds the fields it reads; anything else fails with `invalid_options`.
 ---@class libtmux.SettingOptions
 ---@field scope? 'server'|'session'|'window'|'pane'|'global_session'|'global_window'
+---@field process? libtmux.CreationProcessOptions
+
+---@class libtmux.SettingListOptions: libtmux.SettingOptions
 ---@field inherit? boolean Read fallback values; defaults to true.
+
+---@class libtmux.SettingGetOptions: libtmux.SettingListOptions
 ---@field index? integer Array slot; reads still inspect the whole array.
+
+---@class libtmux.SettingUnsetOptions: libtmux.SettingOptions
+---@field index? integer Array slot.
+
+---@class libtmux.SettingSetOptions: libtmux.SettingUnsetOptions
 ---@field append? boolean String concatenation or unindexed built-in hook append.
+
+--- Running a hook reads only its handle's own scope.
+---@class libtmux.RunHookOptions
 ---@field process? libtmux.CreationProcessOptions
 
 ---@class libtmux.OptionRecord