feat(app-shell): first-run zero-org users land straight on the create-workspace form (#2165)

A brand-new user with no organizations was routed to the org picker
(/organizations), whose empty "No organizations yet" state is pure friction —
there is nothing to pick (one extra hop). Auto-open the existing
CreateWorkspaceDialog when the org list is empty so they land directly on the
"name your workspace" form. Users who already have orgs still see the picker;
the `?create=1` entry is unchanged; the empty-state (with its own "New
organization" button) remains the backdrop if the dialog is dismissed.

The dialog already creates the org from the user's chosen name and eagerly
provisions its production environment (born-with-env), so this completes the
workspace-first onboarding: name your workspace -> org + Production env. It
belongs in the platform (app-shell), reused by any multi-org ObjectOS app;
cloud's onOrganizationCreated hook provisions the env (open mechanism, closed
orchestration — ADR-0002/0024).

Verified: new OrganizationsPage.test.tsx (zero-org auto-opens; multi-org does
not; ?create=1 still opens) — 3/3 pass.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

packages/app-shell/src/console/organizations/OrganizationsPage.tsx

@@ -140,21 +140,30 @@ export function OrganizationsPage() {
   }, [isOrganizationsLoading, orgList.length, manageMode, wantsCreate]);
 
   // Open the create dialog when arriving via the header "Create workspace"
-  // entry (`?create=1`). Guarded so closing the dialog doesn't re-open it.
+  // entry (`?create=1`), OR for a brand-new user who has ZERO organizations:
+  // they have nothing to pick, so land them straight on the "name your
+  // workspace" form instead of an empty picker (one hop fewer on first run).
+  // The empty-state (with its own "New organization" button) remains the
+  // backdrop if they dismiss the dialog. Guarded so closing never re-opens it.
   const createOpenedRef = useRef(false);
   useEffect(() => {
-    if (wantsCreate && !createOpenedRef.current) {
+    if (isOrganizationsLoading) return;
+    const firstRunNoOrg = orgList.length === 0 && canCreateOrg;
+    if ((wantsCreate || firstRunNoOrg) && !createOpenedRef.current) {
       createOpenedRef.current = true;
       setIsCreateOpen(true);
     }
-  }, [wantsCreate]);
+  }, [wantsCreate, orgList.length, canCreateOrg, isOrganizationsLoading]);
 
-  // Show a spinner while we're either still loading, or about to auto-redirect
-  // because there's only one org. This prevents the picker from briefly
-  // flashing on screen for single-org users.
+  // Show a spinner while we're either still loading, about to auto-redirect
+  // because there's only one org, or about to auto-open the create dialog for a
+  // brand-new zero-org user. This prevents the picker / empty-state from
+  // briefly flashing on screen before the redirect or dialog.
   const willAutoSelect =
     !wantsCreate && !isOrganizationsLoading && orgList.length === 1;
-  if (isOrganizationsLoading || willAutoSelect) {
+  const willAutoCreate =
+    !isOrganizationsLoading && orgList.length === 0 && canCreateOrg && !createOpenedRef.current;
+  if (isOrganizationsLoading || willAutoSelect || willAutoCreate) {
     return (
       <div className="flex flex-1 items-center justify-center py-20">
         <Loader2 className="h-5 w-5 animate-spin text-muted-foreground" />

packages/app-shell/src/console/organizations/__tests__/OrganizationsPage.test.tsx

@@ -0,0 +1,99 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * OrganizationsPage — zero-org first-run auto-opens the create-workspace form.
+ *
+ * A brand-new user with NO organizations has nothing to pick, so the page must
+ * land them straight on the "name your workspace" dialog instead of an empty
+ * picker (one hop fewer on first run). Users who already have organizations
+ * still see the picker; the `?create=1` entry still opens the dialog.
+ */
+
+import '@testing-library/jest-dom/vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+
+vi.mock('@object-ui/i18n', () => ({
+  useObjectTranslation: () => ({
+    t: (key: string, options?: Record<string, unknown>) => String(options?.defaultValue ?? key),
+  }),
+}));
+
+const navigate = vi.fn();
+let searchParams = new URLSearchParams();
+vi.mock('react-router-dom', () => ({
+  useNavigate: () => navigate,
+  useSearchParams: () => [searchParams],
+}));
+
+let authState: Record<string, unknown>;
+vi.mock('@object-ui/auth', () => ({ useAuth: () => authState }));
+
+vi.mock('../resolveHomeUrl', () => ({ resolveRootUrl: () => '/root' }));
+
+// Stub the dialog so the test observes only whether it is opened.
+vi.mock('../CreateWorkspaceDialog', () => ({
+  CreateWorkspaceDialog: ({ open }: { open: boolean }) =>
+    open ? <div data-testid="create-workspace-dialog" /> : null,
+}));
+
+// Passthrough UI primitives (spread props → children render).
+vi.mock('@object-ui/components', () => ({
+  Avatar: (p: any) => <div {...p} />,
+  AvatarImage: (p: any) => <img {...p} />,
+  AvatarFallback: (p: any) => <div {...p} />,
+  Button: (p: any) => <button {...p} />,
+  Input: (p: any) => <input {...p} />,
+  Empty: (p: any) => <div {...p} />,
+  EmptyTitle: (p: any) => <div {...p} />,
+  EmptyDescription: (p: any) => <div {...p} />,
+}));
+vi.mock('lucide-react', () => ({
+  Plus: () => <span />,
+  Search: () => <span />,
+  Loader2: () => <span />,
+}));
+
+import { OrganizationsPage } from '../OrganizationsPage';
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  searchParams = new URLSearchParams();
+  authState = {
+    organizations: [],
+    activeOrganization: null,
+    isOrganizationsLoading: false,
+    switchOrganization: vi.fn(),
+    getAuthConfig: vi.fn().mockResolvedValue({ features: { multiOrgEnabled: true } }),
+  };
+});
+
+describe('OrganizationsPage — zero-org first run', () => {
+  it('auto-opens the create-workspace dialog when the user has no organizations', async () => {
+    render(<OrganizationsPage />);
+    await waitFor(() =>
+      expect(screen.getByTestId('create-workspace-dialog')).toBeInTheDocument(),
+    );
+    // Landed straight on the form — no picker card navigation happened.
+    expect(navigate).not.toHaveBeenCalled();
+  });
+
+  it('does NOT auto-open the dialog when the user already has organizations', async () => {
+    authState.organizations = [
+      { id: 'o1', name: 'Alpha', slug: 'alpha' },
+      { id: 'o2', name: 'Beta', slug: 'beta' },
+    ];
+    render(<OrganizationsPage />);
+    await waitFor(() => expect((authState.getAuthConfig as any)).toHaveBeenCalled());
+    expect(screen.queryByTestId('create-workspace-dialog')).toBeNull();
+  });
+
+  it('still opens the dialog via the explicit ?create=1 entry (regression)', async () => {
+    authState.organizations = [{ id: 'o1', name: 'Alpha', slug: 'alpha' }];
+    searchParams = new URLSearchParams('create=1');
+    render(<OrganizationsPage />);
+    await waitFor(() =>
+      expect(screen.getByTestId('create-workspace-dialog')).toBeInTheDocument(),
+    );
+  });
+});