Add homeycli-inspired features, connection modes, and mDNS discovery

[langtind]

Summary

Major feature release adding homeycli-inspired commands, flexible connection modes, and automatic device discovery.

New Features

Device Shortcuts

homeyctl devices on <name-or-id>       # Turn device on
homeyctl devices off <name-or-id>      # Turn device off
homeyctl devices values <name-or-id>   # Get all capability values

Snapshot Command

homeyctl snapshot                      # System, zones, devices overview
homeyctl snapshot --include-flows      # Include flows

Filter Support

homeyctl devices list --match "kitchen"  # Filter devices by name
homeyctl flows list --match "night"      # Filter flows by name

Connection Modes

homeyctl config set-mode auto    # Prefer local, fallback to cloud (default)
homeyctl config set-mode local   # Always use local connection
homeyctl config set-mode cloud   # Always use cloud connection
homeyctl config set-local <address> <token>
homeyctl config set-cloud <token>

mDNS Discovery

homeyctl config discover         # Find Homey on local network
homeyctl config discover --timeout 10
# Returns: [{"address": "http://10.0.1.1:4859", "homeyId": "abc123", ...}]

Improved AI Documentation

• Added discovery output example
• Added token management commands
• Added utility commands section

Technical Notes

• Replaced hashicorp/mdns with raw mDNS using miekg/dns (macOS compatibility)
• Added comprehensive tests for config and discovery
• Backwards compatible with existing config files

Test plan

• make test - all tests pass
• make lint - no issues
• Verified mDNS discovery works on macOS
• Verified connection mode switching works

Summary by CodeRabbit

• New Features

  • Added connection mode management (local/cloud/auto) with local device discovery capability
  • Added device filtering by name (--match flag), capability value viewing, and on/off control
  • Added flow filtering by name (--match flag)
  • Added token management commands (list, create, delete)
  • Added system snapshot generation with optional flow inclusion

• Documentation

  • Expanded help content with detailed examples and usage guidance for all new commands

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

This PR introduces local network discovery via mDNS, connection mode support (local/cloud/auto), enhanced device and flow filtering, token management with masking, new configuration subcommands, and a system snapshot feature to the Homey CLI.

Changes

Cohort / File(s)	Summary
CLI Help & Documentation cmd/ai.go	Expanded in-context help and examples for connection modes, device filtering (--match), capability values, on/off control, token management, and snapshot commands.
Configuration Management cmd/config.go, cmd/config_test.go	Added token masking helper, structured config output (mode, local, cloud sections), new subcommands (set-mode, set-local, set-cloud, discover), discovery timeout flag, and JSON/table format handling.
Device Management cmd/devices.go	Added --match filter flag for device list filtering, new commands for device capability values retrieval (devices values), and device on/off control (devices on/off) with setDeviceOnOff helper.
Flow Management cmd/flows.go	Introduced --match filter flag and case-insensitive substring filtering for flows list command.
System Snapshot cmd/snapshot.go	New command module for gathering comprehensive Homey state snapshots (system, zones, devices, optional flows) with table and JSON output formats.
Core Configuration internal/config/config.go, internal/config/config_test.go	Added LocalConfig and CloudConfig types, mode-aware fields (Mode, Local, Cloud) while retaining legacy fields; implemented EffectiveMode(), EffectiveToken(), and updated BaseURL() for mode selection; updated Load/Save for new config schema.
Device Discovery internal/discovery/discovery.go, internal/discovery/discovery_test.go	New module implementing mDNS-based Homey device discovery with HTTP verification; includes HomeyCandidate type, DiscoverHomeys(), VerifyHomey(), and DiscoverAndVerify() functions with response parsing and deduplication.
Client Updates internal/client/client.go	Updated token initialization to use EffectiveToken() instead of direct Token field.
Dependencies go.mod	Added github.com/miekg/dns v1.1.61 for mDNS discovery; updated golang.org/x/* indirect dependencies.

Sequence Diagrams

sequenceDiagram
    participant CLI as CLI Command
    participant Resolver as mDNS Resolver
    participant Network as Network
    participant API as HTTP API
    participant Header as Response Header

    CLI->>Resolver: DiscoverAndVerify(ctx, timeout)
    Resolver->>Network: Query _homey._tcp.local & _athom._tcp.local
    Network-->>Resolver: DNS responses (PTR, SRV, TXT, A/AAAA)
    Resolver->>Resolver: Parse candidates & deduplicate
    
    loop For each candidate
        Resolver->>API: VerifyHomey(address, 2s timeout)
        API->>API: GET /api/manager/system/ping
        API-->>Header: X-Homey-ID header
        Header-->>Resolver: HomeyID & success status
        Resolver->>Resolver: Update candidate if verified
    end
    
    Resolver-->>CLI: []HomeyCandidate (verified)

Loading

sequenceDiagram
    participant CLI as CLI Command
    participant API1 as API: GetSystem
    participant API2 as API: GetZones
    participant API3 as API: GetDevices
    participant API4 as API: GetFlows (optional)
    participant JSON as JSON Parser
    participant Output as Output Formatter

    CLI->>API1: GetSystem()
    API1-->>JSON: System data
    JSON->>JSON: Parse & store
    
    CLI->>API2: GetZones()
    API2-->>JSON: Zones data
    JSON->>JSON: Parse & store
    
    CLI->>API3: GetDevices()
    API3-->>JSON: Devices data
    JSON->>JSON: Parse & store
    
    alt include-flows flag set
        CLI->>API4: GetFlows()
        API4-->>JSON: Flows data
        JSON->>JSON: Parse & add to snapshot
    end
    
    JSON->>Output: Unified snapshot object
    Output-->>CLI: Table or JSON output

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~50 minutes

---

🐰 A local discovery hops through networks bright,
Modes and tokens dance in crypto-light,
Snapshots gather all the system's tale,
With filters swift, no Homey shall elude or fail! ✨

✨ Finishing touches

• 📝 Generate docstrings

---

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7f45220 and ad5eadb.

⛔ Files ignored due to path filters (1)

• go.sum is excluded by !**/*.sum

📒 Files selected for processing (12)

• cmd/ai.go
• cmd/config.go
• cmd/config_test.go
• cmd/devices.go
• cmd/flows.go
• cmd/snapshot.go
• go.mod
• internal/client/client.go
• internal/config/config.go
• internal/config/config_test.go
• internal/discovery/discovery.go
• internal/discovery/discovery_test.go

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}