@promptbook/cli 0.114.0-0 → 0.114.0-10

package/apps/agents-server/scripts/kill-port.js

@@ -0,0 +1,163 @@
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+
+/**
+ * Frees the given TCP ports before a build, a development server, or an E2E run binds them again.
+ *
+ * This replaces `npx kill-port`, which resolved an undeclared package through the npm registry on
+ * every single invocation. Freeing a port is a best-effort cleanup step, so nothing here may ever
+ * fail the surrounding command.
+ *
+ * Usage: `node ./scripts/kill-port.js 4021 4440`
+ */
+function killPorts() {
+    for (const port of parsePortArguments(process.argv.slice(2))) {
+        const listeningProcessIds = resolveListeningProcessIds(port);
+
+        if (listeningProcessIds.length === 0) {
+            console.log(`No process is listening on port ${port}.`);
+            continue;
+        }
+
+        for (const processId of listeningProcessIds) {
+            if (killProcess(processId)) {
+                console.log(`Freed port ${port} by stopping process ${processId}.`);
+            } else {
+                console.log(`Could not stop process ${processId} listening on port ${port}.`);
+            }
+        }
+    }
+}
+
+/**
+ * Reads the TCP ports from the command line arguments.
+ *
+ * @param {ReadonlyArray<string>} argumentsList - Raw command line arguments.
+ * @returns {Array<number>} Valid TCP ports.
+ */
+function parsePortArguments(argumentsList) {
+    return argumentsList.map((argument) => Number(argument)).filter(isPort);
+}
+
+/**
+ * Returns whether one value is a usable TCP port number.
+ *
+ * @param {number} value - Parsed command line argument.
+ * @returns {boolean} Whether the value can be freed.
+ */
+function isPort(value) {
+    return Number.isInteger(value) && value > 0 && value <= 65535;
+}
+
+/**
+ * Resolves the process ids currently listening on one TCP port.
+ *
+ * @param {number} port - TCP port to inspect.
+ * @returns {Array<number>} Process ids of the listeners.
+ */
+function resolveListeningProcessIds(port) {
+    if (process.platform === 'win32') {
+        return resolveWindowsListeningProcessIds(port);
+    }
+
+    return resolvePosixListeningProcessIds(port);
+}
+
+/**
+ * Resolves listeners of one TCP port through the Windows `netstat` utility.
+ *
+ * @param {number} port - TCP port to inspect.
+ * @returns {Array<number>} Process ids of the listeners.
+ */
+function resolveWindowsListeningProcessIds(port) {
+    const netstatResult = spawnSync('netstat', ['-a', '-n', '-o', '-p', 'TCP'], { encoding: 'utf8' });
+
+    if (typeof netstatResult.stdout !== 'string') {
+        return [];
+    }
+
+    return dedupeProcessIds(
+        netstatResult.stdout
+            .split(/\r?\n/u)
+            .filter((line) => line.includes('LISTENING'))
+            .map((line) => line.trim().split(/\s+/u))
+            .filter((columns) => columns.length >= 5 && isAddressOnPort(columns[1], port))
+            .map((columns) => Number(columns[columns.length - 1])),
+    );
+}
+
+/**
+ * Resolves listeners of one TCP port through the POSIX `lsof` utility.
+ *
+ * @param {number} port - TCP port to inspect.
+ * @returns {Array<number>} Process ids of the listeners.
+ */
+function resolvePosixListeningProcessIds(port) {
+    const listOpenFilesResult = spawnSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'], {
+        encoding: 'utf8',
+    });
+
+    if (typeof listOpenFilesResult.stdout !== 'string') {
+        return [];
+    }
+
+    return dedupeProcessIds(listOpenFilesResult.stdout.split(/\s+/u).map((value) => Number(value)));
+}
+
+/**
+ * Returns whether one `netstat` local address belongs to the inspected port.
+ *
+ * The address is printed as `0.0.0.0:4440`, `127.0.0.1:4440`, or `[::]:4440`.
+ *
+ * @param {string} address - Local address column of one `netstat` row.
+ * @param {number} port - TCP port to inspect.
+ * @returns {boolean} Whether the row belongs to the port.
+ */
+function isAddressOnPort(address, port) {
+    return address.endsWith(`:${port}`);
+}
+
+/**
+ * Keeps only distinct process ids which are safe to stop.
+ *
+ * The current process and its parent are excluded so that freeing a port can never stop the build,
+ * the test runner, or the shell which started them.
+ *
+ * @param {ReadonlyArray<number>} processIds - Raw process ids.
+ * @returns {Array<number>} Distinct stoppable process ids.
+ */
+function dedupeProcessIds(processIds) {
+    return Array.from(
+        new Set(
+            processIds.filter(
+                (processId) =>
+                    Number.isInteger(processId) &&
+                    processId > 0 &&
+                    processId !== process.pid &&
+                    processId !== process.ppid,
+            ),
+        ),
+    );
+}
+
+/**
+ * Stops one process which holds an inspected port.
+ *
+ * @param {number} processId - Process id of the listener.
+ * @returns {boolean} Whether the process was stopped.
+ */
+function killProcess(processId) {
+    if (process.platform === 'win32') {
+        return spawnSync('taskkill', ['/F', '/PID', String(processId)], { stdio: 'ignore' }).status === 0;
+    }
+
+    try {
+        process.kill(processId, 'SIGKILL');
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+killPorts();

package/apps/agents-server/scripts/prerender-homepage.js

@@ -32,7 +32,7 @@ const SERVER_READY_MARKER = 'Ready in';
 /**
  * Constant for output dir.
  */
-const OUTPUT_DIR = path.join(APP_ROOT, '.next', 'prerendered');
+const OUTPUT_DIR = path.join(APP_ROOT, process.env.NEXT_DIST_DIR || '.next', 'prerendered');
 /**
  * Constant for output file.
  */

package/apps/agents-server/scripts/run-e2e-tests.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const path = require('node:path');
+const { runNpm, startNpm, startNpmWithCollectedOutput } = require('./run-npm.js');
+
+/**
+ * Root directory of the Agents Server app.
+ */
+const APP_ROOT = path.resolve(__dirname, '..');
+
+/**
+ * Runs the complete Agents Server E2E verification flow.
+ *
+ * App linting remains an explicit test phase, but it reads only the sources and therefore does not
+ * depend on the production build. Both run at the same time and the flow waits for the slower one,
+ * which is always the build. The build then skips its duplicate lint pass, and Playwright starts
+ * that same build instead of compiling a second `.next-e2e` output through `webServer`.
+ */
+async function runE2eTests() {
+    const commandOptions = {
+        cwd: APP_ROOT,
+    };
+
+    const lintCompletion = startNpmWithCollectedOutput(['run', 'lint'], commandOptions);
+    const buildStatus = await startNpm(['run', 'build-e2e', '--', '--no-lint'], commandOptions);
+    const lintResult = await lintCompletion;
+
+    console.log('\n> lint (ran next to the production build)\n');
+    process.stdout.write(lintResult.output);
+
+    if (lintResult.status !== 0) {
+        process.exit(lintResult.status);
+    }
+
+    if (buildStatus !== 0) {
+        process.exit(buildStatus);
+    }
+
+    runNpm(['exec', '--', 'playwright', 'test', ...process.argv.slice(2)], {
+        ...commandOptions,
+        environmentOverrides: {
+            PTBK_E2E_BUILD_READY: 'true',
+        },
+    });
+}
+
+void runE2eTests();

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

@@ -0,0 +1,118 @@
+'use strict';
+
+const { spawn, spawnSync } = require('node:child_process');
+
+/**
+ * Platform-specific npm executable.
+ */
+const NPM_EXECUTABLE = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+/**
+ * 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 {{ cwd: string, environmentOverrides?: Readonly<Record<string, string>> }} options - Command options.
+ * @returns {{ cwd: string, env: Record<string, string|undefined>, shell: boolean }} Shared spawn options.
+ */
+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',
+    });
+
+    if (result.error) {
+        console.error(`Failed to run ${NPM_EXECUTABLE}:`, result.error);
+        process.exit(1);
+    }
+
+    if (result.status !== 0) {
+        process.exit(result.status ?? 1);
+    }
+}
+
+/**
+ * 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/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);
+    const emailDnsRecordsSection = createEmailDnsRecordsSection({
+        domain: snapshot.domain,
+        publicIpAddress: snapshot.mailDnsDiagnostic.publicIpAddress,
+        statusSummary: snapshot.mailDnsDiagnostic.summary,
+        isDnsIssue: isManagedServerDnsDiagnosticIssue(snapshot.mailDnsDiagnostic),
+    });
     const isOperational = isStalwartEmailSnapshotOperational(snapshot);
 
     return (
@@ -55,7 +61,8 @@ export default async function AdminEmailServerPage() {
                                     Domain <code>{snapshot.domain}</code> · API{' '}
                                     {snapshot.isReachable ? 'reachable' : 'unavailable'} · bridge{' '}
                                     {snapshot.isBridgeAccountConfigured ? 'configured' : 'missing'} · inbound hook{' '}
-                                    {snapshot.isInboundHookConfigured ? 'configured' : 'missing'}
+                                    {snapshot.isInboundHookConfigured ? 'configured' : 'missing'} · public mail DNS{' '}
+                                    {snapshot.mailDnsDiagnostic.status === 'verified' ? 'verified' : 'needs attention'}
                                 </p>
                                 {snapshot.errorMessage ? (
                                     <p className="mt-2 max-w-4xl whitespace-pre-wrap text-xs">
@@ -111,13 +118,13 @@ export default async function AdminEmailServerPage() {
                         <DnsRecordsInstructions
                             description={
                                 <p>
-                                    Add these records at your DNS provider. Replace <code>&lt;VPS_PUBLIC_IP&gt;</code>{' '}
-                                    with the public address of this VPS.
+                                    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">
@@ -140,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>
+    );
+}