stovesdk.js 0.0.0-stage → 0.3.2

package/index.js

@@ -0,0 +1,117 @@
+'use strict'
+
+// Entry point: locates the compiled addon and loads it.
+//
+// Search order (first hit wins):
+//   1. STOVE_PCSDK_ADDON        — explicit path to a .node file
+//   2. ./build/Release/stovesdk.node   — local `npm run build`
+//   3. ./prebuilds/win32-x64/stovesdk.node — CI prebuild dropped into the package
+//
+// DLL lookup: the .node hard-imports BaseSDK.dll / OwnershipSDK.dll / GameSupportSDK.dll. Node
+// loads addons with LOAD_WITH_ALTERED_SEARCH_PATH, so DLLs placed next to the .node are found
+// first; the directory of the host executable is the other place the Windows loader always looks.
+// When the require() fails with ERR_DLOPEN_FAILED, `load()` checks those two directories for the
+// three DLLs and, if any is absent from both, rethrows with code STOVE_PCSDK_DLL_NOT_FOUND naming
+// the files — Node's own message names neither the DLL nor the directory, and reads as if the
+// .node itself were missing.
+//
+// Nothing here imports Electron, so the same file works from plain Node and the Electron main
+// process. The load is lazy and explicit (`load()`) so merely requiring this module on a
+// non-Windows machine (tests, tooling) does not throw.
+
+const fs = require('fs')
+const path = require('path')
+const { SDK_MODULES } = require('./lib/sdk-dir')
+
+const ADDON_FILE = 'stovesdk.node'
+const SDK_DLLS = Object.freeze(SDK_MODULES.map(mod => `${mod}.dll`))
+
+const ErrorCode = Object.freeze({
+  NOT_INITIALIZED: -1,
+  ALREADY_INITIALIZED: -2,
+  IN_PROGRESS: -3,
+  ABORTED: -4,
+})
+
+function candidateAddonPaths(env = process.env, baseDir = __dirname) {
+  const list = []
+  if (env.STOVE_PCSDK_ADDON && env.STOVE_PCSDK_ADDON.trim()) list.push(path.resolve(env.STOVE_PCSDK_ADDON.trim()))
+  list.push(path.join(baseDir, 'build', 'Release', ADDON_FILE))
+  list.push(path.join(baseDir, 'prebuilds', 'win32-x64', ADDON_FILE))
+  return list
+}
+
+function resolveAddonPath(env = process.env, baseDir = __dirname, exists = fs.existsSync) {
+  const candidates = candidateAddonPaths(env, baseDir)
+  const found = candidates.find(exists)
+  if (found) return found
+  const err = new Error(
+    `[stovesdk] compiled addon not found. Looked in:\n${candidates.map(c => `  - ${c}`).join('\n')}\n` +
+      'Build it with `npm run build` on Windows x64 (with the SDK under sdk/ or STOVE_PCSDK_DIR), ' +
+      'or set STOVE_PCSDK_ADDON to a prebuilt .node file.'
+  )
+  err.code = 'STOVE_PCSDK_ADDON_NOT_FOUND'
+  throw err
+}
+
+// The directories this module can vouch for: the addon's own and the host executable's. The
+// Windows loader also searches the system directories and PATH, but a consumer does not put
+// the SDK there, so a DLL absent from these two is reported as not found.
+function sdkDllSearchDirs(addonPath, execPath = process.execPath) {
+  return [...new Set([path.dirname(path.resolve(addonPath)), path.dirname(path.resolve(execPath))])]
+}
+
+// The SDK DLLs found in none of those directories. Empty when all three are present — then a
+// failed load has another cause (a DLL built for another architecture, its own imports such as
+// the VC++ runtime missing), and the original error says more than this module can.
+function missingSdkDlls(addonPath, execPath = process.execPath, exists = fs.existsSync) {
+  const dirs = sdkDllSearchDirs(addonPath, execPath)
+  return SDK_DLLS.filter(dll => !dirs.some(dir => exists(path.join(dir, dll))))
+}
+
+// The error `load()` throws when `require(addonPath)` threw `err`: a coded error naming the
+// missing SDK DLLs when that is what happened, otherwise `err` itself, untouched.
+function explainLoadError(err, addonPath, execPath = process.execPath, exists = fs.existsSync) {
+  if (!err || err.code !== 'ERR_DLOPEN_FAILED') return err
+  const missing = missingSdkDlls(addonPath, execPath, exists)
+  if (!missing.length) return err
+  const searched = sdkDllSearchDirs(addonPath, execPath)
+  const explained = new Error(
+    `[stovesdk] the addon imports ${SDK_DLLS.join(', ')}; ` +
+      `${missing.join(', ')} ${missing.length === 1 ? 'was' : 'were'} not found next to the addon or next to the host executable. Looked in:\n` +
+      `${searched.map(dir => `  - ${dir}`).join('\n')}\n` +
+      `Copy the SDK's <Module>/Deploy/Bin/x64/Release/<Module>.dll files beside ${path.resolve(addonPath)} ` +
+      'or beside your executable. They are part of the STOVE PC SDK, not of this package.',
+    { cause: err }
+  )
+  explained.code = 'STOVE_PCSDK_DLL_NOT_FOUND'
+  explained.missing = missing
+  explained.searched = searched
+  return explained
+}
+
+let cached = null
+
+function load(addonPath) {
+  if (cached) return cached
+  if (process.platform !== 'win32') {
+    const err = new Error(`[stovesdk] the STOVE PC SDK is Windows-only (platform: ${process.platform})`)
+    err.code = 'STOVE_PCSDK_UNSUPPORTED_PLATFORM'
+    throw err
+  }
+  const file = addonPath ? path.resolve(addonPath) : resolveAddonPath()
+  if (!fs.existsSync(file)) {
+    const err = new Error(`[stovesdk] addon not found: ${file}`)
+    err.code = 'STOVE_PCSDK_ADDON_NOT_FOUND'
+    throw err
+  }
+  try {
+    // eslint-disable-next-line global-require -- native module, resolved at runtime by design
+    cached = require(file)
+  } catch (err) {
+    throw explainLoadError(err, file)
+  }
+  return cached
+}
+
+module.exports = { ADDON_FILE, SDK_DLLS, ErrorCode, candidateAddonPaths, resolveAddonPath, missingSdkDlls, explainLoadError, load }

package/lib/sdk-dir.js

@@ -0,0 +1,58 @@
+'use strict'
+
+// Resolves where the user-supplied STOVE PC SDK lives and what binding.gyp expects to find there.
+//
+//   STOVE_PCSDK_DIR   explicit location (highest priority)
+//   <repo>/sdk        default (gitignored except its README)
+//
+// Expected layout (the shape the SDK zips unpack to — one folder per module):
+//   <sdk>/BaseSDK/Deploy/Include/BaseSDK.h
+//   <sdk>/BaseSDK/Deploy/Lib/x64/Release/BaseSDK.lib
+//   <sdk>/BaseSDK/Deploy/Bin/x64/Release/BaseSDK.dll
+//   ... and the same for OwnershipSDK and GameSupportSDK.
+//   <sdk>/VERSION     optional, one line: the SDK version string baked into getAddonInfo().
+
+const fs = require('fs')
+const path = require('path')
+
+const SDK_MODULES = ['BaseSDK', 'OwnershipSDK', 'GameSupportSDK']
+
+function defaultSdkDir() {
+  return path.join(__dirname, '..', 'sdk')
+}
+
+function resolveSdkDir(env = process.env) {
+  const fromEnv = env.STOVE_PCSDK_DIR
+  return fromEnv && fromEnv.trim() ? path.resolve(fromEnv.trim()) : defaultSdkDir()
+}
+
+function headerPath(sdkDir, mod) {
+  return path.join(sdkDir, mod, 'Deploy', 'Include', `${mod}.h`)
+}
+
+function libPath(sdkDir, mod) {
+  return path.join(sdkDir, mod, 'Deploy', 'Lib', 'x64', 'Release', `${mod}.lib`)
+}
+
+function dllPath(sdkDir, mod) {
+  return path.join(sdkDir, mod, 'Deploy', 'Bin', 'x64', 'Release', `${mod}.dll`)
+}
+
+// Returns the list of required files that are missing (empty = layout is complete).
+function missingSdkFiles(sdkDir, exists = fs.existsSync) {
+  const required = []
+  for (const mod of SDK_MODULES) required.push(headerPath(sdkDir, mod), libPath(sdkDir, mod), dllPath(sdkDir, mod))
+  return required.filter(file => !exists(file))
+}
+
+// Version string for getAddonInfo().sdkVersion: <sdk>/VERSION if present, else 'unknown'.
+function readSdkVersion(sdkDir, readFile = fs.readFileSync) {
+  try {
+    const text = String(readFile(path.join(sdkDir, 'VERSION'), 'utf8')).trim()
+    return text || 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
+module.exports = { SDK_MODULES, defaultSdkDir, resolveSdkDir, headerPath, libPath, dllPath, missingSdkFiles, readSdkVersion }

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "stovesdk.js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.2",
+  "description": "Unofficial Node.js / Electron bindings for the STOVE PC SDK (N-API)",
+  "license": "MIT",
+  "author": "firejune",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Blosharper/stovesdk.js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Blosharper/stovesdk.js/issues"
+  },
+  "homepage": "https://github.com/Blosharper/stovesdk.js#readme",
+  "keywords": [
+    "stove",
+    "pcsdk",
+    "electron",
+    "napi",
+    "gamedev",
+    "achievements"
+  ],
+  "main": "index.js",
+  "types": "index.d.ts",
+  "gypfile": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "lib/",
+    "src/",
+    "tools/",
+    "binding.gyp",
+    "prebuilds/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check-sdk": "node tools/sdk-dir.js check",
+    "build": "node-gyp rebuild --release --arch=x64",
+    "clean": "node-gyp clean",
+    "smoke": "node tools/smoke.js",
+    "test": "node --test \"test/**/*.test.js\"",
+    "typecheck": "tsc --noEmit -p test/tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "node-addon-api": "8.9.2",
+    "node-gyp": "13.0.2",
+    "typescript": "5.9.3"
+  }
+}

package/prebuilds/win32-x64/SHA256SUMS

@@ -0,0 +1 @@
+799924d339bf570c0fbddc3a00d4a5289216af8f80b85aa91fed0ecbc3ddd77b *./stovesdk.node