feat(ui): add sortable column headers to domains table

Reviewed-on: http://gitea.lan:3000/robbond/pleskSaas/pulls/28

app/api/cron/health/route.ts

@@ -0,0 +1,38 @@
+import { NextResponse } from "next/server";
+
+import { env } from "@/lib/env";
+import { runHealthCheckTick } from "@/lib/plesk/health";
+import { createSupabaseAdminClient } from "@/lib/supabase/admin";
+
+export async function POST(req: Request) {
+  const startedAt = Date.now();
+
+  try {
+    const secret = req.headers.get("x-cron-secret");
+    if (!env.cronSecret || !secret || secret !== env.cronSecret) {
+      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+    }
+
+    const supabase = createSupabaseAdminClient() as any;
+    const summary = await runHealthCheckTick(supabase);
+
+    return NextResponse.json({
+      ...summary,
+      duration_ms: Date.now() - startedAt,
+    });
+  } catch (error) {
+    console.error("[health cron] failed", error);
+
+    return NextResponse.json(
+      {
+        error: "Health check job failed",
+        checked: 0,
+        ok: 0,
+        degraded: 0,
+        failed: 0,
+        duration_ms: Date.now() - startedAt,
+      },
+      { status: 500 },
+    );
+  }
+}

app/api/plesk/instances/[id]/health/route.ts

@@ -0,0 +1,73 @@
+import { NextResponse } from "next/server";
+
+import { assertAgencyAdmin, getRouteAgencyContextOrThrow } from "@/lib/agency";
+import { assertRateLimit } from "@/lib/api/rate-limit";
+import { assertSameOrigin } from "@/lib/api/security";
+import { runInstanceHealthCheck } from "@/lib/plesk/health";
+import { createSupabaseRouteClient } from "@/lib/supabase/route";
+
+export async function POST(
+  req: Request,
+  { params }: { params: { id: string } },
+) {
+  try {
+    assertSameOrigin(req);
+
+    const context = await getRouteAgencyContextOrThrow();
+    assertAgencyAdmin(context);
+    assertRateLimit(`plesk-health-check:${context.userId}`, 20, 60_000);
+
+    const supabase = createSupabaseRouteClient() as any;
+
+    const { data: instance, error: instanceError } = await supabase
+      .from("plesk_instances")
+      .select(
+        "id, agency_id, base_url, auth_type, encrypted_secret, health_enabled, health_check_frequency_minutes, health_next_check_at, health_lock_until",
+      )
+      .eq("id", params.id)
+      .eq("agency_id", context.agencyId)
+      .single();
+
+    if (instanceError || !instance) {
+      throw new Error("Plesk instance not found");
+    }
+
+    const result = await runInstanceHealthCheck(supabase, instance, {
+      actorUserId: context.userId,
+      force: true,
+      source: "manual",
+    });
+
+    if (!result.checked) {
+      return NextResponse.json(
+        { error: "Health check is already running for this instance" },
+        { status: 409 },
+      );
+    }
+
+    const { data: updated } = await supabase
+      .from("plesk_instances")
+      .select(
+        "id, health_enabled, health_status, health_last_checked_at, health_last_ok_at, health_last_error, health_last_latency_ms, health_check_frequency_minutes, health_next_check_at",
+      )
+      .eq("id", params.id)
+      .eq("agency_id", context.agencyId)
+      .single();
+
+    return NextResponse.json({
+      ok: true,
+      result,
+      instance: updated,
+    });
+  } catch (error) {
+    return NextResponse.json(
+      {
+        error:
+          error instanceof Error
+            ? error.message
+            : "Health check execution failed",
+      },
+      { status: 400 },
+    );
+  }
+}

app/dashboard/page.tsx

@@ -1,6 +1,7 @@
 import { SignOutButton } from "@/components/auth/sign-out-button";
 import { DashboardControls } from "@/components/dashboard/dashboard-controls";
 import { getServerAgencyContextOrRedirect } from "@/lib/agency";
+import { formatDateTime } from "@/lib/dates";
 import type { Database } from "@/lib/types";
 import { createSupabaseServerClient } from "@/lib/supabase/server";
 import Link from "next/link";
@@ -17,6 +18,78 @@ type ActionLogSummary = Pick<
   Database["public"]["Tables"]["actions_log"]["Row"],
   "target_id" | "status" | "action" | "created_at" | "error_message"
 >;
+type AutosyncLatestLogSummary = Pick<
+  Database["public"]["Tables"]["actions_log"]["Row"],
+  "created_at"
+>;
+type HealthLogSummary = Pick<
+  Database["public"]["Tables"]["actions_log"]["Row"],
+  | "id"
+  | "target_id"
+  | "status"
+  | "action"
+  | "created_at"
+  | "error_message"
+  | "metadata"
+>;
+
+const RELATIVE_TIME_FORMATTER = new Intl.RelativeTimeFormat("en", {
+  numeric: "auto",
+});
+
+function getLatestTimestamp(values: Array<string | null | undefined>) {
+  let latestIso: string | null = null;
+  let latestMs = Number.NEGATIVE_INFINITY;
+
+  for (const value of values) {
+    if (!value) continue;
+    const parsed = new Date(value).getTime();
+    if (Number.isNaN(parsed)) continue;
+    if (parsed > latestMs) {
+      latestMs = parsed;
+      latestIso = value;
+    }
+  }
+
+  return latestIso;
+}
+
+function formatRelativeTime(value?: string | null) {
+  if (!value) return null;
+
+  const targetMs = new Date(value).getTime();
+  if (Number.isNaN(targetMs)) return null;
+
+  const deltaSeconds = Math.round((targetMs - Date.now()) / 1000);
+  const absSeconds = Math.abs(deltaSeconds);
+
+  if (absSeconds < 60) {
+    return RELATIVE_TIME_FORMATTER.format(deltaSeconds, "second");
+  }
+
+  const deltaMinutes = Math.round(deltaSeconds / 60);
+  if (Math.abs(deltaMinutes) < 60) {
+    return RELATIVE_TIME_FORMATTER.format(deltaMinutes, "minute");
+  }
+
+  const deltaHours = Math.round(deltaMinutes / 60);
+  if (Math.abs(deltaHours) < 24) {
+    return RELATIVE_TIME_FORMATTER.format(deltaHours, "hour");
+  }
+
+  const deltaDays = Math.round(deltaHours / 24);
+  if (Math.abs(deltaDays) < 30) {
+    return RELATIVE_TIME_FORMATTER.format(deltaDays, "day");
+  }
+
+  const deltaMonths = Math.round(deltaDays / 30);
+  if (Math.abs(deltaMonths) < 12) {
+    return RELATIVE_TIME_FORMATTER.format(deltaMonths, "month");
+  }
+
+  const deltaYears = Math.round(deltaMonths / 12);
+  return RELATIVE_TIME_FORMATTER.format(deltaYears, "year");
+}
 
 function normalizeDomainLike(value: string) {
   return value.trim().toLowerCase().replace(/\.$/, "");
@@ -49,6 +122,8 @@ export default async function DashboardPage() {
     { data: domains },
     { data: billing },
     { data: autoSyncLogs },
+    { data: latestAutoSyncLog },
+    { data: healthLogs },
   ] = (await Promise.all([
     supabase
       .from("agencies")
@@ -58,7 +133,7 @@ export default async function DashboardPage() {
     supabase
       .from("plesk_instances")
       .select(
-        "id, name, base_url, auth_type, status, error_message, last_connected_at, last_sync_at, last_sync_status, last_sync_error, last_sync_subscriptions, last_sync_domains, auto_sync_enabled, auto_sync_frequency_minutes, last_auto_sync_at, next_auto_sync_at, auto_sync_lock_until",
+        "id, name, base_url, auth_type, status, error_message, last_connected_at, last_sync_at, last_sync_status, last_sync_error, last_sync_subscriptions, last_sync_domains, auto_sync_enabled, auto_sync_frequency_minutes, last_auto_sync_at, next_auto_sync_at, auto_sync_lock_until, health_enabled, health_status, health_last_checked_at, health_last_ok_at, health_last_error, health_last_latency_ms, health_check_frequency_minutes, health_next_check_at, health_lock_until",
       )
       .eq("agency_id", context.agencyId)
       .order("created_at", { ascending: false }),
@@ -89,6 +164,31 @@ export default async function DashboardPage() {
       .eq("action", "plesk_sync_auto")
       .order("created_at", { ascending: false })
       .limit(200),
+    supabase
+      .from("actions_log")
+      .select("created_at")
+      .eq("agency_id", context.agencyId)
+      .eq("target_type", "plesk_instance")
+      .eq("action", "autosync_completed")
+      .eq("status", "success")
+      .order("created_at", { ascending: false })
+      .limit(1)
+      .maybeSingle(),
+    supabase
+      .from("actions_log")
+      .select(
+        "id, target_id, status, action, created_at, error_message, metadata",
+      )
+      .eq("agency_id", context.agencyId)
+      .eq("target_type", "plesk_instance")
+      .in("action", [
+        "health_check_started",
+        "health_check_ok",
+        "health_check_degraded",
+        "health_check_failed",
+      ])
+      .order("created_at", { ascending: false })
+      .limit(400),
   ])) as [
     { data: AgencySummary | null },
     {
@@ -110,6 +210,15 @@ export default async function DashboardPage() {
         last_auto_sync_at: string | null;
         next_auto_sync_at: string | null;
         auto_sync_lock_until: string | null;
+        health_enabled: boolean;
+        health_status: "ok" | "degraded" | "down" | "unknown";
+        health_last_checked_at: string | null;
+        health_last_ok_at: string | null;
+        health_last_error: string | null;
+        health_last_latency_ms: number | null;
+        health_check_frequency_minutes: number;
+        health_next_check_at: string | null;
+        health_lock_until: string | null;
       }> | null;
       error: { message: string } | null;
     },
@@ -138,6 +247,8 @@ export default async function DashboardPage() {
     },
     { data: BillingSummary | null },
     { data: ActionLogSummary[] | null },
+    { data: AutosyncLatestLogSummary | null },
+    { data: HealthLogSummary[] | null },
   ];
 
   const domainInstanceIds = Array.from(
@@ -230,6 +341,67 @@ export default async function DashboardPage() {
     });
   }
 
+  const healthEventsByInstance = new Map<
+    string,
+    Array<{
+      id: string;
+      action: string;
+      status: string;
+      created_at: string;
+      error_message: string | null;
+      metadata: unknown;
+    }>
+  >();
+
+  for (const log of healthLogs ?? []) {
+    if (!log.target_id) continue;
+    const existing = healthEventsByInstance.get(log.target_id) ?? [];
+    if (existing.length >= 10) continue;
+    existing.push({
+      id: log.id,
+      action: log.action,
+      status: log.status,
+      created_at: log.created_at,
+      error_message: log.error_message,
+      metadata: log.metadata,
+    });
+    healthEventsByInstance.set(log.target_id, existing);
+  }
+
+  const healthCounts = { ok: 0, degraded: 0, down: 0, unknown: 0 };
+
+  for (const instance of instances ?? []) {
+    const status = (instance.health_status ?? "unknown") as
+      | "ok"
+      | "degraded"
+      | "down"
+      | "unknown";
+    if (status === "ok") healthCounts.ok += 1;
+    else if (status === "degraded") healthCounts.degraded += 1;
+    else if (status === "down") healthCounts.down += 1;
+    else healthCounts.unknown += 1;
+  }
+
+  const latestHealthCheckAt = getLatestTimestamp(
+    (instances ?? []).map((instance) => instance.health_last_checked_at),
+  );
+
+  const autoSyncEnabledCount = (instances ?? []).filter(
+    (instance) => instance.auto_sync_enabled,
+  ).length;
+
+  const latestAutoSyncFromInstances = getLatestTimestamp(
+    (instances ?? []).map((instance) => instance.last_auto_sync_at),
+  );
+
+  const latestAutoSyncAt =
+    latestAutoSyncFromInstances ?? latestAutoSyncLog?.created_at ?? null;
+
+  const downInstanceNames = (instances ?? [])
+    .filter((instance) => instance.health_status === "down")
+    .slice(0, 3)
+    .map((instance) => instance.name || instance.base_url);
+
   return (
     <main className="mx-auto flex w-full max-w-6xl flex-col gap-6 px-6 py-8">
       <header className="flex items-center justify-between">
@@ -250,6 +422,89 @@ export default async function DashboardPage() {
         </div>
       </header>
 
+      <section className="rounded-xl border border-slate-200 bg-white p-4">
+        <div className="space-y-3 text-sm text-slate-700">
+          <div>
+            <p className="text-xs font-semibold uppercase tracking-wide text-slate-500">
+              Instance Health
+            </p>
+            <div className="mt-1 flex flex-wrap gap-2">
+              <span className="rounded bg-emerald-100 px-2 py-0.5 text-xs font-medium text-emerald-700">
+                Ok: {healthCounts.ok}
+              </span>
+              <span className="rounded bg-amber-100 px-2 py-0.5 text-xs font-medium text-amber-700">
+                Degraded: {healthCounts.degraded}
+              </span>
+              <span className="rounded bg-rose-100 px-2 py-0.5 text-xs font-medium text-rose-700">
+                Down: {healthCounts.down}
+              </span>
+              <span className="rounded bg-slate-100 px-2 py-0.5 text-xs font-medium text-slate-700">
+                Unknown: {healthCounts.unknown}
+              </span>
+            </div>
+          </div>
+
+          {healthCounts.down > 0 ? (
+            <div className="rounded border border-rose-200 bg-rose-50 px-3 py-2 text-xs text-rose-700">
+              {healthCounts.down} instance{healthCounts.down === 1 ? "" : "s"}{" "}
+              down
+              {downInstanceNames.length > 0
+                ? `: ${downInstanceNames.join(", ")}${healthCounts.down > downInstanceNames.length ? ", …" : ""}`
+                : ""}
+            </div>
+          ) : null}
+
+          <div className="flex flex-wrap gap-3">
+            <p>
+              <span className="font-medium text-slate-900">
+                Last Health Check:
+              </span>{" "}
+              <span
+                title={
+                  latestHealthCheckAt
+                    ? formatDateTime(latestHealthCheckAt)
+                    : undefined
+                }
+              >
+                {formatRelativeTime(latestHealthCheckAt) ?? "Never"}
+              </span>
+            </p>
+            <p>
+              <span className="font-medium text-slate-900">Auto Sync:</span>{" "}
+              Enabled on {autoSyncEnabledCount} instance
+              {autoSyncEnabledCount === 1 ? "" : "s"}
+            </p>
+            <p>
+              <span className="font-medium text-slate-900">Last run:</span>{" "}
+              <span
+                title={
+                  latestAutoSyncAt
+                    ? formatDateTime(latestAutoSyncAt)
+                    : undefined
+                }
+              >
+                {formatRelativeTime(latestAutoSyncAt) ?? "Not yet run"}
+              </span>
+            </p>
+          </div>
+
+          <div className="flex flex-wrap gap-2 pt-1">
+            <Link
+              href="/dashboard#instances-panel"
+              className="rounded border border-slate-300 px-3 py-1.5 text-xs font-medium text-slate-700"
+            >
+              Instances
+            </Link>
+            <Link
+              href="/dashboard/activity"
+              className="rounded border border-slate-300 px-3 py-1.5 text-xs font-medium text-slate-700"
+            >
+              Activity
+            </Link>
+          </div>
+        </div>
+      </section>
+
       <section className="grid gap-4 md:grid-cols-3">
         <div className="rounded-xl border border-slate-200 bg-white p-4">
           <p className="text-sm text-slate-500">Plesk Instances</p>
@@ -275,44 +530,49 @@ export default async function DashboardPage() {
           Instances query failed: {instancesError.message}
         </div>
       ) : null}
-      <DashboardControls
+      <section id="instances-panel">
-        instances={instances ?? []}
+        <DashboardControls
-        subscriptions={subscriptions ?? []}
+          instances={instances ?? []}
-        domains={(domains ?? []).map((domain) => {
+          subscriptions={subscriptions ?? []}
-          const joinedStatusByLocalId = domain.subscription_id
+          domains={(domains ?? []).map((domain) => {
-            ? subscriptionStatusById.get(domain.subscription_id)
+            const joinedStatusByLocalId = domain.subscription_id
-            : null;
+              ? subscriptionStatusById.get(domain.subscription_id)
-          const joinedStatusByExternalId = domain.external_subscription_id
+              : null;
-            ? subscriptionStatusByExternalId.get(
+            const joinedStatusByExternalId = domain.external_subscription_id
-                `${domain.plesk_instance_id}:${domain.external_subscription_id}`,
+              ? subscriptionStatusByExternalId.get(
-              )
+                  `${domain.plesk_instance_id}:${domain.external_subscription_id}`,
-            : null;
+                )
-          const joinedStatusByName = subscriptionStatusByInstanceAndName.get(
+              : null;
-            `${domain.plesk_instance_id}:${normalizeDomainLike(domain.domain_name)}`,
+            const joinedStatusByName = subscriptionStatusByInstanceAndName.get(
-          );
+              `${domain.plesk_instance_id}:${normalizeDomainLike(domain.domain_name)}`,
-          const joinedStatusBySuffix = findBestSuffixStatusMatch(
+            );
-            normalizeDomainLike(domain.domain_name),
+            const joinedStatusBySuffix = findBestSuffixStatusMatch(
-            subscriptionStatusNameCandidatesByInstance.get(
+              normalizeDomainLike(domain.domain_name),
-              domain.plesk_instance_id,
+              subscriptionStatusNameCandidatesByInstance.get(
-            ) ?? [],
+                domain.plesk_instance_id,
-          );
+              ) ?? [],
-          const joinedStatus =
+            );
-            joinedStatusByLocalId ??
+            const joinedStatus =
-            joinedStatusByExternalId ??
+              joinedStatusByLocalId ??
-            joinedStatusByName ??
+              joinedStatusByExternalId ??
-            joinedStatusBySuffix;
+              joinedStatusByName ??
+              joinedStatusBySuffix;
 
-          return {
+            return {
-            ...domain,
+              ...domain,
-            status: joinedStatus ?? "unknown",
+              status: joinedStatus ?? "unknown",
-            subscription_name: domain.subscription_id
+              subscription_name: domain.subscription_id
-              ? (subscriptionDisplayNameById.get(domain.subscription_id) ??
+                ? (subscriptionDisplayNameById.get(domain.subscription_id) ??
-                null)
+                  null)
-              : null,
+                : null,
-          };
+            };
-        })}
+          })}
-        autoSyncByInstance={Object.fromEntries(autoSyncByInstance.entries())}
+          autoSyncByInstance={Object.fromEntries(autoSyncByInstance.entries())}
-      />
+          healthEventsByInstance={Object.fromEntries(
+            healthEventsByInstance.entries(),
+          )}
+        />
+      </section>
     </main>
   );
 }

docs/cline-super-prompt.md

@@ -0,0 +1,202 @@
+# Cline Development Super Prompt
+
+You are acting as a senior software engineer working on this repository.
+
+Before making any modifications you must understand the project structure and current implementation.
+
+Always read:
+
+`docs/ai-project-context.md`
+
+before implementing tasks.
+
+---
+
+## Working Method
+
+When given a task follow this process.
+
+Step 1  
+Search the repository for relevant code.
+
+Step 2  
+Identify the correct extension point for the feature.
+
+Step 3  
+Design the minimal safe implementation.
+
+Step 4  
+Modify only the required files.
+
+Step 5  
+Verify existing functionality remains intact.
+
+Never rewrite large parts of the system unless explicitly instructed.
+
+---
+
+## Repository Exploration Rules
+
+Before editing files:
+
+Search for related implementations.
+
+Look for:
+
+- plesk integration
+- sync logic
+- API routes
+- database queries
+- dashboard components
+
+Use existing patterns instead of creating new ones.
+
+---
+
+## Database Rules
+
+The project uses Supabase Postgres.
+
+Never introduce breaking schema changes.
+
+All schema updates must be done using safe migrations.
+
+Never remove columns that may contain production data.
+
+Always assume the database already contains data.
+
+---
+
+## Multi-Tenant Security
+
+This system is multi-tenant.
+
+Users belong to agencies.
+
+All queries must respect agency boundaries.
+
+Never bypass Supabase Row Level Security.
+
+Never expose data across agencies.
+
+---
+
+## Plesk Integration Safety
+
+The platform interacts with Plesk servers using both REST API and CLI commands.
+
+CLI output can vary between Plesk versions.
+
+Always parse CLI output defensively.
+
+Never assume fixed output formatting.
+
+External integration failures must not crash the application.
+
+---
+
+## Sync Pipeline Rules
+
+The sync system is critical to the platform.
+
+Never break existing sync behaviour.
+
+If one subscription fails during sync:
+
+Continue processing the rest.
+
+Log the failure.
+
+Do not abort the entire sync job.
+
+---
+
+## Logging Requirements
+
+Operational events should be written to:
+
+`actions_log`
+
+Examples include:
+
+- instance_connected
+- sync_started
+- sync_completed
+- subscription_suspended
+- subscription_unsuspended
+
+Logging errors must never break primary workflows.
+
+---
+
+## UI Safety
+
+Frontend components must:
+
+Handle missing or null data safely.
+
+Avoid crashing when API responses change.
+
+Display statuses using badges instead of raw text.
+
+---
+
+## Git Workflow
+
+The repository uses:
+
+`master` as the default branch.
+
+All development must occur in feature branches.
+
+Example workflow:
+
+```bash
+git checkout master
+git pull
+git checkout -b feature/<feature-name>
+```
+
+Commit frequently with clear commit messages.
+
+Never commit directly to master.
+
+---
+
+## Implementation Guidelines
+
+Prefer small modular changes.
+
+Avoid large refactors unless requested.
+
+Keep API routes lightweight.
+
+Place integration logic inside lib folders.
+
+Reuse existing utilities where possible.
+
+---
+
+## Error Handling
+
+External services can fail.
+
+Always implement safe error handling.
+
+Prefer returning partial results over failing the entire operation.
+
+Log unexpected behaviour.
+
+---
+
+## Expected Output
+
+When implementing tasks you should:
+
+Modify only the required files.
+
+Maintain existing architecture.
+
+Add clear commit messages.
+
+Ensure the application remains stable.

lib/plesk/health.ts

@@ -0,0 +1,345 @@
+import { randomUUID } from "crypto";
+
+import { testPleskConnection } from "@/lib/plesk/client";
+
+type SupabaseLike = any;
+
+type HealthStatus = "ok" | "degraded" | "down" | "unknown";
+
+type HealthInstance = {
+  id: string;
+  agency_id: string;
+  base_url: string;
+  auth_type: "api_key" | "basic";
+  encrypted_secret: string;
+  health_enabled: boolean;
+  health_check_frequency_minutes: number | null;
+  health_next_check_at: string | null;
+  health_lock_until: string | null;
+};
+
+type HealthCheckResult = {
+  status: Exclude<HealthStatus, "unknown">;
+  latency_ms: number;
+  error_message: string | null;
+};
+
+type RunSingleHealthCheckResult = {
+  checked: boolean;
+  status?: Exclude<HealthStatus, "unknown">;
+  latency_ms?: number;
+  error_message?: string | null;
+};
+
+export type HealthTickSummary = {
+  checked: number;
+  ok: number;
+  degraded: number;
+  failed: number;
+  duration_ms: number;
+};
+
+const MAX_INSTANCES_PER_TICK = 10;
+const MAX_CONCURRENCY = 3;
+const LOCK_LEASE_SECONDS = 5 * 60;
+const HEALTH_TIMEOUT_MS = 15_000;
+const DEGRADED_LATENCY_THRESHOLD_MS = 2_500;
+
+function isDue(instance: HealthInstance, now: number) {
+  if (!instance.health_next_check_at) return true;
+  const dueAt = new Date(instance.health_next_check_at).getTime();
+  return Number.isFinite(dueAt) && dueAt <= now;
+}
+
+function isUnlocked(instance: HealthInstance, now: number) {
+  if (!instance.health_lock_until) return true;
+  const lockUntil = new Date(instance.health_lock_until).getTime();
+  return !Number.isFinite(lockUntil) || lockUntil <= now;
+}
+
+async function insertActionLogBestEffort(
+  supabase: SupabaseLike,
+  payload: Record<string, unknown>,
+) {
+  try {
+    const { error } = await supabase.from("actions_log").insert(payload);
+    if (error) {
+      console.error("[health] actions_log insert failed", error.message);
+    }
+  } catch (error) {
+    console.error("[health] actions_log insert threw", error);
+  }
+}
+
+async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+): Promise<T> {
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeout = setTimeout(() => {
+      reject(new Error("Health check timed out"));
+    }, timeoutMs);
+  });
+
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+async function checkPleskInstanceHealth(
+  instance: Pick<HealthInstance, "base_url" | "auth_type" | "encrypted_secret">,
+): Promise<HealthCheckResult> {
+  const startedAt = Date.now();
+
+  try {
+    await withTimeout(
+      testPleskConnection({
+        baseUrl: instance.base_url,
+        authType: instance.auth_type,
+        encryptedSecret: instance.encrypted_secret,
+      }),
+      HEALTH_TIMEOUT_MS,
+    );
+
+    const latencyMs = Date.now() - startedAt;
+    const status: "ok" | "degraded" =
+      latencyMs > DEGRADED_LATENCY_THRESHOLD_MS ? "degraded" : "ok";
+
+    return {
+      status,
+      latency_ms: latencyMs,
+      error_message: null,
+    };
+  } catch (error) {
+    return {
+      status: "down",
+      latency_ms: Date.now() - startedAt,
+      error_message:
+        error instanceof Error
+          ? error.message.slice(0, 1000)
+          : "health_check_failed",
+    };
+  }
+}
+
+export async function runInstanceHealthCheck(
+  supabase: SupabaseLike,
+  instance: HealthInstance,
+  input?: {
+    actorUserId?: string | null;
+    force?: boolean;
+    source?: "cron" | "manual";
+  },
+): Promise<RunSingleHealthCheckResult> {
+  const lockToken = randomUUID();
+  const actorUserId = input?.actorUserId ?? null;
+  const source = input?.source ?? "cron";
+
+  const { data: lockAcquired, error: lockError } = await supabase.rpc(
+    "acquire_instance_health_lock",
+    {
+      p_instance_id: instance.id,
+      p_lock_token: lockToken,
+      p_ttl_seconds: LOCK_LEASE_SECONDS,
+      p_force: Boolean(input?.force),
+    },
+  );
+
+  if (lockError || !lockAcquired) {
+    return { checked: false };
+  }
+
+  const startedAt = Date.now();
+  const nowIso = new Date().toISOString();
+  const frequencyMinutes = Math.max(
+    instance.health_check_frequency_minutes ?? 30,
+    5,
+  );
+  const nextCheckAtIso = new Date(
+    Date.now() + frequencyMinutes * 60 * 1000,
+  ).toISOString();
+
+  await insertActionLogBestEffort(supabase, {
+    agency_id: instance.agency_id,
+    actor_user_id: actorUserId,
+    target_type: "plesk_instance",
+    target_id: instance.id,
+    action: "health_check_started",
+    status: "pending",
+    metadata: {
+      instance_id: instance.id,
+      lock_token: lockToken,
+      source,
+    },
+  });
+
+  try {
+    const result = await checkPleskInstanceHealth(instance);
+
+    const updates: Record<string, unknown> = {
+      health_status: result.status,
+      health_last_checked_at: nowIso,
+      health_last_latency_ms: result.latency_ms,
+      health_last_error: result.error_message,
+      health_next_check_at: nextCheckAtIso,
+      health_lock_until: null,
+      health_lock_token: null,
+    };
+
+    if (result.status === "ok") {
+      updates.health_last_ok_at = nowIso;
+    }
+
+    const { error: updateError } = await supabase
+      .from("plesk_instances")
+      .update(updates)
+      .eq("id", instance.id)
+      .eq("health_lock_token", lockToken);
+
+    if (updateError) {
+      throw new Error(updateError.message);
+    }
+
+    const action =
+      result.status === "ok"
+        ? "health_check_ok"
+        : result.status === "degraded"
+          ? "health_check_degraded"
+          : "health_check_failed";
+
+    await insertActionLogBestEffort(supabase, {
+      agency_id: instance.agency_id,
+      actor_user_id: actorUserId,
+      target_type: "plesk_instance",
+      target_id: instance.id,
+      action,
+      status: result.status === "down" ? "failed" : "success",
+      error_message: result.error_message,
+      metadata: {
+        instance_id: instance.id,
+        lock_token: lockToken,
+        source,
+        latency_ms: result.latency_ms,
+        duration_ms: Date.now() - startedAt,
+      },
+    });
+
+    return {
+      checked: true,
+      status: result.status,
+      latency_ms: result.latency_ms,
+      error_message: result.error_message,
+    };
+  } catch (error) {
+    const errorMessage =
+      error instanceof Error
+        ? error.message.slice(0, 1000)
+        : "health_check_failed";
+
+    await supabase
+      .from("plesk_instances")
+      .update({
+        health_status: "down",
+        health_last_checked_at: nowIso,
+        health_last_error: errorMessage,
+        health_next_check_at: nextCheckAtIso,
+      })
+      .eq("id", instance.id);
+
+    await insertActionLogBestEffort(supabase, {
+      agency_id: instance.agency_id,
+      actor_user_id: actorUserId,
+      target_type: "plesk_instance",
+      target_id: instance.id,
+      action: "health_check_failed",
+      status: "failed",
+      error_message: errorMessage,
+      metadata: {
+        instance_id: instance.id,
+        lock_token: lockToken,
+        source,
+        duration_ms: Date.now() - startedAt,
+      },
+    });
+
+    return {
+      checked: true,
+      status: "down",
+      latency_ms: Date.now() - startedAt,
+      error_message: errorMessage,
+    };
+  } finally {
+    await supabase.rpc("release_instance_health_lock", {
+      p_instance_id: instance.id,
+      p_lock_token: lockToken,
+    });
+  }
+}
+
+export async function runHealthCheckTick(
+  supabase: SupabaseLike,
+): Promise<HealthTickSummary> {
+  const startedAt = Date.now();
+  const now = Date.now();
+
+  const { data: rows, error } = await supabase
+    .from("plesk_instances")
+    .select(
+      "id, agency_id, base_url, auth_type, encrypted_secret, health_enabled, health_check_frequency_minutes, health_next_check_at, health_lock_until",
+    )
+    .eq("health_enabled", true)
+    .order("health_next_check_at", { ascending: true, nullsFirst: true })
+    .limit(50);
+
+  if (error) {
+    throw new Error(error.message);
+  }
+
+  const eligible = ((rows ?? []) as HealthInstance[])
+    .filter((instance) => isDue(instance, now) && isUnlocked(instance, now))
+    .slice(0, MAX_INSTANCES_PER_TICK);
+
+  let checked = 0;
+  let ok = 0;
+  let degraded = 0;
+  let failed = 0;
+
+  const queue = [...eligible];
+
+  const workers = Array.from(
+    { length: Math.min(MAX_CONCURRENCY, queue.length) },
+    async () => {
+      while (queue.length > 0) {
+        const instance = queue.shift();
+        if (!instance) break;
+
+        const result = await runInstanceHealthCheck(supabase, instance, {
+          actorUserId: null,
+          force: false,
+          source: "cron",
+        });
+
+        if (!result.checked || !result.status) continue;
+
+        checked += 1;
+        if (result.status === "ok") ok += 1;
+        else if (result.status === "degraded") degraded += 1;
+        else failed += 1;
+      }
+    },
+  );
+
+  await Promise.all(workers);
+
+  return {
+    checked,
+    ok,
+    degraded,
+    failed,
+    duration_ms: Date.now() - startedAt,
+  };
+}

lib/types.ts

@@ -89,6 +89,16 @@ export type Database = {
           next_auto_sync_at: string | null;
           auto_sync_lock_until: string | null;
           auto_sync_lock_token: string | null;
+          health_enabled: boolean;
+          health_status: "ok" | "degraded" | "down" | "unknown";
+          health_last_checked_at: string | null;
+          health_last_ok_at: string | null;
+          health_last_error: string | null;
+          health_last_latency_ms: number | null;
+          health_check_frequency_minutes: number;
+          health_next_check_at: string | null;
+          health_lock_until: string | null;
+          health_lock_token: string | null;
           created_at: string;
         };
         Insert: {
@@ -113,6 +123,16 @@ export type Database = {
           next_auto_sync_at?: string | null;
           auto_sync_lock_until?: string | null;
           auto_sync_lock_token?: string | null;
+          health_enabled?: boolean;
+          health_status?: "ok" | "degraded" | "down" | "unknown";
+          health_last_checked_at?: string | null;
+          health_last_ok_at?: string | null;
+          health_last_error?: string | null;
+          health_last_latency_ms?: number | null;
+          health_check_frequency_minutes?: number;
+          health_next_check_at?: string | null;
+          health_lock_until?: string | null;
+          health_lock_token?: string | null;
           created_at?: string;
         };
         Update: {
@@ -137,6 +157,16 @@ export type Database = {
           next_auto_sync_at?: string | null;
           auto_sync_lock_until?: string | null;
           auto_sync_lock_token?: string | null;
+          health_enabled?: boolean;
+          health_status?: "ok" | "degraded" | "down" | "unknown";
+          health_last_checked_at?: string | null;
+          health_last_ok_at?: string | null;
+          health_last_error?: string | null;
+          health_last_latency_ms?: number | null;
+          health_check_frequency_minutes?: number;
+          health_next_check_at?: string | null;
+          health_lock_until?: string | null;
+          health_lock_token?: string | null;
           created_at?: string;
         };
       };

supabase/migrations/CL38_instance_health_monitoring.sql

@@ -0,0 +1,78 @@
+-- CL8: instance health monitoring fields + lock helpers
+
+alter table public.plesk_instances
+  add column if not exists health_enabled boolean not null default true,
+  add column if not exists health_status text not null default 'unknown',
+  add column if not exists health_last_checked_at timestamptz,
+  add column if not exists health_last_ok_at timestamptz,
+  add column if not exists health_last_error text,
+  add column if not exists health_last_latency_ms integer,
+  add column if not exists health_check_frequency_minutes integer not null default 30,
+  add column if not exists health_next_check_at timestamptz,
+  add column if not exists health_lock_until timestamptz,
+  add column if not exists health_lock_token text;
+
+alter table public.plesk_instances
+  drop constraint if exists plesk_instances_health_status_check;
+
+alter table public.plesk_instances
+  add constraint plesk_instances_health_status_check
+  check (health_status in ('ok', 'degraded', 'down', 'unknown'));
+
+alter table public.plesk_instances
+  drop constraint if exists plesk_instances_health_check_frequency_minutes_check;
+
+alter table public.plesk_instances
+  add constraint plesk_instances_health_check_frequency_minutes_check
+  check (health_check_frequency_minutes between 5 and 10080);
+
+create index if not exists idx_plesk_instances_health_due
+  on public.plesk_instances (health_enabled, health_next_check_at);
+
+create or replace function public.acquire_instance_health_lock(
+  p_instance_id uuid,
+  p_lock_token text,
+  p_ttl_seconds integer default 300,
+  p_force boolean default false
+)
+returns boolean
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+  v_acquired boolean := false;
+begin
+  update public.plesk_instances
+  set
+    health_lock_until = now() + make_interval(secs => p_ttl_seconds),
+    health_lock_token = p_lock_token
+  where id = p_instance_id
+    and health_enabled = true
+    and (
+      p_force = true
+      or health_next_check_at is null
+      or health_next_check_at <= now()
+    )
+    and (health_lock_until is null or health_lock_until < now());
+
+  get diagnostics v_acquired = row_count;
+  return v_acquired;
+end;
+$$;
+
+create or replace function public.release_instance_health_lock(
+  p_instance_id uuid,
+  p_lock_token text
+)
+returns void
+language sql
+security definer
+set search_path = public
+as $$
+  update public.plesk_instances
+  set health_lock_until = null,
+      health_lock_token = null
+  where id = p_instance_id
+    and health_lock_token = p_lock_token;
+$$;