xonecas.io
53129
Pa

PAT / commit 84b4ad0

feat: trim down AGENTS.md by removing redundant or repeat info

xonecas2025-12-17 84b4ad0116ab2d219066653e9f62e9ed63e86305 parent f0dd25b

1 file changed

AGENTS.md+21−179
@@ -2,69 +2,24 @@
22
33 This is a personal assistant project, that renders a simple assistant chat layout as a web page, and provides access to an agentic model running locally via ollama. The project uses Next.js for it's typescript framework TailwindCSS for it's styling, and Ollama's typescript/javascript library itself for querying the model.
44
5+You are assisting a developer to implement new features, fix bugs, and maintain the project.
6+
57 ## Project Commands
68
7-All commands should be run from the project root directory:
8-
9-- **Development Server**: `npm run dev` - Starts the Next.js development server
10-- **Build**: `npm run build` - Builds the production-ready Next.js application
11-- **Start Production**: `npm run start` - Starts the production server (requires build first)
12-- **Lint**: `npm run lint` - Runs ESLint to check code quality
13-- **Format**: `npm run format` - Formats all files with Prettier
14-- **Format Check**: `npm run format:check` - Checks code formatting without making changes
15-- **Test**: `npm test` - Runs tests in watch mode using Vitest
16-- **Test UI**: `npm run test:ui` - Opens Vitest UI for interactive test running
17-- **Test Run**: `npm run test:run` - Runs tests once and exits
18-- **DB Generate**: `npm run db:generate` - Generates database migrations using Drizzle Kit
19-- **DB Migrate**: `npm run db:migrate` - Runs database migrations
20-- **DB Studio**: `npm run db:studio` - Opens Drizzle Studio for database management
9+All commands should be run from the project root directory.
10+Commands are listed in [package.json](./package.json) in the scripts section. Use npm to run commands: `npm run <command>`.
2111
2212 ## Dependencies
2313
24-### Production Dependencies
25-
26-Agents MUST use only these existing dependencies. Do NOT add new dependencies without explicit approval:
27-
28-- **next**: ^16.0.10 - Next.js framework
29-- **react**: 18.2.0 - React library
30-- **react-dom**: 18.2.0 - React DOM rendering
31-- **tailwindcss**: ^3.4.0 - Utility-first CSS framework
32-- **@tailwindcss/typography**: ^0.5.x - Tailwind CSS plugin for beautiful typographic defaults
33-- **typescript**: ^5.4.2 - TypeScript compiler
34-- **ollama**: ^0.6.3 - Official Ollama npm package for model interaction
35-- **@googleapis/customsearch**: ^7.0.1 - Google Custom Search API client
36-- **googleapis**: ^169.0.0 - Google APIs client library
37-- **autoprefixer**: ^10.4.17 - CSS post-processor
38-- **postcss**: ^8.4.30 - CSS transformation tool
39-- **drizzle-orm**: ^0.45.1 - TypeScript ORM for SQL databases
40-- **better-sqlite3**: ^12.5.0 - Fast SQLite3 database driver
41-- **react-markdown**: ^10.1.0 - React component for rendering markdown
42-- **remark-gfm**: ^4.0.1 - GitHub Flavored Markdown plugin for remark
43-- **rehype-highlight**: ^7.0.2 - Syntax highlighting plugin for rehype
44-- **highlight.js**: ^11.11.1 - Syntax highlighting library
45-
46-### Dev Dependencies
47-
48-- **@types/node**: ^20.11.18 - TypeScript types for Node.js
49-- **@types/react**: ^18.2.55 - TypeScript types for React
50-- **@types/react-dom**: ^18.2.19 - TypeScript types for React DOM
51-- **eslint**: ^8.56.0 - JavaScript/TypeScript linter
52-- **eslint-config-next**: ^13.5.6 - Next.js ESLint configuration
53-- **prettier**: ^3.2.5 - Code formatter
54-- **prettier-plugin-tailwindcss**: ^0.5.11 - Prettier plugin for sorting Tailwind CSS classes
55-- **drizzle-kit**: ^0.31.8 - Drizzle ORM migration and introspection tool
56-- **@types/better-sqlite3**: ^7.6.13 - TypeScript types for better-sqlite3
57-- **vitest**: ^4.0.16 - Fast unit test framework for Vite
58-- **@vitest/ui**: ^4.0.16 - Vitest UI for interactive test running
14+Use only these existing dependencies.
15+Do NOT add new dependencies without explicit approval.
16+Dependencies are listed in the file [package.json](./package.json).
5917
6018 ## Code Style Guidelines
6119
62-### TypeScript Configuration
63-
64-- **Strict Mode**: Disabled (`strict: false` in tsconfig.json)
65-- **Target**: ES2017
66-- **Module**: ESNext
67-- **JSX**: React JSX transform (`react-jsx`)
20+Always make sure the code is linted, formatted and the tests are passing.
21+Always update existing tests.
22+Add tests when prompted only.
6823
6924 ### Code Style Rules
7025
@@ -103,12 +58,10 @@ Agents MUST use only these existing dependencies. Do NOT add new dependencies wi
10358 - API routes should return `NextResponse` objects
10459
10560 6. **Styling**:
61+ - Avoid using CSS whenever possible
10662 - Use TailwindCSS utility classes exclusively
10763 - Inline Tailwind classes in JSX
108- - Follow existing patterns: `className="flex flex-col bg-neutral-200 dark:bg-neutral-900 p-4"`
10964 - Use responsive design utilities when appropriate
110- - Set default text colors on topmost container to cascade: `text-neutral-800 dark:text-neutral-200`
111- - Use neutral color palette (not slate or gray)
11265 - **Markdown Styling**: Use Tailwind Typography plugin with `prose` classes for markdown content
11366 - Use `prose prose-neutral dark:prose-invert max-w-none` for assistant messages
11467 - The typography plugin is configured in `tailwind.config.js`
@@ -116,11 +69,9 @@ Agents MUST use only these existing dependencies. Do NOT add new dependencies wi
11669
11770 7. **Code Formatting**:
11871 - Use Prettier for code formatting: `npm run format` to format all files
119- - Prettier configuration is in `.prettierrc` (2 spaces, semicolons, double quotes, 100 char width)
72+ - Prettier configuration is in `.prettierrc`
12073 - Prettier automatically sorts Tailwind CSS classes via `prettier-plugin-tailwindcss`
121- - Use consistent indentation (2 spaces)
122- - Add trailing commas in multi-line objects/arrays
123- - Use semicolons
74+
12475
12576 8. **Error Handling**:
12677 - Use `console.error` for errors
@@ -128,86 +79,15 @@ Agents MUST use only these existing dependencies. Do NOT add new dependencies wi
12879 - Return user-friendly error messages in API responses
12980 - Handle API errors gracefully with try/catch blocks
13081
131-9. **File Headers**:
132- - Optional: Add file path comments at the top of library files (e.g., `/* personal-assistant-thing/src/lib/ollama.ts */`)
133-
134-10. **Imports**:
82+9. **Imports**:
13583 - Use absolute imports with `@/` prefix for local files (e.g., `import PaperPlaneIcon from "@/src/components/icons/PaperPlaneIcon"`)
13684 - Group imports: external packages first, then local imports
13785 - Use named imports from libraries (e.g., `import { NextResponse } from "next/server"`)
13886 - Use default imports for component files (e.g., `import PaperPlaneIcon from "@/src/components/icons/PaperPlaneIcon"`)
13987 - Path alias `@/` is configured in `tsconfig.json` to point to the project root
14088
141-## Project Structure
142-
143-```
144-/home/xonecas/src/personal-assistant-thing/
145-├── app/
146-│ ├── api/
147-│ │ ├── chat/
148-│ │ │ └── route.ts # Chat API endpoint
149-│ │ └── threads/
150-│ │ ├── route.ts # Threads API endpoint (GET, POST)
151-│ │ └── [id]/
152-│ │ └── messages/
153-│ │ └── route.ts # Thread messages API endpoint
154-│ ├── globals.css # Global styles
155-│ ├── highlight-theme.css # Syntax highlighting theme
156-│ ├── layout.tsx # Root layout component
157-│ └── page.tsx # Main page component
158-├── src/
159-│ ├── components/
160-│ │ ├── icons/
161-│ │ │ ├── ChevronDownIcon.tsx # Reusable icon components
162-│ │ │ ├── PaperPlaneIcon.tsx
163-│ │ │ └── PlusIcon.tsx
164-│ │ ├── MessageInput.tsx # Message input form component
165-│ │ ├── NoThreadSelected.tsx # Welcome screen when no thread selected
166-│ │ └── Sidebar.tsx # Sidebar component with thread selection
167-│ ├── hooks/
168-│ │ └── useTheme.ts # Custom hook for theme management
169-│ ├── lib/
170-│ │ ├── db/
171-│ │ │ ├── index.ts # Database connection and setup
172-│ │ │ └── schema.ts # Drizzle ORM schema definitions
173-│ │ ├── cache.ts # File-based caching utility with TTL support
174-│ │ ├── debug.ts # Debug logging utility (development only)
175-│ │ ├── ratelimit.ts # Reusable rate limiting utility using cache
176-│ │ ├── ratelimit.test.ts # Tests for rate limiting utility
177-│ │ └── ollama/
178-│ │ ├── index.ts # Ollama API wrapper with tool calling support
179-│ │ ├── duckduckgo.ts # DuckDuckGo Instant Answer tool
180-│ │ ├── weather.ts # Open-Meteo weather tool
181-│ │ └── websearch.ts # Google Custom Search tool
182-├── drizzle/ # Generated migration files
183-│ ├── meta/ # Migration metadata
184-│ └── *.sql # SQL migration files
185-├── data/ # Database files (created at runtime)
186-│ ├── database.db # SQLite database file
187-│ └── cache.json # Cache file (created automatically)
188-├── drizzle.config.ts # Drizzle Kit configuration
189-├── vitest.config.ts # Vitest test framework configuration
190-├── package.json
191-├── tsconfig.json
192-└── tailwind.config.js
193-```
194-
19589 ## Key Implementation Details
19690
197-### UI Style
198-
199-- Always ensure support for both light and dark modes
200-- Use neutral color palette for backgrounds and text (not gray or slate)
201-- Default text colors: `text-neutral-800 dark:text-neutral-200` (set on topmost container to cascade)
202-- Container backgrounds: `bg-neutral-100` for light mode, `bg-neutral-950` for dark mode
203-- Child component backgrounds: `bg-neutral-200` for light mode, `bg-neutral-900` for dark mode
204-- User message backgrounds: `bg-neutral-300` for light mode, `bg-neutral-800` for dark mode
205-- Assistant message backgrounds: `bg-neutral-200` for light mode, `bg-neutral-900` for dark mode
206-- Don't use round corners
207-- The UI should always fit to the available space
208-- Primary colors: green-500 for dark mode, green-900 for light mode
209-- margins and paddings shouldn't stack, use gaps when possible
210-
21191 ### Ollama Integration
21292
21393 - Default model: `gpt-oss`
@@ -283,13 +163,6 @@ Agents MUST use only these existing dependencies. Do NOT add new dependencies wi
283163 - `npm test` - Run tests in watch mode
284164 - `npm run test:ui` - Open Vitest UI for interactive testing
285165 - `npm run test:run` - Run tests once and exit
286-- **Test Coverage**: Currently includes comprehensive tests for `ratelimit.ts` covering:
287- - Initial state creation
288- - Rate limit checking and enforcement
289- - Request counting and incrementing
290- - Window expiration and automatic reset
291- - Manual reset functionality
292- - Edge cases and integration scenarios
293166 - **Mocking**: Tests use Vitest's mocking capabilities to isolate units (e.g., cache module is mocked in rate limiter tests)
294167
295168 ### Database Integration (Drizzle ORM)
@@ -308,46 +181,14 @@ Agents MUST use only these existing dependencies. Do NOT add new dependencies wi
308181 - **Foreign Keys**: Enabled automatically in database connection
309182 - **Usage**: Import `db` from `src/lib/db/index.ts` to query the database
310183
311-### Component Structure
312-
313-- **Home** (`app/page.tsx`): Main page component that orchestrates the chat interface. Loads threads on mount but does not automatically select the latest thread - user must manually select a thread or create a new one. Messages are rendered with ReactMarkdown using Tailwind Typography prose classes for assistant messages.
314-- **Sidebar** (`src/components/Sidebar.tsx`): Sidebar with thread selection, new thread button, and theme selector
315-- **MessageInput** (`src/components/MessageInput.tsx`): Input form for sending messages with keyboard history navigation (ArrowUp/ArrowDown to cycle through previous user messages)
316-- **NoThreadSelected** (`src/components/NoThreadSelected.tsx`): Welcome screen displayed when no thread is selected, shows PAT introduction, current time (updates every second), and thread count. Uses ReactMarkdown with Tailwind Typography prose classes.
317-- **useTheme** (`src/hooks/useTheme.ts`): Custom hook managing theme state (device/dark/light) with localStorage persistence and automatic device preference detection
318-
319-### Type Definitions
320-
321-- **Types** (`src/lib/db/schema.ts`): TypeScript types inferred from Drizzle ORM schema
322- - `Thread`: Thread type with id, title, createdAt, updatedAt (inferred from `threads` table)
323- - `Message`: Message type with id, threadId, role, content, createdAt, generationTimeMs, toolCalls (inferred from `messages` table)
324- - Types are exported using `$inferSelect` and should be imported directly from the schema module
325-
326-### Chat API Flow
327-
328-1. Client sends POST request to `/api/chat` with `{ message: string, threadId: number }`
329-2. API route fetches previous messages from the thread
330-3. API route stores the user message
331-4. API route calls Ollama with the full conversation history
332-5. API route stores the assistant response with generation time and tool calls (if any)
333-6. API route returns `{ answer: string }`
334-
335-### Threads API
336-
337-- **GET** `/api/threads`: Returns list of all threads sorted by most recent
338-- **POST** `/api/threads`: Creates a new thread with optional title, returns the created thread
339-- **GET** `/api/threads/[id]/messages`: Returns all messages for a specific thread
340-
341184 ## Development Workflow
342185
343-1. Start development server: `npm run dev`
344-2. Make code changes
345-3. Test in browser (typically `http://localhost:3000`)
346-4. Write/update tests: `npm test` (watch mode) or `npm run test:ui` (interactive UI)
347-5. Format code: `npm run format`
348-6. Run linter: `npm run lint`
349-7. Run tests: `npm run test:run` (verify all tests pass)
350-8. Build for production: `npm run build`
186+1. Make code changes
187+2. Ask the user to test in browser
188+3. Update existing tests and add more if prompted to.
189+4. Format code: `npm run format`
190+5. Run linter: `npm run lint`
191+6. Run tests: `npm run test:run` (verify all tests pass)
351192
352193 ## Important Constraints
353194
@@ -355,6 +196,7 @@ Agents MUST use only these existing dependencies. Do NOT add new dependencies wi
355196 - **DO NOT** change TypeScript strict mode settings
356197 - **DO NOT** modify Next.js or React versions
357198 - **DO NOT** Commit secrets or API keys, edit `node_modules/` or `vendor/`
199+- **DO NOT** Erase any data without explicit approval
358200 - **DO** maintain existing code style and patterns
359201 - **DO** use existing utility functions from `src/lib/`
360202 - **DO** follow the App Router conventions for Next.js 16