Skip to content

Commit cd7dde9

Browse files
committed
Merge branch '001-spoke-home-assistant-integration' into main: Implement Home Assistant integration
2 parents a8a0e8d + 81a85ac commit cd7dde9

45 files changed

Lines changed: 4057 additions & 23 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Spoke Development Guidelines
2+
3+
Auto-generated from all feature plans. Last updated: 2025-12-01
4+
5+
## Active Technologies
6+
7+
- C# / .NET 10 MAUI + Ixian-Core (blockchain/crypto), QuIXI (bridge communication), Home-assistant-android (reference SDK) (001-spoke-home-assistant-integration)
8+
9+
## Project Structure
10+
11+
```text
12+
src/
13+
tests/
14+
```
15+
16+
## Commands
17+
18+
# Add commands for C# / .NET 10 MAUI
19+
20+
## Code Style
21+
22+
C# / .NET 10 MAUI: Follow standard conventions
23+
24+
## Recent Changes
25+
26+
- 001-spoke-home-assistant-integration: Added C# / .NET 10 MAUI + Ixian-Core (blockchain/crypto), QuIXI (bridge communication), Home-assistant-android (reference SDK)
27+
28+
<!-- MANUAL ADDITIONS START -->
29+
<!-- MANUAL ADDITIONS END -->

.specify/TASKS.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
TODO list (spec-driven starter)
44

5-
1. Wallet: verify new `WalletAdapter` covers key generation and secure storage. [owner: TBD] [status: todo]
5+
1. Wallet: verify new `WalletAdapter` covers key generation and secure storage. [owner: TBD] [status: completed]
66
2. Onboarding: ensure `OnboardingPage` calls SecureStorage and Preferences correctly. [owner: TBD] [status: todo]
77
3. Settings: add a test for `TestConnectionAsync()` flows. [owner: TBD] [status: todo]
88
4. CI: add a job to run `dotnet test` and linting. [owner: TBD] [status: todo]

.specify/memory/constitution.md

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
# <!--
22
# Sync Impact Report
3-
# Version change: 0.1.0 -> 0.1.1
3+
# Version change: 0.1.1 -> 0.2.0
44
# Modified principles:
55
# - none (core principles unchanged; clarifications applied in additional sections)
66
# Added sections:
7-
# - none
7+
# - Styleguide and SDK Compliance
8+
# - Home Assistant OS API Integration
89
# Removed sections:
910
# - none
1011
# Templates requiring updates:
@@ -60,6 +61,18 @@ testing strategy. Each public surface MUST have clear ownership and tests.
6061
Keeping the exposed surface area small preserves clarity for reviewers and
6162
limits the code that needs to be audited or stress-tested in release gating.
6263

64+
### Styleguide and SDK Compliance
65+
All code MUST follow the established patterns, coding standards, and
66+
architectural decisions from Ixian-Core (blockchain core), Ixian-Docs
67+
(documentation framework), QuIXI (bridge communication), and Home-assistant-android
68+
(mobile app development). This ensures consistency, security, and maintainability
69+
across the ecosystem.
70+
71+
### Home Assistant OS API Integration
72+
Integration with Home Assistant OS API MUST use secure, standards-compliant
73+
methods via QuixiScript. All API calls MUST be authenticated, rate-limited,
74+
and handle errors gracefully to prevent disruption of smart home operations.
75+
6376
## Additional Constraints
6477
Security, correctness, and reproducibility take precedence over convenience.
6578
All releases that include cryptographic code or network protocol changes MUST
@@ -112,5 +125,5 @@ security, consensus, or network behavior MUST include a compliance checklist
112125
that maps to the Core Principles above. The checklist MUST be included in the
113126
PR description and verified by reviewers before merge.
114127

115-
**Version**: 0.1.1 | **Ratified**: TODO(RATIFICATION_DATE): provide original adoption date | **Last Amended**: 2025-12-01
128+
**Version**: 0.2.0 | **Ratified**: TODO(RATIFICATION_DATE): provide original adoption date | **Last Amended**: 2025-12-01
116129
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->

.specify/templates/plan-template.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,10 @@ the following check items and their status (PASS/FAIL/NA):
4343
- Development Workflow: how the story is tracked, reviewed, and deployed in
4444
alignment with the constitution's issue/PR governance and migration
4545
expectations.
46+
- Styleguide and SDK Compliance: how the implementation follows patterns from
47+
Ixian-Core, Ixian-Docs, QuIXI, and Home-assistant-android.
48+
- Home Assistant OS API Integration: if applicable, how API interactions are
49+
secure and compliant via QuixiScript.
4650
If any gate is not PASS, the plan MUST include a justification and an
4751
actionable remediation path. Unresolved security or protocol gates MUST block
4852
Phase 0 → Phase 1 progression.

.specify/templates/spec-template.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,10 @@ address:
9393
and environment/config gating expectations are captured in the design.
9494
- Development Workflow: how the feature work, approvals, and migration
9595
commitment aligns with the constitution's issue/PR governance.
96+
- Styleguide and SDK Compliance: how the design follows patterns from
97+
Ixian-Core, Ixian-Docs, QuIXI, and Home-assistant-android.
98+
- Home Assistant OS API Integration: if applicable, how API interactions are
99+
secure and compliant via QuixiScript.
96100

97101
Omitted or incomplete Compliance sections MUST be returned for revision.
98102

.specify/templates/tasks-template.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,10 @@ stories proceed:
7070
- Development Workflow: Add a task that captures issue/spec linkage, PR
7171
compliance checklists, and migration plan sign-offs for governance-affecting
7272
work.
73+
- Styleguide and SDK Compliance: Add a task to review and align code with
74+
patterns from Ixian-Core, Ixian-Docs, QuIXI, and Home-assistant-android.
75+
- Home Assistant OS API Integration: If applicable, add a task to ensure API
76+
interactions are secure and compliant via QuixiScript.
7377

7478
These items are blocking: user story work SHOULD NOT begin until they are
7579
addressed and marked done.

Spoke.Tests/Spoke.Tests.csproj

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,5 +19,4 @@
1919
<Compile Include="..\Spoke\BridgeConnection.cs" />
2020
</ItemGroup>
2121

22-
<Import Project="..\Ixian-Core\IXICore.projitems" Label="Shared" />
2322
</Project>
Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
using System.Text.Json.Serialization;
2+
3+
namespace Spoke.Data.Models;
4+
5+
/// <summary>
6+
/// Configuration for Home Assistant integration
7+
/// </summary>
8+
public class HomeAssistantConfig
9+
{
10+
/// <summary>
11+
/// Base URL of the Home Assistant instance
12+
/// </summary>
13+
public string BaseUrl { get; set; } = string.Empty;
14+
15+
/// <summary>
16+
/// Encrypted long-lived access token
17+
/// </summary>
18+
public byte[] EncryptedAccessToken { get; set; } = Array.Empty<byte>();
19+
20+
/// <summary>
21+
/// WebSocket URL for real-time updates (optional, derived from BaseUrl if not set)
22+
/// </summary>
23+
public string? WebSocketUrl { get; set; }
24+
25+
/// <summary>
26+
/// Home Assistant version
27+
/// </summary>
28+
public string? Version { get; set; }
29+
30+
/// <summary>
31+
/// List of supported features
32+
/// </summary>
33+
public List<string> Features { get; set; } = new();
34+
35+
/// <summary>
36+
/// Validate that the configuration is valid
37+
/// </summary>
38+
public bool IsValid()
39+
{
40+
if (string.IsNullOrWhiteSpace(BaseUrl))
41+
return false;
42+
43+
if (!Uri.TryCreate(BaseUrl, UriKind.Absolute, out var baseUri))
44+
return false;
45+
46+
if (baseUri.Scheme != Uri.UriSchemeHttp && baseUri.Scheme != Uri.UriSchemeHttps)
47+
return false;
48+
49+
if (EncryptedAccessToken.Length == 0)
50+
return false;
51+
52+
return true;
53+
}
54+
55+
/// <summary>
56+
/// Get the WebSocket URL, deriving from BaseUrl if not explicitly set
57+
/// </summary>
58+
public string GetWebSocketUrl()
59+
{
60+
if (!string.IsNullOrWhiteSpace(WebSocketUrl))
61+
return WebSocketUrl;
62+
63+
if (Uri.TryCreate(BaseUrl, UriKind.Absolute, out var baseUri))
64+
{
65+
var wsScheme = baseUri.Scheme == Uri.UriSchemeHttps ? "wss" : "ws";
66+
return $"{wsScheme}://{baseUri.Host}:{baseUri.Port}/api/websocket";
67+
}
68+
69+
return string.Empty;
70+
}
71+
72+
/// <summary>
73+
/// Check if the Home Assistant version is compatible
74+
/// </summary>
75+
public bool IsVersionCompatible()
76+
{
77+
if (string.IsNullOrWhiteSpace(Version))
78+
return false;
79+
80+
// TODO: Implement version compatibility check
81+
// For now, assume versions starting with 2023+ are compatible
82+
return Version.StartsWith("2023") || Version.StartsWith("2024") || Version.StartsWith("2025");
83+
}
84+
85+
/// <summary>
86+
/// Check if a specific feature is supported
87+
/// </summary>
88+
public bool SupportsFeature(string feature) =>
89+
Features.Contains(feature, StringComparer.OrdinalIgnoreCase);
90+
91+
public override string ToString() => $"{BaseUrl} (v{Version ?? "unknown"})";
92+
}
Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
using System.Net;
2+
3+
namespace Spoke.Data.Models;
4+
5+
/// <summary>
6+
/// Represents a connection to a QuIXI bridge server
7+
/// </summary>
8+
public class QuixiConnection
9+
{
10+
/// <summary>
11+
/// Bridge server hostname or IP address
12+
/// </summary>
13+
public string Host { get; set; } = string.Empty;
14+
15+
/// <summary>
16+
/// Bridge server port number
17+
/// </summary>
18+
public int Port { get; set; } = 8080;
19+
20+
/// <summary>
21+
/// Whether to use secure connection (HTTPS/WSS)
22+
/// </summary>
23+
public bool IsSecure { get; set; } = true;
24+
25+
/// <summary>
26+
/// Encrypted authentication token
27+
/// </summary>
28+
public byte[] EncryptedAuthToken { get; set; } = Array.Empty<byte>();
29+
30+
/// <summary>
31+
/// Last successful connection timestamp
32+
/// </summary>
33+
public DateTime? LastConnected { get; set; }
34+
35+
/// <summary>
36+
/// Current connection status
37+
/// </summary>
38+
public ConnectionStatus Status { get; set; } = ConnectionStatus.Disconnected;
39+
40+
/// <summary>
41+
/// Validate that the connection configuration is valid
42+
/// </summary>
43+
public bool IsValid()
44+
{
45+
if (string.IsNullOrWhiteSpace(Host))
46+
return false;
47+
48+
if (Port < 1 || Port > 65535)
49+
return false;
50+
51+
// Validate hostname/IP format
52+
if (!Uri.CheckHostName(Host) && !IPAddress.TryParse(Host, out _))
53+
return false;
54+
55+
return true;
56+
}
57+
58+
/// <summary>
59+
/// Get the full connection URI
60+
/// </summary>
61+
public Uri GetUri()
62+
{
63+
var scheme = IsSecure ? "wss" : "ws";
64+
return new Uri($"{scheme}://{Host}:{Port}");
65+
}
66+
67+
/// <summary>
68+
/// Check if authentication token is present
69+
/// </summary>
70+
public bool HasAuthToken() => EncryptedAuthToken.Length > 0;
71+
72+
public override string ToString() => $"{Host}:{Port} ({Status})";
73+
}
74+
75+
/// <summary>
76+
/// Connection status enumeration
77+
/// </summary>
78+
public enum ConnectionStatus
79+
{
80+
Disconnected,
81+
Connecting,
82+
Connected,
83+
Authenticating,
84+
Authenticated,
85+
Error
86+
}

0 commit comments

Comments
 (0)