libtmux-workspace 0.1.0.alpha.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9514613d11f2325d349731f229675510da8a0e11a1c053fae88f198464e38d84
+  data.tar.gz: a367212c8b49b482cfe9bca60323f8360d38814af096f0f306ac49f642727450
+SHA512:
+  metadata.gz: cbce1a3ca65ec06fd22647ee9e2ff4af2bd85c488e1a9466c88d5dfe091cdacf7585ae9ad8310d995e1c87a033bca7869d1cf1face0f8041fd812a9531fd62e2
+  data.tar.gz: a972900033105a2cc722f20811a72cd065d124e026eee5f55ed65ae7fb5d9dcde6a64e9b2730932542eded315946f31cada5dd557835ab662c22aafc4a639239

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026- libtmux contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,225 @@
+# libtmux-workspace
+
+Load bounded YAML or JSON, inspect an immutable creation plan, then explicitly
+apply it to an open libtmux server. The library
+and installed command-line executable share the core
+[compatibility matrix](https://github.com/libtmux/libtmux-ruby/actions/workflows/compatibility.yml);
+consult its exact per-revision results.
+
+The gem declares Ruby 3.3 or newer and depends on the same-version `libtmux`
+gem, JSON 3.0 and Psych 5.5. See the repository's
+[contribution guide](../../.github/CONTRIBUTING.md) for local builds and checks.
+Imports and planning do not start tmux or run commands.
+
+Install the alpha and its `libtmux-workspace` executable:
+
+```console
+$ gem install libtmux-workspace --pre
+```
+
+## Example
+
+Save this declared subset of tmuxp-style data as `workspace.yaml`. Relative
+directories resolve against the configuration file's directory.
+
+<!-- example: workspace/config -->
+```yaml
+session_name: work
+environment:
+  PROJECT_MODE: development
+windows:
+  - window_name: editor
+    window_index: 1
+    layout: tiled
+    panes:
+      - shell_command: printf 'editor ready\n'
+      - {}
+```
+<!-- /example -->
+
+The [complete workspace program](../../examples/workspace_apply.rb) creates an
+isolated server, applies this document and checks compensation after a later
+failure. Calling `apply` authorizes the configuration's shell commands. This
+excerpt runs inside that program's cleanup wrapper:
+
+<!-- example: workspace_apply/main -->
+```ruby
+workspace = LibTmux::Workspace.load(File.join(__dir__, "workspace.yaml"))
+plan = workspace.plan(snapshot: server.snapshot)
+Example.check(server.list_sessions.size == 1, "planning changed tmux")
+result = plan.apply(server: server)
+Example.check(result.success?, "workspace apply failed")
+Example.check(result.effects.any? { |effect| effect.outcome == :dispatch_only }, "shell dispatch overclaims completion")
+crowded = LibTmux::Workspace.parse(JSON.generate({
+  session_name: "crowded", windows: [{window_name: "small", panes: Array.new(40) { {} }}]
+}), format: :json, base_directory: __dir__)
+error = Example.raises(LibTmux::Workspace::ApplyError) do
+  crowded.plan.apply(server: server, compensate: true)
+end
+Example.check(!error.result.created_refs.empty?, "failure lost partial creation ledger")
+Example.check(error.result.compensation == :completed, "owned compensation failed")
+Example.check(server.list_sessions.map(&:ref).include?(borrowed.ref), "borrowed session was removed")
+```
+<!-- /example -->
+
+## Configuration
+
+The plain declared subset has effective version 1. Optional `profile` and
+`version` must appear together as `libtmux-ruby.workspace` and `1`.
+`workspace.to_h` exports an immutable, normalized, reloadable configuration.
+It contains expanded values and absolute directories; callers control its
+storage and disclosure.
+
+- Root: `session_name`, nonempty `windows`, `options`, `window_options`.
+- Window: `window_name`, nonempty `panes`, `window_index`, `focus`, `layout`,
+  `options`. Indexes are unique nonnegative integers; unspecified indexes use
+  the lowest available value starting at the declared `base-index` or zero.
+- Pane: a command string or a mapping with `focus`, `split`, `size`. Split is
+  `horizontal` or `vertical`. Size is positive cells or `1%` through `99%`;
+  neither applies to the initial pane. Explicit sizes cannot accompany a
+  final named layout.
+- Root, windows and pane mappings accept `start_directory`, `environment`,
+  `shell_command` and `shell_command_before`. Environment maps merge from
+  parent to child. Commands inherit unless overridden; before-commands append
+  in parent-to-child order. Command values accept a string or string array.
+
+At most one window and one pane per window can declare focus; each defaults
+to the first. Layouts are `even-horizontal`, `even-vertical`, `main-horizontal`,
+`main-vertical` and `tiled`. Unknown fields and unsupported features fail with
+a `ConfigError` identifying their configuration position.
+
+Session options accept boolean `status`, `mouse`, `renumber-windows`;
+nonnegative `base-index`, `history-limit`, `status-interval`; and enumerated
+`status-position` and `status-justify`. Window options accept boolean
+`automatic-rename`, `allow-rename`, `remain-on-exit`, `synchronize-panes`,
+`aggressive-resize`; nonnegative `pane-base-index`, `main-pane-width`,
+`main-pane-height`; text `window-status-format`, `window-status-current-format`;
+and enumerated `pane-border-status`. Option text remains tmux option text,
+including any formats that tmux evaluates.
+`pane-base-index` cannot exceed 65535; the other numeric options accept
+integers through 2147483647.
+
+YAML tags, anchors, aliases, duplicate keys, multiple documents and complex
+mapping keys are rejected. JSON duplicate keys are rejected too. No Ruby,
+ERB, plugins or callbacks are evaluated. Defaults bound source and canonical
+bytes to 1 MiB, strings to 64 KiB, nesting to 32, nodes to 10,000, windows to
+128 and panes to 1,024. The corresponding `max_*` parse/load keywords can
+adjust these positive limits. Configuration files must be regular files.
+
+`${NAME}` substitution is opt-in for directories and environment values:
+pass `expand_environment: true, environment: {"NAME" => "value"}` to load or
+parse. Only the supplied bounded mapping is consulted. Shell text and option
+values are unchanged; `~` has no special path meaning. Missing variables fail
+validation. Parsing checks path syntax; apply checks current accessibility.
+Concurrent filesystem changes can still trigger tmux's cwd fallback.
+
+## Apply and failure results
+
+`workspace.plan(snapshot: snapshot)` retains that capture's binding identity
+and rejects a captured name conflict. Every apply takes a fresh snapshot and
+rechecks identity and name absence. The plan creates a new session; it does
+not reconcile, replace or remove a preexisting workspace. The first window
+and pane from each creation command are reused.
+
+Apply is synchronous, uses one monotonic timeout across its core operations,
+and accepts a cancellation token. Panes run `/bin/sh`; explicit initial pane
+environment overrides do not modify the session environment. Window indexes,
+splits, options, layout and focus follow the plan's order. Temporary local
+option overrides disable renumbering and pane synchronization during setup;
+the plan then restores declared values or inheritance.
+
+Session options apply before subsequent windows and split panes are created.
+On tmux 3.2a–3.6, the reused initial pane retains the global `history-limit`
+inherited at session creation. Later panes use the configured session value.
+For uniform history on these versions, configure the server's global value
+before applying the workspace. Apply does not change global options or replace
+the initial pane. On tmux 3.7+, setting the option also updates existing grids.
+
+Shell commands are sent as literal text followed by Enter. Both insertion
+and Enter are dispatch effects: embedded newlines can execute during text
+insertion. Success proves tmux accepted the dispatch, not that a shell
+command finished or succeeded. Shell commands can leave effects beyond tmux.
+
+An `ApplyError` exposes an immutable `result`: completed step IDs, positively
+identified `created_refs`, observed or dispatch-only effects, failed action,
+uncertainty and cleanup diagnostics. Diagnostics omit command payloads and
+paths. Lost creation replies stay uncertain; names are never used to guess
+ownership. A caller may pass `compensate: true` to kill only the positively
+returned new session on failure, after an atomic tmux guard proves that every
+current window and pane has a positively identified created reference. Unknown
+initial entities or borrowed entities moved into that session cause refusal.
+Cleanup uses a separate 0.5-second budget. Compensation status is explicit and
+cannot undo shell effects. The default
+preserves partial state for inspection. Applying or compensating does not
+close the supplied server binding.
+
+## Command-line interface
+
+The gem installs `libtmux-workspace`. `validate` and offline
+`plan` do not contact tmux. Without a filename, discovery requires exactly one
+`.tmuxp.yaml`, `.tmuxp.yml` or `.tmuxp.json` in the current directory.
+
+Check the installed gem version without reading a configuration or contacting
+tmux:
+
+```console
+$ libtmux-workspace --version
+```
+
+```console
+$ libtmux-workspace validate workspace.yaml
+```
+
+Human plans list ordered operations and their effects. `--json` prints the
+same plan data as `Plan#to_h`, including configured command text and paths.
+
+```console
+$ libtmux-workspace plan \
+    --json \
+    workspace.yaml
+```
+
+`load` and `plan --live` require `--socket` for an existing server. This
+detached creation example uses an explicitly supplied `TMUX_SOCKET` value:
+
+```console
+$ libtmux-workspace load \
+    --socket "$TMUX_SOCKET" \
+    --json \
+    workspace.yaml
+```
+
+`--timeout` bounds each apply, live capture or subsequent switch operation
+and defaults to 5 seconds.
+`--compensate` enables guarded cleanup after apply failure. Environment
+expansion requires both `--expand-environment` and explicit `--env NAME=VALUE`
+arguments; ambient environment variables are not copied into that mapping.
+
+`load --attach` opens the CLI's `/dev/tty` after creation and runs an owned
+terminal client until the user detaches. It requires a valid `TERM`. Failure
+to open or attach the terminal retains the successful apply ledger and
+returns status 3. `load --switch CLIENT` switches the explicit current tmux
+client selector to the created session after apply, preserving the session's
+environment. It accepts a current client name, full TTY path or TTY path
+without `/dev/`; native first-match behavior applies. A missing client fails
+without fallback and retains the created session and ledger with status 3.
+Missing or invalid selector arguments fail before creation. Use
+`--switch=VALUE` for a selector beginning with `-`.
+
+The selector is resolved at dispatch; a reconnect matching it is eligible.
+It is not a captured client reference or proof of terminal ownership. Attach
+and switch are mutually exclusive. Neither operation infers a latest client,
+and library `Plan#apply` performs neither operation.
+
+| Exit status | Meaning |
+| --- | --- |
+| 0 | Validation, planning or apply succeeded; requested attach/switch succeeded |
+| 1 | Execution failed before known application effects |
+| 2 | Configuration or arguments are invalid |
+| 3 | Application was partial or uncertain, or a later attach/switch/cleanup failed |
+| 130 | Interrupted; available effect ledger is retained |
+
+JSON mode writes one result or error object to stdout. Apply errors include
+`ApplyResult#to_h`; human errors write the diagnostic and any ledger to stderr.
+Diagnostics omit configuration payloads. Explicit plan rendering and canonical
+configuration export contain those values by design.

data/exe/libtmux-workspace

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "libtmux/workspace/cli"
+
+exit LibTmux::Workspace::CLI.run(ARGV)

data/lib/libtmux/workspace/apply.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module LibTmux
+  class Workspace
+    class ApplyResult
+      Effect = Data.define(:step_id, :action, :outcome)
+      attr_reader :completed_steps, :created_refs, :effects, :failed_step, :failed_action,
+        :compensation, :cleanup_errors
+
+      def initialize(completed_steps:, created_refs:, effects:, failed_step:, failed_action:,
+        uncertain:, compensation:, cleanup_errors:)
+        @completed_steps, @created_refs, @effects = completed_steps.dup.freeze, created_refs.dup.freeze, effects.dup.freeze
+        @failed_step, @failed_action, @uncertain = failed_step, failed_action, uncertain
+        @compensation, @cleanup_errors = compensation, cleanup_errors.map { |error| error.dup.freeze }.freeze
+        freeze
+      end
+      private_class_method :new
+
+      def success?
+        failed_action.nil?
+      end
+
+      def uncertain?
+        @uncertain
+      end
+
+      def inspect
+        "#<#{self.class} success=#{success?} completed_steps=#{completed_steps.length} created_refs=#{created_refs.length} uncertain=#{uncertain?} compensation=#{compensation}>"
+      end
+
+      def to_h
+        {"success" => success?, "completed_steps" => completed_steps,
+          "created_refs" => created_refs.transform_values do |ref|
+            {"binding_key" => ref.binding_key, "kind" => ref.kind.to_s, "id" => ref.id}
+          end,
+          "effects" => effects.map { |effect| {"step_id" => effect.step_id, "action" => effect.action.to_s, "outcome" => effect.outcome.to_s} },
+          "failed_step" => failed_step, "failed_action" => failed_action&.to_s,
+          "uncertain" => uncertain?, "compensation" => compensation.to_s, "cleanup_errors" => cleanup_errors}
+      end
+    end
+
+    class ApplyError < LibTmux::Error
+      attr_reader :result, :failure_class
+
+      def initialize(result, failure)
+        @result, @failure_class = result, failure.class.name.freeze
+        delivery = result.uncertain? ? :possibly_sent : (result.effects.empty? ? :not_sent : :observed)
+        super("workspace apply failed during #{result.failed_action} (#{failure_class})",
+          phase: :apply, delivery: delivery, cleanup_errors: result.cleanup_errors)
+      end
+    end
+
+    class ApplyExecution
+      def initialize(plan, server, timeout, cancel, compensate)
+        raise ArgumentError, "workspace apply requires a Server" unless server.is_a?(LibTmux::Server)
+        raise ArgumentError, "workspace timeout must be finite" unless timeout.is_a?(Numeric) && timeout.finite?
+        raise ArgumentError, "compensate must be boolean" unless [true, false].include?(compensate)
+        if cancel && !(cancel.respond_to?(:reader) && cancel.respond_to?(:cancelled?))
+          raise ArgumentError, "cancel must provide a cancellation reader and state"
+        end
+        @plan, @server, @cancel, @compensate = plan, server, cancel, compensate
+        @deadline = clock + timeout
+        @entities, @created, @completed, @effects, @cleanup_errors = {}, {}, [], [], []
+        @compensation = :not_requested
+        @action, @pending, @mutation = :preflight, false, false
+      end
+
+      def call
+        failure = nil
+        begin
+          Thread.handle_interrupt(Exception => :never) do
+            begin
+              preflight
+              @plan.steps.each do |step|
+                @step = step
+                perform(step)
+                @completed << step.id
+              end
+              checkpoint
+            rescue Exception => error
+              failure = error
+              @uncertain = @pending && @mutation && (!error.is_a?(LibTmux::Error) || error.delivery != :not_sent)
+            ensure
+              compensate if failure && @compensate
+            end
+          end
+        rescue Exception => deferred
+          failure ||= deferred
+        end
+        result = ApplyResult.__send__(:new, completed_steps: @completed, created_refs: @created,
+          effects: @effects, failed_step: failure && @step&.id, failed_action: failure && @action,
+          uncertain: !!@uncertain, compensation: @compensation, cleanup_errors: @cleanup_errors)
+        raise ApplyError.new(result, failure), cause: nil if failure
+
+        result
+      end
+
+      private
+
+      def preflight
+        snapshot = action(:capture_preconditions, mutation: false) { |options| @server.snapshot(**options) }
+        expected = @plan.preconditions.fetch("binding_key")
+        if expected && expected != snapshot.binding_key
+          raise ConflictError.new("workspace plan belongs to another server binding", phase: :apply)
+        end
+        if snapshot.sessions.where(name: @plan.preconditions.fetch("session_name_absent")).exists?
+          raise ConflictError.new("workspace creation requires an absent session name", phase: :apply)
+        end
+        @plan.steps.filter_map { |step| step.arguments["cwd"] }.uniq.each do |directory|
+          unless File.directory?(directory) && File.executable?(directory)
+            raise ConfigError.new("workspace directory is unavailable", expected: "existing accessible directory")
+          end
+        end
+      end
+
+      def perform(step)
+        args = step.arguments
+        target = @entities[step.target]
+        case step.operation
+        when :create_session
+          action(:create_session) do |options|
+            assignments = args.fetch("pane_environment").map { |name, value| "#{name}=#{value}" }
+            receipt = @server.new_session(name: args.fetch("name"), window_name: args.fetch("window_name"),
+              cwd: args.fetch("cwd"), environment: args.fetch("environment"),
+              command: ["/usr/bin/env", "--", *assignments, "/bin/sh"], receipt: true, **options)
+            remember("session", receipt.entity)
+            remember(step.produces[1], receipt.window)
+            remember(step.produces[2], receipt.pane)
+          end
+        when :create_window
+          action(:create_window) do |options|
+            receipt = target.new_window(name: args.fetch("name"), index: args.fetch("index"), command: ["/bin/sh"],
+              cwd: args.fetch("cwd"), environment: args.fetch("environment"), focus: false, receipt: true, **options)
+            remember(step.produces.first, receipt.window)
+            remember(step.produces[1], receipt.pane)
+          end
+        when :split_pane
+          action(:split_pane) do |options|
+            pane = target.split(direction: args.fetch("direction").to_sym, size: args["size"], command: ["/bin/sh"],
+              cwd: args.fetch("cwd"), environment: args.fetch("environment"), focus: false, **options)
+            remember(step.produces.first, pane)
+          end
+        when :move_initial_window
+          link = link_for(target)
+          if link.index != args.fetch("index")
+            action(:move_initial_window) { |options| link.move(session: @entities.fetch("session").ref, index: args.fetch("index"), **options) }
+          end
+        when :set_session_option, :set_window_option
+          action(step.operation) { |options| target.options.set(args.fetch("name"), args.fetch("value"), **options) }
+        when :unset_session_option, :unset_window_option
+          action(step.operation) { |options| target.options.unset(args.fetch("name"), **options) }
+        when :select_layout
+          action(:select_layout) { |options| target.select_layout(args.fetch("layout"), **options) }
+        when :send_command
+          action(:insert_command_text, outcome: :dispatch_only) { |options| target.send_text(args.fetch("command"), **options) }
+          action(:dispatch_command, outcome: :dispatch_only) { |options| target.send_keys("Enter", **options) }
+        when :select_pane
+          action(:select_pane) { |options| target.select(**options) }
+        when :select_window
+          link = link_for(target)
+          action(:select_window) { |options| link.select(**options) }
+        else
+          raise UnsupportedFeatureError.new("workspace plan operation is unsupported", phase: :apply)
+        end
+      end
+
+      def link_for(window)
+        links = action(:acquire_window_link, mutation: false) { |options| @entities.fetch("session").list_window_links(**options) }
+        only(links.select { |link| link.id == window.id })
+      end
+
+      def only(values)
+        unless values.length == 1
+          raise ConflictError.new("created workspace topology changed during apply", phase: :apply, delivery: :observed)
+        end
+        values.first
+      end
+
+      def remember(name, entity)
+        @entities[name] = entity
+        @created[name] = entity.ref
+        entity
+      end
+
+      def action(name, mutation: true, outcome: :observed)
+        @action, @pending, @mutation = name, false, mutation
+        checkpoint
+        raise Cancelled.new("workspace apply was cancelled", phase: :apply) if @cancel&.cancelled?
+        remaining = @deadline - clock
+        raise DeadlineExceeded.new("workspace apply deadline elapsed", phase: :apply) unless remaining.positive?
+
+        @pending = true
+        result = Thread.handle_interrupt(Exception => :on_blocking) { yield(timeout: remaining, cancel: @cancel) }
+        @effects << ApplyResult::Effect.new(step_id: @step&.id, action: name, outcome: outcome) if mutation
+        @pending = false
+        checkpoint
+        result
+      end
+
+      def compensate
+        session = @entities["session"]
+        @compensation = :nothing_owned
+        return unless session
+
+        deadline = clock + 0.5
+        # A deferred interruption can be delivered by a core command checkpoint.
+        # Retry only the positively owned session, within the same cleanup budget.
+        2.times do
+          begin
+            remaining = deadline - clock
+            raise DeadlineExceeded.new("workspace compensation deadline elapsed") unless remaining.positive?
+
+            windows = @created.values.select { |ref| ref.kind == :window }
+            panes = @created.values.select { |ref| ref.kind == :pane }
+            session.kill(expected_windows: windows, expected_panes: panes, timeout: remaining)
+            @compensation = :completed
+            return
+          rescue Exception => cleanup
+            @compensation = :failed
+            @cleanup_errors << "workspace compensation failed (#{cleanup.class})"
+          end
+        end
+      end
+
+      def checkpoint
+        Thread.handle_interrupt(Exception => :immediate) { nil }
+      end
+
+      def clock
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+    private_constant :ApplyExecution
+  end
+end