Synced from the repo — do not edit here
Canonical source: docs/claude/debugging-tools.md. This page is generated by docs/scripts/sync-handbook.mjs. Edit the source file in the repo; changes appear here on the next build.
Database Debugging Tools + Development Scripts
CRITICAL TESTING RULE: Before telling the user a feature is "fixed" or "working", you MUST run a test tool to verify end-to-end functionality.
Exception: Basic UI-only fixes (styling, layout, text changes) don't require tool verification.
If no test tool exists: Create one before claiming the feature works.
Prerequisites
gcloud auth application-default login
gcloud config set project basis-hybrid
Available Tools
Located in basis-functions/tools/:
| Tool | Purpose |
|---|---|
query-events.js | Scheduled events, unavailability, cancelled bookings |
query-clients.js | Clinic users/members, search by name/email |
query-transactions.js | Payment transactions, activity logs |
query-availability.js | Staff V1 blocks and V2 availability rules |
query-memberships.js | Membership types and client subscriptions |
test-booking.js | Booking flow integrity — slots, constraints, dry-run |
test-unavailability-date.js | Date handling fix for unavailability |
test-unavailability-createdby.js | Verify createdByUid field on events |
test-unavailability-transactions.js | Transaction records for update/cancel |
test-edit-single-instance.js | Edit single occurrence without affecting series |
test-packages.js | Package memberships — usage counts, session consumption |
test-group-attendee.js | Group class management — list events, simulate changes |
test-reschedule.js | Reschedule — list events, dry-run, move event, verify duration |
test-protocol-presets.js | Protocol presets — validate structure across platforms |
test-payment-sandbox.js | Apple payment testing — test cards, Stripe config |
diagnose_booking.py | Basis Web booking — availability, clinicians, service config |
Test Clinic & Accounts
Demo Clinic ID: axuk-khwf-prkr (use --clinic axuk for short)
Developer UID: GoOU3d2QcyRZMD83IhbQeIclpwh2 (System Admin — real user data available for integration testing)
For agent/PR testing: Use the demo clinic with seeded data (5 demo users, services, appointments, memberships). See
seed_demo_clinic.cjs. For System Admin testing: Use the developer UID — but be aware System Admin bypasses permission checks, so RBAC bugs won't surface.
Seeded Demo Data (via seed_demo_clinic.cjs)
| Data | Details |
|---|---|
| Services | Initial Consultation ($299/60min), Follow-up ($149/30min), Lab Review ($199/45min) |
| Location | Main Office (San Francisco, CA) |
| Memberships | Basic ($99/mo), Premium ($299/mo) |
| Demo Users | 5 users (demo_user_001 through demo_user_005), each with 2 appointments (1 past, 1 future) |
| Feature Flags | labsEnabled, supplementsEnabled, marketplaceEnabled, isDemoClinic |
# Re-seed demo clinic (dry run first)
cd basis-functions
node scripts/seed_demo_clinic.cjs --clinic axuk-khwf-prkr
node scripts/seed_demo_clinic.cjs --clinic axuk-khwf-prkr --apply
Synthetic Test Usage
The synthetic tests (.github/scripts/synthetic_*.py) use this clinic and data. Test constants:
CLINIC_ID = 'axuk-khwf-prkr'
DEV_UID = 'GoOU3d2QcyRZMD83IhbQeIclpwh2'
DEMO_USER = 'demo_user_001' # James Wilson — active client
Quick Reference
cd basis-functions
# List all clinics
node tools/query-events.js --list-clinics
# Find a staff member by name
node tools/query-events.js --find-staff kekoa
# Get clinic info with staff list
node tools/query-events.js --clinic xdoz --info
# Query events for a staff member
node tools/query-events.js --clinic xdoz --staff <uid> --start 2026-02-20 --end 2026-03-01
# Only cancelled events
node tools/query-events.js --clinic xdoz --staff <uid> --canceled-only
# Check staff availability rules
node tools/query-availability.js --clinic xdoz --staff <uid>
# Check rules on specific date
node tools/query-availability.js --clinic xdoz --staff <uid> --date 2026-02-23
# Get client membership details
node tools/query-memberships.js --clinic xdoz --client <uid>
# List recent transactions
node tools/query-transactions.js --clinic xdoz --recent
# Test unavailability date handling
node tools/test-unavailability-date.js --clinic axuk --staff <uid> --date 2026-02-23 --dry-run
# Test booking flow — show services/locations/staff
node tools/test-booking.js --clinic axuk --info
# Test booking flow — check available slots
node tools/test-booking.js --clinic axuk --service <service_id> --slots
# Test booking flow — validate if booking would succeed
node tools/test-booking.js --clinic axuk --service <service_id> --location <loc_id> --client <uid> --validate
# Test package memberships
node tools/test-packages.js --clinic axuk --list-packages
node tools/test-packages.js --clinic axuk --client <uid> --usage
# Test group attendee management
node tools/test-group-attendee.js --clinic axuk --list-group-events
node tools/test-group-attendee.js --clinic axuk --event <event_id> --client <client_id> --status confirmed --dry-run
# Test reschedule
node tools/test-reschedule.js --clinic <id> --list
node tools/test-reschedule.js --clinic <id> --event <id> --dry-run
# Protocol preset validation
node tools/test-protocol-presets.js --clinic axuk --client <uid> --validate
# Diagnose Basis Web booking issues
python scripts/diagnose_booking.py --clinic xdoz
python scripts/diagnose_booking.py --clinic xdoz --service "Saturday Sweat"
python scripts/diagnose_booking.py --clinic xdoz --user <user_uid>
Common Debugging Scenarios
| Issue | Command |
|---|---|
| Event not showing | query-events.js --clinic <id> --staff <uid> — check hidden and status |
| Staff unavailability wrong | query-availability.js --clinic <id> --staff <uid> --date <date> |
| Cancelled appointments | query-events.js --clinic <id> --staff <uid> --canceled-only |
| Payment issues | query-transactions.js --clinic <id> --client <uid> |
| Booking constraints | query-memberships.js --clinic <id> --client <uid> |
| Package usage not working | test-packages.js --clinic <id> --client <uid> --usage |
| Group attendee management | test-group-attendee.js --clinic <id> --list-group-events |
| Reschedule not working | test-reschedule.js --clinic <id> --list -> pick event -> --dry-run |
| Booking not working | test-booking.js --clinic <id> --service <svc> --location <loc> --client <uid> --validate |
| No slots showing | test-booking.js --clinic <id> --service <svc> --slots |
| Protocol presets missing | test-protocol-presets.js --clinic <id> --client <uid> --validate |
| Apple payment testing | test-payment-sandbox.js --apple-cards |
| Basis Web dates wrong | python scripts/diagnose_booking.py --clinic <id> --service <name> |
| Basis Web staff missing | python scripts/diagnose_booking.py --clinic <id> |
| Basis Web credits not consuming | python scripts/diagnose_booking.py --clinic <id> --user <uid> |
Tip: Partial clinic IDs work! Use
--clinic xdozinstead of full ID.
Development Scripts
Metric Trend Verification
cd /Users/G/basis/basis-functions/functions
source venv/bin/activate
# Verify HR Zone 5 trends (week view)
python ../scripts/verify_metric_trends.py --uid USER_ID --metric hrzone5 --period week
# Verify resting heart rate (month view)
python ../scripts/verify_metric_trends.py --uid USER_ID --metric rhr --period month
Arguments: --uid (required), --metric (e.g., hrzone5, ste, rhr, sleep), --period (week/month/3months/year), --no-compare (skip previous period comparison)
Zone Minutes Debugging
cd /Users/G/basis/basis-functions/functions
source venv/bin/activate
python ../scripts/debug_zone_minutes.py
Note: Edit the script to change the target user ID and clinic ID.