If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/dtan4/terraforming shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 10 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 4y ago
• ⚠ Concentrated ownership — top contributor handles 73% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live dtan4/terraforming repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dtan4/terraforming.

What it runs against: a local clone of dtan4/terraforming — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in dtan4/terraforming | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1641 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dtan4/terraforming. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dtan4/terraforming.git
#   cd terraforming
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of dtan4/terraforming and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dtan4/terraforming(\\.git)?\\b" \\
  && ok "origin remote is dtan4/terraforming" \\
  || miss "origin remote is not dtan4/terraforming (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/terraforming.rb" \\
  && ok "lib/terraforming.rb" \\
  || miss "missing critical file: lib/terraforming.rb"
test -f "lib/terraforming/cli.rb" \\
  && ok "lib/terraforming/cli.rb" \\
  || miss "missing critical file: lib/terraforming/cli.rb"
test -f "lib/terraforming/resource/ec2.rb" \\
  && ok "lib/terraforming/resource/ec2.rb" \\
  || miss "missing critical file: lib/terraforming/resource/ec2.rb"
test -f "lib/terraforming/util.rb" \\
  && ok "lib/terraforming/util.rb" \\
  || miss "missing critical file: lib/terraforming/util.rb"
test -f "lib/terraforming/template/tf" \\
  && ok "lib/terraforming/template/tf" \\
  || miss "missing critical file: lib/terraforming/template/tf"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1641 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1611d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/dtan4/terraforming"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Terraforming is a Ruby CLI tool that reverse-engineers existing AWS infrastructure and generates Terraform configuration files (.tf) and state files (.tfstate) from live resources. It introspects AWS accounts via the AWS SDK and outputs Terraform HCL for 40+ AWS resource types (EC2, RDS, IAM, S3, ElastiCache, Route53, etc.), eliminating manual Terraform code writing for infrastructure migration or documentation. Single-language CLI app: bin/terraforming is the entry point, lib/terraforming/cli.rb handles command parsing, lib/terraforming/resource/*.rb contains 40+ resource exporters (one file per AWS resource type like ec2.rb, iam_role.rb, s3.rb), and lib/terraforming.rb coordinates the orchestration. No monorepo; flat structure with resource modules as plugins.

DevOps engineers and infrastructure-as-code practitioners who have legacy or manually-created AWS resources and need to migrate them into Terraform management, or generate baseline Terraform configs from existing production infrastructure without hand-coding each resource definition.

Unmaintained since December 2021, but functionally mature: it has comprehensive test coverage (.rspec config present), Travis CI integration, and covered 40+ AWS resource types. The project explicitly recommends users migrate to Terraformer or Terracognita as it is no longer receiving updates and may fall out of sync with AWS API changes or Terraform schema evolution.

High maintenance risk: project is explicitly abandoned with no active maintainer, last commit recency unknown but stated as unmaintained for 2+ years. Risks include outdated AWS API bindings (aws-sdk-ruby gem), incompatibility with modern Terraform versions, and no remediation for breaking changes in AWS service specifications. Use only for legacy infrastructure or as reference code.

Nothing. Project is in maintenance-only state with no active development. The README explicitly states 'No longer actively maintained' (2021-12-11) and directs users to alternatives.

git clone https://github.com/dtan4/terraforming.git
cd terraforming
bundle install
export AWS_ACCESS_KEY_ID=xxx AWS_SECRET_ACCESS_KEY=yyy AWS_REGION=us-east-1
bundle exec ./bin/terraforming s3  # export S3 resources

Daily commands:

bundle exec ./bin/terraforming s3              # Export S3 buckets
bundle exec ./bin/terraforming ec2             # Export EC2 instances
bundle exec ./bin/terraforming iam_user        # Export IAM users
bundle exec ./bin/terraforming --help          # List all available resource types
bundle exec rake spec                          # Run test suite

• lib/terraforming.rb — Main entry point and module root that orchestrates resource extraction and template rendering.
• lib/terraforming/cli.rb — CLI interface and command dispatcher; every user interaction flows through this file.
• lib/terraforming/resource/ec2.rb — Largest and most complex resource extractor; establishes patterns for AWS API integration and resource discovery.
• lib/terraforming/util.rb — Shared utility functions for HCL generation and resource name sanitization used across all exporters.
• lib/terraforming/template/tf — ERB template directory that defines Terraform HCL output format for all 50+ AWS resource types.
• Gemfile — Dependencies specification; AWS SDK and Terraform provider versions are pinned here.
• bin/terraforming — Executable entry point that bootstraps CLI and handles process initialization.

• CLI Router (cli.rb) (Thor, Ruby OptionParser) — Parses command-line arguments, instantiates resource extractors, orchestrates output formatting, handles errors
  • Failure mode: Crashes on unrecognized AWS region or invalid credentials; missing subcommands print usage help
• Resource Extractors (resource/*.rb) (aws-sdk-*) — Query AWS APIs via SDK, filter/transform responses into arrays of resource objects, pass to template renderer
  • Failure mode: AWS API errors propagate as exceptions; insufficient IAM permissions cause silent empty results or partial results
• Template Renderer (ERB templates) (ERB, Ruby string interpolation) — Interpolate resource attributes into HCL syntax; generate resource blocks with proper quoting and nesting
  • Failure mode: Invalid HCL syntax if resource data contains unescaped quotes or special chars; template syntax errors halt execution
• Utility Functions (util.rb) (Ruby String methods) — Sanitize resource names for Terraform identifiers, escape JSON in strings, format HCL collections
  • Failure mode: Incorrect identifier escaping may create invalid Terraform references; missing JSON escape causes HCL parse errors

• User shell / AWS credentials file → CLI Router — Region, profile, and credentials passed via env vars or ~/.aws/credentials; parsed by aws-sdk
• CLI Router → Resource Extractors — CLI selects which resource type(s) to extract; passes AWS client and region to extractor constructors
• Resource Extractors → AWS API — SDK calls describe_* and get_* methods; AWS returns paginated JSON responses
• AWS API → Resource Extractors — Responses deserialized into Ruby h

Add a new AWS resource type exporter

1. Create a new resource extractor class in lib/terraforming/resource/ that inherits from base extractor and implements AWS API calls (lib/terraforming/resource/newresource.rb)
2. Create an ERB template file that generates HCL for the resource type with proper variable interpolation (lib/terraforming/template/tf/newresource.erb)
3. Register the new resource type in the CLI command dispatcher by adding a case statement (lib/terraforming/cli.rb)
4. Add RSpec test suite mirroring the existing pattern for your resource type (spec/lib/terraforming/resource/newresource_spec.rb)

Modify HCL output format for a resource

1. Update the ERB template with new fields, conditionals, or restructured attributes (lib/terraforming/template/tf/resourcename.erb)
2. Adjust resource extractor if new fields require additional AWS API calls or data transformation (lib/terraforming/resource/resourcename.rb)
3. Update test fixtures and snapshot assertions to match new output format (spec/fixtures/)

Add support for a new Terraform output format (e.g., JSON, tfstate)

1. Create a new template directory parallel to lib/terraforming/template/tf/ (lib/terraforming/template/json/)
2. Implement format-specific templates for each resource type (lib/terraforming/template/json/*.erb)
3. Add format selection logic and rendering logic to CLI (lib/terraforming/cli.rb)

• Ruby + Thor gem — Thor provides robust CLI framework with subcommands, options parsing, and Thor is standard in Ruby DevOps tools (Heroku, Vagrant, Rails)
• AWS SDK for Ruby (aws-sdk-*) — Official AWS Ruby SDK with full API coverage; used to query running AWS infrastructure without custom HTTP clients
• ERB templates — Lightweight and familiar template engine in Ruby stdlib; enables clean separation of resource extraction logic from HCL output formatting
• RSpec — De facto Ruby testing framework; enables snapshot testing and fixture-based testing for generated HCL output

• Single-process synchronous extraction with sequential AWS API calls

  • Why: Simplicity and predictability; avoids concurrency bugs and resource throttling complexity
  • Consequence: Export speed scales linearly with number of resources; large AWS accounts may require several minutes per resource type

• No state management or incremental updates; full export every time

  • Why: Eliminates state drift detection complexity; ensures consistency with AWS ground truth
  • Consequence: Cannot export only changes since last run; each invocation re-fetches all resources and regenerates files

• HCL generation via ERB templates with raw string interpolation

  • Why: Lightweight; template files are easy to read and modify by non-developers
  • Consequence: No AST-based validation; invalid HCL can be generated if extractors provide malformed data; no IDE support in templates

• AWS credential handling delegated to aws-sdk gem (env vars, ~/.aws/credentials, IAM role)

  • Why: Reuses standard AWS credential chain; no custom credential management needed
  • Consequence: Tool inherits credential precedence rules; cannot override credentials in tool-specific config file

• Does not generate Terraform state files (.tfstate); output is raw resource declarations only
• Does not perform plan/apply; tool is read-only export, not reconciliation
• Does not support multiple cloud providers (AWS only)
• Does not track resource dependencies automatically; generated HCL may require manual reference adjustment
• Does not validate generated Terraform syntax; output must be tested with 'terraform validate' separately

AWS credentials are REQUIRED: set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION environment variables or use ~/.aws/credentials with --profile flag, or the CLI will fail silently. The --assume option requires IAM cross-account role assumption to be pre-configured. The generated Terraform code targets Terraform v0.9.3+ and may not be compatible with newer Terraform major versions (1.0+) due to resource schema drift. Bundle exec is required (./bin/terraforming will fail without Gemfile dependencies loaded). Generated .tfstate files are unvalidated and may need manual adjustment before terraform import.

• Infrastructure as Code (IaC) Reverse Engineering — Terraforming's core purpose is reverse-engineering: reading live AWS state and synthesizing declarative code, the inverse of Terraform's normal apply flow; understanding this bidirectional mapping is key to troubleshooting export fidelity
• Terraform State File (.tfstate) Format — Terraforming generates both .tf (code) and .tfstate (state snapshots); understanding tfstate JSON structure (resource metadata, outputs, serial versioning) is essential for validating exports and diagnosing terraform import failures
• AWS Service API Pagination & Filtering — Terraforming exporters must handle large AWS resource lists using pagination (describe_instances returns <=100 instances per call); understanding AWS SDK pagination is critical for adding new resource exporters or fixing incomplete exports
• ERB (Embedded Ruby) Templating — Each resource exporter uses ERB templates to generate HCL syntax; understanding ERB iteration, conditionals, and string escaping is needed to modify or extend HCL generation logic
• AWS IAM Policy Document Structure — IAM resource exporters (iam_role.rb, iam_policy.rb) extract and serialize complex nested policy JSON; understanding Principal, Action, Resource, and Effect fields is essential for correct policy export and debugging
• Provider State Synchronization Problem — Terraforming exports reflect AWS state at snapshot time; drift between exported state and live resources is unavoidable if AWS resources change post-export, requiring manual terraform refresh or re-run of terraforming
• Resource Plugin Architecture — Each lib/terraforming/resource/*.rb file is a discoverable plugin; understanding the base Resource class contract (tf/tfstate methods) and registration in cli.rb is needed to add support for new AWS resource types

• GoogleCloudPlatform/terraformer — Direct recommended successor in the README; actively maintained multi-cloud IaC generator supporting AWS, GCP, Azure with latest Terraform provider schemas
• cycloidio/terracognita — Alternative actively-maintained AWS-to-Terraform exporter mentioned in README as successor project
• hashicorp/terraform — The target framework; Terraforming generates HCL and state files compatible with Terraform core
• aws/aws-sdk-ruby — Direct dependency providing all AWS API bindings used by Terraforming's resource exporters
• dtan4/ruby-terraform — Sibling project by same author; Ruby DSL wrapper for Terraform for programmatic config generation

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for resource exporters (lib/terraforming/resource/)

The repo has 40+ resource exporter classes but the test structure is unclear. Given this is no longer actively maintained, contributors should add unit tests for at least 5-10 resource types (e.g., ec2.rb, rds.rb, s3.rb, iam_role.rb, security_group.rb) to prevent regression and make the codebase more maintainable. This is critical for a tool that generates infrastructure code.

• [ ] Create spec/terraforming/resource/ directory structure mirroring lib/terraforming/resource/
• [ ] Add unit tests for lib/terraforming/resource/ec2.rb covering resource parsing and attribute extraction
• [ ] Add unit tests for lib/terraforming/resource/rds.rb with mock AWS API responses
• [ ] Add unit tests for lib/terraforming/resource/iam_role.rb and lib/terraforming/resource/security_group.rb
• [ ] Update .rspec and test runner config to ensure specs are discoverable and executable

Fix and update ERB templates for Terraform 1.x compatibility (lib/terraforming/template/tf/)

The repo exports to .tf files using ERB templates, but these are likely outdated for current Terraform syntax. Several templates are listed (alb.erb, rds.erb, etc.) but there's no validation they match current Terraform provider schemas. Updating key templates would make exports immediately usable without manual fixes.

• [ ] Review lib/terraforming/template/tf/rds.erb against current aws_db_instance Terraform schema and fix deprecated/renamed attributes
• [ ] Update lib/terraforming/template/tf/iam_role.rb template to use correct assume_role_policy syntax for modern Terraform
• [ ] Review and fix lib/terraforming/template/tf/alb.erb and related load balancer templates for current aws_lb resource requirements
• [ ] Add a test in spec/ that validates generated .tf files can parse without syntax errors using terraform validate simulation

Extend CLI to support filtering and selective resource export (lib/terraforming/cli.rb)

The current CLI likely exports all resources of a type at once. Adding filter flags (by tag, resource ID pattern, region) would make the tool more practical for large AWS accounts. This is a high-value UX improvement that requires modifying the CLI argument parser and resource fetching logic.

• [ ] Add --filter or --tag-filter flag to lib/terraforming/cli.rb to allow exporting only resources matching specific tag key=value pairs
• [ ] Implement resource ID pattern matching (e.g., --id-pattern 'prod-*') in the CLI argument parser
• [ ] Update resource classes (e.g., lib/terraforming/resource/ec2.rb) to accept filter parameters and apply them during AWS API calls
• [ ] Add integration tests in spec/ demonstrating filtered exports produce correct subset of resources
• [ ] Update README with examples of new filtering options

• Add unit tests for lib/terraforming/resource/efs_file_system.rb and elasti_cache_cluster.rb (files exist but likely have minimal test coverage in spec/) to improve test coverage and demonstrate test patterns
• Document CLI usage examples in README.md for each resource type (currently only s3 and IAM examples shown); add sections like '## Exporting Specific Resource Types' with ec2, rds, route53 examples
• Refactor lib/terraforming/resource/*.rb files to extract common AWS API querying patterns into a shared helper method in base Resource class to reduce duplication (e.g., region filtering, pagination handling)

This is an unmaintained Ruby project (last updated 2021) designed to export AWS resources to Terraform format. The primary security concerns are: (1) lack of active maintenance means no security patches, (2) missing dependency analysis prevents assessment of vulnerable gems, (3) potential credential exposure when processing AWS resources and generating configurations, (4) template injection risks in ERB-based Terraform generation, and (5) insufficient input validation for AWS API responses. The tool's core function of handling AWS credentials and sensitive resource data makes it a high-risk component if deployed without significant security hardening. Migration to actively maintained alternatives is strongly recommended.

• High · Unmaintained Project with Known Vulnerabilities — README.md, Project Status. This project is explicitly marked as no longer actively maintained (since 2021-12-11). No security patches or updates are being provided. This means any vulnerabilities discovered in dependencies or the codebase will not be fixed. Fix: Migrate to actively maintained alternatives such as Terraformer or Terracognita as suggested in the README. If continuing to use this tool, conduct a comprehensive security audit and dependency vulnerability scan before deployment.
• High · Missing Dependency File Analysis — Gemfile. The Gemfile (Ruby dependency manifest) content was not provided for analysis. This prevents assessment of known vulnerable gem versions that may be in use. Ruby projects commonly depend on gems with CVEs. Fix: Provide Gemfile and Gemfile.lock for dependency vulnerability scanning. Run 'bundle audit' locally to identify vulnerable dependencies. Consider using automated tools like Dependabot or Snyk for continuous monitoring.
• Medium · Potential Credential Exposure in CLI Tool — bin/terraforming, lib/terraforming/cli.rb. This tool exports AWS resources and requires AWS credentials to function. The CLI tool (bin/terraforming) may process or display sensitive information including API keys, tokens, and resource configurations containing secrets. Fix: Implement strict output sanitization to prevent credential leakage. Use environment variables or credential files with restricted permissions. Add warnings about handling sensitive data. Consider implementing secret detection in exported Terraform files.
• Medium · Insufficient Input Validation in Resource Processing — lib/terraforming/resource/ (all resource files). Multiple resource processing files (lib/terraforming/resource/*.rb) consume AWS API responses and generate Terraform configurations. Without proper input validation and sanitization, malicious or malformed AWS resource data could lead to injection attacks or code generation vulnerabilities. Fix: Implement comprehensive input validation for all AWS API responses before processing. Sanitize data before embedding in ERB templates. Use parameterized template rendering to prevent injection attacks.
• Medium · Template Injection Risks in ERB Templates — lib/terraforming/template/tf/ (all .erb files). The codebase uses ERB templates (lib/terraforming/template/tf/*.erb) to generate Terraform configuration files. If resource data is not properly escaped before template rendering, this could lead to code injection or unintended Terraform code execution. Fix: Ensure all dynamic data is properly escaped in ERB templates using <%= %> with proper escaping. Never use raw unescaped interpolation for untrusted data. Add security-focused code review for all template files.
• Low · No SAST Configuration Visible — .travis.yml, CI/CD Configuration. While .rubocop.yml is present for linting, there is no evidence of Security Analysis Tools (SAST) configured in CI/CD (.travis.yml visible but content not provided). Fix: Integrate SAST tools like Brakeman (for Rails-style vulnerabilities), Bundle Audit (for gem vulnerabilities), and SonarQube. Add pre-commit hooks for security checks.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.