update documentation

Author: Smartsheet-JB-Brown

cline_docs/package-manager/implementation/01-architecture.md

@@ -13,6 +13,7 @@ graph TD
     User[User] -->|Interacts with| UI[Package Manager UI]
     UI -->|Sends messages| MH[Message Handler]
     MH -->|Processes requests| PM[PackageManagerManager]
+    PM -->|Validates sources| PSV[PackageManagerSourceValidation]
     PM -->|Fetches repos| GF[GitFetcher]
     GF -->|Scans metadata| MS[MetadataScanner]
     MS -->|Reads| FS[File System / Git Repositories]
@@ -171,6 +172,16 @@ classDiagram
         +sortItems(sortBy, order): PackageManagerItem[]
         +refreshRepository(url): void
         -queueOperation(operation): void
+        -validateSources(sources): ValidationError[]
+    }
+
+    class PackageManagerSourceValidation {
+        +validateSourceUrl(url): ValidationError[]
+        +validateSourceName(name): ValidationError[]
+        +validateSourceDuplicates(sources): ValidationError[]
+        +validateSource(source): ValidationError[]
+        +validateSources(sources): ValidationError[]
+        -isValidGitRepositoryUrl(url): boolean
     }
 
     class GitFetcher {
@@ -190,16 +201,25 @@ classDiagram
     }
 
     class PackageManagerViewStateManager {
-        -items: PackageManagerItem[]
-        -filters: Filters
-        -sortBy: string
-        -sortOrder: string
-        +setFilters(filters): void
-        +getFilteredAndSortedItems(): PackageManagerItem[]
-        -itemMatchesFilters(item): boolean
+        -state: ViewState
+        -stateChangeHandlers: Set
+        -fetchTimeoutId: NodeJS.Timeout
+        -sourcesModified: boolean
+        +initialize(): void
+        +onStateChange(handler): () => void
+        +cleanup(): void
+        +getState(): ViewState
+        +transition(transition): Promise<void>
+        -notifyStateChange(): void
+        -clearFetchTimeout(): void
+        -isFilterActive(): boolean
+        -filterItems(items): PackageManagerItem[]
+        -sortItems(items): PackageManagerItem[]
+        +handleMessage(message): Promise<void>
     }
 
     PackageManagerManager --> GitFetcher: uses
+    PackageManagerManager --> PackageManagerSourceValidation: uses
     GitFetcher --> MetadataScanner: uses
     PackageManagerManager --> PackageManagerViewStateManager: updates
 ```
@@ -239,26 +259,37 @@ classDiagram
 
 1. **PackageManagerViewStateManager**
 
-    - Manages view-level state
-    - Handles filtering and sorting
-    - Maintains UI preferences
+    - Manages frontend state and backend synchronization
+    - Handles state transitions and message processing
+    - Manages filtering, sorting, and view preferences
     - Coordinates with backend state
+    - Handles timeout protection for operations
+    - Manages source modification tracking
+    - Provides state change subscriptions
+
+2. **PackageManagerSourceValidation**
+
+    - Validates Git repository URLs for any domain
+    - Validates source names and configurations
+    - Detects duplicate sources (case-insensitive)
+    - Provides structured validation errors
+    - Supports multiple Git protocols (HTTPS, SSH, Git)
 
-2. **PackageManagerItemCard**
+3. **PackageManagerItemCard**
 
     - Displays package information
     - Handles tag interactions
     - Manages expandable sections
     - Shows match highlights
 
-3. **ExpandableSection**
+4. **ExpandableSection**
 
     - Provides collapsible sections
     - Manages expand/collapse state
     - Handles animations
     - Shows section metadata
 
-4. **TypeGroup**
+5. **TypeGroup**
     - Groups items by type
     - Formats item lists
     - Highlights search matches

cline_docs/package-manager/implementation/02-core-components.md

@@ -234,37 +234,129 @@ The filtering system provides rich functionality:
     - Support highlighting
     - Maintain match context
 
+## PackageManagerSourceValidation
+
+The PackageManagerSourceValidation component handles validation of package manager sources and their configurations.
+
+### Responsibilities
+
+- Validating Git repository URLs for any domain
+- Validating source names and configurations
+- Detecting duplicate sources
+- Providing structured validation errors
+- Supporting multiple Git protocols
+
+### Implementation Details
+
+```typescript
+export class PackageManagerSourceValidation {
+	/**
+	 * Validates a package manager source URL
+	 */
+	public static validateSourceUrl(url: string): ValidationError[] {
+		// Implementation details
+	}
+
+	/**
+	 * Validates a package manager source name
+	 */
+	public static validateSourceName(name?: string): ValidationError[] {
+		// Implementation details
+	}
+
+	/**
+	 * Validates sources for duplicates
+	 */
+	public static validateSourceDuplicates(
+		sources: PackageManagerSource[],
+		newSource?: PackageManagerSource,
+	): ValidationError[] {
+		// Implementation details
+	}
+
+	/**
+	 * Checks if a URL is a valid Git repository URL
+	 */
+	private static isValidGitRepositoryUrl(url: string): boolean {
+		// Implementation details
+	}
+}
+```
+
+### Key Algorithms
+
+#### URL Validation
+
+The URL validation system supports:
+
+1. **Protocol Validation**:
+
+    - HTTPS URLs
+    - SSH URLs
+    - Git protocol URLs
+    - Custom domains and ports
+
+2. **Domain Validation**:
+
+    - Any valid domain name
+    - IP addresses
+    - Localhost for testing
+    - Internal company domains
+
+3. **Path Validation**:
+    - Username/organization
+    - Repository name
+    - Optional .git suffix
+    - Subpath support
+
 ## PackageManagerViewStateManager
 
-The PackageManagerViewStateManager handles UI state and view-level operations.
+The PackageManagerViewStateManager manages frontend state and synchronization with the backend.
 
 ### Responsibilities
 
-- Managing view-level state
-- Handling UI filters
-- Coordinating sorting
-- Managing item visibility
+- Managing frontend state transitions
+- Handling message processing
+- Managing timeouts and retries
+- Coordinating with backend state
+- Providing state change subscriptions
+- Managing source modification tracking
+- Handling filtering and sorting
 
 ### Implementation Details
 
 ```typescript
 class PackageManagerViewStateManager {
-	private items: PackageManagerItem[] = []
-	private sortBy: "name" | "lastUpdated" = "name"
-	private sortOrder: "asc" | "desc" = "asc"
-	private filters: Filters = { type: "", search: "", tags: [] }
+	private state: ViewState
+	private stateChangeHandlers: Set<StateChangeHandler>
+	private fetchTimeoutId?: NodeJS.Timeout
+	private sourcesModified: boolean
+
+	/**
+	 * Initialize state manager
+	 */
+	public initialize(): void {
+		// Implementation details
+	}
+
+	/**
+	 * Subscribe to state changes
+	 */
+	public onStateChange(handler: StateChangeHandler): () => void {
+		// Implementation details
+	}
 
 	/**
-	 * Get filtered and sorted items
+	 * Process state transitions
 	 */
-	public getFilteredAndSortedItems(): PackageManagerItem[] {
+	public async transition(transition: ViewStateTransition): Promise<void> {
 		// Implementation details
 	}
 
 	/**
-	 * Check if item matches current filters
+	 * Handle incoming messages
 	 */
-	private itemMatchesFilters(item: PackageManagerItem | Subcomponent): boolean {
+	public async handleMessage(message: any): Promise<void> {
 		// Implementation details
 	}
 }
@@ -278,6 +370,7 @@ The components work together through well-defined interfaces:
 
 1. **Repository Operations**:
 
+    - PackageManagerManager validates sources with PackageManagerSourceValidation
     - PackageManagerManager coordinates with GitFetcher
     - GitFetcher manages repository state
     - MetadataScanner processes repository content
@@ -286,9 +379,11 @@ The components work together through well-defined interfaces:
 2. **State Management**:
 
     - PackageManagerManager maintains backend state
-    - ViewStateManager handles UI state
-    - State changes trigger UI updates
+    - ViewStateManager handles UI state transitions
+    - ViewStateManager processes messages
+    - State changes notify subscribers
     - Components react to state changes
+    - Timeout protection ensures responsiveness
 
 3. **User Interactions**:
     - UI events trigger state updates

cline_docs/package-manager/implementation/03-data-structures.md

@@ -109,25 +109,88 @@ Enhanced match tracking:
 
 ## State Management Structures
 
+### ValidationError
+
+```typescript
+/**
+ * Error type for package manager source validation
+ */
+export interface ValidationError {
+	field: string
+	message: string
+}
+```
+
+Used for structured validation errors:
+
+- **field**: The field that failed validation (e.g., "url", "name")
+- **message**: Human-readable error message
+
 ### ViewState
 
 ```typescript
 /**
  * View-level state management
  */
 interface ViewState {
-	items: PackageManagerItem[]
-	sortBy: "name" | "lastUpdated"
-	sortOrder: "asc" | "desc"
+	allItems: PackageManagerItem[]
+	displayItems?: PackageManagerItem[]
+	isFetching: boolean
+	activeTab: "browse" | "sources"
+	refreshingUrls: string[]
+	sources: PackageManagerSource[]
 	filters: Filters
+	sortConfig: {
+		by: "name" | "author" | "lastUpdated"
+		order: "asc" | "desc"
+	}
 }
 ```
 
 Manages UI state:
 
-- Current items
-- Sort configuration
-- Filter state
+- **allItems**: All available items
+- **displayItems**: Currently filtered/displayed items
+- **isFetching**: Loading state indicator
+- **activeTab**: Current view tab
+- **refreshingUrls**: Sources being refreshed
+- **sources**: Package manager sources
+- **filters**: Active filters
+- **sortConfig**: Sort configuration
+
+### ViewStateTransition
+
+```typescript
+/**
+ * State transition types and payloads
+ */
+type ViewStateTransition = {
+	type:
+		| "FETCH_ITEMS"
+		| "FETCH_COMPLETE"
+		| "FETCH_ERROR"
+		| "SET_ACTIVE_TAB"
+		| "UPDATE_FILTERS"
+		| "UPDATE_SORT"
+		| "REFRESH_SOURCE"
+		| "REFRESH_SOURCE_COMPLETE"
+		| "UPDATE_SOURCES"
+	payload?: {
+		items?: PackageManagerItem[]
+		tab?: "browse" | "sources"
+		filters?: Partial<Filters>
+		sortConfig?: Partial<SortConfig>
+		url?: string
+		sources?: PackageManagerSource[]
+	}
+}
+```
+
+Defines state transitions:
+
+- Operation types
+- Optional payloads
+- Type-safe transitions
 
 ### Filters
 
@@ -364,14 +427,28 @@ function validateMetadata(metadata: unknown): metadata is ComponentMetadata {
 /**
  * Validate Git repository URL
  */
-function isValidGitUrl(url: string): boolean {
-	if (!url) return false
+function isValidGitRepositoryUrl(url: string): boolean {
+	// HTTPS pattern (any domain)
+	const httpsPattern =
+		/^https?:\/\/[a-zA-Z0-9_.-]+(\.[a-zA-Z0-9_.-]+)*\/[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+(\/.+)*(\.git)?$/
+
+	// SSH pattern (any domain)
+	const sshPattern = /^git@[a-zA-Z0-9_.-]+(\.[a-zA-Z0-9_.-]+)*:([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+)(\.git)?$/
 
-	// Support common Git URL formats
-	return /^(https?:\/\/|git@)/.test(url) && /\.git$/.test(url)
+	// Git protocol pattern (any domain)
+	const gitProtocolPattern = /^git:\/\/[a-zA-Z0-9_.-]+(\.[a-zA-Z0-9_.-]+)*\/[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+(\.git)?$/
+
+	return httpsPattern.test(url) || sshPattern.test(url) || gitProtocolPattern.test(url)
 }
 ```
 
+Supports:
+
+- Any valid domain name
+- Multiple Git protocols
+- Optional .git suffix
+- Subpath components
+
 ## Data Flow
 
 The Package Manager transforms data through several stages: