chore: add CLAUDE.md and rules for Claude Code guidance

Author: d4rken

.claude/CLAUDE.md

@@ -0,0 +1,18 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+# Octi Server
+
+Sync server for the [Octi](https://github.com/d4rken-org/octi) Android app. Devices in the same account push/pull module data through this server, with real-time WebSocket notifications.
+
+- **Package**: `eu.darken.octi.kserver`
+- **Architecture**: Ktor 3 + Dagger 2 DI + file-based JSON persistence (no database)
+- **Key tech**: Kotlin coroutines, kotlinx-serialization, Netty, KSP
+
+## Rules
+
+- [Architecture](rules/architecture.md) — Domain hierarchy, routing, persistence, sync flow, auth
+- [Build Commands](rules/build-commands.md) — Gradle commands, running locally, Docker, CI
+- [Testing](rules/testing.md) — TestRunner, integration tests, helpers
+- [Commit Guidelines](rules/commit-guidelines.md) — Commit message format and examples

.claude/rules/architecture.md

@@ -0,0 +1,80 @@
+# Architecture
+
+## Domain Hierarchy
+
+Entities nest: **Account → Device → Module**. This maps directly to both the code packages and the on-disk storage layout.
+
+```
+dataPath/accounts/{accountId}/
+├── account.json
+├── shares/{shareId}.json
+└── devices/{deviceId}/
+    ├── device.json
+    └── modules/{sha1(moduleId)}/
+        ├── blob          (binary payload)
+        └── meta.json     (Module.Info)
+```
+
+## Startup Flow
+
+```
+App.main(args) → parse CLI config → DaggerAppComponent.build() → App.launch() → Server.start()
+```
+
+`Server.start()` installs Ktor middleware (logging, WebSockets, content negotiation, body limits, rate limiting, status pages), then registers all routes.
+
+## Routing
+
+Each domain has a `*Route` class (`@Singleton`, injected by Dagger) with a `setup(Routing)` method called from `Server.kt`. All endpoints live under `/v1/`.
+
+| Route | Path | Purpose |
+|-------|------|---------|
+| AccountRoute | `/v1/account` | Create/delete accounts |
+| ShareRoute | `/v1/account/share` | Generate/consume share codes |
+| DeviceRoute | `/v1/devices` | List/delete/reset devices |
+| ModuleRoute | `/v1/module/{moduleId}` | Read/write/delete module data |
+| WsRoute | `/v1/ws` | WebSocket sync notifications |
+| StatusRoute | `/v1/status` | Health check |
+| MyIpRoute | `/v1/myip` | Client IP echo |
+
+## Persistence
+
+**No database.** All state is JSON files on disk + in-memory `ConcurrentHashMap` caches.
+
+- Repos (`AccountRepo`, `DeviceRepo`, `ModuleRepo`, `ShareRepo`) load everything into memory at startup via `runBlocking` in `init {}`.
+- File writes use `kotlinx.serialization`.
+- `Device` operations are protected by a per-device `Mutex`.
+- Module IDs are SHA-1 hashed for safe directory names.
+
+## Sync Flow
+
+1. Device A writes module → `POST /v1/module/{moduleId}`
+2. `ModuleRepo` stores data, calls `SyncNotifier.enqueue()`
+3. `SyncNotifier` debounces 500ms, then broadcasts `ModuleChanged` event
+4. `ConnectionRegistry` delivers event to all WebSocket sessions in the account except the originator
+5. Device B receives event, fetches updated data via `GET /v1/module/{moduleId}`
+
+## Authentication
+
+- `X-Device-ID` header: device UUID
+- `Authorization: Basic base64(accountId:devicePassword)` header
+- Device password: 50 random bytes, generated at registration, constant-time comparison
+- Helper: `HttpExtensions.authenticateDevice()` — parses headers, looks up device, verifies credentials, updates `lastSeen`
+
+## Background Jobs
+
+All run in `AppScope` (application-wide `SupervisorJob + Dispatchers.Default`):
+
+- **Account GC**: removes accounts with no devices after 10 min
+- **Device expiration**: removes devices not seen in 90 days
+- **Module expiration**: removes modules not accessed in 90 days
+- **Share expiration**: cleans up expired share codes (60 min TTL)
+
+## WebSocket Connection Limits
+
+Managed by `ConnectionRegistry`:
+- Per account: 64
+- Per IP: 32
+- Global: 10,000
+- Frame rate: 120 frames/min per connection
+- Oldest session evicted when per-account limit exceeded

.claude/rules/build-commands.md

@@ -0,0 +1,59 @@
+# Build Commands
+
+## Building
+
+```bash
+# Build distribution
+./gradlew clean installDist
+
+# Assemble only (CI uses this)
+./gradlew assemble
+```
+
+Output: `./build/install/octi-server/`
+
+## Testing
+
+```bash
+# Run all tests
+./gradlew test
+
+# Full checks (tests + verification)
+./gradlew check
+
+# Run a single test class
+./gradlew test --tests "eu.darken.octi.kserver.module.ModuleFlowTest"
+
+# Run a single test method
+./gradlew test --tests "eu.darken.octi.kserver.module.ModuleFlowTest.writing a module"
+```
+
+## Running Locally
+
+```bash
+./build/install/octi-server/bin/octi-server --datapath=./octi-data
+```
+
+CLI arguments:
+- `--datapath=<path>` (required) — data storage directory
+- `--port=<num>` — server port (default: 8080)
+- `--debug` — verbose logging
+- `--disable-rate-limits` — disable rate limiting
+
+## Docker
+
+```bash
+docker run -v octi-data:/etc/octi-server -p 8080:8080 ghcr.io/d4rken-org/octi-server
+```
+
+Environment variables: `OCTI_PORT`, `OCTI_DEBUG`, `OCTI_DATA_DIR`
+
+## CI
+
+- **code-checks.yml**: runs `assemble` + `check` on push to main and PRs
+- **release-tag.yml**: builds `installDist`, zips, creates GitHub release on `v*` tags
+- JDK 17 (adopt), Gradle 8.13
+
+## Context Management
+
+When running gradle builds or tests, use the Task tool with a sub-agent to keep verbose output isolated from the main conversation context. Run gradle directly only when the user explicitly requests full output.

.claude/rules/commit-guidelines.md

@@ -0,0 +1,24 @@
+# Commit Message Guidelines
+
+## Format
+
+- Imperative mood, present tense ("Add feature" not "Added feature")
+- First line: 50-60 characters max
+- No module prefix — flat commit messages
+- Optionally add a blank line and detailed description body
+
+## Examples from History
+
+```
+Restrict GITHUB_TOKEN permissions to minimum required
+Rename project from octi-sync-server-kotlin to octi-server
+Remove idle timeout cleanup, rely on Ktor ping/pong for WS liveness
+Add WebSocket-based real-time sync notifications
+Add share code consumption and account linking
+```
+
+## Prefixes
+
+- `fix:` / `chore:` / `feat:` style prefixes are used (lowercase, with colon)
+- **Release commits**: `Release: {version}`
+- **Dependency upgrades**: `Upgrade {dependency} from {old} to {new}`

.claude/rules/testing.md

@@ -0,0 +1,37 @@
+# Testing
+
+## Stack
+
+JUnit 5 + Kotest matchers + MockK + Ktor test host
+
+## Test Infrastructure
+
+### `TestRunner` (base class)
+- Starts a real server on a random port with a temp data directory
+- Provides an HTTP client pre-configured with JSON content negotiation
+- Tears down server and deletes temp data after each test
+
+### `runTest2 { }` lambda
+All integration tests use this pattern — it sets up the environment and provides a receiver with helper functions.
+
+### `TestRunnerExtensions.kt` helpers
+Pre-built flows for common operations:
+- `createDevice()` / `createDeviceRaw()` — register a device and get credentials
+- `createShareCode()` — generate a share code for an account
+- `addDeviceId()` / `addAuth()` / `addCredentials()` — attach auth headers
+- `readModule()` / `writeModule()` / `deleteModule()` — module CRUD
+- `listDevices()` / `deleteDevice()` — device management
+
+### Data classes
+- `Credentials` — wraps device ID + auth pair
+- `Auth` — account ID + password
+
+## Test Organization
+
+- `*FlowTest` — integration tests with full HTTP round-trips (most tests are this type)
+- `*RepoTest` — unit tests for persistence layer
+- `*Test` — unit tests for individual components (RateLimiter, ConnectionRegistry, etc.)
+
+## Assertions
+
+Uses Kotest matchers: `shouldBe`, `shouldNotBe`, `shouldBeNull`, etc.