@magicpixelart/cli 0.5.24 → 0.5.26

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.26] — 2026-09-21
+
+- Clicking Sync now selects exactly that artboard and clears sibling selections,
+  so generated variants and pasted items in the same document stay out of the
+  game project.
+- Unity, Godot, and GameMaker now strictly require an explicit per-artboard
+  sync flag. Existing working-set paths can no longer bypass that choice.
+- Previously downloaded, now-unmarked siblings are removed on the next sync;
+  locally edited files remain protected as conflicts.
+
+## [0.5.25] — 2026-09-21
+
+- A sync no longer spends one request per file just to be told nothing changed:
+  files whose MagicPixel document has not been touched since the last sync are
+  skipped outright, instead of being re-checked one at a time.
+- "Nothing changed" replies no longer count against the daily request
+  allowance, so a watcher can idle all day without exhausting it.
+- A watcher that has been quiet for 15 minutes now polls every 30 seconds
+  (was 10), and snaps straight back to the fast interval on the first change.
+
 ## [0.5.24] — 2026-09-21
 
 - `push --force` keeps your local copy when a sprite changed in both places. It

package/README.md

@@ -150,7 +150,7 @@ Sync is built to be cheap: a no-op run is one small manifest request, zero PNG b
 | `connect`  | `string[]` | `["**"]` on engines | Game PNG globs to keep in Connected. Empty on JS projects. |
 | `emitIndex`| `boolean`  | `true`                  | Emit `<outDir>/index.ts` with typed asset map.   |
 | `unityPpu` | `number?`  | `32`                    | Unity only: pixels-per-unit in generated `.meta`. |
-| `unitySyncAll` | `boolean?` | `false`             | Unity only: sync every artboard, not just those flagged in the editor. |
+| `unitySyncAll` | `boolean?` | `false`             | Game engines only: sync every artboard instead of only the one explicitly selected in the editor. |
 | `push`     | `boolean?` | `true`                  | Upload local PNG changes (outDir + `connect` working set) to MagicPixel on every `sync`. Set `false` for pull-only. |
 | `endpoint` | `string?`  | production URL          | Override the API base (testing only). Must be **HTTPS**. |
 

package/dist/commands/sync.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, partitionWithheldEntries, workingSetPullKeys } from '../util/unityFilter.js';
+import { filterUnityManifest, isWorkingSetEntry, partitionWithheldEntries, shouldPruneDeselectedEntry, 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, hasNewExplicitRelease } from '../util/pullDecision.js';
+import { canSkipWithoutHashing, decidePull, hasNewExplicitRelease } from '../util/pullDecision.js';
 import { hasUnpushedLocalEdit } from '../util/localEdit.js';
 import { shouldReconcile } from '../util/reconcile.js';
 import { runPush } from './push.js';
@@ -372,10 +372,12 @@ function isNetworkError(err) {
 }
 /**
  * Idle thresholds (seconds of consecutive idleness) at which the watcher steps
- * down from the configured interval to 5s, then to 10s. Single source of truth
- * for both the watch loop and its regression tests.
+ * down from the configured interval to 5s, then 10s, then 30s. Single source of
+ * truth for both the watch loop and its regression tests. The last step keeps a
+ * watcher left running overnight from spending the daily request allowance on
+ * polls nobody is waiting for.
  */
-export const IDLE_BACKOFF_THRESHOLDS = { softSec: 60, hardSec: 300 };
+export const IDLE_BACKOFF_THRESHOLDS = { softSec: 60, hardSec: 300, coldSec: 900 };
 /**
  * Pure helper: given how long we've been idle (wall-clock seconds since the
  * last pulled or pushed change) and the configured poll interval, return the
@@ -385,6 +387,8 @@ export const IDLE_BACKOFF_THRESHOLDS = { softSec: 60, hardSec: 300 };
  * off, ticks are longer than `intervalSec`.
  */
 export function nextBackoffForIdle(idleSeconds, intervalSec, thresholds = IDLE_BACKOFF_THRESHOLDS) {
+    if (thresholds.coldSec != null && idleSeconds >= thresholds.coldSec)
+        return Math.max(intervalSec, 30);
     if (idleSeconds >= thresholds.hardSec)
         return Math.max(intervalSec, 10);
     if (idleSeconds >= thresholds.softSec)
@@ -565,7 +569,7 @@ async function runOnce(opts, runOpts = {}) {
         }
         throw e;
     }
-    // Unity projects sync only the artboards flagged "Sync to Unity" in the
+    // Game-engine projects sync only artboards explicitly selected in the
     // editor (parity with the in-app sync button). `unitySyncAll: true` in
     // magicpixel.json opts back into everything.
     onStatus?.('Looking through your game sprites…');
@@ -613,23 +617,21 @@ async function runOnce(opts, runOpts = {}) {
         }
     }
     const workingSet = workingSetPullKeys(sourceByKey, state.synced);
-    // Files whose artboard is no longer flagged for Unity. Deleted even in
+    // Files whose artboard is no longer selected. Deleted even in
     // incremental mode: un-checking the box in the editor must actually remove
     // the sprite from the game project, not leave a stale copy behind.
     // Working-set (sourceRel) files are never deleted — they're the user's art.
     const deselectedPaths = [];
-    // Sprites whose "Sync to Unity" flag the server omitted. Not downloaded
+    // Sprites whose game-sync flag the server omitted. Not downloaded
     // (strict opt-in) but explicitly shielded from pruning: a transient server
     // response must never delete art from someone's game project.
     const unknownFlagPaths = new Set();
-    if (projectKind === 'Unity') {
-        const filtered = applyUnityPullPolicy(manifest, {
-            syncAll: config.unitySyncAll,
-            alwaysPull: (entry) => isWorkingSetEntry(entry, workingSet),
-        });
+    if (isEngineKind(projectKind)) {
+        const filtered = filterUnityManifest(manifest, { syncAll: config.unitySyncAll });
+        const syncedKeys = new Set(Object.keys(state.synced ?? {}));
         if (filtered.unknown.length > 0) {
             const n = filtered.unknown.length;
-            const msg = `${n} artboard${n === 1 ? '' : 's'} came back without a "Sync to Unity" flag — skipped (existing files kept).`;
+            const msg = `${n} artboard${n === 1 ? '' : 's'} came back without a game-sync flag — skipped (existing files kept).`;
             if (verbose) {
                 console.log(kleur.yellow(`! ${msg}`));
                 console.log(kleur.dim(`  Fix: re-run \`${cmd('sync')}\` in a moment, or upgrade with \`npm i -D @magicpixelart/cli@latest\`.`));
@@ -648,49 +650,24 @@ async function runOnce(opts, runOpts = {}) {
                 unknownFlagPaths.add(p);
                 continue;
             }
-            if (sourceByKey.has(entry.key))
+            // A tracked download is ours to reconcile even when its path now falls
+            // under a connect glob. Genuine game-authored files have no synced
+            // baseline and remain protected.
+            if (!shouldPruneDeselectedEntry(entry, { sourceByKey, syncedKeys }))
                 continue;
             if (existsSync(p))
                 deselectedPaths.push(p);
         }
-        if (filtered.noneFlagged) {
-            // Nothing flagged for pull — don't dump the library, and don't prune.
-            // Local sprites still go up so they appear in MagicPixel on connect.
-            if (verbose) {
-                console.log();
-                console.log(kleur.yellow('! No artboards are flagged "Sync to Unity" — nothing to pull.'));
-                console.log(kleur.dim(`  Working-set sprites (\`connect\` in magicpixel.json) still push into MagicPixel.`));
-                console.log(kleur.dim('  Flag folders/artboards in the library to pull them back into Unity.'));
-            }
-            const empty = {
-                added: [],
-                modified: [],
-                removed: [],
-                unchanged: 0,
-                failed: 0,
-                bytesIn: 0,
-                bytesSaved: 0,
-                renamed: [],
-                conflicts: [],
-            };
-            // Persist validators even when the cursor didn't move, so the next
-            // one-shot run starts from a conditional GET.
-            const lastSync = observedUpdatedAt && !(state.lastSync && state.lastSync > observedUpdatedAt)
-                ? observedUpdatedAt
-                : state.lastSync;
-            await saveState({
-                ...state,
-                ...(lastSync ? { lastSync } : {}),
-                ...(since ? {} : { lastReconcile: startedAt }),
-                manifestEtags: manifestEtagsSnapshot(),
-            });
-            await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode, onStatus);
-            return empty;
+        if (filtered.noneFlagged && verbose) {
+            console.log();
+            console.log(kleur.dim(since
+                ? '  No changed artboards are selected for download.'
+                : '  No artboards are selected for download.'));
         }
         const skipped = manifest.length - filtered.entries.length;
         manifest = filtered.entries;
         if (verbose && skipped > 0) {
-            console.log(kleur.dim(`  unity → ${skipped} artboard${skipped === 1 ? '' : 's'} not flagged for sync (skipped)`));
+            console.log(kleur.dim(`  game sync → ${skipped} artboard${skipped === 1 ? '' : 's'} not selected (skipped)`));
         }
     }
     // Detect renames: same id, different key vs prior snapshot.
@@ -770,7 +747,14 @@ async function runOnce(opts, runOpts = {}) {
             previousReleasedVersion: synced[entry.key]?.releasedVersion,
             lastSync: state.lastSync,
         });
-        if (!freshRelease && entry.sha256 && previousCloudSha256 === entry.sha256 && existsSync(pathFor(entry))) {
+        if (canSkipWithoutHashing({
+            freshRelease,
+            fileExists: existsSync(pathFor(entry)),
+            cloudSha256: entry.sha256,
+            previousCloudSha256,
+            cloudUpdatedAt: entry.updated_at,
+            previousCloudUpdatedAt: synced[entry.key]?.cloudUpdatedAt,
+        })) {
             shaByEntryId.set(entry.id, null);
             unchanged++;
             if (entry.size_bytes)
@@ -911,8 +895,8 @@ async function runOnce(opts, runOpts = {}) {
     };
     for (const p of renameStalePaths)
         addOrphan(p);
-    // Un-checked "Sync to Unity" artboards: their PNG (and .meta) leaves the
-    // Unity project on the next sync, incremental or not. Working-set originals
+    // Deselected artboards: their PNG (and Unity .meta) leaves the game project
+    // on the next sync, incremental or not. Working-set originals
     // are never in this list.
     for (const p of deselectedPaths)
         addOrphan(p);
@@ -953,7 +937,7 @@ async function runOnce(opts, runOpts = {}) {
         }
     }
     // A locally-edited file is never deleted, whatever put it in the prune set
-    // (deselected "Sync to Unity", trashed document, rename fallback,
+    // (deselected game sync, trashed document, rename fallback,
     // previous-key sweep): that edit is the only copy of the work until the user
     // pushes it or discards it. Manifest-resident conflicts were already detected
     // during the diff, so they skip the re-hash.
@@ -1317,6 +1301,7 @@ async function runOnce(opts, runOpts = {}) {
                 sha256: sha,
                 diskSha256,
                 legacy: true,
+                ...(entry.updated_at ? { cloudUpdatedAt: entry.updated_at } : {}),
                 ...(sourceRel ? { sourceRel } : {}),
                 ...(entry.released_at ? { releasedAt: entry.released_at } : {}),
                 ...(entry.released_version != null ? { releasedVersion: entry.released_version } : {}),
@@ -1329,6 +1314,7 @@ async function runOnce(opts, runOpts = {}) {
             sha256: sha,
             diskSha256,
             ...(typeof entry.layer_count === 'number' ? { layers: entry.layer_count } : {}),
+            ...(entry.updated_at ? { cloudUpdatedAt: entry.updated_at } : {}),
             ...(sourceRel ? { sourceRel } : {}),
             ...(entry.released_at ? { releasedAt: entry.released_at } : {}),
             ...(entry.released_version != null ? { releasedVersion: entry.released_version } : {}),

package/dist/util/pullDecision.js

@@ -30,6 +30,30 @@ export function hasNewExplicitRelease(opts) {
     const previous = Date.parse(baseline);
     return Number.isFinite(previous) && released > previous;
 }
+/**
+ * Cheap "nothing to do" test that runs before we hash the local PNG and before
+ * any per-file request. Two ways to prove a row is unchanged:
+ *
+ *  1. The manifest still reports the exact cloud composite sha we recorded.
+ *  2. The manifest has no sha at all (legacy / uncached documents) but the
+ *     row's `updated_at` has not moved since we last synced this key. A row
+ *     cannot change — including an editor Sync release — without its
+ *     `updated_at` advancing, so there is nothing to fetch.
+ *
+ * Case 2 is what stops a quiet project from spending one conditional download
+ * per file on every sync just to be told "304 Not Modified".
+ */
+export function canSkipWithoutHashing(opts) {
+    if (opts.freshRelease || !opts.fileExists)
+        return false;
+    if (opts.cloudSha256 && opts.previousCloudSha256 === opts.cloudSha256)
+        return true;
+    if (opts.cloudSha256)
+        return false;
+    return Boolean(opts.cloudUpdatedAt &&
+        opts.previousCloudUpdatedAt &&
+        opts.cloudUpdatedAt === opts.previousCloudUpdatedAt);
+}
 export function decidePull(opts) {
     const cloud = opts.cloudSha256 ?? null;
     const local = opts.localSha256;

package/dist/util/unityFilter.js

@@ -1,5 +1,5 @@
 /**
- * Per-artboard Unity sync opt-in (strict), with a working-set override.
+ * Per-artboard game sync opt-in (strict).
  *
  * In the editor, each artboard has a "Sync to Unity" checkbox (and library
  * folders have a folder-level switch that cascades). A project may hold 100
@@ -12,11 +12,8 @@
  * `unknown` so the caller can warn instead of silently syncing the whole
  * library into someone's game project.
  *
- * Exception: sprites already in the game (connect working set / previously
- * synced keys) always pull. An editor save nulls `artboard_index` and the
- * next manifest often omits `unity` (or rebuilds it as false because the
- * layer JSON dropped `syncToUnity`). Those saves must still write back to
- * the original PNG.
+ * There is deliberately no working-set override: a local path or previous
+ * download must never turn an unmarked sibling into a pull candidate.
  */
 /**
  * Split the manifest into syncable entries and withheld ones. Withheld entries
@@ -69,24 +66,18 @@ export function isWorkingSetEntry(entry, pull) {
     }
     return false;
 }
+/**
+ * Whether an explicitly unmarked manifest entry should leave the local game.
+ * A file previously pulled by MagicPixel is safe to reconcile even if it now
+ * matches a connect glob; a game-authored working-set file without a sync
+ * baseline remains protected.
+ */
+export function shouldPruneDeselectedEntry(entry, opts) {
+    if (!entry.key)
+        return false;
+    return !opts.sourceByKey.has(entry.key) || opts.syncedKeys.has(entry.key);
+}
 /**
  * Flagged artboards, plus any working-set sprite whose Unity flag is missing
  * or false after an editor save / index rebuild.
  */
-export function applyUnityPullPolicy(manifest, opts = {}) {
-    const filtered = filterUnityManifest(manifest, { syncAll: opts.syncAll });
-    if (opts.syncAll || !opts.alwaysPull)
-        return filtered;
-    const already = new Set(filtered.entries);
-    // 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);
-    return {
-        entries: filtered.entries.concat(extra),
-        unknown: filtered.unknown.filter((e) => !extraSet.has(e)),
-        noneFlagged: false,
-    };
-}

package/package.json

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