sanityops-cli 0.1.3__py3-none-any.whl

sanityops_cli/defect_checker/renderer.py

@@ -0,0 +1,203 @@
+# Copyright 2026 zipsonken
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""Render defect-check results in the terminal, grouped by artifact type."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+from rich.markup import escape
+from rich.panel import Panel
+from rich.table import Table
+
+#: URL advertised in the footer for the full experience.
+FULL_EXPERIENCE_URL = "https://www.sanityops.org"
+
+#: Map defect-check module names to display group labels.
+_MODULE_LABELS: dict[str, str] = {
+    "QDS": "Skills",
+    "QDT": "Tools",
+    "QDP": "Prompts",
+    "CROSS": "Cross",
+}
+
+#: Map module names to singular type labels for panel titles.
+_MODULE_TYPE_LABELS: dict[str, str] = {
+    "QDS": "Skill",
+    "QDT": "Tool",
+    "QDP": "Prompt",
+}
+
+
+def _resolve_artifact_names(result: dict[str, Any]) -> str | None:
+    """Resolve artifact names from defect's artifact_refs.
+
+    1. Collects artifact_refs from all defects
+    2. Maps refs to artifact names via artifacts[].id -> artifacts[].name
+    3. Returns comma-separated names or None
+    """
+    artifacts = [a for a in result.get("artifacts") or [] if isinstance(a, dict)]
+    by_id = {a.get("id"): a for a in artifacts if isinstance(a.get("id"), str)}
+
+    names: list[str] = []
+    refs: list[str] = []
+    for defect in result.get("defects") or []:
+        if not isinstance(defect, dict):
+            continue
+        for ref in defect.get("artifact_refs") or []:
+            if isinstance(ref, str) and ref not in refs:
+                refs.append(ref)
+
+    seen: set[str] = set()
+    for ref in refs:
+        artifact = by_id.get(ref)
+        name = artifact.get("name") if artifact else None
+        if isinstance(name, str) and name and name not in seen:
+            names.append(name)
+            seen.add(name)
+
+    if names:
+        return ", ".join(names)
+    if len(artifacts) == 1:
+        name = artifacts[0].get("name")
+        if isinstance(name, str) and name:
+            return name
+    return None
+
+
+def resolve_artifact_title(result: dict[str, Any]) -> str | None:
+    """Generate panel title for QDS/QDT/QDP/CROSS results.
+
+    Returns:
+        - "Skill morning-report" (type + name) if artifacts resolvable
+        - "Skills" (plural label) if not resolvable
+        - "Cross" for CROSS module
+        - None for unknown modules
+    """
+    module = result.get("module")
+
+    if module == "CROSS":
+        return "Cross"
+
+    fallback_label = _MODULE_LABELS.get(module)
+    if fallback_label is None:
+        return None
+
+    artifact_names = _resolve_artifact_names(result)
+    type_label = _MODULE_TYPE_LABELS.get(module)
+    if type_label and artifact_names:
+        return f"{type_label} {artifact_names}"
+    return fallback_label
+
+
+#: Maximum number of defects rendered per group.
+MAX_DEFECTS_PER_GROUP = 2
+
+
+class DefectRenderer:
+    """Renders a defect-check response dict for the terminal (English output)."""
+
+    def __init__(self, console: Console):
+        self.console = console
+
+    def render(self, result: dict, *, report_path: str | None = None) -> None:
+        """Render summary, per-group defects, and the footer."""
+        self._render_summary(result.get("summary", {}))
+        self._render_artifact_groups(result.get("results", []))
+        self._render_footer(report_path)
+
+    # ------------------------------------------------------------------
+    # Summary
+    # ------------------------------------------------------------------
+
+    def _render_summary(self, summary: dict[str, Any]) -> None:
+        total = summary.get("total_defects", 0)
+        p0 = summary.get("p0_count", 0)
+        p1 = summary.get("p1_count", 0)
+        p2 = summary.get("p2_count", 0)
+        gate = summary.get("gate_result", "PASS")
+
+        table = Table(title="Defect Check Summary", border_style="blue")
+        table.add_column("Metric", style="bold")
+        table.add_column("Value")
+        table.add_row("Total defects", str(total))
+        table.add_row("Severity", f"P0: {p0}   P1: {p1}   P2: {p2}")
+        gate_style = "red bold" if gate == "FAIL" else "green bold"
+        table.add_row("Gate", f"[{gate_style}]{gate}[/]")
+        self.console.print(table)
+        self.console.print()
+
+    # ------------------------------------------------------------------
+    # Artifact groups
+    # ------------------------------------------------------------------
+
+    def _render_artifact_groups(self, results: list[dict[str, Any]]) -> None:
+        for result in results:
+            title = resolve_artifact_title(result)
+            if title is None:
+                continue
+            defects = result.get("defects", [])
+            if not defects:
+                continue
+            self._render_group(title, defects)
+            self.console.print()
+
+    def _render_group(self, label: str, defects: list[dict[str, Any]]) -> None:
+        lines: list[str] = []
+        shown = defects[:MAX_DEFECTS_PER_GROUP]
+        for defect in shown:
+            lines.append(self._format_defect(defect))
+
+        hidden = len(defects) - len(shown)
+        if hidden > 0:
+            lines.append(f"[dim]... {hidden} more defects not shown[/dim]")
+
+        body = "\n".join(lines)
+        self.console.print(Panel(body, title=label, border_style="cyan"))
+
+    def _format_defect(self, defect: dict[str, Any]) -> str:
+        severity = defect.get("severity", "NONE")
+        defect_id = defect.get("id") or "defect"
+        lines = [f"[bold red]✗ [{severity}] {defect_id}[/]"]
+        if defect.get("location"):
+            lines.append(f"  [dim]Location[/] : {defect['location']}")
+        if defect.get("impact"):
+            lines.append(f"  [dim]Impact[/]   : {defect['impact']}")
+        if defect.get("fix_suggestion"):
+            lines.append(f"  [dim]Fix[/]      : {defect['fix_suggestion']}")
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------------
+    # Footer
+    # ------------------------------------------------------------------
+
+    def _render_footer(self, report_path: str | None = None) -> None:
+        lines: list[str] = []
+        if report_path:
+            lines.append(f"Report saved to [magenta]{escape(report_path)}[/magenta]")
+        lines.extend(
+            [
+                "For the full experience, visit",
+                FULL_EXPERIENCE_URL,
+            ]
+        )
+        self.console.print(
+            Panel(
+                "\n".join(lines),
+                border_style="green",
+            )
+        )

sanityops_cli/exceptions/__init__.py

@@ -0,0 +1,14 @@
+# Copyright 2026 zipsonken
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#

sanityops_cli/exceptions/api_exceptions.py

@@ -0,0 +1,60 @@
+# Copyright 2026 zipsonken
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""API exception definitions for sanityops CLI."""
+
+from sanityops_cli.exceptions.base_exceptions import SanityopsError
+
+
+class APIError(SanityopsError):
+    """Base exception for API-related errors."""
+
+    exit_code: int = 5
+
+
+class AuthenticationError(APIError):
+    """Authentication failed (401/403).
+
+    The API key is invalid, expired, or lacks required permissions.
+    """
+
+    exit_code: int = 5
+
+
+class ProjectNotFoundError(APIError):
+    """Project not found (404).
+
+    The specified project ID does not exist or user lacks access.
+    """
+
+    exit_code: int = 6
+
+
+class NetworkError(APIError):
+    """Network-related error.
+
+    Connection timeout, DNS failure, or other network issues.
+    """
+
+    exit_code: int = 7
+
+
+class APIValidationError(APIError):
+    """Validation error (422).
+
+    Request parameters failed validation.
+    """
+
+    exit_code: int = 2

sanityops_cli/exceptions/base_exceptions.py

@@ -0,0 +1,25 @@
+# Copyright 2026 zipsonken
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""Sanityops CLI Error Definitions"""
+
+
+class SanityopsError(Exception):
+    """Sanityops CLI Base Exception Class"""
+    exit_code: int = 2
+
+class ValidationError(SanityopsError):
+    """Validation Error Exception Class"""
+    exit_code: int = 2

sanityops_cli/help_panel.py

@@ -0,0 +1,49 @@
+"""Getting Started and Advanced Usage panels for CLI help output."""
+
+from rich.panel import Panel
+from rich.text import Text
+
+GETTING_STARTED_TEXT = """\
+  1. Run 'sanityops-cli init' to create the default configuration
+  2. Edit .sanityops/inspect_config.yaml to configure your project
+  3. Run 'sanityops-cli inspect' to start the inspection
+  4. Run 'sanityops-cli inspect repair' to generate fixes (optional)
+"""
+
+ADVANCED_USAGE_TEXT = """\
+  CI/CD Integration:
+    1. Commit .sanityops/inspect_config.yaml to the repository
+    2. Set LLM API keys via environment variables (never commit sensitive keys)
+    3. Run 'sanityops-cli inspect' in the pipeline
+
+  Config Command (sanityops-cli config --help):
+    View detailed configuration options and usage examples
+"""
+
+
+def get_getting_started_panel() -> Panel:
+    """Create the Getting Started panel for help output.
+
+    Returns:
+        A Rich Panel containing the 4-step Getting Started workflow.
+    """
+    return Panel(
+        Text(GETTING_STARTED_TEXT, justify="left"),
+        title="Getting Started",
+        border_style="blue",
+        padding=(0, 1),
+    )
+
+
+def get_advanced_usage_panel() -> Panel:
+    """Create the Advanced Usage panel for help output.
+
+    Returns:
+        A Rich Panel containing CI/CD integration and config reference.
+    """
+    return Panel(
+        Text(ADVANCED_USAGE_TEXT, justify="left"),
+        title="Advanced Usage",
+        border_style="cyan",
+        padding=(0, 1),
+    )

sanityops_cli/logging/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2026 zipsonken
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from sanityops_cli.logging.logger import Logger
+
+__all__ = ["Logger"]

sanityops_cli/logging/logger.py

@@ -0,0 +1,108 @@
+# Copyright 2026 zipsonken
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""File-based logging for sanityops-cli operations."""
+
+from __future__ import annotations
+
+import logging
+import re
+from datetime import date
+from pathlib import Path
+
+#: Patterns used to redact secrets before writing to disk.
+_SECRET_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"sk-[A-Za-z0-9_-]{8,}"), "sk-***"),
+    (re.compile(r"(api[_-]?key\s*[:=]\s*)[^\s\"',}]+", re.IGNORECASE), r"\1***"),
+]
+
+__all__ = ["Logger"]
+
+
+class Logger:
+    """Appends timestamped, leveled messages to a dated log file.
+
+    Each instance owns its own stdlib logger and file handler so multiple
+    instances (e.g. in tests) do not share handlers.
+
+    Process-scoped usage (the CLI) intentionally relies on interpreter exit to
+    flush and close the handler; ``close()`` is provided for long-lived callers
+    and tests to release the handle explicitly.
+    """
+
+    def __init__(self, log_dir: Path | None = None) -> None:
+        if log_dir is not None:
+            self.log_dir = Path(log_dir)
+        else:
+            self.log_dir = Path.home() / ".sanityops" / "logs"
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+        self.log_file = self.log_dir / f"sanityops-cli-{date.today().isoformat()}.log"
+        self._logger = logging.getLogger(f"sanityops_cli.{id(self)}")
+        self._logger.setLevel(logging.DEBUG)
+        self._logger.propagate = False
+        handler = logging.FileHandler(self.log_file, encoding="utf-8")
+        handler.setFormatter(
+            logging.Formatter(
+                "%(asctime)s [%(levelname)s] %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+            )
+        )
+        self._logger.addHandler(handler)
+
+    def debug(self, message: str) -> None:
+        self._logger.debug(Logger.redact(message))
+
+    def info(self, message: str) -> None:
+        self._logger.info(Logger.redact(message))
+
+    def warning(self, message: str) -> None:
+        self._logger.warning(Logger.redact(message))
+
+    def error(self, message: str) -> None:
+        self._logger.error(Logger.redact(message))
+
+    def step_started(self, step_name: str) -> None:
+        self.info(f"Step started: {step_name}")
+
+    def step_completed(self, step_name: str, duration: float) -> None:
+        self.info(f"Step completed: {step_name} ({duration:.2f}s)")
+
+    def step_failed(self, step_name: str, error: str) -> None:
+        self.error(f"Step failed: {step_name} - {error}")
+
+    def get_log_path(self) -> Path:
+        return self.log_file
+
+    def close(self) -> None:
+        """Close and remove the file handler, releasing the open handle.
+
+        Safe to call more than once; after closing, further log calls are
+        dropped (no handler remains to write them).
+        """
+        for handler in self._logger.handlers[:]:
+            handler.close()
+            self._logger.removeHandler(handler)
+
+    @staticmethod
+    def redact(message: str) -> str:
+        """Mask API keys and secret-bearing substrings before logging.
+
+        Coverage is intentionally limited to OpenAI-style ``sk-...`` keys and
+        ``api_key=`` / ``api-key:`` assignments; other credential formats
+        (e.g. AWS, Azure) are not matched and should not be logged.
+        """
+        for pattern, repl in _SECRET_PATTERNS:
+            message = pattern.sub(repl, message)
+        return message

sanityops_cli/main.py

@@ -0,0 +1,123 @@
+# Copyright 2026 zipsonken
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""Sanityops CLI Entrance — Typer Application"""
+
+import sys
+
+# Windows consoles default to GBK/cp936 in zh-CN locales, which cannot encode
+# symbols like ✓/✗/⚠ used throughout the CLI output. Force UTF-8 streams early
+# so output never crashes regardless of terminal code page.
+for _stream in (sys.stdout, sys.stderr):
+    if hasattr(_stream, "reconfigure"):
+        try:
+            _stream.reconfigure(encoding="utf-8", errors="replace")
+        except (ValueError, OSError):
+            pass
+
+import typer  # noqa: E402 - must come after stdout reconfiguration
+from rich.console import Console  # noqa: E402
+
+from sanityops_cli import __version__  # noqa: E402
+from sanityops_cli.commands.config import config_app  # noqa: E402
+from sanityops_cli.commands.init import init_config  # noqa: E402
+from sanityops_cli.commands.inspect import inspect_app  # noqa: E402
+from sanityops_cli.exceptions.base_exceptions import ValidationError  # noqa: E402
+from sanityops_cli.help_panel import (  # noqa: E402
+    get_advanced_usage_panel,
+    get_getting_started_panel,
+)
+
+app = typer.Typer(
+    name="Sanityops-cli",
+    help="Sanityops CLI Tool — A cli tool for sanityops",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"sanityops-cli v{__version__}")
+        typer.echo("Copyright (C) 2026 zipsonken / Sanity AI Labs")
+        typer.echo("License: Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)")
+        raise typer.Exit()
+
+
+@app.callback()
+def callback(
+    _version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show version and exit",
+        is_eager=True,
+        callback=version_callback,
+    ),
+):
+    """Sanityops CLI callback."""
+
+app.add_typer(inspect_app, name="inspect", help="Static defect inspection of logical artifacts (System Prompts, Skills, Tool Schemas), suitable for local development or CI/CD integration")
+app.add_typer(
+    config_app,
+    name="config",
+    help="Get and set sanityops configuration (server base URL, API key, etc.)",
+)
+app.command("init")(init_config)
+
+
+def main():
+    """Entrance function for the Sanityops CLI application."""
+    # Show panels only when --help is the sole flag or there are no args.
+    # This narrow trigger avoids showing panels on usage errors (-h, --bogus).
+    #
+    # Note: --version/-V doesn't need explicit handling here because:
+    # - `--version` won't match the exact `["--help"]` check
+    # - Single-arg `--version` has len > 1, so is_no_args_help is False
+    # - It falls through to the normal app() path, which prints version and exits.
+    is_only_help = sys.argv[1:] == ["--help"]
+    is_no_args_help = len(sys.argv) == 1
+
+    if is_only_help or is_no_args_help:
+        # Use a custom console to capture and extend help output
+        console = Console()
+        try:
+            app()
+        except SystemExit as e:
+            # Swallow the help exit so the panels can be printed after it.
+            # --help exits 0; no_args_is_help triggers Typer's help which
+            # exits 2 (Click's UsageError code). We catch both and continue
+            # to print panels, resulting in exit 0 for both cases.
+            if e.code not in (0, 2):
+                raise
+        # Print the Getting Started and Advanced Usage panels
+        console.print()
+        console.print(get_getting_started_panel())
+        console.print()
+        console.print(get_advanced_usage_panel())
+        return
+
+    try:
+        app()
+    except ValidationError as e:
+        print(f"Validation Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Unknown Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

sanityops_cli/progress/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2026 zipsonken
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from sanityops_cli.progress.tracker import ProgressTracker, StepContext
+
+__all__ = ["ProgressTracker", "StepContext"]