fss-link 1.5.7 → 1.6.0

package/scripts/install-windows.ps1

@@ -0,0 +1,427 @@
+# FSS Link Windows Installation Script
+# Supports Windows 10+ with automatic dependency management
+
+param(
+    [switch]$Help,
+    [switch]$Version,
+    [switch]$Force,
+    [switch]$NoChocolatey
+)
+
+# Color output functions
+function Write-Info {
+    param([string]$Message)
+    Write-Host "[INFO] $Message" -ForegroundColor Blue
+}
+
+function Write-Success {
+    param([string]$Message)
+    Write-Host "[SUCCESS] $Message" -ForegroundColor Green
+}
+
+function Write-Warning {
+    param([string]$Message)
+    Write-Host "[WARNING] $Message" -ForegroundColor Yellow
+}
+
+function Write-Error {
+    param([string]$Message)
+    Write-Host "[ERROR] $Message" -ForegroundColor Red
+}
+
+# Check if running as Administrator
+function Test-Administrator {
+    $currentUser = [Security.Principal.WindowsIdentity]::GetCurrent()
+    $principal = New-Object Security.Principal.WindowsPrincipal($currentUser)
+    return $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+}
+
+# Check Windows version
+function Test-WindowsVersion {
+    Write-Info "Checking Windows version..."
+    
+    $version = [System.Environment]::OSVersion.Version
+    $buildNumber = (Get-ItemProperty "HKLM:SOFTWARE\Microsoft\Windows NT\CurrentVersion").ReleaseId
+    
+    Write-Info "Windows version: $($version.Major).$($version.Minor) Build $buildNumber"
+    
+    if ($version.Major -ge 10) {
+        Write-Success "Windows version supported"
+        return $true
+    } else {
+        Write-Error "Windows 10+ required, found Windows $($version.Major).$($version.Minor)"
+        return $false
+    }
+}
+
+# Check for Node.js
+function Test-NodeJS {
+    Write-Info "Checking Node.js installation..."
+    
+    try {
+        $nodeVersion = & node --version 2>$null
+        if ($nodeVersion) {
+            $version = $nodeVersion.TrimStart('v')
+            $majorVersion = [int]($version.Split('.')[0])
+            
+            if ($majorVersion -ge 20) {
+                Write-Success "Node.js $nodeVersion detected (>= 20.0.0 required)"
+                return $true
+            } else {
+                Write-Warning "Node.js $nodeVersion detected, but 20.0.0+ required"
+                return $false
+            }
+        }
+    } catch {
+        Write-Warning "Node.js not found"
+        return $false
+    }
+    
+    return $false
+}
+
+# Check for Chocolatey
+function Test-Chocolatey {
+    Write-Info "Checking for Chocolatey package manager..."
+    
+    try {
+        $chocoVersion = & choco --version 2>$null
+        if ($chocoVersion) {
+            Write-Success "Chocolatey $chocoVersion found"
+            return $true
+        }
+    } catch {
+        Write-Warning "Chocolatey not found"
+        return $false
+    }
+    
+    return $false
+}
+
+# Install Chocolatey
+function Install-Chocolatey {
+    Write-Info "Installing Chocolatey package manager..."
+    
+    Set-ExecutionPolicy Bypass -Scope Process -Force
+    [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
+    
+    try {
+        Invoke-Expression ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
+        
+        # Refresh environment variables
+        $env:PATH = [System.Environment]::GetEnvironmentVariable("PATH", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH", "User")
+        
+        if (Test-Chocolatey) {
+            Write-Success "Chocolatey installed successfully"
+            return $true
+        } else {
+            Write-Error "Chocolatey installation verification failed"
+            return $false
+        }
+    } catch {
+        Write-Error "Chocolatey installation failed: $($_.Exception.Message)"
+        return $false
+    }
+}
+
+# Install Node.js
+function Install-NodeJS {
+    Write-Info "Installing Node.js 20..."
+    
+    if ($NoChocolatey) {
+        Write-Info "Manual Node.js installation selected"
+        Write-Info "Please download and install Node.js 20+ from https://nodejs.org/"
+        Write-Info "Press Enter when installation is complete..."
+        Read-Host
+        
+        if (Test-NodeJS) {
+            Write-Success "Node.js installed successfully"
+            return $true
+        } else {
+            Write-Error "Node.js installation verification failed"
+            return $false
+        }
+    } else {
+        try {
+            # Install Node.js via Chocolatey
+            & choco install nodejs --version=20.11.0 -y
+            
+            # Refresh environment variables
+            $env:PATH = [System.Environment]::GetEnvironmentVariable("PATH", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH", "User")
+            
+            if (Test-NodeJS) {
+                Write-Success "Node.js installed successfully"
+                return $true
+            } else {
+                Write-Error "Node.js installation verification failed"
+                return $false
+            }
+        } catch {
+            Write-Error "Node.js installation failed: $($_.Exception.Message)"
+            return $false
+        }
+    }
+}
+
+# Install Visual Studio Build Tools
+function Install-BuildTools {
+    Write-Info "Installing Visual Studio Build Tools..."
+    
+    if ($NoChocolatey) {
+        Write-Info "Please install Visual Studio Build Tools 2019 or later manually"
+        Write-Info "Download from: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019"
+        Write-Info "Press Enter when installation is complete..."
+        Read-Host
+        return $true
+    } else {
+        try {
+            & choco install visualstudio2019buildtools -y
+            Write-Success "Visual Studio Build Tools installed"
+            return $true
+        } catch {
+            Write-Warning "Build tools installation may have failed: $($_.Exception.Message)"
+            Write-Info "FSS Link installation will continue, but native modules may not compile"
+            return $true
+        }
+    }
+}
+
+# Install Python
+function Install-Python {
+    Write-Info "Installing Python 3..."
+    
+    if ($NoChocolatey) {
+        Write-Info "Please install Python 3.8+ manually from https://python.org/"
+        Write-Info "Press Enter when installation is complete..."
+        Read-Host
+        return $true
+    } else {
+        try {
+            & choco install python3 -y
+            
+            # Refresh PATH
+            $env:PATH = [System.Environment]::GetEnvironmentVariable("PATH", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH", "User")
+            
+            Write-Success "Python 3 installed"
+            return $true
+        } catch {
+            Write-Warning "Python installation may have failed: $($_.Exception.Message)"
+            return $true
+        }
+    }
+}
+
+# Install FSS Link
+function Install-FSSLink {
+    Write-Info "Installing FSS Link..."
+    
+    try {
+        # Try global installation first
+        & npm install -g fss-link
+        
+        if (Test-FSSLink) {
+            Write-Success "FSS Link installed globally"
+            return $true
+        } else {
+            throw "Global installation verification failed"
+        }
+    } catch {
+        Write-Warning "Global installation failed, trying alternative approach: $($_.Exception.Message)"
+        
+        try {
+            # Create local npm directory
+            $npmGlobalPath = "$env:USERPROFILE\.npm-global"
+            New-Item -ItemType Directory -Path $npmGlobalPath -Force | Out-Null
+            
+            & npm config set prefix $npmGlobalPath
+            
+            # Add to PATH
+            $userPath = [System.Environment]::GetEnvironmentVariable("PATH", "User")
+            $npmBinPath = "$npmGlobalPath\bin"
+            
+            if ($userPath -notlike "*$npmBinPath*") {
+                [System.Environment]::SetEnvironmentVariable("PATH", "$userPath;$npmBinPath", "User")
+                $env:PATH = "$env:PATH;$npmBinPath"
+            }
+            
+            # Install locally
+            & npm install -g fss-link
+            
+            Write-Success "FSS Link installed locally"
+            return $true
+        } catch {
+            Write-Error "FSS Link installation failed: $($_.Exception.Message)"
+            return $false
+        }
+    }
+}
+
+# Test FSS Link installation
+function Test-FSSLink {
+    try {
+        $fssVersion = & fss-link --version 2>$null
+        if ($fssVersion) {
+            Write-Success "FSS Link installed successfully: $fssVersion"
+            return $true
+        }
+    } catch {
+        return $false
+    }
+    
+    return $false
+}
+
+# Verify FSS Link functionality
+function Test-FSSLinkFunctionality {
+    Write-Info "Running FSS Link functionality tests..."
+    
+    try {
+        # Test help command
+        $helpOutput = & fss-link --help 2>$null
+        if ($helpOutput) {
+            Write-Success "✅ Help command working"
+        } else {
+            Write-Warning "⚠️ Help command failed"
+        }
+        
+        # Test parsers
+        $parsersOutput = & fss-link test-parsers 2>$null
+        if ($parsersOutput) {
+            Write-Success "✅ Document parsers working"
+        } else {
+            Write-Warning "⚠️ Document parsers test failed"
+        }
+        
+        return $true
+    } catch {
+        Write-Warning "Some functionality tests failed: $($_.Exception.Message)"
+        return $false
+    }
+}
+
+# Print usage information
+function Show-Usage {
+    Write-Host @"
+
+🚀 FSS Link Installation Complete!
+
+📋 Quick Start:
+  fss-link --version              # Check version
+  fss-link --help                 # Show help
+  fss-link test-parsers           # Test document processing
+  
+🔧 Configuration:
+  fss-link init                   # Initialize configuration
+  fss-link models setup           # Set up model profiles
+
+📚 Documentation:
+  https://github.com/FSSCoding/fss-link/blob/main/INSTALLATION.md
+  https://github.com/FSSCoding/fss-link/blob/main/fss-docs/README.md
+
+🎯 Example Usage:
+  fss-link -p "analyze this project"
+  fss-link --tools excel-parser -p "parse spreadsheet.xlsx"
+  fss-link --tools web-scraper -p "scrape https://example.com"
+
+💻 Windows Specific:
+  - FSS Link is now in your PATH
+  - Restart PowerShell/Command Prompt to ensure PATH changes take effect
+  - Use Windows Terminal for the best experience
+
+"@ -ForegroundColor Cyan
+}
+
+# Main installation flow
+function Main {
+    Write-Host "🚀 FSS Link Windows Installation Script" -ForegroundColor Cyan
+    Write-Host "=======================================" -ForegroundColor Cyan
+    Write-Host ""
+    
+    # Check if running as administrator
+    if (Test-Administrator) {
+        Write-Warning "Running as Administrator. FSS Link will be installed globally."
+    }
+    
+    # Check Windows version
+    if (-not (Test-WindowsVersion)) {
+        exit 1
+    }
+    
+    # Install Chocolatey if needed (unless disabled)
+    if (-not $NoChocolatey -and -not (Test-Chocolatey)) {
+        Write-Info "Installing Chocolatey for automated dependency management..."
+        if (-not (Install-Chocolatey)) {
+            Write-Error "Chocolatey installation failed"
+            Write-Info "Re-run with -NoChocolatey flag for manual installation"
+            exit 1
+        }
+    }
+    
+    # Install Node.js if needed
+    if (-not (Test-NodeJS)) {
+        if (-not (Install-NodeJS)) {
+            Write-Error "Node.js installation failed"
+            exit 1
+        }
+    }
+    
+    # Install build tools
+    Install-BuildTools | Out-Null
+    
+    # Install Python
+    Install-Python | Out-Null
+    
+    # Install FSS Link
+    if (-not (Install-FSSLink)) {
+        Write-Error "FSS Link installation failed"
+        Write-Info "Please check the installation manually or report issues at:"
+        Write-Info "https://github.com/FSSCoding/fss-link/issues"
+        exit 1
+    }
+    
+    # Verify installation
+    Test-FSSLinkFunctionality | Out-Null
+    
+    Show-Usage
+    Write-Success "🎉 FSS Link installation successful!"
+}
+
+# Handle script parameters
+if ($Help) {
+    Write-Host @"
+FSS Link Windows Installation Script
+
+Usage: .\install-windows.ps1 [options]
+
+Options:
+  -Help           Show this help message
+  -Version        Show script version
+  -Force          Force reinstallation
+  -NoChocolatey   Skip Chocolatey installation (manual mode)
+
+This script will:
+1. Check Windows version compatibility
+2. Install Chocolatey package manager (unless -NoChocolatey)
+3. Install Node.js 20+ and dependencies
+4. Install Visual Studio Build Tools
+5. Install FSS Link from npm
+6. Verify the installation
+
+Examples:
+  .\install-windows.ps1                    # Standard installation
+  .\install-windows.ps1 -NoChocolatey     # Manual installation mode
+  .\install-windows.ps1 -Force            # Force reinstallation
+"@
+    exit 0
+}
+
+if ($Version) {
+    Write-Host "FSS Link Windows Installation Script v1.0.0"
+    exit 0
+}
+
+# Set execution policy for this session
+Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force
+
+# Run main installation
+Main

package/scripts/local_telemetry.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import path from 'path';
+import fs from 'fs';
+import { spawn, execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import {
+  BIN_DIR,
+  OTEL_DIR,
+  ensureBinary,
+  fileExists,
+  manageTelemetrySettings,
+  registerCleanup,
+  waitForPort,
+} from './telemetry_utils.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const OTEL_CONFIG_FILE = path.join(OTEL_DIR, 'collector-local.yaml');
+const OTEL_LOG_FILE = path.join(OTEL_DIR, 'collector.log');
+const JAEGER_LOG_FILE = path.join(OTEL_DIR, 'jaeger.log');
+const JAEGER_PORT = 16686;
+
+// This configuration is for the primary otelcol-contrib instance.
+// It receives from the CLI on 4317, exports traces to Jaeger on 14317,
+// and sends metrics/logs to the debug log.
+const OTEL_CONFIG_CONTENT = `
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: "localhost:4317"
+processors:
+  batch:
+    timeout: 1s
+exporters:
+  otlp:
+    endpoint: "localhost:14317"
+    tls:
+      insecure: true
+  debug:
+    verbosity: detailed
+service:
+  telemetry:
+    logs:
+      level: "debug"
+    metrics:
+      level: "none"
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp]
+    metrics:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [debug]
+    logs:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [debug]
+`;
+
+async function main() {
+  // 1. Ensure binaries are available, downloading if necessary.
+  // Binaries are stored in the project's .fss-link/otel/bin directory
+  // to avoid modifying the user's system.
+  if (!fileExists(BIN_DIR)) fs.mkdirSync(BIN_DIR, { recursive: true });
+
+  const otelcolPath = await ensureBinary(
+    'otelcol-contrib',
+    'open-telemetry/opentelemetry-collector-releases',
+    (version, platform, arch, ext) =>
+      `otelcol-contrib_${version}_${platform}_${arch}.${ext}`,
+    'otelcol-contrib',
+    false, // isJaeger = false
+  ).catch((e) => {
+    console.error(`��� Error getting otelcol-contrib: ${e.message}`);
+    return null;
+  });
+  if (!otelcolPath) process.exit(1);
+
+  const jaegerPath = await ensureBinary(
+    'jaeger',
+    'jaegertracing/jaeger',
+    (version, platform, arch, ext) =>
+      `jaeger-${version}-${platform}-${arch}.${ext}`,
+    'jaeger',
+    true, // isJaeger = true
+  ).catch((e) => {
+    console.error(`🛑 Error getting jaeger: ${e.message}`);
+    return null;
+  });
+  if (!jaegerPath) process.exit(1);
+
+  // 2. Kill any existing processes to ensure a clean start.
+  console.log('🧹 Cleaning up old processes and logs...');
+  try {
+    execSync('pkill -f "otelcol-contrib"');
+    console.log('✅ Stopped existing otelcol-contrib process.');
+  } catch (_e) {} // eslint-disable-line no-empty
+  try {
+    execSync('pkill -f "jaeger"');
+    console.log('✅ Stopped existing jaeger process.');
+  } catch (_e) {} // eslint-disable-line no-empty
+  try {
+    if (fileExists(OTEL_LOG_FILE)) fs.unlinkSync(OTEL_LOG_FILE);
+    console.log('✅ Deleted old collector log.');
+  } catch (e) {
+    if (e.code !== 'ENOENT') console.error(e);
+  }
+  try {
+    if (fileExists(JAEGER_LOG_FILE)) fs.unlinkSync(JAEGER_LOG_FILE);
+    console.log('✅ Deleted old jaeger log.');
+  } catch (e) {
+    if (e.code !== 'ENOENT') console.error(e);
+  }
+
+  let jaegerProcess, collectorProcess;
+  let jaegerLogFd, collectorLogFd;
+
+  const originalSandboxSetting = manageTelemetrySettings(
+    true,
+    'http://localhost:4317',
+    'local',
+  );
+
+  registerCleanup(
+    () => [jaegerProcess, collectorProcess],
+    () => [jaegerLogFd, collectorLogFd],
+    originalSandboxSetting,
+  );
+
+  if (!fileExists(OTEL_DIR)) fs.mkdirSync(OTEL_DIR, { recursive: true });
+  fs.writeFileSync(OTEL_CONFIG_FILE, OTEL_CONFIG_CONTENT);
+  console.log('📄 Wrote OTEL collector config.');
+
+  // Start Jaeger
+  console.log(`🚀 Starting Jaeger service... Logs: ${JAEGER_LOG_FILE}`);
+  jaegerLogFd = fs.openSync(JAEGER_LOG_FILE, 'a');
+  jaegerProcess = spawn(
+    jaegerPath,
+    ['--set=receivers.otlp.protocols.grpc.endpoint=localhost:14317'],
+    { stdio: ['ignore', jaegerLogFd, jaegerLogFd] },
+  );
+  console.log(`⏳ Waiting for Jaeger to start (PID: ${jaegerProcess.pid})...`);
+
+  try {
+    await waitForPort(JAEGER_PORT);
+    console.log(`✅ Jaeger started successfully.`);
+  } catch (_) {
+    console.error(`🛑 Error: Jaeger failed to start on port ${JAEGER_PORT}.`);
+    if (jaegerProcess && jaegerProcess.pid) {
+      process.kill(jaegerProcess.pid, 'SIGKILL');
+    }
+    if (fileExists(JAEGER_LOG_FILE)) {
+      console.error('📄 Jaeger Log Output:');
+      console.error(fs.readFileSync(JAEGER_LOG_FILE, 'utf-8'));
+    }
+    process.exit(1);
+  }
+
+  // Start the primary OTEL collector
+  console.log(`🚀 Starting OTEL collector... Logs: ${OTEL_LOG_FILE}`);
+  collectorLogFd = fs.openSync(OTEL_LOG_FILE, 'a');
+  collectorProcess = spawn(otelcolPath, ['--config', OTEL_CONFIG_FILE], {
+    stdio: ['ignore', collectorLogFd, collectorLogFd],
+  });
+  console.log(
+    `⏳ Waiting for OTEL collector to start (PID: ${collectorProcess.pid})...`,
+  );
+
+  try {
+    await waitForPort(4317);
+    console.log(`✅ OTEL collector started successfully.`);
+  } catch (_) {
+    console.error(`🛑 Error: OTEL collector failed to start on port 4317.`);
+    if (collectorProcess && collectorProcess.pid) {
+      process.kill(collectorProcess.pid, 'SIGKILL');
+    }
+    if (fileExists(OTEL_LOG_FILE)) {
+      console.error('📄 OTEL Collector Log Output:');
+      console.error(fs.readFileSync(OTEL_LOG_FILE, 'utf-8'));
+    }
+    process.exit(1);
+  }
+
+  [jaegerProcess, collectorProcess].forEach((proc) => {
+    if (proc) {
+      proc.on('error', (err) => {
+        console.error(`${proc.spawnargs[0]} process error:`, err);
+        process.exit(1);
+      });
+    }
+  });
+
+  console.log(`
+✨ Local telemetry environment is running.`);
+  console.log(
+    `
+🔎 View traces in the Jaeger UI: http://localhost:${JAEGER_PORT}`,
+  );
+  console.log(`📊 View metrics in the logs and metrics: ${OTEL_LOG_FILE}`);
+  console.log(
+    `
+📄 Tail logs and metrics in another terminal: tail -f ${OTEL_LOG_FILE}`,
+  );
+  console.log(`
+Press Ctrl+C to exit.`);
+}
+
+main();