pcli-agent 0.1.0__py3-none-any.whl

pcli/tools/toolbox/plugins/__init__.py

@@ -0,0 +1,6 @@
+from pcli.tools.toolbox.plugins.httpd import HttpdPlugin
+from pcli.tools.toolbox.plugins.kafka import KafkaPlugin
+from pcli.tools.toolbox.plugins.kubectl import KubectlPlugin
+from pcli.tools.toolbox.plugins.sge import SgePlugin
+
+ALL_PLUGINS = [KubectlPlugin(), SgePlugin(), KafkaPlugin(), HttpdPlugin()]

pcli/tools/toolbox/plugins/httpd.py

@@ -0,0 +1,99 @@
+"""Curated plugin for Apache httpd, via apachectl/apache2ctl."""
+
+from __future__ import annotations
+
+import re
+
+from pcli.tools.toolbox.plugin_base import CommandSpec, DetectionResult, ToolboxPlugin
+
+_VERSION_RE = re.compile(r"Apache/(\d+)\.(\d+)\.(\d+)")
+
+
+def _configtest_args(_args: dict) -> list[str]:
+    return ["-t"]
+
+
+def _dump_vhosts_args(_args: dict) -> list[str]:
+    return ["-S"]
+
+
+def _dump_modules_args(_args: dict) -> list[str]:
+    return ["-M"]
+
+
+def _graceful_args(_args: dict) -> list[str]:
+    return ["-k", "graceful"]
+
+
+def _restart_args(_args: dict) -> list[str]:
+    return ["-k", "restart"]
+
+
+def _stop_args(_args: dict) -> list[str]:
+    return ["-k", "stop"]
+
+
+class HttpdPlugin(ToolboxPlugin):
+    software_name = "httpd"
+    binary_names = ("apachectl", "apache2ctl", "httpd", "apache2")
+    version_args = ("-v",)
+
+    def parse_version(self, version_output: str) -> tuple[int, ...] | None:
+        match = _VERSION_RE.search(version_output)
+        if not match:
+            return None
+        return tuple(int(g) for g in match.groups())
+
+    def build_tools(self, detection: DetectionResult) -> list[CommandSpec]:
+        binary = detection.binary_path
+        return [
+            CommandSpec(
+                name="configtest",
+                description="Check the Apache httpd configuration for syntax errors.",
+                parameters={"type": "object", "properties": {}},
+                build_args=_configtest_args,
+                binary_path=binary,
+                risk="read",
+            ),
+            CommandSpec(
+                name="dump_vhosts",
+                description="Show the parsed virtual host configuration.",
+                parameters={"type": "object", "properties": {}},
+                build_args=_dump_vhosts_args,
+                binary_path=binary,
+                risk="read",
+            ),
+            CommandSpec(
+                name="dump_modules",
+                description="List loaded Apache modules.",
+                parameters={"type": "object", "properties": {}},
+                build_args=_dump_modules_args,
+                binary_path=binary,
+                risk="read",
+            ),
+            CommandSpec(
+                name="graceful_restart",
+                description="Gracefully restart httpd (reload config without dropping "
+                "existing connections).",
+                parameters={"type": "object", "properties": {}},
+                build_args=_graceful_args,
+                binary_path=binary,
+                risk="mutate",
+            ),
+            CommandSpec(
+                name="restart",
+                description="Restart httpd.",
+                parameters={"type": "object", "properties": {}},
+                build_args=_restart_args,
+                binary_path=binary,
+                risk="mutate",
+            ),
+            CommandSpec(
+                name="stop",
+                description="Stop httpd.",
+                parameters={"type": "object", "properties": {}},
+                build_args=_stop_args,
+                binary_path=binary,
+                risk="destructive",
+            ),
+        ]

pcli/tools/toolbox/plugins/kafka.py

@@ -0,0 +1,162 @@
+"""Curated plugin for Apache Kafka's admin CLIs (kafka-topics,
+kafka-consumer-groups). Like SGE, this is a suite of separate scripts, so
+sibling binaries are resolved independently in build_tools()."""
+
+from __future__ import annotations
+
+import re
+import shutil
+
+from pcli.tools.toolbox.plugin_base import CommandSpec, DetectionResult, ToolboxPlugin
+
+_VERSION_RE = re.compile(r"(\d+)\.(\d+)\.(\d+)")
+
+_BOOTSTRAP_PARAM = {
+    "bootstrap_server": {
+        "type": "string",
+        "description": "Kafka bootstrap server, e.g. 'localhost:9092'.",
+    }
+}
+
+
+def _which_any(*names: str) -> str | None:
+    for name in names:
+        if path := shutil.which(name):
+            return path
+    return None
+
+
+def _list_topics_args(args: dict) -> list[str]:
+    return ["--bootstrap-server", args["bootstrap_server"], "--list"]
+
+
+def _describe_topic_args(args: dict) -> list[str]:
+    return ["--bootstrap-server", args["bootstrap_server"], "--describe", "--topic", args["topic"]]
+
+
+def _create_topic_args(args: dict) -> list[str]:
+    return [
+        "--bootstrap-server",
+        args["bootstrap_server"],
+        "--create",
+        "--topic",
+        args["topic"],
+        "--partitions",
+        str(args.get("partitions", 1)),
+        "--replication-factor",
+        str(args.get("replication_factor", 1)),
+    ]
+
+
+def _delete_topic_args(args: dict) -> list[str]:
+    return ["--bootstrap-server", args["bootstrap_server"], "--delete", "--topic", args["topic"]]
+
+
+def _list_consumer_groups_args(args: dict) -> list[str]:
+    return ["--bootstrap-server", args["bootstrap_server"], "--list"]
+
+
+def _describe_consumer_group_args(args: dict) -> list[str]:
+    return ["--bootstrap-server", args["bootstrap_server"], "--describe", "--group", args["group"]]
+
+
+class KafkaPlugin(ToolboxPlugin):
+    software_name = "kafka"
+    binary_names = ("kafka-topics.sh", "kafka-topics", "kafka-topics.bat")
+    version_args = ("--version",)
+
+    def parse_version(self, version_output: str) -> tuple[int, ...] | None:
+        match = _VERSION_RE.search(version_output)
+        if not match:
+            return None
+        return tuple(int(g) for g in match.groups())
+
+    def build_tools(self, detection: DetectionResult) -> list[CommandSpec]:
+        topics_bin = detection.binary_path
+        specs = [
+            CommandSpec(
+                name="list_topics",
+                description="List all Kafka topics.",
+                parameters={
+                    "type": "object",
+                    "properties": _BOOTSTRAP_PARAM,
+                    "required": ["bootstrap_server"],
+                },
+                build_args=_list_topics_args,
+                binary_path=topics_bin,
+                risk="read",
+            ),
+            CommandSpec(
+                name="describe_topic",
+                description="Show partition/replica detail for a specific topic.",
+                parameters={
+                    "type": "object",
+                    "properties": {**_BOOTSTRAP_PARAM, "topic": {"type": "string"}},
+                    "required": ["bootstrap_server", "topic"],
+                },
+                build_args=_describe_topic_args,
+                binary_path=topics_bin,
+                risk="read",
+            ),
+            CommandSpec(
+                name="create_topic",
+                description="Create a new Kafka topic.",
+                parameters={
+                    "type": "object",
+                    "properties": {
+                        **_BOOTSTRAP_PARAM,
+                        "topic": {"type": "string"},
+                        "partitions": {"type": "integer"},
+                        "replication_factor": {"type": "integer"},
+                    },
+                    "required": ["bootstrap_server", "topic"],
+                },
+                build_args=_create_topic_args,
+                binary_path=topics_bin,
+                risk="mutate",
+            ),
+            CommandSpec(
+                name="delete_topic",
+                description="Delete a Kafka topic.",
+                parameters={
+                    "type": "object",
+                    "properties": {**_BOOTSTRAP_PARAM, "topic": {"type": "string"}},
+                    "required": ["bootstrap_server", "topic"],
+                },
+                build_args=_delete_topic_args,
+                binary_path=topics_bin,
+                risk="destructive",
+            ),
+        ]
+
+        if consumer_groups_bin := _which_any(
+            "kafka-consumer-groups.sh", "kafka-consumer-groups", "kafka-consumer-groups.bat"
+        ):
+            specs += [
+                CommandSpec(
+                    name="list_consumer_groups",
+                    description="List Kafka consumer groups.",
+                    parameters={
+                        "type": "object",
+                        "properties": _BOOTSTRAP_PARAM,
+                        "required": ["bootstrap_server"],
+                    },
+                    build_args=_list_consumer_groups_args,
+                    binary_path=consumer_groups_bin,
+                    risk="read",
+                ),
+                CommandSpec(
+                    name="describe_consumer_group",
+                    description="Show lag/offset detail for a specific consumer group.",
+                    parameters={
+                        "type": "object",
+                        "properties": {**_BOOTSTRAP_PARAM, "group": {"type": "string"}},
+                        "required": ["bootstrap_server", "group"],
+                    },
+                    build_args=_describe_consumer_group_args,
+                    binary_path=consumer_groups_bin,
+                    risk="read",
+                ),
+            ]
+
+        return specs

pcli/tools/toolbox/plugins/kubectl.py

@@ -0,0 +1,211 @@
+"""Curated plugin for kubectl (Kubernetes CLI). One binary, many subcommands."""
+
+from __future__ import annotations
+
+import re
+
+from pcli.tools.toolbox.plugin_base import CommandSpec, DetectionResult, ToolboxPlugin
+
+_VERSION_RE = re.compile(r"[Vv]ersion:\s*v?(\d+)\.(\d+)\.(\d+)")
+
+
+def _get_args(args: dict) -> list[str]:
+    argv = ["get", args["resource"]]
+    if args.get("name"):
+        argv.append(args["name"])
+    if args.get("all_namespaces"):
+        argv.append("--all-namespaces")
+    elif args.get("namespace"):
+        argv += ["--namespace", args["namespace"]]
+    if args.get("output"):
+        argv += ["-o", args["output"]]
+    return argv
+
+
+def _describe_args(args: dict) -> list[str]:
+    argv = ["describe", args["resource"], args["name"]]
+    if args.get("namespace"):
+        argv += ["--namespace", args["namespace"]]
+    return argv
+
+
+def _logs_args(args: dict) -> list[str]:
+    argv = ["logs", args["pod_name"]]
+    if args.get("namespace"):
+        argv += ["--namespace", args["namespace"]]
+    if args.get("container"):
+        argv += ["-c", args["container"]]
+    if args.get("tail"):
+        argv += ["--tail", str(args["tail"])]
+    if args.get("previous"):
+        argv.append("--previous")
+    return argv
+
+
+def _get_contexts_args(_args: dict) -> list[str]:
+    return ["config", "get-contexts"]
+
+
+def _apply_args(args: dict) -> list[str]:
+    argv = ["apply", "-f", args["file"]]
+    if args.get("namespace"):
+        argv += ["--namespace", args["namespace"]]
+    if args.get("dry_run"):
+        argv.append("--dry-run=client")
+    return argv
+
+
+def _scale_args(args: dict) -> list[str]:
+    argv = ["scale", args["resource"], args["name"], "--replicas", str(args["replicas"])]
+    if args.get("namespace"):
+        argv += ["--namespace", args["namespace"]]
+    return argv
+
+
+def _delete_args(args: dict) -> list[str]:
+    argv = ["delete", args["resource"], args["name"]]
+    if args.get("namespace"):
+        argv += ["--namespace", args["namespace"]]
+    return argv
+
+
+class KubectlPlugin(ToolboxPlugin):
+    software_name = "kubectl"
+    binary_names = ("kubectl",)
+    version_args = ("version", "--client")
+
+    def parse_version(self, version_output: str) -> tuple[int, ...] | None:
+        match = _VERSION_RE.search(version_output)
+        if not match:
+            return None
+        return tuple(int(g) for g in match.groups())
+
+    def build_tools(self, detection: DetectionResult) -> list[CommandSpec]:
+        binary = detection.binary_path
+        return [
+            CommandSpec(
+                name="get",
+                description="List Kubernetes resources of a given type (pods, deployments, "
+                "services, nodes, ...).",
+                parameters={
+                    "type": "object",
+                    "properties": {
+                        "resource": {
+                            "type": "string",
+                            "description": "Resource type, e.g. 'pods', 'deployments', 'svc', 'nodes'.",
+                        },
+                        "name": {"type": "string", "description": "Specific resource name (optional)."},
+                        "namespace": {"type": "string"},
+                        "all_namespaces": {"type": "boolean"},
+                        "output": {
+                            "type": "string",
+                            "description": "Output format, e.g. 'json', 'yaml', 'wide'.",
+                        },
+                    },
+                    "required": ["resource"],
+                },
+                build_args=_get_args,
+                binary_path=binary,
+                risk="read",
+            ),
+            CommandSpec(
+                name="describe",
+                description="Show detailed information about a specific Kubernetes resource.",
+                parameters={
+                    "type": "object",
+                    "properties": {
+                        "resource": {"type": "string"},
+                        "name": {"type": "string"},
+                        "namespace": {"type": "string"},
+                    },
+                    "required": ["resource", "name"],
+                },
+                build_args=_describe_args,
+                binary_path=binary,
+                risk="read",
+            ),
+            CommandSpec(
+                name="logs",
+                description="Fetch logs from a pod (optionally a specific container).",
+                parameters={
+                    "type": "object",
+                    "properties": {
+                        "pod_name": {"type": "string"},
+                        "namespace": {"type": "string"},
+                        "container": {"type": "string"},
+                        "tail": {
+                            "type": "integer",
+                            "description": "Number of lines from the end of the log to show.",
+                        },
+                        "previous": {
+                            "type": "boolean",
+                            "description": "Show logs from the previous terminated container instance.",
+                        },
+                    },
+                    "required": ["pod_name"],
+                },
+                build_args=_logs_args,
+                binary_path=binary,
+                risk="read",
+            ),
+            CommandSpec(
+                name="get_contexts",
+                description="List available kubeconfig contexts.",
+                parameters={"type": "object", "properties": {}},
+                build_args=_get_contexts_args,
+                binary_path=binary,
+                risk="read",
+            ),
+            CommandSpec(
+                name="apply",
+                description="Apply a Kubernetes manifest file (create/update resources).",
+                parameters={
+                    "type": "object",
+                    "properties": {
+                        "file": {"type": "string", "description": "Path to the manifest file."},
+                        "namespace": {"type": "string"},
+                        "dry_run": {
+                            "type": "boolean",
+                            "description": "Preview the change without applying it.",
+                        },
+                    },
+                    "required": ["file"],
+                },
+                build_args=_apply_args,
+                binary_path=binary,
+                risk="mutate",
+            ),
+            CommandSpec(
+                name="scale",
+                description="Scale a deployment/replicaset/statefulset to a given replica count.",
+                parameters={
+                    "type": "object",
+                    "properties": {
+                        "resource": {"type": "string", "description": "e.g. 'deployment'."},
+                        "name": {"type": "string"},
+                        "replicas": {"type": "integer"},
+                        "namespace": {"type": "string"},
+                    },
+                    "required": ["resource", "name", "replicas"],
+                },
+                build_args=_scale_args,
+                binary_path=binary,
+                risk="mutate",
+            ),
+            CommandSpec(
+                name="delete",
+                description="Delete a specific Kubernetes resource.",
+                parameters={
+                    "type": "object",
+                    "properties": {
+                        "resource": {"type": "string"},
+                        "name": {"type": "string"},
+                        "namespace": {"type": "string"},
+                    },
+                    "required": ["resource", "name"],
+                },
+                build_args=_delete_args,
+                binary_path=binary,
+                risk="destructive",
+            ),
+        ]

pcli/tools/toolbox/plugins/sge.py

@@ -0,0 +1,146 @@
+"""Curated plugin for Sun Grid Engine / Univa Grid Engine — unlike kubectl or
+httpd, this is a suite of separate binaries (qstat/qsub/qdel/qacct/qhost),
+so build_tools() resolves each sibling independently and only includes
+commands whose binary is actually present."""
+
+from __future__ import annotations
+
+import re
+import shutil
+
+from pcli.tools.toolbox.plugin_base import CommandSpec, DetectionResult, ToolboxPlugin
+
+_VERSION_RE = re.compile(r"(\d+)\.(\d+)\.(\d+)")
+
+
+def _qstat_args(args: dict) -> list[str]:
+    argv = []
+    if args.get("all_users"):
+        argv += ["-u", args.get("user") or "*"]
+    if args.get("job_id"):
+        argv += ["-j", str(args["job_id"])]
+    if args.get("full"):
+        argv.append("-f")
+    return argv
+
+
+def _qhost_args(args: dict) -> list[str]:
+    return ["-q"] if args.get("queues") else []
+
+
+def _qacct_args(args: dict) -> list[str]:
+    return ["-j", str(args["job_id"])]
+
+
+def _qsub_args(args: dict) -> list[str]:
+    argv: list[str] = []
+    if args.get("queue"):
+        argv += ["-q", args["queue"]]
+    if args.get("job_name"):
+        argv += ["-N", args["job_name"]]
+    argv.append(args["script"])
+    return argv
+
+
+def _qdel_args(args: dict) -> list[str]:
+    return [str(args["job_id"])]
+
+
+class SgePlugin(ToolboxPlugin):
+    software_name = "sge"
+    binary_names = ("qstat",)
+    version_args = ("-help",)
+
+    def parse_version(self, version_output: str) -> tuple[int, ...] | None:
+        match = _VERSION_RE.search(version_output)
+        if not match:
+            # `qstat -help` doesn't reliably print a parseable version across SGE/UGE
+            # forks; treat any output at all as "present, version unknown".
+            return (0,)
+        return tuple(int(g) for g in match.groups())
+
+    def build_tools(self, detection: DetectionResult) -> list[CommandSpec]:
+        specs: list[CommandSpec] = [
+            CommandSpec(
+                name="qstat",
+                description="Show the status of scheduled/running jobs in the grid.",
+                parameters={
+                    "type": "object",
+                    "properties": {
+                        "all_users": {"type": "boolean"},
+                        "user": {"type": "string"},
+                        "job_id": {"type": "integer"},
+                        "full": {"type": "boolean", "description": "Full job/queue detail."},
+                    },
+                },
+                build_args=_qstat_args,
+                binary_path=detection.binary_path,
+                risk="read",
+            )
+        ]
+
+        if qhost := shutil.which("qhost"):
+            specs.append(
+                CommandSpec(
+                    name="qhost",
+                    description="Show the status of execution hosts in the grid.",
+                    parameters={"type": "object", "properties": {"queues": {"type": "boolean"}}},
+                    build_args=_qhost_args,
+                    binary_path=qhost,
+                    risk="read",
+                )
+            )
+
+        if qacct := shutil.which("qacct"):
+            specs.append(
+                CommandSpec(
+                    name="qacct",
+                    description="Show accounting/history information for a completed job.",
+                    parameters={
+                        "type": "object",
+                        "properties": {"job_id": {"type": "integer"}},
+                        "required": ["job_id"],
+                    },
+                    build_args=_qacct_args,
+                    binary_path=qacct,
+                    risk="read",
+                )
+            )
+
+        if qsub := shutil.which("qsub"):
+            specs.append(
+                CommandSpec(
+                    name="qsub",
+                    description="Submit a job script to the grid scheduler.",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "script": {"type": "string", "description": "Path to the job script."},
+                            "queue": {"type": "string"},
+                            "job_name": {"type": "string"},
+                        },
+                        "required": ["script"],
+                    },
+                    build_args=_qsub_args,
+                    binary_path=qsub,
+                    risk="mutate",
+                )
+            )
+
+        if qdel := shutil.which("qdel"):
+            specs.append(
+                CommandSpec(
+                    name="qdel",
+                    description="Delete/cancel a submitted job.",
+                    parameters={
+                        "type": "object",
+                        "properties": {"job_id": {"type": "integer"}},
+                        "required": ["job_id"],
+                    },
+                    build_args=_qdel_args,
+                    binary_path=qdel,
+                    risk="destructive",
+                )
+            )
+
+        return specs

pcli/tools/toolbox/store.py

@@ -0,0 +1,65 @@
+"""Persistent cache for toolbox discovery results.
+
+Curated plugins re-detect live on every load (a `--version` probe is cheap
+and catches upgrades) — nothing curated needs to be cached. Only the
+LLM-synthesized schemas for uncurated software are cached, keyed by a hash
+of the --help corpus they were generated from, so an unchanged install
+doesn't re-trigger an LLM call on every startup.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+
+from pcli.config.paths import toolbox_dir
+
+
+def _atomic_write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(path.suffix + ".tmp")
+    tmp_path.write_text(content, encoding="utf-8")
+    os.replace(tmp_path, path)
+
+
+def registry_path() -> Path:
+    return toolbox_dir() / "registry.json"
+
+
+def read_registry() -> dict[str, dict]:
+    path = registry_path()
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def write_registry(registry: dict[str, dict]) -> None:
+    _atomic_write(registry_path(), json.dumps(registry, indent=2))
+
+
+def synthesized_schema_path(software_name: str) -> Path:
+    return toolbox_dir() / software_name / "synthesized.json"
+
+
+def read_synthesized_schema(software_name: str) -> dict | None:
+    path = synthesized_schema_path(software_name)
+    if not path.exists():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def write_synthesized_schema(
+    software_name: str, *, help_corpus_hash: str, version: str, tools: list[dict]
+) -> None:
+    _atomic_write(
+        synthesized_schema_path(software_name),
+        json.dumps(
+            {"help_corpus_hash": help_corpus_hash, "version": version, "tools": tools}, indent=2
+        ),
+    )
+
+
+def hash_corpus(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]