registry/AGENTS.md

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

bun run fmt    # Format all code (Prettier + Terraform)
bun run fmt:ci # Check formatting (CI mode)

Testing

# 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

# 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:

---
display_name: "Module Name"
description: "Brief description"
icon: "../../../../.icons/tool.svg"
verified: false
tags: ["tag1", "tag2"]
---

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