feat(staging): implement ephemeral staging VM provisioning and TrueNAS snapshot clone workflow

scripts/truenas-staging-teardown.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# This script destroys the ephemeral staging ZFS clone and the base snapshot.
+# Required environment variables:
+# TRUENAS_IP: The IP address of the TrueNAS scale instance
+# TRUENAS_API_KEY: The API token for TrueNAS
+# POOL_NAME: The name of the ZFS pool (e.g., "tank")
+# SOURCE_DATASET: The name of the production dataset (e.g., "apps/jellyfin")
+# PR_NUMBER: The Pull Request number
+
+if [[ -z "${TRUENAS_IP:-}" || -z "${TRUENAS_API_KEY:-}" || -z "${POOL_NAME:-}" || -z "${SOURCE_DATASET:-}" || -z "${PR_NUMBER:-}" ]]; then
+    echo "Error: Missing required environment variables."
+    exit 1
+fi
+
+BASE_URL="http://${TRUENAS_IP}/api/v2.0"
+HEADERS=(
+    "-H" "Authorization: Bearer ${TRUENAS_API_KEY}"
+    "-H" "Content-Type: application/json"
+)
+
+DATASET_ID="${POOL_NAME}/${SOURCE_DATASET}"
+SNAPSHOT_NAME="pr-${PR_NUMBER}-base"
+CLONE_DATASET_ID="${POOL_NAME}/${SOURCE_DATASET}-pr-${PR_NUMBER}"
+
+# TrueNAS API requires the ID to be URL-encoded for dataset deletion
+# URL encoding helper (replace / with %2F)
+ENCODED_CLONE_ID="${CLONE_DATASET_ID//\//%2F}"
+ENCODED_SNAPSHOT_ID="${DATASET_ID}@${SNAPSHOT_NAME}"
+ENCODED_SNAPSHOT_ID="${ENCODED_SNAPSHOT_ID//\//%2F}"
+
+echo "1. Destroying staging clone ${CLONE_DATASET_ID}..."
+curl -s -X DELETE "${BASE_URL}/zfs/dataset/id/${ENCODED_CLONE_ID}" "${HEADERS[@]}" > /dev/null
+
+echo "2. Destroying base snapshot ${DATASET_ID}@${SNAPSHOT_NAME}..."
+curl -s -X DELETE "${BASE_URL}/zfs/snapshot/id/${ENCODED_SNAPSHOT_ID}" "${HEADERS[@]}" > /dev/null
+
+echo "Staging dataset and snapshot cleaned up successfully."