fix(projects): return a Project's environments in fork order

The Project API listed environments by workspace id, so every client had to rebuild the
fork tree to show them. They now come back roots first, each fork right after the
environment it was forked from, siblings by name; a fork whose parent the viewer cannot see
is a root, as before. The contract documents the order, and the org project view reads it
as is.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lrd1NLD9qx2KBLVnw32c3E

Author: TheodoreSpeaks

apps/sim/app/o/[organizationId]/p/hooks/use-projects.ts

@@ -14,7 +14,7 @@ export interface Project {
   id: string
   name: string
   organizationId: string | null
-  /** Roots first, each fork after its parent, siblings by name. */
+  /** In the API's order: roots first, each fork after its parent, siblings by name. */
   environments: ProjectEnvironment[]
   canAdminister: boolean
 }
@@ -30,30 +30,15 @@ function byName(a: { name: string }, b: { name: string }): number {
 }
 
 function toProject(record: ProjectRecord): Project {
-  const visible = new Set(record.environments.map((environment) => environment.id))
-  const children = new Map<string | null, ProjectEnvironment[]>()
-  for (const environment of record.environments) {
-    const parent = environment.forkedFromWorkspaceId
-    const parentId = parent && visible.has(parent) ? parent : null
-    const siblings = children.get(parentId) ?? []
-    siblings.push({ workspaceId: environment.id, name: environment.name, parentId })
-    children.set(parentId, siblings)
-  }
-  const environments: ProjectEnvironment[] = []
-  const visit = (parentId: string | null) => {
-    for (const environment of [...(children.get(parentId) ?? [])].sort(byName)) {
-      environments.push(environment)
-      visit(environment.workspaceId)
-    }
-  }
-  visit(null)
-  if (environments.length !== record.environments.length)
-    throw new Error(`Project ${record.id} has a fork cycle among its environments`)
   return {
     id: record.id,
     name: record.name,
     organizationId: record.organizationId,
-    environments,
+    environments: record.environments.map((environment) => ({
+      workspaceId: environment.id,
+      name: environment.name,
+      parentId: environment.forkedFromWorkspaceId,
+    })),
     canAdminister: record.capabilities.administer,
   }
 }

apps/sim/lib/api/contracts/projects.ts

@@ -20,6 +20,7 @@ const projectSchema = z.object({
   archivedAt: z.coerce.date().nullable(),
   createdAt: z.coerce.date(),
   updatedAt: z.coerce.date(),
+  /** Roots first, each fork right after the environment it was forked from, siblings by name. */
   environments: z.array(projectEnvironmentSchema),
   capabilities: z.object({ administer: z.boolean(), issues: z.boolean() }),
 })

apps/sim/lib/projects/__integration__/foundation.integration.ts

@@ -1035,6 +1035,57 @@ describe('Project foundation at the database and application boundary', () => {
     }
   )
 
+  check(
+    'orders environments roots first, each fork after its parent, siblings by name',
+    async () => {
+      const f = await fixture(true, 1)
+      const [root] = f.ids
+      /** Ascending ids, assigned so id order disagrees with fork order. */
+      const [staging, sandbox, dev] = Array.from({ length: 3 }, () => generateId()).sort()
+      await db.transaction(async (tx) => {
+        for (const [id, name, parent] of [
+          [staging, 'Staging', root],
+          [dev, 'Dev', root],
+          [sandbox, 'Sandbox', dev],
+        ] as const) {
+          await tx.insert(workspace).values({
+            id,
+            projectId: f.projectId,
+            name,
+            ownerId: f.ownerId,
+            billedAccountUserId: f.ownerId,
+            organizationId: f.organizationId,
+            workspaceMode: 'organization',
+            forkedFromWorkspaceId: parent,
+          })
+          await tx.insert(permissions).values({
+            id: generateId(),
+            entityType: 'workspace',
+            entityId: id,
+            userId: f.ownerId,
+            permissionType: 'admin',
+          })
+        }
+      })
+      const result = await getProject.execute({
+        principal: f.owner,
+        input: { projectId: f.projectId },
+        request,
+      })
+      expect(
+        result.project.environments.map(({ id, forkedFromWorkspaceId }) => [
+          id,
+          forkedFromWorkspaceId,
+        ])
+      ).toEqual([
+        [root, null],
+        [dev, root],
+        [sandbox, dev],
+        [staging, root],
+      ])
+    }
+  )
+
   check(
     'hides inaccessible environments and denies mismatched scopes and workspace keys',
     async () => {

apps/sim/lib/projects/application/authorization.ts

@@ -2,6 +2,7 @@ import type { Principal, SessionPrincipal } from '@sim/auth/principal'
 import { member, permissionGroup, permissions, project } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
 import { isOrgAdminRole } from '@sim/platform-authz/workspace'
+import { compareStrings } from '@sim/utils/string'
 import { and, asc, eq, inArray, sql } from 'drizzle-orm'
 import { PrincipalKindAuthorizationError } from '@/lib/core/application/workspace-authorization'
 import { OrchestrationError } from '@/lib/core/orchestration/types'
@@ -147,6 +148,42 @@ async function loadProjectAccess(
 }
 
 /** Applies the access rules to one loaded Project; hidden environments never enter the result. */
+interface ProjectEnvironment {
+  id: string
+  name: string
+  forkedFromWorkspaceId: string | null
+}
+
+/**
+ * Roots first, each fork right after the environment it was forked from, siblings by name. A
+ * fork whose parent the viewer cannot see is presented as a root.
+ */
+function orderEnvironments(
+  rows: readonly { id: string; name: string; parentId: string | null }[]
+): ProjectEnvironment[] {
+  const ids = new Set(rows.map((row) => row.id))
+  const children = new Map<string | null, ProjectEnvironment[]>()
+  for (const row of rows) {
+    const parent = row.parentId && ids.has(row.parentId) ? row.parentId : null
+    const siblings = children.get(parent) ?? []
+    siblings.push({ id: row.id, name: row.name, forkedFromWorkspaceId: parent })
+    children.set(parent, siblings)
+  }
+  const ordered: ProjectEnvironment[] = []
+  const visit = (parent: string | null) => {
+    const siblings = (children.get(parent) ?? []).sort(
+      (a, b) => compareStrings(a.name, b.name) || compareStrings(a.id, b.id)
+    )
+    for (const environment of siblings) {
+      ordered.push(environment)
+      visit(environment.id)
+    }
+  }
+  visit(null)
+  if (ordered.length !== rows.length) throw new Error('Project environments contain a fork cycle')
+  return ordered
+}
+
 async function evaluateProjectAccess(
   tx: DbTransaction,
   principal: SessionPrincipal,
@@ -200,17 +237,7 @@ async function evaluateProjectAccess(
     if (record.archivedAt) throw new OrchestrationError('conflict', 'Project is archived')
     refuseCapability('project_issues.use')
   }
-  const visibleIds = new Set(visible.map((row) => row.id))
-  return {
-    record,
-    canAdminister,
-    canUseIssues,
-    environments: visible.map((row) => ({
-      id: row.id,
-      name: row.name,
-      forkedFromWorkspaceId: row.parentId && visibleIds.has(row.parentId) ? row.parentId : null,
-    })),
-  }
+  return { record, canAdminister, canUseIssues, environments: orderEnvironments(visible) }
 }
 
 export type AuthorizedProject = Awaited<ReturnType<typeof evaluateProjectAccess>>