Install Script

Overview

The TailStack install scripts (install.ps1 and install.sh) are production-grade orchestration utilities that manage parallel PNPM installations across your entire monorepo. Unlike simple pnpm install -r, these scripts intelligently monitor system resources and dynamically adjust concurrency to prevent system crashes.

Key Features

Smart Parallelization

Dynamically adjusts concurrent installations based on real-time CPU and RAM usage

Load Monitoring

Continuously monitors system metrics to prevent resource exhaustion

Automatic Throttling

Suspends jobs when system load exceeds thresholds, resumes when safe

State Machine Architecture

Robust RUNNING/PAUSED state management with hysteresis loops

How It Works

System Architecture

The install script implements a sophisticated orchestration loop:

Three-State System

RUNNING State
PAUSED State
COMPLETED State

Active Processing Mode

Spawns new jobs based on available resources
Dynamic concurrency: Floor(Cores × (1 - CPU/100))
Minimum 1 job, maximum = logical cores
Monitors RAM: pauses if < 500MB free

Transitions:

→ PAUSED when CPU or RAM exceeds 90%

Usage

PowerShell
Shell

# From repository root
.\scripts\install.ps1

Requirements:

PowerShell 5.1+ (Windows) or PowerShell Core 7+ (cross-platform)
PNPM installed and in PATH
Windows: CIM/WMI access for system monitoring

# From repository root
./scripts/install.sh

Requirements:

Bash 4.0+ (Linux) or Bash 3.2+ (macOS)
PNPM installed and in PATH
Access to /proc/stat and /proc/meminfo (Linux) or sysctl (macOS)

Load Monitoring System

Metrics Collection

The script monitors two critical metrics:

CPU Usage

Measurement:

Windows: Win32_Processor.LoadPercentage via CIM
Linux/macOS: /proc/stat delta calculation

Update Frequency: Every 1 second

RAM Usage

Measurement:

Windows: Win32_OperatingSystem memory counters
Linux: /proc/meminfo MemAvailable
macOS: vm_stat equivalent

Update Frequency: Every 1 second

Threshold System

Critical Threshold (90%)

Triggers: System enters PAUSED stateActions:

All running jobs receive suspend signal
No new jobs spawn
Dashboard shows “PAUSED” status

Rationale: Prevents system from becoming unresponsive due to excessive load. Jobs are suspended (not killed) to preserve progress.

Safe Threshold (75%)

Triggers: System returns to RUNNING stateActions:

All suspended jobs receive resume signal
New jobs can spawn based on dynamic limits
Dashboard shows “RUNNING” status

Rationale: Hysteresis (75% resume vs 90% pause) prevents rapid state oscillation.

Dynamic Concurrency

Formula:

Remaining Capacity = 100 - Current CPU Usage
Dynamic Limit = Floor(Logical Cores × Remaining Capacity / 100)
Minimum Limit = 1

Example (8-core system):

CPU at 20% → 8 × 0.80 = 6 concurrent jobs
CPU at 50% → 8 × 0.50 = 4 concurrent jobs
CPU at 80% → 8 × 0.20 = 1 concurrent job

Output Examples

Normal Operation
High Load Scenario
Completion Summary

[36m---  PNPM ORCHESTRATOR ---[0m
Scanning for package.json...[32m Found 23 projects.[0m
-> Start: packages/api
-> Start: packages/web
-> Start: packages/mobile

[35m[PNPM Orchestrator (RUNNING)] CPU: 45% | RAM: 62% | Active: 3 | Queued: 20 | Progress: 13%[0m

[32m[Success] /home/user/project/packages/api[0m

-> Start: packages/shared

[35m[PNPM Orchestrator (RUNNING)] CPU: 52% | RAM: 68% | Active: 3 | Queued: 17 | Progress: 26%[0m

[35m[PNPM Orchestrator (RUNNING)] CPU: 88% | RAM: 85% | Active: 6 | Queued: 12 | Progress: 47%[0m

[33m[WARN] High Load (CPU:91% RAM:87%). Suspending...[0m

[35m[PNPM Orchestrator (PAUSED)] CPU: 91% | RAM: 87% | Active: 6 | Queued: 12 | Progress: 47%[0m
[35m[PNPM Orchestrator (PAUSED)] CPU: 89% | RAM: 84% | Active: 6 | Queued: 12 | Progress: 47%[0m
[35m[PNPM Orchestrator (PAUSED)] CPU: 78% | RAM: 76% | Active: 6 | Queued: 12 | Progress: 47%[0m
[35m[PNPM Orchestrator (PAUSED)] CPU: 72% | RAM: 71% | Active: 6 | Queued: 12 | Progress: 47%[0m

[36m[INFO] Load Normalized. Resuming...[0m

[35m[PNPM Orchestrator (RUNNING)] CPU: 68% | RAM: 69% | Active: 6 | Queued: 12 | Progress: 47%[0m

[35m[PNPM Orchestrator (RUNNING)] CPU: 32% | RAM: 58% | Active: 0 | Queued: 0 | Progress: 100%[0m

[36m--- SUMMARY ---[0m
[32mSuccessful: 22[0m
[31mFailed:     1[0m

Advanced Features

Job Suspension (Process Control)

Windows Implementation
Unix Implementation

C# Interop with kernel32.dll

Native Thread Control

[DllImport("kernel32.dll")]
public static extern IntPtr OpenThread(int dwDesiredAccess, 
    bool bInheritHandle, int dwThreadId);

[DllImport("kernel32.dll")]
public static extern int SuspendThread(IntPtr hThread);

[DllImport("kernel32.dll")]
public static extern int ResumeThread(IntPtr hThread);

PowerShell Usage:

function Suspend-JobTree ($ProcessObject) {
    foreach ($thread in $ProcessObject.Threads) {
        $hThread = [ProcControl]::OpenThread(0x0002, $false, $thread.Id)
        [ProcControl]::SuspendThread($hThread) | Out-Null
        [ProcControl]::CloseHandle($hThread) | Out-Null
    }
}

Windows implementation suspends individual threads, preserving process state perfectly. Memory remains allocated but CPU consumption drops to zero.

POSIX Signal Control

Process Group Suspension

suspend_job() {
    local pid=$1
    if kill -0 "$pid" 2>/dev/null; then
        # SIGSTOP suspends the entire process group
        kill -SIGSTOP "$pid" 2>/dev/null || true
    fi
}

resume_job() {
    local pid=$1
    if kill -0 "$pid" 2>/dev/null; then
        # SIGCONT resumes the process group
        kill -SIGCONT "$pid" 2>/dev/null || true
    fi
}

Unix implementation uses signals sent to process groups, ensuring child processes (spawned by PNPM) are also suspended/resumed.

Crash Prevention

Why standard pnpm install -r can crash your system:

Spawns all installations simultaneously
No resource monitoring
Can exceed available RAM (OOM killer)
Maxes out CPU (system becomes unresponsive)
No graceful degradation

The TailStack install scripts solve these issues:

✅ Dynamic concurrency based on actual load
✅ Automatic throttling prevents resource exhaustion
✅ Job suspension instead of termination
✅ Progress preservation during pauses
✅ Predictable behavior with state machine

Performance Characteristics

Execution Speed

Typical Performance (vs sequential):

Packages	Sequential	Parallel Script	Speedup
5-10	2-5 min	30-60 sec	3-5×
10-30	5-15 min	1-3 min	4-6×
30-100	15-45 min	3-8 min	5-7×

Factors affecting speed:

Network latency (package downloads)
Shared dependencies (PNPM store hits)
System specs (CPU cores, RAM, disk I/O)
Background load (other applications)

Resource Consumption

CPU Usage:

Startup: 20-40% (scanning phase)
Active: 60-90% (installation phase)
Throttled: 40-60% (dynamic adjustment)
PAUSED: 10-20% (monitoring only)

RAM Usage:

Per job: 100-300 MB average
Concurrent jobs: 1-3 GB total
Safety margin: 500 MB minimum free
Peak: Typically 60-80% of total RAM

Scalability

System Requirements:

Monorepo Size	Min RAM	Min CPU	Recommended
Small (5-10)	4 GB	2 cores	8 GB, 4 cores
Medium (30)	8 GB	4 cores	16 GB, 8 cores
Large (100+)	16 GB	8 cores	32 GB, 16 cores

The script automatically adapts to available resources.

Troubleshooting

Installation Failures

Check Summary Output:

[31mFailed:     3[0m

Common Causes:

Network errors: Retry or check firewall
Peer dependency conflicts: Check package.json
Insufficient disk space: Clear PNPM store
Corrupted cache: Run clean script first

Manual fix:

# Navigate to failed package
cd packages/failed-package

# Try installation with verbose logging
pnpm install --loglevel=debug

Script Hangs or Freezes

Symptoms:

Dashboard stops updating
Progress stuck at same percentage
System responsive but script unresponsive

Solutions:1. Interrupt gracefully (Bash):

# Press Ctrl+C
# Script kills all background jobs automatically

2. Force termination:

# PowerShell: Kill script process
Stop-Process -Name powershell -Force

# Bash: Kill script and children
pkill -f "install.sh"

PNPM Not Found Error

Error Message:

pnpm is not found in PATH. Please install Node/PNPM first.

Solutions:Install PNPM globally:

npm install -g pnpm

Verify installation:

pnpm --version

Add to PATH (if needed):

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/share/pnpm:$PATH"

Permission Errors

Windows:

# Enable script execution
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Linux/macOS:

# Make script executable
chmod +x ./scripts/install.sh

# Fix ownership if needed
sudo chown -R $USER:$USER .

Best Practices

Run After Clean

Always run clean script before install for best results:

./scripts/clean.sh
# Press 'y' to auto-launch install

Close Resource-Heavy Apps

Free up system resources before installation:

Close browsers with many tabs
Pause video streaming
Exit Docker containers
Stop development servers

Monitor First Run

Watch the dashboard during first run to understand system behavior:

Note typical CPU/RAM usage
Observe pause/resume cycles
Check completion time as baseline

Use in CI/CD Carefully

CI environments may need adjustments:

# GitHub Actions example
- name: Install dependencies
  run: ./scripts/install.sh
  timeout-minutes: 30

Consider using standard PNPM in CI (predictable resources):

- run: pnpm install --frozen-lockfile

Technical Implementation

State Machine Logic

State Transitions (Pseudo-code)

while (queue.length > 0 || running.length > 0) {
  metrics = getSystemMetrics();
  cleanupFinishedJobs();
  
  // Hysteresis: different thresholds for pause vs resume
  if (metrics.cpu >= 90 || metrics.ram >= 90) {
    if (state !== 'PAUSED') {
      suspendAllJobs();
      state = 'PAUSED';
    }
  } else if (metrics.cpu <= 75 && metrics.ram <= 75) {
    if (state === 'PAUSED') {
      resumeAllJobs();
      state = 'RUNNING';
    }
  }
  
  if (state === 'RUNNING') {
    dynamicLimit = calculateConcurrency(metrics, cores);
    spawnJobsUpToLimit(dynamicLimit);
  }
  
  updateDashboard(metrics, state);
  sleep(1000);
}

Metrics Collection

function Get-Metrics {
    $os = Get-CimInstance Win32_OperatingSystem
    $proc = Get-CimInstance Win32_Processor
    
    $totalRam = $os.TotalVisibleMemorySize  # KB
    $freeRam = $os.FreePhysicalMemory       # KB
    $ramUsage = 100 - [math]::Round(($freeRam / $totalRam) * 100)
    
    return @{
        CpuUsage  = [math]::Round($proc.LoadPercentage)
        RamUsage  = $ramUsage
        FreeRamMB = [math]::Round($freeRam / 1024)
    }
}

Clean Script

Learn about the cleanup utility that pairs with install

Custom Scripts

Create your own automation scripts for the monorepo

Monorepo Management

Understand PNPM workspaces and dependency management

Frontend

Backend

Automation

Overview

Key Features

Smart Parallelization

Load Monitoring

Automatic Throttling

State Machine Architecture

How It Works

System Architecture

Three-State System

Usage

Load Monitoring System

Metrics Collection

CPU Usage

RAM Usage

Threshold System

Output Examples

Advanced Features

Job Suspension (Process Control)

Crash Prevention

Performance Characteristics

Troubleshooting

Best Practices

Technical Implementation

State Machine Logic

Metrics Collection

Clean Script

Custom Scripts

Monorepo Management

Build docs developers (and LLMs) love

Frontend

Backend

Automation

​Overview

​Key Features

Smart Parallelization

Load Monitoring

Automatic Throttling

State Machine Architecture

​How It Works

​System Architecture

​Three-State System

​Usage

​Load Monitoring System

​Metrics Collection

CPU Usage

RAM Usage

​Threshold System

​Output Examples

​Advanced Features

​Job Suspension (Process Control)

​Crash Prevention

​Performance Characteristics

​Troubleshooting

​Best Practices

​Technical Implementation

​State Machine Logic

​Metrics Collection

​Related Documentation

Clean Script

Custom Scripts

Monorepo Management

Build docs developers (and LLMs) love

Overview

Key Features

How It Works

System Architecture

Three-State System

Usage

Load Monitoring System

Metrics Collection

Threshold System

Output Examples

Advanced Features

Job Suspension (Process Control)

Crash Prevention

Performance Characteristics

Troubleshooting

Best Practices

Technical Implementation

State Machine Logic

Metrics Collection

Related Documentation