@absolutejs/deploy 0.3.1 → 0.4.0

package/README.md

@@ -188,6 +188,47 @@ happen. Admin helpers: `listHetznerServers({ token, labelSelector?
 })` (Hetzner's `'env=prod'` / `'env in (prod,staging)'` syntax);
 `destroyHetznerServer({ token, id })` (404 idempotent success).
 
+## `@absolutejs/deploy/cloudflare` — DNS automation (0.4.0)
+
+After provisioning a Target, point a hostname at its IP without
+leaving the deploy script. `cloudflareProvider({ token, zoneId })`
+implements the shared `DnsProvider` contract from
+`@absolutejs/deploy/dns`.
+
+```ts
+import { hetznerTarget } from '@absolutejs/deploy/hetzner';
+import { cloudflareProvider } from '@absolutejs/deploy/cloudflare';
+import { ensureDnsForTarget } from '@absolutejs/deploy/dns';
+
+const target = await hetznerTarget({ /* … */ });
+const dns = cloudflareProvider({
+  token: process.env.CLOUDFLARE_TOKEN!,
+  zoneId: process.env.CLOUDFLARE_ZONE_ID!,
+});
+
+// Idempotent — create or update so the A record points at target.ipv4.
+await ensureDnsForTarget(dns, {
+  name: 'api.example.com',
+  target,
+  ttl: 60,
+  proxied: false,
+});
+```
+
+`upsert` is the canonical entry: finds by exact (name, type); skips
+the API call entirely when the existing record already matches the
+spec (no churn on TTL / proxied / comment agreement). Multiple
+records sharing the same (name, type) throw with a "resolve
+manually" message instead of silently picking one.
+
+Auth uses Cloudflare API tokens with `Zone:DNS:Edit` scope (global
+keys not supported). Pair with `provider.list({ name?, type? })`
+for inventory, `provider.delete(id)` for tear-down (404 idempotent
+success).
+
+The same `DnsProvider` contract applies to other providers — Route
+53 / DigitalOcean DNS / etc. follow next.
+
 ## DigitalOcean Droplet — first deploy (manual)
 
 Assuming a fresh Ubuntu/Debian Droplet:
@@ -207,9 +248,11 @@ bun run my-deploy-script.ts
 
 The first run creates `/srv/<appName>/releases/<id>/`, drops a systemd unit at `/etc/systemd/system/<appName>.service` (if you're using `systemdManager`), starts the service, and probes. Subsequent runs just add a new release dir and swap the symlink.
 
-## What v0.3.0 does NOT include
+## What v0.4.0 does NOT include
 
-- Provider-specific HTTP-API adapters beyond DigitalOcean + Hetzner (Cloudflare Workers, Fly Machines, AWS Fargate, GCP Cloud Run). Linode / Vultr follow the same shape and are next on the list.
+- TLS certificate automation. ACME / Let's Encrypt is a separate concern — coming next.
+- Cloud-provider compute targets beyond DigitalOcean + Hetzner. Linode / Vultr / Fly Machines follow the same shape and are next on the list.
+- DNS providers beyond Cloudflare. Route 53 / DigitalOcean DNS / Hetzner DNS slot into the same `DnsProvider` contract.
 - Bun installation on the remote — caller does it once, out of band.
 - Multi-target / fan-out deploys (caller iterates).
 - Zero-downtime port-swap (start new release on a fresh port, then nginx-reload). The default pipeline does stop-then-start; for true zero-downtime, replace the `restart` step.

package/dist/cloudflare.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @absolutejs/deploy/cloudflare — Cloudflare DNS adapter implementing
+ * the {@link DnsProvider} contract from `./dns`.
+ *
+ * Scope: one provider instance is bound to one Cloudflare zone. Multi-
+ * zone callers construct one provider per zone.
+ *
+ * Auth: Cloudflare API tokens with `Zone:DNS:Edit` scope. Global API
+ * keys are intentionally not supported — tokens are the modern path.
+ *
+ * Narrow CloudflareClientLike interface keeps `cloudflare` SDK out as
+ * a hard dep. Default client uses `fetch` against
+ * `api.cloudflare.com/client/v4`.
+ */
+import type { DnsProvider } from './dns';
+/**
+ * Minimal subset of Cloudflare API calls. Lets callers BYO a client
+ * with retry / observability / etc.
+ */
+export type CloudflareClientLike = {
+    request: <T = unknown>(method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, body?: unknown) => Promise<T>;
+};
+export declare class CloudflareError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+/**
+ * fetch-backed default client. Throws CloudflareError on non-2xx OR
+ * on a 2xx with `success: false` (Cloudflare returns 200 + an errors
+ * array for some validation failures, hence the second check).
+ */
+export declare const createCloudflareClient: (token: string, options?: {
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}) => CloudflareClientLike;
+export type CloudflareProviderOptions = {
+    /** API token with `Zone:DNS:Edit` permission. Required unless `client` is set. */
+    token?: string;
+    /** Custom client. Overrides token-built default. */
+    client?: CloudflareClientLike;
+    /** Cloudflare Zone ID this provider operates on. */
+    zoneId: string;
+    /** Optional zone name for log copy. Default uses `zoneId` truncated. */
+    zoneName?: string;
+};
+/**
+ * Build a {@link DnsProvider} bound to one Cloudflare zone.
+ */
+export declare const cloudflareProvider: (options: CloudflareProviderOptions) => DnsProvider;

package/dist/cloudflare.js

@@ -0,0 +1,155 @@
+// @bun
+// src/cloudflare.ts
+var CLOUDFLARE_API_BASE = "https://api.cloudflare.com/client/v4";
+
+class CloudflareError extends Error {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.name = "CloudflareError";
+    this.status = status;
+    this.body = body;
+  }
+}
+var createCloudflareClient = (token, options = {}) => {
+  const base = options.baseUrl ?? CLOUDFLARE_API_BASE;
+  const f = options.fetch ?? fetch;
+  return {
+    request: async (method, path, body) => {
+      const init = {
+        headers: {
+          authorization: `Bearer ${token}`,
+          "content-type": "application/json"
+        },
+        method
+      };
+      if (body !== undefined)
+        init.body = JSON.stringify(body);
+      const response = await f(`${base}${path}`, init);
+      const text = await response.text();
+      const parsed = text.length > 0 ? JSON.parse(text) : undefined;
+      if (!response.ok) {
+        throw new CloudflareError(`Cloudflare API ${method} ${path} failed: ${response.status} ${response.statusText}`, response.status, parsed);
+      }
+      return parsed;
+    }
+  };
+};
+var resolveClient = (options) => {
+  if (options.client !== undefined)
+    return options.client;
+  if (options.token !== undefined && options.token.length > 0) {
+    return createCloudflareClient(options.token);
+  }
+  throw new Error("[deploy/cloudflare] either `token` or `client` must be provided");
+};
+var toDnsRecord = (raw) => ({
+  content: raw.content,
+  id: raw.id,
+  name: raw.name,
+  type: raw.type,
+  ...raw.ttl !== undefined ? { ttl: raw.ttl } : {},
+  ...raw.proxied !== undefined ? { proxied: raw.proxied } : {},
+  ...raw.comment !== undefined ? { comment: raw.comment } : {}
+});
+var specEqualsRecord = (spec, record) => {
+  if (record.content !== spec.content)
+    return false;
+  if (spec.ttl !== undefined && record.ttl !== spec.ttl)
+    return false;
+  if (spec.proxied !== undefined && record.proxied !== spec.proxied)
+    return false;
+  if (spec.comment !== undefined && record.comment !== spec.comment)
+    return false;
+  return true;
+};
+var buildQuery = (filter) => {
+  const params = [];
+  if (filter?.name !== undefined) {
+    params.push(`name=${encodeURIComponent(filter.name)}`);
+  }
+  if (filter?.type !== undefined) {
+    params.push(`type=${encodeURIComponent(filter.type)}`);
+  }
+  return params.length > 0 ? `?${params.join("&")}` : "";
+};
+var cloudflareProvider = (options) => {
+  const client = resolveClient(options);
+  const { zoneId } = options;
+  const zoneLabel = options.zoneName ?? zoneId.slice(0, 8);
+  const recordsPath = `/zones/${zoneId}/dns_records`;
+  const list = async (filter) => {
+    const response = await client.request("GET", `${recordsPath}${buildQuery(filter)}`);
+    return response.result.map(toDnsRecord);
+  };
+  const find = async (key) => {
+    const matches = await list(key);
+    const exact = matches.filter((record) => record.name === key.name || record.name === `${key.name}.`);
+    if (exact.length === 0)
+      return;
+    if (exact.length > 1) {
+      throw new Error(`[deploy/cloudflare] multiple ${key.type} records for "${key.name}" in zone ${zoneLabel} \u2014 drifted state; resolve manually before upsert.`);
+    }
+    return exact[0];
+  };
+  const create = async (spec) => {
+    const response = await client.request("POST", recordsPath, {
+      content: spec.content,
+      name: spec.name,
+      type: spec.type,
+      ...spec.ttl !== undefined ? { ttl: spec.ttl } : {},
+      ...spec.proxied !== undefined ? { proxied: spec.proxied } : {},
+      ...spec.comment !== undefined ? { comment: spec.comment } : {}
+    });
+    return toDnsRecord(response.result);
+  };
+  const update = async (id, spec) => {
+    const response = await client.request("PUT", `${recordsPath}/${id}`, {
+      content: spec.content,
+      name: spec.name,
+      type: spec.type,
+      ...spec.ttl !== undefined ? { ttl: spec.ttl } : {},
+      ...spec.proxied !== undefined ? { proxied: spec.proxied } : {},
+      ...spec.comment !== undefined ? { comment: spec.comment } : {}
+    });
+    return toDnsRecord(response.result);
+  };
+  const deleteRecord = async (id) => {
+    try {
+      await client.request("DELETE", `${recordsPath}/${id}`);
+    } catch (error) {
+      if (error instanceof CloudflareError && error.status === 404) {
+        return;
+      }
+      throw error;
+    }
+  };
+  const upsert = async (spec) => {
+    const existing = await find({ name: spec.name, type: spec.type });
+    if (existing === undefined) {
+      return create(spec);
+    }
+    if (specEqualsRecord(spec, existing)) {
+      return existing;
+    }
+    return update(existing.id, spec);
+  };
+  return {
+    create,
+    delete: deleteRecord,
+    description: `cloudflare zone "${zoneLabel}"`,
+    find,
+    list,
+    update,
+    upsert
+  };
+};
+export {
+  createCloudflareClient,
+  cloudflareProvider,
+  CloudflareError
+};
+
+//# debugId=CC538CE8BF2FCBDB64756E2164756E21
+//# sourceMappingURL=cloudflare.js.map

package/dist/cloudflare.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/cloudflare.ts"],
+  "sourcesContent": [
+    "/**\n * @absolutejs/deploy/cloudflare — Cloudflare DNS adapter implementing\n * the {@link DnsProvider} contract from `./dns`.\n *\n * Scope: one provider instance is bound to one Cloudflare zone. Multi-\n * zone callers construct one provider per zone.\n *\n * Auth: Cloudflare API tokens with `Zone:DNS:Edit` scope. Global API\n * keys are intentionally not supported — tokens are the modern path.\n *\n * Narrow CloudflareClientLike interface keeps `cloudflare` SDK out as\n * a hard dep. Default client uses `fetch` against\n * `api.cloudflare.com/client/v4`.\n */\n\nimport type {\n\tDnsProvider,\n\tDnsRecord,\n\tDnsRecordFilter,\n\tDnsRecordSpec,\n\tDnsRecordType\n} from './dns';\n\nconst CLOUDFLARE_API_BASE = 'https://api.cloudflare.com/client/v4';\n\n/**\n * Minimal subset of Cloudflare API calls. Lets callers BYO a client\n * with retry / observability / etc.\n */\nexport type CloudflareClientLike = {\n\trequest: <T = unknown>(\n\t\tmethod: 'GET' | 'POST' | 'PUT' | 'DELETE',\n\t\tpath: string,\n\t\tbody?: unknown\n\t) => Promise<T>;\n};\n\n/** Cloudflare's standard envelope on every response. */\ntype CloudflareResponse<T> = {\n\tsuccess: boolean;\n\tresult: T;\n\terrors?: Array<{ code: number; message: string }>;\n\tmessages?: Array<{ code: number; message: string }>;\n};\n\n/** Raw record from Cloudflare's API. */\ntype CloudflareDnsRecord = {\n\tid: string;\n\tname: string;\n\ttype: string;\n\tcontent: string;\n\tttl?: number;\n\tproxied?: boolean;\n\tcomment?: string;\n\tzone_id?: string;\n\tzone_name?: string;\n};\n\nexport class CloudflareError extends Error {\n\treadonly status: number;\n\treadonly body: unknown;\n\tconstructor(message: string, status: number, body: unknown) {\n\t\tsuper(message);\n\t\tthis.name = 'CloudflareError';\n\t\tthis.status = status;\n\t\tthis.body = body;\n\t}\n}\n\n/**\n * fetch-backed default client. Throws CloudflareError on non-2xx OR\n * on a 2xx with `success: false` (Cloudflare returns 200 + an errors\n * array for some validation failures, hence the second check).\n */\nexport const createCloudflareClient = (\n\ttoken: string,\n\toptions: { baseUrl?: string; fetch?: typeof fetch } = {}\n): CloudflareClientLike => {\n\tconst base = options.baseUrl ?? CLOUDFLARE_API_BASE;\n\tconst f = options.fetch ?? fetch;\n\treturn {\n\t\trequest: async <T>(\n\t\t\tmethod: 'GET' | 'POST' | 'PUT' | 'DELETE',\n\t\t\tpath: string,\n\t\t\tbody?: unknown\n\t\t): Promise<T> => {\n\t\t\tconst init: RequestInit = {\n\t\t\t\theaders: {\n\t\t\t\t\tauthorization: `Bearer ${token}`,\n\t\t\t\t\t'content-type': 'application/json'\n\t\t\t\t},\n\t\t\t\tmethod\n\t\t\t};\n\t\t\tif (body !== undefined) init.body = JSON.stringify(body);\n\t\t\tconst response = await f(`${base}${path}`, init);\n\t\t\tconst text = await response.text();\n\t\t\tconst parsed = text.length > 0 ? JSON.parse(text) : undefined;\n\t\t\tif (!response.ok) {\n\t\t\t\tthrow new CloudflareError(\n\t\t\t\t\t`Cloudflare API ${method} ${path} failed: ${response.status} ${response.statusText}`,\n\t\t\t\t\tresponse.status,\n\t\t\t\t\tparsed\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn parsed as T;\n\t\t}\n\t};\n};\n\nexport type CloudflareProviderOptions = {\n\t/** API token with `Zone:DNS:Edit` permission. Required unless `client` is set. */\n\ttoken?: string;\n\t/** Custom client. Overrides token-built default. */\n\tclient?: CloudflareClientLike;\n\t/** Cloudflare Zone ID this provider operates on. */\n\tzoneId: string;\n\t/** Optional zone name for log copy. Default uses `zoneId` truncated. */\n\tzoneName?: string;\n};\n\nconst resolveClient = (\n\toptions: Pick<CloudflareProviderOptions, 'client' | 'token'>\n): CloudflareClientLike => {\n\tif (options.client !== undefined) return options.client;\n\tif (options.token !== undefined && options.token.length > 0) {\n\t\treturn createCloudflareClient(options.token);\n\t}\n\tthrow new Error(\n\t\t'[deploy/cloudflare] either `token` or `client` must be provided'\n\t);\n};\n\nconst toDnsRecord = (raw: CloudflareDnsRecord): DnsRecord => ({\n\tcontent: raw.content,\n\tid: raw.id,\n\tname: raw.name,\n\ttype: raw.type as DnsRecordType,\n\t...(raw.ttl !== undefined ? { ttl: raw.ttl } : {}),\n\t...(raw.proxied !== undefined ? { proxied: raw.proxied } : {}),\n\t...(raw.comment !== undefined ? { comment: raw.comment } : {})\n});\n\nconst specEqualsRecord = (spec: DnsRecordSpec, record: DnsRecord): boolean => {\n\tif (record.content !== spec.content) return false;\n\tif (spec.ttl !== undefined && record.ttl !== spec.ttl) return false;\n\tif (spec.proxied !== undefined && record.proxied !== spec.proxied)\n\t\treturn false;\n\tif (spec.comment !== undefined && record.comment !== spec.comment)\n\t\treturn false;\n\treturn true;\n};\n\nconst buildQuery = (filter?: DnsRecordFilter): string => {\n\tconst params: string[] = [];\n\tif (filter?.name !== undefined) {\n\t\tparams.push(`name=${encodeURIComponent(filter.name)}`);\n\t}\n\tif (filter?.type !== undefined) {\n\t\tparams.push(`type=${encodeURIComponent(filter.type)}`);\n\t}\n\treturn params.length > 0 ? `?${params.join('&')}` : '';\n};\n\n/**\n * Build a {@link DnsProvider} bound to one Cloudflare zone.\n */\nexport const cloudflareProvider = (\n\toptions: CloudflareProviderOptions\n): DnsProvider => {\n\tconst client = resolveClient(options);\n\tconst { zoneId } = options;\n\tconst zoneLabel = options.zoneName ?? zoneId.slice(0, 8);\n\tconst recordsPath = `/zones/${zoneId}/dns_records`;\n\n\tconst list = async (filter?: DnsRecordFilter): Promise<DnsRecord[]> => {\n\t\tconst response = await client.request<\n\t\t\tCloudflareResponse<CloudflareDnsRecord[]>\n\t\t>('GET', `${recordsPath}${buildQuery(filter)}`);\n\t\treturn response.result.map(toDnsRecord);\n\t};\n\n\tconst find = async (key: {\n\t\tname: string;\n\t\ttype: DnsRecordType;\n\t}): Promise<DnsRecord | undefined> => {\n\t\tconst matches = await list(key);\n\t\t// Cloudflare's filter is sometimes substring-loose on `name`; pin to\n\t\t// an exact match here so a `'api.example.com'` lookup never returns\n\t\t// `'api.example.com.staging'`.\n\t\tconst exact = matches.filter(\n\t\t\t(record) => record.name === key.name || record.name === `${key.name}.`\n\t\t);\n\t\tif (exact.length === 0) return undefined;\n\t\tif (exact.length > 1) {\n\t\t\tthrow new Error(\n\t\t\t\t`[deploy/cloudflare] multiple ${key.type} records for \"${key.name}\" in zone ${zoneLabel} — drifted state; resolve manually before upsert.`\n\t\t\t);\n\t\t}\n\t\treturn exact[0];\n\t};\n\n\tconst create = async (spec: DnsRecordSpec): Promise<DnsRecord> => {\n\t\tconst response = await client.request<\n\t\t\tCloudflareResponse<CloudflareDnsRecord>\n\t\t>('POST', recordsPath, {\n\t\t\tcontent: spec.content,\n\t\t\tname: spec.name,\n\t\t\ttype: spec.type,\n\t\t\t...(spec.ttl !== undefined ? { ttl: spec.ttl } : {}),\n\t\t\t...(spec.proxied !== undefined ? { proxied: spec.proxied } : {}),\n\t\t\t...(spec.comment !== undefined ? { comment: spec.comment } : {})\n\t\t});\n\t\treturn toDnsRecord(response.result);\n\t};\n\n\tconst update = async (\n\t\tid: string,\n\t\tspec: DnsRecordSpec\n\t): Promise<DnsRecord> => {\n\t\tconst response = await client.request<\n\t\t\tCloudflareResponse<CloudflareDnsRecord>\n\t\t>('PUT', `${recordsPath}/${id}`, {\n\t\t\tcontent: spec.content,\n\t\t\tname: spec.name,\n\t\t\ttype: spec.type,\n\t\t\t...(spec.ttl !== undefined ? { ttl: spec.ttl } : {}),\n\t\t\t...(spec.proxied !== undefined ? { proxied: spec.proxied } : {}),\n\t\t\t...(spec.comment !== undefined ? { comment: spec.comment } : {})\n\t\t});\n\t\treturn toDnsRecord(response.result);\n\t};\n\n\tconst deleteRecord = async (id: string): Promise<void> => {\n\t\ttry {\n\t\t\tawait client.request('DELETE', `${recordsPath}/${id}`);\n\t\t} catch (error) {\n\t\t\tif (error instanceof CloudflareError && error.status === 404) {\n\t\t\t\treturn; // already gone — idempotent\n\t\t\t}\n\t\t\tthrow error;\n\t\t}\n\t};\n\n\tconst upsert = async (spec: DnsRecordSpec): Promise<DnsRecord> => {\n\t\tconst existing = await find({ name: spec.name, type: spec.type });\n\t\tif (existing === undefined) {\n\t\t\treturn create(spec);\n\t\t}\n\t\tif (specEqualsRecord(spec, existing)) {\n\t\t\treturn existing;\n\t\t}\n\t\treturn update(existing.id, spec);\n\t};\n\n\treturn {\n\t\tcreate,\n\t\tdelete: deleteRecord,\n\t\tdescription: `cloudflare zone \"${zoneLabel}\"`,\n\t\tfind,\n\t\tlist,\n\t\tupdate,\n\t\tupsert\n\t};\n};\n"
+  ],
+  "mappings": "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",
+  "debugId": "CC538CE8BF2FCBDB64756E2164756E21",
+  "names": []
+}

package/dist/dns.d.ts

@@ -0,0 +1,101 @@
+/**
+ * DNS provider contract for `@absolutejs/deploy`. Provider-specific
+ * adapters (Cloudflare, Route 53, etc.) implement `DnsProvider`; the
+ * deploy pipeline composes them with a cloud `Target` to point a
+ * hostname at a freshly-provisioned IP.
+ *
+ * Operations are zone-scoped: a `DnsProvider` instance is bound to
+ * one zone at construction time. Multi-zone hosts construct one
+ * provider per zone.
+ */
+/** Record types we care about for deploy workflows. */
+export type DnsRecordType = 'A' | 'AAAA' | 'CNAME' | 'TXT' | 'MX';
+/** A DNS record as it exists in the provider. */
+export type DnsRecord = {
+    /** Provider-assigned id (Cloudflare uuid, Route 53 set name, etc.). */
+    id: string;
+    /** Fully-qualified record name (`api.example.com.`). */
+    name: string;
+    type: DnsRecordType;
+    /** Record value — IP for A/AAAA, hostname for CNAME, text for TXT, etc. */
+    content: string;
+    ttl?: number;
+    /**
+     * Cloudflare's orange-cloud proxy flag. Other providers ignore this
+     * field. Default behavior is provider-specific: Cloudflare defaults
+     * to `true` (proxied) for new records when omitted.
+     */
+    proxied?: boolean;
+    comment?: string;
+};
+/** Desired state for an upsert. */
+export type DnsRecordSpec = {
+    /** Record name. May be `'@'` for the zone apex or relative ('api'). */
+    name: string;
+    type: DnsRecordType;
+    content: string;
+    ttl?: number;
+    proxied?: boolean;
+    comment?: string;
+};
+export type DnsRecordFilter = {
+    name?: string;
+    type?: DnsRecordType;
+};
+/**
+ * Zone-scoped DNS operations. Implementations: `cloudflareProvider`,
+ * future `route53Provider`, etc.
+ */
+export type DnsProvider = {
+    /** Human-readable description for logs (`'cloudflare zone "example.com"'`). */
+    readonly description: string;
+    /** List records, optionally filtered by name + type. */
+    list: (filter?: DnsRecordFilter) => Promise<DnsRecord[]>;
+    /**
+     * Find one record by exact (name, type). Returns undefined if absent.
+     * Throws if multiple records share that key (drifted state — multiple
+     * A records pointing at different IPs, etc.).
+     */
+    find: (key: {
+        name: string;
+        type: DnsRecordType;
+    }) => Promise<DnsRecord | undefined>;
+    create: (spec: DnsRecordSpec) => Promise<DnsRecord>;
+    update: (id: string, spec: DnsRecordSpec) => Promise<DnsRecord>;
+    delete: (id: string) => Promise<void>;
+    /**
+     * Create or update so the (name, type) record matches `spec`. The
+     * canonical "point this DNS at this IP" entry point — idempotent.
+     */
+    upsert: (spec: DnsRecordSpec) => Promise<DnsRecord>;
+};
+/**
+ * Compose a DNS provider with a cloud Target's IPv4. Idempotently
+ * ensures an A record (name → target.ipv4) exists. Returns the
+ * resulting DNS record.
+ *
+ * Usage:
+ *
+ *   const target = await digitalOceanTarget({ ... });
+ *   const dns = cloudflareProvider({ token, zoneId });
+ *   await ensureDnsForTarget(dns, {
+ *     name: 'api.example.com',
+ *     target,
+ *     ttl: 60,
+ *     proxied: false,
+ *   });
+ */
+export declare const ensureDnsForTarget: (provider: DnsProvider, options: {
+    /** Record name (FQDN, relative, or `'@'` for zone apex). */
+    name: string;
+    /** Cloud Target with an `ipv4` field. */
+    target: {
+        ipv4: string;
+    };
+    /** Default 300s. */
+    ttl?: number;
+    /** Cloudflare orange-cloud. Other providers ignore. */
+    proxied?: boolean;
+    /** Optional record comment for audit trails. */
+    comment?: string;
+}) => Promise<DnsRecord>;

package/dist/dns.js

@@ -0,0 +1,16 @@
+// @bun
+// src/dns.ts
+var ensureDnsForTarget = async (provider, options) => provider.upsert({
+  content: options.target.ipv4,
+  name: options.name,
+  type: "A",
+  ...options.ttl !== undefined ? { ttl: options.ttl } : {},
+  ...options.proxied !== undefined ? { proxied: options.proxied } : {},
+  ...options.comment !== undefined ? { comment: options.comment } : {}
+});
+export {
+  ensureDnsForTarget
+};
+
+//# debugId=9927EACBFED2D7E864756E2164756E21
+//# sourceMappingURL=dns.js.map

package/dist/dns.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/dns.ts"],
+  "sourcesContent": [
+    "/**\n * DNS provider contract for `@absolutejs/deploy`. Provider-specific\n * adapters (Cloudflare, Route 53, etc.) implement `DnsProvider`; the\n * deploy pipeline composes them with a cloud `Target` to point a\n * hostname at a freshly-provisioned IP.\n *\n * Operations are zone-scoped: a `DnsProvider` instance is bound to\n * one zone at construction time. Multi-zone hosts construct one\n * provider per zone.\n */\n\n/** Record types we care about for deploy workflows. */\nexport type DnsRecordType = 'A' | 'AAAA' | 'CNAME' | 'TXT' | 'MX';\n\n/** A DNS record as it exists in the provider. */\nexport type DnsRecord = {\n\t/** Provider-assigned id (Cloudflare uuid, Route 53 set name, etc.). */\n\tid: string;\n\t/** Fully-qualified record name (`api.example.com.`). */\n\tname: string;\n\ttype: DnsRecordType;\n\t/** Record value — IP for A/AAAA, hostname for CNAME, text for TXT, etc. */\n\tcontent: string;\n\tttl?: number;\n\t/**\n\t * Cloudflare's orange-cloud proxy flag. Other providers ignore this\n\t * field. Default behavior is provider-specific: Cloudflare defaults\n\t * to `true` (proxied) for new records when omitted.\n\t */\n\tproxied?: boolean;\n\tcomment?: string;\n};\n\n/** Desired state for an upsert. */\nexport type DnsRecordSpec = {\n\t/** Record name. May be `'@'` for the zone apex or relative ('api'). */\n\tname: string;\n\ttype: DnsRecordType;\n\tcontent: string;\n\tttl?: number;\n\tproxied?: boolean;\n\tcomment?: string;\n};\n\nexport type DnsRecordFilter = {\n\tname?: string;\n\ttype?: DnsRecordType;\n};\n\n/**\n * Zone-scoped DNS operations. Implementations: `cloudflareProvider`,\n * future `route53Provider`, etc.\n */\nexport type DnsProvider = {\n\t/** Human-readable description for logs (`'cloudflare zone \"example.com\"'`). */\n\treadonly description: string;\n\t/** List records, optionally filtered by name + type. */\n\tlist: (filter?: DnsRecordFilter) => Promise<DnsRecord[]>;\n\t/**\n\t * Find one record by exact (name, type). Returns undefined if absent.\n\t * Throws if multiple records share that key (drifted state — multiple\n\t * A records pointing at different IPs, etc.).\n\t */\n\tfind: (key: {\n\t\tname: string;\n\t\ttype: DnsRecordType;\n\t}) => Promise<DnsRecord | undefined>;\n\tcreate: (spec: DnsRecordSpec) => Promise<DnsRecord>;\n\tupdate: (id: string, spec: DnsRecordSpec) => Promise<DnsRecord>;\n\tdelete: (id: string) => Promise<void>;\n\t/**\n\t * Create or update so the (name, type) record matches `spec`. The\n\t * canonical \"point this DNS at this IP\" entry point — idempotent.\n\t */\n\tupsert: (spec: DnsRecordSpec) => Promise<DnsRecord>;\n};\n\n/**\n * Compose a DNS provider with a cloud Target's IPv4. Idempotently\n * ensures an A record (name → target.ipv4) exists. Returns the\n * resulting DNS record.\n *\n * Usage:\n *\n *   const target = await digitalOceanTarget({ ... });\n *   const dns = cloudflareProvider({ token, zoneId });\n *   await ensureDnsForTarget(dns, {\n *     name: 'api.example.com',\n *     target,\n *     ttl: 60,\n *     proxied: false,\n *   });\n */\nexport const ensureDnsForTarget = async (\n\tprovider: DnsProvider,\n\toptions: {\n\t\t/** Record name (FQDN, relative, or `'@'` for zone apex). */\n\t\tname: string;\n\t\t/** Cloud Target with an `ipv4` field. */\n\t\ttarget: { ipv4: string };\n\t\t/** Default 300s. */\n\t\tttl?: number;\n\t\t/** Cloudflare orange-cloud. Other providers ignore. */\n\t\tproxied?: boolean;\n\t\t/** Optional record comment for audit trails. */\n\t\tcomment?: string;\n\t}\n): Promise<DnsRecord> =>\n\tprovider.upsert({\n\t\tcontent: options.target.ipv4,\n\t\tname: options.name,\n\t\ttype: 'A',\n\t\t...(options.ttl !== undefined ? { ttl: options.ttl } : {}),\n\t\t...(options.proxied !== undefined ? { proxied: options.proxied } : {}),\n\t\t...(options.comment !== undefined ? { comment: options.comment } : {})\n\t});\n"
+  ],
+  "mappings": ";;AA6FO,IAAM,qBAAqB,OACjC,UACA,YAaA,SAAS,OAAO;AAAA,EACf,SAAS,QAAQ,OAAO;AAAA,EACxB,MAAM,QAAQ;AAAA,EACd,MAAM;AAAA,KACF,QAAQ,QAAQ,YAAY,EAAE,KAAK,QAAQ,IAAI,IAAI,CAAC;AAAA,KACpD,QAAQ,YAAY,YAAY,EAAE,SAAS,QAAQ,QAAQ,IAAI,CAAC;AAAA,KAChE,QAAQ,YAAY,YAAY,EAAE,SAAS,QAAQ,QAAQ,IAAI,CAAC;AACrE,CAAC;",
+  "debugId": "9927EACBFED2D7E864756E2164756E21",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/deploy",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Generic Bun-project deploy pipeline. A Target (localTarget / sshTarget) is anywhere you can exec + upload — DigitalOcean droplets, Linode, Hetzner, Vultr, your own boxes. Bundled pipeline: prepare → upload → install → build → link → restart → verify. Atomic symlink swap, release history, prune, hooks. SSH shells out to system ssh/rsync — zero ssh2 deps.",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
     "release"
   ],
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts src/digitalocean.ts src/hetzner.ts --outdir dist --sourcemap --target=bun && tsc --project tsconfig.build.json",
+    "build": "rm -rf dist && bun build src/index.ts src/digitalocean.ts src/hetzner.ts src/dns.ts src/cloudflare.ts --outdir dist --sourcemap --target=bun && tsc --project tsconfig.build.json",
     "test": "bun test tests/",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write \"./**/*.{ts,json,md}\"",
@@ -56,6 +56,16 @@
       "types": "./dist/hetzner.d.ts",
       "import": "./dist/hetzner.js",
       "default": "./dist/hetzner.js"
+    },
+    "./dns": {
+      "types": "./dist/dns.d.ts",
+      "import": "./dist/dns.js",
+      "default": "./dist/dns.js"
+    },
+    "./cloudflare": {
+      "types": "./dist/cloudflare.d.ts",
+      "import": "./dist/cloudflare.js",
+      "default": "./dist/cloudflare.js"
     }
   },
   "files": ["dist", "README.md"]