@carecard/validate 3.27.0 → 3.29.0

package/.agents/skills/pkg-validate-validation-library/SKILL.md

@@ -101,6 +101,9 @@ depend on those folders being present.
 - Keep key-based property sanitization in `lib/validateProperties.js`.
 - Keep whitelist, nested-path, casing, flattening, and CareCard bad-input
   behavior in `lib/validateWhitelistProperties.js`.
+- Import shared casing and bad-input behavior through the focused
+  `@carecard/common-util/case-converter` and `@carecard/common-util/errors`
+  entrypoints so the package root remains safe for browser bundles.
 - Preserve the package's CommonJS module style unless the repository is
   intentionally migrated.
 - Keep the deprecated `validate` namespace export backward-compatible while
@@ -124,7 +127,8 @@ depend on those folders being present.
 - `validateProperties` should return a new sanitized object and omit unknown or
   invalid fields without mutating the input.
 - `validateWhitelistProperties` should reject missing or invalid required fields
-  with CareCard `BAD_INPUT` errors through `@carecard/common-util`.
+  with CareCard `BAD_INPUT` errors through the focused
+  `@carecard/common-util/errors` entrypoint.
 - Optional whitelist fields should be ignored when absent and rejected when
   present but invalid.
 - Preserve supported snake_case and camelCase field aliases unless a task
@@ -196,41 +200,42 @@ and remaining risk.
 
 ## Remote Git Operations Guardrail
 
-Do not run remote Git or GitHub operations unless the current user request explicitly asks for them. This includes `git fetch`, `git pull`, `git push`, `git push --delete`, remote branch cleanup, GitHub API calls, and any `gh pr` command that creates, updates, readies, merges, closes, or cleans up a pull request. Do not infer permission from branch names, validation needs, prior workflow habits, or convenience; ask first when remote state would help but was not requested.
+Fetches needed to establish a fresh `origin/main` at task start and before a
+source-branch push are authorized without a separate approval question. Commits,
+pushes, PR mutations, and branch cleanup require an authorized task; a request
+for local work alone does not authorize publication. An authorized squash merge
+into `main` includes the merged-source cleanup, local `main` update, and
+`development` synchronization below unless the user explicitly says otherwise.
+Never delete local or remote `main`, or force-push to remote `main`, including
+with `--force-with-lease`.
 
 ## Agent Guidance Git Workflow
 
-When this skill or any repository-owned `.agents` guidance changes, use the
-repository's agents-only Git workflow:
-
-1. Work from the affected repository root and confirm only intended `.agents`
-   files changed.
-2. Use `development` as the base branch when `origin/development` exists;
-   otherwise use the repository's default base branch, usually `main`.
-3. Create or update `feature/codex` from the updated remote base branch and
-   commit all the changed `.agents` guidance files there.
-4. Push `feature/codex`, create or reuse a pull request into the base branch,
-   and mark the pull request ready for review with `gh pr ready <number>`.
-5. Squash-merge with administrator privileges and delete the remote branch:
-
-   ```sh
-   gh pr merge <number> --squash --admin --delete-branch
-   ```
-
-6. After merge, update the local base branch and remove the local feature
-   branch:
-
-   ```sh
-   git fetch origin <base> --prune
-   git switch <base>
-   git pull --ff-only origin <base>
-   git branch -d feature/codex
-   git ls-remote --heads origin feature/codex
-   ```
-
-Do not commit or push `.agents` guidance changes directly from `development`
-or `main`. Do not stage unrelated files, generated output, dependency folders,
-build artifacts, logs, or `.DS_Store`.
+Work from the owning repository root and stage only intended guidance changes.
+Use freshly fetched `origin/main` as the default base. Start `<agent-name>/<task-name>`
+from it, or rebase existing work when it does not already contain the latest
+`origin/main`. An explicit user instruction to use the current or another
+working branch overrides the default `<agent-name>/<task-name>` selection.
+
+Fetch again before every source-branch push and rebase only when the branch
+does not already contain the latest `origin/main`. Required fetches need no
+separate approval; commits, pushes, PR mutations, and cleanup require an
+authorized task. A local guidance edit does not authorize publishing it.
+
+For an authorized merge, create or reuse the PR into `main`, run applicable
+validation, and squash-merge; administrator privileges may be used without
+GitHub reviews. Verify the merge and delete its source branch remotely and
+locally after checking for newer unmerged work. Then fast-forward local `main`
+and replace local and remote branches named exactly `development` with the
+latest remote `main` commit, using an explicit observed-commit
+`--force-with-lease` remotely. Create a missing development counterpart when
+either existed; leave repositories with neither unchanged. If development was
+the merged source, recreate it from the new main. Verify commit parity and
+cleanup; preserve dirty worktrees and report conflicts or rejected leases.
+
+Never delete local or remote `main` or force-push to remote `main`, including
+with `--force-with-lease`. Guard exact destination refs before deleting or
+forcing any branch. Do not amend commits or stage unrelated files.
 
 ## Fail-Closed Test Lifecycle Audit
 

package/.codex/AGENTS.md

@@ -1,5 +1,17 @@
 # Codex Instructions For pkg-validate
 
+## Mandatory startup for every agent
+
+Every agent, including Codex, Claude, other assistants, and delegated agents,
+must read and follow [carecard-must-do](../.agents/skills/carecard-must-do/SKILL.md)
+before beginning or resuming any task. This includes planning, questions,
+read-only investigation, coding, review, documentation, and validation.
+
+Then load the [repository engineering standards](../.agents/skills/pkg-validate-coding-standards-and-best-practices/SKILL.md)
+and the specialist skills relevant to the task.
+An agent without automatic skill discovery must open the skill explicitly;
+the requirement applies regardless of the agent platform.
+
 ## Non-negotiable Codex banked-reset requirement
 
 - Never use or consume a banked Codex rate-limit reset automatically.
@@ -133,10 +145,10 @@ The `pkg-*` directories are reusable CareCard packages. Shared API response, err
 - Use coverage reports only as diagnostics for potentially untested observable behavior. Percentages for lines, branches, functions, and statements are not functional evidence and must not determine test assertions. Never add implementation-detail tests to preserve a metric or lower thresholds to hide a failing check; report any conflict with the behavior-only policy.
 - Keep tests readable and domain-specific. Prefer explicit helper names over generic test utilities that hide important behavior.
 - Use existing test frameworks and layouts:
-    - JavaScript `api-*`: usually Mocha, Supertest, `test/index.test.js`, and Docker-backed Postgres scripts.
-    - TypeScript `api-*`: usually Jest and `tests/index.test.ts`.
-    - `pkg-*`: Mocha plus TypeScript type tests where present.
-    - `app-dashboard`: Vitest, React Testing Library, mock API tests, and Selenium for end-to-end flows.
+  - JavaScript `api-*`: usually Mocha, Supertest, `test/index.test.js`, and Docker-backed Postgres scripts.
+  - TypeScript `api-*`: usually Jest and `tests/index.test.ts`.
+  - `pkg-*`: Mocha plus TypeScript type tests where present.
+  - `app-dashboard`: Vitest, React Testing Library, mock API tests, and Selenium for end-to-end flows.
 - For database tests, use existing seed, migration, rollback, and cleanup patterns. Keep tests isolated and make cleanup reliable even after failures.
 - Add tests for API success responses, validation errors, auth/authz errors, JWT errors, not-found/conflict cases, and unexpected error handling when those paths change.
 - For frontend changes, test rendered UI, public HTTP or network outcomes, navigation, accessibility, and user-visible flows at the narrowest practical level first. Use focused non-test dependency checks for validation, transform, query, mutation, hook, and module organization.

package/AGENTS.md

@@ -1,4 +1,16 @@
-# Codex Instructions
+# Agent Instructions
+
+## Mandatory startup for every agent
+
+Every agent, including Codex, Claude, other assistants, and delegated agents,
+must read and follow [carecard-must-do](.agents/skills/carecard-must-do/SKILL.md)
+before beginning or resuming any task. This includes planning, questions,
+read-only investigation, coding, review, documentation, and validation.
+
+Then load the [repository engineering standards](.agents/skills/pkg-validate-coding-standards-and-best-practices/SKILL.md)
+and the specialist skills relevant to the task.
+An agent without automatic skill discovery must open the skill explicitly;
+the requirement applies regardless of the agent platform.
 
 ## Non-negotiable Codex banked-reset requirement
 

package/CLAUDE.md

@@ -0,0 +1,43 @@
+# Repository Agent Instructions
+
+## Mandatory startup for every agent
+
+Every agent, including Codex, Claude, other assistants, and delegated agents,
+must read and follow [carecard-must-do](.agents/skills/carecard-must-do/SKILL.md)
+before beginning or resuming any task. This includes planning, questions,
+read-only investigation, coding, review, documentation, and validation.
+
+Then load the [repository engineering standards](.agents/skills/pkg-validate-coding-standards-and-best-practices/SKILL.md)
+and the specialist skills relevant to the task.
+An agent without automatic skill discovery must open the skill explicitly;
+the requirement applies regardless of the agent platform.
+
+Also read [AGENTS.md](AGENTS.md) for the full repository instructions.
+
+## Existing repository isolation contract
+
+Non-negotiable repository isolation rule: Every repository must run its Husky
+hooks and tests using only files, code, fixtures, dependencies, and services
+contained within that repository. Tests and Husky scripts must not import,
+require, read, execute, or otherwise depend on sibling repositories or paths
+outside the repository root. app-e2e-tests is the only exception because
+cross-repository end-to-end testing is its explicit responsibility.
+
+Also apply [$carecard-workspace-standards](.agents/skills/carecard-workspace-standards/SKILL.md)
+for the mandatory TDD and code organization rules.
+
+## Existing test-preservation policy
+
+The TDD and validation requirements are non-negotiable and cannot be
+overridden. The separate pre-existing-test protection still requires the
+user's fresh, explicit permission for each exact proposed test modification.
+
+A pre-existing test—defined as any test present before work on the current task
+begins—must not be deleted, disabled, skipped, weakened, excluded from execution,
+or otherwise removed. A pre-existing test must not be modified without the
+user's explicit approval for the exact proposed change. If changing a
+pre-existing test is believed necessary, stop before making the change and
+request approval. The request must identify every affected test, describe the
+precise proposed modification, provide detailed technical justification, and
+explain all known or reasonably foreseeable regression risks. Until approval is
+granted, leave every pre-existing test unchanged.

package/lib/validateNewUserRoleRequest.js

@@ -1,8 +1,6 @@
 'use strict';
 
-const {
-  error: { throwBadInputError },
-} = require('@carecard/common-util');
+const { throwBadInputError } = require('@carecard/common-util/errors');
 const { isUserRoleRequestRoleString } = require('./validate');
 
 const DEFAULT_USER_ROLE_REQUEST_ROLE = 'student';

package/lib/validateWhitelistProperties.js

@@ -1,9 +1,7 @@
 'use strict';
 
-const {
-  error: { throwBadInputError },
-  caseConverter: { keysToSnakeCase },
-} = require('@carecard/common-util');
+const { keysToSnakeCase } = require('@carecard/common-util/case-converter');
+const { throwBadInputError } = require('@carecard/common-util/errors');
 
 const { validateProperties } = require('./validateProperties');
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carecard/validate",
-  "version": "3.27.0",
+  "version": "3.29.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/CareCard-ca/pkg-validate.git"
@@ -47,7 +47,7 @@
     "typescript": "6.0.3"
   },
   "dependencies": {
-    "@carecard/common-util": "3.27.0"
+    "@carecard/common-util": "3.29.0"
   },
   "nyc": {
     "all": true,
@@ -67,6 +67,6 @@
     "glob": "13.0.6",
     "minimatch": "10.2.6",
     "serialize-javascript": "7.0.5",
-    "js-yaml": "4.3.1"
+    "js-yaml": "4.3.2"
   }
 }

package/readme.md

@@ -54,6 +54,11 @@ General validators are available both as top-level exports and under the
 deprecated `validate` namespace. `validatePassword` is intentionally available
 only as one direct export.
 
+The package root is safe to import from browser bundles. Its whitelist and role
+request validators use the focused `@carecard/common-util/case-converter` and
+`@carecard/common-util/errors` entrypoints, so importing `isEmailString` does
+not load server-only request context or trace storage.
+
 ```js
 isEmailString('jane@example.com'); // true
 validate.isEmailString('jane@example.com'); // true
@@ -204,12 +209,12 @@ await validateWhitelistProperties(input, ['user.first_name', 'user.contact.email
 
 ### Options
 
-| Option               | Default  | Behavior                                                                                                                                                                           |
-| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `optionalProperties` | `[]`     | Additional property paths that may be present. Absent optional paths are ignored. Present optional paths must be valid.                                                            |
-| `convertToSnakeCase` | `false`  | When `true`, converts returned keys, including nested keys, to snake_case using `@carecard/common-util`. Conversion happens before flattening.                                     |
-| `flattenOutput`      | `false`  | When `true`, removes nested objects from the returned value so every validated leaf becomes a top-level key.                                                                       |
-| `flattenKeyStyle`    | `'path'` | Controls flattened key naming when `flattenOutput` is `true`. Use `'path'` for full dot-notation keys or `'leaf'` for direct leaf names. Invalid values throw a `BAD_INPUT` error. |
+| Option               | Default  | Behavior                                                                                                                                                                                  |
+| -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `optionalProperties` | `[]`     | Additional property paths that may be present. Absent optional paths are ignored. Present optional paths must be valid.                                                                   |
+| `convertToSnakeCase` | `false`  | When `true`, converts returned keys, including nested keys, to snake_case using the browser-safe `@carecard/common-util/case-converter` entrypoint. Conversion happens before flattening. |
+| `flattenOutput`      | `false`  | When `true`, removes nested objects from the returned value so every validated leaf becomes a top-level key.                                                                              |
+| `flattenKeyStyle`    | `'path'` | Controls flattened key naming when `flattenOutput` is `true`. Use `'path'` for full dot-notation keys or `'leaf'` for direct leaf names. Invalid values throw a `BAD_INPUT` error.        |
 
 Example with only the default options: