@magicpixelart/cli 0.5.28 → 0.5.29

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.29]
+
+### Fixed
+- Ship `magicpixel resync <folder>`: the npm 0.5.28 build was published before the command landed.
+
+## [0.5.28]
+
+### Added
+- `magicpixel resync <folder>` (`--dry-run`, `--yes`): make one MagicPixel folder match the local game folder. Local files overwrite their MagicPixel copies (size follows the file); files missing locally move to Trash. Nothing is trashed if any upload fails or the game scan was capped.
+- `sync --watch` runs "Resync from game…" requests queued from the library folder menu.
+
 ## [0.5.27] — 2026-09-21
 
 - Fixed Sync presses that changed only an artboard selection being skipped as

package/dist/api.js

@@ -449,3 +449,29 @@ export async function pushSpritesAdaptive(sprites, retryOpts) {
         }
     }
 }
+// ---------- folder resync (local folder is the source of truth) -------------
+export function resolveResyncEndpoint() {
+    return resolveIngestEndpoint().replace(/\/ingest$/, '/resync');
+}
+async function postResync(body) {
+    const url = resolveResyncEndpoint();
+    return retryTransient('resync', async () => {
+        const { headers, requestId } = buildHeaders({ 'Content-Type': 'application/json' });
+        const res = await safeFetch(url, { method: 'POST', headers, body: JSON.stringify(body) });
+        const serverRequestId = res.headers.get('x-request-id') ?? requestId;
+        if (res.ok)
+            return (await res.json());
+        const text = await res.text();
+        throw new ApiError(res.status, withRequestId(friendlyApiError(res.status, text, 'resync', errorCodeFromResponse(res)), serverRequestId), serverRequestId);
+    });
+}
+export function pruneResyncFolder(folderPath, keepAssetIds, dryRun) {
+    return postResync({ action: 'prune', folderPath, keepAssetIds, dryRun });
+}
+export async function claimResyncRequest() {
+    const r = await postResync({ action: 'claim' });
+    return r.request ?? null;
+}
+export async function reportResyncRequest(id, status, message, counts) {
+    await postResync({ action: 'report', id, status, message, counts });
+}

package/dist/commands/push.js

@@ -41,7 +41,11 @@ export async function runPush(opts = {}) {
 }
 export async function runPushWith(config, state, opts = {}) {
     const quiet = opts.quiet === true;
-    const empty = { created: 0, updated: 0, unchanged: 0, conflict: 0, error: 0, imported: 0 };
+    if (opts.replace)
+        opts = { ...opts, flatten: true };
+    const empty = {
+        created: 0, updated: 0, unchanged: 0, conflict: 0, error: 0, imported: 0, keptAssetIds: [], scanned: 0,
+    };
     const spinner = quiet ? null : ora(countingSpritesText(0)).start();
     const kind = await detectProjectKind();
     const index = opts.gameIndex
@@ -110,7 +114,7 @@ export async function runPushWith(config, state, opts = {}) {
         const segments = entry
             ? entry.adoptRel.replace(/\.png$/i, '').split('/')
             : key.split('/');
-        if (opts.excludeKeys?.has(key)) {
+        if (opts.excludeKeys?.has(key) || (opts.keyFilter && !opts.keyFilter(key))) {
             reportHash();
             return;
         }
@@ -129,7 +133,7 @@ export async function runPushWith(config, state, opts = {}) {
         if (sourceByKey.has(k))
             folderTreeKeys.add(k);
     }
-    const actions = planPush(candidates, state.synced, { flatten: opts.flatten, folderTreeKeys });
+    const actions = planPush(candidates, state.synced, { flatten: opts.flatten, folderTreeKeys, replace: opts.replace });
     const skipped = actions.filter((a) => a.kind === 'skip' && a.reason !== 'legacy').length;
     const legacy = actions.filter((a) => a.kind === 'skip' && a.reason === 'legacy');
     const flattenBlocked = actions.filter((a) => a.kind === 'needs-flatten');
@@ -162,7 +166,10 @@ export async function runPushWith(config, state, opts = {}) {
         await persistDiskFingerprints(state, candidates);
         if (!quiet)
             console.log(kleur.green('✓ nothing to push.'));
-        return { ...empty, imported: matched.entries.length, unchanged: skipped };
+        return {
+            ...empty, imported: matched.entries.length, unchanged: skipped,
+            keptAssetIds: collectKeptAssetIds(candidates, state.synced ?? {}, []), scanned: candidates.length,
+        };
     }
     if (opts.dryRun) {
         if (!quiet) {
@@ -173,7 +180,10 @@ export async function runPushWith(config, state, opts = {}) {
             }
             console.log(kleur.dim('--dry-run: nothing sent.'));
         }
-        return { ...empty, imported: matched.entries.length };
+        return {
+            ...empty, imported: matched.entries.length,
+            keptAssetIds: collectKeptAssetIds(candidates, state.synced ?? {}, []), scanned: candidates.length,
+        };
     }
     const outRoot = resolve(process.cwd(), config.outDir);
     const shaByKey = new Map(candidates.map((c) => [c.key, c.diskSha256]));
@@ -195,10 +205,14 @@ export async function runPushWith(config, state, opts = {}) {
                 layerIdx: a.layerIdx,
                 baseSha256: a.baseSha256,
                 flatten: opts.flatten === true,
+                ...(opts.replace ? { replace: true } : {}),
             });
         }
         else if (a.kind === 'adopt') {
-            sprites.push({ key: a.key, pngBase64, diskSha256, path: a.path, pathNames: a.pathNames, name: a.name });
+            sprites.push({
+                key: a.key, pngBase64, diskSha256, path: a.path, pathNames: a.pathNames, name: a.name,
+                ...(opts.replace ? { replace: true } : {}),
+            });
         }
     }
     const progress = quiet ? null : ora(`Pushing 0/${sprites.length}…`).start();
@@ -296,7 +310,27 @@ export async function runPushWith(config, state, opts = {}) {
     }
     if (failed)
         process.exitCode = 1;
-    return { ...counts, imported: matched.entries.length };
+    return {
+        ...counts, imported: matched.entries.length,
+        keptAssetIds: collectKeptAssetIds(candidates, synced, results), scanned: candidates.length,
+    };
+}
+/**
+ * Library documents that now mirror an in-scope local file: every successful
+ * push result, plus unchanged candidates already recorded in sync state.
+ */
+export function collectKeptAssetIds(candidates, synced, results) {
+    const out = new Set();
+    for (const r of results) {
+        if (r.assetId && (r.status === 'created' || r.status === 'updated' || r.status === 'unchanged'))
+            out.add(r.assetId);
+    }
+    for (const c of candidates) {
+        const id = synced[c.key]?.assetId;
+        if (id)
+            out.add(id);
+    }
+    return [...out];
 }
 /**
  * Sprites to re-send under `--force`: every sprite the cloud refused because it

package/dist/commands/resync.js

@@ -0,0 +1,123 @@
+/**
+ * `magicpixel resync <folder>` — make one MagicPixel library folder match the
+ * local game folder exactly:
+ *   - every local sprite in the folder overwrites its MagicPixel copy (size
+ *     follows the file, MagicPixel-only edits are replaced);
+ *   - new local sprites are imported;
+ *   - MagicPixel files in that folder with no local file go to Trash.
+ */
+import kleur from 'kleur';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { loadConfig, loadState } from '../config.js';
+import { ensureEngineConnect } from '../util/engineConnect.js';
+import { detectProjectKind, isEngineKind } from '../util/framework.js';
+import { indexGamePngs, countingSpritesText } from '../util/gameScan.js';
+import { pruneResyncFolder } from '../api.js';
+import { runPushWith } from './push.js';
+/** Same slug rules as library folders / manifest keys. */
+export function slugifySegment(input) {
+    return input.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+export function parseFolderArg(folder) {
+    return folder
+        .replace(/\\/g, '/')
+        .split('/')
+        .map((s) => slugifySegment(s.trim()))
+        .filter(Boolean);
+}
+/**
+ * True when `key` (`<folders…>/<doc>/<artboard>`) lives inside `segments`.
+ * Only the folder part of the key counts, so resyncing `enemies` never touches
+ * a root document that happens to be named "enemies".
+ */
+export function keyInFolder(key, segments) {
+    const parts = key.split('/');
+    const folderParts = parts.slice(0, Math.max(0, parts.length - 2));
+    if (folderParts.length < segments.length)
+        return false;
+    return segments.every((s, i) => folderParts[i] === s);
+}
+async function confirm(prompt) {
+    if (!stdin.isTTY)
+        return false;
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        const a = (await rl.question(prompt)).trim().toLowerCase();
+        return a === 'y' || a === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function resyncCommand(folder, opts = {}) {
+    await runResync(parseFolderArg(folder), opts);
+}
+export async function runResync(segments, opts = {}) {
+    if (segments.length === 0) {
+        throw new Error('Pass a folder, e.g. `magicpixel resync Sprites/Enemies`. Resyncing the whole project is `push --force`.');
+    }
+    const log = (m) => { if (!opts.quiet)
+        console.log(m); };
+    const config = await ensureEngineConnect(await loadConfig(), process.cwd(), !opts.dryRun);
+    const kind = await detectProjectKind();
+    if (!isEngineKind(kind))
+        throw new Error('This folder is not a Unity/Godot/GameMaker project.');
+    const gameIndex = await indexGamePngs(kind, process.cwd(), config.outDir, {
+        onProgress: opts.quiet ? undefined : (p) => { stdout.write(`\r${countingSpritesText(p)}`); },
+    });
+    if (!opts.quiet)
+        stdout.write('\n');
+    const keyFilter = (key) => keyInFolder(key, segments);
+    const label = segments.join('/');
+    // Plan first: what would change, and what would go to Trash.
+    const plan = await runPushWith(config, await loadState(), {
+        dryRun: true, replace: true, keyFilter, gameIndex, quiet: true,
+    });
+    if (plan.scanned === 0) {
+        throw new Error(`No local sprites found in "${label}". Nothing was changed. Check the folder name with \`magicpixel search\`.`);
+    }
+    const pruneAllowed = !gameIndex.capped;
+    const preview = pruneAllowed && plan.keptAssetIds.length > 0
+        ? await pruneResyncFolder(segments, plan.keptAssetIds, true)
+        : null;
+    log(kleur.bold(`Resync ${label} from your game`));
+    log(`  local sprites: ${plan.scanned}`);
+    if (preview) {
+        log(`  to trash in MagicPixel (no local file): ${preview.wouldTrash.length}`);
+        for (const n of preview.wouldTrash.slice(0, 10))
+            log(kleur.dim(`    - ${n}`));
+        if (preview.wouldTrash.length > 10)
+            log(kleur.dim(`    …and ${preview.wouldTrash.length - 10} more`));
+    }
+    if (!pruneAllowed)
+        log(kleur.yellow('  ! game scan hit its file cap — nothing will be trashed.'));
+    log(kleur.dim('  Local files win: MagicPixel copies are overwritten and resized to match.'));
+    if (opts.dryRun) {
+        log(kleur.dim('--dry-run: nothing sent.'));
+        return { push: plan, trashed: 0, pruneSkipped: 'dry-run' };
+    }
+    if (!opts.yes && !(await confirm('Continue? (y/N) '))) {
+        throw new Error('Cancelled. Re-run with --yes to skip this question.');
+    }
+    const push = await runPushWith(config, await loadState(), {
+        replace: true, keyFilter, gameIndex, quiet: opts.quiet,
+    });
+    let pruneSkipped = null;
+    let trashed = 0;
+    if (!pruneAllowed)
+        pruneSkipped = 'game scan capped';
+    else if (push.error > 0 || push.conflict > 0)
+        pruneSkipped = 'some sprites failed to upload';
+    else if (push.keptAssetIds.length === 0)
+        pruneSkipped = 'no files confirmed';
+    else {
+        const res = await pruneResyncFolder(segments, push.keptAssetIds, false);
+        trashed = res.trashed;
+    }
+    if (pruneSkipped)
+        log(kleur.yellow(`! Nothing moved to Trash (${pruneSkipped}). Re-run once fixed.`));
+    else
+        log(kleur.green(`✓ ${label} resynced. ${trashed} file${trashed === 1 ? '' : 's'} moved to Trash.`));
+    return { push, trashed, pruneSkipped };
+}

package/dist/commands/sync.js

@@ -28,6 +28,46 @@ import { canSkipWithoutHashing, decidePull, hasNewExplicitRelease } from '../uti
 import { hasUnpushedLocalEdit } from '../util/localEdit.js';
 import { shouldReconcile } from '../util/reconcile.js';
 import { runPush } from './push.js';
+import { claimResyncRequest, reportResyncRequest } from '../api.js';
+import { runResync } from './resync.js';
+/** How often the watcher asks for a library "Resync from game" request. */
+const RESYNC_POLL_MS = 15_000;
+let lastResyncPollAt = 0;
+/**
+ * Run one queued library "Resync from game…" request, if any. Never throws:
+ * a failed resync is reported back to MagicPixel and the watcher keeps going.
+ */
+async function maybeRunQueuedResync(quiet) {
+    if (Date.now() - lastResyncPollAt < RESYNC_POLL_MS)
+        return;
+    lastResyncPollAt = Date.now();
+    let req = null;
+    try {
+        req = await claimResyncRequest();
+    }
+    catch {
+        return;
+    }
+    if (!req)
+        return;
+    if (!quiet) {
+        process.stdout.write('\x1b[2K\r');
+        console.log(kleur.bold(`↻ Resyncing "${req.folderName}" from your game (requested in MagicPixel)…`));
+    }
+    try {
+        const out = await runResync(req.folderPath, { yes: true, quiet });
+        const p = out.push;
+        await reportResyncRequest(req.id, 'done', out.pruneSkipped ? `Nothing trashed: ${out.pruneSkipped}` : null, {
+            created: p.created, updated: p.updated, unchanged: p.unchanged,
+            conflict: p.conflict, error: p.error, trashed: out.trashed,
+        });
+    }
+    catch (e) {
+        await reportResyncRequest(req.id, 'failed', e.message).catch(() => { });
+        if (!quiet)
+            console.log(kleur.red(`! Resync failed: ${e.message}`));
+    }
+}
 /** Did the push half of a run actually move bytes into MagicPixel? */
 export function pushWasActive(pushed) {
     if (!pushed)
@@ -222,6 +262,7 @@ async function watchLoop(opts) {
             pausedForNetwork = false;
             pausedForQuota = false;
             consecutiveAuthFailures = 0;
+            await maybeRunQueuedResync(opts.quiet === true);
             if (wasPausedForAuth && !opts.quiet) {
                 process.stdout.write('\x1b[2K\r');
                 console.log(`${kleur.dim(timestamp())} ${kleur.green('✓')} Key accepted again — resuming.`);

package/dist/index.js

@@ -15,6 +15,7 @@ import { doctorCommand } from './commands/doctor.js';
 import { repairCommand } from './commands/repair.js';
 import { startCommand } from './commands/start.js';
 import { connectCommand } from './commands/connect.js';
+import { resyncCommand } from './commands/resync.js';
 import { searchCommand } from './commands/search.js';
 import { parseWatchInterval, parseConcurrency } from './util/flagValidators.js';
 import { CLI_VERSION } from './version.js';
@@ -100,6 +101,13 @@ program
     .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('resync <folder>')
+    .description('Make one MagicPixel folder match your local game folder (local wins, missing files go to Trash)')
+    .option('-y, --yes', 'Skip the confirmation question')
+    .option('--dry-run', 'Show what would change without sending anything')
+    .addHelpText('after', '\nExamples:\n  $ magicpixel resync Sprites/Enemies --dry-run\n  $ magicpixel resync Sprites/Enemies\n')
+    .action(wrap("resync", async (folder, opts) => resyncCommand(folder, opts)));
 program
     .command('connect <glob>')
     .description('Limit which game folders sync (default is all sprites)')

package/dist/util/pushPlan.js

@@ -120,11 +120,13 @@ export function planPush(candidates, synced, opts = {}) {
         if (known) {
             const connected = Boolean(c.sourceRel || opts.folderTreeKeys?.has(c.key) || (stateKey != null && opts.folderTreeKeys?.has(stateKey)));
             const lastDisk = lastPushedDiskSha(known, { connected });
-            if (lastDisk === c.diskSha256) {
+            // Resync (replace) sends every in-scope sprite: local wins even when
+            // only the MagicPixel copy changed. The server reports true no-ops.
+            if (lastDisk === c.diskSha256 && !opts.replace) {
                 out.push({ kind: 'skip', key: c.key, reason: 'unchanged' });
                 continue;
             }
-            if (lastDisk === undefined) {
+            if (lastDisk === undefined && !opts.replace) {
                 // Connected original with no disk baseline yet. Ingest's composite
                 // sha is not the game file — seeding happens in `applyDiskFingerprints`.
                 out.push({ kind: 'skip', key: c.key, reason: 'unchanged' });

package/package.json

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