@makefully/adaptfully 5.2.0 → 5.3.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project are documented in this file.
 
+## 5.3.0 — 2026-11-11
+
+### Added
+
+- **Store-assets upload ledger** — `lib/node/store-assets-ledger.js` owns `meta/store-assets/upload-ledger.json` (sequenced SHA-256 set skip for Play/ASC listing sync).
+- **Opt-in listing deploys** — `adaptfully deploy <platform> --deployment *-listing` may target keys not in the platform release fan-out; assets-only zips skip the prior AAB/IPA tree and package `credentialsFrom` sibling folders under `meta/deployments/`.
+
 ## 5.2.0 — 2026-11-11
 
 ### Added

package/lib/node/archive.js

@@ -163,20 +163,37 @@ export function createArchive(deployFolder, contents, options = {}) {
 }
 
 /**
- * Prior artifact zip plus one deployment folder for /deploy.
+ * Prior artifact zip plus deployment folder(s) for /deploy.
+ * Always packages non-deployment meta (including store-assets) from META_DIR.
  *
  * @param {string} artifactPath
- * @param {string} publishDir
+ * @param {string} publishDir Primary deployment folder (…/meta/deployments/<key>)
  * @param {string} [contents]
- * @param {{ log?: (message: string) => void }} [options]
+ * @param {{ log?: (message: string) => void, deploymentDirs?: string[], includeArtifact?: boolean }} [options]
  */
 export function createDeployArchive(artifactPath, publishDir, contents, options = {}) {
     const
         zip = archiver('zip', { zlib: { level: 0 } }),
-        log = options.log ?? console.log;
+        log = options.log ?? console.log,
+        includeArtifact = options.includeArtifact !== false,
+        extraDirs = Array.isArray(options.deploymentDirs) ? options.deploymentDirs : [];
+
+    if (includeArtifact && artifactPath && fs.existsSync(artifactPath)) {
+        zip.directory(toPosixDir(artifactPath), false);
+    }
 
-    zip.directory(toPosixDir(artifactPath), false);
-    appendMeta(zip, publishDir, [], { log });
+    // Prefer meta/deployments/<key> packaging (not legacy meta/publish) so
+    // credentialsFrom sibling keys resolve under the same layout Wrapfully reads.
+    const dirs = [];
+    if (publishDir) {
+        dirs.push(publishDir);
+    }
+    for (const dir of extraDirs) {
+        if (dir && !dirs.includes(dir)) {
+            dirs.push(dir);
+        }
+    }
+    appendMeta(zip, null, dirs, { log });
 
     if (contents) {
         zip.append(contents, { name: 'package.json' });

package/lib/node/deploy.js

@@ -227,6 +227,7 @@ export async function submitWrapfullyChore ({
  *   platformKey?: string,
  *   deploymentKey?: string,
  *   artifactPath?: string,
+ *   includeArtifact?: boolean,
  *   accessToken?: string,
  *   encrypt?: boolean,
  *   encryptPublicKey?: string,
@@ -273,7 +274,11 @@ export async function send (
         if (!options.deploymentKey) {
             throw new Error('deploy stage requires options.deploymentKey');
         }
-        archiveStream = createDeployArchive(options.artifactPath, options.publishDir, contents, {log});
+        archiveStream = createDeployArchive(options.artifactPath, options.publishDir, contents, {
+            log,
+            deploymentDirs: options.deploymentDirs,
+            includeArtifact: options.includeArtifact !== false,
+        });
     } else if (stage === 'release') {
         archiveStream = createReleaseArchive(deployFolder, contents, options.deploymentDirs ?? [], {log});
     } else {

package/lib/node/index.js

@@ -115,3 +115,20 @@ export {
     runAppleSigning,
     runOpenssl,
 } from './apple-signing.js';
+export {
+    LEDGER_FILENAME,
+    LEDGER_VERSION,
+    emptyLedger,
+    ledgerFileExists,
+    ledgerMatchesSet,
+    ledgerPath,
+    listOrderedImageFiles,
+    makeSetKey,
+    readLedger,
+    recordSetSuccess,
+    sequencesEqual,
+    sha256Buffer,
+    sha256File,
+    sha256Sequence,
+    writeLedger,
+} from './store-assets-ledger.js';

package/lib/node/pipeline.js

@@ -1,3 +1,5 @@
+import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { loadProjectConfig, resolveServerUrl, resolveAccessToken, resolveEncryptFlag } from './config.js';
 import { send } from './deploy.js';
@@ -21,6 +23,28 @@ import { androidKeystoreFromCli } from './android-keystore.js';
 import { appleSigningFromCli } from './apple-signing.js';
 import { buildGameId } from './fs-name.js';
 
+/**
+ * @param {string} deploymentDir
+ * @returns {object | null}
+ */
+function readDeploymentManifest(deploymentDir) {
+    try {
+        const raw = fs.readFileSync(path.join(deploymentDir, 'manifest.json'), 'utf8');
+        return JSON.parse(raw);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Listing sync deployers do not need the prior AAB/IPA artifact tree.
+ * @param {string | null | undefined} type
+ * @returns {boolean}
+ */
+function isListingDeployerType(type) {
+    return type === 'google-listing' || type === 'apple-listing';
+}
+
 /** @typedef {'prebuild' | 'build' | 'deploy' | 'release'} AdaptfullyStage */
 
 const VALID_STAGES = new Set(['prebuild', 'build', 'deploy', 'release']);
@@ -66,11 +90,17 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
         ?? resolveExtractRoot(outputRoot, platformKey);
 
     if (options.deployment) {
+        const publishDir = resolvePublishDir(options.deployment);
+        const exists = fs.existsSync(publishDir);
         if (!deployments.includes(options.deployment)) {
-            throw new Error(
-                `Deployment "${options.deployment}" is not configured for platform "${platformKey}". `
-                + `Available deployments: ${deployments.join(', ')}`,
-            );
+            // Deploy stage may target opt-in keys (e.g. android-listing) that are
+            // intentionally omitted from the platform's release fan-out list.
+            if (stage !== 'deploy' || !exists) {
+                throw new Error(
+                    `Deployment "${options.deployment}" is not configured for platform "${platformKey}". `
+                    + `Available deployments: ${deployments.join(', ')}`,
+                );
+            }
         }
         deployments = [options.deployment];
     } else if (stage === 'build') {
@@ -83,10 +113,19 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
 
     let artifactPath = options.artifactPath;
     if (stage === 'deploy' && !artifactPath) {
-        artifactPath = resolveBuildArtifactDir(pkg, {
-            outputRoot: options.outputRoot,
-            platformKey,
-        });
+        const primaryKey = deployments[0];
+        const primaryManifest = primaryKey
+            ? readDeploymentManifest(resolvePublishDir(primaryKey))
+            : null;
+        if (isListingDeployerType(primaryManifest?.type)) {
+            // Assets-only: meta/store-assets + deployment folders; skip heavy binary tree.
+            artifactPath = fs.mkdtempSync(path.join(os.tmpdir(), 'adaptfully-listing-'));
+        } else {
+            artifactPath = resolveBuildArtifactDir(pkg, {
+                outputRoot: options.outputRoot,
+                platformKey,
+            });
+        }
     }
 
     const prebuiltDir = stage === 'deploy'
@@ -153,9 +192,25 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
     for (const deploymentKey of deployments) {
         const publishDir = deploymentKey === 'zip' ? undefined : resolvePublishDir(deploymentKey);
         const wrapStage = stage === 'deploy' ? 'deploy' : 'build';
-        const deploymentDirs = wrapStage === 'build'
+        /** @type {string[]} */
+        let deploymentDirs = wrapStage === 'build'
             ? resolveBuildCredentialDirs(platformKey, pkg)
             : [];
+        let includeArtifact = true;
+
+        if (wrapStage === 'deploy' && publishDir) {
+            const manifest = readDeploymentManifest(publishDir);
+            if (isListingDeployerType(manifest?.type)) {
+                includeArtifact = Boolean(options.artifactPath);
+                deploymentDirs = [];
+                if (manifest?.credentialsFrom) {
+                    const sibling = resolvePublishDir(String(manifest.credentialsFrom));
+                    if (fs.existsSync(sibling)) {
+                        deploymentDirs.push(sibling);
+                    }
+                }
+            }
+        }
 
         log(
             `adaptfully: ${stage} ${platformKey} → `
@@ -165,9 +220,13 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
 
         if (deploymentDirs.length) {
             log(
-                `adaptfully: build signing credentials → ${
-                    deploymentDirs.map((dir) => path.resolve(dir)).join(', ')
-                }`,
+                wrapStage === 'deploy'
+                    ? `adaptfully: listing credentialsFrom → ${
+                        deploymentDirs.map((dir) => path.resolve(dir)).join(', ')
+                    }`
+                    : `adaptfully: build signing credentials → ${
+                        deploymentDirs.map((dir) => path.resolve(dir)).join(', ')
+                    }`,
             );
         }
         log(`adaptfully: extract → ${extractRoot}`);
@@ -187,6 +246,7 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
                 deploymentDirs,
                 deploymentKey: wrapStage === 'deploy' ? deploymentKey : undefined,
                 artifactPath,
+                includeArtifact,
             },
         );
 

package/lib/node/store-assets-ledger.js

@@ -0,0 +1,194 @@
+/**
+ * Upload ledger for store listing image sets (Play, ASC, future platforms).
+ * Lives at assets/meta/store-assets/upload-ledger.json (zip: meta/store-assets/…).
+ *
+ * Set key: `{platform}/{locale}/{slot}` e.g. google/en-US/phoneScreenshots
+ */
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const LEDGER_FILENAME = 'upload-ledger.json';
+export const LEDGER_VERSION = 1;
+
+/**
+ * @param {string} storeAssetsRoot Absolute path to store-assets (…/meta/store-assets)
+ * @returns {string}
+ */
+export function ledgerPath(storeAssetsRoot) {
+    return path.join(storeAssetsRoot, LEDGER_FILENAME);
+}
+
+/**
+ * @param {string} platform
+ * @param {string} locale
+ * @param {string} slot
+ * @returns {string}
+ */
+export function makeSetKey(platform, locale, slot) {
+    return `${platform}/${locale}/${slot}`;
+}
+
+/**
+ * @param {string | Buffer | Uint8Array} data
+ * @returns {string}
+ */
+export function sha256Buffer(data) {
+    return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<string>}
+ */
+export async function sha256File(filePath) {
+    const hash = crypto.createHash('sha256');
+    const handle = await fsp.open(filePath, 'r');
+    try {
+        const stream = handle.createReadStream();
+        for await (const chunk of stream) {
+            hash.update(chunk);
+        }
+    } finally {
+        await handle.close();
+    }
+    return hash.digest('hex');
+}
+
+/**
+ * Ordered SHA-256 for each path (display / upload order).
+ * @param {string[]} filePaths Absolute paths
+ * @returns {Promise<string[]>}
+ */
+export async function sha256Sequence(filePaths) {
+    const out = [];
+    for (const filePath of filePaths) {
+        out.push(await sha256File(filePath));
+    }
+    return out;
+}
+
+/**
+ * @param {string[]} a
+ * @param {string[]} b
+ * @returns {boolean}
+ */
+export function sequencesEqual(a, b) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i += 1) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * @returns {{ version: number, sets: Record<string, object> }}
+ */
+export function emptyLedger() {
+    return { version: LEDGER_VERSION, sets: {} };
+}
+
+/**
+ * @param {string} storeAssetsRoot
+ * @returns {Promise<{ version: number, sets: Record<string, object> }>}
+ */
+export async function readLedger(storeAssetsRoot) {
+    const file = ledgerPath(storeAssetsRoot);
+    try {
+        const raw = await fsp.readFile(file, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object') {
+            return emptyLedger();
+        }
+        const sets = parsed.sets && typeof parsed.sets === 'object' ? parsed.sets : {};
+        return { version: Number(parsed.version) || LEDGER_VERSION, sets };
+    } catch (err) {
+        if (err && (err.code === 'ENOENT' || err instanceof SyntaxError)) {
+            return emptyLedger();
+        }
+        throw err;
+    }
+}
+
+/**
+ * @param {string} storeAssetsRoot
+ * @param {{ version?: number, sets: Record<string, object> }} ledger
+ * @returns {Promise<void>}
+ */
+export async function writeLedger(storeAssetsRoot, ledger) {
+    await fsp.mkdir(storeAssetsRoot, { recursive: true });
+    const payload = {
+        version: ledger.version || LEDGER_VERSION,
+        sets: ledger.sets || {},
+    };
+    await fsp.writeFile(ledgerPath(storeAssetsRoot), `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * @param {{ version: number, sets: Record<string, object> }} ledger
+ * @param {string} setKey
+ * @param {string[]} sequence
+ * @param {boolean} [force]
+ * @returns {boolean} true when local sequence matches last successful upload
+ */
+export function ledgerMatchesSet(ledger, setKey, sequence, force = false) {
+    if (force) {
+        return false;
+    }
+    const entry = ledger?.sets?.[setKey];
+    if (!entry || !Array.isArray(entry.sha256Sequence)) {
+        return false;
+    }
+    return sequencesEqual(entry.sha256Sequence, sequence);
+}
+
+/**
+ * Record a successful upload for one set. Does not touch other sets.
+ * @param {{ version: number, sets: Record<string, object> }} ledger
+ * @param {string} setKey
+ * @param {{ sha256Sequence: string[], assetIds?: string[], uploadedAt?: string }} update
+ */
+export function recordSetSuccess(ledger, setKey, update) {
+    if (!ledger.sets) {
+        ledger.sets = {};
+    }
+    ledger.sets[setKey] = {
+        sha256Sequence: [...update.sha256Sequence],
+        uploadedAt: update.uploadedAt || new Date().toISOString(),
+        ...(Array.isArray(update.assetIds) ? { assetIds: [...update.assetIds] } : {}),
+    };
+}
+
+/**
+ * Sync-friendly: list image files in a directory in alphanumeric order.
+ * @param {string} dir
+ * @returns {Promise<string[]>} Absolute paths
+ */
+export async function listOrderedImageFiles(dir) {
+    let names;
+    try {
+        names = await fsp.readdir(dir);
+    } catch (err) {
+        if (err && err.code === 'ENOENT') {
+            return [];
+        }
+        throw err;
+    }
+    const images = names
+        .filter((name) => /\.(png|jpe?g|webp)$/i.test(name))
+        .sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
+    return images.map((name) => path.join(dir, name));
+}
+
+/**
+ * @param {string} storeAssetsRoot
+ * @returns {boolean}
+ */
+export function ledgerFileExists(storeAssetsRoot) {
+    return fs.existsSync(ledgerPath(storeAssetsRoot));
+}

package/package.json

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