skybrush-log-analyzer 0.1.0__tar.gz

skybrush_log_analyzer-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.3
+Name: skybrush-log-analyzer
+Version: 0.1.0
+Summary: Command line application for ArduPilot log analysis using https://logs.skybrush.io.
+Author: Peter Volf, Tamas Nepusz, Gabor Vasarhelyi
+Author-email: Peter Volf <do.volfp@gmail.com>, Tamas Nepusz <tamas@collmot.com>, Gabor Vasarhelyi <vasarhelyi@collmot.com>
+Requires-Dist: httpx2>=2.9.1
+Requires-Dist: platformdirs>=4.11.0
+Requires-Dist: typer>=0.27.1
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Skybrush Log Analyzer
+
+Command line application for analyzing ArduPilot logs using [Skybrush Log Analyzer](https://logs.skybrush.io).
+
+Agent skill included for AI assistance.
+
+## Install
+
+**Option A (recommended): install as a tool**
+
+```bash
+uv tool install skybrush-log-analyzer
+```
+
+If `uv` warns that its tool binary directory (e.g. `~/.local/bin`) is not on your `PATH`, follow its suggestion so `skybrush-log-analyzer` can be invoked directly.
+
+**Option B: run without installing**
+
+Skip installation and prefix every CLI command with `uvx skybrush-log-analyzer`.
+
+## How to use
+
+The commands below assume Option A.
+
+1. Create a Skybrush API key at [https://account.skybrush.io/developer](https://account.skybrush.io/developer)
+2. Log in with your API key: `skybrush-log-analyzer login`
+3. Navigate to the directory containing your log files and analyze a log file: `skybrush-log-analyzer analyze <path-to-log-file>`
+
+Run `skybrush-log-analyzer --help` to see all commands.
+
+## Agent skill
+
+The project comes with an agent skill that helps agents use the included CLI to help you with log analysis.
+
+You can install the skill with the following command:
+
+```bash
+skybrush-log-analyzer add-skill
+```
+
+Or, without installing the CLI:
+
+```bash
+uvx skybrush-log-analyzer add-skill
+```
+
+Good to know:
+
+- By default, the skill will be installed globally to `.agents/skills` in your home directory.
+- If you use Claude Code, add the `--claude` option to the command, which changes the install path to `.claude/skills`.
+- To install the skill in the current working directory, use the `--local` option.
+
+Depending on your agent harness, you may need to restart or reload the harness so it recognizes the newly installed skill.
+
+Assuming you logged in and navigated to your log files as described above, all you need to do is start a new agent session, check whether the `skybrush-log-analysis` skill appears in the list of loaded skills, and prompt the agent to analyze a log file or list available log analysis tests.
+
+## Upgrade
+
+When using `uv tool`, upgrade the CLI and re-install the bundled agent skill so that it matches the new version:
+
+```bash
+uv tool upgrade skybrush-log-analyzer
+skybrush-log-analyzer add-skill --force
+```
+
+When using `uvx`, the CLI always runs the latest revision, but the installed skill does not follow automatically. Refresh it periodically to avoid inconsistency between the skill and the CLI:
+
+```bash
+uvx skybrush-log-analyzer add-skill --force
+```
+
+## Troubleshooting
+
+### [Windows] Character encoding issues
+
+Set `PYTHONIOENCODING=utf-8` before commands to avoid Windows codepage errors (e.g. `UnicodeEncodeError` on `µ`), or set the `PYTHONUTF8=1` environment variable permanently.

skybrush_log_analyzer-0.1.0/README.md

@@ -0,0 +1,76 @@
+# Skybrush Log Analyzer
+
+Command line application for analyzing ArduPilot logs using [Skybrush Log Analyzer](https://logs.skybrush.io).
+
+Agent skill included for AI assistance.
+
+## Install
+
+**Option A (recommended): install as a tool**
+
+```bash
+uv tool install skybrush-log-analyzer
+```
+
+If `uv` warns that its tool binary directory (e.g. `~/.local/bin`) is not on your `PATH`, follow its suggestion so `skybrush-log-analyzer` can be invoked directly.
+
+**Option B: run without installing**
+
+Skip installation and prefix every CLI command with `uvx skybrush-log-analyzer`.
+
+## How to use
+
+The commands below assume Option A.
+
+1. Create a Skybrush API key at [https://account.skybrush.io/developer](https://account.skybrush.io/developer)
+2. Log in with your API key: `skybrush-log-analyzer login`
+3. Navigate to the directory containing your log files and analyze a log file: `skybrush-log-analyzer analyze <path-to-log-file>`
+
+Run `skybrush-log-analyzer --help` to see all commands.
+
+## Agent skill
+
+The project comes with an agent skill that helps agents use the included CLI to help you with log analysis.
+
+You can install the skill with the following command:
+
+```bash
+skybrush-log-analyzer add-skill
+```
+
+Or, without installing the CLI:
+
+```bash
+uvx skybrush-log-analyzer add-skill
+```
+
+Good to know:
+
+- By default, the skill will be installed globally to `.agents/skills` in your home directory.
+- If you use Claude Code, add the `--claude` option to the command, which changes the install path to `.claude/skills`.
+- To install the skill in the current working directory, use the `--local` option.
+
+Depending on your agent harness, you may need to restart or reload the harness so it recognizes the newly installed skill.
+
+Assuming you logged in and navigated to your log files as described above, all you need to do is start a new agent session, check whether the `skybrush-log-analysis` skill appears in the list of loaded skills, and prompt the agent to analyze a log file or list available log analysis tests.
+
+## Upgrade
+
+When using `uv tool`, upgrade the CLI and re-install the bundled agent skill so that it matches the new version:
+
+```bash
+uv tool upgrade skybrush-log-analyzer
+skybrush-log-analyzer add-skill --force
+```
+
+When using `uvx`, the CLI always runs the latest revision, but the installed skill does not follow automatically. Refresh it periodically to avoid inconsistency between the skill and the CLI:
+
+```bash
+uvx skybrush-log-analyzer add-skill --force
+```
+
+## Troubleshooting
+
+### [Windows] Character encoding issues
+
+Set `PYTHONIOENCODING=utf-8` before commands to avoid Windows codepage errors (e.g. `UnicodeEncodeError` on `µ`), or set the `PYTHONUTF8=1` environment variable permanently.

skybrush_log_analyzer-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[project]
+name = "skybrush-log-analyzer"
+version = "0.1.0"
+description = "Command line application for ArduPilot log analysis using https://logs.skybrush.io."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx2>=2.9.1",
+    "platformdirs>=4.11.0",
+    "typer>=0.27.1",
+]
+
+[[project.authors]]
+name = "Peter Volf"
+email = "do.volfp@gmail.com"
+
+[[project.authors]]
+name = "Tamas Nepusz"
+email = "tamas@collmot.com"
+
+[[project.authors]]
+name = "Gabor Vasarhelyi"
+email = "vasarhelyi@collmot.com"
+
+[project.scripts]
+skybrush-log-analyzer = "skybrush_log_analyzer.main:run"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.1",
+    "poethepoet>=0.48.0",
+    "ruff>=0.16.9",
+    "zensical>=0.0.65",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+
+[tool.mypy]
+strict = true
+show_error_codes = true
+
+[tool.ruff]
+line-length = 108
+exclude = [
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "dist",
+    "docs",
+]
+
+[tool.ruff.lint]
+select = [
+    "B",
+    "C",
+    "E",
+    "F",
+    "I",
+    "S",
+    "W",
+]
+
+[tool.poe.tasks]
+serve-docs = "zensical serve"
+build-docs = "zensical build --clean"
+format = "ruff format . --check"
+format-fix = "ruff format ."
+lint = "ruff check ."
+lint-fix = "ruff check . --fix"
+type = "mypy ."
+
+[tool.poe.tasks.check]
+sequence = [
+    "format",
+    "lint",
+    "type",
+]
+ignore_fail = "return_non_zero"

skybrush_log_analyzer-0.1.0/pyproject.toml.orig

@@ -0,0 +1,74 @@
+[project]
+name = "skybrush-log-analyzer"
+version = "0.1.0"
+description = "Command line application for ArduPilot log analysis using https://logs.skybrush.io."
+readme = "README.md"
+authors = [
+    { name = "Peter Volf", email = "do.volfp@gmail.com" },
+    { name = "Tamas Nepusz", email = "tamas@collmot.com" },
+    { name = "Gabor Vasarhelyi", email = "vasarhelyi@collmot.com" },
+]
+requires-python = ">=3.11"
+dependencies = [
+    "httpx2>=2.9.1",
+    "platformdirs>=4.11.0",
+    "typer>=0.27.1",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.1",
+    "poethepoet>=0.48.0",
+    "ruff>=0.16.9",
+    "zensical>=0.0.65",
+]
+
+[project.scripts]
+skybrush-log-analyzer = "skybrush_log_analyzer.main:run"
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root=""
+
+[tool.mypy]
+strict = true
+show_error_codes = true
+
+[tool.ruff]
+line-length = 108
+exclude = [
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "dist",
+    "docs",
+]
+lint.select = [
+    "B", # flake8-bugbear
+    "C", # flake8-comprehensions
+    "E", # pycodestyle errors
+    "F", # pyflakes
+    "I", # isort
+    "S", # flake8-bandit - we must ignore these rules in tests
+    "W", # pycodestyle warnings
+]
+
+[tool.poe.tasks]
+serve-docs = "zensical serve"
+build-docs = "zensical build --clean"
+
+format = "ruff format . --check"
+format-fix = "ruff format ."
+
+lint = "ruff check ."
+lint-fix = "ruff check . --fix"
+
+type = "mypy ."
+
+check.sequence = ["format", "lint", "type"]
+check.ignore_fail = "return_non_zero"

skybrush_log_analyzer-0.1.0/skybrush_log_analyzer/analysis.py

@@ -0,0 +1,70 @@
+from typing import Any
+
+
+def to_agent_view(analysis: dict[str, Any]) -> dict[str, Any]:
+    """
+    Returns the compact, agent-facing view of an analysis API response.
+
+    Drops internal IDs and null fields, orders test results by severity,
+    counts the statuses, omits the messages of passing tests, and adds a
+    note when there are no test results.
+    """
+    tests = [
+        _test_view(result)
+        for result in sorted(
+            analysis.get("test_results") or [],
+            key=lambda result: _STATUS_RANK.get(result.get("status"), len(_STATUS_RANK)),
+        )
+    ]
+    view = {
+        "note_title": analysis.get("note_title"),
+        "note_description": analysis.get("note_description"),
+        "status_counts": _status_counts(tests),
+        "test_results": tests,
+    }
+    if not tests:
+        view["note"] = "No test results in this group; run the analyze command to produce them."
+    return _without_none_fields(view)
+
+
+_STATUS_RANK = {
+    status: rank
+    for rank, status in enumerate(
+        (
+            "FAIL",
+            "WARN",
+            "INFO",
+            "PASS",
+            "SKIP",
+            "NOT_APPLICABLE",
+        )
+    )
+}
+
+
+def _test_view(result: dict[str, Any]) -> dict[str, Any]:
+    messages = [] if result.get("status") == "PASS" else result.get("messages") or []
+    view: dict[str, Any] = {
+        "test_name": result.get("test_name"),
+        "status": result.get("status"),
+        "title": result.get("title"),
+    }
+    if messages:
+        view["messages"] = [_message_view(message) for message in messages]
+    return _without_none_fields(view)
+
+
+def _message_view(message: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in message.items() if key != "id" and value is not None}
+
+
+def _status_counts(tests: list[dict[str, Any]]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for test in tests:
+        status = test["status"]
+        counts[status] = counts.get(status, 0) + 1
+    return counts
+
+
+def _without_none_fields(view: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in view.items() if value is not None}

skybrush_log_analyzer-0.1.0/skybrush_log_analyzer/api_client.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import IO, TYPE_CHECKING, Any
+
+import httpx2
+
+from .errors import BadRequest, ResponseParsingFailed, ServerError, Unauthenticated
+from .typing import SuggestionCategory
+from .utils import calculate_file_hash
+
+if TYPE_CHECKING:
+    from .auth_client import AuthClient
+    from .config import Config
+
+
+@dataclass(frozen=True, slots=True)
+class APIClient:
+    config: Config
+    auth: AuthClient
+
+    def version(self) -> Any:
+        return self.request("/version")
+
+    def tests(self, group: str = "default") -> Any:
+        if group == "all":
+            # No "all" listing route on the backend; merge the two listings.
+            merged: list[dict[str, Any]] = []
+            seen: set[str] = set()
+            for listing in (self.request("/tests"), self.request("/tests/extras")):
+                for test in listing:
+                    name = test.get("name")
+                    if name not in seen:
+                        seen.add(name)
+                        merged.append(test)
+            return merged
+        return self.request("/tests/extras" if group == "extra" else "/tests")
+
+    def analyze(self, path: Path, *, test_names: list[str] | None = None) -> Any:
+        # POST returns the new run only; test results live on the merged by-hash view.
+        with path.open("rb") as f:
+            self.request(
+                "/analysis/",
+                method="POST",
+                files={"file": (path.name, f, "application/octet-stream")},
+                data={"test_names": test_names} if test_names is not None else None,
+                timeout=30,
+            )
+
+        return self.get_analysis(path)
+
+    def get_web_login_url(self) -> str:
+        """Acquires a web login URL for the user."""
+        link = self.request("/login-ticket/", method="POST")
+        login_url = link.get("login_url") if isinstance(link, dict) else None
+        if not isinstance(login_url, str) or not login_url:
+            raise ResponseParsingFailed()
+        return login_url
+
+    def suggest(self, *, category: SuggestionCategory, title: str, content: str) -> Any:
+        return self.request(
+            "/suggestion/",
+            method="POST",
+            json={
+                "category": category,
+                "title": title,
+                "content": content,
+            },
+        )
+
+    def get_analysis(self, path: Path, *, extras: bool = False) -> Any:
+        suffix = "/extras" if extras else ""
+        return self.request(
+            f"/analysis/by-hash/{calculate_file_hash(path.read_bytes())}{suffix}",
+            params={"filename": path.name},
+        )
+
+    def request(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        data: dict[str, Any] | None = None,
+        files: dict[str, tuple[str, IO[bytes], str]] | None = None,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        timeout: int | float = 5,
+    ) -> Any:
+        response = self._send_request(
+            path,
+            method=method,
+            data=data,
+            files=files,
+            params=params,
+            json=json,
+            timeout=timeout,
+        )
+
+        if response.status_code == 401:
+            self.auth.refresh_token()
+            # File bodies may have been consumed; rewind when possible.
+            if files is not None:
+                for _, file_obj, _ in files.values():
+                    seek = getattr(file_obj, "seek", None)
+                    if callable(seek):
+                        seek(0)
+            response = self._send_request(
+                path,
+                method=method,
+                data=data,
+                files=files,
+                params=params,
+                json=json,
+                timeout=timeout,
+            )
+            if response.status_code == 401:
+                raise Unauthenticated()
+
+        status_code = response.status_code
+        if 400 <= status_code < 500:
+            print(f"Request failed ({status_code}): {response.text}")
+            raise BadRequest(response.text)
+
+        if status_code >= 500:
+            raise ServerError()
+
+        try:
+            return response.json()
+        except Exception as e:
+            raise ResponseParsingFailed() from e
+
+    def _send_request(
+        self,
+        path: str,
+        *,
+        method: str,
+        data: dict[str, Any] | None,
+        files: dict[str, tuple[str, IO[bytes], str]] | None,
+        params: dict[str, Any] | None,
+        json: dict[str, Any] | None,
+        timeout: int | float,
+    ) -> httpx2.Response:
+        with httpx2.Client(
+            base_url=self.config.api_url,
+            headers=self.auth.make_auth_headers(),
+            timeout=timeout,
+        ) as client:
+            return client.request(method, path, files=files, data=data, params=params, json=json)

skybrush_log_analyzer-0.1.0/skybrush_log_analyzer/auth_client.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import httpx2
+
+from .errors import AccountUnreachable, InvalidAPIKey, Unauthenticated
+
+if TYPE_CHECKING:
+    from .config import Config
+
+
+class AuthClient:
+    """Acquires and stores API tokens from the account."""
+
+    __slots__ = ("_config", "_token")
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+        self._token: str | None = None
+
+    def make_auth_headers(self) -> dict[str, str]:
+        """
+        Returns authorization headers for API requests.
+
+        Raises:
+            Unauthenticated: No API key is configured.
+            InvalidAPIKey: The account rejected the API key.
+            AccountUnreachable: The account could not be reached or returned an unexpected response.
+        """
+        return {"Authorization": f"Bearer {self._get_token()}"}
+
+    def refresh_token(self) -> None:
+        """
+        Discards any stored token and acquires a new one.
+
+        Raises:
+            Unauthenticated: No API key is configured.
+            InvalidAPIKey: The account rejected the API key.
+            AccountUnreachable: The account could not be reached or returned an unexpected response.
+        """
+        # Invalidate everything
+        self._token = None
+        self._config.clear_token()
+        # Request fresh token
+        self._request_new_token()
+
+    def _get_token(self) -> str:
+        """
+        Returns token from memory, storage, or a fresh token request.
+
+        Raises:
+            Unauthenticated: No API key is configured.
+            InvalidAPIKey: The account rejected the API key.
+            AccountUnreachable: The account could not be reached or returned an unexpected response.
+        """
+        if self._token is not None:
+            return self._token
+
+        token = self._config.load_token()
+        if token is not None:
+            self._token = token
+            return token
+
+        return self._request_new_token()
+
+    def _request_new_token(self) -> str:
+        """
+        Acquires a new token and stores it.
+
+        Raises:
+            Unauthenticated: No API key is configured.
+            InvalidAPIKey: The account rejected the API key.
+            AccountUnreachable: The account could not be reached or returned an unexpected response.
+        """
+        if not self._config.api_key:
+            raise Unauthenticated()
+
+        try:
+            with httpx2.Client(base_url=self._config.account_url, timeout=5) as client:
+                response = client.post(
+                    "/api/get-api-token",
+                    json={"apiKey": self._config.api_key},
+                )
+        except httpx2.HTTPError as e:
+            raise AccountUnreachable(str(e)) from e
+
+        if response.status_code in (401, 403):
+            raise InvalidAPIKey("API key rejected by account app")
+
+        if response.status_code != 200:
+            raise AccountUnreachable(f"Unexpected status from account app: {response.status_code}")
+
+        try:
+            body = response.json()
+        except Exception as e:
+            raise AccountUnreachable("Account app returned non-JSON response") from e
+
+        token = body.get("result") if isinstance(body, dict) else None
+        if not isinstance(token, str) or not token:
+            raise AccountUnreachable("Account app response missing token result")
+
+        self._config.save_token(token)
+        self._token = token
+        return token

skybrush_log_analyzer-0.1.0/skybrush_log_analyzer/cli.py

@@ -0,0 +1,276 @@
+import shutil
+import webbrowser
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from .analysis import to_agent_view
+from .api_client import APIClient
+from .auth_client import AuthClient
+from .config import Config, describe_config_location, load_config, login, logout
+from .errors import (
+    AccountUnreachable,
+    ApplicationError,
+    BadRequest,
+    ConfigError,
+    InvalidAPIKey,
+    ResponseParsingFailed,
+    ServerError,
+    Unauthenticated,
+    typer_error_handler,
+)
+from .paths import ConfigPath, DestinationPath, ResourcePath
+from .typing import SuggestionCategory, TestGroup
+from .utils import print_json
+
+app = typer.Typer(
+    name="ArduPilot log analysis CLI",
+    help="CLI application for ArduPilot log analysis services provided by the Skybrush.io team.",
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+config = load_config()
+auth = AuthClient(config)
+client = APIClient(config, auth)
+
+
+@app.command()
+def web() -> None:
+    """Open the log analysis web interface in the default browser."""
+    with typer_error_handler(config):
+        url = client.get_web_login_url()
+        print(f"Opening {url} ...")
+        webbrowser.open(url)
+
+
+@app.command()
+def account() -> None:
+    """Open the Skybrush account page in the default browser."""
+    print(f"Opening {config.account_url} ...")
+    webbrowser.open(config.account_url)
+
+
+@app.command()
+def version() -> None:
+    """Show analysis backend version info."""
+    with typer_error_handler(config):
+        print_json(client.version())
+
+
+@app.command()
+def tests(
+    group: Annotated[
+        TestGroup,
+        typer.Argument(
+            help="Test group to list: the default tests, the extra (verbose) ones, or all of them."
+        ),
+    ] = "default",
+) -> None:
+    """List available ArduPilot log tests."""
+    with typer_error_handler(config):
+        print_json(client.tests(group))
+
+
+@app.command()
+def analyze(
+    file: Annotated[Path, typer.Argument(help="Path to the ArduPilot log file.")],
+    test: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--test",
+            "-t",
+            help="Test name to run (repeatable). Omit to run all tests.",
+        ),
+    ] = None,
+) -> None:
+    """Upload the given log file, run the analysis on it, and print the results."""
+    if not file.is_file():
+        print(f"Log file not found: {file}")
+        raise typer.Exit(code=1)
+
+    with typer_error_handler(config):
+        # Refresh the API token before file upload to try to avoid hitting
+        # token expiration during the operation.
+        auth.refresh_token()
+        result = client.analyze(file, test_names=test)
+        print_json(to_agent_view(result))
+
+
+@app.command(name="get-analysis")
+def get_analysis(
+    file: Annotated[Path, typer.Argument(help="Path to the ArduPilot log file.")],
+    raw: Annotated[
+        bool,
+        typer.Option("--raw", help="Print the raw API response without trimming."),
+    ] = False,
+) -> None:
+    """Fetch existing analysis for the given log file."""
+    if not file.is_file():
+        print(f"Log file not found: {file}")
+        raise typer.Exit(code=1)
+
+    with typer_error_handler(config):
+        result = client.get_analysis(file)
+        print_json(result if raw else to_agent_view(result))
+
+
+@app.command(name="get-analysis-extras")
+def get_analysis_extras(
+    file: Annotated[Path, typer.Argument(help="Path to the ArduPilot log file.")],
+    raw: Annotated[
+        bool,
+        typer.Option("--raw", help="Print the raw API response without trimming."),
+    ] = False,
+) -> None:
+    """Fetch the extra, verbose test results for the given log file."""
+    if not file.is_file():
+        print(f"Log file not found: {file}")
+        raise typer.Exit(code=1)
+
+    with typer_error_handler(config):
+        result = client.get_analysis(file, extras=True)
+        print_json(result if raw else to_agent_view(result))
+
+
+@app.command(name="suggest")
+def suggest(
+    content: Annotated[
+        str,
+        typer.Argument(
+            help="Feedback content (10-2000 characters). "
+            "Describe the error noticed, the missing log test, or the user feedback."
+        ),
+    ],
+    title: Annotated[
+        str,
+        typer.Option(
+            "--title", "-t", help="Short summary (1-100 characters, excluding surrounding whitespace)."
+        ),
+    ],
+    category: Annotated[
+        SuggestionCategory,
+        typer.Option(
+            "--category", "-c", help="Feedback category. Use 'test_case' for missing or improved log tests."
+        ),
+    ],
+) -> None:
+    """Submit feedback about the analysis service to the Skybrush team."""
+    content = content.strip()
+    if not (10 <= len(content) <= 2000):
+        raise typer.BadParameter(
+            "Feedback content must be 10-2000 characters long (excluding surrounding whitespace)."
+        )
+
+    title = title.strip()
+    if not (1 <= len(title) <= 100):
+        raise typer.BadParameter(
+            "Feedback title must be 1-100 characters long (excluding surrounding whitespace)."
+        )
+
+    with typer_error_handler(config):
+        result = client.suggest(category=category, title=title, content=content)
+        print_json(result)
+
+
+@app.command(name="login")
+def login_cmd(
+    api_key: Annotated[str, typer.Option(prompt="API key")],
+    local: Annotated[
+        bool,
+        typer.Option("--local", help="Whether to update the local config instead of the global one."),
+    ] = False,
+) -> None:
+    """Log in with a Skybrush API key."""
+    candidate = Config(
+        api_key=api_key,
+        api_url=config.api_url,
+        account_url=config.account_url,
+        config_dir=ConfigPath.dir(local=local),
+    )
+    candidate_auth = AuthClient(candidate)
+    candidate_client = APIClient(candidate, candidate_auth)
+
+    with typer_error_handler(candidate):
+        # Mint a fresh token with the candidate key and check backend acceptance.
+        candidate_auth.refresh_token()
+        candidate_client.version()
+        try:
+            login(api_key, local=local)
+        except OSError as e:
+            raise ConfigError(str(e)) from e
+    print("Logged in.")
+
+
+@app.command(name="logout")
+def logout_cmd() -> None:
+    """Log out."""
+    if config.api_key is None:
+        print("Not logged in.")
+        raise typer.Exit(code=1)
+
+    with typer_error_handler(config):
+        try:
+            logout(config)
+        except OSError as e:
+            raise ConfigError(str(e)) from e
+    print(f"Logged out ({describe_config_location(config)}).")
+
+
+@app.command(name="add-skill")
+def add_skill(
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Overwrite existing skill installation."),
+    ] = False,
+    local: Annotated[
+        bool,
+        typer.Option(
+            "--local", help="Whether to install into the project-local or the global skills directory."
+        ),
+    ] = False,
+    claude: Annotated[
+        bool,
+        typer.Option("--claude", help="Whether to install for Claude Code."),
+    ] = False,
+) -> None:
+    """Install the bundled agent skill for the current user."""
+    source = ResourcePath.skill()
+    dest = DestinationPath.skill(local=local, claude=claude)
+    if dest.exists():
+        if not force:
+            print(f"{dest} already exists, use --force to overwrite.")
+            raise typer.Exit(code=1)
+        shutil.rmtree(dest)
+    shutil.copytree(source, dest)
+    print(f"Skill installed in {dest}.")
+
+
+@app.command()
+def auth_status() -> None:
+    """Show current Skybrush account authentication status."""
+    if config.api_key is None:
+        print("No API key configured. Use the login command to log in.")
+        raise typer.Exit(code=1)
+
+    print(f"Using {describe_config_location(config)}.")
+    try:
+        auth.refresh_token()
+        client.version()
+        print(f"Authenticated at {config.account_url}.")
+    except InvalidAPIKey:
+        print(f"API key is invalid or has been revoked. Create a new one at {config.account_url}.")
+        raise typer.Exit(code=1) from None
+    except AccountUnreachable:
+        print(f"Could not reach {config.account_url} to refresh the API token.")
+        raise typer.Exit(code=1) from None
+    except Unauthenticated:
+        print("Backend rejected the API token.")
+        raise typer.Exit(code=1) from None
+    except (BadRequest, ResponseParsingFailed, ServerError):
+        print("Backend could not validate the API token.")
+        raise typer.Exit(code=1) from None
+    except ApplicationError:
+        print("Authentication status check failed.")
+        raise typer.Exit(code=1) from None

skybrush_log_analyzer-0.1.0/skybrush_log_analyzer/config.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from .paths import ConfigPath
+
+_DEFAULT_API_URL = "https://logs.skybrush.io/api/v1"
+_DEFAULT_ACCOUNT_URL = "https://account.skybrush.io"
+_CONFIG_FILENAME = "config.toml"
+_TOKEN_FILENAME = "token.txt"  # noqa: S105
+
+
+@dataclass(kw_only=True, frozen=True, slots=True)
+class Config:
+    """Application config."""
+
+    account_url: str
+    api_key: str | None
+    api_url: str
+    config_dir: Path
+
+    @property
+    def token_path(self) -> Path:
+        return self.config_dir / _TOKEN_FILENAME
+
+    def load_token(self) -> str | None:
+        """Loads the saved token if it exists."""
+        try:
+            token = self.token_path.read_text().strip()
+        except OSError:
+            return None
+        return token or None
+
+    def save_token(self, token: str) -> None:
+        """Saves the given token, creating parent directories as needed."""
+        self.token_path.parent.mkdir(parents=True, exist_ok=True)
+        self.token_path.write_text(token)
+
+    def clear_token(self) -> None:
+        """Deletes the saved token if it exists."""
+        try:
+            self.token_path.unlink()
+        except FileNotFoundError:
+            pass
+
+
+def load_config() -> Config:
+    """
+    Loads the application config.
+
+    Config directory search order:
+
+    - Project-local: `<current-working-directory>/.skybrush-log-analyzer/`
+    - Global: `<user-config-dir>/skybrush-log-analyzer/`
+    """
+    for directory in (ConfigPath.dir(local=True), ConfigPath.dir(local=False)):
+        path = directory / _CONFIG_FILENAME
+        if path.is_file():
+            data = _read_toml(path)
+            return Config(
+                api_key=data.get("api_key"),
+                api_url=data.get("api_url", _DEFAULT_API_URL),
+                account_url=data.get("account_url", _DEFAULT_ACCOUNT_URL),
+                config_dir=directory,
+            )
+
+    return Config(
+        api_key=None,
+        api_url=_DEFAULT_API_URL,
+        account_url=_DEFAULT_ACCOUNT_URL,
+        config_dir=ConfigPath.dir(local=False),
+    )
+
+
+def login(api_key: str, *, local: bool = False) -> None:
+    """
+    Stores the given API key in the application's config file.
+
+    Arguments:
+        api_key: The API key to store.
+        local: Whether the project-local or the global config file
+            should be updated.
+    """
+    path = ConfigPath.dir(local=local) / _CONFIG_FILENAME
+    data = _read_toml(path)
+    data["api_key"] = api_key
+    _write_toml(path, data)
+
+
+def logout(config: Config) -> None:
+    """
+    Removes the config file for the given `Config` and
+    clears the corresponding token if it exists.
+
+    """
+    try:
+        (config.config_dir / _CONFIG_FILENAME).unlink()
+    except FileNotFoundError:
+        pass
+
+    config.clear_token()
+
+
+def describe_config_location(config: Config) -> str:
+    """Human-readable label for the config directory corresponding to the given config."""
+    if config.config_dir == ConfigPath.dir(local=True):
+        return f"local config at {config.config_dir}"
+    if config.config_dir == ConfigPath.dir(local=False):
+        return f"global config at {config.config_dir}"
+    return f"custom config at {config.config_dir}"
+
+
+def _read_toml(path: Path) -> dict[str, str]:
+    """
+    Reads the given toml file, returning only flat string values.
+
+    Returns an empty dict for a missing or unparseable file.
+    """
+    if not path.is_file():
+        return {}
+    try:
+        with path.open("rb") as fh:
+            data = tomllib.load(fh)
+    except tomllib.TOMLDecodeError as e:
+        import warnings
+
+        warnings.warn(f"Ignoring unparseable config file {path}: {e}", stacklevel=2)
+        return {}
+
+    # Keep flat string values only; ignore anything else.
+    return {k: v for k, v in data.items() if isinstance(v, str)}
+
+
+def _write_toml(path: Path, data: dict[str, str]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = [f'{k} = "{_escape(v)}"' for k, v in data.items()]
+    path.write_text("\n".join(lines) + ("\n" if lines else ""))
+
+
+def _escape(value: str) -> str:
+    # Minimal TOML basic-string escaping.
+    return value.replace("\\", "\\\\").replace('"', '\\"')

skybrush_log_analyzer-0.1.0/skybrush_log_analyzer/errors.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+import typer
+
+if TYPE_CHECKING:
+    from .config import Config
+
+
+class ApplicationError(Exception):
+    """Base class for errors raised by the CLI application."""
+
+
+class ApplicationErrorWithMessage(ApplicationError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+    @property
+    def message(self) -> str:
+        return str(self.args[0])
+
+
+class ConfigError(ApplicationErrorWithMessage): ...
+
+
+class Unauthenticated(ApplicationError): ...
+
+
+class InvalidAPIKey(ApplicationErrorWithMessage): ...
+
+
+class AccountUnreachable(ApplicationErrorWithMessage): ...
+
+
+class BadRequest(ApplicationErrorWithMessage): ...
+
+
+class ServerError(ApplicationError): ...
+
+
+class ResponseParsingFailed(ApplicationError): ...
+
+
+@contextmanager
+def typer_error_handler(config: Config) -> Iterator[None]:  # noqa: C901
+    try:
+        yield
+    except Unauthenticated as e:
+        print("Authentication error. Check your API key.")
+        raise typer.Exit(1) from e
+    except InvalidAPIKey as e:
+        print(f"Your API key is invalid or has been revoked. Create a new one at {config.account_url}.")
+        raise typer.Exit(1) from e
+    except AccountUnreachable as e:
+        print(f"Could not reach {config.account_url} to acquire an API token.")
+        raise typer.Exit(1) from e
+    except BadRequest as e:
+        print(f"Bad request: {e.message}")
+        raise typer.Exit(1) from e
+    except ConfigError as e:
+        print(f"Config error: {e.message}")
+        raise typer.Exit(1) from e
+    except ServerError as e:
+        print("An error occurred on the server.")
+        raise typer.Exit(1) from e
+    except ResponseParsingFailed as e:
+        print("Server returned non-JSON response.")
+        raise typer.Exit(1) from e
+    except ApplicationErrorWithMessage as e:
+        print(f"An unexpected error occurred: {e.message}")
+        raise typer.Exit(1) from e
+    except ApplicationError as e:
+        print("An unexpected error occurred.")
+        raise typer.Exit(1) from e
+    except Exception as e:
+        print("An unexpected error occurred.")
+        raise typer.Exit(1) from e

skybrush_log_analyzer-0.1.0/skybrush_log_analyzer/main.py

@@ -0,0 +1,8 @@
+def run() -> None:
+    from .cli import app
+
+    app()
+
+
+if __name__ == "__main__":
+    run()

skybrush_log_analyzer-0.1.0/skybrush_log_analyzer/paths.py

@@ -0,0 +1,36 @@
+import importlib.resources
+from pathlib import Path
+from typing import cast
+
+import platformdirs
+
+
+class ResourcePath:
+    @classmethod
+    def skill(cls) -> Path:
+        """Path to the bundled agent skill."""
+        return cls._resources_root() / "skills" / "skybrush-log-analysis"
+
+    @classmethod
+    def _resources_root(cls) -> Path:
+        """Path to the root of the bundled resources."""
+        return cast(Path, importlib.resources.files("skybrush_log_analyzer") / "resources")
+
+
+class DestinationPath:
+    @classmethod
+    def skill(cls, *, local: bool, claude: bool = False) -> Path:
+        """Installation path of the agent skill in the given scope."""
+        base = Path.cwd() if local else Path.home()
+        harness_dir = ".claude" if claude else ".agents"
+        return base / harness_dir / "skills" / "skybrush-log-analysis"
+
+
+class ConfigPath:
+    @classmethod
+    def dir(cls, *, local: bool) -> Path:
+        """Config directory in the given scope."""
+        if local:
+            return Path.cwd() / ".skybrush-log-analyzer"
+
+        return platformdirs.user_config_path("skybrush-log-analyzer")

skybrush_log_analyzer-0.1.0/skybrush_log_analyzer/resources/skills/skybrush-log-analysis/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: skybrush-log-analysis
+description: Uses the Skybrush Log Analyzer to analyze ArduPilot logs. Use it to run deterministic log analysis, or check available log analysis tools and tests.
+---
+
+# Overview
+
+Skybrush Log Analyzer is a Q&A style ArduPilot log analyzer with test algorithms covering many categories (motor, gps, battery etc.), answering questions about a single log file with human-readable output.
+
+Invoke the CLI as `skybrush-log-analyzer <COMMAND>`. If `skybrush-log-analyzer` is not available, fall back to: `uvx skybrush-log-analyzer <COMMAND>`.
+
+On Windows set `PYTHONIOENCODING=utf-8` (or `PYTHONUTF8=1`) before invoking the CLI.
+
+If authentication fails, stop and tell the user! Do not try to fix it by reading env files or environment variables!
+
+If you encounter an issue during the analysis process, stop and notify the user!
+
+Do not attempt any extra, manual analysis unless directly requested by the user.
+
+Avoid rabbit-holes!
+
+## Commands
+
+- `--help`: Show help
+- `version`: Get version info
+- `tests`: List available log tests (`tests` lists the default tests; `tests extra` the extra, verbose ones; `tests all` both groups)
+- `analyze PATH/TO/LOG.bin`: Analyze a log file (runs all tests by default) - uploads the log, runs the analysis, and prints a compact summary of the default test results (omitting passing tests). Extra, verbose tests are run and results are stored too, but only shown via `get-analysis-extras`.
+- `analyze PATH/TO/LOG.bin -t TEST_NAME`: Run only the given tests, `-t` / `--test` can be repeated:`-t TEST_A -t TEST_B`
+- `get-analysis PATH/TO/LOG.bin`: Fetch previously stored analysis results for the given log file (same compact summary as `analyze`, default test results only); add `--raw` for the untrimmed API response
+- `get-analysis-extras PATH/TO/LOG.bin`: Fetch the extra, verbose test results for the given log file (e.g. full parameter value listing) that are excluded from the default output; add `--raw` for the untrimmed API response
+- `suggest -t "TITLE" -c CATEGORY "FEEDBACK TEXT"`: Submit valuable feedback about the analysis service to the Skybrush team; `-t` / `--title` is a short summary (1-100 characters) and `-c` / `--category` is one of `test_case`, `feature`, `improvement`, `bug`, `other`
+- `auth-status`: Show the current authentication status
+
+## Standard results vs. extras
+
+- `get-analysis` and `get-analysis-extras` are complementary: the former returns the default test results, the latter the extra, verbose ones.
+- Empty `test_results` in either output means no tests from that group have been run for the given log file yet - run `analyze` to produce them.
+- If a test the user asked about is missing from the standard output, check the extras.
+
+## Analysis process
+
+STEP 1: Look for existing analysis results using the `get-analysis` command
+
+- Yes: Notify the user about existing results, ask if fresh log analysis should be triggered, and proceed accordingly.
+- No: Move on to next step.
+
+STEP 2: Did the user ask to test or analyze a specific component or topic?
+
+- Yes: Query available tests using the `tests` command. Propose test list to user. The most cost-effective solution is often to run all tests once, and later query and filter existing results.
+- No: Move on to next step with no test name filtering.
+
+STEP 3: Analyze the log file using the `analyze` command
+
+STEP 4: Interpret and summarize the relevant results to the user
+
+## Submitting feedback
+
+Submit feedback with the `suggest` command when you notice any of the following:
+
+- A test result contradicts what the log actually shows (suspected bug) — category `bug`.
+- No available test covers something you or the user needed, or an existing test would need a change to cover it — category `test_case`.
+- The results are correct but confusing, incomplete, or hard to work with — category `improvement`, or `feature` if it requires a new capability.
+- The user's reaction suggests that feedback or test suite changes would be useful (e.g. they question a result, seem dissatisfied with it, or pinpoint a key detail that would have helped the analysis) — category `other` unless it clearly matches one of the above.
+
+Regarding the feedback message:
+
+- Make it technical and self-contained
+- Make it concise, but detailed enough for the reader to fully understand the details and the context
+- Reference affected or related test names and log messages where relevant
+- End the message with a line identifying yourself, in this format: `By: <model> (<harness>)`
+
+Never include secrets in the feedback!
+
+Submit as soon as the issue is understood well enough for meaningful feedback; do not let it interrupt or delay the analysis for the user.
+
+Submit at most one suggestion per distinct issue.
+
+You may submit feedback autonomously. If you are unsure whether something is worth submitting, ask the user first. The feedback API is rate limited.

skybrush_log_analyzer-0.1.0/skybrush_log_analyzer/typing.py

@@ -0,0 +1,5 @@
+from typing import Literal
+
+TestGroup = Literal["default", "extra", "all"]
+
+SuggestionCategory = Literal["test_case", "feature", "improvement", "bug", "other"]

skybrush_log_analyzer-0.1.0/skybrush_log_analyzer/utils.py

@@ -0,0 +1,13 @@
+import hashlib
+import json
+from typing import Any
+
+
+def calculate_file_hash(content: bytes) -> str:
+    """Calculate SHA256 hash of file content."""
+    return hashlib.sha256(content).hexdigest()
+
+
+def print_json(data: Any) -> None:
+    """Dumps the given data to JSON and prints the result."""
+    print(json.dumps(data, ensure_ascii=False, allow_nan=False))