[Alex-Dolid]

Sets up @alexify/mailer the way the other Alexis libraries are set up, before any code lands. It follows @alexify/protoarray's "set up the repository as an Alexis library" commit, with the later CI fixes and the comparison generator taken from @alexify/metaschema.

The mailer will be an email library of its own, in the place of Nodemailer or Upyo, in two parts:

• the transport: SMTP client, MIME builder, DKIM, and HTTP providers on fetch, starting with SES v2;
• a reliability layer on top: queue/outbox, audit log, delivery events, suppression, idempotency.

This PR adds only the scaffold. The API is a placeholder.

What's included

• Package: plain CommonJS, no build step, a hand-written index.d.ts, a closed exports map, files allowlist, engines >=22.0.0, pnpm 10.34.5.
• Placeholder API: createMailer(options) throws createMailer is not implemented yet. Its signature is provisional until the Phase 0 contracts (Message, Transport, QueueDriver, AuditSink).
• Tooling: oxlint and oxfmt with the shared Alexis configs, node:test with c8 gates (98/98/90/100), tsd, check:dts, pnpm size, and a zero-dependency pnpm bench. The bench has reference scenarios: base64 attachments, Message-ID, DKIM RSA-SHA256, the audit-log hashes, and the outbox record JSON.
• Tests:
  • mailer — the placeholder throws as expected;
  • export-parity — runtime exports match index.d.ts, and ESM named imports work;
  • dependencies — package.json has no dependencies/peerDependencies, and src/ requires only node:* and relative .js files;
  • bundle — the entry works after esbuild, minified and not;
  • scripts — the size budget passes, fails when exceeded, and rejects a bad argument.
• CI:
  • lint, format, size gate (4 KB min+gzip);
  • tsd and check:dts;
  • tests on Node 22/24 × Ubuntu/Windows;
  • coverage, with pipefail so the c8 gates fail the job;
  • docs build, plus a check that the comparison table matches its data;
  • one aggregate ci-success check for branch protection.
• Docs: a VitePress site for mailer.vercel.app with Why, Getting Started, Exports, and Compared with alternatives. That page holds a feature matrix of 14 Node.js email libraries, generated from docs/comparison.json by pnpm docs:comparison.
• Repository files: README, CHANGELOG (Keep a Changelog), CONTRIBUTING, SECURITY (threat model for the transport and the layers), CODE_OF_CONDUCT, CLAUDE.md (with the roadmap: phases 0–3 and decisions), and the seven metaskills (js-conventions and npm-publish adapted).

Decisions

• Node only. No browser.js or browser field: sending from a browser would expose credentials, and SMTP needs sockets.
• Zero runtime dependencies. The transports are built on node:* and fetch; SES is signed with our own SigV4. Infrastructure drivers (BullMQ, MongoDB) are passed in by the application, as @alexify/metaschema's ./mongodb takes the driver module.
• Our own transport, not a wrapper over Nodemailer. The risk is covered by a correctness suite (golden .eml, DKIM checked by an independent verifier, fuzzing) planned as P0 in Phase 1.
• The comparison matrix comes from reading each library's source as of 2026-10-07. Findings that name a bug were not reproduced, except for emailjs, and the page says so.

Verification

pnpm install --frozen-lockfile
pnpm lint && pnpm format:check
pnpm test && pnpm run test:coverage   # 100% of src/
pnpm run test:types && pnpm run check:dts
pnpm size --max-gzip 4                # 0.2 KB
pnpm docs:comparison && git diff --exit-code docs/guide/comparison.md
pnpm run docs:build
pnpm pack --dry-run                   # index.js, index.d.ts, src/, README, CHANGELOG, LICENSE, SECURITY, package.json

All of the above pass locally. I also reviewed the docs site in light and dark themes.

After merge (manual)

• Create the Vercel project mailer.vercel.app
• Branch protection on main requiring ci-success
• Enable private vulnerability reporting

🤖 Generated with Claude Code