hatchkit 0.1.41 → 0.1.43

package/dist/email/setup.js

@@ -0,0 +1,263 @@
+/*
+ * Email setup orchestrator.
+ *
+ * Configures Cloudflare Email Routing end-to-end for one zone:
+ *   1. Enable Email Routing on the zone (idempotent).
+ *   2. Verify (or add) the destination address — the verification email
+ *      lands in the user's inbox; they click the link before routing
+ *      starts working. Skipping verify isn't an option — Cloudflare
+ *      rejects forwards to unverified destinations.
+ *   3. Upsert the receiving MX records (3 Cloudflare hosts).
+ *   4. Upsert a single SPF TXT, merging Cloudflare's include with any
+ *      pre-existing senders (e.g. Resend). One SPF record per zone is
+ *      the RFC 7208 rule — multiple records cause PermError.
+ *   5. Upsert a DMARC TXT at `_dmarc.<zone>`. Default `p=quarantine`
+ *      with `sp=none` to avoid breaking subdomain senders.
+ *   6. Create the forwarding rules — one per `<localPart>@<zone>` →
+ *      destination. Idempotent: existing rules with matching matchers
+ *      get their forward updated; otherwise we POST a new rule.
+ *   7. Optionally set the catch-all (a single rule per zone, separate
+ *      endpoint from the rule list).
+ *
+ * Caller surfaces results via the {@link EmailSetupResult} so the
+ * create/adopt run-ledger can record each newly created resource for
+ * later rollback.
+ */
+import chalk from "chalk";
+import { CloudflareApi, } from "../utils/cloudflare-api.js";
+import { buildDmarcRecord, buildSpfRecord, parseSpfIncludes } from "./spf.js";
+/** Cloudflare-published MX hosts for Email Routing. Verified against
+ *  what `GET /zones/{id}/email/routing/dns` returns — kept hardcoded
+ *  so a hatchkit run can describe the records up-front without an
+ *  extra API call, and because the values have been stable since the
+ *  Email Routing product launched. The API stays the source of truth
+ *  in practice: the email module calls `getEmailRoutingDnsRecords()`
+ *  and uses *those* values, falling back to this list only if CF is
+ *  unreachable. */
+export const CLOUDFLARE_EMAIL_ROUTING_MX = [
+    { host: "route1.mx.cloudflare.net", priority: 1 },
+    { host: "route2.mx.cloudflare.net", priority: 2 },
+    { host: "route3.mx.cloudflare.net", priority: 3 },
+];
+export async function runEmailSetup(opts) {
+    const cf = new CloudflareApi({ token: opts.token, accountId: opts.accountId });
+    const zone = await cf.getZoneByName(opts.domain);
+    if (!zone) {
+        throw new Error(`No Cloudflare zone for "${opts.domain}". Add the zone to your CF account and re-run.`);
+    }
+    const accountId = opts.accountId ?? zone.account?.id;
+    if (!accountId) {
+        throw new Error(`Cloudflare account id could not be resolved for zone ${opts.domain}. Set it via \`hatchkit config add dns\` (advanced — leave blank only when the token spans one account).`);
+    }
+    // Step 1 — enable routing on the zone. Idempotent; CF returns the
+    // current settings on re-enable. We still record whether *this* call
+    // flipped enabled=false → true so the rollback ledger doesn't yank
+    // a routing setup the user enabled by hand earlier.
+    const beforeRouting = await cf.getEmailRouting(zone.id);
+    if (!beforeRouting?.enabled) {
+        await cf.enableEmailRouting(zone.id);
+    }
+    const routingEnabledThisRun = !beforeRouting?.enabled;
+    // Step 2 — destination address. CF sends a verification email if it
+    // didn't already exist.
+    const dest = await cf.addEmailDestination(accountId, opts.destination);
+    // Step 3 — MX records. Fetch CF's recommended list first (in case the
+    // hosts change), fall back to the constant if the call fails.
+    let mxRecords = CLOUDFLARE_EMAIL_ROUTING_MX.map((m) => ({
+        name: opts.domain,
+        content: m.host,
+        priority: m.priority,
+    }));
+    try {
+        const recommended = await cf.getEmailRoutingDnsRecords(zone.id);
+        const mx = recommended.filter((r) => r.type === "MX");
+        if (mx.length > 0) {
+            mxRecords = mx.map((r) => ({
+                name: r.name,
+                content: r.content,
+                priority: r.priority ?? 10,
+            }));
+        }
+    }
+    catch {
+        // Fall back to constants — see the comment on
+        // CLOUDFLARE_EMAIL_ROUTING_MX. CF's list is authoritative; the
+        // fallback keeps setup working if that one endpoint flakes.
+    }
+    const dnsRecords = [];
+    for (const mx of mxRecords) {
+        const res = await cf.upsertRecord(zone.id, {
+            type: "MX",
+            name: mx.name,
+            content: mx.content,
+            priority: mx.priority,
+        });
+        dnsRecords.push({
+            id: res.id,
+            name: mx.name,
+            type: "MX",
+            content: mx.content,
+            created: res.created,
+            updated: res.updated,
+        });
+    }
+    // Step 4 — SPF. Merge Cloudflare's include with whatever's already on
+    // the zone (Resend, SES, etc.) and any caller-supplied includes.
+    const existingSpf = await findApexSpf(cf, zone.id, opts.domain);
+    const mergedIncludes = new Set(["_spf.mx.cloudflare.net"]);
+    for (const inc of opts.extraSpfIncludes ?? [])
+        mergedIncludes.add(inc);
+    if (existingSpf) {
+        for (const inc of parseSpfIncludes(existingSpf.content))
+            mergedIncludes.add(inc);
+    }
+    const spfContent = buildSpfRecord({ includes: [...mergedIncludes] });
+    // Delete any *other* SPF TXT records first — exactly one SPF record
+    // per zone per RFC 7208. The upsert below patches `existingSpf` in
+    // place; stale duplicates (zone moved between providers, etc.) get
+    // removed here.
+    await deleteStaleSpfRecords(cf, zone.id, opts.domain, existingSpf?.id);
+    const spfRes = await cf.upsertRecord(zone.id, {
+        type: "TXT",
+        name: opts.domain,
+        content: spfContent,
+    });
+    dnsRecords.push({
+        id: spfRes.id,
+        name: opts.domain,
+        type: "TXT",
+        content: spfContent,
+        created: spfRes.created,
+        updated: spfRes.updated,
+    });
+    // Step 5 — DMARC.
+    const dmarcName = `_dmarc.${opts.domain}`;
+    const dmarcContent = buildDmarcRecord({
+        rua: opts.dmarcRua ?? `dmarc@${opts.domain}`,
+        policy: opts.dmarcPolicy ?? "quarantine",
+    });
+    const dmarcRes = await cf.upsertRecord(zone.id, {
+        type: "TXT",
+        name: dmarcName,
+        content: dmarcContent,
+    });
+    dnsRecords.push({
+        id: dmarcRes.id,
+        name: dmarcName,
+        type: "TXT",
+        content: dmarcContent,
+        created: dmarcRes.created,
+        updated: dmarcRes.updated,
+    });
+    // Step 6 — per-address forwarding rules.
+    const rules = [];
+    for (const localPart of opts.addresses) {
+        const address = `${localPart}@${opts.domain}`;
+        const res = await cf.upsertEmailRoutingRule(zone.id, {
+            address,
+            forwardTo: [opts.destination],
+            name: `Forward ${address}`,
+        });
+        rules.push({ address, id: res.id, created: res.created, updated: res.updated });
+    }
+    // Step 7 — catch-all (zone-level singleton). `changed` reflects the
+    // catch-all rule itself — its `enabled` flag and forward destination —
+    // not the zone-level Email Routing toggle (that's `routingEnabledThisRun`).
+    let catchAll;
+    if (opts.catchAll) {
+        const beforeRule = await cf.getEmailCatchAll(zone.id);
+        const beforeEnabled = beforeRule?.enabled ?? false;
+        const beforeForward = (beforeRule?.actions?.[0]?.value ?? []).join(",");
+        const wantForward = [opts.destination].join(",");
+        await cf.setEmailCatchAll(zone.id, {
+            forwardTo: [opts.destination],
+            enabled: true,
+            name: "Catch-all",
+        });
+        catchAll = { enabled: true, changed: !beforeEnabled || beforeForward !== wantForward };
+    }
+    return {
+        domain: opts.domain,
+        zoneId: zone.id,
+        accountId,
+        routingEnabledThisRun,
+        destination: {
+            record: dest,
+            createdThisRun: !dest.existed,
+            verified: dest.verified ?? null,
+        },
+        dnsRecords,
+        rules,
+        catchAll,
+    };
+}
+/** Find the apex SPF TXT record (one starting with `v=spf1`). Returns
+ *  null when no SPF record exists yet. There MAY be other TXT records
+ *  at the apex (verification tokens, etc.) — they're left alone. */
+async function findApexSpf(cf, zoneId, domain) {
+    const all = await cf.findRecordsByName(zoneId, domain, "TXT");
+    return all.find((r) => /^"?v=spf1\b/i.test(r.content)) ?? null;
+}
+/** Delete every *other* SPF TXT at the apex except the one we're about
+ *  to upsert. Multiple SPF records cause receivers to PermError per
+ *  RFC 7208, so a clean zone has exactly one. Skips the record we're
+ *  keeping (identified by id). */
+async function deleteStaleSpfRecords(cf, zoneId, domain, keepId) {
+    const all = await cf.findRecordsByName(zoneId, domain, "TXT");
+    for (const rec of all) {
+        if (!/^"?v=spf1\b/i.test(rec.content))
+            continue;
+        if (rec.id === keepId)
+            continue;
+        await cf.deleteRecord(zoneId, rec.id);
+    }
+}
+/** Pretty-print the result for the CLI. Centralised here so both the
+ *  standalone command and the create/adopt-flow hook print the same
+ *  status block. */
+export function printEmailSetupSummary(result) {
+    console.log(chalk.bold(`\n  ── Email setup: ${result.domain} ──────────────────────────\n`));
+    if (result.routingEnabledThisRun) {
+        console.log(chalk.green("  ✓ Enabled Cloudflare Email Routing on zone"));
+    }
+    else {
+        console.log(chalk.dim("  · Email Routing already enabled"));
+    }
+    const verifySuffix = result.destination.verified === "active"
+        ? chalk.green(" (verified)")
+        : chalk.yellow(" (pending — check inbox + click verify link)");
+    if (result.destination.createdThisRun) {
+        console.log(chalk.green(`  ✓ Added destination ${result.destination.record.email}`) + verifySuffix);
+    }
+    else {
+        console.log(chalk.dim(`  · Destination ${result.destination.record.email} already on account`) +
+            verifySuffix);
+    }
+    for (const rec of result.dnsRecords) {
+        const tag = rec.created
+            ? chalk.green("✓ created")
+            : rec.updated
+                ? chalk.yellow("· updated")
+                : chalk.dim("· unchanged");
+        console.log(`  ${tag} ${rec.type.padEnd(4)} ${rec.name}  →  ${truncate(rec.content, 60)}`);
+    }
+    for (const r of result.rules) {
+        const tag = r.created
+            ? chalk.green("✓ created")
+            : r.updated
+                ? chalk.yellow("· updated")
+                : chalk.dim("· unchanged");
+        console.log(`  ${tag} rule ${r.address}`);
+    }
+    if (result.catchAll) {
+        const tag = result.catchAll.changed ? chalk.green("✓ enabled") : chalk.dim("· already enabled");
+        console.log(`  ${tag} catch-all *@${result.domain}`);
+    }
+    if (result.destination.verified !== "active") {
+        console.log(chalk.yellow(`\n  ! Forwards won't deliver until ${result.destination.record.email} clicks the Cloudflare verification email.`));
+    }
+}
+function truncate(s, n) {
+    return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+//# sourceMappingURL=setup.js.map

package/dist/email/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/email/setup.ts"],"names":[],"mappings":"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"}

package/dist/email/spf.d.ts

@@ -0,0 +1,56 @@
+/** Common SPF includes for popular senders. The Resend value is the
+ *  one their dashboard tells you to add; AWS SES users would substitute
+ *  `amazonses.com` etc. Hatchkit auto-includes Cloudflare's host; other
+ *  senders come from configuration. */
+export declare const SPF_INCLUDES: {
+    readonly cloudflareEmailRouting: "_spf.mx.cloudflare.net";
+    readonly resend: "_spf.resend.com";
+    readonly amazonSes: "amazonses.com";
+    readonly google: "_spf.google.com";
+};
+export type SpfQualifier = "~all" | "-all" | "?all" | "+all";
+/** Build a single SPF TXT record content string. Sorts includes for
+ *  deterministic output (matters for idempotent upserts: same input =
+ *  same record content = no PATCH on re-run). */
+export declare function buildSpfRecord(opts: {
+    /** Hostnames to wrap as `include:<host>`. Order-insensitive. */
+    includes: string[];
+    /** Optional `ip4:` / `ip6:` mechanisms. */
+    ip4?: string[];
+    ip6?: string[];
+    /** Default `~all` — see file header. */
+    qualifier?: SpfQualifier;
+}): string;
+/** Parse the includes out of an existing SPF record so we can union
+ *  them with new ones (e.g. when adding Cloudflare to a zone that
+ *  already has Resend). Lenient: returns an empty list for malformed
+ *  input rather than throwing — the caller can decide whether to
+ *  overwrite or surface the parse failure. */
+export declare function parseSpfIncludes(record: string): string[];
+/** Build a DMARC TXT record content string.
+ *
+ *  Default policy is `p=quarantine` — failed-DMARC mail lands in spam
+ *  rather than the inbox. `sp=none` deliberately exempts subdomains
+ *  (e.g. `staging.<domain>`) because they often send via third-party
+ *  services not aligned with the apex. `rua` is the aggregate-report
+ *  destination — same address as the forwarding inbox by default, so
+ *  the operator gets weekly delivery summaries.
+ *
+ *  Tweaks (call sites can override):
+ *   · `policy: "none"` — observe-only, no enforcement. Use during
+ *     a soft rollout when you're not sure every legit sender is
+ *     aligned yet.
+ *   · `subdomainPolicy: "quarantine"` — extend enforcement to
+ *     subdomains. Only safe once those subdomains' senders are known. */
+export declare function buildDmarcRecord(opts: {
+    rua: string;
+    policy?: "none" | "quarantine" | "reject";
+    subdomainPolicy?: "none" | "quarantine" | "reject";
+    /** Percentage of mail subject to policy (0-100). Default 100. Drop
+     *  to e.g. 20 during a soft rollout. */
+    percent?: number;
+    /** SPF/DKIM alignment mode — strict ("s") or relaxed ("r"). */
+    alignmentSpf?: "s" | "r";
+    alignmentDkim?: "s" | "r";
+}): string;
+//# sourceMappingURL=spf.d.ts.map

package/dist/email/spf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spf.d.ts","sourceRoot":"","sources":["../../src/email/spf.ts"],"names":[],"mappings":"AAgCA;;;uCAGuC;AACvC,eAAO,MAAM,YAAY;;;;;CAKf,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7D;;iDAEiD;AACjD,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,gEAAgE;IAChE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,wCAAwC;IACxC,SAAS,CAAC,EAAE,YAAY,CAAC;CAC1B,GAAG,MAAM,CAUT;AAED;;;;8CAI8C;AAC9C,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CASzD;AAED;;;;;;;;;;;;;;yEAcyE;AACzE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,CAAC;IAC1C,eAAe,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,CAAC;IACnD;4CACwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;IACzB,aAAa,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;CAC3B,GAAG,MAAM,CAWT"}

package/dist/email/spf.js

@@ -0,0 +1,102 @@
+/*
+ * SPF + DMARC TXT-record helpers.
+ *
+ * SPF rules-of-the-road that make this small but important:
+ *
+ *   1. **One SPF TXT per domain.** RFC 7208 §3.2 — multiple records
+ *      cause receivers to PermError. So if Resend's records already
+ *      include `v=spf1 …` and Cloudflare Email Routing wants its own
+ *      `v=spf1 …`, they MUST be merged into ONE record, not added as
+ *      siblings.
+ *
+ *   2. **Maximum 10 DNS lookups inside the SPF chain.** Each `include:`
+ *      counts as one lookup. Cloudflare Email Routing's
+ *      `_spf.mx.cloudflare.net` and (e.g.) Resend's
+ *      `_spf.resend.com` each cost one — well under the cap, but worth
+ *      knowing if a user later piles on more senders.
+ *
+ *   3. **Order of `include:` mechanisms does NOT matter for the verdict,
+ *      but a stable order makes hatchkit's idempotent upserts a no-op
+ *      on re-run.** We sort the includes alphabetically before joining.
+ *
+ *   4. **Qualifier (`~all` vs `-all`):** we default to `~all` (softfail)
+ *      — recipients see a soft signal that mail from unauthorised IPs
+ *      is suspicious but they still accept it. This pairs well with
+ *      DMARC at `p=quarantine`, which makes the final disposition call
+ *      via alignment rather than SPF-fail-alone. Upgrade to `-all`
+ *      (hardfail) once you're confident no legitimate sender is missing
+ *      from the include list.
+ */
+const CLOUDFLARE_EMAIL_ROUTING_SPF_INCLUDE = "_spf.mx.cloudflare.net";
+/** Common SPF includes for popular senders. The Resend value is the
+ *  one their dashboard tells you to add; AWS SES users would substitute
+ *  `amazonses.com` etc. Hatchkit auto-includes Cloudflare's host; other
+ *  senders come from configuration. */
+export const SPF_INCLUDES = {
+    cloudflareEmailRouting: CLOUDFLARE_EMAIL_ROUTING_SPF_INCLUDE,
+    resend: "_spf.resend.com",
+    amazonSes: "amazonses.com",
+    google: "_spf.google.com",
+};
+/** Build a single SPF TXT record content string. Sorts includes for
+ *  deterministic output (matters for idempotent upserts: same input =
+ *  same record content = no PATCH on re-run). */
+export function buildSpfRecord(opts) {
+    const includes = [...new Set(opts.includes)].sort();
+    const ip4 = opts.ip4 ? [...new Set(opts.ip4)].sort() : [];
+    const ip6 = opts.ip6 ? [...new Set(opts.ip6)].sort() : [];
+    const parts = ["v=spf1"];
+    for (const i of ip4)
+        parts.push(`ip4:${i}`);
+    for (const i of ip6)
+        parts.push(`ip6:${i}`);
+    for (const inc of includes)
+        parts.push(`include:${inc}`);
+    parts.push(opts.qualifier ?? "~all");
+    return parts.join(" ");
+}
+/** Parse the includes out of an existing SPF record so we can union
+ *  them with new ones (e.g. when adding Cloudflare to a zone that
+ *  already has Resend). Lenient: returns an empty list for malformed
+ *  input rather than throwing — the caller can decide whether to
+ *  overwrite or surface the parse failure. */
+export function parseSpfIncludes(record) {
+    const trimmed = record.trim().replace(/^"|"$/g, "").trim();
+    if (!/^v=spf1\b/i.test(trimmed))
+        return [];
+    const includes = [];
+    for (const part of trimmed.split(/\s+/)) {
+        const m = part.match(/^include:(.+)$/i);
+        if (m)
+            includes.push(m[1].toLowerCase());
+    }
+    return includes;
+}
+/** Build a DMARC TXT record content string.
+ *
+ *  Default policy is `p=quarantine` — failed-DMARC mail lands in spam
+ *  rather than the inbox. `sp=none` deliberately exempts subdomains
+ *  (e.g. `staging.<domain>`) because they often send via third-party
+ *  services not aligned with the apex. `rua` is the aggregate-report
+ *  destination — same address as the forwarding inbox by default, so
+ *  the operator gets weekly delivery summaries.
+ *
+ *  Tweaks (call sites can override):
+ *   · `policy: "none"` — observe-only, no enforcement. Use during
+ *     a soft rollout when you're not sure every legit sender is
+ *     aligned yet.
+ *   · `subdomainPolicy: "quarantine"` — extend enforcement to
+ *     subdomains. Only safe once those subdomains' senders are known. */
+export function buildDmarcRecord(opts) {
+    const parts = [
+        "v=DMARC1",
+        `p=${opts.policy ?? "quarantine"}`,
+        `sp=${opts.subdomainPolicy ?? "none"}`,
+        `rua=mailto:${opts.rua}`,
+        `pct=${opts.percent ?? 100}`,
+        `adkim=${opts.alignmentDkim ?? "r"}`,
+        `aspf=${opts.alignmentSpf ?? "r"}`,
+    ];
+    return parts.join("; ");
+}
+//# sourceMappingURL=spf.js.map

package/dist/email/spf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spf.js","sourceRoot":"","sources":["../../src/email/spf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,oCAAoC,GAAG,wBAAwB,CAAC;AAEtE;;;uCAGuC;AACvC,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,sBAAsB,EAAE,oCAAoC;IAC5D,MAAM,EAAE,iBAAiB;IACzB,SAAS,EAAE,eAAe;IAC1B,MAAM,EAAE,iBAAiB;CACjB,CAAC;AAIX;;iDAEiD;AACjD,MAAM,UAAU,cAAc,CAAC,IAQ9B;IACC,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACpD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,MAAM,KAAK,GAAG,CAAC,QAAQ,CAAC,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,GAAG;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,GAAG;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5C,KAAK,MAAM,GAAG,IAAI,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC,CAAC;IACzD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC,CAAC;IACrC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;;;8CAI8C;AAC9C,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3D,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QACxC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACxC,IAAI,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;yEAcyE;AACzE,MAAM,UAAU,gBAAgB,CAAC,IAUhC;IACC,MAAM,KAAK,GAAa;QACtB,UAAU;QACV,KAAK,IAAI,CAAC,MAAM,IAAI,YAAY,EAAE;QAClC,MAAM,IAAI,CAAC,eAAe,IAAI,MAAM,EAAE;QACtC,cAAc,IAAI,CAAC,GAAG,EAAE;QACxB,OAAO,IAAI,CAAC,OAAO,IAAI,GAAG,EAAE;QAC5B,SAAS,IAAI,CAAC,aAAa,IAAI,GAAG,EAAE;QACpC,QAAQ,IAAI,CAAC,YAAY,IAAI,GAAG,EAAE;KACnC,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/index.js

@@ -235,6 +235,13 @@ async function main() {
             await handleDns();
             break;
         }
+        case "email": {
+            if (args.includes("--help") && args.length === 2)
+                return printHelp("email");
+            const { handleEmailCommand } = await import("./email/index.js");
+            await handleEmailCommand(args.slice(1));
+            break;
+        }
         case "gh-pages":
         case "pages": {
             if (args.includes("--help"))
@@ -442,7 +449,7 @@ async function handleAdd() {
     const positional = args.slice(1).filter((a) => !a.startsWith("--"));
     let baseName = positional[0];
     const rawService = positional[1];
-    const allServices = ["glitchtip", "openpanel", "resend", "s3"];
+    const allServices = ["glitchtip", "openpanel", "resend", "s3", "email"];
     if (!baseName) {
         const { input } = await import("@inquirer/prompts");
         const { validateProjectName } = await import("./utils/validate.js");
@@ -465,6 +472,11 @@ async function handleAdd() {
                     value: "s3",
                     checked: false,
                 },
+                {
+                    name: "Email forwarding (Cloudflare Email Routing — MX/SPF/DMARC + rules)",
+                    value: "email",
+                    checked: false,
+                },
             ],
             required: true,
         });
@@ -764,7 +776,7 @@ async function handleRemove() {
     const skipConfirm = args.includes("--yes") || args.includes("-y");
     let baseName = positional[0];
     const rawService = positional[1];
-    const allServices = ["glitchtip", "openpanel", "resend", "s3"];
+    const allServices = ["glitchtip", "openpanel", "resend", "s3", "email"];
     if (!baseName) {
         const { input } = await import("@inquirer/prompts");
         const { validateProjectName } = await import("./utils/validate.js");
@@ -783,6 +795,11 @@ async function handleRemove() {
                 { name: "OpenPanel (deletes the project)", value: "openpanel", checked: true },
                 { name: "Resend (deletes the API key)", value: "resend", checked: true },
                 { name: "S3 / R2 (deletes per-bucket scoped tokens)", value: "s3", checked: false },
+                {
+                    name: "Email forwarding (deletes routing rules + DNS records; keeps destination)",
+                    value: "email",
+                    checked: false,
+                },
             ],
             required: true,
         });
@@ -914,6 +931,9 @@ async function handleCreate() {
     // Summary before execution
     console.log(chalk.bold("\n  ── Summary ───────────────────────────────────────────────\n"));
     console.log(`  Project:    ${chalk.cyan(config.name)}`);
+    if (config.description) {
+        console.log(`  Descr.:     ${chalk.cyan(config.description)}`);
+    }
     console.log(`  Domain:     ${chalk.cyan(config.domain)}`);
     if (config.deploymentMode === "gh-pages") {
         console.log(`  Deploy to:  ${chalk.cyan("GitHub Pages (static)")}`);
@@ -1277,6 +1297,61 @@ async function handleCreate() {
             const { pushInitialBranch } = await import("./deploy/github.js");
             await pushInitialBranch(appDir);
         }
+        // Step 6.6: optional email forwarding setup (Cloudflare Email
+        // Routing). Opt-in prompt — most projects want it but a scripted
+        // / non-interactive create shouldn't pay the latency cost or sink
+        // on a missing accountId without explicit consent.
+        if (config.scaffoldRepo && !config.dryRun && !nonInteractive && process.stdin.isTTY) {
+            try {
+                const wantsEmail = await confirm({
+                    message: `Set up email forwarding for ${chalk.cyan(config.domain)} (Cloudflare Email Routing)?`,
+                    default: true,
+                });
+                if (wantsEmail) {
+                    const { runEmailSetupForDomain } = await import("./email/index.js");
+                    const result = await runEmailSetupForDomain({ domain: config.domain }, appDir);
+                    // Mirror adopt's ledger plumbing so `hatchkit destroy <project>`
+                    // can roll back the email-routing state we just created.
+                    if (ledger && result.destination.createdThisRun) {
+                        ledger.record({
+                            kind: "cloudflareEmailDestination",
+                            accountId: result.accountId,
+                            destinationId: result.destination.record.id,
+                            email: result.destination.record.email,
+                        });
+                    }
+                    for (const dns of result.dnsRecords) {
+                        if (!dns.created)
+                            continue;
+                        ledger?.record({
+                            kind: "cloudflareDnsRecord",
+                            zoneId: result.zoneId,
+                            recordId: dns.id,
+                            name: dns.name,
+                            type: dns.type,
+                        });
+                    }
+                    for (const rule of result.rules) {
+                        if (!rule.created)
+                            continue;
+                        ledger?.record({
+                            kind: "cloudflareEmailRoutingRule",
+                            zoneId: result.zoneId,
+                            ruleId: rule.id,
+                            address: rule.address,
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                // Soft-fail: email forwarding is a follow-up convenience, not a
+                // gating step for the rest of `create`. The user can re-run
+                // `hatchkit email setup` once any underlying issue (e.g. zone
+                // not yet in Cloudflare) is fixed.
+                console.log(chalk.yellow(`  ⚠ Email forwarding setup skipped: ${err.message}`));
+                console.log(chalk.dim(`    Re-run with \`hatchkit email setup --domain ${config.domain}\`.`));
+            }
+        }
         // Step 7: Deploy ML services
         if (config.runDeployment &&
             deploy.length > 0 &&
@@ -1361,7 +1436,7 @@ async function handleCreate() {
     }
     if (config.features.includes("desktop")) {
         console.log(chalk.yellow("\n  Next (desktop): replace build/icon.png with a 512×512 logo, then:"));
-        console.log(chalk.dim("    pnpm icons:desktop     # cross-platform (electron-icon-builder)"));
+        console.log(chalk.dim("    pnpm icons:desktop     # cross-platform (icon-gen)"));
     }
     if (config.features.includes("desktop") || config.features.includes("mobile")) {
         console.log(chalk.yellow("\n  Server CORS: TRUSTED_ORIGINS is already set in .env.example for native clients."));
@@ -1653,8 +1728,41 @@ function printHelp(topic) {
         ${chalk.dim("INWX_SANDBOX=1")} → use the OTE sandbox instead of production.
 
   ${chalk.bold("Prerequisites:")}
-    Run ${chalk.cyan("hatchkit config add dns")} and choose Cloudflare, then answer
+    Run ${chalk.cyan("hatchkit config add dns")} (Cloudflare-only), then answer
     ${chalk.cyan("yes")} to "Is INWX your domain registrar?" when prompted.
+`);
+        return;
+    }
+    if (topic === "email") {
+        console.log(`
+  ${chalk.bold("hatchkit email")} — Cloudflare Email Routing setup
+
+  ${chalk.bold("Subcommands:")}
+    setup    Configure Email Routing + DNS (MX, SPF, DMARC) for a domain
+    status   Print current routing state (read-only)
+
+  ${chalk.bold("Flags (setup):")}
+    --domain <fqdn>           Override the project domain
+    --to <email>              Forwarding destination (saved globally on first use)
+    --addresses <list>        Comma-separated local parts (skips picker)
+    --all-defaults            Use every default preset; skip picker
+    --no-catch-all            Don't set the *@domain catch-all rule
+    --dmarc <none|quarantine|reject>  DMARC policy (default: quarantine)
+    --no-resend-spf           Skip auto-merging _spf.resend.com
+
+  ${chalk.bold("What it sets:")}
+    · Email Routing enabled on the zone
+    · Destination address verified at Cloudflare (verification email sent)
+    · MX records → route1/route2/route3.mx.cloudflare.net
+    · SPF TXT (single record, merged with Resend if detected)
+    · DMARC TXT at _dmarc.<domain> (default p=quarantine sp=none)
+    · One forwarding rule per picked address
+    · Optional catch-all rule (*@<domain>)
+
+  ${chalk.bold("Prerequisites:")}
+    DNS must be on Cloudflare (${chalk.cyan("hatchkit config add dns")}). The token
+    needs Zone:DNS:Edit + Zone:Email Routing Rules:Edit +
+    Account:Email Routing Addresses:Edit.
 `);
         return;
     }
@@ -2216,6 +2324,7 @@ function printHelp(topic) {
     sync            Push the manifest's domain/ports onto the matching Coolify app(s)
     gh-pages        Wire GitHub Pages for the current repo (static / Vite / Jekyll — with DNS)
     dns             DNS reconciliation helpers (link-to-cloudflare, …)
+    email           Set up Cloudflare Email Routing + MX/SPF/DMARC (setup/status)
     keys show <p>   Print the dotenvx private key for a project
     keys set <p>    Upsert the key into the OS keychain (after \`dotenvx rotate\`)
     keys rotate <p> Rotate the dotenvx keypair, mirror to keychain + (optional) deploy targets