devopsiq 0.1.0__py3-none-any.whl

tools/git_ci.py

@@ -0,0 +1,257 @@
+"""Read-only git / CI tools (Phases 5 and 8).
+
+Seven tools for code-and-pipeline problems: repository status (git status),
+recent history (git log), working-tree diff summary (git diff), open pull
+requests and (Phase 8) GitHub Actions runs, one run's jobs, and workflow
+listing — all via the GitHub CLI (gh). Operating on the CURRENT WORKING
+DIRECTORY the agent was launched from (like terraform).
+
+Safety model:
+- Only `git status --short --branch`, `git log --oneline -n`, `git diff
+  --stat HEAD`, `gh pr list`, `gh run list`, `gh run view` and `gh workflow
+  list` exist. No git reset, checkout/switch, commit, push, pull, clean, or
+  stash; no gh pr create/merge/close, no gh workflow run, no run cancel/
+  rerun — nothing that changes state on GitHub.
+- No free-form args: neither git nor gh ever receives user-supplied text
+  beyond bounded integers, so flag/dispatch injection is impossible.
+- git and gh must be installed; gh additionally needs authentication and to
+  be inside a GitHub repository. Missing pieces surface as the exact CLI
+  error — never invented.
+"""
+
+from tools.base import Tool, ToolError, read_command_output
+from tools.registry import register
+
+_TIMEOUT_S = 10
+
+
+def _checked_count(args: dict, key: str, default: int, maximum: int, label: str) -> int:
+    try:
+        count = int(args.get(key, default))
+    except (TypeError, ValueError):
+        raise ToolError(f"{label} must be an integer between 1 and {maximum}")
+    if not 1 <= count <= maximum:
+        raise ToolError(f"{label} must be between 1 and {maximum}")
+    return count
+
+
+def _git_repo_status(args: dict) -> str:
+    return read_command_output(("git", "status", "--short", "--branch"), timeout=_TIMEOUT_S)
+
+
+def _git_log(args: dict) -> str:
+    count = _checked_count(args, "count", 20, 100, "count")
+    return read_command_output(
+        ("git", "log", "--oneline", "-n", str(count)), timeout=_TIMEOUT_S
+    )
+
+
+def _git_diff(args: dict) -> str:
+    return read_command_output(("git", "diff", "--stat", "HEAD"), timeout=_TIMEOUT_S)
+
+
+def _gh_prs(args: dict) -> str:
+    count = _checked_count(args, "limit", 10, 50, "limit")
+    return read_command_output(
+        (
+            "gh", "pr", "list", "--limit", str(count),
+            "--json", "number,title,state,headRefName,isDraft,updatedAt",
+        ),
+        timeout=_TIMEOUT_S,
+    )
+
+
+GIT_REPO_STATUS = Tool(
+    name="git_repo_status",
+    description=(
+        "Repository status of the current working directory (git status "
+        "--short --branch): current branch, ahead/behind, and modified/"
+        "staged/untracked files. Use for 'have local changes been applied', "
+        "unclean trees before a deploy. Read-only."
+    ),
+    parameters={"type": "object", "properties": {}, "additionalProperties": False},
+    executor=_git_repo_status,
+)
+
+GIT_LOG = Tool(
+    name="git_log",
+    description=(
+        "Recent commit history of the current working directory "
+        "(git log --oneline -n): short hash + subject per commit. Use to see "
+        "what changed recently or whether a fix was committed. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "count": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 100,
+                "default": 20,
+                "description": "How many commits to show (1–100).",
+            }
+        },
+        "additionalProperties": False,
+    },
+    executor=_git_log,
+)
+
+GIT_DIFF = Tool(
+    name="git_diff",
+    description=(
+        "Summary of working-tree changes vs HEAD in the current working "
+        "directory (git diff --stat HEAD): files changed plus insertions/"
+        "deletions. Use to judge the size/impact of uncommitted changes. "
+        "Read-only."
+    ),
+    parameters={"type": "object", "properties": {}, "additionalProperties": False},
+    executor=_git_diff,
+)
+
+GH_PRS = Tool(
+    name="gh_prs",
+    description=(
+        "List open pull requests of the current GitHub repository as JSON "
+        "(gh pr list): number, title, state, head branch, draft flag, updated "
+        "time. Use for 'what is waiting to merge', CI/CD pull-request state. "
+        "Requires the gh CLI installed, authenticated, and a repository with "
+        "a GitHub remote. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "limit": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 50,
+                "default": 10,
+                "description": "How many PRs to list (1–50).",
+            }
+        },
+        "additionalProperties": False,
+    },
+    executor=_gh_prs,
+)
+
+# --- Phase 8: GitHub Actions (via gh) — run listing, one run's detail,
+# workflow listing. Ids are digits-only validated, which blocks flag
+# injection; `gh workflow run` and every mutating verb stay absent. ----------
+
+
+def _checked_run_id(args: dict) -> str:
+    run_id = args.get("run_id")
+    if (
+        not isinstance(run_id, str)
+        or not run_id.isdigit()
+        or not 1 <= len(run_id) <= 20
+    ):
+        raise ToolError("run_id must be the numeric GitHub Actions run id")
+    return run_id
+
+
+def _gh_runs(args: dict) -> str:
+    limit = _checked_count(args, "limit", 10, 50, "limit")
+    return read_command_output(
+        (
+            "gh", "run", "list", "--limit", str(limit),
+            "--json", "databaseId,displayTitle,status,conclusion,"
+            "workflowName,createdAt,event,headBranch",
+        ),
+        timeout=_TIMEOUT_S,
+    )
+
+
+def _gh_run_view(args: dict) -> str:
+    run_id = _checked_run_id(args)
+    return read_command_output(
+        ("gh", "run", "view", run_id, "--json", "status,conclusion,jobs"),
+        timeout=_TIMEOUT_S,
+    )
+
+
+def _gh_workflows(args: dict) -> str:
+    limit = _checked_count(args, "limit", 20, 100, "limit")
+    return read_command_output(
+        ("gh", "workflow", "list", "--limit", str(limit),
+         "--json", "id,name,state"),
+        timeout=_TIMEOUT_S,
+    )
+
+
+GH_RUNS = Tool(
+    name="gh_runs",
+    description=(
+        "List recent GitHub Actions workflow runs as JSON (gh run list): run "
+        "id, title, workflow name, status, conclusion, branch, event, created "
+        "time. Use for 'which deploy failed', the CI record behind a broken "
+        "release. Requires gh installed, authenticated, in a GitHub repo. "
+        "Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "limit": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 50,
+                "default": 10,
+                "description": "How many runs to list (1–50).",
+            }
+        },
+        "additionalProperties": False,
+    },
+    executor=_gh_runs,
+)
+
+GH_RUN_VIEW = Tool(
+    name="gh_run_view",
+    description=(
+        "One GitHub Actions run's detail as JSON (gh run view): overall "
+        "status/conclusion plus per-job state (each job's name, status, "
+        "conclusion, steps). Use with gh_runs to find which job/step failed. "
+        "Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "run_id": {
+                "type": "string",
+                "description": "Numeric Actions run id (from gh_runs).",
+            }
+        },
+        "required": ["run_id"],
+        "additionalProperties": False,
+    },
+    executor=_gh_run_view,
+)
+
+GH_WORKFLOWS = Tool(
+    name="gh_workflows",
+    description=(
+        "List the GitHub Actions workflows of the current repository as JSON "
+        "(gh workflow list): id, name, state (active/disabled). Use to check "
+        "which pipelines exist and whether one is disabled. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "limit": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 100,
+                "default": 20,
+                "description": "How many workflows to list (1–100).",
+            }
+        },
+        "additionalProperties": False,
+    },
+    executor=_gh_workflows,
+)
+
+register(GIT_REPO_STATUS)
+register(GIT_LOG)
+register(GIT_DIFF)
+register(GH_PRS)
+register(GH_RUNS)
+register(GH_RUN_VIEW)
+register(GH_WORKFLOWS)

tools/helm.py

@@ -0,0 +1,168 @@
+"""Read-only Helm release tools (Phase 9).
+
+Three tools over the helm CLI: list releases (helm list), one release's
+status (helm status), and its revision history (helm history). All are
+reads of release metadata Helm keeps in the cluster — nothing here installs,
+upgrades, rolls back or uninstalls anything.
+
+Safety model (same shape as tools/kubernetes.py):
+- Only fixed argv templates with the list/status/history verbs exist. There
+  is no install, upgrade, rollback, uninstall, delete or template path.
+- Release and namespace names are validated against Kubernetes DNS naming
+  rules before touching helm — blocks flag injection and garbage input.
+- `--max` on history is a bounded integer (1–50).
+- helm must be installed and pointed at a cluster (its own kubeconfig
+  handling); missing/unreachable surfaces as the exact CLI error.
+"""
+
+import re
+
+from tools.base import Tool, ToolError, read_command_output
+from tools.registry import register
+
+# Helm release names follow Kubernetes naming: lowercase DNS-style.
+_NAME_RE = re.compile(r"[a-z0-9](?:[-a-z0-9.]{0,251}[a-z0-9])?")
+_TIMEOUT_S = 15
+
+
+def _check_name(value, kind: str) -> str:
+    if (
+        not isinstance(value, str)
+        or len(value) > 253
+        or not _NAME_RE.fullmatch(value)
+    ):
+        raise ToolError(
+            f"invalid Helm {kind} name {value!r}: expected lowercase "
+            "letters, digits, '-' or '.', max 253 characters"
+        )
+    return value
+
+
+def _namespace(args: dict) -> str:
+    return _check_name(args.get("namespace") or "default", "namespace")
+
+
+def _checked_max(args: dict) -> int:
+    try:
+        maximum = int(args.get("max", 10))
+    except (TypeError, ValueError):
+        raise ToolError("max must be an integer between 1 and 50")
+    if not 1 <= maximum <= 50:
+        raise ToolError("max must be between 1 and 50")
+    return maximum
+
+
+def _helm_list(args: dict) -> str:
+    if args.get("all_namespaces"):
+        argv = ("helm", "list", "--all-namespaces")
+    else:
+        argv = ("helm", "list", "-n", _namespace(args))
+    return read_command_output(argv, timeout=_TIMEOUT_S)
+
+
+def _helm_status(args: dict) -> str:
+    release = _check_name(args.get("release"), "release")
+    namespace = _namespace(args)
+    return read_command_output(
+        ("helm", "status", release, "-n", namespace),
+        timeout=_TIMEOUT_S,
+    )
+
+
+def _helm_history(args: dict) -> str:
+    release = _check_name(args.get("release"), "release")
+    namespace = _namespace(args)
+    return read_command_output(
+        ("helm", "history", release, "-n", namespace,
+         "--max", str(_checked_max(args))),
+        timeout=_TIMEOUT_S,
+    )
+
+
+HELM_LIST = Tool(
+    name="helm_list",
+    description=(
+        "List Helm releases (helm list): name, namespace, revision, "
+        "updated time, status (deployed/failed/pending-upgrade), chart "
+        "version, app version. Use for 'which releases exist and are they "
+        "healthy', and to find the release behind a broken workload. "
+        "Requires helm + a configured cluster. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "namespace": {
+                "type": "string",
+                "description": "Namespace to list (default: \"default\").",
+            },
+            "all_namespaces": {
+                "type": "boolean",
+                "description": "List across all namespaces instead of one.",
+            },
+        },
+        "additionalProperties": False,
+    },
+    executor=_helm_list,
+)
+
+HELM_STATUS = Tool(
+    name="helm_status",
+    description=(
+        "One Helm release's status (helm status): revision, state, chart, "
+        "and the release's last-deployed notes. Use to see why a release is "
+        "failed or pending and which revision is live. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "release": {
+                "type": "string",
+                "description": "Release name.",
+            },
+            "namespace": {
+                "type": "string",
+                "description": "Namespace of the release (default: \"default\").",
+            },
+        },
+        "required": ["release"],
+        "additionalProperties": False,
+    },
+    executor=_helm_status,
+)
+
+HELM_HISTORY = Tool(
+    name="helm_history",
+    description=(
+        "A Helm release's revision history (helm history --max): each "
+        "revision with its status, chart version, and updated time. Use to "
+        "correlate an incident start with an upgrade, or to find the last "
+        "good revision. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "release": {
+                "type": "string",
+                "description": "Release name.",
+            },
+            "namespace": {
+                "type": "string",
+                "description": "Namespace of the release (default: \"default\").",
+            },
+            "max": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 50,
+                "default": 10,
+                "description": "How many revisions to show (1–50).",
+            },
+        },
+        "required": ["release"],
+        "additionalProperties": False,
+    },
+    executor=_helm_history,
+)
+
+register(HELM_LIST)
+register(HELM_STATUS)
+register(HELM_HISTORY)