initial commit
This commit is contained in:
@@ -0,0 +1,244 @@
|
||||
# AGENTS.md
|
||||
|
||||
This file contains guidelines and commands for agentic coding agents working in
|
||||
the Veridian repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
Veridian is a Nuxt 4 application built with TypeScript, using PostgreSQL with
|
||||
Drizzle ORM, better-auth for authentication, and UnoCSS for styling. The app is
|
||||
an agnetic chat platform that is meant to provide a well rounded experience for
|
||||
interacting with LLMs as well as providing a way to manage agents and provide
|
||||
helpful tools like RAG (retrieval augmented generation) and web scraping/search.
|
||||
|
||||
You should be connected to the Nuxt docs MCP server, if you need to reference
|
||||
the documentation or are unsure on how to implement something, consult the
|
||||
docs.
|
||||
|
||||
## Core Commands
|
||||
|
||||
As an agentic agent, never run the development server yourself.
|
||||
Instead, once you have completed your task, end generation and inform me that
|
||||
you are done and request a review of your changes. You are allowed to use
|
||||
database commands.
|
||||
|
||||
### Database Commands
|
||||
|
||||
- `tsx db/migrate.ts` - Run database migrations
|
||||
- `bun x @better-auth/cli@latest generate --output db/auth/auth.schema.ts` -
|
||||
Generate authentication schema based on `lib/auth.ts`
|
||||
- `bun x drizzle-kit generate` - Generate migration files
|
||||
- `bun x drizzle-kit push` - Push schema changes to database
|
||||
- `bun x drizzle-kit studio` - Open Drizzle Studio for database inspection
|
||||
|
||||
## Tech Stack & Dependencies
|
||||
|
||||
- **Framework**: Nuxt 4 (SSR enabled)
|
||||
- **Language**: TypeScript with strict configuration
|
||||
- **Database**: PostgreSQL with Drizzle ORM
|
||||
- **Auth**: better-auth with email/password and social providers
|
||||
- **Styling**: UnoCSS with presetMini
|
||||
- **Icons**: @nuxt/icon with Iconify, use Myna UI Icons
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
**Follow the LLVM golden rule: If you are extending, enhancing, or bug fixing
|
||||
already implemented code, use the style that is already being used so that
|
||||
the source is uniform and easy to follow.**
|
||||
|
||||
- **Always end lines with a semicolon regardless of surrounding code**
|
||||
- Use 4 spaces for indentation
|
||||
- Use consistent naming conventions for variables, functions, and constants
|
||||
- Always use strict equality checks (`===` and `!==`) instead of loose equality
|
||||
checks (`==` and `!=`)
|
||||
- Prefer using explicity equality checks over truthy/falsy checks
|
||||
e.g., prefer `if (value !== null)` instead of `if (value)`
|
||||
- Always check existing code patterns before implementing new features
|
||||
- Follow existing component and composable structures
|
||||
- Use proper TypeScript types for all function parameters and returns
|
||||
- Implement proper cleanup in composables (e.g., useClickOutside)
|
||||
- Prefer reactive state management over direct DOM manipulation
|
||||
- Keep components focused and single-purpose
|
||||
- Use semantic HTML elements where appropriate
|
||||
|
||||
### General Structure
|
||||
|
||||
- Use Nuxt's app directory structure (`app/`, `server/`, `lib/`)
|
||||
- Auth configuration in `lib/auth.ts`
|
||||
- Server API routes go in `server/api/`
|
||||
- Composables go in `app/composables/`
|
||||
- Database schema in `db/schema.ts`
|
||||
- Database migrations in `db/migrations/`
|
||||
|
||||
### TypeScript Guidelines
|
||||
|
||||
- Use strict TypeScript with no implicit any
|
||||
- Export types and interfaces explicitly
|
||||
- Use `computed()` and `ref()` from Vue 3 reactivity system
|
||||
- Type API responses and database models
|
||||
|
||||
### Vue Components
|
||||
|
||||
- **Never use self-closing tags, excluding images, br, hr, and input**
|
||||
- Use `<script setup lang="ts">` syntax
|
||||
- Strongly prefer composition API over options API
|
||||
- Prefer composables for shared state management
|
||||
- Maintain consistent 4-space indentation
|
||||
- Use PascalCase for component file names
|
||||
|
||||
### CSS/Styling
|
||||
|
||||
- Use UnoCSS utility classes exclusively
|
||||
- Never use margin for spacing, always prefer flexbox or grid
|
||||
- Prefer inline utility classes over custom CSS
|
||||
- Use semantic color variables: `--color-base`, `--color-neutral`, `--color-accent`, `--color-subtle`
|
||||
If you need to add new color variables, they are located in `app/assets/css/base.css`,
|
||||
along with a general CSS reset.
|
||||
- Apply consistent spacing and layout patterns
|
||||
- Use responsive prefixes only when necessary
|
||||
|
||||
### Imports
|
||||
|
||||
- Order imports: Vue/Nuxt imports first, then local files, then dependencies
|
||||
- `~/` is an alias for `app/` and `~~/` is an alias for the root of the project
|
||||
- Avoid wildcard imports
|
||||
- Keep imports sorted alphabetically within groups
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- **Page**: camelCase
|
||||
- **Composables**: camelCase
|
||||
- **Components**: PascalCase when referenced in templates
|
||||
- **Functions/Variables**: camelCase
|
||||
- **Constants**: UPPER_SNAKE_CASE for environment variables only
|
||||
- **Database tables**: snake_case
|
||||
- **API routes**: kebab-case path segments
|
||||
|
||||
### Database Patterns
|
||||
|
||||
- Use Drizzle ORM with PostgreSQL
|
||||
- Export all schemas from `db/schema.ts`
|
||||
- Use environment variables for database credentials
|
||||
- `db/auth/auth.schema.ts` is a generated file, do not touch it. If you need to
|
||||
change the authentication schema, edit `lib/auth.ts` and run the generation
|
||||
script.
|
||||
|
||||
### Error Handling
|
||||
|
||||
- Use proper TypeScript error types
|
||||
- Implement try-catch blocks for database operations
|
||||
- Provide user-friendly error messages in API responses
|
||||
- Log errors appropriately without exposing sensitive data
|
||||
|
||||
### Performance Guidelines
|
||||
|
||||
- Leverage Nuxt's auto-imports and code splitting
|
||||
- Use `useState()` for shared state across components
|
||||
- Implement proper loading states with async operations
|
||||
- Optimize database queries and use indexes where needed
|
||||
|
||||
## Authentication Implementation
|
||||
|
||||
The app uses better-auth with:
|
||||
|
||||
- Email/password authentication (configurable via env vars)
|
||||
- Drizzle adapter for PostgreSQL
|
||||
- Session management through cookies
|
||||
- Auth plugins in `app/plugins/` for client/server initialization
|
||||
- Global auth middleware in `app/middleware/auth.global.ts`
|
||||
|
||||
All users must be signed in to view pages aside from authentication pages.
|
||||
(located in `app/pages/auth/`), you do not need to check if session or user
|
||||
objects are null or undefined, use the non-null assertion operator (`!`) where
|
||||
necessary. In API routes, you can use `protectRoute` to guarantee that the
|
||||
user must be authenticated.
|
||||
|
||||
## File Organization
|
||||
|
||||
```
|
||||
|-- app/ # Application code
|
||||
│ |-- components/ # Vue components
|
||||
│ |-- composables/ # Reuseable composition functions
|
||||
│ |-- layouts/ # Layout components
|
||||
│ |-- middleware/ # Route middleware
|
||||
│ |-- pages/ # File-based routing
|
||||
│ \-- plugins/ # Vue/Nuxt plugins
|
||||
|-- server/ # Server-side code
|
||||
│ \-- api/ # API routes
|
||||
|-- db/ # Database related files
|
||||
│ |-- schema.ts # Database schema
|
||||
│ |-- migrate.ts # Migration runner
|
||||
│ \-- migrations/ # Migration files
|
||||
\-- lib/ # Shared utilities
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
Currently no test framework is configured, and tests are not currently a
|
||||
requirement.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Key environment variables:
|
||||
|
||||
- `DATABASE_URL` - PostgreSQL connection string
|
||||
- `BETTER_AUTH_SECRET` - Authentication secret
|
||||
- `DISABLE_LOCAL_AUTH` - Disable email/password auth
|
||||
- `DISABLE_SIGNUP` - Disable user registration
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Composables Pattern
|
||||
|
||||
```typescript
|
||||
export const useFeature = () => {
|
||||
const state = useState<Type>('feature:state', () => defaultValue)
|
||||
const computed = computed(() => /* logic */)
|
||||
|
||||
const actions = {
|
||||
// methods
|
||||
}
|
||||
|
||||
return { state, computed, ...actions }
|
||||
}
|
||||
```
|
||||
|
||||
### API Route Pattern
|
||||
|
||||
API routes are defined in `server/api/` and are exported as a single object.
|
||||
|
||||
File names contain information about the route, e.g. `user.get.ts` specifies a
|
||||
GET route to `/user`. This applies for all HTTP methods.
|
||||
|
||||
```typescript
|
||||
// an example GET route to /user
|
||||
export default defineEventHandler(async (event) => {
|
||||
try {
|
||||
// implementation
|
||||
return { success: true, data: result };
|
||||
} catch (error) {
|
||||
throw createError({
|
||||
statusCode: 500,
|
||||
statusMessage: "Error description",
|
||||
});
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
```typescript
|
||||
import { users } from "~~/db/schema";
|
||||
|
||||
// an example POST route to /user
|
||||
export default defineEventHandler(async (event) => {
|
||||
const body = await readBody(event);
|
||||
|
||||
const { email, name, password } = body;
|
||||
|
||||
const [user] = await db
|
||||
.insert(users)
|
||||
.values({ email, name, password })
|
||||
.returning();
|
||||
|
||||
return user;
|
||||
});
|
||||
```
|
||||
Reference in New Issue
Block a user