@cyanautomation/kaseki-agent 1.4.1

package/scripts/kaseki-maturity-score.sh

@@ -0,0 +1,291 @@
+#!/usr/bin/env bash
+# kaseki-maturity-score.sh
+# Calculates the kaseki-agent repository maturity score and outputs JSON
+# 
+# This script evaluates the repository against 9 maturity signal categories:
+# 1. Setup & Installation
+# 2. Testing & Quality  
+# 3. CI/CD & Automation
+# 4. Documentation
+# 5. Governance
+# 6. Security
+# 7. Operability
+# 8. Performance & Efficiency
+# 9. Maintenance & Sustainability
+#
+# Usage: kaseki-maturity-score.sh [repo_path] [output_json_file]
+# Default: uses /workspace/repo and outputs to /results/maturity-score.json
+
+set -euo pipefail
+
+REPO_PATH="${1:-.}"
+OUTPUT_FILE="${2:-/results/maturity-score.json}"
+
+# Score tracking variables
+SETUP_SCORE=0
+TESTING_SCORE=0
+CICD_SCORE=0
+DOCS_SCORE=0
+GOVERNANCE_SCORE=0
+SECURITY_SCORE=0
+OPERABILITY_SCORE=0
+PERFORMANCE_SCORE=0
+MAINTENANCE_SCORE=0
+
+evaluate_setup() {
+  local score=0
+  
+  # Check for package.json (1 point)
+  [ -f "$REPO_PATH/package.json" ] && score=$((score + 1))
+  
+  # Check for package-lock.json (1 point)
+  [ -f "$REPO_PATH/package-lock.json" ] && score=$((score + 1))
+  
+  # Check for TypeScript config (1 point)
+  [ -f "$REPO_PATH/tsconfig.json" ] && score=$((score + 1))
+  
+  # Check for Dockerfile (1 point)
+  [ -f "$REPO_PATH/Dockerfile" ] && score=$((score + 1))
+  
+  # Check for README (1 point)
+  [ -f "$REPO_PATH/README.md" ] && score=$((score + 1))
+  
+  # Check for .gitignore (1 point)
+  [ -f "$REPO_PATH/.gitignore" ] && score=$((score + 1))
+  
+  # Check for Node.js version pinned in Dockerfile (1 point)
+  grep -q "node:" "$REPO_PATH/Dockerfile" 2>/dev/null && score=$((score + 1))
+  
+  SETUP_SCORE="$score"
+}
+
+evaluate_testing() {
+  local score=0
+  
+  # Check for jest/test config (1 point)
+  [ -f "$REPO_PATH/jest.config.ts" ] || [ -f "$REPO_PATH/jest.config.js" ] && score=$((score + 1))
+  
+  # Check for test directory (1 point)
+  [ -d "$REPO_PATH/test" ] && score=$((score + 1))
+  
+  # Check for src test files (1 point)
+  find "$REPO_PATH/src" -name "*.test.ts" -o -name "*.test.js" 2>/dev/null | grep -q . && score=$((score + 1))
+  
+  # Check for ESLint config (1 point)
+  [ -f "$REPO_PATH/.eslintrc" ] || [ -f "$REPO_PATH/.eslintrc.json" ] || [ -f "$REPO_PATH/.eslintrc.js" ] && score=$((score + 1))
+  
+  # Check for TypeScript strict mode (1 point)
+  grep -q '"strict":\s*true' "$REPO_PATH/tsconfig.json" 2>/dev/null && score=$((score + 1))
+  
+  TESTING_SCORE="$score"
+}
+
+evaluate_cicd() {
+  local score=0
+  
+  # Check for GitHub Actions workflows (2 points)
+  [ -d "$REPO_PATH/.github/workflows" ] && score=$((score + 2))
+  
+  # Check for build workflow (1 point)
+  find "$REPO_PATH/.github/workflows" \( -name "*.yml" -o -name "*.yaml" \) -print0 2>/dev/null | xargs -0 grep -l "build\|docker" 2>/dev/null | grep -q . && score=$((score + 1))
+  
+  # Check for Dependabot config (1 point)
+  [ -f "$REPO_PATH/.github/dependabot.yml" ] && score=$((score + 1))
+  
+  # Check for shell linting in workflows (1 point)
+  find "$REPO_PATH/.github/workflows" -name "*.yml" -print0 2>/dev/null | xargs -0 grep -l "shellcheck" 2>/dev/null | grep -q . && score=$((score + 1))
+  
+  CICD_SCORE="$score"
+}
+
+evaluate_docs() {
+  local score=0
+  
+  # Check for CONTRIBUTING.md (1 point)
+  [ -f "$REPO_PATH/CONTRIBUTING.md" ] && score=$((score + 1))
+  
+  # Check for CLAUDE.md (1 point)
+  [ -f "$REPO_PATH/CLAUDE.md" ] && score=$((score + 1))
+  
+  # Check for docs directory (1 point)
+  [ -d "$REPO_PATH/docs" ] && score=$((score + 1))
+  
+  # Check for repo-maturity.md (1 point)
+  [ -f "$REPO_PATH/docs/repo-maturity.md" ] && score=$((score + 1))
+  
+  # Check for well-structured README (1 point)
+  grep -q "## \|### " "$REPO_PATH/README.md" 2>/dev/null && score=$((score + 1))
+  
+  DOCS_SCORE="$score"
+}
+
+evaluate_governance() {
+  local score=0
+  
+  # Check for issue templates (1 point)
+  [ -d "$REPO_PATH/.github/ISSUE_TEMPLATE" ] && [ "$(find "$REPO_PATH/.github/ISSUE_TEMPLATE" -type f | wc -l)" -gt 0 ] && score=$((score + 1))
+  
+  # Check for PR template (1 point)
+  [ -d "$REPO_PATH/.github/PULL_REQUEST_TEMPLATE" ] && [ "$(find "$REPO_PATH/.github/PULL_REQUEST_TEMPLATE" -type f | wc -l)" -gt 0 ] && score=$((score + 1))
+  
+  # Check for STYLE.md or style guide (0.5 points, counted as 1 if present)
+  [ -f "$REPO_PATH/STYLE.md" ] && score=$((score + 1))
+  
+  GOVERNANCE_SCORE="$score"
+}
+
+evaluate_security() {
+  local score=0
+  
+  # Check for Trivy scanning in CI (1.5 points, rounded to 1 or 2)
+  find "$REPO_PATH/.github/workflows" -name "*.yml" -print0 2>/dev/null | xargs -0 grep -l "trivy\|Trivy" 2>/dev/null | grep -q . && score=$((score + 2))
+  
+  # Check for no hardcoded secrets (1 point)
+  ! find "$REPO_PATH/src" -type f \( -name "*.ts" -o -name "*.js" \) -print0 2>/dev/null | xargs -0 grep -l "sk-or-\|OPENROUTER_API_KEY=" 2>/dev/null | grep -q . && score=$((score + 1))
+  
+  # Check for Dockerfile security flags (1 point)
+  grep -q "cap-drop\|read-only\|security-opt" "$REPO_PATH/Dockerfile" 2>/dev/null && score=$((score + 1))
+  
+  SECURITY_SCORE="$score"
+}
+
+evaluate_operability() {
+  local score=0
+  
+  # Check for --dry-run support (1 point)
+  grep -q "KASEKI_DRY_RUN\|--dry-run" "$REPO_PATH/run-kaseki.sh" 2>/dev/null && score=$((score + 1))
+  
+  # Check for structured logging (1 point)
+  grep -q "json_encode\|emit_progress\|emit_json_log" "$REPO_PATH/run-kaseki.sh" 2>/dev/null && score=$((score + 1))
+  
+  # Check for health check script (1 point)
+  [ -f "$REPO_PATH/scripts/kaseki-healthcheck.sh" ] && score=$((score + 1))
+  
+  # Check for metrics/timing tracking (1 point)
+  grep -q "stage-timings\|validation-timings" "$REPO_PATH/kaseki-agent.sh" 2>/dev/null && score=$((score + 1))
+  
+  OPERABILITY_SCORE="$score"
+}
+
+evaluate_performance() {
+  local score=0
+  
+  # Check for dependency caching (2 points)
+  grep -q "kaseki-cache\|KASEKI_DEPENDENCY_CACHE_DIR" "$REPO_PATH/kaseki-agent.sh" 2>/dev/null && score=$((score + 2))
+  
+  # Check for build cache in Dockerfile (1 point)
+  grep -q "cache" "$REPO_PATH/Dockerfile" 2>/dev/null && score=$((score + 1))
+  
+  # Check for multi-stage build (1 point)
+  grep -c "FROM" "$REPO_PATH/Dockerfile" 2>/dev/null | grep -q "[2-9]" && score=$((score + 1))
+  
+  PERFORMANCE_SCORE="$score"
+}
+
+evaluate_maintenance() {
+  local score=0
+  
+  # Check for SECURITY.md (1 point)
+  [ -f "$REPO_PATH/SECURITY.md" ] && score=$((score + 1))
+  
+  # Check for LICENSE (1 point)
+  [ -f "$REPO_PATH/LICENSE" ] || [ -f "$REPO_PATH/LICENSE.md" ] && score=$((score + 1))
+  
+  # Check for version consistency (1 point)
+  grep -q '"version"' "$REPO_PATH/package.json" 2>/dev/null && score=$((score + 1))
+  
+  MAINTENANCE_SCORE="$score"
+}
+
+# Run all evaluations
+evaluate_setup
+evaluate_testing
+evaluate_cicd
+evaluate_docs
+evaluate_governance
+evaluate_security
+evaluate_operability
+evaluate_performance
+evaluate_maintenance
+
+# Calculate total score
+TOTAL_SCORE=$((
+  SETUP_SCORE +
+  TESTING_SCORE +
+  CICD_SCORE +
+  DOCS_SCORE +
+  GOVERNANCE_SCORE +
+  SECURITY_SCORE +
+  OPERABILITY_SCORE +
+  PERFORMANCE_SCORE +
+  MAINTENANCE_SCORE
+))
+
+# Maximum possible score
+MAX_SCORE=50  # Calculated from all categories above
+
+# Percentage
+PERCENTAGE=$((TOTAL_SCORE * 100 / MAX_SCORE))
+
+# Output JSON
+mkdir -p "$(dirname "$OUTPUT_FILE")"
+cat > "$OUTPUT_FILE" <<EOF
+{
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "total_score": $TOTAL_SCORE,
+  "max_score": $MAX_SCORE,
+  "percentage": $PERCENTAGE,
+  "rating": "$(
+    if [ $TOTAL_SCORE -ge 45 ]; then
+      echo "Exemplary"
+    elif [ $TOTAL_SCORE -ge 40 ]; then
+      echo "Mature"
+    elif [ $TOTAL_SCORE -ge 30 ]; then
+      echo "Capable"
+    else
+      echo "Developing"
+    fi
+  )",
+  "categories": {
+    "setup_and_installation": {
+      "score": $SETUP_SCORE,
+      "max": 7
+    },
+    "testing_and_quality": {
+      "score": $TESTING_SCORE,
+      "max": 5
+    },
+    "cicd_and_automation": {
+      "score": $CICD_SCORE,
+      "max": 5
+    },
+    "documentation": {
+      "score": $DOCS_SCORE,
+      "max": 5
+    },
+    "governance": {
+      "score": $GOVERNANCE_SCORE,
+      "max": 3
+    },
+    "security": {
+      "score": $SECURITY_SCORE,
+      "max": 4
+    },
+    "operability": {
+      "score": $OPERABILITY_SCORE,
+      "max": 4
+    },
+    "performance_and_efficiency": {
+      "score": $PERFORMANCE_SCORE,
+      "max": 4
+    },
+    "maintenance_and_sustainability": {
+      "score": $MAINTENANCE_SCORE,
+      "max": 3
+    }
+  }
+}
+EOF
+
+# Output to stdout as well
+cat "$OUTPUT_FILE"

package/scripts/kaseki-performance-metrics.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# kaseki-performance-metrics.sh
+# Analyzes stage timings and generates performance benchmarks
+#
+# Reads the stage-timings.tsv file and generates a performance report
+# in JSON format with summary statistics and percentiles
+#
+# Usage: kaseki-performance-metrics.sh <stage_timings_tsv> [output_json]
+# Default output: /results/performance-metrics.json
+
+set -euo pipefail
+
+STAGE_TIMINGS_FILE="${1:-/results/stage-timings.tsv}"
+OUTPUT_FILE="${2:-/results/performance-metrics.json}"
+
+if [ ! -f "$STAGE_TIMINGS_FILE" ]; then
+  echo '{"error": "stage-timings.tsv not found"}' > "$OUTPUT_FILE"
+  exit 1
+fi
+
+# Parse stage timings and calculate metrics
+TOTAL_TIME=0
+STAGE_COUNT=0
+declare -a DURATIONS
+
+while IFS=$'\t' read -r stage _exit_code duration _detail; do
+  [ -z "$stage" ] && continue
+  [ -z "$duration" ] && continue
+  
+  DURATIONS+=("$duration")
+  TOTAL_TIME=$((TOTAL_TIME + duration))
+  STAGE_COUNT=$((STAGE_COUNT + 1))
+done < "$STAGE_TIMINGS_FILE"
+
+# Calculate statistics
+if [ "$STAGE_COUNT" -eq 0 ]; then
+  cat > "$OUTPUT_FILE" <<EOF
+{
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "total_stages": 0,
+  "total_duration_seconds": 0,
+  "average_stage_duration_seconds": 0,
+  "status": "no_data"
+}
+EOF
+  exit 0
+fi
+
+AVG_DURATION=$((TOTAL_TIME / STAGE_COUNT))
+
+# Sort durations for percentile calculation
+mapfile -t sorted_durations < <(printf '%s\n' "${DURATIONS[@]}" | sort -n)
+
+# Calculate percentiles
+P50_INDEX=$((STAGE_COUNT * 50 / 100))
+P90_INDEX=$((STAGE_COUNT * 90 / 100))
+P95_INDEX=$((STAGE_COUNT * 95 / 100))
+P99_INDEX=$((STAGE_COUNT * 99 / 100))
+
+# Handle edge cases
+[ $P50_INDEX -eq 0 ] && P50_INDEX=0
+[ $P90_INDEX -ge $STAGE_COUNT ] && P90_INDEX=$((STAGE_COUNT - 1))
+[ $P95_INDEX -ge $STAGE_COUNT ] && P95_INDEX=$((STAGE_COUNT - 1))
+[ $P99_INDEX -ge $STAGE_COUNT ] && P99_INDEX=$((STAGE_COUNT - 1))
+
+P50="${sorted_durations[$P50_INDEX]:-0}"
+P90="${sorted_durations[$P90_INDEX]:-0}"
+P95="${sorted_durations[$P95_INDEX]:-0}"
+P99="${sorted_durations[$P99_INDEX]:-0}"
+
+MIN_DURATION="${sorted_durations[0]:-0}"
+MAX_DURATION="${sorted_durations[$((STAGE_COUNT - 1))]:-0}"
+
+# Determine performance rating
+if [ "$TOTAL_TIME" -lt 300 ]; then
+  RATING="Excellent"
+elif [ "$TOTAL_TIME" -lt 600 ]; then
+  RATING="Good"
+elif [ "$TOTAL_TIME" -lt 1200 ]; then
+  RATING="Acceptable"
+else
+  RATING="Slow"
+fi
+
+# Generate output JSON
+mkdir -p "$(dirname "$OUTPUT_FILE")"
+cat > "$OUTPUT_FILE" <<EOF
+{
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "summary": {
+    "total_stages": $STAGE_COUNT,
+    "total_duration_seconds": $TOTAL_TIME,
+    "average_stage_duration_seconds": $AVG_DURATION,
+    "min_stage_duration_seconds": $MIN_DURATION,
+    "max_stage_duration_seconds": $MAX_DURATION,
+    "rating": "$RATING"
+  },
+  "percentiles": {
+    "p50_seconds": $P50,
+    "p90_seconds": $P90,
+    "p95_seconds": $P95,
+    "p99_seconds": $P99
+  },
+  "recommendations": [
+    $(
+      if [ "$MAX_DURATION" -gt 300 ]; then
+        echo '"Consider optimizing stages taking >5 minutes",'
+      fi
+      if [ "$P99" -gt 60 ]; then
+        echo '"Some stages exceed 1 minute; review for parallelization",'
+      fi
+      if [ "$AVG_DURATION" -gt 30 ]; then
+        echo '"Average stage duration is high; profile for bottlenecks",'
+      fi
+      echo '"Good performance baseline"'
+    )
+  ]
+}
+EOF
+
+# Print to stdout as well
+cat "$OUTPUT_FILE"

package/scripts/kaseki-preflight.sh

@@ -0,0 +1,270 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+mode="${1:-run}"
+output_format="text"  # text or json
+guide_mode=0          # 0 or 1
+
+# Parse flags
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --json)
+      output_format="json"
+      shift
+      ;;
+    --guide)
+      guide_mode=1
+      shift
+      ;;
+    run|doctor)
+      mode="$1"
+      shift
+      ;;
+    *)
+      printf 'Error: unknown flag or mode: %s\n' "$1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+required_bins=(docker)
+optional_bins=()
+case "$mode" in
+  run)
+    optional_bins=(curl wget sshpass git node npm)
+    ;;
+  doctor)
+    optional_bins=(curl wget sshpass git node npm)
+    ;;
+  *)
+    printf 'Error: unknown preflight mode: %s\n' "$mode" >&2
+    exit 2
+    ;;
+esac
+
+missing_required=()
+missing_optional=()
+
+for bin in "${required_bins[@]}"; do
+  if ! command -v "$bin" >/dev/null 2>&1; then
+    missing_required+=("$bin")
+  fi
+done
+
+for bin in "${optional_bins[@]}"; do
+  if ! command -v "$bin" >/dev/null 2>&1; then
+    missing_optional+=("$bin")
+  fi
+done
+
+# Detect OS for install suggestions
+detect_os() {
+  if [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    if [ -f /etc/os-release ]; then
+      # shellcheck disable=SC1091
+      . /etc/os-release
+      case "$ID" in
+        debian|ubuntu|raspbian)
+          echo "debian"
+          ;;
+        fedora|centos|rhel)
+          echo "fedora"
+          ;;
+        arch|manjaro)
+          echo "arch"
+          ;;
+        *)
+          echo "linux"
+          ;;
+      esac
+    else
+      echo "linux"
+    fi
+  elif [[ "$OSTYPE" == "darwin"* ]]; then
+    echo "macos"
+  else
+    echo "unknown"
+  fi
+}
+
+# Get install command for detected OS
+get_install_command() {
+  local bin="$1"
+  local detected_os
+  detected_os="$(detect_os)"
+  
+  case "$detected_os" in
+    debian)
+      case "$bin" in
+        docker) echo "sudo apt update && sudo apt install -y docker.io" ;;
+        git) echo "sudo apt install -y git" ;;
+        curl) echo "sudo apt install -y curl" ;;
+        wget) echo "sudo apt install -y wget" ;;
+        node|npm) echo "curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - && sudo apt install -y nodejs" ;;
+        sshpass) echo "sudo apt install -y sshpass" ;;
+        *) echo "sudo apt install -y $bin" ;;
+      esac
+      ;;
+    fedora)
+      case "$bin" in
+        docker) echo "sudo dnf install -y docker" ;;
+        git) echo "sudo dnf install -y git" ;;
+        curl) echo "sudo dnf install -y curl" ;;
+        wget) echo "sudo dnf install -y wget" ;;
+        node|npm) echo "curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash - && sudo dnf install -y nodejs" ;;
+        sshpass) echo "sudo dnf install -y sshpass" ;;
+        *) echo "sudo dnf install -y $bin" ;;
+      esac
+      ;;
+    arch)
+      case "$bin" in
+        docker) echo "sudo pacman -S --needed docker" ;;
+        git) echo "sudo pacman -S --needed git" ;;
+        curl) echo "sudo pacman -S --needed curl" ;;
+        wget) echo "sudo pacman -S --needed wget" ;;
+        node|npm) echo "sudo pacman -S --needed nodejs npm" ;;
+        sshpass) echo "sudo pacman -S --needed sshpass" ;;
+        *) echo "sudo pacman -S --needed $bin" ;;
+      esac
+      ;;
+    macos)
+      case "$bin" in
+        docker) echo "brew install --cask docker" ;;
+        git) echo "brew install git" ;;
+        curl) echo "brew install curl" ;;
+        wget) echo "brew install wget" ;;
+        node|npm) echo "brew install node" ;;
+        sshpass) echo "brew install sshpass" ;;
+        *) echo "brew install $bin" ;;
+      esac
+      ;;
+    *)
+      echo "Please install $bin manually"
+      ;;
+  esac
+}
+
+# Output helpers
+output_text_mode() {
+  if [ "${#missing_required[@]}" -gt 0 ]; then
+    printf 'Error: missing required host dependencies: %s\n' "$(IFS=', '; echo "${missing_required[*]}")" >&2
+    printf 'Install them, then re-run ./run-kaseki.sh.\n' >&2
+    return 1
+  fi
+  
+  printf 'Preflight required dependencies: ok (%s)\n' "$(IFS=', '; echo "${required_bins[*]}")"
+  if [ "${#missing_optional[@]}" -eq 0 ]; then
+    printf 'Preflight optional dependencies: ok (%s)\n' "$(IFS=', '; echo "${optional_bins[*]}")"
+  else
+    printf 'Preflight optional dependencies: missing (%s)\n' "$(IFS=', '; echo "${missing_optional[*]}")"
+  fi
+  
+  return 0
+}
+
+output_json_mode() {
+  local status="ready"
+  [ "${#missing_required[@]}" -gt 0 ] && status="failed"
+  
+  # Build JSON output
+  cat <<EOF
+{
+  "status": "$status",
+  "required_ok": $([[ ${#missing_required[@]} -eq 0 ]] && echo "true" || echo "false"),
+  "optional_ok": $([[ ${#missing_optional[@]} -eq 0 ]] && echo "true" || echo "false"),
+  "required_bins": $(printf '%s\n' "${required_bins[@]}" | jq -sR -c 'split("\n")[:-1]'),
+  "optional_bins": $(printf '%s\n' "${optional_bins[@]}" | jq -sR -c 'split("\n")[:-1]'),
+  "missing_required": $(printf '%s\n' "${missing_required[@]}" | jq -sR -c 'split("\n")[:-1]'),
+  "missing_optional": $(printf '%s\n' "${missing_optional[@]}" | jq -sR -c 'split("\n")[:-1]'),
+  "detected_os": "$(detect_os)"
+}
+EOF
+  
+  [ "${#missing_required[@]}" -gt 0 ] && return 1 || return 0
+}
+
+output_guide_mode() {
+  echo "╔════════════════════════════════════════════════════════════╗"
+  echo "║          Kaseki Agent Preflight Guide                       ║"
+  echo "╚════════════════════════════════════════════════════════════╝"
+  echo ""
+  
+  local detected_os
+  detected_os="$(detect_os)"
+  echo "System Information:"
+  echo "  OS: $detected_os"
+  echo "  Shell: $SHELL"
+  echo ""
+  
+  # Check required dependencies
+  echo "Required Dependencies:"
+  for bin in "${required_bins[@]}"; do
+    if command -v "$bin" >/dev/null 2>&1; then
+      echo "  ✓ $bin"
+    else
+      echo "  ✗ $bin (MISSING)"
+      local install_cmd
+      install_cmd=$(get_install_command "$bin")
+      echo "    Install: $install_cmd"
+    fi
+  done
+  echo ""
+  
+  # Check optional dependencies
+  echo "Optional Dependencies:"
+  for bin in "${optional_bins[@]}"; do
+    if command -v "$bin" >/dev/null 2>&1; then
+      echo "  ✓ $bin"
+    else
+      echo "  ○ $bin (optional, not found)"
+      local install_cmd
+      install_cmd=$(get_install_command "$bin")
+      echo "    Install: $install_cmd"
+    fi
+  done
+  echo ""
+  
+  # Summary and next steps
+  if [ "${#missing_required[@]}" -gt 0 ]; then
+    echo "⚠ Action Required:"
+    echo "  Install missing required dependencies:"
+    for bin in "${missing_required[@]}"; do
+      local install_cmd
+      install_cmd=$(get_install_command "$bin")
+      echo "    $install_cmd"
+    done
+    echo ""
+    echo "  After installing, run: ./run-kaseki.sh --doctor"
+    return 1
+  else
+    echo "✓ All required dependencies are installed!"
+    if [ "${#missing_optional[@]}" -gt 0 ]; then
+      echo ""
+      echo "⚠ Note: Some optional dependencies are missing:"
+      for bin in "${missing_optional[@]}"; do
+        echo "    - $bin"
+      done
+      echo "  These are optional but recommended for full functionality."
+    fi
+    return 0
+  fi
+}
+
+# Route to appropriate output mode
+case "$output_format" in
+  json)
+    output_json_mode
+    ;;
+  text)
+    if [ "$guide_mode" -eq 1 ]; then
+      output_guide_mode
+    else
+      output_text_mode
+    fi
+    ;;
+  *)
+    printf 'Error: unknown output format: %s\n' "$output_format" >&2
+    exit 2
+    ;;
+esac
+