feat(console): resolve post-login landing from app metadata, not a hardcode (#2027)

Replace CloudAwareRootRedirect's hardcoded PREFERRED_APPS=['cloud_control'] with
RootLandingRedirect, resolving the landing from app metadata: the isDefault app
(its homePageId picks the page) → else the single visible app → else /home. This
gives isDefault routing semantics (was a display-only badge) and removes the
cloud-specific bake-in, so any product declares its landing in source rather than
forking the Console. Pure resolveLandingPath() extracted + unit-tested (7 cases).

Back-compat: no isDefault app + ≥2 visible apps still lands on /home; cloud is
unaffected (cloud_control already isDefault). The landing is a build-time product
decision in metadata, not a runtime Settings-UI preference.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

.changeset/metadata-driven-landing.md

@@ -0,0 +1,26 @@
+---
+'@object-ui/console': minor
+---
+
+feat(console): resolve the post-login landing from app metadata, not a hardcode
+
+The root route (`/`) previously redirected via a hardcoded
+`PREFERRED_APPS = ['cloud_control']` in `CloudAwareRootRedirect` — baking one
+product's policy (cloud) into the shared Console, with no supported way for a
+deployment to opt out of the `/home` launcher or land somewhere custom without
+forking the SPA.
+
+`CloudAwareRootRedirect` is replaced by `RootLandingRedirect`, which resolves the
+landing purely from app metadata (`resolveLandingPath`, unit-tested):
+
+1. the app marked `isDefault: true` → `/apps/<it>` (its own `homePageId` then
+   selects the landing page within it);
+2. else the single visible app (`active !== false && hidden !== true`) → that app;
+3. else `/home` — the multi-app workspace launcher (legacy default).
+
+This gives `isDefault` **routing semantics** (it was a display-only badge) — a
+back-compat-relevant contract change. Back-compat: a deployment with no
+`isDefault` app and ≥2 visible apps still lands on `/home`, exactly as before;
+cloud is unaffected (`cloud_control` is already `isDefault: true`) and the
+cloud-specific hardcode is removed. The landing is now a build-time product
+decision a developer declares in metadata, not a runtime Settings-UI preference.

apps/console/src/App.tsx

@@ -39,7 +39,7 @@ import {
 } from '@object-ui/app-shell';
 
 import { AppContent } from './AppContent';
-import { CloudAwareRootRedirect } from './components/CloudAwareRootRedirect';
+import { RootLandingRedirect } from './components/RootLandingRedirect';
 import { FormPage } from './components/FormPage';
 import { MetadataHmrReloader } from './components/MetadataHmrReloader';
 import SharedRecordPage from './pages/SharedRecordPage';
@@ -292,7 +292,7 @@ export function App() {
                 <AppContent />
               </ProtectedRoute>
             } />
-            <Route path="/" element={<ConnectedShell><CloudAwareRootRedirect /></ConnectedShell>} />
+            <Route path="/" element={<ConnectedShell><RootLandingRedirect /></ConnectedShell>} />
             <Route path="*" element={<Navigate to="/" replace />} />
           </Routes>
         </ConsoleShell>

apps/console/src/components/CloudAwareRootRedirect.tsx

@@ -0,0 +1,50 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { resolveLandingPath } from './RootLandingRedirect';
+
+describe('resolveLandingPath', () => {
+  it('routes to the App marked isDefault (isDefault now ROUTES, not just badges)', () => {
+    expect(
+      resolveLandingPath([
+        { name: 'crm' },
+        { name: 'cloud_control', isDefault: true },
+        { name: 'setup' },
+      ]),
+    ).toBe('/apps/cloud_control');
+  });
+
+  it('prefers isDefault over the single-visible-app rule', () => {
+    expect(
+      resolveLandingPath([{ name: 'a', isDefault: true }, { name: 'b' }, { name: 'c' }]),
+    ).toBe('/apps/a');
+  });
+
+  it('lands directly in the single visible App when none is isDefault', () => {
+    expect(resolveLandingPath([{ name: 'only_app' }])).toBe('/apps/only_app');
+  });
+
+  it('ignores hidden/inactive Apps when counting "single visible"', () => {
+    expect(
+      resolveLandingPath([
+        { name: 'main' },
+        { name: 'secret', hidden: true },
+        { name: 'off', active: false },
+      ]),
+    ).toBe('/apps/main');
+  });
+
+  it('falls back to /home for a multi-app deployment with no isDefault (legacy behavior)', () => {
+    expect(resolveLandingPath([{ name: 'a' }, { name: 'b' }])).toBe('/home');
+  });
+
+  it('falls back to /home when there are no apps', () => {
+    expect(resolveLandingPath([])).toBe('/home');
+    expect(resolveLandingPath(null)).toBe('/home');
+    expect(resolveLandingPath(undefined)).toBe('/home');
+  });
+
+  it('ignores entries without a name', () => {
+    expect(resolveLandingPath([{ isDefault: true }, { name: 'real' }])).toBe('/apps/real');
+  });
+});

apps/console/src/components/RootLandingRedirect.test.ts

@@ -0,0 +1,62 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * RootLandingRedirect — element for `<Route path="/" />`.
+ *
+ * Resolves the post-login landing from APP METADATA, so any product built on
+ * the framework (cloud's control plane, an ISV's product, a per-project
+ * runtime) declares its landing in source rather than forking the Console. This
+ * replaces the previous hardcoded `PREFERRED_APPS = ['cloud_control']` redirect,
+ * which baked one product's policy into the shared bundle.
+ *
+ * The landing is a build/dev-time PRODUCT decision, declared in metadata — not a
+ * runtime, per-tenant, Settings-UI preference. Resolution order (see
+ * {@link resolveLandingPath}):
+ *   1. the App marked `isDefault: true` → `/apps/<it>` — and that App's own
+ *      `homePageId` then selects the landing page within it;
+ *   2. else the single visible App (`active !== false && hidden !== true`)
+ *      → `/apps/<it>` (a one-app deployment shouldn't show a one-tile launcher);
+ *   3. else `/home` — the multi-app workspace launcher (the legacy default).
+ *
+ * NOTE: this gives `isDefault` ROUTING semantics; it was previously a
+ * display-only badge. Back-compat: a deployment with no `isDefault` App and ≥2
+ * visible Apps still lands on `/home`, exactly as before. (A deploy-time ops
+ * override is intentionally kept server-side, not read here — the metadata
+ * declaration is the source of truth.)
+ */
+
+import { Navigate } from 'react-router-dom';
+import { useMetadata, LoadingFallback } from '@object-ui/app-shell';
+
+/** Minimal shape this resolver needs off each App metadata record. */
+interface LandingApp {
+  name?: string;
+  isDefault?: boolean;
+  active?: boolean;
+  hidden?: boolean;
+}
+
+/**
+ * The path `/` should redirect to, resolved purely from the App list. Extracted
+ * from the component so the policy is unit-testable without a router/render.
+ */
+export function resolveLandingPath(apps: readonly LandingApp[] | null | undefined): string {
+  const list = (apps ?? []).filter((a): a is LandingApp & { name: string } => Boolean(a?.name));
+
+  // 1. The App the product declared as default (isDefault now ROUTES, not just badges).
+  const defaultApp = list.find((a) => a.isDefault === true);
+  if (defaultApp) return `/apps/${defaultApp.name}`;
+
+  // 2. A single-app deployment lands straight in that App (no one-tile launcher).
+  const visible = list.filter((a) => a.active !== false && a.hidden !== true);
+  if (visible.length === 1) return `/apps/${visible[0].name}`;
+
+  // 3. Multi-app default: the workspace launcher.
+  return '/home';
+}
+
+export function RootLandingRedirect() {
+  const { apps, loading } = useMetadata();
+  if (loading) return <LoadingFallback />;
+  return <Navigate to={resolveLandingPath(apps as LandingApp[] | undefined)} replace />;
+}