fix: harden workspace registry installation docs

scripts/test-verify-workspace-install-docs.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Regression test for copyable installation examples and secret-file validation.
+set -euo pipefail
+
+root="$(cd "$(dirname "$0")/.." && pwd -P)"
+output="$(mktemp "${TMPDIR:-/tmp}/thoth-install-docs-test.XXXXXX")"
+trap 'rm -f "$output"' EXIT HUP INT TERM
+
+"$root/scripts/verify-workspace-install-docs.sh" --fixtures-only >"$output"
+
+for fixture in \
+  "copied local base fixture" \
+  "copied server PostgreSQL/TLS fixture" \
+  "copied HTTPS Git override fixture" \
+  "copied SSH Git override fixture" \
+  "non-path secret-file fixture rejected"; do
+  grep -Fqx "$fixture passed" "$output" >/dev/null || {
+    echo "missing fixture verification: $fixture" >&2
+    cat "$output" >&2
+    exit 1
+  }
+done

scripts/verify-workspace-install-docs.sh

@@ -5,7 +5,117 @@ set -euo pipefail
 root="$(cd "$(dirname "$0")/.." && pwd -P)"
 profile="${1:-}"
 
+trim() {
+  local value="$1"
+  value="${value#"${value%%[![:space:]]*}"}"
+  value="${value%"${value##*[![:space:]]}"}"
+  printf '%s' "$value"
+}
+
+verify_secret_file_values() {
+  local source="$1" line trimmed name value
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    trimmed="$(trim "$line")"
+    if [[ "$trimmed" == *=* || "$trimmed" == *:* ]]; then
+      name="$(trim "${trimmed%%[=:]*}")"
+      value="$(trim "${trimmed#"$name"}")"
+      value="$(trim "${value#[:=]}")"
+      if [[ "$name" =~ ^[A-Za-z_][A-Za-z0-9_]*_FILE$ ]]; then
+        value="$(trim "${value%%#*}")"
+      value="${value#\"}"; value="${value%\"}"
+      value="${value#\'}"; value="${value%\'}"
+      if [[ -n "$value" && "$value" != /* ]]; then
+        echo "non-path secret-file value for $name in $source" >&2
+        return 1
+      fi
+      fi
+    fi
+  done <"$source"
+  return 0
+}
+
+verify_server_public_contract() {
+  local server_example="$root/docs/install/examples/server-compose.workspace-registry.yaml"
+  for expected in \
+    'THT_SESSION_STORAGE: postgres' \
+    'THT_SESSION_RUNTIME_PASSWORD_FILE: /run/secrets/session_runtime_password' \
+    'THT_SESSION_DB_SSLMODE: ${THT_SESSION_DB_SSLMODE:-verify-full}' \
+    'THT_SESSION_DB_SSLROOTCERT: /run/secrets/session_ca.pem' \
+    'session_runtime_password:' \
+    'session_ca:'; do
+    grep -Fq "$expected" "$server_example" || {
+      echo "server Compose example lacks required public PostgreSQL/TLS contract: $expected" >&2
+      return 1
+    }
+  done
+}
+
+compose_fixture() {
+  local name="$1" directory="$2"; shift 2
+  (
+    cd "$directory"
+    docker compose --env-file .env "$@" config --quiet
+  )
+  echo "$name passed"
+}
+
+verify_copied_operator_fixtures() {
+  local fixture_root local_dir server_dir https_dir ssh_dir
+  fixture_root="$(mktemp -d "${TMPDIR:-/tmp}/thoth-install-fixtures.XXXXXX")"
+  trap 'rm -rf "$fixture_root"' RETURN
+  local_dir="$fixture_root/local"; server_dir="$fixture_root/server"
+  https_dir="$fixture_root/https"; ssh_dir="$fixture_root/ssh"
+  mkdir -p "$local_dir" "$server_dir" "$https_dir" "$ssh_dir"
+
+  cp "$root/docs/install/examples/local-compose.workspace-registry.yaml" "$local_dir/compose.workspace-registry.yaml"
+  printf 'THT_SOURCE_ROOT=%s\n' "$root" >"$local_dir/.env"
+  compose_fixture "copied local base fixture" "$local_dir" -f compose.workspace-registry.yaml
+
+  cp "$root/docs/install/examples/server-compose.workspace-registry.yaml" "$server_dir/compose.workspace-registry.yaml"
+  cp "$root/deploy/workspaces/server-sessions.yaml.example" "$server_dir/server-sessions.yaml"
+  : >"$server_dir/session-runtime-password"; : >"$server_dir/session-ca.pem"
+  printf '%s\n' \
+    "THT_SOURCE_ROOT=$root" \
+    "THT_SERVER_WORKSPACE_CONFIG=$server_dir/server-sessions.yaml" \
+    'THT_SESSION_DB_HOST=sessions.example.invalid' \
+    'THT_SESSION_DB_NAME=thoth_sessions' \
+    'THT_SESSION_RUNTIME_USER=thoth_sessions_app' \
+    "THT_SESSION_RUNTIME_PASSWORD_SOURCE=$server_dir/session-runtime-password" \
+    "THT_SESSION_CA_SOURCE=$server_dir/session-ca.pem" >"$server_dir/.env"
+  compose_fixture "copied server PostgreSQL/TLS fixture" "$server_dir" -f compose.workspace-registry.yaml
+
+  cp "$root/docs/install/examples/local-compose.workspace-registry.yaml" "$https_dir/compose.workspace-registry.yaml"
+  cp "$root/docs/install/examples/git-https.workspace-registry.yaml" "$https_dir/git-https.yaml"
+  : >"$https_dir/git-credentials"; : >"$https_dir/git-ca.pem"
+  printf '%s\n' \
+    "THT_SOURCE_ROOT=$root" \
+    "THT_WORKSPACE_GIT_CREDENTIALS_FILE=$https_dir/git-credentials" \
+    "THT_WORKSPACE_GIT_CA_FILE=$https_dir/git-ca.pem" >"$https_dir/.env"
+  compose_fixture "copied HTTPS Git override fixture" "$https_dir" -f compose.workspace-registry.yaml -f git-https.yaml
+
+  cp "$root/docs/install/examples/local-compose.workspace-registry.yaml" "$ssh_dir/compose.workspace-registry.yaml"
+  cp "$root/docs/install/examples/git-ssh.workspace-registry.yaml" "$ssh_dir/git-ssh.yaml"
+  : >"$ssh_dir/git-ssh-key"; : >"$ssh_dir/git-known-hosts"
+  printf '%s\n' \
+    "THT_SOURCE_ROOT=$root" \
+    "THT_WORKSPACE_GIT_SSH_KEY_FILE=$ssh_dir/git-ssh-key" \
+    "THT_WORKSPACE_GIT_KNOWN_HOSTS_FILE=$ssh_dir/git-known-hosts" >"$ssh_dir/.env"
+  compose_fixture "copied SSH Git override fixture" "$ssh_dir" -f compose.workspace-registry.yaml -f git-ssh.yaml
+
+  printf 'THT_WS_EXAMPLE_DWH_PASSWORD_FILE=not-a-path\n' >"$fixture_root/non-path-secret.env"
+  if verify_secret_file_values "$fixture_root/non-path-secret.env" >/dev/null 2>&1; then
+    echo "non-path secret-file fixture was accepted" >&2
+    return 1
+  fi
+  echo "non-path secret-file fixture rejected passed"
+}
+
 case "$profile" in
+  --fixtures-only)
+    [[ $# -eq 1 ]] || { echo "usage: $0 --fixtures-only" >&2; exit 2; }
+    verify_copied_operator_fixtures
+    exit 0
+    ;;
   --profile)
     profile="${2:-}"
     [[ $# -eq 2 ]] || { echo "usage: $0 --profile {local|server}" >&2; exit 2; }
@@ -72,6 +182,11 @@ if grep -Ein '(^|[[:space:]])(password|api[_-]?key|token|secret)[[:space:]]*[:=]
   echo "installation documentation contains a secret literal" >&2
   exit 1
 fi
+verify_secret_file_values "$manual"
+verify_secret_file_values "$example"
+verify_secret_file_values "$root/docs/install/examples/git-https.workspace-registry.yaml"
+verify_secret_file_values "$root/docs/install/examples/git-ssh.workspace-registry.yaml"
+verify_server_public_contract
 
 commands="$(mktemp "${TMPDIR:-/tmp}/thoth-install-docs.XXXXXX")"
 trap 'rm -f "$commands"' EXIT HUP INT TERM
@@ -99,4 +214,7 @@ echo "== Run isolated workspace-registry bootstrap and recovery smoke =="
   env -u WORKSPACE_GIT_REMOTE ./scripts/workspace-registry-smoke.sh
 )
 
+echo "== Validate copied operator fixtures and optional Git transports =="
+verify_copied_operator_fixtures
+
 echo "$profile installation documentation verification passed"