Source at 4d73c9795adca3e49eea74d1d2cbbbbdcbea0b6c
SHA-256: 4ef3e833cd4beeb62f8dc34994fd4071a0df675c3e2304b3e80fcd6d9579153c
-module(tmux_command). -moduledoc """ Build tmux commands and bounded sequences without performing I/O. Arguments remain binary values. Rendering protects trailing semicolons from tmux's command separator parser. This is distinct from shell quoting and from format expansion. A raw command is trusted application code; external services must apply their own command allowlist and write policy. ```erlang 1> {ok, C} = tmux_command:raw(<<"list-panes">>, [<<"-a">>]), ok. ok 2> tmux_command:argv(C). [<<"list-panes">>,<<"-a">>] 3> tmux_command:literal_format(<<"api-#{pane_id}">>). {ok,<<"api-##{pane_id}">>} 4> tmux_command:launch(#{argv => [<<"/bin/printf">>, <<"hello">>]}). {ok,[<<"/bin/printf">>,<<"hello">>]} ``` Use `literal_format/1` only for a whole argument that tmux expands as a format, such as a new name or cwd. It does not encode a value nested in a format expression. tmux's stored-name escaping and session-name substitutions still apply. Use `literal_format/2` with mode time for commands such as display-message that also expand strftime percent directives. This protects one format-expansion pass, not later visual style rendering or recursive/nested expansion. No renderer reverses stored-name semantics. `launch/1` distinguishes executable argv from an explicitly requested shell command. A singleton argv uses the installed helper's exec-only mode because tmux otherwise passes one argument to its default shell. Empty argv is invalid; default_shell explicitly requests tmux's configured default command/shell. The internal helper uses an absolute path so a child's cwd does not change helper resolution. Relative executable arguments retain their native meaning. Empty shell commands have command-specific lifetime. split-window creates a process-free pane. new-session executes an empty shell command and can remove the new object immediately. new-window does likewise before tmux 3.8; tmux 3.8 creates a process-free pane. Use a persistent job for parent sessions/windows that must remain available across supported versions. Submit commands through `tmux_server:command/3` or `tmux_operation:start/3`. `sequence/1` combines flat command values for one-shot execution with combined output and a possible completed prefix on error. The [job guide](jobs.md) shows submission, completion and cancellation. `tmux_session:rename_command/2` and `tmux_pane:resize_command/2` build values bound to their row's captured origin. Execution through another endpoint returns different_owner before native work. Construction does not validate endpoint liveness or authorize an automatic mutation retry. `wait_for/2` builds native channel signals, waits and advisory locks. `source_file/2` builds configuration loading from stdin or a literal absolute path. Both return command values without opening an endpoint or doing I/O. `to_config/1` renders a command or bounded command list for native configuration input, preserving argument bytes through tmux's lexer. """. -export([raw/2, sequence/1, validate/1, argv/1, literal_format/1, literal_format/2, launch/1, wait_for/2, source_file/2, to_config/1]). -export([generated/3, provenance/1]). -export_type([t/0]). -export_type([wait_action/0, source/0, source_options/0]). -doc "Native wait channel action. lock/unlock are explicit advisory operations, not owned leases.". -type wait_action() :: wait | signal | lock | unlock. -doc "Standard input, or one literal absolute POSIX byte path with no NUL.". -type source() :: stdin | binary(). -doc "Native parse-only and quiet-missing-file flags; both default to false.". -type source_options() :: #{parse_only => boolean(), quiet => boolean()}. -export_type([launch_spec/0]). -doc "Explicit executable argv, an explicitly requested shell command, or tmux's configured default shell.". -type launch_spec() :: default_shell | #{argv := nonempty_list(binary())} | #{shell := binary()}. -export_type([respawn_spec/0]). -doc """ Reuse tmux's saved command/shell, or replace it with argv or a shell command. Used by `tmux_pane:respawn/2` and `tmux_window:respawn/2`. """. -type respawn_spec() :: previous | #{argv := nonempty_list(binary())} | #{shell := binary()}. -doc """ A validated command or flat sequence. Rendering and execution remain separate. Domain builders retain a captured endpoint origin; raw values are unbound. """. -opaque t() :: {tmux_command, binary(), [binary()]} | {tmux_command, binary(), [binary()], #{origin := reference(), kind := session_rename | pane_resize}} | {tmux_sequence, nonempty_list(t())}. -doc """ Validate one trusted command name and binary argv, without I/O. The renderer protects tmux separators; it does not provide shell or nested-format quoting. External services still need their own allowlists and write policy. Names are at most 128 bytes. NUL bytes are rejected, and at most 2,040 arguments fit within a 32 KiB command reservation including framing overhead. """. -spec raw(binary(), [binary()]) -> {ok, t()} | {error, map()}. raw(Name, Arguments) -> case valid_name(Name) of false -> {error, #{code => invalid_command}}; true -> maybe ok ?= words(Arguments, 2040, byte_size(Name) + 2), {ok, {tmux_command, compact(Name), [compact(A) || A <- Arguments]}} end end. -doc """ Build one bounded native command sequence without I/O. Members must be a nonempty flat list of at most 256 command values. Their combined executable argv is limited to 2041 words and 32 KiB including separator overhead. Arguments keep the literal separator protection of `raw/2`; only boundaries between members become native command separators in `argv/1`. Captured members must share an endpoint origin. That origin also binds the sequence; raw members use the caller's explicitly selected endpoint. Submit through `tmux_server:command/3` or `tmux_operation:start/3`. Execution is not atomic. A failed member can leave a completed prefix, and commands can wait or interleave with other work. The one-shot result contains combined bounded stdout/stderr and native exit status, without per-member completion attribution or rollback. Control-mode eligibility is separate. `to_config/1` can serialize a sequence with the same origin-loss policy as other configuration text. """. -spec sequence(nonempty_list(t())) -> {ok, t()} | {error, map()}. sequence([_ | _] = Commands) -> sequence(Commands, 256, 0, 0, none, []); sequence(_) -> {error, #{code => invalid_command, reason => invalid_command_list}}. sequence([], _, _, _, _, Acc) -> {ok, {tmux_sequence, lists:reverse(Acc)}}; sequence([_ | _], 0, _, _, _, _) -> {error, #{code => command_limit}}; sequence([Command | Rest], Left, Words, Bytes, Origin, Acc) -> case Command of {tmux_sequence, _} -> {error, #{code => invalid_command, reason => nested_sequence}}; _ -> maybe {ok, Valid} ?= validate(Command), Args = argv(Valid), Separator = case Acc of [] -> 0; _ -> 1 end, Count = Words + length(Args) + Separator, Size = Bytes + lists:sum([byte_size(A) + 3 || A <- Args]) + Separator * 4, ok ?= case Count =< 2041 andalso Size =< 32768 of true -> ok; false -> {error, #{code => command_limit}} end, Next = case provenance(Valid) of none -> none; #{origin := O} -> O end, {ok, Bound} ?= sequence_origin(Origin, Next), sequence(Rest, Left - 1, Count, Size, Bound, [Valid | Acc]) end end; sequence(_, _, _, _, _, _) -> {error, #{code => invalid_command, reason => invalid_command_list}}. sequence_origin(none, Origin) -> {ok, Origin}; sequence_origin(Origin, none) -> {ok, Origin}; sequence_origin(Origin, Origin) -> {ok, Origin}; sequence_origin(_, _) -> {error, #{code => different_owner}}. -doc """ Build a native `wait-for` command without I/O. Channels are nonempty NUL-free binary names, subject to the command reservation in `raw/2`; neither shell nor format expansion occurs. Submit through `tmux_operation:start/3` for a wait that leaves the caller free, or through `tmux_server:command/3` to await it. `signal` wakes current waiters. On an unlocked channel with no waiters or pending wakeup, it retains one wakeup for a later wait. Signaling that channel again before a wait can clear the pending state. Signals are neither counted nor reliably coalesced events; send once per expected wait. Channel names are shared by all clients of the server. Use separate names for signaling and locking. `lock` acquires an advisory channel lock or waits for an explicit `unlock`; a completed command client's exit does not release its acquired lock. Unlocking an unlocked channel is a native command error. Cancellation retires the library client. It does not undo a signal or release a lock that may already have been acquired; an uncertain lock outcome needs application coordination before another unlock. This is not an owned mutex. ```erlang 1> {ok, Signal} = tmux_command:wait_for(<<"build-ready">>, signal), ok. ok 2> tmux_command:argv(Signal). [<<"wait-for">>,<<"-S">>,<<"--">>,<<"build-ready">>] ``` """. -spec wait_for(binary(), wait_action()) -> {ok, t()} | {error, map()}. wait_for(Channel, Action) -> maybe {ok, Flags} ?= case Action of wait -> {ok, []}; signal -> {ok, [<<"-S">>]}; lock -> {ok, [<<"-L">>]}; unlock -> {ok, [<<"-U">>]}; _ -> {error, #{code => invalid_wait_action}} end, ok ?= case Channel of <<>> -> {error, #{code => invalid_channel}}; _ -> word(Channel) end, raw(<<"wait-for">>, Flags ++ [<<"--">>, Channel]) end. -doc """ Build configuration loading from stdin or one literal absolute path, without I/O. `stdin` renders `source-file -`; supply configuration bytes in the `stdin` option of `tmux_server:command/3` or `tmux_operation:start/3`. Those APIs bound input to 256 KiB including their argument reservation. Paths are NUL-free POSIX byte binaries. Glob metacharacters and backslashes are escaped so only that filename is selected; format expansion is disabled. The combined encoded path and flags must fit `raw/2` limits. The file is read by tmux at execution time; this builder does not open it or bound its size. `parse_only` requests native `-n` parsing without executing the configuration's command list. `quiet` requests native `-q` missing-file suppression; it does not suppress syntax or execution errors. Both default to false. Configuration is trusted tmux code, with its own variable, directive and command semantics. Parse-only is not a sandbox. Execution can partially change server state before an error; cancellation cannot undo those effects. Completion does not prove that background jobs launched by the configuration have finished. ```erlang 1> {ok, Source} = tmux_command:source_file(stdin, #{parse_only => true}), ok. ok 2> tmux_command:argv(Source). [<<"source-file">>,<<"-n">>,<<"--">>,<<"-">>] ``` """. -spec source_file(source(), source_options()) -> {ok, t()} | {error, map()}. source_file(Source, Options) -> maybe {ok, Flags} ?= tmux_args:options(Options, [{parse_only, flag, <<"-n">>}, {quiet, flag, <<"-q">>}]), {ok, Path} ?= source_path(Source), raw(<<"source-file">>, Flags ++ [<<"--">>, Path]) end. source_path(stdin) -> {ok, <<"-">>}; source_path(<<$/, _/binary>> = Path) -> maybe ok ?= word(Path), {ok, << <<(glob_byte(C))/binary>> || <<C>> <= Path >>} end; source_path(_) -> {error, #{code => invalid_source_path}}. glob_byte(C) when C =:= $*; C =:= $?; C =:= $[; C =:= $]; C =:= $\\ -> <<$\\, C>>; glob_byte(C) -> <<C>>. -doc """ Revalidate a command value at a submission boundary. Returns a compact validated command or a tagged shape/argument/resource error, without I/O. """. -spec validate(term()) -> {ok, t()} | {error, map()}. validate({tmux_command, Name, Arguments}) -> raw(Name, Arguments); validate({tmux_sequence, Commands}) -> sequence(Commands); validate({tmux_command, Name, Arguments, #{origin := Origin, kind := Kind} = Metadata}) when map_size(Metadata) =:= 2 -> case generated(Kind, Origin, Arguments) of {ok, {tmux_command, Name, _, _}} = Valid -> Valid; {ok, _} -> {error, #{code => invalid_command}}; Error -> Error end; validate(_) -> {error, #{code => invalid_command}}. -doc false. -spec generated(session_rename | pane_resize, reference(), [binary()]) -> {ok, t()} | {error, map()}. generated(Kind, Origin, Arguments) when is_reference(Origin) -> maybe {ok, Name} ?= case Kind of session_rename -> {ok, <<"rename-session">>}; pane_resize -> {ok, <<"resize-pane">>}; _ -> {error, #{code => invalid_command}} end, {ok, {tmux_command, Name, Words}} ?= raw(Name, Arguments), {ok, {tmux_command, Name, Words, #{origin => Origin, kind => Kind}}} end; generated(_, _, _) -> {error, #{code => invalid_command}}. %% Intent does not establish control eligibility; reply success and error %% shapes require separate qualification before a control dispatcher admits it. -doc false. -spec provenance(t()) -> none | #{origin := reference(), kind := session_rename | pane_resize | sequence}. provenance({tmux_command, _, _}) -> none; provenance({tmux_command, _, _, Metadata}) -> Metadata; provenance({tmux_sequence, Commands}) -> case [O || Command <- Commands, #{origin := O} <- [provenance(Command)]] of [] -> none; [Origin | _] -> #{origin => Origin, kind => sequence} end. parts({tmux_command, Name, Arguments}) -> {Name, Arguments}; parts({tmux_command, Name, Arguments, _}) -> {Name, Arguments}. -doc """ Render a validated command into executable argv, protecting trailing tmux separators. Performs no I/O and raises for an invalid command value. """. -spec argv(t()) -> [binary()]. argv(Command) -> case validate(Command) of {ok, {tmux_sequence, Commands}} -> lists:append(lists:join([<<";">>], [argv(C) || C <- Commands])); {ok, Validated} -> {Name, Arguments} = parts(Validated), [Name | [escape_separator(Word) || Word <- Arguments]]; {error, Detail} -> erlang:error({invalid_command, Detail}, none, [{error_info, #{module => tmux_error}}]) end. -doc """ Render validated commands as native configuration text, without I/O. Accepts one command, a `sequence/1` value, or a nonempty flat list of at most 256 commands. Returns an ASCII binary of at most 32 KiB, without a final newline. Validation uses `validate/1`; escaping growth, command count and aggregate size can return `command_limit`. Lists use native command separators between independently quoted commands. Rendering does not execute them or provide atomic execution or rollback. The text carries no origin token; executing serialized configuration requires the caller to choose and validate its destination explicitly. Each argument is doublequoted. Quote, backslash, dollar, tilde, control and non-ASCII bytes use three-digit octal escapes. Empty arguments, semicolons, newlines and non-UTF-8 byte values remain argument data. The lexer does not expand their variables or tilde prefixes, strip newline indentation, or interpret them as directives, comments or additional commands. Protection covers one lexer pass. Native command-string arguments, including `bind-key` and `set-hook` values, can be parsed again by the receiving command. Render each inner command string separately for its own parse boundary. This is tmux configuration syntax, separate from `argv/1` executable arguments and shell quoting. Native commands still interpret their values and expand formats as usual; `literal_format/2` handles that separate boundary when literal format values are required. Load the text explicitly with `source_file/2`, or store it through a native command that accepts configuration text. The [configuration guide](configuration.md) uses this renderer with explicit execution and completion signals. """. -spec to_config(t() | [t(), ...]) -> {ok, binary()} | {error, map()}. to_config({tmux_sequence, Commands}) -> maybe {ok, {tmux_sequence, Valid}} ?= sequence(Commands), config_commands(Valid, 256, 0, []) end; to_config([_ | _] = Commands) -> config_commands(Commands, 256, 0, []); to_config(Command) -> config_command(Command). config_command({tmux_sequence, _}) -> {error, #{code => invalid_command}}; config_command(Command) -> maybe {ok, Validated} ?= validate(Command), {Name, Arguments} = parts(Validated), Words = [Name | [config_word(Word) || Word <- Arguments]], Text = iolist_to_binary(lists:join(<<" ">>, Words)), case byte_size(Text) =< 32768 of true -> {ok, Text}; false -> {error, #{code => command_limit}} end end. config_commands([], _, _, Acc) -> {ok, iolist_to_binary(lists:join(<<" ; ">>, lists:reverse(Acc)))}; config_commands([_ | _], 0, _, _) -> {error, #{code => command_limit}}; config_commands([Command | Rest], Remaining, Bytes, Acc) -> maybe {ok, Text} ?= config_command(Command), Size = Bytes + byte_size(Text) + case Acc of [] -> 0; _ -> 3 end, case Size =< 32768 of true -> config_commands(Rest, Remaining - 1, Size, [Text | Acc]); false -> {error, #{code => command_limit}} end end; config_commands(_, _, _, _) -> {error, #{code => invalid_command, reason => invalid_command_list}}. config_word(Word) -> [<<$">>, [config_byte(Byte) || <<Byte>> <= Word], <<$">>]. config_byte(Byte) when Byte >= 32, Byte =< 126, Byte =/= $", Byte =/= $\\, Byte =/= $$, Byte =/= $~ -> <<Byte>>; config_byte(Byte) -> <<$\\, ($0 + (Byte bsr 6)), ($0 + ((Byte bsr 3) band 7)), ($0 + (Byte band 7))>>. -doc """ Quote a complete literal argument for tmux format expansion. This does not encode operands nested inside another format expression. Performs no I/O. """. -spec literal_format(binary()) -> {ok, binary()} | {error, map()}. literal_format(Value) -> literal_format(Value, tmux). -doc """ Quote a complete literal format argument. Mode tmux protects hash expansion; mode time also protects strftime percent directives. Stored-name semantics remain tmux's own. This handles one expansion pass, not a nested operand, recursive expansion or later visual style rendering. Performs no I/O. Hash runs before `[` stay unchanged because tmux preserves style-looking prefixes for a separate drawing step. Other hashes are doubled. In time mode, an argument containing percent bytes must fit tmux's 8191-byte strftime result limit after hash encoding and before percent doubling; larger values return `format_limit` with `time_bytes` and `max_bytes`. Arguments without percent bytes skip that native time-expansion limit. The encoded 32 KiB command limit still applies in either mode. """. -spec literal_format(binary(), tmux | time) -> {ok, binary()} | {error, map()}. literal_format(Value, Mode) when Mode =:= tmux; Mode =:= time -> maybe ok ?= word(Value), Hashes = literal_hashes(Value), Encoded = case Mode of tmux -> Hashes; time -> binary:replace(Hashes, <<"%">>, <<"%%">>, [global]) end, Time = Mode =:= time andalso binary:match(Value, <<"%">>) =/= nomatch, case {byte_size(Encoded) =< 32768, Time andalso byte_size(Hashes) > 8191} of {false, _} -> {error, #{code => command_limit}}; {_, true} -> {error, #{code => format_limit, max_bytes => 8191, time_bytes => byte_size(Hashes)}}; _ -> {ok, Encoded} end end; literal_format(_, _) -> {error, #{code => invalid_format_mode}}. literal_hashes(Value) -> case binary:match(Value, <<"#">>) of nomatch -> Value; _ -> iolist_to_binary(lists:reverse(literal_hashes(Value, []))) end. literal_hashes(<<>>, Acc) -> Acc; literal_hashes(<<$#, Rest/binary>>, Acc) -> {Count, Tail} = hash_run(Rest, 1), Size = case Tail of <<$[, _/binary>> -> Count; _ -> Count * 2 end, literal_hashes(Tail, [binary:copy(<<$#>>, Size) | Acc]); literal_hashes(<<Byte, Rest/binary>>, Acc) -> literal_hashes(Rest, [Byte | Acc]). hash_run(<<$#, Rest/binary>>, Count) -> hash_run(Rest, Count + 1); hash_run(Tail, Count) -> {Count, Tail}. -doc """ Render explicit executable argv, an explicitly requested shell command, or default_shell. Singleton argv uses the installed helper's exec-only mode to avoid tmux interpreting it as shell syntax. Performs no I/O. """. -spec launch(launch_spec()) -> {ok, [binary()]} | {error, map()}. launch(default_shell) -> {ok, []}; launch(#{argv := [Executable]} = Spec) when map_size(Spec) =:= 1 -> maybe ok ?= executable(Executable), case code:priv_dir(libtmux_erlang) of {error, _} -> {error, #{code => application_unavailable}}; Priv -> Path = filename:absname(filename:join(Priv, "tmux_owned_io")), Helper = unicode:characters_to_binary(Path), {ok, [Helper, <<"--exec-one">>, Executable]} end end; launch(#{argv := [Executable, _ | _] = Arguments} = Spec) when map_size(Spec) =:= 1 -> maybe ok ?= executable(Executable), ok ?= words(Arguments, 2040, 0), {ok, Arguments} end; launch(#{shell := Shell} = Spec) when map_size(Spec) =:= 1 -> maybe ok ?= word(Shell), {ok, [Shell]} end; launch(_) -> {error, #{code => invalid_launch}}. valid_name(<<First, Rest/binary>> = Name) when First >= $a, First =< $z, byte_size(Name) =< 128 -> valid_name_bytes(Rest); valid_name(_) -> false. valid_name_bytes(<<>>) -> true; valid_name_bytes(<<C, Rest/binary>>) when (C >= $a andalso C =< $z) orelse C =:= $- -> valid_name_bytes(Rest); valid_name_bytes(_) -> false. word(Value) when is_binary(Value), byte_size(Value) =< 32768 -> case binary:match(Value, <<0>>) of nomatch -> ok; _ -> {error, #{code => invalid_argument}} end; word(Value) when is_binary(Value) -> {error, #{code => command_limit}}; word(_) -> {error, #{code => invalid_argument}}. words([], _, _) -> ok; words([_ | _], 0, _) -> {error, #{code => command_limit}}; words([Value | Rest], Remaining, Size) -> maybe ok ?= word(Value), NewSize = Size + byte_size(Value) + 3, case NewSize =< 32768 of true -> words(Rest, Remaining - 1, NewSize); false -> {error, #{code => command_limit}} end end; words(_, _, _) -> {error, #{code => invalid_argument}}. executable(<<>>) -> {error, #{code => invalid_executable}}; executable(Value) -> word(Value). compact(Bytes) -> case binary:referenced_byte_size(Bytes) =:= byte_size(Bytes) of true -> Bytes; false -> binary:copy(Bytes) end. escape_separator(<<>>) -> <<>>; escape_separator(Word) -> case binary:last(Word) of $; -> Prefix = binary:part(Word, 0, byte_size(Word) - 1), <<Prefix/binary, $\\, $;>>; _ -> Word end.