igniter 0.5.0 → 0.5.1

data/packages/igniter-app/lib/igniter/app/stack.rb

@@ -0,0 +1,1726 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "irb"
+require "optparse"
+require "securerandom"
+require "shellwords"
+require "stringio"
+require "time"
+require "yaml"
+require "igniter/ignite"
+
+module Igniter
+  # Root coordinator for mounted multi-app stacks.
+  #
+  # A stack owns:
+  # - shared load paths for repo-level support code
+  # - a registry of named apps under apps/<name>
+  # - a single mounted runtime rooted in stack.rb + stack.yml
+  # - optional local node profiles for multi-instance boot
+  #
+  # Apps are pluggable mounted packages. Nodes are launch profiles of the same
+  # stack. The stack itself owns the server/runtime boundary.
+  class Stack
+    UNDEFINED_IGNITION_STORE = Object.new
+    UNDEFINED_CREDENTIAL_STORE = Object.new
+    AppDefinition = Struct.new(:name, :path, :klass, :root, :access_to, keyword_init: true)
+    ConsoleContext = Struct.new(
+      :stack_class,
+      :root_app_name,
+      :root_app_class,
+      :app_name,
+      :app_class,
+      :node_name,
+      :node_profile,
+      :deployment,
+      :runtime,
+      :mounts,
+      :stack_settings,
+      :mesh,
+      keyword_init: true
+    )
+    SERVICE_MOUNT_METHODS = %w[GET POST PUT PATCH DELETE OPTIONS HEAD].freeze
+
+    class << self
+      def root_dir(path = nil)
+        return @root_dir unless path
+
+        @root_dir = File.expand_path(path)
+        reset_stack_state!
+      end
+
+      def shared_lib_path(path)
+        @shared_lib_paths << path
+      end
+
+      def stack_file(path = nil)
+        return @stack_yml_path unless path
+
+        @stack_yml_path = path
+        reset_stack_state!
+      end
+
+      def config_file(path = nil)
+        stack_file(path)
+      end
+
+      def environment(name = nil)
+        return resolved_environment unless name
+
+        @environment_name = name.to_s
+        reset_stack_state!
+      end
+
+      def environment_file(path = nil)
+        return @environment_yml_path unless path
+
+        @environment_yml_path = path
+        reset_stack_state!
+      end
+
+      def compose_file(path = nil)
+        return @compose_yml_path unless path
+
+        @compose_yml_path = path
+      end
+
+      def ignition_store(store = UNDEFINED_IGNITION_STORE)
+        return (@ignition_store ||= default_ignition_store) if store.equal?(UNDEFINED_IGNITION_STORE)
+
+        @ignition_store = store
+        reload_ignition_trail!
+      end
+
+      def ignition_log(path, retain_events: nil, archive: nil)
+        ignition_store(
+          Igniter::Ignite::Stores::FileStore.new(
+            path: resolve_path(path),
+            max_events: retain_events,
+            archive_path: archive ? resolve_path(archive) : nil
+          )
+        )
+      end
+
+      def credential_store(store = UNDEFINED_CREDENTIAL_STORE)
+        return (@credential_store ||= default_credential_store) if store.equal?(UNDEFINED_CREDENTIAL_STORE)
+
+        @credential_store = store
+        reload_credential_trail!
+      end
+
+      def credential_log(path, retain_events: nil, archive: nil)
+        credential_store(
+          Igniter::App::Credentials::Stores::FileStore.new(
+            path: resolve_path(path),
+            max_events: retain_events,
+            archive_path: archive ? resolve_path(archive) : nil
+          )
+        )
+      end
+
+      def procfile_dev_file(path = nil)
+        return @procfile_dev_path unless path
+
+        @procfile_dev_path = path
+      end
+
+      def app(name = nil, path: nil, klass: nil, default: false, access_to: [])
+        if path || klass
+          raise ArgumentError, "stack app registration requires both path: and klass:" unless path && klass
+
+          definition = AppDefinition.new(
+            name: name.to_sym,
+            path: path.to_s,
+            klass: klass,
+            root: default,
+            access_to: Array(access_to).map(&:to_sym)
+          )
+
+          @apps[definition.name] = definition
+          definition.klass.bind_stack_context(
+            stack_class: self,
+            app_name: definition.name,
+            access_to: definition.access_to
+          ) if definition.klass.respond_to?(:bind_stack_context)
+          @root_app = definition.name if default
+          return definition.klass
+        end
+
+        app_class(name)
+      end
+
+      def mount(name, at:)
+        app_definition(name)
+        @mounts[normalize_app_name(name)] = normalize_mount_path(at)
+      end
+
+      def mounts
+        @mounts.each_with_object({}) do |(name, path), result|
+          result[name] = path.dup
+        end
+      end
+
+      def app_names
+        @apps.keys
+      end
+
+      def interface(name)
+        @apps.each_value do |definition|
+          callable = definition.klass.exposed_interfaces[name.to_sym]
+          return callable if callable
+        end
+        raise KeyError, "No registered app exposes interface #{name.inspect}"
+      end
+
+      def interfaces
+        @apps.each_value.each_with_object({}) do |definition, hash|
+          definition.klass.exposed_interfaces.each { |iface_name, callable| hash[iface_name] = callable }
+        end
+      end
+
+      def root_app
+        normalize_optional_name(stack_settings.dig("stack", "root_app")) ||
+          @root_app ||
+          @apps.keys.first
+      end
+
+      def default_node
+        return root_app unless nodes_defined?
+
+        configured = normalize_optional_name(stack_settings.dig("stack", "default_node"))
+        return configured if configured && node_names.include?(configured)
+
+        fallback = normalize_optional_name(ENV["IGNITER_NODE"])
+        return fallback if fallback && node_names.include?(fallback)
+
+        node_names.first
+      end
+
+      def app_definition(name = nil)
+        requested = normalize_app_name(name || root_app)
+        @apps.fetch(requested) do
+          available = @apps.keys.map(&:inspect).join(", ")
+          raise ArgumentError, "Unknown stack app #{requested.inspect} (available: #{available})"
+        end
+      end
+
+      def app_class(name = nil)
+        setup_load_paths!
+        app_definition(resolve_app_name(name)).klass
+      end
+
+      def start(name = nil, environment: nil)
+        self.environment(environment) if environment
+        return start_node(default_node) if use_stack_runtime_by_default?(name)
+
+        app_class(resolve_app_name(name)).start
+      end
+
+      def rack_app(name = nil, environment: nil)
+        self.environment(environment) if environment
+        return rack_node(default_node) if use_stack_runtime_by_default?(name)
+
+        app_class(resolve_app_name(name)).rack_app
+      end
+
+      def node_names
+        stack_settings.fetch("nodes", {}).keys.map { |node_name| normalize_app_name(node_name) }
+      end
+
+      def node_profile(name = nil)
+        node_name = normalize_app_name(name || default_node)
+        stack_settings.fetch("nodes", {}).fetch(node_name.to_s) do
+          available = node_names.map(&:inspect).join(", ")
+          raise ArgumentError, "Unknown stack node #{node_name.inspect} (available: #{available})"
+        end
+      end
+
+      def start_node(name = nil, environment: nil)
+        self.environment(environment) if environment
+
+        runtime = build_stack_runtime(nodes_defined? ? resolve_node_name(name) : nil)
+        schedulers = start_stack_schedulers(runtime)
+        at_exit { stop_stack_schedulers(schedulers) }
+        runtime.fetch(:root_app_class).host_adapter.start(config: runtime.fetch(:root_config))
+      end
+
+      def rack_node(name = nil, environment: nil)
+        self.environment(environment) if environment
+
+        runtime = build_stack_runtime(nodes_defined? ? resolve_node_name(name) : nil)
+        start_stack_schedulers(runtime)
+        runtime.fetch(:root_app_class).host_adapter.rack_app(config: runtime.fetch(:root_config))
+      end
+
+      def console_context(name = nil, node: nil, environment: nil)
+        self.environment(environment) if environment
+
+        selected_app_name = resolve_app_name(name)
+        selected_node_name = nodes_defined? ? resolve_node_name(node) : nil
+        selected_runtime = build_stack_runtime(selected_node_name)
+
+        ConsoleContext.new(
+          stack_class: self,
+          root_app_name: root_app,
+          root_app_class: app_class(root_app),
+          app_name: selected_app_name,
+          app_class: app_class(selected_app_name),
+          node_name: selected_node_name,
+          node_profile: selected_node_name ? node_profile(selected_node_name) : nil,
+          deployment: deployment_snapshot,
+          runtime: selected_runtime,
+          mounts: mounts,
+          stack_settings: stack_settings,
+          mesh: defined?(Igniter::Cluster::Mesh) ? Igniter::Cluster::Mesh : nil
+        )
+      end
+
+      def console_binding(name = nil, node: nil, environment: nil)
+        context = console_context(name, node: node, environment: environment)
+        console_locals_binding(context)
+      end
+
+      def start_console(name = nil, node: nil, environment: nil, output: $stdout, evaluate: nil)
+        context = console_context(name, node: node, environment: environment)
+        output.puts(console_banner(context))
+        bind = console_locals_binding(context)
+        return evaluate_console(bind, evaluate, output) if evaluate
+
+        bind.irb
+      end
+
+      def start_cli(argv = ARGV)
+        options = parse_cli_options(argv.dup)
+        target = options.delete(:target)
+
+        if options[:print_procfile_dev]
+          self.environment(options[:environment]) if options[:environment]
+          puts procfile_dev
+          return
+        end
+
+        if options[:write_procfile_dev]
+          self.environment(options[:environment]) if options[:environment]
+          write_procfile_dev(options[:write_procfile_dev] == true ? nil : options[:write_procfile_dev])
+          return
+        end
+
+        if options[:dev]
+          start_dev(environment: options[:environment])
+          return
+        end
+
+        if options[:print_compose]
+          self.environment(options[:environment]) if options[:environment]
+          puts compose_yaml
+          return
+        end
+
+        if options[:write_compose]
+          self.environment(options[:environment]) if options[:environment]
+          write_compose(options[:write_compose] == true ? nil : options[:write_compose])
+          return
+        end
+
+        if options[:console]
+          start_console(
+            target,
+            node: options[:node],
+            environment: options[:environment],
+            evaluate: options[:evaluate]
+          )
+          return
+        end
+
+        if options[:node]
+          start_node(options[:node], environment: options[:environment])
+        else
+          start(target, environment: options[:environment])
+        end
+      end
+
+      def stack_settings(reload: false)
+        @stack_settings = nil if reload
+        @ignition_plan = nil if reload
+        @stack_settings ||= deep_merge(
+          load_yaml(resolve_path(@stack_yml_path)),
+          environment_settings
+        )
+      end
+
+      def ignite_settings
+        stack_settings.fetch("ignite", {})
+      end
+
+      def ignition_plan(reload: false)
+        @ignition_plan = nil if reload
+        @ignition_plan ||= build_ignition_plan
+      end
+
+      def ignite(plan: ignition_plan, approved: false, timeout: 5, mesh: nil, request_admission: false, approve_pending_admission: false, bootstrap_remote: false, bootstrap_timeout: 30, session_factory: nil, bootstrapper_factory: nil, await_join: nil, join_timeout: 5, join_poll_interval: 0.1, persist: true)
+        agent = Igniter::Ignite::IgnitionAgent.start
+        report = agent.call(
+          :execute,
+          {
+            plan: plan,
+            runtime_units: runtime_units_snapshot,
+            approved: approved,
+            mesh: mesh,
+            request_admission: request_admission,
+            approve_pending_admission: approve_pending_admission,
+            bootstrap_remote: bootstrap_remote,
+            bootstrap_timeout: bootstrap_timeout,
+            session_factory: session_factory,
+            bootstrapper_factory: bootstrapper_factory,
+            root_dir: @root_dir
+          },
+          timeout: timeout
+        )
+        unless should_await_ignite_join?(report, mesh: mesh, await_join: await_join, bootstrap_remote: bootstrap_remote)
+          persist_ignition_report!(report, source: :ignite) if persist
+          return report
+        end
+
+        report = await_ignite_join(
+          report: report,
+          mesh: mesh,
+          timeout: join_timeout,
+          poll_interval: join_poll_interval
+        )
+        persist_ignition_report!(report, source: :ignite) if persist
+        report
+      ensure
+        agent&.stop(timeout: 1)
+      end
+
+      def ignition_report(**options)
+        ignite(**options, persist: false)
+      end
+
+      def confirm_ignite_join(report:, target_id:, url:, mesh: nil, metadata: {}, timeout: 5, persist: true)
+        agent = Igniter::Ignite::IgnitionAgent.start
+        updated = agent.call(
+          :confirm_join,
+          {
+            report: report,
+            target_id: target_id,
+            url: url,
+            mesh: mesh,
+            metadata: metadata
+          },
+          timeout: timeout
+        )
+        persist_ignition_report!(updated, source: :confirm_join) if persist
+        updated
+      ensure
+        agent&.stop(timeout: 1)
+      end
+
+      def reconcile_ignite(report:, mesh:, timeout: 5, persist: true)
+        agent = Igniter::Ignite::IgnitionAgent.start
+        updated = agent.call(
+          :reconcile,
+          {
+            report: report,
+            mesh: mesh
+          },
+          timeout: timeout
+        )
+        persist_ignition_report!(updated, source: :reconcile) if persist
+        updated
+      ensure
+        agent&.stop(timeout: 1)
+      end
+
+      def detach_ignite_target(report:, target_id:, mesh: nil, metadata: {}, timeout: 5, persist: true, session_factory: nil, decommission_timeout: 30)
+        agent = Igniter::Ignite::IgnitionAgent.start
+        updated = agent.call(
+          :detach,
+          {
+            report: report,
+            target_id: target_id,
+            mesh: mesh,
+            metadata: metadata,
+            root_dir: @root_dir,
+            session_factory: session_factory,
+            decommission_timeout: decommission_timeout
+          },
+          timeout: timeout
+        )
+        persist_ignition_report!(updated, source: :detach) if persist
+        updated
+      ensure
+        agent&.stop(timeout: 1)
+      end
+
+      def teardown_ignite_target(report:, target_id:, mesh: nil, metadata: {}, timeout: 5, persist: true, session_factory: nil, decommission_timeout: 30)
+        agent = Igniter::Ignite::IgnitionAgent.start
+        updated = agent.call(
+          :teardown,
+          {
+            report: report,
+            target_id: target_id,
+            mesh: mesh,
+            metadata: metadata,
+            root_dir: @root_dir,
+            session_factory: session_factory,
+            decommission_timeout: decommission_timeout
+          },
+          timeout: timeout
+        )
+        persist_ignition_report!(updated, source: :teardown) if persist
+        updated
+      ensure
+        agent&.stop(timeout: 1)
+      end
+
+      def reignite_target(target_id:, timeout: 5, persist: true, **options)
+        plan = ignition_plan_for_target(target_id, mode: :expand)
+        ignite(plan: plan, timeout: timeout, persist: persist, **options)
+      end
+
+      def ignition_trail
+        @ignition_trail ||= Igniter::Ignite::Trail.new(store: ignition_store)
+      end
+
+      def ignition_history(limit: 10)
+        ignition_trail.snapshot(limit: limit)
+      end
+
+      def latest_ignition_report
+        ignition_trail.latest_report
+      end
+
+      def credential_trail
+        @credential_trail ||= Igniter::App::Credentials::Trail.new(store: credential_store)
+      end
+
+      def credential_history(limit: 10, filters: nil, order_by: nil, direction: :asc)
+        credential_trail.snapshot(limit: limit, filters: filters, order_by: order_by, direction: direction)
+      end
+
+      def credential_request_history(limit: 10, filters: nil, order_by: nil, direction: :asc)
+        credential_trail.lease_request_snapshot(
+          limit: limit,
+          filters: filters,
+          order_by: order_by,
+          direction: direction
+        )
+      end
+
+      def build_credential_lease_request(credential:, target_node:, request_id: nil, requested_scope: :remote, node: nil,
+                                         actor: nil, origin: nil, source:, reason: nil,
+                                         lease_id: nil, requested_at: Time.now.utc.iso8601, metadata: {})
+        Igniter::App::Credentials::LeaseRequest.new(
+          credential: credential,
+          request_id: request_id || SecureRandom.uuid,
+          requested_scope: requested_scope,
+          node: node,
+          target_node: target_node,
+          actor: actor,
+          origin: origin,
+          source: source,
+          reason: reason,
+          lease_id: lease_id,
+          requested_at: requested_at,
+          metadata: metadata
+        )
+      end
+
+      def request_credential_lease(credential:, target_node:, request_id: nil, requested_scope: :remote, node: nil,
+                                   actor: nil, origin: nil, source:, reason: nil, lease_id: nil,
+                                   requested_at: Time.now.utc.iso8601, metadata: {})
+        request = build_credential_lease_request(
+          credential: credential,
+          request_id: request_id,
+          requested_scope: requested_scope,
+          node: node,
+          target_node: target_node,
+          actor: actor,
+          origin: origin,
+          source: source,
+          reason: reason,
+          lease_id: lease_id,
+          requested_at: requested_at,
+          metadata: metadata
+        )
+
+        {
+          request: request.to_h,
+          policy_allowed: request.policy_allows_request?,
+          next_operation: request.policy_allows_request? ? :issue_or_deny : :deny,
+          event: record_credential_event(request.request_event)
+        }.freeze
+      end
+
+      def issue_credential_lease(request, lease_id: SecureRandom.uuid, actor: nil, origin: nil, source: nil, metadata: {}, timestamp: Time.now.utc.iso8601)
+        canonical_request = normalize_credential_lease_request(request).with(lease_id: lease_id)
+
+        {
+          request: canonical_request.to_h,
+          policy_allowed: canonical_request.policy_allows_request?,
+          event: record_credential_event(
+            canonical_request.issue_event(
+              lease_id: lease_id,
+              actor: actor,
+              origin: origin,
+              source: source,
+              metadata: metadata,
+              timestamp: timestamp
+            )
+          )
+        }.freeze
+      end
+
+      def deny_credential_lease(request, reason:, actor: nil, origin: nil, source: nil, metadata: {}, timestamp: Time.now.utc.iso8601)
+        canonical_request = normalize_credential_lease_request(request).with(reason: reason)
+
+        {
+          request: canonical_request.to_h,
+          policy_allowed: canonical_request.policy_allows_request?,
+          event: record_credential_event(
+            canonical_request.deny_event(
+              reason: reason,
+              actor: actor,
+              origin: origin,
+              source: source,
+              metadata: metadata,
+              timestamp: timestamp
+            )
+          )
+        }.freeze
+      end
+
+      def revoke_credential_lease(request, lease_id: nil, reason: nil, actor: nil, origin: nil, source: nil, metadata: {}, timestamp: Time.now.utc.iso8601)
+        canonical_request = normalize_credential_lease_request(request)
+        resolved_lease_id = lease_id || canonical_request.lease_id
+
+        {
+          request: canonical_request.with(lease_id: resolved_lease_id, reason: reason || canonical_request.reason).to_h,
+          policy_allowed: canonical_request.policy_allows_request?,
+          event: record_credential_event(
+            canonical_request.revoke_event(
+              lease_id: resolved_lease_id,
+              reason: reason,
+              actor: actor,
+              origin: origin,
+              source: source,
+              metadata: metadata,
+              timestamp: timestamp
+            )
+          )
+        }.freeze
+      end
+
+      def record_credential_event(event = nil, **attributes)
+        credential_trail.record(event, **attributes)
+      end
+
+      def reset_credential_trail!
+        credential_trail.clear!
+      end
+
+      def reload_credential_trail!
+        @credential_trail = Igniter::App::Credentials::Trail.new(store: credential_store)
+      end
+
+      def reset_ignition_trail!
+        ignition_trail.clear!
+      end
+
+      def reload_ignition_trail!
+        @ignition_trail = Igniter::Ignite::Trail.new(store: ignition_store)
+      end
+
+      def deployment_snapshot
+        {
+          "stack" => {
+            "root_dir" => @root_dir,
+            "environment" => resolved_environment,
+            "root_app" => root_app.to_s,
+            "default_node" => default_node&.to_s,
+            "mounts" => stringify_hash(mounts)
+          },
+          "apps" => app_names.each_with_object({}) do |app_name, result|
+            definition = app_definition(app_name)
+            app_config = app_deployment(app_name)
+            result[app_name.to_s] = app_config.merge(
+              "app" => app_name.to_s,
+              "path" => definition.path,
+              "class_name" => definition.klass.name || definition.klass.inspect,
+              "root" => (app_name == root_app)
+            )
+          end,
+          "nodes" => runtime_units_snapshot,
+          "ignite" => stringify_nested_keys(ignition_plan.to_h)
+        }
+      end
+
+      def compose_config
+        compose = stack_settings.dig("deploy", "compose") || {}
+        volume_name = compose["volume_name"] || "#{stack_slug}_var"
+        working_dir = compose["working_dir"]
+        build = compose["build"]
+        dockerfile = compose["dockerfile"]
+        build_context = compose["context"]
+        shared_env = stringify_hash(compose["environment"] || {})
+        volume_target = compose["volume_target"]
+
+        services = runtime_units_snapshot.each_with_object({}) do |(unit_name, unit_config), result|
+          service = {}
+          service["build"] = build_config(build_context, dockerfile) if build_context || dockerfile || build
+          service["image"] = build if build.is_a?(String)
+          service["command"] = unit_config["command"] || default_runtime_command(unit_name)
+          service["working_dir"] = working_dir if present?(working_dir)
+
+          env = shared_env.merge(runtime_environment_for_unit(unit_name, unit_config))
+          service["environment"] = env unless env.empty?
+
+          port = unit_config["port"]
+          service["ports"] = ["#{port}:#{port}"] if unit_config["public"] && port
+
+          depends_on = Array(unit_config["depends_on"]).map(&:to_s)
+          service["depends_on"] = depends_on unless depends_on.empty?
+
+          service["volumes"] = ["#{volume_name}:#{volume_target}"] if volume_target
+          result[unit_name] = service
+        end
+
+        config = { "services" => services }
+        config["volumes"] = { volume_name => {} } if volume_target
+        config
+      end
+
+      def compose_yaml
+        YAML.dump(compose_config)
+      end
+
+      def write_compose(path = nil)
+        target = resolve_path(path || @compose_yml_path)
+        FileUtils.mkdir_p(File.dirname(target))
+        File.write(target, compose_yaml)
+        target
+      end
+
+      def dev_services
+        runtime_units_snapshot.map do |unit_name, unit_config|
+          {
+            name: unit_name.to_s,
+            command: unit_config["dev_command"] || unit_config["command"] || default_runtime_command(unit_name),
+            environment: dev_runtime_environment_for_unit(unit_name, unit_config)
+          }
+        end
+      end
+
+      def procfile_dev
+        dev_services.map do |service|
+          "#{service.fetch(:name)}: #{shell_command_with_env(service.fetch(:command), service.fetch(:environment))}"
+        end.join("\n") + "\n"
+      end
+
+      def write_procfile_dev(path = nil)
+        target = resolve_path(path || @procfile_dev_path)
+        FileUtils.mkdir_p(File.dirname(target))
+        File.write(target, procfile_dev)
+        target
+      end
+
+      def start_dev(environment: nil) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        self.environment(environment) if environment
+
+        services = dev_services
+        raise ArgumentError, "No apps registered for stack dev mode" if services.empty?
+
+        log_dir = resolve_dev_log_dir
+        FileUtils.mkdir_p(log_dir)
+        $stdout.puts("[stack:dev] writing logs to #{relative_to_root(log_dir)}")
+
+        processes = {}
+        readers = []
+        stopping = false
+        exit_status = 0
+
+        stop_all = lambda do |signal|
+          next if stopping
+
+          stopping = true
+          processes.each_value do |process|
+            begin
+              Process.kill(signal, process.fetch(:pid))
+            rescue Errno::ESRCH
+              nil
+            end
+          end
+        end
+
+        previous_int = trap("INT") { stop_all.call("TERM") }
+        previous_term = trap("TERM") { stop_all.call("TERM") }
+
+        services.each do |service|
+          reader, writer = IO.pipe
+          log_path = dev_log_path_for(service.fetch(:name), dir: log_dir)
+          pid = Process.spawn(
+            service.fetch(:environment),
+            service.fetch(:command),
+            chdir: @root_dir,
+            out: writer,
+            err: writer
+          )
+          writer.close
+
+          processes[pid] = { name: service.fetch(:name), pid: pid, log_path: log_path }
+          readers << Thread.new(reader, service.fetch(:name), log_path) do |io, name, path|
+            FileUtils.mkdir_p(File.dirname(path))
+            File.open(path, "w") do |log|
+              log.sync = true
+              log.puts("# igniter dev log")
+              log.puts("# service=#{name}")
+              log.puts("# started_at=#{Time.now.utc.iso8601}")
+              log.puts
+
+              io.each_line do |line|
+                prefixed = "[#{name}] #{line}"
+                $stdout.print(prefixed)
+                log.print(prefixed)
+              end
+            end
+          ensure
+            io.close unless io.closed?
+          end
+        end
+
+        until processes.empty?
+          pid, status = Process.wait2
+          process = processes.delete(pid)
+          next unless process
+
+          exit_status = status.exitstatus if status.exitstatus.to_i != 0 && exit_status.zero?
+
+          unless stopping
+            warn "[stack:dev] #{process.fetch(:name)} exited with status #{status.exitstatus || "unknown"}"
+            stop_all.call("TERM")
+          end
+        end
+      ensure
+        processes&.each_value do |process|
+          begin
+            Process.kill("KILL", process.fetch(:pid))
+          rescue Errno::ESRCH
+            nil
+          end
+        end
+        readers&.each(&:join)
+        trap("INT", previous_int) if previous_int
+        trap("TERM", previous_term) if previous_term
+        raise SystemExit, exit_status unless exit_status.to_i.zero?
+      end
+
+      def setup_load_paths!
+        configured_paths = Array(stack_settings.dig("stack", "shared_lib_paths"))
+        (@shared_lib_paths + configured_paths).uniq.each do |path|
+          full = File.expand_path(path, @root_dir || Dir.pwd)
+          $LOAD_PATH.unshift(full) unless $LOAD_PATH.include?(full)
+        end
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@root_dir, Dir.pwd)
+        subclass.instance_variable_set(:@stack_yml_path, "stack.yml")
+        subclass.instance_variable_set(:@environment_name, nil)
+        subclass.instance_variable_set(:@environment_yml_path, nil)
+        subclass.instance_variable_set(:@compose_yml_path, "config/deploy/compose.yml")
+        subclass.instance_variable_set(:@procfile_dev_path, "config/deploy/Procfile.dev")
+        subclass.instance_variable_set(:@shared_lib_paths, [])
+        subclass.instance_variable_set(:@apps, {})
+        subclass.instance_variable_set(:@mounts, {})
+        subclass.instance_variable_set(:@root_app, nil)
+        subclass.instance_variable_set(:@stack_settings, nil)
+        subclass.instance_variable_set(:@environment_settings, nil)
+        subclass.instance_variable_set(:@ignition_store, nil)
+        subclass.instance_variable_set(:@ignition_trail, nil)
+        subclass.instance_variable_set(:@credential_store, nil)
+        subclass.instance_variable_set(:@credential_trail, nil)
+      end
+
+      private
+
+      def normalize_credential_lease_request(value)
+        case value
+        when Igniter::App::Credentials::LeaseRequest
+          value
+        when Hash
+          Igniter::App::Credentials::LeaseRequest.from_h(value)
+        else
+          raise ArgumentError, "request must be a LeaseRequest or Hash"
+        end
+      end
+
+      def validate_interface_access!
+        exposed = interfaces
+        @apps.each_value do |definition|
+          definition.access_to.each do |required|
+            next if exposed.key?(required)
+
+            raise ArgumentError,
+              "App #{definition.name.inspect} declares access_to #{required.inspect} " \
+              "but no registered app exposes it. Known interfaces: #{exposed.keys.inspect}"
+          end
+        end
+      end
+
+      def parse_cli_options(argv)
+        options = {}
+
+        parser = OptionParser.new do |opts|
+          opts.banner = <<~TEXT
+            Usage: stack.rb [app] [options]
+
+            Stack-first runtime surface:
+              stack.rb                 Start the mounted stack runtime
+              stack.rb dashboard       Start one app directly
+
+            Canonical wrappers:
+              bin/start                Start the mounted stack runtime
+              bin/console              Open the igniter console
+              bin/dev                  Start all local node profiles
+          TEXT
+
+          opts.separator("")
+          opts.separator("Common flows:")
+          opts.separator("    --node NAME       Boot one named node profile")
+          opts.separator("    --console         Open the igniter console")
+          opts.separator("    --dev             Start all local node profiles with prefixed logs (+ var/log/dev/*.log)")
+          opts.separator("    --print-compose   Render compose config from stack nodes")
+          opts.separator("    --print-procfile-dev  Render Procfile.dev from stack nodes")
+          opts.separator("")
+          opts.separator("Examples:")
+          opts.separator("    stack.rb")
+          opts.separator("    stack.rb dashboard")
+          opts.separator("    stack.rb --node seed")
+          opts.separator("    stack.rb --console --node seed")
+          opts.separator("    stack.rb --console --node seed --eval 'context.node_name'")
+          opts.separator("    stack.rb --dev")
+          opts.separator("")
+
+          opts.on("--app NAME", "Start a specific app by name") do |value|
+            options[:target] = value
+          end
+
+          opts.on("--node NAME", "Start a named local node profile") do |value|
+            options[:node] = value
+          end
+
+          opts.on("--console", "Start an interactive stack console (same surface as bin/console)") do
+            options[:console] = true
+          end
+
+          opts.on("-e", "--eval CODE", "Evaluate Ruby inside the stack console and exit") do |value|
+            options[:evaluate] = value
+          end
+
+          opts.on("--env NAME", "Use config/environments/<NAME>.yml overlay") do |value|
+            options[:environment] = value
+          end
+
+          opts.on("--print-compose", "Print a Docker Compose config generated from stack nodes") do
+            options[:print_compose] = true
+          end
+
+          opts.on("--write-compose [PATH]", "Write a Docker Compose config generated from stack nodes") do |value|
+            options[:write_compose] = value || true
+          end
+
+          opts.on("--dev", "Start stack nodes locally with prefixed logs and file logs") do
+            options[:dev] = true
+          end
+
+          opts.on("--print-procfile-dev", "Print a Procfile.dev generated from stack nodes") do
+            options[:print_procfile_dev] = true
+          end
+
+          opts.on("--write-procfile-dev [PATH]", "Write a Procfile.dev generated from stack nodes") do |value|
+            options[:write_procfile_dev] = value || true
+          end
+        end
+
+        parser.parse!(argv)
+        options[:target] ||= argv.shift
+        options
+      end
+
+      def resolve_app_name(name = nil)
+        return normalize_app_name(name) if name && app_names.include?(normalize_app_name(name))
+
+        normalize_app_name(name || root_app)
+      end
+
+      def resolve_node_name(name = nil)
+        raise ArgumentError, "No stack nodes configured" unless nodes_defined?
+
+        desired = normalize_app_name(name || default_node)
+        return desired if node_names.include?(desired)
+
+        available = node_names.map(&:inspect).join(", ")
+        raise ArgumentError, "Unknown stack node #{desired.inspect} (available: #{available})"
+      end
+
+      def normalize_app_name(name)
+        name.to_sym
+      end
+
+      def normalize_optional_name(name)
+        value = name.to_s.strip
+        value.empty? ? nil : value.to_sym
+      end
+
+      def nodes_defined?
+        !stack_settings.fetch("nodes", {}).empty?
+      end
+
+      def mounts_defined?
+        !@mounts.empty?
+      end
+
+      def resolved_environment
+        configured = @environment_name.to_s.strip
+        return configured unless configured.empty?
+
+        ENV["IGNITER_ENV"].to_s.strip
+      end
+
+      def environment_settings
+        @environment_settings ||= begin
+          env_name = resolved_environment
+          return {} if env_name.empty?
+
+          path = @environment_yml_path || File.join("config", "environments", "#{env_name}.yml")
+          load_yaml(resolve_path(path))
+        end
+      end
+
+      def app_deployment(name = nil)
+        app_name = normalize_app_name(name || root_app)
+        shared = stack_settings.fetch("shared", {})
+        app = stack_settings.fetch("apps", {}).fetch(app_name.to_s, {})
+        deep_merge(shared, app)
+      end
+
+      def runtime_units_snapshot
+        if nodes_defined?
+          node_names.each_with_object({}) do |node_name, result|
+            result[node_name.to_s] = node_deployment(node_name).merge(
+              "node" => node_name.to_s,
+              "default" => (node_name == default_node)
+            )
+          end
+        else
+          standalone_runtime_units_snapshot
+        end
+      end
+
+      def standalone_runtime_units_snapshot
+        root_name = root_app.to_s
+        units = {
+          root_name => standalone_runtime_deployment(root_name).merge(
+            "node" => root_name,
+            "default" => true
+          )
+        }
+
+        ignition_plan.local_replica_intents.each do |intent|
+          target = intent.target
+          units[target.id] = local_replica_runtime_deployment(target, intent).merge(
+            "node" => target.id,
+            "default" => false
+          )
+        end
+
+        units
+      end
+
+      def standalone_runtime_deployment(name)
+        {
+          "apps" => app_names.map(&:to_s),
+          "root_app" => root_app.to_s,
+          "mounts" => stringify_hash(mounts),
+          "host" => stack_settings.dig("server", "host"),
+          "port" => stack_settings.dig("server", "port"),
+          "public" => true,
+          "command" => "bundle exec ruby stack.rb",
+          "role" => name.to_s,
+          "environment" => shared_runtime_environment
+        }
+      end
+
+      def local_replica_runtime_deployment(target, intent)
+        base = standalone_runtime_deployment(root_app.to_s)
+        server_settings = target.server_settings
+
+        base.merge(
+          "host" => server_settings["host"] || base["host"],
+          "port" => server_settings["port"] || base["port"],
+          "environment" => base.fetch("environment", {}).merge(
+            "IGNITER_NODE" => target.id,
+            "IGNITER_IGNITE_REPLICA" => "true",
+            "IGNITER_IGNITE_TARGET" => target.id,
+            "IGNITER_IGNITE_INTENT" => intent.id
+          ),
+          "ignite" => {
+            "intent_id" => intent.id,
+            "target_id" => target.id,
+            "kind" => target.kind.to_s
+          }
+        )
+      end
+
+      def node_deployment(name = nil)
+        node_name = normalize_app_name(name || default_node)
+        profile = deep_merge(stack_settings.fetch("shared", {}), node_profile(node_name))
+        configured_mounts = stringify_hash(profile.fetch("mounts", {}))
+
+        {
+          "apps" => app_names.map(&:to_s),
+          "root_app" => root_app.to_s,
+          "mounts" => configured_mounts.empty? ? stringify_hash(mounts) : configured_mounts,
+          "host" => profile["host"] || stack_settings.dig("server", "host"),
+          "port" => profile["port"] || profile.dig("http", "port") || stack_settings.dig("server", "port"),
+          "public" => profile.key?("public") ? profile["public"] : true,
+          "command" => profile["command"] || "bundle exec ruby stack.rb --node #{node_name}",
+          "role" => profile["role"] || node_name.to_s,
+          "depends_on" => Array(profile["depends_on"]).map(&:to_s),
+          "environment" => shared_runtime_environment.merge(stringify_hash(profile.fetch("environment", {})))
+        }
+      end
+
+      def build_stack_runtime(node_name = nil)
+        validate_interface_access!
+        selected_node = nodes_defined? ? resolve_node_name(node_name) : nil
+        root_app_name = root_app
+        root_app_class = app_class(root_app_name)
+        mounted_apps = mounted_stack_apps(selected_node)
+        root_app_class.host_adapter.activate_transport!
+        root_config = root_app_class.send(:build!)
+        apply_http_settings!(root_config, stack_http_settings(selected_node))
+        attach_ignite_runtime_hook!(root_config)
+        root_config.custom_routes = mounted_apps.flat_map { |app| app.fetch(:routes) } + Array(root_config.custom_routes)
+
+        {
+          runtime_name: selected_node || root_app_name,
+          root_app_name: root_app_name,
+          root_app_class: root_app_class,
+          root_config: root_config,
+          mounted_apps: mounted_apps
+        }
+      end
+
+      def mounted_stack_apps(node_name = nil)
+        selected_mounts = if node_name && nodes_defined?
+                            node_deployment(node_name).fetch("mounts", {})
+                          else
+                            stringify_hash(mounts)
+                          end
+
+        selected_mounts.map do |app_name, mount_path|
+          build_mounted_app(app_name: app_name, mount_path: mount_path)
+        end
+      end
+
+      def build_mounted_app(app_name:, mount_path:)
+        normalized_app_name = normalize_app_name(app_name)
+        klass = app_class(normalized_app_name)
+
+        klass.host_adapter.activate_transport!
+        config = klass.send(:build!)
+        rack_app = klass.host_adapter.rack_app(config: config)
+
+        {
+          app_name: normalized_app_name,
+          app_class: klass,
+          config: config,
+          rack_app: rack_app,
+          mount_path: normalize_mount_path(mount_path),
+          routes: mounted_app_routes(normalize_mount_path(mount_path), rack_app)
+        }
+      end
+
+      def mounted_app_routes(mount_path, rack_app)
+        pattern = %r{\A#{Regexp.escape(mount_path)}(?<rest>/.*)?\z}
+
+        SERVICE_MOUNT_METHODS.map do |method|
+          {
+            method: method,
+            path: pattern,
+            handler: lambda do |params:, body:, headers:, env:, raw_body:, config:| # rubocop:disable Lint/UnusedBlockArgument
+              forward_mounted_request(
+                rack_app: rack_app,
+                mount_path: mount_path,
+                rest: params[:rest],
+                env: env,
+                raw_body: raw_body
+              )
+            end
+          }
+        end
+      end
+
+      def forward_mounted_request(rack_app:, mount_path:, rest:, env:, raw_body:)
+        forwarded_env = env.to_h.merge(
+          "SCRIPT_NAME" => mount_path,
+          "PATH_INFO" => normalize_forwarded_path(rest),
+          "rack.input" => StringIO.new(raw_body.to_s)
+        )
+        status, headers, body = rack_app.call(forwarded_env)
+        response_body = +""
+        body.each { |chunk| response_body << chunk.to_s }
+        body.close if body.respond_to?(:close)
+
+        {
+          status: status.to_i,
+          headers: headers,
+          body: response_body
+        }
+      end
+
+      def normalize_forwarded_path(rest)
+        value = rest.to_s
+        value.empty? ? "/" : value
+      end
+
+      def normalize_mount_path(path)
+        value = path.to_s.strip
+        value = "/#{value}" unless value.start_with?("/")
+        value = value.sub(%r{/+\z}, "")
+        value.empty? ? "/" : value
+      end
+
+      def apply_http_settings!(config, http_settings)
+        return config unless http_settings.is_a?(Hash)
+
+        config.host = http_settings["host"].to_s if present?(http_settings["host"])
+        config.port = Integer(http_settings["port"]) if http_settings.key?("port") && !http_settings["port"].nil?
+        config.log_format = http_settings["log_format"].to_sym if present?(http_settings["log_format"])
+        config.drain_timeout = Integer(http_settings["drain_timeout"]) if http_settings.key?("drain_timeout") && !http_settings["drain_timeout"].nil?
+        config
+      end
+
+      def attach_ignite_runtime_hook!(config)
+        context = ignite_runtime_boot_context
+        return config unless context
+        return config unless config.respond_to?(:after_start_hooks)
+
+        config.after_start_hooks << lambda do |config:, server:|
+          complete_ignite_runtime_boot!(config: config, server: server, context: context)
+        end
+        config
+      end
+
+      def ignite_runtime_boot_context
+        target_id = ENV["IGNITER_IGNITE_TARGET"].to_s.strip
+        return nil if target_id.empty?
+
+        {
+          target_id: target_id,
+          intent_id: ENV["IGNITER_IGNITE_INTENT"].to_s.strip,
+          mode: ENV["IGNITER_IGNITE_MODE"].to_s.strip
+        }
+      end
+
+      def complete_ignite_runtime_boot!(config:, server:, context:)
+        mesh = defined?(Igniter::Cluster::Mesh) ? Igniter::Cluster::Mesh : nil
+        url = ignite_runtime_join_url(config, mesh: mesh)
+        return if url.nil?
+
+        if mesh
+          mesh.config.local_url = url if mesh.config.local_url.to_s.strip.empty?
+          if mesh.config.seeds.any?
+            Igniter::Cluster::Mesh::Announcer.new(mesh.config).announce_all
+          elsif mesh.config.peer_name
+            peer = Igniter::Cluster::Mesh::Peer.new(
+              name: mesh.config.peer_name,
+              url: url,
+              capabilities: Array(mesh.config.local_capabilities),
+              tags: Array(mesh.config.local_tags),
+              metadata: Igniter::Cluster::Mesh::PeerMetadata.authoritative(
+                mesh.config.local_metadata.merge(
+                  mesh_ignite: {
+                    target_id: context[:target_id],
+                    intent_id: context[:intent_id],
+                    mode: context[:mode],
+                    joined_at: Time.now.utc.iso8601
+                  }.compact
+                ),
+                origin: mesh.config.peer_name
+              )
+            )
+            mesh.config.peer_registry.register(peer)
+          end
+
+          mesh.config.governance_trail&.record(
+            :ignite_runtime_joined,
+            source: :stack_runtime,
+            payload: {
+              target_id: context[:target_id],
+              intent_id: context[:intent_id],
+              mode: context[:mode],
+              url: url,
+              server: server.class.name
+            }.compact
+          )
+        end
+
+        { target_id: context[:target_id], url: url }
+      end
+
+      def ignite_runtime_join_url(config, mesh:)
+        local_url = mesh&.config&.local_url.to_s.strip
+        return local_url unless local_url.empty?
+
+        host = config.host.to_s.strip
+        host = "127.0.0.1" if host.empty? || host == "0.0.0.0"
+        return nil if config.port.nil?
+
+        "http://#{host}:#{config.port}"
+      end
+
+      def should_await_ignite_join?(report, mesh:, await_join:, bootstrap_remote:)
+        enabled = await_join.nil? ? (mesh && bootstrap_remote) : await_join
+        return false unless enabled
+        return false unless mesh
+        return false unless report.is_a?(Igniter::Ignite::IgnitionReport)
+
+        report.awaiting_join? || report.by_status.fetch(:bootstrapped, 0).positive?
+      end
+
+      def await_ignite_join(report:, mesh:, timeout:, poll_interval:)
+        deadline = Time.now + timeout.to_f
+        current = report
+
+        loop do
+          current = reconcile_ignite(report: current, mesh: mesh, persist: false)
+          return current unless current.awaiting_join? || current.by_status.fetch(:bootstrapped, 0).positive?
+          break if Time.now >= deadline
+
+          sleep poll_interval.to_f
+        end
+
+        current
+      end
+
+      def start_stack_schedulers(runtime)
+        schedulers = []
+        root_app_class = runtime.fetch(:root_app_class)
+        root_config = runtime.fetch(:root_config)
+        scheduler = root_app_class.send(:start_scheduler, root_config)
+        schedulers << scheduler if scheduler
+
+        runtime.fetch(:mounted_apps).each do |mounted|
+          scheduler = mounted.fetch(:app_class).send(:start_scheduler, mounted.fetch(:config))
+          schedulers << scheduler if scheduler
+        end
+
+        schedulers
+      end
+
+      def stop_stack_schedulers(schedulers)
+        Array(schedulers).each do |scheduler|
+          scheduler&.stop
+        end
+      end
+
+      def build_config(context, dockerfile)
+        config = {}
+        config["context"] = context if present?(context)
+        config["dockerfile"] = dockerfile if present?(dockerfile)
+        config
+      end
+
+      def runtime_environment_for_unit(unit_name, unit_config)
+        env = stringify_hash(unit_config.fetch("environment", {}))
+        env["IGNITER_NODE"] = unit_name.to_s if nodes_defined?
+        env["IGNITER_ROOT_APP"] = unit_config["root_app"].to_s
+        env["PORT"] = unit_config["port"].to_s if unit_config["port"]
+        env["IGNITER_ENV"] = resolved_environment unless resolved_environment.empty?
+        env.reject { |_key, value| !present?(value) }
+      end
+
+      def dev_runtime_environment_for_unit(unit_name, unit_config)
+        runtime_environment_for_unit(unit_name, unit_config).merge("RUBYOPT" => rubyopt_with_dev_output_sync)
+      end
+
+      def rubyopt_with_dev_output_sync
+        helper = File.expand_path("dev_output_sync", __dir__)
+        parts = []
+        existing = ENV["RUBYOPT"].to_s.strip
+        parts << existing unless existing.empty?
+        parts << "-r#{Shellwords.escape(helper)}"
+        parts.join(" ").strip
+      end
+
+      def shell_command_with_env(command, env)
+        assignments = env.map do |key, value|
+          "#{Shellwords.escape(key)}=#{Shellwords.escape(value)}"
+        end
+        (assignments + [command]).join(" ").strip
+      end
+
+      def console_banner(context)
+        [
+          "Igniter Console",
+          "  stack=#{context.stack_class.name || "anonymous"}",
+          "  root_app=#{context.root_app_name}",
+          "  app=#{context.app_name}",
+          "  node=#{context.node_name || "none"}",
+          "  mounts=#{context.mounts.keys.map(&:to_s).join(", ")}",
+          "  helpers: stack, context, app, root_app, node, deployment, runtime, mesh"
+        ].join("\n")
+      end
+
+      def console_locals_binding(context)
+        bind = Object.new.instance_eval { binding }
+        {
+          stack: context.stack_class,
+          stack_class: context.stack_class,
+          context: context,
+          root_app: context.root_app_class,
+          root_app_name: context.root_app_name,
+          app: context.app_class,
+          app_class: context.app_class,
+          app_name: context.app_name,
+          node: context.node_name,
+          node_name: context.node_name,
+          node_profile: context.node_profile,
+          deployment: context.deployment,
+          runtime: context.runtime,
+          mounts: context.mounts,
+          mesh: context.mesh,
+          stack_settings: context.stack_settings
+        }.each do |name, value|
+          bind.local_variable_set(name, value)
+        end
+        bind
+      end
+
+      def evaluate_console(bind, code, output)
+        result = bind.eval(code)
+        output.puts("=> #{result.inspect}")
+        result
+      end
+
+      def stringify_hash(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          result[key.to_s] = value.to_s
+        end
+      end
+
+      def stringify_nested_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested_value), result|
+            result[key.to_s] = stringify_nested_keys(nested_value)
+          end
+        when Array
+          value.map { |item| stringify_nested_keys(item) }
+        else
+          value
+        end
+      end
+
+      def shared_runtime_environment
+        stringify_hash(stack_settings.dig("shared", "environment") || {})
+      end
+
+      def stack_slug
+        name = stack_settings.dig("stack", "name")
+        candidate = present?(name) ? name : File.basename(@root_dir.to_s)
+        candidate.to_s.strip.downcase.gsub(/[^a-z0-9]+/, "_").gsub(/\A_+|_+\z/, "")
+      end
+
+      def present?(value)
+        !value.to_s.strip.empty?
+      end
+
+      def use_stack_runtime_by_default?(name)
+        name.nil? && mounts_defined?
+      end
+
+      def stack_http_settings(node_name = nil)
+        settings = stringify_hash(stack_settings.fetch("server", {}))
+        if node_name && nodes_defined?
+          settings = settings.merge(stringify_hash(node_profile(node_name).slice("host", "port", "log_format", "drain_timeout")))
+        end
+        settings["port"] = ENV["PORT"] if present?(ENV["PORT"])
+        settings["port"] = settings["port"].to_i if settings["port"]
+        settings
+      end
+
+      def build_ignition_plan
+        settings = ignite_settings
+        mode = normalize_ignite_mode(settings["mode"])
+        strategy = normalize_ignite_strategy(settings["strategy"])
+        approval_mode = normalize_ignite_approval(settings["approval"])
+        request_id = settings["request_id"] || "ignite-#{stack_slug}-#{resolved_environment.empty? ? "default" : resolved_environment}"
+        requested_from = {
+          "stack" => stack_slug,
+          "environment" => resolved_environment,
+          "root_app" => root_app.to_s
+        }
+        requested_by = {
+          "kind" => "stack_config",
+          "source" => "ignite"
+        }
+        seed_node = {
+          "stack" => stack_slug,
+          "root_app" => root_app.to_s,
+          "host" => stack_settings.dig("server", "host"),
+          "port" => stack_settings.dig("server", "port")
+        }
+
+        intents = []
+        Array(settings["replicas"]).each_with_index do |replica, index|
+          intents << build_local_replica_intent(
+            config: replica,
+            index: index + 1,
+            request_id: request_id,
+            mode: mode,
+            strategy: strategy,
+            approval_mode: approval_mode,
+            requested_by: requested_by,
+            requested_from: requested_from,
+            seed_node: seed_node
+          )
+        end
+
+        Array(settings["servers"]).each_with_index do |server, index|
+          intents << build_remote_server_intent(
+            config: server,
+            index: index + 1,
+            request_id: request_id,
+            mode: mode,
+            strategy: strategy,
+            approval_mode: approval_mode,
+            requested_by: requested_by,
+            requested_from: requested_from,
+            seed_node: seed_node
+          )
+        end
+
+        Igniter::Ignite::IgnitionPlan.new(
+          id: request_id,
+          ignite_mode: mode,
+          strategy: strategy,
+          approval_mode: approval_mode,
+          intents: intents,
+          requested_by: requested_by,
+          requested_from: requested_from,
+          seed_node: seed_node,
+          metadata: {}
+        )
+      end
+
+      def build_local_replica_intent(config:, index:, request_id:, mode:, strategy:, approval_mode:, requested_by:, requested_from:, seed_node:)
+        replica = Hash(config)
+        replica_id = (replica["name"] || "replica-#{index}").to_s
+        target = Igniter::Ignite::BootstrapTarget.new(
+          id: replica_id,
+          kind: :local_replica,
+          locator: select_hash_keys(replica, %w[host port]),
+          base_server: select_hash_keys(stack_settings.fetch("server", {}), %w[host port]),
+          capability_intent: Array(replica["capabilities"]),
+          bootstrap_requirements: Hash(replica["bootstrap"] || {}),
+          metadata: reject_hash_keys(replica, %w[name host port capabilities bootstrap])
+        )
+
+        Igniter::Ignite::DeploymentIntent.new(
+          id: "#{request_id}-#{replica_id}",
+          ignite_mode: mode,
+          strategy: strategy,
+          approval_mode: approval_mode,
+          target: target,
+          requested_capabilities: target.capability_intent,
+          requested_by: requested_by,
+          requested_from: requested_from,
+          seed_node: seed_node,
+          join_policy: {
+            "admission" => "required",
+            "trust" => "cluster_default"
+          },
+          correlation: {
+            "ignite_request_id" => request_id,
+            "target_id" => replica_id
+          },
+          metadata: {}
+        )
+      end
+
+      def build_remote_server_intent(config:, index:, request_id:, mode:, strategy:, approval_mode:, requested_by:, requested_from:, seed_node:)
+        server = normalize_remote_server_config(config, index)
+        server_id = server.fetch("id")
+        target = Igniter::Ignite::BootstrapTarget.new(
+          id: server_id,
+          kind: :ssh_server,
+          locator: { "config_path" => server.fetch("config_path") },
+          base_server: select_hash_keys(stack_settings.fetch("server", {}), %w[host port]),
+          capability_intent: Array(server["capabilities"]),
+          bootstrap_requirements: Hash(server["bootstrap"] || {}),
+          metadata: reject_hash_keys(server, %w[id config_path capabilities bootstrap])
+        )
+
+        Igniter::Ignite::DeploymentIntent.new(
+          id: "#{request_id}-#{server_id}",
+          ignite_mode: mode,
+          strategy: strategy,
+          approval_mode: approval_mode,
+          target: target,
+          requested_capabilities: target.capability_intent,
+          requested_by: requested_by,
+          requested_from: requested_from,
+          seed_node: seed_node,
+          join_policy: {
+            "admission" => "required",
+            "trust" => "cluster_default"
+          },
+          correlation: {
+            "ignite_request_id" => request_id,
+            "target_id" => server_id
+          },
+          metadata: {}
+        )
+      end
+
+      def normalize_remote_server_config(config, index)
+        case config
+        when String
+          {
+            "id" => "server-#{index}",
+            "config_path" => config
+          }
+        else
+          hash = Hash(config)
+          {
+            "id" => (hash["name"] || hash["id"] || "server-#{index}").to_s,
+            "config_path" => hash["target"] || hash.fetch("config_path"),
+            "capabilities" => Array(hash["capabilities"]),
+            "bootstrap" => Hash(hash["bootstrap"] || {})
+          }.merge(reject_hash_keys(hash, %w[name id target config_path capabilities bootstrap]))
+        end
+      end
+
+      def normalize_ignite_mode(value)
+        (value || "cold_start").to_sym
+      end
+
+      def normalize_ignite_strategy(value)
+        (value || "parallel").to_sym
+      end
+
+      def normalize_ignite_approval(value)
+        (value || "required").to_sym
+      end
+
+      def select_hash_keys(hash, allowed_keys)
+        Hash(hash).each_with_object({}) do |(key, value), result|
+          result[key.to_s] = value if allowed_keys.include?(key.to_s)
+        end
+      end
+
+      def reject_hash_keys(hash, rejected_keys)
+        Hash(hash).each_with_object({}) do |(key, value), result|
+          result[key.to_s] = value unless rejected_keys.include?(key.to_s)
+        end
+      end
+
+      def default_runtime_command(name)
+        if nodes_defined?
+          "bundle exec ruby stack.rb --node #{name}"
+        else
+          "bundle exec ruby stack.rb"
+        end
+      end
+
+      def resolve_dev_log_dir
+        configured = stack_settings.dig("development", "log_dir") || stack_settings.dig("dev", "log_dir")
+        resolve_path(configured || "var/log/dev")
+      end
+
+      def dev_log_path_for(name, dir: resolve_dev_log_dir)
+        File.join(dir, "#{name}.log")
+      end
+
+      def relative_to_root(path)
+        return path unless @root_dir && path.start_with?(@root_dir.to_s)
+
+        path.delete_prefix(@root_dir.to_s).sub(%r{\A/}, "")
+      end
+
+      def load_yaml(path)
+        return {} unless path && File.exist?(path)
+
+        YAML.safe_load(File.read(path)) || {}
+      end
+
+      def resolve_path(path)
+        return nil if path.nil?
+        return path if File.absolute_path(path) == path
+
+        File.expand_path(path, @root_dir || Dir.pwd)
+      end
+
+      def default_ignition_store
+        Igniter::Ignite::Stores::FileStore.new(
+          path: resolve_path(File.join("var", "ignite", "#{stack_slug}.ndjson")),
+          archive_path: resolve_path(File.join("var", "ignite", "#{stack_slug}.archive.ndjson"))
+        )
+      end
+
+      def default_credential_store
+        Igniter::App::Credentials::Stores::FileStore.new(
+          path: resolve_path(File.join("var", "credentials", "#{stack_slug}.ndjson")),
+          archive_path: resolve_path(File.join("var", "credentials", "#{stack_slug}.archive.ndjson"))
+        )
+      end
+
+      def ignition_plan_for_target(target_id, mode: :expand)
+        target = target_id.to_s
+        base_plan = ignition_plan
+        intent = base_plan.intents.find { |candidate| candidate.target.id == target }
+        raise KeyError, "Unknown ignition target #{target.inspect}" unless intent
+
+        Igniter::Ignite::IgnitionPlan.new(
+          id: "#{base_plan.id}:#{mode}:#{target}:#{Time.now.utc.strftime('%Y%m%d%H%M%S%6N')}",
+          ignite_mode: mode,
+          strategy: base_plan.strategy,
+          approval_mode: base_plan.approval_mode,
+          intents: [intent],
+          requested_by: base_plan.requested_by,
+          requested_from: base_plan.requested_from,
+          seed_node: base_plan.seed_node,
+          metadata: base_plan.metadata.merge("lifecycle_operation" => mode.to_s, "target_id" => target)
+        )
+      end
+
+      def persist_ignition_report!(report, source:)
+        ignition_trail.ingest_report(report, source: source)
+      end
+
+      def deep_merge(base, override)
+        base.merge(override) do |_key, left, right|
+          if left.is_a?(Hash) && right.is_a?(Hash)
+            deep_merge(left, right)
+          else
+            right
+          end
+        end
+      end
+
+      def reset_stack_state!
+        @stack_settings = nil
+        @environment_settings = nil
+        @ignition_plan = nil
+        @ignition_trail = nil
+        @credential_trail = nil
+      end
+    end
+  end
+end