libtmux-workspace 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66d96c81c6ee85c0bc75c616571fd4a8184bdec03117d48424898a6bc5ca7513
-  data.tar.gz: f6677029749a5f5d3eeeea3e1df64a3f78d44243917d1192007de6db8ae2157a
+  metadata.gz: 81a6e6bcb2e2b40052ea69a7ac812919bc40c061eff86d8f1ed24d74db1bdd89
+  data.tar.gz: bed554f76a48119e57294fa4199479ce7d9ce1e9864d9a3189224daa11979be7
 SHA512:
-  metadata.gz: 741f07d62607be8fc81a90c88ff66f69addad12bb7dcbd196059563e4635d629f326048b878ff21d298fb1e00f3b0ef8b862a2c7a5cad88ce054be0727251598
-  data.tar.gz: 470f30b5b38a41c8dc4922b59d205c8ef88119838d0f68eedaba1157b1187b14d81fb45cef815afb15305b1cb23f56e67585ffb8b7e7ad90788ee71bed770144
+  metadata.gz: 42b471a92bea5e05bfea43e6005c0373df57aa5606e00c1e72af64960e33b0de755edfb48d6b4f6b07b665b8d59c9ef45b71a0e62cca087bbe82b50d12117b02
+  data.tar.gz: 37069ac56ea23c718a2e1cf7029297151ca5672a96ca1d4420aeef4b3fbba99e6ead871aebe999e1dc0a828d3d75a9361549f52f20ca6b451c9d4f9300fbbe1e

data/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+Notable changes to `libtmux-workspace`.
+
+Releases are numbered `0.1.N`, and each release increments `N`. The API is not
+settled: pin an exact version to avoid a break.
+
+The gems are released together at one version, so every release has a section
+here. Changes that span gems, such as documentation, CI and release tooling, are
+in the [main changelog](../../CHANGELOG.md).
+
+## 0.1.3 (unreleased)
+
+## 0.1.2 (2026-11-04)
+
+No entries for `libtmux-workspace`.
+
+## 0.1.1 (2026-10-31)
+
+- **Behavior change:** `libtmux-workspace load` and `plan --live` no longer
+  need `--socket`. Without it they use the same choice as `Server.new`, so a
+  command that failed with status 2 for a missing socket now acts on the
+  server tmux would pick. (#71)
+
+## 0.1.0 (2026-10-25)
+
+No entries for `libtmux-workspace`.
+
+## 0.1.0.alpha.3 (2026-10-24)
+
+No entries for `libtmux-workspace`.
+
+## 0.1.0.alpha.2 (2026-10-18)
+
+No entries for `libtmux-workspace`.
+
+## 0.1.0.alpha.1 (2026-09-20)
+
+### libtmux-workspace
+
+- Load YAML or JSON with `LibTmux::Workspace.load` or `.parse`, inspect a
+  creation plan, then apply it explicitly. Supports the documented subset of
+  tmuxp-style configuration. [Workspace example](../../examples/workspace_apply.rb).
+- Validate, plan and load from the `libtmux-workspace` CLI; optionally attach
+  or switch an explicit client after creation. `--version` reports the
+  installed gem version without reading a configuration or contacting tmux.
+  [CLI guide](../../gems/libtmux-workspace/README.md#script-it).
+- Inspect partial application through `ApplyError#result`. Optional
+  compensation removes only a positively identified new session after
+  checking that its windows and panes belong to the apply operation.
+  [Failure results](../../gems/libtmux-workspace/README.md#recover-from-a-failed-apply).

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).
@@ -182,26 +185,47 @@ and never reconciles an existing one.
 [`Workspace.load`][workspace-load] reads the file,
 [`workspace.plan`][workspace-plan-method] plans it against a snapshot, and
 `apply` creates the session. Calling `apply` authorizes the configuration's
-shell commands:
+shell commands.
+
+[The example file](../../examples/api/workspace_apply.rb) writes the same
+document to a temporary `workspace.yaml` before loading it, so it runs saved on
+its own:
 
 <!-- example: api_workspace_apply/main -->
 ```ruby
 require "libtmux"
 require "libtmux/workspace"
-
-LibTmux::Server.start do |server|
-  workspace = LibTmux::Workspace.load(File.expand_path("../workspace.yaml", __dir__))
-  plan = workspace.plan(snapshot: server.snapshot)
-  puts "planned steps: #{plan.steps.length}"
-  result = plan.apply(server: server)
-  puts "applied: #{result.success?}"
-  puts "sessions: #{server.list_sessions.map { |session| session.snapshot.name }.join(', ')}"
+require "tmpdir"
+
+document = <<~'YAML'
+  session_name: work
+  environment:
+    PROJECT_MODE: development
+  windows:
+    - window_name: editor
+      window_index: 1
+      layout: tiled
+      panes:
+        - shell_command: printf 'editor ready\n'
+        - {}
+YAML
+
+Dir.mktmpdir("workspace-") do |directory|
+  path = File.join(directory, "workspace.yaml")
+  File.write(path, document)
+  LibTmux::Server.start do |server|
+    workspace = LibTmux::Workspace.load(path)
+    plan = workspace.plan(snapshot: server.snapshot)
+    puts "planned steps: #{plan.steps.length}"
+    result = plan.apply(server: server)
+    puts "applied: #{result.success?}"
+    puts "sessions: #{server.list_sessions.map { |session| session.snapshot.name }.join(', ')}"
+  end
 end
 ```
 <!-- /example -->
 
-The program runs next to the `workspace.yaml` above, on a private server, and
-prints:
+The program runs on a private server and prints:
 
 ```text
 planned steps: 11
@@ -314,9 +338,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 +359,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 |
@@ -372,7 +400,10 @@ values by design.
 
 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.
+changelogs mark each break. Pin an exact version to avoid one.
+See the [changelog](CHANGELOG.md), and the [main
+changelog](https://github.com/libtmux/libtmux-ruby/blob/master/CHANGELOG.md)
+for changes that span gems.
 
 - **Ruby 3.3 or newer.** The gem depends on the same version of `libtmux`,
   JSON 3.0 and Psych 5.5.
@@ -382,8 +413,10 @@ changelog marks each break. Pin an exact version to avoid one.
   `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"
+    VERSION = "0.1.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libtmux-workspace
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - libtmux contributors
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.2
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -58,6 +58,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - assets/logo.png
@@ -76,7 +77,8 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/libtmux/libtmux-ruby
-  documentation_uri: https://libtmux.org/en/ruby/v0.1.0/workspace/
+  changelog_uri: https://github.com/libtmux/libtmux-ruby/blob/master/gems/libtmux-workspace/CHANGELOG.md
+  documentation_uri: https://libtmux.org/en/ruby/v0.1.2/workspace/
 rdoc_options: []
 require_paths:
 - lib