@promptbook/cli 0.113.0-9 → 0.114.0-0

package/apps/agents-server/src/utils/cloudflare/CloudflareDnsBatchApplication.ts

@@ -0,0 +1,49 @@
+/**
+ * What happened with one DNS record during a batch import into Cloudflare.
+ */
+export type CloudflareDnsBatchRecordStatus = 'created' | 'updated' | 'unchanged' | 'skipped' | 'failed';
+
+/**
+ * Result of importing one DNS record from the DNS manual into Cloudflare.
+ */
+export type CloudflareDnsBatchRecordResult = {
+    /**
+     * DNS record type.
+     */
+    readonly type: string;
+
+    /**
+     * Fully qualified DNS record name.
+     */
+    readonly name: string;
+
+    /**
+     * DNS record value from the DNS manual.
+     */
+    readonly value: string;
+
+    /**
+     * What happened with the record.
+     */
+    readonly status: CloudflareDnsBatchRecordStatus;
+
+    /**
+     * Human-readable explanation shown in the wizard.
+     */
+    readonly message: string;
+};
+
+/**
+ * Result of importing all DNS records of one manual into Cloudflare.
+ */
+export type CloudflareDnsBatchApplication = {
+    /**
+     * Cloudflare zone which received the records.
+     */
+    readonly zoneName: string;
+
+    /**
+     * Result of every imported record.
+     */
+    readonly results: ReadonlyArray<CloudflareDnsBatchRecordResult>;
+};

package/apps/agents-server/src/utils/cloudflare/applyCloudflareDnsRecordInstructions.ts

@@ -0,0 +1,142 @@
+import { spaceTrim } from 'spacetrim';
+import { NotFoundError } from '../../../../../src/errors/NotFoundError';
+import type { DnsRecordInstruction } from '../dnsRecords/DnsRecordInstruction';
+import {
+    CLOUDFLARE_DNS_RECORD_PROXIED,
+    CLOUDFLARE_DNS_RECORD_TTL_AUTOMATIC,
+    type CloudflareApiConfiguration,
+    type CloudflareDnsRecord,
+} from './CloudflareApi';
+import type { CloudflareDnsBatchApplication, CloudflareDnsBatchRecordResult } from './CloudflareDnsBatchApplication';
+import { createCloudflareDnsRecord } from './createCloudflareDnsRecord';
+import { findBestMatchingCloudflareZoneForDomain } from './findBestMatchingCloudflareZoneForDomain';
+import { listAllCloudflareDnsRecords } from './listAllCloudflareDnsRecords';
+import { listCloudflareZones } from './listCloudflareZones';
+import { resolveCloudflareDnsRecordApplyAction } from './resolveCloudflareDnsRecordApplyAction';
+import { updateCloudflareDnsRecord } from './updateCloudflareDnsRecord';
+
+/**
+ * Comment written on every DNS record which the Cloudflare DNS wizard creates or overwrites.
+ */
+const CLOUDFLARE_DNS_WIZARD_RECORD_COMMENT = 'Managed by the Promptbook Agents Server DNS wizard';
+
+/**
+ * Writes all DNS records of one manual into the matching Cloudflare zone at once.
+ *
+ * @param options - Cloudflare API token, configured domain, and the records of the DNS manual.
+ * @returns Result of every record.
+ */
+export async function applyCloudflareDnsRecordInstructions(options: {
+    readonly apiToken: string;
+    readonly domain: string;
+    readonly records: ReadonlyArray<DnsRecordInstruction>;
+}): Promise<CloudflareDnsBatchApplication> {
+    const configuration: CloudflareApiConfiguration = { token: options.apiToken };
+    const zones = await listCloudflareZones(configuration);
+    const zone = findBestMatchingCloudflareZoneForDomain(options.domain, zones);
+
+    if (!zone) {
+        throw new NotFoundError(
+            spaceTrim(`
+                No Cloudflare zone available to this API token contains \`${options.domain}\`.
+
+                Available zones: ${zones.map((availableZone) => `\`${availableZone.name}\``).join(', ') || '*(none)*'}
+
+                **Add the domain to Cloudflare** or use an API token with \`Zone.DNS\` access to its zone.
+            `),
+        );
+    }
+
+    const existingZoneRecords = await listAllCloudflareDnsRecords(configuration, zone.id);
+    const results: Array<CloudflareDnsBatchRecordResult> = [];
+
+    for (const record of options.records) {
+        results.push(
+            await applyCloudflareDnsRecordInstruction({
+                configuration,
+                zoneId: zone.id,
+                record,
+                existingZoneRecords,
+            }),
+        );
+    }
+
+    return { zoneName: zone.name, results };
+}
+
+/**
+ * Writes one DNS record of the manual into Cloudflare.
+ *
+ * @param options - Cloudflare access, target zone, and the record to configure.
+ * @returns Result of the record.
+ *
+ * @private function of `applyCloudflareDnsRecordInstructions`
+ */
+async function applyCloudflareDnsRecordInstruction(options: {
+    readonly configuration: CloudflareApiConfiguration;
+    readonly zoneId: string;
+    readonly record: DnsRecordInstruction;
+    readonly existingZoneRecords: ReadonlyArray<CloudflareDnsRecord>;
+}): Promise<CloudflareDnsBatchRecordResult> {
+    const { configuration, zoneId, record, existingZoneRecords } = options;
+    const action = resolveCloudflareDnsRecordApplyAction(record, existingZoneRecords);
+    const writeInput = {
+        zoneId,
+        type: record.type,
+        name: record.name,
+        content: record.value,
+        proxied: CLOUDFLARE_DNS_RECORD_PROXIED,
+        ttl: CLOUDFLARE_DNS_RECORD_TTL_AUTOMATIC,
+        comment: CLOUDFLARE_DNS_WIZARD_RECORD_COMMENT,
+    };
+
+    try {
+        if (action.kind === 'unchanged') {
+            return createCloudflareDnsBatchRecordResult(record, 'unchanged', 'Already configured in Cloudflare.');
+        }
+
+        if (action.kind === 'skip') {
+            return createCloudflareDnsBatchRecordResult(record, 'skipped', action.reason);
+        }
+
+        if (action.kind === 'update') {
+            await updateCloudflareDnsRecord(configuration, { ...writeInput, recordId: action.recordId });
+
+            return createCloudflareDnsBatchRecordResult(record, 'updated', 'Existing Cloudflare record was updated.');
+        }
+
+        await createCloudflareDnsRecord(configuration, writeInput);
+
+        return createCloudflareDnsBatchRecordResult(record, 'created', 'Added to Cloudflare as DNS only.');
+    } catch (error) {
+        return createCloudflareDnsBatchRecordResult(
+            record,
+            'failed',
+            error instanceof Error ? error.message : 'Cloudflare rejected this record.',
+        );
+    }
+}
+
+/**
+ * Creates one browser-safe record result.
+ *
+ * @param record - DNS record shown in the DNS manual.
+ * @param status - What happened with the record.
+ * @param message - Human-readable explanation.
+ * @returns Record result rendered by the wizard.
+ *
+ * @private function of `applyCloudflareDnsRecordInstructions`
+ */
+function createCloudflareDnsBatchRecordResult(
+    record: DnsRecordInstruction,
+    status: CloudflareDnsBatchRecordResult['status'],
+    message: string,
+): CloudflareDnsBatchRecordResult {
+    return {
+        type: record.type,
+        name: record.name,
+        value: record.value,
+        status,
+        message,
+    };
+}

package/apps/agents-server/src/utils/cloudflare/createCloudflareDnsRecord.ts

@@ -0,0 +1,21 @@
+import type { CloudflareApiConfiguration, CloudflareDnsRecordWriteInput } from './CloudflareApi';
+import { createCloudflareDnsRecordRequestBody } from './createCloudflareDnsRecordRequestBody';
+import { requestCloudflare } from './requestCloudflare';
+
+/**
+ * Creates one Cloudflare DNS record.
+ *
+ * @param configuration - Cloudflare API configuration.
+ * @param record - DNS record to create.
+ */
+export async function createCloudflareDnsRecord(
+    configuration: CloudflareApiConfiguration,
+    record: CloudflareDnsRecordWriteInput,
+): Promise<void> {
+    await requestCloudflare({
+        configuration,
+        method: 'POST',
+        pathname: `/zones/${encodeURIComponent(record.zoneId)}/dns_records`,
+        body: createCloudflareDnsRecordRequestBody(record),
+    });
+}

package/apps/agents-server/src/utils/cloudflare/createCloudflareDnsRecordRequestBody.ts

@@ -0,0 +1,86 @@
+import { isProxyableCloudflareDnsRecordType, type CloudflareDnsRecordWriteInput } from './CloudflareApi';
+import { normalizeCloudflareDnsRecordContent } from './normalizeCloudflareDnsRecordContent';
+
+/**
+ * Cloudflare expects the mail exchanger priority of an `MX` record outside of its content.
+ */
+const CLOUDFLARE_MX_RECORD_CONTENT_PATTERN = /^(\d+)\s+(\S+)$/;
+
+/**
+ * Cloudflare expects the flags, tag, and value of a `CAA` record as structured data.
+ */
+const CLOUDFLARE_CAA_RECORD_CONTENT_PATTERN = /^(\d+)\s+(\S+)\s+"?([^"]*)"?$/;
+
+/**
+ * Creates the Cloudflare API request body for one written DNS record.
+ *
+ * Zone-file style values are translated into the structured fields Cloudflare expects, so that the DNS manual can keep
+ * showing one human-readable value per record.
+ *
+ * @param record - DNS record to create or update.
+ * @returns Cloudflare API request body.
+ */
+export function createCloudflareDnsRecordRequestBody(record: CloudflareDnsRecordWriteInput): Record<string, unknown> {
+    const body: Record<string, unknown> = {
+        type: record.type,
+        name: record.name,
+        ttl: record.ttl,
+        comment: record.comment,
+        ...createCloudflareDnsRecordContentPayload(record.type, record.content),
+    };
+
+    if (isProxyableCloudflareDnsRecordType(record.type)) {
+        body.proxied = record.proxied;
+    }
+    if (record.tags && record.tags.length > 0) {
+        body.tags = record.tags;
+    }
+
+    return body;
+}
+
+/**
+ * Translates one zone-file style record value into the Cloudflare content fields.
+ *
+ * @param type - DNS record type.
+ * @param content - Record value as shown in the DNS manual.
+ * @returns Content, priority, and structured data understood by the Cloudflare API.
+ */
+export function createCloudflareDnsRecordContentPayload(
+    type: string,
+    content: string,
+): {
+    readonly content?: string;
+    readonly priority?: number;
+    readonly data?: Record<string, unknown>;
+} {
+    const normalizedType = type.toUpperCase();
+    const normalizedContent = normalizeCloudflareDnsRecordContent(normalizedType, content);
+
+    if (normalizedType === 'MX') {
+        const mailExchangerMatch = CLOUDFLARE_MX_RECORD_CONTENT_PATTERN.exec(normalizedContent);
+
+        if (mailExchangerMatch) {
+            return {
+                content: (mailExchangerMatch[2] || '').replace(/\.$/, ''),
+                priority: Number(mailExchangerMatch[1]),
+            };
+        }
+    }
+
+    if (normalizedType === 'CAA') {
+        const certificateAuthorityMatch = CLOUDFLARE_CAA_RECORD_CONTENT_PATTERN.exec(normalizedContent);
+
+        if (certificateAuthorityMatch) {
+            return {
+                data: {
+                    flags: Number(certificateAuthorityMatch[1]),
+                    tag: certificateAuthorityMatch[2],
+                    value: certificateAuthorityMatch[3],
+                },
+            };
+        }
+    }
+
+    return { content: normalizedContent };
+}

package/apps/agents-server/src/utils/cloudflare/findBestMatchingCloudflareZoneForDomain.ts

@@ -0,0 +1,41 @@
+import { normalizeDomainForMatching } from '../../../../../src/utils/validators/url/normalizeDomainForMatching';
+import type { CloudflareZone } from './CloudflareApi';
+
+/**
+ * Finds the best matching Cloudflare zone for one fully-qualified domain.
+ *
+ * The longest matching zone wins, so `sub.example.com` prefers a dedicated `sub.example.com` zone over `example.com`.
+ *
+ * @param domain - Fully-qualified domain.
+ * @param zones - Accessible Cloudflare zones.
+ * @returns Best matching zone or `null`.
+ */
+export function findBestMatchingCloudflareZoneForDomain(
+    domain: string,
+    zones: ReadonlyArray<CloudflareZone>,
+): CloudflareZone | null {
+    const normalizedDomain = normalizeDomainForMatching(domain);
+    if (!normalizedDomain) {
+        return null;
+    }
+
+    let bestMatch: CloudflareZone | null = null;
+    let bestMatchZoneNameLength = 0;
+
+    for (const zone of zones) {
+        const normalizedZoneName = normalizeDomainForMatching(zone.name);
+        if (!normalizedZoneName) {
+            continue;
+        }
+        if (normalizedDomain !== normalizedZoneName && !normalizedDomain.endsWith(`.${normalizedZoneName}`)) {
+            continue;
+        }
+
+        if (!bestMatch || normalizedZoneName.length > bestMatchZoneNameLength) {
+            bestMatch = zone;
+            bestMatchZoneNameLength = normalizedZoneName.length;
+        }
+    }
+
+    return bestMatch;
+}

package/apps/agents-server/{scripts/createCloudflareDnsRecordSyncPlan → src/utils/cloudflare}/listAllCloudflareDnsRecords.ts

@@ -1,4 +1,4 @@
-import type { CloudflareApiConfiguration, CloudflareDnsRecord } from './CloudflareDnsRecordSyncPlan';
+import type { CloudflareApiConfiguration, CloudflareDnsRecord } from './CloudflareApi';
 import { requestCloudflare } from './requestCloudflare';
 
 /**
@@ -12,8 +12,6 @@ const CLOUDFLARE_DNS_RECORDS_PAGE_LIMIT = 100;
  * @param configuration - Cloudflare API configuration.
  * @param zoneId - Zone id containing the record.
  * @returns DNS records in the zone.
- *
- * @private function of `createCloudflareDnsRecordSyncPlan`
  */
 export async function listAllCloudflareDnsRecords(
     configuration: CloudflareApiConfiguration,

package/apps/agents-server/{scripts/createCloudflareDnsRecordSyncPlan → src/utils/cloudflare}/listCloudflareZones.ts

@@ -1,4 +1,4 @@
-import type { CloudflareApiConfiguration, CloudflareZone } from './CloudflareDnsRecordSyncPlan';
+import type { CloudflareApiConfiguration, CloudflareZone } from './CloudflareApi';
 import { requestCloudflare } from './requestCloudflare';
 
 /**
@@ -11,8 +11,6 @@ const CLOUDFLARE_ZONES_PAGE_LIMIT = 100;
  *
  * @param configuration - Cloudflare API configuration.
  * @returns Accessible Cloudflare zones.
- *
- * @private function of `syncCloudflareDnsRecords`
  */
 export async function listCloudflareZones(configuration: CloudflareApiConfiguration): Promise<Array<CloudflareZone>> {
     const zones: Array<CloudflareZone> = [];

package/apps/agents-server/{scripts/createCloudflareDnsRecordSyncPlan → src/utils/cloudflare}/normalizeCloudflareDnsRecordContent.ts

@@ -4,8 +4,6 @@
  * @param type - DNS record type.
  * @param content - Raw record content.
  * @returns Normalized content.
- *
- * @private function of `sync-vercel-domains`
  */
 export function normalizeCloudflareDnsRecordContent(type: string, content: string): string {
     const normalizedContent = content.trim();

package/apps/agents-server/{scripts/createCloudflareDnsRecordSyncPlan → src/utils/cloudflare}/requestCloudflare.ts

@@ -1,6 +1,6 @@
 import { spaceTrim } from 'spacetrim';
-import { DatabaseError } from '../../../../src/errors/DatabaseError';
-import type { CloudflareApiConfiguration } from './CloudflareDnsRecordSyncPlan';
+import { PromptbookFetchError } from '../../../../../src/errors/PromptbookFetchError';
+import type { CloudflareApiConfiguration } from './CloudflareApi';
 
 /**
  * Default Cloudflare API base URL.
@@ -43,8 +43,6 @@ type CloudflareApiEnvelope<TResult> = {
  *
  * @param options - HTTP request options.
  * @returns Parsed Cloudflare response envelope.
- *
- * @private function of `syncCloudflareDnsRecords`
  */
 export async function requestCloudflare<TResult = Record<string, unknown>>(options: {
     readonly configuration: CloudflareApiConfiguration;
@@ -71,7 +69,7 @@ export async function requestCloudflare<TResult = Record<string, unknown>>(optio
     const responseText = await response.text();
 
     if (!response.ok) {
-        throw new DatabaseError(
+        throw new PromptbookFetchError(
             spaceTrim(`
                 Cloudflare API request failed.
 
@@ -87,7 +85,7 @@ export async function requestCloudflare<TResult = Record<string, unknown>>(optio
         responseText ? JSON.parse(responseText) : { success: true, result: {} }
     ) as CloudflareApiEnvelope<TResult>;
     if (!parsedResponse.success) {
-        throw new DatabaseError(
+        throw new PromptbookFetchError(
             spaceTrim(`
                 Cloudflare API request returned an unsuccessful envelope.
 

package/apps/agents-server/src/utils/cloudflare/resolveCloudflareDnsRecordApplyAction.ts

@@ -0,0 +1,157 @@
+import { spaceTrim } from 'spacetrim';
+import type { DnsRecordInstruction } from '../dnsRecords/DnsRecordInstruction';
+import { normalizeCloudflareDnsRecordName, type CloudflareDnsRecord } from './CloudflareApi';
+import { createCloudflareDnsRecordContentPayload } from './createCloudflareDnsRecordRequestBody';
+import { normalizeCloudflareDnsRecordContent } from './normalizeCloudflareDnsRecordContent';
+
+/**
+ * DNS record types which hold exactly one value per hostname, so an existing record may be overwritten safely.
+ */
+const SINGLE_VALUE_DNS_RECORD_TYPES: ReadonlySet<string> = new Set(['A', 'AAAA', 'CNAME']);
+
+/**
+ * Version tag which starts a policy `TXT` record, for example `v=spf1 mx -all` or `v=DMARC1; p=quarantine`.
+ */
+const DNS_TEXT_RECORD_POLICY_TAG_PATTERN = /^v=([a-z0-9]+)/i;
+
+/**
+ * What the Cloudflare DNS wizard does with one DNS record of the manual.
+ */
+export type CloudflareDnsRecordApplyAction =
+    | {
+          /**
+           * The record is missing in Cloudflare and will be created.
+           */
+          readonly kind: 'create';
+      }
+    | {
+          /**
+           * An existing Cloudflare record holds the same role and will be overwritten.
+           */
+          readonly kind: 'update';
+
+          /**
+           * Cloudflare id of the overwritten record.
+           */
+          readonly recordId: string;
+      }
+    | {
+          /**
+           * Cloudflare already contains exactly this record.
+           */
+          readonly kind: 'unchanged';
+      }
+    | {
+          /**
+           * The record cannot be written without a human decision.
+           */
+          readonly kind: 'skip';
+
+          /**
+           * Explanation shown in the wizard.
+           */
+          readonly reason: string;
+      };
+
+/**
+ * Resolves what has to be done in Cloudflare so that one DNS record of the manual is configured.
+ *
+ * Conflicting records are never deleted, because one Cloudflare zone can also contain records of unrelated services.
+ *
+ * @param record - DNS record shown in the DNS manual.
+ * @param existingZoneRecords - Records which currently exist in the matching Cloudflare zone.
+ * @returns Action which configures the record.
+ */
+export function resolveCloudflareDnsRecordApplyAction(
+    record: DnsRecordInstruction,
+    existingZoneRecords: ReadonlyArray<CloudflareDnsRecord>,
+): CloudflareDnsRecordApplyAction {
+    const matchingRecords = existingZoneRecords.filter(
+        (existingRecord) =>
+            existingRecord.type.toUpperCase() === record.type.toUpperCase() &&
+            normalizeCloudflareDnsRecordName(existingRecord.name) === normalizeCloudflareDnsRecordName(record.name),
+    );
+
+    if (matchingRecords.some((existingRecord) => isCloudflareDnsRecordAlreadyConfigured(existingRecord, record))) {
+        return { kind: 'unchanged' };
+    }
+
+    if (matchingRecords.length === 0) {
+        return { kind: 'create' };
+    }
+
+    const overwritableRecord = matchingRecords.length === 1 ? matchingRecords[0] : undefined;
+
+    if (overwritableRecord && isOverwritableCloudflareDnsRecord(overwritableRecord, record)) {
+        return { kind: 'update', recordId: overwritableRecord.id };
+    }
+
+    return {
+        kind: 'skip',
+        reason: spaceTrim(`
+            Cloudflare already has a different \`${record.type}\` record for \`${record.name}\`.
+            **Remove the conflicting record in Cloudflare** and import again.
+        `),
+    };
+}
+
+/**
+ * Checks whether one existing Cloudflare record already holds the value from the DNS manual.
+ *
+ * @param existingRecord - Record which currently exists in Cloudflare.
+ * @param record - DNS record shown in the DNS manual.
+ * @returns `true` when nothing has to be written.
+ */
+function isCloudflareDnsRecordAlreadyConfigured(
+    existingRecord: CloudflareDnsRecord,
+    record: DnsRecordInstruction,
+): boolean {
+    const contentPayload = createCloudflareDnsRecordContentPayload(record.type, record.value);
+
+    if (contentPayload.priority !== undefined && (existingRecord.priority ?? null) !== contentPayload.priority) {
+        return false;
+    }
+
+    return (
+        normalizeCloudflareDnsRecordContent(record.type, existingRecord.content) ===
+        normalizeCloudflareDnsRecordContent(record.type, contentPayload.content ?? record.value)
+    );
+}
+
+/**
+ * Checks whether one existing Cloudflare record holds the same role as the record from the DNS manual.
+ *
+ * @param existingRecord - Record which currently exists in Cloudflare.
+ * @param record - DNS record shown in the DNS manual.
+ * @returns `true` when the existing record may be overwritten.
+ */
+function isOverwritableCloudflareDnsRecord(existingRecord: CloudflareDnsRecord, record: DnsRecordInstruction): boolean {
+    const normalizedType = record.type.toUpperCase();
+
+    if (SINGLE_VALUE_DNS_RECORD_TYPES.has(normalizedType)) {
+        return true;
+    }
+
+    if (normalizedType !== 'TXT') {
+        return false;
+    }
+
+    // Note: One hostname can hold many unrelated `TXT` records, but only one record of each policy, for example
+    //       only one SPF policy is valid for a domain.
+    const existingPolicyTag = extractDnsTextRecordPolicyTag(existingRecord.content);
+
+    return existingPolicyTag !== null && existingPolicyTag === extractDnsTextRecordPolicyTag(record.value);
+}
+
+/**
+ * Extracts the policy version tag of one `TXT` record.
+ *
+ * @param content - Raw `TXT` record content.
+ * @returns Lowercased policy tag like `spf1` or `null` when the record is not a policy.
+ */
+function extractDnsTextRecordPolicyTag(content: string): string | null {
+    const unquotedContent = content.trim().replace(/^"(.*)"$/s, '$1');
+    const policyTagMatch = DNS_TEXT_RECORD_POLICY_TAG_PATTERN.exec(unquotedContent);
+
+    return policyTagMatch ? (policyTagMatch[1] || '').toLowerCase() : null;
+}

package/apps/agents-server/src/utils/cloudflare/updateCloudflareDnsRecord.ts

@@ -0,0 +1,26 @@
+import type { CloudflareApiConfiguration, CloudflareDnsRecordWriteInput } from './CloudflareApi';
+import { createCloudflareDnsRecordRequestBody } from './createCloudflareDnsRecordRequestBody';
+import { requestCloudflare } from './requestCloudflare';
+
+/**
+ * Updates one existing Cloudflare DNS record.
+ *
+ * @param configuration - Cloudflare API configuration.
+ * @param record - DNS record to write over the existing Cloudflare record.
+ */
+export async function updateCloudflareDnsRecord(
+    configuration: CloudflareApiConfiguration,
+    record: CloudflareDnsRecordWriteInput & {
+        /**
+         * Cloudflare id of the record that is overwritten.
+         */
+        readonly recordId: string;
+    },
+): Promise<void> {
+    await requestCloudflare({
+        configuration,
+        method: 'PATCH',
+        pathname: `/zones/${encodeURIComponent(record.zoneId)}/dns_records/${encodeURIComponent(record.recordId)}`,
+        body: createCloudflareDnsRecordRequestBody(record),
+    });
+}