# AGENTS.md - Agentic Coding Guidelines

## Project Overview

This is a Bash shell script project for collecting Docker and server information on Debian/Ubuntu systems.

**Primary Language**: Bash  
**Main File**: `docker-info.sh`

---

## Build/Lint/Test Commands

Since this is a Bash script project without a formal build system, use these commands:

### Linting
```bash
# ShellCheck (static analysis for bash scripts)
shellcheck docker-info.sh

# Check for syntax errors
bash -n docker-info.sh
```

### Testing
```bash
# Run the script (requires Docker to be installed for full functionality)
bash docker-info.sh

# Or make executable and run directly
chmod +x docker-info.sh
./docker-info.sh
```

### Single Test Pattern
```bash
# Test specific functions by sourcing and calling them
source docker-info.sh && command_exists docker
source docker-info.sh && print_success "test message"
```

---

## Code Style Guidelines

### General Bash Style

- **Shebang**: Always use `#!/usr/bin/env bash`
- **Set options**: Use `set -euo pipefail` at the start of scripts
  - `-e`: Exit on error
  - `-u`: Exit on undefined variables
  - `-o pipefail`: Pipeline fails if any command fails

### Formatting

- **Indentation**: 4 spaces (no tabs)
- **Line length**: Keep lines under 100 characters
- **Quotes**: Always quote variables: `"$variable"` not `$variable`
- **Functions**: Use `snake_case` for function names
- **Constants**: Use `UPPER_CASE` for constants and color codes

### Naming Conventions

```bash
# Functions - snake_case
print_header() { }
get_server_info() { }
check_root() { }

# Variables - descriptive names
local container_output
local cpu_count
local total_mem

# Constants - UPPER_CASE
readonly RED='\033[0;31m'
readonly HEADER_COLOR="${BRIGHT_CYAN}"
```

### Error Handling

```bash
# Always check command existence before use
command_exists() {
    command -v "$1" >/dev/null 2>&1
}

# Use proper exit codes
if ! command_exists docker; then
    print_error "Docker未安装"
    return 1
fi

# Redirect errors appropriately
docker ps 2>/dev/null || print_warning "无法列出容器"
```

### Function Structure

```bash
# Document functions with comments
# 获取服务器信息
get_server_info() {
    print_header "服务器信息"
    
    # Use local for function-scoped variables
    local cpu_count=$(grep -c '^processor' /proc/cpuinfo)
    local cpu_model=$(grep 'model name' /proc/cpuinfo | head -1 | cut -d: -f2 | xargs)
    
    # Call other functions for output
    print_key_value "CPU核心数" "$cpu_count"
}
```

### Color/Styling Code

- Define color codes as constants at the top of the file
- Group related colors together (basic, bright, background, styles)
- Use descriptive names: `HEADER_COLOR`, `SUCCESS_COLOR`, `ERROR_COLOR`
- Always reset colors with `${NC}` after colored output

### Output Patterns

```bash
# Use helper functions for consistent output
print_header()   # Boxed titles
print_section()  # Section headers with arrows
print_key_value() # Key: Value pairs
print_success()  # Green checkmark
print_warning()  # Yellow warning
print_error()    # Red X
```

### Comments

- Use Chinese comments to match existing codebase style
- Keep comments concise and meaningful
- Comment complex logic or non-obvious behavior

---

## Testing Checklist

Before submitting changes:

- [ ] Run `shellcheck docker-info.sh` with no warnings
- [ ] Run `bash -n docker-info.sh` for syntax check
- [ ] Test on a system with Docker installed
- [ ] Test on a system without Docker (should handle gracefully)
- [ ] Verify all color output displays correctly
- [ ] Check that tables align properly

---

## Dependencies

**Required**: None (uses standard POSIX utilities)

**Optional but recommended**:
- `jq` - For better JSON parsing of Docker info
- `shellcheck` - For linting

---

## File Structure

```
/shumengya/project/bash/docker-info/
└── docker-info.sh    # Main script file
```

---

## Security Notes

- This script may require root access for some Docker operations
- Always validate user input if added in the future
- Use proper quoting to prevent word splitting and globbing
- Sanitize any data passed to eval or similar dangerous operations