zutils/README.md

# zutils - User-Friendly Terminal Tools

A collection of user-friendly CLI tools written in Go that make common Linux tasks easier with beautiful, colored, and organized output.

## Features

- 🎨 **Beautiful colored terminal output** - Easy to read and visually appealing
- 📊 **Organized information display** - Structured and logical layout
- 🚀 **Fast and lightweight** - Single binary, no external dependencies
- 🔍 **Comprehensive information** - Multiple data points in one view
- 💡 **Token estimation** - For AI/LLM context planning
- ⚡ **Easy to use** - Just one character shortcut: `z`
- 🏗️ **Well-structured** - Modular architecture for easy expansion

## Installation

### Build from source

```bash
cd zutils
go build -o zutils
```

### Install to system path

```bash
# Using the install script (recommended)
./install.sh

# Or manually
cp zutils ~/.local/bin/
ln -s ~/.local/bin/zutils ~/.local/bin/z
```

The install script creates both `zutils` and `z` (shortcut) commands.

## Usage

### Command Syntax

```bash
z info <file|dir|network|path>
```

Or without the `info` subcommand (auto-detect):

```bash
z <file|directory>
```

### Examples

#### File Information

Get detailed information about a file:

```bash
z info main.go
# or simply
z main.go
```

Output includes:
- File path and name
- File size (formatted)
- File type detection
- Content statistics:
  - Line count
  - Word count
  - Character count
  - Estimated token count (for AI/LLM context)
- File details:
  - Permissions (human-readable)
  - Last modified timestamp
  - File extension

#### Directory Information

Analyze a directory:

```bash
z info /path/to/directory
# or simply
z /path/to/directory
```

Output includes:
- Total directory size
- File count
- Directory count
- Largest files (top 5)
- Largest directories (top 5)
- File type distribution
- Last modified timestamp

#### Network Information

Display network information:

```bash
z info network
```

Output includes:
- Local IP addresses (IPv4 and IPv6)
- Public IP address
- DNS servers
- Active network connections (top 10)

## Quick Reference

```bash
# File information
z README.md
z info file main.go

# Directory information
z .
z info dir /path/to/dir

# Network information
z info network

# Auto-detect (file or directory)
z /path/to/anything
```

## Project Structure

The project follows a clean, modular architecture for easy expansion:

```
zutils/
├── cmd/                 # Command implementations
│   ├── info.go          # Info command router
│   ├── file.go          # File information
│   ├── dir.go           # Directory information
│   ├── network.go       # Network information
│   └── autodetect.go    # Auto-detection logic
├── pkg/                 # Shared packages
│   ├── colors/          # Color constants
│   ├── formatter/       # Output formatting utilities
│   └── types/           # Command registry and types
├── examples/            # Example files for testing
├── main.go             # Entry point
├── go.mod              # Go module definition
├── install.sh          # Installation script
└── README.md           # This file
```

### Architecture Highlights

**Command Registry Pattern:**
- Easy to add new commands
- Centralized command management
- Extensible handler system

**Modular Design:**
- Separated concerns (commands, colors, formatting, types)
- Reusable components
- Easy to maintain and test

**No External Dependencies:**
- Uses Go standard library only
- Fast compilation
- Small binary size

## Adding New Commands

The project is designed to make adding new commands easy:

1. Create a new file in `cmd/` directory
2. Implement your command handler function
3. Register it in `main.go` using the command registry

Example:

```go
// In cmd/mycommand.go
package cmd

import (
    "fmt"
    "github.com/zemenawi/zutils/pkg/colors"
)

func MyCommand(args []string) error {
    fmt.Printf("%s%sHello from my command!%s\n", colors.Green, colors.Bold, colors.Reset)
    return nil
}

// In main.go
registry.Register(&types.Command{
    Name:        "mycmd",
    Description: "My custom command",
    Handler:     cmd.MyCommand,
})
```

## Why zutils?

Traditional Linux tools suffer from:
- ❌ Confusing command-line options and flags
- ❌ Unformatted or hard-to-read output
- ❌ Multiple tools needed for simple tasks
- ❌ Poor default displays that overwhelm users

**zutils** solves these issues by:
- ✅ Providing intuitive commands
- ✅ Beautiful, colored, organized output
- ✅ Combining multiple pieces of information in one view
- ✅ Great user experience for terminal users
- ✅ Single-character shortcut (`z`)
- ✅ Auto-detection of file/directory types

## Token Estimation

The token count is estimated using a rough approximation (words / 0.75), commonly used for:
- Planning AI/LLM context windows
- Estimating API token costs
- Understanding text complexity

**Note:** Actual token counts vary by model and tokenizer. This is an estimate for planning purposes.

## Development

### Building

```bash
go build -o zutils
```

### Cross-compilation

```bash
# Linux
GOOS=linux GOARCH=amd64 go build -o zutils-linux-amd64

# macOS
GOOS=darwin GOARCH=amd64 go build -o zutils-darwin-amd64

# Windows
GOOS=windows GOARCH=amd64 go build -o zutils-windows-amd64.exe
```

### Testing

```bash
# Test file info
z info main.go

# Test directory info
z info .

# Test network info
z info network

# Test auto-detect
z main.go
z .
```

## Future Enhancements

Planned features for future versions:

- [ ] `stats` command - System overview (CPU, RAM, Disk, processes)
- [ ] `find` command - File searching with filters
- [ ] `diff` command - Side-by-side file comparison
- [ ] `compress` / `extract` commands - Archive handling
- [ ] `procs` command - Process management
- [ ] `port` command - Port usage checking
- [ ] `mem` command - Memory usage details
- [ ] `disk` command - Disk usage analysis
- [ ] `watch` mode - Monitor changes in real-time
- [ ] JSON output mode for scripting
- [ ] Configuration file for custom colors
- [ ] Shell completion (bash, zsh, fish)

## License

MIT License - Feel free to use, modify, and distribute.

## Contributing

Contributions are welcome! The modular structure makes it easy to add new features:

1. Add your command to `cmd/`
2. Use shared utilities from `pkg/`
3. Register in `main.go`
4. Test thoroughly
5. Submit pull request

Feel free to:
- Report bugs
- Suggest new features
- Submit pull requests
- Improve documentation

## Author

Created with ❤️ to make terminal tools more user-friendly.

---

**Tip:** Use `z` as your one-character shortcut for all zutils commands!