libtmux-workspace 0.1.0.alpha.1 → 0.1.0.alpha.3

checksums.yaml

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

data/README.md

@@ -1,24 +1,54 @@
+<!-- libtmux-logo -->
+<div align="center">
+  <picture>
+    <source srcset="assets/logo.svg" type="image/svg+xml">
+    <img src="assets/logo.png" width="128" height="128" alt="libtmux for Ruby workspace">
+  </picture>
+</div>
+<!-- /libtmux-logo -->
+
+<div align="center">
+
 # 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.
+[Load][workspace-load] bounded YAML or JSON, inspect an immutable
+[creation plan][workspace-plan-class], then explicitly
+[apply][workspace-plan-apply] it to an open libtmux server.
+
+[API reference](https://libtmux.org/en/ruby/latest/workspace/reference/) ·
+[Command reference](https://libtmux.org/en/ruby/latest/workspace/cli/) ·
+[Guides](https://libtmux.org/en/ruby/latest/workspace/guides/) ·
+[RubyGems](https://rubygems.org/gems/libtmux-workspace)
+
+</div>
+
+Part of [libtmux for Ruby](https://github.com/libtmux/libtmux-ruby#readme).
+Built on [libtmux](https://github.com/libtmux/libtmux-ruby/tree/master/gems/libtmux).
+
+Check a workspace file, see the ordered steps a load would run, and create the
+session on a running tmux server, from the `libtmux-workspace` command or from
+Ruby.
 
-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.
+Validation and offline planning need no running daemon, and imports start no
+tmux process.
 
-Install the alpha and its `libtmux-workspace` executable:
+**Contents** — [Quick start](#quick-start) ·
+[Write the file](#write-the-file) ·
+[Create the session](#create-the-session) ·
+[Failed apply](#recover-from-a-failed-apply) ·
+[Attach or switch](#attach-or-switch-to-the-new-session) ·
+[Scripts](#script-it) · [Leaves out](#what-it-leaves-out) ·
+[Support](#support-and-status) · [Documentation](#documentation)
+
+## Quick start
+
+Install the alpha 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
 ```
 
-## Example
-
 Save this declared subset of tmuxp-style data as `workspace.yaml`. Relative
 directories resolve against the configuration file's directory.
 
@@ -37,127 +67,235 @@ windows:
 ```
 <!-- /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:
+Check the file. [`validate`][cli-validate] reads no tmux state:
+
+```console
+$ libtmux-workspace validate workspace.yaml
+```
+
+```text
+Workspace configuration is valid.
+```
+
+Print the ordered operations a load would run. Offline [`plan`][cli-plan] does
+not contact tmux either:
+
+```console
+$ libtmux-workspace plan workspace.yaml
+```
+
+```text
+offline_create: 11 ordered steps
+1. create_session session (creation)
+2. set_session_option session (configuration)
+3. set_window_option window:0 (configuration)
+4. move_initial_window window:0 (configuration)
+5. split_pane pane:0:0 (creation)
+6. select_layout window:0 (configuration)
+7. send_command pane:0:0 (dispatch_only)
+8. unset_window_option window:0 (configuration)
+9. select_pane pane:0:0 (configuration)
+10. select_window window:0 (configuration)
+11. unset_session_option session (configuration)
+```
+
+## Write the file
 
-<!-- example: workspace_apply/main -->
+### [`Workspace.load`][workspace-load]: the declared subset
+
+`load` reads a regular file of bounded size and infers JSON or YAML from its
+extension. [`Workspace.parse`][workspace-parse] takes the text and a base
+directory instead. Both return an immutable workspace:
+
+- Root: `session_name`, nonempty `windows`, `options`, `window_options`.
+- Window: `window_name`, nonempty `panes`, `window_index`, `focus`, `layout`,
+  `options`.
+- Pane: a command string, or a mapping with `focus`, `split` and `size`.
+- Root, windows and panes accept `start_directory`, `environment`,
+  `shell_command` and `shell_command_before`.
+- Layouts are `even-horizontal`, `even-vertical`, `main-horizontal`,
+  `main-vertical` and `tiled`.
+- At most one window and one pane per window declare focus.
+- Without a filename, the command looks for exactly one `.tmuxp.yaml`,
+  `.tmuxp.yml` or `.tmuxp.json` in the current directory.
+- An unknown field or an unsupported feature fails with a
+  [`ConfigError`][workspace-configerror] that names its position in the file.
+- YAML tags, anchors and aliases are rejected, and no Ruby, ERB, plugins or
+  callbacks run.
+- `${NAME}` substitution is opt-in: pass
+  `expand_environment: true, environment: {"NAME" => "value"}` to `load` or
+  `parse`, or `--expand-environment --env NAME=VALUE` to the command.
+- [`workspace.to_h`][workspace-to_h] exports an immutable, normalized and
+  reloadable configuration, with expanded values and absolute directories.
+
+The full field, option and limit lists are in
+[Workspace parsing][behavior-workspace-parsing].
+
+## Create the session
+
+### [`libtmux-workspace load`][cli-load]: build it on a running server
+
+`load` needs a running server. It never starts one, so start a private server
+with a keepalive session and no user configuration:
+
+```console
+$ WORKSPACE_TMP=$(mktemp -d)
+```
+
+```console
+$ tmux -S "$WORKSPACE_TMP/tmux.sock" -f /dev/null new-session -d -s keepalive
+```
+
+Create the workspace's session on that socket. It stays detached:
+
+```console
+$ libtmux-workspace load \
+    --socket "$WORKSPACE_TMP/tmux.sock" \
+    workspace.yaml
+```
+
+```text
+Workspace created; 11 steps completed. Shell commands were dispatched.
+```
+
+The new `work` session holds the `editor` window:
+
+```console
+$ tmux -S "$WORKSPACE_TMP/tmux.sock" list-windows -t work
+```
+
+Stop only the private server and remove its directory:
+
+```console
+$ tmux -S "$WORKSPACE_TMP/tmux.sock" kill-server
+```
+
+```console
+$ rm -rf "$WORKSPACE_TMP"
+```
+
+Loading the same file again fails with status 1: a plan creates a new session
+and never reconciles an existing one.
+
+### [`Plan#apply`][workspace-plan-apply]: the same from Ruby
+
+[`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:
+
+<!-- example: api_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)
+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(', ')}"
 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 program runs next to the `workspace.yaml` above, on a private server, and
+prints:
 
-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.
+```text
+planned steps: 11
+applied: true
+sessions: work
+```
 
-- 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.
+- A snapshot makes the plan reject a name that already exists, and every
+  `apply` takes a fresh snapshot and checks again.
+- The plan creates a new session. It does not reconcile, replace or remove an
+  existing one.
+- Success shows that tmux accepted the dispatch of each shell command. It does
+  not show that the command finished.
+
+The [complete program](../../examples/workspace_apply.rb) also runs the
+installed command with `--switch`. The contract is in
+[Workspace apply][behavior-workspace-apply].
+
+## Recover from a failed apply
+
+### [`ApplyError#result`][workspace-applyerror-result]: what exists after a failure
+
+A failed apply raises [`ApplyError`][workspace-applyerror]. Its immutable
+`result` holds the completed step IDs, the
+[`created_refs`][workspace-applyresult-created_refs] tmux returned, the
+effects it observed, and the failed action. Pass `compensate: true` to remove
+only the session the apply created:
+
+<!-- example: api_workspace_failure/main -->
+```ruby
+require "json"
+require "libtmux"
+require "libtmux/workspace"
+
+LibTmux::Server.start do |server|
+  server.new_session(name: "borrowed", command: ["/bin/cat"])
+  crowded = LibTmux::Workspace.parse(
+    JSON.generate({session_name: "crowded", windows: [{window_name: "small", panes: Array.new(40) { {} }}]}),
+    format: :json, base_directory: __dir__
+  )
+  begin
+    crowded.plan.apply(server: server, compensate: true)
+  rescue LibTmux::Workspace::ApplyError => error
+    puts "failed action: #{error.result.failed_action}"
+    puts "created a session: #{error.result.created_refs.key?('session')}"
+    puts "compensation: #{error.result.compensation}"
+  end
+  puts "sessions: #{server.list_sessions.map { |session| session.snapshot.name }.join(', ')}"
+end
+```
+<!-- /example -->
+
+That many panes do not fit in one window, so tmux refuses a split after the
+session exists. It prints:
+
+```text
+failed action: split_pane
+created a session: true
+compensation: completed
+sessions: borrowed
+```
+
+- Compensation removes the new session only after a tmux guard shows that
+  every window and pane in it has a positively identified created reference.
+- An unknown initial entity, or a borrowed entity moved into the session,
+  makes it refuse.
+- Compensation cannot undo what shell commands did. Without it, the partial
+  state stays for you to inspect.
+- Diagnostics omit command payloads and paths. Names are never used to guess
+  ownership.
+
+The command takes `--compensate`. The contracts are in
+[Workspace results][behavior-workspace-results].
+
+## Attach or switch to the new session
+
+### [`load --switch`][cli-load]: move a client to the session
+
+- `load --attach` opens the CLI's `/dev/tty` after creation and runs an owned
+  terminal client until you detach. It requires a valid `TERM`.
+- `load --switch CLIENT` switches a current tmux client to the created session
+  after apply, keeping the session's environment.
+- `CLIENT` is a client name, a full TTY path or a TTY path without `/dev/`.
+  Use `--switch=VALUE` for a selector that begins with `-`.
+- A missing client, or a failure to open or attach the terminal, keeps the
+  created session and returns status 3.
+- Attach and switch are mutually exclusive, and neither infers a latest
+  client. The library's [`Plan#apply`][workspace-plan-apply] does neither.
+
+The selector rules are in [Client switching][behavior-client-switching].
+
+## Script it
+
+### [`--json`][cli-load]: one object on stdout
 
 Check the installed gem version without reading a configuration or contacting
 tmux:
@@ -166,12 +304,9 @@ tmux:
 $ 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.
+same plan data as [`Plan#to_h`][workspace-plan-to_h], including configured
+command text and paths:
 
 ```console
 $ libtmux-workspace plan \
@@ -179,8 +314,9 @@ $ libtmux-workspace plan \
     workspace.yaml
 ```
 
-`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` require `--socket` for an existing
+server. This detached creation example uses an explicitly supplied
+`TMUX_SOCKET` value:
 
 ```console
 $ libtmux-workspace load \
@@ -189,27 +325,20 @@ $ libtmux-workspace load \
     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.
+`libtmux-workspace --help` lists every option. The
+[command reference][ws-cli] has a page for each command.
+
+| 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` |
+| `--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 |
+| `--attach` | Attach this CLI's terminal after a successful `load` |
+| `--switch CLIENT` | Switch an explicit current client to the new session after `load` |
+| `--expand-environment` | Expand `${NAME}` in directories and environment values; requires `--env` |
+| `--env NAME=VALUE` | Supply a value for expansion; ambient environment variables are not copied |
 
 | Exit status | Meaning |
 | --- | --- |
@@ -219,7 +348,77 @@ and library `Plan#apply` performs neither operation.
 | 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.
+Apply errors include [`ApplyResult#to_h`][workspace-applyresult-to_h]. Human
+errors write the diagnostic and any ledger to stderr. Diagnostics omit
+configuration payloads; plan rendering and canonical export contain those
+values by design.
+
+## What it leaves out
+
+- **Reconciliation.** A plan creates a new session and never replaces or
+  removes an existing workspace. The contract is in
+  [Workspace plans][behavior-workspace-plans].
+- **Shell command completion.** Apply records a shell command as dispatched.
+  Embedded newlines can execute while the text is inserted. See
+  [Workspace apply][behavior-workspace-apply].
+- **Rollback of shell effects.** Compensation removes only tmux objects the
+  apply created. See [Workspace results][behavior-workspace-results].
+- **Features beyond the declared subset.** Plugins, ERB and callbacks are
+  rejected, and a [`ConfigError`][workspace-configerror] names the position.
+- **A guessed client.** Attach and switch need an explicit client. See
+  [Client switching][behavior-client-switching].
+
+## Support and status
+
+**Alpha.** APIs may change between releases.
+
+- **Ruby 3.3 or newer.** The gem depends on the same version of `libtmux`,
+  JSON 3.0 and Psych 5.5.
+- **tmux 3.3a or newer** to load or apply a plan.
+- **Older daemons.** `load` creates nothing and prints the refusal with the
+  floor and the remedy. With `--json`, the refusal is in `error.message` and
+  `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.
+- **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.
+
+## Documentation
+
+| | |
+| --- | --- |
+| [Reference](https://libtmux.org/en/ruby/latest/workspace/reference/) | Every public workspace class and method |
+| [Command reference][ws-cli] | A page for `validate`, `plan` and `load` |
+| [Guides][workspace-guides] | Validate, inspect and explicitly apply a plan |
+| [Topics][workspace-topics] | Format, planning boundaries, effects and failure ledgers |
+| [Public behavior][behavior-workspace-parsing] | Parsing, plans, apply, results and the command |
+| [Recipes][doc-recipes] | The workspace plan, load and failure program |
+
+[behavior-client-switching]: ../../docs/reference/behavior.md#client-switching
+[behavior-workspace-apply]: ../../docs/reference/behavior.md#workspace-apply
+[behavior-workspace-parsing]: ../../docs/reference/behavior.md#workspace-parsing
+[behavior-workspace-plans]: ../../docs/reference/behavior.md#workspace-plans
+[behavior-workspace-results]: ../../docs/reference/behavior.md#workspace-results
+[cli-load]: https://libtmux.org/en/ruby/latest/workspace/cli/load/
+[cli-plan]: https://libtmux.org/en/ruby/latest/workspace/cli/plan/
+[cli-validate]: https://libtmux.org/en/ruby/latest/workspace/cli/validate/
+[compat]: https://github.com/libtmux/libtmux-ruby/actions/workflows/compatibility.yml
+[doc-recipes]: ../../docs/recipes.md
+[workspace-applyerror]: https://libtmux.org/en/ruby/latest/workspace/reference/libtmux-workspace-applyerror/
+[workspace-applyerror-result]: https://libtmux.org/en/ruby/latest/workspace/reference/libtmux-workspace-applyerror-result/
+[workspace-applyresult-created_refs]: https://libtmux.org/en/ruby/latest/workspace/reference/libtmux-workspace-applyresult-created_refs/
+[workspace-applyresult-to_h]: https://libtmux.org/en/ruby/latest/workspace/reference/libtmux-workspace-applyresult-to_h/
+[workspace-configerror]: https://libtmux.org/en/ruby/latest/workspace/reference/libtmux-workspace-configerror/
+[workspace-guides]: https://libtmux.org/en/ruby/latest/workspace/guides/
+[workspace-load]: https://libtmux.org/en/ruby/latest/workspace/reference/libtmux-workspace-load/
+[workspace-parse]: https://libtmux.org/en/ruby/latest/workspace/reference/libtmux-workspace-parse/
+[workspace-plan-apply]: https://libtmux.org/en/ruby/latest/workspace/reference/libtmux-workspace-plan-apply/
+[workspace-plan-class]: https://libtmux.org/en/ruby/latest/workspace/reference/libtmux-workspace-plan-1qko/
+[workspace-plan-method]: https://libtmux.org/en/ruby/latest/workspace/reference/libtmux-workspace-plan-1c5c/
+[workspace-plan-to_h]: https://libtmux.org/en/ruby/latest/workspace/reference/libtmux-workspace-plan-to_h/
+[workspace-to_h]: https://libtmux.org/en/ruby/latest/workspace/reference/libtmux-workspace-to_h/
+[workspace-topics]: https://libtmux.org/en/ruby/latest/workspace/topics/
+[ws-cli]: https://libtmux.org/en/ruby/latest/workspace/cli/

data/assets/logo.svg

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 135.46667 135.46666" role="img" aria-label="libtmux for Ruby — workspace CLI" class="libtmux-logo" data-language="ruby" data-variant="workspace" focusable="false"><title>libtmux for Ruby — workspace CLI</title><g transform="translate(-210.28959,-409.98108)" data-part="artwork"><path d="m 334.66493,533.88598 v 11.56176 h 3.76501 c 4.04619,2.1e-4 7.32623,-3.28012 7.32632,-7.32631 v -4.23545 z" fill="#333333" data-part="base-edge"></path><g transform="matrix(1.024,0,0,1.024,-5.0469422,-9.8395302)" data-part="primary-tile"><path d="M 227.78906,0 213.98242,3.6992188 V 460.62109 H 241.4082 V 15.564453 Z" transform="matrix(0.26458333,0,0,0.26458333,210.28959,409.98108)" fill="#2D0002" data-part="primary-edge"></path><path d="m 210.28981,417.13553 v 113.86425 l 60.26885,2.60089 V 409.98109 h -53.11441 c -3.95129,0 -7.15444,3.20315 -7.15444,7.15444 z" fill="#701516" data-part="primary"></path></g><g transform="matrix(1.024,0,0,1.024,-5.0469422,-9.8395302)" data-part="lower-tile"><path d="m 486.38086,246.03906 -5.24805,4.99805 v 207.2207 l 5.24805,-0.93164 L 500,465.18945 V 261.60352 Z" transform="matrix(0.26458333,0,0,0.26458333,210.28959,409.98108)" fill="#67221F" data-part="lower-edge"></path><path d="m 278.70874,475.07917 v 64.8875 l 60.26883,-8.98455 v -55.90295 z" fill="#984640" data-part="lower"></path></g><path d="m 210.28959,533.88598 v 4.23545 c 9e-5,4.04619 3.28012,7.32651 7.32631,7.32631 h 117.12417 c 4.04619,2e-4 7.32621,-3.28012 7.32631,-7.32631 v -4.23545 z" fill="#231F20" data-part="base"></path><g transform="matrix(1.024,0,0,1.024,-5.0469422,-9.8395302)" data-part="upper-tile"><path d="m 459.33984,0 -25.33593,2.1074219 h 21.38281 c 14.93397,0 27.04101,12.1070061 27.04101,27.0410161 l 1.51727,183.649512 2.43542,2.38046 -1.84468,1.91057 15.46424,13.65284 L 500,42.603516 C 499.99913,8.8176763 474.27408,-6.8031496e-4 459.33984,0 Z" transform="matrix(0.26458333,0,0,0.26458333,210.28959,409.98108)" fill="#854A46" data-part="upper-side"></path><path d="m 331.82331,409.98109 h -53.11442 v 56.93261 h 60.26885 v -49.77817 c 0,-3.95129 -3.20315,-7.15444 -7.15443,-7.15444 z" fill="#B6706A" data-part="upper"></path><path d="m 278.7089,466.9137 h 60.26885 l 3.6035,4.11782 h -60.26932 z" fill="#733A36" data-part="upper-bottom"></path></g></g></svg>

data/lib/libtmux/workspace/cli.rb

@@ -76,7 +76,7 @@ module LibTmux
       rescue Interrupt, LibTmux::Cancelled => error
         report(error, kind: "interrupted", status: 130)
       rescue LibTmux::Error, SystemCallError, IOError => error
-        report(error, kind: "execution", status: @result ? 3 : 1)
+        report(error, kind: version_refusal?(error) ? "tmux_unsupported" : "execution", status: @result ? 3 : 1)
       end
 
       private
@@ -157,10 +157,21 @@ module LibTmux
         @out.puts(@json ? JSON.generate(value) : human)
       end
 
+      # A refusal before dispatch sent nothing, and its message says what to
+      # change, so it replaces the generic failure line.
+      def pre_dispatch_refusal?(error)
+        error.is_a?(LibTmux::UnsupportedFeatureError) && error.phase == :admission && error.delivery == :not_sent
+      end
+
+      # Only a refusal that names the tmux floor carries the machine code.
+      def version_refusal?(error)
+        LibTmux::Internal::TmuxVersion.refusal?(error)
+      end
+
       def report(error, kind:, status:)
         message = if kind == "arguments"
           @argument_message || "Invalid arguments; use --help for supported options."
-        elsif error.is_a?(Workspace::ConfigError) || error.is_a?(Workspace::ApplyError)
+        elsif error.is_a?(Workspace::ConfigError) || error.is_a?(Workspace::ApplyError) || pre_dispatch_refusal?(error)
           error.message
         else
           "Workspace #{kind} failed#{error ? " (#{error.class})" : ''}."

data/lib/libtmux/workspace/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libtmux-workspace
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha.1
+  version: 0.1.0.alpha.3
 platform: ruby
 authors:
 - libtmux contributors
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0.alpha.1
+        version: 0.1.0.alpha.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0.alpha.1
+        version: 0.1.0.alpha.3
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -60,6 +60,8 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- assets/logo.png
+- assets/logo.svg
 - exe/libtmux-workspace
 - lib/libtmux/workspace.rb
 - lib/libtmux/workspace/apply.rb
@@ -74,6 +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/
 rdoc_options: []
 require_paths:
 - lib