Tools

A collection of small utility scripts.

Setup

Run ./setup.sh to install Claude commands, skills, and npm dependencies.

Then configure credentials for each tool:

grafana/

Copy .env.template to .env and fill in:

Variable	Description
GRAFANA_URL_DEV	Dev Grafana base URL
GRAFANA_URL_PROD	Prod Grafana base URL
GRAFANA_TOKEN_DEV	Dev Grafana API token
GRAFANA_TOKEN_PROD	Prod Grafana API token

mongo/

Copy .env.template to .env and fill in:

Variable	Description
MONGO_URL_DEV	Dev MongoDB connection string
MONGO_URL_PROD	Prod MongoDB connection string
MONGO_URL_LOCAL	Local MongoDB connection string (e.g. mongodb://localhost:27017)

couchdb/

Copy .env.template to .env and fill in:

Variable	Description
COUCH_URL_DEV	Dev CouchDB API base URL (no /_utils path)
COUCH_URL_PROD	Prod CouchDB API base URL
COUCH_USER_DEV / COUCH_PASSWORD_DEV	Dev basic-auth credentials
COUCH_USER_PROD / COUCH_PASSWORD_PROD	Prod basic-auth credentials

firebase/

Add service account JSON files to firebase/:

• firebaseKey-dev.json — dev Firebase service account
• firebaseKey-prod.json — prod Firebase service account

hrm/

Requires GitHub CLI installed and authenticated:

brew install gh && gh auth login

Firebase (firebase/)

Firebase Admin SDK utilities for user management:

• phoneNumber.js — Look up users by phone number or list all users
• updateUser.js — Update user display name, email, or role

All scripts support --prod flag to target the production Firebase project. See firebase/README.md for detailed usage.

Mongo (mongo/)

MongoDB utilities for querying and updating data:

• index.js — List available databases
• query.js — Run find queries against a collection
• update.js — Preview and apply MongoDB updates safely
• portal-user.js — Resolve a portal user's full permission chain (Users → PermissionUsers → PermissionAssignments → PermissionSets)
• sync-to-local.js — Copy collections from DEV or PROD (--prod) to local MongoDB (drop & replace)

CouchDB (couchdb/)

Read-only CouchDB utilities (sync-internal servers):

• index.js — List databases; connection module with basic auth and --prod / --region <code> support
• query.js — Fetch a doc by _id, list docs by _id prefix (--prefix role_), run Mango _find selectors, or list docs via _all_docs

HRM (hrm/)

HRM version lookup utilities:

• hrmVersion.js — Fetch HRM frontend and backend versions for dev or prod, plus the Go module versions (go-permission, go-permission-portal-enums, go-actionguard) from hrm-service git tags, and resolve the git branch each version was published from (via hrm-service publish workflow runs; --no-branch to skip)

Grafana (grafana/)

Grafana connection utilities:

• connect.js — Test Grafana connectivity and query Grafana HTTP APIs

Emulator (emulator/)

Android emulator utilities (requires adb, no credentials):

• fix-time.sh — Sync the emulator clock to real time via NTP force-refresh. Fixes the stale quickboot-snapshot clock that makes FeedMe POS refuse to boot with "This Device has incorrect time". Works on production images (no root needed), no emulator restart required.

Custom commands (.claude/commands/)

• hrm-version — Look up HRM frontend, backend, and Go module versions for both dev and prod, including the source branch each version was published from (marked (latest) when that commit is still the branch tip)
• mongo — Query MongoDB databases and collections
• mongo-update — Update MongoDB documents with preview and confirmation; includes permission-aware workflow for portal users
• portal-user — Look up portal users with full permission resolution (Users → PermissionUsers → PermissionAssignments → PermissionSets)
• grafana — Connect to Grafana and query Grafana HTTP APIs
• mongo-sync — Copy MongoDB collections from dev or prod to local with confirmation workflow
• couchdb — Query CouchDB (read-only): list databases or fetch documents
• emulator-time — Sync the Android emulator clock to real time (fixes stale quickboot-snapshot clock that blocks POS boot)

Custom skills (.claude/skills/)

• firebase — Firebase user management helpers for user lookup and updates
• mongo-sync — Copy and dump MongoDB collections from prod/dev to local
• dedup-portal-user — Option A fix for duplicate companyDB.Users docs caused by Firebase phone re-linking (back up → migrate PermissionUsers → clear stale phoneNumber → verify)

Repository conventions

• Custom .claude skills and commands should be reflected in both README.md and CLAUDE.md once the user confirms the change is wanted.

License

MIT