@promptbook/cli 0.113.0-9 → 0.114.0-0

package/apps/agents-server/src/app/agents/[agentName]/projects/[projectName]/vscode/route.ts

@@ -0,0 +1,76 @@
+import { NextResponse } from 'next/server';
+import { NotAllowed } from '../../../../../../../../../src/errors/NotAllowed';
+import { NotFoundError } from '../../../../../../../../../src/errors/NotFoundError';
+import { createAgentForbiddenResponse } from '@/src/utils/agentAccess';
+import {
+    AGENT_PROJECT_DETAILS_FORBIDDEN_MESSAGE,
+    resolveAgentProjectsAccess,
+} from '@/src/utils/agentProjects/agentProjectAccess';
+import {
+    resolveAgentProjectCodeServerThemeMode,
+    startAgentProjectCodeServerSession,
+} from '@/src/utils/agentProjects/agentProjectCodeServerRegistry';
+import { resolveAgentRouteTarget } from '@/src/utils/agentRouting/resolveAgentRouteTarget';
+import { isUserGlobalAdmin } from '@/src/utils/isUserGlobalAdmin';
+
+/**
+ * Forces request-time authorization and code-server session resolution.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * code-server sessions require Node.js process APIs.
+ */
+export const runtime = 'nodejs';
+
+/**
+ * Opens one agent project in browser VS Code.
+ */
+export async function GET(
+    request: Request,
+    { params }: { params: Promise<{ agentName: string; projectName: string }> },
+): Promise<Response> {
+    const { agentName: rawAgentName, projectName: rawProjectName } = await params;
+    const routeTarget = await resolveAgentRouteTarget(decodeURIComponent(rawAgentName));
+
+    if (routeTarget === null || routeTarget.kind !== 'local') {
+        return NextResponse.json({ error: 'Agent not found.' }, { status: 404 });
+    }
+
+    const access = await resolveAgentProjectsAccess(routeTarget.canonicalAgentId, { request });
+    if (!access.isProjectOverviewVisible) {
+        return createAgentForbiddenResponse();
+    }
+
+    if (!access.isProjectDetailsVisible || !access.currentUser) {
+        return createAgentForbiddenResponse(AGENT_PROJECT_DETAILS_FORBIDDEN_MESSAGE);
+    }
+
+    const isCurrentUserGlobalAdmin = await isUserGlobalAdmin();
+    if (!isCurrentUserGlobalAdmin) {
+        return createAgentForbiddenResponse('Only super admins can open project VS Code.');
+    }
+
+    try {
+        const session = await startAgentProjectCodeServerSession({
+            request,
+            agentPermanentId: routeTarget.canonicalAgentId,
+            projectName: decodeURIComponent(rawProjectName),
+            currentUser: access.currentUser,
+            themeMode: await resolveAgentProjectCodeServerThemeMode(access.currentUser, request),
+            isSuperAdmin: isCurrentUserGlobalAdmin,
+        });
+
+        return NextResponse.redirect(session.browserUrl);
+    } catch (error) {
+        if (error instanceof NotAllowed) {
+            return NextResponse.json({ error: error.message }, { status: 500 });
+        }
+
+        if (error instanceof NotFoundError) {
+            return NextResponse.json({ error: error.message }, { status: 404 });
+        }
+
+        throw error;
+    }
+}

package/apps/agents-server/src/app/agents/[agentName]/projects/page.tsx

@@ -0,0 +1,91 @@
+import { FolderKanbanIcon } from 'lucide-react';
+import Link from 'next/link';
+import { AgentProjectsBoard } from '@/src/components/AgentProjects/AgentProjectsBoard';
+import { ForbiddenPage } from '@/src/components/ForbiddenPage/ForbiddenPage';
+import { resolveAgentProjectsAccess } from '@/src/utils/agentProjects/agentProjectAccess';
+import { ADMIN_AGENT_PROJECTS_DASHBOARD_HREF } from '@/src/utils/agentProjects/agentProjectHrefs';
+import { listAgentProjects } from '@/src/utils/agentProjects/listAgentProjects';
+import { formatResourceBytes } from '@/src/utils/resourceMonitor/formatResourceMonitorValue';
+import { loadLocalAgentSourceSnapshot } from '@/src/utils/localChatRunner/ensureLocalAgentFolder';
+import { enforceCanonicalLocalAgentId, getAgentName } from '../_utils';
+
+/**
+ * Forces fresh project listings from disk on every request.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Builds canonical projects-dashboard path for one local agent id.
+ */
+function buildCanonicalAgentProjectsPath(canonicalAgentId: string): string {
+    return `/agents/${encodeURIComponent(canonicalAgentId)}/projects`;
+}
+
+/**
+ * Renders the Projects dashboard of one agent.
+ *
+ * The dashboard lists all projects the agent keeps in its local `projects/` folder —
+ * isolated folders the agent fully controls and can reference in the chat.
+ */
+export default async function AgentProjectsPage({ params }: { params: Promise<{ agentName: string }> }) {
+    const agentName = await getAgentName(params);
+    const canonicalAgentId = await enforceCanonicalLocalAgentId(agentName, buildCanonicalAgentProjectsPath);
+
+    const access = await resolveAgentProjectsAccess(canonicalAgentId);
+    if (!access.isProjectOverviewVisible) {
+        return <ForbiddenPage />;
+    }
+
+    const [projects, agentSnapshot] = await Promise.all([
+        listAgentProjects(canonicalAgentId),
+        loadLocalAgentSourceSnapshot(canonicalAgentId).catch(() => null),
+    ]);
+    const isAdmin = access.currentUser?.isAdmin === true;
+    const totalSizeBytes = projects.reduce((accumulatedSizeBytes, project) => accumulatedSizeBytes + project.sizeBytes, 0);
+
+    return (
+        <div className="container mx-auto space-y-6 px-4 py-8">
+            <div className="mt-20 flex flex-col gap-3 md:flex-row md:items-end md:justify-between">
+                <div>
+                    <p className="text-xs font-semibold uppercase tracking-[0.22em] text-gray-400">
+                        {agentSnapshot?.agentName || canonicalAgentId}
+                    </p>
+                    <h1 className="mt-1 flex items-center gap-2 text-3xl font-light text-gray-900">
+                        <FolderKanbanIcon className="h-7 w-7 text-gray-400" aria-hidden />
+                        Projects
+                    </h1>
+                    {access.isProjectDetailsVisible ? (
+                        <p className="mt-1 max-w-3xl text-sm text-gray-500">
+                            Every project is one folder the agent fully controls — it can create and edit files there,
+                            run scripts, keep a git repository, and link the files into the chat.
+                        </p>
+                    ) : (
+                        <p className="mt-1 max-w-3xl text-sm text-gray-500">
+                            Projects shared by this agent.
+                        </p>
+                    )}
+                </div>
+                {access.isProjectDetailsVisible && (
+                    <div className="flex flex-wrap items-center gap-2 text-xs text-gray-500">
+                        <span className="rounded-md border border-gray-200 bg-white px-3 py-1.5">
+                            {projects.length} {projects.length === 1 ? 'project' : 'projects'},{' '}
+                            <span className="font-mono text-gray-700">{formatResourceBytes(totalSizeBytes)}</span>
+                        </span>
+                        {isAdmin && (
+                            <Link
+                                href={ADMIN_AGENT_PROJECTS_DASHBOARD_HREF}
+                                className="rounded-md border border-blue-200 bg-blue-50 px-3 py-1.5 font-semibold text-blue-700 hover:bg-blue-100"
+                            >
+                                All agents&apos; projects
+                            </Link>
+                        )}
+                    </div>
+                )}
+            </div>
+            <AgentProjectsBoard
+                agentPermanentId={canonicalAgentId}
+                projects={projects}
+            />
+        </div>
+    );
+}

package/apps/agents-server/src/app/api/admin/chat-tasks/[taskId]/cancel/route.ts

@@ -1,19 +1,19 @@
-import { after, NextResponse } from 'next/server';
+import { NextResponse } from 'next/server';
 import { getCurrentUser } from '@/src/utils/getCurrentUser';
-import { cancelScheduledUserChatTimeout, getUserChatTimeoutById } from '@/src/utils/userChatTimeout';
-import {
-    getUserChatJobById,
-    persistUserChatJobTerminalState,
-    requestUserChatJobCancellation,
-    triggerUserChatJobWorker,
-} from '@/src/utils/userChat';
+import { cancelAdminChatTaskById } from '@/src/utils/cancelAdminChatTaskById';
+import { readRequiredAdminReason } from '@/src/utils/readRequiredAdminReason';
 import { isUserAdmin } from '@/src/utils/isUserAdmin';
+import { isUserGlobalAdmin } from '@/src/utils/isUserGlobalAdmin';
 
 /**
  * Requests admin cancellation for one queued or running durable chat task.
  */
 export async function POST(request: Request, { params }: { params: Promise<{ taskId: string }> }) {
-    if (!(await isUserAdmin())) {
+    const requestUrl = new URL(request.url);
+    const serverDomain = requestUrl.searchParams.get('serverDomain')?.trim() || null;
+    const isAuthorized = serverDomain ? await isUserGlobalAdmin() : await isUserAdmin();
+
+    if (!isAuthorized) {
         return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
     }
 
@@ -27,65 +27,23 @@ export async function POST(request: Request, { params }: { params: Promise<{ tas
 
     try {
         const actor = (await getCurrentUser())?.username || 'admin';
-        const job = await getUserChatJobById(taskId);
-
-        if (job) {
-            if (job.status === 'COMPLETED' || job.status === 'FAILED' || job.status === 'CANCELLED') {
-                return NextResponse.json({ error: 'Task is already finished.' }, { status: 409 });
-            }
-
-            console.info('[admin-chat-task] cancel', {
-                actor,
-                taskId,
-                reason,
-                kind: 'CHAT_COMPLETION',
-                status: job.status,
-            });
-
-            const cancellationRequestedJob = await requestUserChatJobCancellation(taskId);
-            if (!cancellationRequestedJob) {
-                return NextResponse.json({ error: 'Task could not be cancelled.' }, { status: 409 });
-            }
-
-            if (job.status === 'QUEUED') {
-                await persistUserChatJobTerminalState({
-                    job: cancellationRequestedJob,
-                    status: 'CANCELLED',
-                    failureReason: 'Chat generation was cancelled by an administrator before it started.',
-                });
-            } else {
-                after(() =>
-                    triggerUserChatJobWorker({
-                        origin: new URL(request.url).origin,
-                        preferredJobId: taskId,
-                    }).catch((error) =>
-                        console.error('[admin-chat-task] failed to wake worker after cancellation request', error),
-                    ),
-                );
-            }
-
-            return NextResponse.json({ ok: true });
-        }
+        const outcome = await cancelAdminChatTaskById({
+            taskId,
+            actor,
+            reason,
+            requestOrigin: requestUrl.origin,
+            serverDomain,
+        });
 
-        const timeout = await getUserChatTimeoutById(taskId);
-        if (!timeout) {
+        if (outcome === 'NOT_FOUND') {
             return NextResponse.json({ error: 'Task not found.' }, { status: 404 });
         }
 
-        if (timeout.status === 'COMPLETED' || timeout.status === 'FAILED' || timeout.status === 'CANCELLED') {
+        if (outcome === 'ALREADY_FINISHED') {
             return NextResponse.json({ error: 'Task is already finished.' }, { status: 409 });
         }
 
-        console.info('[admin-chat-task] cancel', {
-            actor,
-            taskId,
-            reason,
-            kind: 'CHAT_TIMEOUT',
-            status: timeout.status,
-        });
-
-        const cancelledTimeout = await cancelScheduledUserChatTimeout(taskId);
-        if (!cancelledTimeout) {
+        if (outcome === 'NOT_CANCELLABLE') {
             return NextResponse.json({ error: 'Task could not be cancelled.' }, { status: 409 });
         }
 
@@ -98,19 +56,3 @@ export async function POST(request: Request, { params }: { params: Promise<{ tas
         );
     }
 }
-
-/**
- * Reads and validates the required admin reason payload.
- */
-async function readRequiredAdminReason(request: Request): Promise<string | null> {
-    const payload = (await request.json().catch(() => ({}))) as {
-        reason?: unknown;
-    };
-
-    if (typeof payload.reason !== 'string') {
-        return null;
-    }
-
-    const reason = payload.reason.trim();
-    return reason.length > 0 ? reason : null;
-}

package/apps/agents-server/src/app/api/admin/chat-tasks/[taskId]/retry/route.ts

@@ -8,12 +8,18 @@ import {
 } from '@/src/utils/userChatTimeout';
 import { getUserChatJobById, retryUserChatJob, triggerUserChatJobWorker } from '@/src/utils/userChat';
 import { isUserAdmin } from '@/src/utils/isUserAdmin';
+import { isUserGlobalAdmin } from '@/src/utils/isUserGlobalAdmin';
+import { runWithRegisteredServerContext } from '@/src/tools/mapRegisteredServerContexts';
 
 /**
  * Requeues one failed durable chat task from the admin dashboard.
  */
 export async function POST(request: Request, { params }: { params: Promise<{ taskId: string }> }) {
-    if (!(await isUserAdmin())) {
+    const requestUrl = new URL(request.url);
+    const serverDomain = requestUrl.searchParams.get('serverDomain')?.trim() || null;
+    const isAuthorized = serverDomain ? await isUserGlobalAdmin() : await isUserAdmin();
+
+    if (!isAuthorized) {
         return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
     }
 
@@ -25,7 +31,7 @@ export async function POST(request: Request, { params }: { params: Promise<{ tas
         return NextResponse.json({ error: 'A non-empty reason is required.' }, { status: 400 });
     }
 
-    try {
+    const retryTaskInCurrentServer = async (): Promise<NextResponse> => {
         const actor = (await getCurrentUser())?.username || 'admin';
         const job = await getUserChatJobById(taskId);
 
@@ -49,7 +55,7 @@ export async function POST(request: Request, { params }: { params: Promise<{ tas
 
             after(() =>
                 triggerUserChatJobWorker({
-                    origin: new URL(request.url).origin,
+                    origin: requestUrl.origin,
                     preferredJobId: retriedJob.id,
                 }).catch((error) => console.error('[admin-chat-task] failed to wake worker after retry', error)),
             );
@@ -83,11 +89,23 @@ export async function POST(request: Request, { params }: { params: Promise<{ tas
 
         after(() =>
             triggerUserChatTimeoutWorker({
-                origin: new URL(request.url).origin,
+                origin: requestUrl.origin,
             }).catch((error) => console.error('[admin-chat-task] failed to wake timeout worker after retry', error)),
         );
 
         return NextResponse.json({ ok: true });
+    };
+
+    try {
+        const response = serverDomain
+            ? await runWithRegisteredServerContext(serverDomain, retryTaskInCurrentServer)
+            : await retryTaskInCurrentServer();
+
+        if (!response) {
+            return NextResponse.json({ error: 'Task not found.' }, { status: 404 });
+        }
+
+        return response;
     } catch (error) {
         console.error('[admin-chat-task] retry failed', { taskId, error });
         return NextResponse.json(

package/apps/agents-server/src/app/api/admin/chat-tasks/[taskId]/route.ts

@@ -0,0 +1,31 @@
+import { NextResponse } from 'next/server';
+import { getAdminChatTaskById } from '@/src/utils/getAdminChatTaskById';
+import { isUserAdmin } from '@/src/utils/isUserAdmin';
+import { isUserGlobalAdmin } from '@/src/utils/isUserGlobalAdmin';
+
+/**
+ * Loads one durable background task for the admin task detail page.
+ */
+export async function GET(request: Request, { params }: { params: Promise<{ taskId: string }> }) {
+    const serverDomain = new URL(request.url).searchParams.get('serverDomain')?.trim() || null;
+
+    const isAuthorized = serverDomain ? await isUserGlobalAdmin() : await isUserAdmin();
+    if (!isAuthorized) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    try {
+        const { taskId: rawTaskId } = await params;
+        const taskId = decodeURIComponent(rawTaskId);
+        const task = await getAdminChatTaskById(taskId, serverDomain);
+
+        if (!task) {
+            return NextResponse.json({ error: 'Task not found.' }, { status: 404 });
+        }
+
+        return NextResponse.json({ task });
+    } catch (error) {
+        console.error('[admin-chat-task] detail failed', error);
+        return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
+    }
+}

package/apps/agents-server/src/app/api/admin/chat-tasks/[taskId]/terminal/route.ts

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server';
 import { createInteractiveTerminalEventStream } from '@/src/utils/createInteractiveTerminalEventStream';
 import { isUserGlobalAdmin } from '@/src/utils/isUserGlobalAdmin';
 import { resolveAdminTaskTerminalSession } from '@/src/utils/taskTerminal/resolveAdminTaskTerminalSession';
+import { runWithRegisteredServerContext } from '@/src/tools/mapRegisteredServerContexts';
 
 /**
  * Forces fresh terminal snapshots and live streams for every request.
@@ -24,24 +25,32 @@ export async function GET(request: Request, { params }: { params: Promise<{ task
 
     const { taskId: rawTaskId } = await params;
     const taskId = decodeURIComponent(rawTaskId);
+    const serverDomain = new URL(request.url).searchParams.get('serverDomain')?.trim() || null;
 
     try {
-        const terminalResolution = await resolveAdminTaskTerminalSession(taskId);
-        if (!terminalResolution) {
-            return NextResponse.json({ error: 'Task not found.' }, { status: 404 });
-        }
-
-        const { searchParams } = new URL(request.url);
-        if (searchParams.get('stream') === '1') {
-            return createInteractiveTerminalEventStream(
-                request,
-                taskId,
-                terminalResolution.session,
-                terminalResolution.subscribe,
-            );
-        }
-
-        return NextResponse.json({ session: terminalResolution.session });
+        const resolveTerminalResponse = async (): Promise<Response | null> => {
+            const terminalResolution = await resolveAdminTaskTerminalSession(taskId);
+            if (!terminalResolution) {
+                return null;
+            }
+
+            if (new URL(request.url).searchParams.get('stream') === '1') {
+                return createInteractiveTerminalEventStream(
+                    request,
+                    taskId,
+                    terminalResolution.session,
+                    terminalResolution.subscribe,
+                );
+            }
+
+            return NextResponse.json({ session: terminalResolution.session });
+        };
+
+        const response = serverDomain
+            ? await runWithRegisteredServerContext(serverDomain, resolveTerminalResponse)
+            : await resolveTerminalResponse();
+
+        return response || NextResponse.json({ error: 'Task not found.' }, { status: 404 });
     } catch (error) {
         console.error('[admin-chat-task] terminal failed', { taskId, error });
         return NextResponse.json(

package/apps/agents-server/src/app/api/admin/chat-tasks/cancel-all/route.ts

@@ -0,0 +1,45 @@
+import { NextResponse } from 'next/server';
+import { getCurrentUser } from '@/src/utils/getCurrentUser';
+import { cancelAllActiveAdminChatTasks } from '@/src/utils/cancelAllActiveAdminChatTasks';
+import { readRequiredAdminReason } from '@/src/utils/readRequiredAdminReason';
+import { isUserAdmin } from '@/src/utils/isUserAdmin';
+
+/**
+ * Requests admin cancellation for every active (queued or running) durable chat task at once.
+ */
+export async function POST(request: Request) {
+    if (!(await isUserAdmin())) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const reason = await readRequiredAdminReason(request);
+
+    if (!reason) {
+        return NextResponse.json({ error: 'A non-empty reason is required.' }, { status: 400 });
+    }
+
+    try {
+        const actor = (await getCurrentUser())?.username || 'admin';
+        const summary = await cancelAllActiveAdminChatTasks({
+            actor,
+            reason,
+            requestOrigin: new URL(request.url).origin,
+        });
+
+        console.info('[admin-chat-task] cancel-all', {
+            actor,
+            reason,
+            matchedCount: summary.matchedCount,
+            cancelledCount: summary.cancelledCount,
+            hasMore: summary.hasMore,
+        });
+
+        return NextResponse.json({ ok: true, ...summary });
+    } catch (error) {
+        console.error('[admin-chat-task] cancel-all failed', error);
+        return NextResponse.json(
+            { error: error instanceof Error ? error.message : 'Failed to cancel all tasks.' },
+            { status: 500 },
+        );
+    }
+}

package/apps/agents-server/src/app/api/admin/default-agents/reinstate/route.ts

@@ -0,0 +1,62 @@
+import { NextResponse } from 'next/server';
+import { seedCoreAgents } from '../../../../../database/seedCoreAgents';
+import { reinstateDefaultAgents } from '../../../../../database/reinstateDefaultAgents';
+import { $provideServer } from '../../../../../tools/$provideServer';
+import { invalidateCachedActiveOrganizationSnapshots } from '../../../../../utils/agentOrganization/loadAgentOrganizationState';
+import { isUserAdmin } from '../../../../../utils/isUserAdmin';
+
+/**
+ * Supported reinstatement scopes for the bundled agents.
+ *
+ * @private type of the default-agents reinstate route
+ */
+type ReinstateScope = 'core' | 'default';
+
+/**
+ * Reinstates the missing bundled core or normal default agents on the current server.
+ *
+ * This exposes — ex-post and admin-gated — the same default/core agent creation logic that runs when a server is first
+ * created, so an admin can restore agents that were removed without recreating the whole server.
+ *
+ * @param request - Incoming reinstate request carrying the `scope`.
+ * @returns Names of the agents created during this run.
+ */
+export async function POST(request: Request) {
+    if (!(await isUserAdmin())) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    let scope: ReinstateScope;
+    try {
+        const body = (await request.json()) as { scope?: unknown };
+        if (body.scope !== 'core' && body.scope !== 'default') {
+            return NextResponse.json(
+                { error: 'The `scope` field must be either `core` or `default`.' },
+                { status: 400 },
+            );
+        }
+        scope = body.scope;
+    } catch {
+        return NextResponse.json({ error: 'Invalid JSON request body.' }, { status: 400 });
+    }
+
+    try {
+        const { tablePrefix } = await $provideServer();
+        const createdAgentNames =
+            scope === 'core'
+                ? (await seedCoreAgents({ tablePrefix })).createdAgentNames
+                : (await reinstateDefaultAgents({ tablePrefix })).createdAgentNames;
+
+        // Note: Drop the short-lived organization snapshot cache so the newly created agents appear immediately.
+        invalidateCachedActiveOrganizationSnapshots();
+
+        return NextResponse.json({ scope, createdAgentNames });
+    } catch (error) {
+        return NextResponse.json(
+            {
+                error: error instanceof Error ? error.message : 'Failed to reinstate the bundled agents.',
+            },
+            { status: 500 },
+        );
+    }
+}

package/apps/agents-server/src/app/api/admin/dns-records/cloudflare/route.ts

@@ -0,0 +1,116 @@
+import { NextResponse } from 'next/server';
+import { spaceTrim } from 'spacetrim';
+import { NotFoundError } from '../../../../../../../../src/errors/NotFoundError';
+import { applyCloudflareDnsRecordInstructions } from '../../../../../utils/cloudflare/applyCloudflareDnsRecordInstructions';
+import type { DnsRecordInstruction, DnsRecordSelection } from '../../../../../utils/dnsRecords/DnsRecordInstruction';
+import { resolveDnsRecordBatchPlan } from '../../../../../utils/dnsRecords/resolveDnsRecordBatchPlan';
+import { isUserAdmin } from '../../../../../utils/isUserAdmin';
+import { isUserGlobalAdmin } from '../../../../../utils/isUserGlobalAdmin';
+
+/**
+ * Payload sent by the Cloudflare DNS wizard.
+ */
+type CloudflareDnsWizardRequestBody = {
+    /**
+     * Cloudflare API token pasted by the administrator, empty when the VPS token should be used.
+     */
+    readonly apiToken?: string;
+
+    /**
+     * Domain whose DNS records are configured.
+     */
+    readonly domain?: string;
+
+    /**
+     * Whether all shown records or one shown alternative has to be configured.
+     */
+    readonly recordSelection?: DnsRecordSelection;
+
+    /**
+     * DNS records shown in the DNS manual.
+     */
+    readonly records?: ReadonlyArray<DnsRecordInstruction>;
+};
+
+/**
+ * Writes the DNS records of one manual into Cloudflare in one batch.
+ *
+ * @param request - Cloudflare DNS wizard request.
+ * @returns Result of every imported record.
+ */
+export async function POST(request: Request) {
+    if (!(await isUserAdmin())) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const body = ((await request.json().catch(() => null)) || {}) as CloudflareDnsWizardRequestBody;
+    const domain = (body.domain || '').trim();
+    const records = body.records || [];
+
+    if (!domain || records.length === 0) {
+        return NextResponse.json(
+            {
+                error: spaceTrim(`
+                    Both \`domain\` and \`records\` are required to import DNS records into Cloudflare.
+                `),
+            },
+            { status: 400 },
+        );
+    }
+
+    // Note: `CLOUDFLARE_API_TOKEN` belongs to the whole VPS, so only a super admin may write DNS records with it.
+    //       Every other administrator has to provide their own token.
+    const configuredApiToken = (await isUserGlobalAdmin()) ? process.env.CLOUDFLARE_API_TOKEN || '' : '';
+    const apiToken = ((body.apiToken || '').trim() || configuredApiToken).trim();
+
+    if (!apiToken) {
+        return NextResponse.json(
+            {
+                error: spaceTrim(`
+                    A Cloudflare API token is required.
+
+                    Create a token with the **Edit zone DNS** template in Cloudflare and paste it above. Only a super
+                    admin can import with the \`CLOUDFLARE_API_TOKEN\` configured on this VPS.
+                `),
+            },
+            { status: 400 },
+        );
+    }
+
+    // Note: The batch plan is resolved again on the server, so that placeholder values and record alternatives can
+    //       never be written into Cloudflare even when the browser sends them.
+    const { applicableRecords } = resolveDnsRecordBatchPlan({
+        records,
+        recordSelection: body.recordSelection === 'one' ? 'one' : 'all',
+    });
+
+    if (applicableRecords.length === 0) {
+        return NextResponse.json(
+            {
+                error: spaceTrim(`
+                    None of the records for \`${domain}\` can be imported automatically.
+
+                    Add them manually or fill in their placeholder values first.
+                `),
+            },
+            { status: 400 },
+        );
+    }
+
+    try {
+        const application = await applyCloudflareDnsRecordInstructions({
+            apiToken,
+            domain,
+            records: applicableRecords,
+        });
+
+        return NextResponse.json(application);
+    } catch (error) {
+        return NextResponse.json(
+            {
+                error: error instanceof Error ? error.message : 'Failed to import the DNS records into Cloudflare.',
+            },
+            { status: error instanceof NotFoundError ? 404 : 502 },
+        );
+    }
+}