test-ssd 0.1.0__tar.gz

test_ssd-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: test-ssd
+Version: 0.1.0
+Summary: UGREEN NAS NVMe SSD screening CLI
+Author: Codex
+Keywords: nvme,ssd,fio,smartctl,nas,ugreen
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# SSD Test CLI
+
+`test-ssd` is a Python 3 CLI for screening refurbished NVMe SSDs on a UGREEN NAS or another Linux host with `smartctl`, `nvme-cli`, `fio`, `lsblk`, and `dmesg` installed.
+
+## Install
+
+From PyPI:
+
+```bash
+pipx install test-ssd
+```
+
+or:
+
+```bash
+pip install test-ssd
+```
+
+From this project directory:
+
+```bash
+./install.sh
+```
+
+That installs the package into the current Python environment and exposes both `test-ssd` and `ssdtest` as shell commands.
+
+If `~/.local/bin` is not already on your `PATH`, add it once:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+## Commands
+
+```bash
+test-ssd scan
+test-ssd run --label bb-refurb-01
+test-ssd history
+test-ssd show <run_id>
+```
+
+Module entry point:
+
+```bash
+python3 -m ssdtest scan
+```
+
+## Notes
+
+- `run` requires root.
+- The destructive test writes the full target device.
+- Reports default to `/root/nvme-tests` and include raw command outputs, `report.json`, and `report.md`.

test_ssd-0.1.0/README.md

@@ -0,0 +1,52 @@
+# SSD Test CLI
+
+`test-ssd` is a Python 3 CLI for screening refurbished NVMe SSDs on a UGREEN NAS or another Linux host with `smartctl`, `nvme-cli`, `fio`, `lsblk`, and `dmesg` installed.
+
+## Install
+
+From PyPI:
+
+```bash
+pipx install test-ssd
+```
+
+or:
+
+```bash
+pip install test-ssd
+```
+
+From this project directory:
+
+```bash
+./install.sh
+```
+
+That installs the package into the current Python environment and exposes both `test-ssd` and `ssdtest` as shell commands.
+
+If `~/.local/bin` is not already on your `PATH`, add it once:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+## Commands
+
+```bash
+test-ssd scan
+test-ssd run --label bb-refurb-01
+test-ssd history
+test-ssd show <run_id>
+```
+
+Module entry point:
+
+```bash
+python3 -m ssdtest scan
+```
+
+## Notes
+
+- `run` requires root.
+- The destructive test writes the full target device.
+- Reports default to `/root/nvme-tests` and include raw command outputs, `report.json`, and `report.md`.

test_ssd-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "test-ssd"
+version = "0.1.0"
+description = "UGREEN NAS NVMe SSD screening CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+  { name = "Codex" }
+]
+keywords = ["nvme", "ssd", "fio", "smartctl", "nas", "ugreen"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: System Administrators",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: System :: Monitoring",
+  "Topic :: System :: Systems Administration",
+  "Topic :: Utilities",
+]
+
+[project.scripts]
+ssdtest = "ssdtest.cli:main"
+test-ssd = "ssdtest.cli:main"
+
+[tool.setuptools]
+include-package-data = false
+
+[tool.setuptools.packages.find]
+include = ["ssdtest*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

test_ssd-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

test_ssd-0.1.0/ssdtest/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

test_ssd-0.1.0/ssdtest/__main__.py

@@ -0,0 +1,5 @@
+from ssdtest.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

test_ssd-0.1.0/ssdtest/cli.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from ssdtest.reports import find_report, load_history
+from ssdtest.system import inventory_devices
+from ssdtest.workflow import run_interactive
+
+
+DEFAULT_REPORT_ROOT = Path("/root/nvme-tests")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    prog = Path(sys.argv[0]).name or "test-ssd"
+    parser = argparse.ArgumentParser(prog=prog, description="UGREEN NAS NVMe SSD screening CLI")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    scan = subparsers.add_parser("scan", help="list detected NVMe devices")
+    scan.add_argument("--report-root", default=str(DEFAULT_REPORT_ROOT))
+
+    run = subparsers.add_parser("run", help="run the guided destructive SSD screening workflow")
+    run.add_argument("--label", help="human-readable label for the test run")
+    run.add_argument("--device", help="specific NVMe namespace path, for example /dev/nvme2n1")
+    run.add_argument("--report-root", default=str(DEFAULT_REPORT_ROOT))
+
+    history = subparsers.add_parser("history", help="list historical test reports")
+    history.add_argument("--report-root", default=str(DEFAULT_REPORT_ROOT))
+
+    show = subparsers.add_parser("show", help="show one historical report summary")
+    show.add_argument("run_id")
+    show.add_argument("--report-root", default=str(DEFAULT_REPORT_ROOT))
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    report_root = Path(args.report_root)
+
+    if args.command == "scan":
+        devices, _ = inventory_devices()
+        _print_scan(devices)
+        return 0
+    if args.command == "run":
+        artifacts = run_interactive(report_root=report_root, label=args.label, requested_device=args.device)
+        print("")
+        print(f"Verdict: {artifacts.verdict.verdict}")
+        print(f"Report directory: {artifacts.log_dir}")
+        print(f"Markdown report: {artifacts.log_dir / 'report.md'}")
+        print(f"JSON report: {artifacts.log_dir / 'report.json'}")
+        if artifacts.verdict.reasons:
+            print("Reasons:")
+            for item in artifacts.verdict.reasons:
+                print(f"  - {item}")
+        if artifacts.verdict.notes:
+            print("Notes:")
+            for item in artifacts.verdict.notes:
+                print(f"  - {item}")
+        return 0 if artifacts.verdict.verdict == "PASS" else 1
+    if args.command == "history":
+        _print_history(load_history(report_root))
+        return 0
+    if args.command == "show":
+        try:
+            report = find_report(report_root, args.run_id)
+        except FileNotFoundError as exc:
+            print(str(exc))
+            return 1
+        _print_show(report)
+        return 0
+    parser.error("unknown command")
+    return 2
+
+
+def _print_scan(devices) -> None:
+    print("PATH\tCTRL\tSIZE_GIB\tMODEL\tSERIAL\tSTATUS")
+    for device in devices:
+        status: list[str] = []
+        if device.is_system:
+            status.append("system")
+        if device.danger_reasons:
+            status.extend(device.danger_reasons)
+        if not status:
+            status.append("candidate")
+        print(
+            f"{device.path}\t{device.ctrl_path}\t{device.size_gib:.1f}\t{device.model}\t{device.serial}\t"
+            f"{'; '.join(status)}"
+        )
+
+
+def _print_history(records: list[dict[str, object]]) -> None:
+    if not records:
+        print("No reports found.")
+        return
+    print("RUN_ID\tSTARTED\tLABEL\tSERIAL\tVERDICT\tDURATION_S")
+    for record in records:
+        device = record.get("device", {})
+        final = record.get("final", {})
+        print(
+            f"{record.get('run_id')}\t{record.get('started_at')}\t{record.get('label')}\t"
+            f"{device.get('serial')}\t{final.get('verdict')}\t{record.get('duration_seconds')}"
+        )
+
+
+def _print_show(report: dict[str, object]) -> None:
+    device = report.get("device", {})
+    final = report.get("final", {})
+    report_path = report.get("_report_path")
+    report_dir = Path(report_path).parent if report_path else None
+    print(f"Run ID: {report.get('run_id')}")
+    print(f"Label: {report.get('label')}")
+    print(f"Device: {device.get('dev')} ({device.get('model')}, {device.get('serial')})")
+    print(f"Verdict: {final.get('verdict')}")
+    print(f"Completed: {final.get('completed')}")
+    print(f"Duration: {report.get('duration_seconds')} seconds")
+    print(f"Markdown report: {report_dir / 'report.md' if report_dir else 'unknown'}")
+    reasons = final.get("reasons") or []
+    notes = final.get("notes") or []
+    if reasons:
+        print("Reasons:")
+        for item in reasons:
+            print(f"  - {item}")
+    if notes:
+        print("Notes:")
+        for item in notes:
+            print(f"  - {item}")

test_ssd-0.1.0/ssdtest/models.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class CommandResult:
+    args: list[str]
+    stdout: str
+    stderr: str
+    exit_code: int
+    duration_seconds: float
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0
+
+
+@dataclass(slots=True)
+class DeviceInfo:
+    name: str
+    path: str
+    ctrl_path: str
+    size_bytes: int
+    model: str
+    serial: str
+    generic_path: str = ""
+    mountpoints: list[str] = field(default_factory=list)
+    child_mountpoints: list[str] = field(default_factory=list)
+    system_reasons: list[str] = field(default_factory=list)
+    danger_reasons: list[str] = field(default_factory=list)
+
+    @property
+    def size_gib(self) -> float:
+        return self.size_bytes / (1024 ** 3)
+
+    @property
+    def mounted(self) -> bool:
+        return bool(self.mountpoints)
+
+    @property
+    def has_mounted_children(self) -> bool:
+        return bool(self.child_mountpoints)
+
+    @property
+    def is_system(self) -> bool:
+        return bool(self.system_reasons)
+
+    @property
+    def is_eligible(self) -> bool:
+        return not self.danger_reasons and not self.is_system
+
+
+@dataclass(slots=True)
+class HealthSnapshot:
+    critical_warning: int | None = None
+    temperature_c: int | None = None
+    available_spare: int | None = None
+    percentage_used: int | None = None
+    data_units_written: int | None = None
+    media_errors: int | None = None
+    num_err_log_entries: int | None = None
+    unsafe_shutdowns: int | None = None
+
+    def as_dict(self) -> dict[str, int | None]:
+        return {
+            "critical_warning": self.critical_warning,
+            "temperature_c": self.temperature_c,
+            "available_spare": self.available_spare,
+            "percentage_used": self.percentage_used,
+            "data_units_written": self.data_units_written,
+            "media_errors": self.media_errors,
+            "num_err_log_entries": self.num_err_log_entries,
+            "unsafe_shutdowns": self.unsafe_shutdowns,
+        }
+
+
+@dataclass(slots=True)
+class StageResult:
+    name: str
+    ok: bool
+    skipped: bool = False
+    allow_failure: bool = False
+    exit_code: int | None = None
+    duration_seconds: float = 0.0
+    command: list[str] = field(default_factory=list)
+    log_file: str = ""
+    note: str = ""
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "name": self.name,
+            "ok": self.ok,
+            "skipped": self.skipped,
+            "allow_failure": self.allow_failure,
+            "exit_code": self.exit_code,
+            "duration_seconds": round(self.duration_seconds, 3),
+            "command": self.command,
+            "log_file": self.log_file,
+            "note": self.note,
+        }
+
+
+@dataclass(slots=True)
+class VerdictResult:
+    verdict: str
+    reasons: list[str]
+    notes: list[str]
+    completed: bool
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "verdict": self.verdict,
+            "reasons": self.reasons,
+            "notes": self.notes,
+            "completed": self.completed,
+        }
+
+
+@dataclass(slots=True)
+class RunArtifacts:
+    run_id: str
+    label: str
+    log_dir: Path
+    started_at: str
+    ended_at: str
+    duration_seconds: float
+    device: DeviceInfo
+    stage_results: dict[str, StageResult]
+    verdict: VerdictResult
+    health_before: HealthSnapshot
+    health_after: HealthSnapshot
+    health_deltas: dict[str, int | float | None]
+    dmesg_issues: list[str]

test_ssd-0.1.0/ssdtest/parsers.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import re
+import shlex
+from typing import Any
+
+from ssdtest.models import HealthSnapshot
+
+
+def _parse_int(value: str) -> int | None:
+    cleaned = value.strip()
+    if not cleaned:
+        return None
+    match = re.search(r"0x[0-9a-fA-F]+|[-+]?\d[\d,]*", cleaned)
+    if not match:
+        return None
+    token = match.group(0).replace(",", "")
+    return int(token, 0)
+
+
+def _parse_percent(value: str) -> int | None:
+    match = re.search(r"(\d+)\s*%?", value)
+    return int(match.group(1)) if match else None
+
+
+def _parse_temperature(value: str) -> int | None:
+    match = re.search(r"(-?\d+)\s*C", value)
+    if match:
+        return int(match.group(1))
+    return _parse_int(value)
+
+
+def parse_nvme_list(text: str) -> list[dict[str, str]]:
+    entries: list[dict[str, str]] = []
+    for line in text.splitlines():
+        if not line.strip() or line.startswith("Node") or line.startswith("---"):
+            continue
+        base = re.match(r"^(?P<node>\S+)\s+(?P<generic>\S+)\s+(?P<serial>\S+)\s+(?P<rest>.+)$", line)
+        if not base:
+            continue
+        extra = re.split(r"\s{2,}", base.group("rest").strip())
+        if len(extra) < 5:
+            continue
+        entries.append(
+            {
+                "node": base.group("node"),
+                "generic": base.group("generic"),
+                "serial": base.group("serial"),
+                "model": extra[0],
+                "namespace": extra[1],
+                "usage": extra[2],
+                "format": extra[3],
+                "fw_rev": extra[4],
+            }
+        )
+    return entries
+
+
+def parse_lsblk_pairs(text: str) -> list[dict[str, str]]:
+    records: list[dict[str, str]] = []
+    for line in text.splitlines():
+        if not line.strip():
+            continue
+        record: dict[str, str] = {}
+        for token in shlex.split(line):
+            if "=" not in token:
+                continue
+            key, value = token.split("=", 1)
+            record[key] = value
+        if record:
+            records.append(record)
+    return records
+
+
+def parse_nvme_smart_log(text: str) -> HealthSnapshot:
+    data: dict[str, Any] = {}
+    key_map = {
+        "critical_warning": ("critical_warning", _parse_int),
+        "temperature": ("temperature_c", _parse_temperature),
+        "available_spare": ("available_spare", _parse_percent),
+        "percentage_used": ("percentage_used", _parse_percent),
+        "data_units_written": ("data_units_written", _parse_int),
+        "media_errors": ("media_errors", _parse_int),
+        "num_err_log_entries": ("num_err_log_entries", _parse_int),
+        "unsafe_shutdowns": ("unsafe_shutdowns", _parse_int),
+    }
+    for line in text.splitlines():
+        if ":" not in line:
+            continue
+        raw_key, raw_value = line.split(":", 1)
+        key = raw_key.strip().lower()
+        if key in key_map:
+            field_name, parser = key_map[key]
+            data[field_name] = parser(raw_value)
+    return HealthSnapshot(**data)
+
+
+def parse_smartctl_x(text: str) -> HealthSnapshot:
+    data: dict[str, Any] = {}
+    patterns = {
+        "critical_warning": (r"Critical Warning:\s*(.+)$", _parse_int),
+        "temperature_c": (r"Temperature:\s*(.+)$", _parse_temperature),
+        "available_spare": (r"Available Spare:\s*(.+)$", _parse_percent),
+        "percentage_used": (r"Percentage Used:\s*(.+)$", _parse_percent),
+        "data_units_written": (r"Data Units Written:\s*(.+)$", _parse_int),
+        "media_errors": (r"Media and Data Integrity Errors:\s*(.+)$", _parse_int),
+        "num_err_log_entries": (r"Error Information Log Entries:\s*(.+)$", _parse_int),
+        "unsafe_shutdowns": (r"Unsafe Shutdowns:\s*(.+)$", _parse_int),
+    }
+    for field_name, (pattern, parser) in patterns.items():
+        match = re.search(pattern, text, re.MULTILINE | re.IGNORECASE)
+        if match:
+            data[field_name] = parser(match.group(1))
+    return HealthSnapshot(**data)
+
+
+def merge_health(primary: HealthSnapshot, fallback: HealthSnapshot) -> HealthSnapshot:
+    data: dict[str, int | None] = {}
+    for field_name in HealthSnapshot.__dataclass_fields__:
+        primary_value = getattr(primary, field_name)
+        data[field_name] = primary_value if primary_value is not None else getattr(fallback, field_name)
+    return HealthSnapshot(**data)
+
+
+def parse_nvme_error_log(text: str) -> dict[str, int]:
+    counts = [_parse_int(match.group(1)) for match in re.finditer(r"error_count\s*:\s*(.+)$", text, re.MULTILINE)]
+    clean_counts = [count for count in counts if count is not None]
+    return {
+        "entries_seen": len(clean_counts),
+        "max_error_count": max(clean_counts) if clean_counts else 0,
+    }
+
+
+def extract_new_dmesg_lines(before: str, after: str) -> list[str]:
+    before_lines = before.splitlines()
+    after_lines = after.splitlines()
+    if len(after_lines) >= len(before_lines) and after_lines[: len(before_lines)] == before_lines:
+        return after_lines[len(before_lines) :]
+
+    index = 0
+    while index < min(len(before_lines), len(after_lines)) and before_lines[index] == after_lines[index]:
+        index += 1
+    return after_lines[index:]
+
+
+def detect_dmesg_issues(before: str, after: str) -> list[str]:
+    issue_lines: list[str] = []
+    patterns = [
+        r"\bnvme\d+\b.*\b(reset|timeout|abort|failed|error)\b",
+        r"\bI/O error\b",
+        r"\bcritical medium error\b",
+        r"\bcontroller is down\b",
+        r"\bPCIe Bus Error\b",
+    ]
+    for line in extract_new_dmesg_lines(before, after):
+        lowered = line.lower()
+        if "nvme" not in lowered and "i/o error" not in lowered and "pcie" not in lowered:
+            continue
+        if any(re.search(pattern, line, re.IGNORECASE) for pattern in patterns):
+            issue_lines.append(line)
+    return issue_lines