Adds dry-run and validation capabilities to deployment scripts to ensure safe execution.

BUILD_PR_LEVEL_09_26_DEPLOY_VALIDATION_AND_DRYRUN

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,10 +2,10 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-- refine scripts in scripts/PS/deploy/
-- ensure docker-ready deployment flow
-- standardize parameters and logging
-- enforce script structure rules
+- add dry-run mode to scripts/PS/deploy/
+- validate inputs and environment
+- prevent destructive execution without explicit confirmation
+- improve output messaging
 - commit format:
   description first line
   PR name last line

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,2 @@
-Refine Docker deploy scripts with standardized mode handling/logging and deploy-folder enforcement checks.
-BUILD_PR_LEVEL_09_25_DOCKER_DEPLOY_SCRIPT_REFINEMENT
+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

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-BUILD_PR_LEVEL_09_26_DEPLOY_VALIDATION_AND_DRYRUN
+BUILD_PR_LEVEL_09_27_DEPLOY_ENV_CONFIG_STANDARDIZATION

docs/dev/reports/change_summary.txt

@@ -1,17 +1,18 @@
-BUILD_PR_LEVEL_09_25_DOCKER_DEPLOY_SCRIPT_REFINEMENT
+BUILD_PR_LEVEL_09_26_DEPLOY_VALIDATION_AND_DRYRUN
 
 Scope:
-- Refined deploy scripts under scripts/PS/deploy/ only.
-- Kept behavior surgical and non-destructive by default.
+- Refined deployment safety/validation behavior only under `scripts/PS/deploy/`.
+- No runtime, engine, tool UI, or non-deploy scope changes.
 
 Implemented:
-- Added shared deploy execution mode normalization (`-Apply` / `-DryRun`) in WebsiteRepoDeploymentCommon.ps1.
-- Added shared structured deploy logging helper with consistent level+timestamp output.
-- Added deploy script placement enforcement (`scripts/PS/deploy/`) with actionable failure text.
-- Added Docker artifact readiness assertion after artifact writes in prep/update flows.
-- Updated prep/update/clean entry scripts to use shared mode/logging enforcement helpers.
+- 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.
 
-Docs/Tracking:
-- Updated commit comment format (description first line, PR name last line).
-- Updated validation checklist for focused PowerShell/deploy checks.
-- Updated roadmap with status-only progression tied to acceptance enforcement.
+Tracking:
+- Commit comment format enforced (description first line, PR name last line, no leading blank line).
+- Roadmap updated with status-only change.

docs/dev/reports/validation_checklist.txt

@@ -1,6 +1,9 @@
-[x] PowerShell parse/readiness checks on touched deploy scripts
-[x] focused dry-run smoke checks for prep/update/clean deploy flow
-[x] focused apply smoke checks in tmp staging path for prep/update/clean deploy flow
-[x] Docker artifact readiness assertions pass after prep/update apply flows
-[x] script structure validation smoke run passes
-[x] roadmap updated with status-only change
+[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] Script structure validation smoke run passes
+[x] Roadmap updated with status-only change

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -627,7 +627,7 @@
 - [x] finish active promotion-gate lane enough to remove it from half-active status
 - [.] convert repo structure normalization into exact move-map BUILDs with explicit validation
 - [.] re-baseline this roadmap after active execution lanes stabilize
-- [ ] split future implementation into small dependency-ordered PRs
+- [.] split future implementation into small dependency-ordered PRs
 - [ ] avoid broad repo-wide cleanup passes until the active lanes above are materially further along
 
 - [x] relocate active template surfaces to `tools/templates/` and remove the empty root `templates/` directory

docs/pr/BUILD_PR_LEVEL_09_26_DEPLOY_VALIDATION_AND_DRYRUN.md

@@ -0,0 +1,16 @@
+# BUILD_PR — LEVEL 09_26 — DEPLOY VALIDATION AND DRY-RUN
+
+## Objective
+Add validation and dry-run capabilities to deployment scripts to ensure safe execution before actual Docker deployment.
+
+## Scope
+- add dry-run mode to deploy scripts
+- validate required inputs and environment
+- ensure no destructive operations without confirmation
+
+## Out of Scope
+- no runtime changes
+- no tool UI changes
+
+## Roadmap Instruction
+- Update roadmap status only

scripts/PS/deploy/Clean-WebsiteRepoDeployment.ps1

@@ -3,7 +3,8 @@ param(
     [string]$StagingRoot,
     [switch]$RemoveMetadata,
     [switch]$Apply,
-    [switch]$DryRun
+    [switch]$DryRun,
+    [switch]$ConfirmDestructive
 )
 
 Set-StrictMode -Version Latest
@@ -15,6 +16,7 @@ $executionMode = Resolve-DeployExecutionMode -Apply:$Apply.IsPresent -DryRun:$Dr
 
 $paths = Get-WebsiteDeploymentPaths -StagingRoot $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) {
@@ -42,11 +44,15 @@ if ($executionMode.isDryRun) {
         mode = $executionMode.label
         targetCount = $targets.Count
         targets = @($targets)
+        dockerCliFound = $environment.dockerCliFound
+        destructiveConfirmationRequired = $true
     }
-    Write-DeployLog -Level "INFO" -Message "Run with -Apply to remove deployment artifacts."
+    Write-DeployLog -Level "INFO" -Message "Next step: run Clean-WebsiteRepoDeployment.ps1 -Apply -ConfirmDestructive after reviewing the dry-run output."
     exit 0
 }
 
+Assert-ExplicitDestructiveConfirmation -IsDryRun:$executionMode.isDryRun -ConfirmDestructive:$ConfirmDestructive.IsPresent -OperationName "Clean-WebsiteRepoDeployment delete" -TargetCount $targets.Count
+
 foreach ($target in $targets) {
     if (-not (Test-PathWithinRoot -Path $target -RootPath $paths.stagingRoot)) {
         throw "Safety check failed. Target escapes staging root: $target"
@@ -61,4 +67,5 @@ Write-DeployLog -Level "SUCCESS" -Message "Cleaned website deployment artifacts.
     script = "Clean-WebsiteRepoDeployment"
     mode = $executionMode.label
     targetCount = $targets.Count
+    dockerCliFound = $environment.dockerCliFound
 }

scripts/PS/deploy/Prep-WebsiteRepoDeployment.ps1

@@ -16,11 +16,13 @@ $executionMode = Resolve-DeployExecutionMode -Apply:$Apply.IsPresent -DryRun:$Dr
 $repoRoot = Get-DeployRepoRoot
 $paths = Get-WebsiteDeploymentPaths -StagingRoot $StagingRoot
 Test-StagingRootSafety -StagingRoot $paths.stagingRoot
+$environment = Assert-DeployEnvironmentReadiness -Paths $paths
 
 $normalizedIncludePaths = Normalize-IncludePaths -IncludePaths $IncludePaths
 if ($normalizedIncludePaths.Count -eq 0) {
     $normalizedIncludePaths = Get-DefaultWebsiteIncludePaths
 }
+Assert-NormalizedIncludePaths -IncludePaths $normalizedIncludePaths
 
 $missing = New-Object System.Collections.Generic.List[string]
 foreach ($entry in $normalizedIncludePaths) {
@@ -44,8 +46,9 @@ if ($executionMode.isDryRun) {
         mode = $executionMode.label
         stagingRoot = $paths.stagingRoot
         includePaths = $normalizedIncludePaths
+        dockerCliFound = $environment.dockerCliFound
     }
-    Write-DeployLog -Level "INFO" -Message "Run with -Apply to create staging folders, deployment plan, and Docker artifacts."
+    Write-DeployLog -Level "INFO" -Message "Next step: run Prep-WebsiteRepoDeployment.ps1 -Apply after reviewing include paths and staging root."
     exit 0
 }
 
@@ -70,4 +73,5 @@ Write-DeployLog -Level "SUCCESS" -Message "Prepared website deployment staging."
     stagingRoot = $paths.stagingRoot
     planPath = $paths.planPath
     dockerfilePath = $paths.dockerfilePath
+    dockerCliFound = $environment.dockerCliFound
 }

scripts/PS/deploy/Update-WebsiteRepoDeployment.ps1

@@ -3,7 +3,8 @@ param(
     [string]$StagingRoot,
     [string[]]$IncludePaths,
     [switch]$Apply,
-    [switch]$DryRun
+    [switch]$DryRun,
+    [switch]$ConfirmDestructive
 )
 
 Set-StrictMode -Version Latest
@@ -16,6 +17,7 @@ $executionMode = Resolve-DeployExecutionMode -Apply:$Apply.IsPresent -DryRun:$Dr
 $repoRoot = Get-DeployRepoRoot
 $paths = Get-WebsiteDeploymentPaths -StagingRoot $StagingRoot
 Test-StagingRootSafety -StagingRoot $paths.stagingRoot
+$environment = Assert-DeployEnvironmentReadiness -Paths $paths
 
 $normalizedIncludePaths = Normalize-IncludePaths -IncludePaths $IncludePaths
 if ($normalizedIncludePaths.Count -eq 0) {
@@ -27,6 +29,7 @@ if ($normalizedIncludePaths.Count -eq 0) {
         $normalizedIncludePaths = Get-DefaultWebsiteIncludePaths
     }
 }
+Assert-NormalizedIncludePaths -IncludePaths $normalizedIncludePaths
 
 $copyEntries = New-Object System.Collections.Generic.List[object]
 foreach ($entry in $normalizedIncludePaths) {
@@ -56,8 +59,10 @@ if ($executionMode.isDryRun) {
         mode = $executionMode.label
         siteRoot = $paths.siteRoot
         includePaths = $normalizedIncludePaths
+        dockerCliFound = $environment.dockerCliFound
+        destructiveConfirmationRequired = $true
     }
-    Write-DeployLog -Level "INFO" -Message "Run with -Apply to refresh staged website content."
+    Write-DeployLog -Level "INFO" -Message "Next step: run Update-WebsiteRepoDeployment.ps1 -Apply -ConfirmDestructive after reviewing the dry-run output."
     exit 0
 }
 
@@ -73,6 +78,9 @@ Ensure-Directory -Path $paths.stagingRoot
 Ensure-Directory -Path $paths.metaRoot
 Ensure-Directory -Path $paths.siteRoot
 
+$existingSiteRoot = Test-Path -LiteralPath $paths.siteRoot
+Assert-ExplicitDestructiveConfirmation -IsDryRun:$executionMode.isDryRun -ConfirmDestructive:$ConfirmDestructive.IsPresent -OperationName "Update-WebsiteRepoDeployment site refresh" -TargetCount $(if ($existingSiteRoot) { 1 } else { 0 })
+
 if (Test-Path -LiteralPath $paths.siteRoot) {
     if (-not (Test-PathWithinRoot -Path $paths.siteRoot -RootPath $paths.stagingRoot)) {
         throw "Site root safety check failed: $($paths.siteRoot)"
@@ -111,4 +119,5 @@ Write-DeployLog -Level "SUCCESS" -Message "Updated website deployment staging co
     copiedEntries = $copyEntries.Count
     dockerfilePath = $paths.dockerfilePath
     reportPath = $paths.updateReportPath
+    dockerCliFound = $environment.dockerCliFound
 }