# AGENTS.md - Agent Coding Guidelines

This document provides guidelines for agents working in this repository.

## Project Overview

This is a **Bash shell script** project for displaying Linux port information (TCP, UDP, HTTP services). The main file is `port_info.sh`.

## Build / Lint / Test Commands

### Running the Script
```bash
# Make executable and run
chmod +x port_info.sh
./port_info.sh

# Or run directly with bash
bash port_info.sh
```

### Linting
Use **shellcheck** for static analysis:
```bash
# Install shellcheck (if not present)
apt-get install shellcheck  # Debian/Ubuntu
yum install epel-release && yum install ShellCheck  # RHEL/CentOS

# Run shellcheck on the script
shellcheck port_info.sh

# Run with specific severity levels
shellcheck -S error port_info.sh   # Errors only
shellcheck -S warning port_info.sh # Warnings and errors
```

### Testing a Single Function
Bash doesn't have traditional unit tests, but you can test functions interactively:
```bash
# Source the script and test specific functions
source port_info.sh
get_service_name 80    # Test port-to-service lookup
check_commands         # Test command detection
```

### Syntax Validation
```bash
# Check bash syntax without executing
bash -n port_info.sh
```

## Code Style Guidelines

### File Organization
- Single script files for small utilities
- Use clear section separators: `#===============================================================================`
- Group related functions together
- Main execution at the bottom of the file

### Formatting
- Indentation: 4 spaces
- Use `#!/bin/bash` shebang (not `#!/bin/sh` for bash-specific features)
- Maximum line length: ~100 characters (flexible for output formatting)
- Use uppercase for constants/variables, lowercase for function names

### Variable Naming
- Constants (colors, separators): UPPERCASE with underscores, e.g., `RED`, `SEPARATOR`
- Global variables: UPPERCASE, e.g., `PORT_CMD`
- Local variables in functions: lowercase with underscores, e.g., `local port=$1`
- Function names: lowercase with underscores, e.g., `check_commands()`

### Functions
```bash
# Good function definition
function_name() {
    local arg1=$1
    local arg2=$2
    
    # function body
    
    return 0  # Always return explicit status
}

# Or with function keyword
check_commands() {
    # ...
}
```

### Color Variables
Define colors at the top of the script using ANSI escape codes:
```bash
RED='\033[38;5;196m'
GREEN='\033[38;5;46m'
NC='\033[0m'  # No Color - always reset at end
```

### Error Handling
- Use `command -v` to check command availability
- Redirect stderr with `2>/dev/null` for expected errors
- Exit with status 1 on fatal errors: `exit 1`
- Use descriptive error messages with colors

### Input Handling
- Prefer arguments over interactive input
- Validate inputs before processing
- Use `local` for all function parameters
- Check for required arguments

### String Comparisons
```bash
# String equality
if [ "$var" = "value" ]; then
    # ...
fi

# Numeric comparison
if [ "$num" -eq 0 ]; then
    # ...
fi

# Regex matching
if [[ "$port" =~ ^[0-9]+$ ]]; then
    # ...
fi
```

### Output Formatting
- Use `printf` for formatted output (not `echo` for complex output)
- Use color codes with `${COLOR}...${NC}` pattern
- Consistent column widths in tables

### Common Patterns

#### Command Availability Check
```bash
if command -v ss &> /dev/null; then
    PORT_CMD="ss"
elif command -v netstat &> /dev/null; then
    PORT_CMD="netstat"
else
    echo -e "${RED}Error: command not found${NC}"
    exit 1
fi
```

#### Reading Lines
```bash
while IFS= read -r line; do
    # process line
done < <(command)
```

#### Safe Variable Usage
- Always quote variables: `"$var"` not `$var`
- Use `${var}` for clarity in complex expressions
- Initialize variables before use

### Shellcheck Compliance
Run `shellcheck` and fix all warnings:
- SC2086: Quote variables to prevent word splitting
- SC2166: Use `&&` instead of `-a` in test expressions
- SC2027: Quote strings containing newlines
- SC2248: Prefer printf over echo

## File Extensions
- Bash scripts: `.sh`
- No extension for executable scripts (optional)

## Documentation
- Add Chinese comments for Chinese-language projects
- Use section headers: `#===============================================================================`
- Document function purpose before definition
- Include usage information in comments

## Dependencies
This script requires:
- `ss` or `netstat net` (from-tools package)
- Standard Linux utilities: `awk`, `grep`, `sed`, `sort`, `uniq`

## Common Tasks

### Adding a New Port Service
Edit `get_service_name()` function in `port_info.sh`:
```bash
get_service_name() {
    local port=$1
    case $port in
        80)     echo "HTTP" ;;
        443)    echo "HTTPS" ;;
        3306)   echo "MySQL" ;;
        # Add new port here
        9000)   echo "PHP-FPM" ;;
        *)      echo "未知" ;;
    esac
}
```

### Adding a New Display Section
1. Create a new function following existing patterns
2. Add function call in `main()`
3. Use consistent color scheme and formatting