libtmux-workspace 0.1.0.alpha.1

data/lib/libtmux/workspace/plan.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module LibTmux
+  class Workspace
+    class Plan
+      Step = Data.define(:id, :operation, :target, :arguments, :produces, :effect) do
+        def inspect
+          "#<#{self.class} id=#{id} operation=#{operation} effect=#{effect}>"
+        end
+      end
+      attr_reader :mode, :preconditions, :steps
+
+      def initialize(workspace, snapshot: nil)
+        unless snapshot.nil? || snapshot.is_a?(LibTmux::Snapshot)
+          raise ArgumentError, "workspace planning requires a captured Snapshot"
+        end
+        @configuration = workspace.to_h
+        name = @configuration.fetch("session_name")
+        if snapshot && snapshot.sessions.where(name: name).exists?
+          raise ConflictError.new("workspace creation requires an absent session name", phase: :plan)
+        end
+        @mode = snapshot ? :captured_create : :offline_create
+        @preconditions = immutable({"session_name_absent" => name,
+          "binding_key" => snapshot&.binding_key, "capture_id" => snapshot&.capture_id})
+        @steps = []
+        build
+        @steps.freeze
+        freeze
+      end
+
+      def to_h
+        {"profile" => PROFILE, "version" => CONFIG_VERSION, "mode" => mode.to_s,
+          "preconditions" => preconditions,
+          "steps" => steps.map do |step|
+            {"id" => step.id, "operation" => step.operation.to_s, "target" => step.target,
+              "arguments" => step.arguments, "produces" => step.produces, "effect" => step.effect.to_s}
+          end}
+      end
+
+      def inspect
+        "#<#{self.class} mode=#{mode} steps=#{steps.length}>"
+      end
+
+      def apply(server:, timeout: 5.0, cancel: nil, compensate: false)
+        ApplyExecution.new(self, server, timeout, cancel, compensate).call
+      end
+
+      private
+
+      def build
+        windows = @configuration.fetch("windows")
+        initial = windows.first.fetch("panes").first
+        add(:create_session, "session", {"name" => @configuration.fetch("session_name"),
+          "window_name" => windows.first.fetch("window_name"), "cwd" => initial.fetch("start_directory"),
+          "session_cwd" => @configuration.fetch("start_directory"),
+          "environment" => @configuration.fetch("environment"), "pane_environment" => initial.fetch("environment")},
+          produces: ["session", "window:0", "pane:0:0"], effect: :creation)
+        add(:set_session_option, "session", {"name" => "renumber-windows", "value" => false})
+        add(:set_window_option, "window:0", {"name" => "synchronize-panes", "value" => false})
+        add(:move_initial_window, "window:0", {"session" => "session", "index" => windows.first.fetch("window_index")})
+        @configuration.fetch("options").sort.each do |name, value|
+          add(:set_session_option, "session", {"name" => name, "value" => value}) unless name == "renumber-windows"
+        end
+        windows.each_with_index do |window, position|
+          unless position.zero?
+            pane = window.fetch("panes").first
+            add(:create_window, "session", {"name" => window.fetch("window_name"), "index" => window.fetch("window_index"),
+              "cwd" => pane.fetch("start_directory"), "environment" => pane.fetch("environment"), "focus" => false},
+              produces: ["window:#{position}", "pane:#{position}:0"], effect: :creation)
+            add(:set_window_option, "window:#{position}", {"name" => "synchronize-panes", "value" => false})
+          end
+          window.fetch("panes").each_with_index do |pane, pane_position|
+            next if pane_position.zero?
+            add(:split_pane, "pane:#{position}:#{pane_position - 1}",
+              {"direction" => pane.fetch("split"), "size" => pane["size"], "cwd" => pane.fetch("start_directory"),
+                "environment" => pane.fetch("environment"), "focus" => false},
+              produces: ["pane:#{position}:#{pane_position}"], effect: :creation)
+          end
+        end
+        windows.each_with_index do |window, position|
+          window.fetch("options").sort.each do |name, value|
+            next if name == "synchronize-panes"
+            add(:set_window_option, "window:#{position}", {"name" => name, "value" => value})
+          end
+          add(:select_layout, "window:#{position}", {"layout" => window.fetch("layout")}) if window["layout"]
+          window.fetch("panes").each_with_index do |pane, pane_position|
+            (pane.fetch("shell_command_before") + pane.fetch("shell_command")).each do |command|
+              add(:send_command, "pane:#{position}:#{pane_position}", {"command" => command}, effect: :dispatch_only)
+            end
+          end
+          if window.fetch("options").key?("synchronize-panes")
+            add(:set_window_option, "window:#{position}", {"name" => "synchronize-panes", "value" => window.fetch("options").fetch("synchronize-panes")})
+          else
+            add(:unset_window_option, "window:#{position}", {"name" => "synchronize-panes"})
+          end
+          pane_focus = window.fetch("panes").index { |pane| pane.fetch("focus") }
+          add(:select_pane, "pane:#{position}:#{pane_focus}", {})
+        end
+        selected = windows.index { |window| window.fetch("focus") }
+        add(:select_window, "window:#{selected}", {"session" => "session"})
+        if @configuration.fetch("options").key?("renumber-windows")
+          add(:set_session_option, "session", {"name" => "renumber-windows", "value" => @configuration.fetch("options").fetch("renumber-windows")})
+        else
+          add(:unset_session_option, "session", {"name" => "renumber-windows"})
+        end
+      end
+
+      def add(operation, target, arguments, produces: [], effect: :configuration)
+        @steps << Step.new(id: @steps.length + 1, operation: operation, target: target.freeze,
+          arguments: immutable(arguments), produces: immutable(produces), effect: effect)
+      end
+
+      def immutable(value)
+        case value
+        when Hash then value.to_h { |key, child| [key.dup.freeze, immutable(child)] }.freeze
+        when Array then value.map { |child| immutable(child) }.freeze
+        when String then value.dup.freeze
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/libtmux/workspace/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module LibTmux
+  class Workspace
+    VERSION = "0.1.0.alpha.1"
+  end
+end

data/lib/libtmux/workspace.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "libtmux"
+require "json"
+require "psych"
+require "libtmux/workspace/version"
+
+module LibTmux
+  class Workspace
+    PROFILE = "libtmux-ruby.workspace"
+    CONFIG_VERSION = 1
+    LIMITS = {max_bytes: 1 << 20, max_depth: 32, max_nodes: 10_000,
+      max_string_bytes: 1 << 16, max_windows: 128, max_panes: 1024}.freeze
+    private_constant :LIMITS
+
+    class ConfigError < LibTmux::Error
+      def initialize(message = "invalid workspace configuration", path: "$", expected: nil)
+        super("#{message} at #{path}#{expected ? "; expected #{expected}" : ''}", path: path, expected: expected, phase: :workspace)
+      end
+    end
+    class ConflictError < LibTmux::Error; end
+
+    def self.load(path, format: nil, **options)
+      unless path.is_a?(String) && !path.empty? && !path.include?("\0")
+        raise ArgumentError, "workspace path must be a nonempty String without NUL"
+      end
+      filename = File.expand_path(path)
+      format ||= case File.extname(filename).downcase
+      when ".json" then :json
+      when ".yaml", ".yml" then :yaml
+      else raise ConfigError.new("workspace file format is unknown", expected: "JSON/YAML extension or explicit format")
+      end
+      limit = options.fetch(:max_bytes, LIMITS.fetch(:max_bytes))
+      raise ArgumentError, "workspace byte limit must be a positive integer" unless limit.is_a?(Integer) && limit.positive?
+
+      bytes = File.open(filename, File::RDONLY | File::NONBLOCK) do |file|
+        raise ConfigError.new("invalid workspace file", expected: "regular configuration file") unless file.stat.file?
+        file.binmode
+        file.read(limit + 1) || ""
+      end
+      parse(bytes, format: format, base_directory: File.dirname(filename), **options)
+    rescue SystemCallError
+      raise ConfigError.new("workspace file could not be read", expected: "readable configuration file"), cause: nil
+    end
+
+    def self.parse(bytes, format:, base_directory:, expand_environment: false, environment: {}, **limits)
+      unless (limits.keys - LIMITS.keys).empty? && limits.values.all? { |value| value.is_a?(Integer) && value.positive? }
+        raise ArgumentError, "workspace limits must be known positive integers"
+      end
+      bounds = LIMITS.merge(limits).freeze
+      document = Document.new(bounds).parse(bytes, format)
+      config = Normalizer.new(base_directory, expand_environment, environment, bounds).normalize(document)
+      if JSON.generate(config).bytesize > bounds.fetch(:max_bytes)
+        raise ConfigError.new("normalized workspace exceeds its wire byte limit", expected: "bounded canonical JSON")
+      end
+      Document.new(bounds).validate_tree(config)
+      new(config)
+    end
+
+    def initialize(config)
+      @config = config
+      freeze
+    end
+    private_class_method :new
+
+    def to_h
+      @config
+    end
+
+    def plan(snapshot: nil)
+      Plan.new(self, snapshot: snapshot)
+    end
+
+    def inspect
+      "#<#{self.class} profile=#{PROFILE} version=#{CONFIG_VERSION} windows=#{@config.fetch('windows').length}>"
+    end
+  end
+end
+
+require "libtmux/workspace/document"
+require "libtmux/workspace/normalizer"
+require "libtmux/workspace/plan"
+require "libtmux/workspace/apply"

data/sig/libtmux-workspace.rbs

@@ -0,0 +1,79 @@
+module LibTmux
+  class Workspace
+    private def self.new: (*untyped, **untyped) -> instance
+    VERSION: String
+    PROFILE: String
+    CONFIG_VERSION: Integer
+
+    class ConfigError < LibTmux::Error
+      def initialize: (?String, ?path: String, ?expected: String?) -> void
+    end
+    class ConflictError < LibTmux::Error
+    end
+    class ApplyError < LibTmux::Error
+      attr_reader result: ApplyResult
+      attr_reader failure_class: String
+      def initialize: (ApplyResult, Exception) -> void
+    end
+
+    class ApplyResult
+      private def self.new: (*untyped, **untyped) -> instance
+      class Effect < Data
+        def self.new: (Integer?, Symbol, :observed | :dispatch_only) -> instance
+                    | (step_id: Integer?, action: Symbol, outcome: :observed | :dispatch_only) -> instance
+        alias self.[] self.new
+        def self.members: () -> Array[Symbol]
+        attr_reader step_id: Integer?
+        attr_reader action: Symbol
+        attr_reader outcome: :observed | :dispatch_only
+      end
+      attr_reader completed_steps: Array[Integer]
+      attr_reader created_refs: Hash[String, LibTmux::EntityRef]
+      attr_reader effects: Array[Effect]
+      attr_reader failed_step: Integer?
+      attr_reader failed_action: Symbol?
+      attr_reader compensation: :not_requested | :nothing_owned | :completed | :failed
+      attr_reader cleanup_errors: Array[String]
+      def success?: () -> bool
+      def uncertain?: () -> bool
+      def to_h: () -> Hash[String, untyped]
+      def inspect: () -> String
+    end
+
+    class CLI
+      private def self.new: (*untyped, **untyped) -> instance
+      def run: () -> Integer
+      def self.run: (Array[String], ?out: untyped, ?err: untyped, ?directory: String, ?environment: untyped) -> Integer
+    end
+
+    def self.load: (String, ?format: :yaml | :json | nil, ?expand_environment: bool, ?environment: Hash[String, String], **Integer) -> Workspace
+    def self.parse: (String, format: :yaml | :json, base_directory: String, ?expand_environment: bool, ?environment: Hash[String, String], **Integer) -> Workspace
+    def to_h: () -> Hash[String, untyped]
+    def plan: (?snapshot: LibTmux::Snapshot?) -> Plan
+    def inspect: () -> String
+
+    class Plan
+      class Step < Data
+        def self.new: (Integer, Symbol, String, Hash[String, untyped], Array[String], Symbol) -> instance
+                    | (id: Integer, operation: Symbol, target: String, arguments: Hash[String, untyped], produces: Array[String], effect: Symbol) -> instance
+        alias self.[] self.new
+        def self.members: () -> Array[Symbol]
+        attr_reader id: Integer
+        attr_reader operation: Symbol
+        attr_reader target: String
+        attr_reader arguments: Hash[String, untyped]
+        attr_reader produces: Array[String]
+        attr_reader effect: Symbol
+        def inspect: () -> String
+      end
+
+      attr_reader mode: :offline_create | :captured_create
+      attr_reader preconditions: Hash[String, String?]
+      attr_reader steps: Array[Step]
+      def initialize: (Workspace, ?snapshot: LibTmux::Snapshot?) -> void
+      def to_h: () -> Hash[String, untyped]
+      def apply: (server: LibTmux::Server, ?timeout: Numeric, ?cancel: untyped, ?compensate: bool) -> ApplyResult
+      def inspect: () -> String
+    end
+  end
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: libtmux-workspace
+version: !ruby/object:Gem::Version
+  version: 0.1.0.alpha.1
+platform: ruby
+authors:
+- libtmux contributors
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: libtmux
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0.alpha.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0.alpha.1
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.2
+- !ruby/object:Gem::Dependency
+  name: psych
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.5.0
+description: Validate YAML or JSON workspace configurations, inspect creation plans
+  and apply them to tmux.
+executables:
+- libtmux-workspace
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/libtmux-workspace
+- lib/libtmux/workspace.rb
+- lib/libtmux/workspace/apply.rb
+- lib/libtmux/workspace/cli.rb
+- lib/libtmux/workspace/document.rb
+- lib/libtmux/workspace/normalizer.rb
+- lib/libtmux/workspace/plan.rb
+- lib/libtmux/workspace/version.rb
+- sig/libtmux-workspace.rbs
+homepage: https://github.com/libtmux/libtmux-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/libtmux/libtmux-ruby
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Data-only workspace consumer package for libtmux
+test_files: []