aether-colony 1.1.0

package/bin/generate-commands.sh

@@ -0,0 +1,291 @@
+#!/bin/bash
+# generate-commands.sh - Sync commands between Claude Code and OpenCode
+#
+# This script helps keep commands in sync between the two platforms.
+# Currently it provides a simple diff-based sync, with plans for full
+# YAML-based generation in the future.
+#
+# Usage:
+#   ./bin/generate-commands.sh [check|sync|diff]
+#
+# Commands:
+#   check  - Check if commands are in sync (exit 1 if not)
+#   sync   - Copy Claude Code commands to OpenCode (with tool name translation)
+#   diff   - Show differences between command sets
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+
+CLAUDE_DIR="$PROJECT_DIR/.claude/commands/ant"
+OPENCODE_DIR="$PROJECT_DIR/.opencode/commands/ant"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+log_info() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Compute SHA hash with error handling
+# Returns 0 on success, 1 on failure
+# Echoes hash on success, error message on failure
+compute_hash() {
+    local file="$1"
+
+    if [[ ! -r "$file" ]]; then
+        echo "NOT_READABLE"
+        return 1
+    fi
+
+    local hash
+    hash=$(shasum "$file" 2>/dev/null | cut -d' ' -f1)
+    if [[ -z "$hash" ]]; then
+        echo "HASH_FAILED"
+        return 1
+    fi
+
+    echo "$hash"
+    return 0
+}
+
+# Count commands in each directory
+count_commands() {
+    local dir="$1"
+    if [[ -d "$dir" ]]; then
+        find "$dir" -name "*.md" | wc -l | tr -d ' '
+    else
+        echo "0"
+    fi
+}
+
+# List command files (PLAN-006 fix #13 - warn about non-.md files)
+list_commands() {
+    local dir="$1"
+    if [[ -d "$dir" ]]; then
+        # Check for non-.md files and warn
+        local non_md_count
+        non_md_count=$(find "$dir" -type f ! -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+        if [[ "$non_md_count" -gt 0 ]]; then
+            log_warn "$non_md_count non-.md file(s) found in $dir (ignored)"
+        fi
+
+        find "$dir" -name "*.md" -exec basename {} \; | sort
+    fi
+}
+
+# Check if directories are in sync (by file count and names)
+check_sync() {
+    log_info "Checking command sync status..."
+
+    local claude_count=$(count_commands "$CLAUDE_DIR")
+    local opencode_count=$(count_commands "$OPENCODE_DIR")
+
+    echo "Claude Code commands: $claude_count"
+    echo "OpenCode commands:    $opencode_count"
+
+    # PLAN-006 fix #10 - warn about empty directories
+    if [[ "$claude_count" -eq 0 ]] && [[ "$opencode_count" -eq 0 ]]; then
+        log_warn "Both command directories are empty"
+        echo "This may indicate a misconfiguration"
+    fi
+
+    # PLAN-006 fix #11 - warn about large command counts
+    local max_commands=500
+    if [[ "$claude_count" -gt "$max_commands" ]] || [[ "$opencode_count" -gt "$max_commands" ]]; then
+        log_warn "Large number of commands ($claude_count/$opencode_count)"
+        echo "This may cause performance issues during sync checks"
+    fi
+
+    if [[ "$claude_count" != "$opencode_count" ]]; then
+        log_error "Command counts don't match!"
+        return 1
+    fi
+
+    # Check file names match
+    local claude_files=$(list_commands "$CLAUDE_DIR")
+    local opencode_files=$(list_commands "$OPENCODE_DIR")
+
+    if [[ "$claude_files" != "$opencode_files" ]]; then
+        log_error "Command file names don't match!"
+        echo ""
+        echo "Only in Claude Code:"
+        comm -23 <(echo "$claude_files") <(echo "$opencode_files") | sed 's/^/  /'
+        echo ""
+        echo "Only in OpenCode:"
+        comm -13 <(echo "$claude_files") <(echo "$opencode_files") | sed 's/^/  /'
+        return 1
+    fi
+
+    log_info "Commands are in sync ($claude_count commands)"
+    return 0
+}
+
+# Check content-level sync using checksums (Pass 2)
+# Compares each matching file pair by SHA-1 hash and reports diffs
+check_content() {
+    log_info "Checking content-level sync (checksums)..."
+
+    local drift_count=0
+    local error_count=0
+    local match_count=0
+    local drift_files=""
+    local error_files=""
+
+    # Use null delimiter for safe iteration (handles filenames with spaces)
+    while IFS= read -r -d '' claude_file; do
+        local file
+        file=$(basename "$claude_file")
+        local opencode_file="$OPENCODE_DIR/$file"
+
+        # Skip if OpenCode file doesn't exist (already caught by Pass 1)
+        if [[ ! -f "$opencode_file" ]]; then
+            continue
+        fi
+
+        # Compute hashes with error handling
+        local claude_hash opencode_hash
+        claude_hash=$(compute_hash "$claude_file")
+        if [[ $? -ne 0 ]]; then
+            log_error "Cannot hash $claude_file ($claude_hash)"
+            error_files="${error_files}  ${file} (${claude_hash})\n"
+            error_count=$((error_count + 1))
+            continue
+        fi
+
+        opencode_hash=$(compute_hash "$opencode_file")
+        if [[ $? -ne 0 ]]; then
+            log_error "Cannot hash $opencode_file ($opencode_hash)"
+            error_files="${error_files}  ${file} (${opencode_hash})\n"
+            error_count=$((error_count + 1))
+            continue
+        fi
+
+        if [[ "$claude_hash" != "$opencode_hash" ]]; then
+            drift_count=$((drift_count + 1))
+            drift_files="${drift_files}  ${file}\n"
+
+            log_warn "Content drift: $file"
+            echo "  Claude:  $claude_hash"
+            echo "  OpenCode: $opencode_hash"
+
+            # PLAN-006 fix #12 - improved diff error handling
+            echo "  ---"
+            local diff_output
+            if diff_output=$(diff -u "$claude_file" "$opencode_file" 2>&1); then
+                # Files are same (shouldn't happen if hashes differ, but handle it)
+                echo "$diff_output" | head -20
+            else
+                local diff_exit=$?
+                if [[ "$diff_output" == *"diff:"* && "$diff_output" == *"No such file"* ]]; then
+                    log_error "diff failed: $diff_output"
+                else
+                    # Normal diff output (exit 1 means files differ)
+                    echo "$diff_output" | head -20
+                fi
+            fi
+            echo "  ---"
+            echo ""
+        else
+            match_count=$((match_count + 1))
+        fi
+    done < <(find "$CLAUDE_DIR" -name "*.md" -type f -print0 2>/dev/null | sort -z)
+
+    # Report results
+    if [[ "$error_count" -gt 0 ]]; then
+        echo ""
+        log_error "Hash errors in $error_count file(s):"
+        echo -e "$error_files"
+    fi
+
+    if [[ "$drift_count" -gt 0 ]]; then
+        echo ""
+        log_warn "Content drift detected in $drift_count file(s) (non-blocking):"
+        echo -e "$drift_files"
+        # Content drift is advisory — structural sync is what matters
+    fi
+
+    if [[ "$error_count" -gt 0 ]]; then
+        return 1
+    fi
+
+    log_info "All file contents match (checksums verified: $match_count files)"
+    return 0
+}
+
+# Show diff between command sets
+show_diff() {
+    log_info "Comparing command sets..."
+
+    # Use null delimiter for safe iteration (handles filenames with spaces)
+    while IFS= read -r -d '' claude_file; do
+        local file
+        file=$(basename "$claude_file")
+        local opencode_file="$OPENCODE_DIR/$file"
+
+        if [[ ! -f "$opencode_file" ]]; then
+            log_warn "$file exists only in Claude Code"
+            continue
+        fi
+
+        # Compare file sizes as a quick check
+        local claude_size=$(wc -l < "$claude_file" | tr -d ' ')
+        local opencode_size=$(wc -l < "$opencode_file" | tr -d ' ')
+
+        if [[ "$claude_size" != "$opencode_size" ]]; then
+            echo "$file: $claude_size lines (Claude) vs $opencode_size lines (OpenCode)"
+        fi
+    done < <(find "$CLAUDE_DIR" -name "*.md" -type f -print0 2>/dev/null | sort -z)
+}
+
+# Display help
+show_help() {
+    echo "Aether Command Sync Tool"
+    echo ""
+    echo "Usage: $0 [command]"
+    echo ""
+    echo "Commands:"
+    echo "  check   Check if commands are in sync"
+    echo "  diff    Show differences between command sets"
+    echo "  help    Show this help message"
+    echo ""
+    echo "Directories:"
+    echo "  Claude Code: $CLAUDE_DIR"
+    echo "  OpenCode:    $OPENCODE_DIR"
+    echo ""
+    echo "Note: Commands are maintained manually in both directories."
+    echo "Use this tool to verify they stay in sync."
+}
+
+# Main
+case "${1:-check}" in
+    check)
+        # Pass 1: file count + name check
+        check_sync
+        # Pass 2: content-level checksum comparison
+        check_content
+        ;;
+    diff)
+        show_diff
+        ;;
+    help|--help|-h)
+        show_help
+        ;;
+    *)
+        log_error "Unknown command: $1"
+        show_help
+        exit 1
+        ;;
+esac

package/bin/lib/caste-colors.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * Caste Color Definitions Module
+ *
+ * Centralized caste styling with colors and emojis for consistent
+ * theming across the Aether colony system.
+ *
+ * Caste Colors (ANSI + picocolors):
+ * - builder:  blue   (🔨) - Construction, implementation
+ * - watcher:  green  (👁️) - Observation, monitoring
+ * - scout:    yellow (🔍) - Exploration, investigation
+ * - chaos:    red    (🎲) - Testing, disruption
+ * - prime:    magenta (👑) - Coordination, leadership
+ */
+
+const pc = require('picocolors');
+
+// Caste definitions with colors and emojis (per CONTEXT.md decisions)
+const CASTE_STYLES = {
+  builder:  { color: 'blue',   emoji: '🔨🐜', ansi: '\033[34m', pc: pc.blue },
+  watcher:  { color: 'green',  emoji: '👁️🐜',  ansi: '\033[32m', pc: pc.green },
+  scout:    { color: 'yellow', emoji: '🔍🐜', ansi: '\033[33m', pc: pc.yellow },
+  chaos:    { color: 'red',    emoji: '🎲🐜', ansi: '\033[31m', pc: pc.red },
+  prime:    { color: 'magenta',emoji: '👑🐜', ansi: '\033[35m', pc: pc.magenta }
+};
+
+// Get style for a caste (case-insensitive)
+function getCasteStyle(caste) {
+  const key = caste.toLowerCase();
+  return CASTE_STYLES[key] || { color: 'reset', emoji: '🐜', ansi: '\033[0m', pc: (s) => s };
+}
+
+// Format ant name with color and emoji: "🔨 Builder" (both colored)
+function formatAnt(name, caste) {
+  const style = getCasteStyle(caste);
+  return `${style.emoji} ${style.pc(name)}`;
+}
+
+// Format with ANSI codes (for bash scripts)
+function formatAntAnsi(name, caste) {
+  const style = getCasteStyle(caste);
+  const reset = '\x1b[0m';
+  return `${style.ansi}${style.emoji} ${name}${reset}`;
+}
+
+// Get all castes for iteration
+function getCastes() {
+  return Object.keys(CASTE_STYLES);
+}
+
+module.exports = {
+  CASTE_STYLES,
+  getCasteStyle,
+  formatAnt,
+  formatAntAnsi,
+  getCastes
+};

package/bin/lib/colors.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * Aether Color Palette Module
+ *
+ * Centralized color definitions for consistent CLI theming.
+ * Uses picocolors for lightweight, NO_COLOR-friendly terminal colors.
+ *
+ * Aether Brand Colors:
+ * - queen: magenta (Queen ant)
+ * - colony: cyan (Colony/nest)
+ * - worker: yellow (Workers)
+ * - success: green
+ * - warning: yellow
+ * - error: red
+ * - info: blue
+ */
+
+const pc = require('picocolors');
+
+/**
+ * Detect if color output is enabled
+ * Checks --no-color flag and NO_COLOR environment variable
+ * @returns {boolean} True if colors should be enabled
+ */
+function isColorEnabled() {
+  // Check explicit --no-color flag
+  if (process.argv.includes('--no-color')) {
+    return false;
+  }
+  // Check environment variable (NO_COLOR set to any non-empty value disables colors)
+  if (process.env.NO_COLOR && process.env.NO_COLOR !== '') {
+    return false;
+  }
+  // Check if stdout is TTY (disable colors when piped)
+  if (!process.stdout.isTTY) {
+    return false;
+  }
+  return true;
+}
+
+const enabled = isColorEnabled();
+const p = enabled ? pc : pc.createColors(false);
+
+/**
+ * Aether brand color palette
+ * Semantic naming based on ant colony hierarchy and message types
+ */
+module.exports = {
+  // Aether brand - ant colony hierarchy
+  queen: p.magenta,      // Queen ant - magenta
+  colony: p.cyan,        // Colony/nest - cyan
+  worker: p.yellow,      // Workers - yellow
+
+  // Semantic message colors
+  success: p.green,
+  warning: p.yellow,
+  error: p.red,
+  info: p.blue,
+
+  // Text styles
+  bold: p.bold,
+  dim: p.dim,
+  italic: p.italic,
+  underline: p.underline,
+  strikethrough: p.strikethrough,
+
+  // Headers (combined styles)
+  header: (text) => p.bold(p.cyan(text)),
+  subheader: (text) => p.bold(text),
+
+  // Utility
+  isEnabled: () => enabled,
+
+  // Raw picocolors access for advanced usage
+  raw: p
+};

package/bin/lib/errors.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+/**
+ * Aether Error Class Hierarchy
+ *
+ * Centralized error handling for the Aether Colony CLI.
+ * Provides structured JSON output, error codes, and recovery suggestions.
+ */
+
+/**
+ * Error codes enum - categorized by error type
+ */
+const ErrorCodes = {
+  // System errors (1-99)
+  E_HUB_NOT_FOUND: 'E_HUB_NOT_FOUND',
+  E_REPO_NOT_INITIALIZED: 'E_REPO_NOT_INITIALIZED',
+  E_FILE_SYSTEM: 'E_FILE_SYSTEM',
+  E_GIT_ERROR: 'E_GIT_ERROR',
+
+  // Validation errors (100-199)
+  E_INVALID_STATE: 'E_INVALID_STATE',
+  E_MANIFEST_INVALID: 'E_MANIFEST_INVALID',
+  E_JSON_PARSE: 'E_JSON_PARSE',
+
+  // Runtime errors (200-299)
+  E_UPDATE_FAILED: 'E_UPDATE_FAILED',
+  E_LOCK_TIMEOUT: 'E_LOCK_TIMEOUT',
+  E_ATOMIC_WRITE_FAILED: 'E_ATOMIC_WRITE_FAILED',
+
+  // Unexpected errors (300-399)
+  E_UNEXPECTED: 'E_UNEXPECTED',
+  E_UNCAUGHT_EXCEPTION: 'E_UNCAUGHT_EXCEPTION',
+  E_UNHANDLED_REJECTION: 'E_UNHANDLED_REJECTION',
+
+  // Configuration errors (400-499)
+  E_CONFIG: 'E_CONFIG',
+};
+
+/**
+ * Base AetherError class
+ * All application errors extend this class for consistent handling
+ */
+class AetherError extends Error {
+  /**
+   * @param {string} code - Error code from ErrorCodes
+   * @param {string} message - Human-readable error message
+   * @param {object} details - Additional error context
+   * @param {string|null} recovery - Recovery suggestion for user
+   */
+  constructor(code, message, details = {}, recovery = null) {
+    super(message);
+    this.name = 'AetherError';
+    this.code = code;
+    this.details = details;
+    this.recovery = recovery;
+    this.timestamp = new Date().toISOString();
+
+    // Maintain proper stack trace in V8 environments
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, AetherError);
+    }
+  }
+
+  /**
+   * Convert error to structured JSON object
+   * @returns {object} Structured error representation
+   */
+  toJSON() {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        details: this.details,
+        recovery: this.recovery,
+        timestamp: this.timestamp,
+      },
+    };
+  }
+
+  /**
+   * Convert error to string for console output
+   * @returns {string} Formatted error string
+   */
+  toString() {
+    let str = `${this.code}: ${this.message}`;
+    if (this.recovery) {
+      str += `\n  Recovery: ${this.recovery}`;
+    }
+    return str;
+  }
+}
+
+/**
+ * HubError - Hub-related errors (distribution hub not found, corrupted, etc.)
+ */
+class HubError extends AetherError {
+  constructor(message, details = {}) {
+    super(
+      ErrorCodes.E_HUB_NOT_FOUND,
+      message,
+      details,
+      'Run: aether install'
+    );
+    this.name = 'HubError';
+  }
+}
+
+/**
+ * RepoError - Repository initialization errors
+ */
+class RepoError extends AetherError {
+  constructor(message, details = {}) {
+    super(
+      ErrorCodes.E_REPO_NOT_INITIALIZED,
+      message,
+      details,
+      'Run /ant:init in this repo first'
+    );
+    this.name = 'RepoError';
+  }
+}
+
+/**
+ * GitError - Git operation errors
+ */
+class GitError extends AetherError {
+  constructor(message, details = {}) {
+    super(
+      ErrorCodes.E_GIT_ERROR,
+      message,
+      details,
+      'Check git status and resolve conflicts'
+    );
+    this.name = 'GitError';
+  }
+}
+
+/**
+ * ValidationError - State validation errors
+ */
+class ValidationError extends AetherError {
+  constructor(message, details = {}) {
+    super(
+      ErrorCodes.E_INVALID_STATE,
+      message,
+      details,
+      'Check the state file and fix validation errors'
+    );
+    this.name = 'ValidationError';
+  }
+}
+
+/**
+ * FileSystemError - File operation errors
+ */
+class FileSystemError extends AetherError {
+  constructor(message, details = {}) {
+    super(
+      ErrorCodes.E_FILE_SYSTEM,
+      message,
+      details,
+      'Check file permissions and available disk space'
+    );
+    this.name = 'FileSystemError';
+  }
+}
+
+/**
+ * ConfigurationError - Environment/configuration errors
+ */
+class ConfigurationError extends AetherError {
+  constructor(message, details = {}) {
+    super(
+      ErrorCodes.E_CONFIG,
+      message,
+      details,
+      'Check environment variables and configuration'
+    );
+    this.name = 'ConfigurationError';
+  }
+}
+
+/**
+ * StateSchemaError - State file schema validation errors (PLAN-007 Fix 3)
+ */
+class StateSchemaError extends AetherError {
+  constructor(message, details = {}) {
+    super(
+      ErrorCodes.E_INVALID_STATE,
+      message,
+      details,
+      'Check state file structure and fix schema errors, or restore from backup'
+    );
+    this.name = 'StateSchemaError';
+  }
+}
+
+/**
+ * Map error codes to sysexits.h exit codes
+ * @param {string} code - Error code
+ * @returns {number} Exit code (0-255)
+ */
+function getExitCode(code) {
+  switch (code) {
+    case ErrorCodes.E_HUB_NOT_FOUND:
+      return 69; // EX_UNAVAILABLE - service unavailable
+    case ErrorCodes.E_REPO_NOT_INITIALIZED:
+      return 78; // EX_CONFIG - configuration error
+    case ErrorCodes.E_INVALID_STATE:
+    case ErrorCodes.E_MANIFEST_INVALID:
+    case ErrorCodes.E_JSON_PARSE:
+      return 65; // EX_DATAERR - data format error
+    case ErrorCodes.E_FILE_SYSTEM:
+    case ErrorCodes.E_ATOMIC_WRITE_FAILED:
+      return 74; // EX_IOERR - I/O error
+    case ErrorCodes.E_GIT_ERROR:
+      return 70; // EX_SOFTWARE - internal software error
+    case ErrorCodes.E_LOCK_TIMEOUT:
+      return 73; // EX_CANTCREAT - can't create (lock) file
+    case ErrorCodes.E_CONFIG:
+      return 78; // EX_CONFIG - configuration error
+    default:
+      return 1; // Generic error
+  }
+}
+
+/**
+ * Wrap a plain Error in an AetherError
+ * @param {Error} error - Plain error to wrap
+ * @returns {AetherError} Wrapped error
+ */
+function wrapError(error) {
+  if (error instanceof AetherError) {
+    return error;
+  }
+  return new AetherError(
+    ErrorCodes.E_UNEXPECTED,
+    error.message,
+    { stack: error.stack, name: error.name },
+    'Please report this issue with the error details'
+  );
+}
+
+module.exports = {
+  AetherError,
+  HubError,
+  RepoError,
+  GitError,
+  ValidationError,
+  FileSystemError,
+  ConfigurationError,
+  StateSchemaError,
+  ErrorCodes,
+  getExitCode,
+  wrapError,
+};