# @push.rocks/smartsystem

A TypeScript library for interacting with the system it's running on, including environment, network, and hardware information.

# readme.md for @push.rocks/smartsystem

Smart System Interaction for Node.js — your unified gateway to hardware, OS, environment, and network intelligence.

> Zero-hassle system information and environment management for modern Node.js applications.

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## 🌟 Features

`@push.rocks/smartsystem` consolidates system interaction into a single, elegant TypeScript-first API:

- 🔧 **Unified System Interface** — One `Smartsystem` instance to rule them all
- 🌍 **Runtime Detection** — Identify Node.js, Deno, Bun, or browser environments via [@push.rocks/smartenv](https://www.npmjs.com/package/@push.rocks/smartenv)
- 💻 **CPU Information** — Direct access to CPU core specs without the boilerplate
- 🌐 **Network Intelligence** — Port scanning, speed tests, DNS resolution, traceroutes, and more via [@push.rocks/smartnetwork](https://www.npmjs.com/package/@push.rocks/smartnetwork)
- 📊 **Deep System Insights** — Comprehensive hardware, OS, Docker, and performance data via [systeminformation](https://www.npmjs.com/package/systeminformation)
- ⚡ **TypeScript Native** — Built with TypeScript, for TypeScript (but works great with JS too!)

## 📦 Installation

```bash
# Using pnpm (recommended)
pnpm add @push.rocks/smartsystem

# Using npm
npm install @push.rocks/smartsystem
```

## 🚀 Quick Start

```typescript
import { Smartsystem } from '@push.rocks/smartsystem';

// Create your system interface
const mySystem = new Smartsystem();

// CPU cores at a glance
console.log(`Running on ${mySystem.cpus.length} CPU cores`);

// Deep system data
const osInfo = await mySystem.information.osInfo();
console.log(`OS: ${osInfo.distro} ${osInfo.release}`);
```

## 📖 API Overview

The `Smartsystem` class provides these powerful properties:

| Property | Type | Description |
|----------|------|-------------|
| `env` | `Smartenv` | Runtime environment detection — identify Node.js, Deno, Bun, browser, CI, and OS platform |
| `cpus` | `os.CpuInfo[]` | Direct access to CPU core information (model, speed, times) |
| `network` | `SmartNetwork` | Network utilities — port scanning, speed tests, DNS, ping, traceroute |
| `information` | `systeminformation` | Full access to 50+ system data functions (CPU, memory, disk, GPU, Docker, etc.) |

## 💡 Usage Examples

### 🌍 Runtime Environment Detection

Detect where your code is running and adapt accordingly:

```typescript
const mySystem = new Smartsystem();

// Runtime identification
console.log(`Runtime: ${mySystem.env.runtimeEnv}`); // 'node', 'deno', 'bun', or 'browser'
console.log(`Is Node.js: ${mySystem.env.isNode}`);
console.log(`Is CI: ${mySystem.env.isCI}`);

// OS detection
if (await mySystem.env.isLinuxAsync()) {
  console.log('🐧 Running on Linux');
} else if (await mySystem.env.isMacAsync()) {
  console.log('🍎 Running on macOS');
}

// Conditionally load modules based on runtime
const fsModule = await mySystem.env.getSafeModuleFor<typeof import('fs')>('node', 'fs');
```

### 💻 CPU Information at Your Fingertips

```typescript
const mySystem = new Smartsystem();

console.log(`CPU Cores: ${mySystem.cpus.length}`);
console.log(`Primary CPU: ${mySystem.cpus[0].model}`);
console.log(`Speed: ${mySystem.cpus[0].speed} MHz`);
```

### 🌐 Network Intelligence

Leverage the full power of `SmartNetwork`:

```typescript
const mySystem = new Smartsystem();

// Check if a local port is available
const portFree = await mySystem.network.isLocalPortUnused(3000);
console.log(`Port 3000 available: ${portFree}`);

// Find a free port in a range
const freePort = await mySystem.network.findFreePort(8000, 9000);
console.log(`Free port found: ${freePort}`);

// Check remote port availability
const isReachable = await mySystem.network.isRemotePortAvailable('example.com', { port: 443 });
console.log(`Remote HTTPS reachable: ${isReachable}`);

// DNS resolution
const dns = await mySystem.network.resolveDns('example.com');
console.log(`A records: ${dns.A.join(', ')}`);

// Ping a host
const pingResult = await mySystem.network.ping('8.8.8.8', { count: 3 });

// Get public IP addresses
const publicIps = await mySystem.network.getPublicIps();
console.log(`Public IPv4: ${publicIps.v4}`);

// Run a speed test
const speed = await mySystem.network.getSpeed();
console.log(`Download: ${speed.downloadSpeed} | Upload: ${speed.uploadSpeed}`);

// HTTP endpoint health check
const health = await mySystem.network.checkEndpoint('https://example.com');
console.log(`Status: ${health.status}, RTT: ${health.rtt}ms`);

// Traceroute
const hops = await mySystem.network.traceroute('example.com', { maxHops: 15 });
hops.forEach(hop => console.log(`TTL ${hop.ttl}: ${hop.ip} (${hop.rtt}ms)`));
```

### 📊 Deep System Insights

Access detailed system information via `systeminformation`:

```typescript
const mySystem = new Smartsystem();

// Hardware information
const systemInfo = await mySystem.information.system();
console.log(`System: ${systemInfo.manufacturer} ${systemInfo.model}`);

// Operating system details
const osInfo = await mySystem.information.osInfo();
console.log(`OS: ${osInfo.distro} ${osInfo.release}`);

// Real-time CPU metrics
const load = await mySystem.information.currentLoad();
console.log(`CPU Load: ${load.currentLoad.toFixed(2)}%`);

// Memory usage
const mem = await mySystem.information.mem();
console.log(`Memory: ${(mem.used / mem.total * 100).toFixed(2)}% used`);

// Disk information
const disk = await mySystem.information.fsSize();
disk.forEach(fs => console.log(`${fs.mount}: ${fs.use.toFixed(1)}% used`));

// GPU details
const gpu = await mySystem.information.graphics();
gpu.controllers.forEach(c => console.log(`GPU: ${c.model} (${c.vram}MB VRAM)`));

// Network interfaces
const defaultIface = await mySystem.information.networkInterfaceDefault();
console.log(`Default network interface: ${defaultIface}`);
```

## 🎯 Real-World Use Cases

### System Health Monitoring

Build a health check endpoint for your application:

```typescript
const mySystem = new Smartsystem();

async function healthCheck() {
  const load = await mySystem.information.currentLoad();
  const mem = await mySystem.information.mem();
  const disk = await mySystem.information.fsSize();

  return {
    status: 'healthy',
    metrics: {
      cpuLoad: `${load.currentLoad.toFixed(2)}%`,
      memoryUsage: `${(mem.used / mem.total * 100).toFixed(2)}%`,
      diskUsage: disk.map(fs => ({
        mount: fs.mount,
        usage: `${fs.use.toFixed(2)}%`
      }))
    }
  };
}
```

### Network Traffic Monitoring

Track bandwidth in real time:

```typescript
const mySystem = new Smartsystem();

async function monitorNetwork() {
  const defaultInterface = await mySystem.information.networkInterfaceDefault();
  await mySystem.information.networkStats(defaultInterface); // baseline

  await new Promise(resolve => setTimeout(resolve, 1000));

  const current = await mySystem.information.networkStats(defaultInterface);
  const rxSpeed = (current[0].rx_sec / 1024 / 1024).toFixed(2);
  const txSpeed = (current[0].tx_sec / 1024 / 1024).toFixed(2);

  console.log(`📥 Download: ${rxSpeed} MB/s | 📤 Upload: ${txSpeed} MB/s`);
}
```

### Smart Resource Scaling

Dynamically scale workers based on available resources:

```typescript
const mySystem = new Smartsystem();

async function getOptimalWorkerCount() {
  const cpuCount = mySystem.cpus.length;
  const load = await mySystem.information.currentLoad();
  const mem = await mySystem.information.mem();

  const memoryConstraint = Math.floor(mem.available / (512 * 1024 * 1024)); // 512MB per worker
  const cpuConstraint = Math.max(1, Math.floor(cpuCount * (1 - load.currentLoad / 100)));

  return Math.min(memoryConstraint, cpuConstraint, cpuCount);
}
```

### 🐳 Docker & Container Awareness

Inspect Docker state from within your app:

```typescript
const mySystem = new Smartsystem();

const dockerInfo = await mySystem.information.dockerInfo();
console.log(`Docker containers: ${dockerInfo.containers} (${dockerInfo.containersRunning} running)`);

const containers = await mySystem.information.dockerContainers();
containers.forEach(c => console.log(`  ${c.name}: ${c.state}`));
```

### Cross-Platform Logic

Write platform-aware code cleanly:

```typescript
const mySystem = new Smartsystem();

if (await mySystem.env.isLinuxAsync()) {
  // Linux-specific setup
} else if (await mySystem.env.isMacAsync()) {
  // macOS-specific setup
} else if (await mySystem.env.isWindowsAsync()) {
  // Windows-specific setup
}
```

## 🛠️ TypeScript Support

Full TypeScript support with comprehensive type definitions:

```typescript
import { Smartsystem } from '@push.rocks/smartsystem';
import type { Systeminformation } from 'systeminformation';

const mySystem = new Smartsystem();

// All methods are fully typed
const cpuInfo: Systeminformation.CpuData = await mySystem.information.cpu();
const memInfo: Systeminformation.MemData = await mySystem.information.mem();
```

## 📚 API Documentation

For complete API documentation, visit: [https://code.foss.global/push.rocks/smartsystem](https://code.foss.global/push.rocks/smartsystem)

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH  
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

# changelog.md for @push.rocks/smartsystem

## 2026-02-13 - 3.0.8 - fix(deps)
bump dependencies, adjust build script and npmextra publish config, and refresh documentation

- Bumped runtime deps: @push.rocks/lik ^6.0.0 -> ^6.2.2, @push.rocks/smartenv ^5.0.2 -> ^6.0.0, @push.rocks/smartnetwork ^3.0.0 -> ^4.4.0, @push.rocks/smartpromise ^4.0.2 -> ^4.2.3, systeminformation ^5.12.1 -> ^5.30.7
- Updated devDependencies: @git.zone/tsbuild ^2.1.63 -> ^4.1.2, @git.zone/tsrun ^1.3.3 -> ^2.0.1, @git.zone/tstest ^1.0.72 -> ^3.1.8; removed tslint and tslint-config-prettier
- Changed build script to remove --allowimplicitany ("build": "(tsbuild tsfolders)")
- Updated npmextra.json: migrated keys to scoped entries (@git.zone/cli, @git.zone/tsdoc, @ship.zone/szci), added release registries (verdaccio + npm) and accessLevel
- Documentation updates: expanded readme.md with examples, runtime detection, network and system usage, legal/licensing clarifications; added readme.hints.md

## 2025-08-29 - 3.0.7 - fix(build)
Switch build script to run tsbuild on tsfolders instead of using the --web flag

- Updated package.json scripts.build from "(tsbuild --web --allowimplicitany)" to "(tsbuild tsfolders --allowimplicitany)"
- This is a build-script change only; no source API changes were made

## 2025-08-29 - 3.0.6 - fix(smartsystem)
Add typings entry and normalize package description; sync commitinfo

- Add "typings": "dist_ts/index.d.ts" to package.json to expose TypeScript declaration file.
- Normalize package description wording (replace contraction "it's" with "it is") for consistency and clarity.
- Update ts/00_commitinfo_data.ts description to match the package.json description.

## 2025-08-29 - 3.0.5 - fix(metadata)
Clarify package/module description by expanding contraction

- Replaced "it's" with "it is" in the package/module description to improve clarity (files updated: npmextra.json, ts/00_commitinfo_data.ts).
- Documentation/metadata-only change; no runtime or API changes.
- Bump patch version to 3.0.5.

## 2025-08-29 - 3.0.4 - fix(smartsystem)
Bump version to 3.0.4

- Patch release: increment package version to 3.0.4
- No functional code changes detected in source files
- Tests are present but contain placeholder implementations
- Dependencies are pinned as wildcard '*' and were not updated

## 2025-08-29 - 3.0.3 - fix(readme)
Update README: expand documentation, add installation, usage examples, API overview, and advanced guides

- Completely revamped README with a clearer project description and features list
- Added Installation section with npm / pnpm / yarn examples
- Added Quick Start, API overview, and multiple usage examples (env, CPU, network, systeminformation)
- Added Real-World Use Cases (health check, network monitoring, resource scaling) and Advanced Features (cross-platform, Docker detection)
- Clarified TypeScript support and added links to full API documentation
- Documentation-only changes; no code or API behaviour modified

## 2025-08-29 - 3.0.2 - fix(smartsystem)
Normalize package scopes, update dev dependencies and tooling, add pnpm workspace and packageManager, remove GitLab CI, and update imports/docs/tests

- Normalize package scope names from @pushrocks/* to @push.rocks/* across source, commit info and README
- Update dependency versions: bump @push.rocks/smartpromise to ^4.0.2 and ensure other @push.rocks packages use caret ranges
- Switch dev tooling namespaces to @git.zone (tsbuild/tsrun/tstest) and add @git.zone/tsrun
- Enhance npm scripts: make test run with verbose, logfile and increased timeout
- Add packageManager field (pnpm@10.14.0+sha512...) to package.json and add pnpm-workspace.yaml with onlyBuiltDependencies: [esbuild]
- Remove legacy .gitlab-ci.yml CI configuration
- Update imports in ts and test files to match new package namespaces

## 2024-05-29 - 3.0.1 - chore
Update of package metadata and TypeScript configuration.

- update description
- update tsconfig (adjustments to TypeScript config)
- update npmextra.json: githost (fixes to githost entries)

## 2022-07-28 - 3.0.0 - fix(core)
Minor core fixes and release of 3.0.0.

- fix(core): update

## 2022-07-28 - 2.0.10 - BREAKING (core)
Breaking change: module format switched to ESM.

- BREAKING CHANGE(core): switch to esm
- misc maintenance and fixes leading up to this release

## 2017-07-31 - 2.0.1..2.0.9 - maintenance
Series of patch releases with small fixes and upkeep across the 2.0.x line.

- Multiple patch releases (2.0.1 → 2.0.9) containing repeated core fixes
- Updates to README and repository metadata
- update yarn lock (notably in 2.0.1)

## 2017-07-31 - 1.0.0..1.0.18 - initial development & improvements
Initial development, feature additions and documentation improvements across 1.0.x.

- initial releases and basic module structure; first working version
- add npm as default module loader (1.0.6)
- improve path resolution and add keywords (1.0.4–1.0.5)
- add docs, improve README and tests across multiple 1.0.x releases
- CI updates and general streamlining of the project