linux-bash/port-info/AGENTS.md

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

# 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:

# 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:

# 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

# 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

# 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:

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

# 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

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

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:

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