feat: send-email template registry + queued variant (closes #2064)

[chubes4]

Summary

Closes #2064.

Three additions, all backwards-compatible with the existing
extrachill-events → QualifyDigestAbilities consumer:

1. Template registry on datamachine/send-email — new optional
   template + context inputs. Templates are resolved via the new
   datamachine_email_templates filter ([id => callable( array $context ): string]),
   applied lazily inside execute() so consumers can hook at any
   priority before the first call. Unknown ids return a structured
   failure. Template render runs BEFORE placeholder replacement so
   templates may emit {site_name}, {year}, etc.
2. Per-site SMTP routing on datamachine/send-email — new optional
   mail_site_id input. When > 0 and multisite is active, wraps ONLY
   the wp_mail() call in switch_to_blog() / restore_current_blog().
   Validation, header building, and template rendering still run in the
   original site context. Invalid blog ids and non-multisite environments
   return a structured error.
3. datamachine/send-email-queued ability — same payload shape as
   datamachine/send-email plus send_at (ISO 8601 or unix timestamp)
   and priority. Empty send_at enqueues async via
   as_enqueue_async_action; otherwise as_schedule_single_action.
   Worker hook datamachine_send_email_worker invokes the synchronous
   ability and re-enqueues on failure with a 5-minute backoff, hard
   cap of 3 total attempts. Attempt counter rides in _attempt on the
   payload (internal — not exposed in the public schema). AS group:
   data-machine-email.

Files touched

File	Purpose
inc/Abilities/Publish/SendEmailAbility.php	Add template/context/mail_site_id inputs, datamachine_email_templates filter, switch_to_blog plumbing
inc/Abilities/Publish/SendEmailQueuedAbility.php	New ability + worker + retry policy
data-machine.php	Register SendEmailQueuedAbility in bootstrap
inc/Cli/Commands/EmailCommand.php	Add wp datamachine email send-queued mirroring send plus --send-at, --priority, --template, --context, --mail-site-id
tests/send-email-template-smoke.php	Pure-PHP smoke test covering all new behavior

Smoke test

php tests/send-email-template-smoke.php

Output:

  [PASS] send-email ability registered
  [PASS] send-email-queued ability registered
  [PASS] send-email resolvable via wp_get_ability

Case 1: backward-compat raw body
  [PASS] raw body success
  [PASS] raw body wp_mail called once
  [PASS] raw body subject placeholders resolved
  [PASS] raw body content placeholders resolved
  [PASS] raw body no switch_to_blog

Case 2: template render then placeholder replacement
  [PASS] template render success
  [PASS] template body contains rendered context
  [PASS] placeholders applied after template render

Case 3: unknown template
  [PASS] unknown template fails
  [PASS] unknown template error mentions id

Case 4: mail_site_id switches blog around wp_mail only
  [PASS] mail_site_id success
  [PASS] switch_to_blog called once with site 7
  [PASS] wp_mail observed switched blog
  [PASS] restore_current_blog returned current to 1

Case 5: invalid mail_site_id rejected
  [PASS] invalid mail_site_id fails
  [PASS] no switch_to_blog on invalid id

Case 6: queued enqueue async
  [PASS] queued async success
  [PASS] queued async returned action_id > 0
  [PASS] queued async used async action
  [PASS] queued async hook is worker

Case 7: queued send_at parses ISO 8601
  [PASS] queued ISO success
  [PASS] queued ISO used single action
  [PASS] queued ISO timestamp roughly matches

Case 8: queued invalid send_at rejected
  [PASS] invalid send_at fails

Case 9: worker retry + give up
  [PASS] worker scheduled a retry on first failure
  [PASS] retry uses worker hook
  [PASS] retry payload increments _attempt
  [PASS] retry scheduled ~5 min out
  [PASS] worker gives up at MAX_ATTEMPTS
  [PASS] worker success: no retry
  [PASS] worker success: wp_mail invoked
  [PASS] worker strips _attempt before forwarding

OK: 35 assertions passed

Manual end-to-end check (CLI)

After deploy, the queued path can be exercised end-to-end with:

# Register a fake template via wp eval, then queue + drain.
wp eval 'add_filter("datamachine_email_templates", function($t){ $t["smoke"] = fn($c) => "<p>Hello ".($c["who"] ?? "world")."</p>"; return $t; });'
wp datamachine email send-queued --to=admin@example.com --subject="Smoke {date}" --template=smoke --context='{"who":"chubes"}'
wp datamachine drain

Vendor-name grep guard

grep -E 'extrachill|sendy|easy.wp.smtp|kimaki|cc-connect|telegram|slack|whatsapp' \
  inc/Abilities/Publish/SendEmailAbility.php \
  inc/Abilities/Publish/SendEmailQueuedAbility.php \
  inc/Cli/Commands/EmailCommand.php \
  tests/send-email-template-smoke.php
# (no matches — exit 1)

Touched files are clean. Pre-existing vendor-name occurrences elsewhere in inc/ are out of scope for this PR.

Backwards compatibility

The existing single consumer (extrachill-events →
QualifyDigestAbilities::send_digest_email()) calls
datamachine/send-email with only to/subject/body/cc/headers-equivalent
fields. All new inputs are optional with sensible defaults:

• template = "" → unchanged raw-body flow
• context = [] → only consulted when template is set
• mail_site_id = 0 → no switch_to_blog

Existing wp datamachine email send CLI and the inc/Api/Email.php
REST shim are not modified — they continue to work unchanged.

What's intentionally NOT in this PR

• HTML template content / branding — belongs in extrachill-multisite (separate issue).
• Per-plugin migrations from raw wp_mail() — one issue per plugin will follow.
• Auth/permission overhaul — PermissionHelper::can_manage() stays for both abilities.
• New top-level CLI group — queued sends sit under existing wp datamachine email.

cc <@532385681268408341> — ready for review.

[homeboy-ci]

Homeboy Results — data-machine

Lint

✅ lint — passed

ℹ️ Full options: homeboy docs commands/lint
Deep dive: homeboy lint data-machine --changed-since f7c7e25

Test

✅ test — passed

• 597 passed
• 3 skipped

ℹ️ Auto-fix lint issues: homeboy refactor data-machine --from lint --write
ℹ️ Collect coverage: homeboy test data-machine --coverage
ℹ️ Save test baseline: homeboy test data-machine --baseline
ℹ️ Pass args to test runner: homeboy test -- [args]
ℹ️ Full options: homeboy docs commands/test
Deep dive: homeboy test data-machine --changed-since f7c7e25

Audit

✅ audit — passed

• requested_detectors — 35 finding(s)
• dead_code — 15 finding(s)
• parallel-implementation — 7 finding(s)
• dead_guard — 3 finding(s)
• test_coverage — 3 finding(s)
• Publish — 2 finding(s)
• intra-method-duplication — 1 finding(s)
• Total: 66 finding(s)

Deep dive: homeboy audit data-machine --changed-since f7c7e25

Tooling versions

• Homeboy CLI: homeboy 0.182.0+eaec2212
• Extension: wordpress from https://github.com/Extra-Chill/homeboy-extensions
• Extension revision: dd47f26a
• Action: unknown@unknown