pangea-core 0.1.0 → 0.3.0

data/lib/pangea/cli/cascade.rb

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+require_relative 'config'
+require_relative 'operations'
+require_relative 'reactivity'
+require_relative 'theme'
+
+module Pangea
+  class CLI
+    # Cascade — when the user runs plan/apply/destroy on a template that
+    # participates in reactive relationships (declared in pangea.yml's
+    # reactivity.asks block), automatically include every transitively
+    # reachable workspace, in the right order:
+    #
+    #   - plan  : topological (upstream first, downstream after)
+    #   - apply : topological (upstream must exist before downstream reads)
+    #   - destroy: reverse topological (tear down leaves before roots)
+    #
+    # Each workspace's phase emits a themed section divider plus a
+    # structured summary line. Set PANGEA_NO_CASCADE=1 to fall back to
+    # single-workspace behavior even when a cascade would otherwise fire.
+    class Cascade
+      attr_reader :graph, :ordered_names, :seed_name, :seed_template_file,
+                  :outcomes, :max_depth
+
+      def self.enabled?
+        ENV['PANGEA_NO_CASCADE'] != '1'
+      end
+
+      # Build a cascade plan from a user-provided template file path. Returns
+      # nil if:
+      #  - cascade is disabled (PANGEA_NO_CASCADE=1)
+      #  - the template is not in a scannable constellation
+      #  - the resolved cascade has only the seed itself (depth 0, no
+      #    reactive neighbors in range, or platform scope filters everyone
+      #    but the seed)
+      #
+      # Depth resolution (first match wins):
+      #  1. explicit `max_depth:` argument (CLI --depth N)
+      #  2. ENV['PANGEA_CASCADE_DEPTH']
+      #  3. workspace or root pangea.yml `cascade.default_depth`
+      #  4. nil (unlimited — the full transitive closure)
+      #
+      # Platform scope: when ENV['PLATFORM'] is set AND
+      # `{constellation_root}/platforms/{platform}.yaml` declares a
+      # `layers:` list, the cascade is intersected with that list so
+      # that workspaces the platform does not use are skipped. The seed
+      # is always included. Absent platform / file / layers key → no
+      # filter (full closure).
+      def self.for_template(template_file, max_depth: nil)
+        return nil unless enabled?
+
+        workspaces_root = Reactivity::Graph.workspaces_root_for(template_file)
+        return nil unless workspaces_root
+
+        graph = Reactivity::Graph.scan(workspaces_root)
+        seed_dir = File.dirname(File.expand_path(template_file))
+        seed_name = File.basename(seed_dir)
+
+        return nil unless graph.include?(seed_name)
+
+        depth = resolve_depth(
+          explicit: max_depth,
+          seed_dir: seed_dir,
+          workspaces_root: workspaces_root,
+        )
+
+        cascade_names = graph.cascade_set(seed_name, max_depth: depth)
+        cascade_names = filter_by_platform_scope(
+          cascade_names,
+          workspaces_root: workspaces_root,
+          seed_name: seed_name,
+        )
+        return nil if cascade_names.size <= 1
+
+        ordered = graph.topo_sort(cascade_names)
+        new(
+          graph: graph,
+          ordered_names: ordered,
+          seed_name: seed_name,
+          seed_template_file: File.expand_path(template_file),
+          max_depth: depth,
+        )
+      end
+
+      # Intersect the cascade with the set of workspaces the current
+      # platform actually uses. Keeps the seed even if the platform
+      # doesn't declare it (defensive — the user explicitly asked to
+      # plan/apply that workspace).
+      def self.filter_by_platform_scope(names, workspaces_root:, seed_name:)
+        platform_name = ENV['PLATFORM']
+        return names if platform_name.nil? || platform_name.empty?
+
+        platforms_dir = File.expand_path('../platforms', workspaces_root)
+        yml_path = File.join(platforms_dir, "#{platform_name}.yaml")
+        return names unless File.exist?(yml_path)
+
+        platform = YAML.safe_load(File.read(yml_path)) || {}
+        layers = Array(platform['layers']).map(&:to_s)
+        return names if layers.empty?
+
+        allowed = layers.map { |layer| "platform-#{layer}" }.to_set
+        allowed << seed_name
+        Set.new(names.select { |n| allowed.include?(n) })
+      rescue StandardError
+        names
+      end
+
+      # Resolve the depth cap from CLI arg → env → workspace yml → root yml.
+      # Returns nil for unlimited. A non-numeric / negative value falls
+      # through to the next source.
+      def self.resolve_depth(explicit:, seed_dir:, workspaces_root:)
+        candidates = [
+          explicit,
+          parse_int(ENV['PANGEA_CASCADE_DEPTH']),
+          yaml_depth(File.join(seed_dir, 'pangea.yml')),
+          yaml_depth(File.join(File.dirname(workspaces_root), 'pangea.yml')),
+        ]
+        candidates.find { |d| !d.nil? }
+      end
+
+      def self.parse_int(value)
+        return nil if value.nil?
+        return value.negative? ? nil : value if value.is_a?(Integer)
+        return nil if value.to_s.strip.empty?
+
+        i = Integer(value.to_s, 10)
+        i.negative? ? nil : i
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def self.yaml_depth(path)
+        return nil unless File.exist?(path)
+
+        config = YAML.safe_load(File.read(path)) || {}
+        parse_int(config.dig('cascade', 'default_depth'))
+      rescue StandardError
+        nil
+      end
+
+      def initialize(graph:, ordered_names:, seed_name:, seed_template_file:, max_depth: nil)
+        @graph = graph
+        @ordered_names = ordered_names
+        @seed_name = seed_name
+        @seed_template_file = seed_template_file
+        @max_depth = max_depth
+        @outcomes = []
+      end
+
+      # Run plan across every cascaded workspace in topological order.
+      # Upstream fails → we continue anyway so the user sees what else drifts.
+      def plan(namespace: nil)
+        announce(:plan)
+        each_stage(ordered_names, primary: :plan) { |ops| ops.plan }
+      end
+
+      # Apply in topological order; abort the cascade on the first failure
+      # since downstream reads assume upstream state.
+      def apply(namespace: nil)
+        announce(:apply)
+        each_stage(ordered_names, primary: :apply, abort_on_failure: true) { |ops| ops.apply }
+      end
+
+      # Destroy in reverse topological order.
+      def destroy(namespace: nil)
+        announce(:destroy)
+        each_stage(ordered_names.reverse, primary: :destroy) { |ops| ops.destroy }
+      end
+
+      private
+
+      def announce(op)
+        t = Theme
+        t.section("cascade #{op}")
+        parts = [
+          [:info, 'Seed'],
+          [:resource, seed_name],
+          [:info, '→'],
+          [:count, ordered_names.size.to_s],
+          [:info, 'workspace(s)'],
+        ]
+        if max_depth
+          parts.concat([[:info, 'depth'], [:count, max_depth.to_s]])
+        end
+        t.structured_log(*parts)
+        t.structured_log(
+          [:info, 'Order'],
+          [:path, ordered_names.join(' → ')],
+        )
+      end
+
+      def each_stage(names, primary:, abort_on_failure: false)
+        failures = []
+        names.each_with_index do |name, i|
+          workspace = graph[name]
+          template_file = detect_template(workspace)
+          next unless template_file
+
+          stage_banner(name, i + 1, names.size)
+          ops = nil
+          begin
+            config = Config.new(template_file, namespace: nil)
+            ops = Operations.new(config)
+            run_actions(ops, workspace.pre_actions, primary, :pre)
+            yield ops
+            run_actions(ops, workspace.post_actions, primary, :post)
+            record_outcome(ops)
+          rescue StandardError => e
+            record_outcome(ops, fallback_name: name, error: e)
+            failures << [name, e]
+            if abort_on_failure
+              Theme.log("cascade aborted at #{name}: #{e.message}", level: :error)
+              break
+            else
+              Theme.log("stage #{name} failed: #{e.message}", level: :warning)
+            end
+          end
+        end
+
+        render_recap
+        unless failures.empty?
+          Theme.log(
+            "cascade completed with #{failures.size} failure(s): #{failures.map(&:first).join(', ')}",
+            level: :warning,
+          )
+        end
+        failures.empty?
+      end
+
+      # Execute declared pre/post actions at the current cascade visit.
+      # Silently skips actions that would conflict with the primary command
+      # (belt-and-suspenders — Workspace.load already rejects them).
+      def run_actions(ops, actions, primary, position)
+        return if actions.nil? || actions.empty?
+
+        primary_s = primary.to_s
+        actions.each do |action|
+          next if action == primary_s
+
+          Theme.structured_log(
+            [:divider, "  cascade.#{position}_action"],
+            [:info, action],
+          )
+          case action
+          when 'synth'  then ops.synth
+          when 'output' then ops.output
+          when 'init'   then ops.init
+          end
+        end
+      end
+
+      # Capture the StageOutcome from an Operations instance; fall back to
+      # a synthetic "failed before counts" outcome when the stage raised
+      # before Operations#run_tofu populated last_outcome.
+      def record_outcome(ops, fallback_name: nil, error: nil)
+        outcome = ops&.last_outcome
+        outcome ||= Operations::StageOutcome.new(
+          operation: 'unknown',
+          workspace: fallback_name || ops&.config&.template_name,
+          success: error.nil?,
+          added: 0, changed: 0, removed: 0,
+          transient_errors: 0, dropped_warnings: 0,
+          error: error&.message,
+        )
+        @outcomes << outcome
+      end
+
+      # Themed recap table: one row per stage with counts + status.
+      def render_recap
+        return if outcomes.empty?
+
+        t = Theme
+        t.section('cascade recap')
+
+        totals = { added: 0, changed: 0, removed: 0, failed: 0, transient: 0 }
+        outcomes.each do |o|
+          totals[:added]     += o.added.to_i
+          totals[:changed]   += o.changed.to_i
+          totals[:removed]   += o.removed.to_i
+          totals[:failed]    += 1 unless o.success
+          totals[:transient] += o.transient_errors.to_i
+        end
+
+        outcomes.each do |o|
+          status_role = if !o.success then :error
+                        elsif o.transient_errors.to_i.positive? then :transient
+                        elsif o.total_changes.zero? then :noop
+                        else :success
+                        end
+          status_glyph = case status_role
+                         when :error     then '✗'
+                         when :transient then '⚠'
+                         when :noop      then '='
+                         else                 '✔'
+                         end
+          t.structured_log(
+            [status_role, status_glyph],
+            [:resource, o.workspace.to_s.ljust(24)],
+            [:info, o.operation.to_s.ljust(7)],
+            [:create, "+#{o.added.to_i}"],
+            [:update, "~#{o.changed.to_i}"],
+            [:delete, "-#{o.removed.to_i}"],
+            marker_level: status_role == :error ? :error : :info,
+          )
+        end
+
+        t.structured_log(
+          [:heading, 'Total:'],
+          [:create, "+#{totals[:added]} added"],
+          [:update, "~#{totals[:changed]} changed"],
+          [:delete, "-#{totals[:removed]} destroyed"],
+          [:error, "✗#{totals[:failed]} failed"],
+          [:transient, "⚠#{totals[:transient]} transient"],
+          marker_level: totals[:failed].positive? ? :error : :heading,
+        )
+      end
+
+      # A workspace dir contains one or more .rb templates alongside
+      # pangea.yml. Pick the one whose basename matches the workspace name
+      # with hyphens -> underscores; fall back to the first *.rb file.
+      def detect_template(workspace)
+        preferred = File.join(workspace.dir, "#{workspace.name.tr('-', '_')}.rb")
+        return preferred if File.exist?(preferred)
+
+        candidates = Dir.glob(File.join(workspace.dir, '*.rb')).sort
+        candidates.first
+      end
+
+      def stage_banner(name, idx, total)
+        t = Theme
+        t.structured_log(
+          [:divider, "── [#{idx}/#{total}]"],
+          [:resource, name],
+          [:divider, '──────────────────'],
+        )
+      end
+    end
+  end
+end

data/lib/pangea/cli/config.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'fileutils'
+
+module Pangea
+  class CLI
+    # Resolves workspace configuration from pangea.yml files.
+    # Handles namespace resolution, state backend config, and workspace paths.
+    class Config
+      attr_reader :template_file, :template_dir, :template_name,
+                  :namespace, :workspace_dir, :backend_config
+
+      def initialize(template_file, namespace: nil)
+        @template_file = File.expand_path(template_file)
+        @template_dir = File.dirname(@template_file)
+        @template_name = File.basename(@template_file, '.rb')
+        @namespace = resolve_namespace(namespace)
+        @workspace_dir = build_workspace_dir
+        @backend_config = resolve_backend_config
+      end
+
+      def template_content
+        @template_content ||= File.read(@template_file)
+      end
+
+      private
+
+      def resolve_namespace(explicit)
+        return explicit if explicit && !explicit.empty?
+
+        env_ns = ENV['PANGEA_NAMESPACE']
+        return env_ns if env_ns && !env_ns.empty?
+
+        load_default_namespace || 'default'
+      end
+
+      def load_default_namespace
+        # Check workspace pangea.yml first, fall back to root
+        [@template_dir, Dir.pwd].uniq.each do |dir|
+          yml = find_pangea_yml(dir)
+          next unless yml
+
+          config = YAML.safe_load(File.read(yml)) || {}
+          return config['default_namespace'] if config['default_namespace']
+        end
+        nil
+      end
+
+      def build_workspace_dir
+        home = ENV.fetch('HOME', '.')
+        dir = File.join(home, '.pangea', 'workspaces', @namespace, @template_name)
+        FileUtils.mkdir_p(dir)
+        dir
+      end
+
+      def resolve_backend_config
+        # Load root config first, then workspace — workspace wins on conflicts.
+        # Use deep_merge so nested keys (namespaces, state) compose correctly.
+        # Root is discovered by walking up from the TEMPLATE directory (not
+        # pwd) until a directory with pangea.yml that declares state.s3.*
+        # defaults is found. This is the same boundary logic WorkspaceConfig
+        # uses — the two must agree for backend merging to work. Previously
+        # this used Dir.pwd, which silently loaded the workspace's own
+        # pangea.yml as "root" when pangea was run from within the workspace,
+        # dropping the bucket/region defaults on the floor.
+        root_dir = find_root_pangea_dir(@template_dir)
+        root_config = root_dir ? (load_pangea_yml(root_dir) || {}) : {}
+        ws_config = load_pangea_yml(@template_dir) || {}
+        merged = deep_merge(root_config, ws_config)
+
+        ns_config = merged.dig('namespaces', @namespace)
+        return {} unless ns_config
+
+        state = ns_config['state'] || {}
+        state_type = state['type'] || 's3'
+        s3_defaults = merged.dig('state', 's3') || {}
+
+        case state_type
+        when 'local'
+          { 'local' => { 'path' => state['path'] || 'terraform.tfstate' } }
+        when 's3'
+          key_prefix = interpolate_env(state['key'] || s3_defaults['key'])
+          {
+            's3' => {
+              'bucket' => state['bucket'] || s3_defaults['bucket'],
+              'key' => "#{key_prefix}/#{@template_name}/terraform.tfstate",
+              'region' => state['region'] || s3_defaults['region'] || 'us-east-1',
+              'dynamodb_table' => state['dynamodb_table'] || s3_defaults['dynamodb_table'],
+              'encrypt' => state.fetch('encrypt', s3_defaults.fetch('encrypt', true)),
+            }.compact,
+          }
+        else
+          {}
+        end
+      end
+
+      # Substitute ${ENV_VAR} references in a string against the current
+      # process environment. Lets pangea.yml `state.key` values express
+      # partitioning dimensions (e.g. `pangea/platform-dns/${PLATFORM}`)
+      # without pangea-core knowing about any specific dimension —
+      # that's a domain concern owned by the consumer (e.g.
+      # pangea-architectures). Pure string templating, no YAML coercion.
+      #
+      # Raises if a referenced env var is unset, so a partitioned-state
+      # scheme fails fast instead of silently collapsing to a shared key
+      # when the operator forgets to export the dimension variable.
+      def interpolate_env(template)
+        return template unless template.is_a?(String)
+
+        template.gsub(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/) do
+          var = Regexp.last_match(1)
+          val = ENV[var]
+          if val.nil? || val.empty?
+            raise "[pangea] state.key references ${#{var}} but the env is unset " \
+                  "(workspace: #{@template_name}). Export #{var} before running."
+          end
+          val
+        end
+      end
+
+      def find_pangea_yml(dir)
+        path = File.join(dir, 'pangea.yml')
+        File.exist?(path) ? path : nil
+      end
+
+      # Walk up from `start_dir` looking for a pangea.yml that declares
+      # top-level `state.s3.*` defaults (the marker of the "true" root).
+      # Returns nil if no such file is found before reaching the filesystem
+      # root.
+      def find_root_pangea_dir(start_dir)
+        dir = File.expand_path(start_dir)
+        loop do
+          yml = find_pangea_yml(dir)
+          if yml
+            config = YAML.safe_load(File.read(yml)) rescue {}
+            # A root pangea.yml declares state.s3.* defaults; workspace-
+            # level pangea.yml files declare namespaces[].state.{type,key}
+            # but no top-level state.s3 block.
+            return dir if config.is_a?(Hash) && config.dig('state', 's3').is_a?(Hash)
+          end
+          parent = File.dirname(dir)
+          return nil if parent == dir
+          dir = parent
+        end
+      end
+
+      def load_pangea_yml(dir)
+        path = find_pangea_yml(dir)
+        return nil unless path
+
+        YAML.safe_load(File.read(path)) || {}
+      rescue StandardError
+        nil
+      end
+
+      # Recursively merge two hashes — values from `override` win on conflicts.
+      def deep_merge(base, override)
+        base.merge(override) do |_key, old_val, new_val|
+          if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            deep_merge(old_val, new_val)
+          else
+            new_val
+          end
+        end
+      end
+    end
+  end
+end