sounding 0.0.1 → 0.0.3

package/README.md

@@ -14,6 +14,8 @@ The canonical Sails-native surface is:
 - `sails.sounding`
 - `sails.helpers.user.signupWithTeam(...)` inside trials
 - `get('/api/issues')` or `sails.sounding.request.get('/api/issues')` inside endpoint-style trials
+- `await auth.login.withPassword('creator@example.com', page, { password: 'secret123' })` inside browser trials
+- `await auth.request.withPassword('creator@example.com', { password: 'secret123' })` inside request trials
 - request helpers default to Sails virtual requests powered by `sails.request()`
 - Inertia-style visits can use `visit('/pricing')` and partial reload options like `{ component, only }`
 - a trial can opt into stricter parity with `test('...', { transport: 'http' }, ...)`
@@ -26,12 +28,26 @@ 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 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`
 - `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,15 +14,38 @@ const { createExpect } = require('./lib/create-expect')
 const { createTestApi } = require('./lib/create-test-api')
 const { getDefaultConfig } = require('./lib/default-config')
 
+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 getEnabledEnvironments(sails).includes(getCurrentEnvironment(sails))
+}
+
 function soundingHook(sails) {
   const runtime = createRuntime(sails)
 
   return {
     defaults: {
+      // Hook defaults live under `sails.config.sounding`.
       sounding: getDefaultConfig(),
     },
 
     configure() {
+      if (!shouldEnableHook(sails)) {
+        return
+      }
+
       sails.hooks ||= {}
       sails.sounding = runtime
       sails.hooks.sounding = this
@@ -30,6 +53,10 @@ function soundingHook(sails) {
     },
 
     initialize(done) {
+      if (!shouldEnableHook(sails)) {
+        return done()
+      }
+
       sails.sounding = runtime
       Object.assign(this, runtime)
       sails.hooks.sounding = this

package/lib/create-auth-helpers.js

@@ -1,3 +1,5 @@
+const { resolveAuthConfig } = require('./resolve-auth-config')
+
 function normalizeEmail(value) {
   return String(value || '')
     .trim()
@@ -9,12 +11,38 @@ function looksLikeEmail(value) {
 }
 
 function createAuthHelpers({ sails, world, mailbox, request }) {
-  function getUserModel() {
-    return sails?.models?.user || sails?.models?.User
+  function getAuthConfig() {
+    return resolveAuthConfig({ sails })
+  }
+
+  function getAuthModel() {
+    return getAuthConfig().model
+  }
+
+  function resolveWorldActor(alias) {
+    if (!alias || typeof alias !== 'string') {
+      return null
+    }
+
+    const auth = getAuthConfig()
+
+    return (
+      world.current?.[auth.worldCollection]?.[alias] ||
+      world.current?.users?.[alias] ||
+      world.current?.creators?.[alias] ||
+      null
+    )
   }
 
   async function createUserFromEmail(email, fullName) {
-    const User = getUserModel()
+    const auth = getAuthConfig()
+    const User = getAuthModel()
+
+    if (auth.modelIdentity !== 'user') {
+      throw new Error(
+        `Sounding auth helpers could not auto-create a missing ${auth.modelIdentity} record.`
+      )
+    }
 
     if (!sails?.helpers?.user?.signupWithTeam) {
       throw new Error(
@@ -42,17 +70,18 @@ function createAuthHelpers({ sails, world, mailbox, request }) {
     return signupResult.user
   }
 
-  async function resolveUser(actorOrEmail, options = {}) {
-    const User = getUserModel()
+  async function resolveActor(actorOrEmail, options = {}) {
+    const auth = getAuthConfig()
+    const User = getAuthModel()
 
     if (!actorOrEmail) {
-      throw new Error('Sounding auth helpers require an actor, user, or email address.')
+      throw new Error('Sounding auth helpers require an actor or email address.')
     }
 
     let candidate = actorOrEmail
 
-    if (typeof candidate === 'string' && world.current?.users?.[candidate]) {
-      candidate = world.current.users[candidate]
+    if (typeof candidate === 'string' && !looksLikeEmail(candidate)) {
+      candidate = resolveWorldActor(candidate) || candidate
     }
 
     if (candidate?.id && User?.findOne) {
@@ -76,7 +105,7 @@ function createAuthHelpers({ sails, world, mailbox, request }) {
 
     if (!user) {
       throw new Error(
-        `Sounding auth helpers could not find a user for ${normalizedEmail}.`
+        `Sounding auth helpers could not find a ${auth.modelIdentity} for ${normalizedEmail}.`
       )
     }
 
@@ -84,13 +113,13 @@ function createAuthHelpers({ sails, world, mailbox, request }) {
   }
 
   async function issueMagicLink(actorOrEmail, options = {}) {
-    const User = getUserModel()
+    const User = getAuthModel()
 
     if (!User?.updateOne) {
-      throw new Error('Sounding auth helpers require a User model with updateOne().')
+      throw new Error('Sounding auth helpers require an auth model with updateOne().')
     }
 
-    const user = await resolveUser(actorOrEmail, {
+    const user = await resolveActor(actorOrEmail, {
       createIfMissing: true,
       ...options,
     })
@@ -115,7 +144,7 @@ function createAuthHelpers({ sails, world, mailbox, request }) {
   }
 
   async function requestMagicLink(actorOrEmail, options = {}) {
-    const user = await resolveUser(actorOrEmail, {
+    const user = await resolveActor(actorOrEmail, {
       createIfMissing: true,
       ...options,
     })
@@ -138,18 +167,109 @@ function createAuthHelpers({ sails, world, mailbox, request }) {
     }
   }
 
+  async function loginWithPassword(actorOrEmail, page, options = {}) {
+    if (!page || typeof page.goto !== 'function') {
+      throw new Error('Sounding password browser login requires a Playwright page.')
+    }
+
+    const auth = getAuthConfig()
+    const actor = await resolveActor(actorOrEmail, {
+      createIfMissing: false,
+      ...options,
+    })
+    const email = normalizeEmail(actor?.email || actorOrEmail)
+
+    if (!options.password) {
+      throw new Error('Sounding password login requires a `password` option.')
+    }
+
+    const loginUrl = new URL(auth.password.pagePath, 'http://sounding.local')
+
+    for (const [key, value] of Object.entries(auth.password.pageQuery || {})) {
+      if (value != null) {
+        loginUrl.searchParams.set(key, String(value))
+      }
+    }
+
+    if (options.returnUrl) {
+      loginUrl.searchParams.set(auth.password.form.returnUrl, options.returnUrl)
+    }
+
+    await page.goto(`${loginUrl.pathname}${loginUrl.search}`)
+    await page.fill(auth.password.selectors.email, email)
+    await page.fill(auth.password.selectors.password, options.password)
+
+    if (options.rememberMe && typeof page.check === 'function') {
+      await page.check(auth.password.selectors.rememberMe)
+    }
+
+    await page.click(auth.password.selectors.submit)
+
+    return {
+      actor,
+      email,
+      path: `${loginUrl.pathname}${loginUrl.search}`,
+    }
+  }
+
+  async function requestWithPassword(actorOrEmail, options = {}) {
+    const auth = getAuthConfig()
+    const actor = await resolveActor(actorOrEmail, {
+      createIfMissing: false,
+      ...options,
+    })
+    const email = normalizeEmail(actor?.email || actorOrEmail)
+
+    if (!options.password) {
+      throw new Error('Sounding password request auth requires a `password` option.')
+    }
+
+    const payload = {
+      [auth.password.form.email]: email,
+      [auth.password.form.password]: options.password,
+    }
+
+    if (options.rememberMe !== undefined) {
+      payload[auth.password.form.rememberMe] = options.rememberMe
+    }
+
+    if (options.returnUrl !== undefined) {
+      payload[auth.password.form.returnUrl] = options.returnUrl
+    }
+
+    const targetRequest = options.request || request
+    const response = await targetRequest.post(
+      auth.password.loginPath,
+      payload,
+      options.requestOptions || {}
+    )
+
+    return {
+      actor,
+      email,
+      request: targetRequest,
+      response,
+    }
+  }
+
   const login = {
     async as(actorOrEmail, page, options = {}) {
       const magicLink = await issueMagicLink(actorOrEmail, options)
       await page.goto(magicLink.url)
       return magicLink
     },
+    withPassword: loginWithPassword,
   }
 
   return {
-    resolveUser,
+    conventions: getAuthConfig(),
+    resolveActor,
+    resolveUser: resolveActor,
     issueMagicLink,
     requestMagicLink,
+    request: {
+      withPassword: requestWithPassword,
+    },
     login,
   }
 }

package/lib/create-request-client.js

@@ -1,5 +1,6 @@
 const { Transform } = require('node:stream')
 const QS = require('node:querystring')
+const { resolveAuthConfig } = require('./resolve-auth-config')
 
 function isAbsoluteUrl(value) {
   return /^https?:\/\//i.test(value)
@@ -526,11 +527,13 @@ function createRequestClient({
         return this
       }
 
+      const auth = resolveAuthConfig({ sails, getConfig })
       const actorHeaders = actor.headers || actor.sounding?.headers || {}
       const actorSession = actor.session ||
         actor.sounding?.session || {
-          ...(actor.id ? { userId: actor.id } : {}),
+          ...(actor.id ? { [auth.sessionKey]: actor.id } : {}),
           ...(actor.team ? { teamId: actor.team } : {}),
+          ...(actor.teamId ? { teamId: actor.teamId } : {}),
         }
 
       return this.withHeaders(actorHeaders).withSession(actorSession)

package/lib/default-config.js

@@ -1,4 +1,7 @@
 const DEFAULT_CONFIG = Object.freeze({
+  // 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',
@@ -33,6 +36,21 @@ const DEFAULT_CONFIG = Object.freeze({
   },
   auth: {
     defaultActor: 'guest',
+    modelIdentity: null,
+    sessionKey: null,
+    worldCollection: null,
+    password: {
+      loginPath: '/login',
+      pagePath: '/login',
+      pageQuery: {},
+      form: {
+        email: 'email',
+        password: 'password',
+        rememberMe: 'rememberMe',
+        returnUrl: 'returnUrl',
+      },
+      selectors: {},
+    },
   },
 })
 

package/lib/resolve-auth-config.js

@@ -0,0 +1,93 @@
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function normalizeIdentity(value) {
+  if (typeof value !== 'string') {
+    return null
+  }
+
+  const normalized = value.trim().toLowerCase()
+  return normalized || null
+}
+
+function titleCase(value) {
+  if (!value) {
+    return value
+  }
+
+  return `${value[0].toUpperCase()}${value.slice(1)}`
+}
+
+function resolveSoundingConfig({ sails, getConfig } = {}) {
+  return (typeof getConfig === 'function' ? getConfig() : null) || sails?.config?.sounding || {}
+}
+
+function getModelByIdentity(sails, identity) {
+  const normalizedIdentity = normalizeIdentity(identity)
+
+  if (!normalizedIdentity) {
+    return null
+  }
+
+  return sails?.models?.[normalizedIdentity] || sails?.models?.[titleCase(normalizedIdentity)] || null
+}
+
+function detectModelIdentity(sails) {
+  for (const candidate of ['user', 'creator']) {
+    if (getModelByIdentity(sails, candidate)) {
+      return candidate
+    }
+  }
+
+  return 'user'
+}
+
+function resolvePasswordConfig(authConfig = {}) {
+  const passwordConfig = isPlainObject(authConfig.password) ? authConfig.password : {}
+  const formConfig = isPlainObject(passwordConfig.form) ? passwordConfig.form : {}
+  const selectorConfig = isPlainObject(passwordConfig.selectors) ? passwordConfig.selectors : {}
+  const form = {
+    email: formConfig.email || 'email',
+    password: formConfig.password || 'password',
+    rememberMe: formConfig.rememberMe || 'rememberMe',
+    returnUrl: formConfig.returnUrl || 'returnUrl',
+  }
+
+  return {
+    loginPath: passwordConfig.loginPath || authConfig.loginPath || '/login',
+    pagePath: passwordConfig.pagePath || passwordConfig.loginPath || authConfig.loginPath || '/login',
+    pageQuery: isPlainObject(passwordConfig.pageQuery) ? passwordConfig.pageQuery : {},
+    form,
+    selectors: {
+      email: selectorConfig.email || `input[name="${form.email}"], input[type="email"]`,
+      password:
+        selectorConfig.password || `input[name="${form.password}"], input[type="password"]`,
+      rememberMe:
+        selectorConfig.rememberMe ||
+        `input[name="${form.rememberMe}"], input[id="${form.rememberMe}"], input[type="checkbox"]`,
+      submit: selectorConfig.submit || 'button[type="submit"], input[type="submit"]',
+    },
+  }
+}
+
+function resolveAuthConfig({ sails, getConfig } = {}) {
+  const soundingConfig = resolveSoundingConfig({ sails, getConfig })
+  const authConfig = isPlainObject(soundingConfig.auth) ? soundingConfig.auth : {}
+  const modelIdentity = normalizeIdentity(authConfig.modelIdentity) || detectModelIdentity(sails)
+
+  return {
+    modelIdentity,
+    model: getModelByIdentity(sails, modelIdentity),
+    sessionKey: authConfig.sessionKey || `${modelIdentity}Id`,
+    worldCollection: authConfig.worldCollection || `${modelIdentity}s`,
+    password: resolvePasswordConfig(authConfig),
+  }
+}
+
+module.exports = {
+  detectModelIdentity,
+  getModelByIdentity,
+  resolveAuthConfig,
+  resolveSoundingConfig,
+}

package/package.json

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