Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .claude/skills
26 changes: 24 additions & 2 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.
**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: '<Hebrew description>', 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.
79 changes: 79 additions & 0 deletions .github/skills/add-bulk-action/SKILL.md
Original file line number Diff line number Diff line change
@@ -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/<entity>.jsx` and `server/src/entity-modules/<entity>.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=<name>&extra.ids=<selectedIds>&...` → `BaseEntityController.doAction` → `<Entity>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 `<Input>` 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/<entity>.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/<entity>.config.ts`:
- Override `doAction(req, body)` on the entity's service class (extend `BaseEntityService`) if not already overridden.
- Add a `case '<name>':` 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 <project>`) 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/<entity>.jsx`.
2. Find the matching `case '<name>':` in that entity's `doAction()` in `server/src/entity-modules/<entity>.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, `<BulkFixReferenceButton key="fixReferences" label="תיקון שיוך" />`
- 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.<field>` |
| 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 |
106 changes: 106 additions & 0 deletions .github/skills/bump-shared-ref/SKILL.md
Original file line number Diff line number Diff line change
@@ -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/<project>/client/shared # or server/shared
git fetch origin
git log --oneline HEAD..<target-branch-or-commit> # 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/<project>/client/shared # or server/shared
git checkout <target-commit-or-branch>
cd /workspaces/<project>
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/<name>.jsx`, `entity-modules/<name>.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/<changed files> # adjust for client vs server side
git commit -m "chore: bump client/shared to <short-hash>

- <consumer change 1, if any>
- <consumer change 2, if any>"
```

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/<project>/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 |
Loading
Loading