@clipboard-health/ai-rules 1.6.43 → 1.7.0

package/common/AGENTS.md

@@ -1,63 +1,267 @@
 <!-- Generated by Ruler -->
 
-<!-- Source: .ruler/common/codeStyleAndStructure.md -->
+<!-- Source: .ruler/common/commitMessages.md -->
 
-# Code style and structure
+# Commit Messages
 
-- Write concise, technical TypeScript code with accurate examples.
-- Use functional and declarative programming patterns.
-- Prefer iteration and modularization over code duplication.
-- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
-- Structure files: constants, types, exported functions, non-exported functions.
-- Avoid magic strings and numbers; define constants.
-- Use camelCase for files and directories (e.g., modules/shiftOffers.ts).
-- When declaring functions, use the `function` keyword, not `const`.
-- Files should read from top to bottom: `export`ed items live on top and the internal functions and methods they call go below them.
-- Prefer data immutability.
+Follow Conventional Commits 1.0 spec for commit messages and PR titles.
 
-# Commit messages
+<!-- Source: .ruler/common/configuration.md -->
 
-- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
+# Configuration
 
-<!-- Source: .ruler/common/errorHandlingAndValidation.md -->
+```text
+Contains secrets?
+  └── Yes → SSM Parameter Store
+  └── No → Engineers-only, tolerate 1hr propagation?
+      └── Yes → Hardcode with @clipboard-health/config
+      └── No → 1:1 with DB entity OR needs custom UI?
+          └── Yes → Database
+          └── No → LaunchDarkly feature flag
+```
 
-# Error handling and validation
+<!-- Source: .ruler/common/featureFlags.md -->
 
-- Sanitize user input.
-- Handle errors and edge cases at the beginning of functions.
-- Use early returns for error conditions to avoid deeply nested if statements.
-- Place the happy path last in the function for improved readability.
-- Avoid unnecessary else statements; use the if-return pattern instead.
-- Use guard clauses to handle preconditions and invalid states early.
-- Implement proper error logging and user-friendly error messages.
-- Favor `@clipboard-health/util-ts`'s `Either` type for expected errors instead of `try`/`catch`.
+# Feature Flags
+
+**Naming:** `YYYY-MM-[kind]-[subject]` (e.g., `2024-03-release-new-booking-flow`)
+
+| Kind         | Purpose                  |
+| ------------ | ------------------------ |
+| `release`    | Gradual rollout to 100%  |
+| `enable`     | Kill switch              |
+| `experiment` | Trial for small audience |
+| `configure`  | Runtime config           |
+
+**Rules:**
+
+- "Off" = default/safer value
+- No permanent flags (except `configure`)
+- Create archival ticket when creating flag
+- Validate staging before production
+- Always provide default values in code
+- Clean up after full launch
+
+<!-- Source: .ruler/common/loggingObservability.md -->
+
+# Logging & Observability
+
+## Log Levels
+
+| Level | When                                       |
+| ----- | ------------------------------------------ |
+| ERROR | Required functionality broken (2am pager?) |
+| WARN  | Optional broken OR recovered from failure  |
+| INFO  | Informative, ignorable during normal ops   |
+| DEBUG | Local only, not production                 |
+
+## Best Practices
+
+```typescript
+// Bad
+logger.error("Operation failed");
+logger.error(`Operation failed for workplace ${workplaceId}`);
+
+// Good—structured context
+logger.error("Exporting urgent shifts to CSV failed", {
+  workplaceId,
+  startDate,
+  endDate,
+});
+```
+
+**Never log:** PII, PHI, tokens, secrets, SSN, account numbers, entire request/response/headers.
+
+Use metrics for counting:
+
+```typescript
+datadogMetrics.increment("negotiation.errors", { state: "New York" });
+```
+
+<!-- Source: .ruler/common/pullRequests.md -->
+
+# Pull Requests
+
+**Requirements:**
+
+1. Clear title: change summary + ticket; Conventional Commits 1.0
+2. Thorough description: why, not just what
+3. Small & focused: single concept
+4. Tested: service tests + validation proof
+5. Passing CI
+
+**Description:** Link ticket, context, reasoning, areas of concern.
+
+<!-- Source: .ruler/common/security.md -->
+
+# Security
+
+**Secrets:**
+
+- `.env` locally (gitignored)
+- Production: AWS SSM Parameter Store
+- Prefer short-lived tokens
+
+**Naming:** `[ENV]_[VENDOR]_[TYPE]_usedBy_[CLIENT]_[SCOPE]_[CREATED_AT]_[OWNER]`
+
+<!-- Source: .ruler/common/structuredConcurrency.md -->
+
+# Structured Concurrency
+
+```typescript
+// Cancellation propagation
+async function fetchWithTimeout(url: string, timeoutMs: number): Promise<Response> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { signal: controller.signal });
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+// All results regardless of failures
+const results = await Promise.allSettled(operations);
+const succeeded = results.filter((r) => r.status === "fulfilled");
+const failed = results.filter((r) => r.status === "rejected");
+```
 
 <!-- Source: .ruler/common/testing.md -->
 
 # Testing
 
-- Follow the Arrange-Act-Assert convention for tests with newlines between each section.
-- Name test variables using the `mockX`, `input`, `expected`, `actual` convention.
-- Aim for high test coverage, writing both positive and negative test cases.
-- Prefer `it.each` for multiple test cases.
-- Avoid conditional logic in tests.
+## Unit Tests
+
+Use when: error handling hard to trigger black-box, concurrency scenarios, >5 variations, pure function logic.
+
+## Conventions
+
+- Use `it` not `test`; `describe` for grouping
+- Arrange-Act-Assert with newlines between
+- Variables: `mockX`, `input`, `expected`, `actual`
+- Prefer `it.each` for multiple cases
+- No conditional logic in tests
 
 <!-- Source: .ruler/common/typeScript.md -->
 
-# TypeScript usage
-
-- Use strict-mode TypeScript for all code; prefer interfaces over types.
-- Avoid enums; use const maps instead.
-- Strive for precise types. Look for type definitions in the codebase and create your own if none exist.
-- Avoid using type assertions like `as` or `!` unless absolutely necessary.
-- Use the `unknown` type instead of `any` when the type is truly unknown.
-- Use an object to pass multiple function params and to return results.
-- Leverage union types, intersection types, and conditional types for complex type definitions.
-- Use mapped types and utility types (e.g., `Partial<T>`, `Pick<T>`, `Omit<T>`) to transform existing types.
-- Implement generic types to create reusable, flexible type definitions.
-- Utilize the `keyof` operator and index access types for dynamic property access.
-- Implement discriminated unions for type-safe handling of different object shapes where appropriate.
-- Use the `infer` keyword in conditional types for type inference.
-- Leverage `readonly` properties for function parameter immutability.
-- Prefer narrow types whenever possible with `as const` assertions, `typeof`, `instanceof`, `satisfies`, and custom type guards.
-- Implement exhaustiveness checking using `never`.
+# TypeScript
+
+## Naming Conventions
+
+| Element               | Convention            | Example                      |
+| --------------------- | --------------------- | ---------------------------- |
+| File-scope constants  | UPPER_SNAKE_CASE      | `MAX_RETRY_COUNT`            |
+| Acronyms in camelCase | Lowercase after first | `httpRequest`, `gpsPosition` |
+| Files                 | Singular, dotted      | `user.service.ts`            |
+
+## Core Rules
+
+- Strict-mode TypeScript; prefer interfaces over types
+- Avoid enums—use const maps
+- NEVER use `any`—use `unknown` or generics
+- Avoid type assertions (`as`, `!`) unless absolutely necessary
+- Use `function` keyword for declarations, not `const`
+- Prefer `undefined` over `null`
+- Explicit return types on functions
+- Files read top-to-bottom: exports first, internal helpers below
+- Boolean props: `is*`, `has*`, `should*`, `can*`
+- Use const assertions for constants: `as const`
+
+## Types
+
+```typescript
+// Strong typing
+function process(arg: unknown) {} // Better than any
+function process<T>(arg: T) {} // Best
+
+// Nullable checks
+if (foo == null) {
+} // Clear intent
+if (isDefined(foo)) {
+} // Better with utility
+
+// Quantity values—always unambiguous
+const money = { amountInMinorUnits: 500, currencyCode: "USD" };
+const durationMinutes = 30;
+```
+
+**Type Techniques:**
+
+- Union, intersection, conditional types for complex definitions
+- Mapped types: `Partial<T>`, `Pick<T>`, `Omit<T>`
+- `keyof`, index access types, discriminated unions
+- `as const`, `typeof`, `instanceof`, `satisfies`, type guards
+- Exhaustiveness checking with `never`
+- `readonly` for parameter immutability
+
+## Functions
+
+```typescript
+// Object arguments with interfaces
+interface CreateUserRequest {
+  email: string;
+  name?: string;
+}
+
+function createUser(request: CreateUserRequest): User {
+  const { email, name } = request; // Destructure inside
+  // ...
+}
+
+// Guard clauses for early returns
+function processOrder(order: Order): Result {
+  if (!order.isValid) {
+    return { error: "Invalid order" };
+  }
+  // Main logic
+}
+```
+
+## Objects & Arrays
+
+```typescript
+// Spread over Object.assign
+const updated = { ...original, name: "New Name" };
+
+// Array methods over loops (unless breaking early)
+const doubled = items.map((item) => item * 2);
+const sorted = items.toSorted((a, b) => a - b); // Immutable
+
+// For early exit
+for (const item of items) {
+  if (condition) break;
+}
+```
+
+## Async
+
+```typescript
+// async/await over .then()
+async function fetchData(): Promise<Data> {
+  const response = await api.get("/data");
+  return response.data;
+}
+
+// Parallel
+const results = await Promise.all(items.map(processItem));
+
+// Sequential (when needed)
+for (const item of items) {
+  // eslint-disable-next-line no-await-in-loop
+  await processItem(item);
+}
+```
+
+## Classes
+
+```typescript
+class UserService {
+  public async findById(request: FindByIdRequest): Promise<User> {}
+  private validateUser(user: User): boolean {}
+}
+
+// Extract pure functions outside classes
+function formatUserName(first: string, last: string): string {
+  return `${first} ${last}`;
+}
+```