aether-colony 5.2.1 → 5.3.1

package/.aether/utils/clash-detect.sh

@@ -0,0 +1,239 @@
+#!/bin/bash
+# Clash detection utility -- detects file conflicts across git worktrees.
+#
+# When multiple agents work in parallel worktrees, they could accidentally
+# edit the same file from different worktrees. This script checks for that.
+#
+# Usage: clash-detect --file <path> [--worktree <path>]
+# Returns JSON: {ok:true, result:{conflict:false}} or
+#               {ok:true, result:{conflict:true, conflicting_worktrees:[...]}}
+#
+# Environment:
+#   AETHER_ROOT  - repo root (auto-detected if not set)
+#   WORKTREE_DIR - current worktree path (to exclude self from checks)
+#
+# When sourced by aether-utils.sh, provides _clash_detect function.
+# When run directly, executes _clash_detect with provided arguments.
+
+# Only set strict mode when run directly (not sourced)
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    set -uo pipefail
+fi
+
+# Set AETHER_ROOT if not already set (e.g., when sourced)
+: "${AETHER_ROOT:=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+
+# Fallback error constant for standalone execution (when not sourced by aether-utils.sh)
+: "${E_VALIDATION_FAILED:=E_VALIDATION_FAILED}"
+
+# Allowlist of path patterns that bypass clash detection (branch-local state)
+# These files live in .aether/data/ and are unique per worktree/branch
+_CLASH_ALLOWLIST=(
+    ".aether/data/"
+)
+
+# Check if a file path matches the allowlist
+_clash_is_allowlisted() {
+    local file="$1"
+    for pattern in "${_CLASH_ALLOWLIST[@]}"; do
+        if [[ "$file" == "$pattern"* ]]; then
+            return 0
+        fi
+    done
+    return 1
+}
+
+# Normalize a path for comparison on macOS (handles /var vs /private/var)
+_clash_normalize_path() {
+    local p="$1"
+    if [[ -z "$p" ]]; then
+        echo ""
+        return
+    fi
+    if command -v realpath >/dev/null 2>&1; then
+        realpath "$p" 2>/dev/null && return
+    fi
+    (cd "$p" 2>/dev/null && pwd) || echo "$p"
+}
+
+# JSON output helpers (standalone, for direct execution mode)
+_clash_json_ok() {
+    echo "{\"ok\":true,\"result\":$1}"
+}
+
+_clash_json_err() {
+    echo "{\"ok\":false,\"error\":$1}" >&2
+    exit 1
+}
+
+# Bridge: use aether-utils JSON helpers when sourced, standalone when direct
+_cok() {
+    if type json_ok &>/dev/null; then
+        json_ok "$1"
+    else
+        _clash_json_ok "$1"
+    fi
+}
+
+_cerr() {
+    if type json_err &>/dev/null; then
+        json_err "${2:-$E_UNKNOWN}" "$1"
+    else
+        _clash_json_err "\"$1\""
+    fi
+}
+
+# Main clash detection logic
+_clash_detect() {
+    local file=""
+    local worktree="${WORKTREE_DIR:-}"
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --file) file="${2:-}"; shift 2 ;;
+            --worktree) worktree="${2:-}"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    if [[ -z "$file" ]]; then
+        _cerr "Usage: clash-detect --file <path> [--worktree <path>]" "$E_VALIDATION_FAILED"
+    fi
+
+    # Allowlisted files never clash (branch-local state)
+    if _clash_is_allowlisted "$file"; then
+        _cok '{"conflict":false}'
+        return
+    fi
+
+    # Verify we're in a git repo
+    if ! git -C "$AETHER_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+        _cok '{"conflict":false}'
+        return
+    fi
+
+    # Normalize the current worktree path for comparison
+    if [[ -n "$worktree" ]]; then
+        worktree="$(_clash_normalize_path "$worktree")" || worktree=""
+    fi
+
+    # Enumerate all worktrees
+    local conflicting=()
+    while IFS= read -r line; do
+        local wt_path
+        wt_path=$(echo "$line" | awk '{print $1}')
+        [[ -z "$wt_path" ]] && continue
+
+        local abs_wt_path
+        abs_wt_path="$(_clash_normalize_path "$wt_path")" || continue
+
+        # Skip if this is the current worktree (self-check)
+        if [[ -n "$worktree" && "$abs_wt_path" == "$worktree" ]]; then
+            continue
+        fi
+
+        # Check if this worktree has uncommitted changes to the target file
+        local file_status
+        file_status=$(git -C "$abs_wt_path" status --porcelain -- "$file" 2>/dev/null) || continue
+
+        if [[ -n "$file_status" ]]; then
+            local branch_name
+            branch_name=$(git -C "$abs_wt_path" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+            conflicting+=("\"$branch_name\"")
+        fi
+    done < <(git -C "$AETHER_ROOT" worktree list 2>/dev/null | tail -n +2)
+
+    if [[ ${#conflicting[@]} -eq 0 ]]; then
+        _cok '{"conflict":false}'
+    else
+        local conflict_list
+        conflict_list=$(printf '%s,' "${conflicting[@]}")
+        conflict_list="[${conflict_list%,}]"
+        _cok "{\"conflict\":true,\"conflicting_worktrees\":$conflict_list}"
+    fi
+}
+
+# _clash_setup
+# Install or uninstall the clash detection PreToolUse hook.
+#
+# Usage: clash-setup [--install] [--uninstall]
+# Returns JSON: {ok:true, result:{hook_installed:true/false}}
+#
+# Environment:
+#   CLASH_SETTINGS_PATH - path to settings.json (default: .claude/settings.json)
+_clash_setup() {
+    local action=""
+    local settings_path="${CLASH_SETTINGS_PATH:-$AETHER_ROOT/.claude/settings.json}"
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --install)   action="install"; shift ;;
+            --uninstall) action="uninstall"; shift ;;
+            *) shift ;;
+        esac
+    done
+
+    if [[ -z "$action" ]]; then
+        _cerr "Usage: clash-setup [--install] [--uninstall]" "$E_VALIDATION_FAILED"
+    fi
+
+    # Ensure settings file exists
+    if [[ ! -f "$settings_path" ]]; then
+        echo '{}' > "$settings_path" 2>/dev/null || {
+            _cerr "Cannot create settings file at $settings_path" "$E_FILE_NOT_FOUND"
+        }
+    fi
+
+    # Read current settings
+    local settings
+    settings=$(cat "$settings_path" 2>/dev/null) || settings='{}'
+
+    local hook_command='node .aether/utils/hooks/clash-pre-tool-use.js'
+    local hook_entry="{\"type\":\"command\",\"command\":\"$hook_command\",\"timeout\":5}"
+
+    if [[ "$action" == "install" ]]; then
+        # Check if hook already exists in PreToolUse
+        if echo "$settings" | jq -e '.hooks.PreToolUse[]?.hooks[]?.command' 2>/dev/null \
+            | grep -q "clash-pre-tool-use"; then
+            # Already installed
+            _cok '{"hook_installed":true}'
+            return
+        fi
+
+        # Add the hook to PreToolUse array
+        settings=$(echo "$settings" | jq --arg entry "$hook_entry" '
+            if .hooks.PreToolUse then
+                .hooks.PreToolUse += [{"matcher": "Edit|Write", "hooks": [($entry | fromjson)]}]
+            else
+                .hooks.PreToolUse = [{"matcher": "Edit|Write", "hooks": [($entry | fromjson)]}]
+            end
+        ' 2>/dev/null)
+
+        if [[ $? -ne 0 ]] || [[ -z "$settings" ]]; then
+            _cerr "Failed to update settings file" "$E_UNKNOWN"
+        fi
+
+        echo "$settings" > "$settings_path"
+
+        _cok '{"hook_installed":true}'
+
+    elif [[ "$action" == "uninstall" ]]; then
+        # Remove the hook from PreToolUse
+        settings=$(echo "$settings" | jq '
+            if .hooks.PreToolUse then
+                .hooks.PreToolUse = [.hooks.PreToolUse[] |
+                    select(.hooks[]?.command | . != "node .aether/utils/hooks/clash-pre-tool-use.js")
+                ]
+            end
+        ' 2>/dev/null)
+
+        echo "$settings" > "$settings_path"
+
+        _cok '{"hook_installed":false}'
+    fi
+}
+
+# Run if executed directly (not sourced)
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    _clash_detect "$@"
+fi

package/.aether/utils/hooks/clash-pre-tool-use.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// Clash Detection PreToolUse Hook
+//
+// Runs before Edit/Write tool calls in Claude Code.
+// Checks if any other active git worktree has uncommitted changes to the
+// same file, preventing agents from silently overwriting each other's work.
+//
+// Exit codes:
+//   0 - Allow the operation
+//   2 - Block the operation (conflict detected)
+//
+// Design principle: fail-open. If the hook errors for any reason,
+// the operation is allowed. The goal is safety guidance, not blocking work.
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+// Files that are branch-local state and never clash across worktrees
+const ALLOWLIST = [
+  '.aether/data/',
+];
+
+// Timeout for clash-detect subprocess (ms)
+const DETECT_TIMEOUT = 5000;
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const toolName = data.tool_name;
+
+    // Only check Edit and Write operations
+    if (toolName !== 'Edit' && toolName !== 'Write') {
+      process.exit(0);
+    }
+
+    // Extract file path
+    const filePath = data.tool_input?.file_path || '';
+    if (!filePath) {
+      process.exit(0);
+    }
+
+    // Check allowlist (branch-local state files never clash)
+    if (ALLOWLIST.some(pattern => filePath.includes(pattern))) {
+      process.exit(0);
+    }
+
+    // Find the clash-detect script
+    // It lives at .aether/utils/clash-detect.sh relative to the repo root
+    const cwd = data.cwd || process.cwd();
+    const repoClashDetect = path.join(cwd, '.aether', 'utils', 'clash-detect.sh');
+
+    // Extract just the relative file path for clash-detect
+    const relPath = path.relative(cwd, filePath);
+
+    // Determine which clash-detect to use: repo-local or PATH
+    const fs = require('fs');
+    const clashDetect = fs.existsSync(repoClashDetect) ? repoClashDetect : 'clash-detect';
+
+    // Run clash-detect
+    try {
+      const cmd = clashDetect === 'clash-detect'
+        ? `clash-detect --file "${relPath}"`
+        : `bash "${clashDetect}" --file "${relPath}"`;
+      const result = execSync(cmd, {
+        timeout: DETECT_TIMEOUT,
+        encoding: 'utf8',
+        cwd: cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+
+      const parsed = JSON.parse(result.trim());
+      if (parsed.ok && parsed.result?.conflict) {
+        const worktrees = (parsed.result.conflicting_worktrees || []).join(', ');
+        const output = {
+          decision: 'block',
+          reason: `File "${relPath}" has uncommitted changes in worktree(s): ${worktrees}. ` +
+            'Coordinate with the other agent or wait for their changes to be committed.',
+        };
+        process.stderr.write(JSON.stringify(output) + '\n');
+        process.exit(2);
+      }
+
+      // No conflict -- allow
+      process.exit(0);
+    } catch (err) {
+      // Fail-open: if clash-detect fails, allow the operation
+      // This prevents the hook from blocking all work when something goes wrong
+      process.exit(0);
+    }
+  } catch (e) {
+    // Fail-open on any parsing or unexpected error
+    process.exit(0);
+  }
+});

package/.aether/utils/merge-driver-lockfile.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Merge Driver: npm lockfile auto-merge
+#
+# Resolves package-lock.json merge conflicts by keeping "ours" (the branch
+# being merged into). Lockfiles are deterministic outputs of package.json,
+# so the correct resolution is always to regenerate from the target branch's
+# package.json, which effectively means keeping "ours".
+#
+# Usage: merge-driver-lockfile.sh %O %A %B
+#   %O = ancestor (base version)
+#   %A = ours (current branch, the version we want to keep)
+#   %B = theirs (incoming branch)
+#
+# Git merge driver contract:
+#   Exit 0 = conflict resolved (merge continues)
+#   Exit non-zero = conflict unresolved
+#
+# This driver is configured via:
+#   git config merge.lockfile.name "npm lockfile auto-merge"
+#   git config merge.lockfile.driver "bash .aether/utils/merge-driver-lockfile.sh %O %A %B"
+
+set -euo pipefail
+
+ANCESTOR="${1:-}"
+OURS="${2:-}"
+THEIRS="${3:-}"
+
+# Strategy: keep "ours" unchanged.
+# The "ours" file already contains the correct content on disk.
+# We do nothing -- git considers the file resolved when we exit 0.
+#
+# Log for debugging (to stderr so it does not pollute merge output)
+echo "[aether] merge-driver: resolved package-lock.json conflict (kept ours)" >&2
+
+exit 0