v0.10.0 - Diagnostic Information Collection (2025-12-27)¶

What Changed?¶

This release introduces the new doctor module for comprehensive diagnostic information collection. The kazunoko status command now gathers system environment, Python configuration, platform details, and device status in a single command, making remote troubleshooting and support significantly easier.

What's New¶

Main Feature: Doctor Module for Diagnostics¶

What it does: Collects comprehensive diagnostic information for troubleshooting, including:

Library versions (kazunoko and all dependencies)
Python environment (version, virtual environment type)
Platform information (OS, architecture)
Device connection details (port, firmware, status)

How to use it:

CLI Usage (recommended for most users):

# Display comprehensive diagnostics
kazunoko status

# Get JSON output for support tickets
kazunoko status --format json --use-raw

# Get flat format for scripting
kazunoko status --format jsonl --use-flat

# Test without hardware
kazunoko status --mock

Python API Usage:

from kazunoko import connect
from kazunoko.doctor import DiagnosticInfo

# Collect all diagnostic information
with connect() as device:
    diagnostics = DiagnosticInfo.collect(device)

# Access nested information
print(f"Version: {diagnostics.library.kazunoko_version}")
print(f"Python: {diagnostics.python.python_version}")
print(f"OS: {diagnostics.platform.os_system}")
print(f"Port: {diagnostics.device.connected_port}")

Output formats:

Nested JSON (--use-raw):

{
  "library": {
    "kazunoko_version": "0.10.0",
    "pydantic_version": "2.12.5",
    ...
  },
  "python": {
    "python_version": "3.12.7",
    "venv_type": "uv",
    ...
  },
  "platform": {
    "os_system": "Darwin",
    "architecture": "arm64",
    ...
  },
  "device": {
    "connected_port": "/dev/ttyUSB0",
    "firmware_version": "1.19.3",
    ...
  }
}

Flat format (--use-flat, default):

{
  "library_kazunoko_version": "0.10.0",
  "python_python_version": "3.12.7",
  "platform_os_system": "Darwin",
  "device_connected_port": "/dev/ttyUSB0",
  ...
}

Installation¶

Quick Start¶

# Get the release
git checkout v0.10.0

# Setup
task env:setup

# Run diagnostics
uv run kazunoko status

What's Different from the Last Version?¶

✅ Added¶

New Module: doctor.py for diagnostic information collection
Enhanced CLI: kazunoko status command now collects comprehensive diagnostics
Data Classes:
LibraryInfo: Library version information
PythonInfo: Python environment information
PlatformInfo: Platform and OS information
DeviceInfo: Device connection and status information
DiagnosticInfo: Complete diagnostic information container
Mock Support: --mock flag for testing without hardware
Multiple Formats: Table, JSON, JSONL, CSV, SSV, TSV, LTSV output formats
Dual Perspectives: --use-raw (nested) and --use-flat (flattened) output modes

🔧 Changed¶

CLI Behavior: kazunoko status now collects comprehensive diagnostics instead of just device status

Is It Safe to Upgrade?¶

Backward Compatible: Yes

✅ CLI Users: The enhanced status command provides more information but maintains the same interface
✅ Library Users: No breaking changes to existing APIs
✅ Output Formats: All existing format options still work

Use Cases¶

Remote Support¶

Collect diagnostics for remote troubleshooting:

# Generate diagnostic report for support ticket
kazunoko status --format json --use-raw > diagnostics.json

Environment Verification¶

Check if the environment is correctly configured:

# Quick environment check
kazunoko status --format table

# Script-friendly output
kazunoko status --format jsonl --use-flat

CI/CD Integration¶

Verify installation in automated pipelines:

# Test without hardware in CI
kazunoko status --mock --format jsonl

Tests Passed¶

✅ Builds without errors
✅ Works with real device (/dev/cu.usbserial-110)
✅ Works with mock device (--mock)
✅ All output formats verified (table, json, jsonl, csv, ssv, tsv, ltsv)
✅ Nested output verified (--use-raw)
✅ Flat output verified (--use-flat)
✅ Virtual environment detection (uv, venv, conda)
✅ Dependency version collection

Release Details¶

Date: 2025-12-27
Version: v0.10.0
New Files: src/kazunoko/doctor.py (261 lines)
Modified Files: src/kazunoko/cli.py
Key Commits:
563e510: feat(cli): enhance status command with comprehensive diagnostics
0547a70: refactor(cli): simplify status command implementation
05c463c: refactor(cli): unify device handling in status command
995bc17: fix(doctor): remove serial port accessibility check to prevent port conflicts
940ea0b: refactor(doctor): consolidate port fields into connected_port
b71028c: refactor(doctor): organize diagnostic info into nested structure
775092c: refactor(doctor): add class methods for data collection
8cb2fb1: refactor(doctor): remove collect_diagnostics alias
35f7c8c: refactor(doctor): simplify DiagnosticInfo.collect signature

Technical Details¶

Architecture¶

The doctor module uses a clean object-oriented design:

Individual Collectors: Each diagnostic category has its own dataclass with a collect() class method
Nested Structure: Information is organized into logical categories
Type Safety: All data uses Pydantic dataclasses for validation
Flexible Output: Supports both nested and flat perspectives

Module Structure¶

DiagnosticInfo.collect(device)
├── LibraryInfo.collect()      # Library versions
├── PythonInfo.collect()        # Python environment
├── PlatformInfo.collect()      # Platform info
└── DeviceInfo.collect(device)  # Device status

Next Steps¶

Planned improvements for future releases:

Add network connectivity diagnostics
Include disk space and memory usage
Provide diagnostic recommendations and fixes
Export diagnostics in additional formats (markdown, HTML)