@makefully/adaptfully 3.6.1 → 3.8.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project are documented in this file.
 
+## 3.8.0 — 2026-07-10
+
+### Changed
+
+- **`steam-auth` Steamworks app ID** moves from top-level `config.steamId` to **`platforms.<name>.steamId`**. Steam **upload** app IDs belong in each deployment’s `manifest.json` (Wrapfully), not in Adaptfully client config.
+
+## 3.7.0 — 2026-07-09
+
+### Added
+
+- **`adaptfully release <platform>`** stage — single Wrapfully call for build + configured deployments.
+- **`resolveBuildSpec()`** — returns `{ family, targets, platformKey, steamworks, deployments }` for multi-target platforms.
+- **`createSourceArchive`**, **`createDeployArchive`**, **`createReleaseArchive`** — split zip profiles for build/deploy/release.
+- **`--artifact <path>`** on deploy for promoting a prior build artifact.
+
+### Changed
+
+- **`send()`** targets Wrapfully v2 URLs: `/{family}/build`, `/{family}/release`, `/deploy/{key}`.
+- Default **`deployments`** when omitted is `["zip"]` instead of the platform key.
+- **`builder`** in platform config may be a string or array (e.g. `["win","mac","linux"]`).
+
 ## 3.6.1 — 2026-07-06
 
 ### Changed

package/README.md

@@ -21,22 +21,44 @@ Games register platform services before load and retrieve them in-game. Adaptful
 ### Pipeline stages
 
 ```bash
-adaptfully prebuild web     # deploy/ → output/web-prebuild/
-adaptfully build steam      # prebuild + zip and send to Wrapfully
-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
+adaptfully prebuild web                       # deploy/ → output/web-prebuild/
+adaptfully build steam                        # prebuild + zip and send to Wrapfully (default deployment)
+adaptfully deploy web                         # prebuild + POST to Wrapfully for each of web's deployments
+adaptfully deploy web --deployment web-prod   # deploy to a single named deployment
+adaptfully deploy steam                       # prebuild + POST to Wrapfully steam builder
+adaptfully steam-auth                         # one-time: log in with steamcmd → assets/meta/deployments/steam/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` | 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` |
+| `build` | Prebuild, then POST the result to Wrapfully (artifact zip only) |
+| `deploy` | POST the prior build artifact from `./output/` to each configured deployment (or `--deployment`) |
+| `steam-auth` | One-time local setup: install steamcmd, interactive login, write the `steam` deployment's `steam.json` |
 
 `wrapfully-deploy` is a compatibility alias for `adaptfully deploy` when invoked with a Wrapfully builder name (`steam`, `win`, `android`, etc.).
 
+### Platforms vs. deployments
+
+A **platform** (`config.platforms.<key>`) describes *how* to build — registrations, packager, and the Wrapfully builder. A **deployment** describes *where* a build is sent, along with the credentials for that target. This lets a single build fan out to several targets of the same platform type (for example, a staging and a production SFTP host).
+
+- A platform may declare `"deployments": ["<key>", ...]`. Each key maps to a credential folder at `assets/meta/deployments/<key>/`.
+- If a platform has no `deployments` array, the platform key itself is the single default deployment key (so `steam` → `assets/meta/deployments/steam/`).
+- `adaptfully deploy <platform>` prebuilds once, then sends to Wrapfully once per deployment. `--deployment <key>` narrows it to one.
+- Only the selected deployment's folder is shipped in each zip (as `meta/publish/`), so other targets' credentials never travel with a build.
+
+```json
+"config": {
+  "platforms": {
+    "web":       { "registrations": { "auth": "google-auth" }, "deployments": ["web-testing", "web-prod"] },
+    "steam":     { "packager": "electron", "registrations": { "auth": "steam-auth" } },
+    "steam-dev": { "packager": "electron", "registrations": { "auth": "steam-auth" }, "deployments": ["steam"] }
+  }
+}
+```
+
+> **Back-compat:** projects with no `assets/meta/deployments/` directory keep the legacy behavior — the entire `assets/meta/` tree (including `assets/meta/publish/`) is shipped as `meta/`, and a single set of credentials is read from `meta/publish/`.
+
 Place `<!-- adaptfully -->` / `<!-- /adaptfully -->` markers in your HTML templates where registrations should be injected (typically between split bundle scripts, before `account.js` runs).
 
 ```javascript
@@ -113,12 +135,11 @@ Each platform entry may set a **`packager`** (`web`, `electron`, `cordova`, or `
 | `cordova` | `cordova.js` stub, `game-config.js`, CSP/viewport HTML extras |
 | `capacitor` | `game-config.js` (more Capacitor-specific output planned) |
 
-**`steam-auth` requires `packager: "electron"`** and `config.steamId`.
+**`steam-auth` requires `packager: "electron"`** and `platforms.<name>.steamId` (Steamworks app ID for the client preload). Steam **upload** app IDs live separately in each Steam deployment’s `manifest.json` — see Wrapfully docs.
 
 ```json
 {
   "config": {
-    "steamId": 719140,
     "platforms": {
       "web": {
         "packager": "web",
@@ -126,6 +147,7 @@ Each platform entry may set a **`packager`** (`web`, `electron`, `cordova`, or `
       },
       "steam": {
         "packager": "electron",
+        "steamId": 1234567,
         "registrations": { "auth": "steam-auth" }
       }
     }
@@ -138,7 +160,7 @@ Each platform entry may set a **`packager`** (`web`, `electron`, `cordova`, or `
 When `steam-auth` is registered on an **`electron`** platform, Adaptfully prebuild writes:
 
 - **`main.js`** — Electron shell with Steam overlay enabled and a preload script wired in
-- **`preload.js`** — initializes [steamworks.js](https://github.com/ceifa/steamworks.js) with `config.steamId` and exposes `window.__ADAPTFULLY_STEAMWORKS__`
+- **`preload.js`** — initializes [steamworks.js](https://github.com/ceifa/steamworks.js) with `platforms.<name>.steamId` and exposes `window.__ADAPTFULLY_STEAMWORKS__`
 
 The renderer `steam-auth` plugin reads the Steam ID from that bridge. When Steam is available, `autoLogin()` succeeds immediately with `{ id: steamId64, email: '' }`. Optional config keys:
 
@@ -297,16 +319,20 @@ mygame/
 │   ├── web-prebuild/     # after adaptfully prebuild web
 │   └── steam-prebuild/   # after adaptfully prebuild steam
 └── assets/
-    └── meta/             # packaged as meta/ in the zip
+    └── meta/                    # shared files packaged as meta/ in the zip
         ├── icon-foreground.png
         ├── icon-background.png
-        └── publish/      # platform signing & deploy credentials
-            ├── build.json
-            ├── android/
-            ├── apple.json
-            └── ...
+        └── deployments/         # one folder per deployment target (creds)
+            ├── web-testing/
+            │   └── sftp.json
+            ├── web-prod/
+            │   └── sftp.json
+            └── steam/           # default deployment for the `steam` platform
+                └── steam.json
 ```
 
+The selected deployment's folder is shipped as `meta/publish/` in the zip, so per-platform credential file names (`build.json`, `sftp.json`, `steam.json`, `apple.json`, `google.json`, `ms.json`, `android/`, `ms/`) live inside `assets/meta/deployments/<key>/`.
+
 Icons (`icon-foreground.png`, `icon-background.png`) are required for mobile, desktop, and Steam builds.
 
 ### Icons
@@ -345,7 +371,6 @@ Standard npm fields (`name`, `version`, `description`) are used directly. Add a
     "scope": "https://example.com/games/",
     "themeColor": "#1a1a2e",
     "twitterId": "@examplegames",
-    "steamId": 1234567,
     "deployFolder": "deploy",
     "platforms": {
       "web": {
@@ -356,6 +381,7 @@ Standard npm fields (`name`, `version`, `description`) are used directly. Add a
       },
       "steam": {
         "packager": "electron",
+        "steamId": 1234567,
         "registrations": {
           "auth": "steam-auth",
           "storage": "javascript/adaptfully-bridge.js"
@@ -381,7 +407,6 @@ Standard npm fields (`name`, `version`, `description`) are used directly. Add a
 | `scope` | Web/PWA | Base URL scope for the web app |
 | `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`) |
 | `htmlInjections` | Prebuild | Deploy-relative HTML paths to inject (default: `["index.html"]`) |
 | `outputFolder` | Client | Prebuild output root (default: `output`) |
@@ -389,6 +414,7 @@ Standard npm fields (`name`, `version`, `description`) are used directly. Add a
 | `platforms.<name>.builder` | Build/deploy | Override Wrapfully builder for a platform (default: `web` → `webapp`, others match platform key) |
 | `platforms.<name>.builders` | wrapfully-deploy | Map additional Wrapfully builder names to a platform |
 | `platforms.<name>.packager` | Prebuild | `web` (default), `electron`, `cordova`, or `capacitor` — selects the packager class that adds platform-specific files during prebuild |
+| `platforms.<name>.steamId` | Electron + steam-auth | Steamworks app ID baked into `preload.js` (client). Upload app IDs belong in the Steam deployment `manifest.json` |
 | `properties` | Cordova | Cordova config.xml entries (plugins, allow-navigation, etc.) |
 
 ### `wrapfully.json`
@@ -436,11 +462,11 @@ For a single platform, pass the specific builder name rather than a composite.
 
 ### Platform package requirements
 
-Signing keys, provisioning profiles, and store credentials go in `./assets/meta/publish/` on disk (sent as `meta/publish/` in the zip). **These files contain secrets** — add them to `.gitignore` and never commit them to a public repository.
+Signing keys, provisioning profiles, and store credentials go in the deployment folder `./assets/meta/deployments/<deployment>/` on disk (the selected deployment is sent as `meta/publish/` in the zip). The examples below use `<deployment>` as a placeholder for the target key (e.g. `steam`, `web-prod`). **These files contain secrets** — add them to `.gitignore` and never commit them to a public repository. (Projects that have not adopted the `deployments/` layout may still place these under the legacy `./assets/meta/publish/`.)
 
 #### Android (`android`, `android-dev`)
 
-Place keystore files in `assets/meta/publish/android/`. Include `assets/meta/publish/build.json`:
+Place keystore files in `assets/meta/deployments/<deployment>/android/`. Include `assets/meta/deployments/<deployment>/build.json`:
 
 ```json
 {
@@ -465,7 +491,7 @@ Place keystore files in `assets/meta/publish/android/`. Include `assets/meta/pub
 }
 ```
 
-To deploy to Google Play, also include `assets/meta/publish/google.json`:
+To deploy to Google Play, also include `assets/meta/deployments/<deployment>/google.json`:
 
 ```json
 {
@@ -484,7 +510,7 @@ To deploy to Google Play, also include `assets/meta/publish/google.json`:
 
 #### Apple (`ios`, `ios-dev`, `ios-sim`, `mac`, `apple`, `apple-dev`)
 
-Include `assets/meta/publish/build.json` with iOS signing settings:
+Include `assets/meta/deployments/<deployment>/build.json` with iOS signing settings:
 
 ```json
 {
@@ -507,7 +533,7 @@ Include `assets/meta/publish/build.json` with iOS signing settings:
 }
 ```
 
-To deploy to the App Store, include `assets/meta/publish/apple.json`:
+To deploy to the App Store, include `assets/meta/deployments/<deployment>/apple.json`:
 
 ```json
 {
@@ -526,7 +552,7 @@ 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, 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`:
+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/deployments/steam/steam.json`:
 
 ```json
 {
@@ -542,7 +568,7 @@ Accounts **without** Steam Guard only need `username`, `password`, and `configVd
 
 Re-run `adaptfully steam-auth` if Steam invalidates the token (new machine, password change, or expired guard).
 
-Also set `steamId` in your `config` block.
+For Steamworks / `steam-auth` client builds, set `platforms.<name>.steamId`. For Steam **uploads**, set `steamId` on the deployment’s `manifest.json` (see Wrapfully). Those are independent: you can deploy without steam-auth, or use steam-auth without uploading.
 
 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.
 
@@ -552,11 +578,11 @@ When builds relay between servers, `meta/publish/` credentials travel in the zip
 
 `-dev` builders produce debug Electron apps with DevTools enabled and the application menu visible. Dev builds skip code signing, notarization, and Steam upload. No publish credentials are required for dev builds.
 
-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).
+Release `win` builds can be signed with `assets/meta/deployments/<deployment>/ms.json` (see Windows below). Release `mac` builds can use `assets/meta/deployments/<deployment>/apple.json` for signing and notarization (see Apple above).
 
 #### Web (`web` / `webapp`)
 
-`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.
+`adaptfully deploy web` prebuilds and POSTs to the Wrapfully **`webapp`** builder (same conduit as Steam). Put an `sftp.json` in each web deployment folder (e.g. `assets/meta/deployments/web-prod/sftp.json`); the selected deployment is zipped as `meta/publish/sftp.json` for Wrapfully to deploy via SFTP. The inner key stays the builder name (`webapp`).
 
 ```json
 {
@@ -578,7 +604,7 @@ See [Wrapfully README](https://github.com/Makefully-Studios/wrapfully-client) fo
 
 #### 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`:
+To sign the app, place your certificate at `assets/meta/deployments/<deployment>/ms/packcert.pfx` and include `assets/meta/deployments/<deployment>/ms.json`:
 
 ```json
 {

package/lib/node/archive.js

@@ -1,12 +1,57 @@
 import archiver from 'archiver';
 import fs from 'node:fs';
+import path from 'node:path';
+
+const META_DIR = 'assets/meta';
+const DEPLOYMENTS_DIRNAME = 'deployments';
+const PUBLISH_DIRNAME = 'publish';
 
 /**
- * @param {string} deployFolder
- * @param {string} contents - serialized package.json for the zip
- * @param {{ indexHtml?: string }} [options]
+ * @param {import('archiver').Archiver} zip
+ * @param {string} [publishDir] Single deployment folder
+ * @param {string[]} [deploymentDirs] Multiple deployment folders for release
  */
-export function createArchive(deployFolder, contents, options = {}) {
+function appendMeta(zip, publishDir, deploymentDirs = []) {
+    if (!fs.existsSync(META_DIR)) {
+        return;
+    }
+
+    const deploymentsRoot = path.join(META_DIR, DEPLOYMENTS_DIRNAME);
+
+    if (!fs.existsSync(deploymentsRoot)) {
+        zip.directory(`${META_DIR}/`, 'meta');
+        return;
+    }
+
+    for (const entry of fs.readdirSync(META_DIR, { withFileTypes: true })) {
+        if (entry.name === DEPLOYMENTS_DIRNAME || entry.name === PUBLISH_DIRNAME) {
+            continue;
+        }
+
+        const fullPath = path.join(META_DIR, entry.name);
+        if (entry.isDirectory()) {
+            zip.directory(`${fullPath}/`, `meta/${entry.name}`);
+        } else {
+            zip.file(fullPath, { name: `meta/${entry.name}` });
+        }
+    }
+
+    if (publishDir && fs.existsSync(publishDir)) {
+        zip.directory(`${publishDir}/`, `meta/${PUBLISH_DIRNAME}`);
+        return;
+    }
+
+    for (const deploymentDir of deploymentDirs) {
+        if (!fs.existsSync(deploymentDir)) {
+            continue;
+        }
+
+        const deploymentKey = path.basename(deploymentDir);
+        zip.directory(`${deploymentDir}/`, `meta/${DEPLOYMENTS_DIRNAME}/${deploymentKey}`);
+    }
+}
+
+function createZipStream(deployFolder, contents, options = {}) {
     const zip = archiver('zip', { zlib: { level: 0 } });
 
     zip.on('warning', (err) => {
@@ -33,11 +78,64 @@ export function createArchive(deployFolder, contents, options = {}) {
         zip.directory(`${deployFolder}/`, 'deploy');
         zip.file(`${deployFolder}/index.html`, { name: 'deploy/index.html' });
     }
-    if (fs.existsSync('assets/meta/')) {
-        zip.directory('assets/meta/', 'meta');
-    }
+
+    appendMeta(zip, options.publishDir, options.deploymentDirs);
     zip.append(contents, { name: 'package.json' });
     zip.finalize();
 
     return zip;
 }
+
+/**
+ * Game source zip for /build and /release (no credentials unless release).
+ *
+ * @param {string} deployFolder
+ * @param {string} contents
+ * @param {{ indexHtml?: string, publishDir?: string, deploymentDirs?: string[] }} [options]
+ */
+export function createSourceArchive(deployFolder, contents, options = {}) {
+    return createZipStream(deployFolder, contents, options);
+}
+
+/**
+ * @deprecated Use createSourceArchive, createDeployArchive, or createReleaseArchive.
+ */
+export function createArchive(deployFolder, contents, options = {}) {
+    return createSourceArchive(deployFolder, contents, options);
+}
+
+/**
+ * Prior artifact zip plus one deployment folder for /deploy.
+ *
+ * @param {string} artifactPath
+ * @param {string} publishDir
+ * @param {string} [contents]
+ */
+export function createDeployArchive(artifactPath, publishDir, contents) {
+    const zip = archiver('zip', { zlib: { level: 0 } });
+
+    zip.directory(`${artifactPath}/`, false);
+    appendMeta(zip, publishDir);
+
+    if (contents) {
+        zip.append(contents, { name: 'package.json' });
+    }
+
+    zip.finalize();
+    return zip;
+}
+
+/**
+ * Game source zip with all non-zip deployment credential folders for /release.
+ *
+ * @param {string} deployFolder
+ * @param {string} contents
+ * @param {string[]} deploymentDirs
+ * @param {{ indexHtml?: string }} [options]
+ */
+export function createReleaseArchive(deployFolder, contents, deploymentDirs, options = {}) {
+    return createZipStream(deployFolder, contents, {
+        ...options,
+        deploymentDirs,
+    });
+}

package/lib/node/artifacts.js

@@ -0,0 +1,58 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MANIFEST_NAME = 'wrapfully-build.json';
+
+/**
+ * Directory where build responses are extracted (contains wrapfully-build.json).
+ *
+ * @param {{ config?: { outputFolder?: string } }} pkg
+ * @param {string} [outputRoot='output']
+ */
+export function buildOutputDir(pkg, outputRoot = 'output') {
+    const outputFolder = pkg.config?.outputFolder || outputRoot;
+    return path.resolve(outputFolder);
+}
+
+/**
+ * Resolve the artifact directory from a prior `adaptfully build` (or compatible zip extract).
+ *
+ * @param {{ name: string, version: string, config?: { outputFolder?: string } }} pkg
+ * @param {{ outputRoot?: string, platformKey?: string }} [options]
+ * @returns {string}
+ */
+export function resolveBuildArtifactDir(pkg, options = {}) {
+    const artifactDir = buildOutputDir(pkg, options.outputRoot);
+    const manifestPath = path.join(artifactDir, MANIFEST_NAME);
+
+    if (!fs.existsSync(manifestPath)) {
+        throw new Error(
+            'No prior build artifact found in '
+            + `${artifactDir}. Run \`adaptfully build <platform>\` first or pass --artifact <path>.`,
+        );
+    }
+
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    } catch {
+        throw new Error(`Unable to read ${manifestPath}`);
+    }
+
+    const gameId = `${pkg.name}-${pkg.version}`;
+    if (manifest.gameId && manifest.gameId !== gameId) {
+        throw new Error(
+            `Build artifact is for "${manifest.gameId}" but package.json is ${gameId}. `
+            + 'Run a fresh build or pass --artifact <path>.',
+        );
+    }
+
+    if (options.platformKey && manifest.platformKey && manifest.platformKey !== options.platformKey) {
+        throw new Error(
+            `Build artifact is for platform "${manifest.platformKey}" but deploy targets "${options.platformKey}". `
+            + 'Run a fresh build or pass --artifact <path>.',
+        );
+    }
+
+    return artifactDir;
+}

package/lib/node/deploy.js

@@ -3,31 +3,79 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import unzipper from 'unzip-stream';
-import { createArchive } from './archive.js';
+import { createDeployArchive, createReleaseArchive, createSourceArchive } from './archive.js';
 import { listHtmlFilesRecursive } from './fs-utils.js';
 import { printBuildReport } from './report.js';
 
+/**
+ * @param {string} gameId
+ * @param {string} platformKey
+ */
+function buildInfoParam(gameId, platformKey) {
+    return platformKey && platformKey !== gameId ? `${gameId}_${platformKey}` : gameId;
+}
+
+/**
+ * @param {string} server
+ * @param {'build' | 'deploy' | 'release'} stage
+ * @param {string} family
+ * @param {string} gameId
+ * @param {string} platformKey
+ * @param {string} [deploymentKey]
+ */
+function resolveWrapfullyUrl(server, stage, family, gameId, platformKey, deploymentKey) {
+    const info = buildInfoParam(gameId, platformKey);
+
+    if (stage === 'deploy') {
+        return `${server}deploy/${deploymentKey}/${info}`;
+    }
+
+    return `${server}${family}/${stage}/${info}`;
+}
+
 /**
  * @param {string} gameId
  * @param {string} contents
  * @param {string} server
- * @param {string} builder
- * @param {string} deployFolder - prebuilt deploy directory
+ * @param {'build' | 'deploy' | 'release'} stage
+ * @param {string} family
+ * @param {string} deployFolder
  * @param {{ name: string, version: string }} pkg
  * @param {'extract' | string} mode
- * @param {{ log?: (message: string) => void }} [options]
+ * @param {{ log?: (message: string) => void, publishDir?: string, deploymentDirs?: string[], platformKey?: string, deploymentKey?: string, artifactPath?: string }} [options]
  */
-export async function send(gameId, contents, server, builder, deployFolder, pkg, mode = 'extract', options = {}) {
+export async function send(gameId, contents, server, stage, family, deployFolder, pkg, mode = 'extract', options = {}) {
     const log = options.log ?? console.log;
+    const platformKey = options.platformKey ?? family;
     const destination = mode === 'extract'
         ? unzipper.Extract({ path: './output/', concurrency: 1 })
-        : fs.createWriteStream(`./output/${pkg.name}-${pkg.version}-${builder}.zip`);
+        : fs.createWriteStream(`./output/${pkg.name}-${pkg.version}-${stage}-${family}.zip`);
+
+    let archiveStream;
+
+    if (stage === 'deploy') {
+        if (!options.artifactPath) {
+            throw new Error('deploy stage requires options.artifactPath to the prior build artifact directory');
+        }
+        if (!options.deploymentKey) {
+            throw new Error('deploy stage requires options.deploymentKey');
+        }
+        archiveStream = createDeployArchive(options.artifactPath, options.publishDir, contents);
+    } else if (stage === 'release') {
+        archiveStream = createReleaseArchive(deployFolder, contents, options.deploymentDirs ?? []);
+    } else {
+        archiveStream = createSourceArchive(deployFolder, contents);
+    }
 
-    const htmlFiles = listHtmlFilesRecursive(deployFolder);
-    log(`adaptfully: sending ${htmlFiles.length} HTML file(s) from ${path.resolve(deployFolder)}`);
+    const url = resolveWrapfullyUrl(server, stage, family, gameId, platformKey, options.deploymentKey);
+    log(`adaptfully: POST ${url}`);
+
+    if (stage !== 'deploy') {
+        const htmlFiles = listHtmlFilesRecursive(deployFolder);
+        log(`adaptfully: sending ${htmlFiles.length} HTML file(s) from ${path.resolve(deployFolder)}`);
+    }
 
-    const archiveStream = createArchive(deployFolder, contents);
-    const { data } = await axios.post(`${server}${builder}/${gameId}`, archiveStream, {
+    const { data } = await axios.post(url, archiveStream, {
         maxRedirects: 0,
         responseType: 'stream',
     });
@@ -47,6 +95,6 @@ export async function send(gameId, contents, server, builder, deployFolder, pkg,
     }
 
     if (mode === 'extract') {
-        printBuildReport(builder, pkg);
+        printBuildReport(`${stage}-${family}`, pkg);
     }
 }

package/lib/node/index.js

@@ -1,7 +1,8 @@
-export { createArchive } from './archive.js';
+export { buildOutputDir, resolveBuildArtifactDir } from './artifacts.js';
+export { createArchive, createDeployArchive, createReleaseArchive, createSourceArchive } from './archive.js';
 export { loadProjectConfig, resolveServerUrl } from './config.js';
 export { send } from './deploy.js';
-export { adaptfullyFromCli, runAdaptfullyStage } from './pipeline.js';
+export { adaptfullyFromCli, parseStageArgs, runAdaptfullyStage } from './pipeline.js';
 export { prebuildPlatform, prebuildOutputDir, resolveHtmlInjections } from './prebuild.js';
 export { getPackageRoot, getRuntimeDir, resolveRuntimeScript } from './paths.js';
 export {
@@ -28,9 +29,14 @@ export {
     collectRegistrationParts,
     injectAdaptfullyRegistrations,
     resolveBuilderForPlatform,
+    resolveBuildSpec,
     resolveCliPlatformAndBuilder,
+    resolveDeploymentsForPlatform,
+    resolveFamily,
+    resolveFamilyFromTarget,
     resolvePlatformKey,
     resolvePlatformRegistrationsByKey,
+    resolvePublishDir,
     resolveRegistrationAssets,
 } from './registrations.js';
 export { printBuildReport } from './report.js';

package/lib/node/packagers/electron.js

@@ -178,6 +178,19 @@ export function buildElectronPreload(steamAppId) {
     return ELECTRON_PRELOAD_HEAD + steamAppId + ELECTRON_PRELOAD_TAIL;
 }
 
+/**
+ * Steamworks app ID for steam-auth preload, from the active platform config.
+ * @param {string | null | undefined} platformKey
+ * @param {{ config?: { platforms?: Record<string, { steamId?: number | string }> } }} pkg
+ * @returns {number | string | undefined}
+ */
+export function resolvePlatformSteamId(platformKey, pkg) {
+    if (!platformKey) {
+        return undefined;
+    }
+    return pkg.config?.platforms?.[platformKey]?.steamId;
+}
+
 export class ElectronPackager extends Packager {
     /** @type {'electron'} */
     static id = 'electron';
@@ -188,10 +201,10 @@ export class ElectronPackager extends Packager {
     validate() {
         super.validate();
 
-        if (this.usesPlugin('steam-auth') && !this.pkg.config?.steamId) {
+        if (this.usesPlugin('steam-auth') && !resolvePlatformSteamId(this.platformKey, this.pkg)) {
             const platformLabel = this.platformKey ?? this.platforms.join(', ');
             throw new Error(
-                `Platform "${platformLabel}" uses steam-auth but config.steamId is not set.`,
+                `Platform "${platformLabel}" uses steam-auth but platforms.${platformLabel}.steamId is not set.`,
             );
         }
     }
@@ -212,9 +225,10 @@ export class ElectronPackager extends Packager {
         const mainContent = buildElectronMain(withSteam, this.pkg.config?.themeColor);
 
         if (withSteam) {
+            const steamId = resolvePlatformSteamId(this.platformKey, this.pkg);
             fs.writeFileSync(
                 path.join(dest, 'preload.js'),
-                buildElectronPreload(this.pkg.config.steamId),
+                buildElectronPreload(steamId),
             );
             this.log('adaptfully: write preload.js (steam-auth)');
         }

package/lib/node/packagers/index.js

@@ -6,7 +6,12 @@ import { WebPackager } from './web.js';
 
 export { Packager, VALID_PACKAGERS } from './base.js';
 export { WebPackager } from './web.js';
-export { ElectronPackager, buildElectronMain, buildElectronPreload } from './electron.js';
+export {
+    ElectronPackager,
+    buildElectronMain,
+    buildElectronPreload,
+    resolvePlatformSteamId,
+} from './electron.js';
 export { CordovaPackager } from './cordova.js';
 export { CapacitorPackager } from './capacitor.js';
 
@@ -22,7 +27,7 @@ const PACKAGER_REGISTRY = {
 
 /**
  * @param {string} platformKey
- * @param {{ config?: { platforms?: Record<string, { packager?: string, registrations?: Record<string, string> }>, steamId?: number } }} pkg
+ * @param {{ config?: { platforms?: Record<string, { packager?: string, registrations?: Record<string, string>, steamId?: number | string }> } }} pkg
  * @param {{ log?: (message: string) => void, platforms?: string[] }} [options]
  * @returns {Packager}
  */
@@ -54,7 +59,7 @@ export function resolvePlatformPackager(platformKey, pkg) {
 
 /**
  * @param {string} platformKey
- * @param {{ config?: { platforms?: Record<string, { packager?: string, registrations?: Record<string, string> }>, steamId?: number } }} pkg
+ * @param {{ config?: { platforms?: Record<string, { packager?: string, registrations?: Record<string, string>, steamId?: number | string }> } }} pkg
  */
 export function validatePlatformPackager(platformKey, pkg) {
     createPackagerForPlatform(platformKey, pkg).validate();
@@ -70,7 +75,7 @@ export function usesSteamAuth(registrations) {
 /**
  * @param {string} dest
  * @param {string} platformKey
- * @param {{ config?: { platforms?: Record<string, { packager?: string, registrations?: Record<string, string> }>, steamId?: number } }} pkg
+ * @param {{ config?: { platforms?: Record<string, { packager?: string, registrations?: Record<string, string>, steamId?: number | string }> } }} pkg
  * @param {{ log?: (message: string) => void, platforms?: string[] }} [options]
  */
 export function applyPackagerTemplates(dest, platformKey, pkg, options = {}) {

package/lib/node/pipeline.js

@@ -1,50 +1,130 @@
 import { loadProjectConfig, resolveServerUrl } from './config.js';
 import { send } from './deploy.js';
+import { resolveBuildArtifactDir } from './artifacts.js';
 import { prebuildPlatform } from './prebuild.js';
-import { resolveBuilderForPlatform } from './registrations.js';
+import {
+    resolveBuildSpec,
+    resolveDeploymentsForPlatform,
+    resolvePublishDir,
+} from './registrations.js';
 import { steamAuthFromCli } from './steam-auth.js';
 
-/** @typedef {'prebuild' | 'build' | 'deploy'} AdaptfullyStage */
+/** @typedef {'prebuild' | 'build' | 'deploy' | 'release'} AdaptfullyStage */
 
-const VALID_STAGES = new Set(['prebuild', 'build', 'deploy']);
+const VALID_STAGES = new Set(['prebuild', 'build', 'deploy', 'release']);
 
 /**
  * @param {AdaptfullyStage} stage
  * @param {string} platformKey
- * @param {{ pkg: object, deployFolder: string, server?: string, mode?: string, builder?: string, log?: (message: string) => void, outputRoot?: string }} options
+ * @param {{ pkg: object, deployFolder: string, server?: string, mode?: string, deployment?: string, artifactPath?: string, log?: (message: string) => void, outputRoot?: string }} options
  */
 export async function runAdaptfullyStage(stage, platformKey, options) {
     if (!VALID_STAGES.has(stage)) {
-        throw new Error(`Unknown adaptfully stage "${stage}". Expected: prebuild, build, or deploy.`);
+        throw new Error(`Unknown adaptfully stage "${stage}". Expected: prebuild, build, deploy, or release.`);
     }
 
     const log = options.log ?? console.log;
     const { pkg, deployFolder } = options;
+    const buildSpec = resolveBuildSpec(platformKey, pkg);
+    let deployments = resolveDeploymentsForPlatform(platformKey, pkg);
 
-    const prebuiltDir = prebuildPlatform(deployFolder, platformKey, pkg, {
-        log,
-        outputRoot: options.outputRoot,
-    });
+    if (options.deployment) {
+        if (!deployments.includes(options.deployment)) {
+            throw new Error(
+                `Deployment "${options.deployment}" is not configured for platform "${platformKey}". `
+                + `Available deployments: ${deployments.join(', ')}`,
+            );
+        }
+        deployments = [options.deployment];
+    } else if (stage === 'build') {
+        deployments = ['zip'];
+    } else if (stage === 'deploy') {
+        deployments = deployments.filter((key) => key !== 'zip');
+    } else if (stage === 'release') {
+        deployments = deployments.filter((key) => key !== 'zip');
+    }
+
+    let artifactPath = options.artifactPath;
+    if (stage === 'deploy' && !artifactPath) {
+        artifactPath = resolveBuildArtifactDir(pkg, {
+            outputRoot: options.outputRoot,
+            platformKey,
+        });
+    }
+
+    const prebuiltDir = stage === 'deploy'
+        ? artifactPath
+        : prebuildPlatform(deployFolder, platformKey, pkg, {
+            log,
+            outputRoot: options.outputRoot,
+        });
 
     if (stage === 'prebuild') {
-        return { prebuiltDir, platformKey };
+        return { prebuiltDir, platformKey, buildSpec };
     }
 
-    const builder = options.builder ?? resolveBuilderForPlatform(platformKey, pkg);
-    log(`adaptfully: ${stage} ${platformKey} via Wrapfully builder "${builder}"`);
+    const gameId = `${pkg.name}-${pkg.version}`;
+    const contents = JSON.stringify(pkg);
+    /** @type {{ deploymentKey: string, stage: string, family: string }[]} */
+    const sent = [];
 
-    await send(
-        `${pkg.name}-${pkg.version}`,
-        JSON.stringify(pkg),
-        options.server,
-        builder,
-        prebuiltDir,
-        pkg,
-        options.mode ?? 'extract',
-        { log },
-    );
+    if (stage === 'release') {
+        const deploymentDirs = deployments.map((key) => resolvePublishDir(key));
+
+        log(`adaptfully: ${stage} ${platformKey} → ${buildSpec.family} (${buildSpec.targets.join(', ')})`);
+
+        await send(
+            gameId,
+            contents,
+            options.server,
+            'release',
+            buildSpec.family,
+            prebuiltDir,
+            pkg,
+            options.mode ?? 'extract',
+            {
+                log,
+                platformKey,
+                deploymentDirs,
+            },
+        );
+
+        sent.push({ deploymentKey: 'release', stage, family: buildSpec.family });
+        return { prebuiltDir, platformKey, buildSpec, deployments: sent, artifactPath };
+    }
+
+    for (const deploymentKey of deployments) {
+        const publishDir = deploymentKey === 'zip' ? undefined : resolvePublishDir(deploymentKey);
+        const wrapStage = stage === 'deploy' ? 'deploy' : 'build';
+
+        log(
+            `adaptfully: ${stage} ${platformKey} → `
+            + `${deploymentKey === 'zip' ? 'artifact zip' : `deployment "${deploymentKey}"`} `
+            + `via Wrapfully ${buildSpec.family}`,
+        );
 
-    return { prebuiltDir, platformKey, builder };
+        await send(
+            gameId,
+            contents,
+            options.server,
+            wrapStage,
+            buildSpec.family,
+            prebuiltDir,
+            pkg,
+            options.mode ?? 'extract',
+            {
+                log,
+                publishDir,
+                platformKey,
+                deploymentKey: wrapStage === 'deploy' ? deploymentKey : undefined,
+                artifactPath,
+            },
+        );
+
+        sent.push({ deploymentKey, stage: wrapStage, family: buildSpec.family });
+    }
+
+    return { prebuiltDir, platformKey, buildSpec, deployments: sent, artifactPath };
 }
 
 /**
@@ -58,22 +138,27 @@ export async function adaptfullyFromCli(argv = process.argv) {
     }
 
     const stage = command;
-    const platformKey = argv[3];
-    const cliServer = argv[4];
-    const mode = argv[5] ?? 'extract';
+    const { positionals, deployment, artifactPath } = parseStageArgs(argv.slice(3));
+    const platformKey = positionals[0];
+    const cliServer = positionals[1];
+    const mode = positionals[2] ?? 'extract';
 
     if (!stage || !platformKey) {
         throw new Error(
             'Usage:\n'
-            + '  adaptfully <prebuild|build|deploy> <platform> [server] [mode]\n'
+            + '  adaptfully <prebuild|build|deploy|release> <platform> [server] [mode] [--deployment <key>] [--artifact <path>]\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    prebuild + zip and send to Wrapfully (platform release when credentials are in the zip)\n'
+            + '  build     prebuild + POST /{family}/build (zip artifact only)\n'
+            + '  deploy    POST /deploy/{key} with prior artifact + deployment credentials\n'
+            + '  release   prebuild + POST /{family}/release (build + configured deployments)\n'
             + '\n'
-            + '  steam-auth  Install steamcmd if needed, log in interactively, write assets/meta/publish/steam.json',
+            + '  --deployment <key>  Target a single named deployment.\n'
+            + '  --artifact <path>   Prior build artifact directory (deploy only; default: ./output/ after build).\n'
+            + '\n'
+            + '  steam-auth  Install steamcmd if needed, log in interactively, write steam deployment steam.json',
         );
     }
 
@@ -86,5 +171,36 @@ export async function adaptfullyFromCli(argv = process.argv) {
         deployFolder,
         server,
         mode,
+        deployment,
+        artifactPath,
     });
 }
+
+/**
+ * @param {string[]} args
+ * @returns {{ positionals: string[], deployment?: string, artifactPath?: string }}
+ */
+export function parseStageArgs(args) {
+    /** @type {string[]} */
+    const positionals = [];
+    let deployment;
+    let artifactPath;
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+
+        if (arg === '--deployment' && args[i + 1]) {
+            deployment = args[++i];
+        } else if (arg.startsWith('--deployment=')) {
+            deployment = arg.slice('--deployment='.length);
+        } else if (arg === '--artifact' && args[i + 1]) {
+            artifactPath = args[++i];
+        } else if (arg.startsWith('--artifact=')) {
+            artifactPath = arg.slice('--artifact='.length);
+        } else {
+            positionals.push(arg);
+        }
+    }
+
+    return { positionals, deployment, artifactPath };
+}

package/lib/node/registrations.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import { resolveRuntimeScript } from './paths.js';
 
 /** @typedef {Record<string, string>} RegistrationMap */
@@ -299,20 +300,119 @@ export function adaptfullyInjectionForPlatform(platformKey, pkg, options = {}) {
 }
 
 /**
+ * Resolve the deployment target keys for a platform. A platform may declare a
+ * `deployments` array (each entry maps to assets/meta/deployments/<key>/), which
+ * lets one build fan out to multiple targets of the same platform type. When no
+ * `deployments` array is present, the default is `["zip"]` (artifact download only).
+ *
  * @param {string} platformKey
- * @param {{ config?: { platforms?: Record<string, { builder?: string }> } }} pkg
+ * @param {{ config?: { platforms?: Record<string, { deployments?: string[] }> } }} pkg
+ * @returns {string[]}
  */
-export function resolveBuilderForPlatform(platformKey, pkg) {
-    const platform = pkg.config?.platforms?.[platformKey];
-    if (platform?.builder) {
-        return platform.builder;
+export function resolveDeploymentsForPlatform(platformKey, pkg) {
+    const deployments = pkg.config?.platforms?.[platformKey]?.deployments;
+
+    if (Array.isArray(deployments) && deployments.length > 0) {
+        for (const key of deployments) {
+            if (typeof key !== 'string' || !key.length) {
+                throw new Error(
+                    `config.platforms.${platformKey}.deployments entries must be non-empty strings`,
+                );
+            }
+        }
+        return [...deployments];
+    }
+
+    return ['zip'];
+}
+
+/**
+ * Absolute-or-cwd-relative path to a deployment's credential/publish folder.
+ *
+ * @param {string} deploymentKey
+ * @param {string} [metaDir='assets/meta']
+ * @returns {string}
+ */
+export function resolvePublishDir(deploymentKey, metaDir = 'assets/meta') {
+    return path.join(metaDir, 'deployments', deploymentKey);
+}
+
+const ELECTRON_TARGETS = new Set([
+    'win', 'win-dev', 'mac', 'mac-dev', 'linux', 'linux-dev',
+]);
+const CORDOVA_TARGETS = new Set([
+    'android', 'android-dev', 'ios', 'ios-dev', 'ios-sim',
+]);
+
+/**
+ * @param {string} target
+ * @returns {string | null}
+ */
+export function resolveFamilyFromTarget(target) {
+    if (ELECTRON_TARGETS.has(target)) {
+        return 'electron';
+    }
+    if (CORDOVA_TARGETS.has(target)) {
+        return 'cordova';
+    }
+    if (target === 'webapp' || target === 'web') {
+        return 'webapp';
+    }
+    if (target === 'uwp') {
+        return 'uwp';
+    }
+    return null;
+}
+
+/**
+ * @param {string[]} targets
+ * @param {string} [packager]
+ */
+export function resolveFamily(targets, packager) {
+    if (packager === 'electron') {
+        return 'electron';
+    }
+    if (packager === 'cordova' || packager === 'capacitor') {
+        return 'cordova';
+    }
+
+    const families = [...new Set(targets.map((target) => resolveFamilyFromTarget(target)).filter(Boolean))];
+
+    if (families.length === 1) {
+        return families[0];
     }
 
-    if (platformKey === 'web') {
+    if (targets.length === 1 && targets[0] === 'webapp') {
         return 'webapp';
     }
 
-    return platformKey;
+    throw new Error(`Cannot resolve builder family for targets [${targets.join(', ')}]`);
+}
+
+/**
+ * @param {string} platformKey
+ * @param {{ config?: { platforms?: Record<string, { builder?: string | string[], packager?: string, steamworks?: boolean, deployments?: string[] }> } }} pkg
+ */
+export function resolveBuildSpec(platformKey, pkg) {
+    const platform = pkg.config?.platforms?.[platformKey];
+    const builder = platform?.builder ?? (platformKey === 'web' ? 'webapp' : platformKey);
+    const targets = Array.isArray(builder) ? [...builder] : [builder];
+
+    return {
+        family: resolveFamily(targets, platform?.packager),
+        targets,
+        platformKey,
+        steamworks: platform?.steamworks === true,
+        deployments: resolveDeploymentsForPlatform(platformKey, pkg),
+    };
+}
+
+/**
+ * @param {string} platformKey
+ * @param {{ config?: { platforms?: Record<string, { builder?: string | string[] }> } }} pkg
+ */
+export function resolveBuilderForPlatform(platformKey, pkg) {
+    return resolveBuildSpec(platformKey, pkg).family;
 }
 
 /**
@@ -323,9 +423,11 @@ export function resolveCliPlatformAndBuilder(arg, pkg) {
     const platforms = pkg.config?.platforms ?? {};
 
     if (platforms[arg]) {
+        const spec = resolveBuildSpec(arg, pkg);
         return {
             platformKey: arg,
-            builder: resolveBuilderForPlatform(arg, pkg),
+            builder: spec.family,
+            buildSpec: spec,
         };
     }
 

package/lib/node/steam-auth.js

@@ -26,7 +26,7 @@ const STEAMCMD_INSTALL = {
  * @param {string} [projectRoot]
  */
 export function defaultSteamPublishPath(projectRoot = '.') {
-    return path.resolve(projectRoot, 'assets', 'meta', 'publish', 'steam.json');
+    return path.resolve(projectRoot, 'assets', 'meta', 'deployments', 'steam', 'steam.json');
 }
 
 /**

package/package.json

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