pangea 0.0.57 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b67384b1e67ddd2e0ce27af66f4e84cbb477eb9ca4c7d7441f347379a53664a6
-  data.tar.gz: 660bad90a7ad11eeea0efcba6cebb195d4b033ad5f1687f244e9b7323a6d5442
+  metadata.gz: 4ea21a75b0c516b27bb6a7bd07273509323c5343809d5b0379e17842e2952e05
+  data.tar.gz: 0e5f2f1bcd36111e0bb22a62e5689e60063aeef306fb7ee1f27a1da8e03e4c65
 SHA512:
-  metadata.gz: 859e4081b558250b3c130c4d23cf45a4d9f631cb0545e75facb6ef83129f8841c9a9afdaf115b8a3cc7f58ede4e6ff124ca2cf9b3da12e6305475a65b61583ea
-  data.tar.gz: dbc9e49f912a86066c05a9e6f6ddc78605cdb745614b57addd9e538222a066dc21bc6cb356cd428b6ce70d670db50db0108b28ae085bbbf69492b007368e4140
+  metadata.gz: c8a3df832621cbf6f8703b2f0285e0df4bec5b923ce6e88084d1b4658434437379d7f849adc3c1ad75f2c164562e5507686d6c01dcc8434b8a87b37afe2f7ee5
+  data.tar.gz: 99eea2be7e31503322c467f69483e6d70ccd578fbcc0cf6924a9e83bfc6da75f233961d7806afd60ec23a980293c2817d54853149d2caed360846d2fa55abdd5

data/.claude/skills/pangea-cloud-resource-creation/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: pangea-cloud-resource-creation
+description: Creates cloud provider resources for Pangea using Dry::Struct types, terraform-synthesizer integration, and RSpec tests. Use when adding support for new cloud providers (AWS, Hetzner, Cloudflare, GCP, Azure, DigitalOcean, etc.) to Pangea. Covers type definitions, resource functions, synthesis specs, tracker creation, and batch implementation patterns. Apply when implementing resources from provider documentation, adding new cloud integrations, or standardizing resource creation workflows.
+metadata:
+  version: "1.0.0"
+  last_verified: "2025-12-27"
+  research_version: "2025-12-27"
+  domain_keywords:
+    - "terraform"
+    - "cloud-providers"
+    - "infrastructure-as-code"
+    - "resource-synthesis"
+    - "ruby-infrastructure"
+    - "dry-struct"
+---
+
+# Pangea Cloud Provider Resource Creation
+
+## Overview
+
+Standardized pattern for adding cloud provider resources to Pangea. Production-tested with Cloudflare (29 resources) and Hetzner Cloud (25 resources).
+
+**Location**: `pkgs/tools/ruby/pangea/`
+
+## Core Pattern
+
+Each cloud provider resource requires **exactly three files**:
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `types.rb` | `lib/pangea/resources/{resource}/types.rb` | Dry::Struct attribute validation |
+| `resource.rb` | `lib/pangea/resources/{resource}/resource.rb` | terraform-synthesizer + ResourceReference |
+| `synthesis_spec.rb` | `spec/resources/{resource}/synthesis_spec.rb` | RSpec tests for Terraform JSON |
+
+**Critical**: All three files must follow exact patterns. Deviations break synthesis or testing.
+
+## File Structure
+
+```
+pkgs/tools/ruby/pangea/
+├── lib/pangea/resources/
+│   ├── types.rb                           # Central type definitions for ALL providers
+│   ├── {resource_name}/
+│   │   ├── types.rb                       # Resource-specific Dry::Struct
+│   │   └── resource.rb                    # Resource function
+├── spec/resources/
+│   └── {resource_name}/
+│       └── synthesis_spec.rb              # Synthesis tests
+```
+
+## Implementation Workflow
+
+### Phase 1: Planning
+
+1. **Research** - Review Terraform provider documentation
+2. **Create Tracker** - `PROVIDER_IMPLEMENTATION.json` with batches
+3. **Design Types** - Add provider types to central `types.rb`
+
+### Phase 2: Resource Implementation
+
+For each resource, create the three required files:
+
+1. **types.rb** - Dry::Struct with `transform_keys(&:to_sym)`
+2. **resource.rb** - Resource function with conditionals for optional fields
+3. **synthesis_spec.rb** - Tests with `TerraformSynthesizer.new`
+
+### Phase 3: Batch Execution
+
+1. Implement all types first
+2. Complete each batch (all 3 files per resource)
+3. Update tracker: `bin/tracker update resource_name all`
+4. Commit with batch completion message
+
+## Quick Reference
+
+### Attribute Patterns (types.rb)
+
+| Pattern | Syntax |
+|---------|--------|
+| Required | `attribute :name, Type` |
+| Optional with default | `attribute :name, Type.default(value)` |
+| Optional no default | `attribute :name, Type.optional.default(nil)` |
+| Arrays | `attribute :items, Array.of(Type).default([].freeze)` |
+| Hashes | `attribute :labels, Hash.default({}.freeze)` |
+
+### Resource Patterns (resource.rb)
+
+| Pattern | Syntax |
+|---------|--------|
+| Required field | `field_name attrs.field` |
+| Optional field | `field_name attrs.field if attrs.field` |
+| Default field | `field_name attrs.field` (always include) |
+| Nested block | `block_name do ... end` inside conditional |
+| Array blocks | `attrs.items.each do \|item\| ... end` |
+
+### Test Requirements (synthesis_spec.rb)
+
+- Basic resource with defaults
+- Resource with all options
+- Nested blocks/arrays
+- Resource references (interpolation)
+- Resource composition (parent-child)
+
+## Decision Table
+
+| Scenario | Action |
+|----------|--------|
+| Add new cloud provider | Create tracker, implement all batches |
+| Add single resource | Create 3 files, update tracker |
+| Review implementation | Check against anti-patterns |
+| Debug synthesis | Run individual spec, check conditionals |
+| Type validation error | Check `transform_keys`, attribute syntax |
+
+## Anti-Patterns (Quick Check)
+
+| Issue | Fix |
+|-------|-----|
+| Missing `transform_keys(&:to_sym)` | Add to Dry::Struct class |
+| Hardcoded values in resource | Use `attrs.field` |
+| Optional without conditional | Add `if attrs.field` |
+| Missing auto-registration | Add `ResourceRegistry.register_module(...)` |
+| Tests without synthesizer | Use `TerraformSynthesizer.new` |
+
+## Testing
+
+```bash
+cd pkgs/tools/ruby/pangea
+
+# Single resource
+rspec spec/resources/hcloud_volume/synthesis_spec.rb
+
+# All provider resources
+rspec spec/resources/hcloud_*
+```
+
+## When to Use This Skill
+
+- Adding new cloud provider to Pangea
+- Implementing resources from Terraform provider docs
+- Creating resource tracker for new provider
+- Reviewing resource implementation quality
+- User asks: "add support for {cloud provider}"
+- User asks: "implement {terraform resource}"
+
+## Success Criteria
+
+- 100% resource coverage for target provider
+- All resources follow three-file pattern
+- All tests use terraform-synthesizer
+- ResourceReference enables composition
+- Tracker shows 100% completion
+
+## Detailed References
+
+| Reference | Content |
+|-----------|---------|
+| [{baseDir}/references/resource-templates.md](references/resource-templates.md) | Full templates for types.rb, resource.rb, synthesis_spec.rb |
+| [{baseDir}/references/type-system.md](references/type-system.md) | Type definitions, categories, tracker JSON template |
+| [{baseDir}/references/hetzner-volume-example.md](references/hetzner-volume-example.md) | Complete end-to-end implementation example |
+| [{baseDir}/references/tracker-cli.md](references/tracker-cli.md) | Tracker CLI script implementation |
+| [{baseDir}/references/patterns-antipatterns.md](references/patterns-antipatterns.md) | Common patterns, anti-patterns, testing, git workflow |
+
+## Related Resources
+
+- **Hetzner Implementation**: 25 resources (100% complete)
+- **Cloudflare Implementation**: 29 resources (100% complete)
+- **Type System**: `lib/pangea/resources/types.rb`
+- **Synthesizer**: `lib/terraform-synthesizer.rb`
+- **Testing Skill**: `.claude/skills/pangea-rspec-resource-testing.md`

data/.claude/skills/pangea-cloud-resource-creation/references/hetzner-volume-example.md

@@ -0,0 +1,133 @@
+# Complete Example: Hetzner Volume
+
+End-to-end implementation of `hcloud_volume` resource.
+
+## 1. Type Definition in types.rb
+
+```ruby
+# lib/pangea/resources/types.rb (ADD at end before closing 'end')
+
+# Hetzner volume filesystem formats
+HetznerVolumeFormat = String.enum('xfs', 'ext4')
+
+# Hetzner volume size validation (10-10000 GB)
+HetznerVolumeSize = Integer.constrained(gteq: 10, lteq: 10000)
+```
+
+## 2. Resource Types
+
+```ruby
+# lib/pangea/resources/hcloud_volume/types.rb
+# frozen_string_literal: true
+# Copyright 2025 The Pangea Authors
+
+require 'dry-struct'
+require 'pangea/resources/types'
+
+module Pangea
+  module Resources
+    module Hetzner
+      module Types
+        class VolumeAttributes < Dry::Struct
+          transform_keys(&:to_sym)
+
+          # Required
+          attribute :name, Resources::Types::String
+          attribute :size, HetznerVolumeSize
+
+          # Optional
+          attribute :location, HetznerLocation.optional.default(nil)
+          attribute :format, HetznerVolumeFormat.optional.default(nil)
+          attribute :labels, HetznerLabels.default({}.freeze)
+        end
+      end
+    end
+  end
+end
+```
+
+## 3. Resource Function
+
+```ruby
+# lib/pangea/resources/hcloud_volume/resource.rb
+# frozen_string_literal: true
+# Copyright 2025 The Pangea Authors
+
+require 'pangea/resources/base'
+require 'pangea/resources/reference'
+require 'pangea/resources/hcloud_volume/types'
+require 'pangea/resource_registry'
+
+module Pangea
+  module Resources
+    module HcloudVolume
+      def hcloud_volume(name, attributes = {})
+        volume_attrs = Hetzner::Types::VolumeAttributes.new(attributes)
+
+        resource(:hcloud_volume, name) do
+          name volume_attrs.name
+          size volume_attrs.size
+          location volume_attrs.location if volume_attrs.location
+          format volume_attrs.format if volume_attrs.format
+          labels volume_attrs.labels
+        end
+
+        ResourceReference.new(
+          type: 'hcloud_volume',
+          name: name,
+          resource_attributes: volume_attrs.to_h,
+          outputs: {
+            id: "${hcloud_volume.#{name}.id}",
+            size: "${hcloud_volume.#{name}.size}",
+            linux_device: "${hcloud_volume.#{name}.linux_device}"
+          }
+        )
+      end
+    end
+
+    module Hetzner
+      include HcloudVolume
+    end
+  end
+end
+
+Pangea::ResourceRegistry.register_module(Pangea::Resources::Hetzner)
+```
+
+## 4. Synthesis Spec
+
+```ruby
+# spec/resources/hcloud_volume/synthesis_spec.rb
+# frozen_string_literal: true
+# Copyright 2025 The Pangea Authors
+
+require 'spec_helper'
+require 'terraform-synthesizer'
+require 'pangea/resources/hcloud_volume/resource'
+
+RSpec.describe 'hcloud_volume synthesis' do
+  include Pangea::Resources::Hetzner
+
+  let(:synthesizer) { TerraformSynthesizer.new }
+
+  it 'synthesizes volume' do
+    synthesizer.instance_eval do
+      extend Pangea::Resources::Hetzner
+      hcloud_volume(:data, {
+        name: "web-data",
+        size: 100,
+        location: "fsn1",
+        format: "ext4"
+      })
+    end
+
+    result = synthesizer.synthesis
+    volume = result[:resource][:hcloud_volume][:data]
+
+    expect(volume[:name]).to eq("web-data")
+    expect(volume[:size]).to eq(100)
+    expect(volume[:location]).to eq("fsn1")
+    expect(volume[:format]).to eq("ext4")
+  end
+end
+```

data/.claude/skills/pangea-cloud-resource-creation/references/patterns-antipatterns.md

@@ -0,0 +1,149 @@
+# Patterns, Anti-Patterns, and Testing
+
+## Common Patterns
+
+### Nested Blocks
+
+```ruby
+# In resource.rb
+if attrs.health_check
+  health_check do
+    protocol attrs.health_check[:protocol]
+    port attrs.health_check[:port]
+    interval attrs.health_check[:interval] if attrs.health_check[:interval]
+  end
+end
+```
+
+### Array of Nested Blocks
+
+```ruby
+# In resource.rb
+attrs.rules.each do |rule|
+  rule_block do
+    direction rule[:direction]
+    protocol rule[:protocol]
+    port rule[:port] if rule[:port]
+  end
+end
+```
+
+### Conditional Optional Fields
+
+```ruby
+# In resource.rb
+description attrs.description if attrs.description
+location attrs.location if attrs.location
+
+# DON'T: if attrs.optional_field.nil? ... (wrong)
+# DO: if attrs.optional_field ... (correct)
+```
+
+### Computed Properties
+
+```ruby
+# In types.rb
+class ServerAttributes < Dry::Struct
+  attribute :server_type, HetznerServerType
+
+  def is_arm?
+    server_type.start_with?('cax')
+  end
+
+  def cpu_type
+    is_arm? ? 'arm64' : 'x86_64'
+  end
+end
+
+# In resource.rb
+resource(:hcloud_server, name) do
+  server_type attrs.server_type
+  cpu_architecture attrs.cpu_type  # Use computed property
+end
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|--------------|---------|-----|
+| Missing `transform_keys` | Symbol/string key errors | Add `transform_keys(&:to_sym)` |
+| Hardcoded values in resource | Values should come from attrs | Use `attrs.field` |
+| No conditionals for optional | Includes nil in Terraform | `field attrs.val if attrs.val` |
+| Missing auto-registration | Resource unavailable | Add `ResourceRegistry.register_module(...)` |
+| Tests without synthesizer | Doesn't test Terraform generation | Use `TerraformSynthesizer.new` |
+
+## Testing Strategy
+
+### Run Commands
+
+```bash
+cd pkgs/tools/ruby/pangea
+
+# Individual resource
+rspec spec/resources/hcloud_volume/synthesis_spec.rb
+
+# All provider resources
+rspec spec/resources/hcloud_*
+```
+
+### Validate Types in IRB
+
+```ruby
+require 'pangea/resources/hcloud_volume/types'
+
+# Valid input
+attrs = Pangea::Resources::Hetzner::Types::VolumeAttributes.new(
+  name: "test",
+  size: 100,
+  format: "ext4"
+)
+
+# Invalid input (should raise error)
+attrs = Pangea::Resources::Hetzner::Types::VolumeAttributes.new(
+  name: "test",
+  size: 5  # Too small, should fail
+)
+```
+
+## Git Commit Messages
+
+```bash
+# Type definitions
+git commit -m "feat(pangea): add Hetzner Cloud type definitions (12 types)"
+
+# Batch implementation
+git commit -m "feat(pangea): complete Batch 1 - Core Infrastructure (5/5 resources)
+
+Resources implemented:
+- hcloud_ssh_key: SSH key management
+- hcloud_network: Private VPC networks
+- hcloud_firewall: Stateful firewalls
+- hcloud_server: Virtual servers
+- hcloud_network_subnet: Network subnets
+
+All resources include:
+- Dry::Struct type validation
+- terraform-synthesizer integration
+- RSpec synthesis tests
+"
+
+# Completion
+git commit -m "docs(pangea): add Provider implementation completion report
+
+100% coverage (XX/XX resources)
+All batches complete
+"
+```
+
+## Completion Checklist
+
+Before marking a resource complete:
+
+- [ ] Type definitions added to types.rb
+- [ ] types.rb created with Dry::Struct
+- [ ] resource.rb created with resource() function
+- [ ] synthesis_spec.rb created with TerraformSynthesizer tests
+- [ ] All tests pass
+- [ ] Resource auto-registers via ResourceRegistry
+- [ ] Tracker updated
+- [ ] Committed with descriptive message