stovesdk.js 0.0.0-stage → 0.3.2

package/tools/check-tarball.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+'use strict'
+
+// Inspects the file list of `npm pack --dry-run --json` for what must and must not ship.
+//
+//   node tools/check-tarball.js <pack.json>                  source tree: no binary at all, nothing from the SDK (ci.yml)
+//   node tools/check-tarball.js <pack.json> --with-prebuild  publish: exactly prebuilds/win32-x64/stovesdk.node (+ SHA256SUMS), nothing from the SDK (publish.yml)
+//
+// The SDK is bring-your-own and is never redistributed: no sdk/ path, no .dll/.lib/.pdb/.h.
+// The one binary a published tarball may carry is the maintainer-built addon, and only there.
+//
+// `npm pack --json` is an array of one entry up to npm 11 and an object keyed by package name
+// from npm 12; packFiles() takes either.
+
+const PREBUILD = 'prebuilds/win32-x64/stovesdk.node'
+const SUMS = 'prebuilds/win32-x64/SHA256SUMS'
+const SDK_FILE = /^sdk\/|\.(dll|lib|pdb|exe|h|hpp)$/i
+const BINARY = /\.node$/i
+
+// The file paths of the one package in `npm pack --dry-run --json` output, whichever shape.
+function packFiles(json) {
+  const entry = Array.isArray(json) ? json[0] : json && typeof json === 'object' ? Object.values(json)[0] : undefined
+  if (!entry || !Array.isArray(entry.files)) throw new TypeError('not the output of `npm pack --json`: no package entry with a files list')
+  return { name: entry.name, version: entry.version, files: entry.files.map(f => f.path) }
+}
+
+function checkTarball(files, { withPrebuild = false } = {}) {
+  const problems = []
+  const sdk = files.filter(p => SDK_FILE.test(p))
+  if (sdk.length) problems.push(`would ship SDK material or a binary of the kind: ${sdk.join(', ')}`)
+  const binaries = files.filter(p => BINARY.test(p))
+  if (withPrebuild) {
+    for (const must of [PREBUILD, SUMS, 'index.js', 'index.d.ts', 'package.json']) {
+      if (!files.includes(must)) problems.push(`missing from the tarball: ${must}`)
+    }
+    const stray = binaries.filter(p => p !== PREBUILD)
+    if (stray.length) problems.push(`a binary other than the prebuild: ${stray.join(', ')}`)
+  } else if (binaries.length) {
+    problems.push(`a binary in the source tarball: ${binaries.join(', ')}`)
+  }
+  return problems
+}
+
+module.exports = { checkTarball, packFiles, PREBUILD, SUMS }
+
+if (require.main === module) {
+  const [file, flag] = process.argv.slice(2)
+  if (!file) {
+    console.error('usage: node tools/check-tarball.js <pack.json> [--with-prebuild]')
+    process.exit(2)
+  }
+  const { name, version, files } = packFiles(require(require('path').resolve(file)))
+  const withPrebuild = flag === '--with-prebuild'
+  const problems = checkTarball(files, { withPrebuild })
+  if (problems.length) {
+    for (const p of problems) console.error(`::error::${p}`)
+    process.exit(1)
+  }
+  console.log(`npm pack: ${files.length} files, ${name}@${version}, ${withPrebuild ? 'prebuild in, ' : 'no binary, '}nothing from the SDK`)
+}

package/tools/fetch-sdk.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+'use strict'
+
+// Fetches the pinned STOVE PC SDK drop from the vendor's download CDN into a directory laid out
+// the way lib/sdk-dir.js expects, verifying every archive against tools/sdk-manifest.json first.
+//
+//   node tools/fetch-sdk.js <dest>            fetch, verify, extract into <dest>, validate the layout
+//   node tools/fetch-sdk.js <dest> --check    only validate an existing <dest> against the manifest
+//
+// What this encodes (issue #21):
+//   - The SDK version, the archive URLs and their SHA-256 are pinned in the manifest and reviewed
+//     like code. Nothing here derives a URL or accepts an unlisted module.
+//   - Every archive is hashed before anything is extracted. A mismatch fails the whole fetch: no
+//     other version is tried, no hash is rewritten, nothing from that archive touches <dest>.
+//   - <dest> must be empty or absent, so two drops never mix; archives are downloaded under it and
+//     deleted after extraction, so nothing is cached between runs.
+//   - The vendor's zips unpack to `Deploy/…` with no module folder, so each one is extracted into
+//     <dest>/<Module>/; that is the layout sdk/README.md documents and binding.gyp reads.
+//   - The extracted files are the vendor's. This tool puts them in a build directory and nowhere
+//     else — never into the repository, a package or a release.
+
+const fs = require('fs')
+const path = require('path')
+const crypto = require('crypto')
+const { execFileSync } = require('child_process')
+const { SDK_MODULES, missingSdkFiles } = require('../lib/sdk-dir')
+
+const MANIFEST_FILE = path.join(__dirname, 'sdk-manifest.json')
+
+// Problems with a manifest object (empty = usable). Checked before any network access.
+function checkManifest(manifest) {
+  const problems = []
+  if (!manifest || typeof manifest !== 'object') return ['manifest is not an object']
+  if (typeof manifest.version !== 'string' || !/^\d+(\.\d+)+$/.test(manifest.version)) problems.push('version must be a dotted version string')
+  const modules = manifest.modules && typeof manifest.modules === 'object' ? manifest.modules : null
+  if (!modules) return [...problems, 'modules must be an object']
+  const names = Object.keys(modules)
+  for (const mod of SDK_MODULES) if (!names.includes(mod)) problems.push(`modules.${mod} is missing`)
+  for (const name of names) {
+    if (!SDK_MODULES.includes(name)) problems.push(`modules.${name} is not an SDK module this addon links (${SDK_MODULES.join(', ')})`)
+    const entry = modules[name]
+    if (!entry || typeof entry !== 'object') { problems.push(`modules.${name} must be an object`); continue }
+    if (typeof entry.url !== 'string' || !/^https:\/\/[^\s]+\.zip$/.test(entry.url)) problems.push(`modules.${name}.url must be an https URL to a .zip`)
+    if (typeof entry.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(entry.sha256)) problems.push(`modules.${name}.sha256 must be 64 lowercase hex characters`)
+  }
+  return problems
+}
+
+function loadManifest(file = MANIFEST_FILE) {
+  const manifest = JSON.parse(fs.readFileSync(file, 'utf8'))
+  const problems = checkManifest(manifest)
+  if (problems.length) {
+    const err = new Error(`[stovesdk] ${path.basename(file)} is not usable:\n${problems.map(p => `  - ${p}`).join('\n')}`)
+    err.code = 'STOVE_PCSDK_SDK_MANIFEST'
+    throw err
+  }
+  return manifest
+}
+
+function sha256Hex(buffer) {
+  return crypto.createHash('sha256').update(buffer).digest('hex')
+}
+
+// Throws (code STOVE_PCSDK_SDK_CHECKSUM_MISMATCH) unless the archive bytes hash to the pinned value.
+function verifyArchive(buffer, module, expected, url) {
+  const actual = sha256Hex(buffer)
+  if (actual === expected) return actual
+  const err = new Error(
+    `[stovesdk] ${module}: SHA-256 mismatch for ${url}\n  expected ${expected}\n  actual   ${actual}\n` +
+      'The archive is not the pinned drop. Nothing was extracted. If the vendor re-published this version, ' +
+      'review the change and update tools/sdk-manifest.json in a pull request of its own.'
+  )
+  err.code = 'STOVE_PCSDK_SDK_CHECKSUM_MISMATCH'
+  err.module = module
+  err.expected = expected
+  err.actual = actual
+  throw err
+}
+
+async function downloadBuffer(url) {
+  const res = await fetch(url, { redirect: 'follow' })
+  if (!res.ok) {
+    const err = new Error(`[stovesdk] download failed: HTTP ${res.status} for ${url}`)
+    err.code = 'STOVE_PCSDK_SDK_DOWNLOAD'
+    throw err
+  }
+  return Buffer.from(await res.arrayBuffer())
+}
+
+// bsdtar reads zip archives. On Windows it is System32\tar.exe (Windows 10 1803+), named in full
+// because a Git Bash PATH puts GNU tar — which does not read zip — in front of it. Elsewhere `tar`
+// is bsdtar on macOS; on Linux, where GNU tar is the default, `unzip` is tried next.
+function extractZip(zipFile, dir) {
+  fs.mkdirSync(dir, { recursive: true })
+  if (process.platform === 'win32') {
+    const tar = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'tar.exe')
+    execFileSync(tar, ['-xf', zipFile, '-C', dir], { stdio: 'inherit' })
+    return
+  }
+  try {
+    execFileSync('tar', ['-xf', zipFile, '-C', dir], { stdio: ['ignore', 'inherit', 'pipe'] })
+  } catch (tarErr) {
+    try {
+      execFileSync('unzip', ['-q', '-o', zipFile, '-d', dir], { stdio: 'inherit' })
+    } catch {
+      const err = new Error(`[stovesdk] could not extract ${zipFile}: need bsdtar or unzip (tar said: ${String(tarErr.stderr || tarErr.message).trim()})`)
+      err.code = 'STOVE_PCSDK_SDK_EXTRACT'
+      throw err
+    }
+  }
+}
+
+function isEmptyDir(dir) {
+  if (!fs.existsSync(dir)) return true
+  return fs.statSync(dir).isDirectory() && fs.readdirSync(dir).length === 0
+}
+
+function layoutError(dest, missing) {
+  const err = new Error(`[stovesdk] SDK layout incomplete at ${dest}. Missing:\n${missing.map(f => `  - ${f}`).join('\n')}`)
+  err.code = 'STOVE_PCSDK_SDK_LAYOUT'
+  err.missing = missing
+  return err
+}
+
+// Fetches, verifies and extracts every module of the manifest into `dest`. Resolves with a summary.
+// `download` and `extract` are injectable so the rules above can be tested without the network.
+async function fetchSdk(dest, { manifest = loadManifest(), download = downloadBuffer, extract = extractZip, log = () => {} } = {}) {
+  const problems = checkManifest(manifest)
+  if (problems.length) {
+    const err = new Error(`[stovesdk] manifest is not usable:\n${problems.map(p => `  - ${p}`).join('\n')}`)
+    err.code = 'STOVE_PCSDK_SDK_MANIFEST'
+    throw err
+  }
+  dest = path.resolve(dest)
+  if (!isEmptyDir(dest)) {
+    const err = new Error(`[stovesdk] ${dest} exists and is not empty. The fetch only fills an empty directory, so two drops never mix.`)
+    err.code = 'STOVE_PCSDK_SDK_DEST_NOT_EMPTY'
+    throw err
+  }
+  fs.mkdirSync(dest, { recursive: true })
+  const downloads = path.join(dest, '.download')
+  fs.mkdirSync(downloads)
+  const modules = []
+  try {
+    for (const module of SDK_MODULES) {
+      const { url, sha256 } = manifest.modules[module]
+      log(`[stovesdk] ${module}: downloading ${url}`)
+      const buffer = await download(url)
+      verifyArchive(buffer, module, sha256, url)
+      log(`[stovesdk] ${module}: ${buffer.length} bytes, SHA-256 ${sha256} OK`)
+      const zipFile = path.join(downloads, `${module}.zip`)
+      fs.writeFileSync(zipFile, buffer)
+      extract(zipFile, path.join(dest, module))
+      fs.rmSync(zipFile, { force: true })
+      modules.push({ module, url, sha256, bytes: buffer.length })
+    }
+  } finally {
+    fs.rmSync(downloads, { recursive: true, force: true })
+  }
+  fs.writeFileSync(path.join(dest, 'VERSION'), `${manifest.version}\n`)
+  const missing = missingSdkFiles(dest)
+  if (missing.length) throw layoutError(dest, missing)
+  return { dest, version: manifest.version, modules }
+}
+
+module.exports = { MANIFEST_FILE, checkManifest, loadManifest, sha256Hex, verifyArchive, fetchSdk }
+
+if (require.main === module) {
+  const args = process.argv.slice(2)
+  const check = args.includes('--check')
+  const dest = args.find(a => !a.startsWith('--'))
+  if (!dest) {
+    console.error('usage: node tools/fetch-sdk.js <dest> [--check]')
+    process.exit(2)
+  }
+  if (check) {
+    const manifest = loadManifest()
+    const missing = missingSdkFiles(path.resolve(dest))
+    if (missing.length) { console.error(layoutError(path.resolve(dest), missing).message); process.exit(1) }
+    const version = fs.existsSync(path.join(dest, 'VERSION')) ? fs.readFileSync(path.join(dest, 'VERSION'), 'utf8').trim() : 'unknown'
+    if (version !== manifest.version) { console.error(`[stovesdk] ${dest} holds SDK ${version}, the manifest pins ${manifest.version}`); process.exit(1) }
+    console.log(`[stovesdk] SDK ${version} complete at ${path.resolve(dest)}`)
+    process.exit(0)
+  }
+  fetchSdk(dest, { log: console.log })
+    .then(summary => {
+      console.log(`[stovesdk] SDK ${summary.version} ready at ${summary.dest} (${summary.modules.length} modules, ${summary.modules.reduce((n, m) => n + m.bytes, 0)} bytes downloaded, archives removed)`)
+    })
+    .catch(err => {
+      console.error(err && err.message ? err.message : err)
+      process.exit(1)
+    })
+}

package/tools/sdk-dir.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+'use strict'
+
+// Called by binding.gyp (`<!(node tools/sdk-dir.js)`) to print the SDK directory, after checking
+// that the layout lib/sdk-dir.js documents is present. Fails loudly otherwise — node-gyp would
+// fail a few seconds later anyway, but with a far less readable error.
+//
+//   node tools/sdk-dir.js            → prints the resolved SDK directory
+//   node tools/sdk-dir.js version    → prints the SDK version string ('unknown' if no VERSION file)
+//   node tools/sdk-dir.js check      → exit 0 if the layout is complete, 1 otherwise (prints what is missing)
+
+const { resolveSdkDir, missingSdkFiles, readSdkVersion } = require('../lib/sdk-dir')
+
+const sdkDir = resolveSdkDir()
+const mode = process.argv[2] || 'dir'
+
+if (mode === 'version') {
+  process.stdout.write(readSdkVersion(sdkDir))
+  process.exit(0)
+}
+
+const missing = missingSdkFiles(sdkDir)
+if (missing.length) {
+  process.stderr.write(`[stovesdk] STOVE PC SDK not found at ${sdkDir}\n`)
+  process.stderr.write('[stovesdk] Place the SDK under sdk/ or set STOVE_PCSDK_DIR (see sdk/README.md). Missing:\n')
+  for (const file of missing) process.stderr.write(`  - ${file}\n`)
+  process.exit(1)
+}
+
+if (mode === 'check') {
+  process.stdout.write(`[stovesdk] SDK layout OK at ${sdkDir} (version ${readSdkVersion(sdkDir)})\n`)
+  process.exit(0)
+}
+
+// gyp reads this verbatim; forward slashes keep it portable inside the generated project files.
+process.stdout.write(sdkDir.replace(/\\/g, '/'))

package/tools/sdk-manifest.json

@@ -0,0 +1,19 @@
+{
+  "$comment": "The STOVE PC SDK drop that tools/fetch-sdk.js fetches and verifies (issue #21). Reviewed like code: the version is the one the addon has been built and smoke-tested against, and a change here is a pull request of its own, never combined with an addon change. Each archive is checked against its SHA-256 before extraction; a mismatch fails the fetch and nothing is substituted. The files are the vendor's and are never committed, packed or redistributed.",
+  "version": "3.3.2.19",
+  "source": "STOVE developer-center download CDN (the links behind the PC SDK download page)",
+  "modules": {
+    "BaseSDK": {
+      "url": "https://d2x8kymwjom7h7.cloudfront.net/live/application_no/STATIC/developer-center/Store/BaseSDK_3.3.2.19.zip",
+      "sha256": "92e9a0e0a8522c8ef176769695f79aca89de33ae67c27f7c2f41fd26035f5faa"
+    },
+    "OwnershipSDK": {
+      "url": "https://d2x8kymwjom7h7.cloudfront.net/live/application_no/STATIC/developer-center/Store/OwnershipSDK_3.3.2.19.zip",
+      "sha256": "b542032b9a4a53a2e7d3fdda7a871aeef4a9ea9222cd149deea60b0c29810409"
+    },
+    "GameSupportSDK": {
+      "url": "https://d2x8kymwjom7h7.cloudfront.net/live/application_no/STATIC/developer-center/Store/GameSupportSDK_3.3.2.19.zip",
+      "sha256": "ad3a339fbe28055a88839428333700efa34f3a59590dc3a67583145f437f25e9"
+    }
+  }
+}

package/tools/smoke.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+'use strict'
+
+// Load-only smoke for a freshly built addon (Windows). Proves, without a STOVE client:
+//   1. the .node loads (its DLL imports resolve — the SDK DLLs must sit next to it or next to node.exe),
+//   2. the export surface matches index.d.ts,
+//   3. the pure-addon paths behave: refusals before initialize(), argument validation, no-op pump,
+//      no-op uninitialize().
+// Nothing initializes the SDK — that needs a STOVE client session on the machine.
+//
+//   node tools/smoke.js [path/to/stovesdk.node]
+
+const path = require('path')
+const { load } = require('..')
+
+const EXPECTED_EXPORTS = [
+  'getAddonInfo', 'getVersion', 'initialize', 'runCallbacks', 'isInitialized', 'uninitialize',
+  'getOwnershipList', 'getUser', 'getGds', 'getAchievement', 'getAllAchievements', 'getStat', 'setStat',
+]
+
+function fail(message) {
+  console.error(`[smoke] ${message}`)
+  process.exit(1)
+}
+
+const sdk = load(process.argv[2] ? path.resolve(process.argv[2]) : undefined)
+
+const missing = EXPECTED_EXPORTS.filter(name => typeof sdk[name] !== 'function')
+if (missing.length) fail(`missing exports: ${missing.join(', ')}`)
+if (!sdk.constants || !sdk.constants.OwnershipCode || !sdk.constants.OwnershipGameCode || !sdk.constants.ErrorCode) {
+  fail('constants are missing')
+}
+
+const info = sdk.getAddonInfo()
+console.log('[smoke] addon info:', JSON.stringify(info))
+console.log('[smoke] constants:', JSON.stringify(sdk.constants))
+
+if (sdk.isInitialized() !== false) fail('expected isInitialized() === false on a fresh load')
+
+// Informational — exercises a real call into BaseSDK.dll.
+console.log('[smoke] Base_GetVersion:', JSON.stringify(sdk.getVersion()))
+
+// Synchronous identity reads must answer, not throw, before initialize().
+for (const name of ['getUser', 'getGds']) {
+  const answer = sdk[name]()
+  console.log(`[smoke] ${name}() before init:`, JSON.stringify(answer))
+  if (!answer || answer.ok !== false || answer.code !== sdk.constants.ErrorCode.NOT_INITIALIZED) {
+    fail(`${name}() before init must report { ok: false, code: ErrorCode.NOT_INITIALIZED }`)
+  }
+}
+
+// runCallbacks() must be a no-op when nothing is in flight.
+sdk.runCallbacks()
+
+// uninitialize() on a fresh addon must be a harmless no-op with all three slots null.
+const down = sdk.uninitialize()
+console.log('[smoke] uninitialize() on fresh addon:', JSON.stringify(down))
+if (down.base !== null || down.ownership !== null || down.gameSupport !== null) {
+  fail('uninitialize() reported an UnInitialize on a never-initialized SDK')
+}
+
+// Argument validation is synchronous (TypeError / RangeError), never a crash and never an SDK call.
+function expectThrow(label, fn, ctor) {
+  try {
+    fn()
+  } catch (err) {
+    if (err instanceof ctor) {
+      console.log(`[smoke] ${label} threw ${ctor.name} as expected:`, err.message)
+      return
+    }
+    fail(`${label} threw the wrong error type: ${err}`)
+  }
+  fail(`${label} did not throw`)
+}
+expectThrow('initialize() without options', () => sdk.initialize(), TypeError)
+expectThrow('setStat("x") without a value', () => sdk.setStat('x'), TypeError)
+expectThrow('setStat("x", 1.5)', () => sdk.setStat('x', 1.5), RangeError)
+expectThrow('getAchievement(42)', () => sdk.getAchievement(42), TypeError)
+expectThrow('getStat(null)', () => sdk.getStat(null), TypeError)
+
+// Before initialize() every asynchronous entry point must reject through its Promise —
+// never crash the process, never reach the SDK.
+function expectReject(label, promise, step) {
+  return promise.then(
+    () => fail(`${label} resolved without the SDK initialized`),
+    err => {
+      if (!err || err.step !== step || err.code !== sdk.constants.ErrorCode.NOT_INITIALIZED) {
+        fail(`${label} rejected with an unexpected shape: step=${err && err.step} code=${err && err.code}`)
+      }
+      console.log(`[smoke] ${label} rejected as expected:`, err.message)
+    }
+  )
+}
+
+expectReject('getOwnershipList()', sdk.getOwnershipList(), 'ownershipList')
+  .then(() => expectReject('setStat("x", 1)', sdk.setStat('x', 1), 'modifyStat'))
+  .then(() => expectReject('getStat("x")', sdk.getStat('x'), 'stat'))
+  .then(() => expectReject('getAchievement("x")', sdk.getAchievement('x'), 'achievement'))
+  .then(() => expectReject('getAllAchievements()', sdk.getAllAchievements(), 'allAchievements'))
+  .then(() => {
+    console.log('[smoke] OK')
+  })

package/tools/syntax-check.sh

@@ -0,0 +1,40 @@
+#!/bin/sh
+# Parses src/stovesdk.cc with clang `-fsyntax-only` on a non-Windows machine, against the real
+# SDK headers (STOVE_PCSDK_DIR or ./sdk) and a stub <windows.h>. It catches typos, wrong SDK
+# accessor names and N-API misuse before the code reaches a Windows toolchain. It is NOT a build:
+# nothing is linked, and MSVC-only behaviour is not exercised.
+#
+#   sh tools/syntax-check.sh            (needs: clang++, node_modules/node-addon-api, Node headers)
+#
+# The SDK root is passed with -iquote, not -I: the vendor headers include each other with quoted
+# paths relative to that root ("BaseSDK/Deploy/Include/…"), and a plain -I would also let the C++
+# standard library's `#include <version>` resolve to the drop's VERSION file on a case-insensitive
+# file system (macOS, Windows). binding.gyp's include_dirs are unaffected — MSVC builds have passed
+# with VERSION present.
+set -eu
+
+ROOT=$(cd "$(dirname "$0")/.." && pwd)
+SDK_DIR=$(node "$ROOT/tools/sdk-dir.js")
+NAPI_INC=$(node -p "require('$ROOT/node_modules/node-addon-api').include.replace(/\"/g, '')")
+NODE_INC="${NODE_INCLUDE_DIR:-$(dirname "$(dirname "$(command -v node)")")/include/node}"
+[ -f "$NODE_INC/node_api.h" ] || { echo "node_api.h not found under $NODE_INC (set NODE_INCLUDE_DIR)" >&2; exit 1; }
+
+STUB=$(mktemp -d)
+trap 'rm -rf "$STUB"' EXIT
+cat > "$STUB/windows.h" <<'EOF'
+// Minimal stand-in for <windows.h>: only what src/stovesdk.cc and the SDK headers touch.
+#pragma once
+#include <cstdint>
+#define __cdecl
+#define CP_UTF8 65001
+#define __out
+extern "C" int WideCharToMultiByte(unsigned, unsigned long, const wchar_t*, int, char*, int, const char*, int*);
+EOF
+
+clang++ -fsyntax-only -std=c++17 -fshort-wchar -fdeclspec -fms-extensions \
+  -Wno-ignored-attributes -Wno-microsoft -Wno-pragma-pack \
+  -DSTOVE_PCSDK_SYNTAX_CHECK -DNAPI_VERSION=8 -DNAPI_DISABLE_CPP_EXCEPTIONS \
+  -I "$STUB" -I "$NAPI_INC" -I "$NODE_INC" \
+  -iquote "$SDK_DIR" -I "$SDK_DIR/BaseSDK/Deploy/Include" -I "$SDK_DIR/OwnershipSDK/Deploy/Include" -I "$SDK_DIR/GameSupportSDK/Deploy/Include" \
+  "$ROOT/src/stovesdk.cc"
+echo "[syntax-check] OK: src/stovesdk.cc parses against the SDK headers at $SDK_DIR"