aether-colony 1.1.0

package/.aether/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

package/.aether/utils/xml-query.sh

@@ -0,0 +1,201 @@
+#!/bin/bash
+# XML Query Utilities
+# XPath queries with xmlstarlet and xmllint fallback
+#
+# Usage: source .aether/utils/xml-query.sh
+#        xml-query <xml_file> <xpath_expression>
+#        xml-query-attr <xml_file> <xpath_expression>
+#        xml-query-text <xml_file> <element_name>
+#        xml-query-count <xml_file> <xpath_expression>
+
+set -euo pipefail
+
+# Source xml-core.sh for JSON helpers and tool detection
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/xml-core.sh"
+
+# ============================================================================
+# XPath Query Functions
+# ============================================================================
+
+# xml-query: Execute XPath query against XML file
+# Usage: xml-query <xml_file> <xpath_expression>
+# Returns: {"ok":true,"result":{"matches":["value1","value2",...]}}
+xml-query() {
+    local xml_file="${1:-}"
+    local xpath="${2:-}"
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -z "$xpath" ]] && { xml_json_err "MISSING_ARG" "Missing XPath expression"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    local results=""
+
+    # Prefer xmlstarlet for full XPath support
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        results=$(xmlstarlet sel -t -v "$xpath" "$xml_file" 2>/dev/null | tr '\n' '|')
+        # Remove trailing pipe
+        results="${results%|}"
+    elif [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        # xmllint has limited XPath but works for basic queries
+        # Note: xmllint --xpath returns the text content of matched nodes
+        results=$(xmllint --nonet --noent --xpath "$xpath" "$xml_file" 2>/dev/null | \
+                  sed 's/<[^>]*>//g' | tr '\n' '|' | sed 's/|$//')
+    else
+        xml_json_err "TOOL_NOT_AVAILABLE" "No XPath-capable tool available (install xmlstarlet or libxml2)"
+        return 1
+    fi
+
+    # Build JSON array from pipe-separated results
+    if [[ -n "$results" ]]; then
+        local json_array="["
+        local first=true
+        IFS='|' read -ra matches <<< "$results"
+        for match in "${matches[@]}"; do
+            # Trim whitespace and escape for JSON
+            match=$(echo "$match" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+            match=$(echo "$match" | sed 's/\\/\\\\/g; s/"/\\"/g')
+            if [[ "$first" == "true" ]]; then
+                first=false
+                json_array="$json_array\"$match\""
+            else
+                json_array="$json_array,\"$match\""
+            fi
+        done
+        json_array="$json_array]"
+        xml_json_ok "{\"matches\":$json_array}"
+    else
+        xml_json_ok '{"matches":[]}'
+    fi
+}
+
+# xml-query-attr: Extract attribute values using XPath
+# Usage: xml-query-attr <xml_file> <element_xpath> <attribute_name>
+# Returns: {"ok":true,"result":{"attribute":"name","values":["val1","val2"]}}
+xml-query-attr() {
+    local xml_file="${1:-}"
+    local element_xpath="${2:-}"
+    local attr_name="${3:-}"
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -z "$element_xpath" ]] && { xml_json_err "MISSING_ARG" "Missing element XPath"; return 1; }
+    [[ -z "$attr_name" ]] && { xml_json_err "MISSING_ARG" "Missing attribute name"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    local full_xpath="${element_xpath}/@${attr_name}"
+    local results=""
+
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        results=$(xmlstarlet sel -t -v "$full_xpath" "$xml_file" 2>/dev/null | tr '\n' '|')
+        results="${results%|}"
+    elif [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        # xmllint can extract attributes with //@attrname syntax
+        results=$(xmllint --nonet --noent --xpath "$full_xpath" "$xml_file" 2>/dev/null | tr '\n' '|')
+        results="${results%|}"
+    else
+        xml_json_err "TOOL_NOT_AVAILABLE" "No XPath-capable tool available"
+        return 1
+    fi
+
+    # Build JSON array
+    if [[ -n "$results" ]]; then
+        local json_array="["
+        local first=true
+        IFS='|' read -ra values <<< "$results"
+        for val in "${values[@]}"; do
+            val=$(echo "$val" | sed 's/\\/\\\\/g; s/"/\\"/g')
+            if [[ "$first" == "true" ]]; then
+                first=false
+                json_array="$json_array\"$val\""
+            else
+                json_array="$json_array,\"$val\""
+            fi
+        done
+        json_array="$json_array]"
+        xml_json_ok "{\"attribute\":\"$attr_name\",\"values\":$json_array}"
+    else
+        xml_json_ok "{\"attribute\":\"$attr_name\",\"values\":[]}"
+    fi
+}
+
+# xml-query-text: Extract text content of elements
+# Usage: xml-query-text <xml_file> <element_name>
+# Returns: {"ok":true,"result":{"element":"name","text":["text1","text2"]}}
+xml-query-text() {
+    local xml_file="${1:-}"
+    local element_name="${2:-}"
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -z "$element_name" ]] && { xml_json_err "MISSING_ARG" "Missing element name"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    local xpath="//$element_name"
+    local results=""
+
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        # Use -m to match nodes and extract text
+        results=$(xmlstarlet sel -t -m "$xpath" -v "." -n "$xml_file" 2>/dev/null | tr '\n' '|')
+        results="${results%|}"
+    elif [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        # xmllint --xpath returns text content directly for simple paths
+        results=$(xmllint --nonet --noent --xpath "$xpath" "$xml_file" 2>/dev/null | \
+                  sed 's/<[^>]*>//g' | tr '\n' '|' | sed 's/|$//')
+    else
+        xml_json_err "TOOL_NOT_AVAILABLE" "No XPath-capable tool available"
+        return 1
+    fi
+
+    if [[ -n "$results" ]]; then
+        local json_array="["
+        local first=true
+        IFS='|' read -ra texts <<< "$results"
+        for text in "${texts[@]}"; do
+            text=$(echo "$text" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+            text=$(echo "$text" | sed 's/\\/\\\\/g; s/"/\\"/g')
+            if [[ "$first" == "true" ]]; then
+                first=false
+                json_array="$json_array\"$text\""
+            else
+                json_array="$json_array,\"$text\""
+            fi
+        done
+        json_array="$json_array]"
+        xml_json_ok "{\"element\":\"$element_name\",\"text\":$json_array}"
+    else
+        xml_json_ok "{\"element\":\"$element_name\",\"text\":[]}"
+    fi
+}
+
+# xml-query-count: Count nodes matching XPath expression
+# Usage: xml-query-count <xml_file> <xpath_expression>
+# Returns: {"ok":true,"result":{"count":5}}
+xml-query-count() {
+    local xml_file="${1:-}"
+    local xpath="${2:-}"
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -z "$xpath" ]] && { xml_json_err "MISSING_ARG" "Missing XPath expression"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    local count=0
+
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        # Use count() XPath function
+        local count_result
+        count_result=$(xmlstarlet sel -t -v "count($xpath)" "$xml_file" 2>/dev/null)
+        count="${count_result:-0}"
+    elif [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        # Count matching lines (approximate for simple cases)
+        local matches
+        matches=$(xmllint --nonet --noent --xpath "$xpath" "$xml_file" 2>/dev/null | grep -c '<' || true)
+        count="${matches:-0}"
+    else
+        xml_json_err "TOOL_NOT_AVAILABLE" "No XPath-capable tool available"
+        return 1
+    fi
+
+    xml_json_ok "{\"count\":$count}"
+}
+
+# Export functions
+export -f xml-query xml-query-attr xml-query-text xml-query-count

package/.aether/utils/xml-utils.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# XML Utilities Loader
+# Sources all XML modules for backward compatibility
+#
+# IMPORTANT: This file is now a loader only. New code should source
+# individual modules directly from .aether/utils/ or .aether/exchange/
+#
+# Usage: source .aether/utils/xml-utils.sh
+#
+# Modules loaded:
+#   - xml-core.sh      : Core operations (validate, format, escape)
+#   - xml-query.sh     : XPath queries
+#   - xml-convert.sh   : JSON/XML conversion
+#   - xml-compose.sh   : XInclude composition
+#   - pheromone-xml.sh : Pheromone exchange
+#   - wisdom-xml.sh    : Queen wisdom exchange
+#   - registry-xml.sh  : Colony registry exchange
+#
+# Deprecated functions (maintained for compatibility):
+#   - pheromone-to-xml()  -> Use xml-pheromone-export()
+#   - pheromone-from-xml() -> Use xml-pheromone-import()
+#   - queen-wisdom-to-xml() -> Use xml-wisdom-export()
+#   - queen-wisdom-from-xml() -> Use xml-wisdom-import()
+
+set -euo pipefail
+
+# Determine script directory for relative sourcing
+# Handle case when sourced interactively (BASH_SOURCE[0] may be empty)
+if [[ -n "${BASH_SOURCE[0]:-}" ]]; then
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+else
+    # Fallback: derive from the sourced script's location
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+fi
+EXCHANGE_DIR="$(cd "$SCRIPT_DIR/../exchange" && pwd)"
+
+# ============================================================================
+# Load Core Modules
+# ============================================================================
+
+# Core utilities (required by other modules)
+source "$SCRIPT_DIR/xml-core.sh"
+
+# Query functions
+source "$SCRIPT_DIR/xml-query.sh"
+
+# Conversion functions
+source "$SCRIPT_DIR/xml-convert.sh"
+
+# Composition functions
+source "$SCRIPT_DIR/xml-compose.sh"
+
+# ============================================================================
+# Load Exchange Modules
+# ============================================================================
+
+# Pheromone exchange (export/import)
+source "$EXCHANGE_DIR/pheromone-xml.sh"
+
+# Queen wisdom exchange
+source "$EXCHANGE_DIR/wisdom-xml.sh"
+
+# Colony registry exchange
+source "$EXCHANGE_DIR/registry-xml.sh"
+
+# ============================================================================
+# Backward Compatibility Aliases
+# ============================================================================
+
+# Map old function names to new ones for compatibility
+pheromone-to-xml() { xml-pheromone-export "$@"; }
+pheromone-from-xml() { xml-pheromone-import "$@"; }
+queen-wisdom-to-xml() { xml-wisdom-export "$@"; }
+queen-wisdom-from-xml() { xml-wisdom-import "$@"; }
+registry-to-xml() { xml-registry-export "$@"; }
+registry-from-xml() { xml-registry-import "$@"; }
+
+# Export compatibility aliases
+export -f pheromone-to-xml pheromone-from-xml
+export -f queen-wisdom-to-xml queen-wisdom-from-xml
+export -f registry-to-xml registry-from-xml
+
+# ============================================================================
+# Module Information
+# ============================================================================
+
+# xml-utils-info: Display module information
+# Usage: xml-utils-info
+xml-utils-info() {
+    xml_json_ok '{
+        "modules": [
+            "xml-core.sh",
+            "xml-query.sh",
+            "xml-convert.sh",
+            "xml-compose.sh",
+            "pheromone-xml.sh",
+            "wisdom-xml.sh",
+            "registry-xml.sh"
+        ],
+        "note": "This loader provides backward compatibility. New code should source individual modules.",
+        "tools": {
+            "xmllint": '"$XMLLINT_AVAILABLE"',
+            "xmlstarlet": '"$XMLSTARLET_AVAILABLE"',
+            "xsltproc": '"$XSLTPROC_AVAILABLE"'
+        }
+    }'
+}
+
+export -f xml-utils-info
+