fix(dexdex): harden workspace validation for repository actions (#279)

## Summary
- reconcile persisted active workspace IDs so invalid or legacy values
do not break repository actions
- guard workspace-scoped queries/stream/tray/shortcut paths when no
active workspace exists
- improve Repositories UX with workspace-required guidance and inline
validation/mutation error rendering
- add regression tests for legacy ID migration, empty-workspace
blocking, and create error visibility
- update DexDex project/app contract docs to match the new workspace
reconciliation behavior

## Verification
- pnpm --filter dexdex test
- pnpm --filter dexdex build

Author: kdy1

apps/dexdex/src/App.test.tsx

@@ -3,7 +3,7 @@ import userEvent from "@testing-library/user-event";
 import { describe, expect, it, beforeEach } from "vitest";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { TransportProvider } from "@connectrpc/connect-query";
-import { createRouterTransport } from "@connectrpc/connect";
+import { Code, ConnectError, createRouterTransport } from "@connectrpc/connect";
 import { MemoryRouter } from "react-router";
 import { create } from "@bufbuild/protobuf";
 import { timestampFromDate } from "@bufbuild/protobuf/wkt";
@@ -18,6 +18,7 @@ import {
   ReviewAssistService,
   ReviewCommentService,
   RepositoryService,
+  WorkspaceSchema,
   UnitTaskSchema,
   SubTaskSchema,
   RepositorySchema,
@@ -34,6 +35,7 @@ import {
   NotificationType,
   PrStatus,
   AgentCliType,
+  WorkspaceType,
   PullRequestRecordSchema,
 } from "./gen/v1/dexdex_pb";
 
@@ -50,6 +52,9 @@ const localStorageMock = (() => {
 
 Object.defineProperty(window, "localStorage", { value: localStorageMock });
 
+const DEFAULT_WORKSPACE_ID = "ws-default";
+const LEGACY_DEFAULT_WORKSPACE_ID = "workspace-default";
+
 // Mock proto data matching the old MOCK_TASKS shape
 const mockUnitTasks = [
   create(UnitTaskSchema, {
@@ -206,14 +211,14 @@ const mockPullRequests = [
 const mockRepositories = [
   create(RepositorySchema, {
     repositoryId: "repo-oss",
-    workspaceId: "workspace-default",
+    workspaceId: DEFAULT_WORKSPACE_ID,
     repositoryUrl: "https://github.com/example/oss",
     createdAt: timestampFromDate(new Date("2026-03-10T00:00:00Z")),
     updatedAt: timestampFromDate(new Date("2026-03-10T00:00:00Z")),
   }),
   create(RepositorySchema, {
     repositoryId: "repo-infra",
-    workspaceId: "workspace-default",
+    workspaceId: DEFAULT_WORKSPACE_ID,
     repositoryUrl: "https://github.com/example/infra",
     createdAt: timestampFromDate(new Date("2026-03-10T00:00:00Z")),
     updatedAt: timestampFromDate(new Date("2026-03-10T00:00:00Z")),
@@ -223,7 +228,7 @@ const mockRepositories = [
 const mockRepositoryGroups = [
   create(RepositoryGroupSchema, {
     repositoryGroupId: "repo-group-main",
-    workspaceId: "workspace-default",
+    workspaceId: DEFAULT_WORKSPACE_ID,
     members: [
       create(RepositoryGroupMemberSchema, {
         repositoryId: "repo-oss",
@@ -238,11 +243,35 @@ const mockRepositoryGroups = [
 ];
 
 const mockWorkspaceSettings = create(WorkspaceSettingsSchema, {
-  workspaceId: "workspace-default",
+  workspaceId: DEFAULT_WORKSPACE_ID,
   defaultAgentCliType: AgentCliType.CLAUDE_CODE,
 });
 
-function createTestTransport() {
+interface TestTransportOptions {
+  workspaces?: Array<{
+    workspaceId: string;
+    name: string;
+    type?: WorkspaceType;
+  }>;
+  createRepositoryErrorMessage?: string;
+}
+
+function createTestTransport(options: TestTransportOptions = {}) {
+  const workspaces = (options.workspaces ?? [
+    {
+      workspaceId: DEFAULT_WORKSPACE_ID,
+      name: "Default Workspace",
+      type: WorkspaceType.LOCAL_ENDPOINT,
+    },
+  ]).map((workspace) =>
+    create(WorkspaceSchema, {
+      workspaceId: workspace.workspaceId,
+      name: workspace.name,
+      type: workspace.type ?? WorkspaceType.LOCAL_ENDPOINT,
+      createdAt: timestampFromDate(new Date("2026-03-10T00:00:00Z")),
+    }),
+  );
+
   return createRouterTransport((router) => {
     router.service(TaskService, {
       listUnitTasks: () => ({ unitTasks: mockUnitTasks }),
@@ -290,8 +319,27 @@ function createTestTransport() {
       stopAgentSession: () => ({}),
     });
     router.service(WorkspaceService, {
-      getWorkspace: () => ({ workspace: undefined }),
-      listWorkspaces: () => ({ workspaces: [] }),
+      getWorkspace: (req) => ({
+        workspace: workspaces.find((workspace) => workspace.workspaceId === req.workspaceId),
+      }),
+      listWorkspaces: () => ({ workspaces }),
+      createWorkspace: (req) => {
+        const createdWorkspace = create(WorkspaceSchema, {
+          workspaceId: `ws-${Date.now()}`,
+          name: req.name,
+          type: req.type,
+          createdAt: timestampFromDate(new Date()),
+        });
+        workspaces.push(createdWorkspace);
+        return { workspace: createdWorkspace };
+      },
+      setActiveWorkspace: (req) => {
+        const workspace = workspaces.find((item) => item.workspaceId === req.workspaceId);
+        if (!workspace) {
+          throw new Error(`workspace not found: ${req.workspaceId}`);
+        }
+        return { workspace };
+      },
       getWorkspaceWorkStatus: () => ({ status: 0 }),
       getWorkspaceSettings: () => ({ settings: mockWorkspaceSettings }),
       updateWorkspaceSettings: (req) => ({
@@ -315,15 +363,20 @@ function createTestTransport() {
     router.service(RepositoryService, {
       getRepository: () => ({ repository: mockRepositories[0] }),
       listRepositories: () => ({ repositories: mockRepositories }),
-      createRepository: (req) => ({
-        repository: create(RepositorySchema, {
-          repositoryId: `repo-${Date.now()}`,
-          workspaceId: req.workspaceId,
-          repositoryUrl: req.repositoryUrl,
-          createdAt: timestampFromDate(new Date()),
-          updatedAt: timestampFromDate(new Date()),
-        }),
-      }),
+      createRepository: async (req) => {
+        if (options.createRepositoryErrorMessage) {
+          throw new ConnectError(options.createRepositoryErrorMessage, Code.Internal);
+        }
+        return {
+          repository: create(RepositorySchema, {
+            repositoryId: `repo-${Date.now()}`,
+            workspaceId: req.workspaceId,
+            repositoryUrl: req.repositoryUrl,
+            createdAt: timestampFromDate(new Date()),
+            updatedAt: timestampFromDate(new Date()),
+          }),
+        };
+      },
       updateRepository: (req) => ({
         repository: create(RepositorySchema, {
           repositoryId: req.repositoryId,
@@ -379,7 +432,13 @@ function createTestTransport() {
   });
 }
 
-function renderWithProviders(ui: React.ReactElement, { initialEntries = ["/tasks"] }: { initialEntries?: string[] } = {}) {
+function renderWithProviders(
+  ui: React.ReactElement,
+  {
+    initialEntries = ["/tasks"],
+    transportOptions,
+  }: { initialEntries?: string[]; transportOptions?: TestTransportOptions } = {},
+) {
   const queryClient = new QueryClient({
     defaultOptions: {
       queries: {
@@ -390,7 +449,7 @@ function renderWithProviders(ui: React.ReactElement, { initialEntries = ["/tasks
   });
   return render(
     <QueryClientProvider client={queryClient}>
-      <TransportProvider transport={createTestTransport()}>
+      <TransportProvider transport={createTestTransport(transportOptions)}>
         <MemoryRouter initialEntries={initialEntries}>
           {ui}
         </MemoryRouter>
@@ -402,6 +461,7 @@ function renderWithProviders(ui: React.ReactElement, { initialEntries = ["/tasks
 beforeEach(() => {
   localStorageMock.clear();
   document.documentElement.classList.remove("dark");
+  localStorageMock.setItem("dexdex-active-workspace-id", DEFAULT_WORKSPACE_ID);
 });
 
 describe("App", () => {
@@ -755,4 +815,75 @@ describe("App", () => {
     expect(await screen.findByText("Plan approval needed")).toBeTruthy();
     expect(screen.getByText("CI failure on PR #42")).toBeTruthy();
   });
+
+  it("migrates legacy persisted workspace id to canonical workspace id", async () => {
+    localStorageMock.setItem("dexdex-active-workspace-id", LEGACY_DEFAULT_WORKSPACE_ID);
+    renderWithProviders(<App />);
+
+    await screen.findByTestId("task-list");
+    await waitFor(() => {
+      expect(localStorageMock.getItem("dexdex-active-workspace-id")).toBe(DEFAULT_WORKSPACE_ID);
+    });
+  });
+
+  it("blocks repository creation when no workspace exists", async () => {
+    localStorageMock.removeItem("dexdex-active-workspace-id");
+    renderWithProviders(<App />, {
+      initialEntries: ["/repositories"],
+      transportOptions: { workspaces: [] },
+    });
+
+    expect(await screen.findByTestId("repositories-page")).toBeTruthy();
+    expect(screen.getByTestId("repository-workspace-hint")).toBeTruthy();
+
+    const createInput = screen.getByTestId("create-repository-url") as HTMLInputElement;
+    const createButton = screen.getByRole("button", { name: "Add Repository" }) as HTMLButtonElement;
+    expect(createInput.disabled).toBe(true);
+    expect(createButton.disabled).toBe(true);
+  });
+
+  it("shows repository create validation errors", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<App />, { initialEntries: ["/repositories"] });
+
+    expect(await screen.findByTestId("repositories-page")).toBeTruthy();
+    const createInput = screen.getByTestId("create-repository-url") as HTMLInputElement;
+    const createButton = screen.getByRole("button", { name: "Add Repository" }) as HTMLButtonElement;
+
+    await waitFor(() => {
+      expect(createInput.disabled).toBe(false);
+      expect(createButton.disabled).toBe(false);
+    });
+
+    await user.clear(createInput);
+    await user.type(createInput, "github.com/example/new-repo");
+    await user.click(createButton);
+
+    const mutationError = await screen.findByTestId("repository-mutation-error");
+    expect(mutationError.textContent).toBe("Repository URL must start with http:// or https://.");
+  });
+
+  it("shows repository create mutation errors", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<App />, {
+      initialEntries: ["/repositories"],
+      transportOptions: { createRepositoryErrorMessage: "rpc create failed" },
+    });
+
+    expect(await screen.findByTestId("repositories-page")).toBeTruthy();
+    const createInput = screen.getByTestId("create-repository-url") as HTMLInputElement;
+    const createButton = screen.getByRole("button", { name: "Add Repository" }) as HTMLButtonElement;
+
+    await waitFor(() => {
+      expect(createInput.disabled).toBe(false);
+      expect(createButton.disabled).toBe(false);
+    });
+
+    await user.type(createInput, "https://github.com/example/new-repo");
+    await user.click(createButton);
+
+    const mutationError = await screen.findByTestId("repository-mutation-error");
+    expect(mutationError.textContent?.includes("Failed to add repository:")).toBe(true);
+    expect(mutationError.textContent?.includes("rpc create failed")).toBe(true);
+  });
 });

apps/dexdex/src/components/sidebar.tsx

@@ -2,8 +2,8 @@
  * Sidebar navigation component with Linear-style layout.
  */
 
-import { type CSSProperties, useCallback, useEffect, useRef, useState } from "react";
-import { useAppStore } from "../stores/app-store";
+import { type CSSProperties, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { CANONICAL_DEFAULT_WORKSPACE_ID, LEGACY_DEFAULT_WORKSPACE_ID, useAppStore } from "../stores/app-store";
 import { useCreateWorkspaceMutation, useListWorkspaces, useSetActiveWorkspaceMutation } from "../hooks/use-dexdex-queries";
 import { WorkspaceType } from "../gen/v1/dexdex_pb";
 
@@ -28,18 +28,57 @@ function formatMutationError(error: unknown): string {
   return String(error);
 }
 
+function resolveValidWorkspaceId(activeWorkspaceId: string, workspaceIds: string[]): string {
+  if (workspaceIds.length === 0) {
+    return "";
+  }
+
+  const normalizedActiveWorkspaceId = activeWorkspaceId.trim();
+  if (normalizedActiveWorkspaceId && workspaceIds.includes(normalizedActiveWorkspaceId)) {
+    return normalizedActiveWorkspaceId;
+  }
+
+  if (
+    normalizedActiveWorkspaceId === LEGACY_DEFAULT_WORKSPACE_ID &&
+    workspaceIds.includes(CANONICAL_DEFAULT_WORKSPACE_ID)
+  ) {
+    return CANONICAL_DEFAULT_WORKSPACE_ID;
+  }
+
+  return workspaceIds[0];
+}
+
 export function Sidebar({ activePath, onNavigate }: SidebarProps) {
   const { sidebarOpen, connectionStatus, activeWorkspaceId, setActiveWorkspaceId } = useAppStore();
   const [dropdownOpen, setDropdownOpen] = useState(false);
   const [createWorkspaceError, setCreateWorkspaceError] = useState<string | null>(null);
   const dropdownRef = useRef<HTMLDivElement>(null);
-  const { data: workspacesData } = useListWorkspaces();
+  const workspacesQuery = useListWorkspaces();
   const setActiveWorkspaceMutation = useSetActiveWorkspaceMutation();
   const createWorkspaceMutation = useCreateWorkspaceMutation();
 
-  const workspaces = workspacesData?.workspaces ?? [];
+  const workspaces = workspacesQuery.data?.workspaces ?? [];
+  const workspaceIds = useMemo(() => workspaces.map((workspace) => workspace.workspaceId), [workspaces]);
+  const hasWorkspaces = workspaceIds.length > 0;
   const currentWorkspace = workspaces.find((w) => w.workspaceId === activeWorkspaceId);
-  const currentWorkspaceName = currentWorkspace?.name || activeWorkspaceId;
+  const currentWorkspaceName = currentWorkspace?.name || activeWorkspaceId || "No workspace selected";
+
+  useEffect(() => {
+    if (!workspacesQuery.isSuccess) {
+      return;
+    }
+
+    const resolvedWorkspaceId = resolveValidWorkspaceId(activeWorkspaceId, workspaceIds);
+    if (resolvedWorkspaceId === activeWorkspaceId) {
+      return;
+    }
+
+    setCreateWorkspaceError(null);
+    setActiveWorkspaceId(resolvedWorkspaceId);
+    if (resolvedWorkspaceId) {
+      setActiveWorkspaceMutation.mutate({ workspaceId: resolvedWorkspaceId });
+    }
+  }, [activeWorkspaceId, setActiveWorkspaceId, setActiveWorkspaceMutation, workspaceIds, workspacesQuery.isSuccess]);
 
   const handleWorkspaceSwitch = useCallback(
     (workspaceId: string) => {
@@ -313,6 +352,19 @@ export function Sidebar({ activePath, onNavigate }: SidebarProps) {
             {createWorkspaceError}
           </p>
         )}
+        {!createWorkspaceError && !hasWorkspaces && (
+          <p
+            style={{
+              marginTop: "var(--space-2)",
+              marginBottom: 0,
+              fontSize: "var(--font-size-xs)",
+              color: "var(--color-text-tertiary)",
+            }}
+            data-testid="workspace-required-hint"
+          >
+            Create a workspace to enable repositories, repository groups, and task workflows.
+          </p>
+        )}
       </div>
       <div style={navStyle}>
         {NAV_ITEMS.map((item) => {

apps/dexdex/src/features/inbox/inbox-page.tsx

@@ -51,7 +51,7 @@ function getNotificationBadgeColor(type: NotificationType): string {
 export function InboxPage() {
   const navigate = useNavigate();
   const store = useContext(AppStoreContext);
-  const workspaceId = store?.activeWorkspaceId ?? "workspace-default";
+  const workspaceId = store?.activeWorkspaceId ?? "";
 
   const { data: notifications = [], isLoading } = useListNotifications(workspaceId);
   const markReadMutation = useMarkNotificationReadMutation();