@skyhook-io/k8s-ui 1.18.1 → 1.19.0

package/src/components/gitops/GitOpsTableView.tsx

@@ -41,6 +41,7 @@ import { toggleSet } from './GitOpsGraphFilterRail'
 import { useFilterState, defineFilterSchema } from '../../filter-state'
 import { parseContextName } from '../../utils/context-name'
 import { formatCompactAge, formatRelativeAgeTime } from '../../utils/format'
+import { FilterRailPanel } from '../shared/FilterRailPanel'
 
 // =============================================================================
 // GitOpsTableView — the canonical GitOps fleet list (Argo + Flux).
@@ -937,13 +938,17 @@ function GitOpsFilterSidebar({
         side === 'right' ? 'border-l max-[899px]:border-l-0' : 'border-r max-[899px]:border-r-0'
       }`}
     >
-      <div className="flex items-center justify-between border-b border-theme-border px-3 py-2">
-        <span className="text-sm font-medium text-theme-text-secondary">Filters</span>
-        <button type="button" onClick={onClear} className="text-[10px] font-medium text-blue-500 hover:text-blue-400">
-          Clear
-        </button>
-      </div>
-      <div className="flex-1 overflow-y-auto">
+      <FilterRailPanel
+        activeCount={
+          syncFilters.size + healthFilters.size + automationFilters.size + kindFilters.size +
+          projectFilters.size + namespaceFilters.size + (lifecycleFilter === 'all' ? 0 : 1)
+        }
+        clear={
+          <button type="button" onClick={onClear} className="text-[10px] font-medium text-blue-500 hover:text-blue-400">
+            Clear
+          </button>
+        }
+      >
         {loading ? (
           <BoardRailSkeleton
             sections={[
@@ -1062,7 +1067,7 @@ function GitOpsFilterSidebar({
         </GitOpsFilterSection>
           </>
         )}
-      </div>
+      </FilterRailPanel>
     </aside>
   )
 }

package/src/components/gitops/insights/ArgoResourceDiff.test.tsx

@@ -113,6 +113,38 @@ describe('GitOpsChangesView expanded Argo row', () => {
     expect(html).not.toContain('Sync the application to create it')
   })
 
+  test.each([
+    ['ManualDrift', 'The render includes none of the resources this Application manages.', 'Manual'],
+    ['AutoSyncBlockedEmpty', 'A pruning sync could delete every listed resource.', 'Auto · prune'],
+    ['SharedResourceWarning', 'Resolve shared ownership before syncing.', 'Manual'],
+    ['SelfHealDisabled', 'Resolve shared ownership before syncing.', 'Auto'],
+    ['Failed', 'Fix the comparison error and refresh before syncing.', 'Manual'],
+  ])('defers resource sync/create advice to the %s hazard', (reason, hazard, autoSyncMode) => {
+    const data = insight(false)
+    data.summary.autoSyncMode = autoSyncMode
+    data.issues = [{ severity: 'warning', scope: 'operation', reason, message: 'Sync warning', hazard }]
+    data.changes = [
+      { ...change, drift: undefined },
+      { ...change, ref: { ...change.ref, name: 'missing' }, missing: true, hasLive: false, health: 'Missing', drift: undefined },
+      { ...change, ref: { ...change.ref, name: 'health-missing' }, sync: 'Unknown', health: 'Missing', drift: undefined },
+    ]
+    const html = renderToStaticMarkup(<GitOpsChangesView insight={data} />)
+    expect(count(html, 'See the sync warning above before syncing this Application.')).toBe(3)
+    expect(html).not.toContain('Click Sync')
+    expect(html).not.toContain('click Sync to force it')
+    expect(html).not.toContain('Auto-sync should reconcile')
+    expect(html).not.toContain('Sync the application to create it')
+    expect(html).not.toContain('Sync to create it')
+  })
+
+  test('keeps ordinary sync advice when there is no hazard', () => {
+    const data = insight(false)
+    data.summary.autoSyncMode = 'Manual'
+    const html = renderToStaticMarkup(<GitOpsChangesView insight={data} />)
+    expect(html).toContain('Click Sync to apply the desired state.')
+    expect(html).not.toContain('See the sync warning above')
+  })
+
   test("hands the last-applied list to the Argo diff instead of rendering it alongside", () => {
     let passed: GitOpsDrift | undefined
     const html = renderToStaticMarkup(

package/src/components/gitops/insights/GitOpsInsightViews.tsx

@@ -1,4 +1,5 @@
 import { AlertTriangle, ArrowUpDown, ChevronDown, ChevronRight, ChevronUp, CircleAlert, Clock3, GitBranch, GitCommit, Info, Loader2, Plus, RefreshCw, Trash2 } from 'lucide-react'
+import { IssueGuidance } from '../../issues/IssueGuidance'
 import { PaneLoader } from '../../ui/PaneLoader'
 import { clsx } from 'clsx'
 import { Fragment, useEffect, useRef, useState, type ReactNode } from 'react'
@@ -359,7 +360,7 @@ export function GitOpsIssuesBand({
         <GitOpsHistoricalIssuesDisclosure operationFailure={operationFailure} others={others} onSelectIssue={onSelectIssue} onRemediate={onRemediate} remediationPending={remediationPending} />
       ) : (
         <>
-          {operationFailure && <GitOpsFailureCard issue={operationFailure} onSelect={onSelectIssue} onRemediate={onRemediate} remediationPending={remediationPending} />}
+          {operationFailure && <GitOpsFailureCard issue={operationFailure} emptyRenderGuardShown={others[0]?.reason === 'AutoSyncBlockedEmpty'} onSelect={onSelectIssue} onRemediate={onRemediate} remediationPending={remediationPending} />}
           {others.length > 0 && <GitOpsCompactIssueStack issues={others} onSelectIssue={onSelectIssue} />}
         </>
       )}
@@ -383,7 +384,7 @@ function GitOpsLifecycleBanner({ issue }: { issue: GitOpsIssue }) {
           </div>
           <p className="mt-1 text-[13px] text-theme-text-secondary">{issue.message}</p>
           {issue.cause && <p className="mt-1 text-[12px] text-orange-300/90">{issue.cause}</p>}
-          {issue.action && <p className="mt-1 text-[11px] text-theme-text-tertiary">{issue.action}</p>}
+          <IssueNextStep issue={issue} className="mt-1" />
         </div>
       </div>
     </div>
@@ -431,7 +432,7 @@ function GitOpsHistoricalIssuesDisclosure({
       </button>
       <Collapse open={expanded}>
         <div className="border-t border-theme-border">
-          {operationFailure && <GitOpsFailureCard issue={operationFailure} onSelect={onSelectIssue} onRemediate={onRemediate} remediationPending={remediationPending} />}
+          {operationFailure && <GitOpsFailureCard issue={operationFailure} emptyRenderGuardShown={others[0]?.reason === 'AutoSyncBlockedEmpty'} onSelect={onSelectIssue} onRemediate={onRemediate} remediationPending={remediationPending} />}
           {others.length > 0 && <GitOpsCompactIssueStack issues={others} onSelectIssue={onSelectIssue} />}
         </div>
       </Collapse>
@@ -440,15 +441,18 @@ function GitOpsHistoricalIssuesDisclosure({
 }
 
 // Structured failure card. One unit, owns the failure narrative end-to-end:
-// title (parsed cause when recognized, falls back to raw reason), affected
-// resource, retry posture, raw controller error in a collapsed details.
+// title (parsed cause when recognized, falls back to raw reason), sync
+// hazard, cause, next step, affected resource, retry posture, raw controller
+// error in a collapsed details.
 function GitOpsFailureCard({
   issue,
+  emptyRenderGuardShown,
   onSelect,
   onRemediate,
   remediationPending,
 }: {
   issue: GitOpsIssue
+  emptyRenderGuardShown: boolean
   onSelect?: (issue: GitOpsIssue) => void
   // onRemediate fires when the contextual fix button is clicked. The host
   // app (web/) dispatches on issue.remediation.kind to run the right
@@ -492,7 +496,16 @@ function GitOpsFailureCard({
               <span className="text-[11px] text-theme-text-tertiary">retried {issue.retryCount}×</span>
             )}
           </div>
+          {/* Ahead of the body: a cause can end in its own sync advice
+              ("so Argo creates it on sync"), which the hazard overrides. */}
+          {issue.hazard && (
+            <div className={clsx('mt-2 flex items-start gap-1.5 rounded border px-2 py-1.5 text-[12px] font-medium', SEVERITY_BADGE.warning)}>
+              <AlertTriangle className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+              <p className="min-w-0">{emptyRenderGuardShown ? 'See the empty-render guard below before syncing.' : issue.hazard}</p>
+            </div>
+          )}
           {body && <p className="mt-1 text-[13px] text-theme-text-secondary">{body}</p>}
+          <IssueNextStep issue={issue} className="mt-1" />
           {ref && (
             <dl className="mt-2 flex flex-wrap gap-x-5 gap-y-1 text-[12px]">
               <div className="flex gap-1.5">
@@ -637,10 +650,13 @@ function GitOpsCompactIssueStack({ issues, onSelectIssue }: { issues: GitOpsIssu
           )}
           {canExpand && <CollapseChevron open={expanded} className="h-3.5 w-3.5" />}
         </div>
-        {headline.cause && (
-          <p className="truncate pl-[22px] text-[11px] text-theme-text-tertiary">{headline.cause}</p>
-        )}
       </button>
+      {(headline.cause || headline.action) && (
+        <div className="px-4 pb-2 pl-[38px]">
+          {headline.cause && <p className="text-[11px] text-theme-text-tertiary">{headline.cause}</p>}
+          <IssueNextStep issue={headline} />
+        </div>
+      )}
       {canExpand && (
         <Collapse open={expanded}>
         <div className="divide-y divide-theme-border border-t border-theme-border bg-theme-base/40">
@@ -650,33 +666,34 @@ function GitOpsCompactIssueStack({ issues, onSelectIssue }: { issues: GitOpsIssu
             const actionable = !!(onSelectIssue && ref)
             const rawMessage = issue.rawMessage && issue.rawMessage !== issue.message ? issue.rawMessage : ''
             return (
-              <button
-                key={`${issue.reason}-${index}`}
-                type="button"
-                onClick={() => actionable && onSelectIssue?.(issue)}
-                disabled={!actionable}
-                className={clsx(
-                  'group flex w-full items-start gap-2 px-4 py-2 text-left text-xs transition-colors',
-                  actionable ? 'hover:bg-theme-hover/50' : 'cursor-default',
-                )}
-              >
-                {t.icon}
-                <div className="min-w-0 flex-1">
-                  <div className="flex items-center gap-2">
-                    <span className={clsx('font-semibold', t.text)}>{issue.reason}</span>
-                    <span className="text-[10px] uppercase tracking-wide text-theme-text-tertiary">{issue.scope}</span>
+              <div key={`${issue.reason}-${index}`}>
+                <button
+                  type="button"
+                  onClick={() => actionable && onSelectIssue?.(issue)}
+                  disabled={!actionable}
+                  className={clsx(
+                    'group flex w-full items-start gap-2 px-4 py-2 text-left text-xs transition-colors',
+                    actionable ? 'hover:bg-theme-hover/50' : 'cursor-default',
+                  )}
+                >
+                  {t.icon}
+                  <div className="min-w-0 flex-1">
+                    <div className="flex items-center gap-2">
+                      <span className={clsx('font-semibold', t.text)}>{issue.reason}</span>
+                      <span className="text-[10px] uppercase tracking-wide text-theme-text-tertiary">{issue.scope}</span>
+                    </div>
+                    <p className="mt-0.5 text-theme-text-secondary">{issue.message}</p>
+                    {issue.cause && <p className="mt-0.5 text-[11px] text-theme-text-tertiary">{issue.cause}</p>}
+                    {rawMessage && <p className="mt-0.5 break-words font-mono text-[11px] text-theme-text-tertiary">{rawMessage}</p>}
                   </div>
-                  <p className="mt-0.5 text-theme-text-secondary">{issue.message}</p>
-                  {issue.cause && <p className="mt-0.5 text-[11px] text-theme-text-tertiary">{issue.cause}</p>}
-                  {rawMessage && <p className="mt-0.5 break-words font-mono text-[11px] text-theme-text-tertiary">{rawMessage}</p>}
-                  {issue.action && <p className="mt-0.5 text-[11px] text-theme-text-tertiary">{issue.action}</p>}
-                </div>
-                {actionable && ref && (
-                  <span className="shrink-0 self-center text-[11px] font-medium text-theme-text-secondary opacity-70 transition-opacity group-hover:opacity-100">
-                    Open {refText(ref)} →
-                  </span>
-                )}
-              </button>
+                  {actionable && ref && (
+                    <span className="shrink-0 self-center text-[11px] font-medium text-theme-text-secondary opacity-70 transition-opacity group-hover:opacity-100">
+                      Open {refText(ref)} →
+                    </span>
+                  )}
+                </button>
+                <IssueNextStep issue={issue} className="px-4 pb-2 pl-[38px]" />
+              </div>
             )
           })}
         </div>
@@ -686,6 +703,13 @@ function GitOpsCompactIssueStack({ issues, onSelectIssue }: { issues: GitOpsIssu
   )
 }
 
+// IssueNextStep is an issue's next step, styled alike on every surface of the
+// band. Wrapped, never truncated: a next step often ends in the caveat that
+// makes it safe (what not to sync), which truncation would cut.
+function IssueNextStep({ issue, className }: { issue: GitOpsIssue; className?: string }) {
+  return <IssueGuidance action={issue.action} primary={issue.actionPrimary} secondaryTitle={issue.actionSecondaryTitle} secondary={issue.actionSecondary} ordered={issue.reason === 'SharedResourceWarning'} className={clsx('text-[11px] text-theme-text-tertiary', className)} />
+}
+
 // firstSentence/remainderAfterFirstSentence split a string at the first
 // sentence boundary so the failure card can render "headline + body" from a
 // single source string. Falls back to the whole string when there's no
@@ -865,6 +889,7 @@ export function GitOpsChangesView({ insight, error, onOpenResource, onSyncResour
   // honest about what it's NOT checking. Neutral note, not an alarm.
   const ignoredDiffs = insight.summary.ignoredDifferences
   const isArgoRoot = insight.summary.tool === 'argocd' && insight.summary.kind === 'Application'
+  const syncHazard = insight.issues?.find((issue) => issue.hazard)?.hazard
   // Full-diff affordance is offered only when the backend reports the Argo CD
   // integration is connected for this app AND the host wired the loader.
   const argoDiffAvailable = isArgoRoot && !!insight.capabilities?.argoDiffAvailable && !!renderResourceDiff
@@ -1098,9 +1123,9 @@ export function GitOpsChangesView({ insight, error, onOpenResource, onSyncResour
                 const rowKey = refKey(change.ref)
                 const focused = focusKey === rowKey
                 const explanation = change.missing
-                  ? missingResourceMessage(change.sync)
+                  ? missingResourceMessage(change.sync, { hazard: syncHazard })
                   : !change.syncError && !change.message
-                    ? explainChangeStatus(change.sync, change.health, insight.summary)
+                    ? explainChangeStatus(change.sync, change.health, insight.summary, { hazard: syncHazard })
                     : ''
                 const hasInlineDetail = !!(
                   (change.drift && change.drift.entries.length > 0) ||
@@ -1275,7 +1300,12 @@ function explainChangeStatus(
   sync: string | undefined,
   health: string | undefined,
   summary: GitOpsInsight['summary'],
+  context?: { hazard?: string; rolledBack?: boolean },
 ): string {
+  if (context?.hazard && (sync === 'OutOfSync' || health === 'Missing')) {
+    return 'See the sync warning above before syncing this Application.'
+  }
+  if (context?.rolledBack && health === 'Missing') return missingResourceMessage(sync, context)
   const isAuto = (summary.autoSyncMode ?? '').toLowerCase().startsWith('auto')
   const phase = (summary.operationPhase ?? '').toLowerCase()
   const inFlight = phase === 'running'

package/src/components/gitops/insights/GitOpsIssuesBand.test.tsx

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest'
+import { renderToString } from 'react-dom/server'
+import { GitOpsIssuesBand } from './GitOpsInsightViews'
+import type { GitOpsIssue } from '../../../types/gitops-insights'
+import { SEVERITY_BADGE } from '../../../utils/badge-colors'
+
+const guard: GitOpsIssue = {
+  severity: 'critical',
+  scope: 'condition',
+  reason: 'AutoSyncBlockedEmpty',
+  message: 'Auto-sync blocked: the render includes none of the managed resources',
+  rawMessage: 'Skipping sync attempt to [8088f4c]: auto-sync will wipe out all resources',
+  cause: 'Argo CD blocked auto-sync because the render includes none of the resources this Application manages.',
+  action: 'The render includes none of the resources this Application manages. A sync with Prune enabled could delete all of them. Prune=false blocks direct Argo pruning; Prune=confirm requires confirmation. Pruning a rendered Namespace deletes its contents, regardless of their Prune options.',
+}
+
+// The band's top row is the most severe issue. Its next step must be visible
+// without expanding, or a lower row's "click Sync" is the only advice on screen.
+describe('GitOpsIssuesBand headline', () => {
+  it('shows the top issue’s next step when it stands alone', () => {
+    const html = renderToString(<GitOpsIssuesBand issues={[guard]} />)
+    expect(html).toContain(guard.action)
+  })
+
+  it('shows the top issue’s next step above a collapsed stack', () => {
+    const drift: GitOpsIssue = {
+      severity: 'warning',
+      scope: 'operation',
+      reason: 'OutOfSync',
+      message: 'Application is OutOfSync.',
+      action: 'Review the drift.',
+    }
+    const html = renderToString(<GitOpsIssuesBand issues={[guard, drift]} />)
+    expect(html).toContain(guard.action)
+    expect(html.indexOf(guard.action!)).toBeLessThan(html.indexOf(drift.action!))
+  })
+
+  it('renders no next-step line when the top issue has none', () => {
+    const html = renderToString(
+      <GitOpsIssuesBand issues={[{ severity: 'warning', scope: 'condition', reason: 'X', message: 'only a message' }]} />,
+    )
+    expect(html).toContain('only a message')
+    expect(html.match(/pl-\[22px\]/g)).toBeNull()
+  })
+})
+
+// Argo's namespace-not-found cause ends in its own sync advice.
+const failedSync: GitOpsIssue = {
+  severity: 'critical',
+  scope: 'operation',
+  reason: 'Failed',
+  message: 'one or more objects failed to apply, reason: namespaces demo not found',
+  cause: 'The destination namespace does not exist. Create it, or enable CreateNamespace=true in the syncOptions so Argo creates it on sync.',
+  action: 'Open Activity for operation details.',
+}
+const causeAdvice = 'so Argo creates it on sync'
+const emptyRenderHazard = 'The render includes none of the resources this Application manages. A sync with Prune enabled could delete all of them. Prune=false blocks direct Argo pruning; Prune=confirm requires confirmation. Pruning a rendered Namespace deletes its contents, regardless of their Prune options. Check the source path, targetRevision, Helm values, and Kustomize or directory include/exclude settings first.'
+const emptyRenderReference = 'See the empty-render guard below before syncing.'
+
+describe('GitOpsIssuesBand failure card', () => {
+  it('shows the failure’s next step after its cause', () => {
+    const html = renderToString(<GitOpsIssuesBand issues={[failedSync]} />)
+    expect(html).toContain(failedSync.action)
+    expect(html.indexOf(causeAdvice)).toBeLessThan(html.indexOf(failedSync.action!))
+    expect(html).not.toContain(SEVERITY_BADGE.warning)
+  })
+
+  it('warns of a sync hazard before the cause’s own sync advice', () => {
+    const hazard = emptyRenderHazard
+    const html = renderToString(<GitOpsIssuesBand issues={[{ ...failedSync, hazard }]} />)
+    const at = html.indexOf(hazard)
+    expect(at).toBeGreaterThan(-1)
+    expect(at).toBeLessThan(html.indexOf(causeAdvice))
+    expect(html.lastIndexOf(SEVERITY_BADGE.warning, at)).toBeGreaterThan(-1)
+    expect(html).toContain(failedSync.action)
+    expect(html).not.toContain(emptyRenderReference)
+  })
+
+  it.each([false, true])('points to the empty-render guard in the issue band (terminating=%s)', (terminating) => {
+    const html = renderToString(<GitOpsIssuesBand issues={[{ ...failedSync, hazard: emptyRenderHazard }, guard]} terminating={terminating} />)
+    expect(html).toContain(emptyRenderReference)
+    expect(html).not.toContain(emptyRenderHazard)
+    expect(html).toContain(guard.message)
+    expect(html).toContain(guard.action)
+    expect(html.indexOf(emptyRenderReference)).toBeLessThan(html.indexOf(causeAdvice))
+  })
+
+  it('keeps the full hazard when the guard is behind a collapsed row', () => {
+    const comparisonError: GitOpsIssue = { severity: 'critical', scope: 'condition', reason: 'ComparisonError', message: 'Cannot render source.' }
+    const html = renderToString(<GitOpsIssuesBand issues={[{ ...failedSync, hazard: emptyRenderHazard }, comparisonError, guard]} />)
+    expect(html).toContain(emptyRenderHazard)
+    expect(html).not.toContain(emptyRenderReference)
+  })
+
+  it('keeps shared-ownership hazards unchanged', () => {
+    const hazard = 'Resolve shared ownership before syncing: some resources are also tracked by Application payments. A successful sync can take over their tracking unless it uses FailOnSharedResource=true. While Application payments still declares them, its next successful sync can take tracking back.'
+    const shared: GitOpsIssue = { severity: 'warning', scope: 'condition', reason: 'SharedResourceWarning', message: 'Shared resource' }
+    const html = renderToString(<GitOpsIssuesBand issues={[{ ...failedSync, hazard }, shared]} />)
+    expect(html).toContain(hazard)
+    expect(html).not.toContain(emptyRenderReference)
+  })
+
+  it('shows a remote failure’s destination-cluster instruction', () => {
+    const action = 'Create namespace demo on the destination cluster, or add the CreateNamespace=true sync option.'
+    const html = renderToString(<GitOpsIssuesBand issues={[{ ...failedSync, action }]} />)
+    expect(html).toContain(action)
+  })
+})

package/src/components/gitops/insights/insights-helpers.test.ts

@@ -30,6 +30,34 @@ describe('confirmed missing resources', () => {
     expect(isArgoResourceSyncEligible(item, true)).toBe(true)
   })
 
+  it('defers creation advice to the sync hazard while preserving stale Synced refresh advice', () => {
+    for (const sync of ['OutOfSync', 'Unknown', undefined]) {
+      expect(missingResourceMessage(sync, { hazard: 'Resolve shared ownership before syncing.' })).toBe(
+        'Not present in the cluster. See the sync warning above before syncing this Application.',
+      )
+    }
+    expect(missingResourceMessage('Synced', { hazard: 'A pruning sync could delete everything.' })).toContain('Refresh')
+  })
+
+  it('warns that recreating a missing resource can undo a rollback', () => {
+    for (const sync of ['OutOfSync', 'Unknown', undefined]) {
+      expect(missingResourceMessage(sync, { rolledBack: true })).toBe(
+        'Declared in Git but not present in the cluster after a rollback. Sync can recreate it and undo the rollback.',
+      )
+    }
+  })
+
+  it('prioritizes the sync hazard over rollback advice', () => {
+    for (const sync of ['OutOfSync', 'Unknown', undefined]) {
+      expect(missingResourceMessage(sync, { hazard: 'Resolve shared tracking.', rolledBack: true })).toBe(
+        'Not present in the cluster. See the sync warning above before syncing this Application.',
+      )
+    }
+    // Argo calling it Synced means the cluster view is stale: refresh, whatever the context.
+    expect(missingResourceMessage('Synced', { hazard: 'Resolve shared tracking.', rolledBack: true })).toContain('Refresh the application')
+    expect(missingResourceMessage('OutOfSync', {})).toContain('Sync the application')
+  })
+
   it('asks for a refresh when Argo still reports Synced', () => {
     expect(missingResourceMessage('Synced')).toContain('Refresh')
     expect(missingResourceMessage('Synced')).not.toContain('Sync the application')

package/src/components/gitops/insights/insights-helpers.ts

@@ -47,9 +47,11 @@ export function changeHealth(change: GitOpsChange): GitOpsHealthStatus {
   return normalizeHealthStatus(change.health)
 }
 
-export function missingResourceMessage(sync?: string): string {
-  return sync === 'Synced'
-    ? 'Argo reports this resource as synced, but it is not present in the cluster. Refresh the application to check its status.'
+export function missingResourceMessage(sync?: string, context?: { hazard?: string; rolledBack?: boolean }): string {
+  if (sync === 'Synced') return 'Argo reports this resource as synced, but it is not present in the cluster. Refresh the application to check its status.'
+  if (context?.hazard) return 'Not present in the cluster. See the sync warning above before syncing this Application.'
+  return context?.rolledBack
+    ? 'Declared in Git but not present in the cluster after a rollback. Sync can recreate it and undo the rollback.'
     : 'Not present in the cluster. Sync the application to create it.'
 }
 

package/src/components/issues/IssueGuidance.test.tsx

@@ -0,0 +1,190 @@
+// @vitest-environment jsdom
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { GitOpsIssuesBand } from '../gitops/insights/GitOpsInsightViews'
+import { IssueRow } from './IssuesView'
+import { ResourceIssuesSection } from './ResourceIssuesSection'
+import type { GitOpsIssue } from '../../types/gitops-insights'
+import type { Issue } from './types'
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true })
+
+const primary = 'The render includes none of the resources this Application manages. A sync with Prune enabled could delete all of them. Prune=false blocks direct Argo pruning; Prune=confirm requires confirmation. Pruning a rendered Namespace deletes its contents, regardless of their Prune options. Check the source path, targetRevision, Helm values, and Kustomize or directory include/exclude settings first.'
+const secondary = [
+  'If this Application should go away: remove it from the ApplicationSet generator if generated; while the generator still emits it, the ApplicationSet recreates it. Check whether the generated Application survives; its ApplicationSet sync policy may keep it. If it survives, delete it explicitly with the intended cascade choice. For a plain Application, delete the Application. Cleanup follows the cascade/resources finalizer choice and Delete=false / Delete=confirm, not Prune options.',
+  'If it should render empty: set syncPolicy.automated.allowEmpty: true in the Application or its ApplicationSet template. This turns off the empty-render guard for all future syncs.',
+]
+const title = 'If removing all managed resources is intended'
+const cause = 'Argo CD blocked auto-sync because the render includes none of the resources this Application manages.'
+const guard: GitOpsIssue = {
+  severity: 'critical', scope: 'condition', reason: 'AutoSyncBlockedEmpty',
+  message: 'Auto-sync blocked: the render includes none of the managed resources', cause,
+  action: [primary, ...secondary].join(' '), actionPrimary: primary,
+  actionSecondaryTitle: title, actionSecondary: secondary,
+}
+const issue: Issue = {
+  id: 'guard', severity: 'critical', source: 'problem',
+  category: 'gitops_sync_failed', category_group: 'gitops', grouping_scope: 'unknown',
+  kind: 'Application', group: 'argoproj.io', namespace: 'argocd', name: 'empty',
+  reason: guard.reason, message: guard.message, cause,
+  action: guard.action, action_primary: primary,
+  action_secondary_title: title, action_secondary: secondary,
+}
+
+let root: Root
+let element: HTMLDivElement
+beforeEach(() => {
+  element = document.createElement('div')
+  document.body.appendChild(element)
+  root = createRoot(element)
+})
+afterEach(async () => {
+  await act(async () => root.unmount())
+  element.remove()
+})
+
+function disclosure() {
+  const button = [...element.querySelectorAll('button')].find((b) => b.textContent?.includes(title))!
+  expect(button).toBeDefined()
+  return { button, panel: document.getElementById(button.getAttribute('aria-controls')!)! }
+}
+
+function checkPrimaryVisible() {
+  for (const text of [primary, cause]) {
+    const paragraph = [...element.querySelectorAll('p')].find((p) => p.textContent === text)!
+    expect(paragraph).toBeDefined()
+    expect(paragraph.closest('[inert]')).toBeNull()
+  }
+  expect(element.querySelector('button button')).toBeNull()
+}
+
+async function checkDisclosure() {
+  const { button, panel } = disclosure()
+  expect(button.getAttribute('aria-expanded')).toBe('false')
+  expect(panel.style.gridTemplateRows).toBe('0fr')
+  expect(panel.querySelector('[inert]')).not.toBeNull()
+  checkPrimaryVisible()
+  await act(async () => button.click())
+  expect(button.getAttribute('aria-expanded')).toBe('true')
+  expect(panel.style.gridTemplateRows).toBe('1fr')
+  expect(panel.querySelector('[inert]')).toBeNull()
+  for (const paragraph of secondary) expect(panel.textContent).toContain(paragraph)
+  await act(async () => button.click())
+  expect(button.getAttribute('aria-expanded')).toBe('false')
+  expect(panel.querySelector('[inert]')).not.toBeNull()
+}
+
+describe('empty-render guidance', () => {
+  it('shows primary guidance on the detail band and opens both intended-render paths', async () => {
+    await act(async () => root.render(<GitOpsIssuesBand issues={[guard]} />))
+    await checkDisclosure()
+  })
+
+  it('keeps the headline guidance independent of the collapsed detail stack', async () => {
+    const drift: GitOpsIssue = { severity: 'warning', scope: 'condition', reason: 'OtherWarning', message: 'Another condition' }
+    await act(async () => root.render(<GitOpsIssuesBand issues={[guard, drift]} />))
+    await checkDisclosure()
+    const stack = [...element.querySelectorAll('button')].find((b) => b.textContent?.includes('AutoSyncBlockedEmpty'))!
+    expect(stack.getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('opens guidance on a lower detail row after expanding the stack', async () => {
+    const first: GitOpsIssue = { severity: 'critical', scope: 'condition', reason: 'ComparisonError', message: 'Cannot render' }
+    await act(async () => root.render(<GitOpsIssuesBand issues={[first, guard]} />))
+    const stack = [...element.querySelectorAll('button')].find((b) => b.textContent?.includes('ComparisonError'))!
+    await act(async () => stack.click())
+    await checkDisclosure()
+  })
+
+  it.each([false, true])('shows split guidance on the cluster Issues row (open=%s)', async (open) => {
+    await act(async () => root.render(<IssueRow issue={issue} open={open} onToggle={() => {}} />))
+    await checkDisclosure()
+  })
+
+  it('shows primary guidance and disclosure in the resource drawer without expanding its issue', async () => {
+    await act(async () => root.render(<ResourceIssuesSection issues={[issue]} />))
+    await checkDisclosure()
+  })
+
+  it('shows complete action when presentation fields are absent', async () => {
+    const { actionPrimary: _primary, actionSecondaryTitle: _title, actionSecondary: _secondary, ...plain } = guard
+    await act(async () => root.render(<GitOpsIssuesBand issues={[plain]} />))
+    expect(element.textContent).toContain(guard.action)
+    expect(element.querySelectorAll('button[aria-controls]')).toHaveLength(0)
+  })
+})
+
+const moveSteps = [
+  "Check this Application's sync options for FailOnSharedResource=true. If set, the sync will refuse the takeover. Stop unless taking it over is intended and allowed.",
+  "Note the resource's live UID.",
+  'Sync this Application.',
+]
+const movePrimary = "To leave it with Application payments, remove it from this Application's source."
+const moveTitle = 'To move it to this Application'
+const move: GitOpsIssue = {
+  severity: 'warning', scope: 'condition', reason: 'SharedResourceWarning', message: 'Also tracked by payments',
+  action: `${movePrimary} ${moveTitle}: ${moveSteps.join(' ')}`, actionPrimary: movePrimary,
+  actionSecondaryTitle: moveTitle, actionSecondary: moveSteps,
+}
+
+describe('shared-resource move guidance', () => {
+  it.each(['detail', 'cluster'] as const)('renders numbered steps on the %s surface', async (surface) => {
+    const row: Issue = { ...issue, reason: move.reason, message: move.message, action: move.action,
+      action_primary: movePrimary, action_secondary_title: moveTitle, action_secondary: moveSteps }
+    await act(async () => root.render(surface === 'detail'
+      ? <GitOpsIssuesBand issues={[move]} />
+      : <IssueRow issue={row} open={true} onToggle={() => {}} />))
+    const button = [...element.querySelectorAll('button')].find((b) => b.textContent?.includes(moveTitle))!
+    expect(button).toBeDefined()
+    await act(async () => button.click())
+    const panel = document.getElementById(button.getAttribute('aria-controls')!)!
+    expect([...panel.querySelectorAll('ol > li')].map((li) => li.textContent)).toEqual(moveSteps)
+    expect(panel.querySelector('[inert]')).toBeNull()
+    expect(element.textContent).toContain(movePrimary)
+  })
+})
+
+describe('cluster sync hazards', () => {
+  const hazard = 'Resolve shared ownership before syncing: another Application can take tracking back.'
+  it.each([undefined, { nextStep: 'Host next step', cause: 'Host cause' }])('keeps a warning ahead of any next-step source (%j)', async (diagnosisSource) => {
+    await act(async () => root.render(<IssueRow
+      issue={{ ...issue, action_primary: undefined, action_secondary: undefined, action_secondary_title: undefined, hazard }}
+      open={true} onToggle={() => {}} diagnosisSource={diagnosisSource} />))
+    const warning = [...element.querySelectorAll('p')].find((p) => p.textContent === hazard)!
+    expect(warning).toBeDefined()
+    expect(warning.closest('.text-warning-text')).not.toBeNull()
+    expect(warning.closest('[inert]')).toBeNull()
+    expect(element.textContent!.indexOf(hazard)).toBeLessThan(element.textContent!.indexOf(diagnosisSource?.nextStep ?? primary))
+    if (diagnosisSource) expect(element.textContent).toContain(diagnosisSource.nextStep)
+  })
+
+  it('shows a hazard on a collapsed row with no split guidance or action', async () => {
+    await act(async () => root.render(<IssueRow
+      issue={{ ...issue, action: undefined, action_primary: undefined, action_secondary: undefined, action_secondary_title: undefined, hazard }}
+      open={false} onToggle={() => {}} diagnosisSource={{ nextStep: 'Host next step' }} />))
+    const warning = [...element.querySelectorAll('p')].find((p) => p.textContent === hazard)!
+    expect(warning).toBeDefined()
+    expect(warning.closest('[inert]')).toBeNull()
+    expect(warning.closest('.text-warning-text')).not.toBeNull()
+  })
+})
+
+describe('hazard text retained only once in presentation', () => {
+  it.each([false, true])('keeps empty-render guidance and one warning (open=%s)', async (open) => {
+    await act(async () => root.render(<IssueRow issue={{ ...issue, hazard: primary }} open={open} onToggle={() => {}} />))
+    expect([...element.querySelectorAll('p')].filter((p) => p.textContent === primary)).toHaveLength(1)
+    await checkDisclosure()
+  })
+
+  it.each(['hazard only', 'appended hazard'])('keeps one warning for %s actions', async (mode) => {
+    const hazard = 'Sync can take over shared tracking.'
+    const nextStep = "Open the application's sync operation details."
+    const action = mode === 'hazard only' ? hazard : `${nextStep} ${hazard}`
+    await act(async () => root.render(<IssueRow issue={{ ...issue, hazard, action,
+      action_primary: undefined, action_secondary: undefined, action_secondary_title: undefined }} open={true} onToggle={() => {}} />))
+    expect(element.textContent!.split(hazard)).toHaveLength(2)
+    if (mode === 'hazard only') expect(element.textContent).not.toContain('Next step')
+    else expect(element.textContent).toContain(nextStep)
+  })
+})