add shebang to Python scripts, update requirements and make new setup wizard script

SaturniNovaDev · SaturniNovaDev · commit e7d0b795df2e · 2026-03-13T18:30:53.000-04:00
diff --git a/.gitignore b/.gitignore
@@ -1,18 +1,23 @@
-# All sorts of virtual environments
-*env*
+# Python Bytecode
+__pycache__/
+*.py[cod]
 
-# Output from indexation
-index*.json
-*.json
-
-# Output from analysis
-*.pdf
-*.jpg
-*.png
+# Environments
+venv/
+.venv/
+env/
+.env/
+ENV/
+.ENV/
 
-# User Configuration File
+# User-specific Config
 config.ini
 
-# Log files
-*error*
-*.log
+# Application Outputs
+*.json
+*.pdf
+*.log
+
+# OS-specific
+.DS_Store
+Thumbs.db
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# Peters-Disk-Utils (v1.0.0-alpha)
+# Peters-Disk-Utils (v1.0.0-stable)
 
 A lightweight, cross-platform CLI suite for indexing, visualizing, and navigating disk storage. Built for developers and power users who need to analyze large directory structures and explore them offline.
 
@@ -10,54 +10,43 @@ A lightweight, cross-platform CLI suite for indexing, visualizing, and navigatin
 - **OS-Aware Exclusions**: Pre-configured to skip virtual filesystems (Linux) and protected system folders (Windows).
 - **Centralized Config**: Control targets, output names, and verbosity via _config.ini_.
 - **Silent Logging**: Comprehensive error tracking using the `logging` module to keep your terminal clean.
+- **Cross-Platform**: Works seamlessly on Windows and Linux with the same codebase.
+- **Global Usage**: Run the analyzer and navigator from any directory, with outputs saved to the current working directory.
 
 ## 🚀 Quick Start
 
-### 1. Prerequisites
+### 1. **Clone the Repository**
 
-Ensure you have Python 3.10 or higher installed. Install the required dependencies:
+```Bash
+git clone https://github.com/SaturniNovaDev/peters-disk-utils
+```
+
+### 2. **Run the Installer**
 
-```bash
-pip install matplotlib colorama
+On Linux:
+
+```Bash
+cd peters-disk-utils
+chmod +x setup.sh
+./setup.sh
+# Follow the instructions in the wizard
 ```
 
-### 2. Configuration
-
-The suite requires a _config.ini_ file in the root directory.
-
-Use this template and rename it to _config.ini_ in order to configure the program with the best settings.
-
-```ini
-; -- Default configuration template --
-; Rename to 'config.ini' to start using this configuration
-
-[GENERAL]
-; Set to True for full logs, False for single-line status
-Verbose = False
-; How many errors to show in the terminal summary
-ErrorLimit = 20
-; Whether to print the error summary at the end of the scan
-ShowSummary = True
-
-[PATHS]
-; Default names for your outputs
-JsonOutput = disk-index.json
-ChartOutput = analysis.pdf
-; Log file for permission errors
-LogFile = nls-errors.log
-
-; Default directories to scan if no --target param is provided
-[DEFAULT_TARGETS]
-Windows = C:/Users
-Linux = /home
-
-[EXCLUDE]
-; Linux-specific virtual/system files
-LinuxDirs = /proc, /sys, /dev, /run, /snap, /var/lib/lxd
-; Windows-specific system files that often cause permission errors
-WindowsDirs = C:/System Volume Information, C:/$Recycle.Bin, C:/Windows/CSC
+On Windows:
+
+```PowerShell
+cd peters-disk-utils
+.\setup.bat
+# Follow the instructions in the wizard
 ```
 
+The installer will guide you through setting up the necessary Python environment, installing dependencies, and configuring your default targets, as well as optionally adding the tools to your system for global access.
+This works by creating scripts in your system PATH that point to the main Python files, allowing you to run `disk-nls` and `disk-nav` from any terminal.
+
+Keep in mind that **erasing the files in the repository will break this functionality.** I'm working on a future update which will include an uninstaller script to clean up these PATH entries if needed.
+
+If you do, however, want to remove the tools manually, simply delete the `disk-nls` and `disk-nav` scripts from your system PATH (e.g., `/usr/local/bin/` on Linux or the PATH environment variable on Windows).
+
 ## 📖 Usage Guide
 
 ### Step 1: Indexing _disk-nls.py_
@@ -66,11 +55,17 @@ Run the analyzer to create a JSON snapshot of your drive and a visual PDF chart.
 
 ```Bash
 # Uses the default target from config.ini
-python disk-nls.py
+python3 disk-nls.py
 
 # Manually specify a target and enable verbose logging
-python disk-nls.py --target /var/www --verbose
+python3 disk-nls.py --target /var/www --verbose
+
+```
 
+Or, if you have set up the global command:
+
+```Bash
+disk-nls # Optionally specify a target with --target and enable verbose logging with --verbose
 ```
 
 ### Step 2: Navigating _disk-nav.py_
@@ -79,7 +74,13 @@ Explore the generated index interactively using our built-in CLI tool:
 
 ```Bash
 # Loads the default JsonOutput from config.ini
-python disk-nav.py
+python3 ./disk-nav.py
+```
+
+Or, if you have set up the global command:
+
+```Bash
+disk-nav # Optionally specify a source JSON snapshot with --source
 ```
 
 #### Navigator Commands
@@ -91,7 +92,24 @@ python disk-nav.py
 - help: Show available commands.
 - exit: Close the navigator.
 
-## ⚠️ Known Issues (Alpha)
+## Notes
+
+1. System directories and virtual filesystems are automatically excluded based on the OS, but you can customize this in the _config.ini_ file under the `[EXCLUSIONS]` section. If you get permission errors during indexing, run the program as administrator/root or adjust the exclusions to skip problematic directories. **NOTE THAT THIS IS VERY INCONVENIENT**, as the next time you want to analyze the disk, or even access the log, chart or index files, you will have to run the program with elevated permissions again. Run as an administrator/root only if you _NEED_ to analyze protected system folders or virtual filesystems, and be cautious when doing so, as it can lead to unintended consequences if you modify or delete important files.
+
+```Bash
+sudo disk-nls # Reads config.ini and runs with elevated permissions on Linux
+# Or:
+sudo python3 disk-nls.py --target / # Run with elevated permissions on Linux
+# Or:
+python3 disk-nls.py --target /home # Skip non-user directories on Linux
+```
+
+## ⚠️ Known Issues (Stable)
 
-1. Some system-level folders remain inaccessible without Admin/Sudo privileges. Check _nls-errors.log_ for details when indexing system directories.
-2. Very large disk indexes (multi-terabyte) may consume significant RAM during JSON generation. While we work on a solution for this, you might want to avoid indexing non-user directories.
+1. The Ring Chart may not display correctly if there are too many small files or directories, as they can clutter the visualization.
+2. The navigator does not currently support searching or filtering within the index, which can make it difficult to find specific items in large datasets. Future updates will include search functionality.
+3. The tool does not currently handle symbolic links or shortcuts, which may lead to inaccurate size calculations or navigation issues.
+4. The installer does not currently check for existing PATH entries before adding new ones, which could lead to conflicts if the tools are already installed or if there are naming collisions. I recommend reviewing your PATH after installation and removing any duplicates if necessary.
+5. The tool does not currently support incremental updates to the index, meaning that you will need to re-run the analyzer to reflect any changes in the filesystem.
+6. The navigation REPL is still very raw and prone to styling errors.
+7. The tool is known to log some directories with incorrect sizes due to permission issues or special filesystem features. In some occasions, these might be reflected in the index with a size larger than the disk's own capacity. This is a known issue that I am working on fixing in a future update.
diff --git a/disk-nav.py b/disk-nav.py
@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 import os
 import json
 import argparse
diff --git a/disk-nls.py b/disk-nls.py
@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 import os
 import json
 import argparse
@@ -140,6 +141,9 @@ def generate_visuals(index_data, output_file):
     target = os.path.abspath(args.target)
     if not os.path.exists(target):
         print(f"{Fore.RED}Error: Target path '{target}' does not exist.")
+        print(
+            f"{Fore.YELLOW}Please check your --target argument or the [DEFAULT_TARGETS] in config.ini."
+        )
         exit(1)
 
     print(f"{Fore.YELLOW}Target identified: {Fore.WHITE}{target}")
@@ -172,6 +176,13 @@ def generate_visuals(index_data, output_file):
             f"{Fore.WHITE}Duration:   {Fore.CYAN}{final_output['scan_duration_seconds']}s"
         )
         print(f"{Fore.WHITE}Log File:   {Fore.CYAN}{config.get('PATHS', 'LogFile')}")
+        if final_output["scan_duration_seconds"] > 60:
+            print(
+                f"{Fore.YELLOW}Note: Long scan times may indicate a very large target or performance issues. Consider excluding more directories or running with verbose mode for detailed logging."
+            )
+        print(
+            f"{Fore.BLUE}Tip: If you get permission errors during scans, consider skipping system directories or running the tool with elevated permissions (e.g., as administrator or with sudo)."
+        )
 
     generate_visuals(full_structure, args.output)
     print(f"{Fore.GREEN}Index and chart saved successfully.")
diff --git a/requirements.txt b/requirements.txt
@@ -1,3 +1,2 @@
 matplotlib
-tqdm
 colorama
diff --git a/setup.bat b/setup.bat
@@ -0,0 +1,104 @@
+@echo off
+setlocal enabledelayedexpansion
+
+echo --- Peter's Disk Utils - Windows Setup ---
+
+:: 1. Choose Setup Mode
+set /p choice="Use recommended defaults? (y/n): "
+
+if /i "%choice%"=="y" (
+    echo Creating config.ini with Windows defaults...
+    copy config.template config.ini
+    goto VENV
+)
+
+echo --- Custom Configuration ---
+
+set /p VERBOSE="Verbose Mode (True/False) [False]: "
+if "!VERBOSE!"=="" set VERBOSE=False
+
+set /p ELIMIT="Error Limit [20]: "
+if "!ELIMIT!"=="" set ELIMIT=20
+
+set /p SUMMARY="Show Summary at end of scan? (True/False) [True]: "
+if "!SUMMARY!"=="" set SUMMARY=True
+
+set /p TARGET="Default Windows Scan Target [C:/Users]: "
+if "!TARGET!"=="" set TARGET=C:/Users
+
+set /p JSON_OUT="Output JSON Name [disk-index.json]: "
+if "!JSON_OUT!"=="" set JSON_OUT=disk-index.json
+
+set /p CHART_OUT="Output Chart Name [analysis.pdf]: "
+if "!CHART_OUT!"=="" set CHART_OUT=analysis.pdf
+
+set /p LOG_FILE="Output Error Log [nls-errors.log]: "
+if "!LOG_FILE!"=="" set LOG_FILE=nls-errors.log
+
+set /p WIN_DIRS="Ignore which directories? [C:/System Volume Information, C:/$Recycle.Bin]: "
+if "!WIN_DIRS!"=="" set WIN_DIRS=C:/System Volume Information, C:/$Recycle.Bin
+
+:: Build the config file
+echo [GENERAL] > config.ini
+echo Verbose = !VERBOSE! >> config.ini
+echo ErrorLimit = !ELIMIT! >> config.ini
+echo ShowSummary = !SUMMARY! >> config.ini
+echo. >> config.ini
+echo [PATHS] >> config.ini
+echo JsonOutput = !JSON_OUT! >> config.ini
+echo ChartOutput = !CHART_OUT! >> config.ini
+echo LogFile = !LOG_FILE! >> config.ini
+echo. >> config.ini
+echo [DEFAULT_TARGETS] >> config.ini
+echo Windows = !TARGET! >> config.ini
+echo Linux = /home >> config.ini
+echo. >> config.ini
+echo [EXCLUDE] >> config.ini
+echo LinuxDirs = /proc, /sys, /dev, /run, /snap >> config.ini
+echo WindowsDirs = !WIN_DIRS! >> config.ini
+
+:VENV
+echo.
+echo Setting up Virtual Environment...
+python -m venv .venv
+call .venv\Scripts\activate
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+
+:: 2. Create Global Commands
+echo.
+set /p global_choice="Register 'disk-nls' and 'disk-nav' as global commands? (y/n): "
+if /i "%global_choice%"=="y" (
+    set "INSTALL_DIR=%CD%"
+    set "VENV_PY=%CD%\.venv\Scripts\python.exe"
+
+    :: Create disk-nls.bat shim
+    echo @echo off > disk-nls.bat
+    echo "!VENV_PY!" "!INSTALL_DIR!\disk-nls.py" %%* >> disk-nls.bat
+
+    :: Create disk-nav.bat shim
+    echo @echo off > disk-nav.bat
+    echo "!VENV_PY!" "!INSTALL_DIR!\disk-nav.py" %%* >> disk-nav.bat
+
+    echo.
+    echo To use these commands from any folder, you must add this directory to your PATH:
+    echo !INSTALL_DIR!
+    echo.
+    echo Would you like me to try adding it to your User PATH automatically?
+    set /p path_choice="(y/n): "
+    if /i "!path_choice!"=="y" (
+        :: Add to path using setx (takes effect in NEW terminal windows)
+        for /f "tokens=2*" %%A in ('reg query "HKCU\Environment" /v Path') do set "oldpath=%%B"
+        echo !oldpath! | findstr /i "!INSTALL_DIR!" >nul
+        if errorlevel 1 (
+            setx PATH "!oldpath!;!INSTALL_DIR!"
+            echo Success! Please restart your terminal for global commands to work.
+        ) else (
+            echo Directory already in PATH.
+        )
+    )
+)
+
+echo.
+echo Setup Complete!
+pause
diff --git a/setup.sh b/setup.sh

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+#!/usr/bin/env python3`
`1`	`2`	`import os`
`2`	`3`	`import json`
`3`	`4`	`import argparse`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,2 @@`
`1`	`1`	`matplotlib`
`2`		`-tqdm`
`3`	`2`	`colorama`