pangea-core 0.2.0 → 0.3.0

data/lib/pangea/magma/workspace.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Pangea
+  module Magma
+    # Typed Pangea workspace declaration — the M0.1 primitive that
+    # mirrors `magma_pangea::workspace::Workspace` (the Rust trait).
+    # Per theory/PANGEA-MAGMA-ORCHESTRATION.md §III.1.
+    #
+    # Authors:
+    #
+    #   vpc = Pangea::Magma::Workspace.declare(
+    #     name:           :seph_vpc,
+    #     template:       'seph_vpc.rb',
+    #     workspace_dir:  'workspaces/seph-vpc',
+    #     inputs: {
+    #       cidr_block: { type: String, default: '10.0.0.0/16' },
+    #     },
+    #     outputs: {
+    #       vpc_id:    { type: String, sensitive: false },
+    #       subnet_id: { type: String },
+    #     },
+    #     requires: {
+    #       input_format: 'terraform-json',
+    #     },
+    #   )
+    #
+    # Then composes into a Chain (see chain.rb) for multi-workspace
+    # orchestration. Each Workspace consumes magma-arch-test under the
+    # hood via Pangea::Magma.verify_workspace.
+    class Workspace
+      # Typed slot — input or output declaration.
+      Slot = Struct.new(:name, :type, :default, :sensitive, :description,
+                        keyword_init: true) do
+        def to_h
+          { name: name, type: type.to_s,
+            default: default, sensitive: sensitive,
+            description: description }.compact
+        end
+      end
+
+      # Typed requirements — checked at orchestration build time via
+      # Pangea::Backend.verify_compatible! against the chosen backend.
+      Requires = Struct.new(:feature, :input_format, keyword_init: true) do
+        def to_h
+          { feature: feature, input_format: input_format }.compact
+        end
+
+        def empty?
+          feature.nil? && input_format.nil?
+        end
+      end
+
+      # Default requires for every Pangea-rendered workspace. Most
+      # workspaces target the terraform-json input format; declaring
+      # this on every workspace is boilerplate, so we make it the
+      # default and let exotic workspaces override it.
+      DEFAULT_REQUIRES = { input_format: 'terraform-json' }.freeze
+
+      class << self
+        # Build a typed Workspace declaration. Raises ArgumentError if
+        # the declaration is malformed.
+        def declare(name:, template:, workspace_dir:,
+                    inputs: {}, outputs: {}, requires: DEFAULT_REQUIRES)
+          raise ArgumentError, 'name required (Symbol or String)' if name.nil?
+          raise ArgumentError, 'template required' if template.nil?
+          raise ArgumentError, 'workspace_dir required' if workspace_dir.nil?
+
+          new(
+            name:          name.to_sym,
+            template:      template.to_s,
+            workspace_dir: workspace_dir.to_s,
+            inputs:        coerce_slots(inputs),
+            outputs:       coerce_slots(outputs),
+            requires:      Requires.new(**requires),
+          )
+        end
+
+        private
+
+        def coerce_slots(decls)
+          decls.transform_values do |decl|
+            decl = decl.dup
+            decl[:type] ||= String
+            Slot.new(**decl)
+          end
+        end
+      end
+
+      attr_reader :name, :template, :workspace_dir, :inputs, :outputs, :requires
+
+      def initialize(name:, template:, workspace_dir:,
+                     inputs:, outputs:, requires:)
+        @name          = name
+        @template      = template
+        @workspace_dir = workspace_dir
+        @inputs        = inputs
+        @outputs       = outputs
+        @requires      = requires
+      end
+
+      # Verify this workspace works under the chosen backend. Routes
+      # through Pangea::Magma.verify_workspace + Pangea::Backend.
+      def verify(backend: 'magma')
+        Pangea::Backend.verify_compatible!(backend, @requires.to_h) unless @requires.empty?
+        Pangea::Magma.verify_workspace(@workspace_dir)
+      end
+
+      # Serialize for magma flow run consumption.
+      def to_h
+        {
+          name:          @name.to_s,
+          template:      @template,
+          workspace_dir: @workspace_dir,
+          inputs:        @inputs.transform_values(&:to_h),
+          outputs:       @outputs.transform_values(&:to_h),
+          requires:      @requires.to_h,
+        }
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+  end
+end

data/lib/pangea/magma.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require_relative 'backend'
+require_relative 'magma/runner'
+
+module Pangea
+  # Ruby wrapper around the `magma` CLI's fixture / capabilities surface.
+  #
+  # Per theory/MAGMA.md §II.8 interface 1 (drop-in CLI), §II.11 (backend
+  # auto-discovery), and §II.6 (test corpus). This module exists so
+  # pangea-* gems' rspec suites can verify "this workspace works under
+  # magma" with one matcher invocation — no shelling out manually, no
+  # JSON parsing per consumer.
+  #
+  # # Usage
+  #
+  #   require 'pangea/magma'
+  #
+  #   # Direct API:
+  #   report = Pangea::Magma.verify_workspace('workspaces/seph-vpc')
+  #   report['resource_change_count'] # => 3
+  #   report['providers']             # => ["hashicorp/aws"]
+  #
+  #   # Or rspec matchers (require 'pangea/magma/matchers'):
+  #   it 'plans cleanly under magma' do
+  #     expect('workspaces/seph-vpc').to plan_cleanly_under_magma
+  #   end
+  #
+  # # Binary resolution
+  #
+  # `MAGMA_BINARY` env var overrides the binary path. Default is `magma`
+  # (PATH lookup). When magma isn't installed, `installed?` returns
+  # false and rspec matchers skip-with-print rather than failing hard
+  # so CI on machines without magma doesn't break.
+  module Magma
+    class << self
+      # Path to the magma binary. Override via `MAGMA_BINARY` env var.
+      def binary
+        @binary ||= ENV['MAGMA_BINARY'] || 'magma'
+      end
+
+      attr_writer :binary
+
+      # True if the magma binary is reachable + responsive.
+      def installed?
+        return @installed unless @installed.nil?
+        _out, _err, status = Open3.capture3(binary, '--version')
+        @installed = status.success?
+      rescue Errno::ENOENT
+        @installed = false
+      end
+
+      # Probe magma's capability manifest. Returns the parsed JSON
+      # Hash (matching the schema in theory/MAGMA.md §II.11) or
+      # raises Pangea::Backend::BackendUnavailable if magma isn't on PATH.
+      def capabilities
+        @capabilities ||= probe_capabilities
+      end
+
+      # Verify a single workspace (directory or single `.tf.json` file).
+      # Returns the parsed WorkspaceReport Hash; raises VerificationFailed
+      # on non-zero exit.
+      def verify_workspace(path)
+        Runner.invoke('fixture', argv_extras: ['verify', path.to_s])
+      rescue Runner::SubprocessError => e
+        raise VerificationFailed, e.message
+      end
+
+      # Verify every `.tf.json` under `dir`. Returns the parsed
+      # AggregateReport Hash with passed/failed counts + per-workspace
+      # breakdown. Allow exit=1 since the CLI still emits JSON when
+      # some fixtures fail.
+      def verify_directory(dir)
+        Runner.invoke('fixture', argv_extras: ['verify-dir', dir.to_s],
+                      allow_exit: [1])
+      rescue Runner::SubprocessError => e
+        raise VerificationFailed, e.message
+      end
+
+      # Drive `magma flow run <flow.json>` and parse the AggregateReport.
+      # `flow` is the typed flow shape (workspaces + edges); see
+      # `magma-flow` / theory/PANGEA-MAGMA-ORCHESTRATION.md §IV.
+      def flow(flow_hash)
+        Runner.invoke('flow', json_arg: flow_hash)
+      rescue Runner::SubprocessError => e
+        raise VerificationFailed, e.message
+      end
+
+      # Drive `magma migrate <plan.json>` and parse the MigrationReceipt.
+      # `plan` is the typed magma_migrate::MigrationPlan shape.
+      def migrate(plan_hash)
+        Runner.invoke('migrate', json_arg: plan_hash)
+      rescue Runner::SubprocessError => e
+        raise VerificationFailed, e.message
+      end
+
+      # Drive `magma split` directly. `args` keys:
+      # `:from, :from_state, :to, :to_state, :resources (Array<String>), :dry_run (bool)`.
+      def split(args)
+        extras = ['--from',       args.fetch(:from).to_s,
+                  '--from-state', args.fetch(:from_state).to_s,
+                  '--to',         args.fetch(:to).to_s,
+                  '--to-state',   args.fetch(:to_state).to_s]
+        Array(args.fetch(:resources, [])).each { |r| extras += ['--resource', r] }
+        extras << '--dry-run' if args[:dry_run]
+        Runner.invoke('split', argv_extras: extras)
+      rescue Runner::SubprocessError => e
+        raise VerificationFailed, e.message
+      end
+
+      # Drive `magma merge` directly. `args` keys:
+      # `:from, :from_state, :to, :to_state, :dry_run (bool)`.
+      def merge(args)
+        extras = ['--from',       args.fetch(:from).to_s,
+                  '--from-state', args.fetch(:from_state).to_s,
+                  '--to',         args.fetch(:to).to_s,
+                  '--to-state',   args.fetch(:to_state).to_s]
+        extras << '--dry-run' if args[:dry_run]
+        Runner.invoke('merge', argv_extras: extras)
+      rescue Runner::SubprocessError => e
+        raise VerificationFailed, e.message
+      end
+
+      # Reset memoization — for tests that mutate MAGMA_BINARY env.
+      def reset!
+        @installed = nil
+        @binary = nil
+        @capabilities = nil
+      end
+
+      private
+
+      def probe_capabilities
+        Runner.invoke('capabilities')
+      rescue Runner::SubprocessError => e
+        raise Pangea::Backend::BackendUnavailable,
+              "magma capabilities failed (exit #{e.exit_code})"
+      rescue Errno::ENOENT
+        raise Pangea::Backend::BackendUnavailable, "magma binary not on PATH"
+      end
+    end
+
+    # Base class for every Pangea::Magma-raised error. Lets callers
+    # `rescue Pangea::Magma::Error` for any magma subprocess failure
+    # (verify, flow, migrate, split, merge, capabilities, …).
+    class Error < StandardError; end
+
+    # Raised when `magma fixture verify` / `verify-dir` reports a
+    # non-recoverable failure (subprocess crashed, JSON malformed, etc.).
+    # `WorkspaceReport.compatibility.plans_cleanly = false` does NOT
+    # raise — it's a typed status surfaced via the matcher.
+    class VerificationFailed < Error; end
+  end
+end

data/lib/pangea/outputs.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Pangea
+  # Output category management for Terraform templates.
+  #
+  # Outputs are classified into categories that can be independently toggled:
+  #
+  #   :display  — Human-readable info (cluster_name, backend type)
+  #   :data     — Machine-consumable values for cross-template wiring (vpc_id, role_arn)
+  #
+  # Configuration is set on the synthesizer context before outputs are declared:
+  #
+  #   # In template:
+  #   self.pangea_output_config = { display: true, data: true }  # default: all on
+  #   self.pangea_output_config = { display: false, data: true }  # suppress display
+  #   self.pangea_output_config = { display: false, data: false } # suppress all
+  #
+  #   pangea_output :cluster_name, category: :display do
+  #     value cluster_name
+  #     description "K3s cluster name"
+  #   end
+  #
+  #   pangea_output :vpc_id, category: :data do
+  #     value result.network.vpc.id
+  #     description "VPC ID"
+  #   end
+  #
+  # When a category is disabled, the output block is not emitted to Terraform JSON.
+  #
+  module Outputs
+    # Default: all outputs enabled
+    DEFAULT_CONFIG = { display: true, data: true }.freeze
+
+    # Set output rendering configuration.
+    # Called on the synthesizer context (self in a template).
+    def pangea_output_config=(config)
+      @_pangea_output_config = DEFAULT_CONFIG.merge(config)
+    end
+
+    # Get current output configuration.
+    def pangea_output_config
+      @_pangea_output_config || DEFAULT_CONFIG.dup
+    end
+
+    # Declare a categorized output.
+    #
+    # @param name [Symbol] Output name (e.g., :vpc_id)
+    # @param category [Symbol] :display or :data (default: :data)
+    # @param block [Block] Output body (value, description, sensitive)
+    #
+    # The output is only emitted if its category is enabled in pangea_output_config.
+    # If no category is specified, defaults to :data (always emitted unless data is off).
+    def pangea_output(name, category: :data, &block)
+      config = pangea_output_config
+
+      # Master kill switch: if ALL categories are off, emit nothing
+      return if config.values.none?
+
+      # Category-specific toggle
+      return unless config.fetch(category, true)
+
+      # Delegate to the synthesizer's native output method
+      output(name, &block)
+    end
+
+    # Convenience: declare a display-only output.
+    def display_output(name, &block)
+      pangea_output(name, category: :display, &block)
+    end
+
+    # Convenience: declare a data output (for cross-template wiring).
+    def data_output(name, &block)
+      pangea_output(name, category: :data, &block)
+    end
+
+    # Suppress all outputs (useful for module mode where outputs are internal).
+    def suppress_all_outputs!
+      self.pangea_output_config = { display: false, data: false }
+    end
+
+    # Suppress only display outputs (keep data for wiring).
+    def suppress_display_outputs!
+      self.pangea_output_config = { display: false, data: true }
+    end
+
+    # Enable all outputs (default state).
+    def enable_all_outputs!
+      self.pangea_output_config = { display: true, data: true }
+    end
+  end
+end

data/lib/pangea/presets.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Pangea
+  # Preset composition for infrastructure configurations.
+  #
+  # Presets are frozen hashes of configuration overrides that can be composed
+  # (stacked) and merged with user config. Later values win.
+  #
+  # Usage in architectures:
+  #
+  #   module MyArchitecture
+  #     PROFILES = {
+  #       dev:        { encryption: 'AES256', versioning: false }.freeze,
+  #       production: { encryption: 'aws:kms', versioning: true }.freeze,
+  #     }.freeze
+  #
+  #     def self.build(synth, config = {})
+  #       config = Pangea::Presets.apply(config, PROFILES)
+  #       # config[:profile] consumed, defaults merged, user overrides on top
+  #     end
+  #   end
+  #
+  module Presets
+    # Apply a named profile to a config hash.
+    #
+    # Extracts :profile key from config, looks it up in profiles hash,
+    # deep-merges the profile defaults under user config (user wins).
+    #
+    # @param config [Hash] User configuration (may contain :profile key)
+    # @param profiles [Hash] Map of profile name → frozen defaults hash
+    # @param default_profile [Symbol] Fallback profile if none specified
+    # @return [Hash] Merged config with profile defaults applied
+    def self.apply(config, profiles, default_profile: :dev)
+      config = config.dup
+      profile_name = config.delete(:profile) || default_profile
+      profile = profiles[profile_name]
+
+      raise ArgumentError, "Unknown profile :#{profile_name}. Available: #{profiles.keys.join(', ')}" unless profile
+
+      deep_merge(profile, config)
+    end
+
+    # Compose multiple preset hashes into one (left-to-right, later wins).
+    #
+    # @param presets [Array<Hash>] Preset hashes to merge
+    # @return [Hash] Composed preset (frozen)
+    def self.compose(*presets)
+      presets.reduce({}) { |acc, p| deep_merge(acc, p) }.freeze
+    end
+
+    # Deep merge two hashes. Values from `overlay` win over `base`.
+    # Nested hashes are recursively merged; all other types are replaced.
+    #
+    # @param base [Hash]
+    # @param overlay [Hash]
+    # @return [Hash]
+    def self.deep_merge(base, overlay)
+      base.merge(overlay) do |_key, base_val, overlay_val|
+        if base_val.is_a?(Hash) && overlay_val.is_a?(Hash)
+          deep_merge(base_val, overlay_val)
+        else
+          overlay_val
+        end
+      end
+    end
+  end
+end

data/lib/pangea/provider_contract.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Pangea
+  # Contract that all provider modules must satisfy.
+  # Validates that a provider gem exposes the expected interface
+  # for cross-provider composition in pangea-architectures.
+  #
+  # Usage:
+  #   Pangea::ProviderContract.validate!(Pangea::Resources::AWS)
+  #
+  module ProviderContract
+    class ViolationError < StandardError; end
+
+    # Validate that a module satisfies the provider contract.
+    #
+    # A valid provider module must:
+    # 1. Be a Module (not a Class)
+    # 2. Define at least one resource method (matching its prefix)
+    # 3. Be extendable onto a synthesizer object
+    #
+    # @param provider_module [Module] The provider module to validate
+    # @param prefix [String] Expected resource method prefix (e.g., 'aws_')
+    # @raise [ViolationError] if the contract is not satisfied
+    def self.validate!(provider_module, prefix: nil)
+      unless provider_module.is_a?(Module) && !provider_module.is_a?(Class)
+        raise ViolationError, "#{provider_module} must be a Module, got #{provider_module.class}"
+      end
+
+      if prefix
+        methods = provider_module.instance_methods(false)
+        matching = methods.select { |m| m.to_s.start_with?(prefix) }
+        if matching.empty?
+          raise ViolationError, "#{provider_module} has no methods starting with '#{prefix}'"
+        end
+      end
+    end
+
+    # Check without raising — returns [valid?, errors]
+    def self.check(provider_module, prefix: nil)
+      validate!(provider_module, prefix: prefix)
+      [true, []]
+    rescue ViolationError => e
+      [false, [e.message]]
+    end
+
+    # Provider metadata for introspection
+    module Metadata
+      def provider_prefix
+        raise NotImplementedError, "#{self} must define provider_prefix"
+      end
+
+      def resource_count
+        instance_methods(false).count { |m| m.to_s.start_with?(provider_prefix) }
+      end
+
+      def resource_names
+        instance_methods(false).select { |m| m.to_s.start_with?(provider_prefix) }.sort
+      end
+    end
+  end
+end

data/lib/pangea/remote_state.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Pangea
+  # Cross-template state references — reads outputs directly from S3 state.
+  #
+  # No Terraform data sources needed. At synthesis time, reads the other
+  # template's .tfstate from S3, extracts the output value, and returns
+  # it as a literal string. This makes cross-template wiring simple and
+  # dependency-free.
+  #
+  # Usage in a template:
+  #   vpc_id = Pangea::RemoteState.from_template(ws,
+  #     template: 'akeyless-dev-cluster',
+  #     output: :vpc_id,
+  #   )
+  #   # => "vpc-06b5744a5287e2d47" (actual VPC ID from state)
+  #
+  # Or with explicit config:
+  #   vpc_id = Pangea::RemoteState.output(
+  #     template: 'akeyless-dev-cluster',
+  #     output: :vpc_id,
+  #     bucket: 'pangea-terraform-state-376129857990',
+  #     region: 'us-east-1',
+  #   )
+  #
+  module RemoteState
+    # Track implicit dependencies between templates.
+    @dependencies = {}
+
+    class << self
+      attr_reader :dependencies
+
+      # Read an output directly from another template's S3 state file.
+      #
+      # @param template [String] Source template name (state key prefix)
+      # @param output [Symbol, String] Output name to read
+      # @param bucket [String] S3 bucket name (optional if root_config set)
+      # @param region [String] AWS region (optional if root_config set)
+      # @param state_key [String] Override state key (default: pangea convention)
+      # @return [String, nil] The output value, or nil if not found
+      def output(template:, output:, bucket: nil, region: nil, state_key: nil)
+        bucket ||= @root_bucket
+        region ||= @root_region || 'us-east-1'
+
+        raise ArgumentError, "No bucket configured. Call RemoteState.configure or pass bucket:" unless bucket
+
+        # Pangea convention: pangea/{workspace}/{template}/terraform.tfstate
+        key = state_key || "pangea/#{template}/#{template.tr('-', '_')}/terraform.tfstate"
+        state = fetch_state(bucket: bucket, key: key, region: region)
+        return nil unless state
+
+        # Track dependency
+        @dependencies[template] ||= []
+
+        extract_output(state, output.to_s)
+      end
+
+      # Simple one-liner: read an output from another template.
+      # Requires configure() to have been called first (or pass bucket/region).
+      #
+      # Usage:
+      #   Pangea::RemoteState.from('akeyless-dev-cluster', :vpc_id)
+      #
+      # @param template [String] Source template name
+      # @param output [Symbol, String] Output name to read
+      # @return [String, nil] The output value
+      def from(template, output)
+        self.output(template: template, output: output)
+      end
+
+      # Configure root state backend defaults (called once at boot).
+      # Templates inherit these — no need to pass bucket/region everywhere.
+      #
+      # @param bucket [String] S3 bucket name
+      # @param region [String] AWS region
+      def configure(bucket:, region: 'us-east-1')
+        @root_bucket = bucket
+        @root_region = region
+      end
+
+      # Read an output using WorkspaceConfig for backend details.
+      # Extracts bucket/region from the root pangea.yml state.s3 config.
+      #
+      # @param ws [Object] Workspace config (any object with state/s3/bucket)
+      # @param template [String] Source template name
+      # @param output [Symbol, String] Output name to read
+      # @return [String, nil] The output value, or nil if not found
+      def from_template(ws, template:, output:)
+        # Try to extract bucket from workspace config hierarchy
+        bucket = extract_bucket(ws)
+        region = extract_region(ws)
+
+        raise ArgumentError, "Cannot determine state bucket from workspace config" unless bucket
+
+        self.output(template: template, output: output, bucket: bucket, region: region)
+      end
+
+      # Get all templates this workspace depends on.
+      #
+      # @return [Hash] Map of template_name => [output_names_read]
+      def dependency_graph
+        @dependencies.dup
+      end
+
+      # Reset (for testing).
+      def reset!
+        @dependencies = {}
+        @root_bucket = nil
+        @root_region = nil
+      end
+
+      private
+
+      # Extract S3 bucket from workspace config (tries multiple paths).
+      def extract_bucket(ws)
+        return @root_bucket if @root_bucket
+
+        # Try: ws.state_config[:bucket], ws.config[:state][:s3][:bucket], etc.
+        if ws.respond_to?(:state_config)
+          sc = ws.state_config rescue nil
+          return sc['bucket'] || sc[:bucket] if sc.is_a?(Hash)
+        end
+
+        # Try root YAML config path: state.s3.bucket
+        if ws.respond_to?(:raw_config)
+          rc = ws.raw_config rescue nil
+          return rc.dig('state', 's3', 'bucket') if rc.is_a?(Hash)
+        end
+
+        nil
+      end
+
+      # Extract region from workspace config.
+      def extract_region(ws)
+        return @root_region if @root_region
+
+        if ws.respond_to?(:state_config)
+          sc = ws.state_config rescue nil
+          return sc['region'] || sc[:region] if sc.is_a?(Hash)
+        end
+
+        if ws.respond_to?(:raw_config)
+          rc = ws.raw_config rescue nil
+          return rc.dig('state', 's3', 'region') if rc.is_a?(Hash)
+        end
+
+        'us-east-1'
+      end
+
+      # Fetch and parse a Terraform state file from S3.
+      def fetch_state(bucket:, key:, region:)
+        # Use AWS CLI to read state (available in all pangea dev shells)
+        cmd = "aws s3 cp s3://#{bucket}/#{key} - --region #{region} 2>/dev/null"
+        json = `#{cmd}`
+        return nil if json.nil? || json.empty? || $?.exitstatus != 0
+
+        JSON.parse(json)
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Extract an output value from parsed Terraform state.
+      def extract_output(state, output_name)
+        # Terraform state format: { "outputs": { "name": { "value": "..." } } }
+        outputs = state.dig('outputs') || {}
+        output_entry = outputs[output_name]
+        return nil unless output_entry
+
+        output_entry['value']
+      end
+    end
+  end
+end