Repository Tooling & Operational Scripts Reference
This document is the authoritative engineering catalog for all operational, verification, database integrity, deployment, and disaster recovery scripts residing in the [scripts/](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/scripts) directory. Grounded directly in 61 executable automation scripts, this catalog details CLI execution parameters, target invariants, automated CI integration points, and operational use cases.
1. Overview & Execution Standards
All scripts in scripts/ are designed for idempotent execution from the repository root. They interface with local Dockerized Supabase containers or remote staging/production environments via standard environment variables (SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, DATABASE_URL).
graph TD
Root[Monorepo Root] --> DBChecks[Database Integrity & RLS: 40+ db-*-checks.mjs]
Root --> Boundaries[Architecture & Boundary Verifiers: find-admin-violations.cjs]
Root --> Infra[DNS & Cloudflare Sync: sync-cloudflare-dns.mjs]
Root --> DR[Disaster Recovery Drills: command-center-recovery-drill.mjs]
Root --> Compliance[Security & SBOM: generate-sbom.mjs]1.1 Global Execution Conventions
- Module Format: Node.js ESM (
.mjs) or CommonJS (.cjs). - Exit Codes: Returns
0on success; exits with non-zero code (1or2) upon invariant violations or assertion failures. - Fail-Safe: Scripts mutate database state within explicitly rolled-back transactions unless explicitly invoked with
--commitor running in dedicated migration test runners.
2. Database Verification & Concurrency Harness (40+ Scripts)
Executed during local developer resets (supabase db reset) and continuously within GitHub Actions CI via [scripts/db-flow-tests.sh](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/scripts/db-flow-tests.sh).
2.1 Access Control, Staff Permissions & RBAC
| Script File | Target Invariant / Verification Scope |
|---|---|
db-access-tests.mjs | Master Row-Level Security verification suite testing cross-tenant data isolation. |
db-command-table-privilege-checks.mjs | Verifies that direct table INSERT/UPDATE/DELETE privileges are revoked from application roles. |
db-granular-command-capability-checks.mjs | Validates staff permission strings (canManageOrders, canManageFinances, canManageKYC). |
db-launch-staff-capability-checks.mjs | Confirms staff role elevation triggers and AAL2 MFA enforcement checks. |
db-staff-access-command-checks.mjs | Asserts that staff privilege grants are audited in audit_log with timestamped expirations. |
db-staff-invitation-checks.mjs | Tests staff onboarding token issuance, cryptographic hashing, and single-use redemption. |
2.2 Financial Ledger, Escrow & Order Snapshots
| Script File | Target Invariant / Verification Scope |
|---|---|
db-finance-checks.mjs | Asserts general ledger equilibrium: $\sum \text{Credits} - \sum \text{Debits} = 0$. |
db-order-fee-snapshot-checks.mjs | Verifies that order_fee_snapshots calculations remain permanently frozen post-checkout. |
db-checkout-payment-intent-checks.mjs | Simulates checkout intent reservation, stock allocation, and 30-minute expiry timeouts. |
db-payment-intent-inspection-checks.mjs | Tests administrative inspection queries over unconfirmed Paystack checkout intents. |
db-wallet-checks.mjs | Validates that wallet balance updates cannot result in negative balances (balance >= 0). |
db-legacy-wallet-boundary-checks.mjs | Confirms deprecation of unreviewed wallet adjustments (20261011000000). |
2.3 Payouts, Batches & Reconciliations
| Script File | Target Invariant / Verification Scope |
|---|---|
db-reviewed-payout-batch-checks.mjs | Validates Maker-Checker dual authorization for vendor payout batch dispatches. |
db-payout-reconciliation-checks.mjs | Tests reconciliation between Paystack gateway balance and internal escrow liabilities. |
db-payout-transfer-intent-checks.mjs | Asserts unique transfer reference generation and NUBAN check-digit compliance. |
db-payout-exception-checks.mjs | Validates automated error categorization on failed or reversed bank transfers. |
2.4 Refunds, Disputes & Return Cases
| Script File | Target Invariant / Verification Scope |
|---|---|
db-reviewed-wallet-refund-checks.mjs | Tests dual-authorization wallet refunds, ensuring single-actor approvals are rejected. |
db-atomic-return-case-checks.mjs | Validates atomic return case transitions and evidenceFingerprint hashing. |
2.5 High-Concurrency & Race Condition Simulations
| Script File | Target Invariant / Verification Scope |
|---|---|
db-native-concurrency-tests.mjs | Spawns concurrent asynchronous workers competing for the last stock unit; asserts no overselling. |
db-native-return-concurrency-tests.mjs | Simulates concurrent refund requests on a single order; confirms double-refund lockouts. |
2.6 Privacy, Right to be Forgotten & DSAR (NDPA)
| Script File | Target Invariant / Verification Scope |
|---|---|
db-privacy-checks.mjs | Baseline test verifying personal data redaction triggers. |
db-privacy-erasure-plan-checks.mjs | Asserts that erasure impact assessment plans correctly flag erasable vs retained records. |
db-privacy-erasure-execution-checks.mjs | Validates batch deletion across 7 erasable tables while preserving financial ledgers. |
db-subject-privacy-export-checks.mjs | Verifies packaging of personal data exports with SHA-256 digests and 10 MB caps. |
db-expanded-privacy-export-checks.mjs | Validates data inclusion across orders, chats, reviews, and addresses. |
db-privacy-export-artifact-checks.mjs | Tests secure presigned URL generation and 7-day automatic artifact expiration. |
2.7 Moderation & Trust & Safety
| Script File | Target Invariant / Verification Scope |
|---|---|
db-moderation-case-checks.mjs | Validates the 3-strike escalation ladder and automated listing quarantine. |
db-moderation-appeal-checks.mjs | Tests vendor suspension appeal submission, reviewer assignment, and resolution. |
2.8 Customer Support & Outbox Daemons
| Script File | Target Invariant / Verification Scope |
|---|---|
db-support-conversation-checks.mjs | Asserts ticket creation, message threading, and CSAT rating recording. |
db-support-triage-checks.mjs | Validates optimistic concurrency locking during simultaneous agent triage. |
db-support-view-checks.mjs | Tests staff ticket queue filtering by campus and priority. |
db-support-attachment-checks.mjs | Validates presigned URL issuance for private support attachments. |
db-support-notification-outbox-checks.mjs | Validates transactional outbox queueing for asynchronous customer notifications. |
2.9 Governance, Merchandising & Campus Operations
| Script File | Target Invariant / Verification Scope |
|---|---|
db-campus-governance-checks.mjs | Asserts campus pickup hub registration and student ambassador scope validation. |
db-campus-order-checks.mjs | Validates campus scope isolation on order queries (orders.operation_campus). |
db-category-commission-checks.mjs | Tests category-specific commission rate overrides in basis points. |
db-category-governance-checks.mjs | Validates category taxonomy management and parent-child hierarchy depth. |
db-admin-order-status-boundary-checks.mjs | Verifies that administrative order status overrides strictly enforce legal state paths. |
db-configuration-checks.mjs | Validates versioned platform configuration updates. |
configuration-review-db-tests.mjs | Tests the 4-Eyes Principle proposal and approval lifecycle for platform settings. |
db-control-checks.mjs | Asserts platform maintenance mode locking and feature freeze triggers. |
2.10 Auditing & Observability
| Script File | Target Invariant / Verification Scope |
|---|---|
db-audit-export-checks.mjs | Validates tamper-evident audit log extraction to encrypted CSV files. |
db-chunked-audit-export-checks.mjs | Tests cursor-based chunking for multi-gigabyte compliance audit log extractions. |
db-queue-observations-checks.mjs | Verifies BullMQ queue depth and dead-letter observation metric collection. |
db-inbox-campaign-checks.mjs | Tests campus broadcast notification targeting and recipient expansion. |
3. Architecture & Boundary Verification Scripts
Executed in pre-commit hooks and CI pipelines to enforce monorepo architecture rules:
3.1 Admin Surface Isolation (find-admin-violations.cjs)
Scans apps/storefront/src/ to ensure no administrative components, routes, or controllers are imported into the storefront bundle:
node scripts/find-admin-violations.cjs
# Exits with code 1 if any 'debelu-admin' import is detected3.2 Single React Runtime Guard (check-react-runtime.cjs)
Verifies that all workspace packages resolve to a single, identical React 19 instance in node_modules/, preventing dual-instance context bugs:
node scripts/check-react-runtime.cjs3.3 Configuration Drift Detection (check-drift.mjs)
Compares active environment settings against baseline configuration templates, flagging undocumented variables or missing secrets.
4. Infrastructure & DNS Deployment Scripts
4.1 Cloudflare DNS Synchronization (sync-cloudflare-dns.mjs)
Synchronizes apex domain and subdomain DNS records across Railway, Cloudflare Pages, and Vercel edge networks via Cloudflare API:
node scripts/sync-cloudflare-dns.mjs4.2 Supabase Auth Email Template Deployment (deploy-auth-templates.ps1)
PowerShell deployment script compiling and pushing branded HTML transactional email templates (welcome, password reset, magic link) to the Supabase Auth server.
5. Security & Compliance Utilities
5.1 Software Bill of Materials Generator (generate-sbom.mjs)
Generates an audited CycloneDX-compliant Software Bill of Materials ([sbom.json](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/sbom.json)) inventorying all direct and transitive open-source dependencies for security compliance.
node scripts/generate-sbom.mjs5.2 Frontend Credential Verifier (verify-frontend-credentials.cjs)
Scans compiled production bundles (dist/, .next/) to guarantee that no secret keys (PAYSTACK_SECRET_KEY, SUPABASE_SERVICE_ROLE_KEY) are accidentally leaked into client code:
node scripts/verify-frontend-credentials.cjs6. Disaster Recovery & Command Center Drills
6.1 Recovery Drill Runner (command-center-recovery-drill.mjs)
Simulates 8 catastrophic operational failures (database outage, Paystack gateway drop, R2 media unavailability, queue failure, etc.) asserting automated failovers and RTO/RPO SLAs:
node scripts/command-center-recovery-drill.mjs
npm run test scripts/recovery-drill.test.mjs7. Operational Preview Utilities
preview-email.mjs: Renders responsive transactional email templates locally in a browser window.preview-invoice.mjs: Generates and renders a sample buyer escrow invoice / PDF receipt.inspect-granular.mjs: CLI utility inspecting the exact permission matrix assigned to a specific staff user ID.
8. Document Revision History
| Revision | Date | Lead Author | Scope of Changes | Status |
|---|---|---|---|---|
1.0.0 | 2026-10-05 | Principal SRE & Automation Engineer | Complete enterprise scripts reference cataloging all 61 repository utility, verification, concurrency, and disaster recovery scripts. | Active Living Standard |