@ossy/platform 1.39.2 → 3.0.1

package/src/test/flow-runner.js

@@ -0,0 +1,476 @@
+/**
+ * Declarative flow runner — single entry for test, guide, seed, and stress modes.
+ *
+ * User flows are UI-only. The only non-UI read path is the `email` step (dev inbox).
+ *
+ *   import { runFlow, registerInstalledFlows } from '@ossy/platform/test/flow-runner.js'
+ *   await registerInstalledFlows(import.meta.url)
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { faker } from '@faker-js/faker'
+import { Router } from '@ossy/router'
+import { Schema } from '@ossy/schema'
+import { test, expect } from '@playwright/test'
+
+const FLOW_PATTERN = /\.flow\.(mjs|cjs|js)$/
+
+/**
+ * @typedef {'test' | 'guide' | 'seed' | 'stress'} FlowMode
+ *
+ * @typedef {object} FlowRunContext
+ * @property {Record<string, unknown>} fields Filled form values keyed by field name.
+ * @property {string} [email]
+ * @property {string} [userId]
+ * @property {string} [token]
+ * @property {string} [providerSlug]
+ * @property {string} [workspaceId]
+ */
+
+/**
+ * Load `build/manifest.json` from disk.
+ * @param {string} manifestPath
+ */
+export function loadManifest (manifestPath) {
+  if (!fs.existsSync(manifestPath)) {
+    const appRoot = path.dirname(path.dirname(manifestPath))
+    throw new Error(
+      `Missing ${manifestPath}. Flow tests need a built app manifest — ` +
+      `run \`npm run build\` in ${appRoot} first (Playwright does not build for you).`,
+    )
+  }
+  return JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+}
+
+function normalizePageId (pageRef) {
+  if (typeof pageRef !== 'string') return ''
+  return pageRef.startsWith('@') ? pageRef.slice(1) : pageRef
+}
+
+function manifestPages (manifest) {
+  return (manifest.entries ?? []).filter(e => e.type === 'page')
+}
+
+function buildRouter (manifest, locale) {
+  const pages = manifestPages(manifest).map(p => ({ id: p.id, path: p.path }))
+  const config = manifest.config ?? {}
+  return Router.of({
+    pages,
+    defaultLanguage: locale ?? config.defaultLanguage ?? 'en',
+    supportedLanguages: config.supportedLanguages ?? [locale ?? 'en'],
+  })
+}
+
+function findSchema (manifest, schemaId) {
+  return (manifest.schemas ?? []).find(s => s.id === schemaId)
+}
+
+function schemaEngineFromManifest (manifest) {
+  return Schema.of(manifest, {
+    actionIds: (manifest.actions ?? []).map(a => a.id),
+    taskIds: (manifest.tasks ?? []).map(t => t.id),
+  })
+}
+
+/**
+ * Mock form field values via Schema.mock and update the run context.
+ *
+ * @param {import('@ossy/schema').Schema} engine
+ * @param {{ id: string, fields?: { name: string, type?: string }[] }} template
+ * @param {FlowRunContext} context
+ */
+function mockFormContent (engine, template, context) {
+  const content = engine.mock(template, { faker })
+  for (const field of template.fields ?? []) {
+    const value = content[field.name]
+    if (value !== undefined) context.fields[field.name] = value
+    if (field.type === 'email' || field.name?.toLowerCase?.().includes('email')) {
+      context.email = String(value)
+    }
+  }
+  return content
+}
+
+function resolveActionId (action) {
+  if (typeof action === 'string') return action
+  if (action && typeof action.id === 'string') return action.id
+  throw new Error('Flow action step requires an action POJO or id string')
+}
+
+function actionSelector (actionId, service) {
+  return service
+    ? `[data-action="${actionId}"][data-service="${service}"]`
+    : `[data-action="${actionId}"]`
+}
+
+function resolveActionService (action, fallback) {
+  if (typeof action === 'object' && action.service) return action.service
+  return fallback
+}
+
+/** Resolve `$token`-style placeholders from the run context. */
+function resolveContextValue (value, context) {
+  if (typeof value !== 'string' || !value.startsWith('$')) return value
+  const key = value.slice(1)
+  return context[key] ?? context.fields?.[key]
+}
+
+function resolveContextObject (obj, context) {
+  if (!obj || typeof obj !== 'object') return obj
+  const out = {}
+  for (const [key, raw] of Object.entries(obj)) {
+    out[key] = resolveContextValue(raw, context)
+  }
+  return out
+}
+
+function appendSearch (pathname, search, context) {
+  if (!search || typeof search !== 'object') return pathname
+  const params = new URLSearchParams()
+  for (const [key, raw] of Object.entries(search)) {
+    const value = resolveContextValue(raw, context)
+    if (value != null && value !== '') params.set(key, String(value))
+  }
+  const qs = params.toString()
+  return qs ? `${pathname}?${qs}` : pathname
+}
+
+function linkNamePattern (click) {
+  if (click instanceof RegExp) return click
+  return new RegExp(click, 'i')
+}
+
+/**
+ * Execute a declarative flow against a Playwright page.
+ *
+ * @param {{ title?: string, description?: string, steps?: unknown[], metadata?: object }} flow
+ * @param {{
+ *   mode?: FlowMode,
+ *   page?: import('@playwright/test').Page,
+ *   baseURL?: string,
+ *   manifest?: object,
+ *   manifestPath?: string,
+ *   locale?: string,
+ *   context?: FlowRunContext,
+ *   expect?: import('@playwright/test').Expect,
+ * }} options
+ */
+export async function runFlow (flow, options = {}) {
+  const {
+    mode = 'test',
+    page,
+    baseURL = process.env.OSSY_APP_URL ?? process.env.BASE_URL ?? 'http://localhost:3002',
+    manifest: manifestIn,
+    manifestPath,
+    locale: localeIn,
+    context: contextIn,
+    expect: expectFn = expect,
+  } = options
+
+  if (mode !== 'test' && mode !== 'guide' && mode !== 'seed' && mode !== 'stress') {
+    throw new Error(`Unknown flow mode "${mode}"`)
+  }
+
+  if (mode !== 'test') {
+    console.info(`[flow-runner] mode "${mode}" not fully implemented — running test steps`)
+  }
+
+  const manifest = manifestIn ?? loadManifest(manifestPath)
+  const locale = localeIn ?? manifest.config?.defaultLanguage ?? 'en'
+  const router = buildRouter(manifest, locale)
+  const context = contextIn ?? { fields: {} }
+  const steps = flow.steps ?? []
+
+  for (const step of steps) {
+    if (!step || typeof step !== 'object') continue
+
+    if (step.page != null) {
+      if (!page) throw new Error('page step requires a Playwright page')
+      const pageId = normalizePageId(step.page)
+      const params = resolveContextObject(step.params, context)
+      const pathname = router.getPathname({ id: pageId, language: locale, params })
+      if (!pathname) throw new Error(`Page "${pageId}" not found in manifest`)
+      const target = appendSearch(pathname, step.search ?? step.query, context)
+      await page.goto(`${baseURL}${target}`)
+      continue
+    }
+
+    if (step.form) {
+      if (!page) throw new Error('form step requires a Playwright page')
+      const formMeta = step.form
+      const schemaId = formMeta?.schemaId
+      if (!formMeta || typeof formMeta !== 'object' || typeof formMeta.id !== 'string' || typeof schemaId !== 'string') {
+        throw new Error('form step requires a FormMetadata POJO with id and schemaId — import metadata from *.form.js')
+      }
+      const { id: formId } = formMeta
+      const template = findSchema(manifest, schemaId)
+      if (!template?.fields?.length) {
+        throw new Error(`Resource schema "${schemaId}" not found or has no fields`)
+      }
+      const engine = schemaEngineFromManifest(manifest)
+      const content = mockFormContent(engine, template, context)
+      const formRoot = formId ? page.locator(`form[id="${formId}"]`) : page
+      for (const field of template.fields) {
+        const value = content[field.name]
+        const locator = formRoot.locator(`[name="${field.name}"]`)
+        const tag = await locator.evaluate(el => el.tagName.toLowerCase()).catch(() => 'input')
+        if (tag === 'select') {
+          await locator.selectOption(String(value))
+        } else if (tag === 'input') {
+          const inputType = await locator.getAttribute('type')
+          if (inputType === 'checkbox') {
+            if (value) await locator.check()
+          } else {
+            await locator.fill(String(value))
+          }
+        } else {
+          await locator.fill(String(value))
+        }
+      }
+      continue
+    }
+
+    if (step.action != null) {
+      if (!page) throw new Error('action step requires a Playwright page')
+      const actionId = resolveActionId(step.action)
+      const service = resolveActionService(step.action, step.service)
+      const locator = page.locator(actionSelector(actionId, service)).first()
+      const actionTimeout = step.timeout ?? 15000
+      await locator.waitFor({ state: 'visible', timeout: actionTimeout })
+      await locator.click()
+      continue
+    }
+
+    if (step.capture != null) {
+      if (!page) throw new Error('capture step requires a Playwright page')
+      for (const [key, spec] of Object.entries(step.capture)) {
+        if (typeof spec === 'string' && spec.startsWith('$')) {
+          context[key] = resolveContextValue(spec, context)
+          continue
+        }
+        if (typeof spec === 'object' && spec.from === 'urlParam') {
+          const url = new URL(page.url())
+          context[key] = url.searchParams.get(spec.key ?? key)
+          continue
+        }
+        const selector = typeof spec === 'string' ? spec : spec.selector
+        const attr = typeof spec === 'object' ? spec.attr : undefined
+        const locator = page.locator(selector).first()
+        await locator.waitFor({ state: 'attached', timeout: step.timeout ?? 15000 })
+        context[key] = attr
+          ? await locator.getAttribute(attr)
+          : await locator.textContent()
+      }
+      continue
+    }
+
+    if (step.email != null) {
+      if (!page) throw new Error('email step requires a Playwright page')
+      const emailStep = typeof step.email === 'object' ? step.email : { id: step.email }
+      const to = resolveContextValue(emailStep.to ?? '$email', context)
+      const templateId = emailStep.id ?? emailStep.templateId
+      const clickLabel = emailStep.click ?? emailStep.link
+      if (!to) throw new Error('email step requires "to" (recipient email)')
+      if (!templateId) throw new Error('email step requires "id" (email template id)')
+      if (!clickLabel) throw new Error('email step requires "click" (link text in the email)')
+
+      const inboxPath = router.getPathname({ id: 'dev-inbox', language: locale }) ?? '/dev/inbox'
+      const params = new URLSearchParams({ to: String(to), template: String(templateId) })
+      const inboxUrl = `${baseURL}${inboxPath}?${params}`
+      const pattern = linkNamePattern(clickLabel)
+      const deadline = Date.now() + (emailStep.timeout ?? 20000)
+
+      let clicked = false
+      while (Date.now() < deadline && !clicked) {
+        await page.goto(inboxUrl)
+        const link = page.getByRole('link', { name: pattern }).first()
+        try {
+          await link.waitFor({ state: 'visible', timeout: 2000 })
+          await Promise.all([
+            page.waitForLoadState('domcontentloaded'),
+            link.click(),
+          ])
+          clicked = true
+        } catch {
+          await page.waitForTimeout(500)
+        }
+      }
+      if (!clicked) {
+        throw new Error(`Email link "${clickLabel}" not found for to=${to}, template=${templateId}`)
+      }
+      continue
+    }
+
+    if (step.result) {
+      if (!page) throw new Error('result step requires a Playwright page')
+      const { text, url, page: pageRef, action, selector, timeout = 8000 } = step.result
+      if (action != null) {
+        const actionId = resolveActionId(action)
+        const service = resolveActionService(action, step.result.service)
+        await expectFn(page.locator(actionSelector(actionId, service)).first()).toBeVisible({ timeout })
+      }
+      if (selector != null) {
+        await expectFn(page.locator(selector).first()).toBeVisible({ timeout })
+      }
+      if (text != null) {
+        const pattern = text instanceof RegExp ? text : new RegExp(text, 'i')
+        await expectFn(page.getByText(pattern).first()).toBeVisible({ timeout })
+      }
+      if (pageRef != null) {
+        const pageId = normalizePageId(pageRef)
+        const pathname = router.getPathname({ id: pageId, language: locale })
+        if (!pathname) throw new Error(`Result page "${pageId}" not found in manifest`)
+        const pathnameBase = pathname.replace(/\/$/, '') || pathname
+        const escaped = pathnameBase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        await expectFn(page).toHaveURL(new RegExp(`${escaped}\\/?(\\?|#|$)`), { timeout })
+      }
+      if (url != null) {
+        const pattern = url instanceof RegExp ? url : new RegExp(url, 'i')
+        await expectFn(page).toHaveURL(pattern, { timeout })
+      }
+      continue
+    }
+
+    if (step.pickFirst != null) {
+      if (!page) throw new Error('pickFirst step requires a Playwright page')
+      const kind = typeof step.pickFirst === 'string' ? step.pickFirst : step.pickFirst.kind
+      const actionId = {
+        service: 'public-booking/pick-service',
+        date: 'public-booking/pick-date',
+        slot: 'public-booking/pick-slot',
+      }[kind]
+      if (!actionId) throw new Error(`Unknown pickFirst kind "${kind}"`)
+      const locator = page.locator(`${actionSelector(actionId)}:not([disabled])`).first()
+      await locator.waitFor({ state: 'visible', timeout: step.timeout ?? 15000 })
+      await locator.click()
+      continue
+    }
+
+    throw new Error(`Unknown flow step: ${JSON.stringify(step)}`)
+  }
+
+  return context
+}
+
+/**
+ * Register a single `*.flow.js` module as a Playwright test.
+ *
+ * Flows must be self-contained UI journeys — see docs/concepts/TESTING-SPEC.md.
+ *
+ * @param {{ metadata?: object, default?: object }} mod
+ * @param {{ manifestPath?: string, locale?: string }} options
+ */
+export function registerFlow (mod, options = {}) {
+  const meta = mod.metadata ?? mod.default?.metadata ?? {}
+  const flowBody = mod.default ?? mod
+  const id = meta.id ?? flowBody.id
+  if (typeof id !== 'string' || !id) throw new Error('flow module is missing metadata.id')
+
+  const feature = meta.feature ?? id
+  const steps = flowBody.steps ?? []
+  const title = flowBody.title ?? id
+
+  test.describe(feature, () => {
+    test(title, async ({ page, baseURL }) => {
+      const manifestPath = options.manifestPath
+      const manifest = manifestPath ? loadManifest(manifestPath) : undefined
+      await runFlow({ ...flowBody, steps, metadata: meta }, {
+        mode: 'test',
+        page,
+        baseURL,
+        manifest,
+        manifestPath,
+        locale: options.locale,
+      })
+    })
+  })
+}
+
+/**
+ * Register all flows listed in `manifest.flows[]`.
+ * @param {string} manifestPath Absolute path to build/manifest.json
+ */
+export async function registerFlowsFromManifest (manifestPath) {
+  const manifest = loadManifest(manifestPath)
+  const buildDir = path.dirname(manifestPath)
+  const staticDir = path.join(buildDir, 'public', 'static')
+
+  for (const entry of manifest.flows ?? []) {
+    const chunkName = entry.entry.replace(/^\/static\//, '')
+    const chunkPath = path.join(staticDir, chunkName)
+    const mod = await import(pathToFileURL(chunkPath).href + `?ts=${Date.now()}`)
+    registerFlow(mod, { manifestPath, locale: manifest.config?.defaultLanguage })
+  }
+}
+
+function findNodeModules (startDir) {
+  let dir = startDir
+  for (let i = 0; i < 10; i++) {
+    const candidate = path.join(dir, 'node_modules')
+    if (fs.existsSync(candidate)) return candidate
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+function discoverFlowFiles (nmDir) {
+  const results = []
+  const walk = (dir, cb) => {
+    if (!fs.existsSync(dir)) return
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) walk(full, cb)
+      else if (entry.isFile()) cb(full)
+    }
+  }
+
+  const tryPackageDir = (pkgDir) => {
+    const pkgJsonPath = path.join(pkgDir, 'package.json')
+    if (!fs.existsSync(pkgJsonPath)) return
+    let pkg
+    try { pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8')) } catch { return }
+    if (!pkg.ossy?.src) return
+    const srcDir = path.resolve(pkgDir, pkg.ossy.src)
+    walk(srcDir, filePath => {
+      if (FLOW_PATTERN.test(path.basename(filePath))) results.push(filePath)
+    })
+  }
+
+  for (const entry of fs.readdirSync(nmDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+    if (entry.name.startsWith('@')) {
+      const scopeDir = path.join(nmDir, entry.name)
+      if (!fs.existsSync(scopeDir)) continue
+      for (const scoped of fs.readdirSync(scopeDir, { withFileTypes: true })) {
+        if (scoped.isDirectory() || scoped.isSymbolicLink()) {
+          tryPackageDir(path.join(scopeDir, scoped.name))
+        }
+      }
+    } else {
+      tryPackageDir(path.join(nmDir, entry.name))
+    }
+  }
+
+  return results
+}
+
+/**
+ * Walk installed `@ossy/*` packages and register all `*.flow.js` files.
+ * @param {string} fromUrl `import.meta.url` of the calling spec file.
+ * @param {{ manifestPath?: string }} options
+ */
+export async function registerInstalledFlows (fromUrl, options = {}) {
+  const callerDir = path.dirname(fileURLToPath(fromUrl))
+  const nmDir = findNodeModules(callerDir)
+  if (!nmDir) return
+
+  const flowPaths = discoverFlowFiles(nmDir)
+  for (const filePath of flowPaths) {
+    const mod = await import(filePath)
+    registerFlow(mod, options)
+  }
+}

package/src/test/test.util.js

@@ -1,6 +1,9 @@
 import casual from 'casual'
 import { EventStore } from '@ossy/event-store'
 
+const USER_SCHEMA = '@ossy/users/schema/user'
+const TOKEN_SCHEMA = '@ossy/tokens/schema/token'
+
 /** Requires Node 18+ (global `fetch`). */
 
 /**
@@ -130,11 +133,10 @@ export class TestUtil {
     return EventStore.FindEvents(query)
   }
 
-  /** JWT from the latest Verification token aggregate for this user (sign-up or sign-in request). */
   static countVerificationTokenEvents() {
     return EventStore.Collection.countDocuments({
-      aggregateType: 'Token',
-      type: 'Created',
+      type: TOKEN_SCHEMA,
+      event: 'Created',
       'payload.type': 'Verification',
     })
   }
@@ -142,12 +144,12 @@ export class TestUtil {
   static async getLatestApiTokenCreatedEventForSubject(subjectId) {
     const ev = await EventStore.Collection.findOne(
       {
-        aggregateType: 'Token',
-        type: 'Created',
+        type: TOKEN_SCHEMA,
+        event: 'Created',
         'payload.type': 'Api',
         'payload.subject': subjectId,
       },
-      { sort: { created: -1 } }
+      { sort: { created: -1 } },
     )
     if (!ev) {
       throw new Error('No Api token Created event for subject')
@@ -158,12 +160,12 @@ export class TestUtil {
   static async getLatestVerificationJwtForSubject(subjectId) {
     const ev = await EventStore.Collection.findOne(
       {
-        aggregateType: 'Token',
-        type: 'Created',
+        type: TOKEN_SCHEMA,
+        event: 'Created',
         'payload.type': 'Verification',
         'payload.subject': subjectId,
       },
-      { sort: { created: -1 } }
+      { sort: { created: -1 } },
     )
     if (!ev?.payload?.token) {
       return Promise.reject(new Error('No verification token found for subject'))
@@ -175,51 +177,50 @@ export class TestUtil {
     const email = `${casual.email}`
 
     return TestUtil.InvokeAction({
-      actionId: 'authentication/sign-up',
+      actionId: '@ossy/authentication/actions/sign-up',
       body: TestUtil.signUpBody({ email }),
     })
-    .then(() => EventStore.FindEvent({
-      aggregateType: 'User',
-      type: { $in: [ 'SignedUp' ] },
-      'payload.email': email
-    }))
-    .then(event => event.payload.verificationToken)
+      .then(() => EventStore.FindEvent({
+        type: USER_SCHEMA,
+        event: 'Created',
+        'payload.email': email,
+      }))
+      .then(event => event.payload.verificationToken)
   }
 
   static async GetAuthenticatedTestUser(email = casual.email) {
 
     await TestUtil.AssertActionResponse({
-      actionId: 'authentication/sign-up',
+      actionId: '@ossy/authentication/actions/sign-up',
       body: TestUtil.signUpBody({ email }),
       expectedResponseStatus: 200,
-      expectedResponseBody: { ok: true }
+      expectedResponseBody: { ok: true },
     })
 
     const signedUpEvent = await TestUtil.GetEvent({
-      aggregateType: 'User',
-      type: { $in: [ 'SignedUp' ] },
-      'payload.email': email
+      type: USER_SCHEMA,
+      event: 'Created',
+      'payload.email': email,
     })
 
-    const verificationJwt = await TestUtil.getLatestVerificationJwtForSubject(signedUpEvent.aggregateId)
+    const verificationJwt = await TestUtil.getLatestVerificationJwtForSubject(signedUpEvent.resourceId)
 
     await fetch(
       `${baseUrl()}/users/verify-sign-in?token=${verificationJwt}`,
-      { method: 'GET' }
+      { method: 'GET' },
     )
 
     const signInVerifiedEvent = await TestUtil.GetEvent({
-      aggregateType: 'User',
-      aggregateId: signedUpEvent.aggregateId,
-      type: { $in: [ 'SignInVerified' ] },
+      type: USER_SCHEMA,
+      resourceId: signedUpEvent.resourceId,
+      event: 'SignInVerified',
     })
 
     return {
-      id: signedUpEvent.aggregateId,
+      id: signedUpEvent.resourceId,
       token: signInVerifiedEvent.payload.token,
-      email: email,
+      email,
     }
-
   }
 
   static CloseDbConnection() {

package/src/user-app-settings.js

@@ -0,0 +1,44 @@
+export const USER_SETTINGS_COOKIE = 'x-ossy-user-settings'
+export const AUTH_COOKIE = 'auth'
+
+const USER_SETTINGS_MAX_AGE_MS = 2147483647
+const AUTH_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000
+
+export function readUserAppSettings (req) {
+  return JSON.parse(req.signedCookies?.[USER_SETTINGS_COOKIE] || '{}')
+}
+
+export function mergeUserAppSettingsCookie (req, res, partial) {
+  const updated = { ...readUserAppSettings(req), ...partial }
+  res.cookie(USER_SETTINGS_COOKIE, JSON.stringify(updated), {
+    httpOnly: true,
+    signed: true,
+    expires: new Date(Date.now() + USER_SETTINGS_MAX_AGE_MS),
+  })
+}
+
+export function clearWorkspaceFromUserAppSettings (req, res) {
+  const settings = readUserAppSettings(req)
+  delete settings.workspaceId
+  if (Object.keys(settings).length === 0) {
+    res.clearCookie(USER_SETTINGS_COOKIE)
+    return
+  }
+  res.cookie(USER_SETTINGS_COOKIE, JSON.stringify(settings), {
+    httpOnly: true,
+    signed: true,
+    expires: new Date(Date.now() + USER_SETTINGS_MAX_AGE_MS),
+  })
+}
+
+export function setAuthCookie (res, token) {
+  res.cookie(AUTH_COOKIE, token, {
+    httpOnly: true,
+    signed: true,
+    expires: new Date(Date.now() + AUTH_MAX_AGE_MS),
+  })
+}
+
+export function clearAuthCookie (res) {
+  res.clearCookie(AUTH_COOKIE)
+}