Standardizes environment configuration handling for Docker deployment scripts.

BUILD_PR_LEVEL_09_27_DEPLOY_ENV_CONFIG_STANDARDIZATION

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,10 +2,10 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-- add dry-run mode to scripts/PS/deploy/
-- validate inputs and environment
-- prevent destructive execution without explicit confirmation
-- improve output messaging
+- standardize env config handling for scripts/PS/deploy/
+- support .env loading
+- normalize variable names
+- ensure consistent config usage
 - commit format:
   description first line
   PR name last line

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,2 @@
-Add deploy dry-run/environment validation guards and require explicit destructive confirmation for apply cleanup/refresh paths.
-BUILD_PR_LEVEL_09_26_DEPLOY_VALIDATION_AND_DRYRUN
+Standardize deploy env config via shared .env loading, normalized DEPLOY_* variables, and consistent script-level config resolution.
+BUILD_PR_LEVEL_09_27_DEPLOY_ENV_CONFIG_STANDARDIZATION

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-BUILD_PR_LEVEL_09_27_DEPLOY_ENV_CONFIG_STANDARDIZATION
+BUILD_PR_LEVEL_09_28_DEPLOY_EXECUTION_WRAPPER

docs/dev/reports/change_summary.txt

@@ -1,18 +1,22 @@
-BUILD_PR_LEVEL_09_26_DEPLOY_VALIDATION_AND_DRYRUN
+BUILD_PR_LEVEL_09_27_DEPLOY_ENV_CONFIG_STANDARDIZATION
 
 Scope:
-- Refined deployment safety/validation behavior only under `scripts/PS/deploy/`.
-- No runtime, engine, tool UI, or non-deploy scope changes.
+- Standardized deploy-script environment configuration only under `scripts/PS/deploy/`.
+- No runtime, engine, tool UI, or non-deploy behavior expansion.
 
 Implemented:
-- Kept/standardized dry-run behavior across deploy scripts with clearer next-step messaging.
-- Added environment readiness validation (`repo root`, `tmp root`, staging-root containment) before execution.
-- Added include-path contract validation (repo-relative only, no traversal/wildcards/rooted paths).
-- Added explicit destructive confirmation guard via `-ConfirmDestructive` for:
-  - `Update-WebsiteRepoDeployment.ps1` apply path (site-root refresh/delete)
-  - `Clean-WebsiteRepoDeployment.ps1` apply path (artifact deletion)
-- Preserved non-destructive defaults and existing staging-root safety checks.
+- Added shared `.env` loading in `WebsiteRepoDeploymentCommon.ps1` with repo-root default and optional `-EnvFilePath` override.
+- Added normalized deploy env variables:
+  - `DEPLOY_STAGING_ROOT`
+  - `DEPLOY_INCLUDE_PATHS`
+  - `DEPLOY_REMOVE_METADATA`
+  - `DEPLOY_WEB_PORT`
+- Added backward-compat alias handling (`STAGING_ROOT`, `INCLUDE_PATHS`, `REMOVE_METADATA`, `PORT`) with warning logs.
+- Centralized script config resolution via `Resolve-DeployScriptConfig` so prep/update/clean all load config the same way.
+- Added config-load telemetry (`Write-DeployConfigLoadLog`) for consistent operator visibility.
+- Updated docker compose artifact generation to use normalized variable token `${DEPLOY_WEB_PORT:-<default>}`.
+- Added optional `-EnvFilePath` on prep/update/clean and optional `-WebPort` override on prep/update.
 
-Tracking:
-- Commit comment format enforced (description first line, PR name last line, no leading blank line).
-- Roadmap updated with status-only change.
+Result:
+- Deploy scripts now use one consistent config contract with deterministic precedence:
+  explicit params > `.env` values > built-in defaults.

docs/dev/reports/validation_checklist.txt

@@ -1,9 +1,8 @@
 [x] PowerShell parse/readiness checks pass on touched deploy scripts
-[x] Dry-run smoke checks pass for prep/update/clean deploy scripts
-[x] Environment readiness validation executes before deploy operations
-[x] Invalid include path traversal input is rejected
-[x] Update apply is blocked without explicit -ConfirmDestructive
-[x] Clean apply is blocked without explicit -ConfirmDestructive
-[x] Update/Clean apply succeed when -ConfirmDestructive is provided
+[x] .env loading works through shared config resolver for prep/update/clean
+[x] Normalized DEPLOY_* variables resolve consistently across deploy scripts
+[x] Legacy env aliases still work and emit warning telemetry
+[x] Docker compose output uses normalized DEPLOY_WEB_PORT token and resolved default
+[x] Dry-run/apply focused smoke checks pass with .env-sourced config
 [x] Script structure validation smoke run passes
 [x] Roadmap updated with status-only change

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -573,7 +573,7 @@
 - [x] reports structure established
 - [x] templates structure established
 - [x] roadmaps folder recognized as tracker space
-- [.] master roadmap committed and maintained
+- [x] master roadmap committed and maintained
 - [ ] per-component roadmap slices added only when truly needed
 - [ ] structure normalization roadmap linked to future BUILD lanes
 - [ ] phase descriptions normalized repo-wide

docs/pr/BUILD_PR_LEVEL_09_27_DEPLOY_ENV_CONFIG_STANDARDIZATION.md

@@ -0,0 +1,16 @@
+# BUILD_PR — LEVEL 09_27 — DEPLOY ENV CONFIG STANDARDIZATION
+
+## Objective
+Standardize environment configuration handling for Docker deployment scripts.
+
+## Scope
+- unify environment variable handling
+- support .env files
+- ensure consistent config loading across deploy scripts
+
+## Out of Scope
+- no runtime changes
+- no tool UI changes
+
+## Roadmap Instruction
+- Update roadmap status only

scripts/PS/deploy/Clean-WebsiteRepoDeployment.ps1

@@ -2,6 +2,7 @@
 param(
     [string]$StagingRoot,
     [switch]$RemoveMetadata,
+    [string]$EnvFilePath,
     [switch]$Apply,
     [switch]$DryRun,
     [switch]$ConfirmDestructive
@@ -13,16 +14,19 @@ $ErrorActionPreference = "Stop"
 . (Join-Path $PSScriptRoot "WebsiteRepoDeploymentCommon.ps1")
 Assert-DeployScriptLocation -ScriptPath $PSCommandPath
 $executionMode = Resolve-DeployExecutionMode -Apply:$Apply.IsPresent -DryRun:$DryRun.IsPresent
+$resolvedRemoveMetadata = if ($PSBoundParameters.ContainsKey("RemoveMetadata")) { [Nullable[bool]]$RemoveMetadata.IsPresent } else { $null }
+$config = Resolve-DeployScriptConfig -StagingRoot $StagingRoot -RemoveMetadata $resolvedRemoveMetadata -EnvFilePath $EnvFilePath
+Write-DeployConfigLoadLog -ScriptName "Clean-WebsiteRepoDeployment" -Config $config
 
-$paths = Get-WebsiteDeploymentPaths -StagingRoot $StagingRoot
+$paths = Get-WebsiteDeploymentPaths -StagingRoot $config.stagingRoot
 Test-StagingRootSafety -StagingRoot $paths.stagingRoot
 $environment = Assert-DeployEnvironmentReadiness -Paths $paths
 
 $targets = New-Object System.Collections.Generic.List[string]
 if (Test-Path -LiteralPath $paths.siteRoot) {
     $targets.Add($paths.siteRoot)
 }
-if ($RemoveMetadata.IsPresent) {
+if ($config.removeMetadata) {
     foreach ($metadataPath in @($paths.planPath, $paths.updateReportPath, $paths.dockerfilePath, $paths.composePath, $paths.dockerIgnorePath)) {
         if (Test-Path -LiteralPath $metadataPath) {
             $targets.Add($metadataPath)
@@ -34,6 +38,7 @@ if ($targets.Count -eq 0) {
     Write-DeployLog -Level "INFO" -Message "Nothing to clean." -Data @{
         script = "Clean-WebsiteRepoDeployment"
         stagingRoot = $paths.stagingRoot
+        removeMetadata = $config.removeMetadata
     }
     exit 0
 }
@@ -46,6 +51,7 @@ if ($executionMode.isDryRun) {
         targets = @($targets)
         dockerCliFound = $environment.dockerCliFound
         destructiveConfirmationRequired = $true
+        removeMetadata = $config.removeMetadata
     }
     Write-DeployLog -Level "INFO" -Message "Next step: run Clean-WebsiteRepoDeployment.ps1 -Apply -ConfirmDestructive after reviewing the dry-run output."
     exit 0
@@ -68,4 +74,5 @@ Write-DeployLog -Level "SUCCESS" -Message "Cleaned website deployment artifacts.
     mode = $executionMode.label
     targetCount = $targets.Count
     dockerCliFound = $environment.dockerCliFound
+    removeMetadata = $config.removeMetadata
 }

scripts/PS/deploy/Prep-WebsiteRepoDeployment.ps1

@@ -2,6 +2,8 @@
 param(
     [string]$StagingRoot,
     [string[]]$IncludePaths,
+    [int]$WebPort,
+    [string]$EnvFilePath,
     [switch]$Apply,
     [switch]$DryRun
 )
@@ -12,13 +14,16 @@ $ErrorActionPreference = "Stop"
 . (Join-Path $PSScriptRoot "WebsiteRepoDeploymentCommon.ps1")
 Assert-DeployScriptLocation -ScriptPath $PSCommandPath
 $executionMode = Resolve-DeployExecutionMode -Apply:$Apply.IsPresent -DryRun:$DryRun.IsPresent
+$resolvedWebPort = if ($PSBoundParameters.ContainsKey("WebPort")) { [Nullable[int]]$WebPort } else { $null }
+$config = Resolve-DeployScriptConfig -StagingRoot $StagingRoot -IncludePaths $IncludePaths -WebPort $resolvedWebPort -EnvFilePath $EnvFilePath
+Write-DeployConfigLoadLog -ScriptName "Prep-WebsiteRepoDeployment" -Config $config
 
 $repoRoot = Get-DeployRepoRoot
-$paths = Get-WebsiteDeploymentPaths -StagingRoot $StagingRoot
+$paths = Get-WebsiteDeploymentPaths -StagingRoot $config.stagingRoot
 Test-StagingRootSafety -StagingRoot $paths.stagingRoot
 $environment = Assert-DeployEnvironmentReadiness -Paths $paths
 
-$normalizedIncludePaths = Normalize-IncludePaths -IncludePaths $IncludePaths
+$normalizedIncludePaths = Normalize-IncludePaths -IncludePaths $config.includePaths
 if ($normalizedIncludePaths.Count -eq 0) {
     $normalizedIncludePaths = Get-DefaultWebsiteIncludePaths
 }
@@ -64,7 +69,7 @@ Ensure-Directory -Path $paths.stagingRoot
 Ensure-Directory -Path $paths.siteRoot
 Ensure-Directory -Path $paths.metaRoot
 Write-JsonFile -Value $plan -Path $paths.planPath
-Write-DockerDeploymentArtifacts -Paths $paths
+Write-DockerDeploymentArtifacts -Paths $paths -WebPort $config.webPort
 Assert-DockerArtifactReadiness -Paths $paths
 
 Write-DeployLog -Level "SUCCESS" -Message "Prepared website deployment staging." -Data @{
@@ -74,4 +79,5 @@ Write-DeployLog -Level "SUCCESS" -Message "Prepared website deployment staging."
     planPath = $paths.planPath
     dockerfilePath = $paths.dockerfilePath
     dockerCliFound = $environment.dockerCliFound
+    webPort = $config.webPort
 }

scripts/PS/deploy/Update-WebsiteRepoDeployment.ps1

@@ -2,6 +2,8 @@
 param(
     [string]$StagingRoot,
     [string[]]$IncludePaths,
+    [int]$WebPort,
+    [string]$EnvFilePath,
     [switch]$Apply,
     [switch]$DryRun,
     [switch]$ConfirmDestructive
@@ -13,13 +15,16 @@ $ErrorActionPreference = "Stop"
 . (Join-Path $PSScriptRoot "WebsiteRepoDeploymentCommon.ps1")
 Assert-DeployScriptLocation -ScriptPath $PSCommandPath
 $executionMode = Resolve-DeployExecutionMode -Apply:$Apply.IsPresent -DryRun:$DryRun.IsPresent
+$resolvedWebPort = if ($PSBoundParameters.ContainsKey("WebPort")) { [Nullable[int]]$WebPort } else { $null }
+$config = Resolve-DeployScriptConfig -StagingRoot $StagingRoot -IncludePaths $IncludePaths -WebPort $resolvedWebPort -EnvFilePath $EnvFilePath
+Write-DeployConfigLoadLog -ScriptName "Update-WebsiteRepoDeployment" -Config $config
 
 $repoRoot = Get-DeployRepoRoot
-$paths = Get-WebsiteDeploymentPaths -StagingRoot $StagingRoot
+$paths = Get-WebsiteDeploymentPaths -StagingRoot $config.stagingRoot
 Test-StagingRootSafety -StagingRoot $paths.stagingRoot
 $environment = Assert-DeployEnvironmentReadiness -Paths $paths
 
-$normalizedIncludePaths = Normalize-IncludePaths -IncludePaths $IncludePaths
+$normalizedIncludePaths = Normalize-IncludePaths -IncludePaths $config.includePaths
 if ($normalizedIncludePaths.Count -eq 0) {
     if (Test-Path -LiteralPath $paths.planPath) {
         $existingPlan = Read-JsonFile -Path $paths.planPath
@@ -97,7 +102,7 @@ foreach ($entry in $copyEntries) {
 
 $plan = New-WebsiteDeploymentPlan -IncludePaths $normalizedIncludePaths -RepoRoot $repoRoot
 Write-JsonFile -Value $plan -Path $paths.planPath
-Write-DockerDeploymentArtifacts -Paths $paths
+Write-DockerDeploymentArtifacts -Paths $paths -WebPort $config.webPort
 Assert-DockerArtifactReadiness -Paths $paths
 
 $report = [ordered]@{
@@ -120,4 +125,5 @@ Write-DeployLog -Level "SUCCESS" -Message "Updated website deployment staging co
     dockerfilePath = $paths.dockerfilePath
     reportPath = $paths.updateReportPath
     dockerCliFound = $environment.dockerCliFound
+    webPort = $config.webPort
 }