sounding 0.0.2 → 0.0.4

package/README.md

@@ -28,15 +28,28 @@ Sounding also owns its own built-in world engine, so the same package can:
 - capture outgoing mail by wrapping `sails.helpers.mail.send` and storing normalized messages in `sails.sounding.mailbox`
 
 The default configuration story is intentionally calm:
-- Sounding disables its hook automatically when Sails runs in `production`
-- set `sounding.enableInProduction = true` only for controlled production-like environments such as staging
+- Sounding only enables its hook in the environments listed under `sounding.environments`
+- the default is `['test']`, so non-test boot paths stay dark unless you opt in explicitly
+- if you intentionally need Sounding in another environment, add that environment name to the list
 - auth conventions auto-detect `User`/`userId` and `Creator`/`creatorId`, with `sounding.auth` available for overrides
 - Sounding manages a temporary `sails-sqlite` datastore by default
 - managed SQLite artifacts live under `.tmp/db`
 - the default datastore identity is `default`
 - browser projects start with `desktop`
+- mail capture previews use the `mail` layout by default, matching the current `sails-hook-mail` convention
+- apps with a different mail layout can set `sounding.mail.layout`, for example `layout-email`
 - `inherit` remains available when an app already has a serious test datastore story
 
+For example:
+
+```js
+module.exports.sounding = {
+  environments: ['test'],
+}
+```
+
+If you intentionally want Sounding during another boot path, widen the list explicitly, for example `['test', 'console']` or `['test', 'production']`.
+
 This repository starts with docs-driven product research and the first hook/runtime scaffolding for that vision.
 
 See `RESEARCH.md`.

package/index.js

@@ -14,12 +14,22 @@ const { createExpect } = require('./lib/create-expect')
 const { createTestApi } = require('./lib/create-test-api')
 const { getDefaultConfig } = require('./lib/default-config')
 
-function isProductionEnvironment(sails) {
-  return (sails.config?.environment || process.env.NODE_ENV) === 'production'
+function getCurrentEnvironment(sails) {
+  return sails.config?.environment || process.env.NODE_ENV
+}
+
+function getEnabledEnvironments(sails) {
+  const configured = sails.config?.sounding?.environments
+
+  if (Array.isArray(configured)) {
+    return configured
+  }
+
+  return getDefaultConfig().environments
 }
 
 function shouldEnableHook(sails) {
-  return sails.config?.sounding?.enableInProduction === true || !isProductionEnvironment(sails)
+  return getEnabledEnvironments(sails).includes(getCurrentEnvironment(sails))
 }
 
 function soundingHook(sails) {
@@ -27,6 +37,7 @@ function soundingHook(sails) {
 
   return {
     defaults: {
+      // Hook defaults live under `sails.config.sounding`.
       sounding: getDefaultConfig(),
     },
 

package/lib/create-mail-capture.js

@@ -1,6 +1,8 @@
 const path = require('node:path')
 const url = require('node:url')
 
+const DEFAULT_MAIL_LAYOUT = 'mail'
+
 function normalizeList(value) {
   if (value === undefined || value === null || value === '') {
     return []
@@ -62,22 +64,21 @@ function createRenderViewPromise(view) {
   return Promise.resolve(view)
 }
 
-async function renderTemplatePreview(sails, {
-  template,
-  templateData = {},
-  layout = 'layout-email',
-}) {
+async function renderTemplatePreview(sails, inputs = {}, options = {}) {
+  const { template, templateData = {} } = inputs
+
   if (!template || typeof sails?.renderView !== 'function') {
     return undefined
   }
 
+  const resolvedLayout = resolvePreviewLayout(sails, inputs, options)
   const emailTemplatePath = path.join('emails/', template)
   let emailTemplateLayout = false
 
-  if (layout) {
+  if (resolvedLayout) {
     emailTemplateLayout = path.relative(
       path.dirname(emailTemplatePath),
-      path.resolve('layouts/', layout)
+      path.resolve('layouts/', resolvedLayout)
     )
   }
 
@@ -94,6 +95,31 @@ function resolveMailConfig(sails) {
   return sails?.config?.mail || {}
 }
 
+function resolveSoundingMailConfig(sails, options = {}) {
+  if (options.mailSettings) {
+    return options.mailSettings
+  }
+
+  const soundingConfig =
+    options.soundingConfig || options.config || sails?.config?.sounding || {}
+
+  return soundingConfig.mail || {}
+}
+
+function resolvePreviewLayout(sails, inputs = {}, options = {}) {
+  if (Object.prototype.hasOwnProperty.call(inputs, 'layout')) {
+    return inputs.layout
+  }
+
+  const mailSettings = resolveSoundingMailConfig(sails, options)
+
+  if (Object.prototype.hasOwnProperty.call(mailSettings, 'layout')) {
+    return mailSettings.layout
+  }
+
+  return DEFAULT_MAIL_LAYOUT
+}
+
 function resolveMailerName(sails, inputs = {}) {
   return inputs.mailer || process.env.MAIL_MAILER || resolveMailConfig(sails).default
 }
@@ -125,10 +151,11 @@ function toErrorShape(error) {
   }
 }
 
-async function buildCapturedMail(sails, inputs = {}) {
+async function buildCapturedMail(sails, inputs = {}, options = {}) {
   const mailer = resolveMailerName(sails, inputs)
   const transport = resolveTransportName(sails, mailer)
-  const html = await renderTemplatePreview(sails, inputs)
+  const layout = resolvePreviewLayout(sails, inputs, options)
+  const html = await renderTemplatePreview(sails, inputs, options)
   const links = extractLinks(html)
 
   return {
@@ -150,7 +177,7 @@ async function buildCapturedMail(sails, inputs = {}) {
     ctaUrl: resolvePrimaryLink(inputs, links),
     attachments: inputs.attachments || [],
     headers: inputs.headers || {},
-    layout: inputs.layout === undefined ? 'layout-email' : inputs.layout,
+    layout,
   }
 }
 
@@ -173,6 +200,12 @@ function createMailCapture({ sails, mailbox, getConfig }) {
     return settings.deliver === true || settings.mode === 'passthrough'
   }
 
+  function resolveMessageLayout(inputs = {}) {
+    return resolvePreviewLayout(sails, inputs, {
+      mailSettings: resolveMailSettings(),
+    })
+  }
+
   function wrapDeferred(executor, onRejected) {
     let promise = Promise.resolve().then(executor)
 
@@ -267,7 +300,9 @@ function createMailCapture({ sails, mailbox, getConfig }) {
 
   async function captureSuccessfulSend(inputs = {}) {
     try {
-      const message = await buildCapturedMail(sails, inputs)
+      const message = await buildCapturedMail(sails, inputs, {
+        mailSettings: resolveMailSettings(),
+      })
       mailbox.capture({
         ...message,
         status: 'sent',
@@ -279,6 +314,7 @@ function createMailCapture({ sails, mailbox, getConfig }) {
         to: normalizeList(inputs.to),
         subject: inputs.subject || '',
         template: inputs.template,
+        layout: resolveMessageLayout(inputs),
         status: 'sent',
         captureError: toErrorShape(error),
       })
@@ -289,7 +325,9 @@ function createMailCapture({ sails, mailbox, getConfig }) {
     let message
 
     try {
-      message = await buildCapturedMail(sails, inputs)
+      message = await buildCapturedMail(sails, inputs, {
+        mailSettings: resolveMailSettings(),
+      })
     } catch (captureError) {
       message = {
         mailer: resolveMailerName(sails, inputs),
@@ -297,6 +335,7 @@ function createMailCapture({ sails, mailbox, getConfig }) {
         to: normalizeList(inputs.to),
         subject: inputs.subject || '',
         template: inputs.template,
+        layout: resolveMessageLayout(inputs),
         captureError: toErrorShape(captureError),
       }
     }
@@ -388,4 +427,5 @@ module.exports = {
   normalizeList,
   resolvePrimaryLink,
   renderTemplatePreview,
+  resolvePreviewLayout,
 }

package/lib/default-config.js

@@ -1,5 +1,7 @@
 const DEFAULT_CONFIG = Object.freeze({
-  enableInProduction: false,
+  // Sails environments where the Sounding hook should boot.
+  // Keep this test-only by default so non-test processes stay dark.
+  environments: ['test'],
   app: {
     path: '.',
     environment: 'test',
@@ -28,6 +30,7 @@ const DEFAULT_CONFIG = Object.freeze({
   },
   mail: {
     capture: true,
+    layout: 'mail',
   },
   request: {
     transport: 'virtual',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sounding",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Testing framework for Sails applications and The Boring JavaScript Stack.",
   "main": "index.js",
   "license": "MIT",