|
1 | 1 | # AGENTS.md |
2 | 2 |
|
3 | | -This file provides guidance to AI coding assistants when working with code in this repository. |
| 3 | +Coder Registry: Terraform modules/templates for Coder workspaces under `registry/[namespace]/modules/` and `registry/[namespace]/templates/`. |
4 | 4 |
|
5 | | -## Project Overview |
6 | | - |
7 | | -The Coder Registry is a community-driven repository for Terraform modules and templates that extend Coder workspaces. It's organized with: |
8 | | - |
9 | | -- **Modules**: Individual components and tools (IDEs, auth integrations, dev tools) |
10 | | -- **Templates**: Complete workspace configurations for different platforms |
11 | | -- **Namespaces**: Each contributor has their own namespace under `/registry/[namespace]/` |
12 | | - |
13 | | -## Common Development Commands |
14 | | - |
15 | | -### Formatting |
| 5 | +## Commands |
16 | 6 |
|
17 | 7 | ```bash |
18 | | -bun run fmt # Format all code (Prettier + Terraform) |
19 | | -bun run fmt:ci # Check formatting (CI mode) |
20 | | -``` |
21 | | - |
22 | | -### Testing |
23 | | - |
24 | | -```bash |
25 | | -# Test all modules with .tftest.hcl files |
26 | | -bun run test |
27 | | - |
28 | | -# Test specific module (from module directory) |
29 | | -terraform init -upgrade |
30 | | -terraform test -verbose |
31 | | - |
32 | | -# Validate Terraform syntax |
33 | | -./scripts/terraform_validate.sh |
34 | | -``` |
35 | | - |
36 | | -### Module Creation |
37 | | - |
38 | | -```bash |
39 | | -# Generate new module scaffold |
40 | | -./scripts/new_module.sh namespace/module-name |
41 | | -``` |
42 | | - |
43 | | -### TypeScript Testing & Setup |
44 | | - |
45 | | -The repository uses Bun for TypeScript testing with utilities: |
46 | | - |
47 | | -- `test/test.ts` - Testing utilities for container management and Terraform operations |
48 | | -- `setup.ts` - Test cleanup (removes .tfstate files and test containers) |
49 | | -- Container-based testing with Docker for module validation |
50 | | - |
51 | | -## Architecture & Organization |
52 | | - |
53 | | -### Directory Structure |
54 | | - |
55 | | -``` |
56 | | -registry/[namespace]/ |
57 | | -├── README.md # Contributor info with frontmatter |
58 | | -├── .images/ # Namespace avatar (avatar.png/svg) |
59 | | -├── modules/ # Individual components |
60 | | -│ └── [module]/ # Each module has main.tf, README.md, tests |
61 | | -└── templates/ # Complete workspace configs |
62 | | - └── [template]/ # Each template has main.tf, README.md |
63 | | -``` |
64 | | - |
65 | | -### Key Components |
66 | | - |
67 | | -**Module Structure**: Each module contains: |
68 | | - |
69 | | -- `main.tf` - Terraform implementation |
70 | | -- `README.md` - Documentation with YAML frontmatter |
71 | | -- `.tftest.hcl` - Terraform test files (required) |
72 | | -- `run.sh` - Optional startup script |
73 | | - |
74 | | -**Template Structure**: Each template contains: |
75 | | - |
76 | | -- `main.tf` - Complete Coder template configuration |
77 | | -- `README.md` - Documentation with YAML frontmatter |
78 | | -- Additional configs, scripts as needed |
79 | | - |
80 | | -### README Frontmatter Requirements |
81 | | - |
82 | | -All modules/templates require YAML frontmatter: |
83 | | - |
84 | | -```yaml |
85 | | ---- |
86 | | -display_name: "Module Name" |
87 | | -description: "Brief description" |
88 | | -icon: "../../../../.icons/tool.svg" |
89 | | -verified: false |
90 | | -tags: ["tag1", "tag2"] |
91 | | ---- |
| 8 | +bun run fmt # Format code (Prettier + Terraform) - run before commits |
| 9 | +bun run tftest # Run all Terraform tests |
| 10 | +bun run tstest # Run all TypeScript tests |
| 11 | +terraform init -upgrade && terraform test -verbose # Test single module (run from module dir) |
| 12 | +bun test main.test.ts # Run single TS test (from module dir) |
| 13 | +./scripts/terraform_validate.sh # Validate Terraform syntax |
| 14 | +./scripts/new_module.sh ns/name # Create new module scaffold |
| 15 | +.github/scripts/version-bump.sh patch | minor | major # Bump module version after changes |
92 | 16 | ``` |
93 | 17 |
|
94 | | -## Testing Requirements |
95 | | - |
96 | | -### Module Testing |
97 | | - |
98 | | -- Every module MUST have `.tftest.hcl` test files |
99 | | -- Optional `main.test.ts` files for container-based testing or complex business logic validation |
100 | | -- Tests use Docker containers with `--network=host` flag |
101 | | -- Linux required for testing (Docker Desktop on macOS/Windows won't work) |
102 | | -- Use Colima or OrbStack on macOS instead of Docker Desktop |
103 | | - |
104 | | -### Test Utilities |
105 | | - |
106 | | -The `test/test.ts` file provides: |
107 | | - |
108 | | -- `runTerraformApply()` - Execute Terraform with variables |
109 | | -- `executeScriptInContainer()` - Run coder_script resources in containers |
110 | | -- `testRequiredVariables()` - Validate required variables |
111 | | -- Container management functions |
112 | | - |
113 | | -## Validation & Quality |
114 | | - |
115 | | -### Automated Validation |
116 | | - |
117 | | -The Go validation tool (`cmd/readmevalidation/`) checks: |
118 | | - |
119 | | -- Repository structure integrity |
120 | | -- Contributor README files |
121 | | -- Module and template documentation |
122 | | -- Frontmatter format compliance |
123 | | - |
124 | | -### Versioning |
125 | | - |
126 | | -Use semantic versioning for modules: |
127 | | - |
128 | | -- **Patch** (1.2.3 → 1.2.4): Bug fixes |
129 | | -- **Minor** (1.2.3 → 1.3.0): New features, adding inputs |
130 | | -- **Major** (1.2.3 → 2.0.0): Breaking changes |
131 | | - |
132 | | -## Dependencies & Tools |
133 | | - |
134 | | -### Required Tools |
135 | | - |
136 | | -- **Terraform** - Module development and testing |
137 | | -- **Docker** - Container-based testing |
138 | | -- **Bun** - JavaScript runtime for formatting/scripts |
139 | | -- **Go 1.23+** - Validation tooling |
140 | | - |
141 | | -### Development Dependencies |
142 | | - |
143 | | -- Prettier with Terraform and shell plugins |
144 | | -- TypeScript for test utilities |
145 | | -- Various npm packages for documentation processing |
146 | | - |
147 | | -## Workflow Notes |
148 | | - |
149 | | -### Contributing Process |
| 18 | +## Structure |
150 | 19 |
|
151 | | -1. Create namespace (first-time contributors) |
152 | | -2. Generate module/template files using scripts |
153 | | -3. Implement functionality and tests |
154 | | -4. Run formatting and validation |
155 | | -5. Submit PR with appropriate template |
| 20 | +- **Modules**: `registry/[ns]/modules/[name]/` with `main.tf`, `README.md` (YAML frontmatter), `.tftest.hcl` (required) |
| 21 | +- **Templates**: `registry/[ns]/templates/[name]/` with `main.tf`, `README.md` |
| 22 | +- **Validation**: `cmd/readmevalidation/` (Go) validates structure/frontmatter; URLs must be relative, not absolute |
156 | 23 |
|
157 | | -### Testing Workflow |
| 24 | +## Code Style |
158 | 25 |
|
159 | | -- All modules must pass `terraform test` |
160 | | -- Use `bun run test` for comprehensive testing |
161 | | -- Format code with `bun run fmt` before submission |
162 | | -- Manual testing recommended for templates |
| 26 | +- Every module MUST have `.tftest.hcl` tests; optional `main.test.ts` for container/script tests |
| 27 | +- README frontmatter: `display_name`, `description`, `icon`, `verified: false`, `tags` |
| 28 | +- Use semantic versioning; bump version via script when modifying modules |
| 29 | +- Docker tests require Linux or Colima/OrbStack (not Docker Desktop) |
| 30 | +- Use `tf` (not `hcl`) for code blocks in README; use relative icon paths (e.g., `../../../../.icons/`) |
163 | 31 |
|
164 | | -### Namespace Management |
| 32 | +## PR Review Checklist |
165 | 33 |
|
166 | | -- Each contributor gets unique namespace |
167 | | -- Namespace avatar required (avatar.png/svg in .images/) |
168 | | -- Namespace README with contributor info and frontmatter |
| 34 | +- Version bumped via `.github/scripts/version-bump.sh` if module changed (patch=bugfix, minor=feature, major=breaking) |
| 35 | +- Breaking changes documented: removed inputs, changed defaults, new required variables |
| 36 | +- New variables have sensible defaults to maintain backward compatibility |
| 37 | +- Tests pass (`bun run tftest`, `bun run tstest`); add diagnostic logging for test failures |
| 38 | +- README examples updated with new version number; tooltip/behavior changes noted |
| 39 | +- Shell scripts handle errors gracefully (use `|| echo "Warning..."` for non-fatal failures) |
| 40 | +- No hardcoded values that should be configurable; no absolute URLs (use relative paths) |
| 41 | +- If AI-assisted: include model and tool/agent name at footer of PR body (e.g., "Generated with [Amp](thread-url) using Claude") |
0 commit comments