@carecard/auth-util 3.1.16 → 3.2.0

package/.agents/skills/github-pr-create-update/SKILL.md

@@ -1,70 +1,57 @@
 ---
 name: github-pr-create-update
-description: 'Use only when the user explicitly asks for remote Git or GitHub PR work: pushing a branch, creating or updating a PR, or marking a PR ready from the current repository branch.'
+description: 'Use only when the user explicitly asks for remote Git or GitHub PR work: pushing a branch, creating or updating a PR, or marking a PR ready from the current repository branch into development or main.'
 ---
 
 # Pull Request Create
 
 ## Purpose
 
-After the user explicitly asks for remote Git or GitHub PR work, create, update, verify, push, and mark ready a GitHub pull request from the current repository branch into origin/development.
+After the user explicitly asks for remote Git or GitHub PR work, create,
+update, verify, push, and mark ready a GitHub pull request from the current
+repository branch into `development`, or into `main` when `development` is
+absent.
 
 ## When To Use
 
-- Use only when the user explicitly asks to create, update, push for, or mark ready a GitHub pull request from the current repository branch.
+- Use only when the user explicitly asks to create, update, push for, or mark
+  ready a GitHub pull request from the current repository branch.
 
 ## When Not To Use
 
-- Do not use for merging or deleting an already-approved pull request; use the merge cleanup skill.
+- Do not use for merging or deleting an already-approved pull request; use the
+  merge cleanup skill.
 - Do not use for ordinary local commits that do not involve GitHub PR work.
 
 ## 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.
-
-## Relevant Files And Directories
-
-- Git branch state in this repository
-- GitHub pull requests viewed with `gh`
-- repository validation commands and `.husky` scripts
-
-## Coding Principles
-
-- Preserve the repository structure, naming style, module system, and local helper patterns.
-- Prefer readable, maintainable code with meaningful function, variable, file, and test names.
-- Avoid new dependencies unless the existing stack cannot reasonably solve the task and the user confirms the tradeoff.
-
-## Testing Expectations
-
-- Run repository validation before PR creation or merge when code behavior changed.
-- Confirm the branch is clean except intended changes before finishing.
-
-## Safety Constraints
-
-- Do not edit generated output, dependency folders, logs, coverage, dist, or build artifacts unless the task requires it.
-- Do not revert or overwrite user changes; stage only requested skill or instruction files.
-- Never suppress errors, lint failures, type failures, security failures, or failing tests; fix the underlying issue or report the blocker.
-
-## Commit Continuation Rule
-
-Do not amend commits unless the user explicitly asks. If
-hook, formatter, documentation, skill, validation, or review follow-up changes
-appear after a commit, stage only the intended files and make a new commit with
-a clear message.
+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.
 
 ## Scope
 
 Use this skill from the root of the repository whose current branch contains
-the intended PR changes. The repository must have `origin/development`, and
-GitHub CLI must be available and authenticated.
+the intended PR changes. The repository must have `origin/development` or
+`origin/main`, and GitHub CLI must be available and authenticated.
+
+Default terms:
+
+- Base branch: `development` when `origin/development` exists; otherwise
+  `main` when `origin/main` exists.
+- Source branch: the current branch unless the user names another branch.
 
 Do not continue automatically when:
 
-- The current branch is `development`, `main`, `master`, or detached.
+- The source branch is `development`, `main`, `master`, or detached.
 - The working tree has uncommitted changes. Explain that a PR only includes
   committed changes and ask the user whether to commit or stash them.
 - `gh auth status` fails.
-- `origin/development` cannot be fetched.
+- Neither `origin/development` nor `origin/main` exists.
 
 ## Workflow
 
@@ -80,30 +67,26 @@ Do not continue automatically when:
    gh auth status
    ```
 
-2. Pull a fresh development reference from the remote without leaving the
-   source branch:
+2. Select the pull request base branch. Prefer `development`; use `main` only
+   when `origin/development` is absent:
 
    ```sh
-   git fetch origin development --prune
-   ```
-
-   Use `origin/development` as the source of truth. If a local `development`
-   branch exists and is not checked out, it may be fast-forwarded to match the
-   remote without forcing history:
-
-   ```sh
-   git fetch origin development:development
+   if git ls-remote --exit-code --heads origin development >/dev/null 2>&1; then
+     base="development"
+   elif git ls-remote --exit-code --heads origin main >/dev/null 2>&1; then
+     base="main"
+   else
+     echo "No origin/development or origin/main branch exists."
+     exit 1
+   fi
+   git fetch origin "$base" --prune
    ```
 
-   If that local branch update fails because `development` has diverged or is
-   checked out in another worktree, do not force it. Continue using
-   `origin/development` for validation.
-
-3. Check whether the current branch can merge with latest development without
+3. Check whether the current branch can merge with the latest base without
    changing the worktree:
 
    ```sh
-   if git merge-tree --write-tree HEAD origin/development >/tmp/pull-request-create-merge-tree.out
+   if git merge-tree --write-tree HEAD "origin/$base" >/tmp/pull-request-create-merge-tree.out
    then
      merge_conflict_detected=false
    else
@@ -111,11 +94,11 @@ Do not continue automatically when:
    fi
    ```
 
-4. If a merge conflict is detected, try rebasing on latest development:
+4. If a merge conflict is detected, try rebasing on the latest base:
 
    ```sh
    if [ "$merge_conflict_detected" = true ]; then
-     if git rebase origin/development; then
+     if git rebase "origin/$base"; then
        git push --force-with-lease -u origin "$branch"
      else
        git rebase --abort
@@ -127,62 +110,58 @@ Do not continue automatically when:
    fi
    ```
 
-   Do not resolve rebase conflicts unless the user explicitly asks. If the
-   rebase fails, abort it and stop.
+   Do not use `--no-verify`; pre-push hooks must run. Do not resolve rebase
+   conflicts unless the user explicitly asks.
 
-5. Inspect the branch changes before writing the PR title:
+5. Verify the remote branch matches local `HEAD`:
 
    ```sh
-   git log --reverse --format='%s' origin/development..HEAD
-   git diff --stat origin/development...HEAD
+   local_sha="$(git rev-parse HEAD)"
+   remote_sha="$(git ls-remote --heads origin "$branch" | awk '{print $1}')"
+   test "$local_sha" = "$remote_sha"
    ```
 
-   Create a concise, descriptive title from the actual changes. Remove words
-   such as `draft`, `[draft]`, `Draft:`, and `WIP`. Do not leave a generic title
-   such as "updates", "changes", or "draft PR".
+6. Inspect the branch changes before writing the PR title:
 
-6. Reuse an existing open PR for this branch when present:
+   ```sh
+   git log --reverse --format='%s' "origin/$base..HEAD"
+   git diff --stat "origin/$base...HEAD"
+   ```
+
+7. Reuse an existing open PR for this exact branch/base pair when present:
 
    ```sh
    pr_number="$(gh pr list \
      --head "$branch" \
-     --base development \
+     --base "$base" \
      --state open \
      --json number \
      --jq '.[0].number // empty')"
    ```
 
-7. If there is no PR, create one against `development` and capture the new PR
-   number:
+8. If there is no PR, create one against the selected base and capture the new
+   PR number:
 
    ```sh
    pr_url="$(gh pr create \
-     --base development \
+     --base "$base" \
      --head "$branch" \
      --title "$title" \
      --body "$body")"
    pr_number="$(gh pr view "$pr_url" --json number --jq '.number')"
    ```
 
-   Keep the body factual. Mention the main changes and validation commands
-   that were actually run.
-
-8. If a PR exists, mark it ready when it is a draft:
+9. If a PR exists, mark it ready when it is a draft, then keep the title
+   descriptive:
 
    ```sh
    is_draft="$(gh pr view "$pr_number" --json isDraft --jq '.isDraft')"
    if [ "$is_draft" = "true" ]; then
      gh pr ready "$pr_number"
    fi
-   ```
-
-9. Update the PR title after create/reuse so it is descriptive and contains no
-   draft wording:
-
-   ```sh
    gh pr edit "$pr_number" --title "$title"
    ```
 
-10. Final response should include the PR URL, whether a rebase was performed,
-    whether an existing PR was reused or marked ready, and any validation that
-    could not be run.
+10. Final response should include the PR URL, selected base branch, whether a
+    rebase was performed, whether an existing PR was reused or marked ready,
+    and any validation that could not be run.

package/.agents/skills/github-pr-merge-cleanup/SKILL.md

@@ -1,56 +1,38 @@
 ---
 name: github-pr-merge-cleanup
-description: 'Use only when the user explicitly asks for remote Git or GitHub PR work: reviewing remote mergeability, validating, merging, closing, deleting, or cleaning up a pull request branch.'
+description: 'Use only when the user explicitly asks for remote Git or GitHub PR work: pushing a branch, creating a missing PR, reviewing mergeability, validating, merging, deleting, or cleaning up a pull request branch.'
 ---
 
 # Pull Request Merge Close
 
 ## Purpose
 
-After the user explicitly asks for remote Git or GitHub PR work, review, validate, merge, close, delete branch, and clean local state for a GitHub pull request targeting origin/development.
+After the user explicitly asks for remote Git or GitHub PR work, push the
+branch, create a missing PR when needed, review, validate, merge, delete the
+branch when allowed, and clean local state for a GitHub pull request targeting
+`development`, or `main` when `development` is absent.
 
 ## When To Use
 
-- Use only when the user explicitly asks to review mergeability, validate, merge, close, or clean up a GitHub pull request branch.
+- Use only when the user explicitly asks to push, review mergeability,
+  validate, merge, close, or clean up a GitHub pull request branch.
 
 ## When Not To Use
 
-- Do not use for creating a new pull request; use the PR create/update skill.
-- Do not use when the user only asks for local code changes without PR merge work.
+- Do not use for PR-only creation/update work without a merge request; use the
+  PR create/update skill.
+- Do not use when the user only asks for local code changes without PR merge
+  work.
 
 ## 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.
-
-## Relevant Files And Directories
-
-- Git branch state in this repository
-- GitHub pull requests viewed with `gh`
-- repository validation commands and `.husky` scripts
-
-## Coding Principles
-
-- Preserve the repository structure, naming style, module system, and local helper patterns.
-- Prefer readable, maintainable code with meaningful function, variable, file, and test names.
-- Avoid new dependencies unless the existing stack cannot reasonably solve the task and the user confirms the tradeoff.
-
-## Testing Expectations
-
-- Run repository validation before PR creation or merge when code behavior changed.
-- Confirm the branch is clean except intended changes before finishing.
-
-## Safety Constraints
-
-- Do not edit generated output, dependency folders, logs, coverage, dist, or build artifacts unless the task requires it.
-- Do not revert or overwrite user changes; stage only requested skill or instruction files.
-- Never suppress errors, lint failures, type failures, security failures, or failing tests; fix the underlying issue or report the blocker.
-
-## Commit Continuation Rule
-
-Do not amend commits unless the user explicitly asks. If
-hook, formatter, documentation, skill, validation, or review follow-up changes
-appear after a commit, stage only the intended files and make a new commit with
-a clear message.
+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.
 
 ## Scope
 
@@ -60,8 +42,8 @@ branch available locally or on `origin`.
 
 Default terms:
 
-- Base branch: `development` when `origin/development` exists, otherwise the
-  repository default branch.
+- Base branch: `development` when `origin/development` exists, otherwise
+  `main` when `origin/main` exists.
 - Target branch: the current branch unless the user names another branch.
 - Pull request: the open PR whose head is the target branch and whose base is
   the base branch.
@@ -72,35 +54,86 @@ Do not continue automatically when:
 - The target branch is detached or is the base branch.
 - The working tree has uncommitted changes that are not part of the requested
   PR cleanup.
-- No open PR exists for the target branch.
+- Neither `origin/development` nor `origin/main` exists.
 - A rebase or validation fix would require behavior changes instead of coding
   criteria cleanup.
 
+If no open pull request exists for the target branch and selected base, create
+one as part of the merge workflow when the user requested push/PR/merge
+completion.
+
 ## Workflow
 
-1. Capture the base branch, target branch, PR number, and protection state:
+1. Capture the base branch, target branch, and authentication state:
 
    ```sh
    gh auth status
-   base="development"
-   git ls-remote --exit-code --heads origin development >/dev/null 2>&1 || \
-     base="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')"
+   if git ls-remote --exit-code --heads origin development >/dev/null 2>&1; then
+     base="development"
+   elif git ls-remote --exit-code --heads origin main >/dev/null 2>&1; then
+     base="main"
+   else
+     echo "No origin/development or origin/main branch exists."
+     exit 1
+   fi
    target_branch="$(git branch --show-current)"
    test -n "$target_branch"
    test "$target_branch" != "$base"
    git status --short
+   ```
+
+   If the user names a target branch, use that branch instead of the current
+   branch. If the target branch is not local but exists on `origin`, create a
+   local branch from the remote head before continuing:
+
+   ```sh
+   if ! git show-ref --verify --quiet "refs/heads/$target_branch"; then
+     git fetch origin "$target_branch:$target_branch"
+   fi
+   git switch "$target_branch"
    git fetch origin "$base" --prune
-   pr_number="$(gh pr list --head "$target_branch" --base "$base" --state open --json number --jq '.[0].number // empty')"
-   test -n "$pr_number"
-   protected="$(gh api "repos/{owner}/{repo}/branches/$target_branch" --jq '.protected' 2>/dev/null || echo false)"
    ```
 
-   If the PR head branch is not local, create a local branch from the remote
-   head before continuing.
+2. Push the target branch to the same remote branch name. Do not use
+   `--no-verify`; pre-push hooks must run.
 
-2. Check mergeability before changing history:
+   ```sh
+   git push -u origin "$target_branch"
+   local_sha="$(git rev-parse HEAD)"
+   remote_sha="$(git ls-remote --heads origin "$target_branch" | awk '{print $1}')"
+   test "$local_sha" = "$remote_sha"
+   ```
+
+3. Reuse an existing open PR for this exact branch/base pair, or create one
+   when none exists:
+
+   ```sh
+   pr_number="$(gh pr list \
+     --head "$target_branch" \
+     --base "$base" \
+     --state open \
+     --json number \
+     --jq '.[0].number // empty')"
+
+   if [ -z "$pr_number" ]; then
+     git log --reverse --format='%s' "origin/$base..HEAD"
+     git diff --stat "origin/$base...HEAD"
+     pr_url="$(gh pr create \
+       --base "$base" \
+       --head "$target_branch" \
+       --title "$title" \
+       --body "$body")"
+     pr_number="$(gh pr view "$pr_url" --json number --jq '.number')"
+   fi
+   ```
+
+4. Mark draft PRs ready and check mergeability before changing history:
 
    ```sh
+   is_draft="$(gh pr view "$pr_number" --json isDraft --jq '.isDraft')"
+   if [ "$is_draft" = "true" ]; then
+     gh pr ready "$pr_number"
+   fi
    gh pr view "$pr_number" --json mergeStateStatus,mergeable,headRefName,baseRefName
    if git merge-tree --write-tree HEAD "origin/$base" >/tmp/pull-request-merge-close-merge-tree.out
    then
@@ -110,7 +143,7 @@ Do not continue automatically when:
    fi
    ```
 
-3. If a merge conflict is detected, rebase the target branch on the fresh base
+5. If a merge conflict is detected, rebase the target branch on the fresh base
    branch. Abort and stop if the rebase conflicts:
 
    ```sh
@@ -125,33 +158,14 @@ Do not continue automatically when:
    fi
    ```
 
-   Do not resolve rebase conflicts unless the user explicitly asks.
-
-4. Load and apply all relevant repository skills before merging:
-   - Read the repository's `.agents/skills/**/SKILL.md` files that apply to the
-     changed code, plus shared workspace standards when present.
-   - Compare the target branch against the base with
-     `git diff --stat "origin/$base...HEAD"` and inspect changed files.
-   - Check whether the target branch satisfies the applicable coding,
-     architecture, validation, security, and style criteria from those skills.
-   - Run the validation commands required by the skills and repository hooks.
-   - If criteria are not met and the fix does not change functionality, make the
-     minimal cleanup, stage only intended files, commit to the target branch,
-     and push the target branch.
-   - If meeting the criteria would change behavior, stop and report the gap.
-
-5. Confirm the PR is still mergeable after validation changes:
-
-   ```sh
-   git fetch origin "$base" --prune
-   git merge-tree --write-tree HEAD "origin/$base" >/tmp/pull-request-merge-close-final-merge-tree.out
-   gh pr checks "$pr_number"
-   ```
+6. Load and apply all relevant repository skills before merging, then confirm
+   the PR is still mergeable after any validation changes.
 
-6. Merge the PR with GitHub CLI. Delete the remote target branch only when it is
+7. Merge the PR with GitHub CLI. Delete the remote target branch only when it is
    not protected:
 
    ```sh
+   protected="$(gh api "repos/{owner}/{repo}/branches/$target_branch" --jq '.protected' 2>/dev/null || echo false)"
    if [ "$protected" = true ]; then
      gh pr merge "$pr_number" --squash --admin
    else
@@ -159,17 +173,27 @@ Do not continue automatically when:
    fi
    ```
 
-7. Clean up the local repository after merge:
+8. If the merge succeeded and the remote branch still exists while unprotected,
+   delete it explicitly:
 
    ```sh
-   git fetch origin "$base" --prune
+   if [ "$protected" != true ] && git ls-remote --exit-code --heads origin "$target_branch" >/dev/null 2>&1; then
+     git push origin --delete "$target_branch"
+   fi
+   ```
+
+9. Clean up the local repository after merge:
+
+   ```sh
+   git fetch origin --prune
    git switch "$base"
    git pull --ff-only origin "$base"
    git branch -d "$target_branch" || git branch -D "$target_branch"
    git ls-remote --heads origin "$target_branch"
    ```
 
-8. Final response should include the PR URL, whether a rebase was performed,
-   what validation and skill checks ran, whether any cleanup commit was added,
-   whether the remote target branch was deleted or protected, and whether local
-   development is up to date.
+10. Final response should include the PR URL, selected base branch, whether a
+    rebase was performed, what validation and skill checks ran, whether any
+    cleanup commit was added, whether the remote target branch was deleted or
+    protected, whether the local target branch was deleted, and whether local
+    base branch is up to date.

package/.agents/skills/npm-package-flow/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: npm-package-flow
+description: 'Use in pkg-* repositories when publishable package code changes require a version bump, GitHub development/main squash-merge flow, npm publication, and uncommitted consumer package updates in ms-* and app-dashboard.'
+---
+
+# npm Package Flow
+
+## Purpose
+
+Use this skill in a `pkg-*` repository when package code changes need to be
+published to npm and propagated to CareCard consumers.
+
+The package name is the `name` field in the repository `package.json`.
+
+## Publishable vs Non-Publishable Changes
+
+Publishable package changes include runtime source changes, public exports,
+TypeScript declarations, package metadata that affects consumers, security
+behavior, or dependency behavior that changes the package contract.
+
+The following are not publishable package changes by themselves:
+
+- Skills or `.agents` guidance.
+- Documentation and README updates.
+- Tests, fixtures, mocks, snapshots, or validation-only changes.
+- Formatting-only changes and comments.
+
+For non-publishable changes, do not bump the package version, publish to npm,
+or update `ms-*` and `app-dashboard` package versions.
+
+## Required Flow For Publishable Changes
+
+Run this workflow only when the user explicitly asks for package publication,
+remote GitHub merge work, or the full package-flow completion. Remote Git and
+GitHub operations must not be inferred.
+
+1. Finish package code, tests, documentation, and skill updates inside the
+   current `pkg-*` repository.
+2. Bump the package version in `package.json` and `package-lock.json` according
+   to the user request or the package change scope.
+3. Run the package's required tests, lint, type checks, and every direct Husky
+   script. Fix failures before continuing.
+4. Commit the package changes to the current branch.
+5. Push the current branch, create or reuse the PR into `development`,
+   squash-merge it with administrator privileges, and delete the merged branch.
+6. Create a new merge branch from the updated `development` branch and use that
+   branch to open a PR into `main`.
+7. Squash-merge the merge branch into `main` with administrator privileges and
+   delete the merge branch. This `main` merge publishes the package.
+8. Confirm publication with `npm view <package-name>@<version> version`.
+9. Check out a fresh local branch with the same name as the deleted working
+   branch from the updated `development` branch.
+10. Update the new `@carecard/...` package version in `app-dashboard` and in
+    only the `ms-*` repositories that already declare the package, plus any
+    explicitly intended new consumers.
+11. Run `npm install` and relevant validation in each updated consumer.
+12. Do not commit the `ms-*` or `app-dashboard` consumer updates unless the user
+    explicitly asks.
+
+## Consumer Update Rules
+
+- Discover existing consumers by checking each target repository `package.json`
+  for the published package name.
+- Install exact package versions, for example
+  `npm install <package-name>@<version> --save-exact`.
+- Keep consumer updates local and uncommitted unless the user gives a separate
+  commit or PR instruction.
+- If a consumer should become a new dependency, require explicit user intent for
+  that repository.
+
+## Reporting
+
+Report the package name, published version, development PR, main PR, npm
+publication check, consumer repositories updated, validation commands run, and
+any consumer updates intentionally left uncommitted.

package/.agents/skills/npm-package-flow/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: 'npm Package Flow'
+  short_description: 'Use in pkg-* repositories when publishable @carecard package code changes need npm publication and consumer updates.'
+  brand_color: '#0F766E'
+  default_prompt: 'Use $npm-package-flow when this task matches the skill scope.'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carecard/auth-util",
-  "version": "3.1.16",
+  "version": "3.2.0",
   "repository": "https://github.com/CareCard-ca/pkg-auth-util.git",
   "description": "Auth utility functions",
   "main": "index.js",
@@ -42,7 +42,7 @@
     "typescript": "6.0.3"
   },
   "dependencies": {
-    "@carecard/common-util": "3.1.15",
-    "@carecard/validate": "3.1.27"
+    "@carecard/common-util": "3.2.0",
+    "@carecard/validate": "3.3.0"
   }
 }