From f049cbc36a53eb0139f106e6421c2e193ace25f1 Mon Sep 17 00:00:00 2001 From: Peter Dave Hello Date: Fri, 3 Oct 2025 00:18:26 +0800 Subject: [PATCH] Add AGENTS.md (comprehensive agent guide) Mainly generated by codex-cli v0.42.0, with gpt-5-codex high, and this AGENTS.md construction prompt: - https://gist.github.com/PeterDaveHello/f30c38a156982a35683edfd5ece2d474 This guide captures the repository structure, tooling, and safety checks so contributors and coding agents can quickly grasp the project architecture, stay aligned, and deliver efficient, well-vetted changes with confidence. Reference: - https://agents.md/ --- AGENTS.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..e8ba00e06 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,76 @@ +# Repository Guidelines + +## Dos and Don’ts + +- Do run `npm install` before linting or building; scripts expect local `node_modules`. +- Do follow the existing React context and hook pattern (`src/context`, `src/hooks`) instead of introducing ad-hoc globals. +- Do run `npm run lint` and `npm run build` locally before opening a PR; CI (`.github/workflows/build.yml`) blocks on them. +- Do keep sharing features conditional on `VITE_BACKEND_URL`; handle the unset case gracefully as in `src/api/gists.js`. +- Don't reformat, rename, or move unrelated files; let Prettier format only the lines you touch. +- Don't add dependencies, commit `.env` values, or check in generated output (`dist`, `node_modules`). + +## Project Structure and Module Organization + +DrawDB is a Vite-powered React app for designing database diagrams and exporting SQL. + +- `src/` holds production code: routing in `App.jsx`, the entry point in `main.jsx`, and Tailwind styles in `index.css`. +- `src/pages/` contains top-level routes (Editor, LandingPage, Templates, BugReport, NotFound). +- `src/context/` and `src/hooks/` expose per-domain state (diagram, settings, undo/redo, etc.); components consume these rather than manual prop chains. +- `src/components/` contains UI modules (canvas, headers, panels); `src/utils/` and `src/data/` consolidate helpers and static data. +- `src/i18n/locales/` stores locale objects; `src/i18n/i18n.js` wires i18next. +- `public/` holds static assets; `index.html`, `vite.config.js`, `tailwind.config.js`, and `postcss.config.js` define the build surface. +- CI workflows live in `.github/workflows/`; Docker artefacts sit in `Dockerfile` and `compose.yml`. + +## Build, Test, and Development Commands + +Use Node 18 or 20 (matching `.github/workflows/build.yml`) and npm v9+. + +- Install dependencies: `npm install`. +- Start the dev server: `npm run dev` (append `-- --host` when sharing the server, as in `compose.yml`). +- Lint the codebase: `npm run lint`; for targeted checks, `npx eslint src/components/FloatingControls.jsx`. +- Produce a production bundle: `npm run build`; preview it via `npm run preview`. +- Container builds rely on the provided `Dockerfile`; adjust tags in `.github/workflows/docker.yml` rather than inventing new scripts. + +## Coding Style and Naming Conventions + +- Prettier (`.prettierrc.json`) enforces 2-space indentation, double quotes, trailing commas, and semicolons; do not override these defaults. +- ESLint (`.eslintrc.cjs`) extends the React recommended rules; fix `react-refresh` warnings by keeping component exports pure. +- Favor functional React components with PascalCase filenames; hooks must start with `use` and live in `src/hooks`. +- Keep module paths relative to `src/`; extend existing barrel files (e.g., `src/hooks/index.js`) when adding exports. +- Styling relies on Tailwind via `src/index.css`; prefer utility classes and theme tokens over bespoke CSS. +- Comments, variable names, and new translations stay in English unless you are working inside `src/i18n/locales`. + +## Testing Guidelines + +- The repo currently has no automated test suite; regressions are caught through linting and production builds. +- Reproduce fixes through `npm run dev` and targeted manual checks (e.g., validate diagram interactions or exports touched by your change). +- When adding automated coverage, align with Vite/Vitest conventions (co-locate `*.test.jsx` near the module) and confirm the approach with maintainers before introducing new tooling. +- Document manual verification steps in the PR description so reviewers can replay them. + +## Commit and Pull Request Guidelines + +- Base changes off `main`; keep diffs focused and self-contained. +- Follow CONTRIBUTING.md: imperative, capitalized subject lines with an empty line before the body; reference issues when relevant. +- Ensure `npm run lint` and `npm run build` succeed locally; the Build workflow runs both on Node 18 and 20. +- Explain behavioral changes, screenshots, or recordings for UI updates; include locale notes when editing `src/i18n/locales`. +- Use English in commit messages and reviews, matching recent history (e.g., `Update and improve zh-TW Traditional Chinese locale`). + +## Safety and Permissions + +- Ask before adding dependencies, renaming/moving files, or changing build/CI configuration. +- It is safe to read files, inspect history, run scoped lint/build commands, and create small focused patches without prior approval. +- Never commit secrets or share tokens; populate `.env` locally from `.env.sample`, and keep `VITE_BACKEND_URL` unset when backend sharing is not configured. +- Avoid force pushes to shared branches and do not delete user data, diagrams, or locale files without coordination. + +## Architecture Overview + +- Editor state is centralized in contexts under `src/context` (diagram structure, layout, undo/redo, tasks); hooks in `src/hooks` expose domain-specific selectors and mutations. +- API interactions live in `src/api/` (`gists.js`, `email.js`) and depend on `VITE_BACKEND_URL`; ensure features degrade gracefully when the backend is unavailable. +- Export/import workflows sit under `src/utils/exportAs`, `src/utils/importFrom`, and SQL helpers; reuse these helpers instead of duplicating logic in components. +- Templates and seed data live in `src/templates/` and `src/data/`; reference them when adding onboarding or sample content. + +## Security and Configuration Tips + +- Use `.env.sample` as the single source for environment variables; document new keys there when needed. +- When enabling sharing or analytics features locally, supply `VITE_BACKEND_URL` via `.env`, and clear the value before committing. +- Keep dependencies updated via npm; Docker and CI already rely on `npm ci`/`npm install`, so do not introduce alternate package managers.