@toolr/ui-design 0.1.0

package/components/sections/golden-snapshots/status-overview.tsx

@@ -0,0 +1,305 @@
+import { useState, useRef } from 'react'
+import { Archive, Check, AlertTriangle, RotateCcw } from 'lucide-react'
+import { useClickOutside } from '../../hooks/use-click-outside.ts'
+import { useDropdownMaxHeight } from '../../hooks/use-dropdown-max-height.ts'
+import { IconButton } from '../../ui/icon-button.tsx'
+import { Tooltip } from '../../ui/tooltip.tsx'
+import type { GoldenStatus, GoldenMeta, SnapshotsManifest } from './types.ts'
+import { formatDate, formatBytes } from './use-golden-sync.ts'
+
+export interface StatusOverviewProps {
+  status: GoldenStatus | null
+  components: string[]
+  componentLabels?: Record<string, string>
+  devtools: boolean
+  manifest?: SnapshotsManifest | null
+  resettingComponent: string | null
+  resettingAll: boolean
+  onResetComponent: (component: string) => void
+  onResetAll: () => void
+}
+
+function getComponentVersion(meta: GoldenMeta | undefined, component: string): string | undefined {
+  return meta?.components[component]?.version
+}
+
+function renderVersionBadge(meta: GoldenMeta | undefined, color: string) {
+  if (!meta) return null
+  return (
+    <span className={`px-2 py-0.5 ${color} text-xs rounded font-mono`}>
+      {meta.version}
+    </span>
+  )
+}
+
+function VersionStatus({ exists, version, mismatch, defaultColor = 'text-green-400/70' }: { exists: boolean; version?: string; mismatch: boolean; defaultColor?: string }) {
+  if (!exists) return <span className="text-red-400">Missing</span>
+  if (!version) return <span className="text-green-400">Found</span>
+  return <span className={`text-xs font-mono ${mismatch ? 'text-yellow-400' : defaultColor}`}>v{version}</span>
+}
+
+function SyncStatusBanner({ goldenMeta, liveMeta, components }: { goldenMeta: GoldenMeta; liveMeta: GoldenMeta; components: string[] }) {
+  const mismatches = components.filter((comp) => {
+    const gv = getComponentVersion(goldenMeta, comp)
+    const lv = getComponentVersion(liveMeta, comp)
+    return gv !== lv
+  }).length
+
+  return mismatches === 0 ? (
+    <div className="flex items-center gap-2 px-3 py-2 rounded-lg bg-green-500/5 border border-green-500/20">
+      <Check className="w-4 h-4 text-green-400" />
+      <span className="text-sm text-green-400">Golden and Live versions are in sync</span>
+    </div>
+  ) : (
+    <div className="flex items-center gap-2 px-3 py-2 rounded-lg bg-yellow-500/5 border border-yellow-500/20">
+      <AlertTriangle className="w-4 h-4 text-yellow-400" />
+      <span className="text-sm text-yellow-400">Version mismatch — {mismatches} component{mismatches > 1 ? 's' : ''} differ</span>
+    </div>
+  )
+}
+
+export function StatusOverview({
+  status,
+  components,
+  componentLabels,
+  devtools,
+  manifest,
+  resettingComponent,
+  resettingAll,
+  onResetComponent,
+  onResetAll,
+}: StatusOverviewProps) {
+  const anyResetting = resettingComponent !== null || resettingAll
+  const [showResetMenu, setShowResetMenu] = useState(false)
+  const resetMenuRef = useRef<HTMLDivElement>(null)
+  const resetMenuDropdownRef = useDropdownMaxHeight<HTMLDivElement>(showResetMenu)
+
+  useClickOutside(resetMenuRef, showResetMenu, () => setShowResetMenu(false))
+
+  const getLabel = (comp: string) => componentLabels?.[comp] ?? comp.charAt(0).toUpperCase() + comp.slice(1)
+
+  return (
+    <div className="space-y-4">
+      {/* Bundled Seed Info */}
+      <div className="bg-[#181825] rounded-lg p-4 border border-amber-500/30">
+        <div className="flex items-center gap-3 mb-3">
+          <Archive className="w-5 h-5 text-amber-400" />
+          <h3 className="text-[#cdd6f4] font-medium">Bundled Seed (App Distribution)</h3>
+          {status?.seed.meta && renderVersionBadge(status.seed.meta, 'bg-amber-500/20 text-amber-400')}
+        </div>
+        <div className="grid grid-cols-2 gap-4 text-sm">
+          <div>
+            <p className="text-[#6c7086]">Status</p>
+            <p className={status?.seed.exists ? 'text-green-400' : 'text-red-400'}>
+              {status?.seed.exists ? 'Found' : 'Missing'}
+            </p>
+          </div>
+          <div>
+            <p className="text-[#6c7086]">Size (compressed)</p>
+            <p className="text-[#cdd6f4]">{formatBytes(status?.seed.sizeBytes ?? 0)}</p>
+          </div>
+          <div>
+            <p className="text-[#6c7086]">Modified</p>
+            <p className="text-[#cdd6f4]">{status?.seed.modifiedAt ? formatDate(status.seed.modifiedAt) : 'N/A'}</p>
+          </div>
+        </div>
+        {!devtools && (
+          <p className="text-xs text-[#585b70] mt-3">
+            A compressed archive shipped with every release containing default configuration and templates. On first launch, the seed is extracted to initialize your local files.
+          </p>
+        )}
+      </div>
+
+      {/* Sync Status Banner */}
+      {status?.goldenMeta && status?.liveMeta && (
+        <SyncStatusBanner goldenMeta={status.goldenMeta} liveMeta={status.liveMeta} components={components} />
+      )}
+
+      {/* Local Directories */}
+      <div className="grid grid-cols-2 gap-4">
+        {/* Golden */}
+        <div className="bg-[#181825] rounded-lg p-4 border border-blue-500/30">
+          <div className="flex items-center gap-2 mb-3">
+            <div className="w-3 h-3 rounded-full bg-blue-400" />
+            <h4 className="text-[#cdd6f4] font-medium">Golden (Reference)</h4>
+            {renderVersionBadge(status?.goldenMeta, 'bg-blue-500/20 text-blue-400')}
+          </div>
+          <div className="space-y-2 text-sm">
+            {components.map((comp) => {
+              const version = getComponentVersion(status?.goldenMeta, comp)
+              const dirKey = `${comp}Golden`
+              const dirExists = status?.directories[dirKey]?.exists ?? false
+              return (
+                <div key={comp} className="flex justify-between items-center">
+                  <span className="text-[#6c7086]">{getLabel(comp)}</span>
+                  <VersionStatus
+                    exists={dirExists || !!version}
+                    version={version}
+                    mismatch={false}
+                    defaultColor="text-blue-400/70"
+                  />
+                </div>
+              )
+            })}
+          </div>
+          {!devtools && (
+            <p className="text-xs text-[#585b70] mt-3">
+              Reference copy extracted from the bundled seed. Always overwritten during app updates to match the latest release. Do not edit directly.
+            </p>
+          )}
+        </div>
+
+        {/* Live */}
+        <div className="bg-[#181825] rounded-lg p-4 border border-green-500/30">
+          <div className="flex items-center gap-2 mb-3">
+            <div className="w-3 h-3 rounded-full bg-green-400" />
+            <h4 className="text-[#cdd6f4] font-medium">Live (Working Copy)</h4>
+            {renderVersionBadge(status?.liveMeta, 'bg-green-500/20 text-green-400')}
+            <div className="ml-auto relative" ref={resetMenuRef}>
+              <IconButton
+                icon={<RotateCcw className={anyResetting ? 'animate-spin' : ''} />}
+                onClick={() => setShowResetMenu((prev) => !prev)}
+                disabled={anyResetting}
+                size="xs"
+                color="orange"
+                tooltip={{ title: 'Reset options', description: 'Reset live files to golden' }}
+              />
+              {showResetMenu && (
+                <div ref={resetMenuDropdownRef} className="absolute right-0 top-full mt-1 w-56 bg-[#1e1e2e] border border-[#313244] rounded-lg shadow-xl z-50 py-1 overflow-hidden">
+                  <button
+                    onClick={() => { onResetAll(); setShowResetMenu(false) }}
+                    className="w-full text-left px-3 py-2 text-sm text-[#cdd6f4] hover:bg-[#313244] transition-colors"
+                  >
+                    Reset All to Golden
+                  </button>
+                  <div className="border-t border-[#313244] my-1" />
+                  {components.map((comp) => (
+                    <button
+                      key={comp}
+                      onClick={() => { onResetComponent(comp); setShowResetMenu(false) }}
+                      className="w-full text-left px-3 py-2 text-sm text-[#a6adc8] hover:bg-[#313244] transition-colors"
+                    >
+                      Reset {getLabel(comp)}
+                    </button>
+                  ))}
+                </div>
+              )}
+            </div>
+          </div>
+          <div className="space-y-2 text-sm">
+            {components.map((comp) => {
+              const liveV = getComponentVersion(status?.liveMeta, comp)
+              const goldenV = getComponentVersion(status?.goldenMeta, comp)
+              const dirKey = `${comp}Live`
+              const dirExists = status?.directories[dirKey]?.exists ?? false
+              const mismatch = !!(goldenV && liveV && goldenV !== liveV)
+              return (
+                <div key={comp} className="flex justify-between items-center">
+                  <span className="text-[#6c7086]">{getLabel(comp)}</span>
+                  <span className="flex items-center gap-2">
+                    <VersionStatus exists={dirExists || !!liveV} version={liveV} mismatch={mismatch} />
+                    <IconButton
+                      icon={<RotateCcw className={resettingComponent === comp ? 'animate-spin' : ''} />}
+                      onClick={() => onResetComponent(comp)}
+                      disabled={anyResetting}
+                      size="xss"
+                      color="orange"
+                      tooltip={{ title: `Reset ${getLabel(comp)}`, description: `Reset ${getLabel(comp).toLowerCase()} to golden version` }}
+                    />
+                  </span>
+                </div>
+              )
+            })}
+          </div>
+          {!devtools && (
+            <p className="text-xs text-[#585b70] mt-3">
+              Your active working copy — what the app uses at runtime. Customizations are made here and preserved across app updates.
+            </p>
+          )}
+        </div>
+      </div>
+
+      {/* Update Flow — settings only */}
+      {!devtools && (
+        <div className="bg-[#181825]/50 border border-[#313244] rounded-lg p-4">
+          <p className="text-xs font-medium text-[#a6adc8] mb-4">
+            How updates work <span className="font-normal text-[#585b70]">— checked per component ({components.map(getLabel).join(', ')})</span>
+          </p>
+          <div className="grid grid-cols-[auto_auto_auto_auto_auto_auto_auto] items-center gap-x-2 text-xs">
+            {/* Row 1: top branch outcome */}
+            <span /><span /><span /><span /><span />
+            <span className="text-[#585b70] text-base justify-self-center self-end mb-[-4px]">↗</span>
+            <div className="flex flex-col items-center">
+              <Tooltip content={{ title: 'Live updated', description: 'No local customizations were found for this component, so it was automatically updated to match the new golden version.' }} multiline maxWidth={260}>
+                <div className="rounded bg-green-500/10 border border-green-500/20 px-3 py-1.5 whitespace-nowrap w-full text-center cursor-help">
+                  <span className="text-green-400 font-medium">Live updated</span>
+                </div>
+              </Tooltip>
+              <span className="text-[#585b70] mt-0.5">no changes</span>
+            </div>
+
+            {/* Row 2: linear flow */}
+            <div className="flex flex-col items-center">
+              <Tooltip content={{ title: 'App Update', description: 'A new version is installed, shipping a fresh seed archive with updated configuration and templates.' }} multiline maxWidth={260}>
+                <div className="rounded bg-amber-500/10 border border-amber-500/20 px-3 py-1.5 text-center w-full cursor-help">
+                  <span className="text-amber-400 font-medium">App Update</span>
+                </div>
+              </Tooltip>
+              <span className="text-[#585b70] mt-0.5">ships new seed</span>
+            </div>
+            <span className="text-[#585b70] text-lg self-start justify-self-center px-2">→</span>
+            <div className="flex flex-col items-center">
+              <Tooltip content={{ title: 'Golden overwritten', description: 'The golden reference directory is always overwritten with the latest seed. This ensures golden always reflects the newest release.' }} multiline maxWidth={260}>
+                <div className="rounded bg-blue-500/10 border border-blue-500/20 px-3 py-1.5 text-center w-full cursor-help">
+                  <span className="text-blue-400 font-medium">Golden</span>
+                </div>
+              </Tooltip>
+              <span className="text-[#585b70] mt-0.5">overwritten</span>
+            </div>
+            <span className="text-[#585b70] text-lg self-start justify-self-center px-2">→</span>
+            <div className="flex flex-col items-center">
+              <Tooltip content={{ title: 'Compare per component', description: 'Each component is compared individually. If the live version has local changes, it is left untouched.' }} multiline maxWidth={260}>
+                <div className="rounded bg-[#313244]/50 border border-[#313244] px-3 py-1.5 text-center w-full cursor-help">
+                  <span className="text-[#a6adc8] font-medium">Compare</span>
+                </div>
+              </Tooltip>
+              <span className="text-[#585b70] mt-0.5">per component</span>
+            </div>
+            <span /><span />
+
+            {/* Row 3: bottom branch outcome */}
+            <span /><span /><span /><span /><span />
+            <span className="text-[#585b70] text-base justify-self-center self-start mt-[-20px]">↘</span>
+            <div className="flex flex-col items-center">
+              <Tooltip content={{ title: 'Live unchanged', description: 'Local customizations were detected for this component, so it was left untouched. Use the File Diff tab to review differences, or reset it manually.' }} multiline maxWidth={260}>
+                <div className="rounded bg-yellow-500/10 border border-yellow-500/20 px-3 py-1.5 whitespace-nowrap w-full text-center cursor-help">
+                  <span className="text-yellow-400 font-medium">Live unchanged</span>
+                </div>
+              </Tooltip>
+              <span className="text-[#585b70] mt-0.5">has changes</span>
+            </div>
+          </div>
+          <p className="text-xs text-[#585b70] mt-3">
+            When a component has no local changes, it is automatically updated to match the new golden version. Components with customizations are left untouched to preserve your edits — use the File Diff tab to review differences and selectively apply changes. You can reset any component to its golden version at any time using the reset buttons above.
+          </p>
+        </div>
+      )}
+
+      {/* Local Snapshots - devtools only */}
+      {devtools && manifest && (
+        <div className="bg-[#181825] rounded-lg p-4 border border-[#313244]">
+          <div className="flex items-center gap-2 mb-3">
+            <Archive className="w-4 h-4 text-[#6c7086]" />
+            <h4 className="text-[#cdd6f4] font-medium">Local Snapshots</h4>
+          </div>
+          <div className="flex gap-6 text-sm">
+            <div>
+              <span className="text-[#6c7086]">Count: </span>
+              <span className="text-[#cdd6f4]">{manifest.snapshots.length}</span>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

package/components/sections/golden-snapshots/types.ts

@@ -0,0 +1,288 @@
+/**
+ * Golden Snapshots — Shared type definitions
+ *
+ * Part of: Sections > Golden Snapshots
+ *
+ * These types define the CONTRACT between the UI layer (this package) and
+ * the Rust/Tauri backend that each app must implement. Every type here has
+ * a 1:1 mapping to a Rust struct returned by Tauri commands.
+ *
+ * IMPORTANT FOR AI AGENTS:
+ * When adding a new field here, the corresponding Rust struct must also be
+ * updated (and vice versa). The serde rename attributes in Rust use camelCase
+ * to match these TypeScript interfaces.
+ *
+ * Generic design:
+ * - Components are keyed by string name (not hardcoded to specific apps)
+ * - Configr uses: "runtime", "verifier", "simulator", "generator"
+ * - Reviewr uses: "runtime", plus app-specific components
+ * - The UI renders whatever components the backend returns
+ */
+
+// ---------------------------------------------------------------------------
+// Component & Version tracking
+// ---------------------------------------------------------------------------
+
+/** Version info for a single component (runtime, verifier, etc.) */
+export interface ComponentVersion {
+  version: string
+  description?: string
+  updatedAt?: string
+  hash?: string
+}
+
+/**
+ * Golden metadata — describes the state of a golden (reference) or live (working) copy.
+ *
+ * Rust equivalent: `GoldenMeta` in mod.rs
+ * Returned by: `get_status`, `get_golden_meta`
+ *
+ * `components` is a flat map of component name → version info.
+ * Each app defines its own component names.
+ */
+export interface GoldenMeta {
+  version: string
+  createdAt: string
+  description?: string
+  components: Record<string, ComponentVersion>
+}
+
+// ---------------------------------------------------------------------------
+// Status & Directory info
+// ---------------------------------------------------------------------------
+
+/** Filesystem status of a directory (golden, live, snapshots, etc.) */
+export interface DirectoryStatus {
+  exists: boolean
+  path: string
+  fileCount: number
+  totalSizeBytes: number
+}
+
+/** Info about the bundled seed archive */
+export interface SeedInfo {
+  exists: boolean
+  path: string
+  sizeBytes: number
+  modifiedAt?: string
+  meta?: GoldenMeta
+  fileCount: number
+  fileList: string[]
+}
+
+/**
+ * Overall status of the golden/live system.
+ *
+ * Rust equivalent: `ConfigrStatus` in mod.rs (generalize the name per app)
+ * Returned by: `get_status` command
+ *
+ * Contains metadata for both golden and live copies, directory statuses,
+ * and seed info. The UI uses this to render the Status Overview panel.
+ *
+ * `directories` is a flat map so apps can have any number of tracked directories.
+ * Convention: keys are "{component}Golden" and "{component}Live".
+ */
+export interface GoldenStatus {
+  goldenMeta?: GoldenMeta
+  liveMeta?: GoldenMeta
+  directories: Record<string, DirectoryStatus>
+  seed: SeedInfo
+}
+
+// ---------------------------------------------------------------------------
+// File diff
+// ---------------------------------------------------------------------------
+
+export type FileDiffStatus = 'added' | 'removed' | 'modified' | 'unchanged'
+
+/** A single file's diff info between golden and live */
+export interface FileDiffInfo {
+  /** Relative path within the component directory */
+  path: string
+  /** Which component this file belongs to (e.g. "runtime", "verifier") */
+  component: string
+  status: FileDiffStatus
+  goldenSize: number
+  liveSize: number
+}
+
+export interface DiffSummary {
+  added: number
+  removed: number
+  modified: number
+  unchanged: number
+  total: number
+}
+
+/** Which components have changes between golden and live */
+export type ChangedComponents = Record<string, boolean>
+
+/**
+ * Full diff result between golden and live directories.
+ *
+ * Rust equivalent: `GoldenLiveDiff` in mod.rs
+ * Returned by: `get_golden_live_diff` command
+ */
+export interface GoldenLiveDiff {
+  files: FileDiffInfo[]
+  summary: DiffSummary
+  componentChanges: ChangedComponents
+}
+
+// ---------------------------------------------------------------------------
+// Snapshots (versioned archives)
+// ---------------------------------------------------------------------------
+
+/** A single snapshot entry in the manifest */
+export interface SnapshotInfo {
+  version: number
+  filename: string
+  createdAt: string
+  description?: string
+  pinned: boolean
+  metaVersion?: string
+}
+
+/**
+ * Manifest listing all snapshots.
+ *
+ * Rust equivalent: `SnapshotsManifest` in mod.rs
+ * Returned by: `list_golden_snapshots` command
+ */
+export interface SnapshotsManifest {
+  activeVersion: number
+  pinnedVersion?: number
+  snapshots: SnapshotInfo[]
+}
+
+/** Result from creating a new snapshot */
+export interface CreateSnapshotResult {
+  version: number
+  filename: string
+  seedUpdated: boolean
+  changedComponents: ChangedComponents
+  newMeta: GoldenMeta
+}
+
+/** Result from resetting files */
+export interface ResetResult {
+  filesReset: number
+}
+
+// ---------------------------------------------------------------------------
+// API adapter interface
+// ---------------------------------------------------------------------------
+
+/**
+ * GoldenSnapshotsApi — The callback interface that each app must implement.
+ *
+ * This is the bridge between the shared UI and the app-specific backend.
+ * Each function maps to a Tauri command (or any other backend).
+ *
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │ RUST BACKEND IMPLEMENTATION GUIDE                                   │
+ * │                                                                     │
+ * │ Each method below corresponds to a Tauri #[tauri::command].         │
+ * │ The Rust reference implementation lives in:                         │
+ * │   configr/development/src-tauri/src/commands/snapshots/             │
+ * │     ├── mod.rs          — Types + helpers                           │
+ * │     ├── lifecycle.rs    — All command implementations               │
+ * │     ├── runtime_init.rs — Bootstrap (seed → golden → live)          │
+ * │     └── zip_ops.rs      — Zip archive utilities                     │
+ * │                                                                     │
+ * │ REQUIRED Tauri commands for full functionality:                      │
+ * │                                                                     │
+ * │ STATUS & METADATA:                                                  │
+ * │   get_status()              → GoldenStatus                          │
+ * │   get_golden_meta()         → GoldenMeta | null                     │
+ * │   get_golden_live_diff()    → GoldenLiveDiff                        │
+ * │                                                                     │
+ * │ FILE OPERATIONS:                                                    │
+ * │   get_file_content_for_diff(component, path, source) → string|null  │
+ * │   save_live_file_content(component, path, content) → void           │
+ * │   reset_golden_file_to_live(component, path) → void                 │
+ * │   reset_golden_component_to_live(component) → ResetResult           │
+ * │                                                                     │
+ * │ SNAPSHOT MANAGEMENT (devtools only):                                 │
+ * │   create_golden_snapshot(description?) → CreateSnapshotResult        │
+ * │   list_golden_snapshots() → SnapshotsManifest                       │
+ * │   restore_golden_snapshot(version, resetLive) → void                 │
+ * │   pin_golden_snapshot(version, pinned) → void                        │
+ * │   delete_golden_snapshot(version) → void                             │
+ * │                                                                     │
+ * │ VERSION MANAGEMENT:                                                  │
+ * │   update_component_version(component, version, desc?) → void         │
+ * │   bump_golden_version(newVersion, desc?) → void                      │
+ * │                                                                     │
+ * │ DIRECTORY STRUCTURE (Rust backend must maintain):                    │
+ * │   {app_data_dir}/                                                    │
+ * │   ├── golden/              — Reference copy (overwritten on update)  │
+ * │   │   ├── .meta/meta.json  — GoldenMeta serialized                  │
+ * │   │   └── {components}/    — One dir per component                  │
+ * │   ├── live/                — Working copy (user edits preserved)     │
+ * │   │   ├── .meta/meta.json                                           │
+ * │   │   └── {components}/                                             │
+ * │   └── snapshots/           — Versioned zip archives                 │
+ * │       ├── manifest.json    — SnapshotsManifest                      │
+ * │       └── snapshot_v001_YYYY-MM-DD.zip                              │
+ * │                                                                     │
+ * │ KEY BEHAVIORS the Rust backend must implement:                      │
+ * │ 1. Hash-based change detection between golden and live files        │
+ * │ 2. Semver auto-bump per component on snapshot creation              │
+ * │ 3. Selective sync: only update components without user changes      │
+ * │ 4. Snapshot pruning: keep N most recent + all pinned                │
+ * │ 5. Snapshot = zip of live dirs + meta.json                          │
+ * │ 6. create_snapshot copies live → golden after archiving             │
+ * └─────────────────────────────────────────────────────────────────────┘
+ */
+export interface GoldenSnapshotsApi {
+  // --- Status & Metadata ---
+
+  /** Get overall system status (golden/live metadata, directory info, seed) */
+  getStatus: () => Promise<GoldenStatus>
+
+  /** Get golden metadata only (lighter than full status) */
+  getGoldenMeta: () => Promise<GoldenMeta | null>
+
+  /** Get file-level diff between golden and live directories */
+  getDiff: () => Promise<GoldenLiveDiff>
+
+  // --- File Operations ---
+
+  /** Get content of a single file from golden or live */
+  getFileContent: (component: string, path: string, source: 'golden' | 'live') => Promise<string | null>
+
+  /** Save edited content to a live file (devtools only) */
+  saveFile: (component: string, path: string, content: string) => Promise<void>
+
+  /** Reset a single file: copy golden → live */
+  resetFile: (component: string, path: string) => Promise<void>
+
+  /** Reset an entire component (or 'all'): copy golden → live */
+  resetComponent: (component: string) => Promise<ResetResult>
+
+  // --- Snapshot Management (devtools only) ---
+
+  /** Create a new snapshot from current live state */
+  createSnapshot: (description?: string) => Promise<CreateSnapshotResult>
+
+  /** List all snapshots */
+  listSnapshots: () => Promise<SnapshotsManifest>
+
+  /** Restore a snapshot by version number */
+  restoreSnapshot: (version: number, resetLive: boolean) => Promise<void>
+
+  /** Pin/unpin a snapshot (pinned snapshots are never auto-pruned) */
+  pinSnapshot: (version: number, pinned: boolean) => Promise<void>
+
+  /** Delete a snapshot */
+  deleteSnapshot: (version: number) => Promise<void>
+
+  // --- Version Management ---
+
+  /** Update version for a single component */
+  updateComponentVersion: (component: string, version: string, description?: string) => Promise<void>
+
+  /** Bump the overall golden version */
+  bumpVersion: (newVersion: string, description?: string) => Promise<void>
+}