@makefully/adaptfully 3.3.0 → 3.5.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project are documented in this file.
 
+## 3.5.0 — 2026-06-27
+
+### Added
+
+- **`adaptfully steam-auth`** — installs steamcmd if missing, runs an interactive login, and writes `assets/meta/publish/steam.json` with `configVdf` and optional `ssfn` sentry data for Steam Guard accounts.
+- Exported helpers: `runSteamAuth`, `buildSteamPublishJson`, `collectSteamAuthFiles`, `ensureSteamcmd`.
+
+## 3.4.0 — 2026-06-25
+
+### Changed
+
+- Electron **`main.js`** allows same-app `file://` navigation while still opening external http(s) links in the system browser.
+- Steam builds (`steam-auth`) set renderer **`sandbox: false`** so the steamworks preload bridge can reach the main process; non-Steam Electron builds keep `sandbox: true`.
+
 ## 3.3.0 — 2026-06-23
 
 ### Added

package/README.md

@@ -24,6 +24,7 @@ Games register platform services before load and retrieve them in-game. Adaptful
 adaptfully prebuild web     # deploy/ → output/web-prebuild/
 adaptfully build steam      # prebuild + zip and send to Wrapfully
 adaptfully deploy steam     # build + platform release when credentials are present
+adaptfully steam-auth       # one-time: log in with steamcmd → assets/meta/publish/steam.json
 ```
 
 | Stage | What it does |
@@ -31,6 +32,7 @@ adaptfully deploy steam     # build + platform release when credentials are pres
 | `prebuild` | Copy `deploy/` to `output/<platform>-prebuild/` and inject registrations into `config.htmlInjections` |
 | `build` | Prebuild, then POST the result to Wrapfully |
 | `deploy` | Build, then release to the target platform (Steam upload, webapp SFTP, etc. via Wrapfully when credentials are in `assets/meta/publish/`) |
+| `steam-auth` | One-time local setup: install steamcmd, interactive login, write `assets/meta/publish/steam.json` |
 
 `wrapfully-deploy` is a compatibility alias for `adaptfully deploy` when invoked with a Wrapfully builder name (`steam`, `win`, `android`, etc.).
 
@@ -199,6 +201,7 @@ Run from your project root:
 
 ```bash
 npx adaptfully <prebuild|build|deploy> <platform> [server] [mode]
+npx adaptfully steam-auth [--username U] [--password P] [--output path]
 ```
 
 | Stage | Description |
@@ -375,7 +378,7 @@ Standard npm fields (`name`, `version`, `description`) are used directly. Add a
 | `publisherWebsite` | Cordova, web | Company URL |
 | `publisherEmailAddress` | Cordova | Contact email |
 | `scope` | Web/PWA | Base URL scope for the web app |
-| `themeColor` | Cordova, UWP, web | Loading screen / theme color |
+| `themeColor` | Cordova, Electron, UWP, web | Loading screen / theme color |
 | `twitterId` | Web | Twitter handle for meta tags |
 | `steamId` | Steam | Steam app ID |
 | `deployFolder` | Client | Neutral deploy directory staged before prebuild (default: `deploy`) |
@@ -522,15 +525,22 @@ Requires the Android and Apple package requirements above.
 
 `steam-dev` builds debug Electron binaries for Windows, Mac, and Linux without uploading to Steam. No `steam.json` credentials are required.
 
-For release uploads, include `assets/meta/publish/steam.json`:
+For release uploads, run **`adaptfully steam-auth`** once on your machine. It installs steamcmd if needed, logs you in interactively (enter a Steam Guard code if prompted), and writes `assets/meta/publish/steam.json`:
 
 ```json
 {
-  "username": "(your username)",
-  "password": "(your password)"
+  "username": "(your Steam build account)",
+  "password": "(your password)",
+  "configVdf": "(base64 login token from steamcmd)",
+  "sentryFileName": "(only when Steam Guard is enabled)",
+  "sentryFile": "(base64 ssfn file — only when Steam Guard is enabled)"
 }
 ```
 
+Accounts **without** Steam Guard only need `username`, `password`, and `configVdf`. Accounts **with** Steam Guard also include the `ssfn` sentry file so the Wrapfully server can log in without a live 2FA prompt.
+
+Re-run `adaptfully steam-auth` if Steam invalidates the token (new machine, password change, or expired guard).
+
 Also set `steamId` in your `config` block.
 
 Steam builds can run on either the Windows or Mac server. The server that receives the request builds its own platforms and requests the rest from the other server (Windows builds `win` and requests `mac`/`linux`; Mac builds `mac`/`linux` and requests `win`). Install the Steamworks SDK ContentBuilder on any server that will upload to Steam.

package/lib/node/index.js

@@ -34,3 +34,12 @@ export {
     resolveRegistrationAssets,
 } from './registrations.js';
 export { printBuildReport } from './report.js';
+export {
+    buildSteamPublishJson,
+    collectSteamAuthFiles,
+    defaultSteamPublishPath,
+    defaultSteamcmdCacheDir,
+    ensureSteamcmd,
+    runSteamAuth,
+    steamAuthFromCli,
+} from './steam-auth.js';

package/lib/node/packagers/electron.js

@@ -24,16 +24,22 @@ const
 
 const ELECTRON_MAIN_BODY = `
 /**
- * Opens external URLs in the system browser and blocks in-app navigation.
+ * Opens http(s) links in the system browser; allows same-app file:// navigation.
  * @param {Electron.BrowserWindow} win
  */
 function attachExternalLinkHandlers(win) {
     win.webContents.setWindowOpenHandler(({url}) => {
+        if (url.startsWith('file:')) {
+            return {action: 'deny'};
+        }
         shell.openExternal(url);
         return {action: 'deny'};
     });
 
     win.webContents.on('will-navigate', (event, url) => {
+        if (url.startsWith('file:')) {
+            return;
+        }
         event.preventDefault();
         shell.openExternal(url);
     });
@@ -63,7 +69,7 @@ function createWindow () {
             };
         })(),
         win = new BrowserWindow({
-            backgroundColor: '#E4378E',
+            backgroundColor: __THEME_COLOR__,
             width: lastState.bounds.width,
             height: lastState.bounds.height,
             minWidth: 200,
@@ -72,7 +78,7 @@ function createWindow () {
                 devTools: debugMode,
                 nodeIntegration: false,
                 contextIsolation: true,
-                sandbox: true`;
+                sandbox: __SANDBOX__`;
 
 const ELECTRON_MAIN_TAIL = `
             },
@@ -153,11 +159,16 @@ if (steamClient) {
 
 /**
  * @param {boolean} withSteam
+ * @param {string} [themeColor]
  */
-export function buildElectronMain(withSteam) {
+export function buildElectronMain(withSteam, themeColor) {
     const steamInit = withSteam ? STEAM_INIT : '';
     const steamPreload = withSteam ? STEAM_PRELOAD : '';
-    return ELECTRON_MAIN_HEAD + steamInit + ELECTRON_MAIN_BODY + steamPreload + ELECTRON_MAIN_TAIL;
+    const sandbox = withSteam ? 'false' : 'true';
+    const mainBody = ELECTRON_MAIN_BODY
+        .replace('__SANDBOX__', sandbox)
+        .replace('__THEME_COLOR__', String(JSON.stringify(themeColor)));
+    return ELECTRON_MAIN_HEAD + steamInit + mainBody + steamPreload + ELECTRON_MAIN_TAIL;
 }
 
 /**
@@ -198,7 +209,7 @@ export class ElectronPackager extends Packager {
     /** @param {string} dest */
     writeElectronMain(dest) {
         const withSteam = this.usesPlugin('steam-auth');
-        const mainContent = buildElectronMain(withSteam);
+        const mainContent = buildElectronMain(withSteam, this.pkg.config?.themeColor);
 
         if (withSteam) {
             fs.writeFileSync(

package/lib/node/pipeline.js

@@ -2,6 +2,7 @@ import { loadProjectConfig, resolveServerUrl } from './config.js';
 import { send } from './deploy.js';
 import { prebuildPlatform } from './prebuild.js';
 import { resolveBuilderForPlatform } from './registrations.js';
+import { steamAuthFromCli } from './steam-auth.js';
 
 /** @typedef {'prebuild' | 'build' | 'deploy'} AdaptfullyStage */
 
@@ -50,17 +51,29 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
  * @param {string[]} [argv=process.argv]
  */
 export async function adaptfullyFromCli(argv = process.argv) {
-    const stage = argv[2];
+    const command = argv[2];
+
+    if (command === 'steam-auth') {
+        return steamAuthFromCli(argv);
+    }
+
+    const stage = command;
     const platformKey = argv[3];
     const cliServer = argv[4];
     const mode = argv[5] ?? 'extract';
 
     if (!stage || !platformKey) {
         throw new Error(
-            'Usage: adaptfully <prebuild|build|deploy> <platform> [server] [mode]\n'
+            'Usage:\n'
+            + '  adaptfully <prebuild|build|deploy> <platform> [server] [mode]\n'
+            + '  adaptfully steam-auth [--username U] [--password P] [--output path]\n'
+            + '\n'
+            + 'Stages:\n'
             + '  prebuild  Copy deploy/ and apply platform registrations → output/<platform>-prebuild/\n'
             + '  build     prebuild + zip and send to Wrapfully\n'
-            + '  deploy    build + platform release when credentials are present (via Wrapfully)',
+            + '  deploy    build + platform release when credentials are present (via Wrapfully)\n'
+            + '\n'
+            + '  steam-auth  Install steamcmd if needed, log in interactively, write assets/meta/publish/steam.json',
         );
     }
 

package/lib/node/steam-auth.js

@@ -0,0 +1,343 @@
+import { spawn } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+
+const STEAMCMD_INSTALL = {
+    win32: {
+        url: 'https://steamcdn-a.akamaihd.net/client/installer/steamcmd.zip',
+        archive: 'zip',
+    },
+    linux: {
+        url: 'https://steamcdn-a.akamaihd.net/client/installer/steamcmd_linux.tar.gz',
+        archive: 'tar.gz',
+    },
+    darwin: {
+        url: 'https://steamcdn-a.akamaihd.net/client/installer/steamcmd_osx.tar.gz',
+        archive: 'tar.gz',
+    },
+};
+
+/**
+ * @param {string} [projectRoot]
+ */
+export function defaultSteamPublishPath(projectRoot = '.') {
+    return path.resolve(projectRoot, 'assets', 'meta', 'publish', 'steam.json');
+}
+
+/**
+ * @param {string} [cacheRoot]
+ */
+export function defaultSteamcmdCacheDir(cacheRoot) {
+    const root = cacheRoot ?? path.join(os.homedir(), '.adaptfully', 'steamcmd');
+
+    return path.join(root, process.platform);
+}
+
+/**
+ * @param {{ username: string, password: string, configVdfBuffer?: Buffer, sentryFileName?: string, sentryFileBuffer?: Buffer }} auth
+ */
+export function buildSteamPublishJson(auth) {
+    /** @type {Record<string, string>} */
+    const result = {
+        username: auth.username,
+        password: auth.password,
+    };
+
+    if (auth.configVdfBuffer) {
+        result.configVdf = auth.configVdfBuffer.toString('base64');
+    }
+
+    if (auth.sentryFileName && auth.sentryFileBuffer) {
+        result.sentryFileName = auth.sentryFileName;
+        result.sentryFile = auth.sentryFileBuffer.toString('base64');
+    }
+
+    return result;
+}
+
+/**
+ * @param {string} steamcmdDir
+ */
+export async function collectSteamAuthFiles(steamcmdDir) {
+    const configPath = path.join(steamcmdDir, 'config', 'config.vdf');
+    let configVdfBuffer;
+
+    try {
+        configVdfBuffer = await fsp.readFile(configPath);
+    } catch {
+        throw new Error(
+            `Steam login did not produce config/config.vdf at "${configPath}". `
+            + 'Check your username, password, and Steam Guard code.',
+        );
+    }
+
+    const entries = await fsp.readdir(steamcmdDir);
+    const sentryFileName = entries.find((name) => name.startsWith('ssfn'));
+    let sentryFileBuffer;
+
+    if (sentryFileName) {
+        sentryFileBuffer = await fsp.readFile(path.join(steamcmdDir, sentryFileName));
+    }
+
+    return { configVdfBuffer, sentryFileName, sentryFileBuffer };
+}
+
+/**
+ * @param {string} command
+ * @param {string[]} args
+ */
+function runCommand(command, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: 'inherit' });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve(code);
+            } else {
+                reject(new Error(`"${command}" exited with code ${code}`));
+            }
+        });
+    });
+}
+
+/**
+ * @param {string} url
+ * @param {string} dest
+ */
+async function downloadFile(url, dest) {
+    const response = await fetch(url);
+
+    if (!response.ok || !response.body) {
+        throw new Error(`Failed to download ${url}: HTTP ${response.status}`);
+    }
+
+    await pipeline(response.body, createWriteStream(dest));
+}
+
+/**
+ * @param {string} archivePath
+ * @param {string} destDir
+ * @param {'zip' | 'tar.gz'} archiveType
+ */
+async function extractArchive(archivePath, destDir, archiveType) {
+    await fsp.mkdir(destDir, { recursive: true });
+
+    if (archiveType === 'tar.gz') {
+        await runCommand('tar', ['-xzf', archivePath, '-C', destDir]);
+        return;
+    }
+
+    if (process.platform === 'win32') {
+        const escapedArchive = archivePath.replace(/'/g, "''");
+        const escapedDest = destDir.replace(/'/g, "''");
+
+        await runCommand('powershell', [
+            '-NoProfile',
+            '-Command',
+            `Expand-Archive -LiteralPath '${escapedArchive}' -DestinationPath '${escapedDest}' -Force`,
+        ]);
+        return;
+    }
+
+    await runCommand('tar', ['-xf', archivePath, '-C', destDir]);
+}
+
+/**
+ * @param {string} cacheDir
+ */
+export function steamcmdExecutable(cacheDir) {
+    if (process.platform === 'win32') {
+        return path.join(cacheDir, 'steamcmd.exe');
+    }
+
+    return path.join(cacheDir, 'steamcmd.sh');
+}
+
+/**
+ * @param {string} cacheDir
+ */
+async function steamcmdIsInstalled(cacheDir) {
+    const executable = steamcmdExecutable(cacheDir);
+
+    try {
+        await fsp.access(executable);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * @param {string} cacheDir
+ * @param {(message: string) => void} [log]
+ */
+export async function ensureSteamcmd(cacheDir, log = console.log) {
+    if (await steamcmdIsInstalled(cacheDir)) {
+        log(`adaptfully: using steamcmd at ${steamcmdExecutable(cacheDir)}`);
+        return cacheDir;
+    }
+
+    const install = STEAMCMD_INSTALL[process.platform];
+
+    if (!install) {
+        throw new Error(`Steamcmd install is not supported on platform "${process.platform}".`);
+    }
+
+    await fsp.mkdir(cacheDir, { recursive: true });
+
+    const archiveName = install.archive === 'zip' ? 'steamcmd.zip' : 'steamcmd.tar.gz';
+    const archivePath = path.join(cacheDir, archiveName);
+
+    log(`adaptfully: downloading steamcmd from ${install.url}`);
+    await downloadFile(install.url, archivePath);
+    log('adaptfully: extracting steamcmd...');
+    await extractArchive(archivePath, cacheDir, install.archive);
+    await fsp.unlink(archivePath).catch(() => {});
+
+    if (!await steamcmdIsInstalled(cacheDir)) {
+        throw new Error(`Steamcmd install failed; expected executable at ${steamcmdExecutable(cacheDir)}`);
+    }
+
+    if (process.platform !== 'win32') {
+        await fsp.chmod(steamcmdExecutable(cacheDir), 0o755);
+    }
+
+    log(`adaptfully: installed steamcmd to ${cacheDir}`);
+    return cacheDir;
+}
+
+/**
+ * @param {string} cacheDir
+ * @param {string} username
+ * @param {string} password
+ */
+export function runSteamcmdLogin(cacheDir, username, password) {
+    const executable = steamcmdExecutable(cacheDir);
+    const args = ['+login', username, password, '+quit'];
+    const command = process.platform === 'win32' ? executable : executable;
+    const spawnCommand = process.platform === 'win32' ? command : 'bash';
+    const spawnArgs = process.platform === 'win32' ? args : [command, ...args];
+
+    return new Promise((resolve, reject) => {
+        console.log('');
+        console.log('Steamcmd is starting. If Steam Guard is enabled, enter the code when prompted.');
+        console.log('');
+
+        const child = spawn(spawnCommand, spawnArgs, {
+            cwd: cacheDir,
+            stdio: 'inherit',
+        });
+
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve(code);
+            } else {
+                reject(new Error(`steamcmd login failed with exit code ${code}`));
+            }
+        });
+    });
+}
+
+/**
+ * @param {string[]} argv
+ */
+function parseSteamAuthArgv(argv) {
+    /** @type {Record<string, string>} */
+    const options = {
+        projectRoot: '.',
+    };
+
+    for (let i = 3; i < argv.length; i++) {
+        const arg = argv[i];
+
+        if (arg === '--username' && argv[i + 1]) {
+            options.username = argv[++i];
+        } else if (arg === '--password' && argv[i + 1]) {
+            options.password = argv[++i];
+        } else if (arg === '--output' && argv[i + 1]) {
+            options.output = argv[++i];
+        } else if (arg === '--steamcmd-dir' && argv[i + 1]) {
+            options.steamcmdDir = argv[++i];
+        } else if (arg === '--project-root' && argv[i + 1]) {
+            options.projectRoot = argv[++i];
+        }
+    }
+
+    return options;
+}
+
+/**
+ * @param {{ username?: string, password?: string, output?: string, steamcmdDir?: string, projectRoot?: string, log?: (message: string) => void }} [options]
+ */
+export async function runSteamAuth(options = {}) {
+    const log = options.log ?? console.log;
+    const username = options.username
+        ?? process.env.STEAM_USERNAME
+        ?? process.env.STEAM_BUILD_USERNAME;
+    const password = options.password
+        ?? process.env.STEAM_PASSWORD
+        ?? process.env.STEAM_BUILD_PASSWORD;
+    const outputPath = path.resolve(options.output ?? defaultSteamPublishPath(options.projectRoot ?? '.'));
+    const cacheDir = options.steamcmdDir ?? defaultSteamcmdCacheDir();
+
+    let resolvedUsername = username;
+    let resolvedPassword = password;
+
+    if (!resolvedUsername || !resolvedPassword) {
+        const rl = readline.createInterface({ input, output });
+
+        try {
+            if (!resolvedUsername) {
+                resolvedUsername = await rl.question('Steam build account username: ');
+            }
+
+            if (!resolvedPassword) {
+                resolvedPassword = await rl.question('Steam build account password: ');
+            }
+        } finally {
+            rl.close();
+        }
+    }
+
+    resolvedUsername = String(resolvedUsername).trim();
+    resolvedPassword = String(resolvedPassword);
+
+    if (!resolvedUsername || !resolvedPassword) {
+        throw new Error('Steam username and password are required.');
+    }
+
+    await ensureSteamcmd(cacheDir, log);
+    await runSteamcmdLogin(cacheDir, resolvedUsername, resolvedPassword);
+
+    const authFiles = await collectSteamAuthFiles(cacheDir);
+    const steamJson = buildSteamPublishJson({
+        username: resolvedUsername,
+        password: resolvedPassword,
+        ...authFiles,
+    });
+
+    await fsp.mkdir(path.dirname(outputPath), { recursive: true });
+    await fsp.writeFile(outputPath, `${JSON.stringify(steamJson, null, 4)}\n`);
+
+    log(`adaptfully: wrote ${outputPath}`);
+    if (authFiles.sentryFileName) {
+        log(`adaptfully: included Steam Guard sentry file ${authFiles.sentryFileName}`);
+    } else {
+        log('adaptfully: no sentry file was created (Steam Guard may be disabled on this account)');
+    }
+
+    return { outputPath, steamJson };
+}
+
+/**
+ * @param {string[]} [argv]
+ */
+export async function steamAuthFromCli(argv = process.argv) {
+    return runSteamAuth(parseSteamAuthArgv(argv));
+}

package/lib/runtime/auth/steam-auth.js

@@ -162,6 +162,7 @@
 
         whenReady(done) {
             if (!this.#hasSteamBridge()) {
+                console.warn('[adaptfully steam-auth] Steamworks bridge not found on window');
                 this.online = false;
                 done({ error: 'Steamworks client not available' });
                 return;
@@ -179,6 +180,7 @@
                 }
 
                 if (Date.now() - started >= timeoutMs) {
+                    console.warn('[adaptfully steam-auth] timed out waiting for Steam identity');
                     this.online = false;
                     done({ error: 'Steamworks client not available' });
                     return;
@@ -200,10 +202,13 @@
         login(callback) {
             this.#resolveIdentity()
                 .then((identity) => {
-                    this.#applyIdentity(identity);
+                    if (!this.#applyIdentity(identity)) {
+                        console.warn('[adaptfully steam-auth] login: no Steam identity available', identity);
+                    }
                     this.#complete(callback);
                 })
-                .catch(() => {
+                .catch((err) => {
+                    console.error('[adaptfully steam-auth] login failed:', err);
                     this.user = null;
                     this.authenticated = false;
                     this.online = false;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makefully/adaptfully",
-    "version": "3.3.0",
+    "version": "3.5.0",
     "description": "Platform abstraction and Wrapfully deploy client for Makefully games",
     "type": "module",
     "main": "./lib/node/index.js",