addmon/AGENTS.md

Agent Guidelines for addmon

Development Commands

Essential Commands

• bun run dev - Start all applications in development mode
• bun run dev:web - Start only the web application on port 3001
• bun run build - Build all applications
• bun run check - Run Oxlint and Oxfmt formatting
• bun run check-types - TypeScript type checking across all apps

Web-Specific Commands (in apps/web)

• bun run check-types - TypeScript type checking for web app only
• bun run desktop:dev - Start Tauri desktop app in development
• bun run desktop:build - Build Tauri desktop app

Testing

No test framework configured - This project does not currently have tests. When adding tests, consider Vitest (already configured in oxlint settings).

Code Style Guidelines

Linting and Formatting

• Tool: Oxlint (linting) + Oxfmt (formatting)
• Configuration: Root .oxlintrc.json
• Run: bun run check (lints and auto-formats)
• All rules set to "warn" level - Never use as any, @ts-ignore, or @ts-expect-error

TypeScript Configuration

• Strict mode enabled with additional checks:
  • noUncheckedIndexedAccess - Require checks for potentially undefined array/object access
  • noUnusedLocals / noUnusedParameters - Remove unused variables
  • noFallthroughCasesInSwitch - Explicit break/return in all switch cases
• Target: ESNext with bundler module resolution
• Path alias: @/* → ./src/*

Import Order and Grouping

// 1. External libraries (React, TanStack, etc.)
import { createFileRoute } from "@tanstack/react-router";
import { cva } from "class-variance-authority";

// 2. Internal imports with @/ alias
import { cn } from "@/lib/utils";
import { Button } from "@/components/ui/button";
import Header from "@/components/header";

// 3. Type imports (use `import type` for type-only imports)
import type { VariantProps } from "class-variance-authority";

Component Patterns

• Props: Use TypeScript interfaces, prefer VariantProps for component variants
• Destructuring: Always destructure props with defaults
• Variants: Use class-variance-authority (cva) for styling variants
• Classes: Use cn() utility for class merging (from @/lib/utils)
• Exports:
  • UI components: Named exports for related components (e.g., export { Button, buttonVariants })
  • Page components: Default exports for file-based routes
• Data attributes: Use data-slot for component composition patterns

Example component structure:

function MyComponent({
  className,
  variant = "default",
  ...props
}: MyComponentProps & VariantProps<typeof myVariants>) {
  return <div className={cn(myVariants({ variant }), className)} {...props} />;
}

export { MyComponent };

Styling Guidelines

• Framework: TailwindCSS v4 with OKLCH color space
• Theme: Dark mode by default, uses next-themes provider
• CSS Variables: Use semantic color tokens (e.g., bg-background, text-foreground)
• Radius: Base radius is 0.625rem, use semantic tokens (rounded-none from shadcn pattern)
• Custom variant: Dark mode uses @custom-variant dark (&:is(.dark *))

Routing Patterns (TanStack Router)

• File-based routing: Routes in src/routes/
• Route definition:

  export const Route = createFileRoute("/")({
    component: HomePage,
  });
  

• Root route: Use createRootRouteWithContext for global context
• Router setup: defaultPreload: "intent" with pending component as <Loader />

File Organization

src/
├── components/
│   ├── ui/         # shadcn/ui primitives
│   └── *.tsx       # Application-specific components
├── routes/         # TanStack Router files
├── lib/            # Utility functions (e.g., `cn()`)
└── main.tsx        # Entry point

Naming Conventions

• Components: PascalCase (Button.tsx, UserProfile.tsx)
• Utilities: camelCase (cn(), formatDate())
• Constants: UPPER_SNAKE_CASE (TITLE_TEXT, API_URL)
• Files: kebab-case for utilities, PascalCase for components

Error Handling

• Runtime errors: Minimal current handling. Use try/catch for async operations
• Type errors: Fix directly, never suppress with type assertions
• Validation: Use Zod for schema validation (already in dependencies)

Tauri Integration

• Rust code: Located in src-tauri/src/
• Frontend-Rust bridge: Use Tauri invoke patterns
• Commands: Build with bun run desktop:build, dev with bun run desktop:dev

Project Context

• Monorepo: Turborepo with workspaces (apps/, packages/)
• Package Manager: Bun (1.3.5)
• UI Framework: React 19.2.3 with TanStack Router
• Component Library: shadcn/ui (base-lyra style, lucide icons)
• Desktop: Tauri v2 for cross-platform desktop apps

Before Submitting Changes

1. Run bun run check to lint and format code
2. Run bun run check-types to verify type safety
3. Test dev server: bun run dev:web
4. No test coverage required yet (not configured)