@makefully/adaptfully 3.4.0 → 3.6.1

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project are documented in this file.
 
+## 3.6.1 — 2026-07-06
+
+### Changed
+
+- Web deploy uses the same Wrapfully zip-and-post path as Steam (`webapp` builder). Adaptfully does not implement SFTP or other publish targets directly — credentials in `assets/meta/publish/` travel in the zip for Wrapfully to use.
+
+## 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

package/README.md

@@ -23,14 +23,17 @@ Games register platform services before load and retrieve them in-game. Adaptful
 ```bash
 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 deploy web      # prebuild + POST to Wrapfully webapp builder (SFTP when sftp.json is in the zip)
+adaptfully deploy steam    # prebuild + POST to Wrapfully steam builder
+adaptfully steam-auth       # one-time: log in with steamcmd → assets/meta/publish/steam.json
 ```
 
 | Stage | What it does |
 |-------|----------------|
 | `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/`) |
+| `deploy` | Prebuild, zip, POST to Wrapfully; platform release 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 +202,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 +379,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 +526,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.
@@ -543,22 +554,28 @@ When builds relay between servers, `meta/publish/` credentials travel in the zip
 
 Release `win` builds can be signed with `assets/meta/publish/ms.json` (see Windows below). Release `mac` builds can use `assets/meta/publish/apple.json` for signing and notarization (see Apple above).
 
-#### Web app (`webapp`)
+#### Web (`web` / `webapp`)
 
-To deploy via SFTP, include `assets/meta/publish/sftp.json`:
+`adaptfully deploy web` prebuilds and POSTs to the Wrapfully **`webapp`** builder (same conduit as Steam). Include `assets/meta/publish/sftp.json` in the project so it is zipped as `meta/publish/sftp.json` for Wrapfully to deploy via SFTP.
 
 ```json
 {
   "webapp": {
     "host": "(your sftp host)",
     "port": 22,
-    "user": "(your username)",
+    "username": "(your username)",
     "password": "(your password)",
-    "path": "(the sftp subdirectory in which to publish the app)"
+    "path": "/home/user/example.com.incoming",
+    "uploadMode": "direct",
+    "serviceWorker": false,
+    "metaWeb": false,
+    "cleanRemote": false
   }
 }
 ```
 
+See [Wrapfully README](https://github.com/Makefully-Studios/wrapfully-client) for `uploadMode`, `serviceWorker`, `metaWeb`, and `cleanRemote`.
+
 #### Windows (`win`, `win-dev`, `uwp`)
 
 To sign the app, place your certificate at `assets/meta/publish/ms/packcert.pfx` and include `assets/meta/publish/ms.json`:

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

@@ -69,7 +69,7 @@ function createWindow () {
             };
         })(),
         win = new BrowserWindow({
-            backgroundColor: '#E4378E',
+            backgroundColor: __THEME_COLOR__,
             width: lastState.bounds.width,
             height: lastState.bounds.height,
             minWidth: 200,
@@ -159,12 +159,15 @@ 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 : '';
     const sandbox = withSteam ? 'false' : 'true';
-    const mainBody = ELECTRON_MAIN_BODY.replace('__SANDBOX__', sandbox);
+    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;
 }
 
@@ -206,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    prebuild + zip and send to Wrapfully (platform release when credentials are in the zip)\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.4.0",
+    "version": "3.6.1",
     "description": "Platform abstraction and Wrapfully deploy client for Makefully games",
     "type": "module",
     "main": "./lib/node/index.js",