feat: implement per-environment package management

- Added environment selection logic in RequireAuth to redirect users to the environment picker when accessing routes that require an environment context.
- Created new route for managing packages within specific environments, allowing users to install, enable, disable, and uninstall packages.
- Introduced useEnvironmentPackages hook for fetching and managing installed packages in an environment.
- Updated ObjectStackClient to support package management operations per environment.
- Implemented backend API endpoints for package installation, retrieval, enabling, disabling, and uninstallation.
- Defined new schemas for environment package installations and requests in the spec package.
- Removed legacy packages route and adjusted related components to align with the new per-environment package management model.

Author: hotlong

apps/studio/src/components/app-sidebar.tsx

@@ -576,8 +576,15 @@ export function AppSidebar({
               <SidebarMenuItem>
                 <SidebarMenuButton
                   tooltip="Packages"
-                  isActive={location.pathname === '/packages'}
-                  onClick={() => navigate({ to: '/packages' })}
+                  isActive={location.pathname.endsWith('/packages')}
+                  onClick={() => {
+                    const envId = params.environmentId as string | undefined;
+                    if (envId) {
+                      navigate({ to: '/environments/$environmentId/packages', params: { environmentId: envId } });
+                    } else {
+                      navigate({ to: '/environments' });
+                    }
+                  }}
                 >
                   <Package className="h-4 w-4" />
                   <span>Packages</span>

apps/studio/src/hooks/useEnvironmentPackages.ts

@@ -0,0 +1,87 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { useState, useEffect, useCallback } from 'react';
+import { useClient } from '@objectstack/client-react';
+
+export interface EnvPackage {
+  id: string;
+  environmentId: string;
+  packageId: string;
+  version: string;
+  status: string;
+  enabled: boolean;
+  installedAt: string;
+  installedBy?: string;
+  settings?: Record<string, unknown>;
+  upgradeHistory?: Array<{ fromVersion: string; toVersion: string; upgradedAt: string; status: string }>;
+}
+
+export function useEnvironmentPackages(environmentId: string | undefined) {
+  const client = useClient() as any;
+  const [packages, setPackages] = useState<EnvPackage[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const load = useCallback(async () => {
+    if (!client || !environmentId) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const result = await client.environments.packages.list(environmentId);
+      // Normalize snake_case DB fields to camelCase interface
+      const rows = (result?.packages ?? []).map((r: any) => ({
+        id: r.id,
+        environmentId: r.environment_id ?? r.environmentId,
+        packageId: r.package_id ?? r.packageId,
+        version: r.version,
+        status: r.status,
+        enabled: r.enabled,
+        installedAt: r.installed_at ?? r.installedAt,
+        installedBy: r.installed_by ?? r.installedBy,
+        settings: r.settings,
+        upgradeHistory: r.upgrade_history ?? r.upgradeHistory,
+      }));
+      setPackages(rows);
+    } catch (e) {
+      setError(e as Error);
+    } finally {
+      setLoading(false);
+    }
+  }, [client, environmentId]);
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  const install = useCallback(async (body: {
+    packageId: string;
+    version?: string;
+    settings?: Record<string, unknown>;
+    enableOnInstall?: boolean;
+  }) => {
+    if (!client || !environmentId) return;
+    const result = await client.environments.packages.install(environmentId, body);
+    await load();
+    return result?.package;
+  }, [client, environmentId, load]);
+
+  const uninstall = useCallback(async (pkgId: string) => {
+    if (!client || !environmentId) return;
+    await client.environments.packages.uninstall(environmentId, pkgId);
+    await load();
+  }, [client, environmentId, load]);
+
+  const enable = useCallback(async (pkgId: string) => {
+    if (!client || !environmentId) return;
+    await client.environments.packages.enable(environmentId, pkgId);
+    await load();
+  }, [client, environmentId, load]);
+
+  const disable = useCallback(async (pkgId: string) => {
+    if (!client || !environmentId) return;
+    await client.environments.packages.disable(environmentId, pkgId);
+    await load();
+  }, [client, environmentId, load]);
+
+  return { packages, loading, error, install, uninstall, enable, disable, reload: load };
+}

apps/studio/src/routeTree.gen.ts

@@ -22,6 +22,7 @@ import { Route as OrgsNewRouteImport } from './routes/orgs.new'
 import { Route as OrgsOrgIdRouteImport } from './routes/orgs.$orgId'
 import { Route as EnvironmentsEnvironmentIdRouteImport } from './routes/environments.$environmentId'
 import { Route as EnvironmentsEnvironmentIdIndexRouteImport } from './routes/environments.$environmentId.index'
+import { Route as EnvironmentsEnvironmentIdPackagesRouteImport } from './routes/environments.$environmentId.packages'
 import { Route as PackageObjectsNameRouteImport } from './routes/$package.objects.$name'
 import { Route as PackageMetadataTypeNameRouteImport } from './routes/$package.metadata.$type.$name'
 
@@ -92,6 +93,12 @@ const EnvironmentsEnvironmentIdIndexRoute =
     path: '/',
     getParentRoute: () => EnvironmentsEnvironmentIdRoute,
   } as any)
+const EnvironmentsEnvironmentIdPackagesRoute =
+  EnvironmentsEnvironmentIdPackagesRouteImport.update({
+    id: '/packages',
+    path: '/packages',
+    getParentRoute: () => EnvironmentsEnvironmentIdRoute,
+  } as any)
 const PackageObjectsNameRoute = PackageObjectsNameRouteImport.update({
   id: '/objects/$name',
   path: '/objects/$name',
@@ -117,6 +124,7 @@ export interface FileRoutesByFullPath {
   '/environments/': typeof EnvironmentsIndexRoute
   '/orgs/': typeof OrgsIndexRoute
   '/$package/objects/$name': typeof PackageObjectsNameRoute
+  '/environments/$environmentId/packages': typeof EnvironmentsEnvironmentIdPackagesRoute
   '/environments/$environmentId/': typeof EnvironmentsEnvironmentIdIndexRoute
   '/$package/metadata/$type/$name': typeof PackageMetadataTypeNameRoute
 }
@@ -132,6 +140,7 @@ export interface FileRoutesByTo {
   '/environments': typeof EnvironmentsIndexRoute
   '/orgs': typeof OrgsIndexRoute
   '/$package/objects/$name': typeof PackageObjectsNameRoute
+  '/environments/$environmentId/packages': typeof EnvironmentsEnvironmentIdPackagesRoute
   '/environments/$environmentId': typeof EnvironmentsEnvironmentIdIndexRoute
   '/$package/metadata/$type/$name': typeof PackageMetadataTypeNameRoute
 }
@@ -150,6 +159,7 @@ export interface FileRoutesById {
   '/environments/': typeof EnvironmentsIndexRoute
   '/orgs/': typeof OrgsIndexRoute
   '/$package/objects/$name': typeof PackageObjectsNameRoute
+  '/environments/$environmentId/packages': typeof EnvironmentsEnvironmentIdPackagesRoute
   '/environments/$environmentId/': typeof EnvironmentsEnvironmentIdIndexRoute
   '/$package/metadata/$type/$name': typeof PackageMetadataTypeNameRoute
 }
@@ -169,6 +179,7 @@ export interface FileRouteTypes {
     | '/environments/'
     | '/orgs/'
     | '/$package/objects/$name'
+    | '/environments/$environmentId/packages'
     | '/environments/$environmentId/'
     | '/$package/metadata/$type/$name'
   fileRoutesByTo: FileRoutesByTo
@@ -184,6 +195,7 @@ export interface FileRouteTypes {
     | '/environments'
     | '/orgs'
     | '/$package/objects/$name'
+    | '/environments/$environmentId/packages'
     | '/environments/$environmentId'
     | '/$package/metadata/$type/$name'
   id:
@@ -201,6 +213,7 @@ export interface FileRouteTypes {
     | '/environments/'
     | '/orgs/'
     | '/$package/objects/$name'
+    | '/environments/$environmentId/packages'
     | '/environments/$environmentId/'
     | '/$package/metadata/$type/$name'
   fileRoutesById: FileRoutesById
@@ -312,6 +325,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof EnvironmentsEnvironmentIdIndexRouteImport
       parentRoute: typeof EnvironmentsEnvironmentIdRoute
     }
+    '/environments/$environmentId/packages': {
+      id: '/environments/$environmentId/packages'
+      path: '/packages'
+      fullPath: '/environments/$environmentId/packages'
+      preLoaderRoute: typeof EnvironmentsEnvironmentIdPackagesRouteImport
+      parentRoute: typeof EnvironmentsEnvironmentIdRoute
+    }
     '/$package/objects/$name': {
       id: '/$package/objects/$name'
       path: '/objects/$name'
@@ -345,11 +365,14 @@ const PackageRouteWithChildren =
   PackageRoute._addFileChildren(PackageRouteChildren)
 
 interface EnvironmentsEnvironmentIdRouteChildren {
+  EnvironmentsEnvironmentIdPackagesRoute: typeof EnvironmentsEnvironmentIdPackagesRoute
   EnvironmentsEnvironmentIdIndexRoute: typeof EnvironmentsEnvironmentIdIndexRoute
 }
 
 const EnvironmentsEnvironmentIdRouteChildren: EnvironmentsEnvironmentIdRouteChildren =
   {
+    EnvironmentsEnvironmentIdPackagesRoute:
+      EnvironmentsEnvironmentIdPackagesRoute,
     EnvironmentsEnvironmentIdIndexRoute: EnvironmentsEnvironmentIdIndexRoute,
   }
 

apps/studio/src/routes/__root.tsx

@@ -16,12 +16,35 @@ import { SessionProvider, useSession } from '../hooks/useSession';
 /** Routes that don't require authentication. */
 const PUBLIC_ROUTES = new Set(['/login', '/register']);
 
+/**
+ * Routes where an environment selection is NOT required.
+ * Everything under /environments (list + detail), org mgmt, auth pages.
+ */
+function isEnvExemptPath(pathname: string): boolean {
+  return (
+    pathname === '/' ||
+    pathname.startsWith('/login') ||
+    pathname.startsWith('/register') ||
+    pathname.startsWith('/orgs') ||
+    pathname.startsWith('/environments')
+  );
+}
+
 function RequireAuth({ children }: { children: React.ReactNode }) {
   const { user, loading } = useSession();
   const navigate = useNavigate();
   const location = useLocation();
   const isPublic = PUBLIC_ROUTES.has(location.pathname);
 
+  // Redirect to environment picker when the user hits a route that requires
+  // an environment context (e.g. /$package/*) but isn't already under /environments.
+  useEffect(() => {
+    if (loading || !user) return;
+    if (!isEnvExemptPath(location.pathname)) {
+      navigate({ to: '/environments' });
+    }
+  }, [user, loading, location.pathname, navigate]);
+
   useEffect(() => {
     if (loading) return;
     if (!user && !isPublic) {

apps/studio/src/routes/environments.$environmentId.index.tsx

@@ -19,6 +19,7 @@ import {
   RefreshCw,
   Trash,
   AlertTriangle,
+  Package,
 } from 'lucide-react';
 import { AppSidebar } from '@/components/app-sidebar';
 import { SiteHeader } from '@/components/site-header';
@@ -114,12 +115,25 @@ function EnvironmentOverviewComponent() {
                       {env.id}
                     </p>
                   </div>
-                  <Button
-                    variant="outline"
-                    onClick={() => navigate({ to: '/environments' })}
-                  >
-                    Back to list
-                  </Button>
+                  <div className="flex gap-2">
+                    <Button
+                      variant="outline"
+                      className="gap-2"
+                      onClick={() => navigate({
+                        to: '/environments/$environmentId/packages',
+                        params: { environmentId: env.id },
+                      })}
+                    >
+                      <Package className="h-4 w-4" />
+                      Packages
+                    </Button>
+                    <Button
+                      variant="outline"
+                      onClick={() => navigate({ to: '/environments' })}
+                    >
+                      Back to list
+                    </Button>
+                  </div>
                 </div>
 
                 {env.envType === 'production' && (