refactor(registry/coder/modules/coder-utils): return scripts as a keyed map

Keying by phase lets callers write `module.coder_utils.scripts.install`
instead of indexing a list whose length depends on which optional
scripts were configured. Unconfigured phases are `null`. Callers that
want every configured name can use `compact(values(scripts))`.

README documents both patterns.

Author: matifali

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

@@ -99,3 +99,24 @@ The module materializes each script to `${module_directory}/scripts/` before run
 - `start.sh`
 
 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.
+
+## Chaining downstream scripts
+
+The `scripts` output exposes the `coder exp sync` name for each phase keyed by phase, with `null` for phases that were not configured. Downstream modules can sync their own `coder_script` resources behind this pipeline:
+
+```tf
+resource "coder_script" "my_followup" {
+  agent_id = coder_agent.main.id
+  script   = <<-EOT
+    coder exp sync want my-followup ${module.coder_utils.scripts.install}
+    coder exp sync start my-followup
+    # ... work that depends on install completing ...
+  EOT
+}
+```
+
+To wait on every script this module created (regardless of which phases are configured), use `compact(values(...))`:
+
+```tf
+coder exp sync want my-followup ${join(" ", compact(values(module.coder_utils.scripts)))}
+```

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

@@ -199,18 +199,16 @@ resource "coder_script" "start_script" {
   EOT
 }
 
-# Filtered, run-order list of the `coder exp sync` names for every
-# coder_script this module actually creates. Absent scripts (pre/post/start
-# when their inputs are null) are omitted entirely, not padded with empty
-# strings. Downstream modules can use this with
-# `coder exp sync want <self> <each of these>` to serialize their own
-# scripts behind the install pipeline.
+# `coder exp sync` names keyed by phase, for downstream modules that want to
+# serialize their own `coder_script` resources behind this module's pipeline
+# with `coder exp sync want <self> <scripts.install>` or
+# `coder exp sync want <self> <values(compact(scripts))...>`.
 output "scripts" {
-  description = "Ordered list of `coder exp sync` names for the coder_script resources this module creates, in the run order it enforces (pre_install, install, post_install, start). Scripts that were not configured are absent from the list."
-  value = concat(
-    var.pre_install_script != null ? [local.pre_install_script_name] : [],
-    [local.install_script_name],
-    var.post_install_script != null ? [local.post_install_script_name] : [],
-    var.start_script != null ? [local.start_script_name] : [],
-  )
+  description = "`coder exp sync` names for each phase this module can create. Unconfigured phases are null; `install` is always set."
+  value = {
+    pre_install  = var.pre_install_script != null ? local.pre_install_script_name : null
+    install      = local.install_script_name
+    post_install = var.post_install_script != null ? local.post_install_script_name : null
+    start        = var.start_script != null ? local.start_script_name : null
+  }
 }

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

@@ -408,7 +408,7 @@ run "test_optional_scripts_absent_by_default" {
   }
 }
 
-# Verify `scripts` output is a filtered, run-order list
+# Verify `scripts` output is a keyed map of phase names
 run "test_scripts_output_with_all" {
   command = plan
 
@@ -422,28 +422,23 @@ run "test_scripts_output_with_all" {
   }
 
   assert {
-    condition     = length(output.scripts) == 4
-    error_message = "scripts should have 4 entries when every script is set"
+    condition     = output.scripts.pre_install == "test-example-pre_install_script"
+    error_message = "scripts.pre_install must be the pre-install name"
   }
 
   assert {
-    condition     = output.scripts[0] == "test-example-pre_install_script"
-    error_message = "scripts[0] must be the pre-install name"
+    condition     = output.scripts.install == "test-example-install_script"
+    error_message = "scripts.install must be the install name"
   }
 
   assert {
-    condition     = output.scripts[1] == "test-example-install_script"
-    error_message = "scripts[1] must be the install name"
+    condition     = output.scripts.post_install == "test-example-post_install_script"
+    error_message = "scripts.post_install must be the post-install name"
   }
 
   assert {
-    condition     = output.scripts[2] == "test-example-post_install_script"
-    error_message = "scripts[2] must be the post-install name"
-  }
-
-  assert {
-    condition     = output.scripts[3] == "test-example-start_script"
-    error_message = "scripts[3] must be the start name"
+    condition     = output.scripts.start == "test-example-start_script"
+    error_message = "scripts.start must be the start name"
   }
 }
 
@@ -457,13 +452,13 @@ run "test_scripts_output_with_install_only" {
   }
 
   assert {
-    condition     = length(output.scripts) == 1
-    error_message = "scripts should have exactly 1 entry (install) when pre/post/start are unset"
+    condition     = output.scripts.install == "test-example-install_script"
+    error_message = "scripts.install must be the install name"
   }
 
   assert {
-    condition     = output.scripts[0] == "test-example-install_script"
-    error_message = "scripts[0] must be the install name"
+    condition     = output.scripts.pre_install == null && output.scripts.post_install == null && output.scripts.start == null
+    error_message = "unconfigured phases must be null"
   }
 }
 
@@ -478,18 +473,18 @@ run "test_scripts_output_with_install_and_post" {
   }
 
   assert {
-    condition     = length(output.scripts) == 2
-    error_message = "scripts should have 2 entries (install, post)"
+    condition     = output.scripts.install == "test-example-install_script"
+    error_message = "scripts.install must be the install name"
   }
 
   assert {
-    condition     = output.scripts[0] == "test-example-install_script"
-    error_message = "scripts[0] must be the install name"
+    condition     = output.scripts.post_install == "test-example-post_install_script"
+    error_message = "scripts.post_install must be the post-install name"
   }
 
   assert {
-    condition     = output.scripts[1] == "test-example-post_install_script"
-    error_message = "scripts[1] must be the post-install name"
+    condition     = output.scripts.pre_install == null && output.scripts.start == null
+    error_message = "unconfigured phases must be null"
   }
 }