Setup Command

Interactive setup wizard for automated dependency management.

Overview

The setup command provides a comprehensive, Renovate-like setup experience that guides you through configuring Buddy for your project. It automates the entire process from repository detection to workflow generation.

buddy setup [options]

Quick Start

# Interactive setup (recommended)
buddy setup

# Setup with verbose logging
buddy setup --verbose

# Non-interactive setup with defaults
buddy setup --non-interactive

# Non-interactive with specific preset and token setup
buddy setup --non-interactive --preset testing --token-setup new-pat --verbose

Enhanced Features

The setup wizard provides a comprehensive configuration experience with advanced validation:

Core Features

• 🔍 Automatic Repository Detection - Detects GitHub repository from git remote with API validation
• 🔑 Enhanced Token Setup - Comprehensive PAT guidance with scope validation and testing
• 🔧 Repository Settings Validation - Real-time GitHub Actions permissions verification
• ⚙️ Intelligent Workflow Presets - Smart recommendations based on project analysis
• 📝 Project-Aware Configuration - Optimized settings based on detected project characteristics
• 🔄 Validated Workflow Creation - YAML validation and security best practices verification
• 🎯 Comprehensive Instructions - Complete setup verification and troubleshooting guidance

Advanced Enhancements

• 🛡️ Pre-flight Validation - Environment checks, conflict detection, and prerequisite validation
• 📊 Smart Project Analysis - Automatic detection of project type, package manager, and ecosystem
• 📈 Interactive Progress Tracking - Visual progress indicators with step-by-step guidance
• 🔍 Repository Health Checks - API-based validation of repository access and permissions
• ⚙️ Workflow Validation - Real-time YAML syntax and security validation
• 🚀 Recovery Capabilities - Detailed error reporting and setup resumption support
• 📋 Configuration Migration - Seamless import from Renovate and Dependabot configurations
• 🔌 Integration Ecosystem - Extensible plugin system with Slack, Discord, and Jira integrations

Setup Flow

Configuration Migration & Discovery

🔍 Configuration Migration Detection:
Found 1 existing dependency management tool(s):
   • renovate (renovate.json)

📋 Migrating configurations...
✅ Migrated renovate configuration

📋 Configuration Migration Report

## RENOVATE Migration

- **Config Found**: ✅ Yes
- **Confidence**: 🟢 high
- **Migrated Settings**: schedule, packages, ignore, autoMerge, assignees, reviewers

Migration Features:

• Tool Detection - Automatically discovers Renovate (renovate.json, .renovaterc, package.json) and Dependabot (.github/dependabot.yml) configurations
• Smart Conversion - Maps Renovate package rules to Buddy groups, converts schedules to workflow presets, and preserves team assignments
• Compatibility Analysis - Identifies unsupported features like extends presets and regexManagers, provides alternatives and workarounds
• Migration Report - Detailed summary with confidence levels, migrated settings, warnings, and incompatible features

Supported Migrations:

• Renovate: Schedule patterns, package rules, ignore lists, automerge settings, assignees/reviewers
• Dependabot: Update intervals, ignore patterns, package ecosystem configurations
• Confidence Scoring: High (direct mapping), Medium (partial support), Low (significant incompatibilities)

Integration Discovery

🔌 Integration Discovery:
Found 2 available integration(s):
   • slack-integration v1.0.0
   • discord-integration v1.0.0

🔌 Executing integration hooks...
✅ Executed hook: notify-slack
✅ Executed hook: notify-discord

Plugin Discovery:

• Environment Detection - Scans for SLACK_WEBHOOK_URL, DISCORD_WEBHOOK_URL, JIRA_API_TOKEN environment variables
• File-Based Configuration - Checks .buddy/slack-webhook, .buddy/discord-webhook, .buddy/jira-config.json files
• Custom Plugins - Loads plugins from .buddy/plugins/*.json directory with error handling
• Integration Loading - Automatically enables discovered integrations for setup completion notifications

Built-in Integrations:

• Slack: Rich setup completion messages with repository details and project information
• Discord: Colorful embed notifications with project type and package manager details
• Jira: Automatic ticket creation for tracking setup completion with project context

Pre-flight Validation

🔍 Pre-flight Validation
✅ Git repository detected
✅ Bun v1.2.19 detected
⚠️  Found 2 existing workflows. Some may conflict with Buddy workflows.
💡 GitHub CLI detected. This can help with authentication.

Environment Checks:

• Git repository validation - Ensures you're in a git repository with proper remote configuration
• Runtime environment - Validates Node.js or Bun installation for optimal performance
• Git configuration - Checks for user.name and user.email configuration
• GitHub CLI detection - Identifies helpful tools for authentication and setup

Conflict Detection:

• Existing workflows - Scans .github/workflows/ for potential conflicts
• Dependency management tools - Detects Renovate, Dependabot, or other dependency managers
• Configuration conflicts - Identifies existing configuration that might interfere

Smart Project Analysis

🔍 Project Analysis:
📦 Project Type: application
⚙️  Package Manager: bun
🔒 Lock File: Found
📄 Dependency Files: Found
🔄 GitHub Actions: Found
💡 Recommended Preset: Standard Setup

📋 Recommendations:
   • Bun detected. Optimal performance expected.
   • Dependency files detected. Multi-format support enabled.
   • 3 existing workflow(s) found. GitHub Actions updates will be included.

Project Intelligence:

• Project type detection - Identifies library, application, monorepo based on package.json and file structure
• Package manager analysis - Detects Bun, npm, yarn, pnpm with lock file validation
• Dependency ecosystem - Finds pkgx.yaml, deps.yaml, and Launchpad dependency files
• GitHub Actions discovery - Scans existing workflows for update integration
• Smart recommendations - Suggests optimal configuration based on detected characteristics

Interactive Progress Tracking

📊 Setup Progress: 75% [███████████████░░░░░]
🔄 Current Step: Workflow Generation (6/8)
✅ Completed: Pre-flight checks, Project analysis, Repository Detection, GitHub Token Setup, Repository Settings

Progress Features:

• Visual progress bar - Real-time completion percentage with graphical indicators
• Step tracking - Clear indication of current step and total progress
• Completion history - Shows which steps have been successfully completed
• Time tracking - Monitors setup duration for performance insights
• Recovery support - Maintains progress state for resumption after interruptions

Step 3: Repository Detection & Validation

📍 Step 1: Repository Detection
✅ Detected repository: your-org/your-repo
🔗 GitHub URL: https://github.com/your-org/your-repo

Automatically detects your GitHub repository from git remote get-url origin and performs comprehensive validation:

Enhanced Repository Validation:

• API connectivity - Tests GitHub API access and repository permissions
• Repository health - Validates issues are enabled, repository is accessible, and permissions are adequate
• Private repository support - Enhanced validation for private repositories with appropriate token scopes
• Organization settings - Checks for organization-level restrictions that might affect setup

Step 4: GitHub Token Setup

🔑 Step 2: GitHub Token Setup
For full functionality, Buddy needs a Personal Access Token (PAT).
This enables workflow file updates and advanced GitHub Actions features.

Provides three options:

• Create new token - Full guidance through PAT creation process
• Have existing token - Setup for existing PAT
• Skip for now - Use limited GITHUB_TOKEN permissions

Step 5: Repository Settings

🔧 Step 3: Repository Settings

Guides you through configuring GitHub Actions permissions:

1. Repository settings → Actions → General
2. Select "Read and write permissions"
3. Enable "Allow GitHub Actions to create and approve pull requests"

Step 6: Workflow Configuration

⚙️ Step 4: Workflow Configuration
What type of update schedule would you like?

Choose from carefully crafted presets:

Available Presets

Step 7: Configuration File Generation

📝 Step 5: Configuration File
✅ Created buddy.config.json with your repository settings.
💡 You can edit this file to customize Buddy's behavior.

Creates a complete configuration file with:

• Repository information
• Dashboard settings
• Workflow templates
• Package strategies
• Default options

Step 8: Workflow Generation

🔄 Step 6: Workflow Generation
✨ Setting up Standard Setup...
📋 Dashboard updates 3x/week, balanced dependency updates

Generates three core workflows:

1. Dashboard Workflow (buddy-dashboard.yml)

• Schedule: Monday, Wednesday, Friday at 9 AM UTC
• Purpose: Manages dependency dashboard issue
• Features: Manual triggers, dry-run mode, verbose logging

2. Update Check Workflow (buddy-check.yml)

• Schedule: Every 15 minutes
• Purpose: Auto-rebase PRs with checked rebase boxes
• Features: Automatic PR updates, conflict resolution

3. Update Workflow (buddy-update.yml)

• Schedule: Based on selected preset
• Purpose: Scheduled dependency updates
• Features: Manual triggers, strategy selection, package filtering

Workflow Validation & Testing

🔍 Validating Generated Workflows
✅ buddy-dashboard.yml validated successfully
✅ buddy-check.yml validated successfully
✅ buddy-update.yml validated successfully

Validation Features:

• YAML syntax validation - Ensures all generated workflows are syntactically correct
• Required field verification - Validates presence of name, on, jobs, and other essential fields
• Security best practices - Checks token usage, permissions, and security configurations
• Buddy integration - Verifies workflows include proper buddy execution commands
• Permission validation - Ensures workflows have appropriate permissions for their functions

Security Validation:

• Token scope verification - Validates GITHUB_TOKEN vs BUDDY_TOKEN usage
• Permission matrix - Ensures workflows have minimum required permissions
• Secret handling - Validates secure handling of tokens and sensitive information
• Workflow permissions - Checks for explicit permission definitions and security boundaries

Step 9: Final Instructions & Integration Notifications

🎉 Setup Complete!
✅ Generated 3 core workflows in .github/workflows/:

   - buddy-dashboard.yml (Dependency Dashboard Management)
   - buddy-check.yml (Auto-rebase PR checker)
   - buddy-update.yml (Scheduled dependency updates)

📁 Configuration file: buddy.config.json

Provides clear next steps with:

• Git commands for committing changes
• Token setup instructions (if needed)
• Repository permissions configuration
• Links to GitHub settings pages

Integration Notifications:

• Slack Messages - Rich setup completion notifications with repository details, project type, and package manager information
• Discord Embeds - Colorful setup completion embeds with project metadata and timestamp tracking
• Jira Tickets - Automatic task creation for tracking and documenting setup completion
• Custom Hooks - Extensible plugin system for organization-specific notifications and integrations

Command Options

Non-Interactive Mode

For CI/CD pipelines, automated deployments, or when you want to use defaults, the non-interactive mode allows setup without prompts:

Basic Non-Interactive Setup

# Use all defaults (standard preset with default token)
buddy setup --non-interactive

This will:

• ✅ Use the standard preset for workflow configuration
• ✅ Use default-token mode (GITHUB_TOKEN with limited functionality)
• ✅ Skip all interactive prompts and confirmations
• ✅ Still perform migration detection and integration discovery
• ✅ Generate all necessary files with sensible defaults

Advanced Non-Interactive Options

# High-frequency testing setup with verbose output
buddy setup --non-interactive --preset testing --verbose

# Security-focused setup with custom token
buddy setup --non-interactive --preset security --token-setup new-pat

# Standard setup using existing organization secrets
buddy setup --non-interactive --preset standard --token-setup existing-secret

Non-Interactive Behavior

When --non-interactive is enabled:

Token Setup Modes

default-token (Default)

buddy setup --non-interactive --token-setup default-token

• Uses GITHUB_TOKEN provided by GitHub Actions
• Limited functionality (cannot update workflow files)
• Suitable for basic dependency updates
• No additional setup required

existing-secret

buddy setup --non-interactive --token-setup existing-secret

• Assumes BUDDY_TOKEN secret already exists
• Full functionality including workflow file updates
• Suitable for organizations with pre-configured secrets
• Best for production environments

new-pat

buddy setup --non-interactive --token-setup new-pat

• Configures for custom Personal Access Token
• Generates workflows that use BUDDY_TOKEN
• Requires manual token creation and secret setup
• Provides warnings about manual steps needed

Preset Options

Standard Preset

buddy setup --non-interactive --preset standard

• Balanced approach for most projects
• Every 2 hours schedule for testing
• Dry-run enabled by default
• Manual triggers available

Testing Preset

buddy setup --non-interactive --preset testing

• Optimized for development and testing
• Every 2 hours schedule with enhanced logging
• Dry-run mode by default
• Verbose output and detailed summaries

Security Preset

buddy setup --non-interactive --preset security

• Security-focused configuration
• Every 2 hours schedule for rapid security updates
• Enhanced monitoring and reporting
• Security-first update strategy

High-Frequency Preset

buddy setup --non-interactive --preset high-frequency

• Multiple updates per day
• Every 2 hours schedule
• Aggressive update strategy
• Suitable for active development

Minimal Preset

buddy setup --non-interactive --preset minimal

• Low-frequency updates
• Every 2 hours schedule (same as others)
• Conservative approach
• Minimal noise and disruption

CI/CD Integration Examples

GitHub Actions Workflow

name: Setup Buddy
on:
  workflow_dispatch:
    inputs:
      preset:
        description: 'Workflow preset'
        required: false
        default: 'standard'
        type: choice
        options:

          - standard
          - high-frequency
          - security
          - minimal
          - testing

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:

      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - name: Setup Buddy

        run: |
          bunx @buddysh/buddy setup \
            --non-interactive \
            --preset ${{ github.event.inputs.preset || 'standard' }} \
            --token-setup existing-secret \
            --verbose
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Docker Container Setup

FROM oven/bun:latest

WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install

# Non-interactive setup for containerized environments
RUN bunx @buddysh/buddy setup \
    --non-interactive \
    --preset minimal \
    --token-setup default-token \
    --verbose

Shell Script Automation

# !/bin/bash
# setup-buddy.sh

set -e

echo "Setting up Buddy for repository..."

# Check if we're in a git repository
if ! git rev-parse --git-dir > /dev/null 2>&1; then
    echo "Error: Not in a git repository"
    exit 1
fi

# Determine preset based on environment
PRESET="standard"
if [[ "$ENVIRONMENT" == "development" ]]; then
    PRESET="testing"
elif [[ "$ENVIRONMENT" == "production" ]]; then
    PRESET="security"
fi

# Run non-interactive setup
bunx @buddysh/buddy setup \
    --non-interactive \
    --preset "$PRESET" \
    --token-setup existing-secret \
    --verbose

echo "Buddy setup complete!"

Generated Files

The setup process creates several files:

Configuration File (buddy.config.json)

{
  "repository": {
    "owner": "your-org",
    "name": "your-repo",
    "provider": "github"
  },
  "dashboard": {
    "enabled": true,
    "pin": false,
    "title": "Dependency Dashboard"
  },
  "workflows": {
    "enabled": true,
    "outputDir": ".github/workflows",
    "templates": {
      "daily": true,
      "weekly": true,
      "monthly": true
    }
  },
  "packages": {
    "strategy": "all",
    "ignore": []
  },
  "verbose": false
}

Workflow Files

Dashboard Workflow

name: Buddy Dashboard

on:
  schedule:

    - cron: '0 9 _ _ 1,3,5' # Monday, Wednesday, Friday at 9 AM UTC

  workflow_dispatch: # Manual triggering

Update Check Workflow

name: Buddy Check

on:
  schedule:

    - cron: '_/15 _ _ _ _' # Check every 15 minutes

  workflow_dispatch: # Manual trigger

Update Workflow

name: Buddy Update

on:
  schedule:

    - cron: '0 9 _ * 1,3,5' # Mon, Wed, Fri

  workflow_dispatch: # Manual trigger with options

Token Setup Guide

Creating a Personal Access Token

1. Go to GitHub Settings

   https://github.com/settings/tokens
   

2. Generate New Token

   • Click "Generate new token"
   • Give it a descriptive name (e.g., "buddy-token")

3. Select Required Scopes

   • ✅ repo - Full control of private repositories
   • ✅ workflow - Read and write permissions for GitHub Actions

4. Copy Token

   • Copy the generated token immediately
   • You won't be able to see it again

5. Add Repository Secret

   https://github.com/your-org/your-repo/settings/secrets/actions
   

   • Click "New repository secret"
   • Name: BUDDY_TOKEN
   • Value: Your generated token
   • Click "Add secret"

Token Benefits

Repository Settings

Configure GitHub Actions permissions:

1. Repository Settings

   https://github.com/your-org/your-repo/settings/actions
   

2. Workflow Permissions

   • Select "Read and write permissions"
   • ✅ Check "Allow GitHub Actions to create and approve pull requests"
   • Click "Save"

3. Organization Settings (if applicable)

   https://github.com/organizations/your-org/settings/actions
   

   • Configure the same permissions as above
   • Organization settings may override repository settings

Preset Details

Standard Setup (Recommended)

• Dashboard: Monday, Wednesday, Friday at 9 AM UTC
• Updates: Monday, Wednesday, Friday at 9 AM UTC
• Strategy: All updates (major, minor, patch)
• Auto-merge: Disabled (manual review required)
• Best for: Most projects wanting balanced automation

High Frequency

• Dashboard: Daily at 9 AM UTC
• Updates: Every 6 hours
• Strategy: All updates
• Auto-merge: Disabled
• Best for: Active projects needing quick updates

Security Focused

• Dashboard: Daily at 9 AM UTC
• Updates: Every 4 hours
• Strategy: All updates
• Auto-merge: Disabled
• Best for: Security-critical applications

Minimal Updates

• Dashboard: Weekly on Monday at 9 AM UTC
• Updates: Monday only at 9 AM UTC
• Strategy: All updates
• Auto-merge: Disabled
• Best for: Stable projects with low change frequency

Development/Testing

• Dashboard: Manual trigger only
• Updates: Every 15 minutes
• Strategy: Patch updates only
• Auto-merge: Disabled
• Best for: Testing Buddy functionality

Post-Setup

After running setup, follow these steps:

1. Review Generated Files

# Check configuration
cat buddy.config.json

# Review workflows
ls -la .github/workflows/

2. Test Setup

# Test repository detection
buddy scan --verbose

# Test dashboard creation
buddy dashboard --dry-run

3. Commit Changes

# Add generated files
git add .github/workflows/ buddy.config.json

# Commit setup
git commit -m "Add Buddy dependency management workflows"

# Push to repository
git push

4. Verify Workflows

1. Go to repository Actions tab
2. Verify workflows appear in the list
3. Test manual trigger on dashboard workflow
4. Check workflow permissions if needed

Troubleshooting

Setup Issues

"Not a git repository" error:

# Ensure you're in a git repository
git status

# Initialize if needed
git init
git remote add origin https://github.com/your-org/your-repo.git

"Could not detect repository" error:

# Check git remote
git remote get-url origin

# Should return: https://github.com/your-org/your-repo.git
# or: [email protected]:your-org/your-repo.git

Permission Issues

"GitHub Actions is not permitted" error:

1. Check repository settings → Actions → General
2. Ensure "Read and write permissions" is selected
3. Enable "Allow GitHub Actions to create and approve pull requests"
4. Check organization settings if applicable

Workflow files not updating:

1. Ensure BUDDY_TOKEN secret is set
2. Verify token has workflow scope
3. Check repository permissions above

Token Issues

"Bad credentials" error:

1. Verify GITHUB_TOKEN or BUDDY_TOKEN is set
2. Check token hasn't expired
3. Ensure token has required scopes (repo, workflow)

Examples

Interactive Setup

# Standard interactive setup (recommended for first-time users)
buddy setup

# Interactive setup with detailed logging
buddy setup --verbose

Non-Interactive Setup

# Basic non-interactive setup (uses defaults)
buddy setup --non-interactive

# Non-interactive with specific preset
buddy setup --non-interactive --preset testing --verbose

# Production setup with existing secrets
buddy setup --non-interactive --preset security --token-setup existing-secret

# Development setup with new token
buddy setup --non-interactive --preset testing --token-setup new-pat --verbose

Testing Setup Locally

# Test repository detection
buddy setup --verbose

# Test non-interactive flow
buddy setup --non-interactive --preset testing --verbose

# If setup completes, test scanning
buddy scan --dry-run

Technical Implementation

Enhanced Setup Architecture

The enhanced setup command implements several advanced systems for a robust configuration experience:

Pre-flight Validation System

interface ValidationResult {
  success: boolean
  errors: string[]
  warnings: string[]
  suggestions: string[]
}

Environment Validation:

• Git repository checks - Validates .git directory and remote configuration
• Runtime environment - Detects and validates Node.js/Bun installation
• Configuration validation - Checks git user.name and user.email settings
• Tool detection - Identifies GitHub CLI and other helpful development tools

Conflict Detection:

• Workflow scanning - Analyzes .github/workflows/ for potential conflicts
• Tool identification - Detects Renovate, Dependabot, and other dependency managers
• Configuration conflicts - Identifies existing buddy or similar configurations

Smart Project Analysis Engine

interface ProjectAnalysis {
  type: 'library' | 'application' | 'monorepo' | 'unknown'
  packageManager: 'npm' | 'yarn' | 'pnpm' | 'bun' | 'unknown'
  hasLockFile: boolean
  hasDependencyFiles: boolean
  hasGitHubActions: boolean
  recommendedPreset: string
  recommendations: string[]
}

Project Intelligence:

• Type detection algorithm - Analyzes package.json structure, workspace configuration, and file patterns
• Package manager detection - Identifies lock files and package manager signatures
• Ecosystem analysis - Scans for pkgx.yaml, deps.yaml, and Launchpad dependency files
• Workflow integration - Discovers existing GitHub Actions for update integration

Progress Tracking System

interface SetupProgress {
  currentStep: number
  totalSteps: number
  stepName: string
  completed: string[]
  failed?: string
  canResume: boolean
  startTime: Date
}

Progress Features:

• Visual indicators - Real-time progress bars with completion percentages
• State management - Tracks completed steps and current progress
• Recovery support - Maintains state for resumption after interruptions
• Performance monitoring - Tracks setup duration and efficiency

Repository Validation API

async function validateRepositoryAccess(repoInfo: RepositoryInfo): Promise<ValidationResult>

API-Based Validation:

• Repository existence - Tests GitHub API access and repository availability
• Permission validation - Verifies read/write access and organizational restrictions
• Feature availability - Checks if issues, pull requests, and actions are enabled
• Private repository support - Enhanced validation for private repositories

Workflow Validation Engine

async function validateWorkflowGeneration(workflowContent: string): Promise<ValidationResult>

Comprehensive Validation:

• YAML syntax validation - Ensures generated workflows are syntactically correct
• Security best practices - Validates token usage, permissions, and security configurations
• Buddy integration - Verifies workflows include proper execution commands
• Permission matrix validation - Ensures workflows have appropriate GitHub Actions permissions

Error Handling & Recovery

Graceful Error Management:

• Detailed error reporting - Comprehensive error messages with suggested solutions
• Progressive degradation - Continues setup where possible when non-critical steps fail
• Recovery mechanisms - Allows resumption from failed steps with state preservation
• Rollback capabilities - Provides mechanisms to undo partial setup on failure

User Experience Enhancements:

• Clear progress indicators - Visual feedback on setup progression
• Contextual help - Situation-specific guidance and troubleshooting
• Intelligent recommendations - Project-specific suggestions based on analysis
• Setup verification - Post-setup validation to ensure everything works correctly

Next Steps

After successful setup:

1. Learn about the Dashboard - Understand dependency management
2. Explore Update Strategies - Configure update behavior
3. Configure Package Management - Fine-tune package handling
4. Review Pull Request Features - Understand PR automation