Extract shared executeWithGuards helper across spark types

[UniquePixels]

Context

Audit ID: ARCH-5

All four spark types follow the same guards / attempt / log pattern with minor signature variations. A shared `executeWithGuards()` helper would reduce maintenance, especially if more spark types are added.

Approach

Design a generic helper that handles guard execution, attempt wrapping, and error logging. Adapt each spark type's `execute()` to use it. Low priority but should be done before adding new spark types.

Files

• `src/core/sparks/command.ts`
• `src/core/sparks/component.ts`
• `src/core/sparks/event.ts`
• `src/core/sparks/scheduled-event.ts`

[coderabbitai]

Coding Plan

Summary

• Create a single executeWithGuards helper with silent and returnOnActionError options to handle all four spark type variations
• Spark-specific pre-processing (command type check, component param extraction) remains in each spark file
• Action callbacks are passed as closures, allowing each spark to customize arguments while the helper handles the common guard/attempt/log pattern
• Helper lives in src/core/sparks/execute-helper.ts alongside the spark implementations it serves

Design Choices

Design Choice 1: Should param extraction in component.ts occur before or after the helper call?

Options Considered:

1. Move param extraction before the helper call (minor behavior change: params parsed even on guard failure)
2. Keep component.ts partially using the old pattern (reduces value of extraction)
3. Add a pre-action hook to the helper (adds complexity)

Chosen Option: 1

Rationale: The customId is available before guards and doesn't depend on the guarded type; extracting early is semantically acceptable and keeps the refactor clean.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Create the Shared Helper

Implement a flexible executeWithGuards helper that encapsulates the guard-execute-log pattern with configuration options to accommodate all four spark type variations.

Task 1: Design and Implement executeWithGuards Helper

Create a new helper function that handles guard execution, action wrapping, and error logging with configurable behavior for the variations across spark types.

• Create src/core/sparks/execute-helper.ts with the executeWithGuards function
• Define an options interface accepting: guards array, input, logger, context string, action callback, error log fields, error log message
• Add optional flags: silent (controls processGuards behavior, default false) and returnOnActionError (controls whether action failures return early, default true)
• Internally call processGuards with the silent option, return early on guard failure
• Wrap the action callback in attempt(), log errors with provided fields/message
• If returnOnActionError is true, return { ok: false, reason: 'An internal error occurred.' } on action failure; otherwise fall through and return the guard result

Task 2: Export Helper from Sparks Module

Make the helper available for import across the spark type files.

• Export executeWithGuards and its options type from src/core/sparks/execute-helper.ts
• Re-export from src/core/sparks/index.ts for consistency with other spark utilities

Task 3: Add Unit Tests for the Helper

Verify the helper correctly handles all configuration combinations and edge cases.

• Create src/core/sparks/execute-helper.test.ts
• Test guard success path returns the guarded value
• Test guard failure path returns the failure reason
• Test action error with returnOnActionError: true returns internal error result
• Test action error with returnOnActionError: false logs but returns guard result
• Test silent: true option is passed to processGuards
• Use mocking patterns from src/core/lib/test-helpers/

🤖 Prompt for AI agents

Create a new shared helper in `src/core/sparks/execute-helper.ts` that
encapsulates the common guard-execute-log pattern used across all four spark
types, then export it and write unit tests.

**Implement `executeWithGuards` in `src/core/sparks/execute-helper.ts`:**
- Define an options interface that accepts: guards array, input, logger, context
string, action callback, error log fields, error log message
- Add optional boolean flags: `silent` (default `false`, passed to
`processGuards`) and `returnOnActionError` (default `true`)
- Internally call `processGuards` with the `silent` option; return early if
guards fail
- Wrap the action callback in `attempt()`; log errors using the provided fields
and message
- If `returnOnActionError` is `true`, return `{ ok: false, reason: 'An internal
error occurred.' }` on action failure; otherwise fall through and return the
guard result
- Export `executeWithGuards` and its options type from this file
- Re-export both from `src/core/sparks/index.ts`

**Create unit tests in `src/core/sparks/execute-helper.test.ts`:**
- Test guard success path returns the guarded value
- Test guard failure path returns the failure reason
- Test action error with `returnOnActionError: true` returns internal error
result
- Test action error with `returnOnActionError: false` logs but returns guard
result
- Test that `silent: true` is correctly passed through to `processGuards`
- Follow mocking patterns from `src/core/lib/test-helpers/`

Phase 2: Refactor Spark Types to Use Helper

Update each spark type's execute() method to delegate to executeWithGuards while preserving spark-specific pre-processing logic.

Task 1: Refactor command.ts

Adapt the command spark to use the shared helper, keeping the pre-guard type mismatch check.

• Import executeWithGuards from the new helper module
• Keep the pre-guard isContextMenuBuilder !== isContextMenuInteraction check and early return
• Replace the guard/attempt/log block with a single executeWithGuards call
• Pass: guards, interaction, interaction.client.logger, context command:${command.name}
• Pass action as (guarded) => action(guarded), error fields { command: command.name }, message 'Command action failed'
• Use default options (silent: false, returnOnActionError: true)

Task 2: Refactor component.ts

Adapt the component spark, moving param extraction before the helper call.

• Import executeWithGuards from the new helper module
• Move the parameterized ID extraction logic (regex matching on customId) before the helper call
• Replace the guard/attempt/log block with executeWithGuards
• Pass action as a closure: (guarded) => action(guarded, params) to include extracted params
• Pass context component:${key}, error fields { component: key }, message 'Component action failed'
• Use default options (silent: false, returnOnActionError: true)

Task 3: Refactor gateway-event.ts

Adapt the gateway event spark with silent mode and fall-through error handling.

• Import executeWithGuards from the new helper module
• Replace the guard/attempt/log block with executeWithGuards
• Pass: guards, eventArgs[0] as input, client.logger, context gateway:${String(event)}
• Pass action as (guarded) => action(guarded, ...eventArgs.slice(1), client) preserving the spread signature
• Set silent: true and returnOnActionError: false
• Error fields { event }, message 'Gateway event action failed'

Task 4: Refactor scheduled-event.ts

Adapt the scheduled event spark with silent mode and fall-through error handling.

• Import executeWithGuards from the new helper module
• Replace the guard/attempt/log block with executeWithGuards
• Pass: guards, ctx as input, ctx.client.logger, context scheduled:${id}
• Pass action as () => action(ctx)
• Set silent: true and returnOnActionError: false
• Error fields { scheduled: id }, message 'Scheduled event action failed'

Task 5: Verify Existing Tests Pass

Ensure all existing spark type tests continue to pass after refactoring.

• Run tests for command.ts, component.ts, gateway-event.ts, scheduled-event.ts
• Verify no behavioral changes except the documented component.ts param extraction timing
• Fix any test failures caused by mock adjustments needed for the new import

🤖 Prompt for AI agents

Refactor the `execute()` method in each of the four spark type files to delegate
to the `executeWithGuards` helper, preserving spark-specific pre-processing
logic.

**`command.ts`:**
- Import `executeWithGuards` from the new helper module
- Retain the pre-guard `isContextMenuBuilder !== isContextMenuInteraction` check
and its early return
- Replace the guard/attempt/log block with `executeWithGuards`, passing: guards,
interaction, `interaction.client.logger`, context `command:${command.name}`,
action as `(guarded) => action(guarded)`, error fields `{ command: command.name
}`, message `'Command action failed'`
- Use default options (`silent: false`, `returnOnActionError: true`)

**`component.ts`:**
- Import `executeWithGuards` from the new helper module
- Move the parameterized ID extraction logic (regex matching on `customId`) to
before the helper call
- Replace the guard/attempt/log block with `executeWithGuards`, passing: guards,
interaction, logger, context `component:${key}`, action as `(guarded) =>
action(guarded, params)`, error fields `{ component: key }`, message `'Component
action failed'`
- Use default options (`silent: false`, `returnOnActionError: true`)

**`gateway-event.ts`:**
- Import `executeWithGuards` from the new helper module
- Replace the guard/attempt/log block with `executeWithGuards`, passing: guards,
`eventArgs[0]` as input, `client.logger`, context `gateway:${String(event)}`,
action as `(guarded) => action(guarded, ...eventArgs.slice(1), client)`, error
fields `{ event }`, message `'Gateway event action failed'`
- Set `silent: true` and `returnOnActionError: false`

**`scheduled-event.ts`:**
- Import `executeWithGuards` from the new helper module
- Replace the guard/attempt/log block with `executeWithGuards`, passing: guards,
`ctx` as input, `ctx.client.logger`, context `scheduled:${id}`, action as `() =>
action(ctx)`, error fields `{ scheduled: id }`, message `'Scheduled event action
failed'`
- Set `silent: true` and `returnOnActionError: false`

**Verification:**
- Run tests for all four spark types (`command.ts`, `component.ts`,
`gateway-event.ts`, `scheduled-event.ts`)
- Confirm no behavioral regressions except the documented `component.ts` param
extraction timing change
- Fix any test failures caused by mock adjustments needed for the new import

Research

The src/core/sparks/ directory contains the core spark type implementations (command.ts, component.ts, gateway-event.ts, scheduled-event.ts). Each spark's execute() method follows the same structural pattern: run guards via processGuards() from @/core/guards, execute the action wrapped in attempt() from @/core/lib/attempt, and log errors with logger.error(). Variations exist in silent mode, error handling behavior, and action signatures. The src/core/lib/ directory houses shared utilities, making src/core/sparks/ the natural home for a new spark-specific helper.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create a new shared helper in `src/core/sparks/execute-helper.ts` that
encapsulates the common guard-execute-log pattern used across all four spark
types, then export it and write unit tests.

**Implement `executeWithGuards` in `src/core/sparks/execute-helper.ts`:**
- Define an options interface that accepts: guards array, input, logger, context
string, action callback, error log fields, error log message
- Add optional boolean flags: `silent` (default `false`, passed to
`processGuards`) and `returnOnActionError` (default `true`)
- Internally call `processGuards` with the `silent` option; return early if
guards fail
- Wrap the action callback in `attempt()`; log errors using the provided fields
and message
- If `returnOnActionError` is `true`, return `{ ok: false, reason: 'An internal
error occurred.' }` on action failure; otherwise fall through and return the
guard result
- Export `executeWithGuards` and its options type from this file
- Re-export both from `src/core/sparks/index.ts`

**Create unit tests in `src/core/sparks/execute-helper.test.ts`:**
- Test guard success path returns the guarded value
- Test guard failure path returns the failure reason
- Test action error with `returnOnActionError: true` returns internal error
result
- Test action error with `returnOnActionError: false` logs but returns guard
result
- Test that `silent: true` is correctly passed through to `processGuards`
- Follow mocking patterns from `src/core/lib/test-helpers/`
===============================================================================

Task: 2

Refactor the `execute()` method in each of the four spark type files to delegate
to the `executeWithGuards` helper, preserving spark-specific pre-processing
logic.

**`command.ts`:**
- Import `executeWithGuards` from the new helper module
- Retain the pre-guard `isContextMenuBuilder !== isContextMenuInteraction` check
and its early return
- Replace the guard/attempt/log block with `executeWithGuards`, passing: guards,
interaction, `interaction.client.logger`, context `command:${command.name}`,
action as `(guarded) => action(guarded)`, error fields `{ command: command.name
}`, message `'Command action failed'`
- Use default options (`silent: false`, `returnOnActionError: true`)

**`component.ts`:**
- Import `executeWithGuards` from the new helper module
- Move the parameterized ID extraction logic (regex matching on `customId`) to
before the helper call
- Replace the guard/attempt/log block with `executeWithGuards`, passing: guards,
interaction, logger, context `component:${key}`, action as `(guarded) =>
action(guarded, params)`, error fields `{ component: key }`, message `'Component
action failed'`
- Use default options (`silent: false`, `returnOnActionError: true`)

**`gateway-event.ts`:**
- Import `executeWithGuards` from the new helper module
- Replace the guard/attempt/log block with `executeWithGuards`, passing: guards,
`eventArgs[0]` as input, `client.logger`, context `gateway:${String(event)}`,
action as `(guarded) => action(guarded, ...eventArgs.slice(1), client)`, error
fields `{ event }`, message `'Gateway event action failed'`
- Set `silent: true` and `returnOnActionError: false`

**`scheduled-event.ts`:**
- Import `executeWithGuards` from the new helper module
- Replace the guard/attempt/log block with `executeWithGuards`, passing: guards,
`ctx` as input, `ctx.client.logger`, context `scheduled:${id}`, action as `() =>
action(ctx)`, error fields `{ scheduled: id }`, message `'Scheduled event action
failed'`
- Set `silent: true` and `returnOnActionError: false`

**Verification:**
- Run tests for all four spark types (`command.ts`, `component.ts`,
`gateway-event.ts`, `scheduled-event.ts`)
- Confirm no behavioral regressions except the documented `component.ts` param
extraction timing change
- Fix any test failures caused by mock adjustments needed for the new import

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

🔗 Related PRs

#6 - 🌈 improve(testing): consolidate test utilities [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!