Utilities & Maintenance

The ds utils commands provide operational tools for maintenance, data repair, and codebase health checks. These are primarily used by developers maintaining production or investigating data integrity issues.

Maintenance Mode

Enable Maintenance Mode

ds utils maintenance-mode enable

Sets DEVSTRIDE_MAINTENANCE_MODE=true on all Lambda functions in the target stage. While enabled:

• API requests are blocked
• The UI shows a maintenance page
• Background event processors continue running (to drain queues)

Disable Maintenance Mode

ds utils maintenance-mode disable

Removes the DEVSTRIDE_MAINTENANCE_MODE environment variable from all Lambda functions, restoring normal operation.

Data Repair Commands

These commands fix data integrity issues that can arise from bugs, migration edge cases, or manual database edits.

Repair Item Aggregations

ds utils repair item-aggregations --target phil-local -o org_abc123

Recalculates rolled-up values on parent items, boards, and work types:

Scans all children to rebuild aggregation values from source data.

Options:

When to use:

• Item counts or estimates appear incorrect in the UI
• After bulk data imports or migrations
• After fixing data corruption

Repair Item Hierarchy

ds utils repair item-hierarchy --target phil-local -o org_abc123

Rebuilds the hierarchy and hierarchyPath fields by walking the entire parent-child tree. Fixes broken hierarchy metadata without deleting any items.

Options:

When to use:

• Items appear in wrong hierarchy positions
• Parent-child relationships display incorrectly
• After reparenting operations that didn't update paths

Repair Min/Max Dates

ds utils repair min-max-dates --target phil-local

Recalculates rolled-up date ranges on parent items:

• Earliest start date from all children
• Latest end date from all children
• Recursively processes the full item tree

When to use:

• Gantt chart date ranges look incorrect
• After bulk date changes on child items
• Parent items show dates that don't encompass their children

Cleanup Commands

Delete Orphaned Items

# Preview what would be deleted
ds utils delete-orphaned-items --target phil-local --dry-run

# Execute deletion
ds utils delete-orphaned-items --target phil-local

Finds items with no valid parent and deletes them with full cascading cleanup:

Options:

Query Active Emails

ds utils query-active-emails --target dev

Exports active user emails to two files:

• emails.csv — CSV format with headers
• emails.txt — Comma-separated unique list

Criteria: Users who are active members of organizations with active subscriptions. Useful for announcements, user count audits, or marketing.

Codebase Audit Commands

These commands check for common issues in the codebase — missing registrations, incomplete wiring, or forgotten init files.

Check Missing Inits

ds utils check missing-inits

Scans Command and Query handler files and reports any that aren't registered in their module's init file. Unregistered handlers will never execute because the DI container doesn't know about them.

Check Missing Correlation IDs

ds utils check missing-correlation-ids

Checks that all handlers call setCorrelationId() for distributed tracing. Missing correlation IDs make it difficult to trace requests through the event-driven system.

Check Missing Event Handlers

ds utils check missing-event-handlers

Scans for event handler files not wired up in module init files:

• Domain event handlers
• Integration event handlers
• FIFO handlers
• GitHub webhook handlers

Unwired handlers exist on disk but will never be triggered.

Next Steps

• AWS Operations — Cleaning up orphaned cloud resources
• Command Reference — Complete CLI reference