about-system 0.0.17 → 0.0.19

package/src/systeminfo-types.d.ts

@@ -0,0 +1,457 @@
+/**
+ * System Information Types
+ * 
+ * TypeScript type definitions for the system information API response.
+ * All values are returned as clean strings without ANSI color codes or emojis.
+ */
+
+/**
+ * Platform types supported by the system info service
+ */
+export type Platform = 'linux' | 'windows' | 'macos' | 'unknown';
+
+/**
+ * Complete system information object returned by the API
+ */
+export interface SystemInfo {
+  /**
+   * ISO 8601 timestamp indicating when the system information was collected
+   * Format: "2025-01-15T10:30:00.000Z"
+   * Always present regardless of platform
+   * 
+   * @example "2025-01-15T10:30:00.000Z"
+   */
+  timestamp: string;
+
+  // =============================================================================
+  // SYSTEM IDENTITY
+  // =============================================================================
+
+  /**
+   * System hostname or computer name
+   * The network name assigned to this machine
+   * Empty string if unable to determine
+   * 
+   * @example "workstation-linux", "DESKTOP-ABC123", "MacBook-Pro"
+   */
+  hostname: string;
+
+  /**
+   * Username of the currently logged-in user
+   * The user account running the system info service
+   * Empty string if unable to determine
+   * 
+   * @example "admin", "john.doe", "deck"
+   */
+  user: string;
+
+  /**
+   * Operating system platform classification
+   * Categorizes the underlying OS family
+   * Always present, defaults to 'unknown' if detection fails
+   */
+  platform: Platform;
+
+  // =============================================================================
+  // OPERATING SYSTEM INFORMATION
+  // =============================================================================
+
+  /**
+   * Operating system name and version string
+   * Human-readable OS identification including version numbers
+   * Empty string on detection failure
+   * 
+   * @example 
+   * - Linux: "Ubuntu 22.04.3 LTS", "CachyOS Linux", "SteamOS 3.5.7"
+   * - Windows: "Windows 11 Pro", "Windows 10 Enterprise" 
+   * - macOS: "macOS Ventura 13.2.1"
+   */
+  os: string;
+
+  /**
+   * Kernel version string
+   * The core OS kernel version currently running
+   * Format varies by platform
+   * Empty string if unavailable
+   * 
+   * @example
+   * - Linux: "6.2.0-37-generic", "6.1.52-valve16-1-neptune-61"
+   * - Windows: "10.0.22621.2428"
+   * - macOS: "22.3.0"
+   */
+  kernel: string;
+
+  /**
+   * Current shell program being used
+   * The command-line interface shell (Linux/Unix systems only)
+   * Empty string on Windows or if unable to detect
+   * 
+   * @example "bash", "zsh", "fish", "powershell"
+   */
+  shell: string;
+
+  // =============================================================================
+  // HARDWARE SPECIFICATIONS
+  // =============================================================================
+
+  /**
+   * CPU model name and specifications
+   * Processor identification string, cleaned of unnecessary suffixes
+   * "with Radeon Graphics" and similar text is automatically stripped
+   * Empty string if detection fails
+   * 
+   * @example 
+   * - "Intel Core i7-12700K"
+   * - "AMD Ryzen 9 5900HX" 
+   * - "Apple M2 Pro"
+   * - "AMD Custom APU 0405" (Steam Deck)
+   */
+  cpu: string;
+
+  /**
+   * Graphics card model name
+   * Primary GPU identification (Linux systems primarily)
+   * Extracted from lspci output when available
+   * Empty string if no discrete GPU or detection fails
+   * 
+   * @example
+   * - "NVIDIA GeForce RTX 4070"
+   * - "AMD Radeon RX 6800 XT" 
+   * - "Intel UHD Graphics 770"
+   */
+  gpu: string;
+
+  /**
+   * Device or computer model name
+   * Hardware model identification when available
+   * Useful for laptops, prebuilt systems, and specialized devices
+   * Empty string if not available or generic hardware
+   * 
+   * @example
+   * - "Dell OptiPlex 7090"
+   * - "ASUS TUF Gaming A15" 
+   * - "Valve Steam Deck"
+   * - "MacBook Pro 16-inch"
+   */
+  device: string;
+
+  // =============================================================================
+  // REAL-TIME RESOURCE USAGE
+  // =============================================================================
+
+  /**
+   * Root filesystem disk usage percentage
+   * Shows how full the primary disk partition is
+   * Format: number followed by percent sign
+   * Empty string if unable to determine
+   * 
+   * @example "45%", "78%", "12%"
+   */
+  disk_used: string;
+
+  /**
+   * Memory usage in gigabytes
+   * Format: "used/total GB" showing current RAM consumption
+   * Calculated from system memory statistics
+   * Empty string if detection fails
+   * 
+   * @example "12/32GB", "6/16GB", "8/64GB"
+   */
+  ram_used: string;
+
+  /**
+   * Highest CPU consuming process
+   * Format: "percentage processname" of the most resource-intensive process
+   * Percentage is rounded to whole number
+   * Empty string if unable to determine (non-Linux systems)
+   * 
+   * @example "8% firefox", "15% chrome", "3% systemd", "25% game.exe"
+   */
+  top_process: string;
+
+  /**
+   * System uptime since last boot
+   * Format: "Xd Yh Zm" where X=days, Y=hours, Z=minutes
+   * Always present as calculated from system boot time
+   * 
+   * @example "2d 14h 23m", "0d 3h 45m", "15d 2h 1m"
+   */
+  uptime: string;
+
+  // =============================================================================
+  // HARDWARE STATUS (Linux-specific)
+  // =============================================================================
+
+  /**
+   * System temperature reading
+   * CPU or system temperature from thermal sensors (Linux only)
+   * Format: number followed by "°C"
+   * Empty string if no temperature sensors available or non-Linux
+   * 
+   * @example "42°C", "65°C", "38°C"
+   */
+  temperature: string;
+
+  /**
+   * Battery charge level and charging status
+   * Format: "percentage" optionally followed by "+" if charging
+   * Only available on battery-powered devices (laptops, handhelds)
+   * Empty string if no battery present or detection fails
+   * 
+   * @example 
+   * - "85%" (discharging)
+   * - "73%+" (charging) 
+   * - "100%" (full)
+   */
+  battery: string;
+
+  /**
+   * System load averages (Linux only)
+   * Format: "1min 5min 15min" showing system load over time periods
+   * Values represent average system load, where 1.0 = full utilization
+   * Empty string on non-Linux systems
+   * 
+   * @example "0.8 1.2 1.5", "2.1 1.8 1.6", "0.1 0.3 0.4"
+   */
+  load_average: string;
+
+  // =============================================================================
+  // NETWORK INFORMATION
+  // =============================================================================
+
+  /**
+   * Public IP address
+   * External internet-facing IPv4 address
+   * Obtained from ipinfo.io service
+   * Empty string if no internet connection or service unavailable
+   * 
+   * @example "203.0.113.42", "198.51.100.15", "192.0.2.1"
+   */
+  ip: string;
+
+  /**
+   * Local/private IP address(es)
+   * Internal network IP addresses (RFC 1918 ranges)
+   * Multiple addresses separated by spaces if available
+   * Empty string if no network interfaces active
+   * 
+   * @example 
+   * - "192.168.1.100"
+   * - "10.0.0.50 192.168.1.100" (multiple interfaces)
+   * - "172.16.0.10"
+   */
+  iplocal: string;
+
+  /**
+   * Geographic city location
+   * City name based on public IP geolocation
+   * Obtained from ipinfo.io service
+   * Empty string if no internet connection or location unavailable
+   * 
+   * @example "San Francisco", "New York", "London", "Tokyo"
+   */
+  city: string;
+
+  /**
+   * Reverse DNS hostname with HTTP prefix
+   * Format: "http://hostname" from reverse DNS lookup of public IP
+   * Empty string if reverse DNS unavailable or no internet connection
+   * 
+   * @example "http://example.com", "http://host-203-0-113-42.example.net"
+   */
+  domain: string;
+
+  /**
+   * Internet Service Provider name
+   * ISP identification from public IP ownership data
+   * AS (Autonomous System) number prefix is automatically removed
+   * Empty string if no internet connection or data unavailable
+   * 
+   * @example "Comcast Cable", "Verizon Business", "T-Mobile USA", "Cloudflare Inc"
+   */
+  isp: string;
+
+  // =============================================================================
+  // SOFTWARE AND DEVELOPMENT TOOLS
+  // =============================================================================
+
+  /**
+   * Available package managers and development tools
+   * Space-separated list of detected command-line tools
+   * Includes package managers, editors, and development utilities
+   * Empty string if no recognized tools found
+   * 
+   * @example 
+   * - "apt npm pip docker nvim yay" (Linux development setup)
+   * - "pacman yay flatpak" (Arch-based system)
+   * - "npm pip docker hx bun" (Node.js developer setup)
+   */
+  pacman: string;
+
+  /**
+   * Open network ports with associated services
+   * Space-separated list of "port+service" combinations
+   * Shows ports that are actively listening for connections
+   * Empty string if no open ports detected or non-Linux system
+   * 
+   * @example 
+   * - "22ssh 80http 443https" (web server with SSH)
+   * - "3000node 5432postgres" (development services)
+   * - "8080java 9000python" (application servers)
+   */
+  ports: string;
+
+  /**
+   * Running Docker containers with exposed ports
+   * Space-separated list of container names followed by port numbers
+   * Only shows currently running containers
+   * Empty string if Docker not installed, no containers running, or access denied
+   * 
+   * @example 
+   * - "web-server 80 db-postgres 5432"
+   * - "redis-cache 6379 nginx-proxy 443"
+   * - "app-backend 8080"
+   */
+  containers: string;
+
+  /**
+   * Number of active system services
+   * Count of running systemd services (Linux only)  
+   * Format: "number services"
+   * Empty string on non-Linux systems or if systemctl unavailable
+   * 
+   * @example "145 services", "89 services", "203 services"
+   */
+  services_running: string;
+
+  // =============================================================================
+  // EXTENDED SYSTEM INFORMATION (Linux-specific)
+  // =============================================================================
+
+  /**
+   * Available system memory (Linux only)
+   * Amount of memory available for new processes
+   * Format: "number GB available" 
+   * Based on MemAvailable from /proc/meminfo
+   * Empty string on non-Linux systems
+   * 
+   * @example "18GB available", "4GB available", "32GB available"
+   */
+  memory_available: string;
+
+  /**
+   * Swap usage statistics (Linux only)
+   * Virtual memory usage percentage and size
+   * Format: "percentage (size) swap"
+   * Empty string on non-Linux systems or if no swap configured
+   * 
+   * @example "2% (512MB) swap", "0% (0MB) swap", "15% (2048MB) swap"
+   */
+  swap_used: string;
+
+  /**
+   * Number of logged-in users (Linux only)
+   * Count of active user sessions
+   * Format: "number users"
+   * Empty string on non-Linux systems
+   * 
+   * @example "2 users", "1 users", "5 users"
+   */
+  users_logged_in: string;
+
+  /**
+   * Active network interface names (Linux only)
+   * Space-separated list of network interface names with active IPv4 addresses
+   * Excludes loopback interface (lo)
+   * Empty string on non-Linux systems or no active interfaces
+   * 
+   * @example 
+   * - "eth0 wlan0" (wired and wireless)
+   * - "enp3s0" (single ethernet interface)
+   * - "wlp2s0 docker0" (wireless and Docker bridge)
+   */
+  network_interfaces: string;
+
+  /**
+   * Non-root filesystem mount points with usage (Linux only)
+   * Space-separated list of "mountpoint(usage%)" 
+   * Excludes system mounts (/dev, /proc, /sys) and root (/)
+   * Shows up to 3 mount points to prevent excessive output
+   * Empty string on non-Linux systems or only root filesystem mounted
+   * 
+   * @example 
+   * - "/home(85%) /var(23%)"
+   * - "/opt(12%) /tmp(5%) /boot(45%)"
+   * - "/mnt/data(67%)"
+   */
+  mount_points: string;
+
+  /**
+   * Display screen resolution (Linux with X11 only)
+   * Current display resolution from xrandr
+   * Format: "widthxheight"
+   * Empty string if no X11 display, non-Linux, or detection fails
+   * 
+   * @example "1920x1080", "2560x1440", "3840x2160", "1280x800"
+   */
+  screen_resolution: string;
+}
+
+/**
+ * Options for configuring system info collection and output
+ */
+export interface SystemInfoOptions {
+  /** Return JSON object instead of formatted output */
+  json_output?: boolean;
+  
+  /** Force single-line vs multi-line display mode */
+  single_line?: boolean;
+  
+  /** Return data object instead of printing to console (module usage) */
+  returnData?: boolean;
+}
+
+/**
+ * Error object returned when system information collection fails
+ */
+export interface SystemInfoError {
+  /** Error type identifier */
+  error: string;
+  
+  /** Human-readable error message */
+  message: string;
+  
+  /** Additional error details if available */
+  details?: string;
+  
+  /** Timestamp when error occurred */
+  timestamp: string;
+}
+
+/**
+ * Function type for getting system information as JSON
+ * @returns Promise resolving to complete system information object
+ */
+export type GetSystemInfoFunction = () => Promise<SystemInfo>;
+
+/**
+ * Function type for displaying system information with options
+ * @param options Configuration options for output format and behavior
+ * @returns Promise resolving to SystemInfo object if JSON output requested
+ */
+export type DisplaySystemInfoFunction = (options?: SystemInfoOptions) => Promise<SystemInfo | void>;
+
+/**
+ * Platform-specific field availability matrix
+ * Indicates which fields are typically available on each platform
+ */
+export interface PlatformAvailability {
+  /** Fields available on all platforms */
+  universal: Array<keyof SystemInfo>;
+  
+  /** Fields primarily available on Linux */
+  linux_specific: Array<keyof SystemInfo>;
+  
+  /** Fields that may be empty on certain platforms */
+  conditional: Array<keyof SystemInfo>;
+}

package/src/types/internal-types.ts

@@ -0,0 +1,21 @@
+/**
+ * Internal type definitions
+ * @module internal-types
+ */
+
+import type { Cache, CacheEntry } from "../cache/cache";
+import type { IPInfo } from "../utils/network";
+
+/**
+ * Context object passed to info collection functions
+ * @interface InfoContext
+ */
+export interface InfoContext {
+  /** Cache storage */
+  cache: Cache;
+  /** IP information from external API */
+  ipInfo?: IPInfo;
+}
+
+// Re-export cache types for convenience
+export type { Cache, CacheEntry };

package/src/utils/command.ts

@@ -0,0 +1,47 @@
+/**
+ * Command execution utilities
+ * @module command
+ */
+
+import { execSync } from "child_process";
+import { IS_WINDOWS } from "./platform";
+
+/**
+ * Executes a shell command safely with timeout
+ * @param {string} command - Command to execute
+ * @param {object} options - Additional options for execSync
+ * @returns {string} Command output or empty string on error
+ */
+export function execCommand(command: string, options = {}): string {
+  try {
+    const cmd = IS_WINDOWS ? `cmd /c ${command}` : command;
+    return execSync(cmd, {
+      encoding: "utf8",
+      timeout: 10000,
+      stdio: ["pipe", "pipe", "ignore"],
+      ...options,
+    })
+      .toString()
+      .trim();
+  } catch (error) {
+    return "";
+  }
+}
+
+/**
+ * Checks if a command exists in the system PATH
+ * @param {string} command - Command name to check
+ * @returns {boolean} True if command exists
+ */
+export function commandExists(command: string): boolean {
+  try {
+    if (IS_WINDOWS) {
+      execSync(`where ${command}`, { stdio: "ignore" });
+    } else {
+      execSync(`which ${command}`, { stdio: "ignore" });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/network.ts

@@ -0,0 +1,58 @@
+/**
+ * Network utilities for IP information fetching
+ * @module network
+ */
+
+import https from "https";
+import {
+  DEFAULT_IPINFO_TOKEN,
+  DEFAULT_NETWORK_TIMEOUT,
+} from "../cache/cache-config";
+
+/**
+ * IP information from ipinfo.io API
+ * @interface IPInfo
+ */
+export interface IPInfo {
+  /** Public IP address */
+  ip?: string;
+  /** City location */
+  city?: string;
+  /** Reverse DNS hostname */
+  hostname?: string;
+  /** ISP organization string (includes AS number) */
+  org?: string;
+}
+
+/**
+ * Fetches IP geolocation information from ipinfo.io API
+ * @param {string} token - IPInfo.io API token
+ * @param {number} timeout - Request timeout in milliseconds
+ * @returns {Promise<IPInfo>} IP information object or empty object on error
+ */
+export async function fetchIPInfo(
+  token: string = DEFAULT_IPINFO_TOKEN,
+  timeout: number = DEFAULT_NETWORK_TIMEOUT
+): Promise<IPInfo> {
+  return new Promise((resolve) => {
+    const url = `https://ipinfo.io/json${token ? `?token=${token}` : ""}`;
+
+    const req = https.get(url, (res) => {
+      let data = "";
+      res.on("data", (chunk) => (data += chunk));
+      res.on("end", () => {
+        try {
+          resolve(JSON.parse(data));
+        } catch {
+          resolve({});
+        }
+      });
+    });
+
+    req.on("error", () => resolve({}));
+    req.setTimeout(timeout, () => {
+      req.destroy();
+      resolve({});
+    });
+  });
+}

package/src/utils/platform.ts

@@ -0,0 +1,13 @@
+/**
+ * Platform detection utilities
+ * @module platform
+ */
+
+import os from "os";
+
+/**
+ * Platform detection constants
+ */
+export const IS_WINDOWS = os.platform() === "win32";
+export const IS_MAC = os.platform() === "darwin";
+export const IS_LINUX = os.platform() === "linux";