commit b820b69ce653b0bc99cb9f857b091d81d84be7fb Author: vader Date: Sat May 23 11:16:12 2026 +0100 Initial project scaffold and agent docs. Co-authored-by: Cursor diff --git a/.cursor/chat-context-template.md b/.cursor/chat-context-template.md new file mode 100644 index 0000000..959bbb6 --- /dev/null +++ b/.cursor/chat-context-template.md @@ -0,0 +1,31 @@ +# Copy into a new Cursor chat (fill brackets, delete this line) + +## Session +- Type: [learning | implementation | debug] +- Phase: [e.g. Phase 4 — Context discipline] +- Project: financeOne (`/home/duarte/development/financeOne`) + +## Stack +- Next.js, React, TypeScript, Tailwind (planned — see README) +- Verify: `npm run lint && npm test` (when scaffold exists) + +## How I want replies +- Concise and direct; no fluff or long summaries unless I ask. +- Ask me anything unclear (scope, constraints, tradeoffs) before big changes. + +## My profile +- Senior dev/architect; learning Cursor. +- Minimal diffs; match existing patterns; short tradeoff notes when choices matter. +- Do not commit/push unless I ask; no secrets in chat. + +## Goal (this chat) +[One sentence — what “done” looks like] + +## Already decided +- Repo prepared: README, AGENTS.md, `.cursor/rules/`, `.gitignore`, `.env.example` + +## Attachments +@README.md @AGENTS.md @.cursor/rules/ + +--- +[Phase title and your questions below] diff --git a/.cursor/rules/project-core.mdc b/.cursor/rules/project-core.mdc new file mode 100644 index 0000000..61c10d2 --- /dev/null +++ b/.cursor/rules/project-core.mdc @@ -0,0 +1,20 @@ +--- +description: Core FinanceOne project standards for all work +alwaysApply: true +--- + +# FinanceOne — core + +## Responses + +- Concise, direct, plain language. No filler or fancy phrasing. +- Ask 1–3 specific questions when scope, constraints, or approach is unclear — do not guess on large changes. + +## Code + +- Minimal, focused diffs; match existing style and layout. +- Read `AGENTS.md` and `README.md` before multi-file edits. +- No commit, push, or git config changes unless the user explicitly asks. +- No secrets in repo; `.env.local` locally; names in `.env.example` only. +- Money: integer minor units or a decimal library — not JS `number` for currency math. +- Prefer `@` references over whole-repo search when the task names files or areas. diff --git a/.cursor/rules/typescript.mdc b/.cursor/rules/typescript.mdc new file mode 100644 index 0000000..6d5f251 --- /dev/null +++ b/.cursor/rules/typescript.mdc @@ -0,0 +1,13 @@ +--- +description: TypeScript conventions for FinanceOne +globs: **/*.{ts,tsx} +alwaysApply: false +--- + +# TypeScript + +- Prefer explicit return types on exported functions and API handlers. +- Avoid `any`; use `unknown` and narrow, or small domain types. +- Use `import type` for type-only imports. +- Colocate types with features; shared types in a dedicated `types` module when reused. +- Handle errors explicitly; do not swallow failures without logging or user-visible feedback. diff --git a/.cursor/rules/web-ui.mdc b/.cursor/rules/web-ui.mdc new file mode 100644 index 0000000..f22a47f --- /dev/null +++ b/.cursor/rules/web-ui.mdc @@ -0,0 +1,13 @@ +--- +description: React and Next.js UI patterns for FinanceOne +globs: **/*.{tsx,css} +alwaysApply: false +--- + +# Web UI + +- Next.js App Router: default to Server Components; add `"use client"` only for interactivity. +- Accessible markup: labels on inputs, semantic headings, keyboard-friendly controls. +- Tailwind: reuse spacing and color patterns from nearby components; avoid one-off magic values when a token exists. +- Forms: validate on client for UX and on server for security; show clear error messages. +- Loading and empty states for lists (accounts, transactions). diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..46182ce --- /dev/null +++ b/.env.example @@ -0,0 +1,10 @@ +# Copy to .env.local and fill in. Do not commit real values. + +# App +NEXT_PUBLIC_APP_URL=http://localhost:3000 + +# Database (when added) +# DATABASE_URL= + +# Auth (when added) +# AUTH_SECRET= diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0124a29 --- /dev/null +++ b/.gitignore @@ -0,0 +1,40 @@ +# Dependencies +node_modules/ + +# Build / framework +.next/ +out/ +dist/ +build/ +.turbo/ +.vercel/ + +# Environment and secrets +.env +.env.* +!.env.example + +# Logs and debug +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + +# Testing +coverage/ +.nyc_output/ + +# IDE / OS +.idea/ +.vscode/ +*.swp +.DS_Store +Thumbs.db + +# TypeScript +*.tsbuildinfo + +# Misc +.cache/ +*.pem diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b984577 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,58 @@ +# FinanceOne — agent guide + +For Cursor Agent and other coding agents in this repo. + +## How to respond + +- **Be concise**: short paragraphs, bullets when listing. Match reply length to the task. +- **Be direct**: state facts, decisions, and next steps. No filler, hype, or “great question” openers. +- **No fluff**: skip long preambles, repeated summaries, and engagement closers unless the user asks. +- **Ask when it helps**: if scope, constraints, or “done” is unclear — or there are multiple valid approaches — ask **1–3 specific questions** before a large change. Do not guess and build the wrong thing. +- **Say what you need**: missing file paths, env, repro steps, or preferences? Ask once, clearly. + +## Project + +Personal finance web app. Small, reviewable diffs; match existing patterns. + +## Before you change code + +1. Read `README.md` for stack and verify commands. +2. Stay within the user’s request; no drive-by refactors. +3. Prefer `@` file references over whole-repo search when the task names files or areas. + +## Conventions + +- **TypeScript**: strict types; avoid `any` unless justified in a comment. +- **React / Next.js**: App Router; server components by default; `"use client"` only when needed. +- **Styling**: Tailwind utilities; match nearby components. +- **Money**: minor units (cents) or a decimal library — never raw floats for currency. +- **Secrets**: never commit `.env`, keys, or tokens; names only in `.env.example`. + +## Verification + +After substantive changes (when `package.json` exists): + +```bash +npm run lint +npm test +``` + +UI changes: note manual checks or use browser tooling if configured. + +## Git + +- Commit only when the user explicitly asks. +- No force-push to `main` / `master`. +- Do not skip git hooks unless the user asks. + +## Domain + +- **Accounts**: cash, credit, investment — clear balance semantics each. +- **Transactions**: signed amounts; categories/tags optional but consistent. +- **Reports**: aggregate from stored transactions; document timezone (UTC vs user locale). + +## Out of scope unless requested + +- New major dependencies +- Large architectural rewrites +- CI/CD or deployment changes diff --git a/README.md b/README.md new file mode 100644 index 0000000..2e4ebb8 --- /dev/null +++ b/README.md @@ -0,0 +1,69 @@ +# FinanceOne + +Personal finance web application — budgets, accounts, transactions, and reporting. + +## Stack (planned) + +| Layer | Choice | +|-------|--------| +| Runtime | Node.js 20+ | +| Framework | Next.js (App Router) | +| Language | TypeScript | +| Styling | Tailwind CSS | +| Package manager | npm | + +Adjust this table when the scaffold is generated or the stack changes. + +## Prerequisites + +- Node.js 20 or later +- npm 10+ + +## Getting started + +The application scaffold is not generated yet. After `package.json` exists: + +```bash +npm install +cp .env.example .env.local # fill values locally; never commit secrets +npm run dev +``` + +Open [http://localhost:3000](http://localhost:3000). + +## Scripts + +| Command | Purpose | +|---------|---------| +| `npm run dev` | Local development server | +| `npm run build` | Production build | +| `npm run start` | Run production build | +| `npm run lint` | ESLint | +| `npm test` | Unit / integration tests | + +Scripts appear in `package.json` once the app is scaffolded. + +## Environment variables + +See [.env.example](.env.example). Copy to `.env.local` for local development. + +## Project layout (target) + +``` +financeOne/ +├── src/ # application source (after scaffold) +├── public/ +├── .cursor/rules/ # Cursor agent guardrails +├── AGENTS.md # agent workflow and conventions +└── README.md +``` + +## Cursor / agents + +- Read [AGENTS.md](AGENTS.md) first: concise replies, ask when unclear, then conventions and verify steps. +- Rules: `.cursor/rules/`. Chat starter: `.cursor/chat-context-template.md`. +- Verify: `npm run lint` and `npm test` when available. + +## License + +Private / unlicensed unless stated otherwise.