pangea-core 0.1.0 → 0.3.0

data/flake.nix

@@ -2,7 +2,7 @@
   description = "Pangea Core — shared types and utilities for Pangea infrastructure DSL";
 
   inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
     ruby-nix.url = "github:inscapist/ruby-nix";
     flake-utils.url = "github:numtide/flake-utils";
     substrate = {
@@ -14,47 +14,17 @@
       inputs.nixpkgs.follows = "nixpkgs";
       inputs.substrate.follows = "substrate";
     };
+    devenv = {
+      url = "github:cachix/devenv";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
   };
 
-  outputs = {
-    self,
-    nixpkgs,
-    ruby-nix,
-    flake-utils,
-    substrate,
-    forge,
-    ...
-  }:
-    flake-utils.lib.eachSystem ["x86_64-linux" "aarch64-linux" "aarch64-darwin"] (system: let
-      pkgs = import nixpkgs {
-        inherit system;
-        overlays = [ruby-nix.overlays.ruby];
-      };
-      rnix = ruby-nix.lib pkgs;
-      rnix-env = rnix {
-        name = "pangea-core";
-        gemset = ./gemset.nix;
-      };
-      env = rnix-env.env;
-      ruby = rnix-env.ruby;
-
-      rubyBuild = import "${substrate}/lib/ruby-build.nix" {
-        inherit pkgs;
-        forgeCmd = "${forge.packages.${system}.default}/bin/forge";
-        defaultGhcrToken = "";
-      };
-    in {
-      devShells.default = pkgs.mkShell {
-        buildInputs = [env ruby];
-        shellHook = ''
-          export RUBYLIB=$PWD/lib:$RUBYLIB
-          export DRY_TYPES_WARNINGS=false
-        '';
-      };
-
-      apps = rubyBuild.mkRubyGemApps {
-        srcDir = self;
-        name = "pangea-core";
-      };
-    });
+  outputs = { self, nixpkgs, ruby-nix, flake-utils, substrate, forge, ... }:
+    (import "${substrate}/lib/ruby-gem-flake.nix" {
+      inherit nixpkgs ruby-nix flake-utils substrate forge;
+    }) {
+      inherit self;
+      name = "pangea-core";
+    };
 }

data/gemset.nix

@@ -141,7 +141,7 @@
       path = ./.;
       type = "path";
     };
-    version = "0.1.0";
+    version = "0.3.0";
   };
   rake = {
     groups = ["development"];

data/lib/pangea/arch_dsl.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+# Pangea::ArchDsl — the canonical DSL entry point for every Pangea architecture.
+#
+# The Pangea TerraformSynthesizer uses a method_missing DSL where several
+# common invocations silently misbehave:
+#
+#   synth.terraform do ... end
+#     → block runs with self = outer object, NOT synth. `required_providers`
+#       looks up on the calling architecture module and raises NoMethodError.
+#
+#   synth.provider :name, {hash}
+#     → two positional args triggers TooManyFieldValuesError; only block
+#       form is valid.
+#
+#   synth.resource :type, :name, {hash}
+#     → same class of failure; must be `resource :type, :name do ... end`
+#       with block setters.
+#
+#   Pangea::RemoteState.output(state_key: 'pangea/platform-vpc')
+#     → default convention is `pangea/{template}/{tr}/terraform.tfstate`;
+#       explicit overrides hit 404 on the actual bucket layout.
+#
+# This mixin centralizes the correct patterns behind a strongly-typed
+# surface. Architectures include `Pangea::ArchDsl` and call the wrappers
+# below instead of raw synth methods.
+#
+# The bugs this mixin prevents were all encountered during the first
+# platform-eks plan; see STANDARDS.md (pleme-io org root) for the
+# complete rationale.
+
+module Pangea
+  module ArchDsl
+    # ══════════════════════════════════════════════════════════════════
+    # Block-safe DSL evaluation
+    # ══════════════════════════════════════════════════════════════════
+
+    # Run `block` with `synth` as `self` so nested DSL calls like
+    # `terraform do ... end` resolve the way Pangea templates expect.
+    # Closure-over-args is captured explicitly by the caller (pass them
+    # into the block) — inside the block, `self` is the synthesizer.
+    #
+    # @param synth [TerraformSynthesizer]
+    # @yield evaluated with self = synth
+    def self.synth_eval(synth, &block)
+      raise ArgumentError, 'block required' unless block
+      synth.instance_eval(&block)
+    end
+
+    # ══════════════════════════════════════════════════════════════════
+    # Typed data source registration
+    # ══════════════════════════════════════════════════════════════════
+
+    # Register a terraform data source via the synth.data DSL. Uses the
+    # block form with explicit setters so every attr is typed by Pangea's
+    # schema validation path (when the provider gem registers it) or the
+    # raw synth.data path (hand-typed hash) when it does not.
+    #
+    # @param synth    [TerraformSynthesizer]
+    # @param type     [Symbol] terraform data source type (e.g. :aws_network_interface)
+    # @param name     [Symbol, String] local name
+    # @param attrs    [Hash] attribute hash (string values)
+    def self.register_data(synth, type:, name:, attrs:)
+      validate_identifier!(name)
+      captured_attrs = attrs
+      synth.instance_eval do
+        data type do
+          public_send(name) do
+            captured_attrs.each { |k, v| public_send(k, v) }
+          end
+        end
+      end
+    end
+
+    # ══════════════════════════════════════════════════════════════════
+    # Raw resource registration (for providers without typed gems yet)
+    # ══════════════════════════════════════════════════════════════════
+
+    # Register a terraform resource where we don't have a typed Pangea
+    # provider-gem method. Takes explicit meta-arg kwargs so those are
+    # never silently dropped.
+    #
+    # @param synth      [TerraformSynthesizer]
+    # @param type       [Symbol] terraform resource type (e.g. :aws_vpc_endpoint)
+    # @param name       [Symbol, String] local name (canonical underscore form)
+    # @param attrs      [Hash] declared resource attributes
+    # @option meta      :provider    [Symbol, String] provider alias reference
+    # @option meta      :lifecycle   [Hash] lifecycle block
+    # @option meta      :depends_on  [Array<String>] explicit dependencies
+    # @option meta      :count       [Integer, String] count meta-arg
+    # @option meta      :for_each    [String] for_each meta-arg
+    def self.register_raw_resource(synth, type:, name:, attrs:, **meta)
+      validate_identifier!(name)
+      captured_attrs = attrs
+      captured_meta  = meta
+      synth.instance_eval do
+        resource type, name do
+          captured_attrs.each { |k, v| public_send(k, v) }
+          captured_meta.each { |k, v| public_send(k, v) }
+        end
+      end
+    end
+
+    # ══════════════════════════════════════════════════════════════════
+    # RemoteState (defaults the state_key — prevents the 404 class)
+    # ══════════════════════════════════════════════════════════════════
+
+    # Fetch a cross-template output. **Never accepts a state_key override.**
+    # Default convention (pangea/{template}/{tr}/terraform.tfstate) matches
+    # the pangea S3 backend layout exactly; explicit overrides 404.
+    #
+    # @param template [String] upstream template name (e.g. 'platform-vpc')
+    # @param output   [Symbol, String] output key (e.g. :vpc_id)
+    # @return [String, Array, nil]
+    def self.remote_state_output(template:, output:)
+      Pangea::RemoteState.output(template: template, output: output)
+    end
+
+    # ══════════════════════════════════════════════════════════════════
+    # Canonical identifier (resource name)
+    # ══════════════════════════════════════════════════════════════════
+
+    # Canonical resource identifier: underscore-separated, lowercase,
+    # optional suffix. Used for every tf address so downstream references
+    # never drift between hyphen and underscore forms.
+    #
+    # @example
+    #   Pangea::ArchDsl.managed_id('alpha', suffix: 'system_ng')
+    #     # => :alpha_system_ng
+    def self.managed_id(base, suffix: nil)
+      raise ArgumentError, ':base must not be empty' if base.nil? || base.to_s.empty?
+      id = base.to_s.downcase.tr('-', '_')
+      id = "#{id}_#{suffix.to_s.downcase.tr('-', '_')}" if suffix
+      id.to_sym
+    end
+
+    # ══════════════════════════════════════════════════════════════════
+    # Set-safe output ref
+    # ══════════════════════════════════════════════════════════════════
+
+    # Emit `${tolist(aws_X.N.set_attr)[0].element_attr}` for set-returning
+    # terraform attributes. Works around the newer AWS provider where
+    # fields like `certificate_authority` and `identity` are sets
+    # (unindexable) rather than ordered lists.
+    #
+    # @example
+    #   ref_set_first(:aws_eks_cluster, :alpha, :certificate_authority, :data)
+    #     # => "${tolist(aws_eks_cluster.alpha.certificate_authority)[0].data}"
+    def self.ref_set_first(resource_type, resource_name, set_attr, element_attr)
+      "${tolist(#{resource_type}.#{resource_name}.#{set_attr})[0].#{element_attr}}"
+    end
+
+    # ══════════════════════════════════════════════════════════════════
+    # Helpers
+    # ══════════════════════════════════════════════════════════════════
+
+    IDENTIFIER_PATTERN = /\A[a-z0-9_]+\z/
+
+    def self.validate_identifier!(name)
+      s = name.to_s
+      return if s.match?(IDENTIFIER_PATTERN)
+      raise ArgumentError,
+            "identifier '#{s}' must be lowercase snake_case (matching #{IDENTIFIER_PATTERN.source}); " \
+            'use Pangea::ArchDsl.managed_id to canonicalize'
+    end
+  end
+end

data/lib/pangea/architecture.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+# Copyright 2025 The Pangea Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'json'
+
+module Pangea
+  # Abstract declaration of a named infrastructure architecture.
+  #
+  # An Architecture is "a named block of declarative infrastructure
+  # that, when applied to a synthesizer, produces Terraform JSON". It
+  # deliberately doesn't couple to any specific synthesizer — the
+  # block is evaluated in whatever context ``apply`` is handed, so the
+  # same Architecture could be re-rendered against a mock synthesizer
+  # for tests, a dry-run synthesizer for plan preview, or a real
+  # ``TerraformSynthesizer`` for apply.
+  #
+  # Example:
+  #
+  #   Pangea.architecture 'my_fleet' do
+  #     resource :aws_vpc, 'main' do
+  #       cidr_block '10.0.0.0/16'
+  #       tags managed_tags
+  #     end
+  #   end
+  #
+  # The block reaches the synthesizer via ``apply`` below; attribute
+  # method calls inside the ``resource`` block are interpreted by the
+  # synthesizer's own method_missing (see terraform-synthesizer /
+  # abstract-synthesizer for the DSL semantics).
+  class Architecture
+    attr_reader :name, :block
+
+    def initialize(name, block)
+      @name  = name
+      @block = block
+    end
+
+    # Apply this architecture to a synthesizer. The block runs in the
+    # synthesizer's context via ``instance_eval`` — every resource /
+    # variable / output / etc. declared in the block is captured by
+    # the synthesizer's normal method_missing pipeline.
+    def apply(synth)
+      synth.instance_eval(&@block)
+      synth
+    end
+  end
+
+  # Helper methods made available inside architecture blocks. Mixed
+  # into TerraformSynthesizer at load time so the DSL can call things
+  # like ``jsonencode(...)`` and ``managed_tags`` without caller-side
+  # wiring. These are deliberately simple and free of side effects —
+  # they return plain Ruby values the synthesizer can serialise.
+  module TemplateHelpers
+    # Serialise a Ruby hash/array to a JSON string. Matches the shape
+    # Terraform's ``jsonencode(...)`` function produces; callers using
+    # ``jsonencode({ Statement: [...] })`` get a string embedded into
+    # the resource body, which Terraform then consumes verbatim.
+    def jsonencode(value)
+      JSON.generate(value)
+    end
+
+    # Canonical tag set applied to every Pangea-managed resource.
+    # Consumers that want to extend (e.g. add team, cost-center,
+    # environment) can ``merge`` their own hash on top.
+    def managed_tags
+      {
+        ManagedBy: 'pangea',
+        Namespace: ENV.fetch('PANGEA_NAMESPACE', 'default'),
+      }
+    end
+  end
+
+  # Class-level state for the DSL entry point. Each successful call to
+  # ``Pangea.architecture`` stores the block here; the synthesizer's
+  # ``capture_template_block`` reads this as a fallback to its older
+  # ``template :name do ... end`` DSL, so both surfaces coexist.
+  @architectures = {}
+  @last_architecture = nil
+
+  class << self
+    # Register a named architecture and return its Architecture
+    # instance. The block isn't executed here — only captured for
+    # later ``apply`` by the synthesis machinery.
+    #
+    # @param name [String, Symbol] Human-facing name
+    # @yield The architecture body (see Pangea::Architecture)
+    # @return [Pangea::Architecture]
+    def architecture(name, &block)
+      raise ArgumentError, 'Pangea.architecture requires a block' unless block
+
+      arch = Architecture.new(name.to_s, block)
+      @architectures[name.to_s] = arch
+      @last_architecture = arch
+      arch
+    end
+
+    # Lookup by name — returns nil if unknown.
+    def architecture_for(name)
+      @architectures[name.to_s]
+    end
+
+    # Entire registry snapshot (caller gets a dup — the live map is
+    # internal).
+    def architectures
+      @architectures.dup
+    end
+
+    # Most-recently-declared architecture. Used by the synthesizer to
+    # fall back when no explicit ``template :name do`` block was
+    # present in the template file.
+    def last_architecture
+      @last_architecture
+    end
+
+    # Reset the registry — primarily for tests that want a clean
+    # starting state. Not part of the public DSL.
+    def reset_architectures!
+      @architectures = {}
+      @last_architecture = nil
+    end
+  end
+end
+
+# Mix TemplateHelpers into TerraformSynthesizer when it's available.
+# The ``defined?`` guard means pangea-core stays useful in contexts
+# where only the abstract synthesizer (or a mock) is loaded — tests,
+# CI preflight, etc.
+if defined?(TerraformSynthesizer)
+  TerraformSynthesizer.include(Pangea::TemplateHelpers)
+end

data/lib/pangea/backend.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+
+module Pangea
+  # Backend selection + auto-discovery layer.
+  #
+  # Per theory/MAGMA.md §II.11, Pangea supports two execution backends —
+  # tofu (historical default) and magma (pleme-io's Rust-native
+  # executor). The selected backend consumes Pangea-rendered Terraform
+  # JSON and drives plan/apply/destroy.
+  #
+  # Resolution priority:
+  #   1. --backend CLI flag
+  #   2. PANGEA_BACKEND env var
+  #   3. pangea.yml `backend:` field
+  #   4. default: tofu
+  #
+  # Auto-discovery: each backend's binary is probed via `<bin>
+  # capabilities` (magma) / `<bin> version -json` (tofu) on first use;
+  # the resulting capabilities manifest gates feature use with typed
+  # BackendIncompatible errors.
+  module Backend
+    # Raised when a workspace requires a feature the selected backend
+    # doesn't support.
+    class BackendIncompatible < StandardError
+      attr_reader :backend, :feature, :alternatives, :hint
+
+      def initialize(backend:, feature:, alternatives: [], hint: nil)
+        @backend = backend
+        @feature = feature
+        @alternatives = alternatives
+        @hint = hint
+        msg = +"backend=#{backend} does not support #{feature}.\n"
+        unless alternatives.empty?
+          msg << "  Alternatives: #{alternatives.map { |a| "backend=#{a}" }.join(', ')}\n"
+        end
+        msg << "  Hint: #{hint}\n" if hint
+        super(msg)
+      end
+    end
+
+    # Raised when no backend binary is reachable on PATH.
+    class BackendUnavailable < StandardError; end
+
+    # Normalized capabilities — what every backend impl returns from
+    # `.capabilities`. Comparable across tofu / magma so workspace-side
+    # code interacts with one shape.
+    Capabilities = Struct.new(
+      :name,                # 'tofu' | 'magma'
+      :version,             # semver string
+      :supported_protocols, # ['tfplugin5', 'tfplugin6']
+      :input_formats,       # ['hcl2', 'terraform-json'] or ['pangea-ruby-inprocess', 'terraform-json']
+      :subcommands,         # array of supported CLI subcommands
+      :supports_in_memory_pipeline, # bool — magma true, tofu false
+      :supports_workspace_chains,   # bool — magma true, tofu false
+      :raw,                 # the full JSON manifest as a Hash
+      keyword_init: true,
+    )
+
+    # Resolve backend choice from explicit > env > config > default.
+    #
+    # @param explicit [String, nil]  the --backend flag value
+    # @param yml_config [Hash, nil]  the parsed pangea.yml
+    # @return [String] one of 'tofu' or 'magma'
+    def self.resolve(explicit: nil, yml_config: nil)
+      value = explicit ||
+              ENV['PANGEA_BACKEND'] ||
+              yml_config&.dig('backend') ||
+              yml_config&.dig(:backend) ||
+              'tofu'
+      value = value.to_s
+      unless %w[tofu magma].include?(value)
+        raise ArgumentError,
+              "unknown backend #{value.inspect}; expected 'tofu' or 'magma'"
+      end
+      value
+    end
+
+    # Probe a backend's capabilities by spawning `<bin> capabilities`
+    # (magma) or `<bin> version -json` (tofu). Cached per-process.
+    #
+    # @param name [String] 'tofu' or 'magma'
+    # @return [Capabilities]
+    # @raise [BackendUnavailable] if the binary isn't on PATH
+    def self.capabilities(name)
+      @capabilities ||= {}
+      @capabilities[name] ||= probe(name)
+    end
+
+    def self.probe(name)
+      case name
+      when 'magma'  then probe_magma
+      when 'tofu'   then probe_tofu
+      else
+        raise ArgumentError, "unknown backend: #{name}"
+      end
+    end
+
+    def self.probe_magma
+      out, status = Open3.capture2('magma', 'capabilities')
+      raise BackendUnavailable, "magma binary not on PATH" unless status.success?
+
+      m = JSON.parse(out)
+      Capabilities.new(
+        name:                          m['tool'],
+        version:                       m['version'],
+        supported_protocols:           Array(m['supported_protocols']),
+        input_formats:                 Array(m['input_formats']),
+        subcommands:                   Array(m['subcommands']),
+        supports_in_memory_pipeline:   m['in_memory_pipeline_supported'] == true,
+        supports_workspace_chains:     m['workspace_chain_supported'] == true,
+        raw:                           m,
+      )
+    rescue Errno::ENOENT
+      raise BackendUnavailable, "magma binary not on PATH"
+    end
+
+    def self.probe_tofu
+      out, status = Open3.capture2('tofu', 'version', '-json')
+      raise BackendUnavailable, "tofu binary not on PATH" unless status.success?
+
+      m = JSON.parse(out)
+      # tofu's version -json is minimal; we synthesize a Capabilities by
+      # composing version + a compile-time table of "tofu has X
+      # subcommand" plus capability-flags fixed to tofu's known shape.
+      Capabilities.new(
+        name:                          'tofu',
+        version:                       m['terraform_version'] || m['version'] || 'unknown',
+        supported_protocols:           %w[tfplugin5 tfplugin6],
+        input_formats:                 %w[hcl2 terraform-json],
+        subcommands:                   %w[init plan apply destroy state import workspace
+                                          output show refresh taint force-unlock get
+                                          fmt validate console],
+        supports_in_memory_pipeline:   false,
+        supports_workspace_chains:     false,
+        raw:                           m,
+      )
+    rescue Errno::ENOENT
+      raise BackendUnavailable, "tofu binary not on PATH"
+    end
+
+    # Verify a workspace's requirements against the selected backend.
+    # Raises BackendIncompatible with hints when something doesn't match.
+    #
+    # @param backend [String] 'tofu' or 'magma'
+    # @param requires [Hash] e.g. { input_format: 'pangea-ruby-inprocess',
+    #                               feature: :in_memory_pipeline }
+    def self.verify_compatible!(backend, requires)
+      caps = capabilities(backend)
+      if (fmt = requires[:input_format])
+        unless caps.input_formats.include?(fmt.to_s)
+          raise BackendIncompatible.new(
+            backend:      backend,
+            feature:      "input format '#{fmt}'",
+            alternatives: %w[tofu magma].reject { |b| b == backend },
+            hint:         "Set `backend: magma` in pangea.yml if you need #{fmt}.",
+          )
+        end
+      end
+      if requires[:feature] == :in_memory_pipeline && !caps.supports_in_memory_pipeline
+        raise BackendIncompatible.new(
+          backend:      backend,
+          feature:      'in-memory workspace chains',
+          alternatives: ['magma'],
+          hint:         "Switch to backend=magma to use §II.9 in-memory chains.",
+        )
+      end
+    end
+  end
+end