MacSetup Automation Tool

A comprehensive macOS automation tool for quickly configuring new Macs with software installations and system optimizations. Features a modular shell script architecture with extensive logging, configuration management, and user-friendly interfaces.

What This Skill Does

This skill helps you work with the MacSetup project - a powerful macOS automation tool that can transform a fresh Mac into a fully configured development or production environment in hours instead of days. It provides guidance on:

Instructions for AI Agent

When working with the MacSetup codebase, follow these detailed steps:

1. Understanding the Project Structure

First, familiarize yourself with the core architecture:

- `utils.sh` - System utilities and helper functions

- `logger.sh` - Multi-level logging system (DEBUG, INFO, WARN, ERROR, FATAL)

- `config.sh` - Configuration management and profile loading

- `remote-config.sh` - Remote configuration handling

- `packages/` - Software package lists (homebrew.txt, cask.txt, appstore.txt)

- `profiles/` - Pre-defined configuration profiles (basic.conf, developer.conf, designer.conf)

- `system/` - System configuration scripts (defaults.sh)

- `dotfiles/` - Configuration file templates

2. Running and Testing Commands

When the user asks to run or test MacSetup:

**Always start with dry-run mode for safety:**

```bash

./init.sh --dry-run --verbose

```

**Common execution patterns:**

```bash

Interactive wizard (safest for users)

./init.sh

Profile-based installation

./init.sh --profile developer # Developer setup

./init.sh --profile designer # Designer tools

./init.sh --profile basic # Basic office setup

Targeted operations

./init.sh --packages-only # Only install software

./init.sh --config-only # Only configure system settings

Advanced modes

./init.sh --config custom.conf --yes --verbose

./init.sh --remote list # Show community configurations

```

3. Modifying or Adding Features

When making changes to the codebase:

**A. Always use the logging system:**

```bash

In any script, source the logger

source "$(dirname "$0")/scripts/core/logger.sh"

Use appropriate log levels

log_debug "Detailed debugging information"

log_info "Normal operational message"

log_warn "Warning that doesn't stop execution"

log_error "Error that affects operation"

log_fatal "Critical error that stops execution"

```

**B. Follow the modular pattern:**

**C. Configuration file handling:**

**D. Safety patterns to follow:**

```bash

Always check if running in dry-run mode

if [[ "${DRY_RUN:-false}" != "true" ]]; then

# Actual operation

else

log_info "DRY-RUN: Would execute operation"

fi

Create backups before modifications

backup_file "/path/to/important/file"

Handle errors gracefully

if ! some_operation; then

log_error "Operation failed"

return 1

fi

```

4. Creating Custom Profiles

When helping users create custom configurations:

**A. Package list format** (`configs/packages/*.txt`):

```bash

Development tools

git # Version control

node # JavaScript runtime

python # Python interpreter

Containers

docker # Container platform

kubernetes-cli # Kubernetes tools

```

**B. Profile configuration** (`configs/profiles/*.conf`):

```bash

Profile metadata

PROFILE_NAME="Custom Developer Setup"

PROFILE_DESCRIPTION="My personalized development environment"

Package files

PACKAGES_FILE="custom-packages.txt"

CASKS_FILE="custom-apps.txt"

APPSTORE_FILE="custom-appstore.txt"

Installation options

INSTALL_HOMEBREW="true"

INSTALL_CASKS="true"

INSTALL_APPSTORE="false"

Configuration options

CONFIGURE_SYSTEM="true"

CONFIGURE_DOTFILES="true"

DEVELOPER_MODE="true"

Custom settings

SHOW_HIDDEN_FILES="true"

DISABLE_DASHBOARD="false"

```

5. Debugging and Troubleshooting

When investigating issues:

**A. Enable verbose logging:**

```bash

./init.sh --verbose --dry-run

```

**B. Check log files:**

**C. Common troubleshooting steps:**

1. Verify system requirements (macOS version, disk space, admin privileges)

2. Check internet connectivity

3. Ensure Homebrew is properly installed

4. Review configuration file syntax

5. Test with minimal configuration first

6. Check for conflicting existing installations

6. Remote Configuration Management

When working with remote configurations:

```bash

List available community configurations

./init.sh --remote list

Use configuration from URL

./init.sh --remote use https://example.com/config.conf

Install specific community configuration

./init.sh --remote install developer-full

```

7. System Requirements and Compatibility

Always verify:

8. Best Practices for Code Modifications

When modifying the codebase:

1. **Test with dry-run first**: Never run untested code with actual installation

2. **Use the logging system**: Don't use raw `echo` statements

3. **Follow modular pattern**: New features = new modules

4. **Configuration over code**: Use config files instead of hardcoding

5. **Support backup and recovery**: All destructive operations need backups

6. **Error handling**: Every operation should handle failures gracefully

7. **Documentation**: Update relevant docs when adding features

8. **Compatibility**: Test on multiple macOS versions if possible

Example Usage Scenarios

Scenario 1: User wants to set up a development environment

```bash

Recommend the interactive wizard first

./init.sh

Or use the developer profile directly

./init.sh --profile developer --verbose

```

Scenario 2: User wants to preview what will be installed

```bash

Always use dry-run for previewing

./init.sh --profile designer --dry-run --verbose

```

Scenario 3: User wants to add a new software package

1. Determine package type (brew formula, cask, or App Store)

2. Add to appropriate file in `configs/packages/`

3. Test with dry-run: `./init.sh --packages-only --dry-run`

4. Run actual installation: `./init.sh --packages-only`

Scenario 4: User wants to create a team configuration

1. Create custom package lists in `configs/packages/`

2. Create profile config in `configs/profiles/`

3. Test locally with dry-run

4. Share configuration file or host remotely

5. Team members use: `./init.sh --remote use <URL>`

Important Constraints

Notes