ssh-admin AGENTS.md

Agent Guidelines

Code Quality Principles

SOLID

Single Responsibility — Each module owns exactly one concern. Separate business logic from infrastructure concerns. Entry points (e.g., index.ts, main.ts) should only wire components together — no domain logic.

Open/Closed — Extend behavior without modifying existing modules. New features → new files/functions. New rules/patterns → extend arrays or strategy methods, not inline conditionals.

Liskov Substitution — All implementations of an interface must behave consistently. Functions that throw on failure must use a consistent error shape. Stateful components must maintain invariants regardless of implementation.

Interface Segregation — Keep interfaces narrow. Types should not include transient fields (e.g., passwords resolved at runtime). Separate read-only views from mutable configs.

Dependency Inversion — High-level modules depend on abstractions (exported functions/interfaces), not concrete implementations. Define interfaces before introducing new data sources or transport layers.

DRY

Eliminate repetition in these areas:

• Error responses: Extract helpers for common response shapes (errorResponse(message), successResponse(data)).
• Data access: Centralize I/O through dedicated repository/service modules. Never access filesystems or databases directly from handlers.
• Parsing/tokenization: Shared parsing logic belongs in utility modules, duplicated across handlers.
• Validation: Common validation patterns → shared validators, not inline checks.

KISS & YAGNI

• Prefer simple conditionals over complex abstraction layers.
• Only add abstractions when a third similar case appears.
• Use unknown with type guards instead of any when the shape is dynamic.
• Don't add configuration, layers, or patterns "just in case."

---

Design Patterns

Singleton / Module Pattern

Shared state that must be global within a process → export a single instance. Do not create multiple instances. Document this explicitly.