spplice-api 0.1.0

package/docs/example.ts

@@ -0,0 +1,38 @@
+import * as Spplice from "..";
+import path from "node:path";
+
+// Start Steam interface - Steam must be running, user must be logged in
+const steamClient = new Spplice.SteamClient();
+// Get Portal 2 game directory
+const gameDir = steamClient.getGameDir();
+
+// Load default package repository/repositories
+const repositories = await Promise.all([
+  Spplice.Repository.fromURL("https://p2r3.github.io/spplice-repo/index.json")
+]);
+// Aggregate all packages into a single list
+const packages = repositories.map(r => Array.from(r.packages)).flat(1);
+
+// Pick a package to install - for this example, the first one on the list
+const packageToInstall = packages[0]!;
+// Extract the package files to portal2_tempcontent
+packageToInstall.extract(path.join(gameDir, "portal2_tempcontent"));
+// Tell Steam to start the game
+Spplice.SteamClient.launchSteam([
+  "-applaunch", steamClient.appID.toString(),
+  "-tempcontent", // Enable reading from portal2_tempcontent
+  "-netconport 22333" // Enable console TCP socket
+]);
+
+// Connect to the game's developer console
+const gameConsole = new Spplice.Console(22333);
+await gameConsole.connect();
+// Print something to the console
+gameConsole.send("echo Hello from Spplice API!");
+// Monitor and print console output
+setInterval(() => {
+  let line;
+  while (line = gameConsole.readLine()) {
+    console.log("[P2]", line);
+  }
+}, 200);

package/index.ts

@@ -0,0 +1,10 @@
+export {
+  SteamClient
+} from "./src/SteamTools";
+export {
+  SpplicePackage as Package,
+  SppliceRepository as Repository
+} from "./src/PackageTools";
+export {
+  Console
+} from "./src/ConsoleTools";

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "spplice-api",
+  "version": "0.1.0",
+  "module": "index.ts",
+  "type": "module",
+  "private": false,
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@types/lzma-native": "^4.0.4",
+    "@types/tar-stream": "^3.1.4",
+    "lzma-native": "^8.0.6",
+    "ps-list": "^9.0.0",
+    "steamworks-ffi-node": "^0.10.3",
+    "tar-stream": "^3.2.0"
+  },
+  "trustedDependencies": [
+    "steamworks-ffi-node"
+  ]
+}

package/src/ConsoleTools.ts

@@ -0,0 +1,120 @@
+import net from "net";
+
+export class Console {
+
+  // TCP socket handle
+  socket: net.Socket;
+  // Network port number
+  port: number;
+  // Last connection error, or null if none
+  error: Error | null = null;
+  // Connection state - true if connected, false otherwise
+  connected: boolean = false;
+
+  // Whether we expect the socket to close intentionally.
+  // Determines whether a repeat connection is attempted.
+  private closing: boolean = false;
+  // Stores unflushed writes, re-sent if the socket reconnects.
+  private writeBuffer: string = "";
+  // Stores output read from the socket, but not yet read by the client.
+  private readBuffer: string = "";
+
+  /**
+   * Creates and configures TCP socket for Portal 2 netcon.
+   * @param port Network port number for connection.
+   */
+  constructor (port: number) {
+    this.socket = new net.Socket();
+    this.socket.setNoDelay(true);
+    this.socket.setKeepAlive(false);
+    this.port = port;
+    // Listen for incoming data and log to read buffer
+    this.socket.on("data", data => {
+      this.readBuffer += data;
+    });
+    // Clear pending write buffer when data gets flushed
+    this.socket.on("drain", () => {
+      this.writeBuffer = "";
+    });
+    // Reconnect if the socket ever closes unexpectedly
+    this.socket.on("close", () => {
+      this.connected = false;
+      if (!this.closing) {
+        setTimeout(() => this.connect(), 200);
+      }
+    });
+  }
+
+  /**
+   * Connects to the Portal 2 console TCP socket.
+   */
+  async connect () {
+    // Attempt connection to the socket
+    this.error = await new Promise(resolve => {
+      let onConnect: any, onError: any;
+      this.socket.once("error", onError = (err: Error) => {
+        this.socket.off("connect", onConnect);
+        resolve(err);
+      });
+      this.socket.once("connect", onConnect = () => {
+        this.socket.off("error", onError);
+        resolve(null);
+      });
+      this.socket.connect(this.port, "127.0.0.1");
+    });
+    if (!this.error) this.connected = true;
+    // Re-send anything that remains in the write buffer from the last session
+    if (this.writeBuffer) {
+      const success = this.socket.write(this.writeBuffer);
+      if (success) this.writeBuffer = "";
+    }
+  }
+
+  /**
+   * Disconnects from the Portal 2 console socket.
+   */
+  disconnect () {
+    this.closing = true;
+    this.writeBuffer = "";
+    this.readBuffer = "";
+    this.socket.end();
+  }
+
+  /**
+   * Sends a console command to the game.
+   * @param command Command to execute.
+   */
+  send (command: string) {
+    const data = command + "\n";
+    const success = this.socket.write(data);
+    if (!success) this.writeBuffer += data;
+  }
+
+  /**
+   * Reads output from the game console.
+   * @param length Max amount of bytes to read. Default is -1 (read all).
+   */
+  read (length: number = -1): string {
+    let output: string;
+    if (length < 0) {
+      output = this.readBuffer;
+      this.readBuffer = "";
+    } else {
+      output = this.readBuffer.slice(0, length);
+      this.readBuffer = this.readBuffer.slice(length);
+    }
+    return output;
+  }
+
+  /**
+   * Reads and returns one full line of console output. Does not read
+   * incomplete lines. Removes newline and carriage return characters.
+   * @returns One full line of console output, or `null` if no output.
+   */
+  readLine (): string | null {
+    const newlineIndex = this.readBuffer.indexOf("\n");
+    if (newlineIndex === -1) return null;
+    return this.read(newlineIndex + 1).slice(0, -1).replaceAll("\r", "");
+  }
+
+}

package/src/PackageTools.ts

@@ -0,0 +1,170 @@
+import { Readable } from "node:stream";
+import path from "node:path";
+import fs from "node:fs";
+import * as tar from "tar-stream";
+import * as lzma from "lzma-native";
+
+class SpplicePackage {
+
+  title: string;
+  author: string;
+  description: string = "";
+  version: string = "1.0.0";
+  args: string[] = [];
+  file: string;
+  icon: string;
+
+  /**
+   * @param foreignPackage Untrusted "foreign" object (e.g. from an online repo),
+   * assumed to be shaped roughly like a Spplice package.
+   */
+  constructor (foreignPackage: any) {
+    // Title is required
+    this.title = foreignPackage.title.toString().trim();
+    if (!this.title) throw "Invalid package title";
+    // Author is required
+    this.author = foreignPackage.author.toString().trim();
+    if (!this.author) throw "Invalid package author";
+    // Description is optional
+    if (typeof foreignPackage.description === "string") {
+      this.description = foreignPackage.description.trim();
+    }
+    // File URL is required
+    if (typeof foreignPackage.file !== "string") throw "Invalid package file URL";
+    this.file = foreignPackage.file;
+    // Icon URL is required
+    if (typeof foreignPackage.icon !== "string") throw "Invalid package icon URL";
+    this.icon = foreignPackage.icon;
+    // Version is optional
+    if (typeof foreignPackage.version === "string") {
+      this.version = foreignPackage.version;
+    }
+    // Command line arguments are optional
+    if (Array.isArray(foreignPackage.args)) {
+      this.args = foreignPackage.args;
+    } else if (typeof foreignPackage.args === "string") {
+      this.args = [foreignPackage.args];
+    }
+  }
+
+  /**
+   * Extracts a readable stream of a tar.xz archive to the given folder.
+   * @param inputStream Readable stream of input tar.xz file.
+   * @param destinationPath Path to directory in which to extract the archive.
+   */
+  static async extractFromStream (inputStream: Readable, destinationPath: string){
+    return await new Promise((resolve, reject) => {
+      try {
+        const lzmaDecompressor = lzma.createDecompressor();
+        const tarExtractor = tar.extract();
+        tarExtractor.on("entry", (header, stream, next) => {
+          // Get just entry name and type from header.
+          // It's probably best not to replicate permissions/users/groups.
+          const { name, type } = header;
+          const fullPath = path.join(destinationPath, name);
+          // Set up handler to continue when this entry has been parsed
+          stream.on("end", () => next());
+          // For files, pipe them to a write stream.
+          // For directories, quietly create them recursively.
+          if (type === "file") {
+            stream.pipe(fs.createWriteStream(fullPath));
+          } else if (type === "directory") {
+            fs.mkdirSync(fullPath, { recursive: true });
+          }
+          // Drain the rest of the stream if anything remains
+          stream.resume();
+        });
+        // Resolve promise once archive has been extracted
+        tarExtractor.on("finish", resolve);
+        // Pipe the input file - first decompress, then extract
+        inputStream.pipe(lzmaDecompressor).pipe(tarExtractor);
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Extracts a tar.xz archive file to the given folder.
+   * @param filePath Input tar.xz archive path.
+   * @param destinationPath Path to directory in which to extract the archive.
+   */
+  static async extractFromFile (filePath: string, destinationPath: string) {
+    const inputStream = fs.createReadStream(filePath);
+    return await SpplicePackage.extractFromStream(inputStream, destinationPath);
+  }
+
+  /**
+   * Downloads a tar.xz archive from a URL and extracts it to the given folder.
+   * @param fileURL Input tar.xz archive URL.
+   * @param destinationPath Path to directory in which to extract the archive.
+   */
+  static async extractFromURL (fileURL: string, destinationPath: string) {
+    const response = await fetch(fileURL);
+    if (response.status !== 200) throw `Server returned response ${response.status}`;
+    if (!response.body) throw `Server did not return any content.`;
+    const inputStream = Readable.fromWeb(response.body);
+    return await SpplicePackage.extractFromStream(inputStream, destinationPath);
+  }
+
+  /**
+   * Downloads and extracts the package's file archive to the given folder.
+   * @param destinationPath Path to directory in which to extract the archive.
+   */
+  async extract (destinationPath: string) {
+    return await SpplicePackage.extractFromURL(this.file, destinationPath);
+  }
+
+}
+
+class SppliceRepository {
+
+  packages: Set<SpplicePackage> = new Set();
+
+  addPackage (newPackage: SpplicePackage) {
+    this.packages.add(newPackage);
+  }
+  removePackage (removedPackage: SpplicePackage) {
+    this.packages.delete(removedPackage);
+  }
+
+  /**
+   * Fetches a Spplice repository from its URL.
+   * @param repositoryURL Link to Spplice repository index (JSON).
+   * @param strict Whether to throw an error when package parsing fails.
+   * @returns A new Spplice repository.
+   */
+  static async fromURL (repositoryURL: string, strict: boolean = false): Promise<SppliceRepository> {
+
+    // Get JSON data from input URL
+    const response = await fetch(repositoryURL.trim());
+    if (response.status !== 200) throw `Server returned response ${response.status}`;
+    const repositoryData = (await response.json()) as any;
+
+    // Validate repository structure
+    if (!Array.isArray(repositoryData.packages)) {
+      throw "Malformed repository index.";
+    }
+
+    const repository = new SppliceRepository();
+
+    // Try to convert each entry to a Spplice package, skip any that fail
+    for (const entry of repositoryData.packages) {
+      try {
+        const newPackage = new SpplicePackage(entry);
+        repository.addPackage(newPackage);
+      } catch (err) {
+        if (strict) throw err;
+      }
+    }
+
+    return repository;
+
+  }
+
+}
+
+export {
+  SpplicePackage,
+  SppliceRepository
+};

package/src/SteamTools.ts

@@ -0,0 +1,195 @@
+import SteamworksSDK from "steamworks-ffi-node";
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { execSync, execFile } from "node:child_process";
+import psList from "ps-list";
+
+type UserDetails = {
+  steamid: BigInt,
+  name: string
+};
+
+class SteamClient {
+
+  steamworksClient: SteamworksSDK;
+  appID: number;
+
+  /**
+   * Initialize Steamworks API.
+   * @param appID Game's Steam AppID (default 620 = Portal 2)
+   * Note: This makes Steam think that the specified game (Portal 2) is running.
+   */
+  constructor (appID: number = 620) {
+    this.appID = appID;
+    // HACK: Temporarily use AppID of Spacewar - Steam otherwise won't let us launch Portal 2
+    // Fixed by implementing manual startup of Portal 2
+    appID = 480;
+    // The Steamworks SDK requires steam_appid.txt in the working directory when
+    // the app is not launched through Steam, regardless of the envvar.
+    fs.writeFileSync(path.join(process.cwd(), "steam_appid.txt"), appID.toString());
+    this.steamworksClient = SteamworksSDK.getInstance();
+    const success = this.steamworksClient.init({ appId: appID });
+    if (!success) throw "Failed to initialize Steam API";
+  }
+
+  /**
+   * @returns {string} Absolute path to game directory.
+   */
+  getGameDir (): string {
+    const pathString = this.steamworksClient.apps.getAppInstallDir(this.appID) as string;
+    return path.resolve(pathString);
+  }
+
+  /**
+   * @returns {UserDetails} Current user's SteamID64 and username.
+   */
+  getUserDetails (): UserDetails {
+    const steamid = BigInt(this.steamworksClient.getStatus().steamId);
+    const name = this.steamworksClient.friends.getPersonaName();
+    return { steamid, name };
+  }
+
+  /**
+   * Checks whether the currently logged-in user has access to the game on Steam.
+   * @returns {boolean} true if current user has the game, false otherwise.
+   */
+  doesUserOwnGame (): boolean {
+    return this.steamworksClient.apps.isSubscribed();
+  }
+
+  /**
+   * Searches for Steam binaries and returns all that were found. Output is
+   * sorted by how relevant the results are. The most useful result is first.
+   *
+   * @returns {string[]} Array of absolute paths to found Steam executables,
+   * sorted by descending relevance.
+   */
+  static async findSteam (): Promise<string[]> {
+
+    const candidates: string[] = [];
+
+    /**
+     * First pass:
+     *
+     * Start by looking at the list of running system processes.
+     * The most relevant binary is likely one that is currently running.
+     */
+    const processList = await psList();
+    // Sort the process list, putting the most recent processes first.
+    // The more relevant process is the one that was last opened.
+    processList.sort((a, b) => Number(b.startTime) - Number(a.startTime));
+    // Filter for processes with name "steam".
+    const steamProcesses = processList.filter(p =>
+      p.name === "steam" ||
+      p.name === "steam.exe"
+    );
+
+    // TODO: Read registry on Windows
+
+    /**
+     * Second pass:
+     *
+     * Look for processes listening on port 27036. Steam uses this port to do
+     * game streaming, making it a fairly reliable way to fingerprint Steam.
+     */
+    try {
+      let steamPortPIDs: number[] = [];
+      // There's no neat package for this, so we use OS-dependent shells.
+      if (process.platform === "win32") {
+        const stdout = execSync("netstat -ano | findstr :27036");
+        const matches = stdout.toString().match(/\s+(\d+)$/gm);
+        if (matches) steamPortPIDs = [...new Set(matches.map(m => Number(m.trim())))];
+      } else {
+        const stdout = execSync("lsof -i :27036 -t");
+        const result = stdout.toString();
+        steamPortPIDs = result.split("\n").map(Number);
+      }
+      // Filter for processes with the PIDs we found.
+      const steamPortProcesses = processList.filter(p => steamPortPIDs.includes(p.pid));
+      steamProcesses.push(...steamPortProcesses);
+    } catch (_) { }
+
+    // Push process paths to candidate list.
+    for (const process of steamProcesses) {
+      if (process.path) candidates.push(process.path);
+      else if (process.cmd) candidates.push(process.cmd.split(" ")[0]!);
+    }
+
+    /**
+     * Third pass:
+     *
+     * Blindly push common Steam installation paths as a last resort.
+     * These will get validated in the final filtering step.
+     */
+    candidates.push(
+      `C:\\Program Files (x86)\\Steam\\steam.exe`,
+      `${os.homedir()}/.steam/steam/ubuntu12_32/steam`,
+      `${os.homedir()}/.local/share/Steam/ubuntu12_32/steam`,
+      `${os.homedir()}/.var/app/com.valvesoftware.Steam/.local/share/Steam/ubuntu12_32/steam`
+    );
+
+    // Filter and normalize candidate list.
+    for (let i = candidates.length - 1; i >= 0; i--) {
+      // Remove any empty entries
+      if (!candidates[i]?.trim()) {
+        candidates.splice(i, 1);
+        continue;
+      }
+      // Resolve candidate path
+      candidates[i] = path.resolve(candidates[i]!);
+      const candidate = candidates[i]!;
+      // Check that the path actually points to something
+      if (!fs.existsSync(candidate)) {
+        candidates.splice(i, 1);
+        continue;
+      }
+      // Check that the destination is a file
+      const stat = fs.lstatSync(candidate);
+      if (!stat.isFile()) {
+        candidates.splice(i, 1);
+        continue;
+      }
+    }
+
+    // Return list of candidates without duplicates
+    return [...new Set(candidates)];
+
+  }
+
+  /**
+   * Runs the Steam executable with the given command-line arguments.
+   * Can be used to start Steam, or to start a Steam game by using "-applaunch".
+   *
+   * TODO: Replace with manual game launch, hooking virtual file system.
+   *
+   * @param args Command-line arguments for Steam.
+   */
+  static async launchSteam (args: string[] = []) {
+
+    // Get list of canidate Steam executables
+    // TODO: Use Steamworks for this somehow?
+    const steamExes = await SteamClient.findSteam();
+
+    // Try each executable until one works, i.e. doesn't fail before `timeout`
+    const timeout = 5000;
+    for (const steam of steamExes) {
+      const error = await Promise.all([
+        new Promise(resolve => {
+          execFile(steam, args, (error) => {
+            resolve(error);
+          });
+        }),
+        new Promise(resolve => setTimeout(resolve, timeout, false))
+      ]);
+      if (!error) break;
+    }
+
+  }
+
+}
+
+export {
+  type UserDetails,
+  SteamClient
+};

package/test/extract.test.ts

@@ -0,0 +1,11 @@
+import { expect, test } from "bun:test";
+import fs from "node:fs/promises";
+import * as Spplice from "../index";
+
+test("repository package extraction", async () => {
+  const repo = await Spplice.Repository.fromURL("https://p2r3.github.io/spplice-repo/index.json");
+  const pkg = Array.from(repo.packages)[0]!;
+  await pkg.extract(".tmp");
+  expect(await Bun.file(".tmp/scripts/vscripts/mapspawn.nut").exists()).toBeTrue();
+  await fs.rm(".tmp", { recursive: true, force: true });
+});

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}