feat: implement environment provisioning retry mechanism and enhance UI with status badges

Author: hotlong

apps/studio/src/components/environment-status-badge.tsx

@@ -0,0 +1,84 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * EnvironmentStatusBadge — color-coded pill for the environment lifecycle
+ * status (provisioning / active / failed / suspended / archived / migrating).
+ *
+ * Rendered alongside {@link EnvironmentBadge} (which encodes envType) on the
+ * environment list and detail pages so operators can tell at a glance whether
+ * a given environment is ready, still coming up, or broken.
+ *
+ * Keep this component purely presentational — no data fetching or navigation
+ * side-effects — so it can be rendered in tables, badges, and dialogs
+ * without pulling in context.
+ */
+
+import { Loader2, AlertTriangle, CheckCircle2, PauseCircle, Archive, MoveRight } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import type { EnvironmentStatus } from '@objectstack/spec/cloud';
+
+const VARIANT: Record<EnvironmentStatus, string> = {
+  provisioning:
+    'border-sky-500/40 bg-sky-500/10 text-sky-700 dark:text-sky-300',
+  active:
+    'border-emerald-500/40 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300',
+  failed:
+    'border-red-500/40 bg-red-500/10 text-red-700 dark:text-red-300',
+  suspended:
+    'border-amber-500/40 bg-amber-500/10 text-amber-700 dark:text-amber-300',
+  archived:
+    'border-muted bg-muted text-muted-foreground',
+  migrating:
+    'border-violet-500/40 bg-violet-500/10 text-violet-700 dark:text-violet-300',
+};
+
+const LABEL: Record<EnvironmentStatus, string> = {
+  provisioning: 'Provisioning',
+  active: 'Active',
+  failed: 'Provisioning failed',
+  suspended: 'Suspended',
+  archived: 'Archived',
+  migrating: 'Migrating',
+};
+
+function StatusIcon({ status, className }: { status: EnvironmentStatus; className?: string }) {
+  switch (status) {
+    case 'provisioning':
+      return <Loader2 className={cn('h-3 w-3 animate-spin', className)} />;
+    case 'failed':
+      return <AlertTriangle className={cn('h-3 w-3', className)} />;
+    case 'active':
+      return <CheckCircle2 className={cn('h-3 w-3', className)} />;
+    case 'suspended':
+      return <PauseCircle className={cn('h-3 w-3', className)} />;
+    case 'archived':
+      return <Archive className={cn('h-3 w-3', className)} />;
+    case 'migrating':
+      return <MoveRight className={cn('h-3 w-3', className)} />;
+    default:
+      return null;
+  }
+}
+
+export interface EnvironmentStatusBadgeProps {
+  status: EnvironmentStatus;
+  /** Omit the label and show just the icon chip. Useful in dense lists. */
+  iconOnly?: boolean;
+  className?: string;
+}
+
+export function EnvironmentStatusBadge({ status, iconOnly, className }: EnvironmentStatusBadgeProps) {
+  return (
+    <span
+      className={cn(
+        'inline-flex items-center gap-1 rounded border px-1.5 py-0.5 text-[10px] font-medium uppercase tracking-wider',
+        VARIANT[status],
+        className,
+      )}
+      title={LABEL[status]}
+    >
+      <StatusIcon status={status} />
+      {!iconOnly && <span>{LABEL[status]}</span>}
+    </span>
+  );
+}

apps/studio/src/hooks/useEnvironments.ts

@@ -100,38 +100,39 @@ export function useEnvironmentDetail(environmentId: string | undefined) {
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
-  useEffect(() => {
+  const load = useCallback(async () => {
     if (!environmentId || !client?.environments) {
       setDetail(null);
       client?.setEnvironmentId?.(undefined);
       return;
     }
-    let alive = true;
     setLoading(true);
     setError(null);
     client.setEnvironmentId(environmentId);
     rememberActiveEnvironment(environmentId);
+    try {
+      const result = await client.environments.get(environmentId);
+      setDetail(result as EnvironmentDetail);
+    } catch (err) {
+      setError(err as Error);
+      setDetail(null);
+    } finally {
+      setLoading(false);
+    }
+  }, [client, environmentId]);
 
+  useEffect(() => {
+    let alive = true;
     (async () => {
-      try {
-        const result = await client.environments.get(environmentId);
-        if (!alive) return;
-        setDetail(result as EnvironmentDetail);
-      } catch (err) {
-        if (!alive) return;
-        setError(err as Error);
-        setDetail(null);
-      } finally {
-        if (alive) setLoading(false);
-      }
+      if (!alive) return;
+      await load();
     })();
-
     return () => {
       alive = false;
     };
-  }, [client, environmentId]);
+  }, [load]);
 
-  return { detail, loading, error };
+  return { detail, loading, error, reload: load };
 }
 
 /**
@@ -200,3 +201,37 @@ export function useProvisionEnvironment() {
 
   return { provision, provisioning, error };
 }
+
+/**
+ * Hook: retry provisioning for an environment stuck in `failed` state.
+ *
+ * Wraps `client.environments.retryProvisioning(id)`. Exposes `retrying`
+ * state so callers can disable the button and show a spinner while the
+ * server re-runs the driver handshake.
+ */
+export function useRetryProvisioning() {
+  const client = useClient() as any;
+  const [retrying, setRetrying] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const retry = useCallback(
+    async (environmentId: string) => {
+      if (!client?.environments?.retryProvisioning) {
+        throw new Error('Client not ready');
+      }
+      setRetrying(true);
+      setError(null);
+      try {
+        return await client.environments.retryProvisioning(environmentId);
+      } catch (err) {
+        setError(err as Error);
+        throw err;
+      } finally {
+        setRetrying(false);
+      }
+    },
+    [client],
+  );
+
+  return { retry, retrying, error };
+}

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

@@ -17,17 +17,20 @@ import {
   KeyRound,
   MapPin,
   RefreshCw,
+  RotateCw,
   Trash,
   AlertTriangle,
+  Loader2,
   Package,
 } from 'lucide-react';
 import { SiteHeader } from '@/components/site-header';
 import { EnvironmentBadge } from '@/components/environment-badge';
+import { EnvironmentStatusBadge } from '@/components/environment-status-badge';
 import { Card } from '@/components/ui/card';
 import { Button } from '@/components/ui/button';
 import { Badge } from '@/components/ui/badge';
 import { Separator } from '@/components/ui/separator';
-import { useEnvironmentDetail } from '@/hooks/useEnvironments';
+import { useEnvironmentDetail, useRetryProvisioning } from '@/hooks/useEnvironments';
 import { useClient } from '@objectstack/client-react';
 import { useProductionGuard } from '@/components/production-guard';
 import { toast } from '@/hooks/use-toast';
@@ -36,13 +39,47 @@ function EnvironmentOverviewComponent() {
   const { environmentId } = useParams({
     from: '/environments/$environmentId',
   });
-  const { detail, loading } = useEnvironmentDetail(environmentId);
+  const { detail, loading, reload } = useEnvironmentDetail(environmentId);
   const client = useClient() as any;
   const navigate = useNavigate();
   const guard = useProductionGuard();
   const [rotating, setRotating] = useState(false);
+  const { retry, retrying } = useRetryProvisioning();
 
   const env = detail?.environment;
+  const provisioningError =
+    (env?.metadata as Record<string, any> | undefined)?.provisioningError as
+      | { message?: string; failedAt?: string }
+      | undefined;
+
+  const handleRetry = async () => {
+    if (!env) return;
+    try {
+      const result = await retry(env.id);
+      const nextStatus = (result as any)?.environment?.status;
+      if (nextStatus === 'active') {
+        toast({
+          title: 'Provisioning complete',
+          description: 'The environment is now active and ready to use.',
+        });
+      } else if (nextStatus === 'failed') {
+        toast({
+          title: 'Retry failed',
+          description:
+            (result as any)?.environment?.metadata?.provisioningError?.message ??
+            'Provisioning failed again. Check server logs.',
+          variant: 'destructive',
+        });
+      }
+      await reload();
+    } catch (err) {
+      toast({
+        title: 'Retry failed',
+        description: (err as Error).message,
+        variant: 'destructive',
+      });
+    }
+  };
 
   const handleRotate = async () => {
     if (!env) return;
@@ -100,20 +137,32 @@ function EnvironmentOverviewComponent() {
                       {env.isDefault && (
                         <Badge variant="outline">default</Badge>
                       )}
-                      <Badge variant="secondary">{env.status}</Badge>
+                      <EnvironmentStatusBadge status={env.status} />
                     </div>
                     <p className="mt-1 font-mono text-xs text-muted-foreground">
                       {env.id}
                     </p>
                   </div>
                   <div className="flex gap-2">
+                    <Button
+                      variant="outline"
+                      size="sm"
+                      onClick={() => reload()}
+                      disabled={loading}
+                      className="gap-2"
+                      title="Refresh environment status"
+                    >
+                      <RefreshCw className={`h-3.5 w-3.5 ${loading ? 'animate-spin' : ''}`} />
+                      Refresh
+                    </Button>
                     <Button
                       variant="outline"
                       className="gap-2"
                       onClick={() => navigate({
                         to: '/environments/$environmentId/packages',
                         params: { environmentId: env.id },
                       })}
+                      disabled={env.status !== 'active'}
                     >
                       <Package className="h-4 w-4" />
                       Packages
@@ -127,7 +176,56 @@ function EnvironmentOverviewComponent() {
                   </div>
                 </div>
 
-                {env.envType === 'production' && (
+                {env.status === 'provisioning' && (
+                  <Card className="flex items-start gap-3 border-sky-500/40 bg-sky-500/5 p-4">
+                    <Loader2 className="mt-0.5 h-5 w-5 shrink-0 animate-spin text-sky-600" />
+                    <div className="flex-1 text-sm">
+                      <p className="font-medium text-sky-700 dark:text-sky-300">
+                        Provisioning in progress
+                      </p>
+                      <p className="text-muted-foreground">
+                        We&rsquo;re allocating the physical database and
+                        minting credentials for this environment. This
+                        normally takes a few seconds — click Refresh to
+                        check the latest status.
+                      </p>
+                    </div>
+                  </Card>
+                )}
+
+                {env.status === 'failed' && (
+                  <Card className="flex items-start gap-3 border-red-500/40 bg-red-500/5 p-4">
+                    <AlertTriangle className="mt-0.5 h-5 w-5 shrink-0 text-red-600" />
+                    <div className="flex-1 text-sm">
+                      <p className="font-medium text-red-700 dark:text-red-300">
+                        Provisioning failed
+                      </p>
+                      <p className="text-muted-foreground">
+                        {provisioningError?.message ??
+                          'The environment could not be provisioned. Retry to run the driver handshake again.'}
+                      </p>
+                      {provisioningError?.failedAt && (
+                        <p className="mt-1 text-xs text-muted-foreground">
+                          Last attempt: {new Date(provisioningError.failedAt).toLocaleString()}
+                        </p>
+                      )}
+                      <div className="mt-3">
+                        <Button
+                          size="sm"
+                          variant="destructive"
+                          onClick={handleRetry}
+                          disabled={retrying}
+                          className="gap-2"
+                        >
+                          <RotateCw className={`h-3.5 w-3.5 ${retrying ? 'animate-spin' : ''}`} />
+                          {retrying ? 'Retrying…' : 'Retry provisioning'}
+                        </Button>
+                      </div>
+                    </div>
+                  </Card>
+                )}
+
+                {env.envType === 'production' && env.status === 'active' && (
                   <Card className="flex items-start gap-3 border-red-500/40 bg-red-500/5 p-4">
                     <AlertTriangle className="mt-0.5 h-5 w-5 shrink-0 text-red-600" />
                     <div className="text-sm">
@@ -193,7 +291,7 @@ function EnvironmentOverviewComponent() {
                       size="sm"
                       variant="outline"
                       onClick={handleRotate}
-                      disabled={rotating}
+                      disabled={rotating || env.status !== 'active'}
                       className="gap-2"
                     >
                       <RefreshCw

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

@@ -14,12 +14,13 @@
 
 import { createFileRoute, useNavigate } from '@tanstack/react-router';
 import { useState } from 'react';
-import { Plus, Database, MapPin } from 'lucide-react';
+import { Plus, Database, MapPin, RefreshCw } from 'lucide-react';
 import { SiteHeader } from '@/components/site-header';
 import { Button } from '@/components/ui/button';
 import { Card } from '@/components/ui/card';
 import { Badge } from '@/components/ui/badge';
 import { EnvironmentBadge } from '@/components/environment-badge';
+import { EnvironmentStatusBadge } from '@/components/environment-status-badge';
 import { NewEnvironmentDialog } from '@/components/new-environment-dialog';
 import { useEnvironments } from '@/hooks/useEnvironments';
 
@@ -48,6 +49,20 @@ function EnvironmentsListComponent() {
             </Button>
           </div>
 
+          <div className="mb-3 flex items-center justify-end">
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={() => reload()}
+              disabled={loading}
+              className="gap-2"
+              title="Refresh the environment list (does not auto-poll)"
+            >
+              <RefreshCw className={`h-3.5 w-3.5 ${loading ? 'animate-spin' : ''}`} />
+              Refresh
+            </Button>
+          </div>
+
           {loading && (
             <div className="text-sm text-muted-foreground">Loading…</div>
           )}
@@ -92,9 +107,7 @@ function EnvironmentsListComponent() {
                           default
                         </Badge>
                       )}
-                      <Badge variant="secondary" className="text-[10px]">
-                        {env.status}
-                      </Badge>
+                      <EnvironmentStatusBadge status={env.status} />
                     </div>
                     <div className="mt-1 flex items-center gap-3 text-xs text-muted-foreground">
                       <code className="font-mono">{env.slug}</code>