@hogsend/cli 0.10.0 → 0.12.0

package/src/lib/dns-apply.ts

@@ -0,0 +1,218 @@
+import type { DnsRecord } from "@hogsend/engine";
+import type { DnsHostId } from "./dns.js";
+
+/**
+ * Best-effort DNS auto-apply for `hogsend domain add`. Supported hosts:
+ * Cloudflare (CLOUDFLARE_API_TOKEN) and Vercel (VERCEL_TOKEN [+ VERCEL_TEAM_ID]).
+ * These are CLI-PROCESS env vars only — deliberately NOT part of the engine's
+ * validated env (the engine never writes DNS).
+ */
+
+/** True when the host supports auto-apply AND its credential is present. */
+export function canAutoApply(host: DnsHostId, env: NodeJS.ProcessEnv): boolean {
+  switch (host) {
+    case "cloudflare":
+      return Boolean(env.CLOUDFLARE_API_TOKEN);
+    case "vercel":
+      return Boolean(env.VERCEL_TOKEN);
+    default:
+      return false;
+  }
+}
+
+export interface ApplyRecordsOptions {
+  host: DnsHostId;
+  domain: string;
+  records: DnsRecord[];
+  env: NodeJS.ProcessEnv;
+  /** Injectable fetch for tests — NEVER hit the real APIs in CI. */
+  fetchImpl?: typeof fetch;
+}
+
+export interface ApplyRecordsResult {
+  applied: DnsRecord[];
+  skipped: DnsRecord[];
+  errors: string[];
+}
+
+/** Cloudflare error codes meaning "an identical record already exists". */
+const CF_DUPLICATE_CODES = new Set([81057, 81053]);
+
+/**
+ * Registrable domain heuristic for zone lookup: the last two labels. Good
+ * enough for the auto-apply happy path (mail.mysite.com → mysite.com); exotic
+ * public-suffix domains fall back to the error path and manual records.
+ */
+function registrableDomain(domain: string): string {
+  const labels = domain.split(".").filter(Boolean);
+  if (labels.length <= 2) return domain;
+  return labels.slice(-2).join(".");
+}
+
+async function parseJson(res: Response): Promise<unknown> {
+  try {
+    return await res.json();
+  } catch {
+    return undefined;
+  }
+}
+
+async function applyCloudflare(
+  opts: ApplyRecordsOptions,
+  fetchImpl: typeof fetch,
+): Promise<ApplyRecordsResult> {
+  const result: ApplyRecordsResult = { applied: [], skipped: [], errors: [] };
+  const token = opts.env.CLOUDFLARE_API_TOKEN ?? "";
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json",
+  };
+
+  // Resolve the zone id for the registrable domain.
+  const zoneName = registrableDomain(opts.domain);
+  let zoneId: string | undefined;
+  try {
+    const res = await fetchImpl(
+      `https://api.cloudflare.com/client/v4/zones?name=${encodeURIComponent(zoneName)}`,
+      { headers },
+    );
+    const body = (await parseJson(res)) as
+      | { result?: Array<{ id?: string }> }
+      | undefined;
+    zoneId = body?.result?.[0]?.id;
+  } catch (cause) {
+    // `skipped` is reserved for "already present" — a zone failure means
+    // NOTHING was attempted, so it surfaces as a single error.
+    result.errors.push(
+      `Cloudflare zone lookup failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+    );
+    return result;
+  }
+  if (!zoneId) {
+    result.errors.push(
+      `could not resolve a Cloudflare zone for ${zoneName} — is the domain on this account?`,
+    );
+    return result;
+  }
+
+  for (const record of opts.records) {
+    try {
+      const res = await fetchImpl(
+        `https://api.cloudflare.com/client/v4/zones/${zoneId}/dns_records`,
+        {
+          method: "POST",
+          headers,
+          body: JSON.stringify({
+            type: record.type,
+            name: record.name,
+            content: record.value,
+            ttl: record.ttl ?? 1, // 1 = automatic
+            ...(record.priority !== undefined
+              ? { priority: record.priority }
+              : {}),
+            // NEVER proxy mail-verification records — orange-cloud breaks them.
+            proxied: false,
+          }),
+        },
+      );
+      if (res.ok) {
+        result.applied.push(record);
+        continue;
+      }
+      const body = (await parseJson(res)) as
+        | { errors?: Array<{ code?: number; message?: string }> }
+        | undefined;
+      const codes = (body?.errors ?? []).map((e) => e.code ?? 0);
+      if (codes.some((code) => CF_DUPLICATE_CODES.has(code))) {
+        // Identical record already present — idempotent success.
+        result.skipped.push(record);
+        continue;
+      }
+      const message =
+        body?.errors?.[0]?.message ?? `Cloudflare API status ${res.status}`;
+      result.errors.push(`${record.type} ${record.name}: ${message}`);
+    } catch (cause) {
+      result.errors.push(
+        `${record.type} ${record.name}: ${cause instanceof Error ? cause.message : String(cause)}`,
+      );
+    }
+  }
+  return result;
+}
+
+async function applyVercel(
+  opts: ApplyRecordsOptions,
+  fetchImpl: typeof fetch,
+): Promise<ApplyRecordsResult> {
+  const result: ApplyRecordsResult = { applied: [], skipped: [], errors: [] };
+  const token = opts.env.VERCEL_TOKEN ?? "";
+  const teamId = opts.env.VERCEL_TEAM_ID;
+  const base = `https://api.vercel.com/v2/domains/${encodeURIComponent(opts.domain)}/records`;
+  const url = teamId ? `${base}?teamId=${encodeURIComponent(teamId)}` : base;
+
+  for (const record of opts.records) {
+    try {
+      const res = await fetchImpl(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          type: record.type,
+          name: record.name,
+          value: record.value,
+          ...(record.ttl !== undefined ? { ttl: record.ttl } : {}),
+          ...(record.priority !== undefined
+            ? { mxPriority: record.priority }
+            : {}),
+        }),
+      });
+      if (res.ok) {
+        result.applied.push(record);
+        continue;
+      }
+      const body = (await parseJson(res)) as
+        | { error?: { code?: string; message?: string } }
+        | undefined;
+      const code = body?.error?.code ?? "";
+      const message = body?.error?.message ?? "";
+      if (/duplicate/i.test(code) || /already exists/i.test(message)) {
+        result.skipped.push(record);
+        continue;
+      }
+      result.errors.push(
+        `${record.type} ${record.name}: ${message || `Vercel API status ${res.status}`}`,
+      );
+    } catch (cause) {
+      result.errors.push(
+        `${record.type} ${record.name}: ${cause instanceof Error ? cause.message : String(cause)}`,
+      );
+    }
+  }
+  return result;
+}
+
+/**
+ * Apply the DNS records via the host's API. NEVER throws — failures land in
+ * `errors`, "identical record exists" responses land in `skipped`, so the
+ * caller can always render a complete applied/skipped/errors report.
+ */
+export async function applyRecords(
+  opts: ApplyRecordsOptions,
+): Promise<ApplyRecordsResult> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+
+  if (!canAutoApply(opts.host, opts.env)) {
+    return {
+      applied: [],
+      skipped: [...opts.records],
+      errors: [
+        `auto-apply is not available for ${opts.host} — add the records manually in your DNS panel`,
+      ],
+    };
+  }
+
+  if (opts.host === "cloudflare") return applyCloudflare(opts, fetchImpl);
+  return applyVercel(opts, fetchImpl);
+}

package/src/lib/dns.ts

@@ -0,0 +1,217 @@
+import { resolveNs as nodeResolveNs } from "node:dns/promises";
+import type { DnsRecord } from "@hogsend/engine";
+
+/**
+ * DNS-host smarts for `hogsend domain`: detect WHERE a domain's DNS lives (via
+ * its NS records) and render provider DNS records with host-specific guidance
+ * + a panel deep link. Pure CLI-local helpers — no engine/provider coupling
+ * beyond the neutral {@link DnsRecord} shape.
+ */
+
+export type DnsHostId =
+  | "cloudflare"
+  | "vercel"
+  | "route53"
+  | "godaddy"
+  | "namecheap"
+  | "porkbun"
+  | "google"
+  | "unknown";
+
+export interface DnsHostInfo {
+  id: DnsHostId;
+  /** Human label, e.g. "Cloudflare". */
+  label: string;
+  /** Deep link to the host's DNS panel for the domain. */
+  panelUrl: (domain: string) => string;
+  /** NS hostname suffixes that identify this host. */
+  nsSuffixes: string[];
+}
+
+/** The known DNS hosts, keyed by id. `unknown` is the registrar-agnostic fallback. */
+export const DNS_HOSTS: Record<DnsHostId, DnsHostInfo> = {
+  cloudflare: {
+    id: "cloudflare",
+    label: "Cloudflare",
+    nsSuffixes: ["ns.cloudflare.com"],
+    panelUrl: (domain) =>
+      `https://dash.cloudflare.com/?to=/:account/${domain}/dns/records`,
+  },
+  vercel: {
+    id: "vercel",
+    label: "Vercel",
+    nsSuffixes: ["vercel-dns.com"],
+    panelUrl: (domain) => `https://vercel.com/dashboard/domains/${domain}`,
+  },
+  route53: {
+    id: "route53",
+    label: "AWS Route 53",
+    nsSuffixes: ["awsdns-"],
+    panelUrl: () => "https://console.aws.amazon.com/route53/v2/hostedzones",
+  },
+  godaddy: {
+    id: "godaddy",
+    label: "GoDaddy",
+    nsSuffixes: ["domaincontrol.com"],
+    panelUrl: (domain) =>
+      `https://dcc.godaddy.com/control/portfolio/${domain}/settings`,
+  },
+  namecheap: {
+    id: "namecheap",
+    label: "Namecheap",
+    nsSuffixes: ["registrar-servers.com"],
+    panelUrl: (domain) =>
+      `https://ap.www.namecheap.com/domains/domaincontrolpanel/${domain}/advancedns`,
+  },
+  porkbun: {
+    id: "porkbun",
+    label: "Porkbun",
+    nsSuffixes: ["porkbun.com"],
+    panelUrl: (domain) => `https://porkbun.com/account/domain/${domain}`,
+  },
+  google: {
+    id: "google",
+    label: "Google Domains",
+    nsSuffixes: ["googledomains.com", "google.com"],
+    panelUrl: () => "https://domains.google.com/registrar",
+  },
+  unknown: {
+    id: "unknown",
+    label: "your DNS host",
+    nsSuffixes: [],
+    panelUrl: (domain) => `https://${domain}`,
+  },
+};
+
+/** Injectable seams for tests (NEVER hit real DNS in CI). */
+export interface DetectDnsHostOptions {
+  resolveNs?: (hostname: string) => Promise<string[]>;
+}
+
+/**
+ * Detect a domain's DNS host by resolving its NS records and suffix-matching
+ * against {@link DNS_HOSTS}. Walks UP the labels (`a.b.example.com` →
+ * `b.example.com` → `example.com`) until NS records resolve, so subdomains
+ * inherit their registrable domain's host. Any resolver failure → `unknown`
+ * (this NEVER throws — host detection is best-effort UX, not a gate).
+ */
+export async function detectDnsHost(
+  domain: string,
+  opts: DetectDnsHostOptions = {},
+): Promise<DnsHostInfo> {
+  const resolveNs = opts.resolveNs ?? nodeResolveNs;
+
+  const labels = domain.toLowerCase().split(".").filter(Boolean);
+  for (let i = 0; i <= labels.length - 2; i++) {
+    const candidate = labels.slice(i).join(".");
+    let nameservers: string[];
+    try {
+      nameservers = await resolveNs(candidate);
+    } catch {
+      continue; // walk up one label and retry
+    }
+    if (nameservers.length === 0) continue;
+
+    const lowered = nameservers.map((ns) => ns.toLowerCase());
+    for (const host of Object.values(DNS_HOSTS)) {
+      if (host.id === "unknown") continue;
+      const matched = host.nsSuffixes.some((suffix) =>
+        lowered.some((ns) => ns.includes(suffix)),
+      );
+      if (matched) return host;
+    }
+    // NS resolved but nothing matched — it's a host we don't know.
+    return DNS_HOSTS.unknown;
+  }
+  return DNS_HOSTS.unknown;
+}
+
+/** Hosts whose DNS panels expect the record host RELATIVE to the domain. */
+const RELATIVE_HOST_IDS = new Set<DnsHostId>(["namecheap", "godaddy"]);
+
+/** Strip a trailing `.domain` (or bare-domain → `@`) for relative-host panels. */
+function relativeName(name: string, domain: string): string {
+  const lowered = name.toLowerCase();
+  const suffix = `.${domain.toLowerCase()}`;
+  if (lowered === domain.toLowerCase()) return "@";
+  if (lowered.endsWith(suffix))
+    return name.slice(0, name.length - suffix.length);
+  return name;
+}
+
+function renderTable(rows: string[][], header: string[]): string {
+  const all = [header, ...rows];
+  const widths = header.map((_, col) =>
+    Math.max(...all.map((row) => (row[col] ?? "").length)),
+  );
+  const line = (row: string[]) =>
+    row
+      .map((cell, col) => cell.padEnd(widths[col] ?? 0))
+      .join("  ")
+      .trimEnd();
+  return [
+    line(header),
+    line(widths.map((w) => "-".repeat(w))),
+    ...rows.map(line),
+  ].join("\n");
+}
+
+/** Per-host guidance lines appended under the record table. */
+function hostGuidance(host: DnsHostInfo, domain: string | undefined): string[] {
+  switch (host.id) {
+    case "cloudflare":
+      return [
+        "Cloudflare: set Proxy status to DNS only (grey cloud) on every record —",
+        "proxied (orange-cloud) records break email verification.",
+      ];
+    case "namecheap":
+    case "godaddy":
+      return [
+        `${host.label}: enter the host RELATIVE to ${domain ?? "your domain"} (the table above is already relative).`,
+      ];
+    case "vercel":
+      return [
+        "Vercel: add the records under the domain's DNS tab (they apply instantly).",
+      ];
+    default:
+      return [
+        "Add these records in your DNS host's panel exactly as shown, then run",
+        "`hogsend domain check` to poll verification.",
+      ];
+  }
+}
+
+/**
+ * Render the DNS records as an aligned `type/name/value/priority/status` table
+ * with host-specific guidance. For relative-host panels (Namecheap, GoDaddy)
+ * the record names are stripped to be relative to `opts.domain` (skipped when
+ * the domain isn't supplied — the pinned two-arg call stays valid).
+ */
+export function formatRecordsFor(
+  host: DnsHostInfo,
+  records: DnsRecord[],
+  opts: { domain?: string } = {},
+): string {
+  if (records.length === 0) {
+    return "No DNS records reported by the provider yet.";
+  }
+
+  const relative = RELATIVE_HOST_IDS.has(host.id) && opts.domain !== undefined;
+  const rows = records.map((r) => [
+    r.type,
+    relative && opts.domain ? relativeName(r.name, opts.domain) : r.name,
+    r.value,
+    r.priority !== undefined ? String(r.priority) : "",
+    r.status,
+  ]);
+
+  const table = renderTable(rows, [
+    "type",
+    "name",
+    "value",
+    "priority",
+    "status",
+  ]);
+
+  return [table, "", ...hostGuidance(host, opts.domain)].join("\n");
+}

package/src/lib/proc.ts

@@ -0,0 +1,189 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+
+/**
+ * Process orchestration primitives for `hogsend dev`.
+ *
+ * The contract here is pinned (PROJECT_SPEC §d): `spawnManaged`,
+ * `shutdownAll`, `waitForHttp`. Everything else is additive.
+ */
+
+/** How a managed child finished. */
+export interface ProcessExit {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+}
+
+export interface ManagedProcess {
+  name: string;
+  child: ChildProcess;
+  /** Resolves once the child has fully exited (additive to the pinned contract). */
+  exited: Promise<ProcessExit>;
+  /** Register a callback fired once on exit; fires immediately if already exited. */
+  onExit(cb: (info: ProcessExit) => void): void;
+}
+
+/**
+ * Spawn a long-running child with line-prefixed stdio.
+ *
+ * On POSIX the child is spawned `detached`, making it its own process-group
+ * leader. That is the no-orphans mechanism: (a) the terminal's Ctrl-C SIGINT
+ * hits only our process (not the children), so the orderly shutdown can't be
+ * raced, and (b) {@link shutdownAll} can kill the whole tree (`pnpm` →
+ * `tsx watch` → app) with a negative-pid group kill.
+ */
+export function spawnManaged(opts: {
+  name: string;
+  cmd: string;
+  args: string[];
+  cwd: string;
+  env?: Record<string, string>;
+  prefixColor: (s: string) => string;
+  /**
+   * Optional line sink (additive — exists so tests can capture output).
+   * Defaults to process.stdout/stderr writes.
+   */
+  sink?: (line: string) => void;
+}): ManagedProcess {
+  const child = spawn(opts.cmd, opts.args, {
+    cwd: opts.cwd,
+    env: { ...process.env, FORCE_COLOR: "1", ...opts.env },
+    stdio: ["ignore", "pipe", "pipe"],
+    detached: process.platform !== "win32",
+  });
+
+  const prefix = opts.prefixColor(`[${opts.name}]`);
+  const writeOut = opts.sink ?? ((line: string) => process.stdout.write(line));
+  const writeErr = opts.sink ?? ((line: string) => process.stderr.write(line));
+
+  if (child.stdout) {
+    const rl = createInterface({ input: child.stdout });
+    rl.on("line", (line) => writeOut(`${prefix} ${line}\n`));
+  }
+  if (child.stderr) {
+    const rl = createInterface({ input: child.stderr });
+    rl.on("line", (line) => writeErr(`${prefix} ${line}\n`));
+  }
+
+  const callbacks: Array<(info: ProcessExit) => void> = [];
+  let exitInfo: ProcessExit | null = null;
+  const exited = new Promise<ProcessExit>((resolve) => {
+    const settle = (info: ProcessExit) => {
+      if (exitInfo) return;
+      exitInfo = info;
+      resolve(info);
+      for (const cb of callbacks) cb(info);
+    };
+    child.once("close", (code, signal) => settle({ code, signal }));
+    // A spawn failure (e.g. command not found) may never emit `close`.
+    child.once("error", (err) => {
+      writeErr(`${prefix} failed to start: ${err.message}\n`);
+      settle({ code: null, signal: null });
+    });
+  });
+
+  return {
+    name: opts.name,
+    child,
+    exited,
+    onExit(cb) {
+      if (exitInfo) {
+        cb(exitInfo);
+        return;
+      }
+      callbacks.push(cb);
+    },
+  };
+}
+
+function hasExited(proc: ManagedProcess): boolean {
+  return (
+    proc.child.pid === undefined ||
+    proc.child.exitCode !== null ||
+    proc.child.signalCode !== null
+  );
+}
+
+/**
+ * Send `signal` to the child's whole process group (POSIX), falling back to a
+ * direct kill on Windows or when the group kill fails. Swallows ESRCH
+ * (already dead).
+ */
+function killTree(proc: ManagedProcess, signal: NodeJS.Signals): void {
+  const pid = proc.child.pid;
+  if (pid === undefined || hasExited(proc)) return;
+  try {
+    if (process.platform !== "win32") {
+      process.kill(-pid, signal);
+    } else {
+      proc.child.kill(signal);
+    }
+  } catch {
+    try {
+      proc.child.kill(signal);
+    } catch {
+      // already dead — nothing to do
+    }
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Gracefully stop every managed process: SIGTERM the process groups, wait up
+ * to `timeoutMs` (default 5s), then SIGKILL any stragglers. Idempotent — safe
+ * to call twice (e.g. SIGINT and SIGTERM both arriving) and tolerant of
+ * already-exited children.
+ */
+export async function shutdownAll(
+  procs: ManagedProcess[],
+  opts?: { timeoutMs?: number },
+): Promise<void> {
+  if (procs.length === 0) return;
+  const timeoutMs = opts?.timeoutMs ?? 5000;
+
+  for (const proc of procs) killTree(proc, "SIGTERM");
+
+  const allExited = Promise.all(procs.map((p) => p.exited));
+  await Promise.race([allExited, sleep(timeoutMs)]);
+
+  const stragglers = procs.filter((p) => !hasExited(p));
+  if (stragglers.length === 0) return;
+
+  for (const proc of stragglers) killTree(proc, "SIGKILL");
+  // Give the SIGKILLed children a beat to be reaped so callers don't return
+  // while the OS still lists them.
+  await Promise.race([allExited, sleep(2000)]);
+}
+
+/**
+ * Poll `url` every 500ms (2s per-attempt timeout) until it answers 2xx, or
+ * reject after `timeoutMs` with an actionable message carrying the URL and
+ * the last failure (connection error vs non-2xx status).
+ */
+export async function waitForHttp(
+  url: string,
+  timeoutMs: number,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  let lastError = "no attempt completed";
+
+  do {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(2000) });
+      if (res.ok) return;
+      lastError = `last response: HTTP ${res.status}`;
+    } catch (err) {
+      lastError = `last error: ${
+        err instanceof Error ? err.message : String(err)
+      }`;
+    }
+    await sleep(500);
+  } while (Date.now() < deadline);
+
+  throw new Error(
+    `timed out after ${Math.round(timeoutMs / 1000)}s waiting for ${url} (${lastError})`,
+  );
+}