[WIP] feat: Add OpenTofu commands.

Author: jamesiarmes

.gitignore

@@ -9,8 +9,9 @@ settings.local.json
 # Ignore Byebug command history file.
 .byebug_history
 
-## Environment normalization:
+# Environment normalization:
 /.bundle/
+/bin/
 /vendor/bundle
 /lib/bundler/man/
 

.rubocop.yml

@@ -9,6 +9,7 @@ AllCops:
   NewCops: enable
   SuggestExtensions: true
   Exclude:
+    - 'bin/**/*'
     - 'out/**/*'
     - 'vendor/**/*'
     - 'doc/**/*'
@@ -26,7 +27,9 @@ Metrics/MethodLength:
 Naming/FileName:
   Exclude:
     - 'lib/cfa-eng-cli.rb'
+    - 'lib/cfa_eng_cli/config/Doppler.rb'
     - 'README.md'
+    - 'CLAUDE.md'
 
 # Count multi-line hashes and arrays in examples as one line.
 RSpec/ExampleLength:

CLAUDE.md

@@ -0,0 +1,31 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+bundle exec rake              # lint + tests (default)
+bundle exec rake rubocop      # lint only
+bundle exec rake spec         # all tests
+bundle exec rspec spec/unit/cfa_eng_cli/bastion_spec.rb  # single test file
+```
+
+## Architecture
+
+This is a Ruby CLI gem for Code for America engineering teams, built on [Thor](https://github.com/rails/thor). It manages AWS bastion host connections and named profiles.
+
+**Entry point:** `bin/cfa-eng` — defines the top-level Thor class and registers two subcommand groups.
+
+**Two subcommand groups:**
+- `bastion` — creates/deletes tunnel configs and opens SSH tunnels via AWS Session Manager port forwarding
+- `profile` — CRUD for named connection profiles stored as YAML in `~/.codeforamerica/profiles/`
+
+**Command layer** (`lib/cfa_eng_cli/commands/`): Each group is a Thor subcommand class inheriting from `Commands::Command` (base.rb). Commands delegate to business logic classes rather than containing logic themselves.
+
+**Business logic** (`lib/cfa_eng_cli/`):
+- `Bastion` — discovers running EC2 bastion instances by project/environment tags, constructs `SessionTarget`, and opens port-forwarding tunnels
+- `SessionManager` — wraps the AWS SSM `StartSession` API and shells out to the `session-manager-plugin` binary to maintain the connection
+- `SessionTarget` — simple data object holding instance ID, region, and AWS profile name
+
+**Config system** (`lib/cfa_eng_cli/config/`): Uses the [ConfigSL](https://github.com/codeforamerica/configsl) gem for declarative schema definitions. `Config::Base` handles YAML serialization. `Config::Profile` and `Config::RemoteTunnel` define the data shapes. Profile YAML files live at `~/.codeforamerica/profiles/<name>.yaml`.

Gemfile

@@ -5,7 +5,7 @@ source 'https://rubygems.org'
 gemspec
 
 # TODO: Move to gemspec once a new release has been cut.
-gem 'configsl', git: 'https://github.com/jamesiarmes/configsl.git', branch: 'collections'
+gem 'configsl', git: 'https://github.com/jamesiarmes/configsl.git', branch: 'main'
 
 group :development do
   gem 'rake', '~> 13.4'

Gemfile.lock

@@ -1,7 +1,7 @@
 GIT
   remote: https://github.com/jamesiarmes/configsl.git
-  revision: 2023f113349cb1e70918ccb6b0598ba11a6add02
-  branch: collections
+  revision: 297b420f32e47752638d2d43823f5c6a71866f39
+  branch: main
   specs:
     configsl (1.0.2)
       facets (~> 3.1)

README.md

@@ -3,3 +3,244 @@
 > [!CAUTION]
 > This is a work in progress. You are welcome to try it out, and contribute,
 > but it should not be considered stable or production-ready.
+
+`cfa-eng` is a CLI tool for Code for America engineering teams. It manages AWS
+bastion host connections, named profiles, and OpenTofu infrastructure operations.
+
+## Requirements
+
+- Ruby 3.3+
+- [AWS CLI](https://aws.amazon.com/cli/) with the
+  [Session Manager plugin](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)
+- [Doppler CLI](https://docs.doppler.com/docs/install-cli) (for `tofu` commands)
+- [OpenTofu](https://opentofu.org/docs/intro/install/) (for `tofu` commands)
+
+## Installation
+
+```bash
+gem install cfa-eng-cli
+```
+
+Or add it to your `Gemfile`:
+
+```ruby
+gem 'cfa-eng-cli'
+```
+
+## Configuration
+
+`cfa-eng` uses **profiles** to store named sets of connection settings. Most
+commands require a profile, specified with `--profile` or the `CFA_PROFILE`
+environment variable.
+
+```bash
+export CFA_PROFILE=my-app
+```
+
+Profile files are stored as YAML in `~/.codeforamerica/profiles/`.
+
+<!-- cspell:ignore codeforamerica -->
+
+## Commands
+
+### `profile` — Manage profiles
+
+#### `profile create`
+
+Creates a new profile. All fields can be supplied as options; any omitted fields
+are prompted for interactively.
+
+```bash
+cfa-eng profile create
+cfa-eng profile create --name my-app --project snap --environment staging \
+  --aws-profile shared-services-dev --region us-east-1
+```
+
+| Option | Description |
+|---|---|
+| `--name` | Profile name |
+| `--project` | Project name |
+| `--environment` | Deployment environment (e.g. `staging`, `production`) |
+| `--aws-profile` | AWS CLI profile to use for credentials |
+| `--region` | Primary AWS region (default: `us-east-1`) |
+| `--doppler-project` | Doppler project for secrets (default: `shared-services`) |
+| `--doppler-environment` | Doppler environment prefix used for config names, e.g. `infra` produces configs like `infra_dev`, `infra_prod`, `infra_<env>` (default: `infra`) |
+
+#### `profile list`
+
+Lists all saved profiles.
+
+```bash
+cfa-eng profile list
+```
+
+#### `profile delete PROFILE`
+
+Deletes a profile. Prompts for confirmation unless `--yes` is given.
+
+```bash
+cfa-eng profile delete my-app
+cfa-eng profile delete my-app --yes
+```
+
+#### `profile rename PROFILE NAME`
+
+Renames a profile. Prompts for confirmation unless `--yes` is given.
+
+```bash
+cfa-eng profile rename my-app my-renamed-app
+cfa-eng profile rename my-app my-renamed-app --yes
+```
+
+---
+
+### `bastion` — Connect to bastion hosts
+
+The `bastion` commands connect to AWS bastion hosts via SSM Session Manager port
+forwarding. A profile is required for all bastion commands.
+
+All `bastion` commands accept:
+
+| Option | Description |
+|---|---|
+| `--profile NAME` | Profile to use (default: `$CFA_PROFILE`) |
+
+#### `bastion create-tunnel`
+
+Adds a tunnel configuration to a profile. Prompts interactively for tunnel
+settings.
+
+```bash
+cfa-eng bastion create-tunnel --profile my-app
+```
+
+#### `bastion delete-tunnel NAME`
+
+Removes a named tunnel configuration from a profile.
+
+```bash
+cfa-eng bastion delete-tunnel my-db --profile my-app
+```
+
+#### `bastion tunnel`
+
+Opens an SSH tunnel through the bastion to a remote host using a saved tunnel
+configuration.
+
+```bash
+cfa-eng bastion tunnel --name my-db --profile my-app
+```
+
+| Option | Description |
+|---|---|
+| `--name` | Name of the tunnel configuration to use |
+
+---
+
+### `tofu` — Run OpenTofu operations
+
+The `tofu` commands wrap common OpenTofu operations. They automatically fetch
+secrets from Doppler, select the appropriate AWS profile for the environment,
+and run `tofu init` before each operation.
+
+A profile is required for all `tofu` commands and supplies the environment,
+AWS credentials, project name, and Doppler project.
+
+All `tofu` commands accept:
+
+| Option | Description |
+|---|---|
+| `--profile NAME` | Profile to use (default: `$CFA_PROFILE`) |
+
+These commands must be run from the root of an OpenTofu repository (a directory
+containing `tofu/configs/`).
+
+#### `tofu plan CONFIG`
+
+Runs `tofu plan -concise` for the given configuration layer.
+
+```bash
+cfa-eng tofu plan foundation --profile my-app
+cfa-eng tofu plan application --profile my-app --args="-out tfplan"
+```
+
+| Option | Description |
+|---|---|
+| `--args STRING` | Extra arguments forwarded to `tofu plan` |
+
+#### `tofu apply CONFIG`
+
+Runs `tofu apply` for the given configuration layer.
+
+```bash
+cfa-eng tofu apply foundation --profile my-app
+cfa-eng tofu apply application --profile my-app --args="-auto-approve"
+```
+
+| Option | Description |
+|---|---|
+| `--args STRING` | Extra arguments forwarded to `tofu apply` |
+
+#### `tofu destroy CONFIG`
+
+Runs `tofu destroy` for the given configuration layer.
+
+```bash
+cfa-eng tofu destroy application --profile my-app
+```
+
+| Option | Description |
+|---|---|
+| `--args STRING` | Extra arguments forwarded to `tofu destroy` |
+
+#### `tofu output CONFIG`
+
+Shows the outputs for the given configuration layer.
+
+```bash
+cfa-eng tofu output foundation --profile my-app
+cfa-eng tofu output foundation --profile my-app --args="-json"
+```
+
+| Option | Description |
+|---|---|
+| `--args STRING` | Extra arguments forwarded to `tofu output` |
+
+#### `tofu force-unlock CONFIG LOCK_ID`
+
+Force-unlocks a stuck state lock for the given configuration layer. Prompts for
+confirmation before proceeding. Does not fetch Doppler secrets.
+
+```bash
+cfa-eng tofu force-unlock foundation abc-1234-5678 --profile my-app
+```
+
+> [!WARNING]
+> Only use this if you are certain the lock is stale. Unlocking while another
+> operation is in progress will corrupt state.
+
+#### `tofu bootstrap`
+
+Bootstraps the remote S3 state backend for a new environment. If the state
+bucket does not yet exist, it applies the `foundation` configuration with a
+local backend first and then migrates state to S3.
+
+```bash
+cfa-eng tofu bootstrap --profile my-app
+```
+
+> [!NOTE]
+> `tofu bootstrap` always operates on `tofu/configs/foundation`.
+
+### AWS profile selection
+
+For `tofu` commands, the AWS profile is taken from the saved profile's
+`aws_profile` field. If no `aws_profile` is stored in the profile, the CLI
+selects a default based on the environment:
+
+| Environment | Default AWS profile |
+|---|---|
+| `production` | `shared-services-prod` |
+| All others | `shared-services-dev` |
+
+A red warning is printed before any operation targeting `production`.

cfa-eng-cli.gemspec

@@ -11,6 +11,8 @@ Gem::Specification.new do |s|
   s.authors     = ['Code for America']
   s.email       = 'infra@codeforamerica.org'
   s.files       = Dir['lib/**/*'] + Dir['Gemfile*'] + ['Rakefile']
+  s.bindir      = 'exe'
+  s.executables << 'cfa-eng'
   s.homepage    = 'https://codeforamerica.org'
   s.metadata    = {
     'bug_tracker_uri' => 'https://github.com/codeforamerica/cfa-eng-url/issues',

bin/cfa-eng exe/cfa-engbin/cfa-eng renamed to exe/cfa-eng

@@ -22,6 +22,9 @@ class CfaEng < Thor
 
   desc 'profile SUBCOMMAND', 'Commands for managing profiles.'
   subcommand 'profile', CfaEngCli::Commands::Profile
+
+  desc 'tofu SUBCOMMAND', 'Commands for running OpenTofu operations.'
+  subcommand 'tofu', CfaEngCli::Commands::Tofu
 end
 
 CfaEng.start(ARGV)

lib/cfa-eng-cli.rb

@@ -2,6 +2,7 @@
 
 require_relative 'cfa_eng_cli/bastion'
 require_relative 'cfa_eng_cli/commands'
+require_relative 'cfa_eng_cli/open_tofu'
 require_relative 'cfa_eng_cli/config'
 require_relative 'cfa_eng_cli/version'
 

lib/cfa_eng_cli/commands.rb

@@ -2,3 +2,4 @@
 
 require_relative 'commands/bastion'
 require_relative 'commands/profile'
+require_relative 'commands/tofu'