From 7d19a724fe9be34a52c8a693f59c8028e0be2b9c Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Sat, 17 Jan 2026 15:34:52 +0500 Subject: [PATCH 1/3] chore: update AGENTS.md with commands and PR review checklist - Add separate tftest/tstest commands - Add single test execution commands - Document version-bump.sh script usage - Add URL validation note (must be relative) - Add tf vs hcl code block guidance - Add PR Review Checklist based on recent PR feedback --- AGENTS.md | 192 +++++++++--------------------------------------------- 1 file changed, 30 insertions(+), 162 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bc69ef4a8..0f89e60ad 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,168 +1,36 @@ # AGENTS.md -This file provides guidance to AI coding assistants when working with code in this repository. - -## Project Overview - -The Coder Registry is a community-driven repository for Terraform modules and templates that extend Coder workspaces. It's organized with: - -- **Modules**: Individual components and tools (IDEs, auth integrations, dev tools) -- **Templates**: Complete workspace configurations for different platforms -- **Namespaces**: Each contributor has their own namespace under `/registry/[namespace]/` - -## Common Development Commands - -### Formatting - -```bash -bun run fmt # Format all code (Prettier + Terraform) -bun run fmt:ci # Check formatting (CI mode) -``` - -### Testing - -```bash -# Test all modules with .tftest.hcl files -bun run test - -# Test specific module (from module directory) -terraform init -upgrade -terraform test -verbose - -# Validate Terraform syntax -./scripts/terraform_validate.sh -``` - -### Module Creation +Coder Registry: Terraform modules/templates for Coder workspaces under `registry/[namespace]/modules/` and `registry/[namespace]/templates/`. +## Commands ```bash -# Generate new module scaffold -./scripts/new_module.sh namespace/module-name -``` - -### TypeScript Testing & Setup - -The repository uses Bun for TypeScript testing with utilities: - -- `test/test.ts` - Testing utilities for container management and Terraform operations -- `setup.ts` - Test cleanup (removes .tfstate files and test containers) -- Container-based testing with Docker for module validation - -## Architecture & Organization - -### Directory Structure - -``` -registry/[namespace]/ -├── README.md # Contributor info with frontmatter -├── .images/ # Namespace avatar (avatar.png/svg) -├── modules/ # Individual components -│ └── [module]/ # Each module has main.tf, README.md, tests -└── templates/ # Complete workspace configs - └── [template]/ # Each template has main.tf, README.md -``` - -### Key Components - -**Module Structure**: Each module contains: - -- `main.tf` - Terraform implementation -- `README.md` - Documentation with YAML frontmatter -- `.tftest.hcl` - Terraform test files (required) -- `run.sh` - Optional startup script - -**Template Structure**: Each template contains: - -- `main.tf` - Complete Coder template configuration -- `README.md` - Documentation with YAML frontmatter -- Additional configs, scripts as needed - -### README Frontmatter Requirements - -All modules/templates require YAML frontmatter: - -```yaml ---- -display_name: "Module Name" -description: "Brief description" -icon: "../../../../.icons/tool.svg" -verified: false -tags: ["tag1", "tag2"] ---- +bun run fmt # Format code (Prettier + Terraform) - run before commits +bun run tftest # Run all Terraform tests +bun run tstest # Run all TypeScript tests +terraform init -upgrade && terraform test -verbose # Test single module (run from module dir) +bun test main.test.ts # Run single TS test (from module dir) +./scripts/terraform_validate.sh # Validate Terraform syntax +./scripts/new_module.sh ns/name # Create new module scaffold +.github/scripts/version-bump.sh patch|minor|major # Bump module version after changes ``` -## Testing Requirements - -### Module Testing - -- Every module MUST have `.tftest.hcl` test files -- Optional `main.test.ts` files for container-based testing or complex business logic validation -- Tests use Docker containers with `--network=host` flag -- Linux required for testing (Docker Desktop on macOS/Windows won't work) -- Use Colima or OrbStack on macOS instead of Docker Desktop - -### Test Utilities - -The `test/test.ts` file provides: - -- `runTerraformApply()` - Execute Terraform with variables -- `executeScriptInContainer()` - Run coder_script resources in containers -- `testRequiredVariables()` - Validate required variables -- Container management functions - -## Validation & Quality - -### Automated Validation - -The Go validation tool (`cmd/readmevalidation/`) checks: - -- Repository structure integrity -- Contributor README files -- Module and template documentation -- Frontmatter format compliance - -### Versioning - -Use semantic versioning for modules: - -- **Patch** (1.2.3 → 1.2.4): Bug fixes -- **Minor** (1.2.3 → 1.3.0): New features, adding inputs -- **Major** (1.2.3 → 2.0.0): Breaking changes - -## Dependencies & Tools - -### Required Tools - -- **Terraform** - Module development and testing -- **Docker** - Container-based testing -- **Bun** - JavaScript runtime for formatting/scripts -- **Go 1.23+** - Validation tooling - -### Development Dependencies - -- Prettier with Terraform and shell plugins -- TypeScript for test utilities -- Various npm packages for documentation processing - -## Workflow Notes - -### Contributing Process - -1. Create namespace (first-time contributors) -2. Generate module/template files using scripts -3. Implement functionality and tests -4. Run formatting and validation -5. Submit PR with appropriate template - -### Testing Workflow - -- All modules must pass `terraform test` -- Use `bun run test` for comprehensive testing -- Format code with `bun run fmt` before submission -- Manual testing recommended for templates - -### Namespace Management - -- Each contributor gets unique namespace -- Namespace avatar required (avatar.png/svg in .images/) -- Namespace README with contributor info and frontmatter +## Structure +- **Modules**: `registry/[ns]/modules/[name]/` with `main.tf`, `README.md` (YAML frontmatter), `.tftest.hcl` (required) +- **Templates**: `registry/[ns]/templates/[name]/` with `main.tf`, `README.md` +- **Validation**: `cmd/readmevalidation/` (Go) validates structure/frontmatter; URLs must be relative, not absolute + +## Code Style +- Every module MUST have `.tftest.hcl` tests; optional `main.test.ts` for container/script tests +- README frontmatter: `display_name`, `description`, `icon`, `verified: false`, `tags` +- Use semantic versioning; bump version via script when modifying modules +- Docker tests require Linux or Colima/OrbStack (not Docker Desktop) +- Use `tf` (not `hcl`) for code blocks in README; use relative icon paths (e.g., `../../../../.icons/`) + +## PR Review Checklist +- Version bumped via `.github/scripts/version-bump.sh` if module changed (patch=bugfix, minor=feature, major=breaking) +- Breaking changes documented: removed inputs, changed defaults, new required variables +- New variables have sensible defaults to maintain backward compatibility +- Tests pass (`bun run tftest`, `bun run tstest`); add diagnostic logging for test failures +- README examples updated with new version number; tooltip/behavior changes noted +- Shell scripts handle errors gracefully (use `|| echo "Warning..."` for non-fatal failures) +- No hardcoded values that should be configurable; no absolute URLs (use relative paths) From 013a6fdad344aa4f36b826cac52928010a139a96 Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Sat, 17 Jan 2026 15:36:47 +0500 Subject: [PATCH 2/3] chore: add AI attribution requirement to PR checklist --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 0f89e60ad..8434a51d3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,3 +34,4 @@ bun test main.test.ts # Run single TS test (from module dir) - README examples updated with new version number; tooltip/behavior changes noted - Shell scripts handle errors gracefully (use `|| echo "Warning..."` for non-fatal failures) - No hardcoded values that should be configurable; no absolute URLs (use relative paths) +- If AI-assisted: include model and tool/agent name at footer of PR body (e.g., "Generated with [Amp](thread-url) using Claude") From c8b03a4313495616c075f00bb29bb6b8a4eedf7c Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Sat, 17 Jan 2026 15:42:22 +0500 Subject: [PATCH 3/3] chore: format AGENTS.md --- AGENTS.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8434a51d3..42ac3ed24 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,23 +3,26 @@ Coder Registry: Terraform modules/templates for Coder workspaces under `registry/[namespace]/modules/` and `registry/[namespace]/templates/`. ## Commands + ```bash -bun run fmt # Format code (Prettier + Terraform) - run before commits -bun run tftest # Run all Terraform tests -bun run tstest # Run all TypeScript tests -terraform init -upgrade && terraform test -verbose # Test single module (run from module dir) -bun test main.test.ts # Run single TS test (from module dir) -./scripts/terraform_validate.sh # Validate Terraform syntax -./scripts/new_module.sh ns/name # Create new module scaffold -.github/scripts/version-bump.sh patch|minor|major # Bump module version after changes +bun run fmt # Format code (Prettier + Terraform) - run before commits +bun run tftest # Run all Terraform tests +bun run tstest # Run all TypeScript tests +terraform init -upgrade && terraform test -verbose # Test single module (run from module dir) +bun test main.test.ts # Run single TS test (from module dir) +./scripts/terraform_validate.sh # Validate Terraform syntax +./scripts/new_module.sh ns/name # Create new module scaffold +.github/scripts/version-bump.sh patch | minor | major # Bump module version after changes ``` ## Structure + - **Modules**: `registry/[ns]/modules/[name]/` with `main.tf`, `README.md` (YAML frontmatter), `.tftest.hcl` (required) - **Templates**: `registry/[ns]/templates/[name]/` with `main.tf`, `README.md` - **Validation**: `cmd/readmevalidation/` (Go) validates structure/frontmatter; URLs must be relative, not absolute ## Code Style + - Every module MUST have `.tftest.hcl` tests; optional `main.test.ts` for container/script tests - README frontmatter: `display_name`, `description`, `icon`, `verified: false`, `tags` - Use semantic versioning; bump version via script when modifying modules @@ -27,6 +30,7 @@ bun test main.test.ts # Run single TS test (from module dir) - Use `tf` (not `hcl`) for code blocks in README; use relative icon paths (e.g., `../../../../.icons/`) ## PR Review Checklist + - Version bumped via `.github/scripts/version-bump.sh` if module changed (patch=bugfix, minor=feature, major=breaking) - Breaking changes documented: removed inputs, changed defaults, new required variables - New variables have sensible defaults to maintain backward compatibility