@ossy/app 1.40.2 → 3.0.1

package/README.md

@@ -70,6 +70,12 @@ export default {
 }
 ```
 
+Optional flags:
+
+| Key | Default | Purpose |
+|-----|---------|---------|
+| `enablePushInvalidation` | `false` | App-wide SSE cache invalidation. Prefer `<PushInvalidationSubscriber />` on specific pages instead — see [@ossy/sdk-react README](../sdk-react/README.md#push-invalidation). |
+
 Config is loaded at build time and merged with request-time settings (e.g. user theme preference from cookies).
 
 ## API routes
@@ -94,40 +100,71 @@ Build output: `build/.ossy/api.generated.json` — a registry of `[{ id, path, m
 
 ## Background tasks (`*.task.js`)
 
-For background job processors, create `*.task.js` files in `src/`. Each file exports a `metadata` object with a `type` field and a default handler function.
+Task modules export `metadata` (id, optional `triggers` / `schedule`) and a `run` function. They are registered by `TaskService` at server startup.
+
+**Sync invoke:** `POST /actions` with `{ action, payload }` awaits the primary task at `{feature}/tasks/{intent}` derived from the action id.
+
+**Async:** changestream events and cron schedules dispatch matching tasks without blocking the caller.
+
+Build output includes task entries in the manifest for server registration. Async execution does **not** use a separate polling worker — see ADR 0003.
+
+Task ids use the canonical form `@ossy/{feature}/tasks/{intent}`. Action ids (`@ossy/{feature}/actions/{intent}`) map to their primary task via ADR 0003.
+
+## Schemas (`*.schema.js`)
+
+Resource document schemas are POJOs default-exported from `*.schema.js` in `src/` or installed feature packages. The build discovers them, validates canonical ids (`@{provider}/{feature}/schema/{concept}`), and merges them into `manifest.schemas`.
 
 ```js
-// src/send-email.task.js
-export const metadata = {
-  type: 'send-email',
+// packages/booking/src/service.schema.js
+export default {
+  id: '@ossy/booking/schema/service',
+  name: 'Service',
+  fields: [{ name: 'name', type: 'text', required: true }],
 }
+```
+
+Forms reference a schema via `metadata.schemaId` (not `templateId`).
+
+## Forms (`*.form.js`)
+
+Form modules export intent metadata only — field definitions live on the schema:
 
-export default async function handle({ sdk, job }) {
-  // process the job
+```js
+export const metadata = {
+  id: '@ossy/booking/form/service',
+  schemaId: '@ossy/booking/schema/service',
 }
 ```
 
-The worker polls the job queue every 3 seconds and lazy-imports the handler module the first time a job of that type arrives.
+## Build manifest
+
+`app build` writes `build/manifest.json` plus derived catalogs:
+
+| Output | Purpose |
+|--------|---------|
+| `manifest.json` | Pages, actions, tasks, `schemas`, components, layouts, `taskCatalog`, `taskGraphEdges`, … |
+| `build/capabilities.json` | Automation UI catalog — actions, tasks, schemas, edges |
+| `build/actions.schema.json` | JSON Schema for agent/MCP tool inputs per action |
 
-Build output: `build/.ossy/tasks.generated.json` — a registry of `[{ type, module }]` entries. Run the worker with `node build/worker.js`. Requires `OSSY_WORKSPACE_ID`, `OSSY_API_URL`, and `OSSY_API_TOKEN` environment variables.
+Action and task metadata are validated at build time via `@ossy/schema`. Task triggers reference schema ids (`type: '@ossy/platform/schema/file'`) and lifecycle events (`Created`, `Patched`, …).
 
 ## Components (`*.component.jsx`)
 
 Register injectable UI via `*.component.jsx` in `src/` or feature packages. Components are bundled separately and resolved into slots at runtime.
 
-**Shell chrome** — the app assigns placement in `*.layout.jsx`:
+**App chrome** — the app assigns placement in `*.layout.jsx`:
 
 ```jsx
 export const slots = {
-  'shell:header': 'app-header',
-  'shell:sidebar': 'app-sidebar',
+  'app:header': 'app-header',
+  'app:sidebar': 'app-sidebar',
 }
 ```
 
 **Resource / input UI** — feature packages use `metadata.id` as the slot key:
 
 ```jsx
-export const metadata = { id: 'resource:booking/service/form' }
+export const metadata = { id: '@ossy/booking/form/service' }
 export default function ServiceForm() { … }
 ```
 

package/cli/build.task.js

@@ -13,7 +13,7 @@ import getPlatformFiles, {
   PAGE_FILE_PATTERN,
   API_FILE_PATTERN,
   TASK_FILE_PATTERN,
-  RESOURCE_FILE_PATTERN,
+  SCHEMA_FILE_PATTERN,
   COMPONENT_FILE_PATTERN,
   AGGREGATE_FILE_PATTERN,
   INTEGRATION_FILE_PATTERN,
@@ -21,13 +21,14 @@ import getPlatformFiles, {
   EMAIL_FILE_PATTERN,
   ACTION_FILE_PATTERN,
   E2E_FILE_PATTERN,
+  FLOW_FILE_PATTERN,
   LAYOUT_FILE_PATTERN,
   TRANSLATIONS_FILE_PATTERN,
 } from './get-platform-files.task.js'
 import { manifestPlugin } from './manifest-plugin.js'
 import { mergeAndEmitTranslations } from './merge-translations.task.js'
 
-export { PAGE_FILE_PATTERN, API_FILE_PATTERN, TASK_FILE_PATTERN, RESOURCE_FILE_PATTERN, COMPONENT_FILE_PATTERN, AGGREGATE_FILE_PATTERN, INTEGRATION_FILE_PATTERN, STARTUP_FILE_PATTERN, EMAIL_FILE_PATTERN, ACTION_FILE_PATTERN, E2E_FILE_PATTERN, LAYOUT_FILE_PATTERN, TRANSLATIONS_FILE_PATTERN }
+export { PAGE_FILE_PATTERN, API_FILE_PATTERN, TASK_FILE_PATTERN, SCHEMA_FILE_PATTERN, COMPONENT_FILE_PATTERN, AGGREGATE_FILE_PATTERN, INTEGRATION_FILE_PATTERN, STARTUP_FILE_PATTERN, EMAIL_FILE_PATTERN, ACTION_FILE_PATTERN, E2E_FILE_PATTERN, FLOW_FILE_PATTERN, LAYOUT_FILE_PATTERN, TRANSLATIONS_FILE_PATTERN }
 
 // Generated entry stubs live under `build/.ossy/entries/`. Putting them
 // inside `build/` means they're cleaned automatically with every build,
@@ -126,10 +127,8 @@ function generateTaskStub ({ stubAbs, sourceAbs }) {
   ].join('\n')
 }
 
-// Resources are pure data (POJOs default-exported from `*.resource.js`).
-// The stub only pass-through re-exports the default so the manifest plugin
-// can read it via the same `await import(chunkUrl)` path as the other kinds.
-function generateResourceStub ({ stubAbs, sourceAbs }) {
+// Schemas are pure data (POJOs default-exported from `*.schema.js`).
+function generateSchemaStub ({ stubAbs, sourceAbs }) {
   const importPath = relImport(stubAbs, sourceAbs)
   return [
     '// Generated by @ossy/app — do not edit',
@@ -166,7 +165,22 @@ function generateAggregateStub ({ stubAbs, sourceAbs }) {
 // Integrations are server-side only. The stub re-exports `id`, `credentials`,
 // and `connect` so the manifest plugin can validate them and the platform
 // server can call `connect({ env })` at startup.
-function generateIntegrationStub ({ stubAbs, sourceAbs }) {
+//
+// grafana-metrics mutates a package singleton (`metrics`). A relative re-export
+// gets bundled into its own copy, so TaskService recordings never reach
+// connect() — re-export via @ossy/observability to keep one module instance.
+function generateIntegrationStub ({ stubAbs, sourceAbs, packageName }) {
+  const base = path.basename(sourceAbs)
+  if (packageName === '@ossy/observability' && base === 'grafana-metrics.integration.js') {
+    return [
+      '// Generated by @ossy/app — do not edit',
+      "import { grafanaMetricsIntegration } from '@ossy/observability'",
+      'export const id = grafanaMetricsIntegration.id',
+      'export const credentials = grafanaMetricsIntegration.credentials',
+      'export const connect = grafanaMetricsIntegration.connect',
+      '',
+    ].join('\n')
+  }
   const importPath = relImport(stubAbs, sourceAbs)
   return [
     '// Generated by @ossy/app — do not edit',
@@ -208,6 +222,16 @@ function generateActionStub ({ stubAbs, sourceAbs }) {
   ].join('\n')
 }
 
+// Forms are intent metadata (schemaId reference). Field schema lives on the resource.
+function generateFormStub ({ stubAbs, sourceAbs }) {
+  const importPath = relImport(stubAbs, sourceAbs)
+  return [
+    '// Generated by @ossy/app — do not edit',
+    `export { metadata } from '${importPath}'`,
+    '',
+  ].join('\n')
+}
+
 // E2e tests are Playwright test modules. The stub re-exports `id`, `feature`,
 // `requires`, and the default test function so the manifest plugin can validate
 // them and the e2e runner can import and execute them.
@@ -220,6 +244,15 @@ function generateE2eStub ({ stubAbs, sourceAbs }) {
   ].join('\n')
 }
 
+function generateFlowStub ({ stubAbs, sourceAbs }) {
+  const importPath = relImport(stubAbs, sourceAbs)
+  return [
+    '// Generated by @ossy/app — do not edit',
+    `export { metadata, default } from '${importPath}'`,
+    '',
+  ].join('\n')
+}
+
 // Layouts are React components that wrap page renders. The stub re-exports
 // everything (including required `id`) plus the
 // default component so the manifest plugin can validate them and the server
@@ -237,14 +270,16 @@ function generateLayoutStub ({ stubAbs, sourceAbs }) {
 function stubFor (kind, args) {
   if (kind === 'page') return generatePageStub(args)
   if (kind === 'api') return generateApiStub(args)
-  if (kind === 'resource') return generateResourceStub(args)
+  if (kind === 'schema') return generateSchemaStub(args)
   if (kind === 'component') return generateComponentStub(args)
   if (kind === 'aggregate') return generateAggregateStub(args)
   if (kind === 'integration') return generateIntegrationStub(args)
   if (kind === 'startup') return generateStartupStub(args)
   if (kind === 'email') return generateEmailStub(args)
   if (kind === 'action') return generateActionStub(args)
+  if (kind === 'form') return generateFormStub(args)
   if (kind === 'e2e') return generateE2eStub(args)
+  if (kind === 'flow') return generateFlowStub(args)
   if (kind === 'layout') return generateLayoutStub(args)
   return generateTaskStub(args)
 }
@@ -294,14 +329,16 @@ export async function build (cliArgs = []) {
     ...platformFiles.pages,
     ...platformFiles.apis,
     ...platformFiles.tasks,
-    ...platformFiles.resources,
+    ...platformFiles.schemas,
     ...platformFiles.components,
     ...platformFiles.aggregates,
     ...platformFiles.integrations,
     ...platformFiles.startups,
     ...platformFiles.emails,
     ...platformFiles.actions,
+    ...platformFiles.forms,
     ...platformFiles.e2es,
+    ...platformFiles.flows,
     ...platformFiles.layouts,
   ]
 
@@ -313,7 +350,7 @@ export async function build (cliArgs = []) {
     const effectiveSrcDir = packageSrcDir || srcDir
     const inputName = entryNameFromSource(sourcePath, effectiveSrcDir, packageName)
     const stubAbs = path.join(stubDir, stubFileNameFor(kind, sourcePath, effectiveSrcDir, packageName))
-    fs.writeFileSync(stubAbs, stubFor(kind, { stubAbs, sourceAbs: sourcePath }), 'utf8')
+    fs.writeFileSync(stubAbs, stubFor(kind, { stubAbs, sourceAbs: sourcePath, packageName, packageSrcDir }), 'utf8')
     stubInputMap[inputName] = stubAbs
     entriesByStub.set(stubAbs, { kind, sourcePath, packageName, packageSrcDir })
   }
@@ -350,6 +387,8 @@ export async function build (cliArgs = []) {
       if (id === '@ossy/platform' || id.startsWith('@ossy/platform/')) return true
       if (id === '@ossy/event-store' || id.startsWith('@ossy/event-store/')) return true
       if (id === '@ossy/observability' || id.startsWith('@ossy/observability/')) return true
+      // Shared in-memory outbox — email integration appends, dev-inbox API reads.
+      if (id === '@ossy/email/local-outbox') return true
       return false
     },
     plugins: [

package/cli/get-platform-files.task.js

@@ -4,19 +4,21 @@ import path from 'node:path'
 export const PAGE_FILE_PATTERN = /\.page\.(jsx?|tsx?)$/
 export const API_FILE_PATTERN = /\.api\.(mjs|cjs|js)$/
 export const TASK_FILE_PATTERN = /\.task\.(mjs|cjs|js)$/
-export const RESOURCE_FILE_PATTERN = /\.resource\.(mjs|cjs|js)$/
+export const SCHEMA_FILE_PATTERN = /\.schema\.(mjs|cjs|js)$/
 export const COMPONENT_FILE_PATTERN = /\.component\.(jsx?|tsx?)$/
 export const AGGREGATE_FILE_PATTERN = /\.aggregate\.(mjs|cjs|js)$/
 export const INTEGRATION_FILE_PATTERN = /\.integration\.(mjs|cjs|js)$/
 export const STARTUP_FILE_PATTERN = /\.startup\.(mjs|cjs|js)$/
 export const EMAIL_FILE_PATTERN = /\.email\.(jsx?|tsx?)$/
 export const ACTION_FILE_PATTERN = /\.action\.(mjs|cjs|js)$/
+export const FORM_FILE_PATTERN = /\.form\.(mjs|cjs|js)$/
 export const E2E_FILE_PATTERN = /\.e2e\.(mjs|cjs|js)$/
+export const FLOW_FILE_PATTERN = /\.flow\.(mjs|cjs|js)$/
 export const LAYOUT_FILE_PATTERN = /\.layout\.(jsx?|tsx?)$/
 export const TRANSLATIONS_FILE_PATTERN = /\.translations\.json$/
 
 /**
- * @typedef {'page' | 'api' | 'task' | 'resource' | 'component' | 'aggregate' | 'integration' | 'startup' | 'email' | 'action' | 'e2e' | 'layout'} EntryKind
+ * @typedef {'page' | 'api' | 'task' | 'schema' | 'component' | 'aggregate' | 'integration' | 'startup' | 'email' | 'action' | 'form' | 'e2e' | 'flow' | 'layout'} EntryKind
  *
  * @typedef {object} PlatformEntry
  * @property {EntryKind} kind          Which bucket this entry lives in.
@@ -28,15 +30,17 @@ export const TRANSLATIONS_FILE_PATTERN = /\.translations\.json$/
  * @property {PlatformEntry[]} pages         Discovered `*.page.{jsx,tsx,...}` entries.
  * @property {PlatformEntry[]} apis          Discovered `*.api.{js,mjs,cjs}` entries.
  * @property {PlatformEntry[]} tasks         Discovered `*.task.{js,mjs,cjs}` entries.
- * @property {PlatformEntry[]} resources     Discovered `*.resource.{js,mjs,cjs}` entries.
+ * @property {PlatformEntry[]} schemas       Discovered `*.schema.{js,mjs,cjs}` entries (ADR 0006).
  * @property {PlatformEntry[]} components    Discovered `*.component.{jsx,tsx,...}` entries.
  * @property {PlatformEntry[]} aggregates    Discovered `*.aggregate.{js,mjs,cjs}` entries (installed packages only).
  * @property {PlatformEntry[]} integrations  Discovered `*.integration.{js,mjs,cjs}` entries.
  * @property {PlatformEntry[]} startups      Discovered `*.startup.{js,mjs,cjs}` entries.
  * @property {PlatformEntry[]} emails        Discovered `*.email.{jsx,tsx,...}` entries.
  * @property {PlatformEntry[]} actions       Discovered `*.action.{js,mjs,cjs}` entries.
+ * @property {PlatformEntry[]} forms         Discovered `*.form.{js,mjs,cjs}` entries.
  * @property {PlatformEntry[]} e2es          Discovered `*.e2e.{js,mjs,cjs}` entries (installed packages only).
- * @property {PlatformEntry[]} layouts       Discovered `*.layout.{jsx,tsx,...}` entries (app root `src/` only — never from installed packages).
+ * @property {PlatformEntry[]} flows         Discovered `*.flow.{js,mjs,cjs}` entries (installed packages only).
+ * @property {PlatformEntry[]} layouts       Discovered `*.layout.{jsx,tsx,...}` entries (app and installed packages).
  */
 export function discoverFilesByPattern (srcDir, filePattern) {
   const dir = path.resolve(srcDir)
@@ -58,14 +62,16 @@ function classifyFile (absPath) {
   if (PAGE_FILE_PATTERN.test(base)) return 'page'
   if (API_FILE_PATTERN.test(base)) return 'api'
   if (TASK_FILE_PATTERN.test(base)) return 'task'
-  if (RESOURCE_FILE_PATTERN.test(base)) return 'resource'
+  if (SCHEMA_FILE_PATTERN.test(base)) return 'schema'
   if (COMPONENT_FILE_PATTERN.test(base)) return 'component'
   if (AGGREGATE_FILE_PATTERN.test(base)) return 'aggregate'
   if (INTEGRATION_FILE_PATTERN.test(base)) return 'integration'
   if (STARTUP_FILE_PATTERN.test(base)) return 'startup'
   if (EMAIL_FILE_PATTERN.test(base)) return 'email'
   if (ACTION_FILE_PATTERN.test(base)) return 'action'
+  if (FORM_FILE_PATTERN.test(base)) return 'form'
   if (E2E_FILE_PATTERN.test(base)) return 'e2e'
+  if (FLOW_FILE_PATTERN.test(base)) return 'flow'
   if (LAYOUT_FILE_PATTERN.test(base)) return 'layout'
   return null
 }
@@ -167,16 +173,17 @@ export function discoverInstalledPackageEntries (projectRoot) {
       ...discoverFilesByPattern(packageSrcDir, PAGE_FILE_PATTERN),
       ...discoverFilesByPattern(packageSrcDir, API_FILE_PATTERN),
       ...discoverFilesByPattern(packageSrcDir, TASK_FILE_PATTERN),
-      ...discoverFilesByPattern(packageSrcDir, RESOURCE_FILE_PATTERN),
+      ...discoverFilesByPattern(packageSrcDir, SCHEMA_FILE_PATTERN),
       ...discoverFilesByPattern(packageSrcDir, COMPONENT_FILE_PATTERN),
       ...discoverFilesByPattern(packageSrcDir, AGGREGATE_FILE_PATTERN),
       ...discoverFilesByPattern(packageSrcDir, INTEGRATION_FILE_PATTERN),
       ...discoverFilesByPattern(packageSrcDir, STARTUP_FILE_PATTERN),
       ...discoverFilesByPattern(packageSrcDir, EMAIL_FILE_PATTERN),
       ...discoverFilesByPattern(packageSrcDir, ACTION_FILE_PATTERN),
+      ...discoverFilesByPattern(packageSrcDir, FORM_FILE_PATTERN),
       ...discoverFilesByPattern(packageSrcDir, E2E_FILE_PATTERN),
-      // Layouts are intentionally excluded: *.layout.jsx is an app-level
-      // primitive only. Feature packages must never define layouts.
+      ...discoverFilesByPattern(packageSrcDir, FLOW_FILE_PATTERN),
+      ...discoverFilesByPattern(packageSrcDir, LAYOUT_FILE_PATTERN),
     ]
     for (const sourcePath of files) {
       const stat = fs.statSync(sourcePath)
@@ -222,21 +229,20 @@ export function discoverInstalledPackageEntries (projectRoot) {
  * @returns {Promise<PlatformFiles>}
  */
 export default async function getPlatformFiles (srcDir) {
-  const out = { pages: [], apis: [], tasks: [], resources: [], components: [], aggregates: [], integrations: [], startups: [], emails: [], actions: [], e2es: [], layouts: [] }
-  const bucketByKind = { page: 'pages', api: 'apis', task: 'tasks', resource: 'resources', component: 'components', aggregate: 'aggregates', integration: 'integrations', startup: 'startups', email: 'emails', action: 'actions', e2e: 'e2es', layout: 'layouts' }
+  const out = { pages: [], apis: [], tasks: [], schemas: [], components: [], aggregates: [], integrations: [], startups: [], emails: [], actions: [], forms: [], e2es: [], flows: [], layouts: [] }
+  const bucketByKind = { page: 'pages', api: 'apis', task: 'tasks', schema: 'schemas', component: 'components', aggregate: 'aggregates', integration: 'integrations', startup: 'startups', email: 'emails', action: 'actions', form: 'forms', e2e: 'e2es', flow: 'flows', layout: 'layouts' }
 
   // Aggregates and e2e tests are only discovered from installed packages — never
   // from the local `src/` — to avoid pulling in per-project duplicates of the
   // same aggregate class or test suite that is canonically owned by the feature
   // package.
-  // Layouts are the opposite restriction: they are only discovered from the
-  // app's own `src/`, never from installed packages. Feature packages are pure
-  // content (pages, actions, tasks, etc.) and must never define layouts.
+  // Layouts are discovered from the app's `src/` and from installed packages
+  // (`@ossy/app` ships default layouts via `ossy.src`).
   const localFiles = [
     ...discoverFilesByPattern(srcDir, PAGE_FILE_PATTERN),
     ...discoverFilesByPattern(srcDir, API_FILE_PATTERN),
     ...discoverFilesByPattern(srcDir, TASK_FILE_PATTERN),
-    ...discoverFilesByPattern(srcDir, RESOURCE_FILE_PATTERN),
+    ...discoverFilesByPattern(srcDir, SCHEMA_FILE_PATTERN),
     ...discoverFilesByPattern(srcDir, COMPONENT_FILE_PATTERN),
     ...discoverFilesByPattern(srcDir, INTEGRATION_FILE_PATTERN),
     ...discoverFilesByPattern(srcDir, STARTUP_FILE_PATTERN),
@@ -248,7 +254,7 @@ export default async function getPlatformFiles (srcDir) {
     const stat = fs.statSync(sourcePath)
     if (!stat.isFile() || stat.size === 0) continue
     const kind = classifyFile(sourcePath)
-    if (!kind || kind === 'aggregate' || kind === 'e2e') continue
+    if (!kind || kind === 'aggregate' || kind === 'e2e' || kind === 'flow') continue
     out[bucketByKind[kind]].push({ kind, sourcePath })
   }