smartscan 0.2.0__tar.gz → 0.3.0__tar.gz

{smartscan-0.2.0 → smartscan-0.3.0}/AGENTS.md

@@ -14,10 +14,15 @@ smartscan is a CLI tool that runs `smartctl` on all disk devices, extracts key S
 - DO NOT use ad hoc `pip install` commands instead of updating `pyproject.toml`.
 - DO NOT edit generated output under `site/`; rebuild it from source.
 
+## Agent Guidelines
+
+- Do not read or write files that are excluded by `.gitignore`, unless a skill or the user explicitly directs you to do so.
+- Proactively use available agent skills when a task matches a skill's description.
+
 ## Conventions
 
 - Application code lives under `src/smartscan`.
-- The CLI uses stdlib `argparse` with `argcomplete` for shell completion. Subcommands: `collect` and `query`.
+- The CLI uses stdlib `argparse` with `argcomplete` for shell completion. Subcommands: `collect`, `query`, and `lsblk`.
 - Terminal output uses [Rich](https://rich.readthedocs.io/) for styled tables and formatting.
 - Configuration uses [Pydantic](https://docs.pydantic.dev/) `BaseModel` for validation.
 - SMART field structures use `TypedDict` (`SmartInfo`) for type safety.
@@ -30,15 +35,18 @@ smartscan is a CLI tool that runs `smartctl` on all disk devices, extracts key S
 
 | Module | Responsibility |
 |---|---|
-| `constants.py` | Default paths, DB schema, error messages |
+| `constants.py` | Default paths, database migrations, error messages |
 | `exceptions.py` | `SmartScanError` hierarchy |
 | `models.py` | `SmartScanConfig` (Pydantic), `SmartInfo` (TypedDict) |
+| `fields.py` | `FieldDef` registry — single source of truth for field metadata, DB columns, display labels |
 | `config.py` | `load_config()` — read TOML config into `SmartScanConfig` |
 | `logging.py` | `setup_logging()` |
-| `smartctl.py` | `find_disks()`, `run_smartctl()`, `extract_fields()`, helpers |
-| `output.py` | Rich-powered `print_table()`, `print_query_table()`, `print_json_output()` |
-| `database.py` | SQLite init, open, save, query |
-| `commands.py` | `do_collect()`, `do_query()` |
+| `smartctl.py` | `find_disks()`, `run_smartctl()`, `extract_fields()`, `build_device_tree()`, helpers |
+| `thresholds.py` | `check_thresholds()`, `Alert` dataclass |
+| `output.py` | Rich-powered `print_table()`, `print_query_table()`, `print_json_output()`, `print_lsblk_tree()` |
+| `database.py` | SQLite init, open, save, query, schema generation |
+| `llm.py` | `BaseLLMProvider` → `OpenAIProvider` / `AnthropicProvider`, `call_llm()`, `_build_prompt()` |
+| `commands.py` | `do_collect()`, `do_query()`, `do_lsblk()` |
 | `cli.py` | `create_parser()`, `main()` |
 
 ## Testing Guidelines

{smartscan-0.2.0 → smartscan-0.3.0}/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-06-14
+
+### Added
+
+- Global `--exclude` option usable by all subcommands, including `collect`
+- `exclude_patterns` top-level config key shared across subcommands
+- Exclude patterns now match both symlink names and resolved target paths
+
+### Changed
+
+- `identify` subcommand renamed to `lsblk` (**breaking**: CLI invocation changes)
+- `exclude_patterns` config key removed from `[lsblk]` section; use top-level key instead (**breaking**: update TOML config)
+- Extracted `fields.py` and `llm.py` into dedicated modules
+
 ## [0.2.0] - 2026-06-13
 
 ### Added
@@ -56,6 +70,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Threshold checks now also run in `query` mode for historical alert display
 - Database migration errors are now logged with a warning instead of being silently swallowed, except for expected "duplicate column" cases
 - Docker image now installs `smartmontools` so the `smartctl` binary is available at run time
-
-[0.2.0]: https://github.com/ak1ra-lab/smartscan/tag/?h=v0.2.0
-[0.1.0]: https://github.com/ak1ra-lab/smartscan/tag/?h=v0.1.0

{smartscan-0.2.0 → smartscan-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smartscan
-Version: 0.2.0
+Version: 0.3.0
 Summary: A CLI tool that collects SMART data from disk devices, checks configurable health thresholds, optionally analyses results with an LLM, and tracks history in SQLite.
 Project-URL: Homepage, https://github.com/ak1ra-lab/smartscan
 Project-URL: Repository, https://github.com/ak1ra-lab/smartscan
@@ -55,9 +55,9 @@ smartscan query --since 2026-01-01
 Map disks to their /dev/disk/ identifiers (no root needed):
 
 ```bash
-smartscan identify
-smartscan identify --source by-id "Samsung"
-smartscan identify --exclude '^/dev/(loop|zd)\d+'
+smartscan lsblk
+smartscan lsblk --source by-id "Samsung"
+smartscan lsblk --exclude '^/dev/(loop|zd)\d+'
 ```
 
 Read the [full documentation](https://ak1ra-lab.github.io/smartscan/) for shell completion, configuration reference, and advanced usage.

{smartscan-0.2.0 → smartscan-0.3.0}/README.md

@@ -32,9 +32,9 @@ smartscan query --since 2026-01-01
 Map disks to their /dev/disk/ identifiers (no root needed):
 
 ```bash
-smartscan identify
-smartscan identify --source by-id "Samsung"
-smartscan identify --exclude '^/dev/(loop|zd)\d+'
+smartscan lsblk
+smartscan lsblk --source by-id "Samsung"
+smartscan lsblk --exclude '^/dev/(loop|zd)\d+'
 ```
 
 Read the [full documentation](https://ak1ra-lab.github.io/smartscan/) for shell completion, configuration reference, and advanced usage.

{smartscan-0.2.0 → smartscan-0.3.0}/docs/configuration.md

@@ -13,6 +13,12 @@ db_path = "~/.local/share/smartscan/smartscan.db"
 # Custom log file path
 log_file = "~/.local/state/smartscan/smartscan.log"
 
+# Regex patterns to exclude disk devices by symlink name or resolved path.
+# Applies to both `collect` and `lsblk` subcommands.
+# Useful for filtering out optical drives, loop devices, ZFS zvols, etc.
+# Example: exclude_patterns = ["BD-RE", '^/dev/(loop|zd)\d+']
+exclude_patterns = []
+
 # ── collect ────────────────────────────────────────────────────
 [collect]
 # Skip database writes (run once without saving)
@@ -29,17 +35,12 @@ no_save = false
 # Show only records from the last N days (overrides `since`)
 # last_days = 7
 
-# ── identify ────────────────────────────────────────────────────
-[identify]
+# ── lsblk ────────────────────────────────────────────────────
+[lsblk]
 # Restrict to specific /dev/disk/ source directories
 # (by-id, by-path, by-diskseq; default: all when empty)
 # source = ["by-id", "by-path"]
 
-# Regex patterns to exclude resolved device paths.
-# Useful for filtering out loop devices, ZFS zvols, etc.
-# Example: exclude_patterns = ["^/dev/(loop|zd)\\d+"]
-exclude_patterns = []
-
 # ── Threshold alerts ────────────────────────────────────────────
 [thresholds]
 # Master switch: set to false to disable all threshold checks

{smartscan-0.2.0 → smartscan-0.3.0}/docs/index.md

@@ -6,7 +6,7 @@ A CLI tool that runs `smartctl` on all disks, extracts key SMART health metrics,
 
 - Collects SMART data via `smartctl --all --json` from `/dev/disk/by-id/ata-*` and `/dev/disk/by-id/nvme-*`.
 - Displays results as Rich-styled tables with warnings for critical values.
-- Maps disk devices to their `/dev/disk/` identifiers (by-id, by-path, by-diskseq) with a Rich tree view (`identify` subcommand).
+- Maps disk devices to their `/dev/disk/` identifiers (by-id, by-path, by-diskseq) with a Rich tree view (`lsblk` subcommand).
 - Stores historical data in SQLite for trend analysis (`query` subcommand).
 - Supports JSON lines output for scripting.
 - Configurable via TOML config file with Pydantic validation.
@@ -57,14 +57,14 @@ smartscan --json collect
 smartscan --json query --since 2024-01-01
 ```
 
-`smartscan identify` maps block devices to their identifiers under `/dev/disk/`. It does not require root:
+`smartscan lsblk` maps block devices to their identifiers under `/dev/disk/`. It does not require root:
 
 ```shell
-smartscan identify
-smartscan identify "Samsung"
-smartscan identify --source by-id
-smartscan identify --source by-id --source by-diskseq
-smartscan --json identify
+smartscan lsblk
+smartscan lsblk "Samsung"
+smartscan lsblk --source by-id
+smartscan lsblk --source by-id --source by-diskseq
+smartscan --json lsblk
 ```
 
 Output example:

{smartscan-0.2.0 → smartscan-0.3.0}/src/smartscan/cli.py

@@ -10,7 +10,7 @@ import sys
 
 import argcomplete
 
-from .commands import do_collect, do_identify, do_query
+from .commands import do_collect, do_lsblk, do_query
 from .config import load_config
 from .constants import DEFAULT_CONFIG_PATH, DEFAULT_DB_PATH, DEFAULT_LOG_FILE
 from .exceptions import SmartScanError
@@ -52,6 +52,15 @@ def _build_parser(config: SmartScanConfig | None = None) -> argparse.ArgumentPar
         default=cfg.format == "json",
         help="Output as JSON lines instead of table format",
     )
+    parser.add_argument(
+        "--exclude",
+        dest="exclude_patterns",
+        action="append",
+        metavar="PATTERN",
+        default=cfg.exclude_patterns,
+        help="Regex patterns to exclude disk devices by symlink name or resolved path "
+        "(may be repeated; appended to config exclude_patterns)",
+    )
 
     sub = parser.add_subparsers(dest="command", required=True)
 
@@ -114,33 +123,24 @@ def _build_parser(config: SmartScanConfig | None = None) -> argparse.ArgumentPar
         help="Show extended fields in terminal output",
     )
 
-    identify_parser = sub.add_parser(
-        "identify",
+    lsblk_parser = sub.add_parser(
+        "lsblk",
         help="Map disk devices to their /dev/disk identifiers",
     )
-    identify_parser.add_argument(
+    lsblk_parser.add_argument(
         "pattern",
         nargs="?",
         default=".*",
         help="Regex pattern to filter identifier names",
     )
-    identify_parser.add_argument(
+    lsblk_parser.add_argument(
         "--source",
-        dest="identify_source",
+        dest="lsblk_source",
         action="append",
         choices=["by-id", "by-path", "by-diskseq"],
         default=None,
         help="Restrict to specific /dev/disk/ source directories "
-        "(appended to identify.source config; may be repeated; default: all)",
-    )
-    identify_parser.add_argument(
-        "--exclude",
-        dest="identify_exclude",
-        action="append",
-        metavar="PATTERN",
-        default=None,
-        help="Additional regex patterns to exclude resolved device paths "
-        "(appended to identify.exclude_patterns config; may be repeated)",
+        "(appended to lsblk.source config; may be repeated; default: all)",
     )
 
     argcomplete.autocomplete(parser)
@@ -166,12 +166,12 @@ def main() -> None:
         args.llm_config = config.llm
         args.collect_config = config.collect
         args.query_config = config.query
-        args.identify_config = config.identify
+        args.lsblk_config = config.lsblk
 
         if args.command == "query":
             do_query(args)
-        elif args.command == "identify":
-            do_identify(args)
+        elif args.command == "lsblk":
+            do_lsblk(args)
         else:
             do_collect(args)
     except SmartScanError as exc:

{smartscan-0.2.0 → smartscan-0.3.0}/src/smartscan/commands.py

@@ -8,49 +8,100 @@ import sqlite3
 import sys
 import time
 from argparse import Namespace
+from typing import Any
 
 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_identify_json,
-    print_identify_tree,
     print_json_output,
     print_llm_analysis,
+    print_lsblk_json,
+    print_lsblk_tree,
     print_query_table,
     print_table,
     row_to_fields,
 )
 from .smartctl import build_device_tree, extract_fields, find_disks, run_smartctl
-from .thresholds import check_thresholds
+from .thresholds import Alert, check_thresholds
 
 
-def do_identify(args: Namespace) -> None:
+def _build_alerts_text(alerts: list[Alert]) -> str:
+    if not alerts:
+        return "  (none)"
+    return "\n".join(f"  - {a.message}" for a in alerts)
+
+
+def _collect_one_disk(
+    disk_idx: int,
+    total_disks: int,
+    symlink: Any,
+    conn: sqlite3.Connection | None,
+    args: Namespace,
+) -> int:
+    disk_name = symlink.name
+    disk_path = os.readlink(symlink)
+
+    data, rc = run_smartctl(symlink)
+    if not data:
+        return rc
+
+    fields = extract_fields(data)
+
+    alerts: list[Alert] = []
+    if args.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 = _build_alerts_text(alerts)
+        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 < total_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)
+
+    return rc
+
+
+def do_lsblk(args: Namespace) -> None:
     from .smartctl import _SOURCE_DIRS
 
-    config_cfg = args.identify_config
+    config_cfg = args.lsblk_config
 
     sources_list = list(config_cfg.source or _SOURCE_DIRS)
-    if args.identify_source:
-        sources_list.extend(args.identify_source)
+    if args.lsblk_source:
+        sources_list.extend(args.lsblk_source)
     sources = tuple(sources_list)
 
-    exclude_list = list(config_cfg.exclude_patterns)
-    if args.identify_exclude:
-        exclude_list.extend(args.identify_exclude)
-
     try:
         devices = build_device_tree(
-            args.pattern, sources=sources, exclude_patterns=exclude_list or None
+            args.pattern,
+            sources=sources,
+            exclude_patterns=args.exclude_patterns or None,
         )
     except DiskNotFoundError as exc:
         logging.error("%s", exc)
         sys.exit(1)
 
     if args.json:
-        print_identify_json(devices)
+        print_lsblk_json(devices)
     else:
-        print_identify_tree(devices)
+        print_lsblk_tree(devices)
 
 
 def do_collect(args: Namespace) -> None:
@@ -67,56 +118,17 @@ def do_collect(args: Namespace) -> None:
             logging.error("Failed to open database at %s: %s", args.db_path, exc)
 
     try:
-        disks = find_disks(args.pattern)
+        disks = find_disks(args.pattern, exclude_patterns=args.exclude_patterns or None)
     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)
+        rc = _collect_one_disk(disk_idx, len(disks), symlink, conn, args)
         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()
 

{smartscan-0.2.0 → smartscan-0.3.0}/src/smartscan/constants.py

@@ -1,4 +1,4 @@
-"""Default paths, database schema, and error message constants."""
+"""Default paths, database migration constants, and error messages."""
 
 DEFAULT_DB_PATH = "~/.local/share/smartscan/smartscan.db"
 DEFAULT_LOG_FILE = "~/.local/state/smartscan/smartscan.log"
@@ -15,43 +15,6 @@ SMARTCTL_ERROR_MSGS = [
     "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",

{smartscan-0.2.0 → smartscan-0.3.0}/src/smartscan/database.py

@@ -10,11 +10,34 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-from .constants import DB_MIGRATIONS, DB_SCHEMA
+from .constants import DB_MIGRATIONS
 from .exceptions import InvalidDateError
+from .fields import ALL_HEALTH_FIELDS, get_field
 from .models import SmartInfo
 
 
+def _build_schema() -> str:
+    col_defs = [
+        "    id INTEGER PRIMARY KEY AUTOINCREMENT",
+        "    timestamp TEXT NOT NULL",
+        "    disk_name TEXT NOT NULL",
+        "    disk_path TEXT NOT NULL",
+    ]
+    for f in ALL_HEALTH_FIELDS:
+        col_defs.append(f"    {f.db_column} {f.db_type}")
+    col_defs.append("    raw_json TEXT")
+    col_defs.append("    llm_analysis TEXT")
+    cols = ",\n".join(col_defs)
+    return (
+        f"CREATE TABLE IF NOT EXISTS smart_info (\n{cols}\n);\n"
+        "CREATE INDEX IF NOT EXISTS idx_smart_info_disk_ts\n"
+        "    ON smart_info(disk_path, timestamp);"
+    )
+
+
+DB_SCHEMA = _build_schema()
+
+
 def _run_migrations(conn: sqlite3.Connection) -> None:
     for sql in DB_MIGRATIONS:
         try:
@@ -105,30 +128,7 @@ _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",
+    *(f.db_column for f in ALL_HEALTH_FIELDS),
     "raw_json",
     "llm_analysis",
 )
@@ -152,30 +152,7 @@ def save_to_db(
             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"],
+            *(get_field(fields, f.key) for f in ALL_HEALTH_FIELDS),
             json.dumps(raw_data, ensure_ascii=False),
             llm_analysis,
         ),