pangea-core 0.2.0 → 0.3.0

data/lib/pangea/cli/theme.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module Pangea
+  class CLI
+    # Nord-palette ANSI theming for the pangea CLI.
+    #
+    # Emits 24-bit color escape sequences using the Nord palette
+    # (https://www.nordtheme.com/) mapped to semantic roles. Falls back to
+    # plain text when:
+    #
+    # - Neither stdout nor stderr is a TTY (piped / captured output)
+    # - `NO_COLOR` is set (https://no-color.org/)
+    # - `PANGEA_NO_COLOR` is set
+    # - `TERM` is `dumb`
+    #
+    # Nord palette reference:
+    #   Polar Night (backgrounds, muted text):
+    #     nord0  #2E3440
+    #     nord1  #3B4252
+    #     nord2  #434C5E
+    #     nord3  #4C566A   ← most-used muted foreground
+    #   Snow Storm (foregrounds):
+    #     nord4  #D8DEE9
+    #     nord5  #E5E9F0
+    #     nord6  #ECEFF4   ← brightest fg (resource addresses, headings)
+    #   Frost (info / progress / primary accent):
+    #     nord7  #8FBCBB   ← headings (teal)
+    #     nord8  #88C0D0   ← primary info/progress (cyan)
+    #     nord9  #81A1C1   ← paths, secondary (blue)
+    #     nord10 #5E81AC   ← backgrounds / rarely used
+    #   Aurora (semantic accents):
+    #     nord11 #BF616A   ← error (red)
+    #     nord12 #D08770   ← destroy (orange)
+    #     nord13 #EBCB8B   ← warning, replace, counts (yellow)
+    #     nord14 #A3BE8C   ← success, create (green)
+    #     nord15 #B48EAD   ← meta, import (purple)
+    module Theme
+      # rgb triples
+      NORD = {
+        nord0:  [46,  52,  64],
+        nord1:  [59,  66,  82],
+        nord2:  [67,  76,  94],
+        nord3:  [76,  86,  106],
+        nord4:  [216, 222, 233],
+        nord5:  [229, 233, 240],
+        nord6:  [236, 239, 244],
+        nord7:  [143, 188, 187],
+        nord8:  [136, 192, 208],
+        nord9:  [129, 161, 193],
+        nord10: [94,  129, 172],
+        nord11: [191, 97,  106],
+        nord12: [208, 135, 112],
+        nord13: [235, 203, 139],
+        nord14: [163, 190, 140],
+        nord15: [180, 142, 173],
+      }.freeze
+
+      # Semantic role → palette entry.
+      SEMANTICS = {
+        # Structural
+        label:        :nord3,    # "[pangea]" prefix (muted)
+        divider:      :nord3,    # horizontal rules, tree glyphs
+        heading:      :nord7,    # section titles
+        resource:     :nord6,    # resource addresses (brightest fg)
+        path:         :nord9,    # file paths
+        namespace:    :nord15,   # namespaces / envs
+        count:        :nord13,   # numeric counts (emphasis)
+        # Status levels
+        info:         :nord8,    # neutral info / progress
+        success:      :nord14,   # success / create
+        warning:      :nord13,   # warning
+        error:        :nord11,   # error
+        transient:    :nord12,   # transient / retry-worthy error
+        deprecation:  :nord3,    # dropped deprecation summary (muted)
+        # Change actions
+        create:       :nord14,   # + (green)
+        update:       :nord8,    # ~ (cyan)
+        delete:       :nord11,   # - (red)
+        replace:      :nord13,   # ± (yellow)
+        read:         :nord9,    # > (blue)
+        import:       :nord15,   # → (purple)
+        noop:         :nord3,    # = (muted)
+      }.freeze
+
+      # Ordered list of roles used to test output is theme-reachable.
+      ROLES = SEMANTICS.keys.freeze
+
+      # The blackmatter family marker. Adopted from the blackmatter-shell
+      # starship prompt (`[❄](bold #88C0D0)` — Nord frost cyan snowflake).
+      # Every pangea-emitted line begins with this glyph, colored by the
+      # line's semantic level — visual coherence with the rest of the
+      # pleme-io / blackmatter-themed shell.
+      MARKER = '❄'
+
+      module_function
+
+      # Whether ANSI is currently enabled (TTY + not disabled by env).
+      def enabled?
+        return @enabled unless @enabled.nil?
+        @enabled = compute_enabled
+      end
+
+      # Force-enable (for testing). Pass nil to restore auto-detect.
+      def override_enabled(value)
+        @enabled = value
+      end
+
+      # RGB tuple for a role, or nil if unknown.
+      def rgb_for(role)
+        NORD[SEMANTICS[role]]
+      end
+
+      # Colorise `text` with the given semantic role.
+      def color(role, text)
+        return text.to_s unless enabled?
+        rgb = rgb_for(role)
+        return text.to_s unless rgb
+        "\e[38;2;#{rgb[0]};#{rgb[1]};#{rgb[2]}m#{text}\e[0m"
+      end
+
+      # Bold emphasis.
+      def bold(text)
+        return text.to_s unless enabled?
+        "\e[1m#{text}\e[0m"
+      end
+
+      # Dim emphasis.
+      def dim(text)
+        return text.to_s unless enabled?
+        "\e[2m#{text}\e[0m"
+      end
+
+      # The marker in its level color — `❄` tinted by semantic role.
+      def marker(level: :info)
+        bold(color(level, MARKER))
+      end
+
+      # Standard pangea-prefixed log line. Emits to stderr by default.
+      # `level` is a semantic role (info / success / warning / error) and
+      # drives both the snowflake color and the body color.
+      def log(message, level: :info, io: $stderr)
+        io.puts "#{marker(level: level)} #{color(level, message)}"
+      end
+
+      # Structured log with multiple highlighted fragments. Example:
+      #
+      #   Theme.structured_log(
+      #     [:info,      'Synthesizing'],
+      #     [:path,      '/path/to/template.rb'],
+      #     [:deprecation, 'in namespace'],
+      #     [:namespace, 'development'],
+      #   )
+      #
+      # Produces: `❄ Synthesizing /path/to/template.rb in namespace development`
+      # with the snowflake in the info color and each token colored per its role.
+      def structured_log(*parts, io: $stderr, marker_level: :info)
+        body = parts.map { |(role, text)| color(role, text) }.join(' ')
+        io.puts "#{marker(level: marker_level)} #{body}"
+      end
+
+      # Section divider with snowflake title. Used to separate synth/init/
+      # plan/apply phases when the output would otherwise run together.
+      # Shape: `❄ title ─────────────────────`
+      def section(title, io: $stderr, width: 72, level: :heading)
+        label = " #{title} "
+        head = "#{marker(level: level)}#{color(level, label)}"
+        # account for the marker glyph + space that don't count toward Nord widths
+        trailing_len = [width - label.length - 2, 4].max
+        trailing = '─' * trailing_len
+        io.puts "#{head}#{color(:divider, trailing)}"
+      end
+
+      # Action glyph + color for a planned change. Returns a two-character
+      # colored string suitable for inline use (e.g., "  #{glyph} addr").
+      def action_glyph(action)
+        glyph, role = case action
+                      when 'create'  then ['+', :create]
+                      when 'update'  then ['~', :update]
+                      when 'delete'  then ['-', :delete]
+                      when 'replace' then ['±', :replace]
+                      when 'read'    then ['>', :read]
+                      when 'import'  then ['→', :import]
+                      when 'no-op'   then ['=', :noop]
+                      else                ['?', :info]
+                      end
+        color(role, glyph)
+      end
+
+      # Status glyphs for apply progress (inherit action colors via semantics).
+      def progress_glyph = color(:info, '➜')
+      def success_glyph  = color(:success, '✔')
+      def error_glyph    = color(:error, '✗')
+
+      # Pretty-print a count with semantic color. Zero counts are muted.
+      def count(n, role: :count)
+        text = n.to_s
+        if n.to_i.zero?
+          color(:deprecation, text)
+        else
+          color(role, text)
+        end
+      end
+
+      class << self
+        private
+
+        def compute_enabled
+          return false if ENV['NO_COLOR']
+          return false if ENV['PANGEA_NO_COLOR']
+          return false if ENV['TERM'] == 'dumb'
+          $stderr.tty? || $stdout.tty?
+        end
+      end
+    end
+  end
+end

data/lib/pangea/cli/tofu_events.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'theme'
+
+module Pangea
+  class CLI
+    # Parses and renders the NDJSON event stream from
+    # `tofu plan -json` / `tofu apply -json` / `tofu destroy -json`.
+    #
+    # OpenTofu's -json flag emits one JSON object per line. Each event has
+    # `@level`, `@message`, `@timestamp`, and `type` fields, plus
+    # type-specific payload. Parsing the stream structurally (instead of
+    # grep'ing human-readable output) lets us:
+    #
+    # - Filter deprecation warnings (inline_policy, etc.) by matching on
+    #   diagnostic.summary, not by string regex over arbitrary output.
+    # - Classify errors as transient (eventual consistency, throttling,
+    #   service unavailable) vs permanent, by inspecting diagnostic.detail.
+    # - Render a clean, Nord-themed human summary across plan / apply /
+    #   destroy with per-resource change glyphs and elapsed timings.
+    # - Feed the event stream into higher-level orchestration (audit logs,
+    #   retry decisions, telemetry) as a typed data structure.
+    #
+    # When `PANGEA_VERBOSE=1` is set, operations.rb bypasses this module
+    # and runs tofu in pass-through mode for full debug output.
+    module TofuEvents
+      # Diagnostic message patterns that indicate a transient failure —
+      # safe to retry. We match against both `summary` and `detail`.
+      TRANSIENT_ERROR_PATTERNS = [
+        /NoSuchEntity/,          # IAM eventual consistency (role not yet visible)
+        /InvalidClientTokenId/,  # IAM creds not yet propagated
+        /Throttling/,            # API rate limit
+        /RequestLimitExceeded/,  # API rate limit
+        /RequestTimeout/,        # Transient timeout
+        /InternalFailure/,       # AWS internal
+        /ServiceUnavailable/,    # Service outage
+      ].freeze
+
+      # Warning summaries to drop from human output. These are known,
+      # understood, and not actionable at the user level.
+      DROPPED_WARNING_PATTERNS = [
+        /inline_policy is deprecated/,
+        /Argument is deprecated/,
+      ].freeze
+
+      # One parsed event from the NDJSON stream.
+      class Event
+        attr_reader :raw
+
+        def initialize(hash)
+          @raw = hash
+        end
+
+        def type        = @raw['type']
+        def level       = @raw['@level']
+        def message     = @raw['@message']
+        def timestamp   = @raw['@timestamp']
+        def diagnostic  = @raw['diagnostic']
+        def hook        = @raw['hook']
+        def change      = @raw['change']
+        def changes     = @raw['changes']
+        def operation   = @raw['operation']
+
+        def diagnostic? = type == 'diagnostic'
+
+        def transient_error?
+          return false unless diagnostic?
+          d = diagnostic
+          return false if d.nil? || d['severity'] != 'error'
+          blob = "#{d['summary']} #{d['detail']}"
+          TRANSIENT_ERROR_PATTERNS.any? { |p| blob.match?(p) }
+        end
+
+        def dropped_warning?
+          return false unless diagnostic?
+          d = diagnostic
+          return false if d.nil? || d['severity'] != 'warning'
+          summary = d['summary'].to_s
+          DROPPED_WARNING_PATTERNS.any? { |p| summary.match?(p) }
+        end
+
+        def resource_address
+          (hook || {}).dig('resource', 'addr') \
+            || (change || {}).dig('resource', 'addr')
+        end
+      end
+
+      # Accumulates events and exposes summary information.
+      class Collector
+        attr_reader :events, :transient_errors,
+                    :plan_summary, :apply_summary,
+                    :dropped_warnings
+
+        def initialize
+          @events = []
+          @transient_errors = []
+          @dropped_warnings = []
+          @plan_summary = nil
+          @apply_summary = nil
+        end
+
+        def consume(event)
+          @events << event
+          @transient_errors << event if event.transient_error?
+          @dropped_warnings << event if event.dropped_warning?
+
+          if event.type == 'change_summary'
+            changes = event.changes || {}
+            # OpenTofu emits `operation` inside the `changes` hash, not at
+            # event root. Fall back to top-level for forward compat.
+            op = changes['operation'] || event.operation
+            if op == 'plan'
+              @plan_summary = changes
+            elsif op == 'apply'
+              @apply_summary = changes
+            end
+          end
+        end
+
+        def any_transient_errors? = !@transient_errors.empty?
+
+        # Nord-themed one-line summary. Zero counts are muted, non-zero
+        # counts use semantic colors (create=green, change=cyan, destroy=red).
+        def summary_line
+          t = Theme
+          if @apply_summary
+            a, c, r = @apply_summary.values_at('add', 'change', 'remove').map(&:to_i)
+            "#{t.bold(t.color(:heading, 'Apply:'))} " \
+              "#{t.color(:create, a)} added, " \
+              "#{t.color(:update, c)} changed, " \
+              "#{t.color(:delete, r)} destroyed"
+          elsif @plan_summary
+            a, c, r = @plan_summary.values_at('add', 'change', 'remove').map(&:to_i)
+            if (a + c + r).zero?
+              t.bold(t.color(:heading, 'Plan: No changes.'))
+            else
+              "#{t.bold(t.color(:heading, 'Plan:'))} " \
+                "#{t.color(:create, a)} to add, " \
+                "#{t.color(:update, c)} to change, " \
+                "#{t.color(:delete, r)} to destroy"
+            end
+          end
+        end
+      end
+
+      module_function
+
+      # Render a single event as a one-line human-readable string, or nil
+      # if the event is not user-facing (dropped warnings, internal logs).
+      # Output is Nord-themed via Pangea::CLI::Theme.
+      def render_human(event)
+        return nil if event.dropped_warning?
+
+        case event.type
+        when 'version', 'log', 'change_summary',
+             'refresh_start', 'refresh_complete', 'apply_progress',
+             'outputs'
+          # Omitted from output. `outputs` (the type event, not state
+          # outputs) is redundant with the change_summary.
+          nil
+        when 'planned_change'
+          action = event.change&.dig('action')
+          addr = event.resource_address
+          return nil unless action && addr
+          "  #{Theme.action_glyph(action)} #{Theme.color(:resource, addr)}"
+        when 'apply_start'
+          addr = event.resource_address
+          addr ? "  #{Theme.progress_glyph} #{Theme.color(:resource, addr)}" : nil
+        when 'apply_complete'
+          addr = event.resource_address
+          addr ? "  #{Theme.success_glyph} #{Theme.color(:resource, addr)}" : nil
+        when 'apply_errored'
+          addr = event.resource_address
+          err = event.hook&.dig('error')
+          body = err ? "#{Theme.color(:resource, addr)}: #{Theme.color(:error, err)}" \
+                     : Theme.color(:resource, addr.to_s)
+          "  #{Theme.error_glyph} #{body}"
+        when 'diagnostic'
+          d = event.diagnostic
+          return nil if d.nil?
+          severity = d['severity'].to_s
+          role = case severity
+                 when 'error'   then :error
+                 when 'warning' then :warning
+                 else :info
+                 end
+          prefix = Theme.color(role, "[#{severity.upcase}]")
+          lines = ["#{prefix} #{Theme.color(:resource, d['summary'])}"]
+          detail = d['detail'].to_s
+          unless detail.empty?
+            # Indent the detail with a subtle left-bar for visual grouping.
+            detail.lines.each do |dl|
+              lines << "  #{Theme.color(:divider, '│')} #{Theme.color(role, dl.chomp)}"
+            end
+          end
+          lines.join("\n")
+        else
+          event.message if event.level != 'info'
+        end
+      end
+
+      # Parse one NDJSON line. Returns an Event, or nil if the line is not
+      # valid JSON (tofu sometimes emits non-JSON prelude lines — notably
+      # the "Initializing the backend..." text during `tofu init` which
+      # doesn't support -json).
+      def parse_line(line)
+        return nil if line.nil? || line.empty?
+        Event.new(JSON.parse(line))
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Run `cmd` with args, streaming -json output. Yields each Event to
+      # the block if given, otherwise collects silently. Returns the
+      # Collector regardless. Exit status is available via $?.
+      def stream(cmd, args)
+        collector = Collector.new
+        IO.popen([cmd, *args], err: %i[child out]) do |io|
+          io.each_line do |line|
+            line = line.chomp
+            event = parse_line(line)
+            if event.nil?
+              # Non-JSON passthrough (rare, but tofu init etc. may emit
+              # human-readable text before the JSON stream begins).
+              yield_raw(line) if block_given?
+              next
+            end
+            collector.consume(event)
+            yield event if block_given?
+          end
+        end
+        collector
+      end
+
+      # Helper for yield_raw — overridable in specs. Default: echo to stderr.
+      def yield_raw(line)
+        $stderr.puts line unless line.strip.empty?
+      end
+    end
+  end
+end

data/lib/pangea/cli.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative 'cli/config'
+require_relative 'cli/synthesizer'
+require_relative 'cli/operations'
+require_relative 'cli/cascade'
+require_relative 'cli/orchestrate'
+
+module Pangea
+  # CLI for the Pangea IaC DSL.
+  #
+  # Synthesizes Ruby templates into Terraform JSON and runs tofu operations.
+  #
+  #   pangea plan template.rb --namespace development
+  #   pangea apply template.rb --namespace production
+  #   pangea destroy template.rb --namespace development
+  #   pangea synth template.rb  # synthesis only
+  #   pangea bulk plan --namespace development  # all .rb templates in cwd
+  #   pangea orchestrate distribution.rb --backend magma
+  #
+  class CLI
+    OPERATIONS = %w[plan apply destroy synth output init bulk orchestrate].freeze
+
+    HELP = <<~HELP
+      Usage: pangea <operation> <template.rb> [--namespace <ns>] [--depth <n>]
+
+      Operations:
+        plan         Synthesize + tofu plan
+        apply        Synthesize + tofu apply -auto-approve
+        destroy      Synthesize + tofu destroy -auto-approve
+        synth        Synthesize only (write JSON, no tofu)
+        output       Run tofu output -json on existing workspace
+        init         Synthesize + tofu init (no plan/apply)
+        bulk         Run operation on all .rb templates in a directory
+        orchestrate  Drive `magma flow run` over a Pangea::Magma::Orchestrator
+                     / Chain / Distribution declared in the template file.
+                     Flags: --backend (magma|tofu), --only foo,bar, --dry-run.
+
+      Bulk usage:
+        pangea bulk <operation> [--namespace <ns>] [--dir <path>]
+
+      Options:
+        --namespace, -n   Namespace (overrides pangea.yml default_namespace)
+        --dir, -d         Directory for bulk operations (default: current dir)
+        --depth, -D <n>   Cap cascade depth (0 = seed only, 1 = direct
+                          neighbors, nil = unlimited). Default resolves from
+                          PANGEA_CASCADE_DEPTH → workspace pangea.yml
+                          cascade.default_depth → root pangea.yml same →
+                          unlimited.
+        --no-cascade      Run seed workspace only; same as PANGEA_NO_CASCADE=1
+        --help, -h        Show this help
+
+      Per-workspace cascade actions (pangea.yml `cascade` block):
+        default_depth: N               — default depth for this workspace
+        pre_actions:  [synth, output, init]  — run before primary command
+        post_actions: [synth, output, init]  — run after  primary command
+      Note: pre/post actions cannot name plan/apply/destroy/deploy.
+    HELP
+
+    class << self
+      def run(argv = ARGV.dup)
+        operation, template_file, namespace, bulk_dir, options = parse(argv)
+
+        case operation
+        when 'bulk'
+          run_bulk(template_file, namespace, bulk_dir)
+        when 'orchestrate'
+          Orchestrate.run(template_file, backend: options[:backend],
+                          only: options[:only], dry_run: options[:dry_run])
+        else
+          run_single(operation, template_file, namespace, options)
+        end
+      end
+
+      private
+
+      def run_single(operation, template_file, namespace, options = {})
+        # plan / apply / destroy on a template that participates in
+        # reactive relationships cascades across the constellation in
+        # dependency order. Other operations (synth/output/init) stay
+        # single-workspace — they don't materially change infra state.
+        cascade_ops = %w[plan apply destroy]
+        if cascade_ops.include?(operation) && options[:no_cascade] != true
+          cascade = Cascade.for_template(template_file, max_depth: options[:depth])
+          if cascade
+            case operation
+            when 'plan'    then return cascade.plan(namespace: namespace)
+            when 'apply'   then return cascade.apply(namespace: namespace)
+            when 'destroy' then return cascade.destroy(namespace: namespace)
+            end
+          end
+        end
+
+        config = Config.new(template_file, namespace: namespace)
+        ops = Operations.new(config)
+
+        case operation
+        when 'synth'  then ops.synth(json_output: true)
+        when 'plan'   then ops.plan
+        when 'apply'  then ops.apply
+        when 'destroy' then ops.destroy
+        when 'output' then ops.output
+        when 'init'   then ops.init
+        else raise "Unknown operation: #{operation}"
+        end
+      end
+
+      def run_bulk(sub_operation, namespace, dir)
+        dir ||= Dir.pwd
+        templates = Dir.glob(File.join(dir, '*.rb'))
+
+        if templates.empty?
+          $stderr.puts "[pangea] No .rb template files found in #{dir}"
+          exit 1
+        end
+
+        templates.each do |tmpl|
+          $stderr.puts "==> #{sub_operation}: #{File.basename(tmpl)}"
+          run_single(sub_operation, tmpl, namespace)
+        end
+      end
+
+      def parse(argv)
+        operation = argv.shift
+
+        if operation.nil? || %w[--help -h].include?(operation)
+          $stderr.puts HELP
+          exit(operation.nil? ? 1 : 0)
+        end
+
+        unless OPERATIONS.include?(operation)
+          $stderr.puts "Error: unknown operation '#{operation}'"
+          $stderr.puts HELP
+          exit 1
+        end
+
+        namespace = extract_flag(argv, '--namespace', '-n')
+        bulk_dir = extract_flag(argv, '--dir', '-d')
+        depth_raw = extract_flag(argv, '--depth', '-D')
+        no_cascade = extract_switch(argv, '--no-cascade')
+        backend = extract_flag(argv, '--backend', '-b')
+        only_raw = extract_flag(argv, '--only', '-o')
+        dry_run = extract_switch(argv, '--dry-run')
+
+        options = {
+          depth: parse_depth(depth_raw),
+          no_cascade: no_cascade,
+          backend: backend,
+          only: only_raw ? only_raw.split(',').map(&:to_sym) : nil,
+          dry_run: dry_run,
+        }
+
+        if operation == 'bulk'
+          # For bulk: first remaining arg is the sub-operation
+          sub_operation = argv.shift
+          unless sub_operation && %w[plan apply destroy synth init].include?(sub_operation)
+            $stderr.puts "Error: bulk requires a sub-operation (plan, apply, destroy, synth, init)"
+            exit 1
+          end
+          [operation, sub_operation, namespace, bulk_dir, options]
+        else
+          template_file = argv.shift
+          unless template_file
+            $stderr.puts "Error: template file required"
+            exit 1
+          end
+          unless File.exist?(template_file)
+            $stderr.puts "Error: template file not found: #{template_file}"
+            exit 1
+          end
+          [operation, template_file, namespace, nil, options]
+        end
+      end
+
+      def extract_flag(argv, long, short)
+        idx = argv.index(long) || argv.index(short)
+        return nil unless idx
+
+        argv.delete_at(idx) # remove flag
+        argv.delete_at(idx) # remove value (now at same index)
+      end
+
+      def extract_switch(argv, long)
+        idx = argv.index(long)
+        return false unless idx
+
+        argv.delete_at(idx)
+        true
+      end
+
+      # Parse a --depth CLI value. Accepts non-negative ints; rejects
+      # garbage with a clear error so users don't silently fall through
+      # to "unlimited" on a typo.
+      def parse_depth(raw)
+        return nil if raw.nil?
+
+        Integer(raw, 10).tap do |n|
+          if n.negative?
+            $stderr.puts "Error: --depth must be >= 0 (got #{raw})"
+            exit 1
+          end
+        end
+      rescue ArgumentError, TypeError
+        $stderr.puts "Error: --depth must be an integer (got #{raw.inspect})"
+        exit 1
+      end
+    end
+  end
+end