@ossy/app 1.40.2 → 1.40.3

package/cli/manifest-plugin.js

@@ -4,6 +4,16 @@ import { pathToFileURL } from 'node:url'
 
 import { metadataIdFromFile, defaultPageRoute } from './get-platform-files.task.js'
 import { discoverPackageDefinitions } from '../src/manifest/discover-package-definitions.js'
+import { buildActionsSchema } from '../src/manifest/build-actions-schema.js'
+import { buildCapabilities } from '../src/manifest/build-capabilities.js'
+import { extractTaskCatalogEntry, buildTaskCatalogEdges } from '../src/manifest/extract-task-catalog.js'
+import {
+  Schema,
+  isActionId,
+  taskIdFromActionId,
+  CAPABILITY_SCHEMA_ID,
+} from '@ossy/schema'
+import { isCanonicalSchemaId } from '@ossy/schema'
 
 /**
  * @typedef {import('./get-platform-files.task.js').PlatformEntry} PlatformEntry
@@ -62,14 +72,19 @@ import { discoverPackageDefinitions } from '../src/manifest/discover-package-def
  * @property {string} entry  URL the platform serves the startup bundle from.
  *
  * @typedef {object} EmailManifestEntry
- * @property {string} id     Unique email id (e.g. `'authentication/verify-sign-in'`).
+ * @property {string} id     Unique email id (e.g. `'@ossy/authentication/emails/verify-sign-in'`).
  * @property {string} entry  URL the platform serves the email bundle from.
  *
  * @typedef {object} ActionManifestEntry
- * @property {string} id      Unique action slug (e.g. `'authentication/request-sign-in'`).
+ * @property {string} id      Unique action slug (e.g. `'@ossy/authentication/actions/request-sign-in'`).
  * @property {string} entry   URL the platform serves the action bundle from.
  * @property {string} access  Access level: `'public'` | `'authenticated'` | `'workspace'`.
  *
+ * @typedef {object} FormManifestEntry
+ * @property {string} id           Unique form slug (e.g. `'@ossy/authentication/form/sign-up'`).
+ * @property {string} schemaId   Resource schema id (e.g. `'@ossy/authentication/sign-up'`).
+ * @property {string} entry        URL the platform serves the form bundle from.
+ *
  * @typedef {object} LayoutManifestEntry
  * @property {string} id      Unique layout id (e.g. `'app-shell'`).
  * @property {string} entry   URL the platform serves the layout bundle from.
@@ -82,16 +97,24 @@ import { discoverPackageDefinitions } from '../src/manifest/discover-package-def
  * @property {string[]} requires  Runtime dependencies needed (e.g. `['server', 'database']`).
  * @property {string} entry    URL the platform serves the e2e bundle from.
  *
+ * @typedef {object} FlowManifestEntry
+ * @property {string} id       Unique flow id (e.g. `'@ossy/authentication/actions/sign-up'`).
+ * @property {string} feature  Grouping label (e.g. `'authentication'`).
+ * @property {string[]} requires  Runtime dependencies needed (e.g. `['server', 'database']`).
+ * @property {string} entry    URL the platform serves the flow bundle from.
+ *
  * @typedef {object} Manifest
  * @property {ManifestEntry[]} entries              Flat, ordered list of every routable thing.
  * @property {ComponentManifestEntry[]} components  Discovered `*.component.*` entries, keyed by id.
- * @property {object[]} resourceTemplates           Each `*.resource.js` file's default-exported template object.
+ * @property {object[]} schemas           Each `*.schema.js` file's default-exported template object.
  * @property {AggregateManifestEntry[]} aggregates  Discovered `*.aggregate.js` entries from installed packages.
  * @property {IntegrationManifestEntry[]} integrations  Discovered `*.integration.js` entries.
  * @property {StartupManifestEntry[]} startups      Discovered `*.startup.js` entries.
  * @property {EmailManifestEntry[]} emails          Discovered `*.email.{jsx,tsx}` entries.
  * @property {ActionManifestEntry[]} actions        Discovered `*.action.js` entries.
+ * @property {FormManifestEntry[]} forms           Discovered `*.form.js` entries.
  * @property {E2eManifestEntry[]} e2es              Discovered `*.e2e.js` entries from installed packages.
+ * @property {FlowManifestEntry[]} flows            Discovered `*.flow.js` entries from installed packages.
  * @property {LayoutManifestEntry[]} layouts        Discovered `*.layout.{jsx,tsx}` entries (includes app `slots` map).
  * @property {object} config                        Inlined `src/config.js` default export.
  * @property {Record<string, object>} [definitions] Package Definition metadata keyed by slug.
@@ -131,6 +154,12 @@ import { discoverPackageDefinitions } from '../src/manifest/discover-package-def
  * @param {ManifestPluginOptions} options
  * @returns {import('rollup').Plugin}
  */
+function reportValidationError (plugin, result, sourcePath) {
+  if (result.ok) return
+  const message = result.errors?.[0]?.message ?? result.message ?? 'Validation failed'
+  plugin.error(`[@ossy/app][build] ${sourcePath}: ${message}`)
+}
+
 function entryPackage (entryInfo, appPackageName) {
   return entryInfo.packageName || appPackageName
 }
@@ -141,8 +170,10 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
     async writeBundle (_, bundle) {
       /** @type {ManifestEntry[]} */
       const entries = []
+      /** @type {Record<string, { path: string, method?: string, query?: string[] }>} */
+      const actionRoutes = {}
       /** @type {object[]} */
-      const resourceTemplates = []
+      const schemas = []
       /** @type {import('./get-platform-files.task.js').ComponentManifestEntry[]} */
       const components = []
       /** @type {AggregateManifestEntry[]} */
@@ -155,6 +186,8 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
       const emails = []
       /** @type {ActionManifestEntry[]} */
       const actions = []
+      /** @type {FormManifestEntry[]} */
+      const forms = []
       const seenIds = { page: new Set(), api: new Set(), task: new Set(), component: new Set() }
       const seenResourceIds = new Set()
       const seenAggregateIds = new Set()
@@ -162,12 +195,18 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
       const seenStartupIds = new Set()
       const seenEmailIds = new Set()
       const seenActionIds = new Set()
+      const seenFormIds = new Set()
       /** @type {E2eManifestEntry[]} */
       const e2es = []
       const seenE2eIds = new Set()
+      /** @type {FlowManifestEntry[]} */
+      const flows = []
+      const seenFlowIds = new Set()
       /** @type {LayoutManifestEntry[]} */
       const layouts = []
       const seenLayoutIds = new Set()
+      /** @type {Array<{ mod: object, entryInfo: import('./get-platform-files.task.js').PlatformEntry, url: string, pkg: string }>} */
+      const taskPending = []
       for (const fileName of Object.keys(bundle)) {
         const chunk = bundle[fileName]
         if (chunk.type !== 'chunk' || !chunk.isEntry) continue
@@ -268,8 +307,8 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
           continue
         }
 
-        // Actions are intent: `metadata` only (`{ id, access }`). Matching task
-        // with the same id holds `run` (see ADR 0003).
+        // Actions are intent: `metadata` only (`{ id, access }`). Primary implementation
+        // lives in `{feature}/tasks/{intent}` derived from the action id (ADR 0003).
         if (entryInfo.kind === 'action') {
           const actionId = mod?.metadata?.id
           if (typeof actionId !== 'string' || actionId.trim() === '') {
@@ -281,11 +320,47 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             this.error(`[@ossy/app][build] Duplicate action id "${actionId}"`)
           }
           const access = mod.metadata?.access ?? 'authenticated'
+          reportValidationError(
+            this,
+            Schema.of({ schemas: [] }).validate(
+              CAPABILITY_SCHEMA_ID.ACTION_META,
+              { id: actionId, ...(mod.metadata?.access != null ? { access: mod.metadata.access } : {}) },
+              { sourcePath: entryInfo.sourcePath },
+            ),
+            entryInfo.sourcePath,
+          )
           seenActionIds.add(actionId)
           actions.push({ id: actionId, entry: url, access, package: entryPackage(entryInfo, appPackageName) })
           continue
         }
 
+        // Forms are intent metadata (`metadata` only) referencing a resource template.
+        if (entryInfo.kind === 'form') {
+          const formId = mod?.metadata?.id
+          const schemaId = mod?.metadata?.schemaId
+          if (typeof formId !== 'string' || formId.trim() === '') {
+            this.error(
+              `[@ossy/app][build] form entry ${entryInfo.sourcePath} must export a non-empty string "metadata.id"`,
+            )
+          }
+          if (typeof schemaId !== 'string' || schemaId.trim() === '') {
+            this.error(
+              `[@ossy/app][build] form entry ${entryInfo.sourcePath} must export a non-empty string "metadata.schemaId"`,
+            )
+          }
+          if (seenFormIds.has(formId)) {
+            this.error(`[@ossy/app][build] Duplicate form id "${formId}"`)
+          }
+          seenFormIds.add(formId)
+          forms.push({
+            id: formId,
+            schemaId,
+            entry: url,
+            package: entryPackage(entryInfo, appPackageName),
+          })
+          continue
+        }
+
         // Aggregates are server-side classes — the bundle exports `Aggregate`
         // (the class) and `id` (the AggregateType string). They don't produce
         // routable entries; they accumulate into a separate `aggregates` array.
@@ -344,6 +419,36 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
           continue
         }
 
+        if (entryInfo.kind === 'flow') {
+          const flowMeta = mod?.metadata ?? mod?.default?.metadata ?? {}
+          const flowId = flowMeta.id ?? mod?.default?.id
+          const feature = flowMeta.feature
+          const requires = flowMeta.requires
+          const flowBody = mod?.default
+          if (typeof flowId !== 'string' || flowId.trim() === '') {
+            this.error(
+              `[@ossy/app][build] flow entry ${entryInfo.sourcePath} must export metadata.id`,
+            )
+          }
+          if (!flowBody || typeof flowBody !== 'object' || !Array.isArray(flowBody.steps)) {
+            this.error(
+              `[@ossy/app][build] flow entry ${entryInfo.sourcePath} must default-export an object with steps[]`,
+            )
+          }
+          if (seenFlowIds.has(flowId)) {
+            this.error(`[@ossy/app][build] Duplicate flow id "${flowId}"`)
+          }
+          seenFlowIds.add(flowId)
+          flows.push({
+            id: flowId,
+            feature: typeof feature === 'string' ? feature : '',
+            requires: Array.isArray(requires) ? requires : [],
+            entry: url,
+            package: entryPackage(entryInfo, appPackageName),
+          })
+          continue
+        }
+
         // Layouts wrap every page render. The bundle exports `id` and a default
         // export (the React component). Only one `*.layout.jsx` per app is
         // supported. They don't produce routable entries; they accumulate into
@@ -400,27 +505,51 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
           continue
         }
 
-        // Resources are pure data — the default export *is* the template.
-        // They don't use `metadata`, don't need a derived id, and don't
-        // produce a routable manifest entry; they accumulate into a separate
-        // `resourceTemplates` array on the manifest.
-        if (entryInfo.kind === 'resource') {
-          const template = mod && mod.default
-          if (!template || typeof template !== 'object' || Array.isArray(template)) {
+        if (entryInfo.kind === 'schema') {
+          const schema = mod && mod.default
+          if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
             this.error(
-              `[@ossy/app][build] resource entry ${entryInfo.sourcePath} must default-export an object`,
+              `[@ossy/app][build] schema entry ${entryInfo.sourcePath} must default-export an object`,
             )
           }
-          if (typeof template.id !== 'string' || template.id.trim() === '') {
+          if (typeof schema.id !== 'string' || schema.id.trim() === '') {
             this.error(
-              `[@ossy/app][build] resource entry ${entryInfo.sourcePath} default export is missing a non-empty string "id"`,
+              `[@ossy/app][build] schema entry ${entryInfo.sourcePath} default export is missing a non-empty string "id"`,
             )
           }
-          if (seenResourceIds.has(template.id)) {
-            this.error(`[@ossy/app][build] Duplicate resource template id "${template.id}"`)
+          if (!isCanonicalSchemaId(schema.id)) {
+            this.error(
+              `[@ossy/app][build] schema entry ${entryInfo.sourcePath} id must match @{provider}/{feature}/schema/{concept} — got "${schema.id}"`,
+            )
           }
-          seenResourceIds.add(template.id)
-          resourceTemplates.push({ ...template, package: entryPackage(entryInfo, appPackageName) })
+          if (seenResourceIds.has(schema.id)) {
+            this.error(`[@ossy/app][build] Duplicate schema id "${schema.id}"`)
+          }
+          seenResourceIds.add(schema.id)
+          schemas.push({ ...schema, package: entryPackage(entryInfo, appPackageName) })
+          continue
+        }
+
+        if (entryInfo.kind === 'task') {
+          const taskMeta = mod?.metadata
+          const taskId = taskMeta?.id
+          if (typeof taskId !== 'string' || taskId.trim() === '') {
+            this.error(
+              `[@ossy/app][build] task entry ${entryInfo.sourcePath} must export a non-empty string "metadata.id"`,
+            )
+          }
+          if (isActionId(taskId)) {
+            this.error(
+              `[@ossy/app][build] Task "${taskId}" uses /actions/ — use /tasks/ (e.g. "${taskIdFromActionId(taskId)}")`,
+            )
+          }
+          if (seenIds.task.has(taskId)) {
+            this.error(`[@ossy/app][build] Duplicate task id "${taskId}"`)
+          }
+          seenIds.task.add(taskId)
+          const pkg = entryPackage(entryInfo, appPackageName)
+          taskPending.push({ mod, entryInfo, url, pkg })
+          entries.push({ type: 'task', id: taskId, entry: url, package: pkg })
           continue
         }
 
@@ -438,7 +567,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
           if (mod.slot != null) {
             this.error(
               `[@ossy/app][build] component ${entryInfo.sourcePath} must not export \`slot\`. ` +
-              'Assign components to shell slots in `*.layout.jsx` via `export const slots`.',
+              'Assign components to app slots in `*.layout.jsx` via `export const slots`.',
             )
           }
           components.push({ id, entry: url, package: entryPackage(entryInfo, appPackageName) })
@@ -447,6 +576,19 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
 
         if (entryInfo.kind === 'page') {
           const pagePath = rawMeta.path !== undefined ? rawMeta.path : defaultPageRoute(id)
+          reportValidationError(
+            this,
+            Schema.of({ schemas: [] }).validate(
+              CAPABILITY_SCHEMA_ID.PAGE_META,
+              {
+                id,
+                path: pagePath,
+                ...(rawMeta.title != null ? { title: rawMeta.title } : {}),
+              },
+              { sourcePath: entryInfo.sourcePath },
+            ),
+            entryInfo.sourcePath,
+          )
           entries.push({
             type: 'page',
             id,
@@ -467,12 +609,74 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
               `Add a \`path\` to the metadata or default-export object (e.g. \`path: '/api/${id}'\`).`,
             )
           }
-          entries.push({ type: 'api', id, path: rawMeta.path, entry: url, package: entryPackage(entryInfo, appPackageName) })
-        } else {
-          entries.push({ type: 'task', id, entry: url, package: entryPackage(entryInfo, appPackageName) })
+          const apiEntry = {
+            type: 'api',
+            id,
+            path: rawMeta.path,
+            entry: url,
+            package: entryPackage(entryInfo, appPackageName),
+          }
+          if (typeof rawMeta.action === 'string' && rawMeta.action.trim()) {
+            apiEntry.action = rawMeta.action
+            apiEntry.method = rawMeta.method ?? 'GET'
+            if (Array.isArray(rawMeta.query)) apiEntry.query = rawMeta.query
+            actionRoutes[rawMeta.action] = {
+              path: rawMeta.path,
+              method: rawMeta.method ?? 'GET',
+              ...(Array.isArray(rawMeta.query) && rawMeta.query.length ? { query: rawMeta.query } : {}),
+            }
+          }
+          entries.push(apiEntry)
         }
       }
 
+      const actionIdSet = new Set(actions.map((a) => a.id))
+      const schemaIdSet = new Set(schemas.map((s) => s.id))
+      const taskIdList = taskPending.map(({ mod }) => mod?.metadata?.id).filter(Boolean)
+
+      const schemaEngine = Schema.of(
+        { schemas },
+        { actionIds: [...actionIdSet], taskIds: taskIdList, strictRefs: true },
+      )
+
+      for (const { mod, entryInfo } of taskPending) {
+        reportValidationError(
+          this,
+          schemaEngine.validate(CAPABILITY_SCHEMA_ID.TASK_META, mod?.metadata ?? {}, {
+            strictRefs: true,
+            schemaIds: schemaIdSet,
+            sourcePath: entryInfo.sourcePath,
+          }),
+          entryInfo.sourcePath,
+        )
+      }
+
+      const taskCatalog = taskPending.map(({ mod, url, pkg }) =>
+        extractTaskCatalogEntry({
+          metadata: mod?.metadata ?? {},
+          package: pkg,
+          entry: url,
+          actionIdsInManifest: actionIdSet,
+        }),
+      )
+
+      for (const entry of taskCatalog) {
+        reportValidationError(
+          this,
+          schemaEngine.validate(CAPABILITY_SCHEMA_ID.TASK_CAPABILITY, entry, {
+            strictRefs: true,
+            schemaIds: schemaIdSet,
+            actionIds: actionIdSet,
+            allowDerived: true,
+            allowUnknownKeys: true,
+            label: entry.id,
+          }),
+          entry.id,
+        )
+      }
+
+      const taskGraphEdges = buildTaskCatalogEdges(taskCatalog)
+
       if (layouts.length > 1) {
         this.error(
           `[@ossy/app][build] Only one *.layout.jsx per app is allowed (found ${layouts.length}). ` +
@@ -488,19 +692,40 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
       const manifest = {
         entries,
         components,
-        resourceTemplates,
+        schemas,
         aggregates,
         integrations,
         startups,
         emails,
         actions,
+        forms,
         e2es,
+        flows,
         layouts,
         definitions,
         config: configValue || {},
+        actionRoutes,
+        taskCatalog,
+        taskGraphEdges,
       }
       fs.mkdirSync(path.dirname(manifestPath), { recursive: true })
       fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8')
+
+      const buildDirPath = path.dirname(manifestPath)
+      const tasks = taskCatalog.map((t) => ({ id: t.id }))
+      const capabilities = buildCapabilities({
+        actions,
+        tasks,
+        schemas,
+        taskCatalog,
+        taskGraphEdges,
+      })
+      const capabilitiesPath = path.join(buildDirPath, 'capabilities.json')
+      fs.writeFileSync(capabilitiesPath, JSON.stringify(capabilities, null, 2), 'utf8')
+
+      const actionsSchemaPath = path.join(buildDirPath, 'actions.schema.json')
+      const actionsSchema = buildActionsSchema(actions, { schemas, tasks })
+      fs.writeFileSync(actionsSchemaPath, JSON.stringify(actionsSchema, null, 2), 'utf8')
     },
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/app",
-  "version": "1.40.2",
+  "version": "1.40.3",
   "description": "",
   "source": "./src/index.js",
   "main": "./src/index.js",
@@ -9,10 +9,12 @@
     ".": "./src/index.js",
     "./shell": "./src/shell/index.js",
     "./runtime/page-runtime": "./runtime/page-runtime.js",
-    "./runtime/resolve-shell-slots": "./runtime/resolve-shell-slots.js",
+    "./runtime/resolve-app-slots": "./runtime/resolve-app-slots.js",
     "./runtime/api-runtime": "./runtime/api-runtime.js",
     "./runtime/task-runtime": "./runtime/task-runtime.js",
     "./manifest/build-manifest-summary": "./src/manifest/build-manifest-summary.js",
+    "./manifest/build-actions-schema": "./src/manifest/build-actions-schema.js",
+    "./manifest/build-capabilities": "./src/manifest/build-capabilities.js",
     "./manifest/discover-package-definitions": "./src/manifest/discover-package-definitions.js",
     "./manifest/serialize-package-definition": "./src/manifest/serialize-package-definition.js"
   },
@@ -42,15 +44,17 @@
     "@babel/eslint-parser": "^7.15.8",
     "@babel/preset-react": "^7.26.3",
     "@babel/register": "^7.25.9",
-    "@ossy/design-system": "^1.40.2",
-    "@ossy/locale": "^1.40.2",
+    "@ossy/design-system": "^1.40.3",
+    "@ossy/locale": "^1.40.3",
     "@ossy/pages": "^1.23.0",
-    "@ossy/platform": "^1.39.2",
-    "@ossy/router": "^1.40.2",
-    "@ossy/router-react": "^1.40.2",
-    "@ossy/sdk": "^1.40.2",
-    "@ossy/sdk-react": "^1.40.2",
-    "@ossy/themes": "^1.40.2",
+    "@ossy/platform": "^1.39.3",
+    "@ossy/router": "^1.40.3",
+    "@ossy/router-react": "^1.40.3",
+    "@ossy/schema": "^1.0.1",
+    "@ossy/sdk": "^1.40.3",
+    "@ossy/sdk-react": "^1.40.3",
+    "@ossy/themes": "^1.40.3",
+    "@ossy/workspaces": "^1.17.3",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-babel": "^7.0.0",
     "@rollup/plugin-commonjs": "^29.0.0",
@@ -84,5 +88,5 @@
     "README.md",
     "tsconfig.json"
   ],
-  "gitHead": "2b8745d57fee8b6c08787e2755b4df489291a5cd"
+  "gitHead": "a0d89185a17f8de8ce328c3a648c108ff1d61d8f"
 }

package/runtime/page-runtime.js

@@ -1,7 +1,7 @@
 import { createElement } from 'react'
 import { pageIdToDocumentTitleKey, resolveMessage } from '@ossy/locale'
 import { App } from '../src/shell/App.jsx'
-import { resolvePageSlots } from './resolve-shell-slots.js'
+import { resolvePageSlots } from './resolve-app-slots.js'
 
 /**
  * Dynamically imports each component bundle listed in `entries` and returns a
@@ -129,10 +129,11 @@ export function createPageEntry (pageModule, options = {}) {
 
     const { Layout = null, componentEntries = [], layoutSlots = {}, ...pageProps } = props
     const componentsById = await loadComponents(componentEntries)
+    const PageContent = (slotProps = {}) => createElement(Component, { ...pageProps, ...slotProps })
     const components = resolvePageSlots({
       layoutSlots,
       componentsById,
-      pageComponent: Component,
+      pageComponent: PageContent,
     })
     const tree = buildTree({ Component, Layout, metadata, props: { ...pageProps, components } })
     const bootstrapUrl = toBootstrapUrl(entryUrl)
@@ -175,10 +176,11 @@ export function createPageEntry (pageModule, options = {}) {
       loadComponents(componentEntries),
       loadLayout(layoutEntry),
     ]).then(([{ hydrateRoot }, componentsById, Layout]) => {
+      const PageContent = (slotProps = {}) => createElement(Component, { ...pageProps, ...slotProps })
       const components = resolvePageSlots({
         layoutSlots,
         componentsById,
-        pageComponent: Component,
+        pageComponent: PageContent,
       })
       hydrateRoot(document, buildTree({ Component, Layout, metadata, props: { ...pageProps, components } }))
     }).catch((err) => {

package/runtime/resolve-app-slots.js

@@ -0,0 +1,89 @@
+/** Canonical app chrome slot names (namespaced). App layout maps chrome only — not content. */
+export const APP_SLOT_NAMES = [
+  'app:header',
+  'app:sidebar',
+  'app:toolbar',
+  'app:notifications',
+  'app:system-messages',
+]
+
+/** Platform-owned slot filled with the current route page component. */
+export const CONTENT_SLOT_NAME = 'app:content'
+
+const APP_SLOT_PREFIX = 'app'
+
+/** Bare app region → namespaced key (legacy fallback for app components only). */
+const BARE_APP_REGION = {
+  header: 'app:header',
+  sidebar: 'app:sidebar',
+  toolbar: 'app:toolbar',
+  notifications: 'app:notifications',
+  'system-messages': 'app:system-messages',
+  content: CONTENT_SLOT_NAME,
+}
+
+/**
+ * Normalize a slot map key to the canonical namespaced form when it is a bare app region.
+ *
+ * @param {string} slotName
+ * @returns {string}
+ */
+export function normalizeAppSlotName (slotName) {
+  const key = typeof slotName === 'string' ? slotName.trim() : ''
+  return BARE_APP_REGION[key] ?? key
+}
+
+/**
+ * Build `Record<slotName, Component>` from the app layout's static `slots` map
+ * (`slotName → componentId`) and components loaded by `metadata.id`.
+ *
+ * @param {Record<string, string> | null | undefined} layoutSlotsMap
+ * @param {Record<string, import('react').ComponentType>} componentsById
+ * @returns {Record<string, import('react').ComponentType>}
+ */
+export function resolveAppSlots (layoutSlotsMap, componentsById) {
+  /** @type {Record<string, import('react').ComponentType>} */
+  const resolved = {}
+
+  const map = layoutSlotsMap && typeof layoutSlotsMap === 'object' ? layoutSlotsMap : {}
+  for (const [rawSlot, componentId] of Object.entries(map)) {
+    const slotName = normalizeAppSlotName(rawSlot)
+    const id = typeof componentId === 'string' ? componentId.trim() : ''
+    if (!slotName || !id || slotName === CONTENT_SLOT_NAME) continue
+    const Component = componentsById[id]
+    if (Component) resolved[slotName] = Component
+  }
+
+  for (const slotName of APP_SLOT_NAMES) {
+    if (resolved[slotName]) continue
+    if (componentsById[slotName]) {
+      resolved[slotName] = componentsById[slotName]
+      continue
+    }
+    const bare = slotName.slice(`${APP_SLOT_PREFIX}:`.length)
+    if (componentsById[bare]) resolved[slotName] = componentsById[bare]
+  }
+
+  return resolved
+}
+
+/**
+ * Full provider slot map for a page request: app chrome and page content.
+ * Feature components register at canonical ADR 0006 ids (`@ossy/…/view|form/…`).
+ *
+ * @param {{
+ *   layoutSlots?: Record<string, string> | null,
+ *   componentsById?: Record<string, import('react').ComponentType>,
+ *   pageComponent?: import('react').ComponentType | null,
+ * }} options
+ * @returns {Record<string, import('react').ComponentType>}
+ */
+export function resolvePageSlots ({ layoutSlots, componentsById = {}, pageComponent = null } = {}) {
+  const appSlots = resolveAppSlots(layoutSlots, componentsById)
+  /** @type {Record<string, import('react').ComponentType>} */
+  const resolved = { ...componentsById, ...appSlots }
+  if (pageComponent) {
+    resolved[CONTENT_SLOT_NAME] = pageComponent
+  }
+  return resolved
+}

package/src/manifest/action-id-to-tool-name.js

@@ -0,0 +1,29 @@
+/**
+ * Derive MCP tool name from platform action id.
+ *
+ * @example
+ * actionIdToToolName('@ossy/resources/actions/list') // 'ossy_resources_list'
+ *
+ * @param {string} actionId
+ * @returns {string}
+ */
+export function actionIdToToolName (actionId) {
+  const parts = actionId.split('/')
+  if (parts.length >= 4 && parts[0].startsWith('@') && parts[2] === 'actions') {
+    const provider = parts[0].slice(1)
+    return `${provider}_${parts[1]}_${parts[3]}`.replace(/-/g, '_')
+  }
+  return `ossy_${actionId.replace(/^@/, '').replace(/\//g, '_').replace(/-/g, '_')}`
+}
+
+/**
+ * @param {string} actionId
+ * @returns {string}
+ */
+export function humanizeActionId (actionId) {
+  const intent = actionId.split('/').pop() || actionId
+  return intent
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ')
+}