@promptbook/cli 0.113.0-9 → 0.114.0-1

package/apps/agents-server/src/components/CloudflareDnsWizard/CloudflareDnsWizard.tsx

@@ -0,0 +1,88 @@
+'use client';
+
+import { useState } from 'react';
+import type { DnsRecordInstruction, DnsRecordSelection } from '../../utils/dnsRecords/DnsRecordInstruction';
+import { resolveDnsRecordBatchPlan } from '../../utils/dnsRecords/resolveDnsRecordBatchPlan';
+import { CloudflareDnsApiTokenImportStep } from './CloudflareDnsApiTokenImportStep';
+import { CloudflareDnsCheckStep } from './CloudflareDnsCheckStep';
+import { CloudflareDnsManualStep } from './CloudflareDnsManualStep';
+import { CloudflareDnsWizardStepNavigation } from './CloudflareDnsWizardStepNavigation';
+import { CLOUDFLARE_DNS_WIZARD_STEPS, type CloudflareDnsWizardStep } from './CloudflareDnsWizardSteps';
+import { CloudflareDnsZoneFileImportStep } from './CloudflareDnsZoneFileImportStep';
+
+/**
+ * Guided Cloudflare instructions displayed alongside the provider-neutral DNS record table.
+ *
+ * The record table remains the single source of truth for the values to configure. This wizard adds the two batch
+ * ways of configuring all of them at once - an API token import and a zone file import - and keeps the manual steps
+ * as a fallback.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export function CloudflareDnsWizard({
+    domain,
+    recordSelection,
+    records,
+}: {
+    /**
+     * Hostname whose DNS records are being configured.
+     */
+    readonly domain: string;
+
+    /**
+     * Whether all listed records or one listed alternative must be configured.
+     */
+    readonly recordSelection: DnsRecordSelection;
+
+    /**
+     * The canonical DNS records displayed by the parent instruction panel.
+     */
+    readonly records: ReadonlyArray<DnsRecordInstruction>;
+}) {
+    const batchPlan = resolveDnsRecordBatchPlan({ records, recordSelection });
+    const isBatchImportAvailable = batchPlan.applicableRecords.length > 0;
+    const availableSteps = CLOUDFLARE_DNS_WIZARD_STEPS.filter((step) => isBatchImportAvailable || !step.isBatchStep);
+    const [currentStep, setCurrentStep] = useState<CloudflareDnsWizardStep>(
+        isBatchImportAvailable ? 'import-with-api-token' : 'add-manually',
+    );
+
+    return (
+        <section
+            aria-label="Cloudflare DNS setup"
+            className="space-y-4 rounded-lg border border-amber-200 bg-white/70 p-4"
+        >
+            <div className="space-y-1">
+                <h3 className="font-semibold">Cloudflare setup wizard</h3>
+                <p className="text-xs text-amber-800">
+                    {isBatchImportAvailable
+                        ? 'Add all records from this manual to Cloudflare at once, or add them one by one.'
+                        : 'Follow the steps below to add the records from this manual in Cloudflare.'}
+                </p>
+            </div>
+
+            <CloudflareDnsWizardStepNavigation
+                currentStep={currentStep}
+                onStepChange={setCurrentStep}
+                steps={availableSteps}
+            />
+
+            {currentStep === 'import-with-api-token' ? (
+                <CloudflareDnsApiTokenImportStep
+                    batchPlan={batchPlan}
+                    domain={domain}
+                    recordSelection={recordSelection}
+                />
+            ) : null}
+
+            {currentStep === 'import-zone-file' ? (
+                <CloudflareDnsZoneFileImportStep batchPlan={batchPlan} domain={domain} />
+            ) : null}
+
+            {currentStep === 'add-manually' ? (
+                <CloudflareDnsManualStep domain={domain} recordSelection={recordSelection} records={records} />
+            ) : null}
+
+            {currentStep === 'check-dns' ? <CloudflareDnsCheckStep recordSelection={recordSelection} /> : null}
+        </section>
+    );
+}

package/apps/agents-server/src/components/CloudflareDnsWizard/CloudflareDnsWizardStepNavigation.tsx

@@ -0,0 +1,53 @@
+'use client';
+
+import type { CLOUDFLARE_DNS_WIZARD_STEPS, CloudflareDnsWizardStep } from './CloudflareDnsWizardSteps';
+
+/**
+ * Renders the selectable progression for the Cloudflare DNS setup wizard.
+ *
+ * @private used by the Cloudflare DNS setup wizard
+ */
+export function CloudflareDnsWizardStepNavigation({
+    currentStep,
+    onStepChange,
+    steps,
+}: {
+    /**
+     * Step currently visible to the administrator.
+     */
+    readonly currentStep: CloudflareDnsWizardStep;
+
+    /**
+     * Updates the currently visible wizard step.
+     */
+    readonly onStepChange: (step: CloudflareDnsWizardStep) => void;
+
+    /**
+     * Steps available for the shown records.
+     */
+    readonly steps: typeof CLOUDFLARE_DNS_WIZARD_STEPS;
+}) {
+    return (
+        <div className="flex flex-wrap gap-2" aria-label="Cloudflare setup steps">
+            {steps.map((step) => {
+                const isCurrentStep = currentStep === step.id;
+
+                return (
+                    <button
+                        key={step.id}
+                        type="button"
+                        aria-current={isCurrentStep ? 'step' : undefined}
+                        onClick={() => onStepChange(step.id)}
+                        className={`rounded-md px-3 py-1.5 text-xs font-semibold transition ${
+                            isCurrentStep
+                                ? 'bg-amber-700 text-white shadow-sm'
+                                : 'border border-amber-200 bg-white text-amber-800 hover:bg-amber-100'
+                        }`}
+                    >
+                        {step.label}
+                    </button>
+                );
+            })}
+        </div>
+    );
+}

package/apps/agents-server/src/components/CloudflareDnsWizard/CloudflareDnsWizardSteps.ts

@@ -0,0 +1,36 @@
+/**
+ * Stable identifiers for the Cloudflare DNS setup wizard steps.
+ *
+ * @private used by the Cloudflare DNS setup wizard
+ */
+export type CloudflareDnsWizardStep = 'import-with-api-token' | 'import-zone-file' | 'add-manually' | 'check-dns';
+
+/**
+ * Labels and order of the Cloudflare DNS setup wizard steps.
+ *
+ * The two batch steps are alternatives which configure all records at once, the manual step stays available as a
+ * fallback for records which cannot be batched.
+ *
+ * @private used by the Cloudflare DNS setup wizard
+ */
+export const CLOUDFLARE_DNS_WIZARD_STEPS: ReadonlyArray<{
+    /**
+     * Stable step identifier.
+     */
+    readonly id: CloudflareDnsWizardStep;
+
+    /**
+     * Label of the step button.
+     */
+    readonly label: string;
+
+    /**
+     * Whether the step configures all records at once.
+     */
+    readonly isBatchStep: boolean;
+}> = [
+    { id: 'import-with-api-token', label: 'Import with API token', isBatchStep: true },
+    { id: 'import-zone-file', label: 'Import zone file', isBatchStep: true },
+    { id: 'add-manually', label: 'Add manually', isBatchStep: false },
+    { id: 'check-dns', label: 'Check DNS', isBatchStep: false },
+];

package/apps/agents-server/src/components/CloudflareDnsWizard/CloudflareDnsZoneFileImportStep.tsx

@@ -0,0 +1,109 @@
+'use client';
+
+import { useState } from 'react';
+import { createDnsZoneFileExport } from '../../utils/dnsRecords/createDnsZoneFileExport';
+import type { DnsRecordBatchPlan } from '../../utils/dnsRecords/resolveDnsRecordBatchPlan';
+import { CloudflareDnsExcludedRecordsNote } from './CloudflareDnsExcludedRecordsNote';
+
+/**
+ * Cloudflare help page for importing a zone file.
+ *
+ * @private used by the Cloudflare DNS setup wizard
+ */
+const CLOUDFLARE_ZONE_FILE_IMPORT_GUIDE_URL =
+    'https://developers.cloudflare.com/dns/manage-dns-records/how-to/import-and-export/';
+
+/**
+ * Exports all records of the DNS manual as one zone file which Cloudflare imports at once.
+ *
+ * @private used by the Cloudflare DNS setup wizard
+ */
+export function CloudflareDnsZoneFileImportStep({
+    batchPlan,
+    domain,
+}: {
+    /**
+     * Records which can be exported at once together with the excluded ones.
+     */
+    readonly batchPlan: DnsRecordBatchPlan;
+
+    /**
+     * Hostname whose DNS records are being configured.
+     */
+    readonly domain: string;
+}) {
+    const [isCopied, setIsCopied] = useState(false);
+    const zoneFile = createDnsZoneFileExport({ domain, records: batchPlan.applicableRecords });
+
+    /**
+     * Copies the generated zone file into the clipboard.
+     */
+    const handleCopyZoneFile = async () => {
+        try {
+            await navigator.clipboard.writeText(zoneFile);
+            setIsCopied(true);
+        } catch (error) {
+            console.error('Failed to copy the zone file:', error);
+        }
+    };
+
+    /**
+     * Downloads the generated zone file so that it can be uploaded to Cloudflare.
+     */
+    const handleDownloadZoneFile = () => {
+        const zoneFileUrl = URL.createObjectURL(new Blob([zoneFile], { type: 'text/plain' }));
+        const downloadLink = document.createElement('a');
+
+        downloadLink.href = zoneFileUrl;
+        downloadLink.download = `${domain}-dns-records.txt`;
+        downloadLink.click();
+        URL.revokeObjectURL(zoneFileUrl);
+    };
+
+    return (
+        <div className="space-y-3">
+            <p className="font-medium">Import all records as a zone file</p>
+            <ol className="list-decimal space-y-1 pl-5 text-amber-900">
+                <li>Download or copy the zone file below.</li>
+                <li>
+                    In Cloudflare open DNS, then Records, then <span className="font-semibold">Import and Export</span>.
+                </li>
+                <li>
+                    Select <span className="font-semibold">Import DNS records</span> and upload the file.
+                </li>
+                <li>Keep proxying turned off so that this page can verify the hostname.</li>
+            </ol>
+
+            <div className="flex flex-wrap gap-2">
+                <button
+                    type="button"
+                    onClick={() => void handleCopyZoneFile()}
+                    className="rounded-md bg-amber-700 px-3 py-1.5 text-xs font-semibold text-white shadow-sm transition hover:bg-amber-800"
+                >
+                    {isCopied ? 'Copied' : 'Copy zone file'}
+                </button>
+                <button
+                    type="button"
+                    onClick={handleDownloadZoneFile}
+                    className="rounded-md border border-amber-200 bg-white px-3 py-1.5 text-xs font-semibold text-amber-800 transition hover:bg-amber-100"
+                >
+                    Download zone file
+                </button>
+                <a
+                    href={CLOUDFLARE_ZONE_FILE_IMPORT_GUIDE_URL}
+                    target="_blank"
+                    rel="noreferrer"
+                    className="inline-flex items-center font-semibold text-amber-700 underline decoration-amber-400 underline-offset-2 hover:text-amber-900"
+                >
+                    Cloudflare import guide
+                </a>
+            </div>
+
+            <pre className="overflow-auto rounded-md border border-amber-200 bg-white p-3 font-mono text-xs text-slate-800">
+                {zoneFile}
+            </pre>
+
+            <CloudflareDnsExcludedRecordsNote excludedRecords={batchPlan.excludedRecords} />
+        </div>
+    );
+}

package/apps/agents-server/src/components/CloudflareDnsWizard/useCloudflareDnsRecordImport.ts

@@ -0,0 +1,71 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import type { CloudflareDnsBatchApplication } from '../../utils/cloudflare/CloudflareDnsBatchApplication';
+import type { DnsRecordInstruction, DnsRecordSelection } from '../../utils/dnsRecords/DnsRecordInstruction';
+
+/**
+ * Endpoint which writes the records of one DNS manual into Cloudflare.
+ *
+ * @private used by the Cloudflare DNS setup wizard
+ */
+const CLOUDFLARE_DNS_IMPORT_ENDPOINT = '/api/admin/dns-records/cloudflare';
+
+/**
+ * Imports all records of one DNS manual into Cloudflare with one API token.
+ *
+ * The token is only passed through to the server for this one import and is never persisted by the browser.
+ *
+ * @param options - Domain and records of the DNS manual.
+ * @returns Import state and the import handler.
+ *
+ * @private used by the Cloudflare DNS setup wizard
+ */
+export function useCloudflareDnsRecordImport(options: {
+    readonly domain: string;
+    readonly recordSelection: DnsRecordSelection;
+    readonly records: ReadonlyArray<DnsRecordInstruction>;
+}): {
+    readonly isImporting: boolean;
+    readonly application: CloudflareDnsBatchApplication | null;
+    readonly errorMessage: string | null;
+    readonly importRecords: (apiToken: string) => Promise<void>;
+} {
+    const [isImporting, setIsImporting] = useState(false);
+    const [application, setApplication] = useState<CloudflareDnsBatchApplication | null>(null);
+    const [errorMessage, setErrorMessage] = useState<string | null>(null);
+    const { domain, recordSelection, records } = options;
+
+    const importRecords = useCallback(
+        async (apiToken: string) => {
+            setIsImporting(true);
+            setErrorMessage(null);
+            setApplication(null);
+
+            try {
+                const response = await fetch(CLOUDFLARE_DNS_IMPORT_ENDPOINT, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ apiToken, domain, recordSelection, records }),
+                });
+                const payload = (await response.json().catch(() => null)) as
+                    | (CloudflareDnsBatchApplication & { readonly error?: string })
+                    | null;
+
+                if (!response.ok || !payload || payload.error) {
+                    setErrorMessage(payload?.error || 'Failed to import the DNS records into Cloudflare.');
+                    return;
+                }
+
+                setApplication(payload);
+            } catch (error) {
+                setErrorMessage(error instanceof Error ? error.message : 'Failed to reach Cloudflare.');
+            } finally {
+                setIsImporting(false);
+            }
+        },
+        [domain, recordSelection, records],
+    );
+
+    return { isImporting, application, errorMessage, importRecords };
+}