@clipboard-health/ai-rules 1.2.0 → 1.2.2

package/backend/CLAUDE.md

@@ -1,219 +1 @@
-<!-- Source: .ruler/backend/nestJsApis.md -->
-
-# NestJS APIs
-
-- Use a three-tier architecture:
-  - Controllers in the entrypoints tier translate from data transfer objects (DTOs) to domain objects (DOs) and call the logic tier.
-  - Logic tier services call other services in the logic tier and repos and gateways at the data tier. The logic tier operates only on DOs.
-  - Data tier repos translate from DOs to data access objects (DAOs), call the database using either Prisma for Postgres or Mongoose for MongoDB, and then translate from DAOs to DOs before returning to the logic tier.
-- Use ts-rest to define contracts using Zod schemas, one contract per resource.
-- A controller implements each ts-rest contract.
-- Requests and responses follow the JSON:API specification, including pagination for listings.
-- Use TypeDoc to document public functions, classes, methods, and complex code blocks.
-
-<!-- Source: .ruler/backend/notifications.md -->
-
-# Notifications
-
-Send notifications through [Knock](https://docs.knock.app) using the `@clipboard-health/notifications` NPM library.
-
-## Usage
-
-<embedex source="packages/notifications/examples/usage.md">
-
-1. Search your service for a `NotificationJobEnqueuer` instance. If there isn't one, create and export it:
-
-   ```ts
-   import { NotificationJobEnqueuer } from "@clipboard-health/notifications";
-
-   import { BackgroundJobsService } from "./setup";
-
-   // Create and export one instance of this in your microservice.
-   export const notificationJobEnqueuer = new NotificationJobEnqueuer({
-     // Use your instance of `@clipboard-health/mongo-jobs` or `@clipboard-health/background-jobs-postgres` here.
-     adapter: new BackgroundJobsService(),
-   });
-   ```
-
-1. Implement a minimal job, calling off to a NestJS service for any business logic and to send the notification.
-
-   ```ts
-   import { type BaseHandler } from "@clipboard-health/background-jobs-adapter";
-   import { type NotificationData } from "@clipboard-health/notifications";
-   import { isFailure, toError } from "@clipboard-health/util-ts";
-
-   import { type ExampleNotificationService } from "./exampleNotification.service";
-
-   export type ExampleNotificationData = NotificationData<{
-     workplaceId: string;
-   }>;
-
-   export const EXAMPLE_NOTIFICATION_JOB_NAME = "ExampleNotificationJob";
-
-   // For mongo-jobs, you'll implement HandlerInterface<ExampleNotificationData["Job"]>
-   // For background-jobs-postgres, you'll implement Handler<ExampleNotificationData["Job"]>
-   export class ExampleNotificationJob implements BaseHandler<ExampleNotificationData["Job"]> {
-     public name = EXAMPLE_NOTIFICATION_JOB_NAME;
-
-     constructor(private readonly service: ExampleNotificationService) {}
-
-     async perform(data: ExampleNotificationData["Job"], job: { attemptsCount: number }) {
-       const result = await this.service.sendNotification({
-         ...data,
-         // Include the job's attempts count for debugging, this is called `retryAttempts` in `background-jobs-postgres`.
-         attempt: job.attemptsCount + 1,
-       });
-
-       if (isFailure(result)) {
-         throw toError(result.error);
-       }
-     }
-   }
-   ```
-
-1. Search your service for a constant that stores workflow keys. If there isn't one, create and export it:
-
-   ```ts
-   export const WORKFLOW_KEYS = {
-     eventStartingReminder: "event-starting-reminder",
-   } as const;
-   ```
-
-1. Enqueue your job:
-
-   ```ts
-   import {
-     EXAMPLE_NOTIFICATION_JOB_NAME,
-     type ExampleNotificationData,
-   } from "./exampleNotification.job";
-   import { notificationJobEnqueuer } from "./notificationJobEnqueuer";
-   import { WORKFLOW_KEYS } from "./workflowKeys";
-
-   async function enqueueNotificationJob() {
-     await notificationJobEnqueuer.enqueueOneOrMore<ExampleNotificationData["Enqueue"]>(
-       EXAMPLE_NOTIFICATION_JOB_NAME,
-       // Important: Read the TypeDoc documentation for additional context.
-       {
-         /**
-          * Set expiresAt at enqueue-time so it remains stable across job retries. Use date-fns in your
-          * service instead of this manual calculation.
-          */
-         expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),
-         // Set idempotencyKey at enqueue-time so it remains stable across job retries.
-         idempotencyKey: {
-           resourceId: "event-123",
-         },
-         // Set recipients at enqueue-time so they respect our notification provider's limits.
-         recipients: ["userId-1"],
-
-         workflowKey: WORKFLOW_KEYS.eventStartingReminder,
-
-         // Any additional enqueue-time data passed to the job:
-         workplaceId: "workplaceId-123",
-       },
-     );
-   }
-
-   // eslint-disable-next-line unicorn/prefer-top-level-await
-   void enqueueNotificationJob();
-   ```
-
-1. Trigger the job in your NestJS service:
-
-   ```ts
-   import { type NotificationClient } from "@clipboard-health/notifications";
-
-   import { type ExampleNotificationData } from "./exampleNotification.job";
-
-   type ExampleNotificationDo = ExampleNotificationData["Job"] & { attempt: number };
-
-   export class ExampleNotificationService {
-     constructor(private readonly client: NotificationClient) {}
-
-     async sendNotification(params: ExampleNotificationDo) {
-       const { attempt, expiresAt, idempotencyKey, recipients, workflowKey, workplaceId } = params;
-
-       // Assume this comes from a database and are used as template variables...
-       // Use @clipboard-health/date-time's formatShortDateTime in your service for consistency.
-       const data = { favoriteColor: "blue", favoriteAt: new Date().toISOString(), secret: "2" };
-
-       // Important: Read the TypeDoc documentation for additional context.
-       return await this.client.trigger({
-         attempt,
-         body: {
-           data,
-           recipients,
-           workplaceId,
-         },
-         expiresAt: new Date(expiresAt),
-         idempotencyKey,
-         keysToRedact: ["secret"],
-         workflowKey,
-       });
-     }
-   }
-   ```
-
-</embedex>
-
-<!-- Source: .ruler/common/codeStyleAndStructure.md -->
-
-# Code style and structure
-
-- 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.
-
-# Commit messages
-
-- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
-
-<!-- Source: .ruler/common/errorHandlingAndValidation.md -->
-
-# Error handling and validation
-
-- 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`.
-
-<!-- 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.
-
-<!-- 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`.
+@AGENTS.md

package/common/CLAUDE.md

@@ -1,61 +1 @@
-<!-- Source: .ruler/common/codeStyleAndStructure.md -->
-
-# Code style and structure
-
-- 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.
-
-# Commit messages
-
-- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
-
-<!-- Source: .ruler/common/errorHandlingAndValidation.md -->
-
-# Error handling and validation
-
-- 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`.
-
-<!-- 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.
-
-<!-- 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`.
+@AGENTS.md