gentleman-system_skill

Overview

This skill describes system detection and command execution patterns used by Gentleman.Dots. It documents the OS type enum, SystemInfo shape, detection priority (Termux first), and the correct command execution helpers for different environments. The goal is to make adding OS support, modifying detection logic, and running platform-specific commands consistent and safe.

How this skill works

Detection builds a SystemInfo struct by checking Termux first, then runtime.GOOS and additional checks for Arch or Debian families. SystemInfo exposes flags like IsTermux, IsARM, HasBrew, and Prefix to drive behavior. Command execution helpers choose proper behavior: plain Run for simple exec, RunWithLogs for streaming output, RunSudo* for privileged ops, RunBrew* for Homebrew, and RunPkg* for Termux pkg manager.

When to use it

• Adding support for a new OS or variant (add OSType, detection, and installer case).
• Changing OS detection logic or adding new detection heuristics (Termux, Arch, Debian).
• Running commands that require platform-specific handling (sudo, brew, pkg).
• Implementing backup/restore or file operations that depend on HomeDir/Prefix.
• Choosing the correct exec function when logs, sudo, or package managers are needed.

Best practices

• Always check Termux first; it runs on Linux but needs special handling.
• Populate SystemInfo completely so downstream code can branch safely (HasBrew, HasPkg, IsARM, Prefix).
• Use RunWithLogs or Run*WithLogs when you need real-time output for progress or telemetry.
• Use CommandExists("tool") before attempting installs to avoid unnecessary operations.
• When adding a new OS, update Detect(), add an isNewOS() helper, and add an installer case.

Example use cases

• Add support for a new BSD: add OSType constant, implement isBSD(), update Detect(), and add installer steps.
• Install a tool: use RunBrewWithLogs on macOS, RunSudoWithLogs on Arch, RunPkgInstall on Termux.
• Detect Homebrew prefix for Apple Silicon vs Intel using runtime.GOARCH to choose paths.
• Implement backup: use EnsureDir, CopyFile, and CopyDir with homeDir from SystemInfo.
• Write tests: run Go tests under installer/internal/system for Detect and Exec behavior.