domma-cms 0.116.1 → 0.116.3

package/admin/js/templates/docs/usage-navigation.html

@@ -80,14 +80,32 @@
                   <p>The <code>admin-sidebar</code> menu is this sidebar. In the Menus editor you can move Tools
                       between folders, rename them, hide them or add links of your own. Dashboard, Menus, Users and
                       My Profile can be moved but never hidden, so you can always get back from a bad edit.</p>
-                  <p>Folders can hold folders. The built-in Tools come in a <strong>Core</strong> group inside Tools;
-                      move a Tool out of it, or move the whole group, and your arrangement is kept. A group that
+                  <p>Folders can hold folders. Tools start in groups inside Tools by what they are for -
+                      Productivity, Communication, Marketing, Publishing, Business and Maintenance (a site set up
+                      before 0.103 may still have a <strong>Core</strong> group); move a Tool out of its group, or
+                      move the whole group, and your arrangement is kept. A group that
                       nothing of yours has been saved into is not stored - it is made again when the sidebar draws,
                       and a user who may use none of its Tools does not see it. <strong>Back to its default
                       place</strong> on a Tool puts it back in its group. Each folder remembers whether you left it
                       open or closed on its own, so closing Tools &gt; Core does not close a project that is also
                       called Core.</p>
 
+                  <h3>Counts on the sidebar</h3>
+                  <p>A Tool's badge shows what needs attention - unread messages, late tasks - in red when
+                      something is late. When nothing does, it shows a plain count instead of a blank: Todo the
+                      tasks done, Analytics today's page views, Booking the bookings in the next seven days, the
+                      Shop its products. Hover a badge for what it means. Those plain counts are left out of a
+                      closed folder's total, so a folder's number still only adds up what needs you.</p>
+
+                  <h3>Resize or fold the sidebar</h3>
+                  <p>Drag the sidebar's right edge (mouse, touch or pen) to make it wider or narrower;
+                      double-click the edge to put it back. From the keyboard, focus the edge: the arrow keys
+                      change the width (with Shift for bigger steps), Home and End go to the narrowest and widest,
+                      and Enter folds it. The chevron in the sidebar header - or dragging the edge past its
+                      narrowest - folds it to a rail of icons: hover or focus one for its name and what its
+                      count means, and click a folder to open its contents beside the rail. The width and whether
+                      it is folded are remembered in this browser.</p>
+
                   <h3>Arrange the sidebar in place</h3>
                   <p>You can also rearrange the sidebar without leaving the page you are on. Click the six-dot
                       button at the top of the sidebar, beside the site name, to turn on <strong>Arrange</strong>.

package/admin/js/templates/docs/usage-pages.html

@@ -81,6 +81,18 @@ Your Markdown content goes here.</code></pre>
                       project answers 404 to everyone. See <a href="#/docs/usage/users-roles">Users &amp;
                       Roles</a> for how the role ladder works.</p>
 
+                  <h3>Projects</h3>
+                  <p>A page belongs to a project - the <code>project</code> field, or its URL's. To remove a
+                      project and everything filed under it - its pages with their versions and share links,
+                      collections and their entries, forms, blocks, views, components, actions, menus, API
+                      endpoints and tokens - open <strong>Projects &gt; (the project) &gt; Settings</strong> and
+                      choose <strong>Delete with contents</strong>. It lists exactly what will go and asks you to
+                      type the project's slug back; links to its pages leave every other menu. Nothing is touched
+                      while a user or role is filed under the project (people are never deleted with content), while
+                      one of its menus fills a site slot such as the navbar, or while a built-in collection is filed
+                      under it. A starter's example pages show
+                      <strong>Remove sample content</strong> on the project's overview, which does the same.</p>
+
                   <h3>Navigation</h3>
                   <p>A page is added to the navbar or footer in <strong>Content &gt; Menus</strong>, not in the page
                       editor. See <a href="#/docs/usage/navigation">Navigation</a>.</p>

package/admin/js/templates/docs/usage-shortcodes.html

@@ -946,6 +946,18 @@ Body content in **Markdown** is supported.
                       <code>[christmas /]</code>; <code>[christmas snow-only="true" /]</code> is just the falling snow). Many can also be added to a card, box, hero, banner, column or
                       button as attributes: <code>[card reveal reveal-animation="zoom"]</code>. Settings are at
                       <strong>System &gt; Effects</strong>.</p>
+                  <p><code>[celebrate character="robin" /]</code> puts one character on a page at any time of year,
+                      whatever the theme or date: <code>elf</code>, <code>leprechaun</code>, <code>bagpiper</code>,
+                      <code>knight</code>, <code>dragon</code>, <code>welsh-dragon</code>, <code>cupid</code>,
+                      <code>robin</code>, <code>snowman</code> and a few cheekier ones. <code>size</code> is
+                      <code>small</code>, <code>medium</code> (the default), <code>large</code>,
+                      <code>xlarge</code> or a height in pixels; <code>animate="false"</code> keeps it still.
+                      Christmas has two naughty elves and St Patrick's a leprechaun scene, all off unless you ask
+                      for them (<code>peeing-elf</code>, <code>thieving-elf</code>, <code>mooning-elf</code>,
+                      <code>mooning-leprechaun</code>, each <code>="true"</code>).</p>
+                  <p>In the page editor, right-click and open <strong>Celebrations</strong> to insert any seasonal
+                      theme, butterflies, ticker tape or fireworks. Right-click an existing one to switch its
+                      parts on and off - Christmas's snow only, or each decoration.</p>
 
                   <h3>Actions on pages</h3>
                   <p><code>[cta action="..." entry="..."]Label[/cta]</code> places a button that runs a CMS Action

package/admin/js/templates/docs/usage-site-settings.html

@@ -23,7 +23,10 @@
                           <td>General</td>
                           <td>Site title and tagline; <strong>Site URL</strong> (the site's real address, used for
                               password reset links, canonical links and the sitemap - set it); <strong>Admin
-                              home</strong> (the screen the admin opens on); the default spacer size.</td>
+                              home</strong> (the screen the admin opens on); the default spacer size. The
+                              browser-tab icon is the brand logo, or the first letter of the site's name when there
+                              is none (a <code>favicon</code> in <code>config/site.json</code> takes first
+                              place).</td>
                       </tr>
                       <tr>
                           <td>SEO</td>

package/admin/js/templates/docs/usage-tools.html

@@ -7,8 +7,14 @@
   <div class="col-12">
     <div class="docs-body">
 
-<p>Contacts, Notes, Todo, Analytics and SEO are part of the CMS. They sit together in a <strong>Core</strong>
-                      group inside the sidebar's Tools folder (<strong>Tools &gt; Core &gt; Notes</strong>) and are on unless you switch them off at the top of the Marketplace (<strong>System &gt;
+<p>Contacts, Notes, Todo, Calculator, Analytics and SEO are part of the CMS. In the sidebar's Tools folder
+                      they start in groups by what they are for, alongside the Marketplace Tools:
+                      <strong>Productivity</strong> (Notes, Todo, Calculator, Calendar), <strong>Communication</strong>
+                      (Contacts, email, Messages), <strong>Marketing</strong> (Analytics, SEO, Feedback),
+                      <strong>Publishing</strong>, <strong>Business</strong> and <strong>Maintenance</strong>, so
+                      Notes is at <strong>Tools &gt; Productivity &gt; Notes</strong>. Anything you have already
+                      arranged stays where you put it - a site set up earlier may still have them in a
+                      <strong>Core</strong> group. They are on unless you switch them off at the top of the Marketplace (<strong>System &gt;
                       Plugins</strong>). Switching a Tool off hides it and stops its screens and API; nothing is
                       deleted. Who may use each is a permission under <strong>System &gt; Roles</strong> (Tools
                       group): the level-0 role and Admin have them all to begin with (Admin is given them once -
@@ -83,7 +89,10 @@
                   <p>How the site looks to search engines: an audit of every page with a score, each page's search
                       result and share card as they will look, titles and descriptions used twice, redirects (added
                       for you when a page is renamed), the sitemap and robots.txt, and who runs the site. SEO Pro
-                      adds a not-found log, a link monitor and SEO history.</p>
+                      (Marketplace) adds Google Search Console in the admin - searches, clicks and positions, and
+                      your sitemap sent to Google by hand or once a day after pages change - verification codes,
+                      IndexNow, page speed, rich results, sitemap rules, a not-found log, a link monitor and SEO
+                      history. Its own guide is under <a href="#/docs/plugins">Plugin guides</a>.</p>
 
                   <h3>Notifications</h3>
                   <p>The bell in the admin, and <strong>System &gt; Notifications</strong>. Opening the screen marks
@@ -97,14 +106,23 @@
                       open never appears, nor do drafts, <code>noindex</code> pages or pages in a disabled
                       project.</p>
 
+                  <h3>Support</h3>
+                  <p>Every site has <strong>Support</strong> in the sidebar: Domma's email, phone and hours always
+                      to hand, and <strong>Ask for help</strong> to start a conversation with the Domma team -
+                      normal or urgent. Replies appear in the admin, with a count on the sidebar badge, and by
+                      email. Right-click a request (or use its ⋮ button, or Shift+F10) to mark it read or resolved,
+                      archive it or remove it from the list. On a site Domma does not host, Support shows the
+                      contact card and an email link only.</p>
+
                   <h3>Plugins</h3>
-                  <p>Tools from the Marketplace (Calendar, Blog, Feedback, Mail Reader and others) sit directly in
-                      the Tools folder when switched on, beside the Core group, unless the plugin names a group of
-                      its own. See <a href="#/docs/plugins">Plugin guides</a> for each one you have
+                  <p>Tools from the Marketplace (Calendar, Booking, Blog, Feedback, Mail Reader and others) join
+                      the same groups in the Tools folder when switched on; one the CMS does not know sits
+                      directly in Tools unless the plugin names a group of its own. See <a href="#/docs/plugins">Plugin guides</a> for each one you have
                       installed, and <a href="#/docs/usage/plugins">Plugins</a> for installing and switching.</p>
 
 
-<section><h3>Calculator</h3><p>Choose Floating to keep Calculator alongside your work, or Standard to open its own page. Both offer Basic and Scientific layouts. Use the settings cog in the card header to choose the layout, accent colour, angle units and floating position, or drag the floating card header. MC clears memory, MR recalls it, MS stores the current value, and M+/M− add or subtract from memory. The display previews valid calculations as you type. Scientific functions support degrees or radians. Preferences are remembered in this browser.</p></section>
+                  <h3>Calculator</h3>
+                  <p>Choose Floating to keep Calculator alongside your work, or Standard to open its own page. Both offer Basic and Scientific layouts. Use the settings cog in the card header to choose the layout, accent colour, angle units and floating position, or drag the floating card header. MC clears memory, MR recalls it, MS stores the current value, and M+/M− add or subtract from memory. The display previews valid calculations as you type. Scientific functions support degrees or radians. Preferences are remembered in this browser.</p>
 
     </div>
   </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domma-cms",
-  "version": "0.116.1",
+  "version": "0.116.3",
   "description": "File-based CMS powered by Domma and Fastify. Run npx domma-cms my-site to create a new project.",
   "type": "module",
   "main": "server/server.js",

package/plugins/_lib/mail/imapPool.js

@@ -206,7 +206,7 @@ export function createPool(config) {
             } catch {
                 // Already down - nothing to close.
             }
-            return {ok: false, error: describeError(err)};
+            return {ok: false, error: describeError(err, connection)};
         }
     }
 
@@ -261,19 +261,52 @@ export function createPool(config) {
 }
 
 /**
- * Turn an IMAP/network error into something worth showing a user.
+ * Turn an IMAP/SMTP/network error into something worth showing a user.
  *
  * ImapFlow's own messages are decent but its auth failures surface as raw
- * server responses, which vary by server and read like a stack trace.
+ * server responses, which vary by server and read like a stack trace. TLS
+ * failures are worse: OpenSSL's text ("…:tls_validate_record_header:wrong
+ * version number:…") names nothing the user can change. nodemailer also wraps
+ * every socket error as `ESOCKET`, dropping the TLS code, so those are
+ * recognised by `reason`/message as well as by code.
  *
- * @param   {Error & {code?: string, authenticationFailed?: boolean}} err
+ * @param   {Error & {code?: string, reason?: string, authenticationFailed?: boolean}} err
+ * @param   {{host?: string, port?: number, secure?: boolean}} [connection] - what was tried, so the message can name it
  * @returns {string}
  */
-export function describeError(err) {
+export function describeError(err, connection = {}) {
     if (!err) return 'Unknown error.';
-    if (err.authenticationFailed) return 'The mail server rejected that username and password.';
+    if (err.authenticationFailed || err.code === 'EAUTH') return 'The mail server rejected that username and password.';
 
-    switch (err.code) {
+    const host = connection.host || 'The mail server';
+    const port = connection.port ? `Port ${connection.port}` : 'That port';
+    const text = `${err.reason || ''} ${err.message || ''}`;
+
+    // Implicit TLS against a port that starts in plain text (587, 143, 25):
+    // the "server hello" is a greeting line, which OpenSSL reads as a bad version.
+    if (err.code === 'ERR_SSL_WRONG_VERSION_NUMBER' || /wrong version number/i.test(text)) {
+        return connection.secure
+            ? `${port} does not start with TLS, so Implicit TLS must be off for it - ports 587 and 143 switch to TLS with STARTTLS. Untick Implicit TLS, or use the implicit-TLS port (465 to send, 993 to read).`
+            : `${port} answered in a different TLS mode from the one chosen. Check the port and the Implicit TLS setting.`;
+    }
+    if (['DEPTH_ZERO_SELF_SIGNED_CERT', 'SELF_SIGNED_CERT_IN_CHAIN'].includes(err.code) || /self[- ]signed certificate/i.test(text)) {
+        return `${host === 'The mail server' ? 'The mail server’s' : `${host}’s`} TLS certificate is self-signed, so the server cannot prove who it is. `
+            + `Install a trusted certificate (Let’s Encrypt, for example) that covers this hostname on the mail server. `
+            + `For a server you control, the plugin’s allowInsecureTLS setting accepts it instead.`;
+    }
+    if (err.code === 'ERR_TLS_CERT_ALTNAME_INVALID' || /altnames|does not match certificate/i.test(text)) {
+        return `The mail server’s TLS certificate does not cover ${connection.host || 'that hostname'}. Use the hostname the certificate was issued for, or reissue it to include this one.`;
+    }
+    if (err.code === 'CERT_HAS_EXPIRED' || /certificate has expired/i.test(text)) {
+        return 'The mail server’s TLS certificate has expired. It needs renewing on the server.';
+    }
+    if (['UNABLE_TO_VERIFY_LEAF_SIGNATURE', 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY'].includes(err.code) || /unable to (verify the first certificate|get local issuer)/i.test(text)) {
+        return 'The mail server’s TLS certificate could not be verified - it is missing its intermediate certificate, or was issued by an authority this server does not trust.';
+    }
+
+    // nodemailer reports these as ESOCKET/EDNS; the system code survives only in the message.
+    const netCode = text.match(/\b(ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ETIMEDOUT|ECONNRESET)\b/)?.[1] ?? err.code;
+    switch (netCode) {
         case 'ENOTFOUND':
         case 'EAI_AGAIN':
             return 'That mail server hostname could not be resolved.';
@@ -282,11 +315,6 @@ export function describeError(err) {
         case 'ETIMEDOUT':
         case 'ECONNRESET':
             return 'The mail server did not respond in time.';
-        case 'CERT_HAS_EXPIRED':
-        case 'DEPTH_ZERO_SELF_SIGNED_CERT':
-        case 'SELF_SIGNED_CERT_IN_CHAIN':
-        case 'ERR_TLS_CERT_ALTNAME_INVALID':
-            return 'The mail server’s TLS certificate could not be verified.';
         default:
             return err.message || 'The mail server connection failed.';
     }

package/plugins/_lib/mail/send.js

@@ -13,6 +13,7 @@ import {createRequire} from 'node:module';
 import nodemailer from 'nodemailer';
 
 import {bareAddress, formatFrom} from '../admin/mail/identity.js';
+import {describeError} from './imapPool.js';
 import {normalisePriority, priorityHeaders} from './priority.js';
 
 // MailComposer is not on nodemailer's public export, but it is the piece that
@@ -389,7 +390,7 @@ export async function verifySmtp(transportConfig, allowInsecureTLS = false) {
         await transport.verify();
         return {ok: true};
     } catch (err) {
-        return {ok: false, error: err.message};
+        return {ok: false, error: describeError(err, transportConfig)};
     } finally {
         transport.close();
     }