@caleb-collar/steamcmd 1.0.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,141 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **ESM module support**: Package now supports both CommonJS (`require`) and ES Modules (`import`)
+- **`getInstalledApps()`**: List all installed Steam applications in a directory
+- **`update()`**: Update an existing Steam application installation
+- **`validate()`**: Validate an installed Steam application
+- **`getInstalledVersion()`**: Get the installed version (build ID) of a Steam application
+- **`createProgressEmitter()`**: Create an EventEmitter for real-time progress tracking
+
+### Changed
+
+- **package.json**: Added `exports` field for dual CJS/ESM support
+- **package.json**: Added `module` field pointing to ESM entry point
+
+## [1.0.0-alpha.1] - 2026-01-31
+
+### Added
+
+- **Promise/async-await support**: All API functions now return Promises when no callback is provided
+- **Progress tracking**: New `onProgress` callback for tracking download and installation progress
+- **Output streaming**: New `onOutput` callback for real-time SteamCMD output
+- **Utility functions**: `isInstalled()`, `ensureInstalled()`, and `getInfo()`
+- **Custom error classes**: `SteamCmdError`, `DownloadError`, and `InstallError` with error codes
+- **Input validation**: Comprehensive validation for all options with descriptive error messages
+- **TypeScript definitions**: Full type definitions in `types/steamcmd.d.ts`
+- **Test suite**: Comprehensive unit and integration tests with >80% coverage
+- **CI/CD pipeline**: GitHub Actions for testing on Node 18/20/22 across Linux, Windows, and macOS
+- **Automated publishing**: GitHub workflow for npm publishing on release
+- **Dependabot**: Automated dependency updates
+
+### Changed
+
+- **BREAKING**: Minimum Node.js version is now 18 (previously no requirement)
+- **BREAKING**: Download URLs now use HTTPS instead of HTTP
+- **Dependencies**: Replaced `tarball-extract` with `tar` (actively maintained)
+- **Dependencies**: Replaced `path-extra` with `env-paths` (modern alternative)
+- **Dependencies**: Updated `commander` from v2 to v12 (CLI improvements)
+- **Dependencies**: Updated `unzipper` to latest version
+- **Dependencies**: Updated `standard` to v17 (dev dependency)
+- **Data directory**: Now uses `env-paths` conventions
+  - Linux: `~/.local/share/steamcmd` (was `~/.config/steamcmd`)
+  - macOS: `~/Library/Application Support/steamcmd` (unchanged)
+  - Windows: `%LOCALAPPDATA%\steamcmd` (unchanged)
+
+### Fixed
+
+- Security: Download URLs now use HTTPS instead of HTTP
+- Error handling: All async operations now properly catch and report errors
+- CLI: Updated to work with Commander v12 API
+
+### Deprecated
+
+- Callback-based API: Still supported but Promise API is recommended
+
+## [0.3.1] - Previous Version
+
+This was the last version before the modernization effort. See the git history for changes prior to this release.
+
+---
+
+## Migration Guide: 0.x to 1.0
+
+### Minimum Node.js Version
+
+Update to Node.js 18 or higher:
+
+```bash
+node --version  # Must be >= 18.0.0
+```
+
+### Using Promises (Recommended)
+
+Before (callbacks):
+
+```javascript
+steamcmd.install({ applicationId: 740 }, function (err) {
+  if (err) {
+    console.error(err);
+    return;
+  }
+  console.log("Done");
+});
+```
+
+After (async/await):
+
+```javascript
+try {
+  await steamcmd.install({ applicationId: 740 });
+  console.log("Done");
+} catch (err) {
+  console.error(err);
+}
+```
+
+### Data Directory Change (Linux)
+
+If you have an existing SteamCMD installation on Linux, it may be in the old location:
+
+```bash
+# Old location
+~/.config/steamcmd
+
+# New location
+~/.local/share/steamcmd
+```
+
+You can either:
+
+1. Let the library download SteamCMD again to the new location
+2. Move your existing installation: `mv ~/.config/steamcmd ~/.local/share/steamcmd`
+
+### Error Handling
+
+The library now throws typed errors:
+
+```javascript
+const { SteamCmdError, InstallError } = require("steamcmd");
+
+try {
+  await steamcmd.install(options);
+} catch (err) {
+  if (err instanceof InstallError) {
+    console.error(`Install failed with code: ${err.code}`);
+    console.error(`Exit code: ${err.exitCode}`);
+  }
+}
+```
+
+[Unreleased]: https://github.com/dahlgren/node-steamcmd/compare/v1.0.0-alpha.1...HEAD
+[1.0.0-alpha.1]: https://github.com/dahlgren/node-steamcmd/compare/v0.3.1...v1.0.0-alpha.1
+[0.3.1]: https://github.com/dahlgren/node-steamcmd/releases/tag/v0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2014-2026 Björn Dahlgren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,385 @@
+# SteamCMD
+
+[![CI](https://github.com/dahlgren/node-steamcmd/actions/workflows/ci.yml/badge.svg)](https://github.com/dahlgren/node-steamcmd/actions/workflows/ci.yml)
+[![npm version](https://badge.fury.io/js/steamcmd.svg)](https://www.npmjs.com/package/steamcmd)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Node.js wrapper for Valve's [SteamCMD](https://developer.valvesoftware.com/wiki/SteamCMD) tool. Download, install, and manage Steam applications programmatically.
+
+**Features:**
+
+- Automatic SteamCMD download and installation
+- Promise-based API with async/await support
+- Progress tracking for downloads and installations
+- TypeScript definitions included
+- Cross-platform (Windows, Linux, macOS)
+
+SteamCMD will be automatically downloaded to your platform-specific data folder:
+
+- **Linux:** `~/.local/share/steamcmd`
+- **macOS:** `~/Library/Application Support/steamcmd`
+- **Windows:** `%LOCALAPPDATA%\steamcmd`
+
+## Requirements
+
+**Node.js 18 or higher** is required.
+
+See [SteamCMD requirements](https://developer.valvesoftware.com/wiki/SteamCMD) for platform-specific dependencies.
+
+For Ubuntu/Debian:
+
+```bash
+sudo apt-get install lib32gcc-s1
+```
+
+## Installation
+
+```bash
+npm install steamcmd
+```
+
+## Usage
+
+### Module API (Recommended)
+
+#### Basic Installation
+
+```javascript
+const steamcmd = require("steamcmd");
+
+// Install a dedicated server (e.g., Counter-Strike 2)
+await steamcmd.install({
+  applicationId: 730,
+  path: "./cs2-server",
+});
+```
+
+#### With Authentication
+
+```javascript
+await steamcmd.install({
+  applicationId: 123456,
+  path: "./game-server",
+  username: "your-steam-username",
+  password: "your-steam-password",
+  steamGuardCode: "12345", // If Steam Guard is enabled
+});
+```
+
+#### Workshop Items
+
+```javascript
+// Download a workshop item
+await steamcmd.install({
+  applicationId: 107410, // Arma 3
+  workshopId: 450814997,
+  path: "./arma3",
+});
+```
+
+#### Progress Tracking
+
+```javascript
+await steamcmd.install({
+  applicationId: 740,
+  path: "./csds",
+  onProgress: (progress) => {
+    console.log(`${progress.phase}: ${progress.percent}%`);
+    // Output: "downloading: 45%", "validating: 100%"
+  },
+  onOutput: (data, type) => {
+    // type is 'stdout' or 'stderr'
+    process.stdout.write(data);
+  },
+});
+```
+
+#### Utility Functions
+
+```javascript
+const steamcmd = require("steamcmd");
+
+// Check if SteamCMD is installed
+const installed = await steamcmd.isInstalled();
+console.log("SteamCMD installed:", installed);
+
+// Get installation info
+const info = steamcmd.getInfo();
+console.log(info);
+// {
+//   directory: '/home/user/.local/share/steamcmd',
+//   executable: '/home/user/.local/share/steamcmd/steamcmd.sh',
+//   platform: 'linux',
+//   isSupported: true
+// }
+
+// Manually ensure SteamCMD is installed
+await steamcmd.ensureInstalled({
+  onProgress: (p) => console.log(`Download: ${p.percent}%`),
+});
+
+// List installed apps in a directory
+const apps = await steamcmd.getInstalledApps({ path: "./server" });
+console.log(apps);
+// [{ appId: 740, name: 'CSGO Server', buildId: 12345, ... }]
+
+// Get installed version of an app
+const version = await steamcmd.getInstalledVersion({
+  applicationId: 740,
+  path: "./server",
+});
+console.log(version);
+// { appId: 740, name: 'CSGO Server', buildId: 12345, lastUpdated: Date }
+
+// Update an existing installation
+await steamcmd.update({
+  applicationId: 740,
+  path: "./server",
+  onProgress: (p) => console.log(`Update: ${p.percent}%`),
+});
+
+// Validate an installation
+await steamcmd.validate({
+  applicationId: 740,
+  path: "./server",
+});
+```
+
+#### EventEmitter Progress
+
+```javascript
+const steamcmd = require("steamcmd");
+
+// Create an event emitter for real-time progress
+const emitter = steamcmd.createProgressEmitter("install", {
+  applicationId: 740,
+  path: "./server",
+});
+
+emitter.on("progress", (p) => {
+  console.log(`${p.phase}: ${p.percent}%`);
+});
+
+emitter.on("output", (data, type) => {
+  process.stdout.write(`[${type}] ${data}`);
+});
+
+emitter.on("error", (err) => {
+  console.error("Failed:", err.message);
+});
+
+emitter.on("complete", () => {
+  console.log("Done!");
+});
+```
+
+#### Error Handling
+
+```javascript
+const { SteamCmdError, DownloadError, InstallError } = require("steamcmd");
+
+try {
+  await steamcmd.install({
+    applicationId: 740,
+    path: "./server",
+  });
+} catch (err) {
+  if (err instanceof SteamCmdError) {
+    console.error(`SteamCMD error: ${err.message} (code: ${err.code})`);
+  } else if (err instanceof InstallError) {
+    console.error(`Install failed: ${err.message}`);
+    console.error(`Exit code: ${err.exitCode}`);
+  } else {
+    throw err;
+  }
+}
+```
+
+#### Legacy Callback API
+
+```javascript
+// Callback-style is still supported for backward compatibility
+steamcmd.install({ applicationId: 740, path: "./server" }, (err) => {
+  if (err) {
+    console.error("Installation failed:", err.message);
+    return;
+  }
+  console.log("Installation complete!");
+});
+```
+
+### API Reference
+
+#### `install(options, [callback])`
+
+Install a Steam application or Workshop item.
+
+| Option           | Type               | Description                                           |
+| ---------------- | ------------------ | ----------------------------------------------------- |
+| `applicationId`  | `number \| string` | Steam application ID to install                       |
+| `workshopId`     | `number \| string` | Workshop item ID (requires `applicationId`)           |
+| `path`           | `string`           | Installation directory                                |
+| `username`       | `string`           | Steam username for authentication                     |
+| `password`       | `string`           | Steam password for authentication                     |
+| `steamGuardCode` | `string`           | Steam Guard code for 2FA                              |
+| `platform`       | `string`           | Target platform: `'windows'`, `'macos'`, or `'linux'` |
+| `onProgress`     | `function`         | Progress callback: `(progress) => void`               |
+| `onOutput`       | `function`         | Output callback: `(data, type) => void`               |
+
+**Returns:** `Promise<void>` if no callback provided, `undefined` if callback provided.
+
+#### `isInstalled()`
+
+Check if SteamCMD is installed and executable.
+
+**Returns:** `Promise<boolean>`
+
+#### `ensureInstalled([options])`
+
+Ensure SteamCMD is installed, downloading if necessary.
+
+| Option       | Type       | Description                |
+| ------------ | ---------- | -------------------------- |
+| `onProgress` | `function` | Download progress callback |
+
+**Returns:** `Promise<void>`
+
+#### `getInfo()`
+
+Get information about the SteamCMD installation.
+
+**Returns:** `{ directory, executable, platform, isSupported }`
+
+#### `getInstalledApps(options)`
+
+List all installed Steam applications in a directory.
+
+| Option | Type     | Description                    |
+| ------ | -------- | ------------------------------ |
+| `path` | `string` | Installation directory to scan |
+
+**Returns:** `Promise<Array>` - Array of installed app info objects
+
+#### `getInstalledVersion(options)`
+
+Get the installed version of a Steam application.
+
+| Option          | Type               | Description            |
+| --------------- | ------------------ | ---------------------- |
+| `applicationId` | `number \| string` | Steam application ID   |
+| `path`          | `string`           | Installation directory |
+
+**Returns:** `Promise<Object | null>` - Version info or null if not installed
+
+#### `update(options)`
+
+Update an installed Steam application.
+
+| Option           | Type               | Description                    |
+| ---------------- | ------------------ | ------------------------------ |
+| `applicationId`  | `number \| string` | Steam application ID to update |
+| `path`           | `string`           | Installation directory         |
+| `username`       | `string`           | Steam username (optional)      |
+| `password`       | `string`           | Steam password (optional)      |
+| `steamGuardCode` | `string`           | Steam Guard code (optional)    |
+| `onProgress`     | `function`         | Progress callback (optional)   |
+
+**Returns:** `Promise<void>`
+
+#### `validate(options)`
+
+Validate an installed Steam application.
+
+| Option          | Type               | Description                      |
+| --------------- | ------------------ | -------------------------------- |
+| `applicationId` | `number \| string` | Steam application ID to validate |
+| `path`          | `string`           | Installation directory           |
+| `username`      | `string`           | Steam username (optional)        |
+| `password`      | `string`           | Steam password (optional)        |
+| `onProgress`    | `function`         | Progress callback (optional)     |
+
+**Returns:** `Promise<void>`
+
+#### `createProgressEmitter(operation, options)`
+
+Create an EventEmitter for real-time progress tracking.
+
+| Parameter   | Type     | Description                                           |
+| ----------- | -------- | ----------------------------------------------------- |
+| `operation` | `string` | Operation type: `'install'`, `'update'`, `'validate'` |
+| `options`   | `object` | Same options as `install()`                           |
+
+**Returns:** `EventEmitter` - Emits `'progress'`, `'output'`, `'error'`, and `'complete'` events
+
+### Command Line Interface
+
+```bash
+npx steamcmd <appid> [workshopid] [options]
+```
+
+**Options:**
+
+| Option                     | Description                               |
+| -------------------------- | ----------------------------------------- |
+| `-u, --username <value>`   | Steam username                            |
+| `-p, --password <value>`   | Steam password                            |
+| `--path <value>`           | Install path (default: current directory) |
+| `--platform <value>`       | Target platform                           |
+| `--steamGuardCode <value>` | Steam Guard code                          |
+| `-h, --help`               | Show help                                 |
+
+**Examples:**
+
+```bash
+# Install CS2 dedicated server
+npx steamcmd 730 --path ./cs2-server
+
+# Install with authentication
+npx steamcmd 123456 --username myuser --password mypass --path ./game
+
+# Install a workshop item
+npx steamcmd 107410 450814997 --path ./arma3
+```
+
+## TypeScript
+
+TypeScript definitions are included:
+
+```typescript
+import steamcmd, { SteamCmdError, InstallOptions } from "steamcmd";
+
+const options: InstallOptions = {
+  applicationId: 740,
+  path: "./server",
+  onProgress: (progress) => {
+    console.log(`${progress.phase}: ${progress.percent}%`);
+  },
+};
+
+await steamcmd.install(options);
+```
+
+## ES Modules
+
+The package supports both CommonJS and ES Modules:
+
+```javascript
+// CommonJS
+const steamcmd = require("steamcmd");
+
+// ES Modules
+import steamcmd from "steamcmd";
+// or with named exports
+import { install, getInfo, SteamCmdError } from "steamcmd";
+```
+
+## Finding App IDs
+
+- [Steam Application IDs](https://developer.valvesoftware.com/wiki/Steam_Application_IDs)
+- [SteamDB](https://steamdb.info/)
+
+Workshop IDs can be found in the URL of any Workshop item page.
+
+## License
+
+MIT © [Björn Dahlgren](https://github.com/dahlgren)

package/bin/steamcmd

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+const { program } = require('commander')
+
+const steamcmd = require('../src/steamcmd')
+
+program
+  .name('steamcmd')
+  .description('Download and install Steam applications via SteamCMD')
+  .argument('<appid>', 'Steam Application ID to install')
+  .argument('[workshopid]', 'Workshop item ID (optional)')
+  .option('-u, --username <value>', 'Steam Username')
+  .option('-p, --password <value>', 'Steam Password')
+  .option('--path <value>', 'Install Path instead of CWD')
+  .option('--platform <value>', 'Install application for specific OS')
+  .option('--steamGuardCode <value>', 'Code for steam guard')
+  .parse(process.argv)
+
+const args = program.args
+const options = program.opts()
+
+const appId = args[0]
+const workshopId = args[1]
+
+const installPath = options.path || process.cwd()
+
+steamcmd.install({
+  applicationId: appId,
+  path: installPath,
+  username: options.username,
+  password: options.password,
+  platform: options.platform,
+  steamGuardCode: options.steamGuardCode,
+  workshopId
+})

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@caleb-collar/steamcmd",
+  "version": "1.0.0-alpha.1",
+  "description": "Node.js wrapper for SteamCMD - download, install, and manage Steam applications programmatically",
+  "main": "src/steamcmd.js",
+  "module": "src/steamcmd.mjs",
+  "types": "types/steamcmd.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/steamcmd.d.ts",
+        "default": "./src/steamcmd.mjs"
+      },
+      "require": {
+        "types": "./types/steamcmd.d.ts",
+        "default": "./src/steamcmd.js"
+      }
+    }
+  },
+  "scripts": {
+    "lint": "standard --verbose **/*.js bin/*",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "bin": {
+    "steamcmd": "./bin/steamcmd"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "types/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "steam",
+    "steamcmd",
+    "valve",
+    "game-server",
+    "dedicated-server",
+    "workshop",
+    "download",
+    "install"
+  ],
+  "author": "Björn Dahlgren",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caleb-collar/node-steamcmd.git"
+  },
+  "bugs": {
+    "url": "https://github.com/caleb-collar/node-steamcmd/issues"
+  },
+  "homepage": "https://github.com/caleb-collar/node-steamcmd#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "env-paths": "^2.2.1",
+    "tar": "^7.4.3",
+    "unzipper": "^0.12.3"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.18",
+    "standard": "^17.1.2",
+    "vitest": "^4.0.18"
+  }
+}