smartscan 0.1.0__py3-none-any.whl

smartscan/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("smartscan")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

smartscan/__main__.py

@@ -0,0 +1,4 @@
+from smartscan.cli import main
+
+if __name__ == "__main__":
+    main()

smartscan/cli.py

@@ -0,0 +1,139 @@
+# PYTHON_ARGCOMPLETE_OK
+
+"""CLI entry point with argparse subcommands for collect and query modes."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+import argcomplete
+
+from .commands import do_collect, do_query
+from .config import load_config
+from .constants import DEFAULT_CONFIG_PATH, DEFAULT_DB_PATH, DEFAULT_LOG_FILE
+from .exceptions import SmartScanError
+from .logging import setup_logging
+from .models import SmartScanConfig
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Build the argument parser for argcomplete integration, without config defaults."""
+    return _build_parser()
+
+
+def _build_parser(config: SmartScanConfig | None = None) -> argparse.ArgumentParser:
+    """Build the argument parser with config-driven defaults."""
+    cfg = config or SmartScanConfig()
+
+    parser = argparse.ArgumentParser(
+        description="Extract and display important SMART information from disk devices.",
+    )
+
+    parser.add_argument(
+        "--config",
+        default=DEFAULT_CONFIG_PATH,
+        help=f"TOML config file path (default: {DEFAULT_CONFIG_PATH})",
+    )
+    parser.add_argument(
+        "--db-path",
+        default=cfg.db_path,
+        help=f"Database file path (default: {DEFAULT_DB_PATH})",
+    )
+    parser.add_argument(
+        "--log-file",
+        default=cfg.log_file,
+        help=f"Log file path (default: {DEFAULT_LOG_FILE})",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        default=cfg.format == "json",
+        help="Output as JSON lines instead of table format",
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    collect_parser = sub.add_parser(
+        "collect", help="Collect SMART data from disk devices"
+    )
+    collect_parser.add_argument(
+        "pattern",
+        nargs="?",
+        default=".*",
+        help="Regex pattern to filter disk devices",
+    )
+    collect_parser.add_argument(
+        "--no-save",
+        action="store_true",
+        default=cfg.no_save,
+        help="Skip saving SMART data to database",
+    )
+    collect_parser.add_argument(
+        "--force-llm",
+        action="store_true",
+        help="Force LLM analysis on all disks, bypassing both config and threshold checks",
+    )
+    collect_parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Show extended fields in terminal output",
+    )
+
+    query_parser = sub.add_parser(
+        "query", help="Query historical SMART data from database"
+    )
+    query_parser.add_argument(
+        "pattern",
+        nargs="?",
+        default=".*",
+        help="Regex pattern to filter disk_name",
+    )
+    query_parser.add_argument(
+        "--since",
+        metavar="DATE",
+        help="Start date (YYYY-MM-DD) for query",
+    )
+    query_parser.add_argument(
+        "--until",
+        metavar="DATE",
+        help="End date (YYYY-MM-DD) for query",
+    )
+    query_parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Show extended fields in terminal output",
+    )
+
+    argcomplete.autocomplete(parser)
+    return parser
+
+
+def main() -> None:
+    """Entry point: load config, parse args, and dispatch to the appropriate subcommand."""
+    try:
+        pre_parser = argparse.ArgumentParser(add_help=False)
+        pre_parser.add_argument("--config", default=DEFAULT_CONFIG_PATH)
+        pre_args, remaining = pre_parser.parse_known_args()
+
+        config = load_config(pre_args.config)
+
+        parser = _build_parser(config)
+        args = parser.parse_args(remaining)
+
+        setup_logging(args.log_file)
+
+        args.thresholds_enabled = config.thresholds.enabled
+        args.threshold_rules = config.thresholds
+        args.llm_config = config.llm
+
+        if args.command == "query":
+            do_query(args)
+        else:
+            do_collect(args)
+    except SmartScanError as exc:
+        logging.error("%s", exc)
+        sys.exit(1)

smartscan/commands.py

@@ -0,0 +1,144 @@
+"""High-level command implementations for collect and query workflows."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sqlite3
+import sys
+import time
+from argparse import Namespace
+
+from .database import init_db, open_db, query_smart_info, save_to_db
+from .exceptions import DiskNotFoundError
+from .llm import call_llm
+from .output import (
+    print_json_output,
+    print_llm_analysis,
+    print_query_table,
+    print_table,
+    row_to_fields,
+)
+from .smartctl import extract_fields, find_disks, run_smartctl
+from .thresholds import check_thresholds
+
+
+def do_collect(args: Namespace) -> None:
+    if os.geteuid() != 0:
+        logging.warning(
+            "This program typically requires root privileges to access SMART data."
+        )
+
+    conn = None
+    if not args.no_save:
+        try:
+            conn = init_db(args.db_path)
+        except OSError as exc:
+            logging.error("Failed to open database at %s: %s", args.db_path, exc)
+
+    try:
+        disks = find_disks(args.pattern)
+    except DiskNotFoundError as exc:
+        logging.error("%s", exc)
+        sys.exit(1)
+
+    thresholds_enabled = args.thresholds_enabled
+
+    exit_code = 0
+    for disk_idx, symlink in enumerate(disks):
+        disk_name = symlink.name
+        disk_path = os.readlink(symlink)
+
+        data, rc = run_smartctl(symlink)
+        if rc != 0:
+            exit_code = 1
+
+        if not data:
+            continue
+
+        fields = extract_fields(data)
+
+        alerts = []
+        if thresholds_enabled:
+            alerts = check_thresholds(fields, args.threshold_rules)
+
+        if args.json:
+            print_json_output(disk_name, disk_path, fields, data)
+        else:
+            print_table(disk_name, fields, alerts, verbose=args.verbose)
+
+        llm_analysis = None
+        if args.force_llm or (args.llm_config.enabled and alerts):
+            alerts_text = (
+                "\n".join(f"  - {a.message}" for a in alerts) if alerts else "  (none)"
+            )
+            llm_analysis = call_llm(fields, alerts_text, args.llm_config, raw_data=data)
+        if llm_analysis:
+            if not args.json:
+                print_llm_analysis(llm_analysis)
+            if args.llm_config.delay > 0 and disk_idx < len(disks) - 1:
+                time.sleep(args.llm_config.delay)
+
+        if conn:
+            try:
+                save_to_db(
+                    conn, disk_name, disk_path, fields, data, llm_analysis=llm_analysis
+                )
+            except sqlite3.Error as exc:
+                logging.error("Failed to save SMART data for %s: %s", disk_name, exc)
+
+    if conn:
+        conn.close()
+
+    sys.exit(exit_code)
+
+
+def do_query(args: Namespace) -> None:
+    from .database import parse_date
+
+    since = parse_date(args.since) if args.since else None
+    until = parse_date(args.until) if args.until else None
+
+    conn = open_db(args.db_path)
+    if conn is None:
+        sys.exit(0)
+
+    try:
+        rows = query_smart_info(conn, args.pattern, since, until)
+    except sqlite3.OperationalError as exc:
+        logging.error("Query failed: %s", exc)
+        conn.close()
+        sys.exit(1)
+
+    if not rows:
+        logging.info("No SMART records found matching the query.")
+        conn.close()
+        sys.exit(0)
+
+    for row in rows:
+        fields = row_to_fields(row)
+
+        alerts = []
+        if args.thresholds_enabled:
+            alerts = check_thresholds(fields, args.threshold_rules)
+
+        if args.json:
+            llm_col = row["llm_analysis"] if "llm_analysis" in row.keys() else None
+            print_json_output(
+                row["disk_name"],
+                row["disk_path"],
+                fields,
+                timestamp=row["timestamp"],
+                llm_analysis=llm_col,
+            )
+        else:
+            print_query_table(
+                row["disk_name"],
+                row["disk_path"],
+                row["timestamp"],
+                fields,
+                alerts=alerts,
+                verbose=args.verbose,
+            )
+
+    conn.close()

smartscan/config.py

@@ -0,0 +1,54 @@
+"""TOML configuration file loading with Pydantic validation."""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+
+from .models import SmartScanConfig
+
+_ENV_VAR_RE = re.compile(r"\$\{(\w+)\}")
+
+
+def _expand_env_vars(obj: Any) -> Any:
+    if isinstance(obj, dict):
+        return {k: _expand_env_vars(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_expand_env_vars(v) for v in obj]
+    if isinstance(obj, str):
+        return _ENV_VAR_RE.sub(lambda m: os.environ.get(m.group(1), ""), obj)
+    return obj
+
+
+def load_config(config_path: str | None = None) -> SmartScanConfig:
+    """Read a TOML configuration file and return a validated :class:`SmartScanConfig`."""
+    from .constants import DEFAULT_CONFIG_PATH
+
+    path = config_path or DEFAULT_CONFIG_PATH
+    expanded = Path(path).expanduser()
+    if not expanded.is_file():
+        return SmartScanConfig()
+
+    try:
+        raw = tomllib.loads(expanded.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        logging.warning("Failed to parse config file %s: %s", expanded, exc)
+        return SmartScanConfig()
+
+    if not isinstance(raw, dict):
+        logging.warning("Invalid config file format; expected a TOML table.")
+        return SmartScanConfig()
+
+    raw = _expand_env_vars(raw)
+
+    try:
+        return SmartScanConfig.model_validate(raw)
+    except ValidationError as exc:
+        logging.warning("Invalid config values: %s", exc)
+        return SmartScanConfig()

smartscan/constants.py

@@ -0,0 +1,86 @@
+"""Default paths, database schema, and error message constants."""
+
+DEFAULT_DB_PATH = "~/.local/share/smartscan/smartscan.db"
+DEFAULT_LOG_FILE = "~/.local/state/smartscan/smartscan.log"
+DEFAULT_CONFIG_PATH = "~/.config/smartscan/smartscan.toml"
+
+SMARTCTL_ERROR_MSGS = [
+    "Bit 0: Command line did not parse.",
+    "Bit 1: Device open failed, device did not return an IDENTIFY DEVICE structure, or device is in a low-power mode.",
+    "Bit 2: Some SMART or other ATA command to the disk failed, or there was a checksum error in a SMART data structure.",
+    "Bit 3: SMART status check returned 'DISK FAILING'.",
+    "Bit 4: We found prefail Attributes <= threshold.",
+    "Bit 5: SMART status check returned 'DISK OK' but we found that some (usage or prefail) Attributes have been <= threshold at some time in the past.",
+    "Bit 6: The device error log contains records of errors.",
+    "Bit 7: The device self-test log contains records of errors. [ATA only] Failed self-tests outdated by a newer successful extended self-test are ignored.",
+]
+
+DB_SCHEMA = """
+CREATE TABLE IF NOT EXISTS smart_info (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    timestamp TEXT NOT NULL,
+    disk_name TEXT NOT NULL,
+    disk_path TEXT NOT NULL,
+    model_family TEXT,
+    model_name TEXT,
+    serial_number TEXT,
+    firmware_version TEXT,
+    user_capacity_bytes INTEGER,
+    user_capacity_gib REAL,
+    rotation_rate TEXT,
+    interface_speed TEXT,
+    power_on_time_hours TEXT,
+    power_cycle_count TEXT,
+    smart_status TEXT,
+    temperature_celsius TEXT,
+    reallocated_sector_ct TEXT,
+    current_pending_sector TEXT,
+    offline_uncorrectable TEXT,
+    reallocated_event_count TEXT,
+    ata_smart_error_log_count TEXT,
+    self_test_status TEXT,
+    udma_crc_error_count TEXT,
+    raw_read_error_rate TEXT,
+    spin_retry_count TEXT,
+    power_off_retract_count TEXT,
+    load_cycle_count TEXT,
+    helium_level TEXT,
+    raw_json TEXT,
+    llm_analysis TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_smart_info_disk_ts
+    ON smart_info(disk_path, timestamp);
+"""
+
+DB_MIGRATIONS = [
+    "ALTER TABLE smart_info ADD COLUMN serial_number TEXT",
+    "ALTER TABLE smart_info ADD COLUMN firmware_version TEXT",
+    "ALTER TABLE smart_info ADD COLUMN smart_status TEXT",
+    "ALTER TABLE smart_info ADD COLUMN current_pending_sector TEXT",
+    "ALTER TABLE smart_info ADD COLUMN offline_uncorrectable TEXT",
+    "ALTER TABLE smart_info ADD COLUMN reallocated_event_count TEXT",
+    "ALTER TABLE smart_info ADD COLUMN udma_crc_error_count TEXT",
+    "ALTER TABLE smart_info ADD COLUMN raw_read_error_rate TEXT",
+    "ALTER TABLE smart_info ADD COLUMN spin_retry_count TEXT",
+    "ALTER TABLE smart_info ADD COLUMN power_off_retract_count TEXT",
+    "ALTER TABLE smart_info ADD COLUMN load_cycle_count TEXT",
+    "ALTER TABLE smart_info ADD COLUMN helium_level TEXT",
+    "ALTER TABLE smart_info ADD COLUMN llm_analysis TEXT",
+]
+
+DEFAULT_SYSTEM_PROMPT = """\
+You are a hard drive health diagnostic expert analyzing SMART data.
+Examine the provided SMART attributes and give a concise assessment:
+
+1. Overall health status: HEALTHY / WARNING / CRITICAL
+2. Key concerns with specific metric values (if any)
+3. Recommended action (one sentence)
+
+Be factual and conservative. Do not cause unnecessary alarm for borderline values.
+If all metrics are within normal ranges, state the drive is healthy.
+If you cannot make a definitive assessment, say so honestly.
+
+Additionally, check the self-test log for the most recent long (extended)
+self-test and compare its lifetime hours against the drive's total power-on
+hours. If a significant portion of the drive's lifetime has passed since the
+last long self-test, recommend running one."""

smartscan/database.py

@@ -0,0 +1,183 @@
+"""SQLite database operations: init, save, query for SMART history."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .constants import DB_MIGRATIONS, DB_SCHEMA
+from .exceptions import InvalidDateError
+from .models import SmartInfo
+
+
+def _run_migrations(conn: sqlite3.Connection) -> None:
+    for sql in DB_MIGRATIONS:
+        try:
+            conn.execute(sql)
+        except sqlite3.OperationalError as exc:
+            if "duplicate column" not in str(exc):
+                logging.warning("Migration failed: %s", exc)
+
+
+def init_db(db_path: str) -> sqlite3.Connection:
+    """Create or open the SQLite database, applying the schema and enabling WAL mode."""
+    expanded = Path(db_path).expanduser()
+    expanded.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(expanded))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.executescript(DB_SCHEMA)
+    _run_migrations(conn)
+    return conn
+
+
+def open_db(db_path: str) -> sqlite3.Connection | None:
+    """Open the database in read-only mode for querying, returning ``None`` if it doesn't exist."""
+    expanded = Path(db_path).expanduser()
+    if not expanded.is_file():
+        logging.warning("Database not found: %s", expanded)
+        return None
+    conn = sqlite3.connect(f"file:{expanded}?mode=ro", uri=True)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def register_regexp(conn: sqlite3.Connection) -> None:
+    def _regexp(pattern: str, value: str | None) -> bool:
+        if value is None:
+            return False
+        return bool(re.search(pattern, value))
+
+    conn.create_function("REGEXP", 2, _regexp)
+
+
+def parse_date(date_str: str) -> datetime:
+    """Parse a ``YYYY-MM-DD`` date string into a UTC-aware datetime.
+
+    Raises:
+        InvalidDateError: If the string does not match the expected format.
+    """
+    try:
+        return datetime.strptime(date_str, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+    except ValueError as exc:
+        raise InvalidDateError(
+            f"Invalid date format: {date_str} (expected YYYY-MM-DD)"
+        ) from exc
+
+
+def query_smart_info(
+    conn: sqlite3.Connection,
+    pattern: str | None,
+    since: datetime | None,
+    until: datetime | None,
+) -> list[sqlite3.Row]:
+    """Query historical SMART records with optional disk name regex and date range filters."""
+    register_regexp(conn)
+
+    conditions: list[str] = []
+    params: list[str] = []
+
+    if pattern:
+        conditions.append("disk_name REGEXP ?")
+        params.append(pattern)
+
+    if since:
+        conditions.append("timestamp >= ?")
+        params.append(since.strftime("%Y-%m-%dT00:00:00Z"))
+
+    if until:
+        conditions.append("timestamp <= ?")
+        params.append(until.strftime("%Y-%m-%dT23:59:59Z"))
+
+    where = " AND ".join(conditions) if conditions else "1=1"
+    sql = f"SELECT * FROM smart_info WHERE {where} ORDER BY disk_path, timestamp"
+
+    logging.debug("Query: %s  params: %s", sql, params)
+    return conn.execute(sql, params).fetchall()
+
+
+_COLUMNS_INSERT = (
+    "timestamp",
+    "disk_name",
+    "disk_path",
+    "model_family",
+    "model_name",
+    "serial_number",
+    "firmware_version",
+    "user_capacity_bytes",
+    "user_capacity_gib",
+    "rotation_rate",
+    "interface_speed",
+    "power_on_time_hours",
+    "power_cycle_count",
+    "smart_status",
+    "temperature_celsius",
+    "reallocated_sector_ct",
+    "current_pending_sector",
+    "offline_uncorrectable",
+    "reallocated_event_count",
+    "ata_smart_error_log_count",
+    "self_test_status",
+    "udma_crc_error_count",
+    "raw_read_error_rate",
+    "spin_retry_count",
+    "power_off_retract_count",
+    "load_cycle_count",
+    "helium_level",
+    "raw_json",
+    "llm_analysis",
+)
+
+
+def save_to_db(
+    conn: sqlite3.Connection,
+    disk_name: str,
+    disk_path: str,
+    fields: SmartInfo,
+    raw_data: dict[str, Any],
+    llm_analysis: str | None = None,
+) -> None:
+    """Persist a single SMART data record into the database."""
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    placeholders = ", ".join("?" * len(_COLUMNS_INSERT))
+    columns = ", ".join(_COLUMNS_INSERT)
+    conn.execute(
+        f"INSERT INTO smart_info ({columns}) VALUES ({placeholders})",
+        (
+            timestamp,
+            disk_name,
+            disk_path,
+            fields["model_family"],
+            fields["model_name"],
+            fields["serial_number"],
+            fields["firmware_version"],
+            fields["user_capacity_bytes"],
+            fields["user_capacity_gib"],
+            fields["rotation_rate"],
+            fields["interface_speed"],
+            fields["power_on_time"],
+            fields["power_cycle_count"],
+            fields["smart_status"],
+            fields["temperature"],
+            fields["reallocated_sector_ct"],
+            fields["current_pending_sector"],
+            fields["offline_uncorrectable"],
+            fields["reallocated_event_count"],
+            fields["ata_smart_error_log"],
+            fields["self_test_status"],
+            fields["udma_crc_error_count"],
+            fields["raw_read_error_rate"],
+            fields["spin_retry_count"],
+            fields["power_off_retract_count"],
+            fields["load_cycle_count"],
+            fields["helium_level"],
+            json.dumps(raw_data, ensure_ascii=False),
+            llm_analysis,
+        ),
+    )
+    conn.commit()

smartscan/exceptions.py

@@ -0,0 +1,25 @@
+"""Custom exception hierarchy for smartscan error handling."""
+
+
+class SmartScanError(Exception):
+    pass
+
+
+class ConfigError(SmartScanError):
+    pass
+
+
+class DiskNotFoundError(SmartScanError):
+    pass
+
+
+class SmartctlError(SmartScanError):
+    pass
+
+
+class DatabaseError(SmartScanError):
+    pass
+
+
+class InvalidDateError(SmartScanError):
+    pass