libtmux-workspace 0.1.0.alpha.3 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c27c9bbe4d2cf44b5cbee027902519d4443858717ac679f12d879b426869d1c
-  data.tar.gz: b8da758f2977f2a1b4fb15230951db6e094704b24f117b54d0eae4aa42e2b821
+  metadata.gz: 67f1d8ae912d503b3f05aa72b9740ab8610899bf110ff6c9def7a491e2ab1467
+  data.tar.gz: b508046883150482276d3647766aa3beedd7d63e658662eb8643a8667262a355
 SHA512:
-  metadata.gz: 4688b7848b4408a2a7f397d8468ddbb0581f8e330dbea1472d414b37f12ebf32be957b43a3a3b386b758f3b51ebd1416255ddd2714978441978f3c50e5c909aa
-  data.tar.gz: d6fcee3d35cd4261025cd62e6a9beef1b353ccab5bc08c1ceb56f05cd5535a9f02746371f2136e558c662741e4cfa4490395b732d85174543ca26f4f82745aac
+  metadata.gz: d2a319893795e19c71a96ef8060f5468fbbd9218bd566ded215872e057064da62c53cd6c0883f98191ead6f7b7d7ff8cf2c3682eca7d6c8d2a5af56d46fdede5
+  data.tar.gz: e725e40e92e6515ea0cb8d49c5b7051e0e7a89499a97c7cd9c4254d19d0a865a9b8621a0381cca32d008e164f062974437ab78dc1abea8849800fd317cc652bd

data/README.md

@@ -20,6 +20,9 @@
 [Guides](https://libtmux.org/en/ruby/latest/workspace/guides/) ·
 [RubyGems](https://rubygems.org/gems/libtmux-workspace)
 
+[![libtmux.org](https://img.shields.io/badge/docs-libtmux.org-0b7285)](https://libtmux.org/en/ruby/latest/workspace/)
+[![libtmux-workspace](https://img.shields.io/gem/v/libtmux-workspace?label=libtmux-workspace)](https://rubygems.org/gems/libtmux-workspace)
+
 </div>
 
 Part of [libtmux for Ruby](https://github.com/libtmux/libtmux-ruby#readme).
@@ -42,11 +45,11 @@ tmux process.
 
 ## Quick start
 
-Install the alpha and its `libtmux-workspace` executable. It needs Ruby 3.3 or
+Install the gem and its `libtmux-workspace` executable. It needs Ruby 3.3 or
 newer, and tmux 3.3a or newer to load a plan:
 
 ```console
-$ gem install libtmux-workspace --pre
+$ gem install libtmux-workspace
 ```
 
 Save this declared subset of tmuxp-style data as `workspace.yaml`. Relative
@@ -314,9 +317,13 @@ $ libtmux-workspace plan \
     workspace.yaml
 ```
 
-[`load`][cli-load] and `plan --live` require `--socket` for an existing
-server. This detached creation example uses an explicitly supplied
-`TMUX_SOCKET` value:
+[`load`][cli-load] and `plan --live` act on an existing server. Without
+`--socket`, they use the socket in `LIBTMUX_SOCKET_PATH`, else the name in
+`LIBTMUX_SOCKET`, else the server `TMUX` names when run inside tmux, else
+tmux's default socket. When both variables are set, the path wins, an empty
+variable counts as unset, and `--socket` ignores both. A command run from a tmux
+pane with none of these set acts on that pane's server. This detached creation
+example names its socket with a `TMUX_SOCKET` value:
 
 ```console
 $ libtmux-workspace load \
@@ -331,7 +338,7 @@ $ libtmux-workspace load \
 | Option | Effect |
 | --- | --- |
 | `--json` | Write one structured result or error object to stdout |
-| `--socket PATH` | Select the existing server's socket for `load` or `plan --live` |
+| `--socket PATH` | Select the existing server's socket for `load` or `plan --live`; the default follows the socket variables, then `TMUX`, then tmux's default socket |
 | `--live` | Capture a snapshot before planning |
 | `--timeout SECONDS` | Bound each apply, live capture or switch operation; the default is 5 |
 | `--compensate` | Run guarded cleanup after an apply failure |
@@ -370,7 +377,9 @@ values by design.
 
 ## Support and status
 
-**Alpha.** APIs may change between releases.
+Releases are numbered `0.1.N`, and each release increments `N`. The API is not
+settled: any release may change or remove exported identifiers, and the
+changelog marks each break. Pin an exact version to avoid one.
 
 - **Ruby 3.3 or newer.** The gem depends on the same version of `libtmux`,
   JSON 3.0 and Psych 5.5.
@@ -380,8 +389,10 @@ values by design.
   `error.kind` is `tmux_unsupported`.
 - **Linux, including WSL, and macOS.** The library and the command share the
   core [compatibility workflow][compat]: Ruby 3.3, 3.4 and 4.0 with tmux 3.3a
-  through 3.8 on Ubuntu 24.04, with per-revision results. macOS is supported on
-  a best-effort basis, and CI coverage for it is highly limited.
+  through 3.8 on Ubuntu 24.04, with per-revision results. A push and a pull
+  request run the oldest and newest of those releases, 3.3a and 3.8, and a
+  release runs all of them. macOS is supported on a best-effort basis, and CI
+  coverage for it is highly limited.
 - **History limit.** On tmux 3.3a to 3.6 the reused initial pane keeps the
   global `history-limit`. Set the server's global value before you apply to
   get one history size.

data/lib/libtmux/workspace/cli.rb

@@ -85,7 +85,9 @@ module LibTmux
         @parser ||= OptionParser.new do |options|
           options.banner = "Usage: libtmux-workspace validate|plan|load [options] [FILE]"
           options.on("--json", "Write structured JSON to stdout") { @json = true }
-          options.on("--socket PATH", "Explicit existing tmux socket for load or plan --live") { |value| @options[:socket] = value }
+          options.on("--socket PATH", "Socket of the existing tmux server for load or plan --live",
+            "Default: LIBTMUX_SOCKET_PATH, then LIBTMUX_SOCKET, then the",
+            "server TMUX names, then tmux's default socket") { |value| @options[:socket] = value }
           options.on("--live", "Acquire a snapshot before planning") { @options[:live] = true }
           options.on("--timeout SECONDS", Float, "Per-operation apply/capture/switch deadline (default: 5)") { |value| @options[:timeout] = value }
           options.on("--compensate", "Attempt guarded cleanup of positively created resources on failure") { @options[:compensate] = true }
@@ -125,7 +127,7 @@ module LibTmux
         raise ArgumentError if command != "load" && (@options[:attach] || @options[:switch] || @options[:compensate])
         raise ArgumentError if @options[:live] && command != "plan"
         live = command == "load" || @options[:live]
-        raise ArgumentError if live && (!@options[:socket].is_a?(String) || @options[:socket].empty?)
+        raise ArgumentError if @options.key?(:socket) && @options[:socket].empty?
         raise ArgumentError if !live && @options[:socket]
         if @options[:attach]
           term = @environment["TERM"]
@@ -145,7 +147,23 @@ module LibTmux
       end
 
       def with_server(&block)
-        LibTmux::Server.open(socket_path: File.expand_path(@options.fetch(:socket), @directory), &block)
+        LibTmux::Server.open(endpoint: endpoint, &block)
+      end
+
+      # --socket wins; otherwise the core reads the variables, TMUX and tmux's default.
+      def endpoint
+        socket = @options[:socket]
+        LibTmux::Endpoint.new(socket_path: (expand_socket(socket) if socket), environment: @environment)
+      rescue ArgumentError => error
+        @argument_message = "Invalid arguments: #{error.message}."
+        raise
+      end
+
+      # File.expand_path puts the user it cannot find in its message.
+      def expand_socket(socket)
+        File.expand_path(socket, @directory)
+      rescue ArgumentError
+        raise ArgumentError, "--socket cannot be expanded to a path; its leading ~ names no home directory"
       end
 
       def human_plan(plan)

data/lib/libtmux/workspace/version.rb

@@ -2,6 +2,6 @@
 
 module LibTmux
   class Workspace
-    VERSION = "0.1.0.alpha.3"
+    VERSION = "0.1.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libtmux-workspace
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha.3
+  version: 0.1.1
 platform: ruby
 authors:
 - libtmux contributors
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0.alpha.3
+        version: 0.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0.alpha.3
+        version: 0.1.1
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -76,7 +76,7 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/libtmux/libtmux-ruby
-  documentation_uri: https://libtmux.org/en/ruby/v0.1.0.alpha.3/workspace/
+  documentation_uri: https://libtmux.org/en/ruby/v0.1.1/workspace/
 rdoc_options: []
 require_paths:
 - lib