vibe-forge 0.1.0 → 0.2.1

package/bin/forge.sh

@@ -13,6 +13,11 @@
 #   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
 
@@ -20,99 +25,24 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 FORGE_ROOT="$(dirname "$SCRIPT_DIR")"
 CONFIG_FILE="$FORGE_ROOT/.forge/config.json"
 
-# Colors
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m'
-
 # =============================================================================
-# Helper Functions
+# Load Shared Libraries
 # =============================================================================
 
-load_config() {
-    if [[ ! -f "$CONFIG_FILE" ]]; then
-        echo -e "${RED}Error: Vibe Forge not initialized.${NC}"
-        echo "Run 'forge init' first."
-        exit 1
-    fi
-
-    # Parse JSON config (basic extraction)
-    PLATFORM=$(grep -o '"platform": *"[^"]*"' "$CONFIG_FILE" | cut -d'"' -f4)
-    GIT_BASH_PATH=$(grep -o '"git_bash_path": *"[^"]*"' "$CONFIG_FILE" | cut -d'"' -f4)
-
-    # Set environment for Windows
-    # Claude Code on Windows needs backslashes in the path
-    if [[ "$PLATFORM" == "windows" && -n "$GIT_BASH_PATH" ]]; then
-        # Convert forward slashes to backslashes for Windows
-        GIT_BASH_PATH_WIN="${GIT_BASH_PATH//\//\\}"
-        export CLAUDE_CODE_GIT_BASH_PATH="$GIT_BASH_PATH_WIN"
-
-        # Add common Windows paths that Git Bash might miss
-        # npm global path (where claude is typically installed)
-        NPM_PATH="/c/Users/$USER/AppData/Roaming/npm"
-        if [[ -d "$NPM_PATH" ]] && [[ ":$PATH:" != *":$NPM_PATH:"* ]]; then
-            export PATH="$NPM_PATH:$PATH"
-        fi
-
-        # Also try with USERPROFILE
-        if [[ -n "$USERPROFILE" ]]; then
-            NPM_PATH_ALT="$USERPROFILE/AppData/Roaming/npm"
-            NPM_PATH_ALT="${NPM_PATH_ALT//\\//}"  # Convert backslashes
-            if [[ -d "$NPM_PATH_ALT" ]] && [[ ":$PATH:" != *":$NPM_PATH_ALT:"* ]]; then
-                export PATH="$NPM_PATH_ALT:$PATH"
-            fi
-        fi
-    fi
-}
-
-get_personality_path() {
-    local agent="$1"
-    local personality_file=""
-
-    case "$agent" in
-        "hub"|"planning"|"master"|"forge-master"|"")
-            personality_file="$FORGE_ROOT/agents/planning-hub/personality.md"
-            ;;
-        "anvil")
-            personality_file="$FORGE_ROOT/agents/anvil/personality.md"
-            ;;
-        "furnace")
-            personality_file="$FORGE_ROOT/agents/furnace/personality.md"
-            ;;
-        "crucible")
-            personality_file="$FORGE_ROOT/agents/crucible/personality.md"
-            ;;
-        "sentinel")
-            personality_file="$FORGE_ROOT/agents/sentinel/personality.md"
-            ;;
-        "scribe")
-            personality_file="$FORGE_ROOT/agents/scribe/personality.md"
-            ;;
-        "herald")
-            personality_file="$FORGE_ROOT/agents/herald/personality.md"
-            ;;
-        "ember")
-            personality_file="$FORGE_ROOT/agents/ember/personality.md"
-            ;;
-        "aegis")
-            personality_file="$FORGE_ROOT/agents/aegis/personality.md"
-            ;;
-        *)
-            echo -e "${RED}Unknown agent: $agent${NC}"
-            echo "Available agents: anvil, furnace, crucible, sentinel, scribe, herald, ember, aegis"
-            exit 1
-            ;;
-    esac
-
-    if [[ ! -f "$personality_file" ]]; then
-        echo -e "${RED}Error: Personality file not found: $personality_file${NC}"
-        exit 1
-    fi
-
-    echo "$personality_file"
-}
+# 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/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
+    load_agents_from_json "$FORGE_ROOT/$AGENTS_CONFIG" 2>/dev/null || true
+fi
 
 # =============================================================================
 # Commands
@@ -124,19 +54,31 @@ cmd_init() {
 
 cmd_start() {
     local agent="${1:-hub}"
-    load_config
 
+    # 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 1
+    }
+
+    # Get personality path (SECURITY: path traversal protection)
     local personality_path
-    personality_path=$(get_personality_path "$agent")
+    personality_path=$(get_agent_personality_path "$FORGE_ROOT" "$resolved") || {
+        log_error "Personality file not found for agent: $resolved"
+        exit 1
+    }
 
+    # Get display name
     local agent_name
-    if [[ "$agent" == "hub" || "$agent" == "" ]]; then
-        agent_name="Planning Hub"
-    else
-        agent_name="$agent"
-    fi
+    agent_name=$(get_agent_display_name "$resolved")
 
-    echo -e "${YELLOW}🔥 Starting $agent_name...${NC}"
+    log_header "🔥 Starting $agent_name..."
     echo ""
 
     # Build the system prompt from personality file
@@ -144,7 +86,7 @@ cmd_start() {
     system_prompt=$(cat "$personality_path")
 
     # Add project context if it exists
-    local project_context="$FORGE_ROOT/context/project-context.md"
+    local project_context="$FORGE_ROOT/$CONTEXT_DIR/project-context.md"
     if [[ -f "$project_context" ]]; then
         system_prompt="$system_prompt
 
@@ -156,7 +98,7 @@ $(cat "$project_context")"
     fi
 
     # Add startup instructions based on agent type
-    if [[ "$agent" == "hub" || "$agent" == "planning" || "$agent" == "" ]]; then
+    if [[ "$resolved" == "hub" ]]; then
         # Planning Hub startup - Party Mode Team
         system_prompt="$system_prompt
 
@@ -180,8 +122,8 @@ On startup: Announce yourself (name, icon, role), check tasks/pending/ and tasks
 
     # Launch Claude Code with the personality
     # --dangerously-skip-permissions avoids repeated prompts when starting agents
-    # Use --resume with initial prompt to trigger welcome but stay interactive
-    if [[ "$agent" == "hub" || "$agent" == "planning" || "$agent" == "" ]]; then
+    # 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"
@@ -189,13 +131,12 @@ On startup: Announce yourself (name, icon, role), check tasks/pending/ and tasks
 }
 
 cmd_status() {
-    load_config
+    require_forge_config "$FORGE_ROOT"
 
-    local state_file="$FORGE_ROOT/context/forge-state.yaml"
+    local state_file="$FORGE_ROOT/$CONTEXT_DIR/forge-state.yaml"
 
     echo ""
-    echo -e "${YELLOW}🔥 Forge Status${NC}"
-    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    log_header "🔥 Forge Status"
 
     if [[ -f "$state_file" ]]; then
         cat "$state_file"
@@ -210,18 +151,18 @@ cmd_status() {
 }
 
 cmd_test() {
-    load_config
+    require_forge_config "$FORGE_ROOT"
 
     echo ""
-    echo -e "${YELLOW}🧪 Testing Vibe Forge setup...${NC}"
+    log_header "🧪 Testing Vibe Forge setup..."
     echo ""
 
     # Test Claude Code
     echo "Testing Claude Code..."
     if claude --version &> /dev/null; then
-        echo -e "${GREEN}✅ Claude Code working${NC}"
+        log_success "Claude Code working"
     else
-        echo -e "${RED}❌ Claude Code not working${NC}"
+        log_error "Claude Code not working"
         exit 1
     fi
 
@@ -232,24 +173,32 @@ cmd_test() {
     test_output=$(claude --system-prompt "You are a test. Respond with only: FORGE_TEST_OK" --print "test" 2>&1 | head -1)
 
     if [[ "$test_output" == *"FORGE_TEST_OK"* || "$test_output" == *"test"* ]]; then
-        echo -e "${GREEN}✅ Personality loading working${NC}"
+        log_success "Personality loading working"
     else
-        echo -e "${YELLOW}⚠️  Personality loading may have issues${NC}"
+        log_warn "Personality loading may have issues"
         echo "   Output: $test_output"
     fi
 
     echo ""
-    echo -e "${GREEN}🔥 Setup validated!${NC}"
+    log_success "🔥 Setup validated!"
 }
 
 cmd_spawn() {
     local agent="${1:-}"
 
     if [[ -z "$agent" ]]; then
-        echo -e "${RED}Error: No agent specified.${NC}"
+        log_error "No agent specified."
         echo "Usage: forge spawn <agent>"
         echo ""
-        echo "Available agents: anvil, furnace, crucible, sentinel, scribe, herald, ember, aegis"
+        show_available_agents
+        exit 1
+    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 1
     fi
 
@@ -286,8 +235,7 @@ cmd_daemon() {
 
 cmd_help() {
     echo ""
-    echo -e "${YELLOW}🔥 Vibe Forge${NC}"
-    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    log_header "🔥 Vibe Forge"
     echo ""
     echo "Usage: forge [command] [options]"
     echo ""
@@ -301,20 +249,21 @@ cmd_help() {
     echo "  daemon <action>     Manage background daemon (start|stop|status|notifications|clear)"
     echo "  help                Show this help message"
     echo ""
-    echo "Agents:"
-    echo "  anvil               Frontend Developer"
-    echo "  furnace             Backend Developer"
-    echo "  crucible            Tester / QA"
-    echo "  sentinel            Code Reviewer"
-    echo "  scribe              Documentation"
-    echo "  herald              Release Manager"
-    echo "  ember               DevOps"
-    echo "  aegis               Security"
+    echo "Agents (with aliases):"
+    echo "  anvil     (frontend, ui, fe)      - Frontend Developer"
+    echo "  furnace   (backend, api, be)      - Backend Developer"
+    echo "  crucible  (test, testing, qa)     - Tester / QA"
+    echo "  sentinel  (review, reviewer, cr)  - Code Reviewer"
+    echo "  scribe    (docs, documentation)   - Documentation"
+    echo "  herald    (release, deploy)       - Release Manager"
+    echo "  ember     (devops, ops, infra)    - DevOps"
+    echo "  aegis     (security, sec, appsec) - Security"
     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 ""
 }
@@ -357,7 +306,7 @@ main() {
             cmd_start "hub"
             ;;
         *)
-            echo -e "${RED}Unknown command: $command${NC}"
+            log_error "Unknown command: $command"
             echo "Run 'forge help' for usage."
             exit 1
             ;;

package/bin/lib/agents.sh

@@ -0,0 +1,157 @@
+#!/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]:-}"
+}

package/bin/lib/colors.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+#
+# Vibe Forge - Shared Color Definitions and Logging
+# Source this file in other scripts: source "$SCRIPT_DIR/lib/colors.sh"
+#
+
+# Colors (only if terminal supports them)
+if [[ -t 1 ]]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[1;33m'
+    BLUE='\033[0;34m'
+    CYAN='\033[0;36m'
+    NC='\033[0m'
+else
+    RED=''
+    GREEN=''
+    YELLOW=''
+    BLUE=''
+    CYAN=''
+    NC=''
+fi
+
+# Logging functions
+log_error() {
+    echo -e "${RED}Error: $1${NC}" >&2
+}
+
+log_success() {
+    echo -e "${GREEN}✓ $1${NC}"
+}
+
+log_info() {
+    echo -e "${BLUE}ℹ $1${NC}"
+}
+
+log_warn() {
+    echo -e "${YELLOW}⚠ $1${NC}"
+}
+
+log_header() {
+    echo -e "${YELLOW}$1${NC}"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+}