syspanel 0.1.0__tar.gz

syspanel-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# Environment
+env/
+venv/
+ENV/
+VENV/
+.venv/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Build and distribution
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+*.whl
+*.tar.gz
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Testing / typing / linting
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.tox/
+
+# Data and downloads
+dl/
+downloads/
+
+# Databases
+*.db
+*.sqlite
+*.sqlite3
+
+# Secrets / local config
+.env
+*.local
+
+# App runtime data
+.system-tools/
+*.jsonl
+
+# IDE and OS
+.DS_Store
+.vscode/
+.idea/
+*.swp
+*.swo
+*~

syspanel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pandiyaraj Karuppasamy
+
+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.

syspanel-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: syspanel
+Version: 0.1.0
+Summary: A local Windows system dashboard: resource monitor, disk tree viewer, battery health, process manager, service watchlist, startup monitor and cleanup manager.
+Project-URL: Repository, https://github.com/pandiyarajk/syspanel
+Project-URL: Issues, https://github.com/pandiyarajk/syspanel/issues
+Author-email: Pandiyaraj Karuppasamy <pandiyarajk@live.com>
+License: MIT
+License-File: LICENSE
+Keywords: battery-health,dashboard,disk-usage,process-manager,system-monitor,windows
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.110
+Requires-Dist: jinja2>=3.1
+Requires-Dist: psutil>=6.0
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: send2trash>=1.8
+Requires-Dist: uvicorn[standard]>=0.29
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=4.0; extra == 'dev'
+Provides-Extra: windows
+Requires-Dist: pywin32>=306; (sys_platform == 'win32') and extra == 'windows'
+Description-Content-Type: text/markdown
+
+# syspanel
+
+A local, self-contained Windows system dashboard: resource monitor, disk tree
+viewer, battery health, process manager, service watchlist, startup monitor,
+cleanup manager, and restart control — one web app, no cloud, no build step.
+
+## Install
+
+```bash
+pip install syspanel[windows]
+```
+
+## Run
+
+```bash
+syspanel
+```
+
+Opens `http://127.0.0.1:8765/` in your browser. Useful flags:
+
+```bash
+syspanel --no-browser          # don't auto-open a tab
+syspanel --read-only           # disable every mutating route
+syspanel --host 0.0.0.0 --allow-remote   # expose beyond localhost (prints a bearer token)
+```
+
+## Modules
+
+| Module | What it shows |
+|---|---|
+| Resources | Live CPU / RAM / network / disk I/O, 1s push over WebSocket |
+| Disk Tree | Drive-picker dropdown, squarified treemap + sortable/clickable table, background scan with progress that survives navigating away and back |
+| Battery | Design vs. current capacity, cycle count, wear verdict (via `powercfg`) |
+| Processes | Sortable/searchable process table; kill with denylist protection |
+| Services | Full service list, a persisted watchlist with alerts, start/stop/restart |
+| Startup | Registry Run/RunOnce, Startup folder, and logon scheduled tasks; enable/disable/delete |
+| Cleanup | Declarative target catalog (Temp, crash dumps, Windows Update cache, Recycle Bin, custom age/retention rules); dry-run preview before every delete |
+| Power | Schedule a restart with a cancellable countdown; requires typing a confirm phrase |
+
+Admin-only actions (Windows\Temp, service control, killing other users'
+processes) show a lock badge when unelevated; use the **Relaunch as
+Administrator** button in the header to UAC-elevate in place.
+
+Pages cache their data across navigation (instant reload, background
+refresh every 5 minutes, plus a manual Refresh button), and Startup/Battery/
+Cleanup are pre-warmed in the background while you're on another page.
+
+## Safety model
+
+Every mutating action goes through one chokepoint (`core/safety.py`):
+a denylist blocks system-critical paths/PIDs, and destructive operations
+require a **preview → confirm token → execute** round trip so exactly what
+was shown is what gets acted on. Every attempt is appended to an audit log
+at `%LOCALAPPDATA%\syspanel\audit.jsonl`.
+
+## Development
+
+```bash
+pip install -e .[dev,windows]
+pytest -q
+```
+
+See `CLAUDE.md` for repo conventions.

syspanel-0.1.0/README.md

@@ -0,0 +1,63 @@
+# syspanel
+
+A local, self-contained Windows system dashboard: resource monitor, disk tree
+viewer, battery health, process manager, service watchlist, startup monitor,
+cleanup manager, and restart control — one web app, no cloud, no build step.
+
+## Install
+
+```bash
+pip install syspanel[windows]
+```
+
+## Run
+
+```bash
+syspanel
+```
+
+Opens `http://127.0.0.1:8765/` in your browser. Useful flags:
+
+```bash
+syspanel --no-browser          # don't auto-open a tab
+syspanel --read-only           # disable every mutating route
+syspanel --host 0.0.0.0 --allow-remote   # expose beyond localhost (prints a bearer token)
+```
+
+## Modules
+
+| Module | What it shows |
+|---|---|
+| Resources | Live CPU / RAM / network / disk I/O, 1s push over WebSocket |
+| Disk Tree | Drive-picker dropdown, squarified treemap + sortable/clickable table, background scan with progress that survives navigating away and back |
+| Battery | Design vs. current capacity, cycle count, wear verdict (via `powercfg`) |
+| Processes | Sortable/searchable process table; kill with denylist protection |
+| Services | Full service list, a persisted watchlist with alerts, start/stop/restart |
+| Startup | Registry Run/RunOnce, Startup folder, and logon scheduled tasks; enable/disable/delete |
+| Cleanup | Declarative target catalog (Temp, crash dumps, Windows Update cache, Recycle Bin, custom age/retention rules); dry-run preview before every delete |
+| Power | Schedule a restart with a cancellable countdown; requires typing a confirm phrase |
+
+Admin-only actions (Windows\Temp, service control, killing other users'
+processes) show a lock badge when unelevated; use the **Relaunch as
+Administrator** button in the header to UAC-elevate in place.
+
+Pages cache their data across navigation (instant reload, background
+refresh every 5 minutes, plus a manual Refresh button), and Startup/Battery/
+Cleanup are pre-warmed in the background while you're on another page.
+
+## Safety model
+
+Every mutating action goes through one chokepoint (`core/safety.py`):
+a denylist blocks system-critical paths/PIDs, and destructive operations
+require a **preview → confirm token → execute** round trip so exactly what
+was shown is what gets acted on. Every attempt is appended to an audit log
+at `%LOCALAPPDATA%\syspanel\audit.jsonl`.
+
+## Development
+
+```bash
+pip install -e .[dev,windows]
+pytest -q
+```
+
+See `CLAUDE.md` for repo conventions.

syspanel-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "syspanel"
+version = "0.1.0"
+description = "A local Windows system dashboard: resource monitor, disk tree viewer, battery health, process manager, service watchlist, startup monitor and cleanup manager."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [
+    { name = "Pandiyaraj Karuppasamy", email = "pandiyarajk@live.com" },
+]
+keywords = ["system-monitor", "dashboard", "disk-usage", "battery-health", "process-manager", "windows"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.29",
+    "psutil>=6.0",
+    "pydantic>=2.6",
+    "pydantic-settings>=2.2",
+    "jinja2>=3.1",
+    "send2trash>=1.8",
+]
+
+[project.urls]
+Repository = "https://github.com/pandiyarajk/syspanel"
+Issues = "https://github.com/pandiyarajk/syspanel/issues"
+
+[project.optional-dependencies]
+windows = [
+    "pywin32>=306; sys_platform == 'win32'",
+]
+dev = [
+    "build>=1.0",
+    "twine>=4.0",
+    "pytest>=7.0",
+    "pytest-asyncio>=0.23",
+    "httpx>=0.27",
+    "ruff>=0.4",
+]
+
+[project.scripts]
+syspanel = "system_tools.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/system_tools"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src/system_tools",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

syspanel-0.1.0/src/system_tools/__init__.py

@@ -0,0 +1,7 @@
+"""system_tools - A local Windows system dashboard.
+
+Author: Pandiyaraj Karuppasamy
+Date: Aug-02-2026
+"""
+
+__version__ = "0.1.0"

syspanel-0.1.0/src/system_tools/__main__.py

@@ -0,0 +1,10 @@
+"""Enables `python -m system_tools`.
+
+Author: Pandiyaraj Karuppasamy
+Date: Aug-02-2026
+"""
+
+from system_tools.cli import main
+
+if __name__ == "__main__":
+    main()

syspanel-0.1.0/src/system_tools/cli.py

@@ -0,0 +1,54 @@
+"""Command-line entry point: `syspanel` / `python -m system_tools`.
+
+Author: Pandiyaraj Karuppasamy
+Date: Aug-02-2026
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import threading
+import webbrowser
+
+import uvicorn
+
+from system_tools import __version__
+from system_tools.config import settings
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="syspanel", description="Local Windows system dashboard")
+    parser.add_argument("--host", default=settings.host, help="Bind host (default: 127.0.0.1)")
+    parser.add_argument("--port", type=int, default=settings.port, help="Bind port")
+    parser.add_argument("--no-browser", action="store_true", help="Don't auto-open a browser tab")
+    parser.add_argument("--read-only", action="store_true", help="Disable all mutating routes")
+    parser.add_argument(
+        "--allow-remote", action="store_true",
+        help="Allow binding beyond 127.0.0.1 (requires a bearer token, printed at startup)",
+    )
+    parser.add_argument("--version", action="version", version=f"syspanel {__version__}")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Parse CLI args, apply them to settings, and run the uvicorn server."""
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+
+    args = _parse_args(argv)
+    settings.host = args.host
+    settings.port = args.port
+    settings.read_only = args.read_only
+    settings.allow_remote = args.allow_remote
+
+    if not args.no_browser and args.host in ("127.0.0.1", "localhost"):
+        def _open():
+            webbrowser.open(f"http://{args.host}:{args.port}/")
+
+        threading.Timer(1.0, _open).start()
+
+    uvicorn.run("system_tools.web.app:create_app", factory=True, host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

syspanel-0.1.0/src/system_tools/config.py

@@ -0,0 +1,54 @@
+"""Runtime configuration, sourced from environment variables.
+
+Author: Pandiyaraj Karuppasamy
+Date: Aug-02-2026
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings. All values may be overridden via SYSTOOLS_* env vars."""
+
+    model_config = SettingsConfigDict(env_prefix="SYSTOOLS_", env_file=".env", extra="ignore")
+
+    host: str = "127.0.0.1"
+    port: int = 8765
+    open_browser: bool = True
+    read_only: bool = False
+    allow_remote: bool = False
+
+    sample_interval_seconds: float = 1.0
+    history_length: int = 300
+    service_watch_interval_seconds: float = 5.0
+    battery_report_cache_seconds: int = 3600
+
+    scan_roots: list[str] = ["C:\\"]
+    scan_prune_ratio: float = 0.001
+
+    confirm_token_ttl_seconds: int = 120
+
+    # User-defined age/retention-based cleanup targets, e.g. app logs or SQL
+    # backups: [{"id": "sql_backups", "label": "SQL backups", "roots": ["D:\\Backups"],
+    #   "extensions": [".bak", ".trn"], "min_age_days": 14, "keep_newest_per_prefix": 2}]
+    custom_cleanup_targets: list[dict] = []
+
+    def data_dir(self) -> Path:
+        """Return the per-user app data directory, creating it if missing.
+
+        Returns:
+            Path: directory used for scan cache, audit log, and confirm tokens.
+        """
+        import os
+
+        base = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
+        path = base / "syspanel"
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+
+settings = Settings()

syspanel-0.1.0/src/system_tools/core/__init__.py

@@ -0,0 +1,5 @@
+"""Core cross-cutting concerns: models, safety, audit, capabilities.
+
+Author: Pandiyaraj Karuppasamy
+Date: Aug-02-2026
+"""

syspanel-0.1.0/src/system_tools/core/audit.py

@@ -0,0 +1,51 @@
+"""Append-only JSONL audit log for every attempted mutating action.
+
+Author: Pandiyaraj Karuppasamy
+Date: Aug-02-2026
+"""
+
+from __future__ import annotations
+
+import getpass
+import json
+import logging
+import time
+
+from system_tools.config import settings
+from system_tools.core.models import AuditEntry
+
+logger = logging.getLogger(__name__)
+
+
+def log_action(
+    action: str,
+    targets: list[str],
+    elevated: bool,
+    success: bool,
+    detail: str | None = None,
+) -> None:
+    """Append one audit record describing an attempted mutating action.
+
+    Args:
+        action: short identifier, e.g. "process.kill", "cleanup.execute".
+        targets: human-readable identifiers of what was acted on.
+        elevated: whether the process held admin rights when the action ran.
+        success: whether the action completed without error.
+        detail: optional free-text outcome summary.
+    """
+    entry = AuditEntry(
+        timestamp=time.time(),
+        action=action,
+        targets=targets,
+        elevated=elevated,
+        success=success,
+        detail=detail,
+    )
+    path = settings.data_dir() / "audit.jsonl"
+    try:
+        with path.open("a", encoding="utf-8") as fh:
+            record = entry.model_dump()
+            record["user"] = getpass.getuser()
+            fh.write(json.dumps(record) + "\n")
+    except OSError:
+        logger.exception("Failed to write audit log entry for action=%s", action)

syspanel-0.1.0/src/system_tools/core/capabilities.py

@@ -0,0 +1,57 @@
+"""Resolve what this OS/privilege level supports, for UI card gating.
+
+Author: Pandiyaraj Karuppasamy
+Date: Aug-02-2026
+"""
+
+from __future__ import annotations
+
+import sys
+
+from system_tools.core.elevation import can_relaunch_elevated, is_admin
+from system_tools.core.models import CapabilityState, Capabilities
+
+
+def get_capabilities() -> Capabilities:
+    """Compute the current capability map for all modules.
+
+    Returns:
+        Capabilities: platform, admin state, and per-module support/lock info.
+    """
+    windows = sys.platform == "win32"
+    admin = is_admin()
+
+    modules: dict[str, CapabilityState] = {
+        "resources": CapabilityState(supported=True),
+        "disk_tree": CapabilityState(supported=True),
+        "battery": CapabilityState(supported=windows, reason=None if windows else "Windows only"),
+        "processes": CapabilityState(supported=True),
+        "process_kill_other_user": CapabilityState(
+            supported=windows, needs_admin=not admin,
+            reason=None if admin else "Killing other users' processes needs admin",
+        ),
+        "services": CapabilityState(supported=windows, reason=None if windows else "Windows only"),
+        "services_control": CapabilityState(
+            supported=windows, needs_admin=not admin,
+            reason=None if admin else "Starting/stopping services needs admin",
+        ),
+        "startup": CapabilityState(supported=windows, reason=None if windows else "Windows only"),
+        "cleanup_user_temp": CapabilityState(supported=True),
+        "cleanup_windows_temp": CapabilityState(
+            supported=windows, needs_admin=not admin,
+            reason=None if admin else "C:\\Windows\\Temp needs admin",
+        ),
+        "cleanup_windows_update_cache": CapabilityState(
+            supported=windows, needs_admin=not admin,
+            reason=None if admin else "SoftwareDistribution\\Download needs admin",
+        ),
+        "cleanup_recycle_bin": CapabilityState(supported=windows),
+        "power_restart": CapabilityState(supported=windows, reason=None if windows else "Windows only"),
+    }
+
+    return Capabilities(
+        platform=sys.platform,
+        is_admin=admin,
+        can_relaunch_elevated=can_relaunch_elevated(),
+        modules=modules,
+    )

syspanel-0.1.0/src/system_tools/core/elevation.py

@@ -0,0 +1,58 @@
+"""Admin-privilege detection and in-app UAC relaunch.
+
+Author: Pandiyaraj Karuppasamy
+Date: Aug-02-2026
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+logger = logging.getLogger(__name__)
+
+
+def is_admin() -> bool:
+    """Return whether the current process holds Windows administrator rights.
+
+    Returns:
+        bool: True if elevated. Always False on non-Windows platforms.
+    """
+    if sys.platform != "win32":
+        return False
+    try:
+        import ctypes
+
+        return bool(ctypes.windll.shell32.IsUserAnAdmin())
+    except Exception:
+        logger.warning("Could not determine admin status", exc_info=True)
+        return False
+
+
+def can_relaunch_elevated() -> bool:
+    """Return whether this platform supports the in-app UAC relaunch flow."""
+    return sys.platform == "win32"
+
+
+def relaunch_elevated(host: str, port: int) -> bool:
+    """Re-spawn the current process elevated via the Windows UAC 'runas' verb.
+
+    Args:
+        host: host the elevated instance should bind to.
+        port: port the elevated instance should bind to.
+
+    Returns:
+        bool: True if the elevation request was accepted by Windows (a new
+            elevated process was launched); the caller should exit this process.
+    """
+    if sys.platform != "win32":
+        raise RuntimeError("Elevation relaunch is only supported on Windows")
+
+    import ctypes
+
+    params = f'-m system_tools --host {host} --port {port}'
+    result = ctypes.windll.shell32.ShellExecuteW(
+        None, "runas", sys.executable, params, None, 1
+    )
+    # ShellExecuteW returns a value > 32 on success.
+    return result > 32

syspanel-0.1.0/src/system_tools/core/errors.py

@@ -0,0 +1,66 @@
+"""Application error types mapped to structured JSON responses.
+
+Author: Pandiyaraj Karuppasamy
+Date: Aug-02-2026
+"""
+
+from __future__ import annotations
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+
+class AppError(Exception):
+    """Base application error carrying an HTTP status and a machine-readable code."""
+
+    status_code = 400
+    code = "app_error"
+
+    def __init__(self, detail: str, status_code: int | None = None) -> None:
+        super().__init__(detail)
+        self.detail = detail
+        if status_code is not None:
+            self.status_code = status_code
+
+
+class NotSupportedError(AppError):
+    """Raised when a feature is unavailable on this OS."""
+
+    status_code = 501
+    code = "not_supported"
+
+
+class NeedsElevationError(AppError):
+    """Raised when an action requires administrator privileges."""
+
+    status_code = 403
+    code = "needs_admin"
+
+
+class ProtectedTargetError(AppError):
+    """Raised when a request targets a denylisted path/PID/service."""
+
+    status_code = 403
+    code = "protected_target"
+
+
+class ConfirmTokenError(AppError):
+    """Raised when a mutating action's confirm token is missing, expired, or stale."""
+
+    status_code = 409
+    code = "confirm_token_invalid"
+
+
+class ReadOnlyModeError(AppError):
+    """Raised when a mutating route is hit while the app is running with --read-only."""
+
+    status_code = 403
+    code = "read_only_mode"
+
+
+async def app_error_handler(request: Request, exc: AppError) -> JSONResponse:
+    """FastAPI exception handler converting AppError subclasses to JSON."""
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"error": exc.code, "detail": exc.detail},
+    )