aether-colony 3.1.17 → 5.1.0

package/runtime/utils/chamber-utils.sh

@@ -1,285 +0,0 @@
-#!/bin/bash
-# Aether Chamber Utilities
-# Manages entombed colonies — directory management, manifest generation, integrity verification
-#
-# Usage:
-#   source .aether/utils/chamber-utils.sh
-#   chamber_create <chamber_dir> <state_file> <goal> <phases_completed> <total_phases> <milestone> <version> <decisions_json> <learnings_json>
-#   chamber_verify <chamber_dir>
-#   chamber_list <chambers_root>
-#   chamber_sanitize_goal <goal>
-
-set -euo pipefail
-
-# Initialize lock state before sourcing (file-lock.sh trap needs these)
-LOCK_ACQUIRED=${LOCK_ACQUIRED:-false}
-CURRENT_LOCK=${CURRENT_LOCK:-""}
-
-# Get script directory for sourcing (preserve parent SCRIPT_DIR if set)
-__chamber_utils_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-AETHER_ROOT="$(cd "$__chamber_utils_dir/../.." && pwd 2>/dev/null || echo "$__chamber_utils_dir/../..")"
-
-# Use parent SCRIPT_DIR if available, otherwise use local
-SCRIPT_DIR="${SCRIPT_DIR:-$__chamber_utils_dir}"
-
-# Source atomic-write for safe file operations
-[[ -f "$SCRIPT_DIR/atomic-write.sh" ]] && source "$SCRIPT_DIR/atomic-write.sh"
-
-# --- JSON output helpers ---
-json_ok() { printf '{"ok":true,"result":%s}\n' "$1"; }
-json_err() {
-  local message="${2:-$1}"
-  printf '{"ok":false,"error":"%s"}\n' "$message" >&2
-  exit 1
-}
-
-# --- Chamber Functions ---
-
-# Sanitize goal string for use in directory names
-# Converts to lowercase, replaces spaces/special chars with hyphens, removes non-alphanumeric
-chamber_sanitize_goal() {
-  local goal="$1"
-  # Convert to lowercase, replace spaces and special chars with hyphens
-  local sanitized=$(echo "$goal" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '-')
-  # Remove leading/trailing hyphens
-  sanitized=$(echo "$sanitized" | sed 's/^-//;s/-$//')
-  # Limit length to avoid overly long directory names
-  if [[ ${#sanitized} -gt 50 ]]; then
-    sanitized="${sanitized:0:50}"
-  fi
-  echo "$sanitized"
-}
-
-# Compute SHA256 hash of a file
-# Returns hash string or empty on error
-chamber_compute_hash() {
-  local file_path="$1"
-  if [[ ! -f "$file_path" ]]; then
-    echo ""
-    return 1
-  fi
-
-  # Try sha256sum first (Linux), then shasum -a 256 (macOS)
-  if command -v sha256sum >/dev/null 2>&1; then
-    sha256sum "$file_path" | cut -d' ' -f1
-  elif command -v shasum >/dev/null 2>&1; then
-    shasum -a 256 "$file_path" | cut -d' ' -f1
-  else
-    echo ""
-    return 1
-  fi
-}
-
-# Create a new chamber (entomb a colony)
-# Arguments:
-#   chamber_dir: Directory to create for this chamber
-#   state_file: Path to COLONY_STATE.json to archive
-#   goal: Colony goal string
-#   phases_completed: Number of completed phases
-#   total_phases: Total number of phases
-#   milestone: Milestone name
-#   version: Version string
-#   decisions_json: JSON array of decisions
-#   learnings_json: JSON array of learnings
-chamber_create() {
-  local chamber_dir="$1"
-  local state_file="$2"
-  local goal="$3"
-  local phases_completed="$4"
-  local total_phases="$5"
-  local milestone="$6"
-  local version="$7"
-  local decisions_json="$8"
-  local learnings_json="$9"
-
-  # Validate inputs
-  [[ -z "$chamber_dir" ]] && json_err "chamber_dir is required"
-  [[ -z "$state_file" ]] && json_err "state_file is required"
-  [[ ! -f "$state_file" ]] && json_err "State file not found: $state_file"
-
-  # Create chamber directory
-  mkdir -p "$chamber_dir" || json_err "Failed to create chamber directory: $chamber_dir"
-
-  # Copy state file to chamber
-  local target_state="$chamber_dir/COLONY_STATE.json"
-  cp "$state_file" "$target_state" || json_err "Failed to copy state file"
-
-  # Compute hash of the copied state file
-  local state_hash=$(chamber_compute_hash "$target_state")
-  [[ -z "$state_hash" ]] && json_err "Failed to compute hash of state file"
-
-  # Generate timestamp
-  local entombed_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-
-  # Create manifest.json
-  local manifest_file="$chamber_dir/manifest.json"
-  local manifest_content=$(cat <<EOF
-{
-  "entombed_at": "$entombed_at",
-  "goal": $(echo "$goal" | jq -Rs '.[:-1]'),
-  "phases_completed": $phases_completed,
-  "total_phases": $total_phases,
-  "milestone": $(echo "$milestone" | jq -Rs '.[:-1]'),
-  "version": $(echo "$version" | jq -Rs '.[:-1]'),
-  "decisions": $decisions_json,
-  "learnings": $learnings_json,
-  "files": {
-    "COLONY_STATE.json": "$state_hash"
-  }
-}
-EOF
-)
-
-  # Write manifest atomically if atomic_write is available, otherwise direct
-  if type atomic_write &>/dev/null; then
-    atomic_write "$manifest_file" "$manifest_content" || json_err "Failed to write manifest"
-  else
-    echo "$manifest_content" > "$manifest_file" || json_err "Failed to write manifest"
-  fi
-
-  # Verify the manifest was written correctly
-  if [[ ! -f "$manifest_file" ]]; then
-    json_err "Manifest file not created"
-  fi
-
-  # Return success with chamber info
-  local result=$(cat <<EOF
-{
-  "chamber_dir": "$chamber_dir",
-  "manifest": {
-    "entombed_at": "$entombed_at",
-    "goal": $(echo "$goal" | jq -Rs '.[:-1]'),
-    "phases_completed": $phases_completed,
-    "total_phases": $total_phases,
-    "milestone": $(echo "$milestone" | jq -Rs '.[:-1]'),
-    "version": $(echo "$version" | jq -Rs '.[:-1]')
-  }
-}
-EOF
-)
-
-  json_ok "$result"
-}
-
-# Verify chamber integrity
-# Arguments:
-#   chamber_dir: Directory containing the chamber
-chamber_verify() {
-  local chamber_dir="$1"
-
-  # Validate inputs
-  [[ -z "$chamber_dir" ]] && json_err "chamber_dir is required"
-  [[ ! -d "$chamber_dir" ]] && json_err "Chamber directory not found: $chamber_dir"
-
-  local manifest_file="$chamber_dir/manifest.json"
-  local state_file="$chamber_dir/COLONY_STATE.json"
-
-  # Check required files exist
-  [[ ! -f "$manifest_file" ]] && json_err "Manifest not found in chamber"
-  [[ ! -f "$state_file" ]] && json_err "COLONY_STATE.json not found in chamber"
-
-  # Read stored hash from manifest
-  local stored_hash=$(jq -r '.files["COLONY_STATE.json"] // empty' "$manifest_file" 2>/dev/null)
-  [[ -z "$stored_hash" ]] && json_err "No hash found in manifest for COLONY_STATE.json"
-
-  # Compute current hash
-  local current_hash=$(chamber_compute_hash "$state_file")
-  [[ -z "$current_hash" ]] && json_err "Failed to compute hash of state file"
-
-  # Compare hashes
-  if [[ "$stored_hash" != "$current_hash" ]]; then
-    local result=$(cat <<EOF
-{
-  "verified": false,
-  "chamber_dir": "$chamber_dir",
-  "error": "hash mismatch",
-  "stored_hash": "$stored_hash",
-  "current_hash": "$current_hash"
-}
-EOF
-)
-    json_ok "$result"
-    return 0
-  fi
-
-  # Verification passed
-  local result=$(cat <<EOF
-{
-  "verified": true,
-  "chamber_dir": "$chamber_dir",
-  "hash": "$current_hash"
-}
-EOF
-)
-
-  json_ok "$result"
-}
-
-# List all chambers
-# Arguments:
-#   chambers_root: Root directory containing chambers (default: .aether/chambers/)
-chamber_list() {
-  local chambers_root="${1:-$AETHER_ROOT/.aether/chambers}"
-
-  # Default to current directory's chambers if AETHER_ROOT not set
-  if [[ -z "$chambers_root" || "$chambers_root" == "/.aether/chambers" ]]; then
-    chambers_root="$(pwd)/.aether/chambers"
-  fi
-
-  # Check if chambers directory exists
-  if [[ ! -d "$chambers_root" ]]; then
-    json_ok "[]"
-    return 0
-  fi
-
-  # Build array of chamber summaries
-  local chambers="["
-  local first=true
-
-  # Find all directories in chambers_root
-  while IFS= read -r -d '' chamber_dir; do
-    local chamber_name=$(basename "$chamber_dir")
-    local manifest_file="$chamber_dir/manifest.json"
-
-    # Skip if no manifest
-    [[ ! -f "$manifest_file" ]] && continue
-
-    # Read manifest fields
-    local goal=$(jq -r '.goal // "unknown"' "$manifest_file" 2>/dev/null)
-    local milestone=$(jq -r '.milestone // "unknown"' "$manifest_file" 2>/dev/null)
-    local phases_completed=$(jq -r '.phases_completed // 0' "$manifest_file" 2>/dev/null)
-    local entombed_at=$(jq -r '.entombed_at // ""' "$manifest_file" 2>/dev/null)
-
-    # Escape for JSON
-    goal=$(echo "$goal" | jq -Rs '.[:-1]')
-    milestone=$(echo "$milestone" | jq -Rs '.[:-1]')
-
-    # Add comma if not first
-    if [[ "$first" == "true" ]]; then
-      first=false
-    else
-      chambers+=","
-    fi
-
-    chambers+=$(cat <<EOF
-{
-  "name": $(echo "$chamber_name" | jq -Rs '.[:-1]'),
-  "goal": $goal,
-  "milestone": $milestone,
-  "phases_completed": $phases_completed,
-  "entombed_at": $(echo "$entombed_at" | jq -Rs '.[:-1]')
-}
-EOF
-)
-  done < <(find "$chambers_root" -mindepth 1 -maxdepth 1 -type d -print0 2>/dev/null || true)
-
-  chambers+="]"
-
-  # Sort by entombed_at descending using jq
-  local sorted=$(echo "$chambers" | jq 'sort_by(.entombed_at) | reverse')
-
-  json_ok "$sorted"
-}
-
-# Export functions for use in other scripts
-export -f chamber_sanitize_goal chamber_compute_hash chamber_create chamber_verify chamber_list

package/runtime/utils/file-lock.sh

@@ -1,122 +0,0 @@
-#!/bin/bash
-# Aether File Lock Utility
-# Implements file locking for concurrent colony access prevention
-#
-# Usage:
-#   source .aether/utils/file-lock.sh
-#   acquire_lock /path/to/file.lock
-#   # ... critical section ...
-#   release_lock /path/to/file.lock
-
-# Aether root detection - use git root if available, otherwise use current directory
-if git rev-parse --show-toplevel >/dev/null 2>&1; then
-    AETHER_ROOT="$(git rev-parse --show-toplevel)"
-else
-    AETHER_ROOT="$(pwd)"
-fi
-
-LOCK_DIR="$AETHER_ROOT/.aether/locks"
-LOCK_TIMEOUT=300  # 5 minutes max lock time
-LOCK_RETRY_INTERVAL=0.5  # Wait 500ms between retries
-LOCK_MAX_RETRIES=100  # Total 50 seconds max wait
-
-# Create lock directory if it doesn't exist
-mkdir -p "$LOCK_DIR"
-
-# Acquire a file lock using flock
-# Arguments: file_path (the resource to lock)
-# Returns: 0 on success, 1 on failure
-# Globals: LOCK_ACQUIRED (set to true when lock acquired)
-acquire_lock() {
-    local file_path="$1"
-    local lock_file="${LOCK_DIR}/$(basename "$file_path").lock"
-    local lock_pid_file="${lock_file}.pid"
-
-    # Check if lock file exists and is stale
-    if [ -f "$lock_file" ]; then
-        local lock_pid=$(cat "$lock_pid_file" 2>/dev/null || echo "")
-        if [ -n "$lock_pid" ]; then
-            # Check if process is still running
-            if ! kill -0 "$lock_pid" 2>/dev/null; then
-                echo "Lock stale (PID $lock_pid not running), cleaning up..."
-                rm -f "$lock_file" "$lock_pid_file"
-            fi
-        fi
-    fi
-
-    # Try to acquire lock with timeout
-    local retry_count=0
-    while [ $retry_count -lt $LOCK_MAX_RETRIES ]; do
-        # Try to create lock file atomically
-        if (set -o noclobber; echo $$ > "$lock_file") 2>/dev/null; then
-            echo $$ > "$lock_pid_file"
-            export LOCK_ACQUIRED=true
-            export CURRENT_LOCK="$lock_file"
-            return 0
-        fi
-
-        retry_count=$((retry_count + 1))
-        if [ $retry_count -lt $LOCK_MAX_RETRIES ]; then
-            sleep $LOCK_RETRY_INTERVAL
-        fi
-    done
-
-    echo "Failed to acquire lock for $file_path after $LOCK_MAX_RETRIES attempts"
-    return 1
-}
-
-# Release a file lock
-# Arguments: None (uses CURRENT_LOCK from acquire_lock)
-release_lock() {
-    if [ "$LOCK_ACQUIRED" = "true" ] && [ -n "$CURRENT_LOCK" ]; then
-        rm -f "$CURRENT_LOCK" "${CURRENT_LOCK}.pid"
-        export LOCK_ACQUIRED=false
-        export CURRENT_LOCK=""
-        return 0
-    fi
-    return 1
-}
-
-# Cleanup function for script exit
-cleanup_locks() {
-    if [ "$LOCK_ACQUIRED" = "true" ]; then
-        release_lock
-    fi
-}
-
-# Register cleanup on exit
-trap cleanup_locks EXIT TERM INT
-
-# Check if a file is currently locked
-is_locked() {
-    local file_path="$1"
-    local lock_file="${LOCK_DIR}/$(basename "$file_path").lock"
-    [ -f "$lock_file" ]
-}
-
-# Get PID of process holding lock
-get_lock_holder() {
-    local file_path="$1"
-    local lock_file="${LOCK_DIR}/$(basename "$file_path").lock.pid"
-    cat "$lock_file" 2>/dev/null || echo ""
-}
-
-# Wait for lock to be released
-wait_for_lock() {
-    local file_path="$1"
-    local max_wait=${2:-$LOCK_TIMEOUT}
-    local waited=0
-
-    while is_locked "$file_path" && [ $waited -lt $max_wait ]; do
-        sleep 1
-        waited=$((waited + 1))
-    done
-
-    if [ $waited -ge $max_wait ]; then
-        return 1
-    fi
-    return 0
-}
-
-# Export functions for use in other scripts
-export -f acquire_lock release_lock is_locked get_lock_holder wait_for_lock cleanup_locks