@hogsend/cli 0.11.0 → 0.12.1

package/skills/hogsend-migrate/references/resend-broadcasts-mapping.md

@@ -0,0 +1,120 @@
+# Resend Broadcasts/Audiences → Hogsend mapping
+
+Audit greps, the concept table, and rewrites for a codebase using Resend's
+Broadcasts + Audiences + Contacts APIs. Resend's API may differ by SDK version —
+treat the left-hand column as "look for", and verify against the project's
+actual calls.
+
+**The special case first: Resend can stay.** Hogsend's default `EmailProvider`
+IS Resend (`@hogsend/plugin-resend`) — the same `RESEND_API_KEY` keeps
+delivering the mail. This migration replaces the ORCHESTRATION layer (who
+decides what to send to whom, when) — broadcasts, audiences, contact state —
+not necessarily the wire. That makes it the lowest-risk migration of the three:
+deliverability, domains, and DKIM are already proven.
+
+## Audit greps (code half)
+
+```bash
+grep -rn "resend" package.json
+# The orchestration surface being migrated:
+grep -rn "resend.broadcasts\.\|resend.audiences\.\|resend.contacts\." src/
+# Plain transactional — DISTINCT, may stay on resend.emails.send or move:
+grep -rn "resend.emails.send" src/
+grep -rn "RESEND_API_KEY\|RESEND_AUDIENCE" . --include="*.env*" --include="*.ts"
+```
+
+GUI half (from the Resend dashboard): audiences + contact counts, broadcast
+history + their content, unsubscribed contacts per audience, and the verified
+sending domains (these carry over untouched when Resend stays the provider).
+
+## Concept mapping
+
+| Resend concept | Hogsend equivalent | Notes |
+|---|---|---|
+| Audience | list — `defineList({ id, name, defaultOptIn })` | Resend audiences are explicit-membership mailing lists → almost always opt-in (`defaultOptIn: false`) |
+| Contact (in an audience) | contact + list membership — `hs.contacts.upsert({ email, properties?, lists: { "<list-id>": true } })` | `firstName`/`lastName` → `properties`; `unsubscribed: true` contacts → suppression import (see `cutover-checklist.md`) |
+| Broadcast | campaign — `hs.campaigns.send({ list, template, props })` | Or `hogsend campaigns send --list <id> --template <key>`. Content becomes a four-file react-email template |
+| `resend.emails.send` (transactional) | EITHER keep as-is (it still works) OR move to `hs.emails.send` | Moving buys first-party open/click tracking, preference/suppression checks, send history, and journey attribution — recommended, not required |
+| Scheduled broadcast | campaign triggered when you want it | A campaign sends on enqueue; schedule via your own cron/workflow if needed |
+| (No workflow product) | journeys — `defineJourney()` | Net-new capability, not a port. Teams on Resend Broadcasts usually hand-rolled drip logic in app code — grep for `setTimeout`/cron-driven email sends worth replacing with journeys |
+
+## Before / after
+
+Audience + contact management (host product code):
+
+```ts
+// BEFORE (Resend — shapes vary by SDK version)
+await resend.contacts.create({
+  email: "ada@example.com",
+  firstName: "Ada",
+  audienceId: NEWSLETTER_AUDIENCE_ID,
+});
+
+// AFTER (@hogsend/client) — list defined once in the Hogsend app via
+// defineList({ id: "newsletter", name: "Newsletter", defaultOptIn: false })
+import { hogsend } from "../lib/hogsend.js";
+
+await hogsend.contacts.upsert({
+  email: "ada@example.com",
+  userId: user.id,
+  properties: { firstName: "Ada" },
+  lists: { newsletter: true },
+});
+// (or, membership alone: hogsend.lists.subscribe({ list: "newsletter", email: "ada@example.com" }))
+```
+
+Broadcast → campaign:
+
+```ts
+// BEFORE: a broadcast created in the Resend dashboard / broadcasts API
+
+// AFTER — template authored in the Hogsend app first
+// (four-file contract → hogsend-authoring-emails skill)
+const { campaignId } = await hogsend.campaigns.send({
+  list: "newsletter",
+  template: "june-update",
+  props: {},
+  name: "June update",
+});
+// Poll progress: await hogsend.campaigns.get(campaignId)
+// CLI: hogsend campaigns send --list newsletter --template june-update
+//      hogsend campaigns status <campaignId> --json
+```
+
+Transactional, if moving (optional but recommended):
+
+```ts
+// BEFORE (Resend direct)
+await resend.emails.send({
+  from: "Acme <hello@acme.com>",
+  to: "ada@example.com",
+  subject: "Reset your password",
+  html: renderedHtml,
+});
+
+// AFTER — Hogsend renders the react-email template, applies tracking +
+// preference checks, records the send, THEN delivers via the same Resend key
+await hogsend.emails.send({
+  to: "ada@example.com",
+  template: "password-reset",
+  props: { resetUrl },
+});
+```
+
+## Resend-specific gotchas
+
+- **Don't double-manage contacts.** Once Hogsend owns the audience (as a
+  list), stop writing to `resend.audiences`/`resend.contacts` — Hogsend's
+  provider integration uses Resend purely as a send wire, not as a contact
+  store.
+- **Unsubscribes move to Hogsend.** Hogsend injects its own unsubscribe/
+  preference links and stores state in its `email_preferences`. Import Resend's
+  per-audience unsubscribed contacts BEFORE the first campaign
+  (`cutover-checklist.md`), and stop relying on Resend-side unsubscribe state
+  afterward.
+- **Domains/DKIM carry over** when Resend stays the provider — verify
+  `RESEND_API_KEY` (and the from-address envs) are set on the Hogsend
+  deployment, then nothing else changes on the deliverability side.
+- **Broadcast HTML is re-authored**, not pasted: rebuild as a react-email
+  component using the Hogsend app's `src/emails/_components/` chrome so
+  tracking + unsubscribe slots work.

package/src/__tests__/dev.test.ts

@@ -0,0 +1,323 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  devCommand,
+  fetchDomainLine,
+  renderDomainLine,
+} from "../commands/dev.js";
+import type { CommandContext } from "../commands/types.js";
+import type { ResolvedConfig } from "../lib/config.js";
+import type { AdminClient, DataPlaneClient, Query } from "../lib/http.js";
+import type { Output } from "../lib/output.js";
+
+vi.mock("../lib/proc.js", () => ({
+  spawnManaged: vi.fn(),
+  shutdownAll: vi.fn(async () => {}),
+  waitForHttp: vi.fn(async () => {}),
+}));
+
+import { spawnManaged } from "../lib/proc.js";
+
+/** Sentinel thrown by the stubbed `out.fail` instead of process.exit(1). */
+class FailSignal extends Error {
+  constructor(readonly failMessage: string) {
+    super(failMessage);
+    this.name = "FailSignal";
+  }
+}
+
+interface Captured {
+  logs: string[];
+  jsonDocs: unknown[];
+}
+
+function makeCtx(opts: {
+  argv: string[];
+  json?: boolean;
+  adminKey?: string;
+  get?: (path: string, query?: Query) => Promise<unknown>;
+  post?: (path: string, body: unknown) => Promise<unknown>;
+}): { ctx: CommandContext; captured: Captured } {
+  const captured: Captured = { logs: [], jsonDocs: [] };
+
+  const out: Output = {
+    interactive: false,
+    isJson: opts.json ?? false,
+    intro: () => {},
+    step: async <T>(_label: string, fn: () => Promise<T>) => fn(),
+    note: (body: string) => {
+      captured.logs.push(body);
+    },
+    table: () => {},
+    kv: () => {},
+    log: (msg: string) => {
+      captured.logs.push(msg);
+    },
+    json: (payload: unknown) => {
+      captured.jsonDocs.push(payload);
+    },
+    outro: () => {},
+    fail: (message: string): never => {
+      throw new FailSignal(message);
+    },
+  };
+
+  const cfg = {
+    baseUrl: "http://localhost:3002",
+    adminKey: opts.adminKey,
+    dataKey: "hsk_data",
+  } as ResolvedConfig;
+
+  const http = {
+    cfg,
+    get: (path: string, query?: Query) =>
+      (opts.get ?? (() => Promise.reject(new Error("unexpected GET"))))(
+        path,
+        query,
+      ),
+    post: () => Promise.reject(new Error("unexpected POST")),
+    patch: () => Promise.reject(new Error("unexpected PATCH")),
+    del: () => Promise.reject(new Error("unexpected DELETE")),
+  } as AdminClient;
+
+  const dataHttp = {
+    cfg,
+    get: () => Promise.reject(new Error("unexpected data GET")),
+    post: (path: string, body: unknown) =>
+      (opts.post ?? (() => Promise.reject(new Error("unexpected data POST"))))(
+        path,
+        body,
+      ),
+    put: () => Promise.reject(new Error("unexpected PUT")),
+    del: () => Promise.reject(new Error("unexpected DELETE")),
+  } as DataPlaneClient;
+
+  const ctx: CommandContext = {
+    argv: opts.argv,
+    cfg,
+    http,
+    dataHttp,
+    out,
+    json: opts.json ?? false,
+  };
+
+  return { ctx, captured };
+}
+
+let cwd: string;
+
+beforeEach(() => {
+  cwd = mkdtempSync(join(tmpdir(), "hogsend-dev-"));
+  vi.mocked(spawnManaged).mockClear();
+  vi.unstubAllGlobals();
+});
+
+afterEach(() => {
+  rmSync(cwd, { recursive: true, force: true });
+  vi.unstubAllGlobals();
+});
+
+describe("hogsend dev --help", () => {
+  it("prints usage and exits cleanly", async () => {
+    const { ctx, captured } = makeCtx({ argv: ["--help"] });
+    await devCommand.run(ctx);
+    const all = captured.logs.join("\n");
+    expect(all).toContain("hogsend dev");
+    expect(all).toContain("--fire");
+    expect(all).toContain("--no-worker");
+    expect(all).toContain("--no-infra");
+    expect(vi.mocked(spawnManaged)).not.toHaveBeenCalled();
+  });
+});
+
+describe("hogsend dev app detection", () => {
+  it("fails with 'not a Hogsend app' in an empty directory", async () => {
+    const { ctx } = makeCtx({ argv: ["--cwd", cwd] });
+    await expect(devCommand.run(ctx)).rejects.toThrow(/not a Hogsend app/i);
+    expect(vi.mocked(spawnManaged)).not.toHaveBeenCalled();
+  });
+
+  it("names the missing worker:dev script", async () => {
+    writeFileSync(
+      join(cwd, "package.json"),
+      JSON.stringify({
+        name: "app",
+        scripts: { dev: "tsx watch src/index.ts" },
+        dependencies: { "@hogsend/engine": "^0.11.0" },
+      }),
+    );
+    const { ctx } = makeCtx({ argv: ["--cwd", cwd] });
+    await expect(devCommand.run(ctx)).rejects.toThrow(/worker:dev/);
+  });
+
+  it("names the missing @hogsend/engine dependency", async () => {
+    writeFileSync(
+      join(cwd, "package.json"),
+      JSON.stringify({
+        name: "app",
+        scripts: { dev: "x", "worker:dev": "y" },
+        dependencies: {},
+      }),
+    );
+    const { ctx } = makeCtx({ argv: ["--cwd", cwd] });
+    await expect(devCommand.run(ctx)).rejects.toThrow(/@hogsend\/engine/);
+  });
+});
+
+describe("hogsend dev --fire", () => {
+  it("delegates to the events send path without booting anything", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ ok: true })),
+    );
+    let seenPath: string | undefined;
+    let seenBody: unknown;
+    const { ctx } = makeCtx({
+      argv: ["--fire", "signup", "--email", "a@b.com", "--prop", "plan=pro"],
+      post: async (path, body) => {
+        seenPath = path;
+        seenBody = body;
+        return { stored: true, exits: [] };
+      },
+    });
+    await devCommand.run(ctx);
+    expect(seenPath).toBe("/v1/events");
+    expect(seenBody).toEqual({
+      name: "signup",
+      email: "a@b.com",
+      eventProperties: { plan: "pro" },
+    });
+    expect(vi.mocked(spawnManaged)).not.toHaveBeenCalled();
+  });
+
+  it("supports --fire=<event> syntax", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ ok: true })),
+    );
+    let seenBody: unknown;
+    const { ctx } = makeCtx({
+      argv: ["--fire=signup", "--user-id", "u_1"],
+      post: async (_path, body) => {
+        seenBody = body;
+        return { stored: true, exits: [] };
+      },
+    });
+    await devCommand.run(ctx);
+    expect(seenBody).toEqual({ name: "signup", userId: "u_1" });
+  });
+
+  it("fails when --fire has no event name", async () => {
+    const { ctx } = makeCtx({ argv: ["--fire"] });
+    await expect(devCommand.run(ctx)).rejects.toThrow(
+      /--fire requires an event name/,
+    );
+  });
+
+  it("fails with a friendly hint when the instance is down", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new Error("ECONNREFUSED");
+      }),
+    );
+    const { ctx } = makeCtx({
+      argv: ["--fire", "signup", "--user-id", "u_1"],
+    });
+    await expect(devCommand.run(ctx)).rejects.toThrow(
+      /is hogsend dev running/i,
+    );
+    expect(vi.mocked(spawnManaged)).not.toHaveBeenCalled();
+  });
+});
+
+describe("renderDomainLine", () => {
+  it("renders a yellow test-mode line with the redirect target", () => {
+    const line = renderDomainLine({
+      domain: "mysite.com",
+      status: { state: "pending" },
+      testMode: { active: true, redirectTo: "doug@x.dev" },
+    });
+    expect(line).toContain("Test mode active");
+    expect(line).toContain("doug@x.dev");
+    expect(line).toContain("pending");
+  });
+
+  it("renders a verified domain line", () => {
+    const line = renderDomainLine({
+      domain: "mysite.com",
+      status: { state: "verified" },
+      testMode: { active: false, redirectTo: null },
+    });
+    expect(line).toContain("mysite.com");
+    expect(line).toContain("verified");
+  });
+
+  it("returns null when there is nothing to say", () => {
+    expect(
+      renderDomainLine({
+        domain: null,
+        status: null,
+        testMode: { active: false, redirectTo: null },
+      }),
+    ).toBeNull();
+  });
+});
+
+describe("fetchDomainLine (guarded soft-consume of /v1/admin/domain)", () => {
+  it("returns null without calling HTTP when no admin key is configured", async () => {
+    const get = vi.fn();
+    const { ctx } = makeCtx({ argv: [], get });
+    await expect(fetchDomainLine(ctx)).resolves.toBeNull();
+    expect(get).not.toHaveBeenCalled();
+  });
+
+  it("returns null when the route 404s (engine without domain-setup)", async () => {
+    const { ctx } = makeCtx({
+      argv: [],
+      adminKey: "hsk_admin",
+      get: async () => {
+        const err = new Error("request failed with status 404");
+        (err as Error & { status: number }).status = 404;
+        throw err;
+      },
+    });
+    await expect(fetchDomainLine(ctx)).resolves.toBeNull();
+  });
+
+  it("returns the rendered line on success", async () => {
+    const { ctx } = makeCtx({
+      argv: [],
+      adminKey: "hsk_admin",
+      get: async (path) => {
+        expect(path).toBe("/v1/admin/domain");
+        return {
+          domain: "mysite.com",
+          status: { state: "verified" },
+          testMode: { active: false, redirectTo: null },
+        };
+      },
+    });
+    const line = await fetchDomainLine(ctx);
+    expect(line).toContain("mysite.com");
+  });
+
+  it("returns null on a malformed response body", async () => {
+    const { ctx } = makeCtx({
+      argv: [],
+      adminKey: "hsk_admin",
+      get: async () => "weird",
+    });
+    await expect(fetchDomainLine(ctx)).resolves.toBeNull();
+  });
+});
+
+describe("hogsend dev infra gating", () => {
+  it("requires package.json before doing anything else (cwd is a dir)", async () => {
+    mkdirSync(join(cwd, "sub"));
+    const { ctx } = makeCtx({ argv: ["--cwd", join(cwd, "sub")] });
+    await expect(devCommand.run(ctx)).rejects.toThrow(/package\.json/);
+  });
+});