pangea-core 0.2.0 → 0.3.0

data/lib/pangea/cli/operations.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'synthesizer'
+require_relative 'theme'
+require_relative 'tofu_events'
+
+module Pangea
+  class CLI
+    # Runs tofu operations (init, plan, apply, destroy, output)
+    # against the synthesized Terraform JSON in the workspace directory.
+    #
+    # By default, plan / apply / destroy use OpenTofu's -json event stream
+    # and render a Nord-themed human summary via Pangea::CLI::TofuEvents.
+    # When `PANGEA_VERBOSE=1` is set, tofu runs in pass-through mode and
+    # colors are surrendered to Terraform's native output.
+    class Operations
+      attr_reader :config
+
+      TOFU = 'tofu'
+
+      # Structured outcome of one plan/apply/destroy invocation. Used by
+      # Cascade to aggregate a recap across every workspace in the run.
+      # `added`/`changed`/`removed` are zero when no change_summary event
+      # fired (verbose mode or non-plan/apply op).
+      StageOutcome = Struct.new(
+        :operation, :workspace, :success, :added, :changed, :removed,
+        :transient_errors, :dropped_warnings, :error,
+        keyword_init: true,
+      ) do
+        def total_changes
+          added.to_i + changed.to_i + removed.to_i
+        end
+      end
+
+      def initialize(config)
+        @config = config
+        @synthesizer = Synthesizer.new(config)
+      end
+
+      # Synthesize template to JSON and write to workspace.
+      # @param json_output [Boolean] if true, also print JSON to stdout
+      # @return [String] path to the written .tf.json file
+      def synth(json_output: false)
+        t = Theme
+        t.section('synth')
+        t.structured_log(
+          [:info, 'Synthesizing'],
+          [:path, config.template_file.to_s],
+          [:deprecation, 'in namespace'],
+          [:namespace, config.namespace.to_s],
+        )
+        manifest = @synthesizer.synthesize
+        json = JSON.pretty_generate(manifest)
+        output_path = File.join(config.workspace_dir, "#{config.template_name}.tf.json")
+        File.write(output_path, json)
+        t.structured_log([:info, 'Wrote'], [:path, output_path])
+        $stdout.puts json if json_output
+        output_path
+      end
+
+      def plan
+        synth
+        in_workspace do
+          tofu_init
+          Theme.section('plan')
+          run_tofu('plan')
+        end
+      end
+
+      def apply
+        synth
+        in_workspace do
+          tofu_init
+          Theme.section('apply')
+          run_tofu('apply', '-auto-approve')
+        end
+      end
+
+      def destroy
+        synth
+        in_workspace do
+          tofu_init
+          Theme.section('destroy')
+          run_tofu('destroy', '-auto-approve')
+        end
+      end
+
+      # The structured outcome of the most recent plan/apply/destroy call
+      # on this Operations instance. nil if none has run yet. Cascade
+      # reads this after each stage to aggregate a recap.
+      attr_reader :last_outcome
+
+      def init
+        synth
+        in_workspace { tofu_init }
+      end
+
+      def output
+        Dir.chdir(config.workspace_dir) do
+          tofu('output', '-json')
+        end
+      end
+
+      private
+
+      def in_workspace(&block)
+        Dir.chdir(config.workspace_dir, &block)
+      end
+
+      def tofu_init
+        # tofu init doesn't support -json — run in pass-through mode.
+        Theme.section('init')
+        Theme.log('Running tofu init...', level: :info)
+        tofu('init', '-input=false', '-no-color', '-reconfigure')
+      end
+
+      # Run plan/apply/destroy in JSON-streamed mode by default, or
+      # pass-through if PANGEA_VERBOSE=1. Records a StageOutcome into
+      # `@last_outcome` for cascade aggregation; re-raises on failure
+      # so callers keep their original exception-based flow.
+      def run_tofu(op, *extra_args)
+        if verbose_mode?
+          tofu(op, '-input=false', '-no-color', *extra_args)
+          @last_outcome = StageOutcome.new(
+            operation: op, workspace: workspace_basename,
+            success: true, added: 0, changed: 0, removed: 0,
+            transient_errors: 0, dropped_warnings: 0, error: nil,
+          )
+        else
+          run_tofu_json(op, *extra_args)
+        end
+      end
+
+      def verbose_mode?
+        ENV['PANGEA_VERBOSE'] == '1'
+      end
+
+      # Stream `tofu <op> -json`, filter/render through TofuEvents,
+      # and raise on failure. Dropped warnings (inline_policy deprecation,
+      # argument deprecation) are summarised at the end, not shown inline.
+      def run_tofu_json(op, *extra_args)
+        args = [op, '-input=false', '-no-color', '-json', *extra_args]
+        t = Theme
+        collector = TofuEvents.stream(TOFU, args) do |event|
+          line = TofuEvents.render_human(event)
+          $stderr.puts(line) if line
+        end
+
+        dropped = collector.dropped_warnings.size
+        if dropped.positive?
+          t.structured_log(
+            [:deprecation, "#{dropped} deprecation warning(s) suppressed"],
+            [:deprecation, '(set PANGEA_VERBOSE=1 to show)'],
+            marker_level: :deprecation,
+          )
+        end
+
+        if (summary = collector.summary_line)
+          $stderr.puts "#{t.marker(level: :heading)} #{summary}"
+        end
+
+        unless $?.success?
+          kind = collector.any_transient_errors? ? :transient : :error
+          label = kind == :transient ? 'transient' : 'failed'
+          t.log(
+            "tofu #{op} #{label} (exit #{$?.exitstatus})",
+            level: kind,
+          )
+          @last_outcome = outcome_from(op, collector, success: false,
+            error: "tofu #{op} #{label} (exit #{$?.exitstatus})")
+          raise "[pangea] tofu #{op} #{label} (exit #{$?.exitstatus})"
+        end
+
+        @last_outcome = outcome_from(op, collector, success: true, error: nil)
+        true
+      end
+
+      def outcome_from(op, collector, success:, error:)
+        summary = collector.apply_summary || collector.plan_summary || {}
+        StageOutcome.new(
+          operation: op,
+          workspace: workspace_basename,
+          success: success,
+          added: summary['add'].to_i,
+          changed: summary['change'].to_i,
+          removed: summary['remove'].to_i,
+          transient_errors: collector.transient_errors.size,
+          dropped_warnings: collector.dropped_warnings.size,
+          error: error,
+        )
+      end
+
+      def workspace_basename
+        File.basename(config.template_dir)
+      end
+
+      def tofu(*args)
+        success = system(TOFU, *args)
+        raise "[pangea] tofu #{args.first} failed" unless success
+
+        success
+      end
+    end
+  end
+end

data/lib/pangea/cli/orchestrate.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Pangea
+  class CLI
+    # `pangea orchestrate <distribution.rb>` — the cross-workspace
+    # operator surface (M0.5). Per
+    # theory/PANGEA-MAGMA-ORCHESTRATION.md §III.6.
+    #
+    # The given Ruby file must define exactly one of:
+    #
+    #   * `orchestrator` — a Pangea::Magma::Orchestrator instance
+    #   * `chain`        — a Pangea::Magma::Chain instance
+    #   * `distribution` — a Pangea::Magma::Distribution instance
+    #
+    # `pangea orchestrate` then drives `magma flow run` over the
+    # resulting chain and prints the parsed AggregateReport JSON.
+    #
+    # CLI flags:
+    #   --backend <magma|tofu>  Backend to dispatch through (default: magma)
+    #   --only foo,bar          Only reconcile these workspaces
+    #   --dry-run               Validate + render flow.json; do not run
+    module Orchestrate
+      class << self
+        def run(template_file, backend: nil, only: nil, dry_run: false)
+          backend ||= 'magma'
+          orch_or_chain = load_template(template_file)
+
+          chain = case orch_or_chain
+                  when Pangea::Magma::Stack
+                    orch_or_chain.chain
+                  when Pangea::Magma::Orchestrator
+                    distribution = orch_or_chain.distribution
+                    distribution.to_chain
+                  when Pangea::Magma::Chain
+                    orch_or_chain
+                  when Pangea::Magma::Distribution
+                    orch_or_chain.to_chain
+                  else
+                    raise ArgumentError,
+                          "#{template_file} did not define `stack`, " \
+                          "`orchestrator`, `chain`, or `distribution` at " \
+                          "top level; got #{orch_or_chain.class}"
+                  end
+
+          chain = subset_chain(chain, only) if only && !only.empty?
+
+          if dry_run
+            puts JSON.pretty_generate(
+              backend: backend,
+              chain:   chain.to_h,
+              note:    'dry-run: nothing executed; pass without --dry-run to drive backend',
+            )
+            return
+          end
+
+          unless backend == 'magma'
+            raise NotImplementedError,
+                  "pangea orchestrate currently dispatches through magma only " \
+                  "(got --backend=#{backend}); tofu backend lands once tofu " \
+                  "exposes a workspace-chain primitive (planned M0.5.x)"
+          end
+
+          report = chain.reconcile_all
+          puts JSON.pretty_generate(report)
+        end
+
+        private
+
+        # Eval the Ruby template file and return the orchestrator /
+        # chain / distribution it left in the top-level binding's
+        # locals. The orchestrate path deliberately does not pull in
+        # the rest of pangea-core (synthesizer/operations/etc.) — only
+        # the typed Magma surface, so consumers can drive `pangea
+        # orchestrate` without a Pangea Ruby renderer install.
+        def load_template(template_file)
+          unless File.exist?(template_file)
+            raise ArgumentError, "template file not found: #{template_file}"
+          end
+
+          # Eval under a fresh top-level binding so `orchestrator = ...`
+          # / `chain = ...` / `distribution = ...` become local vars.
+          binding_obj = TOPLEVEL_BINDING.dup
+          binding_obj.eval(File.read(template_file), template_file)
+          %i[stack orchestrator chain distribution].each do |sym|
+            return binding_obj.local_variable_get(sym) if
+              binding_obj.local_variables.include?(sym)
+          end
+
+          raise ArgumentError,
+                "#{template_file}: no stack/orchestrator/chain/distribution found"
+        end
+
+        def subset_chain(chain, names)
+          wanted = names.map(&:to_sym).to_set
+          sub_workspaces = chain.workspaces.select { |k, _| wanted.include?(k) }
+          sub_edges      = chain.edges.select { |e| wanted.include?(e.from) && wanted.include?(e.to) }
+          Pangea::Magma::Chain.new(
+            workspaces:         sub_workspaces,
+            edges:              sub_edges,
+            output_propagation: chain.output_propagation,
+          )
+        end
+      end
+    end
+  end
+end
+
+require 'set'
+require 'pangea/magma'
+require 'pangea/magma/chain'
+require 'pangea/magma/distribution'
+require 'pangea/magma/orchestrator'
+require 'pangea/magma/stack'

data/lib/pangea/cli/reactivity.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'pathname'
+require 'set'
+
+module Pangea
+  class CLI
+    # Reactivity graph — models typed "ask" relationships between workspaces
+    # in a constellation (e.g. pangea-architectures/workspaces/*).
+    #
+    # arch-synthesizer emits a `reactivity:` block into each generated
+    # pangea.yml describing which upstream (layer, workspace, output) values
+    # this workspace asks for. This module parses those declarations across
+    # all sibling workspaces and exposes queries: upstream_of (workspaces this
+    # one asks from), downstream_of (workspaces that ask from this one), and
+    # `cascade_set` (the transitive closure in both directions — the set of
+    # workspaces that MUST plan/apply together when the user acts on one).
+    #
+    # Topological ordering uses Kahn's algorithm; cycles raise
+    # Reactivity::CycleError with the offending node set.
+    module Reactivity
+      CycleError = Class.new(StandardError)
+      MissingWorkspaceError = Class.new(StandardError)
+
+      # A single typed ask declared in a workspace's pangea.yml.
+      Ask = Struct.new(:layer, :workspace, :output, :bind, keyword_init: true) do
+        def self.from_h(h)
+          new(
+            layer: h.fetch('layer'),
+            workspace: h.fetch('workspace'),
+            output: h.fetch('output'),
+            bind: h.fetch('bind'),
+          )
+        end
+      end
+
+      # Orthogonal actions the workspace runs at every cascade visit.
+      # Restricted to the allowlist below to prevent conflict with the
+      # primary cascade command (plan/apply/destroy/deploy).
+      ALLOWED_ACTIONS = %w[synth output init].freeze
+      CONFLICTING_ACTIONS = %w[plan apply destroy deploy].freeze
+
+      InvalidActionError = Class.new(StandardError)
+
+      # A workspace in the constellation — its directory, name, declared asks,
+      # and any per-cascade-visit actions (pre/post).
+      class Workspace
+        attr_reader :name, :dir, :asks, :pre_actions, :post_actions
+
+        def initialize(name:, dir:, asks: [], pre_actions: [], post_actions: [])
+          @name = name
+          @dir = dir
+          @asks = asks.freeze
+          @pre_actions = pre_actions.freeze
+          @post_actions = post_actions.freeze
+          freeze
+        end
+
+        # Load a workspace from its pangea.yml (returns nil if the dir has no
+        # pangea.yml). Missing blocks are fine — empty arrays are used.
+        #
+        # Schema:
+        #   reactivity:
+        #     asks: [{layer, workspace, output, bind}]
+        #   cascade:
+        #     default_depth: N
+        #     pre_actions:  [synth, output, init]
+        #     post_actions: [synth, output, init]
+        def self.load(dir)
+          yml_path = File.join(dir, 'pangea.yml')
+          return nil unless File.exist?(yml_path)
+
+          config = YAML.safe_load(File.read(yml_path)) || {}
+          name = config['workspace'] || File.basename(dir)
+          asks = Array(config.dig('reactivity', 'asks')).map { |h| Ask.from_h(h) }
+          pre = validate_actions(Array(config.dig('cascade', 'pre_actions')), dir: dir)
+          post = validate_actions(Array(config.dig('cascade', 'post_actions')), dir: dir)
+          new(name: name, dir: dir, asks: asks, pre_actions: pre, post_actions: post)
+        rescue InvalidActionError
+          raise
+        rescue StandardError
+          nil
+        end
+
+        # Sanity-check declared actions: allowlist only, no conflicts with
+        # plan/apply/destroy/deploy. Raises InvalidActionError on violation
+        # so the user gets a clear message at scan time.
+        def self.validate_actions(list, dir:)
+          list.map do |a|
+            s = a.to_s.strip
+            if CONFLICTING_ACTIONS.include?(s)
+              raise InvalidActionError,
+                "#{dir}/pangea.yml declares cascade action '#{s}' which " \
+                "conflicts with the primary command. Use the CLI instead."
+            end
+            unless ALLOWED_ACTIONS.include?(s)
+              raise InvalidActionError,
+                "#{dir}/pangea.yml declares unknown cascade action '#{s}'. " \
+                "Allowed: #{ALLOWED_ACTIONS.join(', ')}."
+            end
+            s
+          end.freeze
+        end
+
+        # Names of workspaces this one asks from (its direct upstream).
+        def upstream_names
+          asks.map(&:workspace).uniq
+        end
+
+        def reactive?
+          !asks.empty?
+        end
+      end
+
+      # Full constellation graph computed from a workspaces root directory.
+      class Graph
+        attr_reader :workspaces
+
+        def initialize(workspaces)
+          @workspaces = workspaces.freeze  # Hash<String, Workspace>
+          freeze
+        end
+
+        # Scan a workspaces root directory (parent of many workspace dirs) and
+        # build a Graph. Returns an empty Graph if the root doesn't exist or
+        # contains no pangea.yml siblings.
+        def self.scan(workspaces_root)
+          return new({}) unless Dir.exist?(workspaces_root)
+
+          ws = {}
+          Dir.entries(workspaces_root).sort.each do |entry|
+            next if entry.start_with?('.')
+
+            dir = File.join(workspaces_root, entry)
+            next unless File.directory?(dir)
+
+            workspace = Workspace.load(dir)
+            ws[workspace.name] = workspace if workspace
+          end
+          new(ws)
+        end
+
+        # Given a template file path, locate the enclosing workspaces root
+        # (the parent dir whose children are the constellation workspaces).
+        # Walks up from the template's directory looking for the first ancestor
+        # that contains multiple pangea.yml siblings. Returns nil if none.
+        def self.workspaces_root_for(template_file)
+          start = File.expand_path(File.dirname(template_file))
+          Pathname.new(start).ascend do |path|
+            parent = path.parent
+            return parent.to_s if siblings_with_pangea_yml(parent) >= 2
+          end
+          nil
+        end
+
+        def self.siblings_with_pangea_yml(parent_path)
+          return 0 unless parent_path.directory?
+
+          parent_path.children.count do |child|
+            child.directory? && child.join('pangea.yml').file?
+          end
+        end
+
+        def [](name)
+          workspaces[name]
+        end
+
+        def include?(name)
+          workspaces.key?(name)
+        end
+
+        def names
+          workspaces.keys
+        end
+
+        # Names of workspaces `name` asks from (direct upstream).
+        def upstream_of(name)
+          ws = workspaces[name] or return []
+          ws.upstream_names.select { |n| workspaces.key?(n) }
+        end
+
+        # Names of workspaces that ask from `name` (direct downstream).
+        def downstream_of(name)
+          workspaces.each_value.select do |w|
+            w.upstream_names.include?(name)
+          end.map(&:name)
+        end
+
+        # Transitive closure of `name` in both directions: every workspace
+        # that must plan/apply together when user acts on `name`.
+        # Returns a Set of names INCLUDING `name` itself.
+        #
+        # @param max_depth [Integer, nil] if set, limits traversal to that
+        #   many hops from `name` (0 = only seed, 1 = seed + direct neighbors,
+        #   etc). nil = unlimited (full reachable set).
+        def cascade_set(name, max_depth: nil)
+          raise MissingWorkspaceError, "unknown workspace: #{name}" unless workspaces.key?(name)
+
+          visited = { name => 0 }
+          frontier = [name]
+          until frontier.empty?
+            n = frontier.shift
+            depth = visited[n]
+            next if max_depth && depth >= max_depth
+
+            (upstream_of(n) + downstream_of(n)).each do |neighbor|
+              next if visited.key?(neighbor)
+
+              visited[neighbor] = depth + 1
+              frontier << neighbor
+            end
+          end
+          Set.new(visited.keys)
+        end
+
+        # Topologically sort a subset of workspace names — earlier names can
+        # run before later ones because no later name asks FROM an earlier one.
+        # Kahn's algorithm; raises CycleError if the subset contains a cycle.
+        def topo_sort(names_subset)
+          subset = names_subset.to_a
+          subset_set = Set.new(subset)
+
+          # incoming edges: name -> names_in_subset_this_asks_from
+          incoming = subset.each_with_object({}) do |n, h|
+            h[n] = upstream_of(n).select { |u| subset_set.include?(u) }
+          end
+
+          ready = subset.select { |n| incoming[n].empty? }.sort
+          ordered = []
+          until ready.empty?
+            n = ready.shift
+            ordered << n
+            subset.each do |m|
+              next unless incoming[m].delete(n)
+
+              ready << m if incoming[m].empty?
+            end
+            ready.sort!
+          end
+
+          unless ordered.size == subset.size
+            stuck = subset - ordered
+            raise CycleError, "reactive ask cycle among: #{stuck.sort.join(', ')}"
+          end
+
+          ordered
+        end
+      end
+    end
+  end
+end

data/lib/pangea/cli/synthesizer.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Pangea
+  class CLI
+    # Synthesizes a Pangea Ruby template into Terraform JSON.
+    # Loads the template, evaluates it on a TerraformSynthesizer,
+    # injects the backend config, and returns the manifest.
+    class Synthesizer
+      attr_reader :config
+
+      def initialize(config)
+        @config = config
+      end
+
+      # @return [Hash] Normalized Terraform manifest with string keys
+      def synthesize
+        load_workspace_libs
+        load_synthesizer_gem
+
+        synth = TerraformSynthesizer.new
+        block = capture_template_block(config.template_content, config.template_file)
+
+        if block
+          synth.instance_eval(&block)
+        else
+          $stderr.puts "[pangea] Warning: no template block found, trying direct eval"
+          synth.instance_eval(config.template_content, config.template_file)
+        end
+
+        manifest = normalize(synth.synthesis)
+        inject_backend(manifest)
+        manifest
+      end
+
+      private
+
+      def load_workspace_libs
+        [config.template_dir, Dir.pwd].uniq.each do |dir|
+          lib_dir = File.join(dir, 'lib')
+          $LOAD_PATH.unshift(lib_dir) if File.directory?(lib_dir) && !$LOAD_PATH.include?(lib_dir)
+        end
+
+        # Auto-require architecture modules if available
+        %w[pangea/architectures pangea/workspace_config].each do |mod|
+          require mod
+        rescue LoadError
+          nil # Optional — not all workspaces have these
+        end
+      end
+
+      def load_synthesizer_gem
+        require 'terraform-synthesizer'
+      rescue LoadError
+        begin
+          require 'terraform_synthesizer'
+        rescue LoadError
+          require 'abstract-synthesizer'
+        end
+      end
+
+      # Captures the block from the template file. Two DSL surfaces
+      # are supported in parallel:
+      #
+      #   template :name do … end         — original; intercepts via
+      #                                     Kernel#template override.
+      #   Pangea.architecture 'name' do … end
+      #                                   — abstract concept; block
+      #                                     lands in
+      #                                     Pangea.last_architecture.
+      #
+      # When both are present in the same file the ``template``
+      # override takes precedence (it runs first during eval); the
+      # architecture fallback catches templates that never call
+      # ``template`` explicitly.
+      def capture_template_block(content, file_path)
+        captured = nil
+        original = method(:template) if respond_to?(:template, true)
+
+        define_singleton_method(:template) { |_name, &blk| captured = blk }
+
+        # Reset the architecture registry's last-declared pointer so
+        # we don't accidentally pick up a leftover from a previous
+        # template's eval in the same process (tests, bulk mode).
+        Pangea.reset_architectures! if Pangea.respond_to?(:reset_architectures!)
+
+        eval(content, binding, file_path) # rubocop:disable Security/Eval
+
+        # Restore original method if it existed
+        if original
+          define_singleton_method(:template, original)
+        else
+          singleton_class.remove_method(:template) if singleton_class.method_defined?(:template)
+        end
+
+        captured || Pangea.last_architecture&.block
+      end
+
+      # JSON round-trip to normalize symbol keys → string keys
+      def normalize(manifest)
+        JSON.parse(JSON.generate(manifest))
+      end
+
+      def inject_backend(manifest)
+        return if config.backend_config.empty?
+
+        manifest['terraform'] ||= {}
+        manifest['terraform']['backend'] = config.backend_config
+
+        # Merge required_providers from template if present
+        # (templates set this via `terraform required_providers: {...}`)
+        if manifest.dig('terraform', 'required_providers').nil? &&
+           manifest.key?('terraform') &&
+           manifest['terraform'].is_a?(Hash)
+          # Already handled — required_providers preserved from synthesis
+        end
+      end
+    end
+  end
+end