@rmrdeveloper/sideroom-pi 5.0.0

package/src/assets/artifacts/guidelines/javascript.md

@@ -0,0 +1,235 @@
+# JavaScript Coding Guidelines
+
+This is the JavaScript rendition of `GUIDELINES_TEMPLATE.md`. It keeps every
+principle and teaching scenario from the template, expressed for modern
+ECMAScript and Node.js. Read it together with the shared template before any
+code-writing operation.
+
+## Quick reference
+
+| Do | Don't |
+| --- | --- |
+| Exit invalid paths early | Bury the happy path in nested `if/else` blocks |
+| Throw on broken invariants | Substitute defaults that hide corrupted state |
+| Separate validation, transformation, persistence, and notification | Put unrelated responsibilities in one function |
+| Extract a repeated domain rule | Generalize a one-off helper |
+| Keep today's invoice and price requirements small | Add options for hypothetical future features |
+| Return replacement values | Mutate parameter-owned arrays or objects |
+| Validate transport input once at the boundary | Repeat the same checks in services and helpers |
+| Name domain literals once | Scatter status strings and event names |
+
+## Principles
+
+### Guard clauses
+
+```js
+// Bad — the real path is buried
+function getDiscount(user) {
+  if (user) {
+    if (user.isActive) {
+      if (user.hasSubscription) return 0.2;
+    }
+  }
+  return 0;
+}
+
+// Good — flat and explicit
+function getDiscount(user) {
+  if (!user) return 0;
+  if (!user.isActive) return 0;
+  if (!user.hasSubscription) return 0;
+  return 0.2;
+}
+```
+
+### Fail fast
+
+```js
+// Bad — a bad zone id is hidden
+function getShippingCost(order) {
+  return ZONES[order.zoneId] ?? ZONES.default;
+}
+
+// Good — preserve the violated invariant
+function getShippingCost(order) {
+  const zone = ZONES[order.zoneId];
+  if (!zone) throw new Error(`Unknown zoneId: ${order.zoneId}`);
+  return zone.baseCost;
+}
+```
+
+### SRP
+
+Keep the user scenario split into validation, normalization, persistence, and
+notification. A coordinator may compose these units, but should not conceal
+their responsibilities.
+
+```js
+function validateUser(data) {
+  if (!data.email) throw new Error('email required');
+}
+function normalizeUser(data) {
+  return { ...data, email: data.email.trim().toLowerCase() };
+}
+async function createUser(data, users, mailer) {
+  validateUser(data);
+  const user = await users.insert(normalizeUser(data));
+  await mailer.send(user.email, 'welcome');
+  return user;
+}
+```
+
+### DRY
+
+Extract ticket-status normalization only after it is a repeated domain rule,
+not because two unrelated strings happen to be trimmed the same way.
+
+```js
+const TICKET_STATUS = Object.freeze({ OPEN: 'open', CLOSED: 'closed' });
+function normalizeTicketStatus(value) {
+  if (Object.values(TICKET_STATUS).includes(value)) return value;
+  throw new Error(`Unknown ticket status: ${value}`);
+}
+```
+
+### KISS
+
+The price example solves only the current requirement. Do not add locale
+strategies or configuration objects without a present use.
+
+```js
+function formatPrice(value) {
+  return `$${value.toFixed(2)}`;
+}
+```
+
+### YAGNI
+
+The invoice example solves only the current requirement. Do not add recurring
+billing flags, multi-currency branches, or future configuration without a
+present use.
+
+```js
+function createInvoice(order) {
+  return { total: order.total, items: order.items };
+}
+```
+
+### Composition, Demeter, and CQS
+
+Compose only useful behavior, ask immediate collaborators for their own data,
+and keep a query separate from mutation.
+
+```js
+const canBark = { makeSound: () => 'Woof' };
+const dog = { ...canBark };
+
+function getCityName(user) {
+  return user.getCityName();
+}
+function peekNextId(counter) {
+  return counter.value + 1;
+}
+function incrementCounter(counter) {
+  counter.value += 1;
+}
+```
+
+### Explicit errors, immutability, and nulls
+
+```js
+async function loadUser(id, api) {
+  try {
+    return await api.getUser(id);
+  } catch (error) {
+    throw new Error(`Failed to load user ${id}`, { cause: error });
+  }
+}
+
+function addItem(cart, item) {
+  return { ...cart, items: [...cart.items, item] };
+}
+
+function getPlanDiscount(user) {
+  return user?.plan?.discount ?? 0;
+}
+```
+
+Use one documented absence convention. Do not overload `null` or `undefined`
+to represent distinct business states when an explicit value is clearer.
+
+### Testability as a design constraint
+
+Inject time and infrastructure dependencies rather than reaching for globals.
+
+```js
+function isSubscriptionExpired(subscription, now) {
+  return subscription.expiresAt < now;
+}
+```
+
+### Dependency direction
+
+Domain calculations receive domain data instead of constructing SQL, HTTP, or
+mail clients themselves.
+
+```js
+function calculateInvoiceTotal(invoice) {
+  return invoice.items.reduce((sum, item) => sum + item.price, 0);
+}
+```
+
+### Clear names
+
+Use `activeSubscriptions`, `remainingDays`, and `externalId`, not `data`,
+`temp`, or `x`.
+
+### Comments
+
+Explain only non-obvious trade-offs and hazards. Do not narrate a line whose
+name and structure already make it clear.
+
+### No magic strings
+
+Name statuses once rather than scattering literals:
+
+```js
+const ORDER_STATUS = Object.freeze({
+  PENDING_PAYMENT: 'pending_payment',
+  PAID: 'paid',
+});
+```
+
+### SOLID
+
+Depend on a mailer port where the infrastructure can vary:
+
+```js
+class SendWelcomeEmail {
+  constructor(mailer) {
+    this.mailer = mailer;
+  }
+  execute(user) {
+    return this.mailer.send(user.email, 'welcome');
+  }
+}
+```
+
+### Validate once
+
+Parse and validate a request body at its transport boundary. Services trust the
+validated command and do not repeat required, type, or range checks.
+
+```js
+function parseUpdateProfile(body) {
+  if (typeof body?.email !== 'string' || body.email.length === 0) {
+    throw new Error('email required');
+  }
+  return { email: body.email };
+}
+async function updateProfile(command, users) {
+  await users.update(command);
+}
+```
+
+When in doubt: **fail fast, keep it flat, keep it small.**

package/src/assets/artifacts/guidelines/php-laravel.md

@@ -0,0 +1,210 @@
+# PHP Laravel Coding Guidelines
+
+This is the PHP Laravel version of `GUIDELINES_TEMPLATE.md`. It preserves the
+same decisions and teaching scenarios using strict PHP, Laravel boundaries,
+and Laravel's testing conventions. The shared baseline remains mandatory.
+
+## Quick reference
+
+| Do | Don't |
+| --- | --- |
+| Guard invalid input early | Nest the happy path in `if/else` pyramids |
+| Throw precise exceptions | Fall back to a default that hides bad state |
+| Keep controller, use case, and infrastructure separate | Validate, persist, and notify in one method |
+| Extract repeated domain behavior | Build a service for one use |
+| Use immutable value data where practical | Mutate caller-owned arrays or models invisibly |
+| Validate in a Form Request once | Repeat its rules in services |
+| Inject interfaces at real seams | Construct facades or clients in domain logic |
+| Use named enums/constants | Repeat status strings |
+
+## Principles
+
+### Guard clauses
+
+The discount example stays flat.
+
+```php
+function getDiscount(?User $user): float
+{
+    if ($user === null) return 0.0;
+    if (! $user->isActive()) return 0.0;
+    if (! $user->hasSubscription()) return 0.0;
+    return 0.2;
+}
+```
+
+### Fail fast
+
+Do not silently choose a default shipping zone.
+
+```php
+function shippingCost(string $zoneId, ZoneRepository $zones): int
+{
+    $zone = $zones->find($zoneId);
+    if ($zone === null) throw new DomainException("Unknown zoneId: {$zoneId}");
+    return $zone->baseCost();
+}
+```
+
+### SRP
+
+The user flow keeps validation, normalization, persistence, and notification
+as distinct responsibilities.
+
+```php
+final class CreateUser
+{
+    public function __construct(private UserRepository $users, private Mailer $mailer) {}
+    public function handle(CreateUserData $data): void
+    {
+        $user = $this->users->create($data->withEmail(strtolower(trim($data->email))));
+        $this->mailer->send($user->email, 'welcome');
+    }
+}
+```
+
+### DRY
+
+Extract the third repeated ticket-status normalization, not a one-off helper.
+
+```php
+enum TicketStatus: string { case Open = 'open'; case Closed = 'closed'; }
+function normalizeTicketStatus(string $value): TicketStatus { return TicketStatus::from($value); }
+```
+
+### KISS
+
+Keep the price and invoice examples limited to their actual requirements.
+
+```php
+function formatPrice(float $value): string { return '$'.number_format($value, 2); }
+```
+
+### YAGNI (You Aren't Gonna Need It)
+
+Build the invoice shape needed today; do not add multi-currency, recurrence,
+queues, events, or cache abstractions without a current use case.
+
+```php
+function createInvoice(Order $order): array { return ['total' => $order->total, 'items' => $order->items]; }
+```
+
+### Composition over inheritance
+
+Use focused services and value objects instead of a base class that forces a
+dog to inherit `fly()`.
+
+```php
+final class Dog { public function __construct(private BarkBehavior $bark) {} public function sound(): string { return $this->bark->sound(); } }
+```
+
+### Law of Demeter
+
+Ask the user for its city instead of chaining relations.
+
+```php
+function cityName(User $user): string { return $user->cityName(); }
+```
+
+### Command Query Separation
+
+Keep peeking at an identifier separate from incrementing a counter.
+
+```php
+function peekNextId(Counter $counter): int { return $counter->value() + 1; }
+function incrementCounter(Counter $counter): void { $counter->increment(); }
+```
+
+### Explicit error handling
+
+Translate infrastructure failures with context; do not catch and return null.
+
+```php
+function loadUser(string $id, UserApi $api): User
+{
+    try { return $api->get($id); }
+    catch (Throwable $error) { throw new RuntimeException("Failed to load user {$id}", 0, $error); }
+}
+```
+
+### Immutability by default
+
+Return a replacement cart or DTO rather than changing the caller's collection.
+
+```php
+function addItem(CartData $cart, ItemData $item): CartData
+{
+    return new CartData([...$cart->items, $item]);
+}
+```
+
+### Null handling
+
+Use explicit nullable contracts and preserve a legitimate zero discount.
+
+```php
+function getDiscount(?User $user): float { return $user?->plan()?->discount() ?? 0.0; }
+```
+
+### Testability as a design constraint
+
+Inject the clock rather than calling `now()` inside domain behavior.
+
+```php
+function isSubscriptionExpired(Subscription $subscription, DateTimeImmutable $now): bool
+{
+    return $subscription->expiresAt() < $now;
+}
+```
+
+### Dependency direction
+
+Use cases receive repositories or domain data; domain code never constructs
+Eloquent queries or reads `Request` globals.
+
+```php
+function calculateInvoiceTotal(Invoice $invoice): int
+{
+    return array_sum(array_map(fn (InvoiceItem $item) => $item->price(), $invoice->items()));
+}
+```
+
+### Clear names
+
+Use `$activeSubscriptions`, `$remainingDays`, and `$externalId`; avoid `$data`,
+`$temp`, and `$result`.
+
+### Comments
+
+Comments explain a hidden trade-off or an idempotency hazard, never narrate a
+line of PHP.
+
+### No magic strings
+
+Use a backed enum for the order state scenario.
+
+```php
+enum OrderStatus: string { case PendingPayment = 'pending_payment'; case Paid = 'paid'; }
+if ($order->status === OrderStatus::PendingPayment) { $payments->request($order); }
+```
+
+### SOLID
+
+Depend on a mailer contract, not an SMTP implementation in a use case.
+
+```php
+interface Mailer { public function send(string $email, string $template): void; }
+final class SendWelcomeEmail { public function __construct(private Mailer $mailer) {} }
+```
+
+### Validate once
+
+The Form Request owns HTTP validation; the service trusts its validated DTO.
+
+```php
+final class UpdateProfileRequest extends FormRequest { public function rules(): array { return ['email' => ['required', 'email']]; } }
+final class UpdateProfile { public function handle(UpdateProfileData $data): void { /* persist $data */ } }
+```
+
+Use one validation contract per body/query. When in doubt: **fail fast, keep it
+flat, keep it small.**

package/src/assets/artifacts/guidelines/python.md

@@ -0,0 +1,227 @@
+# Python Coding Guidelines
+
+This is the Python version of `GUIDELINES_TEMPLATE.md`. It preserves the same
+principles and example scenarios with typed Python, explicit boundaries, and
+Python testing conventions. The shared baseline remains mandatory.
+
+## Quick reference
+
+| Do | Don't |
+| --- | --- |
+| Return early for invalid state | Hide the happy path inside nested branches |
+| Raise precise errors immediately | Use a default to hide a broken invariant |
+| Give each function one reason to change | Validate, transform, save, and notify together |
+| Extract real repeated domain logic | Add abstractions before they earn a second use |
+| Keep inputs immutable by default | Surprise callers by changing their objects |
+| Validate once at transport boundaries | Repeat body/query validation in every layer |
+| Inject time and infrastructure | Reach for global clients in domain code |
+| Use enums and named constants | Spread protocol strings around the codebase |
+
+## Principles
+
+### Guard clauses
+
+The discount scenario is flat and typed.
+
+```python
+def get_discount(user: User | None) -> float:
+    if user is None:
+        return 0.0
+    if not user.is_active:
+        return 0.0
+    if not user.has_subscription:
+        return 0.0
+    return 0.2
+```
+
+### Fail fast
+
+Never conceal a bad zone key with a default zone.
+
+```python
+def shipping_cost(zone_id: str, zones: dict[str, Zone]) -> int:
+    zone = zones.get(zone_id)
+    if zone is None:
+        raise ValueError(f"Unknown zone_id: {zone_id}")
+    return zone.base_cost
+```
+
+### SRP
+
+The user flow separates normalization, persistence, and notification.
+
+```python
+def normalize_email(email: str) -> str:
+    return email.strip().lower()
+
+def create_user(email: str, users: UserRepository, mailer: Mailer) -> User:
+    if not email:
+        raise ValueError("email required")
+    user = users.insert(email=normalize_email(email))
+    mailer.send(user.email, "welcome")
+    return user
+```
+
+### DRY
+
+Extract the third repeated ticket-status normalization, not a helper created
+for a single call.
+
+```python
+class TicketStatus(StrEnum):
+    OPEN = "open"
+    CLOSED = "closed"
+
+def normalize_ticket_status(value: str) -> TicketStatus:
+    return TicketStatus(value)
+```
+
+### KISS
+
+Keep price and invoice code focused on the current requirement.
+
+```python
+def format_price(value: float) -> str:
+    return f"${value:.2f}"
+```
+
+### YAGNI (You Aren't Gonna Need It)
+
+Build the invoice required today. Do not introduce strategy trees, recurring
+invoices, or multiple currencies until the requirement exists.
+
+```python
+def create_invoice(order: Order) -> Invoice:
+    return Invoice(total=order.total, items=order.items)
+```
+
+### Composition over inheritance
+
+Compose a dog's bark behavior rather than inherit an unrelated `fly` method.
+
+```python
+@dataclass(frozen=True)
+class Dog:
+    bark: Callable[[], str]
+
+    def make_sound(self) -> str:
+        return self.bark()
+```
+
+### Law of Demeter
+
+Ask the user for a city instead of traversing `user.address.city.name`.
+
+```python
+def city_name(user: User) -> str:
+    return user.city_name()
+```
+
+### Command Query Separation
+
+Querying the next ID does not increment it.
+
+```python
+def peek_next_id(counter: Counter) -> int: return counter.value + 1
+def increment_counter(counter: Counter) -> None: counter.increment()
+```
+
+### Explicit error handling
+
+Attach context and preserve the original exception.
+
+```python
+def load_user(user_id: str, api: UserApi) -> User:
+    try:
+        return api.get_user(user_id)
+    except ApiError as error:
+        raise RuntimeError(f"Failed to load user {user_id}") from error
+```
+
+### Immutability by default
+
+The cart example returns a replacement dataclass.
+
+```python
+def add_item(cart: Cart, item: Item) -> Cart:
+    return replace(cart, items=(*cart.items, item))
+```
+
+### Null handling
+
+Use `None` consistently and preserve a zero discount.
+
+```python
+def get_discount(user: User | None) -> float:
+    return 0.0 if user is None or user.plan is None else user.plan.discount
+```
+
+### Testability as a design constraint
+
+Pass the clock to the subscription check.
+
+```python
+def is_subscription_expired(subscription: Subscription, now: datetime) -> bool:
+    return subscription.expires_at < now
+```
+
+### Dependency direction
+
+The invoice calculation receives an invoice, not a database connection.
+
+```python
+def calculate_invoice_total(invoice: Invoice) -> int:
+    return sum(item.price for item in invoice.items)
+```
+
+### Clear names
+
+Use `active_subscriptions`, `remaining_days`, and `external_id`, never
+`data`, `temp`, or `obj`.
+
+### Comments
+
+Comments document a provider delivery trade-off or an idempotency hazard,
+never narrate the next statement.
+
+### No magic strings
+
+Name order states once.
+
+```python
+class OrderStatus(StrEnum):
+    PENDING_PAYMENT = "pending_payment"
+    PAID = "paid"
+
+if order.status is OrderStatus.PENDING_PAYMENT:
+    request_payment(order)
+```
+
+### SOLID
+
+The welcome use case depends on a mailer protocol, not SMTP.
+
+```python
+class Mailer(Protocol):
+    def send(self, email: str, template: str) -> None: ...
+
+class SendWelcomeEmail:
+    def __init__(self, mailer: Mailer) -> None: self._mailer = mailer
+```
+
+### Validate once
+
+Parse HTTP/message input into a typed command at the boundary. Application
+services trust that command instead of repeating the same required, type, and
+range checks. Use one schema or validator for each body/query.
+
+```python
+@dataclass(frozen=True)
+class UpdateProfile:
+    email: str
+
+def update_profile(command: UpdateProfile, users: UserRepository) -> None:
+    users.update(command)
+```
+
+When in doubt: **fail fast, keep it flat, keep it small.**