suaveplan/openspec/archive/2026-05-19-add-emailer/tasks.md

Tasks — Ship @suaveplan/emailer

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/emailer.md end-to-end
• 1.2 No prior openspec/specs/emailer/spec.md exists
• 1.3 Read openspec/AGENTS.md Sections 13 and 14
• 1.4 Draft proposal.md
• 1.5 Fill in ## Source mapping
• 1.6 Draft specs/emailer/spec.md
• 1.7 Every requirement carries a **Verified by:** line

2. Implementation

• 2.1 src/error-codes.ts — defineCodes("EMAILER", [...]), 12 codes, typed EmailerError
• 2.2 src/schemas/schemas.ts — Zod schemas for every option bundle and message
• 2.3 src/types/emailer.types.ts — EmailMessage, EmailTransport, hook contexts, stats
• 2.4 src/otel/metrics.ts — counters / histogram / refreshEmailerMeters
• 2.5 src/core/validate/validate.ts — address-formatting + validation helpers
• 2.6 src/core/retry/retry.ts — deterministic retry helper (linear / exponential, AbortSignal)
• 2.7 src/core/email-service/email-service.ts — EmailService class
• 2.8 src/core/email-service/base-email-transport.ts — abstract helper
• 2.9 src/transports/dummy/dummy-transport.ts
• 2.10 src/transports/smtp/smtp-transport.ts + smtp-client-like.types.ts
• 2.11 src/transports/gmail-rest/gmail-rest-transport.ts
• 2.12 src/fakes/fake-smtp-client.ts
• 2.13 src/index.ts — explicit named re-exports, side-effect import of ./error-codes.js

3. Tests

• 3.1 Unit tests at every feature directory, all importing from @suaveplan/testing/runner
• 3.2 src/emailer.spec-conformance.test.ts — type-level, OTel, lifecycle pins
• 3.3 tests/dep-graph.test.ts, tests/no-disallowed.test.ts
• 3.4 Every it(...) carries { timeout: 5000 }

4. Documentation

• 4.1 Sibling .md for every implementation .ts (≥200 words)
• 4.2 README at package root linking every co-located .md

5. Pre-archive 5-gate triple

• 5.1 bun run check
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/emailer
• 5.3 bunx turbo test:coverage --filter=@suaveplan/emailer (100/100/100/100)
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/emailer
• 5.5 bunx turbo build --filter=@suaveplan/emailer

6. Pre-archive 9-row checklist

• 6.1 Generics threaded (EmailService<TTransport>); expectTypeOf on every literal-type claim
• 6.2 Zod schemas wired at every declared boundary
• 6.3 Every error code in EMAILER_CODES thrown by at least one production path
• 6.4 Strict-mode behaviours tested both on and off (validation, retry abort)
• 6.5 OTel instruments emitted from production paths and asserted with real in-memory MeterProvider
• 6.6 Lifecycle dedup tested (verify-fail short-circuit, queue-not-configured guard)
• 6.7 No retroactive tick
• 6.8 No export * in any non-root barrel
• 6.9 No direct vitest / bun:test imports in test files

7. Archive

• 7.1 Fold spec delta into openspec/specs/emailer/spec.md
• 7.2 Move openspec/changes/add-emailer/ → openspec/archive/2026-05-19-add-emailer/