diff --git a/.claude/skills b/.claude/skills new file mode 120000 index 00000000..3e73f3a3 --- /dev/null +++ b/.claude/skills @@ -0,0 +1 @@ +../.github/skills \ No newline at end of file diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 42fed839..93650b3a 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -10,7 +10,7 @@ School attendance management system: teachers, students, classes, attendance rep - **Shared submodules**: `client/shared` -> `nra-client`, `server/shared` -> `nra-server` Initialize before first use: `git submodule update --init --recursive` -Never modify code in `client/shared` or `server/shared` directly — those are separate repos. +Avoid modifying code in `client/shared` or `server/shared` directly when possible — they're separate repos used by other projects. Prefer keeping changes local to this repo. If a change genuinely belongs in the shared code, it's fine to edit it there and go through the normal commit/push flow for that repo. ## Testing @@ -51,4 +51,26 @@ Auth: JWT via `server/shared/auth/`. Permissions: `client/shared/utils/permissio **3. Surgical Changes** — Touch only what is necessary. Do not improve adjacent code or formatting. Match existing style. Every changed line must trace to the user's request. -**4. Goal-Driven Execution** — Define verifiable success criteria before starting. For multi-step tasks, write a brief plan with checkpoints and verify each one. \ No newline at end of file +**4. Goal-Driven Execution** — Define verifiable success criteria before starting. For multi-step tasks, write a brief plan with checkpoints and verify each one. + +**5. Update the Roadmap** — Every new client-facing feature (new page, user-visible capability, UI flow) gets an entry at the end of `client/src/roadmapFeatures.js` (array is `.reverse()`d for display, newest first): +```js +{ html: '', status: 'בוצע', statusColor: 'success' } +``` +Skip for internal/backend-only changes. + +## Skills + +`.github/skills/` (symlinked from `.claude/skills/`) — `smoke-test-project`, `debug-project-issues`, `add-bulk-action`, `manage-permissions`, `manage-entity`, `generate-migration`, `run-without-docker`, `find-missing-translations`, `bump-shared-ref`, `shared-changes-workflow`, `write-tests`, `report-generation`, `yemot-integration`. Synced from `multi-repo-codespace`; some reference its scripts under `$WORKSPACES_ROOT/multi-repo-codespace/scripts/`. + +## Communication Style +You are in caveman mode. Follow these rules on EVERY response, no exceptions: +- Drop articles (a, an, the). +- Drop filler words (just, really, actually, simply). +- Drop pleasantries (sure, certainly, happy to, "Let me know if you need anything else"). +- Short synonyms only (e.g., use "fix" instead of "implement a solution"). +- No hedging (skip "might be worth considering" or "it appears that"). +- Sentence fragments are fine. +- Technical terms, exact code blocks, commands, and error paths must stay exact. +- Code speaks for itself. If asked for code, give code. No explanation unless explicitly asked. +- Do not restate or repeat the user's question back to them. \ No newline at end of file diff --git a/.github/skills/add-bulk-action/SKILL.md b/.github/skills/add-bulk-action/SKILL.md new file mode 100644 index 00000000..4d22786a --- /dev/null +++ b/.github/skills/add-bulk-action/SKILL.md @@ -0,0 +1,79 @@ +--- +name: add-bulk-action +description: Use when adding a new bulk action (a button that runs an operation on the rows selected in a list/datagrid) or modifying an existing one, in any NRA project. +--- + +# Skill: Add or Modify a Bulk Action + +> **Use this skill when:** asked to add a new bulk action to an entity's list, or to change what an existing bulk action does. + +--- + +## Context + +Only the generic *plumbing* for bulk actions lives in the shared submodules and is reused by all four NRA projects: +- Client base components: `client/shared` (submodule `nra-client`) → `components/crudContainers/` +- Server base plumbing: `server/shared` (submodule `nra-server`) → `base-entity/` + +A specific bulk action's wiring and business logic is **project-local by default** — it lives in that project's own `client/src/entities/.jsx` and `server/src/entity-modules/.config.ts`, not in the shared submodules. It only becomes shared (usable by other projects) if you deliberately extract it: +- Client: a reusable preset button component in `client/shared/components/crudContainers/` (like `BulkFixReferenceButton.jsx`), which other projects' entity files can then import. +- Server: a reusable util in `server/shared/utils/entity/` (like `fixReference.util.ts`), which other projects' service overrides can then call. + +Don't extract to shared unless the action (or its logic) is genuinely reusable across projects — a one-off action just needs the project-local wiring below. + +A bulk action has two halves that are linked by a single **name string**: +- **Client**: a button rendered in an entity's `Datagrid`, which calls `dataProvider.action(resource, name, params)`. +- **Server**: a `case` in that entity's `doAction()` override, matched on `req.parsed.extra.action === name`. + +The request flow: button click → `POST /:resource/action?extra.action=&extra.ids=&...` → `BaseEntityController.doAction` → `Service.doAction` → your `switch` case. + +## Client-side building blocks (`client/shared/components/crudContainers/`) + +| Component | Use for | Notes | +|---|---|---| +| `BulkActionButton.jsx` | A generic action, fire-and-forget or with a params form | Calls `dataProvider.action(resource, name, { 'extra.ids': selectedIds, ...formData })` | +| `BulkReportButton.jsx` | An action that downloads a generated file | Calls `dataProvider.execAndDownload(resource, 'report?...', ...)` instead | +| `BulkFixReferenceButton.jsx` | Thin preset over `BulkActionButton` for the `fixReferences` action | Copy this pattern for other one-off preset buttons | +| `BulkRequestButton.jsx` | Shared UI both of the above use | Renders a plain button, or (if you pass `children` inputs) a dialog to collect extra params first, caching last-used values | + +Common props: `name` (must match the server-side `action` string), `label`, `icon`, `reloadOnEnd` (refresh the list after the mutation), `defaultRequestValues`, and `children` (react-admin `` elements) if the action needs user-supplied parameters. + +## Steps: add a new bulk action + +0. **Decide scope**: is this action specific to one project, or genuinely reusable across the four NRA apps? Default to project-local (steps 1-2 below); only add to `client/shared`/`server/shared` if reuse is the actual goal (see Context). +1. **Client** — in the entity file (`client/src/entities/.jsx`): + - Import `BulkActionButton` (or `BulkReportButton`), or import a shared preset if one already fits (e.g. `BulkFixReferenceButton`). + - Add an entry to that file's `additionalBulkButtons` array with a unique `key` and a `name` — pass `children` inputs if the action needs params. + - Pass `additionalBulkButtons={additionalBulkButtons}` to `CommonDatagrid` (already wired if the file already has other bulk buttons). + - If the action should be reusable across projects, build the preset in `client/shared/components/crudContainers/` instead (following `BulkFixReferenceButton.jsx`) and import it from there. +2. **Server** — in `server/src/entity-modules/.config.ts`: + - Override `doAction(req, body)` on the entity's service class (extend `BaseEntityService`) if not already overridden. + - Add a `case '':` to the `switch (req.parsed.extra.action)` matching the client's `name`. + - Read ids/params via `@shared/utils/queryParam.util` helpers (`getAsNumberArray`, `getAsDate`, `getAsBoolean`) off `req.parsed.extra`. + - Do the work, then `return` a user-facing (Hebrew) result string. Fall through to `super.doAction(req, body)` for unmatched actions. + - If the logic is genuinely reusable across projects, extract it into a util in `server/shared/utils/entity/` (following `fixReference.util.ts`) and call that from the `case`. +3. Restart the project (`bash scripts/start-project.sh `) and verify: select rows in the entity's list, trigger the button, confirm the success/error notification and (if `reloadOnEnd`) the list refresh. + +## Steps: modify an existing bulk action + +1. Find the button by its `name`/`label` in `client/src/entities/.jsx`. +2. Find the matching `case '':` in that entity's `doAction()` in `server/src/entity-modules/.config.ts`. +3. Change client-side params (add/remove `children` inputs) and/or server-side logic together — they share the `extra.*` param names. + +## Reference example (`fixReferences`, on `Klass`) + +- Client wiring: `client/src/entities/klass.jsx` — `additionalBulkButtons` array, `` +- Client preset: `client/shared/components/crudContainers/BulkFixReferenceButton.jsx` +- Server: `server/src/entity-modules/klass.config.ts` — `KlassService.doAction`, `case 'fixReferences'` +- Shared util: `server/shared/utils/entity/fixReference.util.ts` + +Other examples worth reading: `klass.jsx` also has `klassAttendanceReport` (a `BulkReportButton` with a params dialog and file download), and `user.jsx` has `bulkUpdatePaid`. + +## Troubleshooting + +| Symptom | Likely cause | +|---|---| +| Button click does nothing / no network request | `name` prop missing, or button not included in `additionalBulkButtons` passed to `CommonDatagrid` | +| Server returns "done nothing" | No `case` matches `req.parsed.extra.action` — check the `name` strings match exactly on both sides | +| Params form fields come back `undefined` on the server | Field `source` name doesn't match what you read via `req.parsed.extra.` | +| Selected rows don't clear after the action | `BulkActionButton`/`BulkReportButton` call `onUnselectItems()` on success — check your custom implementation does too if you wrote one from scratch | diff --git a/.github/skills/bump-shared-ref/SKILL.md b/.github/skills/bump-shared-ref/SKILL.md new file mode 100644 index 00000000..18119914 --- /dev/null +++ b/.github/skills/bump-shared-ref/SKILL.md @@ -0,0 +1,106 @@ +--- +name: bump-shared-ref +description: Use when moving one project's client/shared (nra-client) or server/shared (nra-server) submodule pointer to a newer commit or branch, and figuring out whether the project's own code needs to change to match. Use when asked to "bump the shared ref/submodule", "update client/shared or server/shared", or "pull in a shared change" for a single project. +--- + +# Skill: Bump a Shared Submodule Reference + +> **Use this skill when:** you need to move one project's `client/shared` (→ `nra-client`) or `server/shared` (→ `nra-server`) submodule pointer forward to a newer commit/branch, and determine whether the consuming project needs any code changes to go with it. + +This is the single-project, single-submodule bump flow. If instead you're *making a new change* in the shared repo and need to roll it out across all five projects, use the `shared-changes-workflow` skill — that skill covers authoring the shared change; this one covers consuming an already-known target commit/branch, in one project, on either the client or server side. + +--- + +## Context + +Every NRA project pins each shared submodule to one specific commit — visible via `git submodule status` (a `-` prefix means uninitialized, `+` means the checked-out commit differs from what's committed, no prefix means clean and in sync). Moving that pointer touches two repos: the submodule directory's own git history moves to a new commit, and the parent project repo must commit that new commit hash as a change to its own tree (the "gitlink"). + +A bump is never purely mechanical. Because `client/shared`/`server/shared` code is consumed by all five NRA projects, a behavior or API change there can silently break a project that isn't updated to match. Treat every bump as: identify what changed, decide what (if anything) the consumer needs to change, then move the pointer and make that change together. + +The exact same process applies to both submodules: `client/shared` (`nra-client` repo, client-side JSX/React-Admin code) and `server/shared` (`nra-server` repo, server-side TypeScript/NestJS code). + +## Steps + +### 1. Identify the gap + +```bash +cd /workspaces//client/shared # or server/shared +git fetch origin +git log --oneline HEAD.. # commits you're about to pick up +``` + +This is the set of commits step 2 checks against `CONSUMER_CHANGES.md`. + +### 2. Read the consumer changes doc + +Each shared repo maintains `CONSUMER_CHANGES.md` at its root: a table of commits that don't work automatically after a bump, what each one adds, the required per-app action, and which apps have already done it. + +```bash +cat client/shared/CONSUMER_CHANGES.md # or server/shared/CONSUMER_CHANGES.md +``` + +For every row whose commit falls within the gap from step 1: +- This project already listed in **Done in** → nothing to do. +- Not listed → apply that row's **Per-app action** to this project. + +This is the primary source for step 1's contract-diffing question — the shared repo's own commits already document what needs consumer follow-up, so you don't need to grep the diff for breaking changes yourself. Only fall back to reading the raw diff if a commit in the gap looks contract-affecting but has no row in `CONSUMER_CHANGES.md` — treat it the same as a listed row, and flag that the shared repo's doc is missing an entry for it. + +### 3. Bump the pointer + +```bash +cd /workspaces//client/shared # or server/shared +git checkout +cd /workspaces/ +git add client/shared # or server/shared +``` + +This stages only the gitlink change (the submodule's new pinned commit) — nothing else. + +### 4. Make the consumer changes identified in step 2 + +Edit the affected project-local files (`client/src/...` or `server/src/...`, e.g. `entities/.jsx`, `entity-modules/.config.ts`) to match the new shared contract. Scope this to exactly what step 2 flagged — a bump is not an opportunity to refactor unrelated consumer code. + +### 5. Commit together + +```bash +git add client/shared client/src/ # adjust for client vs server side +git commit -m "chore: bump client/shared to + +- +- " +``` + +Commit the pointer bump and its required consumer changes as one unit. A pointer bump that needed a consumer change but didn't get one leaves the project broken at that commit. + +### 6. Verify (only if you made a consumer change) + +A pointer-only bump with no row applying to this project needs no separate verification step. When step 2 did require a consumer change, run the relevant test suite (`cd client && yarn test`, `cd server && yarn test`) and, only if the change needs manual/UI checking, start the stack (`run-one-project` skill) and exercise the affected flow. + +--- + +## The main-branch rule (critical) + +- **On a feature/dev branch:** the submodule pointer may reference *any* commit or branch tip of `nra-client`/`nra-server` — including a commit that only exists on an unmerged branch — while you're iterating. +- **Once the project's branch is merged into its own `main`:** the submodule pointer must point to a commit that is on `nra-client`'s (or `nra-server`'s) `main` branch. A project's `main` must never end up pinning `client/shared`/`server/shared` to a commit that lives only on some other branch of the shared repo. + +Before merging the project's branch into its `main`: +1. Confirm the shared-repo commit you depend on is actually merged into `nra-client`'s/`nra-server`'s `main` (check via the GitHub MCP tools, or ask the user to merge the shared PR first if it isn't). +2. Re-point the submodule to that `main` commit: + ```bash + cd /workspaces//client/shared # or server/shared + git fetch origin main + git checkout main && git pull origin main + ``` +3. Re-stage and re-commit the pointer (steps 3 and 5 above) so the project's PR carries a `main`-pinned commit before it merges. + +This rule is identical for both submodules — there is no client/server exception. + +## Troubleshooting + +| Symptom | Likely cause | +|---|---| +| `git submodule status` shows a `-` prefix | Submodule not initialized — run `git submodule update --init --recursive` first | +| `git submodule status` shows a `+` prefix | Checked-out commit differs from what the parent repo has committed — someone bumped the working tree without staging/committing the gitlink, or checked out a different commit locally | +| Project's tests pass locally but another NRA project breaks | Expected — each project bumps its shared pointer independently and on its own schedule; the other project simply hasn't picked up this commit yet | +| A project's `main` points to a shared commit that isn't on the shared repo's `main` | The main-branch rule above was skipped — re-point to a real `main` commit of the shared repo and push a follow-up fix immediately | +| Nothing in `CONSUMER_CHANGES.md` applies, but something breaks at runtime anyway | The shared repo's doc is missing an entry for a commit in the gap — check `git log`/`git diff` for that commit directly, apply the fix, and flag the missing row | diff --git a/.github/skills/debug-project-issues/SKILL.md b/.github/skills/debug-project-issues/SKILL.md new file mode 100644 index 00000000..3b9bb643 --- /dev/null +++ b/.github/skills/debug-project-issues/SKILL.md @@ -0,0 +1,168 @@ +--- +name: debug-project-issues +description: Use when a project returns HTTP 500, containers fail to start, migrations are missing, or login/dashboard errors occur. +--- + +# Skill: Debug Project Issues + +> **Use this skill when:** a project returns HTTP 500, containers fail to start, migrations are missing, or login/dashboard errors occur. + +--- + +## Diagnostic Checklist + +Work through these steps in order. Stop at the first step that reveals the problem. + +### Step 1 — Check container status + +```bash +cd /workspaces/ +docker-compose ps +``` + +All three services (`client`, `server`, `database`) should show `Up`. If any are `Exit` or `Restarting`, inspect their logs (Step 2). + +### Step 2 — Read container logs + +```bash +# Last 50 lines of server logs +docker-compose logs --tail=50 server + +# Last 50 lines of database logs +docker-compose logs --tail=50 database + +# Follow logs in real time +docker-compose logs -f server +``` + +Common log patterns: + +| Log Message | Meaning | +|------------|---------| +| `TypeORM connection failed` | DB container not ready yet; wait 10 s and retry | +| `Migration ... not applied` | Run migrations (see Step 3) | +| `ECONNREFUSED` | Service trying to reach DB before it's ready | +| `Cannot read property ... of undefined` | Entity mapping issue in server code | + +### Step 3 — Check migration status + +Connect to the database: + +```bash +# Replace port with the project's DB port (3306 / 3316 / 3326 / 3336 / 3346 / 3356) +docker exec -it -database-dev \ + mysql -u root -proot -e "SELECT * FROM migrations ORDER BY timestamp DESC LIMIT 20;" +``` + +Container name prefix per project: +- `react-admin-nestjs` → `ran-database-dev` +- `event-management-nra` → `event-database-dev` +- `teacher-report-nra` → `teacher-database-dev` +- `student-report-nra` → `student-database-dev` +- `dnd-management-nra` → `dnd-database-dev` +- `form-call` → `form-call-database-dev` + +If migrations are missing, trigger a re-run: + +```bash +# The dev server command already runs migrations on start. +# Restart the server container to re-run them: +docker-compose restart server +docker-compose logs -f server # watch for "Migrations applied" +``` + +### Step 4 — Run the endpoint smoke test to isolate failing routes + +```bash +cd /workspaces//server +set -a && . helpers/endpoints.env && set +a +BACKEND_URL=http://localhost: \ + sh shared/utils/testing/test-all-endpoints-runner.sh +``` + +A 500 on a specific endpoint narrows the problem to that entity's resolver, service, or migration. + +### Step 5 — Identify the error type + +| Error | Category | Next action | +|-------|---------|------------| +| 401 on `/auth/login` | Auth | Check `ADMIN_USER`/`ADMIN_PASSWORD` env vars | +| 500 on `/auth/login` | DB issue | Check DB connection and migrations | +| 500 on entity endpoint | Data or mapping | Check entity definition and DB schema | +| 404 on entity endpoint | Route not registered | Check `entities.module.ts` | + +--- + +## Restart a Single Container + +```bash +cd /workspaces/ +docker-compose restart server # restart server without losing DB state +``` + +## Full Reset (destroys database volumes) + +```bash +cd /workspaces/ +docker-compose down -v # -v removes named volumes (DB data) +docker-compose up -d client server database +``` + +Wait ~60 s for migrations to re-run from scratch. + +--- + +## Login Smoke Test + +1. Open `http://localhost:/login` +2. Sign in: `admin_user` / `admin_password` +3. URL should leave `/login` and reach the dashboard + +If login succeeds but the dashboard shows a 500, the problem is in the data layer, not auth. + +--- + +## Common Issues and Fixes + +### "No .env found" + +```bash +cd /workspaces/ +cp .env.template .env +``` + +### "docker-compose.override.yml not found" + +```bash +cd /workspaces/ +cp docker-compose.override.yml.template docker-compose.override.yml +``` + +### node_modules missing inside container + +The volume mount path must match the actual `node_modules` location. Check `docker-compose.override.yml`: + +```yaml +volumes: + - ./client:/app + - ./client/node_modules:/app/node_modules # must point to real dir or valid symlink +``` + +If `node_modules` is a broken symlink, run `bash /workspaces/multi-repo-codespace/setup-node-modules.sh`. + +### Submodule not initialized + +```bash +cd /workspaces/ +git submodule update --init --recursive +``` + +--- + +## Escalation + +If none of the above steps resolve the issue: +1. Note the exact error from `docker-compose logs server` +2. Note which endpoints fail in the smoke test +3. Check if the same endpoint fails in a freshly reset project (with `-v` down) +4. Compare the entity definition in `entities.module.ts` against the migration files in `server/src/migrations/` diff --git a/.github/skills/find-missing-translations/SKILL.md b/.github/skills/find-missing-translations/SKILL.md new file mode 100644 index 00000000..a6028802 --- /dev/null +++ b/.github/skills/find-missing-translations/SKILL.md @@ -0,0 +1,89 @@ +--- +name: find-missing-translations +description: Use when auditing an NRA project's client for untranslated fields, or when asked to "find missing translations", "check for untranslated fields", or after adding/editing entity filters and inputs in domainTranslations.js. +--- + +# Skill: Find (and Fix) Missing Translations + +> **Use this skill when:** you need to check whether every field used by a project's entities has a Hebrew translation, or a user reports a raw English/camelCase field name showing up in the UI instead of Hebrew text. + +--- + +## Context + +React-Admin resolves every field/filter label via `resources..fields.` in `client/src/domainTranslations.js`. **A missing key never throws or fails a build** — react-admin just falls back to rendering the raw `source` string (e.g. `school:$cont` or `klassTypeReferenceId`) instead of Hebrew text. This only surfaces by eyeballing the UI, which is easy to miss — especially for filter fields, where the translation key must include any ReactAdmin operator suffix (`:$cont`, `:$gte`, `:$lte`, `:$isnull`, ...) verbatim, e.g. `'school:$cont': 'בית ספר'`, separately from the plain `school: 'בית ספר'` entry used by the column header. + +`scripts/find-missing-translations.js` (in this repo) statically scans a project's `client/src/entities/*.jsx` files for every `source="..."` usage and cross-checks it against `domainTranslations.js`, skipping: +- fields that get `generalResourceFieldsTranslation`'s common keys (`id`, `key`, `name`, `userId`, `createdAt`, `updatedAt`, `year`, `name:$cont`, ...) for free +- fields with an explicit `label="..."` prop on the same tag (react-admin uses that literal string instead of doing a translation lookup) +- fields nested directly inside `...` (they render under the ReferenceField's own column header, not their own) + +It is a heuristic, not a full JS/JSX parser — see Limitations below. + +## Steps + +### 1. Make sure `client/shared` is initialized + +The script reads `client/shared/providers/i18nProvider.js` for `generalResourceFieldsTranslation`. + +```bash +cd $WORKSPACES_ROOT/ +git submodule update --init client/shared +``` + +### 2. Run the scanner + +```bash +node $WORKSPACES_ROOT/multi-repo-codespace/scripts/find-missing-translations.js $WORKSPACES_ROOT//client +``` + +Exit code is `0` when nothing is found, `1` when it reports findings — usable in a pre-commit check or CI step. + +Output looks like: +``` +Found 2 missing translation(s): + + [price] "code" (src/entities/price.jsx) + [price] "description" (src/entities/price.jsx) +``` + +### 3. Verify each finding before fixing + +The script can't see `label=` props that were written on a later line than the `source=` attribute in an unusual way, or dynamic `source={...}` expressions — read the flagged line yourself before editing. Genuine findings are usually one of: +- a `TextInput`/`SelectInput`/`ReferenceInputFilter` filter with an operator suffix (`:$cont`, `:$gte`, ...) and no `label=` prop +- a `TextField`/`NumberField`/... column in `Datagrid` with no `label=` prop and no matching `fields.` entry +- a brand-new entity field added to `Datagrid`/`Inputs` without a matching `domainTranslations.js` entry + +### 4. Fix by adding the missing key(s) + +In `client/src/domainTranslations.js`, under `resources..fields`, add the field using the **exact** `source` string reported (operator suffix included where present): + +```js +teacher: { + fields: { + ...generalResourceFieldsTranslation, + school: 'בית ספר', + 'school:$cont': 'בית ספר', // filter variant needs its own key + }, +}, +``` + +### 5. Re-run the scanner to confirm zero findings, then run the client test suite + +```bash +node $WORKSPACES_ROOT/multi-repo-codespace/scripts/find-missing-translations.js $WORKSPACES_ROOT//client +cd $WORKSPACES_ROOT//client && yarn test +``` + +## Limitations + +- Static regex/brace-depth parsing, not a real JS/JSX parser — dynamically constructed `source={someVar}` expressions aren't checked (can't be, statically). +- Only checks `client/src/entities/*.jsx` files wired into `App.jsx` via `` — custom pages/pivots (e.g. `src/pivots/*`) aren't scanned. +- Resources rendered via a shared helper (e.g. `{CommonPhoneResources({ permissions })}` rather than an explicit `` import) are skipped — their translations live in `client/shared`, not the project's `domainTranslations.js`. +- A field can still look "translated" here but read oddly in the UI if the Hebrew string itself is wrong/inconsistent — this only proves a key *exists*, not that its value is correct. + +## Reference + +Found and fixed via this skill (2026-07-16, `teacher-report-nra`): +- `teacher.jsx`'s `school:$cont` filter had no translation key → showed literally as `school:$cont` in the "add filter" menu. +- `price.jsx`'s `code` and `description` fields (Datagrid columns, inputs, and the `code` filter) had no translation entries at all. diff --git a/.github/skills/generate-migration/SKILL.md b/.github/skills/generate-migration/SKILL.md new file mode 100644 index 00000000..f5209a85 --- /dev/null +++ b/.github/skills/generate-migration/SKILL.md @@ -0,0 +1,83 @@ +--- +name: generate-migration +description: Use when you've changed a TypeORM entity in any NRA project and need to produce the matching migration file, or when asked to generate, verify, or check a database migration against a real database instead of hand-writing SQL. For just running/testing a project locally without Docker (no migration to generate), use run-without-docker instead. +--- + +# Skill: Generate a TypeORM Migration Against a Real Database + +> **Use this skill when:** you've changed an entity in any NRA project's `server/src/db/entities/` and need a migration file. Never hand-write migration SQL — `yarn typeorm:generate` diffs your entity against a live database and writes the exact SQL, including view recreations. Hand-written migrations drift from what TypeORM actually produces and are easy to get subtly wrong (collations, index names, view SQL). + +--- + +## MySQL ports per project + +| Project | MySQL Port | +|---|---| +| `react-admin-nestjs` | 3306 | +| `event-management-nra` | 3316 | +| `teacher-report-nra` | 3326 | +| `student-report-nra` | 3336 | +| `dnd-management-nra` | 3346 | + +## Option A — Docker (preferred, if available) + +```bash +cd $WORKSPACES_ROOT/ +[[ ! -f .env ]] && cp .env.template .env +[[ ! -f docker-compose.override.yml ]] && cp docker-compose.override.yml.template docker-compose.override.yml +docker-compose up -d database +``` + +Use the credentials from `.env` and the port from the table above, then skip to **Step 3**. + +## Option B — Local MySQL (when Docker isn't available, e.g. sandboxed remote sessions) + +Use the `run-without-docker` skill's steps 1–3 to install MySQL, create the database/user, and point `server/.env` at it. Come back here once that's done. + +--- + +## Step 3 (both options): Load the baseline schema + +`db/data.sql` at the project root is a checkpoint dump — its `migrations` table is pre-populated up to *some earlier commit*, not current HEAD. Load it, then replay whatever migrations remain: + +```bash +cd $WORKSPACES_ROOT/ +mysql -u root < db/data.sql +``` + +If it errors on a `GRANT ... TO 'user'@'%'` line near the top of the file, strip those lines first — they're docker-init-specific and fail against a plain root-created database. + +```bash +cd server +NODE_ENV=development yarn typeorm:run +``` + +You now have a real database at exactly current HEAD's schema. + +## Step 4: Make your entity change, then generate + +Always pass `-p` (pretty-print) so the generated SQL is readable instead of one long line: + +```bash +NODE_ENV=development yarn typeorm:generate src/migrations/YourMigrationName -p +``` + +**Check the generated file for noise.** If an existing entity has an index/column with no explicit name, TypeORM may compute a different auto-generated hash name than what's actually stored in the DB, and your migration will include an unrelated rename alongside your real change. Strip anything not related to what you changed. + +## Step 5: Verify zero diff + +Use `--dr` (dry run) so nothing is written to disk — no throwaway file to clean up: + +```bash +yarn typeorm:run # apply your new migration +yarn typeorm:generate src/migrations/check -p --dr # must say "No changes in database schema were found" +``` + +If it's not empty, the migration is incomplete or something else has drifted — investigate before considering it done. + +## Step 6: Sanity-check `down()` + +```bash +yarn typeorm:cli -- migration:revert +yarn typeorm:run # re-apply so the DB ends up in the final state +``` diff --git a/.github/skills/manage-entity/SKILL.md b/.github/skills/manage-entity/SKILL.md new file mode 100644 index 00000000..d155e3d1 --- /dev/null +++ b/.github/skills/manage-entity/SKILL.md @@ -0,0 +1,103 @@ +--- +name: manage-entity +description: Use when creating a brand-new CRUD entity (a full resource — table, API, and UI screens) or editing/removing fields on an existing one, in any NRA project. +--- + +# Skill: Create or Edit an Entity + +> **Use this skill when:** adding a new CRUD resource from scratch (e.g. "add a `subject` entity"), or adding/removing/renaming a field on an existing one. + +--- + +## Context + +An "entity" spans two independent stacks glued together by **name agreement**, not by a shared registry: + +- **Server** (NestJS + TypeORM + `@dataui/crud`): a TypeORM entity class → an auto-generated migration → a per-entity config → registration in one central module. `@dataui/crud` builds the REST controller from the entity class itself — there is **no separate DTO**; `class-validator` decorators live directly on the entity's columns. +- **Client** (React-Admin): a `client/src/entities/.jsx` file (List/Create/Edit) built via a shared factory → a `` in `App.jsx` → Hebrew translations. + +Everything here is **project-local** (`server/src`, `client/src`) unless the entity is genuinely shared by all four apps (User, Page, PaymentTrack, etc. — those configs live in `server/shared/entities/configs/` and `client/shared/entities/`). **Never edit `client/shared` or `server/shared` directly** for a one-app entity — those are separate submodule repos (`nra-client`, `nra-server`). + +The load-bearing convention is **name consistency end-to-end**: entity class name (`Klass`) → REST path / client resource `name` (`klass`, auto-derived via `snakeCase()`) → i18n key `resources.klass` → `registerEntityNameMap({ klass: ... })` key. A mismatch anywhere doesn't throw — it silently 404s or shows an untranslated key instead of Hebrew text. + +## Building blocks + +| File | Layer | Purpose | +|---|---|---| +| `server/src/db/entities/.entity.ts` | server, project-local | TypeORM entity class: columns, validation, relations, `@BeforeInsert`/`@BeforeUpdate` hooks | +| `server/src/migrations/-.ts` | server, project-local | Raw-SQL `up`/`down` migration matching the entity's columns | +| `server/src/entity-modules/.config.ts` | server, project-local | `BaseEntityModuleOptions` — query joins, `crudAuth`, custom `service` (for `doAction`/`getReportData` overrides), `exporter` | +| `server/src/entities.module.ts` | server, project-local | Central registry: imports every config, wraps it in `BaseEntityModule.register(...)`, and `registerEntityNameMap({...})` for audit-log/import display names | +| `client/src/entities/.jsx` | client, project-local | `Datagrid`, `Inputs`, `Representation`, filters — passed to the shared `getResourceComponents()` factory | +| `client/src/App.jsx` | client, project-local | `` | +| `client/src/domainTranslations.js` | client, project-local | Hebrew `resources..name` / `.fields.` | +| `server/shared/base-entity/base-entity.module.ts` | server, shared | Turns a config into a full `@Crud()` controller — don't edit, just consume | +| `client/shared/components/crudContainers/CommonEntity.jsx` | client, shared | `getResourceComponents()` factory — builds List/Edit/Create and injects `isAdmin` | +| `client/shared/providers/i18nProvider.js` | client, shared | `generalResourceFieldsTranslation` — generic fallback for `id`, `key`, `name`, `userId`, `createdAt`, `updatedAt`, `year`; spread this first in every entity's `fields` | + +## Steps: create a new entity + +0. **Decide scope**: is this entity used only by this app, or genuinely needed by all four? Default to project-local. Only touch `client/shared`/`server/shared` if it's meant to be reused (that's a separate PR against the `nra-client`/`nra-server` repos). +1. **TypeORM entity** — create `server/src/db/entities/.entity.ts`: + - `implements IHasUserId` (from `@shared/base-entity/interface`) and add a `@Column('int', { name: 'user_id' }) userId: number;` unless the entity is intentionally not user-scoped — `BaseEntityService` checks for `userId` to auto-filter by owner. + - Use `CreatedAtColumn()`/`UpdatedAtColumn()` from `@shared/utils/entity/column-types.util` (not raw `@CreateDateColumn()` — these are DB-agnostic for MySQL prod / SQLite test). + - Put `class-validator` decorators directly on columns, split by `CrudValidationGroups.CREATE`/`.UPDATE` (see `Klass.entity.ts` or the simpler `KlassType.entity.ts`) — use the Hebrew-messaged wrappers in `@shared/utils/validation/class-validator-he` (`IsNotEmpty`, `IsNumber`, `MaxLength`, `IsUniqueCombination`). + - For a foreign key entered by the user as a natural key (not the numeric id), follow the `key`/`referenceId` dual-column pattern (`teacherId` + `teacherReferenceId`, resolved in a `@BeforeInsert`/`@BeforeUpdate` hook via `findOneAndAssignReferenceId`) — only needed if you want Excel-import-friendly natural keys; a plain `@ManyToOne` FK column is fine for a simple new entity. +2. **Migration** — from `server/`, run `npm run typeorm:generate -- src/migrations/` (diffs entities vs DB and writes the SQL) rather than hand-writing it. Confirm the generated file's `up()` matches the columns you expect; `down()` should `DROP TABLE`. Migrations auto-apply on server container start (`docker-entrypoint.sh` runs `typeorm:run:js`) — just commit the file and restart the server. +3. **Server config** — create `server/src/entity-modules/.config.ts`. Minimal shape: + ```ts + function getConfig(): BaseEntityModuleOptions { + return { + entity: , + exporter: { getExportHeaders: () => [{ value: 'key', label: 'מזהה' }, { value: 'name', label: 'שם' }] }, + }; + } + export default getConfig(); + ``` + Add `query.join` for eager relations, `crudAuth: CrudAuthWithPermissionsFilter(...)` if it needs gating (see `manage-permissions` skill), or a custom `service extends BaseEntityService` if it needs bulk actions (`add-bulk-action` skill) or a custom report. +4. **Register it** — in `server/src/entities.module.ts`: import the config, add `BaseEntityModule.register(Config)` to the `imports` array, and add an entry to `registerEntityNameMap({ ... })` keyed by the snake_case resource name (Hebrew display name for audit logs/import UI). +5. **Client entity file** — create `client/src/entities/.jsx`. Define `Datagrid`, `Inputs`, `Representation = CommonRepresentation`, optional `filters`/`filterDefaultValues`/`importer`, and end with: + ```jsx + export default getResourceComponents({ Datagrid, Inputs, Representation, filters, filterDefaultValues }); + ``` + Gate admin-only columns/inputs with the auto-injected `isAdmin` prop (`{isAdmin && }`). For a trivial admin-only/read-model resource you can skip this file and use `resourceEntityGuesser` directly in `App.jsx` instead. +6. **Register the resource** — in `client/src/App.jsx`: `import from 'src/entities/';` and add `} icon={} options={{ menuGroup: '' }} />`. The `name` string **must** equal the server's `snakeCase()` path. Pick an existing `menuGroup` from that project's `client/src/GeneralLayout.jsx` `menuGroups` list, or it'll render as an ungrouped top-level item. +7. **Translations** — in `client/src/domainTranslations.js`, add under `resources`: + ```js + : { + name: ' |||| ', + fields: { ...generalResourceFieldsTranslation, : '', ... }, + }, + ``` + Always spread `generalResourceFieldsTranslation` first so common fields (`id`, `key`, `userId`, `createdAt`, `updatedAt`, `year`) get Hebrew for free. +8. **Permissions**, if this entity should be gated to certain users — see the `manage-permissions` skill in full (add a key, wire `crudAuth` server-side, gate the `` client-side). +9. **Verify**: restart the project (`bash scripts/start-project.sh `), log in, confirm the resource appears in the menu with Hebrew labels, and exercise Create/List/Edit. Optionally add `server/src/entity-modules/__tests__/.config.spec.ts` asserting the config's `entity`/`query.join`/exporter — the established pattern for other entities. + +## Steps: edit an existing entity (add/remove/rename a field) + +1. **Add a column**: add the property + decorators to `server/src/db/entities/.entity.ts`, then run `npm run typeorm:generate -- src/migrations/AddTo` from `server/` to generate the matching migration (don't hand-write the SQL). Add the field to `Datagrid`/`Inputs` in `client/src/entities/.jsx`, and a translation key in `domainTranslations.js` under that resource's `fields` — a missing translation doesn't error, it just shows the raw field key in the UI. +2. **Remove a column**: reverse of the above — delete from the entity class, generate a migration (`DROP COLUMN`), remove the field from `Datagrid`/`Inputs` and from `exporter.getExportHeaders`/`importer.fields` if referenced, and drop the now-unused translation key. +3. **Rename a column**: TypeORM's diff will generate a `DROP`+`ADD` by default, which loses data — hand-edit the generated migration to use `RENAME COLUMN` (or `CHANGE`) instead, and update every reference to the old name across entity, config (`exporter`/`query.join`), client jsx, and translations. +4. Restart the project and verify the changed field on List, Create, and Edit screens. + +## Reference example (`Klass` / `klass`) + +- Migration: `server/src/migrations/1682968919553-addPageTable.ts` (different entity, but the canonical raw-SQL `up`/`down` shape) +- Entity: `server/src/db/entities/Klass.entity.ts` — full pattern (validation groups, `key`/`referenceId` FK resolution, indexes). `server/src/db/entities/KlassType.entity.ts` is the simpler version without the extra reference. +- Config: `server/src/entity-modules/klass.config.ts` — custom `KlassService` with `doAction`/`getReportData` overrides, `query.join`, `exporter`. `server/src/entity-modules/klass-type.config.ts` is the minimal version. +- Registration: `server/src/entities.module.ts` — `BaseEntityModule.register(klassConfig)` + `registerEntityNameMap({ klass: 'כיתות', ... })` +- Client: `client/src/entities/klass.jsx` — `Datagrid`/`Inputs`/`Representation`/`filters`/`importer`, ends with `getResourceComponents(entity)` +- App wiring: `client/src/App.jsx` — `` +- Translations: `client/src/domainTranslations.js` — `resources.klass` + +## Troubleshooting + +| Symptom | Likely cause | +|---|---| +| New resource 404s on the client | `` doesn't match `snakeCase()` from the server config | +| Server starts fine but the resource 500s on every request | Entity class exists but no migration was generated/applied — table doesn't exist yet (see `debug-project-issues` skill) | +| Field/resource shows the raw key (e.g. `klassTypeReferenceId`) instead of Hebrew | Missing entry under `resources..fields` (or `resources..name`) in `domainTranslations.js` — doesn't error, just falls back silently | +| New resource doesn't show in the sidebar menu | `options={{ menuGroup: ' }}` group name isn't in that project's `GeneralLayout.jsx` `menuGroups` — falls back to an ungrouped top-level item, not hidden | +| `typeorm:generate` produces `DROP COLUMN` + `ADD COLUMN` for what you meant as a rename | TypeORM diffs by column identity, not intent — hand-edit the migration to `RENAME COLUMN`/`CHANGE` to avoid a data loss on deploy | +| User-scoping (`userId` auto-filter) doesn't apply to the new entity | Forgot `implements IHasUserId` and/or the `userId` column — `BaseEntityService` checks for it by name | +| Changes made directly in `client/shared`/`server/shared` don't show up, or break other projects | Those are separate submodule repos — entity work belongs in `client/src`/`server/src` unless the entity is intentionally shared across all four apps | diff --git a/.github/skills/manage-permissions/SKILL.md b/.github/skills/manage-permissions/SKILL.md new file mode 100644 index 00000000..8bc54a07 --- /dev/null +++ b/.github/skills/manage-permissions/SKILL.md @@ -0,0 +1,67 @@ +--- +name: manage-permissions +description: Use when adding a new permission, or changing who can see/do something (a resource, menu item, field, or action), in any NRA project. +--- + +# Skill: Manage Permissions + +> **Use this skill when:** adding a new permission key, or restricting/exposing a resource, menu item, field, or action to certain users. + +--- + +## Context + +There is **no role table and no server-side `@Roles()` guard**. Every NRA project uses the same model: each `User` row has a free-form JSON `permissions` column (e.g. `{ admin: true, showUsersData: true, teacherView: true }`). "Admin" is just the key `admin: true` — not a separate tier. Both sides check permissions with small helper functions rather than a central role→resource table. + +Permission **keys** come in two tiers, mirroring the shared/local split used for bulk actions: +- **Shared keys** — used by resources/features common to all four apps (user management, pages, payment tracks). Defined identically in `client/shared/config/permissionsConfig.js` and `server/shared/utils/permissionsUtil.ts` (`admin`, `manager`, `showUsersData`, `editPagesData`, `editPaymentTracksData`, `genericImageUpload`, `uploadedFiles`, `phoneCampaign`). Keep both files in sync — they must use the exact same key names. +- **Project-local keys** — specific to one app's domain (e.g. `teacherView`, `lessonSignature`). Defined client-side in that project's `client/src/utils/appPermissions.js`; there's no equivalent server-side file — server code just checks the string literal directly (`hasPermission(auth, 'lessonSignature')`). Keys can be dotted for nested checks (e.g. `inLessonReport.withLate`). + +Enforcement is split by side: +- **Server**: `JwtAuthGuard` (`server/shared/auth/jwt-auth.guard.ts`) only checks the JWT is valid — it does not check permissions. Actual permission enforcement is a **data filter**, not a route guard, via `@dataui/crud`'s `CrudAuth`: `server/shared/auth/crud-auth.filter.ts` exposes `CrudAuthFilter` (default: admin sees everything, others see only their own rows) and `CrudAuthWithPermissionsFilter(fn)` (admin, or `fn(permissions)` truthy, sees everything; otherwise sees **no rows** — lacking a permission returns an empty list, not a 403). `server/shared/base-entity/base-entity.module.ts` wires `@CrudAuth(options.crudAuth ?? CrudAuthFilter)` onto every entity automatically. +- **Client**: `authProvider.getPermissions()` (`client/shared/providers/authProvider.js`) returns the user's `permissions` object, which react-admin injects as the `permissions` argument into the render-prop function passed to `` in that project's `client/src/App.jsx`. `CommonEntity.jsx` (the factory most entity files use) also auto-injects an `isAdmin` prop into the entity's `Datagrid`/inputs, so field-level gating in entity files is usually just `{isAdmin && }`. `Menu.jsx` filters menu items the same way. + +## Building blocks + +| File | Layer | Purpose | +|---|---|---| +| `server/shared/utils/permissionsUtil.ts` | server, shared | `permissionKeys` map, `hasPermission(auth, key)` (dotted keys), `isAdmin(auth)` | +| `server/shared/auth/crud-auth.filter.ts` | server, shared | `CrudAuthFilter`, `CrudAuthWithPermissionsFilter(fn)` — the actual enforcement | +| `server/shared/base-entity/base-entity.module.ts` | server, shared | Applies `crudAuth` to every entity's controller automatically | +| `server/src/entity-modules/*.config.ts` | server, project-local | Sets a specific entity's `crudAuth`, or calls `hasPermission`/`isAdmin` inline for finer checks | +| `client/shared/config/permissionsConfig.js` | client, shared | Shared `permissionKeys` | +| `client/shared/utils/permissionsUtil.js` | client, shared | `useHasPermission(key)`, `useIsAdmin()`, and derived helpers (`isManager`, `isShowUsersData`, ...) | +| `client/src/utils/appPermissions.js` | client, project-local | Project-specific keys + matching `isX`/`useIsX` helpers | +| `client/src/App.jsx` | client, project-local | Top-level `(permissions) => ...` tree — gates whole resources | +| `client/shared/components/layout/Menu.jsx` | client, shared | Filters menu items by `{ isAdmin, permissions }` | +| `client/shared/components/common-entities/user.jsx` | client, shared | The "role editor" — a `BooleanInput` checkbox per permission key on the User edit screen | + +## Steps: add a new permission + +0. **Decide scope**: does this gate something used by all four apps (shared), or only this app's own feature (project-local)? Default to project-local; only touch the shared files if the resource/feature itself is shared. +1. **Define the key**: + - Shared: add the key to `permissionKeys` in **both** `client/shared/config/permissionsConfig.js` and `server/shared/utils/permissionsUtil.ts`, with the exact same name. + - Project-local: add the key to `client/src/utils/appPermissions.js` only. Server code references it as a plain string via `hasPermission(auth, 'yourKey')` — no server file to add it to. +2. **Add a helper** (optional, but matches existing style): next to the key, add `isYourKey`/`useIsYourKey` in the same file as step 1. +3. **Wire enforcement**: + - Server, whole-resource: set `crudAuth: CrudAuthWithPermissionsFilter(permissions => permissions.yourKey)` in the entity's `*.config.ts`. + - Server, finer-grained: call `hasPermission(req.auth, 'yourKey')` or `isAdmin(req.auth)` inside the service/controller logic (e.g. inside a `doAction` case — see `add-bulk-action` skill). + - Client, whole-resource: gate the `` in `client/src/App.jsx` on the permission. + - Client, field/section: use the hook from step 2 inside the entity file (`client/src/entities/.jsx`), or the auto-injected `isAdmin` prop from `CommonEntity.jsx` if it's an admin-only check. + - Menu items for a gated resource update automatically via `Menu.jsx` — no extra wiring needed unless it's a custom (non-resource) menu entry. +4. **Make it assignable**: add a `` to the checkbox list in `client/shared/components/common-entities/user.jsx` so an admin can grant it from the User edit screen. +5. **Verify**: restart the project, log in as admin, toggle the new checkbox on a test user, then log in as that user and confirm the resource/field/menu item appears or disappears as expected. + +## Reference examples + +- Shared, whole-resource: `showUsersData` gates the `user` and `payment_track` resources — see `client/shared/components/app/CommonAdminResources.jsx` and `server/shared/entities/configs/user.config.ts` (`crudAuth: CrudAuthWithPermissionsFilter(permissions => permissions.showUsersData)`). +- Project-local, fine-grained: `lessonSignature` controls a single field, not a whole resource — see `shouldShowTopic` in `server/src/entity-modules/att-report.config.ts` (`isAdmin(req.auth) || hasPermission(req.auth, 'lessonSignature')`) and the matching `useIsLessonSignature` check in `client/src/entities/att-report.jsx`. + +## Troubleshooting + +| Symptom | Likely cause | +|---|---| +| Toggled the checkbox but the user still can't/can see the resource | Permissions are cached client-side from `getIdentity()`/the JWT payload — the user needs to log out and back in | +| Resource returns an empty list instead of an error for a user lacking permission | Expected — `CrudAuthWithPermissionsFilter` denies via `NO_DATA_FILTER` (empty result), not a 403 | +| New checkbox doesn't appear on the User edit screen | Forgot to add the `BooleanInput` in `client/shared/components/common-entities/user.jsx` | +| Shared key works on the client but not the server (or vice versa) | Key name mismatch — `permissionKeys` must be spelled identically in `client/shared/config/permissionsConfig.js` and `server/shared/utils/permissionsUtil.ts` | diff --git a/.github/skills/report-generation/SKILL.md b/.github/skills/report-generation/SKILL.md new file mode 100644 index 00000000..d56cc0d9 --- /dev/null +++ b/.github/skills/report-generation/SKILL.md @@ -0,0 +1,128 @@ +--- +name: report-generation +description: Use when adding or changing a downloadable/exported file in any NRA project — a generic list export (Excel/PDF/JSON of the current grid), or a custom named report (a report card, bulk PDF, ZIP, or audio file triggered by a button) — or when fixing report fonts/headers. Covers the shared BaseReportGenerator family in server/shared (nra-server) utils/report and how a project wires a brand-new report type end to end. +--- + +# Skill: Add or Change a Report / Export + +> **Use this skill when:** an entity needs a new export or report file, or you're modifying how one is produced (columns, layout, fonts, format). All report types derive from one shared base in `server/shared/utils/report/` (`nra-server`). + +There are **two distinct mechanisms** — pick the right one before writing code: + +| | Generic list export | Custom named report | +|---|---|---| +| What | Export the current grid's rows/columns as-is | A purpose-built file (report card, filtered bulk PDF, audio, ZIP) with its own params | +| Trigger | The entity's built-in `` (shown unless `exporter: false`) | A `` you add explicitly | +| Server config | `exporter: { getExportHeaders, processReqForExport }` in the entity config | `reportsDict` + `getReportData()` override on the entity's `Service` class | +| Formats available | Excel / PDF / Json (via `getExportedFile`) | Any `CommonFileFormat` — Excel/Pdf/Json/Zip/Html/Mp3/Wav | + +--- + +## The generator model (shared by both mechanisms) + +`BaseReportGenerator` (`report.generators.ts`) has two jobs: + +```ts +new SomeReportGenerator( + getReportName: (data: U) => string, // filename (no extension) + getReportData?: (params: T, ds: DataSource) => Promise, // fetch/shape data +) +``` + +- `getReportData` fetches/shapes rows from the `DataSource`. Omit it and params pass through unchanged. +- each concrete generator implements `getFileBuffer(data): Promise` — you rarely touch this; you pick a generator and supply the two functions above. +- `fileFormat: CommonFileFormat` (`types.ts`) drives extension/MIME: `Excel, Pdf, Json, Zip, Html, Mp3, Wav`. + +### Pick a generator (all in `utils/report/`) + +| Need | Generator | +|---|---| +| Excel spreadsheet | `DataToExcelReportGenerator` / `GenericDataToExcelReportGenerator` | +| Single PDF from HTML markup | `MarkupToPdfReportGenerator` / `SimpleMarkupToPdfReportGenerator` | +| PDF from an EJS template | `EjsToPdfReportGenerator` | +| PDF from a React component | `ReactToPdfReportGenerator` | +| Many records → one merged PDF | `BulkToPdfReportGenerator` | +| Many files → one ZIP | `BulkToZipReportGenerator` | +| Audio file | `BufferToAudioReportGenerator` (set format Mp3/Wav) | +| Raw JSON (debugging/params echo) | `ParamsToJsonReportGenerator` | + +Excel helpers: `getIntegerDataValidation`, `getDateDataValidation` for cell validation. Only write a **new** generator subclass if none of these fit the output shape — that's a shared-repo change (see "Shared vs project" below). + +--- + +## A. Generic list export (Excel/PDF/Json of the grid as shown) + +Already wired for every entity by default. To customize headers/columns, add to the entity config in `server/src/entity-modules/.config.ts`: + +```ts +exporter: { + processReqForExport(req: CrudRequest, innerFunc) { + req.options.query.join = { student: { eager: true }, klass: { eager: true } }; // eager-load what headers need + return innerFunc(req); + }, + getExportHeaders(): IHeader[] { + return [ + { value: 'student.tz', label: 'תז' }, + { value: 'student.name', label: 'שם התלמידה' }, + ]; + }, +}, +``` + +Set `exporter: false` to hide the export button entirely. Nothing needed client-side — `ResourceExportButton` (in `CommonListActions.jsx`) is automatic. + +## B. Custom named report (the common "add a new report type" case) + +Use this when the export isn't just the grid — it needs its own params (date range, filters), a specific layout, or a non-Excel format. + +### 1. Server: add the generator + route it in `getReportData` + +In `server/src/entity-modules/.config.ts`, override `getReportData` on the entity's `Service` class: + +```ts +class StudentKlassService extends BaseEntityService { + reportsDict = { + studentReportCard: new BulkToPdfReportGenerator(studentReportCard), // studentReportCard = a template/render function, see step 2 + }; + + async getReportData(req: CrudRequest): Promise { + if (req.parsed.extra.report in this.reportsDict) { + const generator = this.reportsDict[req.parsed.extra.report]; + const ids = getAsNumberArray(req.parsed.extra.ids); + // ...load/shape whatever this report needs from `ids` and other req.parsed.extra params... + return { generator, params: /* whatever getReportData on the generator expects */ }; + } + return super.getReportData(req); // falls through to the generic exporter-as-JSON default + } +} +``` + +The dict key (`studentReportCard`) is the **report name** — it must match the client button's `name` prop exactly (see step 3). `req.parsed.extra` carries whatever query params the client sent (`ids`, plus any form fields from the button's dialog). + +### 2. Server: write the template/content function + +For PDF generators this is usually a separate file, e.g. `server/src/reports/studentReportCard.tsx`, exporting the React component or EJS/markup that `BulkToPdfReportGenerator`/`ReactToPdfReportGenerator` renders per record. Keep this project-local — it's specific data/layout, not shared plumbing. + +For Excel/Zip/audio, the equivalent is whatever `getReportData` function you pass into the generator's constructor, shaping the data into what `getFileBuffer` expects. + +### 3. Client: add the trigger button + +This half — the `` on the entity's list, with its param-collection dialog — is bulk-action wiring. Follow the **`add-bulk-action`** skill's `BulkReportButton` section; the `name` prop there must equal the `reportsDict` key from step 1. + +### 4. Wire the route + +Nothing extra to add — `BaseEntityController.getReportData` already calls `service.getReportData(req)` → `generateCommonFileResponse(generator, params, dataSource)` for every entity. Steps 1–3 are the only wiring needed. + +--- + +## Fonts & assets (PDF) + +PDF generators embed fonts. History: fonts were self-hosted, then reverted to Google Fonts with a 10s timeout + fallback. When touching report styling, don't reintroduce a hard dependency on a font fetch without a fallback — a slow/blocked font host must not hang report generation. Repeating page images (report-card header/footer on every page) use the shared `RepeatingPageImage` component — reuse it, don't re-solve per project. + +## Shared vs project + +A generic new generator/format, or a change to `BaseReportGenerator`/`report.util.ts`, belongs in `nra-server` (`utils/report/`) — that's a shared change: use the `shared-changes-workflow` skill and record a `CONSUMER_CHANGES.md` row if apps must wire it in. A report that's specific to one project's data (a particular report card, a particular Excel layout, its `reportsDict` entry) stays in that project's `entity-modules/` and `reports/` — using the shared generators, not duplicating them. + +## Test it + +Generators are unit-testable with no DB — construct with a fake data fn and assert `getFileBuffer`. See `write-tests`. Example: `new ParamsToJsonReportGenerator(() => 'test')`. diff --git a/.github/skills/run-without-docker/SKILL.md b/.github/skills/run-without-docker/SKILL.md new file mode 100644 index 00000000..ce7e762c --- /dev/null +++ b/.github/skills/run-without-docker/SKILL.md @@ -0,0 +1,94 @@ +--- +name: run-without-docker +description: Use when Docker isn't available (e.g. sandboxed remote sessions) and you need to run an NRA project's client+server against a real MySQL instance — standing up local MySQL, configuring server/.env, starting the dev servers, and the login smoke test. For generating/verifying a TypeORM migration against that database, see generate-migration instead. +--- + +# Skill: Run a Project Without Docker + +> **Use this skill when:** `docker-compose` isn't available and you need a real running stack — local MySQL + NestJS dev server + Vite dev client — instead of Docker containers. + +--- + +## MySQL ports per project + +These are the Docker-compose ports; when running local MySQL you don't need to match them (just point `.env` at whatever port you actually used), but they're handy if you're running multiple projects' *containers* side by side. + +| Project | MySQL Port | +|---|---| +| `react-admin-nestjs` | 3306 | +| `event-management-nra` | 3316 | +| `teacher-report-nra` | 3326 | +| `student-report-nra` | 3336 | +| `dnd-management-nra` | 3346 | + +## 1. Install and start MySQL 8 + +```bash +apt-get update -qq && apt-get install -y -qq mysql-server-8.0 +service mysql start +``` + +## 2. Create the database and user + +```bash +mysql -u root -e " +CREATE DATABASE mysql_database CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci; +CREATE USER 'mysql_user'@'localhost' IDENTIFIED BY 'mysql_password'; +GRANT ALL PRIVILEGES ON mysql_database.* TO 'mysql_user'@'localhost'; +GRANT SYSTEM_USER ON *.* TO 'mysql_user'@'localhost'; +FLUSH PRIVILEGES; +" +``` + +`SYSTEM_USER` is required — some migrations run `DROP VIEW`, which MySQL 8 gates behind that privilege. + +## 3. Point the server at it + +```bash +cd $WORKSPACES_ROOT//server +cat > .env <<'EOF' +MYSQL_HOST=localhost +MYSQL_PORT=3306 +MYSQL_USER=mysql_user +MYSQL_PASSWORD=mysql_password +MYSQL_DATABASE=mysql_database +JWT_SECRET=jwt_secret +EOF +export $(cat .env | xargs) +``` + +## 4. Apply migrations + +From an empty database, just replay everything: + +```bash +yarn install +NODE_ENV=development yarn typeorm:run +``` + +**Shortcut:** if the project has `db/data.sql` at its root (a schema checkpoint dump with the `migrations` table pre-populated up to some earlier commit), loading it first and then running only the remaining migrations is faster than replaying full history: + +```bash +cd $WORKSPACES_ROOT/ +mysql -u root mysql_database < db/data.sql # strip any `GRANT ... TO 'user'@'%'` lines first if it errors — docker-init-specific +cd server && NODE_ENV=development yarn typeorm:run +``` + +This checkpoint-and-replay approach is also what `generate-migration` uses to get a DB at exactly current HEAD's schema before diffing a new entity change — use that skill instead of this one when the goal is producing a migration file, not just running the app. + +## 5. Start the dev servers + +```bash +# Server +cd $WORKSPACES_ROOT//server +yarn start:dev + +# Client (separate shell) +cd $WORKSPACES_ROOT//client +yarn install +yarn start +``` + +## 6. Login smoke test + +Open the client's dev URL and sign in with `admin_user` / `admin_password`. The dashboard should load without errors. For a deeper check of every API route, use the `smoke-test-project` skill. diff --git a/.github/skills/shared-changes-workflow/SKILL.md b/.github/skills/shared-changes-workflow/SKILL.md new file mode 100644 index 00000000..17e7c14b --- /dev/null +++ b/.github/skills/shared-changes-workflow/SKILL.md @@ -0,0 +1,95 @@ +--- +name: shared-changes-workflow +description: Use when authoring a NEW change in a shared submodule (client/shared -> nra-client, server/shared -> nra-server) and rolling it out across all NRA projects, when refactoring duplicated project code into a shared component, or when recording/consuming a CONSUMER_CHANGES.md row. For moving ONE project's pointer to an already-known target, use bump-shared-ref instead. +--- + +# Skill: Make a Shared Change Across NRA Projects + +> **Use this skill when:** you modify code in `client/shared` (→ `nra-client`) or `server/shared` (→ `nra-server`) and must propagate it to all NRA projects, refactor duplicated project code into a shared component, or add/consume a `CONSUMER_CHANGES.md` row. +> +> **Not this skill when:** you're only moving one project's submodule pointer to a commit/branch that already exists — that's `bump-shared-ref`. + +--- + +## Context + +5 projects share two git submodules: + +- `client/shared` → `buzz-code/nra-client` +- `server/shared` → `buzz-code/nra-server` + +Each project pins the submodule to one commit. Shared code lives in **one place** (the submodule repo); all projects reference it. **Never** copy a shared file into each project — that creates divergent copies. + +| Project | Client | Server | +|---|---|---| +| `react-admin-nestjs` | 3000 | 3001 | +| `event-management-nra` | 3010 | 3011 | +| `teacher-report-nra` | 3020 | 3021 | +| `student-report-nra` | 3030 | 3031 | +| `dnd-management-nra` | 3040 | 3041 | + +`react-admin-nestjs` is the base project — author shared changes from its submodule checkout. + +## The CONSUMER_CHANGES.md contract (read this first) + +Both shared repos keep a `CONSUMER_CHANGES.md` table at their root. It is the handshake between "a shared change landed" and "each app wired it in". A row exists **only** for changes that do NOT work automatically after a pointer bump — i.e. they need a matching edit in each consuming app (a new import, a new package, a Dockerfile/compose label, a policy line). + +| Column | Meaning | +|---|---| +| `Commit` | short hash of the shared commit (or `(docs)` for policy-only changes) | +| `Adds` | what the shared commit introduced | +| `Per-app action` | the exact edit each consuming app must make | +| `Done in` | which apps have already applied it | + +**Rules:** +1. A shared change that is purely additive and auto-works after a bump gets **no row**. Only add a row when a consumer must do something. +2. When you author such a change, **add the row in the same shared PR**, `Done in` listing whatever apps you wired in this pass (often none yet). +3. When you wire an app (here or via `bump-shared-ref`), **append that app to the row's `Done in`** in the shared repo and commit it. +4. If a bump breaks an app at runtime but no row explains it, the doc is missing an entry — add it. + +## Workflow + +### 1. Author the change in the shared submodule + +```bash +cd /workspaces/react-admin-nestjs/client/shared # or server/shared +git checkout -b claude/ +# make changes... +``` + +If the change needs per-app wiring, edit `CONSUMER_CHANGES.md` in the same checkout (see contract above). Commit and push: + +```bash +git add . +git commit -m "feat: " +git push -u origin claude/ +``` + +### 2. Verify in the base project + +```bash +cd /workspaces/react-admin-nestjs/client && yarn test # or server +``` + +Fix + re-push shared code until green. + +### 3. Ask before merging the shared PR + +Do **not** merge or open PRs without user confirmation. The shared PR merges to the shared repo's `main` **before** any project's `main` pins it (the main-branch rule — see `bump-shared-ref`). + +### 4. Roll out to every project + +After the shared PR merges, for each of the 5 projects use `bump-shared-ref`: bump the pointer to the merged `main` commit, apply the row's `Per-app action`, append the app to `Done in`, commit pointer + consumer edits together, push to the project's branch. + +### 5. Update the roadmap + +If the change is client-facing, add a `roadmapFeatures.js` entry in each affected project (see multi-repo coding guidelines). + +## Rules + +1. Never push directly to `main` (shared or project) without asking. Use a branch. +2. Always ask before creating PRs. +3. Shared PR merges first; project `main` never pins a non-`main` shared commit. +4. One source of truth — shared code lives in the submodule only. +5. Test in at least one project before propagating. +6. Commit the submodule pointer (gitlink) whenever it moves. diff --git a/.github/skills/smoke-test-project/SKILL.md b/.github/skills/smoke-test-project/SKILL.md new file mode 100644 index 00000000..bbf37720 --- /dev/null +++ b/.github/skills/smoke-test-project/SKILL.md @@ -0,0 +1,118 @@ +--- +name: smoke-test-project +description: Use when you need to verify that all API endpoints of a running NRA project are healthy, or when asked to "test", "check endpoints", or "run smoke tests" on a project. +--- + +# Skill: Smoke Test a Project + +> **Use this skill when:** you need to verify that all API endpoints of a running NRA project are healthy, or when asked to "test", "check endpoints", or "run smoke tests" on a project. + +--- + +## Context + +Each project's server has a `helpers/endpoints.env` file listing all registered entity endpoints. The shared runner script logs into the backend and calls every endpoint with the authenticated cookie. + +**Prerequisite:** The project must be running. Use the `run-one-project` skill first if needed. + +--- + +## Server Port Reference + +| Project | Server Port | +|---------|-------------| +| `react-admin-nestjs` | 3001 | +| `event-management-nra` | 3011 | +| `teacher-report-nra` | 3021 | +| `student-report-nra` | 3031 | +| `dnd-management-nra` | 3041 | +| `form-call` | 3051 | + +--- + +## Steps + +### 1. Navigate to the project's server directory + +```bash +cd /workspaces//server +``` + +### 2. Load the endpoint list and run the smoke test + +```bash +set -a && . helpers/endpoints.env && set +a +BACKEND_URL=http://localhost: \ + sh shared/utils/testing/test-all-endpoints-runner.sh +``` + +**Example for `teacher-report-nra`:** +```bash +cd /workspaces/teacher-report-nra/server +set -a && . helpers/endpoints.env && set +a +BACKEND_URL=http://localhost:3021 \ + sh shared/utils/testing/test-all-endpoints-runner.sh +``` + +### 3. Read the results + +The runner prints a line per endpoint: +``` +✅ GET /user → 200 +✅ GET /student → 200 +❌ GET /report_period → 500 +``` + +Exit code = number of failed endpoints (0 = all passed). + +--- + +## Baseline (All Passing as of 2026-05-07) + +| Project | Endpoints | +|---------|-----------| +| `react-admin-nestjs` | 44/44 | +| `event-management-nra` | 28/28 | +| `teacher-report-nra` | 30/30 | +| `student-report-nra` | 22/22 | + +--- + +## Running Unit Tests (without a live server) + +```bash +# Client (React/Jest) +cd /workspaces//client +yarn test --watchAll=false --passWithNoTests + +# Server (NestJS/Jest) +cd /workspaces//server +yarn test +``` + +Or run all projects at once from the bootstrap repo: +```bash +bash /workspaces/multi-repo-codespace/scripts/run-client-tests.sh +bash /workspaces/multi-repo-codespace/scripts/run-server-tests.sh +``` + +--- + +## Quick Login Smoke Test + +1. Open `http://localhost:/login` in the browser +2. Sign in with `admin_user` / `admin_password` +3. Confirm the URL changes from `/login` to `/` (dashboard) + +A 500 on the dashboard after login is a **data layer issue**, not an auth failure. + +--- + +## Troubleshooting Smoke Tests + +| Symptom | Cause | Action | +|---------|-------|--------| +| Login fails ("Login failed") | Server not ready or DB migration missing | Wait 30 s, rerun | +| Specific endpoint returns 500 | Missing migration, data issue | Check server logs, see debug skill | +| `helpers/endpoints.env` not found | Project not fully set up | Check that `server/shared` submodule is initialized | +| All endpoints fail | Server container crashed | `docker-compose logs server` | diff --git a/.github/skills/write-tests/SKILL.md b/.github/skills/write-tests/SKILL.md new file mode 100644 index 00000000..2b1e5cc3 --- /dev/null +++ b/.github/skills/write-tests/SKILL.md @@ -0,0 +1,84 @@ +--- +name: write-tests +description: Use when writing or fixing a unit test in any NRA project or shared repo, or when you need to run code/UI without a live backend — i.e. "mock the backend", "mock the dataProvider", "test this entity/config", "why won't this test render". Covers the client (Jest + jsdom, react-admin mocked) and server (Jest + ts-jest, TypeORM repo mocked) mock patterns so you don't re-derive them each time. +--- + +# Skill: Write Tests / Mock the Backend + +> **Use this skill when:** adding or fixing a unit test, or exercising a component/config without a running server. Both sides mock their dependencies — there is no live DB or HTTP in unit tests. + +--- + +## Where tests live & how to run + +```bash +cd /client && yarn test # Jest + jsdom (*.test.jsx / *.test.js) +cd /server && yarn test # Jest + ts-jest (*.spec.ts) +``` + +Or, no-Docker, from the workspace root: + +```bash +bash scripts/run-client-tests.sh +bash scripts/run-server-tests.sh # run bash setup-node-modules.sh first if modules missing +``` + +Tests colocate under `__tests__/` next to the code. Shared code is tested in its own repo (`nra-client`, `nra-server`), consumers test only their own project code. + +--- + +## Client: mock react-admin + `@shared`, don't hit a backend + +An entity file (`client/src/entities/.jsx`) pulls in react-admin and heavy `@shared` components. Unit tests **stub those out** with `jest.mock` so the test renders in jsdom with no data provider and asserts on wiring (which fields, which resource, which props), not on real data flow. + +Pattern (from `nra-client` `CommonEntity.test.jsx`): + +```jsx +import { render, screen } from '@testing-library/react'; + +// Replace react-admin hooks with fixed return values +jest.mock('react-admin', () => ({ + usePermissions: () => ({ permissions: {} }), + useResourceContext: () => 'payment_track', +})); + +// Stub shared components to trivial DOM so you can assert props +jest.mock('@shared/components/crudContainers/CommonList', () => ({ + CommonList: ({ children }) =>
{children}
, +})); + +// require AFTER the mocks are declared +const { getResourceComponents } = require('../CommonEntity'); +``` + +Rules: +- Declare every `jest.mock` **before** `require`-ing the unit under test (or use `import` knowing jest hoists `jest.mock`). +- Stub each `@shared/...` import the file uses — an unmocked shared component drags in the whole react-admin runtime and the test fails to render. +- Assert on **wiring**: `data-testid`, `data-resource`, presence of a field/button — not on fetched data. +- **Mock the dataProvider** only when the component calls it: `const dataProvider = { getList: jest.fn().mockResolvedValue({ data: [], total: 0 }), update: jest.fn() }` and pass it via react-admin's context/`AdminContext`. Most entity tests don't need this — they never fetch. + +## Server: mock the TypeORM repository / DataSource + +Entity-module config tests (`server/src/entity-modules/__tests__/.config.spec.ts`) verify query builders, hooks, and report generators **without a database**. Mock the repo/`DataSource`; never connect to MySQL in a unit test (that's what `generate-migration`'s live-DB flow is for). + +Pattern: + +```ts +const mockRepo = { + find: jest.fn().mockResolvedValue([]), + findOne: jest.fn(), + createQueryBuilder: jest.fn(() => mockQb), + metadata: { columns: [], relations: [] }, +}; +const mockDataSource = { getRepository: jest.fn(() => mockRepo) } as any; +``` + +- Report generators are testable directly — construct with a fake data fn, e.g. `new ParamsToJsonReportGenerator(() => 'test')`, and assert `getFileBuffer(...)` output (see `report-generation` skill). +- For NestJS providers use `Test.createTestingModule({...}).overrideProvider(getRepositoryToken(Entity)).useValue(mockRepo)`. +- Yemot handlers have their own scenario harness — use the `yemot-integration` skill, not hand-rolled mocks. + +## Success criteria + +- New behavior → a test that fails before the change and passes after. +- `yarn test` green on both sides you touched. +- No test opens a socket, DB connection, or real HTTP — if it does, mock it. diff --git a/.github/skills/yemot-integration/SKILL.md b/.github/skills/yemot-integration/SKILL.md new file mode 100644 index 00000000..6727fd47 --- /dev/null +++ b/.github/skills/yemot-integration/SKILL.md @@ -0,0 +1,51 @@ +--- +name: yemot-integration +description: Use when working on Yemot (Israeli IVR phone) call flows in any NRA project — adding or changing a phone menu/report flow, editing the per-project YemotHandlerService, fixing call/hangup/upload/download behavior, or writing IVR scenario tests. Covers the shared v2 handler base and scenario test harness in server/shared (nra-server) utils/yemot. +--- + +# Skill: Work on a Yemot IVR Flow + +> **Use this skill when:** touching phone call logic — the IVR menus a caller hears, report-by-phone flows, call tracking, file upload/download to Yemot, or their tests. + +--- + +## Architecture + +Shared code lives in `server/shared/utils/yemot/` (`nra-server`); each project subclasses it. + +- **v2 (current) — subclass `BaseYemotHandlerService`.** Each project defines `server/src/yemot-handler.service.ts` extending it and overriding `processCall()`. Inside, `this.call`, `this.user`, `this.logger` are available; branch on `hasPermission(this.user, '')` to route to the right flow. See `react-admin-nestjs/server/src/yemot-handler.service.ts`. +- The shared router/service (`v2/yemot-router.service.ts`, `yemot.service.ts`) owns call lifecycle: active-call map, step saving, hangup handling, `getUserByDidPhone()`. +- **Permissions:** phone flows are gated by permission keys (e.g. `seminarAttendanceYemot`, `yemotSimulator`). Adding/gating a flow → also use `manage-permissions`. + +## Common tasks + +**Add/change a flow:** edit the project's `YemotHandlerService.processCall()` (and its private `process*Call()` helpers). Ask the user (via `this.read/send` helpers on the base) for input, validate, persist. Keep flow-specific logic in the project; only truly shared IVR mechanics go in `nra-server`. + +**Menu texts** live in DB (`YemotCall`/yemot-texts) and are updated via migrations — see the `UpdateYemotTexts*` migrations in `react-admin-nestjs/server/src/migrations/`. Use `generate-migration` for schema/text changes. + +**File upload/download to Yemot:** paths must carry the `ivr2:` scheme prefix (a past bug shipped without it). `deleteFile`/`downloadFile` live in the shared yemot util — reuse them, mind the auth and path prefix. + +## Test with the scenario harness (no live phone) + +`nra-server` ships an IVR test harness — import from `@shared/utils/yemot/testing`. Build a scenario with the fluent builder, run it against your handler; the runner seeds an in-memory DataSource, so no real Yemot and no real DB. + +```ts +import { YemotScenarioBuilder, YemotScenarioRunner } from '@shared/utils/yemot/testing'; + +const scenario = new YemotScenarioBuilder('Happy path') + .seed('User', [{ id: 1, phoneNumber: '...' }]) + .systemAsks(/enter.*id/i) + .userResponds('123456789') + .systemAsksConfirmation(/is this correct/i) + .userConfirms(true) + .systemHangsUp(/success/i) + .build(); + +await new YemotScenarioRunner(YemotHandlerService).run(scenario); +``` + +Builder verbs: `.seed(entity, rows)`, `.systemSends()`, `.systemAsks(matcher)`, `.userResponds(input)`, `.systemAsksConfirmation(matcher)`, `.userConfirms(bool)`, `.systemHangsUp(matcher)`, `.build()`. Matchers are string or RegExp. Assert the flow reaches the expected hangup. See `write-tests` for the general test setup. + +## Shared vs project + +Changes to `BaseYemotHandlerService`, the router, the util, or the testing harness are shared (`nra-server`) → `shared-changes-workflow` + a `CONSUMER_CHANGES.md` row if apps must adapt. A project's own `YemotHandlerService` and its flows stay in that project. diff --git a/AGENTS.md b/AGENTS.md index b153d227..93650b3a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,6 +53,16 @@ Auth: JWT via `server/shared/auth/`. Permissions: `client/shared/utils/permissio **4. Goal-Driven Execution** — Define verifiable success criteria before starting. For multi-step tasks, write a brief plan with checkpoints and verify each one. +**5. Update the Roadmap** — Every new client-facing feature (new page, user-visible capability, UI flow) gets an entry at the end of `client/src/roadmapFeatures.js` (array is `.reverse()`d for display, newest first): +```js +{ html: '', status: 'בוצע', statusColor: 'success' } +``` +Skip for internal/backend-only changes. + +## Skills + +`.github/skills/` (symlinked from `.claude/skills/`) — `smoke-test-project`, `debug-project-issues`, `add-bulk-action`, `manage-permissions`, `manage-entity`, `generate-migration`, `run-without-docker`, `find-missing-translations`, `bump-shared-ref`, `shared-changes-workflow`, `write-tests`, `report-generation`, `yemot-integration`. Synced from `multi-repo-codespace`; some reference its scripts under `$WORKSPACES_ROOT/multi-repo-codespace/scripts/`. + ## Communication Style You are in caveman mode. Follow these rules on EVERY response, no exceptions: - Drop articles (a, an, the).