aether-colony 3.1.4 → 3.1.15

package/runtime/utils/swarm-display.sh

@@ -32,11 +32,11 @@ get_caste_color() {
 # Caste emojis (must match aether-utils.sh)
 get_caste_emoji() {
   case "$1" in
-    builder)  echo "🔨" ;;
-    watcher)  echo "👁️" ;;
-    scout)    echo "🔍" ;;
-    chaos)    echo "🎲" ;;
-    prime)    echo "👑" ;;
+    builder)  echo "🔨🐜" ;;
+    watcher)  echo "👁️🐜" ;;
+    scout)    echo "🔍🐜" ;;
+    chaos)    echo "🎲🐜" ;;
+    prime)    echo "👑🐜" ;;
     *)        echo "🐜" ;;
   esac
 }

package/runtime/utils/watch-spawn-tree.sh

@@ -4,6 +4,7 @@
 
 DATA_DIR="${1:-.aether/data}"
 SPAWN_FILE="$DATA_DIR/spawn-tree.txt"
+VIEW_STATE_FILE="$DATA_DIR/view-state.json"
 
 # ANSI colors
 YELLOW='\033[33m'
@@ -28,6 +29,43 @@ get_emoji() {
   esac
 }
 
+# Load view state
+load_view_state() {
+  if [[ -f "$VIEW_STATE_FILE" ]]; then
+    cat "$VIEW_STATE_FILE" 2>/dev/null || echo '{}'
+  else
+    echo '{"tunnel_view":{"expanded":[],"collapsed":["__depth_3_plus__"],"default_expand_depth":2,"show_completed":true}}'
+  fi
+}
+
+# Check if item is expanded
+is_expanded() {
+  local item="$1"
+  local depth="${2:-1}"
+  local view_state=$(load_view_state)
+
+  # Check if explicitly expanded
+  if echo "$view_state" | jq -e ".tunnel_view.expanded | contains([\"$item\"])" >/dev/null 2>&1; then
+    return 0
+  fi
+
+  # Check if depth-based auto-collapse applies
+  local default_depth=$(echo "$view_state" | jq -r '.tunnel_view.default_expand_depth // 2')
+  if [[ "$depth" -gt "$default_depth" ]]; then
+    # Check if __depth_3_plus__ is in collapsed (indicating auto-collapse enabled)
+    if echo "$view_state" | jq -e '.tunnel_view.collapsed | contains(["__depth_3_plus__"])' >/dev/null 2>&1; then
+      return 1  # Collapsed by depth
+    fi
+  fi
+
+  # Check if explicitly collapsed
+  if echo "$view_state" | jq -e ".tunnel_view.collapsed | contains([\"$item\"])" >/dev/null 2>&1; then
+    return 1
+  fi
+
+  return 0  # Default to expanded
+}
+
 # Status colors
 get_status_color() {
   case "$1" in
@@ -46,7 +84,7 @@ render_tree() {
   cat << 'EOF'
        .-.
       (o o)  AETHER COLONY
-      | O |  Spawn Tree
+      | O |  Spawn Tree (Collapsible)
        `-`
 EOF
   echo -e "${RESET}"
@@ -110,6 +148,22 @@ EOF
     color=$(get_status_color "$status")
     task="${worker_task[$name]}"
 
+    # Check if collapsed
+    local collapsed=false
+    local child_count=0
+
+    # Count children
+    for child in "${!workers[@]}"; do
+      if [[ "${workers[$child]}" == "$name" ]]; then
+        child_count=$((child_count + 1))
+      fi
+    done
+
+    # Check collapse state (only if has children)
+    if [[ $child_count -gt 0 ]] && ! is_expanded "$name" "$depth"; then
+      collapsed=true
+    fi
+
     # Truncate task for display
     [[ ${#task} -gt 30 ]] && task="${task:0:27}..."
 
@@ -120,30 +174,42 @@ EOF
       connector="├──"
     fi
 
-    echo -e "${indent}${DIM}${connector}${RESET} ${emoji} ${color}${name}${RESET}: ${task} ${DIM}[depth $depth]${RESET}"
-
-    # Find children of this worker
-    local children=()
-    for child in "${!workers[@]}"; do
-      if [[ "${workers[$child]}" == "$name" ]]; then
-        children+=("$child")
+    # Show expand/collapse indicator
+    local expand_indicator=""
+    if [[ $child_count -gt 0 ]]; then
+      if [[ "$collapsed" == "true" ]]; then
+        expand_indicator="▶ [$child_count hidden] "
+      else
+        expand_indicator="▼ "
       fi
-    done
-
-    # Render children
-    local child_indent="${indent}    "
-    if [[ "$is_last" != "true" ]]; then
-      child_indent="${indent}${DIM}│${RESET}   "
     fi
 
-    local child_count=${#children[@]}
-    local child_idx=0
-    for child in "${children[@]}"; do
-      child_idx=$((child_idx + 1))
-      local child_is_last="false"
-      [[ $child_idx -eq $child_count ]] && child_is_last="true"
-      render_worker "$child" "$child_indent" $((depth + 1)) "$child_is_last"
-    done
+    echo -e "${indent}${DIM}${connector}${RESET} ${emoji} ${color}${name}${RESET}: ${expand_indicator}${task} ${DIM}[depth $depth]${RESET}"
+
+    # Render children if not collapsed
+    if [[ "$collapsed" != "true" ]]; then
+      local children=()
+      for child in "${!workers[@]}"; do
+        if [[ "${workers[$child]}" == "$name" ]]; then
+          children+=("$child")
+        fi
+      done
+
+      local child_count=${#children[@]}
+      local child_idx=0
+      for child in "${children[@]}"; do
+        child_idx=$((child_idx + 1))
+        local child_is_last="false"
+        [[ $child_idx -eq $child_count ]] && child_is_last="true"
+
+        local child_indent="${indent}    "
+        if [[ "$is_last" != "true" ]]; then
+          child_indent="${indent}${DIM}│${RESET}   "
+        fi
+
+        render_worker "$child" "$child_indent" $((depth + 1)) "$child_is_last"
+      done
+    fi
   }
 
   # Render root workers (spawned by Queen) at depth 1
@@ -162,6 +228,8 @@ EOF
   completed=$(grep -c "completed" "$SPAWN_FILE" 2>/dev/null || echo "0")
   active=$(grep -c "spawned" "$SPAWN_FILE" 2>/dev/null || echo "0")
   echo -e "Workers: ${GREEN}$completed completed${RESET} | ${YELLOW}$active active${RESET}"
+  echo ""
+  echo -e "${DIM}Controls: e+<name> to expand, c+<name> to collapse${RESET}"
 }
 
 # Initial render

package/runtime/utils/xml-compose.sh

@@ -0,0 +1,247 @@
+#!/bin/bash
+# XML Composition Functions for Worker Priming
+# Part of xml-utils.sh - XInclude-based modular configuration composition
+#
+# Usage: source .aether/utils/xml-compose.sh
+#        xml-compose <input_xml> [output_xml]
+#        xml-compose-worker-priming <priming_xml> [output_xml]
+#
+# These functions enable declarative composition of worker configurations
+# using XInclude directives to merge queen-wisdom, active-trails, and stack-profiles.
+
+set -euo pipefail
+
+# Note: This file should be sourced AFTER xml-utils.sh
+# It relies on xml_json_ok, xml_json_err, and XMLLINT_AVAILABLE variables
+
+# ============================================================================
+# Path Validation (Security)
+# ============================================================================
+
+# xml-validate-include-path: Validate XInclude path for traversal attacks
+# Usage: xml-validate-include-path <include_path> <base_dir>
+# Returns: absolute path on success, exits with error on failure
+xml-validate-include-path() {
+    local include_path="$1"
+    local base_dir="$2"
+
+    # Resolve base directory to absolute path
+    local allowed_dir
+    allowed_dir=$(cd "$base_dir" 2>/dev/null && pwd) || {
+        xml_json_err "INVALID_BASE_DIR" \
+            "Base directory does not exist" \
+            "dir=$base_dir"
+        return 1
+    }
+
+    # First check: reject paths with traversal sequences
+    if [[ "$include_path" =~ \.\.[\/] ]] || [[ "$include_path" =~ [\/]\.\. ]]; then
+        xml_json_err "PATH_TRAVERSAL_DETECTED" \
+            "Path contains traversal sequences" \
+            "path=$include_path"
+        return 1
+    fi
+
+    # Build resolved path
+    local resolved_path
+    if [[ "$include_path" == /* ]]; then
+        # Absolute path - must start with allowed_dir
+        if [[ ! "$include_path" =~ ^"$allowed_dir" ]]; then
+            xml_json_err "PATH_TRAVERSAL_BLOCKED" \
+                "Absolute path outside allowed directory" \
+                "path=$include_path, allowed=$allowed_dir"
+            return 1
+        fi
+        resolved_path="$include_path"
+    else
+        # Relative path - resolve against base_dir
+        resolved_path="$allowed_dir/$include_path"
+    fi
+
+    # Normalize path (remove . and .. components manually for portability)
+    local normalized_path="$resolved_path"
+
+    # Verify final path is within allowed directory
+    if [[ ! "$normalized_path" =~ ^"$allowed_dir" ]]; then
+        xml_json_err "PATH_TRAVERSAL_BLOCKED" \
+            "Resolved path outside allowed directory" \
+            "path=$normalized_path, allowed=$allowed_dir"
+        return 1
+    fi
+
+    echo "$normalized_path"
+}
+
+# ============================================================================
+# XInclude Composition Functions
+# ============================================================================
+
+# xml-compose: Resolve XInclude directives in worker priming documents
+# Usage: xml-compose <input_xml> [output_xml]
+# Returns: {"ok":true,"result":{"composed":true,"output":"...","sources_resolved":N}}
+xml-compose() {
+    local input_xml="${1:-}"
+    local output_xml="${2:-}"
+
+    [[ -z "$input_xml" ]] && { xml_json_err "Missing input XML file argument"; return 1; }
+    [[ -f "$input_xml" ]] || { xml_json_err "Input XML file not found: $input_xml"; return 1; }
+
+    # Check well-formedness first
+    local well_formed_result
+    well_formed_result=$(xml-well-formed "$input_xml" 2>/dev/null)
+    if ! echo "$well_formed_result" | jq -e '.result.well_formed' >/dev/null 2>&1; then
+        xml_json_err "Input XML is not well-formed"
+        return 1
+    fi
+
+    # Use xmllint for XInclude processing if available (with XXE protection)
+    if [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        local composed
+        composed=$(xmllint --nonet --noent --xinclude --format "$input_xml" 2>/dev/null) || {
+            xml_json_err "XInclude composition failed - check that included files exist"
+            return 1
+        }
+
+        # Determine output destination
+        if [[ -n "$output_xml" ]]; then
+            echo "$composed" > "$output_xml"
+            local escaped_output
+            escaped_output=$(echo "$output_xml" | jq -Rs '.[:-1]')
+            xml_json_ok "{\"composed\":true,\"output\":$escaped_output,\"sources_resolved\":\"auto\"}"
+        else
+            # Output to stdout wrapped in JSON
+            local escaped_composed
+            escaped_composed=$(echo "$composed" | jq -Rs '.')
+            xml_json_ok "{\"composed\":true,\"xml\":$escaped_composed,\"sources_resolved\":\"auto\"}"
+        fi
+        return 0
+    fi
+
+    # No xmllint available - error explicitly (manual fallback removed for security)
+    xml_json_err "XMLLINT_REQUIRED" \
+        "xmllint is required for secure XInclude processing" \
+        "install_hint='brew install libxml2'"
+    return 1
+}
+
+# xml-list-includes: List all XInclude references in a document
+# Usage: xml-list-includes <xml_file>
+# Returns: {"ok":true,"result":{"includes":[{"href":"...","parse":"..."},...]}}
+xml-list-includes() {
+    local xml_file="${1:-}"
+
+    [[ -z "$xml_file" ]] && { xml_json_err "Missing XML file argument"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "XML file not found: $xml_file"; return 1; }
+
+    local includes_json="[]"
+
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        # Use xmlstarlet for proper namespace-aware extraction
+        includes_json=$(xmlstarlet sel -N xi="http://www.w3.org/2001/XInclude" \
+            -t -m "//xi:include" \
+            -o '{"href":"' -v "@href" -o '","parse":"' -v "@parse" -o '","xpointer":"' -v "@xpointer" -o '"}' \
+            -n "$xml_file" 2>/dev/null | jq -s '.' || echo "[]")
+    elif [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        # Fallback: grep for xi:include (less reliable but portable)
+        local base_dir
+        base_dir=$(dirname "$xml_file")
+
+        includes_json=$(grep -oE 'xi:include[^>]*href="[^"]+"' "$xml_file" 2>/dev/null | while read -r match; do
+            local href
+            href=$(echo "$match" | grep -oE 'href="[^"]+"' | cut -d'"' -f2)
+            local parse
+            parse=$(echo "$match" | grep -oE 'parse="[^"]+"' | cut -d'"' -f2 || echo "xml")
+            echo "{\"href\":\"$href\",\"parse\":\"$parse\",\"resolved\":\"$base_dir/$href\"}"
+        done | jq -s '.' || echo "[]")
+    else
+        xml_json_err "No XML tool available. Install xmlstarlet or libxml2."
+        return 1
+    fi
+
+    local count
+    count=$(echo "$includes_json" | jq 'length')
+    xml_json_ok "{\"includes\":$includes_json,\"count\":$count}"
+}
+
+# xml-compose-worker-priming: Specialized composition for worker priming documents
+# Usage: xml-compose-worker-priming <priming_xml> [output_xml]
+# Returns: {"ok":true,"result":{"composed":true,"worker_id":"...","caste":"...","sources":{...}}}
+xml-compose-worker-priming() {
+    local priming_xml="${1:-}"
+    local output_xml="${2:-}"
+
+    [[ -z "$priming_xml" ]] && { xml_json_err "Missing priming XML file argument"; return 1; }
+    [[ -f "$priming_xml" ]] || { xml_json_err "Priming XML file not found: $priming_xml"; return 1; }
+
+    # Validate against schema if available
+    local schema_file=".aether/schemas/worker-priming.xsd"
+    if [[ -f "$schema_file" ]] && [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        local validation
+        validation=$(xml-validate "$priming_xml" "$schema_file" 2>/dev/null)
+        if ! echo "$validation" | jq -e '.result.valid' >/dev/null 2>&1; then
+            xml_json_err "Worker priming XML failed schema validation"
+            return 1
+        fi
+    fi
+
+    # Extract worker identity before composition
+    local worker_id worker_caste
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        worker_id=$(xmlstarlet sel -t -v "//*[local-name()='worker-identity']/@id" "$priming_xml" 2>/dev/null || echo "unknown")
+        worker_caste=$(xmlstarlet sel -t -v "//*[local-name()='worker-identity']/*[local-name()='caste']" "$priming_xml" 2>/dev/null || echo "unknown")
+    else
+        # Fallback: sed extraction (portable, no grep -P)
+        worker_id=$(sed -n 's/.*worker-identity[^>]*id="\([^"]*\)".*/\1/p' "$priming_xml" | head -1 || echo "unknown")
+        worker_caste=$(sed -n 's/.*<caste>\([^<]*\)<\/caste>.*/\1/p' "$priming_xml" | head -1 || echo "unknown")
+    fi
+
+    # Compose the document
+    local compose_result
+    if [[ -n "$output_xml" ]]; then
+        compose_result=$(xml-compose "$priming_xml" "$output_xml" 2>/dev/null)
+    else
+        compose_result=$(xml-compose "$priming_xml" 2>/dev/null)
+    fi
+
+    if ! echo "$compose_result" | jq -e '.ok' >/dev/null 2>&1; then
+        xml_json_err "Composition failed: $(echo "$compose_result" | jq -r '.error // "unknown"')"
+        return 1
+    fi
+
+    # Count sources from different sections
+    local queen_wisdom_count active_trails_count stack_profiles_count
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]] && [[ -n "$output_xml" ]]; then
+        queen_wisdom_count=$(xmlstarlet sel -t -v "count(//*[local-name()='queen-wisdom']/*[local-name()='wisdom-source'])" "$output_xml" 2>/dev/null || echo "0")
+        active_trails_count=$(xmlstarlet sel -t -v "count(//*[local-name()='active-trails']/*[local-name()='trail-source'])" "$output_xml" 2>/dev/null || echo "0")
+        stack_profiles_count=$(xmlstarlet sel -t -v "count(//*[local-name()='stack-profiles']/*[local-name()='profile-source'])" "$output_xml" 2>/dev/null || echo "0")
+    else
+        queen_wisdom_count="unknown"
+        active_trails_count="unknown"
+        stack_profiles_count="unknown"
+    fi
+
+    # Build result
+    local result_json
+    result_json=$(jq -n \
+        --arg worker_id "$worker_id" \
+        --arg caste "$worker_caste" \
+        --arg queen_wisdom "$queen_wisdom_count" \
+        --arg active_trails "$active_trails_count" \
+        --arg stack_profiles "$stack_profiles_count" \
+        '{
+            composed: true,
+            worker_id: $worker_id,
+            caste: $caste,
+            sources: {
+                queen_wisdom: $queen_wisdom,
+                active_trails: $active_trails,
+                stack_profiles: $stack_profiles
+            }
+        }')
+
+    xml_json_ok "$result_json"
+}
+
+# Export functions
+export -f xml-compose xml-list-includes xml-compose-worker-priming
+export -f xml-validate-include-path

package/runtime/utils/xml-core.sh

@@ -0,0 +1,186 @@
+#!/bin/bash
+# XML Core Utilities
+# Fundamental XML operations: validation, formatting, escaping
+#
+# Usage: source .aether/utils/xml-core.sh
+#        xml-validate <xml_file> <xsd_file>
+#        xml-well-formed <xml_file>
+#        xml-format <xml_file>
+#        xml-escape <text>
+#        xml-unescape <text>
+
+# ============================================================================
+# Feature Detection
+# ============================================================================
+
+# Check for required XML tools (only if not already set)
+if [[ -z "${XMLLINT_AVAILABLE:-}" ]]; then
+    XMLLINT_AVAILABLE=false
+    if command -v xmllint >/dev/null 2>&1; then
+        XMLLINT_AVAILABLE=true
+    fi
+fi
+
+if [[ -z "${XMLSTARLET_AVAILABLE:-}" ]]; then
+    XMLSTARLET_AVAILABLE=false
+    if command -v xmlstarlet >/dev/null 2>&1; then
+        XMLSTARLET_AVAILABLE=true
+    fi
+fi
+
+if [[ -z "${XSLTPROC_AVAILABLE:-}" ]]; then
+    XSLTPROC_AVAILABLE=false
+    if command -v xsltproc >/dev/null 2>&1; then
+        XSLTPROC_AVAILABLE=true
+    fi
+fi
+
+# ============================================================================
+# JSON Output Helpers
+# ============================================================================
+
+xml_json_ok() { printf '{"ok":true,"result":%s}\n' "$1"; }
+
+xml_json_err() {
+    local code="${1:-UNKNOWN_ERROR}"
+    local message="${2:-$1}"
+    local details="${3:-}"
+    if [[ -n "$details" ]]; then
+        printf '{"ok":false,"error":"%s","code":"%s","details":"%s"}\n' "$message" "$code" "$details" >&2
+    else
+        printf '{"ok":false,"error":"%s","code":"%s"}\n' "$message" "$code" >&2
+    fi
+    return 1
+}
+
+# ============================================================================
+# Core XML Functions
+# ============================================================================
+
+# xml-detect-tools: Detect available XML tools
+# Usage: xml-detect-tools
+# Returns: {"ok":true,"result":{"xmllint":true,"xmlstarlet":false,...}}
+xml-detect-tools() {
+    xml_json_ok "{\"xmllint\":$XMLLINT_AVAILABLE,\"xmlstarlet\":$XMLSTARLET_AVAILABLE,\"xsltproc\":$XSLTPROC_AVAILABLE}"
+}
+
+# xml-validate: Validate XML against XSD schema using xmllint
+# Usage: xml-validate <xml_file> <xsd_file>
+# Returns: {"ok":true,"result":{"valid":true,"errors":[]}} or error
+xml-validate() {
+    local xml_file="${1:-}"
+    local xsd_file="${2:-}"
+
+    # Validate arguments
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -z "$xsd_file" ]] && { xml_json_err "MISSING_ARG" "Missing XSD schema file argument"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+    [[ -f "$xsd_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XSD schema file not found: $xsd_file"; return 1; }
+
+    # Check for xmllint
+    if [[ "$XMLLINT_AVAILABLE" != "true" ]]; then
+        xml_json_err "TOOL_NOT_AVAILABLE" "xmllint not available. Install libxml2 utilities."
+        return 1
+    fi
+
+    # Validate XML against XSD (with XXE protection)
+    local errors
+    errors=$(xmllint --nonet --noent --noout --schema "$xsd_file" "$xml_file" 2>&1) && {
+        xml_json_ok '{"valid":true,"errors":[]}'
+        return 0
+    } || {
+        # Escape errors for JSON
+        local escaped_errors
+        escaped_errors=$(echo "$errors" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\t/\\t/g' | tr '\n' ' ')
+        xml_json_ok "{\"valid\":false,\"errors\":[\"$escaped_errors\"]}"
+        return 0
+    }
+}
+
+# xml-well-formed: Check if XML is well-formed (no schema validation)
+# Usage: xml-well-formed <xml_file>
+# Returns: {"ok":true,"result":{"well_formed":true}} or error
+xml-well-formed() {
+    local xml_file="${1:-}"
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    if [[ "$XMLLINT_AVAILABLE" != "true" ]]; then
+        xml_json_err "TOOL_NOT_AVAILABLE" "xmllint not available. Install libxml2 utilities."
+        return 1
+    fi
+
+    # Check well-formedness with XXE protection
+    if xmllint --nonet --noent --noout "$xml_file" 2>/dev/null; then
+        xml_json_ok '{"well_formed":true}'
+        return 0
+    else
+        xml_json_ok '{"well_formed":false}'
+        return 0
+    fi
+}
+
+# xml-format: Pretty-print XML with proper indentation
+# Usage: xml-format <xml_file> [output_file]
+# Returns: {"ok":true,"result":{"formatted":true,"output":"..."}} or writes to file
+xml-format() {
+    local xml_file="${1:-}"
+    local output_file="${2:-}"
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    if [[ "$XMLLINT_AVAILABLE" != "true" ]]; then
+        xml_json_err "TOOL_NOT_AVAILABLE" "xmllint not available. Install libxml2 utilities."
+        return 1
+    fi
+
+    local formatted
+    formatted=$(xmllint --nonet --noent --format "$xml_file" 2>/dev/null) || {
+        xml_json_err "PARSE_ERROR" "Failed to parse XML file"
+        return 1
+    }
+
+    if [[ -n "$output_file" ]]; then
+        echo "$formatted" > "$output_file"
+        xml_json_ok "{\"formatted\":true,\"path\":\"$output_file\"}"
+    else
+        # Escape for JSON
+        local escaped
+        escaped=$(echo "$formatted" | sed 's/\\/\\\\/g; s/"/\\"/g' | tr '\n' ' ')
+        xml_json_ok "{\"formatted\":true,\"output\":\"$escaped\"}"
+    fi
+}
+
+# xml-escape: Escape special XML characters
+# Usage: xml-escape <text>
+# Returns: Escaped text (not JSON - direct output)
+xml-escape() {
+    local text="${1:-}"
+    # Escape &, <, >, ", '
+    echo "$text" | sed 's/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g; s/"/\&quot;/g; s/'"'"'/\&apos;/g'
+}
+
+# xml-unescape: Unescape XML entities
+# Usage: xml-unescape <text>
+# Returns: Unescaped text (not JSON - direct output)
+xml-unescape() {
+    local text="${1:-}"
+    # Unescape XML entities
+    echo "$text" | sed 's/&amp;/\&/g; s/&lt;/</g; s/&gt;/>/g; s/&quot;/"/g; s/&apos;/'"'"'/g'
+}
+
+# xml-escape-content: Escape content for XML CDATA or text nodes
+# Internal helper for consistent escaping
+_xml_escape_content() {
+    local content="${1:-}"
+    # Basic XML escaping for text content
+    echo "$content" | sed 's/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g'
+}
+
+# Export functions for use by other modules
+export -f xml_json_ok xml_json_err
+export -f xml-detect-tools xml-validate xml-well-formed xml-format
+export -f xml-escape xml-unescape _xml_escape_content
+export XMLLINT_AVAILABLE XMLSTARLET_AVAILABLE XSLTPROC_AVAILABLE