Add uv parser: GUI tracking of uv downloads / installation

astral-uv-research-document.md

@@ -0,0 +1,109 @@
+# Astral UV Package Manager - Comprehensive Research Document
+
+## Overview
+
+UV is an extremely fast Python package and project manager written in Rust by Astral (creators of Ruff). It serves as "a single tool to replace pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more."
+
+### Key Characteristics
+
+- **Performance**: 8-10x faster than pip without caching, 80-115x faster with warm cache
+- **Language**: Written in Rust for maximum performance, memory safety, and efficient parallel processing
+- **Scope**: Drop-in replacement for multiple Python tools (pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv)
+
+## Core Architecture
+
+### PubGrub Algorithm
+
+UV uses the **PubGrub algorithm** (via pubgrub-rs) for dependency resolution:
+
+- **Incremental version solver** using techniques like:
+  - Unit propagation
+  - Logical resolution
+  - Conflict-driven clause learning
+- **Forking Resolver**: Can split resolution for different environment markers (inspired by Poetry)
+
+### Key Optimizations
+
+- **Parallel Downloads**: Downloads multiple packages simultaneously
+- **Efficient Metadata Handling**: Only downloads metadata files instead of entire wheels for dependency resolution
+- **Global Caching**: Uses Copy-on-Write and hardlinks to minimize disk usage
+- **Bytecode Compilation**: Optional post-install compilation for faster startup
+
+## Debug Logging System
+
+### Environment Variables
+
+#### RUST_LOG
+
+Controls log verbosity level using tracing_subscriber-compatible filters:
+
+- `RUST_LOG=trace` - Most verbose (trace-level logging)
+- `RUST_LOG=debug` - Debug-level logging
+- `RUST_LOG=uv=debug` - Debug logging for UV specifically
+- `RUST_LOG=warn,uv=debug` - Global warn, UV debug
+
+#### UV_LOG_CONTEXT
+
+- Adds additional context and structure to log messages
+- Only effective when logging is enabled (via RUST_LOG or -v)
+- Enhances debug output with contextual information
+
+#### Other Debug Variables
+
+- `RUST_BACKTRACE=1` or `RUST_BACKTRACE=full` - Stack traces on errors
+- `TRACING_DURATIONS_FILE` - Performance analysis tracing
+- `UV_STACK_SIZE` - Sets stack size for UV operations
+- `UV_NO_PROGRESS` - Disables progress output
+- `UV_OFFLINE` - Disables network access
+- `UV_PREVIEW` - Enables preview mode features
+
+## Known Limitations
+
+- **Build Backend Output**: UV doesn't display build logs from native extensions in verbose mode (unlike pip)
+- **Sub-command Output**: Limited visibility into subprocess operations
+
+## File System Locations
+
+- **Cache Directory**: `~/.cache/uv/`
+  - `simple-v16/` - Package index cache
+  - `wheels-v5/` - Downloaded wheels cache
+  - `built-wheels-v5/` - Built wheels cache
+- **Virtual Environment**: `.venv/` in project directory
+- **Configuration**: Platform-specific (macOS: `~/Library/Application Support/`)
+
+## Performance Characteristics
+
+- **Resolution Speed**: Milliseconds for most packages
+- **Download Parallelism**: Multiple simultaneous connections
+- **Cache Efficiency**: Hardlinks to avoid duplication
+- **Memory Usage**: Rust's zero-cost abstractions minimize overhead
+
+## Integration Notes
+
+### For ComfyUI Desktop
+
+- UV is bundled as the primary package manager
+- Replaces pip for dependency installation
+- Provides faster installation times
+- Better error messages and conflict resolution
+
+### Command Examples
+
+```bash
+# Basic installation with debug output
+UV_LOG_CONTEXT=1 RUST_LOG=debug uv pip install [packages]
+
+# Clean cache
+uv cache clean
+
+# Uninstall packages
+uv pip uninstall [packages] --quiet
+```
+
+## Future Considerations
+
+When parsing UV output:
+
+1. Handle parallel operations (same timestamp, different operations)
+2. Parse structured data from debug logs for detailed insights
+3. Consider that some operations may be cached and thus instantaneous

src/main-process/appState.ts

@@ -4,6 +4,8 @@ import { EventEmitter } from 'node:events';
 import { InstallStage } from '@/constants';
 import { AppStartError } from '@/infrastructure/appStartError';
 import type { Page } from '@/infrastructure/interfaces';
+import { getUvState } from '@/uv-parser/uvState';
+import type { IUvState } from '@/uv-parser/uvStateInterfaces';
 
 import { type InstallStageInfo, createInstallStageInfo } from './installStages';
 
@@ -31,6 +33,8 @@ export interface IAppState extends Pick<EventEmitter<AppStateEvents>, 'on' | 'on
   readonly loaded: boolean;
   /** The last page the app loaded from the desktop side. @see {@link AppWindow.loadPage} */
   currentPage?: Page;
+  /** UV process state manager for tracking package installations. */
+  readonly uvState: IUvState;
   /** Current installation stage information. */
   readonly installStage: InstallStageInfo;
 
@@ -50,12 +54,17 @@ class AppState extends EventEmitter<AppStateEvents> implements IAppState {
   ipcRegistered = false;
   loaded = false;
   currentPage?: Page;
+  readonly uvState: IUvState;
   installStage: InstallStageInfo;
 
   constructor() {
     super();
     // Initialize install stage to idle
     this.installStage = createInstallStageInfo(InstallStage.IDLE, { progress: 0 });
+    // Initialize UV state
+    this.uvState = getUvState();
+    // Initialize install stage to idle
+    this.installStage = createInstallStageInfo(InstallStage.IDLE, { progress: 0 });
   }
 
   initialize() {

src/uv-parser/interfaces.ts

@@ -0,0 +1,58 @@
+/**
+ * UV Parser Interface Definitions
+ *
+ * Stateless interfaces for implementing a UV pip install output parser.
+ * The parser processes each line independently without maintaining state.
+ */
+import type { UvParsedOutput } from './types';
+
+/**
+ * Stateless UV output parser interface.
+ * Each line is parsed independently without requiring context or state.
+ */
+export interface IUvParser {
+  /**
+   * Parse a single line of UV output without any state context.
+   * Returns undefined if the line cannot be parsed or is not relevant.
+   *
+   * @param line - The line to parse
+   * @returns Parsed output object or undefined
+   */
+  parseLine(line: string): UvParsedOutput | undefined;
+
+  /**
+   * Parse multiple lines of UV output.
+   * Each line is parsed independently.
+   *
+   * @param lines - Array of lines to parse
+   * @returns Array of parsed outputs (undefined entries filtered out)
+   */
+  parseLines(lines: string[]): UvParsedOutput[];
+
+  /**
+   * Parse a complete UV output string.
+   * Splits by newlines and parses each line independently.
+   *
+   * @param output - Complete output string
+   * @returns Array of parsed outputs
+   */
+  parseOutput(output: string): UvParsedOutput[];
+
+  /**
+   * Check if a line can be parsed by this parser.
+   * Useful for filtering or validation.
+   *
+   * @param line - The line to check
+   * @returns True if the line matches any known pattern
+   */
+  canParse(line: string): boolean;
+
+  /**
+   * Get the type of output a line would produce without fully parsing it.
+   * Useful for routing or filtering.
+   *
+   * @param line - The line to check
+   * @returns The output type or undefined if not parseable
+   */
+  getLineType(line: string): UvParsedOutput['type'] | undefined;
+}

src/uv-parser/parseFile.ts

@@ -0,0 +1,46 @@
+/**
+ * Parse UV output file line by line and output JSON
+ *
+ * Usage:
+ *   npx tsx src/uv-parser/parse-file.ts <file-path>
+ *   or
+ *   node --loader tsx src/uv-parser/parse-file.ts <file-path>
+ */
+import { readFileSync } from 'node:fs';
+
+import { createUvParser } from './parser';
+
+// Main function to allow proper error handling
+function main(): void {
+  // Get file path from command line arguments
+  const filePath = process.argv[2];
+
+  if (!filePath) {
+    console.error('Usage: npx tsx parse-file.ts <file-path>');
+    throw new Error('No file path provided');
+  }
+
+  // Read file content
+  const content = readFileSync(filePath, 'utf8');
+  const lines = content.split('\n');
+
+  // Create parser instance
+  const parser = createUvParser();
+
+  // Parse each line and output JSON
+  for (const line of lines) {
+    const parsed = parser.parseLine(line);
+    if (parsed) {
+      console.log(JSON.stringify(parsed));
+    }
+  }
+}
+
+// Run main function and handle errors
+try {
+  main();
+} catch (error) {
+  console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+  // eslint-disable-next-line unicorn/no-process-exit
+  process.exit(1);
+}