AGENTS.md

Rama main · réplica de lectura del repositorio original.

<!-- Generated by Ruler -->


<!-- Source: .ruler/rules.md -->

# Uptimekit Rules

## Project Structure

This is a monorepo with the following structure:

### Apps

- **`apps/dash/`** - Dashboard and public status page application (Next.js)
- **`apps/docs/`** - Documentation site (Next.js)

### Packages

- **`packages/api/`** - Shared API logic and types (oRPC)
- **`packages/auth/`** - Authentication logic and utilities (Better Auth)
- **`packages/db/`** - Database schema and utilities (Drizzle ORM)
- **`packages/config/`** - Shared configuration
- **`packages/scheduler/`** - Job scheduling utilities

## Available Scripts

- `pnpm run dev` - Start all apps in development mode

## Database Commands

All database operations should be run from the web workspace:

- `pnpm run db:push` - Push schema changes to database
- `pnpm run db:studio` - Open database studio
- `pnpm run db:generate` - Generate Drizzle files
- `pnpm run db:migrate` - Run database migrations

Database schema files are located in `packages/db/src/schema/`

Schema includes:

- `auth.ts` - User authentication and session management
- `monitors.ts` - Monitor configurations
- `status-pages.ts` - Status page definitions
- `incidents.ts` - Incident tracking
- `maintenance.ts` - Scheduled maintenance
- `status-updates.ts` - Status update entries
- `integrations.ts` - Third-party integrations (Discord, Slack, etc.)
- `workers.ts` - Worker configurations
- `ssl-notifications.ts` - SSL certificate expiry notifications
- `configuration.ts` - Global configuration settings

## API Structure

- oRPC endpoints are in `packages/api/src/api/`
- Client-side API utils are in `apps/web/src/utils/api.ts`

## Authentication

Authentication is enabled in this project:

- Server auth logic is in `packages/auth/src/lib/auth.ts`
- Web app auth client is in `apps/web/src/lib/auth-client.ts`

## Key Points

- This is a Turborepo monorepo using pnpm workspaces
- Each app has its own `package.json` and dependencies
- Run commands from the root to execute across all workspaces
- Run workspace-specific commands with `pnpm run command-name`
- Turborepo handles build caching and parallel execution

## Code Guidelines

### Formatting & Style

- **Consistency**: Rely on Prettier and ESLint to enforce standard formatting.
- **Imports**: Organize imports logically (External packages -> Internal monorepo packages -> Relative imports).
- **Naming**: Use `camelCase` for functions/variables and `PascalCase` for components/interfaces. Make names descriptive (e.g., `fetchUserData` instead of `getData`).

### Functions

- **Single Responsibility**: Functions should aim to do one thing well.
- **Guard Clauses**: Use early returns to reduce nesting and cognitive load.
- **Size**: Keep functions small. distinct logic blocks should often be extracted into helper functions.
- **Parameters**: Limit the number of arguments (max ~3). Use a configuration object for more complex signatures.

### Comments

- **Self-Documenting Code First**: Write code that is self-explanatory through clear function names, variable names, and structure. If your function name and code clearly describe what it does, **do not add unnecessary comments**.
- **Explain "Why", Not "What"**: The code itself explains what is happening. Use comments to explain the *intent*, business logic, or complex decisions behind the code.
- **Avoid Clutter**: Do not comment obvious logic (e.g., `// Update count` above `count++`). Unnecessary comments add noise and maintenance burden.
- **Function headers**: Use JSDoc/TSDoc for public-facing utilities to document params and return values, but only when the signature isn't self-evident.
- **TODOs**: Use `// TODO:` to mark areas for improvement, but address them sooner rather than later.

## UI Components

### Select Component

Use the Select component with the following pattern:

```tsx
import {
  Select,
  SelectItem,
  SelectContent,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select";

const items = [
  { label: "Next.js", value: "next" },
  { label: "Vite", value: "vite" },
  { label: "Astro", value: "astro" },
];

export default function Particle() {
  return (
    <Select aria-label="Select framework" defaultValue="next">
      <SelectTrigger>
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        {items.map(({ label, value }) => (
          <SelectItem key={value} value={value}>
            {label}
          </SelectItem>
        ))}
      </SelectContent>
    </Select>
  );
}
```

<!-- BEGIN:turborepo-agent-rules -->

# This is NOT the Turborepo you know

Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the `turbo` package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run `node -p "require.resolve('turbo/package.json')"` from a workspace that depends on `turbo`.

Read `docs/README.md` inside that installed package first, then read the relevant pages from its `docs/` directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access.

This block is written and re-added by `turbo` before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in `crates/turborepo-cli/src/cli/agent_guidance.rs`. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set `"agentGuidance": false` in the root `turbo.json` or `turbo.jsonc` to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation.
<!-- END:turborepo-agent-rules -->