runspec-grafana 0.1.0__tar.gz

runspec_grafana-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json
+
+# Stray committed test venv (removed from tracking)
+.venv-test/

runspec_grafana-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to `runspec-grafana` are documented here.
+
+## [0.1.0]
+
+First release. One runnable, `grafana`, with a verb per read tool of the
+[Grafana MCP server](https://github.com/grafana/mcp-grafana), ported onto the
+Grafana HTTP API (no proxy process):
+
+- **Reads** (`autonomous`): `whoami`, `health`, `search-dashboards`,
+  `search-folders`, `get-dashboard`, `list-dashboard-versions`,
+  `list-datasources`, `get-datasource`, `check-datasource`,
+  `query-prometheus`, `query-prometheus-histogram`,
+  `list-prometheus-metric-names`, `list-prometheus-label-names`,
+  `list-prometheus-label-values`, `list-prometheus-metric-metadata`,
+  `query-loki-logs`, `list-loki-label-names`, `list-loki-label-values`,
+  `query-loki-stats`, `query-loki-patterns`, `list-alert-rules`,
+  `get-alert-rule`, `list-contact-points`, `list-silences`,
+  `get-annotations`, `get-annotation-tags`, and `api-get` (GET any `/api/`
+  path).
+- **Changes** (`confirm`): `create-annotation`.
+- Compact output by default, with `--include` / `--raw` / `--include-values` /
+  `--limit` for more; a person at a terminal gets text, everyone else JSON.
+- Globals `--env` (free-form instance label → `GRAFANA_<ENV>_*`), `--url`,
+  `--org-id`, and a `password`-typed `--grafana-token` for the runspec-console
+  secret channel. With nothing set it talks to `http://127.0.0.1:3000`.
+- Not ported yet: dashboard and alert-rule writes, silences writes, OnCall,
+  Incident, Tempo, Pyroscope, SQL/CloudWatch/Elasticsearch queries, panel
+  rendering, and the Grafana Assistant.

runspec_grafana-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: runspec-grafana
+Version: 0.1.0
+Summary: Grafana runnable for runspec — dashboards, datasources, PromQL and LogQL through Grafana, alert rules, silences, and annotations, ported from the Grafana MCP server
+Project-URL: Documentation, https://runspec.app/
+Project-URL: Source, https://github.com/jasonfinestone/runspec/tree/main/packages/python/runspec-grafana
+Project-URL: Changelog, https://github.com/jasonfinestone/runspec/blob/main/packages/python/runspec-grafana/CHANGELOG.md
+Project-URL: Issues, https://github.com/jasonfinestone/runspec/issues
+Keywords: grafana,loki,mcp,monitoring,observability,prometheus,runnable,runspec
+Requires-Python: >=3.10
+Requires-Dist: runspec-grafana-core>=0.1.0
+Requires-Dist: runspec>=0.73.1
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.15.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# runspec-grafana
+
+A Grafana runnable for [runspec](https://pypi.org/project/runspec/), ported from
+the read tools of the [Grafana MCP server](https://github.com/grafana/mcp-grafana)
+onto the Grafana HTTP API — **not** proxying that server. One runnable —
+**`grafana`** — with a verb per tool. `pip install` it into a venv and it's
+discoverable by `runspec local`, `runspec serve` (MCP), and runspec-console.
+
+`runspec serve` flattens each verb into a leaf MCP tool
+(`grafana_search-dashboards`, `grafana_query-prometheus`, …).
+
+## Install
+
+```
+pip install runspec-grafana
+```
+
+## Verbs
+
+All `autonomous` (read-only) except `create-annotation`, which is `confirm`.
+
+| Area | Verbs |
+|---|---|
+| Identity | `whoami`, `health` |
+| Dashboards | `search-dashboards`, `search-folders`, `get-dashboard`, `list-dashboard-versions` |
+| Datasources | `list-datasources`, `get-datasource`, `check-datasource` |
+| Prometheus | `query-prometheus`, `query-prometheus-histogram`, `list-prometheus-metric-names`, `list-prometheus-label-names`, `list-prometheus-label-values`, `list-prometheus-metric-metadata` |
+| Loki | `query-loki-logs`, `list-loki-label-names`, `list-loki-label-values`, `query-loki-stats`, `query-loki-patterns` |
+| Alerting | `list-alert-rules`, `get-alert-rule`, `list-contact-points`, `list-silences` |
+| Annotations | `get-annotations`, `get-annotation-tags`, `create-annotation` |
+| Anything else | `api-get` (GET any `/api/` path, returned as-is) |
+
+PromQL and LogQL run through Grafana's datasource proxy, so only the Grafana
+token is needed — never the datasource's own credentials. `--datasource` takes a
+UID or a name; without it the default (or only) Prometheus or Loki datasource is
+used.
+
+## Output
+
+Results are compact by default, because an agent re-reads every tool result on
+each later step:
+
+- `get-dashboard` returns a summary: folder, tags, variables, and one row per
+  panel. `--include queries` adds each panel's query text, `--panel <id>` keeps
+  one panel, `--raw` returns the full dashboard JSON.
+- `query-prometheus --query-type range` summarises each series (points, first,
+  last, min, max); `--include-values` returns every sample.
+- `query-loki-logs` lists each stream's labels once and gives the lines newest
+  first, each cut to `--max-line-chars` (500).
+- `list-alert-rules` puts firing rules first with counts by state;
+  `--include alerts` adds the active alert instances.
+- Every list takes `--limit` and says `truncated: true` when it cut something.
+
+A person at a terminal gets readable text; agents, pipes, the console's Forms
+tab and schedulers get JSON.
+
+Times accept Unix seconds or milliseconds, RFC 3339, `now-1h`, or a duration
+back from now (`5m`, `1h30m`).
+
+## Auth — env vars
+
+```
+export GRAFANA_URL=https://grafana.example.com            # default http://127.0.0.1:3000
+export GRAFANA_SERVICE_ACCOUNT_TOKEN=glsa_...             # or GRAFANA_TOKEN, or:
+export GRAFANA_USERNAME=<user> GRAFANA_PASSWORD=<password>
+export GRAFANA_ORG_ID=2                                   # X-Grafana-Org-Id
+export GRAFANA_CA_BUNDLE=/etc/pki/internal-ca.pem         # private CA
+```
+
+Use a [service account](https://grafana.com/docs/grafana/latest/administration/service-accounts/)
+token. The **Viewer** role covers every read except `list-dashboard-versions`;
+that and `create-annotation` need **Editor**.
+
+`--env <label>` reads `GRAFANA_<LABEL>_*` first (`--env prod-eu` →
+`GRAFANA_PROD_EU_URL`). `--url`, `--org-id` and `--grafana-token` override the
+environment; the token arg is a `password` type, so it comes through the
+runspec-console secret channel and never on a command line. A runspec-console
+credential labelled `Grafana` of the token kind supplies `GRAFANA_TOKEN`, and
+one of the username + password kind supplies `GRAFANA_USERNAME`/`PASSWORD`,
+with no extra configuration.
+
+## Building your own runnables
+
+The logic lives in [`runspec-grafana-core`](../runspec-grafana-core), which has
+no runspec dependency and surfaces no runnables. A private package can depend on
+it alone, build a `GrafanaConfig` in code, and wrap the helpers as narrower
+runnables — for example a `checkout-errors` runnable that runs one fixed LogQL
+query for a team:
+
+```python
+from runspec_grafana_core import config_from_env, query_loki_logs
+
+cfg = config_from_env("prod")
+errors = query_loki_logs(cfg, '{app="checkout"} |= "level=error"', start="30m", limit=20)
+```

runspec_grafana-0.1.0/README.md

@@ -0,0 +1,95 @@
+# runspec-grafana
+
+A Grafana runnable for [runspec](https://pypi.org/project/runspec/), ported from
+the read tools of the [Grafana MCP server](https://github.com/grafana/mcp-grafana)
+onto the Grafana HTTP API — **not** proxying that server. One runnable —
+**`grafana`** — with a verb per tool. `pip install` it into a venv and it's
+discoverable by `runspec local`, `runspec serve` (MCP), and runspec-console.
+
+`runspec serve` flattens each verb into a leaf MCP tool
+(`grafana_search-dashboards`, `grafana_query-prometheus`, …).
+
+## Install
+
+```
+pip install runspec-grafana
+```
+
+## Verbs
+
+All `autonomous` (read-only) except `create-annotation`, which is `confirm`.
+
+| Area | Verbs |
+|---|---|
+| Identity | `whoami`, `health` |
+| Dashboards | `search-dashboards`, `search-folders`, `get-dashboard`, `list-dashboard-versions` |
+| Datasources | `list-datasources`, `get-datasource`, `check-datasource` |
+| Prometheus | `query-prometheus`, `query-prometheus-histogram`, `list-prometheus-metric-names`, `list-prometheus-label-names`, `list-prometheus-label-values`, `list-prometheus-metric-metadata` |
+| Loki | `query-loki-logs`, `list-loki-label-names`, `list-loki-label-values`, `query-loki-stats`, `query-loki-patterns` |
+| Alerting | `list-alert-rules`, `get-alert-rule`, `list-contact-points`, `list-silences` |
+| Annotations | `get-annotations`, `get-annotation-tags`, `create-annotation` |
+| Anything else | `api-get` (GET any `/api/` path, returned as-is) |
+
+PromQL and LogQL run through Grafana's datasource proxy, so only the Grafana
+token is needed — never the datasource's own credentials. `--datasource` takes a
+UID or a name; without it the default (or only) Prometheus or Loki datasource is
+used.
+
+## Output
+
+Results are compact by default, because an agent re-reads every tool result on
+each later step:
+
+- `get-dashboard` returns a summary: folder, tags, variables, and one row per
+  panel. `--include queries` adds each panel's query text, `--panel <id>` keeps
+  one panel, `--raw` returns the full dashboard JSON.
+- `query-prometheus --query-type range` summarises each series (points, first,
+  last, min, max); `--include-values` returns every sample.
+- `query-loki-logs` lists each stream's labels once and gives the lines newest
+  first, each cut to `--max-line-chars` (500).
+- `list-alert-rules` puts firing rules first with counts by state;
+  `--include alerts` adds the active alert instances.
+- Every list takes `--limit` and says `truncated: true` when it cut something.
+
+A person at a terminal gets readable text; agents, pipes, the console's Forms
+tab and schedulers get JSON.
+
+Times accept Unix seconds or milliseconds, RFC 3339, `now-1h`, or a duration
+back from now (`5m`, `1h30m`).
+
+## Auth — env vars
+
+```
+export GRAFANA_URL=https://grafana.example.com            # default http://127.0.0.1:3000
+export GRAFANA_SERVICE_ACCOUNT_TOKEN=glsa_...             # or GRAFANA_TOKEN, or:
+export GRAFANA_USERNAME=<user> GRAFANA_PASSWORD=<password>
+export GRAFANA_ORG_ID=2                                   # X-Grafana-Org-Id
+export GRAFANA_CA_BUNDLE=/etc/pki/internal-ca.pem         # private CA
+```
+
+Use a [service account](https://grafana.com/docs/grafana/latest/administration/service-accounts/)
+token. The **Viewer** role covers every read except `list-dashboard-versions`;
+that and `create-annotation` need **Editor**.
+
+`--env <label>` reads `GRAFANA_<LABEL>_*` first (`--env prod-eu` →
+`GRAFANA_PROD_EU_URL`). `--url`, `--org-id` and `--grafana-token` override the
+environment; the token arg is a `password` type, so it comes through the
+runspec-console secret channel and never on a command line. A runspec-console
+credential labelled `Grafana` of the token kind supplies `GRAFANA_TOKEN`, and
+one of the username + password kind supplies `GRAFANA_USERNAME`/`PASSWORD`,
+with no extra configuration.
+
+## Building your own runnables
+
+The logic lives in [`runspec-grafana-core`](../runspec-grafana-core), which has
+no runspec dependency and surfaces no runnables. A private package can depend on
+it alone, build a `GrafanaConfig` in code, and wrap the helpers as narrower
+runnables — for example a `checkout-errors` runnable that runs one fixed LogQL
+query for a team:
+
+```python
+from runspec_grafana_core import config_from_env, query_loki_logs
+
+cfg = config_from_env("prod")
+errors = query_loki_logs(cfg, '{app="checkout"} |= "level=error"', start="30m", limit=20)
+```

runspec_grafana-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-grafana"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Grafana runnable for runspec — dashboards, datasources, PromQL and LogQL through Grafana, alert rules, silences, and annotations, ported from the Grafana MCP server"
+readme = "README.md"
+keywords = ["runspec", "runnable", "grafana", "prometheus", "loki", "monitoring", "observability", "mcp"]
+dependencies = [
+    # 0.73.1 keeps httpx's INFO request lines off stdout, so the JSON result
+    # is the only thing an agent reads.
+    "runspec>=0.73.1",
+    "runspec-grafana-core>=0.1.0",
+]
+
+[project.urls]
+Documentation = "https://runspec.app/"
+Source        = "https://github.com/jasonfinestone/runspec/tree/main/packages/python/runspec-grafana"
+Changelog     = "https://github.com/jasonfinestone/runspec/blob/main/packages/python/runspec-grafana/CHANGELOG.md"
+Issues        = "https://github.com/jasonfinestone/runspec/issues"
+
+[project.scripts]
+# Entry point name MUST match the runnable name in runspec.toml (`grafana`).
+grafana = "runspec_grafana.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "ruff==0.15.20",
+    "mypy",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+
+[tool.ruff]
+line-length = 200
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

runspec_grafana-0.1.0/runspec_grafana/__init__.py

@@ -0,0 +1,15 @@
+"""runspec-grafana — Grafana as a runspec runnable (the ``grafana`` runnable).
+
+Ported from the read tools of the
+`Grafana MCP server <https://github.com/grafana/mcp-grafana>`_. The pure HTTP
+logic lives in ``runspec-grafana-core`` (importable with **no** runspec
+dependency); this package wraps each helper as a verb of the ``grafana``
+runnable and is what ``runspec local`` / ``runspec serve`` discover.
+
+The core helpers are re-exported here for convenience, so a caller that already
+depends on ``runspec-grafana`` can ``from runspec_grafana import search_dashboards``
+without also naming ``runspec-grafana-core``.
+"""
+
+from runspec_grafana_core import *  # noqa: F403
+from runspec_grafana_core import __all__  # noqa: F401

runspec_grafana-0.1.0/runspec_grafana/cli.py

@@ -0,0 +1,274 @@
+"""cli.py — the ``grafana`` entry point.
+
+One binary, a verb per Grafana MCP read tool. ``rs.parse("grafana")`` resolves
+the subcommand and its args; we build a :class:`GrafanaConfig` from the
+environment (scoped by the global ``--env``, with ``--url`` / ``--org-id`` /
+``--grafana-token`` overriding), unpack each ``.value`` at the boundary, and
+call the matching :mod:`runspec_grafana_core` helper.
+
+Agents, pipes, the console's Forms tab and schedulers get compact JSON; a
+person at a terminal gets readable text (:mod:`runspec_grafana.render`).
+Failures (:class:`GrafanaError` and arg-shape ``ValueError``s) become a JSON
+``{"error": ...}`` payload + a non-zero exit.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import runspec as rs
+from runspec_grafana_core import (
+    GrafanaConfig,
+    GrafanaError,
+    api_get,
+    check_datasources,
+    config_from_env,
+    create_annotation,
+    get_alert_rule,
+    get_annotation_tags,
+    get_annotations,
+    get_dashboard,
+    get_datasource,
+    health,
+    list_alert_rules,
+    list_contact_points,
+    list_dashboard_versions,
+    list_datasources,
+    list_loki_label_names,
+    list_loki_label_values,
+    list_prometheus_label_names,
+    list_prometheus_label_values,
+    list_prometheus_metric_metadata,
+    list_prometheus_metric_names,
+    list_silences,
+    query_loki_logs,
+    query_loki_patterns,
+    query_loki_stats,
+    query_prometheus,
+    query_prometheus_histogram,
+    search_dashboards,
+    search_folders,
+    whoami,
+)
+
+from runspec_grafana.render import human_text
+
+
+def _emit(payload: Any, *, text: str | None = None) -> None:
+    print(text if text is not None else json.dumps(payload, default=str))
+
+
+def _list(arg: rs.Arg) -> list[str]:
+    return list(arg.value) if arg.value else []
+
+
+def _dispatch(spec: rs.RunSpec, config: GrafanaConfig) -> Any:
+    """Run the active verb against ``config``, unpacking ``spec.<arg>.value`` for
+    only the args the verb declares (globals + its own)."""
+    command = spec.runspec_command
+
+    # ── identity / dashboards ──
+    if command == "whoami":
+        return whoami(config)
+    if command == "health":
+        return health(config)
+    if command == "search-dashboards":
+        return search_dashboards(
+            config,
+            query=spec.query.value,
+            tags=_list(spec.tag),
+            folder_uids=_list(spec.folder_uid),
+            starred=spec.starred.value,
+            limit=spec.limit.value,
+        )
+    if command == "search-folders":
+        return search_folders(config, query=spec.query.value, limit=spec.limit.value)
+    if command == "get-dashboard":
+        return get_dashboard(
+            config,
+            spec.uid.value,
+            version=spec.version.value,
+            include=_list(spec.include),
+            panel_id=spec.panel.value,
+            raw=spec.raw.value,
+        )
+    if command == "list-dashboard-versions":
+        return list_dashboard_versions(config, spec.uid.value, limit=spec.limit.value)
+
+    # ── datasources ──
+    if command == "list-datasources":
+        return list_datasources(config, ds_type=spec.type.value, limit=spec.limit.value)
+    if command == "get-datasource":
+        return get_datasource(config, spec.datasource.value)
+    if command == "check-datasource":
+        return check_datasources(config, refs=_list(spec.datasource), limit=spec.limit.value)
+
+    # ── Prometheus ──
+    if command == "query-prometheus":
+        return query_prometheus(
+            config,
+            spec.query.value,
+            datasource=spec.datasource.value,
+            query_type=spec.query_type.value,
+            at=spec.time.value,
+            start=spec.start.value,
+            end=spec.end.value,
+            step=spec.step.value,
+            limit=spec.limit.value,
+            include_values=spec.include_values.value,
+        )
+    if command == "query-prometheus-histogram":
+        return query_prometheus_histogram(
+            config,
+            spec.metric.value,
+            percentile=spec.percentile.value,
+            selector=spec.selector.value,
+            by=_list(spec.by),
+            rate_interval=spec.rate_interval.value,
+            datasource=spec.datasource.value,
+            query_type=spec.query_type.value,
+            at=spec.time.value,
+            start=spec.start.value,
+            end=spec.end.value,
+            step=spec.step.value,
+            limit=spec.limit.value,
+            include_values=spec.include_values.value,
+        )
+    if command == "list-prometheus-metric-names":
+        return list_prometheus_metric_names(
+            config,
+            datasource=spec.datasource.value,
+            regex=spec.regex.value,
+            matches=_list(spec.match),
+            start=spec.start.value,
+            end=spec.end.value,
+            limit=spec.limit.value,
+        )
+    if command == "list-prometheus-label-names":
+        return list_prometheus_label_names(config, datasource=spec.datasource.value, matches=_list(spec.match), start=spec.start.value, end=spec.end.value, limit=spec.limit.value)
+    if command == "list-prometheus-label-values":
+        return list_prometheus_label_values(
+            config,
+            spec.label.value,
+            datasource=spec.datasource.value,
+            matches=_list(spec.match),
+            start=spec.start.value,
+            end=spec.end.value,
+            limit=spec.limit.value,
+        )
+    if command == "list-prometheus-metric-metadata":
+        return list_prometheus_metric_metadata(config, datasource=spec.datasource.value, metric=spec.metric.value, limit=spec.limit.value)
+
+    # ── Loki ──
+    if command == "query-loki-logs":
+        return query_loki_logs(
+            config,
+            spec.query.value,
+            datasource=spec.datasource.value,
+            start=spec.start.value,
+            end=spec.end.value,
+            limit=spec.limit.value,
+            direction=spec.direction.value,
+            max_line_chars=spec.max_line_chars.value,
+            include_values=spec.include_values.value,
+        )
+    if command == "list-loki-label-names":
+        return list_loki_label_names(config, datasource=spec.datasource.value, query=spec.query.value, start=spec.start.value, end=spec.end.value, limit=spec.limit.value)
+    if command == "list-loki-label-values":
+        return list_loki_label_values(
+            config,
+            spec.label.value,
+            datasource=spec.datasource.value,
+            query=spec.query.value,
+            start=spec.start.value,
+            end=spec.end.value,
+            limit=spec.limit.value,
+        )
+    if command == "query-loki-stats":
+        return query_loki_stats(config, spec.query.value, datasource=spec.datasource.value, start=spec.start.value, end=spec.end.value)
+    if command == "query-loki-patterns":
+        return query_loki_patterns(config, spec.query.value, datasource=spec.datasource.value, start=spec.start.value, end=spec.end.value, limit=spec.limit.value)
+
+    # ── alerting ──
+    if command == "list-alert-rules":
+        return list_alert_rules(
+            config,
+            state=spec.state.value,
+            search=spec.search.value,
+            folder=spec.folder.value,
+            datasource=spec.datasource.value,
+            include=_list(spec.include),
+            limit=spec.limit.value,
+        )
+    if command == "get-alert-rule":
+        return get_alert_rule(config, spec.uid.value, raw=spec.raw.value)
+    if command == "list-contact-points":
+        return list_contact_points(config, name=spec.name.value, include_settings=spec.include_settings.value, limit=spec.limit.value)
+    if command == "list-silences":
+        return list_silences(config, state=spec.state.value, limit=spec.limit.value)
+
+    # ── annotations ──
+    if command == "get-annotations":
+        return get_annotations(
+            config,
+            start=spec.start.value,
+            end=spec.end.value,
+            dashboard_uid=spec.dashboard_uid.value,
+            panel_id=spec.panel.value,
+            tags=_list(spec.tag),
+            match_any=spec.match_any.value,
+            type=spec.type.value,
+            limit=spec.limit.value,
+        )
+    if command == "get-annotation-tags":
+        return get_annotation_tags(config, tag=spec.tag.value, limit=spec.limit.value)
+    if command == "create-annotation":
+        return create_annotation(
+            config,
+            spec.text.value,
+            tags=_list(spec.tag),
+            dashboard_uid=spec.dashboard_uid.value,
+            panel_id=spec.panel.value,
+            at=spec.time.value,
+            end=spec.end.value,
+        )
+
+    # ── escape hatch ──
+    if command == "api-get":
+        return api_get(config, spec.path.value, params=_list(spec.param))
+
+    # require-command = true makes a bare invocation unreachable.
+    raise SystemExit("no command — see `grafana --help`")  # pragma: no cover
+
+
+def _wants_raw(spec: rs.RunSpec) -> bool:
+    return "raw" in spec and bool(spec.raw.value)
+
+
+def _terminal() -> bool:
+    # runspec's logging replaces sys.stdout with a tee whose isatty() is always
+    # False, so ask the real stdout.
+    stream = sys.__stdout__
+    return bool(stream and stream.isatty())
+
+
+def main() -> None:
+    spec = rs.parse("grafana")
+    try:
+        config = config_from_env(env=spec.env.value, url=spec.url.value, token=spec.grafana_token.value, org_id=spec.org_id.value)
+        result = _dispatch(spec, config)
+    except (GrafanaError, ValueError) as exc:
+        _emit({"error": str(exc), "kind": type(exc).__name__})
+        sys.exit(1)
+    # A person at a terminal gets readable text; agents, pipes, the console's
+    # Forms tab and schedulers get JSON.
+    text = None
+    if not spec.runspec_agent and _terminal() and not _wants_raw(spec) and spec.runspec_command != "api-get":
+        text = human_text(result)
+    _emit(result, text=text)
+
+
+if __name__ == "__main__":
+    main()

runspec_grafana-0.1.0/runspec_grafana/render.py

@@ -0,0 +1,93 @@
+"""render.py — readable text for a person at a terminal.
+
+``grafana`` prints JSON to agents, pipes, the console's Forms tab and
+schedulers. When a person runs it in an interactive terminal the compact views
+read better as text: scalar fields as ``Label  value`` lines, the main list as
+a table (or one string per line), and Loki log lines as ``time {labels} line``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+_MAX_CELL = 60
+
+
+def _cell(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, dict):
+        text = ", ".join(f"{k}={v}" for k, v in value.items())
+    elif isinstance(value, list):
+        text = ", ".join(_cell(v) for v in value)
+    else:
+        text = str(value)
+    return text if len(text) <= _MAX_CELL else text[: _MAX_CELL - 1] + "…"
+
+
+def _table(rows: list[dict[str, Any]]) -> list[str]:
+    cols: list[str] = []
+    for row in rows:
+        for key, value in row.items():
+            # Long nested parts (queries, alerts, values) stay out of the table.
+            if key not in cols and not (isinstance(value, list) and value and isinstance(value[0], (dict, list))):
+                cols.append(key)
+    widths = {c: max(len(c), *(len(_cell(r.get(c))) for r in rows)) for c in cols}
+    lines = ["  ".join(c.upper().ljust(widths[c]) for c in cols).rstrip()]
+    lines += ["  ".join(_cell(r.get(c)).ljust(widths[c]) for c in cols).rstrip() for r in rows]
+    return lines
+
+
+def _logs(payload: dict[str, Any]) -> list[str]:
+    streams = payload.get("streams") or []
+    lines = []
+    for entry in payload.get("entries") or []:
+        labels = streams[entry["stream"]]["labels"] if entry.get("stream") is not None and entry["stream"] < len(streams) else {}
+        label_text = "{" + ", ".join(f'{k}="{v}"' for k, v in labels.items()) + "}"
+        lines.append(f"{entry.get('time', '')} {label_text} {entry.get('line', '')}")
+    return lines
+
+
+def _is_rows(value: Any) -> bool:
+    return isinstance(value, list) and bool(value) and all(isinstance(v, dict) for v in value)
+
+
+def human_text(payload: Any) -> str | None:
+    """Text for a terminal, or ``None`` to print JSON instead."""
+    if not isinstance(payload, dict):
+        return None
+    if "entries" in payload and "streams" in payload:
+        body = _logs(payload)
+        footer = f"{payload.get('line_count', len(body))} lines" + (" (more — raise --limit)" if payload.get("truncated") else "")
+        return "\n".join([*body, "", footer]) if body else "No log lines."
+
+    lists = {k: v for k, v in payload.items() if isinstance(v, list) and k not in ("tags", "orgs", "variables", "warnings", "infos")}
+    main_key = next(iter(lists), None)
+    header = {k: v for k, v in payload.items() if k not in lists and k != "truncated" and not _is_rows(v)}
+    sub_tables = {k: v for k, v in payload.items() if k not in lists and _is_rows(v)}
+
+    lines: list[str] = []
+    if header:
+        labels = {k: k.replace("_", " ").capitalize() for k in header}
+        width = max(len(label) for label in labels.values())
+        lines += [f"{labels[k]:<{width}}  {_cell(v) if not isinstance(v, str) else v}" for k, v in header.items()]
+    for key, rows in sub_tables.items():
+        lines += ["", f"{key.replace('_', ' ').capitalize()}:", *(f"  {line}" for line in _table(rows))]
+    if main_key is not None:
+        rows = lists[main_key]
+        lines.append("")
+        if not rows:
+            lines.append(f"No {main_key.replace('_', ' ')}.")
+        elif all(isinstance(r, dict) for r in rows):
+            lines += _table(rows)
+            # Nested row lists (a panel's queries, a rule's alerts) follow the table.
+            for row in rows:
+                for key, value in row.items():
+                    if _is_rows(value):
+                        name = row.get("title") or row.get("name") or row.get("id")
+                        lines += ["", f"{name} — {key.replace('_', ' ')}:", *(f"  {line}" for line in _table(value))]
+        else:
+            lines += [_cell(r) for r in rows]
+        if payload.get("truncated"):
+            lines += ["", "(more — raise --limit)"]
+    return "\n".join(lines).strip("\n")

runspec_grafana-0.1.0/runspec_grafana/runspec.toml

@@ -0,0 +1,324 @@
+#:schema https://runspec.app/runspec.schema.json
+
+# runspec-grafana — Grafana as a runspec runnable, ported from the read tools of
+# the Grafana MCP server: https://github.com/grafana/mcp-grafana
+#
+# One runnable, `grafana`, with a verb per tool. Everything is read-only and
+# `autonomous` except create-annotation, which is `confirm`. `runspec serve`
+# re-expands each verb into its own leaf MCP tool (grafana_search-dashboards,
+# grafana_query-prometheus, …), so a runspec-console agent calls them
+# individually — over SSH on any fleet host.
+#
+# The tools are PORTED onto the Grafana HTTP API, not proxied from the MCP
+# server, so no extra process is involved. PromQL and LogQL go through Grafana's
+# datasource proxy, so only the Grafana token is needed, never the datasource's.
+# Auth is env-var driven:
+#   GRAFANA_URL (default http://127.0.0.1:3000 — right when this runs on the
+#   Grafana host), GRAFANA_SERVICE_ACCOUNT_TOKEN (or GRAFANA_TOKEN) — a service
+#   account token, Viewer role covers every read — or GRAFANA_USERNAME +
+#   GRAFANA_PASSWORD (basic), GRAFANA_ORG_ID, GRAFANA_CA_BUNDLE,
+#   GRAFANA_TLS_VERIFY, GRAFANA_PROXY. Per-instance overrides use a
+#   GRAFANA_<ENV>_ prefix, selected with --env.
+#
+# Times accept Unix seconds or milliseconds, RFC 3339, now-1h, or a duration
+# back from now (5m, 1h30m).
+
+[config]
+autonomy-default = "confirm"
+
+[config.logging]
+store = "per-run"
+
+[grafana]
+description = "Search Grafana dashboards and datasources, query Prometheus and Loki through Grafana, and read alert rules, silences, contact points, and annotations"
+output = "json"
+require-command = true
+examples = [
+  {cmd = "grafana search-dashboards --query api", description = "Find dashboards with 'api' in the title"},
+  {cmd = "grafana get-dashboard --uid abc123 --include queries", description = "A dashboard's panels with the query behind each"},
+  {cmd = "grafana query-prometheus --query 'up == 0'", description = "Which targets are down, via the default Prometheus datasource"},
+  {cmd = "grafana query-loki-logs --query '{app=\"api\"} |= \"error\"' --start 30m", description = "Recent error lines from one app"},
+  {cmd = "grafana list-alert-rules --state firing --include alerts", description = "Firing alerts and the series behind them"},
+  {cmd = "grafana --env prod create-annotation --text 'deploy v2.3' --tag deploy", description = "Mark a deploy on every dashboard that shows deploy annotations"},
+]
+
+# ── global args (inherited by every verb) ──────────────────────────────────
+[grafana.args]
+env = {type = "str", short = "-e", required = false, description = "Instance label: reads GRAFANA_<ENV>_* vars first (e.g. prod, prod-eu), falling back to GRAFANA_*"}
+url = {type = "str", required = false, description = "Grafana base URL; overrides GRAFANA_URL (default http://127.0.0.1:3000)"}
+org-id = {type = "str", required = false, description = "Organization ID (X-Grafana-Org-Id); overrides GRAFANA_ORG_ID. whoami lists the orgs you can reach"}
+grafana-token = {type = "password", required = false, description = "Service account token; overrides GRAFANA_SERVICE_ACCOUNT_TOKEN. Supplied via the runspec-console credential/secret channel (RUNSPEC_GRAFANA_ARG_GRAFANA_TOKEN), never on the command line."}
+
+# ── identity / server → autonomous ─────────────────────────────────────────
+
+[grafana.commands.whoami]
+description = "Show who the credentials are: login, server-admin flag, current org, and the orgs (with roles) they can reach"
+autonomy = "autonomous"
+
+[grafana.commands.health]
+description = "Check the Grafana server: version, commit, and database status"
+autonomy = "autonomous"
+
+# ── search / dashboards → autonomous ───────────────────────────────────────
+
+[grafana.commands.search-dashboards]
+description = "Find dashboards by title text, tag, folder, or starred; returns uid, title, folder, tags, and URL for each"
+autonomy = "autonomous"
+[grafana.commands.search-dashboards.args]
+query = {type = "str", short = "-q", required = false, description = "Text to find in the dashboard title"}
+tag = {type = "str", multiple = true, required = false, description = "Only dashboards with this tag (repeat; all must match)"}
+folder-uid = {type = "str", multiple = true, required = false, description = "Only dashboards in this folder (UID from search-folders; repeat)"}
+starred = {type = "flag", default = false, description = "Only dashboards the caller starred"}
+limit = {type = "int", default = 50, description = "Most dashboards to return (0 = all)"}
+
+[grafana.commands.search-folders]
+description = "Find dashboard folders by title text"
+autonomy = "autonomous"
+[grafana.commands.search-folders.args]
+query = {type = "str", short = "-q", required = false, description = "Text to find in the folder title"}
+limit = {type = "int", default = 50, description = "Most folders to return (0 = all)"}
+
+[grafana.commands.get-dashboard]
+description = "Show a dashboard as a compact summary: folder, tags, variables, and one row per panel (title, type, datasource, query count). Add --include queries for each panel's query text, or --raw for the full JSON"
+autonomy = "autonomous"
+[grafana.commands.get-dashboard.args]
+uid = {type = "str", short = "-u", required = true, description = "Dashboard UID (from search-dashboards or the /d/<uid>/ part of its URL)"}
+include = {type = "choice", options = ["queries", "links"], multiple = true, delimiter = ",", required = false, description = "Add parts: queries (each panel's query text + datasource), links (dashboard links)"}
+panel = {type = "int", required = false, description = "Only this panel (its id from the summary)"}
+version = {type = "int", required = false, description = "A saved version number (from list-dashboard-versions) instead of the current dashboard"}
+raw = {type = "flag", default = false, description = "Return the full dashboard JSON as the API sends it (large)"}
+
+[grafana.commands.list-dashboard-versions]
+description = "List a dashboard's saved versions, newest first: version, time, author, message"
+autonomy = "autonomous"
+[grafana.commands.list-dashboard-versions.args]
+uid = {type = "str", short = "-u", required = true, description = "Dashboard UID"}
+limit = {type = "int", default = 20, description = "Most versions to return (0 = all)"}
+
+# ── datasources → autonomous ───────────────────────────────────────────────
+
+[grafana.commands.list-datasources]
+description = "List configured datasources: uid, name, type, and which is the default"
+autonomy = "autonomous"
+[grafana.commands.list-datasources.args]
+type = {type = "str", short = "-t", required = false, description = "Only this plugin type, e.g. prometheus, loki, tempo, postgres"}
+limit = {type = "int", default = 100, description = "Most datasources to return (0 = all)"}
+
+[grafana.commands.get-datasource]
+description = "Show one datasource's settings; secrets are named only, never shown"
+autonomy = "autonomous"
+[grafana.commands.get-datasource.args]
+datasource = {type = "str", short = "-d", required = true, description = "Datasource UID or name"}
+
+[grafana.commands.check-datasource]
+description = "Run datasource health checks (Grafana's Save & test) and report which fail"
+autonomy = "autonomous"
+[grafana.commands.check-datasource.args]
+datasource = {type = "str", short = "-d", multiple = true, required = false, description = "Datasource UID or name (repeat); all datasources when omitted"}
+limit = {type = "int", default = 50, description = "Most datasources to check when none are named (0 = all)"}
+
+# ── Prometheus through Grafana → autonomous ────────────────────────────────
+
+[grafana.commands.query-prometheus]
+description = "Run a PromQL query against a Prometheus datasource. Instant by default; --query-type range summarises each series (points, first, last, min, max) unless --include-values"
+autonomy = "autonomous"
+[grafana.commands.query-prometheus.args]
+query = {type = "str", short = "-q", required = true, description = "The PromQL expression"}
+datasource = {type = "str", short = "-d", required = false, description = "Prometheus datasource UID or name; default: the default (or only) Prometheus datasource"}
+query-type = {type = "choice", options = ["instant", "range"], default = "instant", description = "instant: one value per series; range: values over a window"}
+time = {type = "str", required = false, description = "Instant query time (Unix seconds, RFC 3339, now-1h, or 1h). Default now"}
+start = {type = "str", required = false, description = "Range start, same forms. Default 1h before end"}
+end = {type = "str", required = false, description = "Range end. Default now"}
+step = {type = "str", required = false, description = "Range resolution step (e.g. 30s, 5m). Default gives about 250 points"}
+include-values = {type = "flag", default = false, description = "Range queries: return every sample, not just the per-series summary"}
+limit = {type = "int", default = 50, description = "Most series to return (0 = all)"}
+
+[grafana.commands.query-prometheus-histogram]
+description = "Compute a percentile (p50, p95, p99 …) from a histogram metric with histogram_quantile; returns the PromQL it ran"
+autonomy = "autonomous"
+[grafana.commands.query-prometheus-histogram.args]
+metric = {type = "str", short = "-m", required = true, description = "Histogram base name, e.g. http_request_duration_seconds (_bucket is added)"}
+percentile = {type = "float", default = 95.0, range = [0.1, 99.99], description = "Percentile, e.g. 50, 95, 99.9"}
+selector = {type = "str", required = false, description = "Label matchers, e.g. job=\"api\",route=\"/login\" (braces optional)"}
+by = {type = "str", multiple = true, required = false, description = "Keep series apart by this label (repeat), e.g. route"}
+rate-interval = {type = "str", default = "5m", description = "rate() window"}
+datasource = {type = "str", short = "-d", required = false, description = "Prometheus datasource UID or name; default: the default Prometheus datasource"}
+query-type = {type = "choice", options = ["instant", "range"], default = "instant", description = "instant: now (or --time); range: over --start..--end"}
+time = {type = "str", required = false, description = "Instant query time. Default now"}
+start = {type = "str", required = false, description = "Range start. Default 1h before end"}
+end = {type = "str", required = false, description = "Range end. Default now"}
+step = {type = "str", required = false, description = "Range resolution step"}
+include-values = {type = "flag", default = false, description = "Range queries: return every sample"}
+limit = {type = "int", default = 50, description = "Most series to return (0 = all)"}
+
+[grafana.commands.list-prometheus-metric-names]
+description = "List metric names in a Prometheus datasource, optionally filtered by a regex"
+autonomy = "autonomous"
+[grafana.commands.list-prometheus-metric-names.args]
+regex = {type = "str", short = "-r", required = false, description = "Keep names matching this regex (searched, case-insensitive), e.g. ^http_"}
+match = {type = "str", multiple = true, required = false, description = "Only metrics on series matching this selector (repeat)"}
+datasource = {type = "str", short = "-d", required = false, description = "Prometheus datasource UID or name"}
+start = {type = "str", required = false, description = "Window start"}
+end = {type = "str", required = false, description = "Window end"}
+limit = {type = "int", default = 100, description = "Most names to return (0 = all)"}
+
+[grafana.commands.list-prometheus-label-names]
+description = "List label names in a Prometheus datasource, optionally only those on series matching a selector"
+autonomy = "autonomous"
+[grafana.commands.list-prometheus-label-names.args]
+match = {type = "str", multiple = true, required = false, description = "Series selector to filter by (repeat)"}
+datasource = {type = "str", short = "-d", required = false, description = "Prometheus datasource UID or name"}
+start = {type = "str", required = false, description = "Window start"}
+end = {type = "str", required = false, description = "Window end"}
+limit = {type = "int", default = 100, description = "Most names to return (0 = all)"}
+
+[grafana.commands.list-prometheus-label-values]
+description = "List the values of one label (e.g. job, instance) in a Prometheus datasource"
+autonomy = "autonomous"
+[grafana.commands.list-prometheus-label-values.args]
+label = {type = "str", short = "-l", required = true, description = "Label name, e.g. job"}
+match = {type = "str", multiple = true, required = false, description = "Series selector to filter by (repeat)"}
+datasource = {type = "str", short = "-d", required = false, description = "Prometheus datasource UID or name"}
+start = {type = "str", required = false, description = "Window start"}
+end = {type = "str", required = false, description = "Window end"}
+limit = {type = "int", default = 100, description = "Most values to return (0 = all)"}
+
+[grafana.commands.list-prometheus-metric-metadata]
+description = "Show type, help text, and unit for metrics in a Prometheus datasource"
+autonomy = "autonomous"
+[grafana.commands.list-prometheus-metric-metadata.args]
+metric = {type = "str", short = "-m", required = false, description = "Metric name; all metrics when omitted"}
+datasource = {type = "str", short = "-d", required = false, description = "Prometheus datasource UID or name"}
+limit = {type = "int", default = 50, description = "Most metrics to return (0 = all)"}
+
+# ── Loki through Grafana → autonomous ──────────────────────────────────────
+
+[grafana.commands.query-loki-logs]
+description = "Run a LogQL query against a Loki datasource. Log queries return lines newest first (labels listed once per stream); metric queries return per-series summaries"
+autonomy = "autonomous"
+[grafana.commands.query-loki-logs.args]
+query = {type = "str", short = "-q", required = true, description = "LogQL, e.g. {app=\"api\"} |= \"error\""}
+datasource = {type = "str", short = "-d", required = false, description = "Loki datasource UID or name; default: the default (or only) Loki datasource"}
+start = {type = "str", required = false, description = "Window start (Unix seconds, RFC 3339, now-1h, or 1h). Default 1h before end"}
+end = {type = "str", required = false, description = "Window end. Default now"}
+direction = {type = "choice", options = ["backward", "forward"], default = "backward", description = "backward: newest first; forward: oldest first"}
+max-line-chars = {type = "int", default = 500, description = "Cut each log line to this many characters (0 = whole line)"}
+include-values = {type = "flag", default = false, description = "Metric queries: return every sample, not just the summary"}
+limit = {type = "int", default = 50, description = "Most log lines (or series) to return (0 = Loki's maximum)"}
+
+[grafana.commands.list-loki-label-names]
+description = "List log label names in a Loki datasource"
+autonomy = "autonomous"
+[grafana.commands.list-loki-label-names.args]
+query = {type = "str", short = "-q", required = false, description = "Only labels on streams matching this selector, e.g. {namespace=\"prod\"}"}
+datasource = {type = "str", short = "-d", required = false, description = "Loki datasource UID or name"}
+start = {type = "str", required = false, description = "Window start. Default 1h ago"}
+end = {type = "str", required = false, description = "Window end. Default now"}
+limit = {type = "int", default = 100, description = "Most names to return (0 = all)"}
+
+[grafana.commands.list-loki-label-values]
+description = "List the values of one log label (e.g. app, namespace) in a Loki datasource"
+autonomy = "autonomous"
+[grafana.commands.list-loki-label-values.args]
+label = {type = "str", short = "-l", required = true, description = "Label name, e.g. app"}
+query = {type = "str", short = "-q", required = false, description = "Only values on streams matching this selector"}
+datasource = {type = "str", short = "-d", required = false, description = "Loki datasource UID or name"}
+start = {type = "str", required = false, description = "Window start. Default 1h ago"}
+end = {type = "str", required = false, description = "Window end. Default now"}
+limit = {type = "int", default = 100, description = "Most values to return (0 = all)"}
+
+[grafana.commands.query-loki-stats]
+description = "Show how much a stream selector covers (streams, chunks, entries, bytes) — check before a broad log query"
+autonomy = "autonomous"
+[grafana.commands.query-loki-stats.args]
+query = {type = "str", short = "-q", required = true, description = "Stream selector, e.g. {app=\"api\"}"}
+datasource = {type = "str", short = "-d", required = false, description = "Loki datasource UID or name"}
+start = {type = "str", required = false, description = "Window start. Default 1h ago"}
+end = {type = "str", required = false, description = "Window end. Default now"}
+
+[grafana.commands.query-loki-patterns]
+description = "Show the log patterns Loki detected for a stream selector, most frequent first (needs Loki's pattern ingester)"
+autonomy = "autonomous"
+[grafana.commands.query-loki-patterns.args]
+query = {type = "str", short = "-q", required = true, description = "Stream selector, e.g. {app=\"api\"}"}
+datasource = {type = "str", short = "-d", required = false, description = "Loki datasource UID or name"}
+start = {type = "str", required = false, description = "Window start. Default 1h ago"}
+end = {type = "str", required = false, description = "Window end. Default now"}
+limit = {type = "int", default = 20, description = "Most patterns to return (0 = all)"}
+
+# ── alerting → autonomous ──────────────────────────────────────────────────
+
+[grafana.commands.list-alert-rules]
+description = "List alert rules and their state (firing first), with counts by state. Add --include alerts for the firing series"
+autonomy = "autonomous"
+[grafana.commands.list-alert-rules.args]
+state = {type = "choice", options = ["firing", "pending", "inactive", "error", "nodata"], required = false, description = "Only rules in this state (or health)"}
+search = {type = "str", short = "-s", required = false, description = "Only rules whose name contains this text"}
+folder = {type = "str", required = false, description = "Only rules in this folder (title)"}
+datasource = {type = "str", short = "-d", required = false, description = "Read a Prometheus/Loki/Mimir datasource's own rules instead of Grafana-managed rules"}
+include = {type = "choice", options = ["alerts", "query", "annotations"], multiple = true, delimiter = ",", required = false, description = "Add parts: alerts (up to 10 active alerts per rule), query, annotations"}
+limit = {type = "int", default = 100, description = "Most rules to return (0 = all)"}
+
+[grafana.commands.get-alert-rule]
+description = "Show a Grafana-managed alert rule's definition: condition, queries, labels, annotations, pending period"
+autonomy = "autonomous"
+[grafana.commands.get-alert-rule.args]
+uid = {type = "str", short = "-u", required = true, description = "Alert rule UID (from list-alert-rules)"}
+raw = {type = "flag", default = false, description = "Return the rule as the provisioning API sends it"}
+
+[grafana.commands.list-contact-points]
+description = "List notification contact points: uid, name, and type"
+autonomy = "autonomous"
+[grafana.commands.list-contact-points.args]
+name = {type = "str", short = "-n", required = false, description = "Only the contact point with this name"}
+include-settings = {type = "flag", default = false, description = "Add each contact point's settings (Grafana redacts secrets)"}
+limit = {type = "int", default = 100, description = "Most contact points to return (0 = all)"}
+
+[grafana.commands.list-silences]
+description = "List silences in Grafana's Alertmanager, with their matchers and end times"
+autonomy = "autonomous"
+[grafana.commands.list-silences.args]
+state = {type = "choice", options = ["active", "pending", "expired", "any"], default = "active", description = "Which silences to show"}
+limit = {type = "int", default = 100, description = "Most silences to return (0 = all)"}
+
+# ── annotations ────────────────────────────────────────────────────────────
+
+[grafana.commands.get-annotations]
+description = "List annotations (deploys, incidents, alert state changes) in a time window, newest first"
+autonomy = "autonomous"
+[grafana.commands.get-annotations.args]
+start = {type = "str", required = false, description = "Window start (Unix seconds or ms, RFC 3339, now-1h, or 1h). Default 24h before end"}
+end = {type = "str", required = false, description = "Window end. Default now"}
+dashboard-uid = {type = "str", required = false, description = "Only annotations on this dashboard"}
+panel = {type = "int", required = false, description = "Only annotations on this panel id"}
+tag = {type = "str", multiple = true, required = false, description = "Only annotations with this tag (repeat; all must match unless --match-any)"}
+match-any = {type = "flag", default = false, description = "Match annotations with any of the tags"}
+type = {type = "choice", options = ["annotation", "alert"], required = false, description = "annotation: made by people or tools; alert: alert state changes"}
+limit = {type = "int", default = 100, description = "Most annotations to return (0 = all)"}
+
+[grafana.commands.get-annotation-tags]
+description = "List annotation tags in use, with a count for each"
+autonomy = "autonomous"
+[grafana.commands.get-annotation-tags.args]
+tag = {type = "str", required = false, description = "Only tags starting with this text"}
+limit = {type = "int", default = 100, description = "Most tags to return"}
+
+[grafana.commands.create-annotation]
+description = "Add an annotation (e.g. a deploy marker) at a time or over a time range — on one dashboard, or organization-wide with tags"
+autonomy = "confirm"
+[grafana.commands.create-annotation.args]
+text = {type = "str", short = "-t", required = true, description = "Annotation text"}
+tag = {type = "str", multiple = true, required = false, description = "Tag (repeat), e.g. deploy"}
+dashboard-uid = {type = "str", required = false, description = "Put it on this dashboard; omit for an organization-wide annotation"}
+panel = {type = "int", required = false, description = "Put it on this panel (needs --dashboard-uid)"}
+time = {type = "str", required = false, description = "When (Unix seconds or ms, RFC 3339, now-5m, or 5m). Default now"}
+end = {type = "str", required = false, description = "End time, for a region annotation"}
+
+# ── escape hatch → autonomous (GET only) ───────────────────────────────────
+
+[grafana.commands.api-get]
+description = "GET any Grafana HTTP API path (read-only) and return its JSON as-is — for what the other verbs don't cover, e.g. /api/org, /api/teams/search"
+autonomy = "autonomous"
+[grafana.commands.api-get.args]
+path = {type = "str", short = "-p", required = true, description = "API path starting with /api/, e.g. /api/org"}
+param = {type = "str", multiple = true, required = false, description = "Query parameter as key=value (repeat)"}

runspec_grafana-0.1.0/tests/test_cli.py

@@ -0,0 +1,139 @@
+"""Wrapper logic: real parsed spec → `_dispatch` → core helper, with the core's
+httpx routed through a MockTransport (no real network), plus main()'s output paths."""
+
+import json
+import os
+from pathlib import Path
+
+import httpx
+import pytest
+from runspec.testing import ParseHarness, no_run_as_check
+from runspec_grafana_core import GrafanaConfig
+from runspec_grafana_core import client as client_mod
+
+from runspec_grafana import cli
+
+SPEC = Path(__file__).parent.parent / "runspec_grafana" / "runspec.toml"
+CFG = GrafanaConfig(url="https://graf")
+_REAL_CLIENT = httpx.Client
+PROM = {"uid": "prom1", "name": "Prometheus", "type": "prometheus", "isDefault": True}
+
+
+@pytest.fixture(autouse=True)
+def _clean_env(monkeypatch):
+    for var in list(os.environ):
+        if var.startswith("GRAFANA_"):
+            monkeypatch.delenv(var, raising=False)
+    monkeypatch.setenv("RUNSPEC_AUDIT", "off")
+
+
+def _route(monkeypatch, routes: dict) -> list[httpx.Request]:
+    seen: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        answer = routes.get(request.url.path)
+        if answer is None:
+            return httpx.Response(404, json={"message": "Not found"})
+        return answer if isinstance(answer, httpx.Response) else httpx.Response(200, json=answer)
+
+    def fake_client(**kwargs):
+        kwargs.pop("proxy", None)
+        kwargs.pop("verify", None)
+        return _REAL_CLIENT(transport=httpx.MockTransport(handler), **kwargs)
+
+    monkeypatch.setattr(client_mod.httpx, "Client", fake_client)
+    return seen
+
+
+def _run(argv: list[str], config: GrafanaConfig = CFG):
+    h = ParseHarness(script_name="grafana", config_path=SPEC)
+    spec = h.expect_ok(argv)
+    try:
+        return cli._dispatch(spec, config)
+    finally:
+        h.close()
+
+
+def test_dispatch_search_dashboards(monkeypatch) -> None:
+    seen = _route(monkeypatch, {"/api/search": [{"uid": "a", "title": "API", "url": "/d/a"}]})
+    out = _run(["search-dashboards", "--query", "api", "--tag", "prod", "--limit", "5"])
+    assert ("query", "api") in seen[0].url.params.multi_items() and ("tag", "prod") in seen[0].url.params.multi_items()
+    assert out["dashboards"] == [{"uid": "a", "title": "API", "url": "https://graf/d/a"}]
+
+
+def test_dispatch_get_dashboard_with_queries(monkeypatch) -> None:
+    dash = {"dashboard": {"uid": "a", "title": "API", "panels": [{"id": 1, "title": "Rate", "type": "timeseries", "targets": [{"refId": "A", "expr": "up"}]}]}, "meta": {}}
+    _route(monkeypatch, {"/api/dashboards/uid/a": dash})
+    out = _run(["get-dashboard", "--uid", "a", "--include", "queries"])
+    assert out["panels"][0]["queries"] == [{"ref_id": "A", "query": "up"}]
+
+
+def test_dispatch_query_prometheus_range(monkeypatch) -> None:
+    seen = _route(
+        monkeypatch,
+        {
+            "/api/datasources": [PROM],
+            "/api/datasources/proxy/uid/prom1/api/v1/query_range": {"status": "success", "data": {"resultType": "matrix", "result": []}},
+        },
+    )
+    out = _run(["query-prometheus", "--query", "up", "--query-type", "range", "--start", "0", "--end", "3600", "--step", "1m"])
+    assert dict(seen[-1].url.params.multi_items())["step"] == "60.0"
+    assert out["result_type"] == "matrix" and out["datasource"]["uid"] == "prom1"
+
+
+def test_dispatch_histogram(monkeypatch) -> None:
+    _route(monkeypatch, {"/api/datasources": [PROM], "/api/datasources/proxy/uid/prom1/api/v1/query": {"status": "success", "data": {"resultType": "vector", "result": []}}})
+    out = _run(["query-prometheus-histogram", "--metric", "lat", "--percentile", "99", "--by", "route"])
+    assert out["query"] == "histogram_quantile(0.99, sum by (le, route) (rate(lat_bucket[5m])))"
+
+
+def test_dispatch_list_datasources_type(monkeypatch) -> None:
+    _route(monkeypatch, {"/api/datasources": [PROM, {"uid": "l", "name": "Loki", "type": "loki"}]})
+    assert _run(["list-datasources", "--type", "loki"])["datasources"] == [{"uid": "l", "name": "Loki", "type": "loki"}]
+
+
+def test_dispatch_create_annotation(monkeypatch) -> None:
+    seen = _route(monkeypatch, {"/api/annotations": {"id": 9, "message": "Annotation added"}})
+    out = _run(["create-annotation", "--text", "deploy", "--tag", "deploy", "--time", "60"])
+    assert seen[0].method == "POST" and json.loads(seen[0].content) == {"text": "deploy", "tags": ["deploy"], "time": 60000}
+    assert out["id"] == 9
+
+
+def test_dispatch_api_get(monkeypatch) -> None:
+    seen = _route(monkeypatch, {"/api/org": {"name": "Main"}})
+    assert _run(["api-get", "--path", "/api/org", "--param", "x=1"]) == {"name": "Main"}
+    assert seen[0].method == "GET"
+
+
+def _main(monkeypatch, argv: list[str], *, tty: bool = False) -> int:
+    monkeypatch.setattr("sys.argv", ["grafana", *argv])
+    monkeypatch.setattr(cli, "_terminal", lambda: tty)
+    code = 0
+    with no_run_as_check():
+        try:
+            cli.main()
+        except SystemExit as exc:
+            code = int(exc.code or 0)
+    return code
+
+
+def test_main_reports_errors_as_json(monkeypatch, capsys) -> None:
+    _route(monkeypatch, {"/api/user": httpx.Response(401, json={"message": "invalid API key"})})
+    code = _main(monkeypatch, ["--url", "https://graf", "whoami"])
+    payload = json.loads(capsys.readouterr().out.strip().splitlines()[-1])
+    assert code == 1 and payload["kind"] == "GrafanaError" and "invalid API key" in payload["error"]
+
+
+def test_main_prints_compact_json_when_piped(monkeypatch, capsys) -> None:
+    _route(monkeypatch, {"/api/datasources": [PROM]})
+    _main(monkeypatch, ["--url", "https://graf", "list-datasources"])
+    out = capsys.readouterr().out.strip().splitlines()[-1]
+    assert json.loads(out)["datasources"][0]["uid"] == "prom1" and "\n" not in out
+
+
+def test_main_prints_text_at_a_terminal(monkeypatch, capsys) -> None:
+    _route(monkeypatch, {"/api/datasources": [PROM]})
+    _main(monkeypatch, ["--url", "https://graf", "list-datasources"], tty=True)
+    out = capsys.readouterr().out
+    assert "UID" in out and "prom1" in out and "{" not in out

runspec_grafana-0.1.0/tests/test_render.py

@@ -0,0 +1,35 @@
+"""Terminal text rendering — pure, no runspec."""
+
+from runspec_grafana.render import human_text
+
+
+def test_rows_become_a_table() -> None:
+    text = human_text({"count": 1, "truncated": True, "dashboards": [{"uid": "a", "title": "API", "tags": ["prod", "eu"]}]})
+    lines = text.splitlines()
+    assert lines[0].startswith("Count") and "UID" in lines[2] and "TAGS" in lines[2]
+    assert "prod, eu" in lines[3] and lines[-1] == "(more — raise --limit)"
+
+
+def test_string_lists_one_per_line() -> None:
+    text = human_text({"datasource": {"uid": "p", "name": "Prom"}, "count": 2, "truncated": False, "values": ["api", "node"]})
+    assert text.splitlines()[-2:] == ["api", "node"]
+
+
+def test_empty_list_says_so() -> None:
+    assert human_text({"count": 0, "truncated": False, "silences": []}).endswith("No silences.")
+
+
+def test_log_lines() -> None:
+    payload = {"line_count": 1, "truncated": False, "streams": [{"labels": {"app": "api"}, "lines": 1}], "entries": [{"time": "T", "stream": 0, "line": "boom"}]}
+    assert human_text(payload).splitlines()[0] == 'T {app="api"} boom'
+
+
+def test_nested_row_lists_follow_the_table() -> None:
+    text = human_text({"panel_count": 1, "panels": [{"id": 1, "title": "Rate", "queries": [{"ref_id": "A", "query": "up"}]}]})
+    table, _, details = text.partition("Rate — queries:")
+    assert "QUERIES" not in table and "Rate" in table
+    assert "REF_ID" in details and "up" in details
+
+
+def test_non_dict_falls_back_to_json() -> None:
+    assert human_text([1, 2]) is None

runspec_grafana-0.1.0/tests/test_spec.py

@@ -0,0 +1,79 @@
+"""Wiring / parsing tests for the `grafana` runnable — no mocks, real spec."""
+
+import sys
+from pathlib import Path
+
+from runspec.testing import ParseHarness
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+SPEC = Path(__file__).parent.parent / "runspec_grafana" / "runspec.toml"
+
+
+def _harness() -> ParseHarness:
+    return ParseHarness(script_name="grafana", config_path=SPEC)
+
+
+def test_smoke_all_verbs() -> None:
+    h = _harness()
+    # --help exits 0, require-command is enforced, omitting required args exits 1,
+    # and a fully-populated invocation parses — for every verb.
+    h.smoke(
+        values={
+            "query": "up",
+            "uid": "abc",
+            "datasource": "prom1",
+            "label": "job",
+            "metric": "http_request_duration_seconds",
+            "text": "deploy",
+            "path": "/api/org",
+        }
+    )
+    h.close()
+
+
+def test_autonomy_tiers() -> None:
+    commands = tomllib.loads(SPEC.read_text())["grafana"]["commands"]
+    tiers = {name: body["autonomy"] for name, body in commands.items()}
+    assert {n for n, t in tiers.items() if t != "autonomous"} == {"create-annotation"}
+    assert tiers["create-annotation"] == "confirm"
+
+
+def test_include_is_a_comma_list() -> None:
+    h = _harness()
+    spec = h.expect_ok(["get-dashboard", "--uid", "abc", "--include", "queries,links"])
+    assert list(spec.include.value) == ["queries", "links"]
+    h.expect_exit(["get-dashboard", "--uid", "abc", "--include", "everything"], contains="include")
+    h.close()
+
+
+def test_query_prometheus_defaults() -> None:
+    h = _harness()
+    spec = h.expect_ok(["query-prometheus", "--query", "up"])
+    assert spec.query_type.value == "instant" and spec.limit.value == 50 and spec.datasource.value is None
+    h.expect_exit(["query-prometheus", "--query", "up", "--query-type", "sideways"])
+    h.close()
+
+
+def test_globals_and_repeatables() -> None:
+    h = _harness()
+    spec = h.expect_ok(["--env", "prod-eu", "--org-id", "2", "search-dashboards", "--tag", "prod", "--tag", "api"])
+    assert spec.env.value == "prod-eu" and spec.org_id.value == "2"
+    assert list(spec.tag.value) == ["prod", "api"]
+    h.close()
+
+
+def test_token_refused_on_command_line() -> None:
+    h = _harness()
+    h.expect_exit(["--grafana-token", "glsa_secret", "whoami"], contains="grafana-token")
+    h.close()
+
+
+def test_histogram_percentile_range() -> None:
+    h = _harness()
+    assert h.expect_ok(["query-prometheus-histogram", "--metric", "lat"]).percentile.value == 95.0
+    h.expect_exit(["query-prometheus-histogram", "--metric", "lat", "--percentile", "150"], contains="percentile")
+    h.close()