@promptbook/cli 0.114.0-2 → 0.114.0-20

package/apps/agents-server/scripts/run-npm.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { spawnSync } = require('node:child_process');
+const { spawn, spawnSync } = require('node:child_process');
 
 /**
  * Platform-specific npm executable.
@@ -8,22 +8,34 @@ const { spawnSync } = require('node:child_process');
 const NPM_EXECUTABLE = process.platform === 'win32' ? 'npm.cmd' : 'npm';
 
 /**
- * Runs one npm command and forwards its output and exit status.
+ * Creates the spawn options shared by every npm command of the Agents Server scripts.
  *
  * Windows resolves npm through a `.cmd` shim, which needs shell execution when spawned from
  * Node.js on some supported Node versions.
  *
- * @param {ReadonlyArray<string>} argumentsList - Arguments passed to npm.
  * @param {{ cwd: string, environmentOverrides?: Readonly<Record<string, string>> }} options - Command options.
+ * @returns {{ cwd: string, env: Record<string, string|undefined>, shell: boolean }} Shared spawn options.
  */
-function runNpm(argumentsList, { cwd, environmentOverrides = {} }) {
-    const result = spawnSync(NPM_EXECUTABLE, argumentsList, {
+function createNpmSpawnOptions({ cwd, environmentOverrides = {} }) {
+    return {
         cwd,
         env: {
             ...process.env,
             ...environmentOverrides,
         },
         shell: process.platform === 'win32',
+    };
+}
+
+/**
+ * Runs one npm command, waits for it, and forwards its output and exit status.
+ *
+ * @param {ReadonlyArray<string>} argumentsList - Arguments passed to npm.
+ * @param {{ cwd: string, environmentOverrides?: Readonly<Record<string, string>> }} options - Command options.
+ */
+function runNpm(argumentsList, options) {
+    const result = spawnSync(NPM_EXECUTABLE, argumentsList, {
+        ...createNpmSpawnOptions(options),
         stdio: 'inherit',
     });
 
@@ -37,6 +49,70 @@ function runNpm(argumentsList, { cwd, environmentOverrides = {} }) {
     }
 }
 
+/**
+ * Starts one npm command without waiting for it and forwards its output to this terminal.
+ *
+ * @param {ReadonlyArray<string>} argumentsList - Arguments passed to npm.
+ * @param {{ cwd: string, environmentOverrides?: Readonly<Record<string, string>> }} options - Command options.
+ * @returns {Promise<number>} Exit status of the finished command.
+ */
+function startNpm(argumentsList, options) {
+    return waitForNpm(
+        spawn(NPM_EXECUTABLE, argumentsList, {
+            ...createNpmSpawnOptions(options),
+            stdio: 'inherit',
+        }),
+    );
+}
+
+/**
+ * Starts one npm command without waiting for it and collects its output instead of printing it.
+ *
+ * Two commands running next to each other cannot share this terminal line by line, so the output of
+ * the quieter one is kept and printed as one readable block once it has finished.
+ *
+ * @param {ReadonlyArray<string>} argumentsList - Arguments passed to npm.
+ * @param {{ cwd: string, environmentOverrides?: Readonly<Record<string, string>> }} options - Command options.
+ * @returns {Promise<{ status: number, output: string }>} Exit status and collected output.
+ */
+function startNpmWithCollectedOutput(argumentsList, options) {
+    const npmProcess = spawn(NPM_EXECUTABLE, argumentsList, {
+        ...createNpmSpawnOptions(options),
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let output = '';
+    const collectOutput = (chunk) => {
+        output = `${output}${chunk.toString()}`;
+    };
+
+    npmProcess.stdout?.on('data', collectOutput);
+    npmProcess.stderr?.on('data', collectOutput);
+
+    return waitForNpm(npmProcess).then((status) => ({ status, output }));
+}
+
+/**
+ * Waits for one started npm command and reports its exit status.
+ *
+ * @param {import('node:child_process').ChildProcess} npmProcess - Started npm command.
+ * @returns {Promise<number>} Exit status of the finished command.
+ */
+function waitForNpm(npmProcess) {
+    return new Promise((resolve) => {
+        npmProcess.once('error', (error) => {
+            console.error(`Failed to run ${NPM_EXECUTABLE}:`, error);
+            resolve(1);
+        });
+
+        npmProcess.once('close', (status) => {
+            resolve(status ?? 1);
+        });
+    });
+}
+
 module.exports = {
     runNpm,
+    startNpm,
+    startNpmWithCollectedOutput,
 };

package/apps/agents-server/src/app/admin/_components/AdminFilterFields.tsx

@@ -0,0 +1,84 @@
+import type { ReactNode } from 'react';
+
+/**
+ * One option of a shared admin filter select.
+ *
+ * @private shared admin UI type
+ */
+export type AdminFilterSelectOption = {
+    readonly label: string;
+    readonly value: string;
+};
+
+/**
+ * Props for the shared admin filter field wrapper.
+ *
+ * @private shared admin UI type
+ */
+type AdminFilterFieldProps = {
+    readonly children: ReactNode;
+    readonly htmlFor: string;
+    readonly label: string;
+};
+
+/**
+ * Props for the shared admin filter select.
+ *
+ * @private shared admin UI type
+ */
+type AdminFilterSelectFieldProps = {
+    readonly disabled?: boolean;
+    readonly id: string;
+    readonly label: string;
+    readonly onChange: (value: string) => void;
+    readonly options: ReadonlyArray<AdminFilterSelectOption>;
+    readonly value: string;
+};
+
+/**
+ * Shared label-and-control wrapper for compact admin filter controls.
+ *
+ * @private shared admin UI component
+ */
+export function AdminFilterField({ children, htmlFor, label }: AdminFilterFieldProps) {
+    return (
+        <div className="flex flex-col gap-1">
+            <label htmlFor={htmlFor} className="text-sm font-medium text-gray-700">
+                {label}
+            </label>
+            {children}
+        </div>
+    );
+}
+
+/**
+ * Shared select control used in admin filter panels.
+ *
+ * @private shared admin UI component
+ */
+export function AdminFilterSelectField({
+    disabled,
+    id,
+    label,
+    onChange,
+    options,
+    value,
+}: AdminFilterSelectFieldProps) {
+    return (
+        <AdminFilterField label={label} htmlFor={id}>
+            <select
+                id={id}
+                value={value}
+                disabled={disabled}
+                onChange={(event) => onChange(event.target.value)}
+                className="rounded-md border border-gray-300 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 disabled:cursor-not-allowed disabled:bg-gray-100 disabled:text-gray-400"
+            >
+                {options.map((option) => (
+                    <option key={option.value} value={option.value}>
+                        {option.label}
+                    </option>
+                ))}
+            </select>
+        </AdminFilterField>
+    );
+}

package/apps/agents-server/src/app/admin/_components/AdminMetricCard.tsx

@@ -0,0 +1,36 @@
+/**
+ * Props for one admin summary metric card.
+ *
+ * @private shared admin UI type
+ */
+type AdminMetricCardProps = {
+    /**
+     * Small heading naming the measured thing.
+     */
+    readonly label: string;
+
+    /**
+     * Measured value, already formatted.
+     */
+    readonly value: string;
+
+    /**
+     * Short sentence saying what the value means.
+     */
+    readonly caption: string;
+};
+
+/**
+ * Small metric card used in the summary header of admin dashboards.
+ *
+ * @private shared admin UI component
+ */
+export function AdminMetricCard({ caption, label, value }: AdminMetricCardProps) {
+    return (
+        <div className="rounded-2xl border border-gray-200 bg-white p-5 shadow-sm">
+            <div className="text-xs font-semibold uppercase tracking-wide text-gray-400">{label}</div>
+            <div className="mt-2 text-3xl font-light text-gray-900">{value}</div>
+            <div className="mt-1 text-sm text-gray-500">{caption}</div>
+        </div>
+    );
+}

package/apps/agents-server/src/app/admin/_components/AdminTaskManagerTabs.tsx

@@ -0,0 +1,97 @@
+'use client';
+
+import { AdminRouteTabs, type AdminRouteTabItem } from './AdminRouteTabs';
+
+/**
+ * Sections of the admin background-work tab group.
+ *
+ * @private shared admin UI type
+ */
+export type AdminTaskManagerTabId = 'server' | 'vps' | 'planned-messages';
+
+/**
+ * Task-manager scope: one server, or the whole VPS.
+ *
+ * @private shared admin UI type
+ */
+export type TaskManagerScope = Exclude<AdminTaskManagerTabId, 'planned-messages'>;
+
+/**
+ * Route of the per-server task manager.
+ *
+ * @private shared admin UI constant
+ */
+export const SERVER_TASK_MANAGER_PATH = '/admin/task-manager';
+
+/**
+ * Route of the VPS-wide (superadmin) task manager.
+ *
+ * @private shared admin UI constant
+ */
+export const VPS_TASK_MANAGER_PATH = '/superadmin/task-manager';
+
+/**
+ * Route of the planned-message manager.
+ *
+ * @private shared admin UI constant
+ */
+export const PLANNED_MESSAGE_MANAGER_PATH = '/admin/planned-messages';
+
+/**
+ * Route-backed sections of the admin background-work tab group.
+ *
+ * The task managers show what background work is running right now; the planned-message manager shows
+ * the plans that keep creating some of that work. They belong to one tab group because an
+ * administrator answering "why does this agent keep waking up?" needs to move between the two.
+ *
+ * @private constant of AdminTaskManagerTabs
+ */
+const ADMIN_TASK_MANAGER_TAB_ITEMS: ReadonlyArray<AdminRouteTabItem<AdminTaskManagerTabId>> = [
+    {
+        id: 'server',
+        href: SERVER_TASK_MANAGER_PATH,
+        label: 'This server',
+    },
+    {
+        id: 'vps',
+        href: VPS_TASK_MANAGER_PATH,
+        label: 'All servers (VPS)',
+    },
+    {
+        id: 'planned-messages',
+        href: PLANNED_MESSAGE_MANAGER_PATH,
+        label: 'Planned messages',
+    },
+];
+
+/**
+ * Props for the admin background-work tabs.
+ *
+ * @private shared admin UI type
+ */
+type AdminTaskManagerTabsProps = {
+    /**
+     * Section the current page belongs to.
+     */
+    readonly activeTabId: AdminTaskManagerTabId;
+
+    /**
+     * Whether the VPS-wide tab is available to the current user (superadmin only).
+     */
+    readonly isSuperAdmin: boolean;
+};
+
+/**
+ * Renders the tabs interlinking the task managers and the planned-message manager.
+ *
+ * The VPS-wide tab is superadmin-only, so an ordinary admin moves between the two per-server sections.
+ *
+ * @private shared admin UI component
+ */
+export function AdminTaskManagerTabs({ activeTabId, isSuperAdmin }: AdminTaskManagerTabsProps) {
+    const visibleTabItems = ADMIN_TASK_MANAGER_TAB_ITEMS.filter(
+        (tabItem) => tabItem.id !== 'vps' || isSuperAdmin,
+    );
+
+    return <AdminRouteTabs activeTabId={activeTabId} items={visibleTabItems} />;
+}

package/apps/agents-server/src/app/admin/email-server/page.tsx

@@ -4,11 +4,12 @@ import { ForbiddenPage } from '../../../components/ForbiddenPage/ForbiddenPage';
 import { StalwartSynchronizeButton } from '../../../components/StalwartSynchronizeButton/StalwartSynchronizeButton';
 import { $provideServer } from '../../../tools/$provideServer';
 import { isUserAdmin } from '../../../utils/isUserAdmin';
-import { createEmailDnsInstructions } from '../../../utils/stalwart/createEmailDnsInstructions';
+import { createEmailDnsRecordsSection } from '../../../utils/stalwart/createEmailDnsRecordsSection';
 import {
     isStalwartEmailSnapshotOperational,
     readStalwartEmailSnapshot,
 } from '../../../utils/stalwart/readStalwartEmailSnapshot';
+import { isManagedServerDnsDiagnosticIssue } from '../../superadmin/servers/ServersRegistryDnsTypes';
 import { AdminConfigurationShell } from '../_components/AdminConfigurationShell';
 import { $synchronizeStalwartEmailDomain } from './actions';
 
@@ -27,7 +28,12 @@ export default async function AdminEmailServerPage() {
 
     const server = await $provideServer();
     const snapshot = await readStalwartEmailSnapshot(server.publicUrl.hostname);
-    const dnsInstructions = createEmailDnsInstructions(snapshot.domain, snapshot.mailDnsDiagnostic.publicIpAddress);
+    const emailDnsRecordsSection = createEmailDnsRecordsSection({
+        domain: snapshot.domain,
+        publicIpAddress: snapshot.mailDnsDiagnostic.publicIpAddress,
+        statusSummary: snapshot.mailDnsDiagnostic.summary,
+        isDnsIssue: isManagedServerDnsDiagnosticIssue(snapshot.mailDnsDiagnostic),
+    });
     const isOperational = isStalwartEmailSnapshotOperational(snapshot);
 
     return (
@@ -111,21 +117,14 @@ export default async function AdminEmailServerPage() {
                     <div className="mt-4">
                         <DnsRecordsInstructions
                             description={
-                                snapshot.mailDnsDiagnostic.publicIpAddress ? (
-                                    <p>
-                                        Add these records at your DNS provider. The A records below use this VPS’s
-                                        detected public address.
-                                    </p>
-                                ) : (
-                                    <p>
-                                        Add these records at your DNS provider. Replace <code>&lt;VPS_PUBLIC_IP&gt;</code>{' '}
-                                        with the public address of this VPS.
-                                    </p>
-                                )
+                                <p>
+                                    Add these records at your DNS provider. The complete DNS setup of this server -
+                                    including its own domain and its generated project domains - is configured together
+                                    on the Super Admin <span className="font-mono">/superadmin/servers</span> page.
+                                </p>
                             }
                             domain={snapshot.domain}
-                            recordSelection="all"
-                            records={dnsInstructions}
+                            sections={[emailDnsRecordsSection]}
                         />
                     </div>
                     <div className="mt-4 space-y-2 rounded-lg bg-blue-50 p-4 text-sm text-blue-950">
@@ -148,9 +147,9 @@ export default async function AdminEmailServerPage() {
                             that hostname.
                         </p>
                         <p>
-                            Open TCP port <code>25</code> publicly. Keep the submission port <code>465</code>{' '}
-                            firewalled unless external mail clients need it, and never expose the Stalwart management
-                            API on port <code>8080</code>.
+                            Open TCP port <code>25</code> publicly. Keep the submission port <code>465</code> firewalled
+                            unless external mail clients need it, and never expose the Stalwart management API on port{' '}
+                            <code>8080</code>.
                         </p>
                     </div>
                     <pre className="mt-4 overflow-auto whitespace-pre-wrap rounded-lg bg-gray-950 p-4 text-xs text-gray-100">

package/apps/agents-server/src/app/admin/messages/MessageParticipants.tsx

@@ -0,0 +1,84 @@
+import type { Json } from '../../../database/schema';
+import { normalizeMessageContacts, type MessageContact } from './messageAdminPresentation';
+
+/**
+ * Props for one sender/recipients table cell.
+ */
+type MessageParticipantsProps = {
+    readonly channel: string;
+    readonly sender: Json;
+    readonly recipients: Json;
+};
+
+/**
+ * Renders sender and recipient values as named contacts instead of raw JSON.
+ */
+export function MessageParticipants({ channel, sender, recipients }: MessageParticipantsProps) {
+    const senderContacts = normalizeMessageContacts(sender);
+    const recipientContacts = normalizeMessageContacts(recipients);
+    const isEmail = channel === 'EMAIL';
+
+    return (
+        <dl className="min-w-56 space-y-2 text-xs">
+            <MessageContactList label={isEmail ? 'From' : 'Sender'} contacts={senderContacts} />
+            <MessageContactList label={isEmail ? 'To' : 'Recipients'} contacts={recipientContacts} />
+        </dl>
+    );
+}
+
+/**
+ * Props for one labelled group of message contacts.
+ */
+type MessageContactListProps = {
+    readonly label: string;
+    readonly contacts: ReadonlyArray<MessageContact>;
+};
+
+/**
+ * Renders a compact label next to one or more message contacts.
+ */
+function MessageContactList({ label, contacts }: MessageContactListProps) {
+    return (
+        <div className="grid grid-cols-[2.5rem_minmax(0,1fr)] items-start gap-2">
+            <dt className="pt-0.5 font-semibold uppercase tracking-wide text-gray-400">{label}</dt>
+            <dd className="min-w-0 space-y-1">
+                {contacts.length > 0
+                    ? contacts.map((contact, index) => (
+                          <MessageContactValue key={`${contact.address}:${index}`} contact={contact} />
+                      ))
+                    : '-'}
+            </dd>
+        </div>
+    );
+}
+
+/**
+ * Props for one normalized message contact.
+ */
+type MessageContactValueProps = {
+    readonly contact: MessageContact;
+};
+
+/**
+ * Renders an optional display name and a wrapping address or generic identifier.
+ */
+function MessageContactValue({ contact }: MessageContactValueProps) {
+    return (
+        <div className="min-w-0 rounded-md border border-gray-200 bg-gray-50 px-2 py-1.5">
+            {contact.fullName ? <div className="truncate font-medium text-gray-800">{contact.fullName}</div> : null}
+            {contact.isEmail ? (
+                <a
+                    href={`mailto:${contact.address}`}
+                    className="break-all text-blue-700 hover:text-blue-900 hover:underline"
+                    title={contact.address}
+                >
+                    {contact.address}
+                </a>
+            ) : (
+                <div className="break-all text-gray-700" title={contact.address}>
+                    {contact.address || '-'}
+                </div>
+            )}
+        </div>
+    );
+}

package/apps/agents-server/src/app/admin/messages/MessageStatus.tsx

@@ -0,0 +1,96 @@
+import type { MessageSendAttemptRow } from '../../../utils/messagesAdmin';
+import {
+    formatMessageSendAttemptLog,
+    getFailedMessageSendAttempts,
+    resolveLatestMessageSendAttemptErrorMessage,
+    resolveMessageStatusPresentation,
+    type MessageStatusPresentation,
+} from './messageAdminPresentation';
+
+/**
+ * Props for the direction-aware message status cell.
+ */
+type MessageStatusProps = {
+    readonly direction: string;
+    readonly attempts: ReadonlyArray<MessageSendAttemptRow> | undefined;
+};
+
+/**
+ * Renders delivery status, a compact failure reason, and the complete persisted provider log.
+ */
+export function MessageStatus({ direction, attempts }: MessageStatusProps) {
+    const status = resolveMessageStatusPresentation(direction, attempts);
+    const failedAttempts = getFailedMessageSendAttempts(attempts);
+    const latestErrorMessage = resolveLatestMessageSendAttemptErrorMessage(attempts);
+
+    return (
+        <div className="min-w-64 space-y-2">
+            <MessageStatusBadge status={status} />
+            {latestErrorMessage ? (
+                <p className="max-w-sm whitespace-normal break-words text-xs leading-relaxed text-red-700">
+                    {latestErrorMessage}
+                </p>
+            ) : null}
+            {failedAttempts.length > 0 ? (
+                <details className="max-w-xl whitespace-normal rounded-md border border-red-200 bg-red-50 p-2 text-xs">
+                    <summary className="cursor-pointer font-medium text-red-800">
+                        <span>Complete log</span> ({failedAttempts.length})
+                    </summary>
+                    <div className="mt-2 space-y-3">
+                        {failedAttempts.map((attempt) => (
+                            <pre
+                                key={attempt.id}
+                                className="max-h-80 overflow-auto whitespace-pre-wrap break-words rounded bg-gray-950 p-3 text-[10px] leading-relaxed text-gray-100"
+                            >
+                                {formatMessageSendAttemptLog(attempt)}
+                            </pre>
+                        ))}
+                    </div>
+                </details>
+            ) : null}
+        </div>
+    );
+}
+
+/**
+ * Props for the compact message status badge.
+ */
+type MessageStatusBadgeProps = {
+    readonly status: MessageStatusPresentation;
+};
+
+/**
+ * Renders the visual badge for one resolved message status.
+ */
+function MessageStatusBadge({ status }: MessageStatusBadgeProps) {
+    if (status.kind === 'received') {
+        return (
+            <span className="inline-flex items-center rounded bg-emerald-100 px-2 py-0.5 text-xs font-medium text-emerald-800">
+                Received
+            </span>
+        );
+    }
+
+    if (status.kind === 'sent') {
+        return (
+            <span className="inline-flex items-center rounded bg-green-100 px-2 py-0.5 text-xs font-medium text-green-800">
+                <span>Sent</span>
+                {status.providerName ? ` (${status.providerName})` : ''}
+            </span>
+        );
+    }
+
+    if (status.kind === 'failed') {
+        return (
+            <span className="inline-flex items-center rounded bg-red-100 px-2 py-0.5 text-xs font-medium text-red-800">
+                <span>Failed</span> ({status.attemptCount})
+            </span>
+        );
+    }
+
+    return (
+        <span className="inline-flex items-center rounded bg-gray-100 px-2 py-0.5 text-xs font-medium text-gray-800">
+            Pending
+        </span>
+    );
+}