@sugar-crash-studios/vibe-forge 0.4.0

package/bin/forge.sh

@@ -0,0 +1,533 @@
+#!/usr/bin/env bash
+#
+# Vibe Forge - Main Launcher
+# Starts the Planning Hub or specific worker agents
+#
+# Usage:
+#   forge              - Start Planning Hub (main session)
+#   forge init         - Initialize Vibe Forge
+#   forge start <agent> - Start a specific worker agent
+#   forge spawn <agent> - Spawn agent in new terminal window/tab
+#   forge status       - Show forge status
+#   forge doctor       - Full environment diagnostics (alias: test)
+#   forge daemon       - Start/stop the background daemon
+#   forge help         - Show help
+#
+# Security Note:
+#   This script uses --dangerously-skip-permissions for Claude Code to enable
+#   seamless agent startup. This is intentional for the forge workflow.
+#   See docs/security.md for details.
+#
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FORGE_ROOT="$(dirname "$SCRIPT_DIR")"
+CONFIG_FILE="$FORGE_ROOT/.forge/config.json"
+
+# =============================================================================
+# Load Shared Libraries
+# =============================================================================
+
+# shellcheck source=lib/colors.sh
+source "$SCRIPT_DIR/lib/colors.sh"
+# shellcheck source=lib/constants.sh
+source "$SCRIPT_DIR/lib/constants.sh"
+# shellcheck source=lib/config.sh
+source "$SCRIPT_DIR/lib/config.sh"
+# shellcheck source=lib/json.sh
+source "$SCRIPT_DIR/lib/json.sh"
+# shellcheck source=lib/agents.sh
+source "$SCRIPT_DIR/lib/agents.sh"
+
+# Load agent configuration from JSON if available
+# This overwrites the fallback values in constants.sh
+if [[ -f "$FORGE_ROOT/$AGENTS_CONFIG" ]]; then
+    if ! load_agents_from_json "$FORGE_ROOT/$AGENTS_CONFIG" 2>/dev/null; then
+        log_warn "Failed to load agents.json, using fallback defaults"
+    fi
+fi
+
+# =============================================================================
+# Commands
+# =============================================================================
+
+cmd_init() {
+    "$SCRIPT_DIR/forge-setup.sh" "$@"
+}
+
+cmd_start() {
+    local agent="${1:-hub}"
+
+    # Load and validate config
+    require_forge_config "$FORGE_ROOT"
+
+    # Validate and resolve agent name (SECURITY: whitelist validation)
+    local resolved
+    resolved=$(resolve_agent "$agent") || {
+        log_error "Unknown agent: $agent"
+        echo ""
+        show_available_agents
+        exit $EXIT_INVALID_ARGUMENT
+    }
+
+    # Get personality path (SECURITY: path traversal protection)
+    local personality_path
+    personality_path=$(get_agent_personality_path "$FORGE_ROOT" "$resolved") || {
+        log_error "Personality file not found for agent: $resolved"
+        exit $EXIT_CONFIG_ERROR
+    }
+
+    # Get display name
+    local agent_name
+    agent_name=$(get_agent_display_name "$resolved")
+
+    log_header "🔥 Starting $agent_name..."
+    echo ""
+
+    # Build the system prompt from personality file
+    local system_prompt
+    system_prompt=$(cat "$personality_path")
+
+    # Add project context if it exists
+    local project_context="$FORGE_ROOT/$CONTEXT_DIR/project-context.md"
+    if [[ -f "$project_context" ]]; then
+        system_prompt="$system_prompt
+
+---
+
+# Project Context
+
+$(cat "$project_context")"
+    fi
+
+    # Add startup instructions based on agent type
+    if [[ "$resolved" == "hub" ]]; then
+        # Planning Hub startup - Party Mode Team
+        system_prompt="$system_prompt
+
+---
+
+# Startup Instructions
+
+On startup, you MUST immediately display the team assembly welcome as shown in the Startup Behavior section of your personality. Show the forge council members assembling with their icons and roles. Then check for any current work status.
+"
+    else
+        # Worker agent startup
+        system_prompt="$system_prompt
+
+---
+
+# Startup Instructions
+
+On startup:
+1. Announce yourself briefly (icon, name, role)
+2. Check tasks/pending/ and tasks/needs-changes/ for tasks assigned to you
+3. If you find assigned tasks, IMMEDIATELY begin working on them (no confirmation needed)
+4. If no tasks found, announce you're idle and ready for work
+
+You are autonomous - when assigned work exists, start it without asking permission.
+"
+    fi
+
+    # Launch Claude Code with the personality
+    # --dangerously-skip-permissions avoids repeated prompts when starting agents
+    # This is documented in docs/security.md
+    if [[ "$resolved" == "hub" ]]; then
+        claude --dangerously-skip-permissions --system-prompt "$system_prompt" "begin"
+    else
+        claude --dangerously-skip-permissions --system-prompt "$system_prompt" "startup"
+    fi
+}
+
+cmd_status() {
+    require_forge_config "$FORGE_ROOT"
+
+    local state_file="$FORGE_ROOT/$CONTEXT_DIR/forge-state.yaml"
+
+    echo ""
+    log_header "🔥 Forge Status"
+
+    if [[ -f "$state_file" ]]; then
+        cat "$state_file"
+    else
+        echo "No active forge state."
+        echo ""
+        echo "Start the forge with: forge"
+    fi
+
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+}
+
+cmd_test() {
+    # Alias for doctor
+    cmd_doctor
+}
+
+cmd_doctor() {
+    echo ""
+    log_header "🩺 Forge Doctor"
+    echo ""
+
+    local issues=0
+
+    # --- Dependencies ---
+    echo "Dependencies"
+    echo "────────────────────────────────────────────────"
+
+    if claude --version &> /dev/null; then
+        local claude_ver
+        claude_ver=$(claude --version 2>&1 | head -1)
+        log_success "Claude Code: $claude_ver"
+    else
+        log_error "Claude Code: not found"
+        echo "   Install from: https://claude.ai/download"
+        issues=$((issues + 1))
+    fi
+
+    if command -v node &> /dev/null; then
+        local node_ver
+        node_ver=$(node --version 2>&1)
+        log_success "Node.js: $node_ver"
+        # Warn if below Node 18
+        local node_major
+        node_major=$(node --version | sed 's/v\([0-9]*\).*/\1/')
+        if [[ "$node_major" -lt 18 ]]; then
+            log_warn "Node.js $node_ver is below recommended v18+"
+        fi
+    else
+        log_error "Node.js: not found"
+        issues=$((issues + 1))
+    fi
+
+    if command -v git &> /dev/null; then
+        local git_ver
+        git_ver=$(git --version 2>&1)
+        log_success "Git: $git_ver"
+    else
+        log_error "Git: not found"
+        issues=$((issues + 1))
+    fi
+
+    if command -v sqlite3 &> /dev/null; then
+        local sq_ver
+        sq_ver=$(sqlite3 --version 2>&1 | head -1)
+        log_success "SQLite3: $sq_ver"
+    else
+        log_warn "SQLite3: not found (daemon metrics disabled)"
+    fi
+
+    # --- Forge Config ---
+    echo ""
+    echo "Configuration"
+    echo "────────────────────────────────────────────────"
+
+    local config_file="$FORGE_ROOT/.forge/config.json"
+    local local_config_file="$FORGE_ROOT/.forge/config.local.json"
+
+    if [[ -f "$config_file" ]]; then
+        log_success "config.json: found"
+        local platform terminal
+        platform=$(json_get_string "$config_file" "platform" 2>/dev/null || echo "unknown")
+        terminal=$(json_get_string "$config_file" "terminal_type" 2>/dev/null || echo "unknown")
+        echo "   Platform: $platform | Terminal: $terminal"
+    else
+        log_error "config.json: not found — run 'forge init'"
+        issues=$((issues + 1))
+    fi
+
+    if [[ -f "$local_config_file" ]]; then
+        log_success "config.local.json: found (local overrides active)"
+    fi
+
+    # --- agents.json sync check ---
+    local agents_file="$FORGE_ROOT/config/agents.json"
+    if [[ -f "$agents_file" ]]; then
+        log_success "agents.json: found"
+        local agent_count
+        agent_count=$(node -e "const a=require('$agents_file'); console.log(Object.keys(a.agents||{}).length)" 2>/dev/null || echo "?")
+        echo "   Agents defined: $agent_count"
+    else
+        log_error "agents.json: not found"
+        issues=$((issues + 1))
+    fi
+
+    # --- Alias collision check ---
+    if [[ -f "$agents_file" ]]; then
+        local collisions
+        collisions=$(node -e "
+const a = require('$agents_file').agents || {};
+const seen = {};
+const dupes = [];
+for (const [name, info] of Object.entries(a)) {
+    const aliases = [name, ...(info.aliases || [])];
+    for (const alias of aliases) {
+        if (seen[alias] && seen[alias] !== name) {
+            dupes.push(alias + ' (' + seen[alias] + ' vs ' + name + ')');
+        }
+        seen[alias] = name;
+    }
+}
+if (dupes.length) console.log('COLLISION: ' + dupes.join(', '));
+" 2>/dev/null || true)
+        if [[ -n "$collisions" ]]; then
+            log_error "Alias collision detected: $collisions"
+            issues=$((issues + 1))
+        else
+            log_success "No alias collisions"
+        fi
+    fi
+
+    # --- Task directories ---
+    echo ""
+    echo "Task System"
+    echo "────────────────────────────────────────────────"
+
+    local tasks_dir="$FORGE_ROOT/tasks"
+    local required_dirs=("pending" "in-progress" "completed" "review" "approved" "merged" "needs-changes" "attention" "bugs")
+    for dir in "${required_dirs[@]}"; do
+        if [[ -d "$tasks_dir/$dir" ]]; then
+            local count
+            count=$(ls "$tasks_dir/$dir/"*.md 2>/dev/null | wc -l | tr -d ' ')
+            log_success "$dir/: $count task(s)"
+        else
+            log_warn "$dir/: missing (will be created by daemon)"
+        fi
+    done
+
+    # --- Daemon ---
+    echo ""
+    echo "Daemon"
+    echo "────────────────────────────────────────────────"
+
+    local pid_file="$FORGE_ROOT/.forge/daemon.pid"
+    if [[ -f "$pid_file" ]]; then
+        local pid
+        pid=$(cat "$pid_file" 2>/dev/null)
+        if kill -0 "$pid" 2>/dev/null; then
+            log_success "Daemon running (PID $pid)"
+        else
+            log_warn "Daemon PID file exists but process is dead — run 'forge daemon start'"
+        fi
+    else
+        log_warn "Daemon not running — run 'forge daemon start' for automated task routing"
+    fi
+
+    # --- Claude Code test ---
+    echo ""
+    echo "Claude Code Integration"
+    echo "────────────────────────────────────────────────"
+
+    local test_output
+    test_output=$(claude --system-prompt "You are a test. Reply only: FORGE_TEST_OK" --print "test" 2>&1 | head -1)
+    if [[ "$test_output" == *"FORGE_TEST_OK"* || "$test_output" == *"test"* ]]; then
+        log_success "Personality injection: working"
+    else
+        log_warn "Personality injection: response unexpected"
+        echo "   Output: $test_output"
+    fi
+
+    # --- Summary ---
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    if [[ $issues -eq 0 ]]; then
+        log_success "🔥 Forge looks healthy"
+    else
+        log_error "Found $issues issue(s) — resolve the errors above before starting"
+    fi
+    echo ""
+}
+
+cmd_spawn() {
+    local agent="${1:-}"
+
+    if [[ -z "$agent" ]]; then
+        log_error "No agent specified."
+        echo "Usage: forge spawn <agent>"
+        echo ""
+        show_available_agents
+        exit $EXIT_INVALID_ARGUMENT
+    fi
+
+    # Validate agent before passing to spawn script (SECURITY: whitelist check)
+    if ! is_valid_agent "$agent"; then
+        log_error "Unknown agent: $agent"
+        echo ""
+        show_available_agents
+        exit $EXIT_INVALID_ARGUMENT
+    fi
+
+    "$SCRIPT_DIR/forge-spawn.sh" "$agent"
+}
+
+cmd_daemon() {
+    local action="${1:-status}"
+
+    case "$action" in
+        "start")
+            echo "Starting forge daemon..."
+            "$SCRIPT_DIR/forge-daemon.sh" start
+            ;;
+        "stop")
+            echo "Stopping forge daemon..."
+            "$SCRIPT_DIR/forge-daemon.sh" stop
+            ;;
+        "status")
+            "$SCRIPT_DIR/forge-daemon.sh" status
+            ;;
+        "notifications"|"notify")
+            shift
+            "$SCRIPT_DIR/forge-daemon.sh" notifications "$@"
+            ;;
+        "clear")
+            "$SCRIPT_DIR/forge-daemon.sh" clear
+            ;;
+        *)
+            echo "Usage: forge daemon [start|stop|status|notifications|clear]"
+            ;;
+    esac
+}
+
+cmd_config() {
+    local setting="${1:-}"
+    local value="${2:-}"
+    local config_file="$FORGE_ROOT/.forge/config.json"
+
+    if [[ ! -f "$config_file" ]]; then
+        log_error "Forge not initialized. Run 'forge init' first."
+        exit $EXIT_CONFIG_ERROR
+    fi
+
+    case "$setting" in
+        "worker-loop"|"loop")
+            case "$value" in
+                "on"|"true"|"1"|"enable"|"enabled")
+                    # Enable worker loop
+                    json_write_bool "$config_file" "worker_loop_enabled" true
+                    log_success "Worker Loop enabled"
+                    echo "Workers will now keep running to check for new tasks."
+                    ;;
+                "off"|"false"|"0"|"disable"|"disabled")
+                    # Disable worker loop
+                    json_write_bool "$config_file" "worker_loop_enabled" false
+                    log_success "Worker Loop disabled"
+                    echo "Workers will exit after completing their tasks."
+                    ;;
+                ""|"status")
+                    # Show current status
+                    local current
+                    current=$(json_read "$config_file" "worker_loop_enabled" "false")
+                    if [[ "$current" == "true" ]]; then
+                        echo "Worker Loop: enabled"
+                    else
+                        echo "Worker Loop: disabled"
+                    fi
+                    ;;
+                *)
+                    echo "Usage: forge config worker-loop [on|off|status]"
+                    ;;
+            esac
+            ;;
+        "")
+            # Show all config
+            echo ""
+            log_header "Forge Configuration"
+            echo ""
+            json_pretty "$config_file"
+            echo ""
+            ;;
+        *)
+            log_error "Unknown setting: $setting"
+            echo ""
+            echo "Available settings:"
+            echo "  worker-loop    Toggle persistent worker mode (on/off)"
+            echo ""
+            echo "Usage: forge config <setting> [value]"
+            ;;
+    esac
+}
+
+cmd_help() {
+    echo ""
+    log_header "🔥 Vibe Forge"
+    echo ""
+    echo "Usage: forge [command] [options]"
+    echo ""
+    echo "Commands:"
+    echo "  (none)              Start the Planning Hub (main session)"
+    echo "  init                Initialize Vibe Forge for this project"
+    echo "  start <agent>       Start a specific worker agent (in current terminal)"
+    echo "  spawn <agent>       Spawn agent in new terminal window/tab"
+    echo "  status              Show current forge status"
+    echo "  doctor              Full environment diagnostics (alias: test)"
+    echo "  daemon <action>     Manage background daemon (start|stop|status|notifications|clear)"
+    echo "  config <setting>    View or change configuration settings"
+    echo "  help                Show this help message"
+    echo ""
+    show_available_agents
+    echo ""
+    echo "Configuration:"
+    echo "  forge config                    Show all settings"
+    echo "  forge config worker-loop on     Enable persistent worker mode"
+    echo "  forge config worker-loop off    Disable persistent worker mode"
+    echo ""
+    echo "Examples:"
+    echo "  forge               Start Planning Hub"
+    echo "  forge init          Initialize for new project"
+    echo "  forge start anvil   Start Anvil (frontend) agent"
+    echo "  forge spawn fe      Spawn frontend agent in new terminal"
+    echo "  forge status        Check current status"
+    echo ""
+}
+
+# =============================================================================
+# Main
+# =============================================================================
+
+main() {
+    local command="${1:-}"
+
+    case "$command" in
+        "init")
+            shift
+            cmd_init "$@"
+            ;;
+        "start")
+            shift
+            cmd_start "$@"
+            ;;
+        "spawn")
+            shift
+            cmd_spawn "$@"
+            ;;
+        "status")
+            cmd_status
+            ;;
+        "test"|"doctor")
+            cmd_doctor
+            ;;
+        "daemon")
+            shift
+            cmd_daemon "$@"
+            ;;
+        "config")
+            shift
+            cmd_config "$@"
+            ;;
+        "help"|"--help"|"-h")
+            cmd_help
+            ;;
+        "")
+            # Default: start Planning Hub
+            cmd_start "hub"
+            ;;
+        *)
+            log_error "Unknown command: $command"
+            echo "Run 'forge help' for usage."
+            exit $EXIT_INVALID_ARGUMENT
+            ;;
+    esac
+}
+
+main "$@"

package/bin/lib/agents.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+#
+# Vibe Forge - Agent Resolution and Validation
+# Source this file in other scripts: source "$SCRIPT_DIR/lib/agents.sh"
+#
+# SECURITY: This module provides safe agent name resolution with whitelist validation.
+# Never pass user input directly to shell commands - always resolve through these functions.
+#
+
+# Ensure constants are loaded
+if [[ -z "${VALID_AGENTS+x}" ]]; then
+    echo "Error: constants.sh must be sourced before agents.sh" >&2
+    exit 1
+fi
+
+# resolve_agent ALIAS
+# Converts an agent alias to its canonical name.
+# Returns: canonical name on stdout, empty string if not found
+# Exit code: 0 if found, 1 if not found
+#
+# SECURITY: This function validates against a whitelist.
+# The returned value is safe to use in file paths and commands.
+resolve_agent() {
+    local input="$1"
+
+    # Normalize to lowercase for matching
+    local normalized
+    normalized=$(echo "$input" | tr '[:upper:]' '[:lower:]')
+
+    # Look up in alias map
+    local canonical="${AGENT_ALIASES[$normalized]:-}"
+
+    if [[ -n "$canonical" ]]; then
+        echo "$canonical"
+        return 0
+    fi
+
+    return 1
+}
+
+# is_valid_agent AGENT
+# Checks if an agent name is valid (either canonical or alias)
+# Returns: 0 if valid, 1 if invalid
+is_valid_agent() {
+    local agent="$1"
+    resolve_agent "$agent" >/dev/null 2>&1
+}
+
+# get_agent_personality_path FORGE_ROOT AGENT
+# Returns the path to an agent's personality file.
+# Uses AGENT_PERSONALITY_FILES from constants.sh (or loaded from agents.json)
+# SECURITY: Validates agent name before constructing path.
+# Returns: full path on stdout
+# Exit code: 0 on success, 1 if agent invalid or file missing
+get_agent_personality_path() {
+    local forge_root="$1"
+    local agent="$2"
+
+    # Resolve and validate agent
+    local canonical
+    canonical=$(resolve_agent "$agent") || {
+        return 1
+    }
+
+    # Get personality file path from configuration
+    local relative_path="${AGENT_PERSONALITY_FILES[$canonical]:-}"
+    if [[ -z "$relative_path" ]]; then
+        # Fallback: construct path if not in config
+        relative_path="agents/$canonical/personality.md"
+    fi
+
+    local personality_path="$forge_root/$relative_path"
+
+    # Validate file exists
+    if [[ ! -f "$personality_path" ]]; then
+        return 1
+    fi
+
+    # SECURITY: Verify the resolved path is within agents directory
+    local real_path
+    real_path=$(cd "$(dirname "$personality_path")" 2>/dev/null && pwd)/$(basename "$personality_path")
+    local agents_dir
+    agents_dir=$(cd "$forge_root/agents" 2>/dev/null && pwd)
+
+    if [[ "$real_path" != "$agents_dir"/* ]]; then
+        echo "Security error: Path traversal detected" >&2
+        return 1
+    fi
+
+    echo "$personality_path"
+    return 0
+}
+
+# show_available_agents
+# Prints a formatted list of available agents with aliases
+# Uses data from AGENT_DISPLAY_NAMES, AGENT_ROLES, and AGENT_ALIASES
+show_available_agents() {
+    echo "Available agents:"
+
+    # Iterate over valid agents (excluding hub for user display)
+    for agent in "${VALID_AGENTS[@]}"; do
+        if [[ "$agent" == "hub" ]]; then
+            continue
+        fi
+
+        # Get display info
+        local role="${AGENT_ROLES[$agent]:-}"
+
+        # Collect aliases for this agent
+        local aliases=()
+        for alias in "${!AGENT_ALIASES[@]}"; do
+            if [[ "${AGENT_ALIASES[$alias]}" == "$agent" && "$alias" != "$agent" ]]; then
+                aliases+=("$alias")
+            fi
+        done
+
+        # Format aliases (take first 3)
+        local alias_str=""
+        if [[ ${#aliases[@]} -gt 0 ]]; then
+            # Sort and take first 3
+            IFS=$'\n' sorted=($(printf '%s\n' "${aliases[@]}" | sort)); unset IFS
+            local display_aliases=("${sorted[@]:0:3}")
+            alias_str="($(IFS=", "; echo "${display_aliases[*]}"))"
+        fi
+
+        # Print formatted line
+        printf "  %-9s %-25s - %s\n" "$agent" "$alias_str" "$role"
+    done
+}
+
+# get_agent_display_name AGENT
+# Returns the display name for an agent (e.g., "Anvil" for "anvil")
+# Uses AGENT_DISPLAY_NAMES from constants.sh (or loaded from agents.json)
+get_agent_display_name() {
+    local agent="$1"
+    local canonical
+    canonical=$(resolve_agent "$agent") || return 1
+
+    # Look up in AGENT_DISPLAY_NAMES array
+    local display_name="${AGENT_DISPLAY_NAMES[$canonical]:-}"
+    if [[ -n "$display_name" ]]; then
+        echo "$display_name"
+    else
+        # Fallback to canonical name with first letter capitalized
+        echo "${canonical^}"
+    fi
+}
+
+# get_agent_role AGENT
+# Returns the role description for an agent
+get_agent_role() {
+    local agent="$1"
+    local canonical
+    canonical=$(resolve_agent "$agent") || return 1
+
+    echo "${AGENT_ROLES[$canonical]:-}"
+}
+
+# get_agent_icon AGENT
+# Returns the icon/emoji for an agent
+get_agent_icon() {
+    local agent="$1"
+    local canonical
+    canonical=$(resolve_agent "$agent") || return 1
+
+    echo "${AGENT_ICONS[$canonical]:-}"
+}
+
+# get_agent_tab_color AGENT
+# Returns the Windows Terminal tab color for an agent (hex format)
+get_agent_tab_color() {
+    local agent="$1"
+    local canonical
+    canonical=$(resolve_agent "$agent") || return 1
+
+    echo "${AGENT_TAB_COLORS[$canonical]:-}"
+}