Merge branch 'main' into aider-tasks-agentapi-support

Author: Harsh9485

.github/copilot-instructions.md

@@ -0,0 +1 @@
+../AGENTS.md

.icons/electric-plug-emoji.svg

@@ -0,0 +1,168 @@
+# 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
+
+```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
+- 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

AGENTS.md

@@ -0,0 +1 @@
+AGENTS.md

CLAUDE.md

@@ -0,0 +1,16 @@
+---
+display_name: Externally Managed Workspace
+description: A template to provision externally managed resources as Coder workspaces
+icon: ../../../../.icons/electric-plug-emoji.svg
+verified: true
+tags: [external]
+---
+
+# Externally Managed Workspace Template
+
+> [!IMPORTANT]
+> External agents require a [Premium](https://coder.com/pricing) Coder license.
+
+This template provides a minimal scaffolding for creating Coder workspaces that connect to externally provisioned compute resources.
+
+Use this template as a starting point to build your own custom templates for scenarios where you need to connect to existing infrastructure.

registry/coder-labs/templates/externally-managed-workspace/README.md

@@ -0,0 +1,74 @@
+terraform {
+  required_providers {
+    coder = {
+      source  = "coder/coder"
+      version = ">= 2.10"
+    }
+  }
+}
+
+data "coder_parameter" "agent_config" {
+  name         = "agent_config"
+  display_name = "Agent Configuration"
+  description  = "Select the operating system and architecture combination for the agent"
+  type         = "string"
+  default      = "linux-amd64"
+
+  option {
+    name  = "Linux AMD64"
+    value = "linux-amd64"
+  }
+  option {
+    name  = "Linux ARM64"
+    value = "linux-arm64"
+  }
+  option {
+    name  = "Linux ARMv7"
+    value = "linux-armv7"
+  }
+  option {
+    name  = "Windows AMD64"
+    value = "windows-amd64"
+  }
+  option {
+    name  = "Windows ARM64"
+    value = "windows-arm64"
+  }
+  option {
+    name  = "macOS AMD64"
+    value = "darwin-amd64"
+  }
+  option {
+    name  = "macOS ARM64 (Apple Silicon)"
+    value = "darwin-arm64"
+  }
+}
+
+data "coder_workspace" "me" {}
+
+locals {
+  agent_config = split("-", data.coder_parameter.agent_config.value)
+  agent_os     = local.agent_config[0]
+  agent_arch   = local.agent_config[1]
+}
+
+resource "coder_agent" "main" {
+  arch = local.agent_arch
+  os   = local.agent_os
+}
+
+resource "coder_external_agent" "main" {
+  agent_id = coder_agent.main.id
+}
+
+# Adds code-server
+# See all available modules at https://registry.coder.com/modules
+module "code-server" {
+  count  = data.coder_workspace.me.start_count
+  source = "registry.coder.com/coder/code-server/coder"
+
+  # This ensures that the latest non-breaking version of the module gets downloaded, you can also pin the module version to prevent breaking changes in production.
+  version = "~> 1.0"
+
+  agent_id = coder_agent.main.id
+}

registry/coder-labs/templates/externally-managed-workspace/main.tf

@@ -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);

registry/coder/modules/kiro/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);