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

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:

} 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.

4.1 KiB Raw Permalink Blame History