kctl-sentry 0.6.3__tar.gz

kctl_sentry-0.6.3/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+.env

kctl_sentry-0.6.3/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: kctl-sentry
+Version: 0.6.3
+Summary: Kodemeio Sentry CLI — error tracking management
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.8.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'

kctl_sentry-0.6.3/README.md

@@ -0,0 +1,117 @@
+# kctl-sentry
+
+Sentry error tracking CLI — error triage, release tracking, and project management for the Kodemeio platform.
+
+## Installation
+
+```bash
+# From workspace (development)
+uv tool install --editable packages/kctl-sentry
+
+# From PyPI
+uv tool install kctl-sentry
+```
+
+## Quick Start
+
+```bash
+# Initialize configuration
+kctl-sentry config init
+
+# Check connectivity
+kctl-sentry health check
+
+# List all projects
+kctl-sentry projects list
+
+# Triage open issues
+kctl-sentry issues list --project my-project
+
+# View error stats
+kctl-sentry stats errors --project my-project
+```
+
+## Command Groups
+
+| Group | Commands | Description |
+|-------|----------|-------------|
+| `config` | init, add, use, show, set, remove, profiles, current, test, migrate | Manage profiles and credentials |
+| `health` | check | Verify Sentry API connectivity |
+| `dashboard` | overview | High-level summary across all projects |
+| `issues` | list, show, resolve, ignore, bulk-resolve, assign | Error issue triage and management |
+| `projects` | list, show, dsn, create | Project listing, details, and DSN retrieval |
+| `releases` | list, show, create, associate | Release tracking and commit association |
+| `alerts` | list, show, create | Alert rule management |
+| `stats` | events, errors | Event and error volume statistics |
+| `teams` | list, show | Team membership and details |
+| `environments` | list | Environment listing per project |
+
+## Global Options
+
+All commands accept these options:
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--json` | | Output as JSON |
+| `--format` | `-f` | Output format: `pretty`, `json`, `csv`, `yaml` |
+| `--quiet` | `-q` | Suppress info messages |
+| `--no-header` | | Omit header row in table/CSV output |
+| `--profile` | `-p` | Config profile name |
+| `--auth-token` | | Auth token override (bypasses config) |
+| `--version` | `-V` | Show version and exit |
+
+## Configuration
+
+Config is stored in `~/.config/kodemeio/config.yaml` under the `sentry` key.
+
+```bash
+# Create a new profile
+kctl-sentry config init
+
+# Add a named profile
+kctl-sentry config add --profile prod
+
+# Switch active profile
+kctl-sentry config use prod
+
+# Show current config (secrets masked)
+kctl-sentry config show
+
+# Test connectivity
+kctl-sentry config test
+```
+
+### Config Keys
+
+| Key | Description |
+|-----|-------------|
+| `url` | Sentry instance URL (e.g. `https://sentry.io` or self-hosted) |
+| `auth_token` | Sentry auth token with `project:read`, `event:read` scopes |
+| `org` | Default organization slug |
+
+## Common Workflows
+
+```bash
+# Bulk resolve all resolved issues in a project
+kctl-sentry issues bulk-resolve --project my-project --status resolved
+
+# Create a release and associate commits
+kctl-sentry releases create --project my-project --version 1.2.3
+kctl-sentry releases associate --project my-project --version 1.2.3
+
+# Get DSN for SDK integration
+kctl-sentry projects dsn my-project
+
+# View event volume over the last 24h
+kctl-sentry stats events --project my-project --period 24h
+```
+
+## Development
+
+```bash
+cd packages/kctl-sentry
+uv sync --all-extras
+uv run pytest tests/ -v
+uv run mypy src/
+uv run ruff check src/
+```

kctl_sentry-0.6.3/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-sentry"
+version = "0.6.3"
+description = "Kodemeio Sentry CLI — error tracking management"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.8.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.2",
+    "httpx>=0.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-httpx>=0.35.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.0",
+]
+
+[project.scripts]
+kctl-sentry = "kctl_sentry.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[project.entry-points."kctl_sentry.plugins"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_sentry"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_sentry-0.6.3/skills/sentry-admin/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: sentry-admin
+description: >
+  Sentry error tracking administration via kctl-sentry CLI (11 groups, ~35 commands).
+  MUST use for ANY kctl-sentry operation.
+  Triggers on: "alerts", "assign", "associate", "bulk-resolve", "check", "config", "current", "dashboard", "deploy", "environments", "errors", "events", "generate", "health", "ignore", "init", "issues", "kctl-sentry", "migrate", "overview", "profile", "profiles", "projects", "releases", "remove", "resolve", "skill", "stats", "teams", "test".
+  Auto-generated: 2026-04-05
+  registry_hash: ff99415189e2
+---
+
+# sentry-admin — kctl-sentry CLI Reference
+
+> Auto-generated from `kctl-sentry` command registry. Do not edit manually.
+> To regenerate: `kctl-sentry skill generate`
+> To add custom content: edit `SKILL.extra.md` in the same directory.
+
+## Overview
+
+**CLI:** `kctl-sentry`
+**Command groups:** 11
+**Total commands:** ~35
+**Install:** `cd cli && uv tool install --editable .`
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | JSON output |
+| `--quiet`, `-q` | Suppress info messages |
+| `--format`, `-f` | Output format: pretty/json/csv/yaml |
+| `--no-header` | Omit CSV header row |
+| `--profile`, `-p` | Config profile name |
+| `--version`, `-V` | Show version |
+
+## Command Reference
+
+### `kctl-sentry alerts`
+
+Manage alert rules.
+
+| Command | Description |
+|---------|-------------|
+| `alerts create <project> <name> [--metric] [--threshold] [--time_window]` | Create a new metric alert rule. |
+| `alerts list [--project]` | List alert rules. |
+| `alerts show <rule_id> <project>` | Show alert rule details and trigger history. |
+
+### `kctl-sentry config`
+
+Manage CLI configuration and profiles.
+
+| Command | Description |
+|---------|-------------|
+| `config add <name> [--auth_token] [--organization] [--url] [--default_project] [--set_default]` | Add or update a profile's Sentry connection. |
+| `config current` | Show the active profile and connection status. |
+| `config init [--auth_token] [--organization] [--url] [--default_project] [--name]` | Initialize CLI configuration. |
+| `config migrate` | Migrate config from flat format to service-scoped format. |
+| `config profiles` | List all profiles with Sentry connection status. |
+| `config remove <name> [--force] [--service_only]` | Remove a profile or just its Sentry config. |
+| `config set <key> <value> [--profile_arg]` | Set a configuration value for the current service. |
+| `config show` | Show configuration. |
+| `config test` | Test API connection. |
+| `config use <name>` | Switch default profile. |
+
+### `kctl-sentry dashboard`
+
+Quick overview of Sentry state.
+
+| Command | Description |
+|---------|-------------|
+| `dashboard overview` | Show unresolved issues, recent releases, and alert status across projects. |
+
+### `kctl-sentry environments`
+
+Manage project environments.
+
+| Command | Description |
+|---------|-------------|
+| `environments list [--project]` | List environments for a project (e.g. |
+
+### `kctl-sentry health`
+
+API connectivity checks.
+
+| Command | Description |
+|---------|-------------|
+| `health check` | Check Sentry API connectivity, org info, and rate limits. |
+
+### `kctl-sentry issues`
+
+Error triage — list, inspect, resolve, ignore, assign issues.
+
+| Command | Description |
+|---------|-------------|
+| `issues assign <issue_id> <to>` | Assign an issue to a team member. |
+| `issues bulk-resolve <project> [--before] [--force]` | Bulk-resolve old unresolved issues in a project. |
+| `issues ignore <issue_id> [--duration] [--count]` | Ignore an issue, optionally for a duration or until N more events. |
+| `issues list [--project] [--status] [--limit] [--sort]` | List recent issues for a project. |
+| `issues resolve <issue_id> [--release]` | Resolve an issue. |
+| `issues show <issue_id>` | Show issue details, stack trace, and affected users. |
+
+### `kctl-sentry projects`
+
+Manage Sentry projects.
+
+| Command | Description |
+|---------|-------------|
+| `projects create <name> <team> [--platform]` | Create a new project. |
+| `projects dsn <slug>` | Get DSN key for SDK configuration. |
+| `projects list` | List all projects with issue counts. |
+| `projects show <slug>` | Show project details. |
+
+### `kctl-sentry releases`
+
+Manage releases and deploy tracking.
+
+| Command | Description |
+|---------|-------------|
+| `releases associate <version> <commits>` | Associate commits with a release for tracking regressions. |
+| `releases create <version> <project>` | Create a new release for a project. |
+| `releases list [--project] [--limit]` | List recent releases. |
+| `releases show <version>` | Show release details and associated issues. |
+
+### `kctl-sentry skill`
+
+Claude Code skill management.
+
+| Command | Description |
+|---------|-------------|
+| `skill generate [--output] [--install] [--check]` | Auto-generate SKILL.md from CLI command registry. |
+
+**Examples:**
+```bash
+kctl-sentry skill generate
+kctl-sentry skill generate --install
+kctl-sentry skill generate --check
+```
+
+### `kctl-sentry stats`
+
+Event and error statistics.
+
+| Command | Description |
+|---------|-------------|
+| `stats errors [--project] [--period]` | Show error rate trends for a project. |
+| `stats events [--project] [--period]` | Show event volume for a project or organization. |
+
+### `kctl-sentry teams`
+
+Manage teams.
+
+| Command | Description |
+|---------|-------------|
+| `teams list` | List all teams in the organization. |
+| `teams show <slug>` | Show team details, members, and assigned projects. |
+
+## Configuration
+
+Shared config: `~/.config/kodemeio/config.yaml`
+
+```bash
+kctl-sentry config init       # Interactive setup
+kctl-sentry config show       # Show current config
+kctl-sentry config profiles   # List profiles
+kctl-sentry config current    # Show active profile
+kctl-sentry config validate   # Verify config
+```

kctl_sentry-0.6.3/src/kctl_sentry/__init__.py

@@ -0,0 +1,3 @@
+"""kctl-sentry: Sentry error tracking management."""
+
+__version__ = "0.6.3"

kctl_sentry-0.6.3/src/kctl_sentry/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as python -m kctl_sentry."""
+
+from kctl_sentry.cli import _run
+
+_run()

kctl_sentry-0.6.3/src/kctl_sentry/cli.py

@@ -0,0 +1,136 @@
+"""Main CLI entry point for kctl-sentry."""
+
+from __future__ import annotations
+
+
+from typing import Annotated
+
+import typer
+from kctl_lib import KctlError, handle_cli_error
+
+from kctl_sentry import __version__
+from kctl_sentry.commands.alerts import app as alerts_app
+from kctl_sentry.commands.config_cmd import app as config_app
+from kctl_sentry.commands.dashboard import app as dashboard_app
+from kctl_sentry.commands.environments import app as environments_app
+from kctl_sentry.commands.health import app as health_app
+from kctl_sentry.commands.issues import app as issues_app
+from kctl_sentry.commands.projects import app as projects_app
+from kctl_sentry.commands.releases import app as releases_app
+from kctl_sentry.commands.stats import app as stats_app
+from kctl_sentry.commands.teams import app as teams_app
+from kctl_sentry.core.callbacks import AppContext
+from kctl_sentry.core.plugins import discover_and_load_plugins
+from kctl_sentry.commands.skill_cmd import app as skill_app
+from kctl_sentry.commands.doctor_cmd import app as doctor_app
+from kctl_lib.self_update import notify_if_outdated
+from kctl_lib.tui import add_tui_command
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-sentry {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-sentry",
+    help="Kodemeio Sentry CLI — error triage, release tracking, and project management.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress info messages")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p", help="Config profile name")] = None,
+    format: Annotated[str, typer.Option("--format", "-f", help="Output format: pretty, json, csv, yaml")] = "pretty",
+    no_header: Annotated[bool, typer.Option("--no-header", help="Omit header row in CSV output")] = False,
+    auth_token: Annotated[str | None, typer.Option("--auth-token", help="Auth token override")] = None,
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version")
+    ] = False,
+) -> None:
+    """Kodemeio Sentry CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output,
+        quiet=quiet,
+        profile=profile,
+        format=format,
+        no_header=no_header,
+        auth_token_override=auth_token,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-sentry", __version__)
+
+
+app.add_typer(config_app, name="config")
+app.add_typer(health_app, name="health")
+app.add_typer(dashboard_app, name="dashboard")
+app.add_typer(issues_app, name="issues")
+app.add_typer(projects_app, name="projects")
+app.add_typer(releases_app, name="releases")
+app.add_typer(alerts_app, name="alerts")
+app.add_typer(stats_app, name="stats")
+app.add_typer(teams_app, name="teams")
+app.add_typer(environments_app, name="environments")
+app.add_typer(skill_app, name="skill", hidden=True)
+app.add_typer(doctor_app, name="doctor")
+
+# Load third-party plugins via entry points
+discover_and_load_plugins(app)
+add_tui_command(app, service_key="sentry", version=__version__)
+
+
+@app.command("self-update")
+def self_update_cmd(ctx: typer.Context) -> None:
+    """Check for updates and upgrade kctl-sentry."""
+    actx = ctx.obj
+    out = actx.output
+
+    from kctl_lib.self_update import check_update
+    from kctl_lib.self_update import update as do_update
+
+    latest = check_update("kctl-sentry", __version__)
+    if latest:
+        out.info(f"Updating to {latest}...")
+        do_update("kctl-sentry")
+        out.success(f"Updated to {latest}")
+    else:
+        out.success("Already up to date")
+
+
+@app.command()
+def completions(
+    shell: Annotated[str, typer.Argument(help="Shell type: zsh, bash, fish")] = "zsh",
+    install: Annotated[bool, typer.Option("--install", help="Install completions")] = False,
+) -> None:
+    """Generate or install shell completions."""
+    from kctl_lib.completions import get_completion_script, install_completions
+
+    if install:
+        path = install_completions("kctl-sentry", shell)
+        if path:
+            typer.echo(f"Completions installed to {path}")
+        else:
+            typer.echo(f"Could not install completions for {shell}", err=True)
+            raise typer.Exit(code=1)
+    else:
+        script = get_completion_script("kctl-sentry", shell)
+        typer.echo(script)
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except KctlError as e:
+        handle_cli_error(e)
+
+
+if __name__ == "__main__":
+    _run()

kctl_sentry-0.6.3/src/kctl_sentry/commands/alerts.py

@@ -0,0 +1,176 @@
+"""Alert rule management commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_sentry.core.callbacks import AppContext
+from kctl_sentry.core.exceptions import KctlError
+
+app = typer.Typer(help="Manage alert rules.")
+
+
+@app.command("list")
+def list_(
+    ctx: typer.Context,
+    project: Annotated[str | None, typer.Option("--project", "-p", help="Filter by project slug")] = None,
+) -> None:
+    """List alert rules."""
+    c: AppContext = ctx.obj
+    out = c.output
+
+    try:
+        rules = c.client.project_get(project, "/rules/") if project else c.client.org_get("/alert-rules/")
+        if not isinstance(rules, list):
+            rules = []
+
+        rows: list[list[str]] = []
+        for rule in rules:
+            rule_id = str(rule.get("id", ""))
+            name = (rule.get("name", "") or "")[:50]
+            # Project-scoped rules have 'projects', org-scoped have 'project'
+            proj_info = ""
+            if isinstance(rule.get("projects"), list):
+                proj_info = ", ".join(rule["projects"])
+            elif isinstance(rule.get("project"), dict):
+                proj_info = rule["project"].get("slug", "")
+
+            status_val = rule.get("status", "active")
+            owner = ""
+            if isinstance(rule.get("owner"), dict):
+                owner = rule["owner"].get("name", "")
+            elif isinstance(rule.get("owner"), str):
+                owner = rule["owner"]
+
+            rows.append([rule_id, name, proj_info, status_val, owner])
+
+        out.table(
+            "Alert Rules",
+            [
+                ("ID", "cyan"),
+                ("Name", ""),
+                ("Project", ""),
+                ("Status", "green"),
+                ("Owner", "dim"),
+            ],
+            rows,
+            data_for_json=rules,
+        )
+    except KctlError as e:
+        out.error(f"Failed to list alerts: {e}")
+        raise typer.Exit(1) from e
+
+
+@app.command("show")
+def show(
+    ctx: typer.Context,
+    rule_id: Annotated[str, typer.Argument(help="Alert rule ID")],
+    project: Annotated[str, typer.Option("--project", "-p", help="Project slug")],
+) -> None:
+    """Show alert rule details and trigger history."""
+    c: AppContext = ctx.obj
+    out = c.output
+
+    try:
+        rule = c.client.project_get(project, f"/rules/{rule_id}/")
+        if not isinstance(rule, dict):
+            rule = {}
+
+        # Parse conditions
+        conditions = rule.get("conditions", [])
+        condition_strs: list[tuple[str, str]] = []
+        for cond in conditions if isinstance(conditions, list) else []:
+            if isinstance(cond, dict):
+                condition_strs.append(("Condition", cond.get("name", str(cond.get("id", "")))))
+
+        # Parse actions
+        actions = rule.get("actions", [])
+        action_strs: list[tuple[str, str]] = []
+        for act in actions if isinstance(actions, list) else []:
+            if isinstance(act, dict):
+                action_strs.append(("Action", act.get("name", str(act.get("id", "")))))
+
+        sections = [
+            (
+                "Alert Rule",
+                [
+                    ("ID", str(rule.get("id", ""))),
+                    ("Name", rule.get("name", "")),
+                    ("Status", rule.get("status", "")),
+                    ("Frequency", f"{rule.get('frequency', '')} seconds"),
+                    ("Date created", (rule.get("dateCreated", "") or "")[:19]),
+                ],
+            ),
+        ]
+
+        if condition_strs:
+            sections.append(("Conditions", condition_strs))
+        if action_strs:
+            sections.append(("Actions", action_strs))
+
+        out.detail(
+            f"Alert Rule: {rule.get('name', rule_id)}",
+            sections,
+            data_for_json=rule,
+        )
+    except KctlError as e:
+        out.error(f"Failed to show alert: {e}")
+        raise typer.Exit(1) from e
+
+
+@app.command("create")
+def create(
+    ctx: typer.Context,
+    project: Annotated[str, typer.Option("--project", "-p", help="Project slug")],
+    name: Annotated[str, typer.Option("--name", "-n", help="Alert rule name")],
+    metric: Annotated[str, typer.Option("--metric", help="Metric: events, users")] = "events",
+    threshold: Annotated[int, typer.Option("--threshold", help="Threshold value")] = 100,
+    time_window: Annotated[int, typer.Option("--time-window", help="Time window in minutes")] = 60,
+) -> None:
+    """Create a new metric alert rule."""
+    c: AppContext = ctx.obj
+    out = c.output
+
+    try:
+        # Map metric to Sentry's aggregate format
+        aggregate_map = {
+            "events": "count()",
+            "users": "count_unique(user)",
+        }
+        aggregate = aggregate_map.get(metric, "count()")
+
+        payload = {
+            "name": name,
+            "aggregate": aggregate,
+            "timeWindow": time_window,
+            "dataset": "events",
+            "query": "",
+            "thresholdType": 0,  # Above threshold
+            "resolveThreshold": None,
+            "triggers": [
+                {
+                    "label": "critical",
+                    "alertThreshold": threshold,
+                    "actions": [],
+                }
+            ],
+            "projects": [project],
+            "owner": None,
+        }
+
+        result = c.client.org_post("/alert-rules/", json=payload)
+        if not isinstance(result, dict):
+            result = {}
+
+        if out.json_mode:
+            out.raw_json(result)
+        else:
+            out.success(f"Alert rule created: {result.get('name', name)}")
+            out.kv("ID", str(result.get("id", "")))
+            out.kv("Metric", aggregate)
+            out.kv("Threshold", str(threshold))
+    except KctlError as e:
+        out.error(f"Failed to create alert: {e}")
+        raise typer.Exit(1) from e