@conduction/nextcloud-vue 1.0.0-beta.21 → 1.0.0-beta.22

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@conduction/nextcloud-vue",
-	"version": "1.0.0-beta.21",
+	"version": "1.0.0-beta.22",
 	"description": "Shared Vue component library for Conduction Nextcloud apps — complements @nextcloud/vue with higher-level components, OpenRegister integration, and NL Design System support",
 	"license": "EUPL-1.2",
 	"author": "Conduction B.V. <info@conduction.nl>",

package/src/composables/useAppManifest.js

@@ -2,19 +2,26 @@ import { ref } from 'vue'
 import axios from '@nextcloud/axios'
 import { generateUrl } from '@nextcloud/router'
 import { validateManifest } from '../utils/validateManifest.js'
+import { resolveManifestSentinels } from '../utils/resolveManifestSentinels.js'
 
 /**
- * Composable that loads and validates a Conduction app manifest.
+ * Composable that loads, resolves, and validates a Conduction app manifest.
  *
- * The composable implements the three-phase flow specified in
- * REQ-JMR-002 of the json-manifest-renderer capability:
+ * The composable implements the four-phase flow specified in
+ * REQ-JMR-002 of the json-manifest-renderer capability + the
+ * substitution step from the `manifest-resolve-sentinel` capability:
  *
  *  1. Synchronous bundled load — `bundledManifest` is the immediate value.
  *  2. Async backend merge — fetches `/index.php/apps/{appId}/api/manifest`
  *     and deep-merges any 200 response over the bundled manifest. 4xx /
  *     5xx / network errors are silently ignored so apps work without a
  *     backend endpoint.
- *  3. Validation — the merged result is validated against
+ *  3. Sentinel resolution — `@resolve:<key>` strings under
+ *     `pages[].config` are substituted with `IAppConfig` values via the
+ *     `resolveManifestSentinels` utility (see its module docs for the
+ *     resolution source chain). Unresolved keys surface on the
+ *     returned `unresolvedSentinels` ref.
+ *  4. Validation — the resolved result is validated against
  *     `app-manifest.schema.json`. On failure, the bundled manifest is
  *     kept and a `console.warn` is emitted with the error list.
  *
@@ -22,7 +29,8 @@ import { validateManifest } from '../utils/validateManifest.js'
  * can hot-swap the manifest without a page reload.
  *
  * @param {string} appId Nextcloud app ID. Used to build the default
- *   backend endpoint URL via `@nextcloud/router`.
+ *   backend endpoint URL via `@nextcloud/router` and to scope
+ *   IAppConfig lookups for `@resolve:<key>` sentinels.
  * @param {object} bundledManifest The manifest shipped with the app (the
  *   default value, available synchronously).
  * @param {object} [options] Configuration options.
@@ -32,7 +40,10 @@ import { validateManifest } from '../utils/validateManifest.js'
  *   return a promise resolving to `{ status: number, data: object }`.
  *   Defaults to `axios.get` from `@nextcloud/axios` (which inherits the
  *   Nextcloud CSRF token automatically).
- * @return {{ manifest: import('vue').Ref<object>, isLoading: import('vue').Ref<boolean>, validationErrors: import('vue').Ref<string[]|null> }}
+ * @param {Function} [options.getAppConfigValue] Override the
+ *   IAppConfig resolver consumed by `resolveManifestSentinels`. Useful
+ *   for tests that want to mount a fixture-driven config map.
+ * @return {{ manifest: import('vue').Ref<object>, isLoading: import('vue').Ref<boolean>, validationErrors: import('vue').Ref<string[]|null>, unresolvedSentinels: import('vue').Ref<string[]> }}
  *
  * @example Basic usage (Composition API)
  * const { manifest, isLoading } = useAppManifest('decidesk', bundled)
@@ -49,11 +60,17 @@ import { validateManifest } from '../utils/validateManifest.js'
  *   endpoint: '/custom/manifest/url',
  *   fetcher: (url) => Promise.resolve({ status: 200, data: { ... } }),
  * })
+ *
+ * @example With sentinel resolution + admin warning surface
+ * const { manifest, unresolvedSentinels } = useAppManifest('softwarecatalog', bundled)
+ * // unresolvedSentinels.value is e.g. ['voorzieningen_register']
+ * // when that IAppConfig key is unset on the tenant.
  */
 export function useAppManifest(appId, bundledManifest, options = {}) {
 	const manifest = ref(bundledManifest)
 	const isLoading = ref(true)
 	const validationErrors = ref(null)
+	const unresolvedSentinels = ref([])
 
 	const endpoint = options.endpoint ?? generateUrl(`/apps/${appId}/api/manifest`)
 	const fetcher = options.fetcher ?? ((url) => axios.get(url))
@@ -65,7 +82,18 @@ export function useAppManifest(appId, bundledManifest, options = {}) {
 				return
 			}
 			const merged = deepMerge(bundledManifest, response.data)
-			const result = validateManifest(merged)
+
+			// Sentinel resolution runs BEFORE validation per
+			// REQ-MRS-002: the validator MUST NEVER observe an
+			// unresolved sentinel at runtime. Resolution failures
+			// (unset IAppConfig keys) substitute null and accumulate
+			// on `unresolvedSentinels`; they do NOT block validation.
+			const { manifest: resolved, unresolved } = await resolveManifestSentinels(merged, appId, {
+				getAppConfigValue: options.getAppConfigValue,
+			})
+			unresolvedSentinels.value = unresolved
+
+			const result = validateManifest(resolved)
 			if (!result.valid) {
 				validationErrors.value = result.errors
 				// eslint-disable-next-line no-console
@@ -75,7 +103,7 @@ export function useAppManifest(appId, bundledManifest, options = {}) {
 				)
 				return
 			}
-			manifest.value = merged
+			manifest.value = resolved
 		} catch (err) {
 			// Silent fallback on 404, network errors, non-200 responses.
 			// Apps without a backend endpoint should keep working.
@@ -84,7 +112,7 @@ export function useAppManifest(appId, bundledManifest, options = {}) {
 		}
 	})()
 
-	return { manifest, isLoading, validationErrors }
+	return { manifest, isLoading, validationErrors, unresolvedSentinels }
 }
 
 /**

package/src/index.js

@@ -119,4 +119,5 @@ export { registerTranslations } from './l10n/index.js'
 export { buildHeaders, buildQueryString, parseResponseError, networkError, genericError } from './utils/index.js'
 export { columnsFromSchema, formatValue, filtersFromSchema, fieldsFromSchema, validateValue } from './utils/index.js'
 export { validateManifest } from './utils/validateManifest.js'
+export { resolveManifestSentinels, clearResolveCache } from './utils/resolveManifestSentinels.js'
 export { filterWidgetsByVisibility, isWidgetVisible, getCurrentUserId, getCurrentUserGroups, resetVisibilityCache } from './utils/index.js'

package/src/utils/resolveManifestSentinels.js

@@ -0,0 +1,268 @@
+/**
+ * Manifest `@resolve:` sentinel resolver.
+ *
+ * Implements the `manifest-resolve-sentinel` capability: walks the
+ * `pages[].config` subtrees of an assembled manifest and replaces every
+ * fully-matched `@resolve:<key>` string with the result of the consuming
+ * app's `IAppConfig` lookup for `<key>`. Other manifest paths
+ * (`route`, `id`, top-level fields, `menu[]`, `pages[].component` etc.)
+ * are intentionally untouched — sentinels there are router / registry
+ * invariants and the schema validator rejects them.
+ *
+ * Resolution source (canonical, per spec):
+ *
+ *  1. `@nextcloud/initial-state` provisioned key
+ *     `app-{appId}-{key}` — zero-network, preferred.
+ *  2. Runtime `GET /index.php/apps/{appId}/api/configs/{key}` — falls
+ *     through silently on 4xx / network error.
+ *  3. `null` — unresolved.
+ *
+ * Empty-state semantics: an unset / empty value substitutes `null` (not
+ * empty string) and is accumulated into the returned `unresolved` array
+ * so consumers can render an admin warning. A `console.warn` is emitted
+ * once per unresolved key with the offending sentinel.
+ *
+ * The resolver is intentionally split into a synchronous walk + an
+ * asynchronous batch resolution: every sentinel is collected first, then
+ * each unique `(appId, key)` is resolved exactly once (initial-state
+ * lookup is synchronous; runtime fetch is per-key cached for the page
+ * lifetime), and finally the manifest is rewritten in a second walk
+ * with the resolved values. This makes the substitution deterministic
+ * — five `@resolve:foo` references in five pages share one fetch.
+ *
+ * @module utils/resolveManifestSentinels
+ */
+
+const SENTINEL_PATTERN = /^@resolve:([a-z][a-z0-9_-]*)$/
+
+/**
+ * Process-wide cache of resolved IAppConfig values, keyed by
+ * `${appId}::${key}`. Cleared via `clearResolveCache()` (test-only).
+ *
+ * @type {Map<string, Promise<*>>}
+ */
+const resolveCache = new Map()
+
+/**
+ * Test-only helper to reset the per-page resolve cache between runs.
+ * Production callers do not need this — the cache is page-lifetime by
+ * design, consistent with the manifest's load-once model.
+ *
+ * @return {void}
+ */
+export function clearResolveCache() {
+	resolveCache.clear()
+}
+
+/**
+ * Walk the manifest's `pages[].config` subtrees and replace every
+ * `@resolve:<key>` sentinel with the resolved IAppConfig value.
+ *
+ * Returns a Promise resolving to `{ manifest, unresolved }`:
+ *  - `manifest` — a NEW manifest object with sentinels substituted; the
+ *    input is NOT mutated.
+ *  - `unresolved` — array of IAppConfig keys whose sentinels resolved
+ *    to `null` (unset / empty / fetch failure). Useful for surfacing
+ *    "n settings unconfigured" admin warnings.
+ *
+ * Sentinels OUTSIDE `pages[].config` are left intact; the schema
+ * validator rejects them downstream so consumers see a clear error
+ * rather than a silent substitution that breaks routing or registry
+ * lookups.
+ *
+ * @param {object} manifest The merged (bundled + backend) manifest.
+ *   Walked but not mutated.
+ * @param {string} appId Nextcloud app ID. Used to scope the
+ *   IAppConfig lookup namespace.
+ * @param {object} [options] Resolver overrides.
+ * @param {Function} [options.getAppConfigValue] Async (appId, key) =>
+ *   value resolver. Override for tests; defaults to the
+ *   initial-state-then-fetch chain documented above.
+ * @param {Function} [options.warn] Override for `console.warn`. Used in
+ *   tests to capture warning calls without polluting test output.
+ * @return {Promise<{ manifest: object, unresolved: string[] }>}
+ */
+export async function resolveManifestSentinels(manifest, appId, options = {}) {
+	if (!isPlainObject(manifest)) {
+		return { manifest, unresolved: [] }
+	}
+
+	const getAppConfigValue = options.getAppConfigValue ?? defaultGetAppConfigValue
+	const warn = options.warn ?? ((...args) => {
+		// eslint-disable-next-line no-console
+		console.warn(...args)
+	})
+
+	// Phase 1: scan for sentinels under pages[].config only. We only
+	// need the unique key set — the second walk does the substitution.
+	const keys = new Set()
+	const pages = Array.isArray(manifest.pages) ? manifest.pages : []
+	for (const page of pages) {
+		if (!isPlainObject(page) || !isPlainObject(page.config)) continue
+		collectSentinelKeys(page.config, keys)
+	}
+
+	if (keys.size === 0) {
+		return { manifest, unresolved: [] }
+	}
+
+	// Phase 2: resolve each unique (appId, key) exactly once.
+	const resolved = new Map()
+	const unresolved = []
+	await Promise.all(Array.from(keys).map(async (key) => {
+		const value = await getAppConfigValue(appId, key)
+		if (value === undefined || value === null || value === '') {
+			resolved.set(key, null)
+			unresolved.push(key)
+			warn(`[resolveManifestSentinels] Manifest sentinel '@resolve:${key}' resolved to null (key unset)`)
+		} else {
+			resolved.set(key, value)
+		}
+	}))
+
+	// Phase 3: rebuild the manifest immutably, substituting sentinels in
+	// pages[].config only. Other fields are passed through by reference.
+	const out = { ...manifest }
+	out.pages = pages.map((page) => {
+		if (!isPlainObject(page) || !isPlainObject(page.config)) return page
+		return { ...page, config: substituteInTree(page.config, resolved) }
+	})
+
+	return { manifest: out, unresolved }
+}
+
+/**
+ * Recursively scan a tree, accumulating every sentinel key into the
+ * provided `keys` Set. Plain objects + arrays are descended; primitive
+ * leaves are checked against the sentinel pattern.
+ *
+ * @param {*} node Current tree node (object, array, or primitive).
+ * @param {Set<string>} keys Accumulator for unique sentinel keys.
+ * @return {void}
+ */
+function collectSentinelKeys(node, keys) {
+	if (typeof node === 'string') {
+		const match = node.match(SENTINEL_PATTERN)
+		if (match) keys.add(match[1])
+		return
+	}
+	if (Array.isArray(node)) {
+		for (const item of node) collectSentinelKeys(item, keys)
+		return
+	}
+	if (isPlainObject(node)) {
+		for (const value of Object.values(node)) collectSentinelKeys(value, keys)
+	}
+}
+
+/**
+ * Recursively rebuild a tree, replacing each fully-matched sentinel
+ * with its resolved value. Returns a NEW tree; input is unchanged.
+ *
+ * @param {*} node Current tree node.
+ * @param {Map<string,*>} resolved Map of key → resolved value (or null).
+ * @return {*} New tree with sentinels substituted.
+ */
+function substituteInTree(node, resolved) {
+	if (typeof node === 'string') {
+		const match = node.match(SENTINEL_PATTERN)
+		if (match && resolved.has(match[1])) {
+			return resolved.get(match[1])
+		}
+		return node
+	}
+	if (Array.isArray(node)) {
+		return node.map((item) => substituteInTree(item, resolved))
+	}
+	if (isPlainObject(node)) {
+		const out = {}
+		for (const [key, value] of Object.entries(node)) {
+			out[key] = substituteInTree(value, resolved)
+		}
+		return out
+	}
+	return node
+}
+
+/**
+ * Default `getAppConfigValue` implementation: consult
+ * `@nextcloud/initial-state` first (zero-network), fall back to a
+ * runtime fetch with per-(appId, key) caching for the page lifetime.
+ *
+ * Returns `null` when neither source resolves a value. Network / 4xx
+ * errors are swallowed silently — the resolver downgrades to "key
+ * unset" in that case (consistent with the silent-fallback pattern in
+ * `useAppManifest`'s backend-merge step).
+ *
+ * @param {string} appId Nextcloud app ID.
+ * @param {string} key IAppConfig key (already validated as
+ *   lowercase + alphanumeric + `_-` by the sentinel regex).
+ * @return {Promise<*>} Resolved value or `null` when unset.
+ */
+async function defaultGetAppConfigValue(appId, key) {
+	const cacheKey = `${appId}::${key}`
+	if (resolveCache.has(cacheKey)) {
+		return resolveCache.get(cacheKey)
+	}
+	const promise = (async () => {
+		// Step 1: initial-state — synchronous, zero-network.
+		const initial = readInitialState(appId, key)
+		if (initial !== undefined && initial !== null && initial !== '') {
+			return initial
+		}
+		// Step 2: runtime fetch — silent fallback on any error.
+		try {
+			const { default: axios } = await import('@nextcloud/axios')
+			const { generateUrl } = await import('@nextcloud/router')
+			const url = generateUrl(`/apps/${appId}/api/configs/${key}`)
+			const response = await axios.get(url)
+			if (response && response.status === 200 && response.data !== undefined) {
+				const data = response.data
+				// API may return either a raw scalar or `{ value: ... }`.
+				if (isPlainObject(data) && 'value' in data) return data.value
+				return data
+			}
+		} catch (e) {
+			// Silent — caller treats as "unset".
+		}
+		return null
+	})()
+	resolveCache.set(cacheKey, promise)
+	return promise
+}
+
+/**
+ * Read a key from `@nextcloud/initial-state`. Looks up the conventional
+ * `app-{appId}-{key}` slot. Returns `undefined` when the package is not
+ * installed (e.g. older host) or the key is not provisioned.
+ *
+ * @param {string} appId Nextcloud app ID.
+ * @param {string} key IAppConfig key.
+ * @return {*} Provisioned value or `undefined`.
+ */
+function readInitialState(appId, key) {
+	try {
+		// `@nextcloud/initial-state` is an optional peer; the host page
+		// may not provision the slot at all. We resolve via require so
+		// jest mocks the import; bundle-side, the package is treeshaken
+		// when no caller pulls it in.
+		// eslint-disable-next-line global-require, import/no-unresolved, n/no-extraneous-require
+		const mod = require('@nextcloud/initial-state')
+		if (typeof mod.loadState === 'function') {
+			return mod.loadState(appId, key, undefined)
+		}
+	} catch (e) {
+		// Package not installed or no slot provisioned — fall through.
+	}
+	return undefined
+}
+
+/**
+ * Type guard — true when value is a plain (non-array, non-null) object.
+ *
+ * @param {*} value Candidate.
+ * @return {boolean} True when value is a plain object.
+ */
+function isPlainObject(value) {
+	return value !== null && typeof value === 'object' && !Array.isArray(value)
+}

package/src/utils/validateManifest.js

@@ -1,3 +1,26 @@
+/**
+ * Pattern matching the `manifest-resolve-sentinel` capability's
+ * sentinel — `@resolve:<key>` where `<key>` is lowercase alphanumeric
+ * with `_` / `-` separators. The full string IS the sentinel; partial
+ * substitution like `prefix-@resolve:foo` is NOT supported and is left
+ * as a plain string for downstream renderers.
+ *
+ * Build-time validation accepts this pattern as a valid `string` for
+ * any `string`-typed field UNDER `pages[].config`, regardless of any
+ * narrower per-field constraint. Other paths reject it explicitly.
+ */
+const SENTINEL_PATTERN = /^@resolve:[a-z][a-z0-9_-]*$/
+
+/**
+ * Test whether a string is a manifest `@resolve:` sentinel.
+ *
+ * @param {*} value Candidate value.
+ * @return {boolean} True when the value is a fully-matched sentinel.
+ */
+function isSentinel(value) {
+	return typeof value === 'string' && SENTINEL_PATTERN.test(value)
+}
+
 /**
  * Validate a manifest object against the manifest JSON Schema.
  *
@@ -15,6 +38,13 @@
  *  - `pages[].component` is required when `type` is "custom".
  *  - Per-type `config` shape rules for the built-in types `logs`,
  *    `settings`, `chat`, `files` (REQ from manifest-page-type-extensions).
+ *  - The `manifest-resolve-sentinel` sentinel `@resolve:<key>` is
+ *    permissively accepted under `pages[].config.*` and explicitly
+ *    REJECTED in `version`, `dependencies[]`, `menu[].route`,
+ *    `menu[].id`, `pages[].id`, `pages[].route`, `pages[].component`,
+ *    `pages[].headerComponent`, `pages[].actionsComponent`,
+ *    `pages[].slots.*` — those are router invariants or registry
+ *    keys.
  *
  * The richer schema constraints (`additionalProperties: false`, `format`
  * URI, etc.) are enforced by the BE / hydra CI validators that consume
@@ -42,6 +72,10 @@ export function validateManifest(manifest, options = {}) {
 
 	if (typeof manifest.version !== 'string') {
 		errors.push('/version must be a string')
+	} else if (isSentinel(manifest.version)) {
+		// `manifest-resolve-sentinel` REQ-MRS-004: sentinel is a router /
+		// registry invariant violation when used here.
+		errors.push(`/version "${manifest.version}" must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
 	} else if (!versionPattern.test(manifest.version)) {
 		errors.push(`/version "${manifest.version}" must match semver pattern`)
 	}
@@ -54,8 +88,15 @@ export function validateManifest(manifest, options = {}) {
 				errors.push(`/menu/${index} must be an object`)
 				return
 			}
-			if (typeof item.id !== 'string') errors.push(`/menu/${index}/id must be a string`)
+			if (typeof item.id !== 'string') {
+				errors.push(`/menu/${index}/id must be a string`)
+			} else if (isSentinel(item.id)) {
+				errors.push(`/menu/${index}/id must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
+			}
 			if (typeof item.label !== 'string') errors.push(`/menu/${index}/label must be a string`)
+			if (item.route !== undefined && isSentinel(item.route)) {
+				errors.push(`/menu/${index}/route must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
+			}
 			if (item.children !== undefined && !Array.isArray(item.children)) {
 				errors.push(`/menu/${index}/children must be an array`)
 			}
@@ -77,12 +118,18 @@ export function validateManifest(manifest, options = {}) {
 			}
 			if (typeof page.id !== 'string') {
 				errors.push(`/pages/${index}/id must be a string`)
+			} else if (isSentinel(page.id)) {
+				errors.push(`/pages/${index}/id must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
 			} else if (seenIds.has(page.id)) {
 				errors.push(`/pages/${index}/id "${page.id}" must be unique within pages[]`)
 			} else {
 				seenIds.add(page.id)
 			}
-			if (typeof page.route !== 'string') errors.push(`/pages/${index}/route must be a string`)
+			if (typeof page.route !== 'string') {
+				errors.push(`/pages/${index}/route must be a string`)
+			} else if (isSentinel(page.route)) {
+				errors.push(`/pages/${index}/route must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
+			}
 			if (typeof page.title !== 'string') errors.push(`/pages/${index}/title must be a string`)
 			if (typeof page.type !== 'string' || page.type.length === 0) {
 				errors.push(`/pages/${index}/type must be a non-empty string`)
@@ -92,6 +139,25 @@ export function validateManifest(manifest, options = {}) {
 			if (page.type === 'custom' && typeof page.component !== 'string') {
 				errors.push(`/pages/${index}/component is required when type is "custom"`)
 			}
+			// `manifest-resolve-sentinel` REQ-MRS-004: registry-key
+			// fields cannot be dynamic — they resolve at module-load
+			// time against `customComponents`, before the loader runs.
+			if (page.component !== undefined && isSentinel(page.component)) {
+				errors.push(`/pages/${index}/component must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
+			}
+			if (page.headerComponent !== undefined && isSentinel(page.headerComponent)) {
+				errors.push(`/pages/${index}/headerComponent must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
+			}
+			if (page.actionsComponent !== undefined && isSentinel(page.actionsComponent)) {
+				errors.push(`/pages/${index}/actionsComponent must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
+			}
+			if (isPlainObject(page.slots)) {
+				for (const [slotName, slotValue] of Object.entries(page.slots)) {
+					if (isSentinel(slotValue)) {
+						errors.push(`/pages/${index}/slots/${slotName} must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
+					}
+				}
+			}
 
 			// Per-type config-shape validation for built-in extended types.
 			// (`manifest-page-type-extensions` spec — covers logs/settings/chat/files.)
@@ -115,6 +181,8 @@ export function validateManifest(manifest, options = {}) {
 			manifest.dependencies.forEach((dep, index) => {
 				if (typeof dep !== 'string') {
 					errors.push(`/dependencies/${index} must be a string`)
+				} else if (isSentinel(dep)) {
+					errors.push(`/dependencies/${index} must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
 				}
 			})
 		}