@promptbook/cli 0.114.0-5 → 0.114.0-50

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/run-e2e-tests.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const path = require('node:path');
-const { runNpm } = require('./run-npm.js');
+const { runNpm, startNpm, startNpmWithCollectedOutput } = require('./run-npm.js');
 
 /**
  * Root directory of the Agents Server app.
@@ -11,17 +11,30 @@ const APP_ROOT = path.resolve(__dirname, '..');
 /**
  * Runs the complete Agents Server E2E verification flow.
  *
- * App linting remains an explicit test phase. The production build then skips
- * its duplicate lint pass, and Playwright starts that same build instead of
- * compiling a second `.next-e2e` output through `webServer`.
+ * 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`.
  */
-function runE2eTests() {
+async function runE2eTests() {
     const commandOptions = {
         cwd: APP_ROOT,
     };
 
-    runNpm(['run', 'lint'], commandOptions);
-    runNpm(['run', 'build-e2e', '--', '--no-lint'], commandOptions);
+    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,
@@ -31,4 +44,4 @@ function runE2eTests() {
     });
 }
 
-runE2eTests();
+void runE2eTests();

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/about/page.tsx

@@ -30,7 +30,7 @@ import { Card } from '../../../components/Homepage/Card';
 import { Section } from '../../../components/Homepage/Section';
 import { isUserAdmin } from '../../../utils/isUserAdmin';
 import { getSession } from '../../../utils/session';
-import { listRegisteredServersUsingServiceRole } from '../../../utils/serverRegistry';
+import { listRegisteredServersUsingServiceRole } from '../../../utils/serverRegistryNode';
 
 /**
  * Constant for promptbook about text.

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">