wraith-cli 1.5.0__tar.gz → 1.7.0__tar.gz

wraith_cli-1.7.0/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run *)",
+      "Bash(./bin/run_tests.sh)",
+      "Bash(git add *)",
+      "Bash(git commit -m '👻 feature/TJP-12062: add enterprise NAS management suite *)",
+      "Bash(python3 -)",
+      "Bash(git -C /home/thomaspeoples/pjt-nas/nas/SovereignDocs/gitea-repos status --short)",
+      "Bash(git -C /home/thomaspeoples/pjt-nas/nas/SovereignDocs/gitea-repos branch --show-current)"
+    ]
+  }
+}

{wraith_cli-1.5.0 → wraith_cli-1.7.0}/CHANGELOG.md

@@ -1,3 +1,7 @@
+## v1.7.0 (2026-06-12)
+
+## v1.6.0 (2026-04-07)
+
 ## v1.5.0 (2026-04-06)
 
 ## v1.4.0 (2026-04-05)

{wraith_cli-1.5.0 → wraith_cli-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wraith-cli
-Version: 1.5.0
+Version: 1.7.0
 Summary: Sovereign Command Centre for a Ghost Stack
 Project-URL: Homepage, https://git.thomaspeoples.com/thomaspeoples/wraith-cli
 Project-URL: Documentation, https://www.thomaspeoples.com/gitea-repos/wraith-cli/
@@ -60,12 +60,35 @@ Description-Content-Type: text/markdown
 
 
 # 👻 Wraith-CLI
-### *Sovereign Orchestration for the Ghost Stack*
+### *Sovereign Orchestration & NAS Management for the Ghost Stack*
 
 **Wraith-CLI** is the nervous system of the Ghost Stack. It bridges the gap between
-high-level container orchestration and bare-metal reality, providing the "Ghost Factory"
-for instant project scaffolding.
+high-level container orchestration and bare-metal reality — instant project scaffolding,
+container operations, and a full NAS management suite in one binary.
 
+---
+
+## 🗄️ NAS Management Suite
+
+| Command | Purpose |
+|---|---|
+| `wraith disks` | Physical disk inventory — model, serial, capacity, HDD/SSD, bus |
+| `wraith storage` | Filesystem usage with configurable warn/crit thresholds |
+| `wraith raid` | mdraid array and ZFS pool health |
+| `wraith smart /dev/sda` | SMART verdict + failure-predicting attributes per drive |
+| `wraith shares` | NFS exports and Samba shares, guest access flagged |
+| `wraith snap` | ZFS/btrfs snapshot create / list / prune (safe by design) |
+| `wraith doctor` | Full health check suite — cron-friendly exit codes, webhook/ntfy alerts |
+| `wraith report` | Timestamped markdown/JSON audit reports |
+
+Every read-only command takes `--json` — pipe Wraith straight into dashboards,
+monitoring stacks, or fleet tooling. Unattended monitoring is one cron line:
+
+```cron
+*/30 * * * * wraith doctor --notify
+```
+
+See the [NAS Management docs](docs/nas.md) for full coverage.
 
 ---
 

{wraith_cli-1.5.0 → wraith_cli-1.7.0}/README.md

@@ -5,12 +5,35 @@
 
 
 # 👻 Wraith-CLI
-### *Sovereign Orchestration for the Ghost Stack*
+### *Sovereign Orchestration & NAS Management for the Ghost Stack*
 
 **Wraith-CLI** is the nervous system of the Ghost Stack. It bridges the gap between
-high-level container orchestration and bare-metal reality, providing the "Ghost Factory"
-for instant project scaffolding.
+high-level container orchestration and bare-metal reality — instant project scaffolding,
+container operations, and a full NAS management suite in one binary.
 
+---
+
+## 🗄️ NAS Management Suite
+
+| Command | Purpose |
+|---|---|
+| `wraith disks` | Physical disk inventory — model, serial, capacity, HDD/SSD, bus |
+| `wraith storage` | Filesystem usage with configurable warn/crit thresholds |
+| `wraith raid` | mdraid array and ZFS pool health |
+| `wraith smart /dev/sda` | SMART verdict + failure-predicting attributes per drive |
+| `wraith shares` | NFS exports and Samba shares, guest access flagged |
+| `wraith snap` | ZFS/btrfs snapshot create / list / prune (safe by design) |
+| `wraith doctor` | Full health check suite — cron-friendly exit codes, webhook/ntfy alerts |
+| `wraith report` | Timestamped markdown/JSON audit reports |
+
+Every read-only command takes `--json` — pipe Wraith straight into dashboards,
+monitoring stacks, or fleet tooling. Unattended monitoring is one cron line:
+
+```cron
+*/30 * * * * wraith doctor --notify
+```
+
+See the [NAS Management docs](docs/nas.md) for full coverage.
 
 ---
 

wraith_cli-1.7.0/docs/nas.md

@@ -0,0 +1,88 @@
+# NAS Management
+
+Wraith turns your Ghost Stack node into a fully managed NAS. The
+suite covers hardware introspection, capacity monitoring, share
+discovery, snapshot lifecycle, and automated health enforcement —
+all from one binary, all scriptable via `--json`.
+
+## Command Overview
+
+| Command | What it does |
+|---|---|
+| `wraith disks` | Physical disk inventory: model, serial, capacity, HDD/SSD, bus |
+| `wraith storage` | Filesystem usage with warn/crit thresholds |
+| `wraith raid` | mdraid array and ZFS pool health |
+| `wraith smart <device>` | Per-drive SMART verdict and failure-predicting attributes |
+| `wraith shares` | NFS exports and Samba shares, guest-access flagged |
+| `wraith snap` | ZFS/btrfs snapshot list / create / prune |
+| `wraith doctor` | Full health check suite with exit codes and alerting |
+| `wraith report` | Point-in-time audit report (markdown or JSON) |
+
+Every read-only command accepts `--json` for machine-readable
+output, making Wraith a drop-in data source for dashboards,
+monitoring pipelines, and fleet tooling.
+
+## The Doctor
+
+`wraith doctor` is the heartbeat of the system. It checks:
+
+- Docker daemon responsiveness
+- Tailscale mesh connectivity
+- Storage utilisation against configured thresholds
+- RAID array and ZFS pool degradation
+- SMART self-assessment on every physical disk
+- HTTP health of every configured stack service
+
+It exits non-zero when anything is critical, so it slots straight
+into cron:
+
+```cron
+*/30 * * * * wraith doctor --notify || logger "NAS degraded"
+```
+
+With `--notify`, warn/crit findings are pushed to your configured
+webhook or [ntfy](https://ntfy.sh) topic.
+
+## Configuration
+
+Add to `.wraith.yaml`:
+
+```yaml
+storage_warn_pct: 80
+storage_crit_pct: 90
+alerts:
+  webhook_url: https://ntfy.sh/my-nas-alerts
+  kind: ntfy        # or "webhook" for a JSON POST
+```
+
+## Snapshots
+
+Snapshot lifecycle management with a safety guarantee: `snap prune`
+only ever considers snapshots Wraith itself created (the `wraith-`
+prefix). Manual snapshots are never touched.
+
+```bash
+wraith snap create tank/data          # ZFS, auto-named
+wraith snap create /srv/data --btrfs-dest /srv/.snapshots/nightly
+wraith snap list tank/data
+wraith snap prune tank/data --keep 7  # confirm before destroy
+```
+
+A nightly rotation is two cron lines:
+
+```cron
+0 2 * * * wraith snap create tank/data
+30 2 * * * wraith snap prune tank/data --keep 14 --yes
+```
+
+## Audit Reports
+
+`wraith report` captures disks, storage, RAID state, and the full
+doctor suite into a timestamped document — an audit trail for
+compliance, capacity planning, or a paper trail before and after
+hardware changes.
+
+```bash
+wraith report                          # markdown, timestamped name
+wraith report -f json -o nightly.json  # feed it to anything
+```

{wraith_cli-1.5.0 → wraith_cli-1.7.0}/docs/usage.md

@@ -18,7 +18,7 @@ $ [OPTIONS] COMMAND [ARGS]...
 **Commands**:
 
 * `init`: Bootstrap a new Wraith environment.
-* `status`: Check the heartbeat of the OpenViking Stack.
+* `status`: Check the heartbeat of the Ghost Stack.
 * `health`: Visualise health of all configured services.
 * `update`: Sync Wraith with the latest PyPI release.
 * `ps`: List running containers with Sovereign...
@@ -28,6 +28,14 @@ $ [OPTIONS] COMMAND [ARGS]...
 * `logs`: Unified hardware health and logging portal.
 * `mesh`: Map the Tailscale Ghost Mesh network.
 * `audit`: Execute a Sovereign security and...
+* `disks`: Inventory the physical disks in this NAS.
+* `storage`: Show filesystem usage across all mounted...
+* `raid`: Report RAID array and ZFS pool health.
+* `smart`: Deep-dive SMART health for a single drive.
+* `shares`: List network shares exposed by this NAS.
+* `doctor`: Run the full NAS health check suite.
+* `report`: Generate a point-in-time NAS health report.
+* `snap`: Manage ZFS/btrfs snapshots.
 
 ## `init`
 
@@ -48,9 +56,9 @@ $ init [OPTIONS]
 
 ## `status`
 
-Check the heartbeat of the OpenViking Stack.
+Check the heartbeat of the Ghost Stack.
 
-Polls the configured VIKING_BASE_URL health
+Polls the configured WRAITH_VIKING_API health
 endpoint to verify if the orchestrator API is responsive.
 
 **Usage**:
@@ -154,7 +162,7 @@ Performs a nuclear reset: stops the container,
 purges the local registration data, and restarts
 the service to force a fresh handshake with Gitea.
 
-Requires GITEA_COMPOSE_PATH as an envelope variable
+Requires GITEA_COMPOSE_PATH as an environment variable
 
 **Usage**:
 
@@ -243,3 +251,219 @@ $ audit [OPTIONS]
 **Options**:
 
 * `--help`: Show this message and exit.
+
+## `disks`
+
+Inventory the physical disks in this NAS.
+
+Enumerates block devices with model, serial, capacity,
+media type (HDD/SSD), bus, and active mountpoints.
+
+**Usage**:
+
+```console
+$ disks [OPTIONS]
+```
+
+**Options**:
+
+* `--json`: Emit machine-readable JSON.
+* `--help`: Show this message and exit.
+
+## `storage`
+
+Show filesystem usage across all mounted volumes.
+
+Colour-codes utilisation against the configured warn/crit
+thresholds (storage_warn_pct / storage_crit_pct).
+
+**Usage**:
+
+```console
+$ storage [OPTIONS]
+```
+
+**Options**:
+
+* `--json`: Emit machine-readable JSON.
+* `--help`: Show this message and exit.
+
+## `raid`
+
+Report RAID array and ZFS pool health.
+
+Parses /proc/mdstat for Linux software RAID and queries
+zpool for ZFS pool state. Degraded arrays surface in red.
+
+**Usage**:
+
+```console
+$ raid [OPTIONS]
+```
+
+**Options**:
+
+* `--json`: Emit machine-readable JSON.
+* `--help`: Show this message and exit.
+
+## `smart`
+
+Deep-dive SMART health for a single drive.
+
+Pulls the self-assessment verdict, temperature, power-on
+hours, and failure-predicting attributes via smartctl.
+
+**Usage**:
+
+```console
+$ smart [OPTIONS] DEVICE
+```
+
+**Arguments**:
+
+* `DEVICE`: Block device path (e.g. /dev/sda)  [required]
+
+**Options**:
+
+* `--json`: Emit machine-readable JSON.
+* `--help`: Show this message and exit.
+
+## `shares`
+
+List network shares exposed by this NAS.
+
+Discovers NFS exports (/etc/exports) and Samba shares
+(smb.conf), flagging guest-accessible SMB shares.
+
+**Usage**:
+
+```console
+$ shares [OPTIONS]
+```
+
+**Options**:
+
+* `--json`: Emit machine-readable JSON.
+* `--help`: Show this message and exit.
+
+## `doctor`
+
+Run the full NAS health check suite.
+
+Checks Docker, Tailscale, storage thresholds, RAID/pool
+health, per-disk SMART status, and service endpoints.
+Exits non-zero on any critical finding — cron-friendly.
+
+**Usage**:
+
+```console
+$ doctor [OPTIONS]
+```
+
+**Options**:
+
+* `--json`: Emit machine-readable JSON.
+* `--notify`: Send warn/crit findings to the configured webhook.
+* `--help`: Show this message and exit.
+
+## `report`
+
+Generate a point-in-time NAS health report.
+
+Captures disks, storage, RAID state, and the full doctor
+check suite into a timestamped markdown or JSON document —
+an audit trail for compliance and capacity planning.
+
+**Usage**:
+
+```console
+$ report [OPTIONS]
+```
+
+**Options**:
+
+* `-o, --output PATH`: Report file destination.
+* `-f, --format TEXT`: Report format: md or json.  [default: md]
+* `--help`: Show this message and exit.
+
+## `snap`
+
+Manage ZFS/btrfs snapshots.
+
+**Usage**:
+
+```console
+$ snap [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `list`: List ZFS snapshots, newest last.
+* `create`: Create a snapshot of a ZFS dataset or...
+* `prune`: Prune old wraith-created snapshots from a...
+
+### `snap list`
+
+List ZFS snapshots, newest last.
+
+**Usage**:
+
+```console
+$ snap list [OPTIONS] [DATASET]
+```
+
+**Arguments**:
+
+* `[DATASET]`: Limit to one ZFS dataset.
+
+**Options**:
+
+* `--json`: Emit machine-readable JSON.
+* `--help`: Show this message and exit.
+
+### `snap create`
+
+Create a snapshot of a ZFS dataset or btrfs subvolume.
+
+**Usage**:
+
+```console
+$ snap create [OPTIONS] TARGET
+```
+
+**Arguments**:
+
+* `TARGET`: ZFS dataset (pool/data) or btrfs subvolume path.  [required]
+
+**Options**:
+
+* `-n, --name TEXT`: Snapshot name override.
+* `--btrfs-dest TEXT`: Treat target as btrfs subvolume; snapshot here.
+* `--help`: Show this message and exit.
+
+### `snap prune`
+
+Prune old wraith-created snapshots from a dataset.
+
+Only snapshots named with the wraith- prefix are candidates;
+manually created snapshots are never touched.
+
+**Usage**:
+
+```console
+$ snap prune [OPTIONS] DATASET
+```
+
+**Arguments**:
+
+* `DATASET`: ZFS dataset to prune.  [required]
+
+**Options**:
+
+* `-k, --keep INTEGER`: Snapshots to retain.  [default: 7]
+* `-y, --yes`: Skip confirmation prompt.
+* `--help`: Show this message and exit.

{wraith_cli-1.5.0 → wraith_cli-1.7.0}/mkdocs.yml

@@ -19,6 +19,7 @@ theme:
 nav:
   - Home: index.md
   - Usage: usage.md
+  - NAS Management: nas.md
   - Technical Reference: reference.md
   - Architecture Reference: architecture.md
   - Security Statement: security.md

{wraith_cli-1.5.0 → wraith_cli-1.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wraith-cli"
-version = "1.5.0"
+version = "1.7.0"
 description = "Sovereign Command Centre for a Ghost Stack"
 readme = "README.md"
 requires-python = ">=3.12"

{wraith_cli-1.5.0 → wraith_cli-1.7.0}/src/wraith_cli/config.py

@@ -17,6 +17,11 @@ class TemplateModel(BaseModel):
     url: str
 
 
+class AlertsModel(BaseModel):
+    webhook_url: str | None = None
+    kind: str = "webhook"  # "webhook" (JSON POST) or "ntfy" (text POST)
+
+
 class WraithSettings(BaseSettings):
     stack_name: str = "Ghost Stack"
     viking_api: HttpUrl | None = None
@@ -25,6 +30,11 @@ class WraithSettings(BaseSettings):
     docker_enabled: bool = False
     tailscale_enabled: bool = False
 
+    # NAS management
+    alerts: AlertsModel = Field(default_factory=AlertsModel)
+    storage_warn_pct: int = 80
+    storage_crit_pct: int = 90
+
     # Provider Settings
     forge_api_url: str | None = None
     forge_token: str | None = None