@@ -5,19 +5,22 @@ This file provides guidance to AI coding assistants when working with code in th
55## Project Overview
66
77The Coder Registry is a community-driven repository for Terraform modules and templates that extend Coder workspaces. It's organized with:
8+
89- ** Modules** : Individual components and tools (IDEs, auth integrations, dev tools)
910- ** Templates** : Complete workspace configurations for different platforms
1011- ** Namespaces** : Each contributor has their own namespace under ` /registry/[namespace]/ `
1112
1213## Common Development Commands
1314
1415### Formatting
16+
1517``` bash
16- bun run fmt # Format all code (Prettier + Terraform)
17- bun run fmt:ci # Check formatting (CI mode)
18+ bun run fmt # Format all code (Prettier + Terraform)
19+ bun run fmt:ci # Check formatting (CI mode)
1820```
1921
2022### Testing
23+
2124``` bash
2225# Test all modules with .tftest.hcl files
2326./scripts/terraform_test_all.sh
@@ -31,20 +34,24 @@ terraform test -verbose
3134```
3235
3336### Module Creation
37+
3438``` bash
3539# Generate new module scaffold
3640./scripts/new_module.sh namespace/module-name
3741```
3842
3943### TypeScript Testing & Setup
44+
4045The repository uses Bun for TypeScript testing with utilities:
46+
4147- ` test/test.ts ` - Testing utilities for container management and Terraform operations
4248- ` setup.ts ` - Test cleanup (removes .tfstate files and test containers)
4349- Container-based testing with Docker for module validation
4450
4551## Architecture & Organization
4652
4753### Directory Structure
54+
4855```
4956registry/[namespace]/
5057├── README.md # Contributor info with frontmatter
@@ -58,18 +65,22 @@ registry/[namespace]/
5865### Key Components
5966
6067** Module Structure** : Each module contains:
68+
6169- ` main.tf ` - Terraform implementation
6270- ` README.md ` - Documentation with YAML frontmatter
6371- ` .tftest.hcl ` - Terraform test files (required)
6472- ` run.sh ` - Optional startup script
6573
6674** Template Structure** : Each template contains:
75+
6776- ` main.tf ` - Complete Coder template configuration
6877- ` README.md ` - Documentation with YAML frontmatter
6978- Additional configs, scripts as needed
7079
7180### README Frontmatter Requirements
81+
7282All modules/templates require YAML frontmatter:
83+
7384``` yaml
7485---
7586display_name : " Module Name"
@@ -83,13 +94,16 @@ tags: ["tag1", "tag2"]
8394## Testing Requirements
8495
8596### Module Testing
97+
8698- Every module MUST have ` .tftest.hcl ` test files
8799- Tests use Docker containers with ` --network=host ` flag
88100- Linux required for testing (Docker Desktop on macOS/Windows won't work)
89101- Use Colima or OrbStack on macOS instead of Docker Desktop
90102
91103### Test Utilities
104+
92105The ` test/test.ts ` file provides:
106+
93107- ` runTerraformApply() ` - Execute Terraform with variables
94108- ` executeScriptInContainer() ` - Run coder_script resources in containers
95109- ` testRequiredVariables() ` - Validate required variables
@@ -98,47 +112,56 @@ The `test/test.ts` file provides:
98112## Validation & Quality
99113
100114### Automated Validation
115+
101116The Go validation tool (` cmd/readmevalidation/ ` ) checks:
102- - Repository structure integrity
117+
118+ - Repository structure integrity
103119- Contributor README files
104120- Module and template documentation
105121- Frontmatter format compliance
106122
107123### Versioning
124+
108125Use semantic versioning for modules:
126+
109127- ** Patch** (1.2.3 → 1.2.4): Bug fixes
110- - ** Minor** (1.2.3 → 1.3.0): New features, adding inputs
128+ - ** Minor** (1.2.3 → 1.3.0): New features, adding inputs
111129- ** Major** (1.2.3 → 2.0.0): Breaking changes
112130
113131## Dependencies & Tools
114132
115133### Required Tools
134+
116135- ** Terraform** - Module development and testing
117136- ** Docker** - Container-based testing
118137- ** Bun** - JavaScript runtime for formatting/scripts
119138- ** Go 1.23+** - Validation tooling
120139
121140### Development Dependencies
141+
122142- Prettier with Terraform and shell plugins
123143- TypeScript for test utilities
124144- Various npm packages for documentation processing
125145
126146## Workflow Notes
127147
128148### Contributing Process
149+
1291501 . Create namespace (first-time contributors)
1301512 . Generate module/template files using scripts
1311523 . Implement functionality and tests
1321534 . Run formatting and validation
1331545 . Submit PR with appropriate template
134155
135156### Testing Workflow
157+
136158- All modules must pass ` terraform test `
137159- Use ` ./scripts/terraform_test_all.sh ` for comprehensive testing
138160- Format code with ` bun run fmt ` before submission
139161- Manual testing recommended for templates
140162
141163### Namespace Management
164+
142165- Each contributor gets unique namespace
143166- Namespace avatar required (avatar.png/svg in .images/)
144- - Namespace README with contributor info and frontmatter
167+ - Namespace README with contributor info and frontmatter
0 commit comments