246 lines
6.4 KiB
Markdown
246 lines
6.4 KiB
Markdown
# Agent Instructions — Codex (Nuxt 3 + FastAPI, Greenfield, Mock-First)
|
|
|
|
This repository contains a **Nuxt 3 frontend**.
|
|
A **FastAPI** backend will be developed in parallel (may be in a separate repo/service).
|
|
|
|
You are an automated coding agent (Codex).
|
|
|
|
Your job is to make **precise, minimal, correct changes** while strictly following these rules.
|
|
Do not guess. If required information is missing, stop and ask one clear question.
|
|
|
|
This is an early-stage project. Prefer **simple, explicit patterns**.
|
|
|
|
---
|
|
|
|
## Repository Structure
|
|
|
|
- Root directory:
|
|
- Deployment artifacts: `Dockerfile`, `deploy/docker-compose.yml`
|
|
- Nuxt application lives in `NautilusDeskTimeFrontend/`
|
|
|
|
- `NautilusDeskTimeFrontend/app/`
|
|
- Nuxt application source (pages, layouts, components, composables)
|
|
|
|
- `NautilusDeskTimeFrontend/server/`
|
|
- Nuxt/Nitro server code may exist
|
|
- Backend business logic belongs in FastAPI, not here
|
|
|
|
- `NautilusDeskTimeFrontend/public/`
|
|
- Static assets served as-is
|
|
|
|
- Generated output (DO NOT EDIT):
|
|
- `NautilusDeskTimeFrontend/.nuxt/`
|
|
- `NautilusDeskTimeFrontend/.output/`
|
|
|
|
---
|
|
|
|
## Commands (Frontend)
|
|
|
|
Run all frontend commands from `NautilusDeskTimeFrontend/`.
|
|
|
|
- `npm install`
|
|
- `npm run dev` (`http://localhost:3000`)
|
|
- `npm run build`
|
|
- `npm run preview`
|
|
- `npm run generate` (if used)
|
|
|
|
Do not modify build scripts unless explicitly instructed.
|
|
|
|
---
|
|
|
|
## Tech Stack
|
|
|
|
Frontend:
|
|
- Nuxt 3
|
|
- Vue 3 (Composition API only)
|
|
- TypeScript
|
|
- Vite
|
|
- Tailwind CSS
|
|
- Plain CSS is allowed when needed
|
|
|
|
Backend (separate service):
|
|
- FastAPI
|
|
- JWT authentication
|
|
|
|
Do not introduce new dependencies unless explicitly requested.
|
|
|
|
---
|
|
|
|
## Global Coding Rules (Strict)
|
|
|
|
- Prefer clarity over abstraction
|
|
- Keep diffs small and scoped
|
|
- Do not refactor unless asked
|
|
- Do not change behavior unless asked
|
|
- Do not remove code unless instructed
|
|
- Avoid speculative features
|
|
- Do not add comments explaining obvious code
|
|
|
|
When no established pattern exists yet:
|
|
- introduce a simple, conventional pattern
|
|
- apply it consistently
|
|
- do not over-engineer
|
|
|
|
---
|
|
|
|
## Vue & Nuxt Conventions
|
|
|
|
### Components
|
|
- Use `<script setup lang="ts">`
|
|
- No Options API
|
|
- No class-based components
|
|
- Props and emits must be typed
|
|
- Avoid `any` and unsafe casts
|
|
- Components must do one job
|
|
|
|
### Pages & Routing
|
|
- Use Nuxt file-based routing
|
|
- Page files in `app/pages/` use lowercase filenames
|
|
- Use `definePageMeta` for layout, middleware, SEO
|
|
- Do not manually configure routes
|
|
|
|
### Composables
|
|
- Prefix composables with `use`
|
|
- No side effects at import time
|
|
- Return only what is required
|
|
- Keep UI concerns out of composables
|
|
|
|
---
|
|
|
|
## Backend Integration (FastAPI)
|
|
|
|
### Source of Truth
|
|
- Backend business logic will live in FastAPI
|
|
- Do not create new `/server/api/*` endpoints in Nuxt unless explicitly instructed
|
|
- Nuxt server code is infrastructure only (optional proxy/SSR helpers)
|
|
|
|
### API Contract & Mocking (IMPORTANT)
|
|
- The FastAPI API may not exist yet.
|
|
- If OpenAPI schema is not available, use **mock data** to build the frontend.
|
|
|
|
Rules for mock data:
|
|
- Mock data must be centralized in a single place (e.g. `app/mocks/`).
|
|
- Mocks should match likely real shapes (typed interfaces).
|
|
- Switching from mock to real API must be easy:
|
|
- Use a single API layer (e.g. `app/composables/useApi.ts` or `app/services/api/`).
|
|
- Pages/components must not directly embed mock fixtures.
|
|
- Prefer feature flags via runtime config (e.g. `useMockApi`) only if needed.
|
|
- Do not invent endpoints; if endpoints are unknown, create placeholders and document assumptions in code only when necessary.
|
|
|
|
### API Access
|
|
- Use `$fetch` for HTTP calls from composables/stores.
|
|
- Use `useFetch` / `useAsyncData` in pages/components when SSR-friendly loading is needed.
|
|
- Do not hardcode hostnames/ports.
|
|
|
|
### Configuration
|
|
- FastAPI base URL must come from runtime config or environment variables.
|
|
- If config keys do not exist yet, create them in `nuxt.config` using conventional names:
|
|
- `runtimeConfig.public.apiBaseUrl`
|
|
- Keep client-only values in `runtimeConfig.public`.
|
|
|
|
---
|
|
|
|
## Authentication (JWT)
|
|
|
|
JWT will be used for authentication.
|
|
|
|
Rules:
|
|
- Do not assume token storage strategy unless specified.
|
|
- Default strategy (if not otherwise specified):
|
|
- Store JWT in memory (Pinia) and optionally persist using existing project preference when defined.
|
|
- Do not implement auth flows that require backend behavior not defined yet.
|
|
- If backend endpoints for auth are unknown, build UI using mock auth responses and typed models.
|
|
|
|
When adding auth:
|
|
- Centralize token attach logic in the API layer (single place).
|
|
- Do not sprinkle Authorization header logic across components.
|
|
- Use `Authorization: Bearer <token>` when making authenticated requests.
|
|
|
|
If any auth detail is unclear (login endpoint, refresh tokens, expiry behavior):
|
|
- Stop and ask one question.
|
|
|
|
---
|
|
|
|
## State Management
|
|
|
|
- Use Pinia only if needed and keep it minimal
|
|
- One store per domain
|
|
- Setup-style stores only
|
|
- Handle async errors explicitly
|
|
- Stores must not manipulate the DOM
|
|
|
|
---
|
|
|
|
## Styling
|
|
|
|
- Use Tailwind by default
|
|
- Plain CSS is allowed when needed
|
|
- Avoid inline styles unless unavoidable
|
|
- Keep `.vue` indentation at **4 spaces**
|
|
|
|
---
|
|
|
|
## TypeScript Rules
|
|
|
|
- Be explicit with types
|
|
- Prefer narrowing over casting
|
|
- Avoid `any`
|
|
- Avoid `as unknown as`
|
|
|
|
---
|
|
|
|
## Testing & Validation
|
|
|
|
- No test framework is configured yet
|
|
- Validate changes by running `npm run dev`
|
|
- Manually exercise affected routes/features
|
|
- If tests are added, document how to run them
|
|
|
|
---
|
|
|
|
## Git Rules (MANDATORY)
|
|
|
|
For every logical change:
|
|
1. Make the change
|
|
2. `git status` must be clean after commit
|
|
3. Commit with a concise imperative message
|
|
4. Push the commit
|
|
|
|
Rules:
|
|
- One logical change per commit
|
|
- Do not mix unrelated changes
|
|
- Do not leave uncommitted changes
|
|
|
|
If commit or push cannot be completed:
|
|
- Stop
|
|
- Explain why
|
|
- Ask one concise question
|
|
|
|
---
|
|
|
|
## Output Requirements
|
|
|
|
When responding with code changes:
|
|
- Modify only relevant files
|
|
- Do not include unchanged files
|
|
- Do not include explanations unless explicitly requested
|
|
- Do not include emojis or conversational text
|
|
- Prefer minimal diffs
|
|
|
|
---
|
|
|
|
## Failure Handling
|
|
|
|
If a task cannot be completed safely:
|
|
- Stop
|
|
- State what is missing
|
|
- Ask one clear question
|
|
|
|
---
|
|
|
|
You are a deterministic Nuxt 3 frontend coding agent.
|
|
Build against mock data when the API is not available.
|
|
Integrate with FastAPI via runtime-configured base URLs.
|
|
Use JWT auth via Bearer tokens when endpoints are defined.
|
|
Maintain clean git history with commit+push for each change.
|