Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions .agents/skills/accesscontrol-admin/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
name: accesscontrol-admin
description: Specialized instructions for managing AccessControl access points, user identities, PIN credentials, recurring schedules, and access logs via the REST API or the 2026-07-28 Model Context Protocol (MCP) server.
---

# AccessControl Admin Skill

Use this skill when integrating, testing, or automating AccessControl doors, users, schedules, or audit logs via the REST API or Model Context Protocol (MCP).

## MCP Server Endpoints

- **SSE Endpoint**: `/mcp/sse`
- **Messages Endpoint**: `/mcp/messages?sessionId=<id>`
- **Protocol Version**: Defaults to `2026-07-28` with negotiated fallback for `2024-11-05`.

## Available MCP Tools

1. `accesscontrol__list_doors`: Returns all configured doors with live lock state, contact sensor status, and auto-lock countdowns.
2. `accesscontrol__unlock_door(doorId, durationMinutes)`: Issues remote unlock with optional auto-lock pause.
3. `accesscontrol__lock_door(doorId)`: Immediately engages the physical lock.
4. `accesscontrol__create_guest_pin(name, pin, validFrom, validUntil, doorIds)`: Dynamically provisions a temporary guest code with start/end UTC timestamps.
5. `accesscontrol__revoke_user(userId)`: Revokes all assigned door policies and wipes hardware slots.
6. `accesscontrol__get_access_logs(doorId, limit)`: Queries access audit logs with user names, timestamps, and unlock methods.

## REST API Endpoints

- `GET /api/doors`: List all doors.
- `POST /api/doors`: Create a door.
- `GET /api/users`: List users, credentials, and door schedules.
- `POST /api/users`: Create a user with PIN and access schedule.
- `GET /api/logs`: Query access audit history.
- `GET /api/logs/stream`: Live Server-Sent Events (SSE) feed of lock/unlock events.
- `GET /health`: Health probe returning HTTP 200 OK.
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
---
name: codemaster-engine
description: Specialized instructions for developing, testing, and debugging CodeMaster hardware providers, MQTT ingestion pipelines, auto-lock state machines, and hardware slot sync loops.
name: accesscontrol-engine
description: Specialized instructions for developing, testing, and debugging AccessControl hardware providers, MQTT ingestion pipelines, auto-lock state machines, and hardware slot sync loops.
---

# CodeMaster Engine Skill
# AccessControl Engine Skill

Use this skill when extending lock providers, keypad providers, door contact sensor parsing, auto-lock logic, or MQTT topic dispatching in `CodeMaster.Engine`.
Use this skill when extending lock providers, keypad providers, door contact sensor parsing, auto-lock logic, or MQTT topic dispatching in `AccessControl.Engine`.

## Architecture & Subsystems

1. **Provider Contracts**:
- `ILockProvider`: Implementations in `src/CodeMaster.Engine/Providers/Locks/`. Must declare `LockCapabilities` and handle asynchronous lock/unlock and slot code synchronization.
- `IKeypadProvider`: Implementations in `src/CodeMaster.Engine/Providers/Keypads/`. Declare `KeypadMode` (`StatelessEvent` like Ring Keypad vs `HardwareSlotted` like Schlage deadbolts).
- `IDoorSensorProvider`: Implementations in `src/CodeMaster.Engine/Providers/Sensors/`. Handle contact state parsing (`Closed` vs `Open`).
- `ILockProvider`: Implementations in `src/AccessControl.Engine/Providers/Locks/`. Must declare `LockCapabilities` and handle asynchronous lock/unlock and slot code synchronization.
- `IKeypadProvider`: Implementations in `src/AccessControl.Engine/Providers/Keypads/`. Declare `KeypadMode` (`StatelessEvent` like Ring Keypad vs `HardwareSlotted` like Schlage deadbolts).
- `IDoorSensorProvider`: Implementations in `src/AccessControl.Engine/Providers/Sensors/`. Handle contact state parsing (`Closed` vs `Open`).

2. **Inbound Channel**:
- High-throughput `System.Threading.Channels.Channel<MqttInboundMessage>` handles messages received from Mosquitto via `MQTTnet`.
Expand All @@ -27,8 +27,8 @@ Use this skill when extending lock providers, keypad providers, door contact sen

## Testing Standards

- All new provider logic or state machine changes MUST be accompanied by xUnit tests in `tests/CodeMaster.Tests.Unit/` or closed-loop tests in `tests/CodeMaster.Tests.Harness/`.
- All new provider logic or state machine changes MUST be accompanied by xUnit tests in `tests/AccessControl.Tests.Unit/` or closed-loop tests in `tests/AccessControl.Tests.Harness/`.
- Run full test suite:
```bash
dotnet test codemaster.slnx
dotnet test accesscontrol.slnx
```
33 changes: 0 additions & 33 deletions .agents/skills/codemaster-admin/SKILL.md

This file was deleted.

14 changes: 7 additions & 7 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -63,23 +63,23 @@ jobs:
with:
node-version: 22
cache: 'npm'
cache-dependency-path: src/CodeMaster.UI/package-lock.json
cache-dependency-path: src/AccessControl.UI/package-lock.json

- name: Install dependencies
run: cd src/CodeMaster.UI && npm ci
run: cd src/AccessControl.UI && npm ci

- name: Run ESLint
run: cd src/CodeMaster.UI && npm run lint
run: cd src/AccessControl.UI && npm run lint

- name: Build frontend
run: cd src/CodeMaster.UI && npm run build
run: cd src/AccessControl.UI && npm run build

- name: Run Vitest Unit Tests
run: cd src/CodeMaster.UI && (npm run test:coverage || npm test)
run: cd src/AccessControl.UI && (npm run test:coverage || npm test)

- name: Run Playwright Layout Inspector
run: |
cd src/CodeMaster.UI
cd src/AccessControl.UI
npx playwright install --with-deps chromium
npx playwright test

Expand All @@ -103,7 +103,7 @@ jobs:
env:
ASPNETCORE_URLS: "http://localhost:8150"
run: |
dotnet run --project src/CodeMaster.Web/CodeMaster.Web.csproj --configuration Release --no-build &
dotnet run --project src/AccessControl.Web/AccessControl.Web.csproj --configuration Release --no-build &
APP_PID=$!
echo "Server started with PID $APP_PID"

Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/docker-publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ on:

env:
REGISTRY: ghcr.io
IMAGE_NAME: spelech/codemaster
IMAGE_NAME: spelech/accesscontrol

jobs:
build-and-push:
Expand Down
24 changes: 12 additions & 12 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,24 @@
# CodeMaster Agents Guide
# AccessControl Agents Guide

This document provides mandatory architectural guidelines, testing conventions, and execution rules for AI coding agents working in the `CodeMaster` repository.
This document provides mandatory architectural guidelines, testing conventions, and execution rules for AI coding agents working in the `AccessControl` repository.

---

## 🏛️ System Overview & Architecture

**CodeMaster** is a high-performance .NET 10 and React 19 containerized access control and lock/keypad management engine, designed as an open-source grade, scalable replacement for Keymaster with zero Home Assistant entity bloat.
**AccessControl** is a high-performance .NET 10 and React 19 containerized access control and lock/keypad management engine, designed as an open-source grade, scalable replacement for Keymaster with zero Home Assistant entity bloat.

- **Backend Runtime**: .NET 10 (`net10.0`), C# 13, `<Nullable>enable</Nullable>`, `<ImplicitUsings>enable</ImplicitUsings>`, `codemaster.slnx`.
- **Backend Runtime**: .NET 10 (`net10.0`), C# 13, `<Nullable>enable</Nullable>`, `<ImplicitUsings>enable</ImplicitUsings>`, `AccessControl.slnx`.
- **Database & Persistence**: Embedded SQLite in **Write-Ahead Logging (WAL)** mode (`PRAGMA journal_mode = WAL;`) using **Dapper** with parameterized scripts and idempotent migrations in `DatabaseSeederService.cs`.
- **MQTT Pipeline**: `System.Threading.Channels.Channel<MqttInboundMessage>` handles high-throughput ingestion from Mosquitto via `MQTTnet` 4.x.
- **Provider Abstraction**:
- `ILockProvider`: `ZWaveJsMqttLockProvider`, `GenericMqttLockProvider`, `VirtualLockProvider`.
- `IKeypadProvider`: `RingMqttKeypadProvider` (Stateless Event), `BuiltInLockKeypadProvider` (Hardware Slotted), `GenericMqttKeypadProvider`.
- `IDoorSensorProvider`: `MqttContactSensorProvider`.
- `INotificationDispatcher`: `HomeAssistantDiscoveryService`, `AppriseNotificationDispatcher`.
- **Frontend SPA**: React 19, TypeScript strict mode, Zustand domain stores, pure CSS custom properties (`theme.css`), compiled into `src/CodeMaster.Web/wwwroot/`.
- **Frontend SPA**: React 19, TypeScript strict mode, Zustand domain stores, pure CSS custom properties (`theme.css`), compiled into `src/AccessControl.Web/wwwroot/`.
- **Dynamic Ingress**: Fully supports Home Assistant Ingress via dynamic `X-Ingress-Path` header / `<meta name="base-path">` resolution.
- **Model Context Protocol (MCP)**: Implements the **2026-07-28 specification** at `/mcp/sse` (with `2024-11-05` fallback), exposing 6 tools: `codemaster__list_doors`, `codemaster__unlock_door`, `codemaster__lock_door`, `codemaster__create_guest_pin`, `codemaster__revoke_user`, `codemaster__get_access_logs`.
- **Model Context Protocol (MCP)**: Implements the **2026-07-28 specification** at `/mcp/sse` (with `2024-11-05` fallback), exposing 6 tools: `accesscontrol__list_doors`, `accesscontrol__unlock_door`, `accesscontrol__lock_door`, `accesscontrol__create_guest_pin`, `accesscontrol__revoke_user`, `accesscontrol__get_access_logs`.

---

Expand All @@ -30,7 +30,7 @@ This document provides mandatory architectural guidelines, testing conventions,
- Work on fresh feature branches off `develop`.
- Use `develop` as the active integration branch before production release on `main`.
- Commit using **atomic Conventional Commits** (`feat:`, `fix:`, `test:`, `docs:`, `chore:`).
- Git remote: `git@github.com:spelech/CodeMaster.git`.
- Git remote: `git@github.com:spelech/AccessControl.git`.
3. **Container Immutability**:
- **NEVER** hot-patch or edit files in running containers. Deploy strictly via built images (`docker compose up -d --build`).
4. **SOLID & Code Modularity**:
Expand All @@ -51,19 +51,19 @@ This document provides mandatory architectural guidelines, testing conventions,

```bash
# Build whole solution
dotnet build codemaster.slnx
dotnet build AccessControl.slnx

# Run all .NET unit & closed-loop harness tests
dotnet test codemaster.slnx
dotnet test AccessControl.slnx

# Run frontend tests & linting
cd src/CodeMaster.UI && npm test && npm run lint
cd src/AccessControl.UI && npm test && npm run lint

# Build frontend production bundle into wwwroot
cd src/CodeMaster.UI && npm run build
cd src/AccessControl.UI && npm run build

# Run Playwright layout audit
cd src/CodeMaster.UI && npx playwright test
cd src/AccessControl.UI && npx playwright test

# Run Release SemVer & Markdown Link Verification
python3 verify_release.py --ci --skip-tests
Expand Down
Loading
Loading