Add requiresObject/requiresService capability gates for UI elements

Author: hotlong

content/docs/references/ui/dashboard.mdx

@@ -88,6 +88,8 @@ Dashboard header action
 | **type** | `Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'grouped-bar' \| 'stacked-bar' \| 'bi-polar-bar' \| 'line' \| 'area' \| 'stacked-area' \| 'step-line' \| 'spline' \| 'pie' \| 'donut' \| 'funnel' \| 'pyramid' \| 'scatter' \| 'bubble' \| 'treemap' \| 'sunburst' \| 'sankey' \| 'word-cloud' \| 'gauge' \| 'solid-gauge' \| 'metric' \| 'kpi' \| 'bullet' \| 'choropleth' \| 'bubble-map' \| 'gl-map' \| 'heatmap' \| 'radar' \| 'waterfall' \| 'box-plot' \| 'violin' \| 'candlestick' \| 'stock' \| 'table' \| 'pivot'>` | ✅ | Visualization type |
 | **chartConfig** | `Object` | optional | Chart visualization configuration |
 | **colorVariant** | `Enum<'default' \| 'blue' \| 'teal' \| 'orange' \| 'purple' \| 'success' \| 'warning' \| 'danger'>` | optional | Widget color variant for theming |
+| **requiresObject** | `string` | optional | Hide the widget unless the named object is registered |
+| **requiresService** | `string` | optional | Hide the widget unless the named kernel service is registered |
 | **actionUrl** | `string` | optional | URL or target for the widget action button |
 | **actionType** | `Enum<'script' \| 'url' \| 'modal' \| 'flow' \| 'api'>` | optional | Type of action for the widget action button |
 | **actionIcon** | `string` | optional | Icon identifier for the widget action button |

packages/objectql/src/protocol.ts

@@ -500,9 +500,16 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         }
 
         // 2. In-memory SchemaRegistry (artifact-loaded out-of-box values).
-        //    Project kernels skip the process-wide registry to avoid cross-
-        //    project leakage; their artifact source is MetadataService below.
-        if (item === undefined && this.projectId === undefined) {
+        //    Both control-plane (unscoped) and project kernels consult the
+        //    registry. The previous guard that skipped the registry for
+        //    project kernels was meant to prevent cross-project leakage at
+        //    the LIST level — but for a single-item lookup the kernel's own
+        //    `engine.registry` is project-local (each ObjectQL instance has
+        //    its own SchemaRegistry), so reading from it is safe and
+        //    necessary. Without this, project-kernel callers of
+        //    `GET /api/v1/meta/object/<name>` 404 even though the object is
+        //    registered and visible via the list endpoint.
+        if (item === undefined) {
             item = this.engine.registry.getItem(request.type, request.name);
             if (item === undefined) {
                 const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];

packages/platform-objects/src/apps/dashboards/system_overview.dashboard.ts

@@ -81,6 +81,9 @@ export const SystemOverviewDashboard = Dashboard.create({
       title: 'Packages Installed',
       type: 'metric',
       object: 'sys_package_installation',
+      // Cloud-only object — only registered when service-tenant is loaded.
+      // Hide this widget gracefully in single-project runtimes.
+      requiresObject: 'sys_package_installation',
       layout: {
         x: 9,
         y: 0,

packages/platform-objects/src/apps/setup.app.ts

@@ -71,9 +71,15 @@ export const SETUP_APP: App = {
       label: 'Platform',
       icon: 'layers',
       children: [
-        { id: 'nav_apps', type: 'object', label: 'Apps', objectName: 'sys_app', icon: 'layout-grid' },
-        { id: 'nav_packages', type: 'object', label: 'Packages', objectName: 'sys_package', icon: 'package' },
-        { id: 'nav_package_installations', type: 'object', label: 'Installations', objectName: 'sys_package_installation', icon: 'package-check' },
+        // `sys_app` / `sys_package` / `sys_package_installation` are
+        // contributed by `@objectstack/service-tenant` (control-plane scope).
+        // Single-project runtimes do not register them — the `requiresObject`
+        // capability flag tells the frontend to hide these entries when the
+        // backing object is not in the SchemaRegistry, avoiding the
+        // 404-when-clicked trap.
+        { id: 'nav_apps', type: 'object', label: 'Apps', objectName: 'sys_app', icon: 'layout-grid', requiresObject: 'sys_app' },
+        { id: 'nav_packages', type: 'object', label: 'Packages', objectName: 'sys_package', icon: 'package', requiresObject: 'sys_package' },
+        { id: 'nav_package_installations', type: 'object', label: 'Installations', objectName: 'sys_package_installation', icon: 'package-check', requiresObject: 'sys_package_installation' },
         { id: 'nav_metadata', type: 'object', label: 'All Metadata', objectName: 'sys_metadata', icon: 'file-cog' },
       ],
     },

packages/spec/src/ui/app.zod.ts

@@ -48,6 +48,31 @@ const BaseNavItemSchema = z.object({
 
   /** Permissions required to see/access this navigation item */
   requiredPermissions: z.array(z.string()).optional().describe('Permissions required to access this item'),
+
+  /**
+   * Capability gate — registered object name.
+   *
+   * When set, the frontend MUST hide (or render disabled) this navigation
+   * entry if the named object is not registered in the runtime's
+   * SchemaRegistry. Useful for cloud-only objects (e.g. `sys_app`,
+   * `sys_package`, `sys_package_installation`) that don't exist in
+   * single-project runtimes — declaring the dependency here avoids
+   * 404-when-clicked traps without hard-coding environment checks in the
+   * UI.
+   *
+   * Independent of `visible` (CEL) and `requiredPermissions` (RBAC) —
+   * this gates on runtime *capability*, not user authorization.
+   */
+  requiresObject: z.string().optional().describe('Hide/disable this entry unless the named object is registered in the runtime'),
+
+  /**
+   * Capability gate — registered service name.
+   *
+   * Same idea as `requiresObject` but keyed on a kernel service
+   * (e.g. `'ai'`, `'tenant'`, `'realtime'`). Hide the entry when the
+   * service isn't installed.
+   */
+  requiresService: z.string().optional().describe('Hide/disable this entry unless the named kernel service is registered'),
 });
 
 /**

packages/spec/src/ui/dashboard.zod.ts

@@ -107,6 +107,27 @@ export const DashboardWidgetSchema = lazySchema(() => z.object({
   /** Color variant for the widget (e.g., KPI card accent color) */
   colorVariant: WidgetColorVariantSchema.optional().describe('Widget color variant for theming'),
 
+  /**
+   * Runtime capability gate — widget is hidden when the named object is
+   * not registered in the runtime's SchemaRegistry. Mirrors
+   * `NavigationItem.requiresObject` so cloud-only widgets (e.g. those
+   * keyed on `sys_app` / `sys_package_installation`) silently disappear
+   * in single-project runtimes instead of rendering a 404 error.
+   *
+   * Defaults to the widget's `object` field when not explicitly set —
+   * any widget that targets an object will be gated on that object's
+   * registration. Set this to a different value (or empty string to
+   * disable) when the widget should appear even if its `object` is
+   * unavailable.
+   */
+  requiresObject: z.string().optional().describe('Hide the widget unless the named object is registered'),
+
+  /**
+   * Runtime capability gate — widget is hidden when the named kernel
+   * service is not registered. Mirrors `NavigationItem.requiresService`.
+   */
+  requiresService: z.string().optional().describe('Hide the widget unless the named kernel service is registered'),
+
   /** Action URL for the widget header action button */
   actionUrl: z.string().optional().describe('URL or target for the widget action button'),