@hogsend/cli 0.11.0 → 0.12.0

package/src/__tests__/dns-apply.test.ts

@@ -0,0 +1,297 @@
+import type { DnsRecord } from "@hogsend/engine";
+import { describe, expect, it, vi } from "vitest";
+import { applyRecords, canAutoApply } from "../lib/dns-apply.js";
+
+/** Mocked fetch — NEVER hits the real Cloudflare/Vercel APIs. */
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+const RECORDS: DnsRecord[] = [
+  {
+    type: "TXT",
+    name: "resend._domainkey.mysite.com",
+    value: "p=MIGfMA0GCSq",
+    purpose: "dkim",
+    status: "pending",
+  },
+  {
+    type: "MX",
+    name: "send.mysite.com",
+    value: "feedback-smtp.us-east-1.amazonses.com",
+    priority: 10,
+    purpose: "spf",
+    status: "pending",
+  },
+];
+
+describe("canAutoApply", () => {
+  it("cloudflare requires CLOUDFLARE_API_TOKEN", () => {
+    expect(canAutoApply("cloudflare", { CLOUDFLARE_API_TOKEN: "t" })).toBe(
+      true,
+    );
+    expect(canAutoApply("cloudflare", {})).toBe(false);
+  });
+
+  it("vercel requires VERCEL_TOKEN", () => {
+    expect(canAutoApply("vercel", { VERCEL_TOKEN: "t" })).toBe(true);
+    expect(canAutoApply("vercel", {})).toBe(false);
+  });
+
+  it("every other host is false even with creds set", () => {
+    for (const host of [
+      "route53",
+      "godaddy",
+      "namecheap",
+      "porkbun",
+      "google",
+      "unknown",
+    ] as const) {
+      expect(
+        canAutoApply(host, { CLOUDFLARE_API_TOKEN: "t", VERCEL_TOKEN: "t" }),
+      ).toBe(false);
+    }
+  });
+});
+
+describe("applyRecords — cloudflare", () => {
+  it("resolves the zone then POSTs each record with proxied:false", async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse({ success: true, result: [{ id: "zone1" }] }),
+      )
+      .mockResolvedValueOnce(jsonResponse({ success: true, result: {} }))
+      .mockResolvedValueOnce(jsonResponse({ success: true, result: {} }));
+
+    const result = await applyRecords({
+      host: "cloudflare",
+      domain: "mysite.com",
+      records: RECORDS,
+      env: { CLOUDFLARE_API_TOKEN: "cf_token" },
+      fetchImpl,
+    });
+
+    expect(result.applied).toHaveLength(2);
+    expect(result.skipped).toHaveLength(0);
+    expect(result.errors).toHaveLength(0);
+
+    const [zoneUrl, zoneInit] = fetchImpl.mock.calls[0] as [
+      string,
+      RequestInit,
+    ];
+    expect(zoneUrl).toBe(
+      "https://api.cloudflare.com/client/v4/zones?name=mysite.com",
+    );
+    expect((zoneInit.headers as Record<string, string>).Authorization).toBe(
+      "Bearer cf_token",
+    );
+
+    const [recUrl, recInit] = fetchImpl.mock.calls[1] as [string, RequestInit];
+    expect(recUrl).toBe(
+      "https://api.cloudflare.com/client/v4/zones/zone1/dns_records",
+    );
+    const payload = JSON.parse(recInit.body as string);
+    expect(payload.proxied).toBe(false);
+    expect(payload.type).toBe("TXT");
+    expect(payload.name).toBe("resend._domainkey.mysite.com");
+
+    // MX priority threaded through.
+    const mxPayload = JSON.parse(
+      (fetchImpl.mock.calls[2] as [string, RequestInit])[1].body as string,
+    );
+    expect(mxPayload.priority).toBe(10);
+  });
+
+  it("counts an identical-record-exists error (81057) as skipped", async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse({ success: true, result: [{ id: "zone1" }] }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(
+          {
+            success: false,
+            errors: [{ code: 81057, message: "Record already exists." }],
+          },
+          400,
+        ),
+      )
+      .mockResolvedValueOnce(jsonResponse({ success: true, result: {} }));
+
+    const result = await applyRecords({
+      host: "cloudflare",
+      domain: "mysite.com",
+      records: RECORDS,
+      env: { CLOUDFLARE_API_TOKEN: "cf_token" },
+      fetchImpl,
+    });
+
+    expect(result.skipped).toHaveLength(1);
+    expect(result.applied).toHaveLength(1);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it("collects other API failures into errors (never throws)", async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse({ success: true, result: [{ id: "zone1" }] }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(
+          { success: false, errors: [{ code: 9999, message: "API boom" }] },
+          400,
+        ),
+      )
+      .mockResolvedValueOnce(jsonResponse({ success: true, result: {} }));
+
+    const result = await applyRecords({
+      host: "cloudflare",
+      domain: "mysite.com",
+      records: RECORDS,
+      env: { CLOUDFLARE_API_TOKEN: "cf_token" },
+      fetchImpl,
+    });
+
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0]).toContain("API boom");
+    expect(result.applied).toHaveLength(1);
+  });
+
+  it("errors out cleanly when the zone cannot be resolved", async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(jsonResponse({ success: true, result: [] }));
+
+    const result = await applyRecords({
+      host: "cloudflare",
+      domain: "mysite.com",
+      records: RECORDS,
+      env: { CLOUDFLARE_API_TOKEN: "cf_token" },
+      fetchImpl,
+    });
+
+    expect(result.applied).toHaveLength(0);
+    expect(result.skipped).toHaveLength(0);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0]).toContain("zone");
+  });
+
+  it("resolves the zone by the registrable domain for subdomains", async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse({ success: true, result: [{ id: "zone1" }] }),
+      )
+      .mockResolvedValue(jsonResponse({ success: true, result: {} }));
+
+    await applyRecords({
+      host: "cloudflare",
+      domain: "mail.mysite.com",
+      records: RECORDS,
+      env: { CLOUDFLARE_API_TOKEN: "cf_token" },
+      fetchImpl,
+    });
+
+    const [zoneUrl] = fetchImpl.mock.calls[0] as [string];
+    expect(zoneUrl).toContain("name=mysite.com");
+  });
+});
+
+describe("applyRecords — vercel", () => {
+  it("POSTs each record to the domains records API", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse({ uid: "rec_1" }));
+
+    const result = await applyRecords({
+      host: "vercel",
+      domain: "mysite.com",
+      records: RECORDS,
+      env: { VERCEL_TOKEN: "v_token" },
+      fetchImpl,
+    });
+
+    expect(result.applied).toHaveLength(2);
+    const [url, init] = fetchImpl.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://api.vercel.com/v2/domains/mysite.com/records");
+    expect((init.headers as Record<string, string>).Authorization).toBe(
+      "Bearer v_token",
+    );
+    const payload = JSON.parse(init.body as string);
+    expect(payload.type).toBe("TXT");
+  });
+
+  it("appends ?teamId= when VERCEL_TEAM_ID is set", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse({ uid: "rec_1" }));
+
+    await applyRecords({
+      host: "vercel",
+      domain: "mysite.com",
+      records: RECORDS.slice(0, 1),
+      env: { VERCEL_TOKEN: "v_token", VERCEL_TEAM_ID: "team_1" },
+      fetchImpl,
+    });
+
+    const [url] = fetchImpl.mock.calls[0] as [string];
+    expect(url).toContain("?teamId=team_1");
+  });
+
+  it("counts a duplicate-record error as skipped", async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse(
+          {
+            error: {
+              code: "duplicate_record",
+              message: "A record already exists",
+            },
+          },
+          400,
+        ),
+      )
+      .mockResolvedValueOnce(jsonResponse({ uid: "rec_2" }));
+
+    const result = await applyRecords({
+      host: "vercel",
+      domain: "mysite.com",
+      records: RECORDS,
+      env: { VERCEL_TOKEN: "v_token" },
+      fetchImpl,
+    });
+
+    expect(result.skipped).toHaveLength(1);
+    expect(result.applied).toHaveLength(1);
+    expect(result.errors).toHaveLength(0);
+  });
+});
+
+describe("applyRecords — unsupported host / missing creds", () => {
+  it("returns everything skipped with an explanatory error", async () => {
+    const result = await applyRecords({
+      host: "godaddy",
+      domain: "mysite.com",
+      records: RECORDS,
+      env: {},
+    });
+    expect(result.applied).toHaveLength(0);
+    expect(result.skipped).toHaveLength(2);
+    expect(result.errors).toHaveLength(1);
+  });
+
+  it("never throws on a transport failure", async () => {
+    const fetchImpl = vi.fn().mockRejectedValue(new Error("ECONNREFUSED"));
+    const result = await applyRecords({
+      host: "cloudflare",
+      domain: "mysite.com",
+      records: RECORDS,
+      env: { CLOUDFLARE_API_TOKEN: "cf_token" },
+      fetchImpl,
+    });
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/dns.test.ts

@@ -0,0 +1,143 @@
+import type { DnsRecord } from "@hogsend/engine";
+import { describe, expect, it } from "vitest";
+import { DNS_HOSTS, detectDnsHost, formatRecordsFor } from "../lib/dns.js";
+
+/** Fixture resolver — NEVER touches real DNS. */
+function resolverFor(map: Record<string, readonly string[]>) {
+  return async (hostname: string): Promise<string[]> => {
+    const ns = map[hostname];
+    if (!ns) {
+      const err = new Error(`queryNs ENOTFOUND ${hostname}`) as Error & {
+        code: string;
+      };
+      err.code = "ENOTFOUND";
+      throw err;
+    }
+    return [...ns];
+  };
+}
+
+const RECORDS: DnsRecord[] = [
+  {
+    type: "TXT",
+    name: "resend._domainkey.mysite.com",
+    value: "p=MIGfMA0GCSq",
+    purpose: "dkim",
+    status: "pending",
+  },
+  {
+    type: "MX",
+    name: "send.mysite.com",
+    value: "feedback-smtp.us-east-1.amazonses.com",
+    priority: 10,
+    purpose: "spf",
+    status: "pending",
+  },
+  {
+    type: "CNAME",
+    name: "pm-bounces.mysite.com",
+    value: "pm.mtasv.net",
+    purpose: "return_path",
+    status: "verified",
+  },
+];
+
+describe("detectDnsHost", () => {
+  it.each([
+    ["cloudflare", ["dana.ns.cloudflare.com", "kirk.ns.cloudflare.com"]],
+    ["vercel", ["ns1.vercel-dns.com", "ns2.vercel-dns.com"]],
+    ["route53", ["ns-123.awsdns-15.com", "ns-456.awsdns-22.net"]],
+    ["godaddy", ["ns01.domaincontrol.com", "ns02.domaincontrol.com"]],
+    ["namecheap", ["dns1.registrar-servers.com", "dns2.registrar-servers.com"]],
+    ["porkbun", ["maceio.ns.porkbun.com", "salvador.ns.porkbun.com"]],
+    ["google", ["ns-cloud-a1.googledomains.com"]],
+  ] as const)("detects %s from its NS suffixes", async (id, ns) => {
+    const host = await detectDnsHost("mysite.com", {
+      resolveNs: resolverFor({ "mysite.com": ns }),
+    });
+    expect(host.id).toBe(id);
+  });
+
+  it("walks up labels until NS records resolve", async () => {
+    const host = await detectDnsHost("a.b.mysite.com", {
+      resolveNs: resolverFor({ "mysite.com": ["dana.ns.cloudflare.com"] }),
+    });
+    expect(host.id).toBe("cloudflare");
+  });
+
+  it("returns unknown for an unrecognized nameserver", async () => {
+    const host = await detectDnsHost("mysite.com", {
+      resolveNs: resolverFor({ "mysite.com": ["ns1.example-dns.io"] }),
+    });
+    expect(host.id).toBe("unknown");
+  });
+
+  it("returns unknown when every lookup errors (never throws)", async () => {
+    const host = await detectDnsHost("mysite.com", {
+      resolveNs: resolverFor({}),
+    });
+    expect(host.id).toBe("unknown");
+  });
+
+  it("exposes a panel deep link per host", () => {
+    const cloudflare = DNS_HOSTS.cloudflare;
+    expect(cloudflare.panelUrl("mysite.com")).toBe(
+      "https://dash.cloudflare.com/?to=/:account/mysite.com/dns/records",
+    );
+    expect(DNS_HOSTS.vercel.panelUrl("mysite.com")).toBe(
+      "https://vercel.com/dashboard/domains/mysite.com",
+    );
+    expect(DNS_HOSTS.namecheap.panelUrl("mysite.com")).toContain(
+      "domaincontrolpanel/mysite.com",
+    );
+    expect(DNS_HOSTS.unknown.panelUrl("mysite.com")).toBe("https://mysite.com");
+  });
+});
+
+describe("formatRecordsFor", () => {
+  it("renders an aligned table with type/name/value/priority/status", () => {
+    const out = formatRecordsFor(DNS_HOSTS.cloudflare, RECORDS, {
+      domain: "mysite.com",
+    });
+    expect(out).toContain("TXT");
+    expect(out).toContain("resend._domainkey.mysite.com");
+    expect(out).toContain("p=MIGfMA0GCSq");
+    expect(out).toContain("10");
+    expect(out).toContain("pending");
+    expect(out).toContain("verified");
+  });
+
+  it("adds the Cloudflare grey-cloud guidance", () => {
+    const out = formatRecordsFor(DNS_HOSTS.cloudflare, RECORDS, {
+      domain: "mysite.com",
+    });
+    expect(out).toContain("DNS only");
+  });
+
+  it("strips the domain suffix for relative-host panels (namecheap/godaddy)", () => {
+    for (const id of ["namecheap", "godaddy"] as const) {
+      const out = formatRecordsFor(DNS_HOSTS[id], RECORDS, {
+        domain: "mysite.com",
+      });
+      // Hosts shown RELATIVE to mysite.com.
+      expect(out).toContain("resend._domainkey");
+      expect(out).not.toContain("resend._domainkey.mysite.com");
+      expect(out).toContain("RELATIVE");
+    }
+  });
+
+  it("prints records verbatim with a generic note for unknown hosts", () => {
+    const out = formatRecordsFor(DNS_HOSTS.unknown, RECORDS, {
+      domain: "mysite.com",
+    });
+    expect(out).toContain("resend._domainkey.mysite.com");
+    expect(out.toLowerCase()).toContain("dns");
+  });
+
+  it("handles an empty record list", () => {
+    const out = formatRecordsFor(DNS_HOSTS.cloudflare, [], {
+      domain: "mysite.com",
+    });
+    expect(typeof out).toBe("string");
+  });
+});

package/src/__tests__/domain-command.test.ts

@@ -0,0 +1,216 @@
+import type { EngineDomainStatus } from "@hogsend/engine";
+import { describe, expect, it } from "vitest";
+import { domainCommand } from "../commands/domain.js";
+import type { CommandContext } from "../commands/types.js";
+import type { ResolvedConfig } from "../lib/config.js";
+import type { AdminClient, HttpError, Query } from "../lib/http.js";
+import type { Output } from "../lib/output.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";
+  }
+}
+
+function makeHttpError(status: number, body: unknown): HttpError {
+  const err = new Error(
+    body &&
+      typeof body === "object" &&
+      "error" in body &&
+      typeof (body as { error: unknown }).error === "string"
+      ? `${status}: ${(body as { error: string }).error}`
+      : `request failed with status ${status}`,
+  ) as HttpError;
+  err.name = "HttpError";
+  err.status = status;
+  err.body = body;
+  return err;
+}
+
+const STATUS_FIXTURE: EngineDomainStatus = {
+  domain: "mysite.com",
+  providerId: "resend",
+  supported: true,
+  status: {
+    domain: "mysite.com",
+    state: "pending",
+    records: [
+      {
+        type: "TXT",
+        name: "resend._domainkey.mysite.com",
+        value: "p=MIGfMA0GCSq",
+        purpose: "dkim",
+        status: "pending",
+      },
+    ],
+    providerId: "resend",
+    checkedAt: "2026-06-09T00:00:00.000Z",
+  },
+  testMode: {
+    active: false,
+    reason: null,
+    redirectTo: null,
+    fromOverride: null,
+  },
+};
+
+interface CapturedOutput {
+  logs: string[];
+  jsonDocs: unknown[];
+}
+
+function makeCtx(opts: {
+  argv: string[];
+  json?: boolean;
+  get?: (path: string, query?: Query) => Promise<unknown>;
+  post?: (path: string, body: unknown) => Promise<unknown>;
+}): { ctx: CommandContext; captured: CapturedOutput } {
+  const captured: CapturedOutput = { 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: "hsk_test",
+    dataKey: undefined,
+    sources: { baseUrl: "default", adminKey: "flag", dataKey: "default" },
+  } as unknown as ResolvedConfig;
+
+  const http = {
+    cfg,
+    get: (path: string, query?: Query) =>
+      (opts.get ?? (() => Promise.reject(new Error("unexpected GET"))))(
+        path,
+        query,
+      ),
+    post: (path: string, body: unknown) =>
+      (opts.post ?? (() => Promise.reject(new Error("unexpected POST"))))(
+        path,
+        body,
+      ),
+    patch: () => Promise.reject(new Error("unexpected PATCH")),
+    del: () => Promise.reject(new Error("unexpected DELETE")),
+  } as AdminClient;
+
+  const ctx: CommandContext = {
+    argv: opts.argv,
+    cfg,
+    http,
+    dataHttp: {} as CommandContext["dataHttp"],
+    out,
+    json: opts.json ?? false,
+  };
+
+  return { ctx, captured };
+}
+
+describe("hogsend domain --help", () => {
+  it("prints usage and exits cleanly (exit 0)", async () => {
+    const { ctx, captured } = makeCtx({ argv: ["--help"] });
+    await domainCommand.run(ctx);
+    expect(captured.logs.join("\n")).toContain("hogsend domain");
+    expect(captured.logs.join("\n")).toContain("add <domain>");
+  });
+
+  it("prints usage when no subcommand is given", async () => {
+    const { ctx, captured } = makeCtx({ argv: [] });
+    await domainCommand.run(ctx);
+    expect(captured.logs.join("\n")).toContain("hogsend domain");
+  });
+
+  it("fails on an unknown subcommand", async () => {
+    const { ctx } = makeCtx({ argv: ["frobnicate"] });
+    await expect(domainCommand.run(ctx)).rejects.toThrow(/unknown subcommand/i);
+  });
+});
+
+describe("hogsend domain status", () => {
+  it("--json emits the EngineDomainStatus as a single parseable document", async () => {
+    const { ctx, captured } = makeCtx({
+      argv: ["status"],
+      json: true,
+      get: async (path, query) => {
+        expect(path).toBe("/v1/admin/domain");
+        expect(query?.refresh).toBeUndefined();
+        return STATUS_FIXTURE;
+      },
+    });
+    await domainCommand.run(ctx);
+    expect(captured.jsonDocs).toHaveLength(1);
+    const doc = JSON.parse(JSON.stringify(captured.jsonDocs[0]));
+    expect(doc).toEqual(STATUS_FIXTURE);
+    expect(doc.testMode).toEqual({
+      active: false,
+      reason: null,
+      redirectTo: null,
+      fromOverride: null,
+    });
+  });
+
+  it("--refresh passes ?refresh=true", async () => {
+    let seenQuery: Query | undefined;
+    const { ctx } = makeCtx({
+      argv: ["status", "--refresh"],
+      json: true,
+      get: async (_path, query) => {
+        seenQuery = query;
+        return STATUS_FIXTURE;
+      },
+    });
+    await domainCommand.run(ctx);
+    expect(seenQuery?.refresh).toBe("true");
+  });
+});
+
+describe("hogsend domain add", () => {
+  it("fails with the unsupported message on a 501 provider_unsupported", async () => {
+    const { ctx } = makeCtx({
+      argv: ["add", "mysite.com"],
+      post: async () => {
+        throw makeHttpError(501, { error: "provider_unsupported" });
+      },
+      // The command resolves the provider id for the message via GET.
+      get: async () => ({
+        ...STATUS_FIXTURE,
+        providerId: "smtp",
+        supported: false,
+        status: null,
+      }),
+    });
+    await expect(domainCommand.run(ctx)).rejects.toThrow(
+      /provider smtp does not support domain management/,
+    );
+  });
+
+  it("fails when the domain argument is missing", async () => {
+    const { ctx } = makeCtx({ argv: ["add"] });
+    await expect(domainCommand.run(ctx)).rejects.toThrow(/missing <domain>/i);
+  });
+
+  it("fails on an invalid domain before any HTTP call", async () => {
+    const { ctx } = makeCtx({ argv: ["add", "not_a_domain"] });
+    await expect(domainCommand.run(ctx)).rejects.toThrow(/invalid domain/i);
+  });
+});