@makefully/adaptfully 3.10.0 → 3.11.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project are documented in this file.
 
+## 3.11.0 — 2026-07-23
+
+### Added
+
+- **Layered icon validation** — build/deploy/release zips always include `meta/icon-foreground.png` and `meta/icon-background.png`. When project icons are missing under `assets/meta/`, Adaptfully **warns** (does not fail) and ships packaged placeholder icons from `lib/assets/`.
+- **`resolveMetaIcons` / `appendMetaIcons`** — exported helpers for resolving project vs placeholder icon paths.
+
+### Changed
+
+- Legacy meta packaging skips re-adding icon filenames so placeholders and project icons are not duplicated in the zip.
+
 ## 3.10.0 — 2026-07-17
 
 ### Added
@@ -13,6 +24,7 @@ All notable changes to this project are documented in this file.
 
 - **Builder family defaults** — `android` / `ios` / `ios-sim` (and `-dev`) resolve to Wrapfully family **`capacitor`**. Explicit `packager: "cordova"` still selects Cordova for that platform. Composite `cordova` / `apple` routes are not used.
 - **`resolveBuildSpec`** includes `socialLogin: boolean`.
+- **Single-target Wrapfully POSTs** go to the target route (`/android/build`, `/ios/release`, …) instead of the family route (`/capacitor/...`), so OS relay and existing target routes keep working.
 
 ## 3.9.0 — 2026-07-15
 

package/README.md

@@ -363,7 +363,7 @@ mygame/
 
 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 (`icon-foreground.png`, `icon-background.png`) are required for mobile, desktop, and Steam builds. If either file is missing from `assets/meta/`, Adaptfully **warns** and ships packaged placeholder icons for that build so Wrapfully can still run.
 
 ### Icons
 
@@ -378,6 +378,8 @@ The build server composites the foreground over the background, applies a bindin
 
 **Recommended format:** 1536×1536 pixel square PNGs for both files. Images with other dimensions are scaled to 1536×1536 automatically, but matching the target size produces the sharpest results.
 
+Missing icons do not fail the Adaptfully client: check the `WARNING missing layered icon(s)` log line and replace the placeholders before a store release.
+
 ## Configuration
 
 Build settings are read from `package.json`. The client merges any `wrapfully.json` fields into `package.json`'s `config` object before sending.

package/lib/node/archive.js

@@ -1,9 +1,9 @@
 import archiver from 'archiver';
 import fs from 'node:fs';
 import path from 'node:path';
+import { appendMetaIcons, isMetaIconFilename, META_DIR } from './icons.js';
 
 const
-    META_DIR = 'assets/meta',
     DEPLOYMENTS_DIRNAME = 'deployments',
     PUBLISH_DIRNAME = 'publish';
 
@@ -38,6 +38,9 @@ function appendMeta(zip, publishDir, deploymentDirs = [], options = {}) {
         log = options.log ?? (() => {}),
         metaDir = path.resolve(META_DIR);
 
+    // Always ship layered icons (project files or Adaptfully placeholders).
+    appendMetaIcons(zip, { metaDir, log });
+
     if (!fs.existsSync(metaDir)) {
         log(`adaptfully: meta dir missing at ${metaDir}; skipping credentials`);
         return;
@@ -46,7 +49,17 @@ function appendMeta(zip, publishDir, deploymentDirs = [], options = {}) {
     const deploymentsRoot = path.join(metaDir, DEPLOYMENTS_DIRNAME);
 
     if (!fs.existsSync(deploymentsRoot)) {
-        appendDirectory(zip, metaDir, 'meta');
+        for (const entry of fs.readdirSync(metaDir, { withFileTypes: true })) {
+            if (isMetaIconFilename(entry.name)) {
+                continue;
+            }
+            const fullPath = path.join(metaDir, entry.name);
+            if (entry.isDirectory()) {
+                appendDirectory(zip, fullPath, `meta/${entry.name}`);
+            } else {
+                zip.file(fullPath, { name: `meta/${entry.name}` });
+            }
+        }
         return;
     }
 
@@ -54,6 +67,9 @@ function appendMeta(zip, publishDir, deploymentDirs = [], options = {}) {
         if (entry.name === DEPLOYMENTS_DIRNAME || entry.name === PUBLISH_DIRNAME) {
             continue;
         }
+        if (isMetaIconFilename(entry.name)) {
+            continue;
+        }
 
         const fullPath = path.join(metaDir, entry.name);
         if (entry.isDirectory()) {

package/lib/node/icons.js

@@ -0,0 +1,97 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getPackageRoot } from './paths.js';
+
+export const META_DIR = 'assets/meta';
+export const ICON_FOREGROUND = 'icon-foreground.png';
+export const ICON_BACKGROUND = 'icon-background.png';
+
+const ICON_FILES = [ICON_FOREGROUND, ICON_BACKGROUND];
+
+/**
+ * Absolute path to a packaged Adaptfully placeholder icon.
+ * @param {string} filename
+ */
+export function resolvePlaceholderIconPath(filename) {
+    return path.join(getPackageRoot(), 'lib', 'assets', filename);
+}
+
+/**
+ * @param {string} [metaDir=META_DIR]
+ */
+export function resolveMetaIconPaths(metaDir = META_DIR) {
+    const root = path.resolve(metaDir);
+    return {
+        metaDir: root,
+        foreground: path.join(root, ICON_FOREGROUND),
+        background: path.join(root, ICON_BACKGROUND),
+    };
+}
+
+/**
+ * Resolve layered icon paths for Wrapfully packaging. Warns (does not throw) when
+ * project icons are missing and falls back to Adaptfully placeholders.
+ *
+ * @param {{ metaDir?: string, log?: (message: string) => void }} [options]
+ * @returns {{
+ *   metaDir: string,
+ *   foreground: string,
+ *   background: string,
+ *   missing: string[],
+ *   usedPlaceholders: boolean,
+ * }}
+ */
+export function resolveMetaIcons(options = {}) {
+    const log = options.log ?? console.log;
+    const { metaDir, foreground, background } = resolveMetaIconPaths(options.metaDir);
+    /** @type {string[]} */
+    const missing = [];
+    let resolvedForeground = foreground;
+    let resolvedBackground = background;
+
+    if (!fs.existsSync(foreground)) {
+        missing.push(ICON_FOREGROUND);
+        resolvedForeground = resolvePlaceholderIconPath(ICON_FOREGROUND);
+    }
+    if (!fs.existsSync(background)) {
+        missing.push(ICON_BACKGROUND);
+        resolvedBackground = resolvePlaceholderIconPath(ICON_BACKGROUND);
+    }
+
+    if (missing.length > 0) {
+        log(
+            `adaptfully: WARNING missing layered icon(s) in ${metaDir}: ${missing.join(', ')}. `
+            + 'Using Adaptfully placeholder icons for this build.',
+        );
+    }
+
+    return {
+        metaDir,
+        foreground: resolvedForeground,
+        background: resolvedBackground,
+        missing,
+        usedPlaceholders: missing.length > 0,
+    };
+}
+
+/**
+ * Append layered icons to a zip under meta/. Uses project icons when present;
+ * otherwise warns and ships Adaptfully placeholders.
+ *
+ * @param {import('archiver').Archiver} zip
+ * @param {{ metaDir?: string, log?: (message: string) => void }} [options]
+ * @returns {ReturnType<typeof resolveMetaIcons>}
+ */
+export function appendMetaIcons(zip, options = {}) {
+    const resolved = resolveMetaIcons(options);
+    zip.file(resolved.foreground, { name: `meta/${ICON_FOREGROUND}` });
+    zip.file(resolved.background, { name: `meta/${ICON_BACKGROUND}` });
+    return resolved;
+}
+
+/**
+ * @param {string} name
+ */
+export function isMetaIconFilename(name) {
+    return ICON_FILES.includes(name);
+}

package/lib/node/index.js

@@ -2,7 +2,17 @@ export { buildOutputDir, clearStaleBuildExtract, resolveBuildArtifactDir } from
 export { createArchive, createDeployArchive, createReleaseArchive, createSourceArchive } from './archive.js';
 export { loadProjectConfig, resolveServerUrl } from './config.js';
 export { send } from './deploy.js';
-export { adaptfullyFromCli, parseStageArgs, runAdaptfullyStage } from './pipeline.js';
+export {
+    appendMetaIcons,
+    ICON_BACKGROUND,
+    ICON_FOREGROUND,
+    isMetaIconFilename,
+    META_DIR,
+    resolveMetaIconPaths,
+    resolveMetaIcons,
+    resolvePlaceholderIconPath,
+} from './icons.js';
+export { adaptfullyFromCli, parseStageArgs, resolveWrapfullyRoute, runAdaptfullyStage } from './pipeline.js';
 export { prebuildPlatform, prebuildOutputDir, resolveHtmlInjections } from './prebuild.js';
 export { getPackageRoot, getRuntimeDir, resolveRuntimeScript } from './paths.js';
 export {

package/lib/node/pipeline.js

@@ -14,6 +14,21 @@ import { steamAuthFromCli } from './steam-auth.js';
 
 const VALID_STAGES = new Set(['prebuild', 'build', 'deploy', 'release']);
 
+/**
+ * Wrapfully URL path segment for build/release.
+ * Single-target platforms post to the target route (`android`, `ios`, …) so OS relay
+ * and long-standing target routes work; multi-target platforms post to the family
+ * (`electron`, …).
+ *
+ * @param {{ family: string, targets: string[] }} buildSpec
+ */
+export function resolveWrapfullyRoute(buildSpec) {
+    if (buildSpec.targets.length === 1) {
+        return buildSpec.targets[0];
+    }
+    return buildSpec.family;
+}
+
 /**
  * @param {AdaptfullyStage} stage
  * @param {string} platformKey
@@ -69,10 +84,15 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
     /** @type {{ deploymentKey: string, stage: string, family: string }[]} */
     const sent = [];
 
+    const wrapfullyRoute = resolveWrapfullyRoute(buildSpec);
+
     if (stage === 'release') {
         const deploymentDirs = deployments.map((key) => resolvePublishDir(key));
 
-        log(`adaptfully: ${stage} ${platformKey} → ${buildSpec.family} (${buildSpec.targets.join(', ')})`);
+        log(
+            `adaptfully: ${stage} ${platformKey} → ${buildSpec.family} `
+            + `(${buildSpec.targets.join(', ')}) via /${wrapfullyRoute}/release`,
+        );
 
         log(
             `adaptfully: release deployments → ${
@@ -85,7 +105,7 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
             contents,
             options.server,
             'release',
-            buildSpec.family,
+            wrapfullyRoute,
             prebuiltDir,
             pkg,
             options.mode ?? 'extract',
@@ -107,7 +127,7 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
         log(
             `adaptfully: ${stage} ${platformKey} → `
             + `${deploymentKey === 'zip' ? 'artifact zip' : `deployment "${deploymentKey}"`} `
-            + `via Wrapfully ${buildSpec.family}`,
+            + `via Wrapfully /${wrapfullyRoute}/${wrapStage} (${buildSpec.family})`,
         );
 
         await send(
@@ -115,7 +135,7 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
             contents,
             options.server,
             wrapStage,
-            buildSpec.family,
+            wrapfullyRoute,
             prebuiltDir,
             pkg,
             options.mode ?? 'extract',
@@ -158,9 +178,9 @@ export async function adaptfullyFromCli(argv = process.argv) {
             + '\n'
             + 'Stages:\n'
             + '  prebuild  Copy deploy/ and apply platform registrations → output/<platform>-prebuild/\n'
-            + '  build     prebuild + POST /{family}/build (zip artifact only)\n'
+            + '  build     prebuild + POST /{target|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'
+            + '  release   prebuild + POST /{target|family}/release (build + configured deployments)\n'
             + '\n'
             + '  --deployment <key>  Target a single named deployment.\n'
             + '  --artifact <path>   Prior build artifact directory (deploy only; default: ./output/ after build).\n'

package/package.json

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