feat(coder-utils): nest scripts under module_directory/scripts (#871)

## Summary

Move script files from the flat `${module_directory}` to a `scripts/`
subdirectory, and prefix each script's filename with
`${agent_name}-utils-` so multiple `coder-utils` instances can safely
share a `module_directory`. Mirrors the layout #870 established for
`logs/` and aligns with the Module Data Layout standard in `AGENTS.md`
(#869).

## Changes

- Compute `local.scripts_directory = "${var.module_directory}/scripts"`
and use it for every `*.sh` path.
- Script filenames are now
`${agent_name}-utils-{pre_install,install,post_install,start}.sh` so two
`coder-utils` instances don't collide on disk.
- Pre-install and install `coder_script`s `mkdir -p` the `scripts/`
sub-path before writing their `.sh`; post-install and start sync-depend
on install, so the directory already exists by the time they run.
- Update the `module_directory` description to call out the nested
`scripts/` and `logs/` paths.
- Add `test_scripts_nested_under_module_directory` asserting the new
paths (including the `${agent_name}-utils-` prefix) and the `mkdir -p`
in each script.
- README: add a "Script file locations" section documenting the new
layout.
- Bump module version to `v1.3.0`.

## Breaking Changes

Consumers reading `${module_directory}/install.sh` (and friends)
directly must look under
`${module_directory}/scripts/${agent_name}-utils-install.sh` instead. No
in-repo consumers exist today.

## Validation

- `terraform fmt -recursive` clean
- `terraform validate` clean
- `terraform test` → 16/16 pass (includes the new
`test_scripts_nested_under_module_directory`)
- `bun test main.test.ts` → 5/5 pass
- `prettier --check` clean

> 🤖 This PR was created with the help of Coder Agents, and needs a human
review. 🧑‍💻

registry/coder/modules/coder-utils/README.md

@@ -20,7 +20,7 @@ The Coder Utils module is a building block for modules that need to run multiple
 ```tf
 module "coder_utils" {
   source  = "registry.coder.com/coder/coder-utils/coder"
-  version = "1.2.0"
+  version = "1.3.0"
 
   agent_id         = coder_agent.main.id
   agent_name       = "myagent"
@@ -70,7 +70,7 @@ By default each `coder_script` renders in the Coder UI as plain "Install Script"
 ```tf
 module "coder_utils" {
   source  = "registry.coder.com/coder/coder-utils/coder"
-  version = "1.2.0"
+  version = "1.3.0"
 
   agent_id         = coder_agent.main.id
   agent_name       = "myagent"
@@ -94,3 +94,14 @@ The module writes each script's stdout+stderr to `${module_directory}/logs/`:
 - `start.log`
 
 Each `coder_script` `mkdir -p`s this subdirectory before its `tee` runs, so the first script to execute creates it.
+
+## Script file locations
+
+The module materializes each script to `${module_directory}/scripts/` before running it:
+
+- `${agent_name}-utils-pre_install.sh`
+- `${agent_name}-utils-install.sh`
+- `${agent_name}-utils-post_install.sh`
+- `${agent_name}-utils-start.sh`
+
+The `${agent_name}-utils-` prefix namespaces files per-agent so multiple `coder-utils` instances can safely share a `module_directory`. The pre-install and install `coder_script`s `mkdir -p` this subdirectory; post-install and start sync-depend on install, so the directory already exists by the time they run.

registry/coder/modules/coder-utils/main.tf

@@ -51,7 +51,7 @@ variable "agent_name" {
 
 variable "module_directory" {
   type        = string
-  description = "The module's working directory for the install/pre/post/start scripts this module writes. Logs land under a `logs/` subdirectory of this path."
+  description = "The module's working directory. Scripts this module writes land under `scripts/` and their logs under `logs/` in this path."
 }
 
 variable "display_name_prefix" {
@@ -77,17 +77,18 @@ locals {
   post_install_script_name = "${var.agent_name}-post_install_script"
   start_script_name        = "${var.agent_name}-start_script"
 
-  pre_install_path  = "${var.module_directory}/pre_install.sh"
-  install_path      = "${var.module_directory}/install.sh"
-  post_install_path = "${var.module_directory}/post_install.sh"
-  start_path        = "${var.module_directory}/start.sh"
+  pre_install_path  = "${local.scripts_directory}/${var.agent_name}-utils-pre_install.sh"
+  install_path      = "${local.scripts_directory}/${var.agent_name}-utils-install.sh"
+  post_install_path = "${local.scripts_directory}/${var.agent_name}-utils-post_install.sh"
+  start_path        = "${local.scripts_directory}/${var.agent_name}-utils-start.sh"
 
   pre_install_log_path  = "${local.log_directory}/pre_install.log"
   install_log_path      = "${local.log_directory}/install.log"
   post_install_log_path = "${local.log_directory}/post_install.log"
   start_log_path        = "${local.log_directory}/start.log"
 
-  log_directory = "${var.module_directory}/logs"
+  scripts_directory = "${var.module_directory}/scripts"
+  log_directory     = "${var.module_directory}/logs"
 
   install_sync_deps = var.pre_install_script != null ? local.pre_install_script_name : null
 
@@ -112,6 +113,7 @@ resource "coder_script" "pre_install_script" {
     set -o pipefail
 
     mkdir -p ${var.module_directory}
+    mkdir -p ${local.scripts_directory}
     mkdir -p ${local.log_directory}
 
     trap 'coder exp sync complete ${local.pre_install_script_name}' EXIT
@@ -135,6 +137,7 @@ resource "coder_script" "install_script" {
     set -o pipefail
 
     mkdir -p ${var.module_directory}
+    mkdir -p ${local.scripts_directory}
     mkdir -p ${local.log_directory}
 
     trap 'coder exp sync complete ${local.install_script_name}' EXIT

registry/coder/modules/coder-utils/main.tftest.hcl

@@ -578,3 +578,53 @@ run "test_logs_nested_under_module_directory" {
     error_message = "install script must mkdir -p the logs/ sub-path"
   }
 }
+
+# Scripts unconditionally land under ${module_directory}/scripts/. Each
+# script that materializes its own `.sh` file mkdirs that path first; the
+# first script to execute creates it for the rest.
+run "test_scripts_nested_under_module_directory" {
+  command = plan
+
+  variables {
+    agent_id            = "test-agent-id"
+    agent_name          = "test-agent"
+    module_directory    = ".test-module"
+    pre_install_script  = "echo pre"
+    install_script      = "echo install"
+    post_install_script = "echo post"
+    start_script        = "echo start"
+  }
+
+  assert {
+    condition     = can(regex("> .test-module/scripts/test-agent-utils-pre_install.sh", coder_script.pre_install_script[0].script))
+    error_message = "pre_install script must be written under module_directory/scripts"
+  }
+
+  assert {
+    condition     = can(regex("> .test-module/scripts/test-agent-utils-install.sh", coder_script.install_script.script))
+    error_message = "install script must be written under module_directory/scripts"
+  }
+
+  assert {
+    condition     = can(regex("> .test-module/scripts/test-agent-utils-post_install.sh", coder_script.post_install_script[0].script))
+    error_message = "post_install script must be written under module_directory/scripts"
+  }
+
+  assert {
+    condition     = can(regex("> .test-module/scripts/test-agent-utils-start.sh", coder_script.start_script[0].script))
+    error_message = "start script must be written under module_directory/scripts"
+  }
+
+  # Only pre_install and install mkdir the scripts/ sub-path. post_install
+  # and start sync-depend on install so the directory already exists by
+  # the time they run.
+  assert {
+    condition     = can(regex("mkdir -p .test-module/scripts", coder_script.pre_install_script[0].script))
+    error_message = "pre_install script must mkdir -p the scripts/ sub-path"
+  }
+
+  assert {
+    condition     = can(regex("mkdir -p .test-module/scripts", coder_script.install_script.script))
+    error_message = "install script must mkdir -p the scripts/ sub-path"
+  }
+}