Documentation

Getting started

InfinitySniper HFX is a modular Windows utility framework written in Node.js with zero runtime dependencies. It ships as a portable folder — unzip it anywhere and start it. On first run it creates its own config, logs, reports, backups and temp folders beside itself.

Packaged

Double-click InfinitySniper HFX.exe. Nothing else is needed — the executable carries its own runtime.

From source

Install Node.js 16 or newer and double-click Run.cmd. There is no npm install step, because there are no packages.

Where to start once it opens

• [16] Quick PC Summary — CPU, GPU, RAM, motherboard, storage, Windows, IP and uptime on one screen.
• [12] System Health — framework checks plus PC checks, combined into a 0–100 score.
• [15] Live System Monitor — an auto-refreshing dashboard of CPU, memory, disk, network and uptime.
• [17] Search Functions — find any of the 56 by name, description or tag.

Navigation

Every interactive choice in the whole application — main menu, sub-menus, confirmations, launchers — is a number. There are no letter shortcuts anywhere, and 0 always means back, exit or cancel.

Function numbers inside a category are assigned automatically from the modules that are installed, so adding or removing one never breaks the menu — and never renumbers anything you had to memorise, because the identifiers used on the command line are stable names, not numbers.

Command line

Every function can be run directly, which makes the whole framework scriptable from a batch file, a shortcut or a scheduled task.

node main.js                      :: interactive menu
node main.js --run hardware-info  :: run one function directly
node main.js --list               :: list every discovered function
node main.js --list --json        :: the same list as one JSON object
node main.js --selftest           :: run all function self-tests
node main.js --repair             :: run a full repair
node main.js --version
node main.js --help

With the packaged build, replace node main.js with InfinitySniper-HFX.exe. Three launchers sit beside it:

• Run.cmd — starts the application with the console set to UTF-8 and virtual-terminal sequences.
• Repair.cmd — verifies and fixes an installation, packaged or from source.
• Build.cmd — produces the executable; Build.cmd 1 builds unattended.

The three editions

The console application is the product. The two windowed editions are launchers, not ports: they discover the modules with --list --json, run them with --run <id>, and every line they show was printed by the engine. No feature is reimplemented, and nothing in the framework depends on either of them.

Desktop Edition

• Loading screen — the window appears only once the catalogue has been read.
• Function list with categories and live search over name, id, description and tags.
• Run in the window, run in a real console (the way to use menus and live views), or run elevated through a UAC prompt.
• Reports tab over the reports/ folder with a preview pane.
• Tools menu: full repair, self-tests, or the console application itself.

Launcher Edition

• Dashboard — processor, Windows, uptime, memory, drives, newest reports, six functions one click away.
• Functions — all of them, searched and filtered, with a detail panel per function.
• Console — the live output of a run in its real colours; prompts are answered in the box underneath, so interactive functions work in the window.
• Reports / Logs — both folders, newest first, readable in place.
• Settings — Safe Mode, Dry Run and the rest, written into config/settings.json.

Project structure

main.js              entry point: bootstrap, menus, built-in screens
Run.cmd              launcher
Repair.cmd           installation verification and repair
Build.cmd            production build -> dist\InfinitySniper-HFX.exe
Export.cmd           turns dist\ into the three shippable folders

Function/            >>> ALL FUNCTIONS LIVE HERE <<<
  _TEMPLATE.js       documented skeleton — copy it to add one
  System/            hardware, HWID, CPU, GPU, RAM, monitors, live monitor
  Storage/           disk health, usage, large files, duplicates
  Network/           adapters, ping, DNS, ports, public IP, scanner, speed
  Maintenance/       cache cleaner, recycle bin
  Diagnostics/       health, event logs, crashes, security, firewall
  Windows/           software, services, tasks, drivers, devices, PATH
  Tools/             file hash, file info, archive info, examples
  Reports/           export center, history views, log viewer

core/                shared subsystems (not user features)
  version.js         single source of truth for name/version/build
  paths.js           every folder; source vs packaged mode
  config.js          settings.json load / merge / validate / save
  ui.js              themes, centred layout, boxes, tables, spinners
  splash.js          animated loading screen shown while booting
  prompt.js          numeric input (readline + buffered pipe reader)
  logger.js          timestamped logs, per-operation logs, retention
  system.js          PowerShell/CIM execution, elevation, formatting
  fs-scan.js         safe filesystem walker used by the storage tools
  report.js          report builder (same output on screen and in .txt)
  kit.js             helpers shared by the function modules
  function-loader.js discovery, validation, dependency/version checks
  category-manager.js categories and automatic numbering
  permission-manager.js admin / Safe Mode / Dry Run gating
  report-manager.js  report registry and the Export Center
  diagnostics.js     environment checks, self-tests, health score
  repair.js          the Repair Center engine
  backup.js          create / restore / list / delete backups
  errors.js          Error ID system (HFX-ERR-…)
  history.js         execution history, favourites, recents
  scripts/           PowerShell collectors

Desktop/             the WinForms launcher    (optional)
Launcher/            the WebView2 launcher    (optional)

config/   settings.json, state.json          created automatically
logs/     application, cleanup, repair, build logs
reports/  generated .txt reports
backups/  configuration and module backups
temp/     scratch space

The eight categories

56 functions in total. The function browser lets you search all of them; this is the map.

[1] System & Hardware — 11

Quick PC Summary · Computer Hardware / HWID Information · Windows Information · CPU Monitor (live) · GPU Information · RAM Information · Monitor Information · Audio Information · USB Information · Battery Information · Live System Monitor

[2] Storage & Files — 7

Storage Health / SMART Check · Disk Space Analyzer · Large File Finder · Duplicate File Finder · Empty Folder Finder · Folder Size Analyzer · Downloads Analyzer

[3] Network — 8

Network Information · Ping Test · DNS Lookup · Port Viewer · Public IP Information · Local Network Scanner · Internet Speed Test · Hosts File Viewer

[4] Maintenance — 2

Cache & Temporary File Cleaner · Recycle Bin Information

[5] Diagnostics — 7

System Health Check · Event Log Summary · BSOD / Crash Summary · Windows Security Status · Firewall Status · Resource Alerts · System Restore Information

[6] Windows Tools — 11

Installed Software List · Services Viewer · Scheduled Tasks Viewer · Driver Information · Device Summary · Startup Manager · Environment Variables · PATH Checker · Process Viewer · Windows Update Status · System Time Check

[7] Custom Functions — 4

File Hash Calculator · File Information · Archive Information · Quick System Snapshot (example module)

[8] Reports — 6

Export Center · Report History · Cleanup History · Repair History · Backup History · Log Viewer

The hardware report

File name HH-MM_DD-MM-YYYY_CunputerHWID.txt — for example 19-56_24-08-2026_CunputerHWID.txt — with the sections [ SYSTEM ], [ OPERATING SYSTEM ], [ CPU ], [ MOTHERBOARD ], [ BIOS ], [ SECURITY & FIRMWARE ], [ MEMORY ], [ GPU ], [ MONITORS ], [ STORAGE ], [ NETWORK ], [ AUDIO ], [ POWER ], [ HARDWARE IDENTIFIERS ] and [ SCAN ENVIRONMENT ].

Settings

config/settings.json is created on first start and merged over the defaults on every load, so new keys appear automatically after an update instead of resetting your file. Everything is editable from Settings [10].

From inside a module, read and write settings through ctx.configApi rather than touching the file:

const minMb = ctx.configApi.get('tools.largeFileMinimumMb');
ctx.configApi.set('tools.maxResults', 200);
ctx.configApi.save();

Themes & appearance

The interface is centred in the console window and re-centres on resize; set ui.align: "left" for the classic layout. Four themes ship, all in 24-bit colour. The switcher in this site's header uses the same four palettes — try one.

A theme maps the semantic colour names the application uses to RGB values — only the pigment changes, never the meaning:

• brightCyan — frames, borders, paths
• brightWhite — values and titles
• brightYellow — menu keys and warnings
• brightGreen — success, OK, recovered
• brightRed — errors
• brightMagenta — spinner and accents
• gray — labels and hints

Writing a module

Copy Function/_TEMPLATE.js into a category folder under a kebab-case file name, fill in the descriptor, write your code in execute(ctx), and start the application. It appears in that category with its own number. No menu code is edited, ever.

module.exports = {
  name: 'My Function',                 // REQUIRED
  description: 'What it does.',
  version: '1.0.0',
  author: 'Your Name',
  category: 'Tools',                   // folder name is used if omitted
  order: 100,                          // sort weight inside the category
  requiredPermissions: 'normal',       // or 'administrator'
  destructive: false,                  // true = blocked by Safe Mode
  dependencies: [],                     // npm packages the module needs
  minimumAppVersion: '1.0.0',         // refused politely if too old
  tags: ['example'],                  // used by Search Functions
  documentation: 'Longer help text.',

  async selfTest(ctx) { return { ok: true, message: 'ready' }; },

  async execute(ctx) {                   // REQUIRED
    ctx.ui.info('Hello');
    return { ok: true };
  },
};

The descriptor

Rules the loader enforces

• Files starting with _ or ., and files ending .disabled.js, are ignored.
• CommonJS only (module.exports). An ESM export produces a clear load error.
• The module id is the file name without its extension — cpu-monitor.
• Menu numbers are assigned automatically per category. Never hard-code one.
• A module that throws during load, init() or execute() is reported and listed in the Function Manager with the exact reason. The application keeps running.

Writing the UI

All output goes through ctx.ui — never console.log, which bypasses the centred layout and the theme. Use the semantic colours only; the theme owns the pigment.

ui.section('PROCESSOR');
ui.field('Model', name);
ui.table(headers, rows);
ui.status('ok', 'Scan complete');
const spin = ui.spinner('Querying WMI'); spin.stop();
ui.progressBar(done, total);

Collecting Windows data

Windows data comes from PowerShell and CIM through ctx.system. Always normalise with asArray(), always clean values, and always survive a failed query with a warning instead of an exception.

const r = await system.runPowerShellJson(script, { timeoutMs: 30000 });

if (!r.ok) {
  ui.warning('Not available on this system.');
  return { ok: false };
}

const rows = system.asArray(r.data);   // single object -> array

Long collectors belong in core/scripts/*.ps1, not in a JavaScript string.

The ctx object

Every module method receives one argument. This is everything on it.

Reports API

Build the report once, then print it and save it. That is what keeps the text file from becoming a lossy second version of what you just read on screen.

const report = ctx.report.createReport({
  title: 'CPU INFORMATION REPORT',
  subtitle: 'Generated by InfinitySniper HFX',
});

const cpu = report.section('CPU');          // -> [ CPU ] in the .txt
cpu.add('Model', name);                     // Label : value
cpu.add('Serial', serial, {
  sensitive: true,
  masked: system.mask(serial),
});

const core = cpu.group('Core 0');            // indented sub-group
core.add('Load', '12 %');
cpu.note('Free-text line');

report.print({ maskSensitive: true });       // coloured, to screen

const file = path.join(
  ctx.paths.reports,
  `${ctx.logger.fileStamp()}_CpuInfo.txt`,
);
const saved = report.save(file);              // -> { ok, size, error }

Values marked sensitive are masked on screen and written in full to the file. File names follow HH-MM_DD-MM-YYYY_<Suffix>.txt via logger.fileStamp(), which sorts sensibly and never collides.

Testing a module

No interactive console is needed. core/prompt.js buffers piped lines, so menus can be driven with digits from stdin.

node --check .\Function\Tools\my-function.js   # syntax
node main.js --list                            # discovery + category
"1`n`n0`n" | node main.js --run my-function   # drive the menus

$env:FORCE_COLOR = 1                            # keep colours when redirecting

Before you call it finished

• node --check every touched file, then node main.js --list.
• Run the module end to end with piped input.
• Confirm no letter shortcuts crept into any prompt.
• Test a destructive module with Dry Run enabled first.
• Restore any settings you changed for testing.

Self-tests

Self-tests must be fast (under about five seconds), read-only, and must never prompt. They are run by Diagnostics, by --selftest, and by the build.

async selfTest(ctx) {
  const r = await ctx.system.runPowerShellJson(
    '@(Get-CimInstance Win32_Processor).Count | ConvertTo-Json',
  );
  return r.ok
    ? { ok: true,  message: 'CPU query responded' }
    : { ok: false, message: 'WMI unavailable' };
}

Safety model

What a destructive module must do

• Set destructive: true and list the capability in permissions.
• Bail out early when ctx.safeMode is on, with a clear message.
• Scan first and show counts, sizes and targets before touching anything.
• Confirm numerically with prompt.confirm → [1] Yes [2] No [0] Cancel.
• Do nothing but report when ctx.dryRun is on.
• Validate every path immediately before acting — never trust a path computed earlier.
• Write an operation log with logger.createOperationLog('<name>').
• Skip locked and in-use files and report them. Never force.

Logging & error IDs

logs/app-YYYY-MM-DD.log        application log, one per day
logs/cleanup_<stamp>.log       one detailed log per cleanup run
logs/repair_<stamp>.log        one detailed log per repair run
logs/errors.json               Error ID store
logs/history.json              function execution history
config/state.json              favourites, recents, run counters

Every important failure gets a quotable Error ID such as HFX-ERR-20260824-0001. The user sees the ID and a plain sentence; the stack trace goes to the log.

A failing function never takes the application down. It shows a recovery menu instead: [1] back to the menu, [2] error details, [3] diagnostics, [4] Repair Center, [0] exit.

Log retention is controlled by logging.keepDays; the Repair Center purges anything older.

Repair, backup and health

Repair Center [11]

Quick, Full, Dependency, Function and Health-check modes. It recreates missing folders, repairs or resets a damaged configuration, cleans stale settings entries, purges old logs, reports invalid modules and missing dependencies, then writes a repair log and a history entry.

Backup Center [13]

Creates plain-folder backups of config/ and Function/ with a manifest — no archive tool needed — restores them after taking a safety copy first, and lists and deletes them.

System Health [12]

Framework checks plus PC checks — free space, memory, SMART, pending reboot, uptime, critical services, recent system errors, Defender — combined into a 0–100 score.

Repair.cmd

Works on both installations. It verifies the executable or main.js and core, the Function folder and its category folders, the configuration, the runtime directories and their write permissions, module compatibility, logs, reports, the backup system and the required runtime.

Building & shipping

Run Build.cmd and choose [1] Full build, or Build.cmd 1 for an unattended one. It performs eleven steps — verify Node.js, verify npm, verify dependencies, run diagnostics, run the function self-tests, validate the project structure, validate the production configuration, clean the previous build, build, verify the generated executable, and write a build report.

InfinitySniper-HFX.exe    the console application
Function/                 external modules, still editable
Desktop/                  the Desktop Edition launcher
README.txt
config/ logs/ reports/ backups/   created on first start

The executable stays a console application — no GUI, no browser, no Electron — and it keeps loading modules from the external Function folder, so new functions can be added without rebuilding.

Three details that make the external folder work

• core/function-loader.js installs a resolver bridge so an external module's require('../../core/kit') still finds the core helpers inside the snapshot.
• package.json lists core/*.js under pkg.scripts. The packager only bundles what it can see being required, and helpers that only external modules use — fs-scan, report-manager — are invisible to it.
• core/scripts/*.ps1 is bundled as an asset and executed as an inline script, because powershell.exe cannot open a file inside the snapshot.

Export.cmd

Export.cmd turns dist\ into the three folders a user actually receives — App Desktop Version, App Launcher Version and CMD Version — each with its own Setup.exe or console launcher, all carrying the application icon. The installers are compiled during the export by the C# compiler that ships with the .NET Framework, so there is nothing to install.

Setup.exe copies the folder wherever the user wants, creates the desktop and Start Menu shortcuts, and writes an Uninstall.cmd that asks before it deletes anything. It also accepts /silent /dir:"…" /noshortcuts for scripted installs.

Each edition is verified before the export finishes: the console engine must list its modules with no invalid:, the desktop edition must pass its self-test, and the launcher must report that it found the engine and built its interface.

Privacy

This application only reads and reports the hardware identification data Windows exposes to a normal process, and writes it to a text file that stays on your machine. It never modifies, hides or spoofs an identifier, and it sends nothing anywhere.

• No telemetry, no analytics, no crash reporting, no update check, no account.
• Everything it writes — settings, logs, reports, backups — lives in the application's own folder.
• Two functions reach the internet, and only because that is what they measure: public-ip asks a public endpoint what your outbound address is, and speed-test transfers data to measure bandwidth. Neither sends anything about your machine.
• Environment variables whose name suggests a secret are masked on screen, in exports and in the logs.

Download InfinitySniper HFX