rw-sysstable 0.2.0__tar.gz

rw_sysstable-0.2.0/.dockerignore

@@ -0,0 +1,61 @@
+# Git
+.git/
+.gitignore
+.gitattributes
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Project docs (not needed at runtime)
+docs/
+*.md
+CHANGELOG.md
+LICENSE
+CODE_OF_CONDUCT.md
+CONTRIBUTING.md
+SECURITY.md
+
+# Tests (not needed at runtime)
+tests/
+*.test.py
+
+# Hermes plugin (installed separately)
+hermes-plugin/
+
+# CI/CD
+.github/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Coverage
+htmlcov/
+.coverage
+.coverage.*
+
+# Environment
+.env
+.env.*
+
+# Pre-commit
+.pre-commit-config.yaml
+
+# Config
+Makefile
+MANIFEST.in
+pyproject.toml
+docker-compose.yml

rw_sysstable-0.2.0/.github/workflows/lint.yml

@@ -0,0 +1,39 @@
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv venv
+          source .venv/bin/activate
+          uv pip install ruff
+
+      - name: Check formatting
+        run: |
+          source .venv/bin/activate
+          ruff format src/ tests/ --check
+
+      - name: Lint
+        run: |
+          source .venv/bin/activate
+          ruff check src/ tests/

rw_sysstable-0.2.0/.github/workflows/pre-commit.yml

@@ -0,0 +1,21 @@
+name: Pre-commit CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Run pre-commit
+        uses: pre-commit/action@v3.0.1

rw_sysstable-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,63 @@
+name: Release & Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install build dependencies
+        run: uv venv && source .venv/bin/activate && uv pip install build
+
+      - name: Build package
+        run: |
+          source .venv/bin/activate
+          python -m build
+
+      - name: Generate changelog
+        id: changelog
+        run: |
+          TAG="${{ github.ref_name }}"
+          VERSION="${TAG#v}"
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          awk -v ver="$VERSION" '
+            $0 ~ "^## \\\\[" ver "\\\\]" { found=1; next }
+            found && /^## / { exit }
+            found { print }
+          ' CHANGELOG.md > _release_body.md || true
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body_path: _release_body.md
+          generate_release_notes: false
+          make_latest: true
+          files: dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          # Uncomment to test on TestPyPI first:
+          # repository-url: https://test.pypi.org/legacy/

rw_sysstable-0.2.0/.github/workflows/smoke-test.yml

@@ -0,0 +1,69 @@
+name: Smoke Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+
+      - name: Build package
+        run: |
+          uv venv
+          source .venv/bin/activate
+          uv pip install build
+          python -m build
+
+      - name: Install from built wheel
+        run: |
+          source .venv/bin/activate
+          uv pip install dist/*.whl
+
+      - name: Smoke test — CLI help
+        run: |
+          source .venv/bin/activate
+          sysstable --help
+
+      - name: Smoke test — subcommand exists
+        run: |
+          source .venv/bin/activate
+          sysstable init --help
+          sysstable start --help
+          sysstable status --help
+          sysstable history --help
+          sysstable trend --help
+          sysstable kill-list --help
+          sysstable processes --help
+          sysstable never-kill --help
+          sysstable resolution-history --help
+          sysstable uninstall --help
+
+      - name: Smoke test — import check
+        run: |
+          source .venv/bin/activate
+          python3 -c "from sysstable import thresholds, config, collector, database, events, daemon, socketd, cli, process_watch, state_machine, resolver; print('All modules import OK')"
+
+      - name: Smoke test — plugin imports
+        run: |
+          source .venv/bin/activate
+          python3 -c "import sys; sys.path.insert(0, 'hermes-plugin'); from rapidwebs_sysstable import register; print('Plugin imports OK')"

rw_sysstable-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,60 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+
+      - name: Install dependencies
+        run: |
+          uv venv
+          source .venv/bin/activate
+          uv pip install -e ".[dev]"
+
+      - name: Run tests with coverage
+        run: |
+          source .venv/bin/activate
+          uv pip install pytest-cov
+          pytest tests/ -v --tb=short --cov=src/sysstable --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Upload coverage artifact
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ github.sha }}
+          path: coverage.xml
+          retention-days: 7

rw_sysstable-0.2.0/.gitignore

@@ -0,0 +1,31 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Coverage
+.coverage
+htmlcov/
+.coverage.*
+
+# Environment
+.env
+.env.*
+
+# Build artifacts
+*.so
+*.dylib

rw_sysstable-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: debug-statements

rw_sysstable-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

rw_sysstable-0.2.0/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] — 2026-07-03
+
+### Added
+
+- **CRITICAL severity level**: Added `Severity.CRITICAL` enum with critical watermark threshold; `_overall_severity()` upgraded to treat CRITICAL as highest
+- **Process Intelligence Engine**: `ProcessSnapshot`/`KillListEntry` dataclasses, `fetch_all_processes()` with 5s timeout safety, lightweight mode (top 20 by memory) for NORMAL state
+- **NoKillManager**: 3-layer protected-process manager (hard-coded + user config + CLI/ENV). Triple (pid, name, cmdline) matching prevents PID-recycling attacks. `SYSTABLE_NEVER_KILL` env var support
+- **ProcessScorer**: Weighted memory/cpu/io/history scoring algorithm with false-positive heuristic (cached process detection penalty)
+- **KillListGenerator**: Filter protected → score → sort → periodic DB persist. Tracks generation count for persistence interval
+- **DB Schema**: 3 new tables — `kill_list_generations` (trigger/entries/ram), `resolution_events` (action/pid/signal/success), `process_snapshots` (full per-process metrics with pid+name index). 7 new query/save/prune methods
+- **Pressure State Machine**: Full lifecycle — NORMAL → CRITICAL_DETECTED → CONFIRMING → COUNTDOWN → RESOLVING → RECOVERED (or MANUAL_INTERVENTION after max retries)
+- **Resolution Executor**: `MemoryPressureResolver` with re-entrance guard, SIGTERM→SIGKILL chain with configurable timeout, pause/unpause with reverse linear backoff schedule, systemd service stop support, insufficient-memory-freed detection
+- **CLI Commands**: `kill-list` (view generation history), `processes` (one-shot or --watch), `never-kill` (display protected list), `resolution-history` (event log). `--never-kill` on `sysstable start`
+- **Plugin v0.2.0**: CRITICAL severity blocks ALL delegation in `pre_tool_call`, resolution context injection in `pre_llm_call`, `resolution_active` field in state output
+- **Integration Tests**: Full e2e lifecycle test (NORMAL→RESOLVING→RECOVERED) and manual intervention test (3 failed retries)
+
+### Changed
+
+- **DEFAULT_CONFIG**: 6 new config blocks — `memory_pressure`, `resolution`, `process_scoring`, `never_kill`; `thresholds.ram_available_mb` now includes `critical: 128`
+- **Daemon loop**: Process snapshot collection during pressure states (FULL) and NORMAL (LIGHTWEIGHT); state machine integration; CRITICAL severity in state output
+- **80 tests** (up from 27), 0 lint
+
+### Security
+
+- Triple (pid, name, cmdline) matching prevents PID-recycling attacks
+- Fork bomb mitigation: max 3 resolution cycles, then MANUAL_INTERVENTION state
+- Re-entrance guard prevents concurrent resolution execution
+- HARD_CODED_NO_KILL immutable frozen set for system-critical processes
+
+## [0.1.0] — 2026-07-02
+
+### Added (open-source package)
+
+- **README**: full docs with badges, architecture diagram, quick start, config reference
+- **LICENSE**: MIT
+- **CONTRIBUTING.md**: dev workflow, branch strategy, commit conventions
+- **CODE_OF_CONDUCT.md**: Contributor Covenant v2.1
+- **SECURITY.md**: supported versions, reporting process, security considerations
+- **CHANGELOG.md**: keepachangelog format
+- **GitHub Actions**: tests (4 Python versions), lint (ruff), publish (PyPI), release (GitHub Releases)
+- **Makefile**: install, test, lint, format, check, clean, build, publish, docker, systemd targets
+- **MANIFEST.in**: include templates, plugins, docs in sdist
+- **.pre-commit-config.yaml**: ruff lint + format, trailing whitespace, yaml/toml checks
+- **Dockerfile**: multi-stage build, slim runtime, non-root user
+- **docker-compose.yml**: volume mounts for /proc, /sys, persistence
+- **.gitignore**: comprehensive ignores for Python, IDE, OS, build artifacts
+- **pyproject.toml**: full metadata, classifiers, URLs, ruff config, pytest config
+- **Bugfix**: config shallow copy → deep copy (nested dict isolation)
+- **Bugfix**: orphan `main.py` placeholder removed
+- **Bugfix**: events dispatch parameter naming (`thresholds_config` → `config`)
+- **Bugfix**: webhook payload reference cleanup
+
+### Added (original release)
+
+- **Daemon** (`sysstabled`): background collection loop, signal handling,
+  configurable interval (default 15s), SQLite WAL-mode storage with
+  configurable retention (24h–14d).
+- **Collector**: psutil-based metric gathering for RAM, ZRAM, SWAP, CPU,
+  load averages, iowait, disk partitions, disk IO rates, network interfaces,
+  battery, temperatures, and uptime.
+- **Threshold Engine**: configurable yellow/orange/red watermarks with
+  reverse-aware comparison (lower=worse for RAM/disk, higher=worse for CPU/temp).
+  Evaluated each cycle; highest severity determines overall system state.
+- **Event Dispatch**: shell hooks, webhooks (HTTP POST), and Python extension
+  scripts — fired per-violation each cycle.
+- **Unix Socket IPC**: daemon listens on `AF_UNIX`; CLI queries metrics
+  without polling.
+- **CLI** (`sysstable`): 7 commands — `init`, `start`, `stop`, `status`,
+  `history`, `trend`, `uninstall`.
+- **Hermes Plugin**: 2 hooks — `pre_tool_call` (blocks delegation on RED,
+  warns on YELLOW/ORANGE) and `pre_llm_call` (injects `[SYSTEM STATUS]`
+  context with violation details).
+- **Systemd Service Template**: `--user` unit with `Restart=on-failure`.
+- **Test Suite**: 20 tests covering collector, database, thresholds, config,
+  events, and plugin logic.
+- **Packaging**: hatchling-based `pyproject.toml`, `sysstable` CLI entry point,
+  optional dev dependencies.

rw_sysstable-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,53 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards
+of acceptable behavior and will take appropriate and fair corrective action.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project team at dev@rapidwebs.com. All complaints will be
+reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

rw_sysstable-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Contributing to RapidWebs-SysStable
+
+Thank you for considering contributing! This document outlines the process.
+
+## Code of Conduct
+
+This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating
+you agree to uphold its terms.
+
+## Getting Started
+
+1. **Fork** the repository.
+2. **Clone** your fork:
+   ```bash
+   git clone https://github.com/your-username/rapidwebs-sysstable.git
+   cd rapidwebs-sysstable
+   ```
+3. **Create a virtual environment**:
+   ```bash
+   uv venv
+   source .venv/bin/activate
+   ```
+4. **Install dev dependencies**:
+   ```bash
+   uv pip install -e ".[dev]"
+   ```
+
+## Development Workflow
+
+1. **Create a branch** off `main`:
+   ```bash
+   git checkout -b feat/your-feature-name
+   ```
+
+2. **Run tests** before and after your changes:
+   ```bash
+   pytest tests/ -v
+   ```
+
+3. **Lint your code**:
+   ```bash
+   ruff check src/ tests/
+   ruff format src/ tests/ --check
+   ```
+
+4. **Run the full verification**:
+   ```bash
+   make check
+   ```
+
+5. **Commit** using conventional commits:
+   - `feat: ...` — new feature
+   - `fix: ...` — bug fix
+   - `docs: ...` — documentation
+   - `refactor: ...` — code restructure
+   - `test: ...` — tests only
+   - `ci: ...` — CI/CD changes
+
+6. **Push and open a Pull Request** against `main`.
+
+## Project Structure
+
+```
+src/sysstable/           # Main package
+  ├── __init__.py        # Version + public API
+  ├── __main__.py        # python -m sysstable
+  ├── daemon.py          # Collection loop + state management
+  ├── collector.py       # psutil metric wrappers
+  ├── thresholds.py      # Watermark matching engine
+  ├── events.py          # Shell hooks, webhooks, python extensions
+  ├── database.py        # SQLite store (WAL mode)
+  ├── socketd.py         # Unix socket IPC
+  ├── cli.py             # Click CLI
+  └── config.py          # YAML config loader
+tests/                   # Pytest test suite
+docs/                    # Systemd service, docs
+hermes-plugin/           # Hermes integration plugin
+```
+
+## Testing Guidelines
+
+- Write tests before fixing bugs (TDD preferred).
+- Use `tempfile` for ephemeral SQLite databases.
+- Tests must not require a running daemon.
+- Test threshold logic with edge cases (None values, boundary conditions).

rw_sysstable-0.2.0/Dockerfile

@@ -0,0 +1,32 @@
+# syntax=docker/dockerfile:1
+FROM python:3.12-slim AS base
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── builder ──
+FROM base AS builder
+WORKDIR /build
+COPY . .
+RUN pip install build && python -m build
+
+# ── runtime ──
+FROM python:3.12-slim
+
+RUN adduser --system --group sysstable
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    procps \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /build/dist/*.whl /tmp/
+RUN pip install /tmp/rw_sysstable-*.whl && rm /tmp/rw_sysstable-*.whl
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD sysstable status >/dev/null 2>&1 || exit 1
+
+USER sysstable
+ENTRYPOINT ["sysstable"]
+CMD ["start", "--foreground"]

rw_sysstable-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RapidWebs Enterprise
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rw_sysstable-0.2.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include *.toml
+recursive-include src/sysstable *.py
+recursive-include hermes-plugin *
+recursive-include docs *
+recursive-include tests *.py