Skip to content

Commit 779c9aa

Browse files
rsteubersteube
committed
added AGENTS.md
1 parent 816b117 commit 779c9aa

1 file changed

Lines changed: 136 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Agent Documentation: carapace-aws
2+
3+
## Project Overview
4+
5+
This repository is a **shell completion provider for AWS CLI**. It uses [carapace](https://github.com/carapace-sh/carapace) to provide enriched, context-aware shell completions for all AWS services. The completions are generated from AWS botocore spec data and stored as YAML files.
6+
7+
## Architecture
8+
9+
### Two Binaries
10+
11+
1. **`carapace-aws`** (`cmd/carapace-aws/`): The actual completion binary. Registers AWS service commands and delegates completion to the carapace-bridge AWS completer.
12+
2. **`carapace-spec-botocore`** (`cmd/carapace-spec-botocore/`): Code generator that converts AWS CLI botocore specs into YAML command definitions.
13+
14+
### Directory Structure
15+
16+
```
17+
cmd/
18+
carapace-aws/ # Main completion binary
19+
cmd/
20+
root.go # CLI structure: root + service + operation commands
21+
botocore/ # ~280 YAML files (aws.<service>.yaml)
22+
botocore.go # Loads embedded YAML files
23+
botocore_generated.go # Service name → description map
24+
aws.<service>.yaml # Per-service command specs
25+
common/
26+
bridge.go # Delegates to carapace-bridge AWS completer
27+
generate/
28+
main.go # Orchestrates spec regeneration
29+
carapace-spec-botocore/ # Spec generator binary
30+
cmd/
31+
root.go # Parses botocore data → YAML
32+
customizations/ # ~40 service-specific customization files
33+
customizations.go
34+
s3.go, ecs.go, iam.go, etc.
35+
pkg/actions/aws/ # Go completion actions (profile, region)
36+
```
37+
38+
### Key Dependencies
39+
40+
- `github.com/carapace-sh/carapace` - Shell completion framework
41+
- `github.com/carapace-sh/carapace-bridge` - Bridges to external completers (including AWS CLI itself)
42+
- `github.com/carapace-sh/carapace-spec` - Command spec types and `ToCobra()` conversion
43+
- `pflag` is **replaced** with `carapace-sh/carapace-pflag` (see `go.mod` line 24)
44+
45+
## Essential Commands
46+
47+
### Build
48+
```bash
49+
go build -C cmd/carapace-aws -v .
50+
# or for all cmd/ dirs:
51+
ls cmd/ | xargs -I'{}' sh -c "cd ./cmd/{} && go build -v ."
52+
```
53+
54+
### Test
55+
```bash
56+
go test -v -coverprofile=profile.cov ./...
57+
# Integration tests (requires AWS credentials):
58+
go test -C cmd/carapace-aws -tags integration -run TestServices -c .
59+
```
60+
61+
### Lint/Format
62+
```bash
63+
gofmt -d -s . # Check formatting
64+
go fmt ./...
65+
staticcheck ./...
66+
```
67+
68+
### Generate (Update AWS Specs)
69+
```bash
70+
# Regenerates YAML specs from AWS CLI repo (reads version from package.json)
71+
go generate ./...
72+
73+
# The generate command clones aws/aws-cli, runs carapace-spec-botocore,
74+
# and regenerates botocore_generated.go
75+
```
76+
77+
### Release
78+
```bash
79+
goreleaser release --clean # Triggered by git tags
80+
```
81+
82+
## Code Generation Workflow
83+
84+
1. `package.json` contains: `"aws": "https://github.com/aws/aws-cli#2.34.61"`
85+
2. `go generate` clones the AWS CLI repo at that tag
86+
3. `carapace-spec-botocore` parses botocore data and outputs YAML files
87+
4. Customizations modify specs (add/remove commands, flags, descriptions)
88+
5. `botocore_generated.go` is regenerated with service map
89+
90+
**Adding a new customization:**
91+
- Create `cmd/carapace-spec-botocore/cmd/customizations/<service>.go`
92+
- Register a function in `init()` that modifies the command spec
93+
- Add to the customizations map: `customizations["servicename"] = func(cmd *command.Command) error { ... }`
94+
95+
## Spec Format
96+
97+
AWS command specs are YAML files following this schema:
98+
99+
```yaml
100+
# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
101+
name: ec2
102+
description: Amazon Elastic Compute Cloud
103+
commands:
104+
- name: accept-address-transfer
105+
description: Accepts an Elastic IP address transfer.
106+
flags:
107+
--address=!: The Elastic IP address (required)
108+
--dry-run: Check permissions without making request
109+
```
110+
111+
Flag conventions:
112+
- `--flag=!` = required flag
113+
- `--flag=` = optional flag
114+
- `nargs: -1` = variadic (multiple values allowed)
115+
116+
## Gotchas
117+
118+
1. **CamelCase → kebab-case**: The generator has a `CamelCaseToDash()` function with extensive hardcoded fixes for edge cases (e.g., `ec2-instance-id`, `whats-app` → `whatsapp`).
119+
120+
2. **S3 is special**: S3 commands are named `s3api` not `s3`. The `s3.go` customization renames the spec.
121+
122+
3. **Extension commands** (`cli-dev`, `configure`, `ddb`, `history`, `login`, `logout`) bypass flag parsing and delegate entirely to the bridge completer.
123+
124+
4. **PreInvoke for flag completion**: Flags not explicitly defined in the YAML spec get completion delegated to the AWS CLI bridge via `PreInvoke`.
125+
126+
5. **Bridged completions**: Most actual completion logic lives in `carapace-bridge` (external). This repo defines the command structure and delegates to it.
127+
128+
6. **pflag replacement**: The `replace github.com/spf13/pflag => github.com/carapace-sh/carapace-pflag v1.1.0` directive in `go.mod` ensures carapace's patched pflag is used.
129+
130+
7. **Gorealeaser hooks**: Runs `go generate` before build (`before.hooks`).
131+
132+
## Testing Approach
133+
134+
- Unit tests for Go code
135+
- Integration tests require AWS credentials (`-tags integration`)
136+
- CI runs full test suite + staticcheck + formatting check

0 commit comments

Comments
 (0)