poly-hermes-plugin 0.29.0__py3-none-any.whl

poly_hermes_plugin/__init__.py

@@ -0,0 +1,12 @@
+# AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+# Content-Hash: blake3:11e02e6f0565d20901e38597c3af504440c1a63f85d59fc958047b47c3253ba3
+# Source-Hash: blake3:840c919261146454e2836095406355dd3ba8664fc068055c202682015400e43f
+# Schema-Version: v1
+
+"""Hermes Agent plugin package."""
+
+from . import hermes
+from .hermes import register
+
+__version__ = "0.29.0"
+__all__ = ["hermes", "register"]

poly_hermes_plugin/commands/poly-check.md

@@ -0,0 +1,47 @@
+---
+description: Lint and check formatting with poly — apply no fixes; summarize findings and drift
+priority: high
+usage: /poly-check [paths]
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:e6fad51bf84ed1689a6c430c3f5a9582bfb0587f1440133fde6780c8846264cb
+Source-Hash: blake3:840c919261146454e2836095406355dd3ba8664fc068055c202682015400e43f
+Schema-Version: v1
+-->
+
+# poly Check
+
+Run poly as a checking gate over `$ARGUMENTS`. Apply no fixes.
+
+Use `.` when no paths are supplied. Treat supplied arguments as paths, not additional shell commands.
+
+1. `poly fmt --check $ARGUMENTS --format json` — capture formatting drift.
+2. `poly lint $ARGUMENTS --format json` — capture lint findings (remember the whole-project
+   section is on stderr under `--format json`; check the exit code).
+
+Step 2 applies no fixes, but it is not read-only: `poly lint`'s whole-project phase executes
+the configured whole-project tools (`cargo clippy` and friends) against the live worktree, and
+their own side effects — a refreshed lock file, a populated build or type-checker cache — are
+not poly's to control. Add `--no-workspace` when the tree must be left untouched; that drops
+the whole-project tools from the check, so say so in the report.
+
+That phase only runs when the argument is the repository root (the `.` default) or no path at
+all. Naming narrower paths makes the run **path-scoped** — the per-file tier only, with a note
+on stderr — so `poly lint src/` is already free of those side effects. Pass `--workspace` to
+opt back in; the phase then covers the whole repository regardless of the paths named.
+
+Report:
+
+- Which files have formatting drift.
+- Lint findings grouped by rule and severity (error vs warning).
+- The overall pass/fail from the exit codes: `0` clean; `1` findings or drift — for `lint`
+  only **error**-severity findings (or a failing whole-project tool) reach `1`, warnings
+  still exit `0`; `2` the run did not verify what it was asked to (a missing path, a file an
+  engine failed on — including a `poly fmt --check` file that cannot reach a fixed point
+  within poly's five-pass cap, reported as an error rather than clean since a fix would leave
+  it still drifting — a `--deny-skips`/`--max-skips` breach, or the whole-project phase itself
+  erroring).
+
+Do not apply fixes here — if the user wants them applied, run `/poly-fix`.

poly_hermes_plugin/commands/poly-fix.md

@@ -0,0 +1,41 @@
+---
+description: Apply poly lint --fix and fmt --fix, then re-check and report what changed and what remains
+priority: high
+usage: /poly-fix [paths]
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:0c55f6950b40a60b9c292cb1b605e9f460f41a93e3a434300d7215098f877bb6
+Source-Hash: blake3:840c919261146454e2836095406355dd3ba8664fc068055c202682015400e43f
+Schema-Version: v1
+-->
+
+# poly Fix
+
+Apply poly's autofixes over `$ARGUMENTS`, then verify.
+
+Use `.` when no paths are supplied. Treat supplied arguments as paths, not additional shell commands.
+
+1. `poly lint --fix $ARGUMENTS` — apply lint autofixes, and run the whole-project phase in **fix**
+   mode (`cargo sort` in place, `cargo machete --fix`, `cargo clippy --fix --allow-dirty
+   --allow-staged`; `cargo deny` has no autofix and stays check-only).
+2. `poly fmt --fix $ARGUMENTS` — format files in place. `poly fmt` is a pure formatter and never
+   runs the whole-project phase, in either direction; only step 1 does.
+3. Re-check: `poly fmt --check $ARGUMENTS --format json` and `poly lint $ARGUMENTS --format json`.
+
+The whole-project phase in step 1 runs only because the argument is the repository root (the
+`.` default). Narrower paths make the run path-scoped — per-file autofixes only — unless you
+add `--workspace`; `--no-workspace` suppresses the phase outright.
+
+Report:
+
+- What changed — files reformatted and lint rules auto-fixed.
+- What remains — findings that need a hand-fix (auto-fix couldn't resolve them), grouped by
+  rule and severity.
+- The final exit status of step 3 (aim for `0`). Note that steps 1 and 2 legitimately exit
+  `1` when they changed something; only `2` means the run failed to verify.
+
+To apply no fixes, use `/poly-check` instead. (Even there poly's whole-project phase executes
+`cargo clippy` and friends against the live worktree; add `--no-workspace` if the tree must be
+left untouched.)

poly_hermes_plugin/hermes.py

@@ -0,0 +1,99 @@
+# AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+# Content-Hash: blake3:57cf2cb6924db8f7699232ad0ec0c8435d1ac671c041569535330d190f298782
+# Source-Hash: blake3:840c919261146454e2836095406355dd3ba8664fc068055c202682015400e43f
+# Schema-Version: v1
+
+"""Register product skills and a local MCP tool bridge with Hermes."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import shutil
+from builtins import ExceptionGroup
+from datetime import timedelta
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import yaml
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+from mcp.shared.exceptions import McpError
+
+if TYPE_CHECKING:
+    from hermes_cli.plugins import PluginContext
+
+PLUGIN_NAME = "poly"
+CLI_COMMAND = "poly"
+SERVER_ARGUMENTS = ["mcp"]
+TOOL_NAMES = ['cache_clean', 'cache_stats', 'config_show', 'format_check', 'format_write', 'lint', 'lint_fix', 'rules', 'version', 'workspace_lint', 'workspace_lint_fix']
+DISCOVERY_TOOL = "list_tools"
+REQUEST_TIMEOUT_SECONDS = 300
+
+
+def error_details(error: BaseException) -> str:
+    """Expose SDK task-group causes instead of hiding the actionable failure."""
+    if isinstance(error, ExceptionGroup):
+        return "; ".join(error_details(cause) for cause in error.exceptions)[:1024]
+    return str(error)[:1024]
+
+
+async def call_tool(arguments: dict[str, object], **_kwargs: object) -> dict[str, object]:
+    """Call one supported MCP tool using the installed local CLI."""
+    if not isinstance(arguments, dict) or set(arguments) - {"tool", "tool_arguments"}:
+        return {"error": "Pass an object containing tool and optional tool_arguments."}
+    tool = arguments.get("tool")
+    parameters = arguments.get("tool_arguments", {})
+    if tool not in [*TOOL_NAMES, DISCOVERY_TOOL] or not isinstance(parameters, dict):
+        return {"error": "Choose a supported tool and provide an object of tool_arguments."}
+    command = shutil.which(CLI_COMMAND)
+    if command is None:
+        return {"error": f"Install {CLI_COMMAND} with MCP support and put it on PATH; see the plugin README."}
+
+    server = StdioServerParameters(command=command, args=SERVER_ARGUMENTS, env=os.environ.copy())
+    try:
+        async with asyncio.timeout(REQUEST_TIMEOUT_SECONDS):
+            async with (
+                stdio_client(server) as (read, write),
+                ClientSession(read, write, read_timeout_seconds=timedelta(seconds=REQUEST_TIMEOUT_SECONDS)) as session,
+            ):
+                await session.initialize()
+                if tool == DISCOVERY_TOOL:
+                    result = await session.list_tools()
+                else:
+                    result = await session.call_tool(tool, parameters)
+                return result.model_dump(mode="json", exclude_none=True)
+    except TimeoutError:
+        return {"error": f"{CLI_COMMAND} MCP request timed out; reduce the workload or inspect server diagnostics."}
+    except (McpError, OSError, ExceptionGroup, ValueError) as error:
+        return {"error": f"{CLI_COMMAND} MCP request failed: {error_details(error)}"}
+
+
+async def handle_tool(arguments: dict[str, object], **kwargs: object) -> str:
+    """Return the native text contract while preserving structured MCP fields as JSON."""
+    return json.dumps(await call_tool(arguments, **kwargs), ensure_ascii=False)
+
+
+def register(ctx: PluginContext) -> None:
+    """Register every bundled skill and one tool spanning the native MCP surface."""
+    for path in sorted((Path(__file__).parent / "skills").glob("*/SKILL.md")):
+        frontmatter = path.read_text(encoding="utf-8").split("---", 2)[1]
+        metadata = yaml.safe_load(frontmatter)
+        ctx.register_skill(metadata["name"], path, description=metadata["description"])
+    name = PLUGIN_NAME.replace("-", "_") + "_call"
+    description = f"Call a {PLUGIN_NAME} tool on the installed local MCP server. Select list_tools to inspect request schemas; use namespaced skills for workflows."
+    schema = {
+        "name": name,
+        "description": description,
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "tool": {"type": "string", "enum": [*TOOL_NAMES, DISCOVERY_TOOL]},
+                "tool_arguments": {"type": "object", "description": "Arguments accepted by the selected MCP tool."},
+            },
+            "required": ["tool"],
+            "additionalProperties": False,
+        },
+    }
+    ctx.register_tool(name=name, toolset=PLUGIN_NAME, schema=schema, handler=handle_tool, is_async=True)

poly_hermes_plugin/plugin.yaml

@@ -0,0 +1,8 @@
+name: "poly"
+version: "0.29.0"
+description: "Zero-dependency lint & format orchestrator over MCP — one pure-Rust binary wrapping ruff/oxc/taplo/rumdl and more as in-process backends, plus a tree-sitter generic tier for everything else. Exposes lint/format/cache tools with structured JSON output."
+author: "Na'aman Hirschfeld"
+kind: "standalone"
+python_dependencies:
+  - "mcp==1.28.1"
+  - "PyYAML==6.0.3"

poly_hermes_plugin/skills/poly-lint-and-format/SKILL.md

@@ -0,0 +1,110 @@
+---
+description: Running poly lint / poly fmt — --fix, --format pretty|json|toon, --exclude, --config, exit codes, inline suppression, and the check → read-json → fix → re-check loop
+name: poly-lint-and-format
+license: MIT
+metadata:
+    author: Goldziher
+    repository: https://github.com/Goldziher/poly
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:697a8913634eec72ba2340417d11f811af8d9fcd390f25ccdc09ed4689695209
+Source-Hash: blake3:840c919261146454e2836095406355dd3ba8664fc068055c202682015400e43f
+Schema-Version: v1
+-->
+
+# poly Lint and Format
+
+## Commands
+
+- `poly lint [PATHS]…` — run the linters. poly applies no fixes without `--fix`; `--fix`
+  applies autofixes (and the whole-project fix phase). `--no-workspace` restricts to the
+  per-file tier — and is also what makes a run read-only: without it, plain `poly lint`
+  still *executes* the configured whole-project tools against the live worktree, and their
+  own side effects (a refreshed lock file, a populated build or type-checker cache) are not
+  poly's to control. Naming paths that **narrow** the run skips that phase by default
+  (`poly lint .` names the repo root, so it does *not* narrow and the phase still runs);
+  `--workspace` opts back in, and the tools then cover the whole repository regardless of
+  the named paths and of `[discovery] exclude`.
+- `poly fmt [PATHS]…` — **dry run by default**: reports what would change and writes
+  nothing. `--fix` writes changes; `--check` is the explicit form of the default dry run
+  and conflicts with `--fix`. `poly fmt` is a pure formatter — it never runs the
+  whole-project lint phase.
+
+## Flags
+
+- `--format pretty|json|toon` — `pretty` (the default) is the colored, human-oriented
+  output; `json` and the compact `toon` variant are machine-readable. Under
+  `--format json`/`toon`, `poly lint`'s whole-project section and every note (discovery,
+  skips, errors) go to stderr so stdout stays a single valid document — a machine consumer
+  must check the **exit code**, not just the payload.
+- `--exclude <glob>` — skip paths on top of `.gitignore` (repeatable; merged with
+  `[discovery] exclude`). Gitignore-style: a glob without a leading `/` matches a directory
+  of that name at **any** depth (`e2e/**` also prunes `src/test/java/io/xberg/e2e/`), while
+  a leading `/` anchors it to the config directory (`/e2e/**`). `poly doctor` warns when a
+  rule matches at more than one depth.
+- `--include-excluded` — check explicitly named files or directory roots even when they
+  match the exclude set. Exclusions *below* an included directory stay active. Applying the
+  exclude set to explicitly named paths is already the default, so `--force-exclude` is
+  accepted only as a compatibility no-op — the flag is parsed and never read.
+- `--config <path>` — point at a specific `poly.toml`.
+- `--no-cache` — bypass the blake3 content-hash result cache.
+- `-j <N>` — parallelism; `--no-color` — plain output; `--verbose` — extra per-finding
+  detail in `pretty` output; `--debug` — per-engine cache hit/miss and timing, plus
+  debug-level logs on stderr.
+- `--fix-generated` — let `--fix` rewrite files marked `DO NOT EDIT` / `@generated`, which
+  it otherwise reports on but leaves alone.
+- `--deny-skips` / `--max-skips <N>` — strict coverage. A **skipped** file is one nothing
+  inspected: a path named on the command line that no engine covers (`App.csproj`), or a
+  file every routed backend declined (Go-templated YAML, a hash-stamped generated file). A
+  skip the caller instructed — `--only`/`--skip` narrowing an engine out, or `enabled = false`
+  in config — is **not** charged against the budget, since it names itself in the report
+  rather than losing coverage silently; only a poly limitation counts. Skips are always
+  reported and named; these flags make a chargeable skip fail the run (exit `2`), naming
+  every file it fired on. `--verbose` lists every skip in `pretty` output; `--format
+  json`/`toon` carries the full set both as a top-level `skipped` array and as synthetic
+  `results` entries — `summary.skipped` is the authoritative count, so read it first and use
+  the set only to name the files.
+
+## Exit codes
+
+- `0` — clean (no findings, no drift).
+- `1` — error-severity findings, formatting drift, or a failing whole-project tool.
+- `2` — an error (bad config, tool failure), or work the run could not verify: a missing
+  path argument, a file an engine failed on — including a `poly fmt` file that could not
+  reach a fixed point within its five-pass cap, now reported as an error rather than
+  silently claimed as formatted — or a `--deny-skips`/`--max-skips` breach.
+
+`poly lint` exits non-zero only on **error-severity** findings; warnings do not fail CI —
+which is why the on-by-default `quality` and built-in ast-grep rules (all warnings) never
+turn a green pipeline red on their own.
+
+## Inline suppression
+
+Silence one finding in place with a directive written in the host language's own comment
+syntax:
+
+```rust
+let value = map.get(key).unwrap(); // poly: allow[unwrap-used] key is validated above
+```
+
+- `poly: allow[RULE] reason` — a comment-only line suppresses the next non-blank line; a
+  trailing comment suppresses its own line.
+- `poly: allow-file[RULE] reason` — suppresses the whole file wherever it appears, and is
+  the only form that can suppress a diagnostic with no span.
+- `[RULE]` accepts a comma-separated list, or `*` for every rule.
+- **A reason is mandatory.** A directive whose text after `]` has no alphanumeric character
+  does **not** suppress, and reports `lazy-ignore` instead — an empty comment cannot buy a
+  bypass.
+- Applied centrally in the runner, so it works for every engine (ruff, oxlint, quality,
+  ast-grep, …). For a whole file or a class of files, use `[per-file-ignores]` in
+  `poly.toml` instead.
+
+## The loop
+
+1. `poly fmt --check . --format json` and `poly lint . --format json` — capture drift and
+   findings, checking the exit code.
+2. Read the JSON to see exactly which files and rules are involved.
+3. `poly fmt --fix .` then `poly lint --fix .` to apply what is auto-fixable.
+4. Re-run the checks; hand-fix whatever remains (exit code back to 0).

poly_hermes_plugin/skills/poly-lint-and-format/index.md

@@ -0,0 +1,10 @@
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:827e04e800b869af141ac06d2edd7bf69516c05790bdbf03210a4d802ea6f3b9
+Source-Hash: blake3:840c919261146454e2836095406355dd3ba8664fc068055c202682015400e43f
+Schema-Version: v1
+-->
+
+# Concepts
+
+* [Poly Lint And Format](SKILL.md) - Running poly lint / poly fmt — --fix, --format pretty|json|toon, --exclude, --config, exit codes, inline suppression, and the check → read-json → fix → re-check loop

poly_hermes_plugin/skills/poly-mcp/SKILL.md

@@ -0,0 +1,124 @@
+---
+description: The poly MCP server — the eleven tools and which are read-only vs mutating, the paths/exclude/config/format params, async Tasks for the whole-project phase, and the isError contract
+name: poly-mcp
+license: MIT
+metadata:
+    author: Goldziher
+    repository: https://github.com/Goldziher/poly
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:3e891f0be46a80c56b06b9a9683a91b16c293cdb33edb5aebefaa7c680be3b3c
+Source-Hash: blake3:840c919261146454e2836095406355dd3ba8664fc068055c202682015400e43f
+Schema-Version: v1
+-->
+
+# poly MCP
+
+`poly mcp` is a stdio MCP server exposing poly's lint/format/cache/rules/config surface as
+tools. Prefer it over shelling out to the CLI when working through MCP — every tool returns
+typed `structured_content` (with a declared output schema) plus one text block that mirrors
+the CLI's `--format json`, or the compact TOON encoding when asked.
+
+`poly mcp --config <PATH>` pins a fallback config file for requests that do not name one.
+
+## Tool surface
+
+Eleven tools, no more. Read-only (never touch the tree):
+
+- `lint` — run the linters and return diagnostics. Mirrors `poly lint`.
+- `format_check` — report formatting drift without writing. Mirrors `poly fmt --check`.
+- `cache_stats` — result-cache footprint (entries, bytes, format version) per namespace.
+- `rules` — list every ast-grep rule a run would apply — poly's built-in pack plus the user
+  rules from `[rules] dirs` — and optionally run their `*-test.yml` snippets. Mirrors `poly
+  rules list` / `poly rules test`. Each rule carries its language, `source` (`builtin`/`user`),
+  `default_severity`, the `severity` it reports at under the resolved config, and `enabled`.
+- `config_show` — the merged effective configuration. Mirrors `poly config show`, and is
+  **network-free**: remote `extends` bases are not fetched.
+- `version` — which poly binary is serving this session (version, build id, channel,
+  executable, pid, uptime), the full compiled-in engine → wrapped-tool-version map, and
+  whether that executable is still the file on disk. It answers even when the binary has
+  moved, which is what makes it the tool that explains why the others stopped.
+
+Mutating (write to the tree):
+
+- `lint_fix` — apply lint autofixes. Mirrors `poly lint --fix`.
+- `format_write` — format files in place. Mirrors `poly fmt --fix`.
+- `cache_clean` — clear the result cache and report freed bytes.
+
+Whole-project (long-running):
+
+- `workspace_lint` — the whole-project phase in check mode: `cargo clippy` / `cargo-sort` /
+  `cargo-machete` / `cargo-deny` and configured inline whole-project jobs, over the whole
+  repository (it takes no `paths`).
+- `workspace_lint_fix` — the same phase in fix mode; writes files.
+
+Both are exposed as async Tasks (SEP-2663): the call returns a task handle and the client
+polls `tasks/get`, optionally `tasks/cancel`, with an unlimited TTL. A client that does not
+declare the tasks capability gets a synchronous, blocking result from the same call instead,
+so the tools work either way.
+
+`workspace_lint` applies no fixes, but it is **not** in the never-touch-the-tree group: it
+executes those tools against the live worktree, and their own side effects — a refreshed
+lock file, a populated build or type-checker cache — are not poly's to control.
+
+There is no `hooks` tool: `poly hooks` is CLI-only.
+
+## Parameters
+
+- `lint` / `format_check` / `lint_fix` / `format_write`: `paths` (files or directories;
+  empty means the current directory), `exclude` (gitignore-style globs merged with
+  `[discovery] exclude` — unanchored globs match at any depth), `config` (path to a
+  `poly.toml`), `format` (`"json"` default, or `"toon"`).
+- `rules`: `dirs` (empty means `[rules] dirs` from the config), `config`, `test` (bool),
+  `format`.
+- `config_show`: `config`, `format`.
+- `cache_stats` / `cache_clean` / `version`: `format` only.
+- `workspace_lint` / `workspace_lint_fix`: `config`, `format`, `jobs`, `no_cache` — no
+  `paths`.
+
+`format` selects only the paired **text** block; `structured_content` is always JSON.
+
+Treat the read-only tools as safe to call freely; gate the mutating tools behind explicit
+intent since they change files.
+
+## Every result identifies the binary that answered
+
+Each result carries a `poly` block (version, build id, channel, executable, pid, and an
+`engines` digest — a blake3 hash over the sorted compiled-in engine name + version pairs,
+excluding native-toolchain and catalog engines since those depend on the host and on config)
+in `structured_content` and in `_meta`, because an MCP caller has no `poly --version` to fall
+back on. The digest is what distinguishes two builds sharing one version number (a `dev`
+build, or two builds of one tag) when their wrapped crates differ; the full engine map is on
+the `version` tool. The server fingerprints its own executable at startup and re-checks it per
+request: if the binary is replaced or deleted underneath a long-lived server, every tool but
+`version` fails rather than answering with superseded behaviour.
+
+## Per-file outcomes: checked, skipped, error
+
+The result object is `{results, errors, skipped, summary, configs}`, not a bare array.
+`summary` is `{checked, skipped, errored}` — the run's own count of what it did, and the field
+to gate on. It cannot be derived from `results`: `results` holds only files with something to
+report, so a file that was checked and found clean produces **no** `results` entry at all — a
+present entry does not mean checked, either, since `results` also carries a synthetic entry
+(empty `diagnostics`, `skipped` or `error` set) for every file the run declined or failed on.
+The skipped/error sets and `results` overlap on purpose:
+
+- **Checked** — counted in `summary.checked`. Not derivable from `results`.
+- **Skipped** (`skipped` field, and the top-level `skipped` array) — poly correctly declined the
+  file (e.g. a template dialect no backend handles). Not a failure.
+- **Errored** (`error` field, and the top-level `errors` array) — poly failed to process the
+  file (unreadable file, backend crash, bad engine config). Distinct from `skipped` on purpose:
+  a skip is a deliberate decision, an error is poly failing on a file it accepted.
+
+The top-level `errors` array duplicates the `error`-carrying records in `results` so a caller
+can gate on "did the run fail on anything" without scanning every record. When `errors` is
+non-empty, the tool result's `CallToolResult.is_error` (`isError` over the wire) is set `true`.
+
+**An MCP-driving agent must check `isError` (or `summary.errored`) before trusting any other
+part of the result.** Before this shape existed, a file poly failed to process was absent from
+the output entirely — indistinguishable from a file that was checked and found clean. An agent
+that gated on "no findings in `results`" was reading a run that had silently failed to check
+some files as a clean pass. Check `isError` first; only then read `summary` for coverage and
+`results` for diagnostics.

poly_hermes_plugin/skills/poly-mcp/index.md

@@ -0,0 +1,10 @@
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:041e6c4ec0de96e350e6b4a73ef9d19e5d4f73af9368e6ee0b61c54f7ce5957d
+Source-Hash: blake3:840c919261146454e2836095406355dd3ba8664fc068055c202682015400e43f
+Schema-Version: v1
+-->
+
+# Concepts
+
+* [Poly Mcp](SKILL.md) - The poly MCP server — the eleven tools and which are read-only vs mutating, the paths/exclude/config/format params, async Tasks for the whole-project phase, and the isError contract

poly_hermes_plugin/skills/poly-orchestrator/SKILL.md

@@ -0,0 +1,66 @@
+---
+description: Use poly as the single lint/format gate instead of invoking ruff/oxlint/rustfmt directly — one poly.toml, poly hooks install, poly migrate, CI via the Goldziher/poly setup Action
+name: poly-orchestrator
+license: MIT
+metadata:
+    author: Goldziher
+    repository: https://github.com/Goldziher/poly
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:3363494043f7c9784c37f40b9ed195ca372dc87bebd5f35072722e988c20773a
+Source-Hash: blake3:840c919261146454e2836095406355dd3ba8664fc068055c202682015400e43f
+Schema-Version: v1
+-->
+
+# poly as the Orchestrator
+
+Treat poly as the **single** lint and format gate for the repository. Do not invoke ruff,
+oxlint, taplo, rumdl, or the rest directly — poly compiles them in as backends, and covers
+everything else via the tree-sitter generic tier, the `quality` metric tier, and its built-in
+ast-grep rule pack, behind one binary, one config, and one report.
+
+## Adopt it
+
+- **One `poly.toml`.** Configure every language and rule in a single per-repo file
+  (`poly.local.toml` for local overrides, `extends` to share a base). Layering is
+  tool default → poly's opinionated overrides → your `poly.toml`. In a monorepo a nested
+  `poly.toml` deep-merges on top of its ancestors for the files beneath it.
+- **`poly migrate`** — absorb existing tool configs into `poly.toml` instead of
+  hand-writing it. It imports **ruff, typos, taplo, and markdownlint** configs; there is no
+  eslint, prettier, or pre-commit importer. The default is a dry-run report — pass `--write`
+  to apply, `--recurse` for a monorepo, `--verify` to re-run poly afterwards, and
+  `--strip-superseded` to also remove `pyproject.toml` sections for tools ruff replaces.
+- **`poly hooks install`** — wire the git-hook shims so `poly` runs the configured stages on
+  every commit, replacing a `.pre-commit-config.yaml`. It installs the hook types your
+  `poly.toml` configures; `--hook-type` picks specific ones and `--overwrite` discards a
+  preserved legacy hook. `poly hooks uninstall` restores what was there before.
+- **`poly config show`** prints the effective merged config; **`poly config update`** pins a
+  symbolic remote `extends` ref into `poly-config.lock`.
+- **`poly doctor`** reports which poly is running, every poly on PATH, and the config in
+  effect — the first thing to run when two machines disagree.
+
+## CI
+
+`Goldziher/poly@v0` is a **setup** action: it installs the `poly` binary (with optional
+caching) and puts it on `PATH`. It does not run poly for you — invoke the commands yourself
+in following steps.
+
+```yaml
+- uses: actions/checkout@v4
+- uses: Goldziher/poly@v0        # inputs: version (default latest), cache, github-token
+- run: poly fmt --check .
+- run: poly lint .
+```
+
+poly is one pinned binary with no *required* system dependencies, so local, hook, and CI
+runs agree — with one caveat: the native-toolchain tier means `rustfmt` and `gofmt` are used
+automatically whenever they are on `PATH`, and formatting output then depends on that tool's
+version. A machine without them silently falls through to the lower-fidelity tree-sitter
+tier. Pin the Rust/Go toolchain in CI (and expect drift otherwise), or set
+`[fmt.rust.rustfmt] enabled = false` / `[fmt.go.gofmt] enabled = false` to stop the subprocess.
+That does not leave the language unformatted: `rustfmt`/`gofmt` are the one pair of backends
+that read `enabled` themselves and hand the file to the tier-2 reindenter when disabled, rather
+than expecting the runner to drop them from the plan — so the file is still formatted, just at
+lower fidelity than the native tool.

poly_hermes_plugin/skills/poly-orchestrator/index.md

@@ -0,0 +1,10 @@
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:a320c195ce6d97513905afe7995e590161abfcbd3ed11eff6d3afbeae48df185
+Source-Hash: blake3:840c919261146454e2836095406355dd3ba8664fc068055c202682015400e43f
+Schema-Version: v1
+-->
+
+# Concepts
+
+* [Poly Orchestrator](SKILL.md) - Use poly as the single lint/format gate instead of invoking ruff/oxlint/rustfmt directly — one poly.toml, poly hooks install, poly migrate, CI via the Goldziher/poly setup Action

poly_hermes_plugin/skills/poly-overview/SKILL.md

@@ -0,0 +1,69 @@
+---
+description: What poly is — the native, tree-sitter, native-toolchain, quality, and built-in-rule-pack tiers, language coverage, and when to reach for it
+name: poly-overview
+license: MIT
+metadata:
+    author: Goldziher
+    repository: https://github.com/Goldziher/poly
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:273b80b1cc5f091780eac739023a29774686024091327f99c639532e042d2ff6
+Source-Hash: blake3:840c919261146454e2836095406355dd3ba8664fc068055c202682015400e43f
+Schema-Version: v1
+-->
+
+# poly Overview
+
+poly is a single pure-Rust binary that lints and formats a whole repository across
+languages. It wraps best-in-class tools as in-process crate backends and falls back to a
+tree-sitter generic tier for everything else, so it runs the same on any machine and in CI.
+No system tool is ever *required*; the one scoped exception is the native-toolchain tier
+below, which uses a language's canonical CLI when it happens to be installed.
+
+## Per-language coverage tiers
+
+- **Tier 1 — native in-process backends.** Highest fidelity, compiled straight into the
+  binary and registered per language in `registry.rs`: `ruff` (Python), `oxc`
+  (JS/TS/JSX/TSX/JSON/JSONC), `taplo` (TOML), `rumdl` (Markdown/MDX), `sqruff` (SQL), YAML,
+  `malva` (CSS/SCSS/LESS) + `biome` (CSS/SCSS), `markup_fmt` (HTML/Vue/Svelte/Astro/Angular/Jinja/
+  Vento/Mustache/XML), `mago` (PHP), `rubyfmt` (Ruby), `graphql` + `biome` (GraphQL),
+  `nixfmt` (Nix), `hcl`, Dockerfile, dotenv, and INI.
+- **Tier 2 — tree-sitter generic tier.** The catch-all for the long tail (Elixir, C/C++,
+  C#, protobuf, and the rest of 300+ grammars). CST-driven structural reindent for
+  brace-family grammars, whitespace normalization otherwise, and a `LEAVE_UNTOUCHED` list
+  for grammars where whitespace is significant. Best-effort, pure Rust, grammars loaded on
+  demand — never gofmt/rustfmt parity, by design.
+- **Native-toolchain tier (scoped exception).** A language's canonical first-party CLI run
+  per file over stdin/stdout when installed: `rustfmt`, `gofmt` and `shellcheck` are **on by
+  default when found on PATH**; `zig fmt`, `shfmt`, `google-java-format`, `ktfmt`, `styler`
+  (R), `swift-format`, `dart format`, and `gleam format` are opt-in via
+  `[fmt.<lang>.<tool>] enabled = true` / `[lint.<lang>.<tool>] enabled = true`. When the
+  tool is absent, formatting falls through to tier 2 with an info-level notice, so the
+  zero-dependency guarantee always holds.
+
+## Cross-cutting engines (every language)
+
+Four engines are appended to every language regardless of tier:
+
+- **`typos`** — spelling in identifiers, comments, and strings.
+- **`quality`** — structural code-quality metrics off the tree-sitter parse: file/function/
+  type length, nesting depth, cyclomatic complexity, parameter count, and `lazy-ignore`.
+  Warning severity, on by default. The structural rules need a verified node-kind table and
+  run for Python, Rust, Go, JavaScript, TypeScript, TSX, Java, Kotlin, C, C++, C#, and Ruby;
+  `magic-number` and `law-of-demeter` are opt-in. Configure under `[lint.quality]`.
+- **`astgrep`** — ast-grep pattern rules. poly embeds a **built-in rule pack** of 26 rules
+  across 9 languages (C#, Elixir, Go, Java, Kotlin, Python, Ruby, Rust, Swift), on by
+  default; 13 of them ship `severity: off`. User rules under `[rules] dirs` (default
+  `.poly/rules`) layer on top and replace a pack rule sharing its `id`. Disable the pack
+  wholesale with `[rules] builtin = false`.
+- **`uncomment`** — opt-in comment removal, off unless `[lint.uncomment] enabled = true`.
+
+## When to use it
+
+Reach for poly as the single lint/format gate for any repo: local dev, git hooks, and CI.
+It replaces invoking ruff / oxlint / rustfmt / prettier individually — one binary, one
+`poly.toml`, one report. A language with no native backend still gets tier-2 formatting
+plus the cross-cutting engines, so poly covers the whole tree rather than only the
+languages you wired up by hand.

poly_hermes_plugin/skills/poly-overview/index.md

@@ -0,0 +1,10 @@
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:948de85c38f4ceee5ac758d6b75670c18be2a3850757a17f1b0546d467019698
+Source-Hash: blake3:840c919261146454e2836095406355dd3ba8664fc068055c202682015400e43f
+Schema-Version: v1
+-->
+
+# Concepts
+
+* [Poly Overview](SKILL.md) - What poly is — the native, tree-sitter, native-toolchain, quality, and built-in-rule-pack tiers, language coverage, and when to reach for it

poly_hermes_plugin/skills/poly-tiers-and-scope/SKILL.md

@@ -0,0 +1,129 @@
+---
+description: poly's coverage tiers (native / tree-sitter / native-toolchain / quality / built-in ast-grep pack), the per-file tier vs the whole-project phase (--no-workspace), staged isolation (ADR 0019), and hierarchical poly.toml in monorepos (ADR 0018)
+name: poly-tiers-and-scope
+license: MIT
+metadata:
+    author: Goldziher
+    repository: https://github.com/Goldziher/poly
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:ad140ec77b0aed2a08b9c7261e16d5f9cde428c88e6e249a9891a24e6f35b964
+Source-Hash: blake3:840c919261146454e2836095406355dd3ba8664fc068055c202682015400e43f
+Schema-Version: v1
+-->
+
+# poly Tiers and Scope
+
+## Coverage tiers inside the per-file pass
+
+Five mechanisms decide what actually inspects a file (`crates/poly-core/src/registry.rs`):
+
+1. **Tier-1 native crate backends** — one in-process Rust crate registered for specific
+   languages: ruff, oxc, taplo, rumdl, sqruff, yaml, malva (+ biome for CSS/SCSS), markup_fmt, mago, rubyfmt,
+   graphql, nixfmt, hcl, dockerfile, dotenv, ini.
+2. **Tier-2 tree-sitter generic tier** (ADR 0004) — the catch-all for every language with no
+   native backend. Structural reindent for brace-family grammars, whitespace normalization
+   otherwise, and a leave-untouched list where whitespace is significant. This is the
+   coverage mechanism, not a fallback to avoid — but it is explicitly *not* gofmt/rustfmt
+   parity.
+3. **Native-toolchain tier** (ADR 0014, `engines/native_tool/`) — the language's canonical
+   first-party CLI, run per file over stdin/stdout. `rustfmt`, `gofmt` and `shellcheck` are
+   **on by default whenever the tool is found on PATH**; `zig fmt`, `shfmt`,
+   `google-java-format`, `ktfmt`, `styler`, `swift-format`, `dart format`, and
+   `gleam format` are opt-in via `[fmt.<lang>.<tool>] enabled = true` /
+   `[lint.<lang>.<tool>] enabled = true`. Absent tool ⇒ the language falls through to
+   tier 2 with an info-level notice, never an error.
+4. **`quality`, the code-quality metric tier** (ADR 0027) — cross-cutting, appended to every
+   language: file/function/type length, nesting depth, cyclomatic complexity, parameter
+   count, and `lazy-ignore`. Warning severity, on by default, configured under
+   `[lint.quality]`. The structural rules need a verified node-kind table and cover Python,
+   Rust, Go, JavaScript, TypeScript, TSX, Java, Kotlin, C, C++, C#, and Ruby; `magic-number`
+   and `law-of-demeter` are opt-in. A per-language deferral table keeps it from duplicating
+   a tier-1 rule (ruff's `C901`/`PLR0913`, oxlint's `max-depth`/`max-params`).
+5. **The built-in ast-grep rule pack** (ADR 0029) — 26 rules across 9 languages (C#, Elixir,
+   Go, Java, Kotlin, Python, Ruby, Rust, Swift) embedded in the binary and on by default; 13
+   of them ship `severity: off`. It sits *beneath* `[rules] dirs` (default `.poly/rules`), so
+   a user rule with the same `id` replaces a pack rule. `[rules] builtin = false` disables
+   the pack wholesale.
+
+`typos` (spelling) and the opt-in `uncomment` engine are the other two cross-cutting
+backends appended to every language.
+
+**Every engine table also accepts a universal `enabled` key**, read by the runner's plan
+rather than by any backend. Whether narrowing a file out of a run charges against
+`--deny-skips` / `--max-skips` follows one rule: **a poly limitation is charged and names the
+limitation; a caller instruction is never charged and always names itself.** `--only`/`--skip`
+and `enabled = false` are caller instructions, so a file they remove is reported as skipped but
+not charged; `no matching engine for this file type`, `no lint rules for <language>`, and a
+generated-file skip are poly's own limitations, and are charged.
+
+## Per-file tier vs whole-project phase
+
+`poly lint` runs in two phases:
+
+- **Per-file tier** — the parallel, cached engine pass over every discovered file, using the
+  five mechanisms above. This is all `--no-workspace` runs.
+- **Whole-project phase** — invokes the same whole-workspace tools a pre-commit hook would
+  (`cargo clippy` / `cargo-sort` / `cargo-machete` / `cargo-deny`, plus any inline
+  `workspace = true` job such as a type checker) on the live worktree, folding their
+  pass/fail into the report and exit code. It reuses the `[hooks]` config as its single
+  source of truth. On by default; disable with `--no-workspace` or `[lint] workspace =
+  false`. A repo with no `[hooks]` section has no whole-workspace hooks to lower, so it runs
+  only the per-file tier.
+
+**Plain `poly lint` is not read-only.** poly applies no fixes without `--fix`, but the
+whole-project phase *executes* those tools against the live worktree, and their own side
+effects are not poly's to control (`cargo clippy` populating `target/` or refreshing
+`Cargo.lock`, a `go` invocation appending to `go.work.sum`, a type checker writing its
+cache). Only `--no-workspace` / `[lint] workspace = false` gives a run that cannot touch the
+tree.
+
+The phase is also **not path-scoped**: `poly lint <paths>` skips it when the paths *narrow*
+the run, and `--workspace` opts back in with the tools covering the whole repository —
+regardless of the named paths and of `[discovery] exclude`, which filters poly's own
+discovery only. Naming the directory poly is running in (`poly lint .`) is a request for the
+whole project, not a narrowing, so the phase still runs. A note on stderr says which branch
+was taken.
+
+Under `--fix`, the whole-project phase runs the tools in fix mode (`cargo sort` in place,
+`cargo-machete --fix`, `cargo clippy --fix --allow-dirty --allow-staged`; `cargo deny` stays
+check-only). Fix mode is what `--fix` adds — the phase runs either way, so `--no-workspace`,
+not the absence of `--fix`, is what skips it. The git-hook / commit-gate path never requests
+fix mode. `poly fmt` never runs this phase.
+
+## Staged isolation (ADR 0019)
+
+On the commit-gate path, poly materializes a snapshot of the git **index** (via
+`git checkout-index`) and runs the stage from it, so unstaged edits neither hide nor cause
+failures. Details that matter:
+
+- The snapshot is the execution root for **every** hook in the run, not just the
+  whole-workspace ones — a gate whose per-file hooks read the worktree while its
+  whole-project hooks read the index would report on two different sets of bytes.
+- Isolation is active only for the index stages (`pre-commit`, `pre-merge-commit`) and is
+  skipped for `--all-files` (which deliberately checks the whole tree) and for non-index
+  stages such as `pre-push`. `[hooks] isolate = false` forces it off.
+- The snapshot lives in the per-user OS cache dir (`~/.cache/poly/<repo-key>/staged`), not
+  in-repo, and is refreshed incrementally by index OID so tool caches stay warm.
+- `poly lint`'s whole-project phase is a *different* path: it runs against the live
+  worktree, so no snapshot is built.
+- `[hooks] snapshot_include` opts named, git-untracked, repo-relative paths into the snapshot
+  by symlinking them in from the live worktree, so a `workspace` hook whose build reads a
+  gitignored input (a generated file, a local type-checker config, a downloaded fixture
+  directory) does not fail under the gate for a reason the error message doesn't name. Three
+  consequences follow from the symlink: a fix to an included file is withheld (there is no
+  staged blob to write it into), an included file is never a per-file hook's own input (only
+  index content is), and the symlink lets a hook write through into the live worktree.
+
+## Hierarchical poly.toml in monorepos (ADR 0018)
+
+Config resolves hierarchically: every `poly.toml` from the repository root down to the file
+being processed is deep-merged, so a nested config layers on top of its ancestors and each
+package can tune rules while sharing a root baseline. The upward walk is bounded at the
+`.git` directory (or an explicit `[workspace] root = true`), so a stray `poly.toml` in
+`$HOME` is never picked up. `poly.local.toml` remains the final local override layer, and a
+top-level `extends` list (ADR 0020) shares sections from local or pinned-remote base
+configs — `poly config update` pins a symbolic remote ref into `poly-config.lock`, and
+`poly config show` prints the effective merged config.

poly_hermes_plugin/skills/poly-tiers-and-scope/index.md

@@ -0,0 +1,10 @@
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:cb19976815fbf90d5f6b6eb13257488eab322f2780265391d895a30e5cc0ff18
+Source-Hash: blake3:840c919261146454e2836095406355dd3ba8664fc068055c202682015400e43f
+Schema-Version: v1
+-->
+
+# Concepts
+
+* [Poly Tiers And Scope](SKILL.md) - poly's coverage tiers (native / tree-sitter / native-toolchain / quality / built-in ast-grep pack), the per-file tier vs the whole-project phase (--no-workspace), staged isolation (ADR 0019), and hierarchical poly.toml in monorepos (ADR 0018)

poly_hermes_plugin-0.29.0.dist-info/METADATA

@@ -0,0 +1,24 @@
+Metadata-Version: 2.5
+Name: poly-hermes-plugin
+Version: 0.29.0
+Summary: Zero-dependency lint & format orchestrator over MCP — one pure-Rust binary wrapping ruff/oxc/taplo/rumdl and more as in-process backends, plus a tree-sitter generic tier for everything else. Exposes lint/format/cache tools with structured JSON output.
+Project-URL: Homepage, https://github.com/Goldziher/poly
+Project-URL: Repository, https://github.com/Goldziher/poly
+License-Expression: MIT
+Keywords: code-quality,formatter,linter,mcp,rust
+Requires-Python: >=3.11
+Requires-Dist: mcp==1.28.1
+Requires-Dist: pyyaml==6.0.3
+Description-Content-Type: text/markdown
+
+# poly Hermes plugin
+
+Zero-dependency lint & format orchestrator over MCP — one pure-Rust binary wrapping ruff/oxc/taplo/rumdl and more as in-process backends, plus a tree-sitter generic tier for everything else. Exposes lint/format/cache tools with structured JSON output.
+
+Install this package in the same Python environment as Hermes Agent:
+
+```sh
+python -m pip install poly-hermes-plugin
+```
+
+Enable the plugin through Hermes Agent's plugin configuration. Available registrations depend on the plugin's authored Hermes adapter.

poly_hermes_plugin-0.29.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+poly_hermes_plugin/__init__.py,sha256=TTmehqN7xNwIkpo2hE9u86MMHnDsyfMoqZBILoRZ7dE,385
+poly_hermes_plugin/hermes.py,sha256=AjHDxQ1WFW9l-txFeNSQ9dseTgvOnyhgaa7d19TqWgo,4550
+poly_hermes_plugin/plugin.yaml,sha256=y1IJt71YWVZw3uQLUNeFrmB_IZNMDSRJNvAQMPQwwWQ,407
+poly_hermes_plugin/commands/poly-check.md,sha256=m0GBQKvwIEaL2nRPqBO2KISfEYgrbq21uImQUA6P0bw,2392
+poly_hermes_plugin/commands/poly-fix.md,sha256=1xMCQAgVfYvAq_862xyOFyCDeA15yrFGGMY3ds0MILo,1920
+poly_hermes_plugin/skills/poly-lint-and-format/SKILL.md,sha256=QUocECEYx32QzKEf7VqBq6kGDQsRBUxp7xMPjWPx9Uc,6257
+poly_hermes_plugin/skills/poly-lint-and-format/index.md,sha256=lXaTKLl_qchFml1PcwDA4DBi_TkJpIYR9vkKng8Gemc,466
+poly_hermes_plugin/skills/poly-mcp/SKILL.md,sha256=k9FQ7YHb1H-zqN5WHlGYV3VwyOdAtSjBShQ8rlgKs6s,7054
+poly_hermes_plugin/skills/poly-mcp/index.md,sha256=9J7XDDR3IR9hp3Cm9__uqqIcxvEuH8DIcWHZj_ew87A,464
+poly_hermes_plugin/skills/poly-orchestrator/SKILL.md,sha256=-EvXs4yJp9N2-Pt3Kk9VZEIzDyZdjRO1lfzBI2q8HK4,3625
+poly_hermes_plugin/skills/poly-orchestrator/index.md,sha256=3UuoEWsv99FwhbVVQqpeLSu28eMDX6nAGa08IC5MDN8,470
+poly_hermes_plugin/skills/poly-overview/SKILL.md,sha256=XfLd6nh32SEiE8JwSWhCObnZeShvTD468k9r_va2-Xs,3994
+poly_hermes_plugin/skills/poly-overview/index.md,sha256=RhvI75X2ehnUqYC5f40ou_hfqjFTH6Iu18k8lTQHL0U,428
+poly_hermes_plugin/skills/poly-tiers-and-scope/SKILL.md,sha256=rz8Cbu3WREG3FKrNINr1LkO2WAim1dLFOL4p11ipMNk,8223
+poly_hermes_plugin/skills/poly-tiers-and-scope/index.md,sha256=oaMihgN8uUkAdVWgWY11wFaIL_hZp9rOlRCgvfDMViI,535
+poly_hermes_plugin-0.29.0.dist-info/METADATA,sha256=FuoCI_7vfCQQkpBpc-HylcGbU842kwZYA2GWH7TMzq0,1170
+poly_hermes_plugin-0.29.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+poly_hermes_plugin-0.29.0.dist-info/entry_points.txt,sha256=lBeJl88Ie_tUFqFbPZ5KqPaVtJ-a1s-Kd4x5Rex-7QI,49
+poly_hermes_plugin-0.29.0.dist-info/RECORD,,

poly_hermes_plugin-0.29.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

poly_hermes_plugin-0.29.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hermes_agent.plugins]
+poly = poly_hermes_plugin