From d98cc967464707cf2f3ee17d00d1b916ba983050 Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Tue, 26 Aug 2025 23:05:25 +0500 Subject: [PATCH 1/4] feat: add AGENTS.md with AI coding assistant guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create comprehensive AGENTS.md with project structure and development commands - Add symlinks for CLAUDE.md and .github/copilot-instructions.md - Include testing requirements, architecture details, and workflow notes - Enable consistent AI assistance across Claude Code and GitHub Copilot 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .github/copilot-instructions.md | 1 + AGENTS.md | 144 ++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 3 files changed, 146 insertions(+) create mode 120000 .github/copilot-instructions.md create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 120000 index 000000000..be77ac83a --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1 @@ +../AGENTS.md \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..09cd209d3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,144 @@ +# 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 +./scripts/terraform_test_all.sh + +# Test specific module (from module directory) +terraform init -upgrade +terraform test -verbose + +# Validate Terraform syntax +./scripts/terraform_validate.sh +``` + +### Module Creation +```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"] +--- +``` + +## Testing Requirements + +### Module Testing +- Every module MUST have `.tftest.hcl` test files +- 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 `./scripts/terraform_test_all.sh` 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 \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 000000000..47dc3e3d8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From 1912809ec164e04553fbbf0e3cf68da9b73b1f5f Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Wed, 27 Aug 2025 02:03:50 +0500 Subject: [PATCH 2/4] fmt --- AGENTS.md | 33 ++++++++++++++++++++++++++++----- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 09cd209d3..3449fef63 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,7 @@ This file provides guidance to AI coding assistants when working with code in th ## 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]/` @@ -12,12 +13,14 @@ The Coder Registry is a community-driven repository for Terraform modules and te ## Common Development Commands ### Formatting + ```bash -bun run fmt # Format all code (Prettier + Terraform) -bun run fmt:ci # Check formatting (CI mode) +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 ./scripts/terraform_test_all.sh @@ -31,13 +34,16 @@ terraform test -verbose ``` ### Module Creation + ```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 @@ -45,6 +51,7 @@ The repository uses Bun for TypeScript testing with utilities: ## Architecture & Organization ### Directory Structure + ``` registry/[namespace]/ ├── README.md # Contributor info with frontmatter @@ -58,18 +65,22 @@ registry/[namespace]/ ### 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" @@ -83,13 +94,16 @@ tags: ["tag1", "tag2"] ## Testing Requirements ### Module Testing + - Every module MUST have `.tftest.hcl` test files - 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 @@ -98,27 +112,33 @@ The `test/test.ts` file provides: ## Validation & Quality ### Automated Validation + The Go validation tool (`cmd/readmevalidation/`) checks: -- Repository structure integrity + +- 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 +- **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 @@ -126,6 +146,7 @@ Use semantic versioning for modules: ## Workflow Notes ### Contributing Process + 1. Create namespace (first-time contributors) 2. Generate module/template files using scripts 3. Implement functionality and tests @@ -133,12 +154,14 @@ Use semantic versioning for modules: 5. Submit PR with appropriate template ### Testing Workflow + - All modules must pass `terraform test` - Use `./scripts/terraform_test_all.sh` 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 \ No newline at end of file +- Namespace README with contributor info and frontmatter From bd89ca2bc72bc6affd0ee33c1afbee10c2ea2911 Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Wed, 27 Aug 2025 18:58:23 +0000 Subject: [PATCH 3/4] docs: update testing commands and add ts test guidance --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3449fef63..bc69ef4a8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ bun run fmt:ci # Check formatting (CI mode) ```bash # Test all modules with .tftest.hcl files -./scripts/terraform_test_all.sh +bun run test # Test specific module (from module directory) terraform init -upgrade @@ -96,6 +96,7 @@ tags: ["tag1", "tag2"] ### 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 @@ -156,7 +157,7 @@ Use semantic versioning for modules: ### Testing Workflow - All modules must pass `terraform test` -- Use `./scripts/terraform_test_all.sh` for comprehensive testing +- Use `bun run test` for comprehensive testing - Format code with `bun run fmt` before submission - Manual testing recommended for templates From cea1209c736749fdb69684e914682a1b6242d5b7 Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Wed, 27 Aug 2025 19:31:19 +0000 Subject: [PATCH 4/4] chore: bun run fmt --- registry/coder/modules/kiro/main.test.ts | 15 ++++++++++++--- registry/coder/modules/windsurf/main.test.ts | 15 ++++++++++++--- 2 files changed, 24 insertions(+), 6 deletions(-) diff --git a/registry/coder/modules/kiro/main.test.ts b/registry/coder/modules/kiro/main.test.ts index 8d8bee636..2d268a844 100644 --- a/registry/coder/modules/kiro/main.test.ts +++ b/registry/coder/modules/kiro/main.test.ts @@ -99,19 +99,28 @@ describe("kiro", async () => { it("writes ~/.kiro/settings/mcp.json when mcp provided", async () => { const id = await runContainer("alpine"); try { - const mcp = JSON.stringify({ servers: { demo: { url: "http://localhost:1234" } } }); + const mcp = JSON.stringify({ + servers: { demo: { url: "http://localhost:1234" } }, + }); const state = await runTerraformApply(import.meta.dir, { agent_id: "foo", mcp, }); - const script = findResourceInstance(state, "coder_script", "kiro_mcp").script; + const script = findResourceInstance( + state, + "coder_script", + "kiro_mcp", + ).script; const resp = await execContainer(id, ["sh", "-c", script]); if (resp.exitCode !== 0) { console.log(resp.stdout); console.log(resp.stderr); } expect(resp.exitCode).toBe(0); - const content = await readFileContainer(id, "/root/.kiro/settings/mcp.json"); + const content = await readFileContainer( + id, + "/root/.kiro/settings/mcp.json", + ); expect(content).toBe(mcp); } finally { await removeContainer(id); diff --git a/registry/coder/modules/windsurf/main.test.ts b/registry/coder/modules/windsurf/main.test.ts index 88e67f3cf..f5aa5e1f9 100644 --- a/registry/coder/modules/windsurf/main.test.ts +++ b/registry/coder/modules/windsurf/main.test.ts @@ -94,19 +94,28 @@ describe("windsurf", async () => { it("writes ~/.codeium/windsurf/mcp_config.json when mcp provided", async () => { const id = await runContainer("alpine"); try { - const mcp = JSON.stringify({ servers: { demo: { url: "http://localhost:1234" } } }); + const mcp = JSON.stringify({ + servers: { demo: { url: "http://localhost:1234" } }, + }); const state = await runTerraformApply(import.meta.dir, { agent_id: "foo", mcp, }); - const script = findResourceInstance(state, "coder_script", "windsurf_mcp").script; + const script = findResourceInstance( + state, + "coder_script", + "windsurf_mcp", + ).script; const resp = await execContainer(id, ["sh", "-c", script]); if (resp.exitCode !== 0) { console.log(resp.stdout); console.log(resp.stderr); } expect(resp.exitCode).toBe(0); - const content = await readFileContainer(id, "/root/.codeium/windsurf/mcp_config.json"); + const content = await readFileContainer( + id, + "/root/.codeium/windsurf/mcp_config.json", + ); expect(content).toBe(mcp); } finally { await removeContainer(id);