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.