hermead 0.1.0__tar.gz

hermead-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+venv/
+.venv/
+
+# IDEs
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Hermes
+.hermes/
+
+# Test coverage
+htmlcov/
+.coverage
+.coverage.*

hermead-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tony Simons
+
+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.

hermead-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: hermead
+Version: 0.1.0
+Summary: Hermes Agent plugin for project-level linting, type-checking, formatting, and security scanning
+Author: Tony Simons
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dashboard
+Requires-Dist: fastapi; extra == 'dashboard'
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-timeout; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# HermeAd
+
+[![PyPI version](https://img.shields.io/pypi/v/hermead?color=blue)](https://pypi.org/project/hermead/)
+[![License](https://img.shields.io/pypi/l/hermead?color=green)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/hermead?color=blueviolet)](https://pypi.org/project/hermead/)
+
+**HermeAd** is a Hermes Agent plugin that automatically runs linters, type checkers, formatters, and security scanners on project files after every `write_file` or `patch` tool call.
+
+No manual commands. No context switching. Files get checked the moment you write them.
+
+## How It Works
+
+HermeAd registers a single `post_tool_call` hook. After each file modification:
+
+1. Detects the file type from extension or filename
+2. Walks up the tree to find the project root (`.git`, `.hg`, or `.hermes` directory)
+3. Loads config: built-in defaults → global `~/.hermes/hermead.yaml` → per-project `.hermes/hermead.yaml`
+4. Auto-detects tooling from `pyproject.toml`, `package.json`, `go.mod`, `Cargo.toml`, `.shellcheckrc`
+5. Routes to the right runner for each check category (lint, type check, format, security)
+
+Results appear inline in the session. Issues surface at the moment of introduction, not after a CI run.
+
+## Quick Install
+
+```bash
+pip install hermead
+```
+
+From source:
+
+```bash
+git clone https://github.com/asimons81/hermead.git
+cd hermead
+pip install -e ".[dev]"
+```
+
+Verify it loaded:
+
+```bash
+hermes plugin list
+# → hermead should appear
+```
+
+## Features
+
+- **Zero-config for common projects.** Works out of the box with ruff + mypy for Python, eslint + prettier + tsc for JS/TS, golangci-lint + go vet + gofmt for Go, clippy + rustfmt for Rust, shellcheck for shell scripts.
+- **Auto-detection.** Reads `pyproject.toml`, `package.json`, `go.mod`, `Cargo.toml`, and `.shellcheckrc` to pick the right tools. Auto-detected tools take priority over config.
+- **Per-project config.** `.hermes/hermead.yaml` overrides global `~/.hermes/hermead.yaml`, which overrides built-in defaults.
+- **Threshold system.** Set findings to `block`, `warn`, or `ignore` per severity level (lint warnings, type errors, security findings).
+- **6 language runners.** Python, JavaScript/TypeScript, Go, Rust, Shell, and a Generic runner for config/script files (semgrep).
+- **Graceful degredation.** Missing tools produce empty results. No crashes, no spurious errors. Use `which <tool>` to check availability.
+- **Ignore patterns.** Skip `node_modules/`, `venv/`, build output dirs, and anything else you add.
+- **Extra CLI args.** Pass custom flags per tool (e.g. `ruff: ["--line-length", "100"]`).
+
+## Configuration
+
+### Quick Start
+
+Create `.hermes/hermead.yaml` at your project root:
+
+```yaml
+python:
+  lint: ruff
+  type_check: mypy
+  formatter: ruff
+  security: semgrep
+
+thresholds:
+  lint_warnings: warn
+  type_errors: block
+  security_high: block
+
+ignore_paths:
+  - node_modules/**
+  - venv/**
+  - __pycache__/**
+```
+
+### Full Reference
+
+```yaml
+# Per-language tool assignments (null = skip that check category)
+python:
+  lint: ruff
+  type_check: mypy
+  formatter: ruff
+  security: semgrep
+
+javascript:
+  lint: eslint
+  type_check: tsc
+  formatter: prettier
+  security: semgrep
+
+go:
+  lint: golangci-lint
+  type_check: go vet
+  formatter: gofmt
+  security: gosec
+
+rust:
+  lint: clippy
+  type_check: cargo check
+  formatter: rustfmt
+  security: cargo audit
+
+shell:
+  lint: shellcheck
+  formatter: shfmt
+
+generic:
+  lint: semgrep
+  security: semgrep
+
+thresholds:
+  lint_warnings: warn       # warn | block | ignore
+  type_errors: block
+  security_high: block
+  security_medium: warn
+  security_low: info
+
+ignore_paths:
+  - node_modules/**
+  - venv/**
+  - .venv/**
+  - __pycache__/**
+  - .git/**
+  - dist/**
+  - build/**
+  - target/**
+  - .hermes/**
+
+extra_args:
+  ruff: ["--line-length", "100"]
+  mypy: ["--strict"]
+  golangci-lint: ["--timeout", "5m"]
+```
+
+## Supported Languages
+
+| Language | Extensions | Lint | Type Check | Format | Security |
+|----------|-----------|------|------------|--------|----------|
+| Python | `.py` | ruff | mypy | ruff / black | bandit / semgrep |
+| JavaScript / TypeScript | `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs` | eslint | tsc | prettier | semgrep |
+| Go | `.go` | golangci-lint | go vet | gofmt | gosec |
+| Rust | `.rs` | clippy | cargo check | rustfmt | cargo audit |
+| Shell | `.sh`, `.bash`, `.zsh`, `.fish` | shellcheck | — | shfmt | — |
+| Generic | Dockerfile, Makefile, `.gitignore`, etc. | semgrep | — | — | semgrep |
+
+## Inline Reports
+
+When HermeAd runs, findings appear in your session as structured results:
+
+```
+╔══════════════════════════════════════════════════════════╗
+║  HermeAd — lint results for src/main.py                 ║
+╠══════════════════════════════════════════════════════════╣
+║  tool: ruff  severity: error  line: 42  col: 5          ║
+║  F841 — local variable 'x' is assigned to but never     ║
+║  used                                                    ║
+╠══════════════════════════════════════════════════════════╣
+║  2 findings (1 error, 1 warning) — 0 blocked, 2 warned  ║
+╚══════════════════════════════════════════════════════════╝
+```
+
+Each result shows the tool, severity, source location, message, and rule code. Empty output means the file passed or the tool wasn't available.
+
+## Contributing
+
+PRs welcome. HermeAd is a young project — the runner interface, result format, and hooks API are still finding their shape.
+
+- Runners live in `hermead/runners/`. Each module self-registers via `register_runner(language, action, func)`.
+- The hook dispatcher lives in `hermead/hooks.py`.
+- Config loading lives in `hermead/config.py`.
+- The registry lives in `hermead/runners/__init__.py`.
+
+Before opening a PR, run the test suite:
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```
+
+## Plugin Architecture
+
+HermeAd is a Hermes Agent plugin — no MCP server, no web server, no external API. It registers a single hook entry point in `pyproject.toml`:
+
+```toml
+[project.entry-points."hermes_agent.plugins"]
+hermead = "hermead:register"
+```
+
+For more on building Hermes plugins, see the [Hermes Agent Plugin Docs](https://hermes-agent.nousresearch.com/docs/plugins).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

hermead-0.1.0/README.md

@@ -0,0 +1,197 @@
+# HermeAd
+
+[![PyPI version](https://img.shields.io/pypi/v/hermead?color=blue)](https://pypi.org/project/hermead/)
+[![License](https://img.shields.io/pypi/l/hermead?color=green)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/hermead?color=blueviolet)](https://pypi.org/project/hermead/)
+
+**HermeAd** is a Hermes Agent plugin that automatically runs linters, type checkers, formatters, and security scanners on project files after every `write_file` or `patch` tool call.
+
+No manual commands. No context switching. Files get checked the moment you write them.
+
+## How It Works
+
+HermeAd registers a single `post_tool_call` hook. After each file modification:
+
+1. Detects the file type from extension or filename
+2. Walks up the tree to find the project root (`.git`, `.hg`, or `.hermes` directory)
+3. Loads config: built-in defaults → global `~/.hermes/hermead.yaml` → per-project `.hermes/hermead.yaml`
+4. Auto-detects tooling from `pyproject.toml`, `package.json`, `go.mod`, `Cargo.toml`, `.shellcheckrc`
+5. Routes to the right runner for each check category (lint, type check, format, security)
+
+Results appear inline in the session. Issues surface at the moment of introduction, not after a CI run.
+
+## Quick Install
+
+```bash
+pip install hermead
+```
+
+From source:
+
+```bash
+git clone https://github.com/asimons81/hermead.git
+cd hermead
+pip install -e ".[dev]"
+```
+
+Verify it loaded:
+
+```bash
+hermes plugin list
+# → hermead should appear
+```
+
+## Features
+
+- **Zero-config for common projects.** Works out of the box with ruff + mypy for Python, eslint + prettier + tsc for JS/TS, golangci-lint + go vet + gofmt for Go, clippy + rustfmt for Rust, shellcheck for shell scripts.
+- **Auto-detection.** Reads `pyproject.toml`, `package.json`, `go.mod`, `Cargo.toml`, and `.shellcheckrc` to pick the right tools. Auto-detected tools take priority over config.
+- **Per-project config.** `.hermes/hermead.yaml` overrides global `~/.hermes/hermead.yaml`, which overrides built-in defaults.
+- **Threshold system.** Set findings to `block`, `warn`, or `ignore` per severity level (lint warnings, type errors, security findings).
+- **6 language runners.** Python, JavaScript/TypeScript, Go, Rust, Shell, and a Generic runner for config/script files (semgrep).
+- **Graceful degredation.** Missing tools produce empty results. No crashes, no spurious errors. Use `which <tool>` to check availability.
+- **Ignore patterns.** Skip `node_modules/`, `venv/`, build output dirs, and anything else you add.
+- **Extra CLI args.** Pass custom flags per tool (e.g. `ruff: ["--line-length", "100"]`).
+
+## Configuration
+
+### Quick Start
+
+Create `.hermes/hermead.yaml` at your project root:
+
+```yaml
+python:
+  lint: ruff
+  type_check: mypy
+  formatter: ruff
+  security: semgrep
+
+thresholds:
+  lint_warnings: warn
+  type_errors: block
+  security_high: block
+
+ignore_paths:
+  - node_modules/**
+  - venv/**
+  - __pycache__/**
+```
+
+### Full Reference
+
+```yaml
+# Per-language tool assignments (null = skip that check category)
+python:
+  lint: ruff
+  type_check: mypy
+  formatter: ruff
+  security: semgrep
+
+javascript:
+  lint: eslint
+  type_check: tsc
+  formatter: prettier
+  security: semgrep
+
+go:
+  lint: golangci-lint
+  type_check: go vet
+  formatter: gofmt
+  security: gosec
+
+rust:
+  lint: clippy
+  type_check: cargo check
+  formatter: rustfmt
+  security: cargo audit
+
+shell:
+  lint: shellcheck
+  formatter: shfmt
+
+generic:
+  lint: semgrep
+  security: semgrep
+
+thresholds:
+  lint_warnings: warn       # warn | block | ignore
+  type_errors: block
+  security_high: block
+  security_medium: warn
+  security_low: info
+
+ignore_paths:
+  - node_modules/**
+  - venv/**
+  - .venv/**
+  - __pycache__/**
+  - .git/**
+  - dist/**
+  - build/**
+  - target/**
+  - .hermes/**
+
+extra_args:
+  ruff: ["--line-length", "100"]
+  mypy: ["--strict"]
+  golangci-lint: ["--timeout", "5m"]
+```
+
+## Supported Languages
+
+| Language | Extensions | Lint | Type Check | Format | Security |
+|----------|-----------|------|------------|--------|----------|
+| Python | `.py` | ruff | mypy | ruff / black | bandit / semgrep |
+| JavaScript / TypeScript | `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs` | eslint | tsc | prettier | semgrep |
+| Go | `.go` | golangci-lint | go vet | gofmt | gosec |
+| Rust | `.rs` | clippy | cargo check | rustfmt | cargo audit |
+| Shell | `.sh`, `.bash`, `.zsh`, `.fish` | shellcheck | — | shfmt | — |
+| Generic | Dockerfile, Makefile, `.gitignore`, etc. | semgrep | — | — | semgrep |
+
+## Inline Reports
+
+When HermeAd runs, findings appear in your session as structured results:
+
+```
+╔══════════════════════════════════════════════════════════╗
+║  HermeAd — lint results for src/main.py                 ║
+╠══════════════════════════════════════════════════════════╣
+║  tool: ruff  severity: error  line: 42  col: 5          ║
+║  F841 — local variable 'x' is assigned to but never     ║
+║  used                                                    ║
+╠══════════════════════════════════════════════════════════╣
+║  2 findings (1 error, 1 warning) — 0 blocked, 2 warned  ║
+╚══════════════════════════════════════════════════════════╝
+```
+
+Each result shows the tool, severity, source location, message, and rule code. Empty output means the file passed or the tool wasn't available.
+
+## Contributing
+
+PRs welcome. HermeAd is a young project — the runner interface, result format, and hooks API are still finding their shape.
+
+- Runners live in `hermead/runners/`. Each module self-registers via `register_runner(language, action, func)`.
+- The hook dispatcher lives in `hermead/hooks.py`.
+- Config loading lives in `hermead/config.py`.
+- The registry lives in `hermead/runners/__init__.py`.
+
+Before opening a PR, run the test suite:
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```
+
+## Plugin Architecture
+
+HermeAd is a Hermes Agent plugin — no MCP server, no web server, no external API. It registers a single hook entry point in `pyproject.toml`:
+
+```toml
+[project.entry-points."hermes_agent.plugins"]
+hermead = "hermead:register"
+```
+
+For more on building Hermes plugins, see the [Hermes Agent Plugin Docs](https://hermes-agent.nousresearch.com/docs/plugins).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

hermead-0.1.0/hermead/__init__.py

@@ -0,0 +1,29 @@
+"""HermeAd: Hermes Agent plugin for project-level linting, type-checking, formatting, and security scanning.
+
+Runs entirely through Hermes hook system. No external API, no MCP server, no web server.
+"""
+
+from hermead.hooks import post_tool_call
+
+__version__ = "0.1.0"
+
+
+def register():
+    """Register HermeAd hooks with the Hermes Agent plugin system.
+
+    Returns the hook registration dict expected by Hermes Agent.
+    """
+    return {
+        "hooks": {
+            "post_tool_call": post_tool_call,
+        },
+        "metadata": {
+            "name": "hermead",
+            "version": __version__,
+            "description": (
+                "Post-tool-call hook that detects write_file/patch on project "
+                "files and auto-runs linting, type-checking, formatting, and "
+                "security checks."
+            ),
+        },
+    }

hermead-0.1.0/hermead/config.py

@@ -0,0 +1,121 @@
+"""Configuration loader for HermeAd.
+
+Loads .hermes/hermead.yaml with per-project first, then global fallback.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "python": {
+        "lint": "ruff",
+        "type_check": "mypy",
+        "formatter": "ruff",
+        "security": "semgrep",
+    },
+    "javascript": {
+        "lint": "eslint",
+        "type_check": "tsc",
+        "formatter": "prettier",
+        "security": "semgrep",
+    },
+    "go": {
+        "lint": "golangci-lint",
+        "type_check": "go vet",
+        "formatter": "gofmt",
+        "security": "gosec",
+    },
+    "rust": {
+        "lint": "clippy",
+        "type_check": "rustc",
+        "formatter": "rustfmt",
+        "security": "cargo audit",
+    },
+    "shell": {
+        "lint": "shellcheck",
+        "type_check": None,
+        "formatter": "shfmt",
+        "security": None,
+    },
+    "generic": {
+        "lint": "semgrep",
+        "type_check": None,
+        "formatter": None,
+        "security": "semgrep",
+    },
+    "thresholds": {
+        "lint_warnings": "warn",
+        "type_errors": "block",
+        "security_high": "block",
+        "security_medium": "warn",
+    },
+    "ignore_paths": [
+        "node_modules/**",
+        "venv/**",
+        ".venv/**",
+        "__pycache__/**",
+        ".git/**",
+        "dist/**",
+        "build/**",
+        "target/**",
+        ".hermes/**",
+    ],
+    "extra_args": {},
+}
+
+
+def find_project_root(path: str | Path | None = None) -> Path | None:
+    """Walk up from *path* (default: cwd) looking for a .git, .hg, or .hermes directory."""
+    start = Path(path or os.getcwd()).resolve()
+    for ancestor in [start] + list(start.parents):
+        if (ancestor / ".git").is_dir():
+            return ancestor
+        if (ancestor / ".hg").is_dir():
+            return ancestor
+        if (ancestor / ".hermes").is_dir():
+            return ancestor
+    return None
+
+
+def load_hermead_config(path: str | Path | None = None) -> dict[str, Any]:
+    """Load the effective HermeAd config, merging global → per-project overrides.
+
+    1. Start with DEFAULT_CONFIG.
+    2. Overlay ``~/.hermes/hermead.yaml`` if it exists (global).
+    3. Overlay ``<project-root>/.hermes/hermead.yaml`` if it exists (per-project).
+    """
+    config: dict[str, Any] = _deep_merge({}, DEFAULT_CONFIG)
+
+    # Global fallback
+    global_path = Path.home() / ".hermes" / "hermead.yaml"
+    if global_path.is_file():
+        with open(global_path, encoding="utf-8") as fh:
+            global_cfg: dict[str, Any] = yaml.safe_load(fh) or {}
+        config = _deep_merge(config, global_cfg)
+
+    # Per-project override
+    project_root = find_project_root(path)
+    if project_root is not None:
+        local_path = project_root / ".hermes" / "hermead.yaml"
+        if local_path.is_file():
+            with open(local_path, encoding="utf-8") as fh:
+                local_cfg: dict[str, Any] = yaml.safe_load(fh) or {}
+            config = _deep_merge(config, local_cfg)
+
+    return config
+
+
+def _deep_merge(base: dict, overlay: dict) -> dict:
+    """Recursively merge *overlay* into *base* (keys in overlay win)."""
+    merged = dict(base)
+    for key, value in overlay.items():
+        if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):
+            merged[key] = _deep_merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged