@ossy/platform 1.35.1 → 1.36.1

package/README.md

@@ -1,95 +1,150 @@
 # @ossy/platform
 
-Ossy application server runtime — Express-based server that loads the build manifest produced by `@ossy/app` and serves pages, APIs, tasks, and integrations.
+Express-based application server runtime for the Ossy platform. It reads the build manifest produced by `@ossy/app build` and wires up pages, API routes, tasks, actions, integrations, aggregates, and startup hooks — all without any server-side configuration.
 
----
+## What it does
 
-## `*.integration.js` — third-party integration primitive
+At startup `@ossy/platform`:
 
-An integration file declares a named third-party client (e.g. a database, email provider, or payment SDK) that the platform connects to once at startup and makes available to every task.
+1. Loads `build/manifest.json` produced by `@ossy/app build`.
+2. Registers and runs all **startup hooks** (`*.startup.js`) in order.
+3. Connects all **integrations** (`*.integration.js`) by calling `connect({ env })`.
+4. Registers all **tasks** (`*.task.js`) with `TaskService` and starts the cron scheduler.
+5. Registers all **resource templates** (`*.resource.js`) with `registerResourceTemplate`.
+6. Rebuilds all **aggregates** (`*.aggregate.js`) from the event store.
+7. Registers all **actions** (`*.action.js`) with `ActionService`.
+8. Starts an Express server that routes requests to pages (`*.page.jsx`) and API handlers (`*.api.js`).
+9. Auto-mounts every action at `POST /actions/:id`.
 
-### File naming
+## Quick start
 
-Name the file `<slug>.integration.js` (or `.mjs` / `.cjs`) and place it anywhere inside `src/`. The build pipeline discovers it automatically using the `*.integration.js` pattern, just like `*.task.js` and `*.page.jsx`.
+```sh
+# In your app directory
+npm install @ossy/app @ossy/platform
 
-### Required exports
+# Build the app
+npx app build
 
-| Export | Type | Description |
-|---|---|---|
-| `id` | `string` | Unique slug used to retrieve the client — e.g. `'email'`, `'stripe'`. |
-| `credentials` | `string[]` | Names of environment variables that must be present. If any are missing the integration is skipped at startup with a warning. |
-| `connect` | `async ({ env }) => client` | Called once at startup with the full `process.env`. Returns the client object stored by `id`. If it throws, the integration is skipped (non-fatal). |
+# Start the server
+npx platform start
+```
 
-### Minimal example
+Or programmatically:
 
 ```js
-// src/stripe.integration.js
-import Stripe from 'stripe'
+import { startServer } from '@ossy/platform'
 
-export const id = 'stripe'
+const { port, close } = await startServer({
+  cwd: process.cwd(),   // defaults to process.cwd()
+  buildDir: 'build',    // defaults to 'build'
+  port: 3000,           // also reads --port / PORT env var
+})
+```
 
-export const credentials = ['STRIPE_SECRET_KEY']
+## Server configuration
 
-export async function connect ({ env }) {
-  return new Stripe(env.STRIPE_SECRET_KEY)
-}
-```
+The server reads configuration from:
+
+- `--port` / `-p` CLI flag, or the `PORT` environment variable (default `3000`).
+- `build/manifest.json` — produced by `@ossy/app build`.
+- `process.env` — used by integrations for their credentials and by startup hooks.
 
-### Consuming integrations inside a task
+Optional environment variables used by the platform itself:
 
-The platform injects `integrations` into every task's `run()` call alongside `sdk`:
+| Variable | Description |
+|---|---|
+| `DB_URL` | MongoDB connection string. Required for tasks and aggregates. |
+| `API_URL` + `OSSY_API_KEY` | SDK configuration. When set, tasks receive a pre-configured SDK instance. |
+| `PORT` | HTTP port. |
+
+## Exported API
 
 ```js
-// src/send-invoice.task.js
-export const metadata = {
-  id: 'send-invoice',
-  triggers: [{ aggregateType: 'Invoice', event: 'InvoiceCreated' }],
-}
-
-export async function run ({ event, sdk, integrations }) {
-  const stripe = integrations.get('stripe')   // null if credentials are missing
-  if (!stripe) return
-
-  await stripe.invoices.send(event.payload.stripeInvoiceId)
-}
+import {
+  startServer,
+  loadManifest,
+  resolveEntryUrl,
+  ConfigService,
+  ActionService,
+  StorageClient,
+  S3Client,
+  LocalStorageClient,
+  getSystemResourceTemplates,
+  normalizeAndValidateDocumentContent,
+  validateResourceTemplatesForImport,
+} from '@ossy/platform'
 ```
 
-`integrations.get(id)` returns `null` when the integration was not loaded (missing credentials, failed `connect()`, or not declared anywhere).
+### `ActionService`
+
+Registry for `*.action.js` command handlers.
 
-### Manifest output
+```js
+import { ActionService } from '@ossy/platform'
 
-After `app build` the manifest contains an `integrations` array:
+// Invoke an action from server-side code (bypasses HTTP)
+const result = await ActionService.invoke('orders/create', {
+  payload: { ... },
+  req: { userId: 'user-123', workspaceId: 'ws-456' },
+})
 
-```json
-{
-  "integrations": [
-    {
-      "id": "stripe",
-      "entry": "/static/stripe.integration-7f2a.js",
-      "credentials": ["STRIPE_SECRET_KEY"]
-    }
-  ]
-}
+// Look up a registered action
+const action = ActionService.get('orders/create')  // { id, access, run } | null
+
+// List all registered actions
+const all = ActionService.all()
 ```
 
-### Built-in integrations
+### `getSystemResourceTemplates`
 
-`@ossy/platform` ships with the following integration that is auto-discovered for every app using the package:
+Returns all resource templates registered from `*.resource.js` files.
 
-| id | Credentials | Client |
-|---|---|---|
-| `email` | `SES_REGION`, `SES_ACCESS_KEY_ID`, `SES_SECRET_ACCESS_KEY` | `SESClient` from `@aws-sdk/client-ses` |
+```js
+import { getSystemResourceTemplates } from '@ossy/platform'
 
-If the SES env vars are not set the `email` integration is silently skipped and `integrations.get('email')` returns `null`.
+const templates = getSystemResourceTemplates()
+// [{ id: '@ossy/tool/doc', name: 'Tool Doc', fields: [...] }, ...]
+```
 
-### `IntegrationService` API
+## Primitives
 
-```js
-import { IntegrationService } from '@ossy/platform/integrations'
+The platform is built around file conventions called **primitives**. Each primitive is a file with a specific naming pattern that the build pipeline auto-discovers.
 
-// Load a list of already-imported integration modules (done automatically by the server).
-await IntegrationService.load(modules, process.env)
+**→ See [PRIMITIVES.md](./PRIMITIVES.md) for the complete reference.**
+
+| Primitive | Pattern | Purpose |
+|---|---|---|
+| Page | `*.page.jsx` | Routable UI (SSR + hydration) |
+| API | `*.api.js` | HTTP endpoint (any method) |
+| Task | `*.task.js` | Event-driven or scheduled async work |
+| Action | `*.action.js` | Named command, auto-exposed at `POST /actions/:id` |
+| Integration | `*.integration.js` | Third-party client connected at startup |
+| Email | `*.email.jsx` | Transactional React email template |
+| Component | `*.component.jsx` | Injectable UI fragment |
+| Resource | `*.resource.js` | Custom document-type schema |
+| Aggregate | `*.aggregate.js` | Event-sourced domain object |
+| Startup | `*.startup.js` | One-time boot hook |
+
+## Request lifecycle
 
-// Retrieve a connected client by id.
-const client = IntegrationService.get('email')  // SESClient | null
 ```
+Incoming request
+  │
+  ├─ POST /actions/:id  ──► ActionService.invoke() ──► action.run({ payload, sdk, log, integrations, req })
+  │
+  ├─ Match API route    ──► api.handle(req, res)
+  │
+  └─ Match page route   ──► page.render(props) ──► HTML response
+```
+
+Requests that do not match an API route or page route receive `404 Not Found`.
+
+## Related packages
+
+| Package | Purpose |
+|---|---|
+| [`@ossy/app`](../app) | Build pipeline — discovers primitives, bundles them, writes `manifest.json` |
+| [`@ossy/event-store`](../event-store) | Event sourcing primitives (`Aggregate`, `EventStore`) |
+| [`@ossy/email`](../email) | Email renderer and `email.integration.js` |
+| [`@ossy/observability`](../observability) | Structured logger and metrics |
+| [`@ossy/router`](../router) | URL matching used by the platform server |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "1.35.1",
+  "version": "1.36.1",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -21,7 +21,9 @@
     "./resources": "./src/resources/index.js",
     "./definition": "./src/Definition.js",
     "./integrations": "./src/integration.service.js",
-    "./test": "./src/test/index.js"
+    "./test": "./src/test/index.js",
+    "./test/e2e-runner.js": "./src/test/e2e-runner.js",
+    "./test/playwright.config.js": "./src/test/playwright.config.js"
   },
   "scripts": {
     "start": "PORT=3003 node -e \"import('./src/server.js').then(m => m.startServer())\"",
@@ -36,13 +38,13 @@
     "@aws-sdk/s3-request-presigner": "^3.1057.0",
     "@aws-sdk/util-create-request": "^3.972.26",
     "@aws-sdk/util-format-url": "^3.972.17",
-    "@ossy/event-store": "^1.4.1",
-    "@ossy/observability": "^1.4.1",
-    "@ossy/policies": "^1.9.1",
-    "@ossy/router": "^1.36.1",
-    "@ossy/sdk": "^1.36.1",
-    "@ossy/tokens": "^1.9.1",
-    "@ossy/users": "^1.9.1",
+    "@ossy/event-store": "^1.5.1",
+    "@ossy/observability": "^1.5.1",
+    "@ossy/policies": "^1.10.1",
+    "@ossy/router": "^1.37.1",
+    "@ossy/sdk": "^1.37.1",
+    "@ossy/tokens": "^1.10.1",
+    "@ossy/users": "^1.10.1",
     "cookie-parser": "^1.4.7",
     "dotenv": ">=16.0.0 <18.0.0",
     "express": ">=5.0.0 <6.0.0",
@@ -52,6 +54,7 @@
   },
   "devDependencies": {
     "@jest/globals": "^30.2.0",
+    "@playwright/test": ">=1.40.0",
     "casual": "^1.6.2",
     "jest": "^30.2.0"
   },
@@ -59,5 +62,5 @@
     "src",
     "Dockerfile"
   ],
-  "gitHead": "a144d7767264d96bc6ae095784d4f884f03a89a0"
+  "gitHead": "d5b71d16ec56c819401c7a74f95d12b2347ca3c4"
 }

package/src/test/e2e-runner.js

@@ -0,0 +1,134 @@
+/**
+ * Playwright test runner for `*.e2e.js` primitive modules.
+ *
+ * Usage in a Playwright spec file:
+ *
+ *   import { registerE2eTest } from '@ossy/platform/test'
+ *   import * as mod from '@ossy/authentication/src/sign-in.e2e.js'
+ *
+ *   registerE2eTest(mod)
+ *
+ * Or for automatic discovery of all installed @ossy/* package e2e tests:
+ *
+ *   import { registerInstalledE2eTests } from '@ossy/platform/test'
+ *   await registerInstalledE2eTests(import.meta.url)
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { test, expect } from '@playwright/test'
+import { signUpAndGetToken, verifySignIn } from './e2e.util.js'
+
+export { signUpAndGetToken, verifySignIn }
+
+/**
+ * Extended Playwright test fixture that injects shared e2e helpers.
+ *
+ * Test functions receive all standard Playwright fixtures plus:
+ *   - `signUpAndGetToken(firstName?, lastName?)` — signs up a user and returns `{ email, userId, token }`
+ *   - `verifySignIn(token)` — calls the verify-sign-in endpoint
+ *   - `expect` — Playwright's enhanced expect
+ */
+export const e2eTest = test.extend({
+  signUpAndGetToken: async ({}, use) => { await use(signUpAndGetToken) },
+  verifySignIn: async ({}, use) => { await use(verifySignIn) },
+})
+
+/**
+ * Register a single `*.e2e.js` module as a Playwright test suite.
+ *
+ * The module must export:
+ *   - `id`       {string}    Unique test id (e.g. `'authentication/sign-in'`)
+ *   - `feature`  {string}    Grouping label (e.g. `'authentication'`)
+ *   - `requires` {string[]}  Dependencies (e.g. `['server', 'database']`)
+ *   - `default`  {Function}  Async test function receiving Playwright fixtures
+ *
+ * @param {{ id: string, feature?: string, requires?: string[], default: Function }} mod
+ */
+export function registerE2eTest(mod) {
+  const { id, feature, default: testFn } = mod
+  if (typeof id !== 'string' || !id) throw new Error(`e2e module is missing a string "id" export`)
+  if (typeof testFn !== 'function') throw new Error(`e2e module "${id}" must default-export a function`)
+
+  e2eTest.describe(feature || id, () => {
+    e2eTest(id, async (fixtures) => {
+      await testFn({ ...fixtures, expect })
+    })
+  })
+}
+
+/**
+ * Walk `node_modules` relative to `fromUrl` (typically `import.meta.url` of
+ * the calling spec file) and register all `*.e2e.js` files found in packages
+ * that declare `"ossy": { "src": "..." }` in their `package.json`.
+ *
+ * @param {string} fromUrl  `import.meta.url` of the calling spec file.
+ */
+export async function registerInstalledE2eTests(fromUrl) {
+  const callerDir = path.dirname(fileURLToPath(fromUrl))
+  const nmDir = findNodeModules(callerDir)
+  if (!nmDir) return
+
+  const e2ePaths = discoverE2eFiles(nmDir)
+  for (const filePath of e2ePaths) {
+    const mod = await import(filePath)
+    registerE2eTest(mod)
+  }
+}
+
+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 discoverE2eFiles(nmDir) {
+  const results = []
+  const E2E_PATTERN = /\.e2e\.(mjs|cjs|js)$/
+
+  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 (E2E_PATTERN.test(path.basename(filePath))) results.push(filePath)
+    })
+  }
+
+  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)
+    }
+  }
+
+  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
+}

package/src/test/e2e.util.js

@@ -0,0 +1,109 @@
+import { MongoClient } from 'mongodb'
+
+const DB_URL = process.env.DB_URL ?? 'mongodb://localhost:27017/'
+const DB_NAME = process.env.DB_NAME ?? 'ossy-local'
+export const API_URL = process.env.OSSY_API_URL ?? process.env.API_URL ?? 'http://localhost:3001/api/v0'
+export const APP_URL = process.env.OSSY_APP_URL ?? process.env.BASE_URL ?? 'http://localhost:3002'
+
+/**
+ * Polls MongoDB until a Verification token appears for the given userId,
+ * or throws if it doesn't arrive within the timeout.
+ *
+ * Uses directConnection=true so the driver doesn't follow the replica-set
+ * member list (which uses Docker-internal hostnames like "mongodb:27017"
+ * even when connecting via localhost port-forwarding).
+ */
+async function getVerificationToken(db, userId, timeoutMs = 10000) {
+  const eventstore = db.collection('eventstore')
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const event = await eventstore.findOne({
+      aggregateType: 'Token',
+      type: 'Created',
+      'payload.type': 'Verification',
+      createdBy: userId,
+    }, { sort: { _id: -1 } })
+    if (event?.payload?.token) return event.payload.token
+    await new Promise(r => setTimeout(r, 200))
+  }
+  throw new Error(`Verification token for user ${userId} not found within ${timeoutMs}ms`)
+}
+
+/**
+ * Polls MongoDB until a SignedUp event for the given email is found.
+ */
+async function getUserIdByEmail(db, email, timeoutMs = 10000) {
+  const eventstore = db.collection('eventstore')
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const event = await eventstore.findOne({
+      aggregateType: 'User',
+      type: 'SignedUp',
+      'payload.email': email,
+    }, { sort: { _id: -1 } })
+    if (event?.aggregateId) return event.aggregateId
+    await new Promise(r => setTimeout(r, 200))
+  }
+  throw new Error(`SignedUp event for ${email} not found within ${timeoutMs}ms`)
+}
+
+/**
+ * Polls MongoDB until the workspace aggregate for the given userId appears.
+ * Not fatal if it doesn't arrive — tests that rely on workspace state should
+ * handle the null return.
+ */
+async function waitForWorkspaceAggregate(db, userId, timeoutMs = 15000) {
+  const aggregates = db.collection('aggregates')
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const workspace = await aggregates.findOne({
+      type: 'Workspace',
+      'state.users': userId,
+    })
+    if (workspace) return workspace
+    await new Promise(r => setTimeout(r, 300))
+  }
+  return null
+}
+
+/**
+ * Signs up a new user via the API and returns `{ email, userId, token }`.
+ *
+ * Waits for the workspace aggregate to be built so tests that rely on
+ * `useWorkspaces()` for the post-login redirect will find a workspace
+ * immediately. Uses a unique email per call to avoid cross-run conflicts.
+ */
+export async function signUpAndGetToken(firstName = 'Test', lastName = 'User') {
+  const email = `e2e-${Date.now()}@ossy.local`
+  const client = new MongoClient(DB_URL, { directConnection: true })
+  try {
+    await client.connect()
+    const db = client.db(DB_NAME)
+
+    const res = await fetch(`${API_URL}/users/sign-up`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ email, firstName, lastName }),
+    })
+    if (!res.ok) throw new Error(`Sign-up failed with status ${res.status}`)
+
+    const userId = await getUserIdByEmail(db, email)
+    const token = await getVerificationToken(db, userId)
+    await waitForWorkspaceAggregate(db, userId)
+
+    return { email, userId, token }
+  } finally {
+    await client.close()
+  }
+}
+
+/**
+ * Calls the verify-sign-in endpoint and returns the raw Set-Cookie header.
+ */
+export async function verifySignIn(token) {
+  const res = await fetch(`${API_URL}/users/verify-sign-in?token=${token}`)
+  if (!res.ok) throw new Error(`Verify sign-in failed with status ${res.status}`)
+  const cookie = res.headers.get('set-cookie')
+  if (!cookie) throw new Error('No Set-Cookie header in verify-sign-in response')
+  return cookie
+}

package/src/test/index.js

@@ -1 +1,2 @@
 export * from './test.util.js'
+export * from './e2e.util.js'

package/src/test/playwright.config.js

@@ -0,0 +1,30 @@
+/**
+ * Reusable Playwright configuration for Ossy feature-package e2e tests.
+ *
+ * Consuming projects can extend this config:
+ *
+ *   // playwright.config.js
+ *   import base from '@ossy/platform/test/playwright.config.js'
+ *   export default { ...base, testDir: './tests' }
+ *
+ * Environment variables (all optional — sensible defaults provided):
+ *   OSSY_APP_URL   Base URL of the running web client  (default: http://localhost:3002)
+ *   OSSY_API_URL   Base URL of the API server           (default: http://localhost:3001/api/v0)
+ *   DB_URL         MongoDB connection string             (default: mongodb://localhost:27017/)
+ *   DB_NAME        MongoDB database name                 (default: ossy-local)
+ */
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+export default {
+  retries: process.env.CI ? 1 : 0,
+  use: {
+    baseURL: process.env.OSSY_APP_URL ?? process.env.BASE_URL ?? 'http://localhost:3002',
+  },
+  reporter: [['list']],
+  env: {
+    OSSY_APP_URL: process.env.OSSY_APP_URL ?? process.env.BASE_URL ?? 'http://localhost:3002',
+    OSSY_API_URL: process.env.OSSY_API_URL ?? process.env.API_URL ?? 'http://localhost:3001/api/v0',
+    DB_URL: process.env.DB_URL ?? 'mongodb://localhost:27017/',
+    DB_NAME: process.env.DB_NAME ?? 'ossy-local',
+  },
+}