Skip to content

CLAUDE.md

Latest commit

 

History

History
76 lines (56 loc) · 2.63 KB

CLAUDE.md

File metadata and controls

76 lines (56 loc) · 2.63 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Bond CLI is a Python command-line tool for interacting with Bond Home automation devices. It provides commands for device discovery, management, firmware upgrades, and diagnostics.

Development Commands

Setup

pip install -e "."                    # Install in editable mode
pip install -r requirements-test.txt  # Install test dependencies

Testing

pytest                                # Run all tests with coverage
pytest bond/database/test_database.py # Run specific test file
pytest -k "test_name"                 # Run tests matching pattern

Linting

flake8 . --count --max-line-length=127 --statistics

Running the CLI

bond discover                         # Find Bonds on network
bond select <bond-id>                 # Select active Bond
bond -h                               # Show all commands

Architecture

Command System

Commands are registered in bond/app.py and live in bond/commands/. Each command module exposes:

  • help / description - Help text
  • run(args) - Execution function
  • setup(parser) - Optional argparse setup
  • arguments - Dict of argument definitions
  • subcommands - List of nested subcommands (for commands like devices, groups, wifi)

Protocol Layer (bond/proto/)

  • http.py - HTTP transport to Bond REST API (/v2/ endpoints)
  • mdns.py - mDNS discovery using zeroconf (_bond._tcp.local.)
  • wye.py - High-level facade exposing get(), post(), put(), patch(), delete()
  • base_transport.py - Async support via request_async() with callbacks

State Management (bond/database/)

Singleton JSON database at ~/.bond/db.json stores:

  • Selected Bond ID
  • Discovered Bond metadata (IP, port, token)
  • Per-Bond settings

Uses MutableMapping interface with thread-safe RLock.

CLI Framework (bond/cli/)

  • main.py - argparse-based command dispatcher
  • console.py - Thread-safe queue-based output with ANSI color support
  • table.py - Fixed-width table formatting

Key Patterns

Adding a new command: Create module in bond/commands/, register in bond/app.py via load_command().

Async requests: Use request_async(method, bondid, on_success=callback, on_error=callback) from protocol layer.

Token authentication: Token passed in BOND-Token header. Can be retrieved via PIN unlock or set manually.

CI/CD

  • Tests run on Python 3.7, 3.8, 3.9
  • Releases: bump version in setup.py, create annotated git tag (git tag -a "vX.Y.Z"), push to trigger PyPI deployment