Altair-sh
119 lines
4.1 KiB
Markdown
119 lines
4.1 KiB
Markdown
# AGENTS.md
|
|
|
|
Guidance for AI coding agents working in this repository.
|
|
|
|
## Project
|
|
|
|
Next.js frontend for a Paradox save file parser. It uploads a game save file to a
|
|
backend service, polls until parsing finishes, and displays the result in a
|
|
grid.
|
|
|
|
- **Next.js 16** (App Router, Turbopack) with **React 19**
|
|
- **TypeScript 6**, **ESLint 9** (flat config), **Prettier 3**
|
|
- **ag-grid** for the data grid, **Bootstrap 5** for styling
|
|
|
|
Source files live in `src/`:
|
|
|
|
- `app/` for routes,
|
|
- `components/` for shared UI
|
|
- `services/` for backend calls
|
|
- `lib/` for helpers
|
|
- `config/` for app config
|
|
- `types/` for .d.ts type declaration files
|
|
|
|
## Terminal
|
|
|
|
**On Windows, prefer `bash.exe`** — but only a real MSYS2, Cygwin, or
|
|
MinGW/Git Bash installation, for example `D:\msys2\usr\bin\bash.exe`.
|
|
|
|
**Never use `C:\Windows\System32\bash.exe`.** Despite its name it is not a
|
|
POSIX bash; it is the launcher stub for WSL. Do not start WSL to run ordinary
|
|
commands.
|
|
|
|
If no MSYS/Cygwin/MinGW bash is installed, **use PowerShell** as the terminal.
|
|
PowerShell is the fallback, never WSL.
|
|
|
|
If bash reports `command not found` for `node` or `npm`, that is a `PATH`
|
|
problem rather than a missing install: MSYS2 defaults `MSYS2_PATH_TYPE` to
|
|
`minimal`, which discards the Windows `PATH`. Setting it to `inherit` fixes it.
|
|
|
|
## Commands
|
|
|
|
```sh
|
|
npm run dev # dev server
|
|
npm run build # production build
|
|
npm run lint # eslint
|
|
npm run format # prettier, rewrites files in src/
|
|
npx tsc --noEmit # typecheck
|
|
```
|
|
|
|
### Checking your work
|
|
|
|
**Always run `npm run lint` and `npm run build` after changing code.** They are
|
|
the primary way to find errors in this project, and they catch different
|
|
things:
|
|
|
|
- `npm run lint` reports code errors and style violations. It must finish with
|
|
zero problems — no errors and no warnings.
|
|
- `npm run build` catches type errors and build-time problems that lint cannot
|
|
see, such as Node APIs leaking into the edge runtime. It must exit cleanly
|
|
and print no warnings.
|
|
|
|
`npx tsc --noEmit` is a faster way to check types alone while iterating, but it
|
|
does not replace a full build.
|
|
|
|
Do not report a change as finished until both commands pass.
|
|
|
|
## Version control
|
|
|
|
This project is managed with **git**.
|
|
|
|
**Read-only git commands are fine to use without asking.**
|
|
`git status`, `git log`, `git diff`, `git show`, `git blame` and similar inspection commands
|
|
may be run freely.
|
|
|
|
**Never run a git command that changes the repository without the user's
|
|
explicit permission.**
|
|
This is a strict ban, and it covers everything that writes to the history, the index,
|
|
or the working tree including `add`, `commit`, `checkout`, `restore`, `reset`,
|
|
`stash`, `branch`, `merge`, `rebase`, `push`, `rm`, etc.
|
|
|
|
Ask first and wait for a clear yes before running such git command.
|
|
|
|
## Conventions
|
|
|
|
Prettier settings live in `.prettierrc` and are not negotiable: **4 spaces, no
|
|
semicolons, single quotes, 80 column width**. Run `npm run format` after
|
|
editing, or match the surrounding style exactly.
|
|
|
|
Import from within `src/` using the `@/` alias, for example
|
|
`import { getMsgFromError } from '@/lib/errors'`.
|
|
|
|
Write doc comments as JSDoc (`/** ... */`), which editors show on hover.
|
|
Plain `//` and `///` comments do not appear in tooltips.
|
|
In `.ts` files put only prose in the JSDoc and let the signature carry the types;
|
|
do not duplicate types in `{braces}`.
|
|
|
|
Catch blocks should not annotate the error. Let it be `unknown` and convert it
|
|
with the shared helper:
|
|
|
|
```ts
|
|
} catch (err) {
|
|
const errMsg = getMsgFromError(err)
|
|
...
|
|
}
|
|
```
|
|
|
|
Avoid `any`; `no-explicit-any` is enforced. Prefer `unknown` plus narrowing.
|
|
|
|
## Things that will bite you
|
|
|
|
**TypeScript is pinned to 6 on purpose.** Do not upgrade it to 7. The Next.js
|
|
ESLint config depends on typescript-eslint, which refuses to run under
|
|
TypeScript 7, and that would break `npm run lint` entirely.
|
|
|
|
**`instrumentation.ts` is compiled for the edge runtime too and it can't be disabled.**
|
|
Anything using `fs`, `path`, or other Node APIs must be imported behind the
|
|
`process.env.NEXT_RUNTIME === 'nodejs'` guard, or the build warns and pulls
|
|
Node-only code into the edge bundle.
|