swa 0.8.6 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c07723e018108852c4b08553e806bdd53e80e88988e2fa1dbdef99b8aebbab3
-  data.tar.gz: 2835192e6d525d1bdb79ae94b698f8435f3311bba1deb145d20a5ab9257e373e
+  metadata.gz: 7881424f25a25e4b4eaabbeb23b23661ca08294c2b7a766a8463ad111a0a31c7
+  data.tar.gz: b35dde4b7c9e44486eb61b31f9cec0bf3656d8f7c539e2e9f80a1dc128e49fc5
 SHA512:
-  metadata.gz: 0cc932811e45b02d1d1b254ca52ba54e188281f59764e4b0efaae4164bdc2695f7c7cfcbab3f0ab92c6cbcfd417b3ef17e05e5a76ce2b29820c7c936cfb65a47
-  data.tar.gz: fc6105d43f360c2db2be74a594bd855a4567618143edbefb6343f46c5dd137af87971468a1d85c9cad5ef2a0b7d2c952f8b9b10c02b60f29f90c910f615e8587
+  metadata.gz: f494cf53c307bb2a6c9603ad59c6912a0371192184c5a2934a55aa0c8cadb692e18148481d306ee124b7113ce02b646e7972fbd2aa1ee2b0def09f778eb1e9be
+  data.tar.gz: 94576ae0691f6b37caccaf7da735b02f107737da10c5ac2781825c90e0fd8439fbb86843039f12a96266ee0c1bd2530f1f39224be21c83823ae0ab8a755cc1b1

data/.beads/.gitignore

@@ -0,0 +1,18 @@
+# SQLite databases
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+
+# Daemon runtime files
+daemon.lock
+daemon.log
+daemon.pid
+bd.sock
+
+# Legacy database files
+db.sqlite
+bd.db
+
+# Keep JSONL exports (source of truth for git)
+!*.jsonl

data/.beads/issues.jsonl

@@ -0,0 +1,5 @@
+{"id":"swa-1","title":"Add CloudTrail support with \"swa cloudtrail query\" command","description":"Implement CloudTrail support in swa to enable querying CloudTrail events. Initial implementation should support \"swa cloudtrail query\" to return the most recent 50 CloudTrail entries. Future enhancements will add filtering and ordering options.","design":"Follow the existing swa architecture patterns:\n\n1. Add aws-sdk-cloudtrail dependency to swa.gemspec\n2. Create lib/swa/cloud_trail/ directory for resource models\n3. Create lib/swa/cloud_trail/event.rb to wrap CloudTrail event records\n4. Create lib/swa/cli/cloud_trail_command.rb following pattern of other service commands\n5. Implement \"query\" subcommand using CollectionBehaviour mixin\n6. Use CloudTrail LookupEvents API to fetch recent events (default limit: 50)\n7. Implement summary() method for one-line event display\n8. Support standard data output (YAML/JSON with JMESPath)\n\nThe command structure should be:\n- swa cloudtrail query summary (default)\n- swa cloudtrail query data [jmespath-query]","acceptance_criteria":"- Running \"swa cloudtrail query\" returns the 50 most recent CloudTrail events\n- Output defaults to summary format (one line per event)\n- \"swa cloudtrail query data\" returns full event data in YAML\n- \"swa cloudtrail query data --json\" returns full event data in JSON\n- JMESPath queries work with the data output\n- Event summary shows key fields (timestamp, event name, username, source IP)\n- Follows existing swa architectural patterns and code style","notes":"Implemented and tested CloudTrail support. All acceptance criteria met:\n- Returns 50 most recent events by default\n- --limit option works correctly (fixed in commit 3012838)\n- Summary format shows timestamp, event name, username, event source\n- Data output in YAML/JSON works\n- JMESPath queries work\n- Follows swa architectural patterns","status":"closed","priority":2,"issue_type":"feature","assignee":"mikewilliams","created_at":"2025-10-25T16:03:46.156464+11:00","updated_at":"2025-10-26T10:19:01.802715+11:00","closed_at":"2025-10-26T10:19:01.802715+11:00"}
+{"id":"swa-2","title":"Add filtering options for cloudtrail events","description":"Add command-line options to filter CloudTrail events by common criteria like event source and event name. This will make it easier to narrow down results without piping through grep/jq.","design":"Add filtering options to the cloudtrail events command:\n\nOptions to add:\n- --source SERVICE - filter by event source (e.g., kms.amazonaws.com, sts.amazonaws.com)\n- --name EVENT_NAME - filter by event name (e.g., Decrypt, AssumeRole)\n\nImplementation approach:\n1. Add option declarations in cloudtrail_command.rb\n2. Apply filters to the collection before .take(max)\n3. Use lazy evaluation to maintain efficiency\n4. Consider using AWS CloudTrail LookupEvents API filters if available (check API docs)\n   - If API supports filtering, pass to lookup_events\n   - Otherwise, filter in Ruby after fetching\n\nFuture enhancements could add:\n- --user USERNAME - filter by username\n- --since/--until - time range filtering\n- --resource - filter by resource type/ARN","acceptance_criteria":"- Can filter by event source: swa cloudtrail events --source kms.amazonaws.com\n- Can filter by event name: swa cloudtrail events --name Decrypt\n- Can combine filters: swa cloudtrail events --source sts.amazonaws.com --name AssumeRole\n- Filters work with all output modes (summary, data)\n- Filters work correctly with --max option\n- Performance is reasonable (uses API filters if available)","notes":"Implemented filtering options for CloudTrail events:\n- Added --source option to filter by event source (e.g. kms.amazonaws.com)\n- Added --name option to filter by event name (e.g. Decrypt)\n- Handles CloudTrail API limitation (only one lookup_attribute at a time) by using most selective filter at API level and applying second filter in Ruby\n- All tests passing with various filter combinations\n- Works with all output modes (summary, data)","status":"closed","priority":2,"issue_type":"feature","assignee":"mikewilliams","created_at":"2025-10-25T16:55:05.923645+11:00","updated_at":"2025-10-25T22:34:46.729002+11:00","closed_at":"2025-10-25T22:34:46.729002+11:00"}
+{"id":"swa-3","title":"Add filtering by caller for cloudtrail events","description":"Add ability to filter CloudTrail events by the identity/caller that made the API call. This is useful for tracking down specific users, roles, or service accounts.","design":"Add --user/--caller option to filter CloudTrail events by the identity making the request.\n\nThe CloudTrail event structure has multiple identity-related fields:\n- username (from envelope) - simplified identity string\n- userIdentity.principalId (in CloudTrail event)\n- userIdentity.arn (in CloudTrail event) \n- userIdentity.userName (in CloudTrail event)\n\nImplementation approach:\n1. Add --user USERNAME option (or --caller)\n2. Consider matching against multiple fields for flexibility:\n   - Match against username field (envelope)\n   - Could also match against userIdentity.principalId or userName\n3. Support partial matching (substring) for convenience\n4. Investigate if CloudTrail LookupEvents API supports username filtering\n\nExamples:\n- swa cloudtrail events --user snowflake\n- swa cloudtrail events --user kafkatopicarchive\n- swa cloudtrail events --user system:serviceaccount\n\nConsider if this should be combined with swa-2 (general filtering) or kept separate.","acceptance_criteria":"- Can filter by caller/user: swa cloudtrail events --user USERNAME\n- Partial matching works (e.g., --user kafka matches kafkatopicarchive-*)\n- Works with other filters and --max option\n- Works with all output modes (summary, data)\n- Helpful error message if no events match the filter","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-10-25T16:55:56.999516+11:00","updated_at":"2025-10-25T22:48:57.404314+11:00","closed_at":"2025-10-25T22:48:57.404314+11:00"}
+{"id":"swa-4","title":"Add general --where filtering for CloudTrail events","description":"Add a flexible --where option that allows filtering CloudTrail events by any field in the CloudTrail event structure using a key=value or key=pattern syntax. This provides more flexible filtering than the specific --source and --name options.","design":"Add --where option for general field matching:\n\nSyntax: --where FIELD=VALUE\n- FIELD: JMESPath-style field path (e.g., awsRegion, userIdentity.type)\n- VALUE: String or wildcard pattern (supports * and ?)\n- Can be specified multiple times (AND logic)\n\nExamples:\n- swa cloudtrail events --where awsRegion=us-west-2\n- swa cloudtrail events --where userIdentity.type=AssumedRole\n- swa cloudtrail events --where userIdentity.sessionContext.sessionIssuer.arn=*:role/emr-iceberg-stats\n- swa cloudtrail events --where eventType=AwsApiCall --where readOnly=false\n\nImplementation approach:\n1. Accept multiple --where options (Clamp supports this)\n2. Parse each into field path and pattern\n3. Extract field values from CloudTrail event using JMESPath or nested hash access\n4. Match using compiled patterns (same as --name and --source)\n5. All --where conditions must match (AND logic)\n\nSince CloudTrail API doesn't support arbitrary field filtering, all filtering will be done in Ruby after fetching events.\n\nNote: This is complementary to --source and --name, which use API filtering when possible.","acceptance_criteria":"- Can filter by any field: swa cloudtrail events --where awsRegion=us-west-2\n- Supports nested fields: --where userIdentity.type=AssumedRole\n- Supports wildcards: --where sourceIPAddress=10.0.*\n- Multiple --where conditions work (AND logic)\n- Works with --source, --name, and --max options\n- Works with all output modes\n- Clear error message if field path is invalid","status":"closed","priority":2,"issue_type":"feature","assignee":"mikewilliams","created_at":"2025-10-25T22:38:44.843229+11:00","updated_at":"2025-10-26T10:16:23.846637+11:00","closed_at":"2025-10-26T10:16:23.846637+11:00"}
+{"id":"swa-5","title":"Add time-based filtering with --after and --before options","description":"Add --after and --before options to cloudtrail events command to filter events by time range. Use the existing parse_datetime function from base_command.rb to parse time arguments and pass StartTime and EndTime parameters to the CloudTrail LookupEvents API.","design":"Add time-based filtering options to cloudtrail events command:\n\nOptions to add:\n- --after TIME - filter events after this time\n- --before TIME - filter events before this time\n\nImplementation approach:\n1. Add option declarations in cloudtrail_command.rb\n2. Use parse_datetime function from base_command.rb (line 66) to parse time arguments\n3. Pass StartTime and EndTime parameters to CloudTrail LookupEvents API\n   - StartTime: corresponds to --after\n   - EndTime: corresponds to --before\n4. CloudTrail API supports these natively, so filtering happens at API level\n\nparse_datetime supports various formats:\n- Absolute: \"2025-01-15\", \"2025-01-15 14:30\"\n- Relative: \"yesterday\", \"last week\", \"2 days ago\"\n- Uses Chronic gem for natural language parsing\n\nExamples:\n- swa cloudtrail events --after \"last week\"\n- swa cloudtrail events --before \"2025-01-20\"\n- swa cloudtrail events --after \"yesterday\" --before \"today\"","acceptance_criteria":"- Can filter events after a time: swa cloudtrail events --after \"last week\"\n- Can filter events before a time: swa cloudtrail events --before \"2025-01-20\"\n- Can combine time filters: swa cloudtrail events --after \"yesterday\" --before \"today\"\n- Supports relative time expressions via parse_datetime\n- Works with other filters (--source, --name, --max)\n- Works with all output modes (summary, data)\n- Clear error message if time parsing fails","status":"closed","priority":2,"issue_type":"feature","assignee":"mikewilliams","created_at":"2025-10-25T22:42:48.949746+11:00","updated_at":"2025-10-25T22:54:47.74188+11:00","closed_at":"2025-10-25T22:54:47.74188+11:00"}

data/.rubocop.yml

@@ -0,0 +1,39 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/EmptyLinesAroundBlockBody:
+  Enabled: false
+  EnforcedStyle: empty_lines
+Layout/EmptyLinesAroundClassBody:
+  EnforcedStyle: empty_lines
+Layout/EmptyLinesAroundModuleBody:
+  EnforcedStyle: empty_lines
+
+Lint/DuplicateBranch:
+  Enabled: false
+Lint/NestedMethodDefinition:
+  Enabled: false
+
+Metrics/AbcSize:
+  Max: 40
+Metrics/BlockLength:
+  Max: 25
+  AllowedMethods:
+    - subcommand
+Metrics/ClassLength:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Max: 15
+Metrics/MethodLength:
+  Max: 30
+Metrics/PerceivedComplexity:
+  Max: 15
+
+Naming/HeredocDelimiterNaming:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+Style/StringLiterals:
+  EnforcedStyle: double_quotes

data/AGENTS.md

@@ -0,0 +1,541 @@
+# swa - AWS CLI (backwards)
+
+## Overview
+
+**swa** is an alternative CLI for AWS that inverts the typical command structure by placing verbs at the end rather than the beginning. The name "swa" is "AWS" spelled backwards, reflecting this design philosophy.
+
+**Version:** 0.8.6
+**Repository:** https://github.com/mdub/swa
+**License:** MIT
+**Language:** Ruby
+
+### Command structure comparison
+
+```bash
+# Standard AWS CLI
+aws ec2 terminate-instances --instance-ids i-9336f049
+
+# swa
+swa ec2 instance i-9336f049 terminate
+```
+
+## What swa does
+
+swa provides a more intuitive interface to AWS services by organizing commands hierarchically by service, resource type, and then action. It supports:
+
+- **Resource inspection** - View details of AWS resources in YAML or JSON format
+- **Resource filtering** - Filter by tags, states, dates, and custom predicates
+- **Batch operations** - List and query collections of resources
+- **JMESPath queries** - Extract specific fields from resource data
+- **Smart resource resolution** - Automatically detect resource types from IDs (e.g., `swa i-123456` → EC2 instance)
+- **Resource actions** - Perform operations like terminate, delete, put, get, etc.
+
+### Supported AWS services
+
+| Service | Resource types |
+|---------|----------------|
+| **EC2** | Instances, AMIs, Key-pairs, Security Groups, Snapshots, Volumes, Subnets, VPCs |
+| **S3** | Buckets, Objects, Object versions |
+| **IAM** | Users, Roles, Groups, Policies, Instance Profiles |
+| **Glue** | Databases, Tables, Crawlers, Jobs, Job Runs, Partitions |
+| **Athena** | Catalogs, Databases, Query Executions |
+| **KMS** | Keys, Aliases |
+| **CloudFormation** | Stacks, Templates, Parameters, Outputs, Resources |
+| **ELB** | Load Balancers (Classic) |
+| **LakeFormation** | Data Lake Settings, LF-Tags, Permissions, Resources |
+
+## Codebase architecture
+
+### Directory structure
+
+```
+/
+├── exe/
+│   └── swa                    # Main executable entry point
+├── lib/
+│   └── swa/
+│       ├── cli/               # Command-line interface layer
+│       │   ├── main_command.rb            # Top-level command dispatcher
+│       │   ├── base_command.rb            # Base class for all commands
+│       │   ├── *_command.rb               # Service-specific commands (9 services)
+│       │   ├── collection_behaviour.rb    # Mixin for listing resources
+│       │   ├── item_behaviour.rb          # Mixin for single resource ops
+│       │   ├── data_output.rb             # Output formatting (YAML/JSON)
+│       │   ├── filter_options.rb          # AWS filtering
+│       │   ├── tag_filter_options.rb      # Tag-based filtering
+│       │   └── selector.rb                # Custom filter predicates
+│       ├── athena/            # Athena resource models
+│       ├── cloud_formation/   # CloudFormation resource models
+│       ├── ec2/               # EC2 resource models
+│       ├── elb/               # ELB resource models
+│       ├── glue/              # Glue resource models
+│       ├── iam/               # IAM resource models
+│       ├── kms/               # KMS resource models
+│       ├── lake_formation/    # LakeFormation resource models
+│       ├── s3/                # S3 resource models
+│       ├── resource.rb        # Base class for AWS SDK resources
+│       ├── record.rb          # Base class for API response records
+│       ├── data_presentation.rb  # Display formatting utilities
+│       └── version.rb         # Version constant
+└── swa.gemspec                # Gem specification
+```
+
+### Key architectural patterns
+
+#### 1. Command hierarchy (Clamp framework)
+
+```
+MainCommand (Swa::CLI::MainCommand)
+├── BaseCommand (authentication, AWS client setup)
+├── Service Commands (e.g., Ec2Command, S3Command)
+│   ├── Collection Subcommands (e.g., "instances", "buckets")
+│   │   └── Actions: summary, ids, data
+│   └── Item Subcommands (e.g., "instance", "bucket")
+│       └── Actions: summary, data, [resource-specific actions]
+```
+
+- **MainCommand** - Top-level dispatcher, includes smart resource ID prefix matching
+- **BaseCommand** - Shared functionality: AWS authentication, region config, logging
+- **Service Commands** - One per AWS service (9 total)
+- **Mixins:**
+  - `CollectionBehaviour` - Provides `summary`, `ids`, `data` subcommands for listings
+  - `ItemBehaviour` - Provides `summary`, `data` subcommands for individual items
+
+#### 2. Resource wrapping pattern
+
+Two base classes wrap AWS SDK objects:
+
+**Resource** class (`lib/swa/resource.rb`):
+- Used for AWS SDK resource objects (EC2, S3, IAM, CloudFormation, ELB)
+- Delegates method calls to underlying SDK resource
+- Provides standard interface:
+  - `summary()` - One-line display string
+  - `id` - Resource identifier
+  - `data()` - Full data as hash (for YAML/JSON output)
+
+**Record** class (`lib/swa/record.rb`):
+- Used for API response data structures (Glue, Athena, KMS, LakeFormation)
+- Wraps plain Ruby hashes/structs from API responses
+- Same standard interface as Resource
+
+Each AWS service has specialized subclasses in its directory (e.g., `Swa::EC2::Instance`, `Swa::S3::Bucket`).
+
+#### 3. Filtering and querying
+
+Multiple filtering mechanisms work together:
+
+- **FilterOptions** - AWS API-level filters (e.g., `--filter name=value`)
+- **TagFilterOptions** - Tag-based filtering (e.g., `--tagged environment=prod`)
+- **Selector** - Custom Ruby predicates for in-memory filtering
+- **Date ranges** - Via Chronic gem for date/time parsing
+- **JMESPath** - Query expressions for extracting specific fields from output
+
+#### 4. Output formatting
+
+**DataOutput** module provides:
+- YAML output (default)
+- JSON output (`--json` / `-J`)
+- JMESPath query support (as command argument)
+- Pretty-printing with indentation
+- CSV support for certain data types
+
+### Core components
+
+#### CLI layer (`lib/swa/cli/`)
+
+| File | Purpose |
+|------|---------|
+| `main_command.rb` | Top-level command, service dispatch, smart ID prefix matching |
+| `base_command.rb` | AWS authentication, region config, client setup |
+| `athena_command.rb` | Athena catalogs, databases, queries |
+| `cloud_formation_command.rb` | CloudFormation stacks, templates |
+| `ec2_command.rb` | EC2 instances, images, volumes, security groups, etc. |
+| `elb_command.rb` | Elastic Load Balancers |
+| `glue_command.rb` | Glue databases, tables, jobs, crawlers |
+| `iam_command.rb` | IAM users, roles, groups, policies |
+| `kms_command.rb` | KMS keys, aliases |
+| `lake_formation_command.rb` | LakeFormation tags, permissions |
+| `s3_command.rb` | S3 buckets, objects |
+| `collection_behaviour.rb` | Mixin: list resources, filter, output |
+| `item_behaviour.rb` | Mixin: single resource inspection |
+| `data_output.rb` | YAML/JSON formatting, JMESPath |
+| `filter_options.rb` | AWS API filter options |
+| `tag_filter_options.rb` | Tag-based filter options |
+| `selector.rb` | Custom predicate filtering |
+
+#### Resource models
+
+Each AWS service has a directory with resource model classes:
+
+- **EC2** - 9 resource types (Instance, Image, KeyPair, SecurityGroup, Snapshot, Volume, Subnet, Vpc, TaggedResource)
+- **S3** - 6 types (Bucket, Object, ObjectVersion, ObjectListEntry, ObjectSummary, ObjectPrefix)
+- **IAM** - 7 types (User, Role, Group, Policy, RolePolicy, InstanceProfile, Credentials)
+- **Glue** - 8 types (Database, Table, Job, JobRun, JobBookmarkEntry, Crawler, Crawl, Partition)
+- **Athena** - 4 types (Catalog, Database, QueryExecution, WorkGroup)
+- **KMS** - 2 types (Key, Alias)
+- **CloudFormation** - 1 type (Stack)
+- **ELB** - 1 type (LoadBalancer)
+- **LakeFormation** - 4 types (DataLakeSettings, Permission, ResourceInfo, Tag)
+
+Each model:
+- Extends `Resource` or `Record`
+- Implements `summary()` for display
+- Exposes attributes via method delegation
+- May implement custom actions (e.g., `terminate`, `delete`, `put`)
+
+### Key dependencies
+
+```ruby
+# AWS SDK (modular approach)
+aws-sdk-athena, aws-sdk-cloudformation, aws-sdk-ec2,
+aws-sdk-elasticloadbalancing, aws-sdk-glue, aws-sdk-iam,
+aws-sdk-kms, aws-sdk-lakeformation, aws-sdk-s3
+
+# CLI framework
+clamp (~> 1.1.0)              # Command-line parsing
+
+# Data processing
+multi_json                    # JSON serialization
+jmespath                      # Query language for JSON
+chronic                       # Natural language date/time parsing
+ox                            # XML parsing
+
+# Display formatting
+console_logger                # Structured logging
+bytesize                      # Human-readable byte sizes
+
+# Utilities
+stackup (~> 1.0.0)            # CloudFormation tooling
+```
+
+## How the codebase hangs together
+
+### 1. Command execution flow
+
+```
+User runs: swa ec2 instance i-123456 data --json
+    ↓
+MainCommand.run (lib/swa/cli/main_command.rb)
+    ↓
+Ec2Command (lib/swa/cli/ec2_command.rb)
+    ↓
+InstanceCommand (defined in Ec2Command via subcommand DSL)
+    ↓
+ItemBehaviour#execute (lib/swa/cli/item_behaviour.rb)
+    ↓
+find_item method (retrieves AWS::EC2::Instance)
+    ↓
+Wrapped as Swa::EC2::Instance (lib/swa/ec2/instance.rb)
+    ↓
+DataCommand.execute (outputs data as JSON)
+    ↓
+Output formatted and printed to stdout
+```
+
+### 2. Smart prefix matching
+
+MainCommand includes logic to detect resource prefixes and route commands automatically:
+
+```ruby
+# In lib/swa/cli/main_command.rb
+case parameter
+when /^i-/         then ["ec2", "instance", parameter]
+when /^ami-/       then ["ec2", "image", parameter]
+when /^sg-/        then ["ec2", "security-group", parameter]
+when /^vol-/       then ["ec2", "volume", parameter]
+when /^snap-/      then ["ec2", "snapshot", parameter]
+when /^s3:\/\//    then s3_url_command_line(parameter)
+when /^arn:.*:iam:.*:policy\//  then ["iam", "policy", parameter]
+# ... etc
+```
+
+This allows shortcut commands like:
+```bash
+swa i-123456 data              # → swa ec2 instance i-123456 data
+swa sg-789abc data             # → swa ec2 security-group sg-789abc data
+```
+
+### 3. Collection vs. item commands
+
+**Collection commands** (plural, e.g., "instances"):
+- List multiple resources
+- Apply filters (tags, state, date ranges, AWS API filters)
+- Support three output modes:
+  - `summary` - One-line per resource (default)
+  - `ids` - Just resource identifiers
+  - `data` - Full YAML/JSON with optional JMESPath
+
+**Item commands** (singular, e.g., "instance"):
+- Address a single resource by ID
+- Support inspection (`summary`, `data`)
+- Support resource-specific actions (`terminate`, `delete`, `get`, `put`, etc.)
+
+### 4. AWS SDK integration
+
+BaseCommand establishes AWS clients:
+```ruby
+def aws_config
+  @aws_config ||= {}.tap do |config|
+    config[:region] = region if region
+    config[:credentials] = aws_credentials if aws_credentials
+    # ... other config
+  end
+end
+```
+
+Service commands create AWS SDK clients:
+```ruby
+def ec2
+  @ec2 ||= Aws::EC2::Resource.new(aws_config)
+end
+```
+
+Resource wrappers delegate to SDK objects:
+```ruby
+class Instance < Swa::Resource
+  def summary
+    [id, image_id, instance_type, state.name, private_ip_address].join(" ")
+  end
+end
+```
+
+### 5. Data presentation
+
+Resources implement `data()` method to return hash for serialization:
+```ruby
+def data
+  {
+    "InstanceId" => id,
+    "ImageId" => image_id,
+    "InstanceType" => instance_type,
+    "State" => state.name,
+    # ... etc
+  }
+end
+```
+
+DataOutput handles formatting:
+- Applies JMESPath query if specified
+- Serializes to YAML (default) or JSON
+- Pretty-prints with proper indentation
+
+### 6. Extension points
+
+The architecture makes it easy to add new services or resources:
+
+1. **Add a new service:**
+   - Create `lib/swa/cli/new_service_command.rb`
+   - Extend `BaseCommand`
+   - Define collection and item subcommands
+   - Register in `MainCommand`
+
+2. **Add a new resource type:**
+   - Create `lib/swa/new_service/new_resource.rb`
+   - Extend `Resource` or `Record`
+   - Implement `summary()` and optionally `data()`
+   - Add command in service command class
+
+3. **Add a new action:**
+   - Define method in resource class
+   - Add subcommand in item command
+   - Handle action-specific options
+
+## Usage patterns
+
+### Basic inspection
+
+```bash
+# List resources
+swa ec2 instances summary
+swa s3 buckets
+swa iam users
+
+# Inspect single resource
+swa ec2 instance i-123456 data
+swa s3 bucket my-bucket data
+swa iam user alice data --json
+```
+
+### Filtering
+
+```bash
+# By tag
+swa ec2 instances --tagged environment=prod
+
+# By state
+swa ec2 instances --state running
+
+# By AWS API filter
+swa ec2 instances --filter availability-zone=us-east-1a
+
+# By date range
+swa ec2 snapshots --since "last week"
+```
+
+### Querying with JMESPath
+
+```bash
+# Extract specific fields
+swa ec2 instances data '[].{Id:InstanceId,Type:InstanceType,State:State.Name}'
+
+# Get just IPs
+swa ec2 instances data '[].PrivateIpAddress'
+
+# Complex query
+swa s3 buckets data '[?CreationDate > `2024-01-01`].Name'
+```
+
+### Resource actions
+
+```bash
+# EC2
+swa ec2 instance i-123456 terminate
+
+# S3
+swa s3 bucket my-bucket object mykey get > file.txt
+echo "content" | swa s3 bucket my-bucket object mykey put
+
+# IAM
+swa iam role my-role assume --session-name mysession
+
+# Glue
+swa glue job my-job start
+swa glue crawler my-crawler start
+```
+
+### Complex operations
+
+```bash
+# Athena query execution
+swa athena query "SELECT * FROM mytable" -D mydb -O s3://bucket/path/
+
+# Glue database and table addressing
+swa glue database mydb table mytable data
+
+# LakeFormation permissions
+swa glue database mydb table mytable lf-permissions
+
+# CloudFormation stack inspection
+swa cf stack my-stack template
+swa cf stack my-stack outputs
+```
+
+### Smart shortcuts
+
+```bash
+# Automatic resource type detection
+swa i-123456 data                    # EC2 instance
+swa ami-789abc data                  # EC2 AMI
+swa sg-456def data                   # EC2 security group
+swa s3://my-bucket/path/file get     # S3 object
+swa arn:aws:iam::123:policy/MyPolicy # IAM policy
+```
+
+## Development focus areas
+
+Based on recent commit history:
+- Glue and LakeFormation integration (active development)
+- ARN-based resource addressing
+- Enhanced filtering and pattern matching
+- Catalog specification for Glue resources
+
+The tool appears to be particularly focused on AWS data services (Glue, Athena, LakeFormation) while maintaining broad coverage of core AWS services.
+
+## Issue Tracking with bd (beads)
+
+**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
+
+### Why bd?
+
+- Dependency-aware: Track blockers and relationships between issues
+- Git-friendly: Auto-syncs to JSONL for version control
+- Agent-optimized: JSON output, ready work detection, discovered-from links
+- Prevents duplicate tracking systems and confusion
+
+### Quick Start
+
+**Check for ready work:**
+```bash
+bd ready --json
+```
+
+**Create new issues:**
+```bash
+bd create "Issue title" -t bug|feature|task -p 0-4 --json
+bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
+```
+
+**Claim and update:**
+```bash
+bd update bd-42 --status in_progress --json
+bd update bd-42 --priority 1 --json
+```
+
+**Complete work:**
+```bash
+bd close bd-42 --reason "Completed" --json
+```
+
+### Issue Types
+
+- `bug` - Something broken
+- `feature` - New functionality
+- `task` - Work item (tests, docs, refactoring)
+- `epic` - Large feature with subtasks
+- `chore` - Maintenance (dependencies, tooling)
+
+### Priorities
+
+- `0` - Critical (security, data loss, broken builds)
+- `1` - High (major features, important bugs)
+- `2` - Medium (default, nice-to-have)
+- `3` - Low (polish, optimization)
+- `4` - Backlog (future ideas)
+
+### Workflow for AI Agents
+
+1. **Check ready work**: `bd ready` shows unblocked issues
+2. **Claim your task**: `bd update <id> --status in_progress`
+3. **Work on it**: Implement, test, document
+4. **Discover new work?** Create linked issue:
+   - `bd create "Found bug" -p 1 --deps discovered-from:<parent-id>`
+5. **Complete**: `bd close <id> --reason "Done"`
+
+### Auto-Sync
+
+bd automatically syncs with git:
+- Exports to `.beads/issues.jsonl` after changes (5s debounce)
+- Imports from JSONL when newer (e.g., after `git pull`)
+- No manual export/import needed!
+
+### MCP Server (Recommended)
+
+If using Claude or MCP-compatible clients, install the beads MCP server:
+
+```bash
+pip install beads-mcp
+```
+
+Add to MCP config (e.g., `~/.config/claude/config.json`):
+```json
+{
+  "beads": {
+    "command": "beads-mcp",
+    "args": []
+  }
+}
+```
+
+Then use `mcp__beads__*` functions instead of CLI commands.
+
+### Important Rules
+
+- ✅ Use bd for ALL task tracking
+- ✅ Always use `--json` flag for programmatic use
+- ✅ Link discovered work with `discovered-from` dependencies
+- ✅ Check `bd ready` before asking "what should I work on?"
+- ❌ Do NOT create markdown TODO lists
+- ❌ Do NOT use external issue trackers
+- ❌ Do NOT duplicate tracking systems
+
+For more details, see README.md and QUICKSTART.md.

data/CLAUDE.md

@@ -0,0 +1,5 @@
+**Note**: This project uses [bd (beads)](https://github.com/steveyegge/beads)
+for issue tracking. Use `bd` commands instead of markdown TODOs.
+See AGENTS.md for workflow details.
+
+@AGENTS.md

data/Gemfile

@@ -1,4 +1,12 @@
-source 'https://rubygems.org'
+# frozen_string_literal: true
+
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in swa.gemspec
 gemspec
+
+group :development do
+  gem "bundler", "~> 2.1"
+  gem "rake", "~> 12.0"
+  gem "rubocop", "~> 1.0"
+end

data/README.md

@@ -82,11 +82,6 @@ SWA is packaged as a Ruby gem, and can be installed with:
 
     gem install swa
 
-On a Mac, I recommend [brew-gem](https://github.com/sportngin/brew-gem) for easy system-wide installation:
-
-    brew install brew-gem
-    brew gem install swa
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/mdub/swa.

data/Rakefile

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require "bundler/setup"
 require "swa"

data/exe/swa

@@ -1,6 +1,7 @@
 #! /usr/bin/env ruby
+# frozen_string_literal: true
 
-$LOAD_PATH << File.expand_path("../../lib", __FILE__)
+$LOAD_PATH << File.expand_path("../lib", __dir__)
 
 require "swa/cli/main_command"