ace-runtime 0.1.0

data/lib/ace/runtime/testing/scripted_runtime.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Ace
+  module Runtime
+    module Testing
+      # Fixture-local signals. Adapters translate these at their
+      # boundary into the contract error model:
+      #   FixtureUnavailable    -> RuntimeUnavailableError
+      #   FixtureStall          -> SendStalledError
+      #   FixtureTargetMissing  -> TargetNotFoundError
+      class FixtureError < StandardError; end
+      class FixtureUnavailable < FixtureError; end
+      class FixtureStall < FixtureError; end
+      class FixtureTargetMissing < FixtureError; end
+
+      # In-memory terminal runtime used by the shared adapter contract
+      # suite. It models the native capabilities adapters bind to
+      # (windows, panes, raw text writes, named keys, capture, agent
+      # state) and records every mutation op in order so the suite can
+      # assert delivery ordering and rejection-before-transport.
+      #
+      # Real adapter suites bind their adapter to this same fixture via
+      # a thin transport bridge; the reference implementation is
+      # test/support/fake_runtime_adapter.rb in the ace-runtime gem.
+      class ScriptedRuntime
+        attr_reader :calls, :context, :windows, :panes
+        attr_accessor :unavailable
+
+        def initialize
+          @calls = []
+          @context = {in_runtime: true, session: "main", window: nil, pane: nil}
+          @windows = {}
+          @panes = {}
+          @unavailable = false
+          @stall_next_send = false
+          @window_seq = 0
+          @pane_seq = 0
+        end
+
+        # --- test controls (never recorded) ---
+
+        def set_context(context)
+          @context = context
+        end
+
+        def set_output(pane_id, text)
+          fetch_pane!(pane_id)[:output] = text
+        end
+
+        def set_agent_state(pane_id, state)
+          fetch_pane!(pane_id)[:agent_state] = state
+        end
+
+        def exit_pane(pane_id)
+          fetch_pane!(pane_id)[:alive] = false
+        end
+
+        def stall_next_send!
+          @stall_next_send = true
+        end
+
+        # Silent setup mutator for pre-existing windows; adapter-driven
+        # creation goes through #create_window so it gets recorded.
+        def seed_window(name, root: "/", preset: nil)
+          @windows[name] = {
+            id: next_window_id, root: root, preset: preset, focused: false, panes: []
+          }
+          @windows[name][:id]
+        end
+
+        # Silent setup mutator for pre-existing panes.
+        def seed_pane(window_name, alive: true, keep_alive: true)
+          pane_id = next_pane_id
+          @panes[pane_id] = {
+            window: window_name, alive: alive, keep_alive: keep_alive,
+            output: "", agent_state: nil
+          }
+          @windows.fetch(window_name)[:panes] << pane_id
+          pane_id
+        end
+
+        # --- queries (never recorded) ---
+
+        def unavailable?
+          @unavailable
+        end
+
+        def window_exists?(name)
+          @windows.key?(name)
+        end
+
+        def window_info(name)
+          @windows[name]
+        end
+
+        def pane_exists?(pane_id)
+          @panes.key?(pane_id)
+        end
+
+        def alive?(pane_id)
+          fetch_pane!(pane_id)[:alive]
+        end
+
+        def agent_state(pane_id)
+          fetch_pane!(pane_id)[:agent_state]
+        end
+
+        # One-shot: a scripted stall means the submission was accepted
+        # but the target never started processing it.
+        def take_stall!
+          stall = @stall_next_send
+          @stall_next_send = false
+          stall
+        end
+
+        # --- native mutation ops (recorded in order) ---
+
+        def create_window(name:, root:, preset: nil)
+          guard_available!
+          raise FixtureTargetMissing, "window '#{name}' already exists" if window_exists?(name)
+
+          record(:create_window, name: name, root: root, preset: preset)
+          @windows[name] = {
+            id: next_window_id, root: root, preset: preset, focused: false, panes: []
+          }
+          @windows[name][:id]
+        end
+
+        def kill_window(name)
+          guard_available!
+          raise FixtureTargetMissing, "no window '#{name}'" unless window_exists?(name)
+
+          record(:kill_window, name: name)
+          @windows.delete(name)
+        end
+
+        def focus_window(name)
+          guard_available!
+          raise FixtureTargetMissing, "no window '#{name}'" unless window_exists?(name)
+
+          record(:focus_window, name: name)
+          @windows.each_value { |info| info[:focused] = false }
+          @windows[name][:focused] = true
+        end
+
+        def split_window(window_name)
+          guard_available!
+          info = @windows[window_name]
+          raise FixtureTargetMissing, "no window '#{window_name}'" unless info
+
+          record(:split_window, window: window_name)
+          pane_id = next_pane_id
+          @panes[pane_id] = {
+            window: window_name, alive: true, keep_alive: false,
+            output: "", agent_state: nil
+          }
+          info[:panes] << pane_id
+          pane_id
+        end
+
+        def set_keep_alive(pane_id, value)
+          guard_available!
+          fetch_pane!(pane_id)
+
+          record(:set_keep_alive, pane: pane_id, value: value)
+          @panes[pane_id][:keep_alive] = value
+        end
+
+        def write_text(pane_id, text)
+          guard_available!
+          pane = fetch_pane!(pane_id)
+
+          raise FixtureStall, "target accepted the submission but never started processing" if take_stall!
+
+          record(:write_text, pane: pane_id, text: text)
+          pane[:output] = text
+        end
+
+        def press_key(pane_id, key)
+          guard_available!
+          pane = fetch_pane!(pane_id)
+
+          raise FixtureStall, "target accepted the submission but never started processing" if take_stall!
+
+          record(:press_key, pane: pane_id, key: key)
+          pane[:alive] = false if key.to_s.match?(/\Aexit\z/i)
+        end
+
+        def capture_output(pane_id, lines:)
+          guard_available!
+          output = fetch_pane!(pane_id)[:output]
+          output.lines.last([lines, 1].max).join
+        end
+
+        private
+
+        def record(op, **args)
+          @calls << {op: op}.merge(args)
+        end
+
+        def guard_available!
+          raise FixtureUnavailable, "runtime backend is not reachable" if @unavailable
+        end
+
+        def fetch_pane!(pane_id)
+          pane = @panes[pane_id]
+          raise FixtureTargetMissing, "no pane '#{pane_id}'" unless pane
+
+          pane
+        end
+
+        def next_window_id
+          @window_seq += 1
+          "w#{@window_seq}"
+        end
+
+        def next_pane_id
+          @pane_seq += 1
+          "%#{@pane_seq}"
+        end
+      end
+    end
+  end
+end

data/lib/ace/runtime/testing.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Packaged adapter contract-test kit. Adapter packages require this in
+# their own test helpers:
+#
+#   require "ace/runtime/testing"
+#
+require_relative "testing/scripted_runtime"
+require_relative "testing/adapter_contract"

data/lib/ace/runtime/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ace
+  module Runtime
+    VERSION = "0.1.0"
+  end
+end

data/lib/ace/runtime.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "runtime/version"
+require "ace/support/config"
+
+# Define the error hierarchy before loading components (they raise these)
+require_relative "runtime/errors"
+
+require_relative "runtime/atoms/detector"
+require_relative "runtime/atoms/name_sanitizer"
+require_relative "runtime/atoms/send_contract"
+require_relative "runtime/registry"
+require_relative "runtime/molecules/runtime_selector"
+
+module Ace
+  module Runtime
+    class << self
+      # Register a duck-typed adapter factory under a runtime name.
+      # Adapter packages call this from their
+      # lib/ace/runtime/adapters/<name>.rb entrypoint.
+      def register(name, factory = nil, &block)
+        registry.register(name, factory, &block)
+      end
+
+      def registry
+        @registry ||= Registry.new
+      end
+
+      def reset_registry!
+        @registry = Registry.new
+      end
+
+      def available
+        registry.available
+      end
+
+      def registered?(name)
+        registry.registered?(name)
+      end
+
+      # Resolve a runtime name to a registered adapter. Unknown names
+      # fail closed with UnknownRuntimeError listing the available
+      # runtimes.
+      def resolve(name)
+        registry.resolve(name)
+      end
+
+      # Side-effect-free detection: :tmux, :herdr, or nil. tmux wins
+      # when both environments are live.
+      def detect(env: ENV)
+        Atoms::Detector.detect(env: env)
+      end
+
+      # Shared window/tab naming policy.
+      def sanitize_name(name, fallback: Atoms::NameSanitizer::FALLBACK)
+        Atoms::NameSanitizer.call(name, fallback: fallback)
+      end
+
+      def gem_root
+        @gem_root ||= ::Gem.loaded_specs["ace-runtime"]&.gem_dir ||
+          File.expand_path("../..", __dir__)
+      end
+
+      def debug?
+        ENV["ACE_DEBUG"] == "1" || ENV["DEBUG"] == "1"
+      end
+
+      # Configured runtime selection (key: `runtime`), merged through the
+      # ACE config cascade (project .ace/ > user ~/.ace/ > gem defaults).
+      def config
+        @config_mutex.synchronize do
+          @config ||= load_config
+        end
+      end
+
+      def reset_config!
+        @config_mutex.synchronize do
+          @config = nil
+        end
+      end
+
+      private
+
+      def load_config
+        resolver = Ace::Support::Config.create(
+          config_dir: ".ace",
+          defaults_dir: ".ace-defaults",
+          gem_path: gem_root
+        )
+
+        resolver.resolve_namespace("runtime").data
+      rescue StandardError => e
+        warn "ace-runtime: Could not load config: #{e.class} - #{e.message}" if debug?
+        {}
+      end
+    end
+
+    @config_mutex = Mutex.new
+  end
+end
+
+require_relative "runtime/cli"

metadata

@@ -0,0 +1,194 @@
+--- !ruby/object:Gem::Specification
+name: ace-runtime
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michal Czyz
+bindir: exe
+cert_chain: []
+date: 2026-09-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ace-support-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: ace-support-config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: ace-support-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.31'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.31'
+- !ruby/object:Gem::Dependency
+  name: ace-support-test-helpers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.88'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.88'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: 'One duck-typed intent API for terminal runtimes: adapter registry with
+  fail-closed resolution, side-effect-free detection, shared name sanitization, typed
+  errors, central send-matrix validation, the ace-runtime send callback CLI, and the
+  shared adapter contract-test suite.'
+email:
+- mc@cs3b.com
+executables:
+- ace-runtime
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ace-defaults/runtime/config.yml"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- docs/usage.md
+- exe/ace-runtime
+- lib/ace/runtime.rb
+- lib/ace/runtime/atoms/detector.rb
+- lib/ace/runtime/atoms/name_sanitizer.rb
+- lib/ace/runtime/atoms/send_contract.rb
+- lib/ace/runtime/cli.rb
+- lib/ace/runtime/cli/commands/send.rb
+- lib/ace/runtime/errors.rb
+- lib/ace/runtime/molecules/runtime_selector.rb
+- lib/ace/runtime/registry.rb
+- lib/ace/runtime/testing.rb
+- lib/ace/runtime/testing/adapter_contract.rb
+- lib/ace/runtime/testing/scripted_runtime.rb
+- lib/ace/runtime/version.rb
+homepage: https://github.com/cs3b/ace
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/cs3b/ace
+  source_code_uri: https://github.com/cs3b/ace/tree/main/ace-runtime/
+  changelog_uri: https://github.com/cs3b/ace/blob/main/ace-runtime/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Runtime-neutral terminal intent contract for ACE
+test_files: []