libtmux-workspace 0.1.0.alpha.1

data/lib/libtmux/workspace/cli.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "libtmux/workspace"
+require "optparse"
+
+module LibTmux
+  class Workspace
+    class CLI
+      def self.run(arguments, out: $stdout, err: $stderr, directory: Dir.pwd, environment: ENV)
+        new(arguments, out, err, directory, environment).run
+      end
+
+      def initialize(arguments, out, err, directory, environment)
+        @arguments, @out, @err, @directory, @environment = arguments.dup, out, err, directory, environment
+        @json = @arguments.include?("--json")
+        @options = {timeout: 5.0, environment: {}, expand_environment: false, compensate: false}
+      end
+      private_class_method :new
+
+      def run
+        return help if @arguments == ["--help"] || @arguments == ["-h"]
+        return version if @arguments == ["--version"]
+
+        command = @arguments.shift
+        raise ArgumentError unless %w[validate plan load].include?(command)
+
+        @arguments.take_while { |argument| argument != "--" }.each_with_index do |argument, index|
+          next unless argument == "--switch"
+          value = @arguments[index + 1]
+          raise OptionParser::MissingArgument, "--switch" if !value || value.start_with?("-")
+        end
+        parser.parse!(@arguments)
+        return help if @options[:help]
+        return version if @options[:version]
+
+        validate_arguments(command)
+        file = configuration_file
+        workspace = Workspace.load(file, expand_environment: @options.fetch(:expand_environment), environment: @options.fetch(:environment))
+        case command
+        when "validate"
+          emit({"valid" => true, "profile" => PROFILE, "version" => CONFIG_VERSION}, "Workspace configuration is valid.")
+        when "plan"
+          if @options[:live]
+            plan = with_server { |server| workspace.plan(snapshot: server.snapshot(timeout: @options.fetch(:timeout))) }
+            emit(plan.to_h, human_plan(plan))
+          else
+            plan = workspace.plan
+            emit(plan.to_h, human_plan(plan))
+          end
+        when "load"
+          with_server do |server|
+            @result = workspace.plan.apply(server: server, timeout: @options.fetch(:timeout), compensate: @options.fetch(:compensate))
+            if @options[:switch]
+              server.switch_client(client: @options.fetch(:switch), session: @result.created_refs.fetch("session"),
+                timeout: @options.fetch(:timeout))
+            end
+            if @options[:attach]
+              File.open("/dev/tty", "r+") do |terminal|
+                result = server.attach(session: @result.created_refs.fetch("session"), terminal: terminal, term: @environment.fetch("TERM"))
+                raise TransportError.new("attached terminal client failed", phase: :terminal) unless result.success?
+              end
+            end
+          end
+          emit(@result.to_h, "Workspace created; #{@result.completed_steps.length} steps completed. Shell commands were dispatched.")
+        end
+        0
+      rescue Workspace::ConfigError => error
+        report(error, kind: "configuration", status: 2)
+      rescue Workspace::ApplyError => error
+        @result = error.result
+        interrupted = ["Interrupt", "LibTmux::Cancelled"].include?(error.failure_class)
+        status = interrupted ? 130 : (@result.uncertain? || !@result.effects.empty? ? 3 : 1)
+        report(error, kind: interrupted ? "interrupted" : "application", status: status)
+      rescue OptionParser::ParseError, ArgumentError, KeyError
+        report(nil, kind: "arguments", status: @result ? 3 : 2)
+      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)
+      end
+
+      private
+
+      def parser
+        @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("--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 }
+          options.on("--attach", "Attach this CLI terminal after successful load") { @options[:attach] = true }
+          options.on("--switch CLIENT", "Switch the explicit current client after successful load") { |value| @options[:switch] = value }
+          options.on("--expand-environment", "Expand ${NAME} in paths/environment using explicit --env values") { @options[:expand_environment] = true }
+          options.on("--env NAME=VALUE", "Add an explicit expansion value; shell command text is unchanged") do |value|
+            name, contents = value.split("=", 2)
+            raise ArgumentError unless contents && /\A[A-Za-z_][A-Za-z0-9_]*\z/.match?(name)
+            raise ArgumentError if @options.fetch(:environment).key?(name)
+
+            @options.fetch(:environment)[name] = contents
+          end
+          options.on("-h", "--help", "Show supported commands and options") { @options[:help] = true }
+          options.on("--version", "Show the installed gem version") { @options[:version] = true }
+        end
+      end
+
+      def help
+        @out.puts(parser)
+        0
+      end
+
+      def version
+        @out.puts(VERSION)
+        0
+      end
+
+      def validate_arguments(command)
+        raise ArgumentError if @arguments.length > 1
+        raise ArgumentError unless @options.fetch(:timeout).finite? && @options.fetch(:timeout).positive?
+        raise ArgumentError if @options[:attach] && @options[:switch]
+        if @options[:switch]
+          client = @options.fetch(:switch)
+          raise ArgumentError unless client.bytesize.between?(1, 1024) && !client.b.include?("\0")
+        end
+        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 !live && @options[:socket]
+        if @options[:attach]
+          term = @environment["TERM"]
+          raise ArgumentError unless term.is_a?(String) && /\A[A-Za-z0-9][A-Za-z0-9_.+-]{0,127}\z/.match?(term)
+        end
+      end
+
+      def configuration_file
+        return File.expand_path(@arguments.first, @directory) if @arguments.first
+
+        candidates = %w[.tmuxp.yaml .tmuxp.yml .tmuxp.json].map { |name| File.join(@directory, name) }.select { |path| File.exist?(path) }
+        unless candidates.length == 1
+          @argument_message = "Provide a configuration file; discovery requires exactly one .tmuxp.yaml, .tmuxp.yml or .tmuxp.json."
+          raise ArgumentError
+        end
+        candidates.first
+      end
+
+      def with_server(&block)
+        LibTmux::Server.open(socket_path: File.expand_path(@options.fetch(:socket), @directory), &block)
+      end
+
+      def human_plan(plan)
+        (["#{plan.mode}: #{plan.steps.length} ordered steps"] +
+          plan.steps.map { |step| "#{step.id}. #{step.operation} #{step.target} (#{step.effect})" }).join("\n")
+      end
+
+      def emit(value, human)
+        @out.puts(@json ? JSON.generate(value) : human)
+      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)
+          error.message
+        else
+          "Workspace #{kind} failed#{error ? " (#{error.class})" : ''}."
+        end
+        value = {"error" => {"kind" => kind, "message" => message, "exit_status" => status}}
+        if error.is_a?(LibTmux::Error)
+          value.fetch("error")["delivery"] = error.delivery.to_s
+          value.fetch("error")["phase"] = error.phase&.to_s
+        end
+        value.fetch("error")["failure_class"] = error.failure_class if error.is_a?(Workspace::ApplyError)
+        value["result"] = @result.to_h if @result
+        if @json
+          @out.puts(JSON.generate(value))
+        else
+          @err.puts(message)
+          @err.puts(JSON.generate(@result.to_h)) if @result
+        end
+        status
+      end
+    end
+  end
+end

data/lib/libtmux/workspace/document.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module LibTmux
+  class Workspace
+    # JSON-compatible scalar rules avoid YAML object loading and implicit dates.
+    class Document
+      class YAMLHandler < Psych::Handler
+        attr_reader :result
+
+        def initialize(limits)
+          @limits, @stack, @nodes, @documents = limits, [], 0, 0
+        end
+
+        def start_document(*)
+          @documents += 1
+          fail_input("exactly one YAML document") unless @documents == 1
+        end
+
+        def start_mapping(anchor, tag, *)
+          container({}, anchor, tag)
+        end
+
+        def start_sequence(anchor, tag, *)
+          container([], anchor, tag)
+        end
+
+        def end_mapping
+          frame = @stack.pop
+          fail_input("complete YAML mapping") unless frame[:key].nil?
+        end
+
+        def end_sequence
+          @stack.pop
+        end
+
+        def scalar(value, anchor, tag, plain, quoted, *)
+          fail_input("YAML without tags or anchors") if anchor || tag
+          visit
+          fail_input("bounded UTF-8 scalar") if value.bytesize > @limits.fetch(:max_string_bytes)
+          decoded = if !plain || quoted
+            value
+          else
+            case value
+            when "true" then true
+            when "false" then false
+            when "null", "~", "" then nil
+            when /\A-?(?:0|[1-9][0-9]*)\z/
+              fail_input("bounded integer token") if value.bytesize > 20
+              Integer(value, 10)
+            when /\A-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?\z/
+              fail_input("bounded scalar token") if value.bytesize > 32
+              Float(value)
+            else value
+            end
+          end
+          append(decoded)
+        end
+
+        def alias(*)
+          fail_input("YAML without aliases")
+        end
+
+        private
+
+        def container(value, anchor, tag)
+          fail_input("YAML without tags or anchors") if anchor || tag
+          visit
+          fail_input("bounded document depth") if @stack.length >= @limits.fetch(:max_depth)
+          append(value)
+          @stack << {value: value, key: nil}
+        end
+
+        def visit
+          @nodes += 1
+          fail_input("bounded document node count") if @nodes > @limits.fetch(:max_nodes)
+        end
+
+        def append(value)
+          if @stack.empty?
+            @result = value
+          elsif @stack.last[:value].is_a?(Array)
+            @stack.last[:value] << value
+          else
+            frame = @stack.last
+            if frame[:key].nil?
+              fail_input("string mapping keys") unless value.is_a?(String)
+              fail_input("unique mapping keys") if frame[:value].key?(value)
+              frame[:key] = value
+            else
+              frame[:value][frame[:key]] = value
+              frame[:key] = nil
+            end
+          end
+        end
+
+        def fail_input(expected)
+          raise ConfigError.new("invalid workspace document", path: "$", expected: expected)
+        end
+      end
+      private_constant :YAMLHandler
+
+      def initialize(limits)
+        @limits = limits
+      end
+
+      def parse(bytes, format)
+        unless bytes.is_a?(String) && bytes.bytesize <= @limits.fetch(:max_bytes)
+          invalid("bounded document bytes")
+        end
+        text = bytes.dup.force_encoding(Encoding::UTF_8)
+        invalid("UTF-8 document") unless text.valid_encoding?
+        value = case format
+        when :json
+          preflight_json(text)
+          JSON.parse(text, max_nesting: @limits.fetch(:max_depth), allow_nan: false, allow_duplicate_key: false)
+        when :yaml
+          handler = YAMLHandler.new(@limits)
+          Psych::Parser.new(handler).parse(text)
+          handler.result
+        else
+          raise ArgumentError, "workspace format must be :json or :yaml"
+        end
+        validate_tree(value)
+        value
+      rescue JSON::ParserError, JSON::NestingError, Psych::Exception, EncodingError
+        raise ConfigError.new("invalid workspace syntax", path: "$", expected: "data-only bounded JSON or YAML"), cause: nil
+      end
+
+      def validate_tree(value)
+        @nodes = 0
+        validate(value)
+      end
+
+      private
+
+      # Bound allocation before JSON creates its object tree or large integers.
+      def preflight_json(text)
+        index, nodes, depth = 0, 0, 0
+        while index < text.bytesize
+          byte = text.getbyte(index)
+          case byte
+          when 34
+            nodes += 1
+            index += 1
+            while index < text.bytesize
+              current = text.getbyte(index)
+              index += 1
+              break if current == 34
+              index += 1 if current == 92
+            end
+            index -= 1
+          when 123, 91
+            nodes += 1
+            depth += 1
+            invalid("bounded document depth") if depth > @limits.fetch(:max_depth)
+          when 125, 93 then depth -= 1
+          when 32, 9, 10, 13, 44, 58 then nil
+          else
+            nodes += 1
+            first = index
+            index += 1 while index < text.bytesize && ![32, 9, 10, 13, 44, 93, 125].include?(text.getbyte(index))
+            invalid("bounded scalar token") if index - first > 32
+            index -= 1
+          end
+          invalid("bounded document node count") if nodes > @limits.fetch(:max_nodes)
+          index += 1
+        end
+      end
+
+      def validate(value, depth = 0)
+        @nodes += 1
+        invalid("bounded document node count") if @nodes > @limits.fetch(:max_nodes)
+        invalid("bounded document depth") if depth > @limits.fetch(:max_depth)
+        case value
+        when Hash
+          value.each do |key, child|
+            invalid("string mapping keys") unless key.is_a?(String)
+            validate(key, depth + 1)
+            validate(child, depth + 1)
+          end
+        when Array then value.each { |child| validate(child, depth + 1) }
+        when String
+          invalid("bounded UTF-8 scalar") if value.bytesize > @limits.fetch(:max_string_bytes) || !value.valid_encoding?
+        when Integer, Float, true, false, nil then nil
+        else invalid("plain data values")
+        end
+      end
+
+      def invalid(expected)
+        raise ConfigError.new("invalid workspace document", path: "$", expected: expected)
+      end
+    end
+    private_constant :Document
+  end
+end

data/lib/libtmux/workspace/normalizer.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+module LibTmux
+  class Workspace
+    class Normalizer
+      COMMON = %w[start_directory environment shell_command shell_command_before].freeze
+      ROOT = (COMMON + %w[profile version session_name windows options window_options]).freeze
+      WINDOW = (COMMON + %w[window_name window_index panes focus layout options]).freeze
+      PANE = (COMMON + %w[focus split size]).freeze
+      LAYOUTS = %w[even-horizontal even-vertical main-horizontal main-vertical tiled].freeze
+      SESSION_OPTIONS = {"base-index" => :index, "status" => :boolean, "mouse" => :boolean,
+        "renumber-windows" => :boolean, "history-limit" => :index,
+        "status-interval" => :index, "status-position" => %w[top bottom],
+        "status-justify" => %w[left centre right absolute-centre],
+        "default-terminal" => :unsupported}.freeze
+      WINDOW_OPTIONS = {"automatic-rename" => :boolean, "allow-rename" => :boolean,
+        "remain-on-exit" => :boolean, "synchronize-panes" => :boolean,
+        "aggressive-resize" => :boolean, "pane-base-index" => :pane_index,
+        "main-pane-width" => :index, "main-pane-height" => :index,
+        "window-status-format" => :text, "window-status-current-format" => :text,
+        "pane-border-status" => %w[off top bottom]}.freeze
+      private_constant :COMMON, :ROOT, :WINDOW, :PANE, :LAYOUTS, :SESSION_OPTIONS, :WINDOW_OPTIONS
+
+      def initialize(base, expand, environment, limits)
+        @limits, @expand, @expanded_bytes = limits, expand, 0
+        @normalized_bytes, @normalized_nodes = 0, 0
+        unless base.is_a?(String) && !base.empty? && !base.include?("\0")
+          raise ArgumentError, "workspace base_directory must be a nonempty String without NUL"
+        end
+        unless expand.equal?(true) || expand.equal?(false)
+          raise ArgumentError, "expand_environment must be Boolean"
+        end
+        @base = File.expand_path(base)
+        @environment = environment_map(environment, "$environment", expand: false)
+        @pane_count = 0
+      end
+
+      def normalize(input)
+        object(input, ROOT, "$")
+        if input.key?("profile") || input.key?("version")
+          unless input["profile"] == PROFILE && input["version"].is_a?(Integer) && input["version"] == CONFIG_VERSION
+            fail_at("$", "#{PROFILE} version #{CONFIG_VERSION}, with both envelope fields")
+          end
+        end
+        name = name(input.fetch("session_name") { fail_at("$.session_name", "session name") }, "$.session_name")
+        root = common(input, {"start_directory" => @base, "environment" => {},
+          "shell_command_before" => [], "shell_command" => []}, "$")
+        root_options = options(input.fetch("options", {}), SESSION_OPTIONS, "$.options")
+        inherited_options = options(input.fetch("window_options", {}), WINDOW_OPTIONS, "$.window_options")
+        windows = input["windows"]
+        unless windows.is_a?(Array) && windows.length.between?(1, @limits.fetch(:max_windows))
+          fail_at("$.windows", "nonempty bounded window array")
+        end
+        indexes, explicit = {}, {}
+        windows.each_with_index do |window, position|
+          path = "$.windows[#{position}]"
+          object(window, WINDOW, path)
+          next unless window.key?("window_index")
+
+          value = index(window["window_index"], "#{path}.window_index")
+          fail_at("#{path}.window_index", "unique window index") if explicit.key?(value)
+          explicit[value] = true
+        end
+        next_index = root_options.fetch("base-index", 0)
+        normalized = windows.each_with_index.map do |window, position|
+          path = "$.windows[#{position}]"
+          if window.key?("window_index")
+            assigned = window.fetch("window_index")
+          else
+            next_index += 1 while explicit.key?(next_index) || indexes.key?(next_index)
+            assigned = index(next_index, "#{path}.window_index")
+            next_index += 1
+          end
+          indexes[assigned] = true
+          normalize_window(window, root, inherited_options, assigned, path)
+        end
+        choose_focus(normalized, "$.windows")
+        # Canonical exports carry commands only at leaves. Reloading must not
+        # prepend already inherited commands a second time.
+        root["shell_command_before"] = []
+        root["shell_command"] = []
+        normalized.each do |window|
+          window["shell_command_before"] = []
+          window["shell_command"] = []
+        end
+        freeze_tree(root.merge("profile" => PROFILE, "version" => CONFIG_VERSION,
+          "session_name" => name, "options" => root_options,
+          "window_options" => inherited_options, "windows" => normalized))
+      end
+
+      private
+
+      def normalize_window(input, parent, inherited_options, assigned, path)
+        value = common(input, parent, path)
+        value["window_name"] = name(input.fetch("window_name") { fail_at("#{path}.window_name", "window name") }, "#{path}.window_name")
+        value["window_index"] = assigned
+        value["focus"] = boolean(input.fetch("focus", false), "#{path}.focus")
+        value["options"] = inherited_options.merge(options(input.fetch("options", {}), WINDOW_OPTIONS, "#{path}.options"))
+        layout = input["layout"]
+        fail_at("#{path}.layout", "supported named layout") if input.key?("layout") && !LAYOUTS.include?(layout)
+        value["layout"] = layout if layout
+        panes = input["panes"]
+        fail_at("#{path}.panes", "nonempty pane array") unless panes.is_a?(Array) && !panes.empty?
+        @pane_count += panes.length
+        fail_at("#{path}.panes", "bounded total pane count") if @pane_count > @limits.fetch(:max_panes)
+        value["panes"] = panes.each_with_index.map do |pane, position|
+          child_path = "#{path}.panes[#{position}]"
+          pane = {"shell_command" => pane} if pane.is_a?(String)
+          object(pane, PANE, child_path)
+          child = common(pane, value, child_path)
+          child["focus"] = boolean(pane.fetch("focus", false), "#{child_path}.focus")
+          if position.zero? && (pane.key?("split") || pane.key?("size"))
+            fail_at(child_path, "split geometry only for subsequent panes")
+          end
+          direction = pane.fetch("split", "vertical")
+          fail_at("#{child_path}.split", "horizontal or vertical") unless %w[horizontal vertical].include?(direction)
+          child["split"] = direction unless position.zero?
+          if pane.key?("size")
+            size = pane["size"]
+            valid = (size.is_a?(Integer) && size.between?(1, (1 << 31) - 1)) ||
+              (size.is_a?(String) && /\A(?:[1-9]|[1-9][0-9])%\z/.match?(size))
+            fail_at("#{child_path}.size", "positive cell count or percentage between 1% and 99%") unless valid
+            fail_at("#{child_path}.size", "split size without a final named layout") if layout
+            child["size"] = size
+          end
+          child
+        end
+        choose_focus(value["panes"], "#{path}.panes")
+        value
+      end
+
+      def common(input, parent, path)
+        directory = if input.key?("start_directory")
+          value = expand(text(input["start_directory"], "#{path}.start_directory", empty: false), "#{path}.start_directory")
+          # Prefixing relative paths avoids File.expand_path's ambient ~ expansion.
+          File.expand_path(value.start_with?(File::SEPARATOR) ? value : File.join(@base, value))
+        else parent.fetch("start_directory")
+        end
+        inherited_environment = parent.fetch("environment").merge(environment_map(input.fetch("environment", {}), "#{path}.environment"))
+        before = parent.fetch("shell_command_before") + commands(input.fetch("shell_command_before", []), "#{path}.shell_command_before")
+        command = input.key?("shell_command") ? commands(input["shell_command"], "#{path}.shell_command") : parent.fetch("shell_command")
+        result = {"start_directory" => directory, "environment" => inherited_environment,
+          "shell_command_before" => before, "shell_command" => command}
+        account(result, path)
+        result
+      end
+
+      def object(value, allowed, path)
+        fail_at(path, "configuration object") unless value.is_a?(Hash)
+        unknown = value.keys - allowed
+        unless unknown.empty?
+          known_unsupported = %w[before_script plugins hooks erb callback callbacks].find { |key| unknown.include?(key) }
+          failure_path = known_unsupported ? "#{path}.#{known_unsupported}" : path
+          fail_at(failure_path, "supported data-only fields; move callbacks or hooks into explicit application code")
+        end
+      end
+
+      def environment_map(value, path, expand: @expand)
+        fail_at(path, "environment object") unless value.is_a?(Hash)
+        fail_at(path, "bounded environment map") if value.length > @limits.fetch(:max_nodes)
+        bytes = 0
+        value.to_h do |key, item|
+          unless key.is_a?(String) && /\A[A-Za-z_][A-Za-z0-9_]*\z/.match?(key)
+            fail_at(path, "portable environment variable names")
+          end
+          item = text(item, path)
+          bytes += key.bytesize + item.bytesize
+          fail_at(path, "bounded environment bytes") if bytes > @limits.fetch(:max_bytes)
+          [key.dup, expand ? self.expand(item, path) : item]
+        end
+      end
+
+      def expand(value, path)
+        return value unless @expand
+
+        output, offset = +"", 0
+        append = lambda do |chunk|
+          fail_at(path, "bounded expanded value") if output.bytesize + chunk.bytesize > @limits.fetch(:max_string_bytes)
+          output << chunk
+        end
+        value.scan(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/) do
+          match = Regexp.last_match
+          append.call(value[offset...match.begin(0)])
+          replacement = @environment.fetch(match[1]) { fail_at(path, "explicit substitution value for every variable") }
+          append.call(replacement)
+          offset = match.end(0)
+        end
+        append.call(value[offset..])
+        @expanded_bytes += output.bytesize
+        if output.bytesize > @limits.fetch(:max_string_bytes) || @expanded_bytes > @limits.fetch(:max_bytes)
+          fail_at(path, "bounded expanded values")
+        end
+        output
+      end
+
+      def account(value, path)
+        @normalized_nodes += 1
+        fail_at(path, "bounded normalized node count") if @normalized_nodes > @limits.fetch(:max_nodes)
+        case value
+        when Hash then value.each { |key, child| account(key, path); account(child, path) }
+        when Array then value.each { |child| account(child, path) }
+        when String
+          @normalized_bytes += value.bytesize
+          fail_at(path, "bounded normalized bytes") if @normalized_bytes > @limits.fetch(:max_bytes)
+        end
+      end
+
+      def text(value, path, empty: true)
+        fail_at(path, "UTF-8 text") unless value.is_a?(String)
+        result = value.dup.force_encoding(Encoding::UTF_8)
+        unless result.valid_encoding? && !result.include?("\0") && (empty || !result.empty?) && result.bytesize <= @limits.fetch(:max_string_bytes)
+          fail_at(path, "bounded UTF-8 text without NUL")
+        end
+        result
+      end
+
+      def name(value, path)
+        result = text(value, path, empty: false)
+        unless !result.match?(/[\x00-\x1f\x7f:.]/) && !result.strip.empty?
+          fail_at(path, "name without controls, colon or period")
+        end
+        result
+      end
+
+      def commands(value, path)
+        value = [value] if value.is_a?(String)
+        fail_at(path, "shell command string or ordered string array") unless value.is_a?(Array)
+        fail_at(path, "bounded command array") if value.length > @limits.fetch(:max_nodes)
+        value.map { |command| text(command, path) }
+      end
+
+      def boolean(value, path)
+        fail_at(path, "Boolean") unless value.equal?(true) || value.equal?(false)
+        value
+      end
+
+      def index(value, path, maximum = (1 << 31) - 1)
+        fail_at(path, "integer index from zero through #{maximum}") unless value.is_a?(Integer) && value.between?(0, maximum)
+        value
+      end
+
+      def options(value, catalog, path)
+        fail_at(path, "typed option object") unless value.is_a?(Hash)
+        value.to_h do |key, item|
+          type = catalog[key]
+          fail_at(path, "supported options for this scope") unless type && type != :unsupported
+          converted = case type
+          when :boolean then boolean(item, "#{path}.#{key}")
+          when :index then index(item, "#{path}.#{key}")
+          when :pane_index then index(item, "#{path}.#{key}", 65535)
+          when :text then text(item, "#{path}.#{key}")
+          else
+            fail_at("#{path}.#{key}", "declared option choice") unless type.include?(item)
+            item.dup
+          end
+          [key.dup, converted]
+        end
+      end
+
+      def choose_focus(values, path)
+        focused = values.count { |item| item.fetch("focus") }
+        fail_at(path, "at most one focused item") if focused > 1
+        values.first["focus"] = true if focused.zero?
+      end
+
+      def freeze_tree(value)
+        case value
+        when Hash then value.to_h { |key, item| [key.dup.freeze, freeze_tree(item)] }.freeze
+        when Array then value.map { |item| freeze_tree(item) }.freeze
+        when String then value.dup.freeze
+        else value
+        end
+      end
+
+      def fail_at(path, expected)
+        raise ConfigError.new(path: path, expected: expected)
+      end
+    end
+    private_constant :Normalizer
+  end
+end