Automation Scripts

Overview

TailStack includes powerful cross-platform automation scripts designed for monorepo management. Each script is available in both PowerShell (.ps1) and Bash (.sh) versions, ensuring compatibility across Windows, Linux, and macOS. All scripts are located in the scripts/ directory at the root of the monorepo.

Available Scripts

Clean Script

The clean script performs a high-velocity, two-phase purge of all node_modules directories and pnpm-lock.yaml files.

./scripts/clean.sh

Features

Parallel Processing - Uses CPU thread count × 2 for maximum concurrency
Brutal Verification - 3-retry loop with forced process termination
Auto-Recovery - Kills locking processes (Node.js, VS Code) automatically
Interactive Handoff - Optionally triggers fresh installation after cleanup

How It Works

Phase 1: Initial Purge

Scans the entire monorepo for targets:

All node_modules directories (recursive)

All pnpm-lock.yaml files

Uses parallel deletion with thread count calculated as:

max_threads = CPU_cores × 2

Phase 2: Verification Loop

Verifies cleanup integrity with up to 3 retry attempts:

First Check - Scans for surviving node_modules

Process Termination - Kills Node.js and VS Code processes if survivors found

Forced Delete - Runs brutal recursive deletion on survivors

Final Verification - Confirms all targets removed

Phase 3: Installation Handoff

Prompts user:

Would you like to trigger a fresh reinstallation? (Y/N)

If accepted, automatically executes the install script.

Implementation Details

Bash (clean.sh)
PowerShell (clean.ps1)

Key Technologies:

find for recursive file discovery
xargs -P for parallel execution (replicates PowerShell RunspacePool)
rm -rf for deletion
pkill for process termination

Performance:

# Calculate optimal thread count
cpu_count=$(nproc)  # or sysctl -n hw.ncpu on macOS
max_threads=$((cpu_count * 2))

# Parallel deletion
cat "$targets_file" | xargs -P "$max_threads" -I {} rm -rf "{}"

Process Management:

stop_locking_processes() {
    pkill -f "node" > /dev/null 2>&1 || true
    pkill -f "Code" > /dev/null 2>&1 || true
    sleep 1
}

Key Technologies:

Get-ChildItem -Recurse for file discovery
RunspacePool for parallel execution
cmd /c rd /s /q for reliable Windows deletion
Stop-Process -Force for process termination

Performance:

$MaxThreads = [Environment]::ProcessorCount * 2
$Pool = [RunspaceFactory]::CreateRunspacePool(1, $MaxThreads)
$Pool.Open()

Deletion Action:

$NukeAction = {
    param($Path)
    if (Test-Path $Path -PathType Container) {
        cmd /c "rd /s /q `"$Path`"" 2>&1
    } else {
        cmd /c "del /f /q `"$Path`"" 2>&1
    }
}

Important: This script forcefully terminates Node.js and VS Code processes. Save all work before running.

Install Script

The install script is a parallel PNPM orchestrator with intelligent load monitoring and anti-crash state management.

./scripts/install.sh

Features

Intelligent Parallelism - Dynamically adjusts concurrency based on system load
Load Monitoring - Continuously tracks CPU and RAM usage
Anti-Crash State Machine - Automatically suspends/resumes jobs to prevent system hangs
Hysteresis Control - Uses threshold-based state transitions (90% critical, 75% safe)
Progress Dashboard - Real-time status updates with metrics

How It Works

Dependency Check

Verifies PNPM is installed and accessible:

if ! command -v pnpm &> /dev/null; then
    echo "pnpm is not found in PATH"
    exit 1
fi

File Discovery

Scans for all package.json files (excluding node_modules):

find . -type d -name "node_modules" -prune -o -type f -name "package.json" -print

Orchestration Loop

Runs continuously until all jobs complete:

Telemetry Collection - Measures CPU/RAM usage

Job Cleanup - Removes completed processes from queue

State Management - Suspends/resumes based on load

Job Spawning - Starts new installs if resources available

Dashboard Update - Displays real-time progress

State Machine

Two-state system with hysteresis:

RUNNING - Normal operation, spawns new jobs

PAUSED - High load detected, jobs suspended

Transition Logic:

RUNNING → PAUSED:  CPU ≥ 90% OR RAM ≥ 90%
PAUSED → RUNNING:  CPU ≤ 75% AND RAM ≤ 75%

Implementation Details

Bash (install.sh)
PowerShell (install.ps1)

Metrics Collection:

get_metrics() {
    # Memory from /proc/meminfo
    local mem_total_kb=$(grep MemTotal /proc/meminfo | awk '{print $2}')
    local mem_avail_kb=$(grep MemAvailable /proc/meminfo | awk '{print $2}')
    CURRENT_RAM=$(( (used_kb * 100) / mem_total_kb ))

    # CPU from /proc/stat delta
    read -r cpu a1 b1 c1 d1 e1 f1 g1 rest < /proc/stat
    sleep 0.1
    read -r cpu a2 b2 c2 d2 e2 f2 g2 rest < /proc/stat
    CURRENT_CPU=$(( (used_delta * 100) / total_delta ))
}

Process Suspension:

suspend_job() {
    local pid=$1
    kill -SIGSTOP "$pid" 2>/dev/null || true
}

resume_job() {
    local pid=$1
    kill -SIGCONT "$pid" 2>/dev/null || true
}

Dynamic Concurrency:

remaining_capacity=$(( 100 - CURRENT_CPU ))
if (( remaining_capacity < 10 )); then remaining_capacity=10; fi
dynamic_limit=$(( (logical_cores * remaining_capacity) / 100 ))

Metrics Collection (CIM-based):

function Get-Metrics {
    $os = Get-CimInstance Win32_OperatingSystem
    $proc = Get-CimInstance Win32_Processor
    
    $totalRam = $os.TotalVisibleMemorySize
    $freeRam = $os.FreePhysicalMemory
    $ramUsage = 100 - [math]::Round(($freeRam / $totalRam) * 100)

    return @{
        CpuUsage  = [math]::Round($proc.LoadPercentage)
        RamUsage  = $ramUsage
        FreeRamMB = [math]::Round($freeRam / 1024)
    }
}

Process Suspension (C# P/Invoke):

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

Dynamic Concurrency:

$loadFactor = 1.0 - ($metrics.CpuUsage / 100.0)
if ($loadFactor -lt 0.1) { $loadFactor = 0.1 }
$dynamicLimit = [math]::Floor($logicalCores * $loadFactor)

Dashboard Output

Real-time metrics displayed during execution:

[PNPM Orchestrator (RUNNING)] CPU: 65% | RAM: 58% | Active: 4 | Queued: 12 | Progress: 35%

Summary Report

After completion:

--- SUMMARY ---
Successful: 18
Failed:     0

Pro Tip: The install script is safe to run on low-spec hardware. It will automatically throttle itself to prevent system crashes.

Script Usage Patterns

Clean Install Workflow

For a completely fresh dependency installation:

# 1. Clean everything
./scripts/clean.sh

# 2. When prompted, select 'Y' to auto-trigger install
# OR manually run install after cleaning:
./scripts/install.sh

Troubleshooting Failed Installs

If installations fail or hang:

# 1. Force clean with automatic retry
./scripts/clean.sh  # Kills locking processes automatically

# 2. Run install with fresh state
./scripts/install.sh

CI/CD Integration

For automated environments:

# Non-interactive clean (requires modification)
# Modify scripts to skip Y/N prompt for CI
./scripts/clean.sh
./scripts/install.sh

CI/CD Note: The scripts include interactive prompts. For automated pipelines, either:

Use standard pnpm install instead
Modify scripts to remove prompts
Use echo y | ./scripts/clean.sh to auto-answer

Performance Benchmarks

Typical performance on a monorepo with 20 packages:

Operation	Time (Standard)	Time (TailStack Scripts)	Improvement
Clean	45-60s	8-15s	4-5x faster
Install	180-240s	90-120s	2x faster
Clean + Install	225-300s	98-135s	2.3x faster

Benchmarks run on 8-core CPU, 16GB RAM

Common Use Cases

Corrupted Dependencies

./scripts/clean.sh   # Remove all node_modules
./scripts/install.sh # Fresh install

Package Version Conflicts

./scripts/clean.sh   # Clear lock files
pnpm install        # Let PNPM resolve fresh

Pre-deployment Verification

./scripts/clean.sh   # Ensure clean state
./scripts/install.sh # Install production deps
pnpm build          # Verify build succeeds

Switching Branches

When switching between branches with different dependencies:

git checkout feature-branch
./scripts/install.sh  # Auto-handles new deps

Next Steps

Learn about the development workflow for running dev servers
Explore PNPM workspace commands
Review customization options for your project

Getting Started

Architecture

Core Concepts

Development

Guides

Automation Scripts

Overview

Available Scripts

Clean Script

Features

How It Works

Implementation Details

Install Script

Features

How It Works

Implementation Details

Dashboard Output

Summary Report

Script Usage Patterns

Clean Install Workflow

Troubleshooting Failed Installs

CI/CD Integration

Performance Benchmarks

Common Use Cases

Corrupted Dependencies

Package Version Conflicts

Pre-deployment Verification

Switching Branches

Next Steps

Build docs developers (and LLMs) love

Getting Started

Architecture

Core Concepts

Development

Guides

​Overview

​Available Scripts

​Clean Script

​Features

​How It Works

​Implementation Details

​Install Script

​Features

​How It Works

​Implementation Details

​Dashboard Output

​Summary Report

​Script Usage Patterns

​Clean Install Workflow

​Troubleshooting Failed Installs

​CI/CD Integration

​Performance Benchmarks

​Common Use Cases

​Corrupted Dependencies

​Package Version Conflicts

​Pre-deployment Verification

​Switching Branches

​Next Steps

Build docs developers (and LLMs) love

Overview

Available Scripts

Clean Script

Features

How It Works

Implementation Details

Install Script

Features

How It Works

Implementation Details

Dashboard Output

Summary Report

Script Usage Patterns

Clean Install Workflow

Troubleshooting Failed Installs

CI/CD Integration

Performance Benchmarks

Common Use Cases

Corrupted Dependencies

Package Version Conflicts

Pre-deployment Verification

Switching Branches

Next Steps