@magicpixelart/cli 0.5.21 → 0.5.24

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.24] — 2026-09-21
+
+- `push --force` keeps your local copy when a sprite changed in both places. It
+  re-sends against the live cloud state rather than skipping the safety check,
+  so a save that lands in between is still reported instead of overwritten.
+- A both-sides-changed refusal now carries the live cloud fingerprint, so a
+  follow-up `push` works even for large documents whose hash wasn't cached —
+  the last case where the sync/push advice could still dead-end.
+- Conflict messages name both ways out: press Sync on the artboard, or
+  `push --force`.
+
+## [0.5.23] — 2026-09-21
+
+- Pressing Sync on an artboard now explicitly chooses MagicPixel's copy when
+  that PNG was also edited locally, resolving the previous sync/push loop.
+- Conflict lists are capped, nested push warnings no longer repeat during
+  sync, and completion summaries include locally unchanged sprites accurately.
+
+## [0.5.22] — 2026-09-14
+
+- Raised the daily sprite download allowance from 1 GiB to 10 GiB for large
+  projects.
+- Daily allowance exhaustion now stops the current request with its UTC reset
+  time instead of sleeping inside `sync --watch` and appearing frozen. Short
+  burst limits continue to retry automatically.
+- `sync --watch` now reports an exhausted allowance once, with a countdown to
+  the reset, then re-checks every 15 minutes instead of retrying every minute
+  all night (each retry counted against the daily request allowance).
+- Allowance messages now say "API allowance" — the same limit covers requests
+  as well as downloaded bytes.
+
 ## [0.5.21] — 2026-09-14
 
 - `sync --watch` can no longer hang forever: every network request now has a

package/dist/api.js

@@ -75,14 +75,21 @@ export class ApiError extends Error {
     status;
     requestId;
     retryAfterMs;
-    constructor(status, message, requestId, retryAfterMs) {
+    code;
+    constructor(status, message, requestId, retryAfterMs, code) {
         super(message);
         this.status = status;
         this.requestId = requestId;
         this.retryAfterMs = retryAfterMs;
+        this.code = code;
     }
 }
-function friendly(status, body, context) {
+export const DAILY_QUOTA_ERROR_CODE = 'daily_quota_exceeded';
+/** Stable API error code; the response body retains legacy text for old CLIs. */
+export function errorCodeFromResponse(res) {
+    return res.headers.get('x-magicpixel-error-code') ?? undefined;
+}
+export function friendlyApiError(status, body, context, code) {
     if (status === 401 || status === 403) {
         return (`${context}: ${status} — API key rejected.\n` +
             `  Fix: regenerate at https://magicpixel.art/settings and re-run \`${cmd('login')}\`.`);
@@ -92,6 +99,9 @@ function friendly(status, body, context) {
             `  Fix: check the "endpoint" field in magicpixel.json, or remove it to use the default.`);
     }
     if (status === 429) {
+        if (code === DAILY_QUOTA_ERROR_CODE) {
+            return `${context}: daily MagicPixel API allowance reached. Resets at 00:00 UTC.`;
+        }
         return `${context}: 429 — rate limited. Retry shortly.`;
     }
     if (status === 546) {
@@ -194,7 +204,8 @@ export async function fetchManifestPage(opts) {
             return data;
         }
         const bodyText = await res.text();
-        throw new ApiError(res.status, withRequestId(friendly(res.status, bodyText, 'manifest'), serverRequestId), serverRequestId, retryAfterMsFromResponse(res));
+        const errorCode = errorCodeFromResponse(res);
+        throw new ApiError(res.status, withRequestId(friendlyApiError(res.status, bodyText, 'manifest', errorCode), serverRequestId), serverRequestId, retryAfterMsFromResponse(res), errorCode);
     }, { max546Attempts: 7 });
 }
 const defaultRetrySleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -224,6 +235,10 @@ export async function retryTransient(context, fn, opts = {}) {
             if (err instanceof ApiError) {
                 if (err.status < 500 && err.status !== 429)
                     throw err;
+                // A daily allowance cannot recover during this request. In particular,
+                // never honour its hours-long Retry-After inside a single watch tick.
+                if (err.code === DAILY_QUOTA_ERROR_CODE)
+                    throw err;
                 lastErr = err;
                 nextDelayMs = err.retryAfterMs ?? 0;
             }
@@ -345,7 +360,8 @@ export async function fetchAssetBytes(config, key, knownSha) {
         if (res.ok)
             return await readBodyWithLimit(res, MAX_ASSET_BYTES);
         const bodyText = await res.text();
-        throw new ApiError(res.status, withRequestId(friendly(res.status, bodyText, `download ${key}`), serverRequestId), serverRequestId, retryAfterMsFromResponse(res));
+        const errorCode = errorCodeFromResponse(res);
+        throw new ApiError(res.status, withRequestId(friendlyApiError(res.status, bodyText, `download ${key}`, errorCode), serverRequestId), serverRequestId, retryAfterMsFromResponse(res), errorCode);
     });
 }
 /**
@@ -393,7 +409,8 @@ export async function pushSprites(sprites, retryOpts) {
             return results;
         }
         const bodyText = await res.text();
-        throw new ApiError(res.status, withRequestId(friendly(res.status, bodyText, 'push'), serverRequestId), serverRequestId, retryAfterMsFromResponse(res));
+        const errorCode = errorCodeFromResponse(res);
+        throw new ApiError(res.status, withRequestId(friendlyApiError(res.status, bodyText, 'push', errorCode), serverRequestId), serverRequestId, retryAfterMsFromResponse(res), errorCode);
     }, retryOpts);
 }
 function isTransientPushError(e) {

package/dist/commands/push.js

@@ -110,6 +110,10 @@ export async function runPushWith(config, state, opts = {}) {
         const segments = entry
             ? entry.adoptRel.replace(/\.png$/i, '').split('/')
             : key.split('/');
+        if (opts.excludeKeys?.has(key)) {
+            reportHash();
+            return;
+        }
         candidates.push({
             key,
             segments,
@@ -141,12 +145,12 @@ export async function runPushWith(config, state, opts = {}) {
     if (skippedUnsafe > 0 && !quiet) {
         console.log(kleur.yellow(`! skipped ${skippedUnsafe} path${skippedUnsafe === 1 ? '' : 's'} that were not regular files inside the project.`));
     }
-    if (legacy.length > 0 && !quiet) {
+    if (legacy.length > 0 && !quiet && !opts.nestedSync) {
         console.log();
         console.log(kleur.yellow(`! ${legacy.length} sprite${legacy.length === 1 ? '' : 's'} came from a legacy single-image file — skipped.`));
         console.log(kleur.dim(`  Fix: open the file in MagicPixel and save it once, then re-run \`${cmd('sync')}\`.`));
     }
-    if (flattenBlocked.length > 0 && !quiet) {
+    if (flattenBlocked.length > 0 && !quiet && !opts.nestedSync) {
         console.log();
         console.log(kleur.yellow(`! ${flattenBlocked.length} sprite${flattenBlocked.length === 1 ? '' : 's'} would flatten a multi-layer artboard — skipped.`));
         for (const a of flattenBlocked.slice(0, 10)) {
@@ -225,7 +229,38 @@ export async function runPushWith(config, state, opts = {}) {
             await saveState({ ...state, synced });
         throw e;
     }
-    const counts = { created: 0, updated: 0, unchanged: 0, conflict: 0, error: 0 };
+    const spriteByKey = new Map(sprites.map((s) => [s.key, s]));
+    if (opts.force) {
+        // Two rounds at most: an adopt-shaped or hash-less refusal comes back
+        // without a live sha, and the retry as an update is what makes the server
+        // composite the artboard and report one.
+        for (let round = 0; round < 2; round++) {
+            const retry = forcedRetrySprites(results, spriteByKey, opts.flatten === true);
+            if (retry.length === 0)
+                break;
+            const retryResults = await pushSpritesAdaptive(retry);
+            synced = await commitPushResults({
+                synced,
+                batchResults: retryResults,
+                candidates,
+                sourceByKey,
+                shaByKey,
+                fpByKey,
+                outDir: config.outDir,
+            });
+            await saveState({ ...state, synced });
+            replaceResultsByKey(results, retryResults);
+            if (retryResults.every((r) => r.status === 'conflict' && !r.sha256))
+                break;
+        }
+    }
+    // Remember the live cloud sha a refusal reported, so a later `push` (with or
+    // without --force) has a baseline the concurrency check accepts. The manifest
+    // hash can be absent for big documents, which used to dead-end this path.
+    if (rememberRefusedCloudShas(synced, results)) {
+        await saveState({ ...state, synced });
+    }
+    const counts = { created: 0, updated: 0, unchanged: skipped, conflict: 0, error: 0 };
     for (const r of results) {
         if (r.status in counts)
             counts[r.status]++;
@@ -241,14 +276,19 @@ export async function runPushWith(config, state, opts = {}) {
             progress.succeed(`Pushed. ${summary}`);
     }
     if (!quiet) {
+        let printedIssues = 0;
         for (const r of results) {
             if (r.status === 'conflict') {
-                console.log(`  ${kleur.yellow('!')} ${r.key}: ${conflictHint(r.reason)}`);
+                if (printedIssues++ < 10)
+                    console.log(`  ${kleur.yellow('!')} ${r.key}: ${conflictHint(r.reason)}`);
             }
             else if (r.status === 'error') {
-                console.log(`  ${kleur.red('!')} ${r.key}: ${r.message ?? 'push failed'}`);
+                if (printedIssues++ < 10)
+                    console.log(`  ${kleur.red('!')} ${r.key}: ${r.message ?? 'push failed'}`);
             }
         }
+        if (printedIssues > 10)
+            console.log(kleur.dim(`  …and ${printedIssues - 10} more`));
         if (counts.created > 0) {
             console.log(kleur.dim(`  ${counts.created} new sprite${counts.created === 1 ? '' : 's'} now live in your MagicPixel library ` +
                 `(working set + ${relative(process.cwd(), outRoot)}). They appear in Connected as they import.`));
@@ -258,6 +298,62 @@ export async function runPushWith(config, state, opts = {}) {
         process.exitCode = 1;
     return { ...counts, imported: matched.entries.length };
 }
+/**
+ * Sprites to re-send under `--force`: every sprite the cloud refused because it
+ * also changed there, re-addressed as an update against the sha the refusal
+ * reported. Not a bypass — the server still compares, so a save that lands in
+ * between refuses again.
+ */
+export function forcedRetrySprites(results, spriteByKey, flatten) {
+    const out = [];
+    for (const r of results) {
+        if (r.status !== 'conflict' || r.reason !== 'cloud-changed' || !r.assetId)
+            continue;
+        const original = spriteByKey.get(r.key);
+        if (!original)
+            continue;
+        // Skip a round we already tried with this exact baseline.
+        if (r.sha256 && original.baseSha256 === r.sha256)
+            continue;
+        out.push({
+            key: original.key,
+            pngBase64: original.pngBase64,
+            diskSha256: original.diskSha256,
+            assetId: r.assetId,
+            layerIdx: typeof r.layerIdx === 'number' ? r.layerIdx : (original.layerIdx ?? 0),
+            baseSha256: r.sha256 ?? null,
+            flatten,
+        });
+    }
+    return out;
+}
+/** Overwrite the earlier outcome for every retried key, in place. */
+export function replaceResultsByKey(results, updates) {
+    for (const u of updates) {
+        const i = results.findIndex((r) => r.key === u.key);
+        if (i >= 0)
+            results[i] = u;
+        else
+            results.push(u);
+    }
+}
+/**
+ * Store the live cloud sha a `cloud-changed` refusal reported as this sprite's
+ * pending baseline. Returns true when anything changed.
+ */
+export function rememberRefusedCloudShas(synced, results) {
+    let changed = false;
+    for (const r of results) {
+        if (r.status !== 'conflict' || r.reason !== 'cloud-changed' || !r.sha256)
+            continue;
+        const prev = synced[r.key];
+        if (!prev || prev.pendingCloudSha256 === r.sha256)
+            continue;
+        synced[r.key] = { ...prev, pendingCloudSha256: r.sha256 };
+        changed = true;
+    }
+    return changed;
+}
 async function commitPushResults(opts) {
     const { batchResults, candidates, sourceByKey, shaByKey, fpByKey, outDir } = opts;
     const failedKeys = new Set(batchResults.filter((r) => r.status === 'conflict' || r.status === 'error').map((r) => r.key));
@@ -276,6 +372,7 @@ async function commitPushResults(opts) {
                 delete nextSynced[r.key];
             const diskSha256 = shaByKey.get(r.key) ?? shaByKey.get(stateKey) ?? nextSynced[stateKey]?.diskSha256;
             const fp = fpByKey.get(r.key) ?? fpByKey.get(stateKey);
+            const previous = nextSynced[stateKey];
             nextSynced[stateKey] = {
                 assetId: r.assetId,
                 layerIdx: typeof r.layerIdx === 'number' ? r.layerIdx : (nextSynced[stateKey]?.layerIdx ?? 0),
@@ -285,6 +382,8 @@ async function commitPushResults(opts) {
                 ...(fp?.diskMtimeMs != null ? { diskMtimeMs: fp.diskMtimeMs } : {}),
                 ...(fp?.diskSize != null ? { diskSize: fp.diskSize } : {}),
                 ...(sourceRel ? { sourceRel } : {}),
+                ...(previous?.releasedAt ? { releasedAt: previous.releasedAt } : {}),
+                ...(previous?.releasedVersion != null ? { releasedVersion: previous.releasedVersion } : {}),
             };
         }
     }
@@ -300,7 +399,7 @@ async function persistDiskFingerprints(state, candidates) {
 function conflictHint(reason) {
     switch (reason) {
         case 'cloud-changed':
-            return `changed in MagicPixel since the last sync — run \`${cmd('sync')}\` first, then re-push.`;
+            return `also changed in MagicPixel. Press Sync on that artboard to use MagicPixel's copy, or run \`${cmd('push --force')}\` to keep this local one.`;
         case 'would-flatten':
             return 'artboard has multiple layers or frames — re-run with --flatten to replace it.';
         case 'legacy-document':
@@ -308,7 +407,7 @@ function conflictHint(reason) {
         case 'not-found':
             return `artboard no longer exists in MagicPixel — run \`${cmd('sync')}\` to refresh.`;
         default:
-            return `conflict — run \`${cmd('sync')}\` and try again.`;
+            return `conflict — review both copies, then press the artboard's Sync button to use MagicPixel's copy.`;
     }
 }
 /**

package/dist/commands/sync.js

@@ -5,7 +5,7 @@ import { existsSync } from 'node:fs';
 import { dirname, relative, resolve } from 'node:path';
 import { loadConfig, loadState, saveState } from '../config.js';
 import { ensureEngineConnect } from '../util/engineConnect.js';
-import { fetchManifestSnapshot, fetchAssetBytes, ApiError, getLastProjectInfo, primeManifestEtags, manifestEtagsSnapshot } from '../api.js';
+import { fetchManifestSnapshot, fetchAssetBytes, ApiError, DAILY_QUOTA_ERROR_CODE, getLastProjectInfo, primeManifestEtags, manifestEtagsSnapshot } from '../api.js';
 import { fileSha256 } from '../util/hash.js';
 import { pruneEmptyDirs, walkOutDirPngs } from '../util/paths.js';
 import { createLimit } from '../util/limit.js';
@@ -15,7 +15,7 @@ import { detectProjectKind, isEngineKind } from '../util/framework.js';
 import { indexGamePngs, matchConnectGlobs, GAME_INDEX_CAP_HINT, connectCapMessage, countingSpritesText } from '../util/gameScan.js';
 import { aliasCollisionKeys, collectSourceRelMap, isPathInside, syncDiskPathFromKey } from '../util/syncPath.js';
 import { DEFAULT_UNITY_PPU, writeMissingUnityMetas } from '../util/unityMeta.js';
-import { applyUnityPullPolicy, isWorkingSetEntry, workingSetPullKeys } from '../util/unityFilter.js';
+import { applyUnityPullPolicy, isWorkingSetEntry, partitionWithheldEntries, workingSetPullKeys } from '../util/unityFilter.js';
 import { selectFullSyncOrphans } from '../util/prunePolicy.js';
 import { runTmpJanitor } from '../util/tmpJanitor.js';
 import { friendlyFsError } from '../util/errors.js';
@@ -24,7 +24,7 @@ import { formatBytes } from '../util/format.js';
 import { computePreviousKeyOrphans } from '../util/previousKeyOrphans.js';
 import { cmd } from '../util/invoke.js';
 import { formatSlowTickLine, formatWatchSpriteLine, SLOW_TICK_HEARTBEAT_MS } from '../util/watchCopy.js';
-import { decidePull } from '../util/pullDecision.js';
+import { decidePull, hasNewExplicitRelease } from '../util/pullDecision.js';
 import { hasUnpushedLocalEdit } from '../util/localEdit.js';
 import { shouldReconcile } from '../util/reconcile.js';
 import { runPush } from './push.js';
@@ -116,6 +116,8 @@ async function watchLoop(opts) {
     // "back online" recovery line. Without this flag a user who walked away
     // during an outage has no signal that things are healthy again.
     let pausedForNetwork = false;
+    // Same idea for the daily API allowance: say it once, then wait quietly.
+    let pausedForQuota = false;
     // After this many consecutive 401/403s we give up and exit non-zero so a
     // parent process (Vite plugin, systemd, pm2) can tell the watcher is
     // genuinely broken (revoked key) rather than transiently blipped.
@@ -214,9 +216,11 @@ async function watchLoop(opts) {
             // another terminal is picked up automatically by the next tick.
             const wasPausedForAuth = pausedForAuth;
             const wasPausedForNetwork = pausedForNetwork;
+            const wasPausedForQuota = pausedForQuota;
             backoffSec = intervalSec;
             pausedForAuth = false;
             pausedForNetwork = false;
+            pausedForQuota = false;
             consecutiveAuthFailures = 0;
             if (wasPausedForAuth && !opts.quiet) {
                 process.stdout.write('\x1b[2K\r');
@@ -226,6 +230,10 @@ async function watchLoop(opts) {
                 process.stdout.write('\x1b[2K\r');
                 console.log(`${kleur.dim(timestamp())} ${kleur.green('✓')} Back online — resuming.`);
             }
+            if (wasPausedForQuota && !wasPausedForAuth && !wasPausedForNetwork && !opts.quiet) {
+                process.stdout.write('\x1b[2K\r');
+                console.log(`${kleur.dim(timestamp())} ${kleur.green('✓')} Daily allowance available again — resuming.`);
+            }
             const changedCount = r.added.length + r.modified.length + r.removed.length + r.renamed.length;
             // Pushing a locally edited sprite is activity too — it just isn't part of
             // the printed pull list. Without it, an artist working only in Unity
@@ -262,6 +270,7 @@ async function watchLoop(opts) {
                 backoffSec,
                 pausedForAuth,
                 pausedForNetwork,
+                pausedForQuota,
                 consecutiveAuthFailures,
                 maxAuthFailures: MAX_AUTH_FAILURES,
             });
@@ -297,6 +306,17 @@ async function watchLoop(opts) {
                 pausedForNetwork = true;
                 backoffSec = decision.nextBackoffSec;
             }
+            else if (decision.kind === 'quota') {
+                consecutiveAuthFailures = 0;
+                if (decision.printMessage) {
+                    const idSuffix = apiErr?.requestId ? kleur.dim(` (request id: ${apiErr.requestId})`) : '';
+                    console.log(`${kleur.dim(timestamp())} ${kleur.yellow('!')} Daily MagicPixel API allowance reached. ` +
+                        `Sprites you already have still work. Resets in ${formatQuotaReset(decision.resetSec)} ` +
+                        `(00:00 UTC); checking again every ${Math.max(1, Math.round(decision.nextBackoffSec / 60))} min.${idSuffix}`);
+                }
+                pausedForQuota = true;
+                backoffSec = decision.nextBackoffSec;
+            }
             else {
                 consecutiveAuthFailures = 0;
                 const idSuffix = apiErr?.requestId ? kleur.dim(` (request id: ${apiErr.requestId})`) : '';
@@ -371,6 +391,19 @@ export function nextBackoffForIdle(idleSeconds, intervalSec, thresholds = IDLE_B
         return Math.max(intervalSec, 5);
     return intervalSec;
 }
+/**
+ * Longest quiet wait while the daily allowance is exhausted. The allowance
+ * resets at UTC midnight, but we re-check periodically so a raised cap (or a
+ * clock/timezone surprise) is picked up without restarting the watcher.
+ */
+export const QUOTA_RECHECK_MAX_SEC = 900;
+/** Human reset countdown: "42 min" / "3h 05m". */
+export function formatQuotaReset(resetSec) {
+    const mins = Math.max(1, Math.round(resetSec / 60));
+    if (mins < 60)
+        return `${mins} min`;
+    return `${Math.floor(mins / 60)}h ${String(mins % 60).padStart(2, '0')}m`;
+}
 /**
  * Pure helper: classify a per-tick error and compute the next backoff +
  * counter updates. Extracted so the auth-failure watchdog and the
@@ -391,6 +424,17 @@ export function classifyTickError(err, state) {
             giveUp: next >= state.maxAuthFailures,
         };
     }
+    if (apiErr?.code === DAILY_QUOTA_ERROR_CODE) {
+        // Nothing recovers until the allowance resets, so stop hammering: each
+        // retry still burns a request against the daily request allowance.
+        const resetSec = Math.max(1, Math.round((apiErr.retryAfterMs ?? 0) / 1000));
+        return {
+            kind: 'quota',
+            nextBackoffSec: Math.min(QUOTA_RECHECK_MAX_SEC, resetSec),
+            printMessage: !state.pausedForQuota,
+            resetSec,
+        };
+    }
     if (isNetworkError(err)) {
         const nextBackoffSec = Math.min(state.backoffSec * 2, 60);
         // Print on the first offline tick, then again whenever backoff changes —
@@ -453,6 +497,8 @@ async function runOnce(opts, runOpts = {}) {
     if (!spinner)
         onStatus?.(since ? 'Checking MagicPixel for edits…' : 'Fetching your sprites from MagicPixel…');
     let manifest;
+    /** In-scope documents withheld by the server (unreleased edits): hold-only. */
+    let withheldEntries = [];
     // Composite keys the cloud reports as gone (document trashed / componentized)
     // since our cursor. Empty on --full, where the manifest itself is the truth.
     let removedRemoteKeys = [];
@@ -480,9 +526,16 @@ async function runOnce(opts, runOpts = {}) {
             since = undefined;
             snapshot = await fetchManifestSnapshot(config, undefined, onManifestProgress);
         }
-        manifest = snapshot.entries;
+        // Documents the user hasn't released with the editor's Sync button are
+        // listed but not syncable: they stay out of every pull/prune decision and
+        // only protect what's already on disk (see `withheldDirs` below).
+        const partitioned = partitionWithheldEntries(snapshot.entries);
+        manifest = partitioned.entries;
+        withheldEntries = partitioned.withheld;
         removedRemoteKeys = snapshot.removedKeys;
-        observedUpdatedAt = maxIsoTimestamp(manifest.map((e) => e.updated_at));
+        // Cursor advances past withheld rows too — they are re-listed whenever the
+        // user presses Sync (the release bumps `updated_at`).
+        observedUpdatedAt = maxIsoTimestamp(snapshot.entries.map((e) => e.updated_at));
         const projectInfo = getLastProjectInfo();
         const projectSuffix = projectInfo && verbose
             ? kleur.dim(` · project: ${projectInfo.name ?? projectInfo.id.slice(0, 8)}`)
@@ -547,6 +600,18 @@ async function runOnce(opts, runOpts = {}) {
             (connected.capped ? ` of ${connected.total} matched` : '')));
     }
     const pathForKey = (key) => syncDiskPathFromKey(config.outDir, key, sourceByKey);
+    // Every folder on disk that belongs to a withheld document. Anything already
+    // written there is held as-is: unreleased edits must never pull, and a full
+    // reconcile must never read the absence of these entries as "deleted".
+    const withheldDirs = new Set();
+    for (const entry of withheldEntries) {
+        try {
+            withheldDirs.add(dirname(pathForKey(entry.key)));
+        }
+        catch {
+            /* unusable key — nothing to protect */
+        }
+    }
     const workingSet = workingSetPullKeys(sourceByKey, state.synced);
     // Files whose artboard is no longer flagged for Unity. Deleted even in
     // incremental mode: un-checking the box in the editor must actually remove
@@ -662,6 +727,7 @@ async function runOnce(opts, runOpts = {}) {
     const shaByEntryId = new Map();
     const toDownload = [];
     const conflicts = [];
+    const failedDownloadKeys = new Set();
     let bytesSaved = 0;
     let unchanged = 0;
     const synced = state.synced ?? {};
@@ -696,7 +762,15 @@ async function runOnce(opts, runOpts = {}) {
         const inWorkingSet = isWorkingSetEntry(entry, workingSet);
         // Unchanged cloud composite: skip hashing the original PNG (it almost
         // never matches) unless the file is gone and we need to restore it.
-        if (entry.sha256 && previousCloudSha256 === entry.sha256 && existsSync(pathFor(entry))) {
+        const previousReleasedAt = synced[entry.key]?.releasedAt;
+        const freshRelease = hasNewExplicitRelease({
+            releasedAt: entry.released_at,
+            previousReleasedAt,
+            releasedVersion: entry.released_version,
+            previousReleasedVersion: synced[entry.key]?.releasedVersion,
+            lastSync: state.lastSync,
+        });
+        if (!freshRelease && entry.sha256 && previousCloudSha256 === entry.sha256 && existsSync(pathFor(entry))) {
             shaByEntryId.set(entry.id, null);
             unchanged++;
             if (entry.size_bytes)
@@ -711,6 +785,11 @@ async function runOnce(opts, runOpts = {}) {
             previousCloudSha256,
             lastPushedDiskSha256: synced[entry.key]?.diskSha256,
             inWorkingSet,
+            releasedAt: entry.released_at,
+            previousReleasedAt,
+            releasedVersion: entry.released_version,
+            previousReleasedVersion: synced[entry.key]?.releasedVersion,
+            lastSync: state.lastSync,
         });
         if (decision === 'conflict') {
             conflicts.push(entry.key);
@@ -749,10 +828,17 @@ async function runOnce(opts, runOpts = {}) {
     // Sprites created in Unity (or any PNG we never pulled) are pending a
     // push into MagicPixel, not orphans — see prunePolicy.ts.
     if (!since) {
+        const protectedPaths = new Set(unknownFlagPaths);
+        if (withheldDirs.size > 0) {
+            for (const local of localPngs) {
+                if (withheldDirs.has(dirname(local.abs)))
+                    protectedPaths.add(local.abs);
+            }
+        }
         const policy = selectFullSyncOrphans({
             localPaths: localPngs.map((a) => a.abs),
             remoteDiskPaths,
-            protectedPaths: unknownFlagPaths,
+            protectedPaths,
             isTracked: (p) => keyByPath.has(p),
         });
         orphans = policy.orphans;
@@ -817,6 +903,9 @@ async function runOnce(opts, runOpts = {}) {
     // local-edit guard applied below. De-duplicates vs the full-sync orphan list.
     const orphanSet = new Set(orphans);
     const addOrphan = (p) => {
+        // Withheld documents are held whole: no prune source may touch them.
+        if (withheldDirs.has(dirname(p)))
+            return;
         if (existsSync(p) && isPathInside(p, outRoot))
             orphanSet.add(p);
     };
@@ -917,6 +1006,12 @@ async function runOnce(opts, runOpts = {}) {
         if (e.folder)
             knownFolderSlugs.add(e.folder.split('/')[0]);
     }
+    // Withheld docs are absent from `manifest` — without their slugs a sibling
+    // folder like `tiles-2/` would read as a legacy suffix collision.
+    for (const e of withheldEntries) {
+        if (e.folder)
+            knownFolderSlugs.add(e.folder.split('/')[0]);
+    }
     for (const key of Object.values(previousAssets)) {
         const top = key.split('/')[0];
         if (top)
@@ -1049,6 +1144,7 @@ async function runOnce(opts, runOpts = {}) {
         }
         catch (e) {
             result.failed++;
+            failedDownloadKeys.add(entry.key);
             progress?.stop();
             // Multi-line messages come from friendlyFsError — print all lines
             // so the user sees the fix hint. Single-line errors stay terse.
@@ -1189,9 +1285,21 @@ async function runOnce(opts, runOpts = {}) {
         // Conflicted keys keep their old baselines: recording the new cloud sha
         // (with the locally-edited disk sha) would make both halves believe they
         // are in sync and freeze the divergence forever.
-        if (conflictSet.has(entry.key))
+        if (conflictSet.has(entry.key)) {
+            const previous = nextSynced[entry.key];
+            if (previous && entry.sha256) {
+                nextSynced[entry.key] = { ...previous, pendingCloudSha256: entry.sha256 };
+            }
+            continue;
+        }
+        if (failedDownloadKeys.has(entry.key))
             continue;
-        const sha = entry.sha256 ?? (await fileSha256(pathFor(entry)));
+        // After a write, the actual downloaded bytes are the disk/cloud baseline.
+        // The manifest hash may be null or represent a cached composite while the
+        // download endpoint serves storage bytes for a single-artboard document.
+        const sha = writtenKeys.has(entry.key)
+            ? await fileSha256(pathFor(entry))
+            : (entry.sha256 ?? (await fileSha256(pathFor(entry))));
         if (!sha)
             continue;
         const prev = nextSynced[entry.key];
@@ -1203,7 +1311,16 @@ async function runOnce(opts, runOpts = {}) {
         // them anyway, flagged, so `push` skips them with a hint instead of
         // adopting the same art as a second document.
         if (typeof entry.layer_idx !== 'number' || entry.layer_idx < 0) {
-            nextSynced[entry.key] = { assetId: entry.asset_id, layerIdx: 0, sha256: sha, diskSha256, legacy: true, ...(sourceRel ? { sourceRel } : {}) };
+            nextSynced[entry.key] = {
+                assetId: entry.asset_id,
+                layerIdx: 0,
+                sha256: sha,
+                diskSha256,
+                legacy: true,
+                ...(sourceRel ? { sourceRel } : {}),
+                ...(entry.released_at ? { releasedAt: entry.released_at } : {}),
+                ...(entry.released_version != null ? { releasedVersion: entry.released_version } : {}),
+            };
             continue;
         }
         nextSynced[entry.key] = {
@@ -1213,6 +1330,8 @@ async function runOnce(opts, runOpts = {}) {
             diskSha256,
             ...(typeof entry.layer_count === 'number' ? { layers: entry.layer_count } : {}),
             ...(sourceRel ? { sourceRel } : {}),
+            ...(entry.released_at ? { releasedAt: entry.released_at } : {}),
+            ...(entry.released_version != null ? { releasedVersion: entry.released_version } : {}),
         };
     }
     const nextState = {
@@ -1291,6 +1410,8 @@ async function runOnce(opts, runOpts = {}) {
     if (result.failed > 0 && verbose) {
         console.log(kleur.yellow(`\n${result.failed} download${result.failed === 1 ? '' : 's'} failed — lastSync not advanced. Re-run to retry.`));
     }
+    onStatus?.('Checking your game files…');
+    const pushed = await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode, onStatus, conflictSet);
     if (verbose) {
         console.log();
         const summary = `downloaded ${downloaded} (added ${result.added.length}, modified ${result.modified.length}), ` +
@@ -1299,25 +1420,23 @@ async function runOnce(opts, runOpts = {}) {
             (shouldPrune ? `, pruned ${result.removed.length}` : '') +
             (renamed.length ? `, renamed ${renamed.length}` : '') +
             (result.failed ? `, failed ${result.failed}` : '');
-        console.log(result.failed ? kleur.yellow(`done with errors. ${summary}`) : kleur.green(`✓ done. ${summary}`));
-        // Per-file change list. Suppress renames here — printRenames below owns
-        // the rename block (it adds the import-update hints). Letting both fire
-        // would print each rename twice.
+        const pushFailed = (pushed?.conflict ?? 0) + (pushed?.error ?? 0);
+        console.log(result.failed || pushFailed
+            ? kleur.yellow(`Sync finished with issues. ${summary}`)
+            : kleur.green(`✓ Sync complete. ${summary}`));
         printChanges(result, '  ', { includeRenames: renamed.length === 0 });
         if (renamed.length > 0)
             printRenames(renamed, { withHints: true });
     }
-    onStatus?.('Checking your game files…');
-    const pushed = await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode, onStatus);
     if (result.failed)
         process.exitCode = 1;
     return { ...result, pushed };
 }
-async function maybePushLocalSprites(pushEnabled, verbose, gameIndex, announceErrors = verbose, onStatus) {
+async function maybePushLocalSprites(pushEnabled, verbose, gameIndex, announceErrors = verbose, onStatus, excludeKeys) {
     if (pushEnabled === false)
         return null;
     try {
-        return await runPush({ quiet: !verbose, gameIndex, onStatus });
+        return await runPush({ quiet: !verbose, nestedSync: true, gameIndex, onStatus, excludeKeys });
     }
     catch (e) {
         if (announceErrors) {
@@ -1393,11 +1512,13 @@ function humanTime(iso) {
 function printConflicts(keys, removedRemotely = new Set()) {
     console.log();
     console.log(kleur.yellow(`${keys.length} sprite${keys.length === 1 ? '' : 's'} changed in both places — not overwritten:`));
-    for (const key of keys) {
+    for (const key of keys.slice(0, 10)) {
         const note = removedRemotely.has(key) ? kleur.dim(' (no longer synced from MagicPixel)') : '';
         console.log(`  ${kleur.yellow('~')} ${key}${note}`);
     }
-    console.log(kleur.dim(`  Keep the local edit: run \`${cmd('push')}\` (it will report the cloud change), or delete the PNG to accept MagicPixel's copy.`));
+    if (keys.length > 10)
+        console.log(kleur.dim(`  …and ${keys.length - 10} more`));
+    console.log(kleur.dim(`  Use MagicPixel's copy: press Sync on that artboard. Keep the local edit: run \`${cmd('push --force')}\`.`));
     if (removedRemotely.size > 0) {
         console.log(kleur.dim(`  Marked (no longer synced): re-check "Sync to Unity" (or restore the document) to push the edit up, or delete the PNG to accept the removal.`));
     }

package/dist/commands/whoami.js

@@ -1,6 +1,6 @@
 import kleur from 'kleur';
 import { loadConfig, defaultConfig, resolveEndpoint, getApiKey } from '../config.js';
-import { ApiError, retryTransient, retryAfterMsFromResponse, getLastProjectInfo } from '../api.js';
+import { ApiError, errorCodeFromResponse, friendlyApiError, retryTransient, retryAfterMsFromResponse, getLastProjectInfo } from '../api.js';
 import { safeFetch } from '../util/security.js';
 import { authHeaders } from '../util/authHeaders.js';
 export async function whoamiCommand() {
@@ -32,9 +32,10 @@ export async function whoamiCommand() {
         }
         if (res.status >= 500 || res.status === 429) {
             const bodyText = await res.text();
+            const errorCode = errorCodeFromResponse(res);
             // Pass Retry-After through so retryTransient honours server back-pressure
             // (matches fetchManifestPage / fetchAssetBytes).
-            throw new ApiError(res.status, bodyText.slice(0, 200), serverRequestId, retryAfterMsFromResponse(res));
+            throw new ApiError(res.status, friendlyApiError(res.status, bodyText, 'whoami', errorCode), serverRequestId, retryAfterMsFromResponse(res), errorCode);
         }
         if (!res.ok) {
             const bodyText = await res.text();

package/dist/index.js

@@ -97,7 +97,8 @@ program
     .description('Upload local sprite edits back to MagicPixel (two-way sync)')
     .option('--dry-run', 'Print what would be pushed without sending anything')
     .option('--flatten', 'Allow replacing multi-layer artboards with the flat local image')
-    .addHelpText('after', '\nExamples:\n  $ magicpixel push --dry-run      # see what changed on disk\n  $ magicpixel push                # send local edits + new sprites\n')
+    .option('--force', 'Keep your local copy when a sprite also changed in MagicPixel')
+    .addHelpText('after', '\nExamples:\n  $ magicpixel push --dry-run      # see what changed on disk\n  $ magicpixel push                # send local edits + new sprites\n  $ magicpixel push --force        # your local copy wins on both-sides-changed\n')
     .action(wrap("push", async (opts) => pushCommand(opts)));
 program
     .command('connect <glob>')

package/dist/util/auth.js

@@ -1,5 +1,5 @@
 import { resolveEndpoint } from '../config.js';
-import { ApiError, retryTransient } from '../api.js';
+import { ApiError, errorCodeFromResponse, friendlyApiError, retryAfterMsFromResponse, retryTransient } from '../api.js';
 import { safeFetch, readBodyWithLimit } from './security.js';
 import { authHeaders } from './authHeaders.js';
 /**
@@ -32,9 +32,10 @@ export async function assertKeyValid(key, config) {
             // we ultimately surface.
             const bodyBytes = await readBodyWithLimit(res, 16 * 1024).catch(() => new Uint8Array());
             const body = new TextDecoder().decode(bodyBytes);
+            const errorCode = errorCodeFromResponse(res);
             // 5xx + 429 retry through retryTransient; other 4xx bubble immediately.
-            throw new ApiError(res.status, `Server returned ${res.status}: ${body.slice(0, 120)}\n` +
-                `  (request id: ${serverRequestId})`, serverRequestId);
+            throw new ApiError(res.status, `${friendlyApiError(res.status, body, 'validate key', errorCode)}\n` +
+                `  (request id: ${serverRequestId})`, serverRequestId, retryAfterMsFromResponse(res), errorCode);
         }
         await res.body?.cancel();
     });

package/dist/util/pullDecision.js

@@ -14,10 +14,30 @@
  * that file, the entry is reported instead of downloaded.
  */
 import { isLocalEdit } from './localEdit.js';
+/** A newer editor Sync press explicitly chooses MagicPixel for this sprite. */
+export function hasNewExplicitRelease(opts) {
+    if (opts.releasedVersion != null && opts.previousReleasedVersion != null) {
+        return opts.releasedVersion > opts.previousReleasedVersion;
+    }
+    if (!opts.releasedAt)
+        return false;
+    const released = Date.parse(opts.releasedAt);
+    if (!Number.isFinite(released))
+        return false;
+    const baseline = opts.previousReleasedAt ?? opts.lastSync;
+    if (!baseline)
+        return false;
+    const previous = Date.parse(baseline);
+    return Number.isFinite(previous) && released > previous;
+}
 export function decidePull(opts) {
     const cloud = opts.cloudSha256 ?? null;
     const local = opts.localSha256;
     const prev = opts.previousCloudSha256;
+    // A fresh explicit release is the user's scoped instruction for the cloud
+    // copy to replace this PNG, even if the PNG also changed locally.
+    if (hasNewExplicitRelease(opts))
+        return 'pull';
     // Missing on disk → restore from cloud (MagicPixel-only art and deletions).
     if (!local)
         return 'pull';

package/dist/util/pushPlan.js

@@ -145,7 +145,10 @@ export function planPush(candidates, synced, opts = {}) {
                 key: c.key,
                 assetId: known.assetId,
                 layerIdx: known.layerIdx,
-                baseSha256: known.sha256,
+                // `sync` records the live cloud hash when it protects a dual edit.
+                // A later explicit `push` can then safely keep the local copy without
+                // bypassing the server's optimistic-concurrency check.
+                baseSha256: known.pendingCloudSha256 ?? known.sha256,
             });
             continue;
         }

package/dist/util/unityFilter.js

@@ -18,14 +18,27 @@
  * layer JSON dropped `syncToUnity`). Those saves must still write back to
  * the original PNG.
  */
+/**
+ * Split the manifest into syncable entries and withheld ones. Withheld entries
+ * are never pull candidates (not even under `unitySyncAll`) and carry no bytes;
+ * callers use them only to protect what's already on disk from pruning.
+ */
+export function partitionWithheldEntries(manifest) {
+    const withheld = [];
+    const entries = [];
+    for (const e of manifest)
+        (e.withheld === true ? withheld : entries).push(e);
+    return { entries, withheld };
+}
 export function filterUnityManifest(manifest, opts = {}) {
+    const syncable = partitionWithheldEntries(manifest).entries;
     if (opts.syncAll)
-        return { entries: manifest, noneFlagged: false, unknown: [] };
-    const entries = manifest.filter((e) => e.unity === true);
-    const unknown = manifest.filter((e) => typeof e.unity !== 'boolean');
+        return { entries: syncable, noneFlagged: false, unknown: [] };
+    const entries = syncable.filter((e) => e.unity === true);
+    const unknown = syncable.filter((e) => typeof e.unity !== 'boolean');
     return {
         entries,
-        noneFlagged: manifest.length > 0 && entries.length === 0,
+        noneFlagged: syncable.length > 0 && entries.length === 0,
         unknown,
     };
 }
@@ -65,7 +78,9 @@ export function applyUnityPullPolicy(manifest, opts = {}) {
     if (opts.syncAll || !opts.alwaysPull)
         return filtered;
     const already = new Set(filtered.entries);
-    const extra = manifest.filter((e) => !already.has(e) && opts.alwaysPull(e));
+    // Withheld entries stay out: a working-set sprite the user hasn't released
+    // must not be pulled over the copy in the game project.
+    const extra = partitionWithheldEntries(manifest).entries.filter((e) => !already.has(e) && opts.alwaysPull(e));
     if (extra.length === 0)
         return filtered;
     const extraSet = new Set(extra);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magicpixelart/cli",
-  "version": "0.5.21",
+  "version": "0.5.24",
   "description": "Sync MagicPixel pixel-art assets to your local project.",
   "type": "module",
   "bin": {