NAME
LibTmux::Workspace - Versioned JSON configuration and owned orchestration
SYNOPSIS
use LibTmux::Workspace;
my $workspace = LibTmux::Workspace->from_json($json_octets);
my $plan = $workspace->plan(existing => 'error');
my $report = $workspace->load(server => $server);
METHODS
new
new(config => $hashref) validates and copies a libtmux.workspace/v1 configuration. No I/O occurs. Sessions contain named windows with nonempty pane arrays. Each pane requires literal command arguments or an explicit shell_command. Environment values inherit from workspace, session, and window, with pane values taking precedence. All configuration errors throw Config.
from_json
Decode bounded UTF-8 JSON octets with core JSON::PP and call "new". Reject unsupported versions, unknown keys, invalid commands, and duplicate names. YAML is not part of this distribution.
plan
plan(existing => 'error'|'skip') returns a fresh data plan in input order. It performs no tmux I/O or mutations. A dry-run does not prove live availability or command success. Exports share no mutable arrays with the loader. No context-dependent return values are used.
load
load(server => $server, existing => 'error'|'skip') uses public LibTmux::Server operations. It checks all session-name conflicts before creation. error rejects any existing target with Conflict; skip leaves that entire session alone, so repeated application creates only absent sessions. A missing server permits explicit creation; other acquisition failures propagate.
Return one report containing created IDs, skipped names, and completed steps. On failure, rollback only sessions returned by successful creation, then throw Load with original cause and partial-effect report. An uncertain creation without a returned ID cannot be rolled back safely. Existing resources are never rollback targets. Layouts apply after splitting; working directories and environments reach every initial process. Completion means command acceptance and captured state, not application readiness.
COMMAND LINE
The packaged libtmux-workspace executable exposes validate, plan, and load. --dry-run selects planning without tmux I/O. See the installed executable's help for socket and repeat-application options.
DOCUMENTATION
Read the Perl documentation and workspace guide for complete configuration and CLI examples. The API reference documents validation, planning, loading, and failure reports. The CPAN distribution includes runnable consumer examples. The 0.x API can change between releases.