Skip to content

AGENTS.md

Latest commit

 

History

History
225 lines (165 loc) · 6.26 KB

AGENTS.md

File metadata and controls

225 lines (165 loc) · 6.26 KB

AGENTS.md - AI Coding Agent Guidelines

This document provides guidelines for AI coding agents working in this repository.

Project Overview

This is a Tauri 2.x desktop application with:

  • Frontend: Angular 20 (TypeScript) + Tailwind CSS v4
  • Backend: Rust (Tauri native backend)
  • Styling: Neobrutalism theme with light/dark mode support
  • Platform: Cross-platform desktop app (Windows, macOS, Linux)

Directory Structure

Directory Purpose
src/ Angular frontend source code
src/app/components/ Reusable UI components (sidenav, theme-toggle)
src/app/layouts/ Layout components (main-layout)
src/app/pages/ Page components (dashboard, accounts, quotas)
src/app/services/ Angular services (theme.service)
src/styles/ Global styles (theme_light, theme_dark, theme)
src/assets/ Static assets (images, SVGs)
src-tauri/ Rust/Tauri backend source code

Build Commands

# Development
npm run start              # Angular dev server (port 1420)
npm run tauri dev          # Full Tauri dev mode (Angular + native window)
npm run watch              # Angular watch mode

# Production
npm run build              # Build Angular frontend
npm run tauri build        # Build complete Tauri application

# Rust (from src-tauri/)
cargo build                # Build Rust backend
cargo build --release      # Build release version

Test Commands

# Angular tests
npm test                                           # Run all tests
ng test --include=**/my-component.spec.ts          # Single test file
ng test --include=**/file.spec.ts -- --grep="desc" # Single test case

# Rust tests (from src-tauri/)
cargo test                 # Run all tests
cargo test test_name       # Run specific test
cargo test -- --nocapture  # Run with output

Lint & Format Commands

# TypeScript/Angular
npm run lint               # Lint TypeScript
npx prettier --write .     # Format with Prettier

# Rust (from src-tauri/)
cargo fmt                  # Format Rust code
cargo clippy               # Run Rust linter
cargo clippy -- -D warnings # Clippy with warnings as errors

Tailwind CSS v4 Configuration

This project uses Tailwind CSS v4 with CSS-first configuration (no tailwind.config.js).

Theme Files Structure

File Purpose
src/styles/theme_light.css Light mode CSS variables (:root)
src/styles/theme_dark.css Dark mode CSS variables (.dark class)
src/styles/theme.css Tailwind imports, @theme inline, base styles
src/styles.css Main entry point, imports all theme files

Using Tailwind in Component CSS

Component CSS files must use @reference to access Tailwind utilities:

@reference "../../../styles.css";  /* Adjust path based on component location */

.my-class {
  @apply flex items-center gap-2;
  @apply bg-background text-foreground;
}

Custom Theme Colors

/* Available theme colors (defined in theme.css) */
bg-background, bg-secondary-background, bg-main
text-foreground, text-main-foreground
border-border
shadow-shadow

Code Style Guidelines

TypeScript Configuration

Strict mode enabled: strict, noImplicitReturns, strictTemplates

Import Organization

// 1. Angular packages
import { Component, inject, signal, input } from "@angular/core";

// 2. External libraries
import { LucideAngularModule, Sun, Moon } from "lucide-angular";

// 3. Local imports
import { ThemeService } from "../../services/theme.service";

Naming Conventions

Construct Convention Example
Files kebab-case theme-toggle.component.ts
Classes PascalCase ThemeToggleComponent
Variables/Functions camelCase isDark, toggleTheme
Component selectors kebab-case app-theme-toggle
Signals camelCase isCollapsed = signal(false)

Angular Patterns

// Use signals for reactive state
isCollapsed = signal(false);

// Use input() for component inputs (Angular 17+)
collapsed = input(false);

// Use inject() for dependency injection
private themeService = inject(ThemeService);

// Use explicit return types
toggle(): void {
  this.themeService.toggleTheme();
}

Formatting Rules

  • Indentation: 2 spaces
  • Quotes: Double quotes
  • Semicolons: Required
  • Trailing commas: Required in multi-line

Component Guidelines

Creating New Components

  1. Create directory: src/app/components/{name}/
  2. Create files: {name}.component.ts, {name}.component.html, {name}.component.css
  3. Use standalone components with explicit imports
  4. Add @reference in CSS for Tailwind utilities

Component Template

import { Component } from "@angular/core";

@Component({
  selector: "app-my-component",
  standalone: true,
  imports: [],
  templateUrl: "./my-component.component.html",
  styleUrl: "./my-component.component.css",
})
export class MyComponent {}

Using Lucide Icons

import { LucideAngularModule, Sun, Moon } from "lucide-angular";

@Component({
  imports: [LucideAngularModule],
})
export class MyComponent {
  readonly Sun = Sun;
  readonly Moon = Moon;
}
<lucide-icon [img]="Sun" [size]="20" />

Important Notes

  1. Dev server port: 1420 (configured in angular.json)
  2. Build output: dist/os-app/browser/
  3. App identifier: com.ken.os-app
  4. Sidenav width: 300px expanded, 64px collapsed
  5. Dark mode: Toggle via .dark class on <html> element

VS Code Extensions (Recommended)

  • tauri-apps.tauri-vscode - Tauri extension
  • rust-lang.rust-analyzer - Rust language support
  • angular.ng-template - Angular Language Service
  • bradlc.vscode-tailwindcss - Tailwind CSS IntelliSense