@promptbook/cli 0.113.0-9 → 0.114.0-1

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

@@ -0,0 +1,160 @@
+import { CheckCircle2, Mail, Server, TriangleAlert } from 'lucide-react';
+import { DnsRecordsInstructions } from '../../../components/DnsRecordsInstructions/DnsRecordsInstructions';
+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 {
+    isStalwartEmailSnapshotOperational,
+    readStalwartEmailSnapshot,
+} from '../../../utils/stalwart/readStalwartEmailSnapshot';
+import { AdminConfigurationShell } from '../_components/AdminConfigurationShell';
+import { $synchronizeStalwartEmailDomain } from './actions';
+
+/**
+ * Always reads live Stalwart and agent state.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Domain-level administration for the bundled Stalwart email service.
+ */
+export default async function AdminEmailServerPage() {
+    if (!(await isUserAdmin())) {
+        return <ForbiddenPage />;
+    }
+
+    const server = await $provideServer();
+    const snapshot = await readStalwartEmailSnapshot(server.publicUrl.hostname);
+    const dnsInstructions = createEmailDnsInstructions(snapshot.domain);
+    const isOperational = isStalwartEmailSnapshotOperational(snapshot);
+
+    return (
+        <AdminConfigurationShell activePage="email-server">
+            <div className="space-y-6">
+                <section
+                    className={`rounded-xl border p-5 ${
+                        isOperational
+                            ? 'border-emerald-200 bg-emerald-50 text-emerald-950'
+                            : 'border-amber-200 bg-amber-50 text-amber-950'
+                    }`}
+                >
+                    <div className="flex flex-col gap-4 md:flex-row md:items-center md:justify-between">
+                        <div className="flex items-start gap-3">
+                            {isOperational ? (
+                                <CheckCircle2 className="mt-0.5 h-5 w-5 text-emerald-600" />
+                            ) : (
+                                <TriangleAlert className="mt-0.5 h-5 w-5 text-amber-600" />
+                            )}
+                            <div>
+                                <h2 className="font-semibold">
+                                    {isOperational ? 'Agent email is operational' : 'Agent email needs attention'}
+                                </h2>
+                                <p className="mt-1 text-sm">
+                                    Domain <code>{snapshot.domain}</code> · API{' '}
+                                    {snapshot.isReachable ? 'reachable' : 'unavailable'} · bridge{' '}
+                                    {snapshot.isBridgeAccountConfigured ? 'configured' : 'missing'} · inbound hook{' '}
+                                    {snapshot.isInboundHookConfigured ? 'configured' : 'missing'}
+                                </p>
+                                {snapshot.errorMessage ? (
+                                    <p className="mt-2 max-w-4xl whitespace-pre-wrap text-xs">
+                                        {snapshot.errorMessage}
+                                    </p>
+                                ) : null}
+                            </div>
+                        </div>
+                        <StalwartSynchronizeButton
+                            label="Synchronize Stalwart"
+                            synchronize={$synchronizeStalwartEmailDomain}
+                        />
+                    </div>
+                </section>
+
+                <section className="rounded-xl border border-gray-200 bg-white p-5">
+                    <h2 className="flex items-center gap-2 text-lg font-semibold text-gray-900">
+                        <Mail className="h-5 w-5 text-gray-400" />
+                        Agent addresses
+                    </h2>
+                    <p className="mt-1 text-sm text-gray-500">
+                        Dotted, compact, permanent-id, and plus-tagged variants route to the same agent.
+                    </p>
+                    <div className="mt-4 divide-y divide-gray-100 rounded-lg border border-gray-200">
+                        {snapshot.agents.map((agent) => (
+                            <div key={agent.permanentId} className="grid gap-1 px-4 py-3 md:grid-cols-[1fr_2fr]">
+                                <div>
+                                    <p className="font-medium text-gray-900">{agent.displayName}</p>
+                                    <p className="text-xs text-gray-500">{agent.visibility}</p>
+                                </div>
+                                <div>
+                                    <code className="text-sm text-gray-800">{agent.preferredEmail}</code>
+                                    <p className="mt-1 break-all text-xs text-gray-500">
+                                        {agent.aliases.map((alias) => `${alias}@${snapshot.domain}`).join(', ')}
+                                    </p>
+                                </div>
+                            </div>
+                        ))}
+                        {snapshot.agents.length === 0 ? (
+                            <p className="px-4 py-5 text-sm text-gray-500">
+                                No active agents have email addresses yet.
+                            </p>
+                        ) : null}
+                    </div>
+                </section>
+
+                <section className="rounded-xl border border-gray-200 bg-white p-5">
+                    <h2 className="flex items-center gap-2 text-lg font-semibold text-gray-900">
+                        <Server className="h-5 w-5 text-gray-400" />
+                        Domain and DNS instructions
+                    </h2>
+                    <div className="mt-4">
+                        <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.
+                                </p>
+                            }
+                            domain={snapshot.domain}
+                            recordSelection="all"
+                            records={dnsInstructions}
+                        />
+                    </div>
+                    <div className="mt-4 space-y-2 rounded-lg bg-blue-50 p-4 text-sm text-blue-950">
+                        <p>
+                            <strong>DKIM:</strong> copy every DKIM record from Stalwart’s generated zone below. The
+                            selector and public key are generated by Stalwart and must not be invented.
+                        </p>
+                        <p>
+                            <strong>Reverse DNS / PTR:</strong> ask the VPS provider to map the sending IP to{' '}
+                            <code>mail.{snapshot.domain}</code>. Forward and reverse DNS must agree.
+                        </p>
+                        <p>
+                            <strong>MTA-STS:</strong> serve the policy below as plain text from{' '}
+                            <code>https://mta-sts.{snapshot.domain}/.well-known/mta-sts.txt</code> with a publicly
+                            trusted TLS certificate.
+                        </p>
+                        <p>
+                            <strong>SMTP TLS:</strong> after <code>mail.{snapshot.domain}</code> resolves publicly,
+                            configure Stalwart ACME certificate management or import a publicly trusted certificate for
+                            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>.
+                        </p>
+                    </div>
+                    <pre className="mt-4 overflow-auto whitespace-pre-wrap rounded-lg bg-gray-950 p-4 text-xs text-gray-100">
+                        {`version: STSv1\nmode: enforce\nmx: mail.${snapshot.domain}\nmax_age: 604800`}
+                    </pre>
+                    <h3 className="mt-5 text-sm font-semibold text-gray-900">Stalwart authoritative zone</h3>
+                    <pre className="mt-2 max-h-96 overflow-auto whitespace-pre-wrap rounded-lg bg-gray-950 p-4 text-xs text-gray-100">
+                        {snapshot.dnsZoneFile ||
+                            'Synchronize the domain and make the Stalwart API reachable to load generated DKIM and mail DNS records.'}
+                    </pre>
+                </section>
+            </div>
+        </AdminConfigurationShell>
+    );
+}

package/apps/agents-server/src/app/admin/files/FilesGalleryClient.tsx

@@ -7,17 +7,33 @@ import { FilesGalleryTable } from './FilesGalleryTable';
 import { FilesGalleryViewModeToggle } from './FilesGalleryViewModeToggle';
 import { useFilesGalleryState } from './useFilesGalleryState';
 
+/**
+ * Props accepted by `FilesGalleryClient`.
+ *
+ * @private client props of `/admin/files`
+ */
+type FilesGalleryClientProps = {
+    /**
+     * Whether the page header should keep the standalone top offset.
+     */
+    readonly isHeaderOffsetEnabled?: boolean;
+};
+
 /**
  * Handles files gallery client.
  */
-export function FilesGalleryClient() {
+export function FilesGalleryClient({ isHeaderOffsetEnabled = true }: FilesGalleryClientProps) {
     const { formatText } = useAgentNaming();
     const { language } = useServerLanguage();
     const filesGalleryState = useFilesGalleryState();
 
     return (
-        <div className="container mx-auto px-4 py-8 space-y-6">
-            <div className="flex justify-between items-center mt-20 mb-4">
+        <>
+            <div
+                className={`flex justify-between items-center mb-4 ${
+                    isHeaderOffsetEnabled ? 'mt-20' : ''
+                }`.trim()}
+            >
                 <h1 className="text-3xl text-gray-900 font-light">Files Gallery</h1>
                 <FilesGalleryViewModeToggle
                     viewMode={filesGalleryState.viewMode}
@@ -34,7 +50,10 @@ export function FilesGalleryClient() {
                     isLoading={filesGalleryState.isLoading}
                     page={filesGalleryState.page}
                     limit={filesGalleryState.limit}
+                    sortBy={filesGalleryState.sortBy}
+                    sortOrder={filesGalleryState.sortOrder}
                     handlePageChange={filesGalleryState.handlePageChange}
+                    handleSortChange={filesGalleryState.handleSortChange}
                 />
             ) : (
                 <FilesGalleryGrid
@@ -46,6 +65,6 @@ export function FilesGalleryClient() {
                     observerTarget={filesGalleryState.observerTarget}
                 />
             )}
-        </div>
+        </>
     );
 }

package/apps/agents-server/src/app/admin/files/FilesGalleryGrid.tsx

@@ -3,7 +3,10 @@ import Link from 'next/link';
 import type { ServerLanguageCode } from '../../../languages/ServerLanguageRegistry';
 import { buildAgentProfileHref } from '../../../utils/agentRouting/agentRouteHrefs';
 import { formatServerLanguageHumanReadableDate } from '../../../utils/localization/formatServerLanguageHumanReadableDate';
+import { formatResourceBytes } from '../../../utils/resourceMonitor/formatResourceMonitorValue';
+import { resolveFilesGalleryFileHref } from './filesGalleryLinks';
 import { FilesGalleryStatusBadge } from './FilesGalleryStatusBadge';
+import type { FileWithAgent } from './filesGalleryTypes';
 import type { UseFilesGalleryState } from './useFilesGalleryState';
 
 /**
@@ -21,13 +24,6 @@ type FilesGalleryGridProps = Pick<UseFilesGalleryState, 'files' | 'isLoading' |
     readonly language: ServerLanguageCode;
 };
 
-/**
- * Formats one file size for the compact grid view.
- */
-function formatFilesGalleryCompactFileSize(fileSize: number): string {
-    return `${(fileSize / 1024).toFixed(1)} KB`;
-}
-
 /**
  * Renders the grid view of the files gallery, including infinite-scroll feedback.
  *
@@ -44,60 +40,47 @@ export function FilesGalleryGrid({
     return (
         <>
             <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 xl:grid-cols-5 gap-4">
-                {files.map((file) => (
-                    <div
-                        key={file.id}
-                        className="group relative border rounded-lg overflow-hidden bg-white shadow-sm hover:shadow-md transition-shadow"
-                    >
-                        <a
-                            href={file.storageUrl || '#'}
-                            target="_blank"
-                            rel="noopener noreferrer"
-                            className="block aspect-square relative bg-gray-100 flex items-center justify-center"
+                {files.map((file) => {
+                    const fileHref = resolveFilesGalleryFileHref(file);
+
+                    return (
+                        <div
+                            key={file.id}
+                            className="group relative border rounded-lg overflow-hidden bg-white shadow-sm hover:shadow-md transition-shadow"
                         >
-                            {file.fileType.startsWith('image/') && file.storageUrl ? (
-                                /* eslint-disable-next-line @next/next/no-img-element */
-                                <img
-                                    src={file.storageUrl}
-                                    alt={file.fileName}
-                                    className="object-cover w-full h-full transition-transform duration-300 group-hover:scale-105"
-                                    loading="lazy"
-                                />
-                            ) : (
-                                <File className="w-16 h-16 text-gray-400" />
-                            )}
-                        </a>
-                        <div className="p-3">
-                            <div className="flex items-center justify-between gap-2 mb-1">
-                                {file.agent ? (
-                                    <Link
-                                        href={buildAgentProfileHref(file.agent.permanentId || file.agent.agentName)}
-                                        className="text-xs font-medium text-blue-600 hover:underline truncate"
-                                    >
-                                        {file.agent.agentName}
-                                    </Link>
-                                ) : (
-                                    <span className="text-xs text-gray-400">{formatText('No agent')}</span>
-                                )}
-                                <span className="text-[10px] text-gray-400 whitespace-nowrap">
-                                    {formatServerLanguageHumanReadableDate(file.createdAt, language)}
-                                </span>
-                            </div>
-                            <p className="text-xs text-gray-600 truncate" title={file.fileName}>
-                                {file.fileName}
-                            </p>
-                            <div className="mt-1 flex justify-between items-center">
-                                <span className="text-[10px] text-gray-500">
-                                    {formatFilesGalleryCompactFileSize(file.fileSize)}
-                                </span>
-                                <FilesGalleryStatusBadge
-                                    status={file.status}
-                                    className="px-1.5 py-0.5 rounded-full text-[10px] font-medium"
-                                />
+                            <FilesGalleryGridPreview file={file} fileHref={fileHref} />
+                            <div className="p-3">
+                                <div className="flex items-center justify-between gap-2 mb-1">
+                                    {file.agent ? (
+                                        <Link
+                                            href={buildAgentProfileHref(file.agent.permanentId || file.agent.agentName)}
+                                            className="text-xs font-medium text-blue-600 hover:underline truncate"
+                                        >
+                                            {file.agent.agentName}
+                                        </Link>
+                                    ) : (
+                                        <span className="text-xs text-gray-400">{formatText('No agent')}</span>
+                                    )}
+                                    <span className="text-[10px] text-gray-400 whitespace-nowrap">
+                                        {formatServerLanguageHumanReadableDate(file.createdAt, language)}
+                                    </span>
+                                </div>
+                                <p className="text-xs text-gray-600 truncate" title={file.fileName}>
+                                    {file.fileName}
+                                </p>
+                                <div className="mt-1 flex justify-between items-center">
+                                    <span className="text-[10px] text-gray-500">
+                                        {formatResourceBytes(file.fileSize)}
+                                    </span>
+                                    <FilesGalleryStatusBadge
+                                        status={file.status}
+                                        className="px-1.5 py-0.5 rounded-full text-[10px] font-medium"
+                                    />
+                                </div>
                             </div>
                         </div>
-                    </div>
-                ))}
+                    );
+                })}
             </div>
 
             {files.length === 0 && !isLoading && <div className="text-center text-gray-500 py-12">No files found.</div>}
@@ -109,3 +92,88 @@ export function FilesGalleryGrid({
         </>
     );
 }
+
+/**
+ * Props accepted by `FilesGalleryGridPreview`.
+ *
+ * @private type of <FilesGalleryGrid/>
+ */
+type FilesGalleryGridPreviewProps = {
+    /**
+     * File rendered in the gallery card.
+     */
+    readonly file: FileWithAgent;
+
+    /**
+     * Resolved public file URL, or `null` when the row has no usable URL.
+     */
+    readonly fileHref: string | null;
+};
+
+/**
+ * Renders the square preview/open target for one grid card.
+ *
+ * @param props - Preview props.
+ * @returns Linked or static preview tile.
+ * @private function of <FilesGalleryGrid/>
+ */
+function FilesGalleryGridPreview({ file, fileHref }: FilesGalleryGridPreviewProps) {
+    const preview = <FilesGalleryGridPreviewContent file={file} fileHref={fileHref} />;
+
+    if (!fileHref) {
+        return (
+            <div className="block aspect-square relative bg-gray-100 flex items-center justify-center">{preview}</div>
+        );
+    }
+
+    return (
+        <a
+            href={fileHref}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="block aspect-square relative bg-gray-100 flex items-center justify-center"
+        >
+            {preview}
+        </a>
+    );
+}
+
+/**
+ * Props accepted by `FilesGalleryGridPreviewContent`.
+ *
+ * @private type of <FilesGalleryGrid/>
+ */
+type FilesGalleryGridPreviewContentProps = {
+    /**
+     * File rendered in the gallery card.
+     */
+    readonly file: FileWithAgent;
+
+    /**
+     * Resolved public file URL, or `null` when the row has no usable URL.
+     */
+    readonly fileHref: string | null;
+};
+
+/**
+ * Renders either the image thumbnail or a generic file icon.
+ *
+ * @param props - Preview content props.
+ * @returns Preview content.
+ * @private function of <FilesGalleryGrid/>
+ */
+function FilesGalleryGridPreviewContent({ file, fileHref }: FilesGalleryGridPreviewContentProps) {
+    if (file.fileType.startsWith('image/') && fileHref) {
+        return (
+            /* eslint-disable-next-line @next/next/no-img-element */
+            <img
+                src={fileHref}
+                alt={file.fileName}
+                className="object-cover w-full h-full transition-transform duration-300 group-hover:scale-105"
+                loading="lazy"
+            />
+        );
+    }
+
+    return <File className="w-16 h-16 text-gray-400" />;
+}

package/apps/agents-server/src/app/admin/files/FilesGalleryStatusBadge.tsx

@@ -1,4 +1,4 @@
-import type { FileWithAgent } from './actions';
+import type { FileWithAgent } from './filesGalleryTypes';
 
 /**
  * Props for FilesGalleryStatusBadge.